technology posts - idmontie's Portfolio

In a previous article, I discussed <a href="/blog/post/2025-01-12-api-surfaces">Surfaces</a> as an abstraction on APIs and how we could measure complexity as the size of that surfaces&#x27; perimeter – the &quot;visible&quot; part of the API to consumers. I shared this article with a colleague who I was actively working closely with on a new implementation of a design system. They has some interesting feedback on different ways of reducing complexity of certain APIs that I felt compelled to revisit this topic.
In the context of a design system, we have tokens, components, and combinations of lower level components that typically follow the <a href="https://atomicdesign.bradfrost.com/">Brad Frost</a> pattern of attems, molecules, and organisms. At the atom level, a component&#x27;s complexity follows the Surface API pattern I described very closely in the previous article. As the number of props increases, the component&#x27;s complexity increases with it:
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>C</mi><mo>∝</mo><mi mathvariant="normal">∣</mi><mi>p</mi><mi mathvariant="normal">∣</mi></mrow><annotation encoding="application/x-tex">C \propto |p|</annotation></semantics></math>C∝∣p∣
It also increases with the number of prop combinations that the type system allows:
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>C</mi><mo>∝</mo><munderover><mo>∏</mo><mrow><mi>n</mi><mo>=</mo><mn>1</mn></mrow><mrow><mi mathvariant="normal">∣</mi><mi>p</mi><mi mathvariant="normal">∣</mi></mrow></munderover><msub><mi>p</mi><mi>n</mi></msub></mrow><annotation encoding="application/x-tex">C \propto \prod_{n=1}^{|p|} p_n</annotation></semantics></math>C∝n=1∏∣p∣​pn​
So the goal should be to keep the number of prop combinations as low as possible to avoid the possible cartiesian explosion in size, and therefor a dramatic increase to the component&#x27;s complexity. My last article described a few ways to limit the combinations by using strict typings to reduce multiple props into a single prop. In this article, I&#x27;ll explore some very specific examples of this and additional ways to reduce complexity.
<h2>Reducing Prop Complexity</h2>
Before we dive into reducing prop complexity, I&#x27;d like to split the types of Design Systems I am going to discuss into two categories: those meant to serve many different projects, and those meant to serve a handful of projects.
HeroUI (formerly NextUI), Boostrap, Material Design, etc are the former. They are meant to be flexible enough to serve a wide range of use-cases. The components contained in these design systems will often exhibit the complexity explosion caused by the cartesian product of the props they have to support. For example, let&#x27;s look at the prop types for just the button in HeroUI:
<img alt="HeroUI button props" src="/media/2026-02-01-api-complexity-revisited/heorui-button-props.png" style="max-height:500px;margin:auto;text-align:center"/>
We&#x27;ll focus on just the first three props after <code>children</code>: we have 7 different variants, 6 colors, and 3 sizes. Just these props alone means we already have 126 different ways the button can be styled. If we want to ensure a change does not break anything, I would expect the CI to take snapshots of these 126 different combinations. Which means 126 states to capture, snapshot, and review. We haven&#x27;t even taken into account that these buttons can have normal, hovered, pressed, and disabled states. Or that they can have startContent, endContent, or loading states as well.
On the other hand, if we are designing for an internal design system, we can be much more discerning in the props we allow. We might use HeroUI, Boostrap, or another UI toolkit as a base, however, when constructing an internal design system, the mainainters should aim to reduce the API complexity as much as possible. This helps both the maintainers keep a consistent design without introducing breaking changes everytime there is an update, and helps the consumers be able to work with a straightfoward design system. The internal design system can act as a facade for the more generic component library, and in doing so will achieve two benefits: 1. it enables a layer to allow the internals of the design system to change without impacting the consumers, and 2. it provides a reduced API complexity to consumers which is our main goal in this article.
Most of the reduction in prop complexity from facading the general design system component in our internal design system is made by making strong opinions. If we can determine that there will only ever be two kinds of buttons on our site – DefaultButton and PrimaryButton – we can reduce the complexity of the API by omitting secondary, success, warning, danger, and other variants. Likewise, if we know we only want Solid and Bordered versions of buttons, we can mit light, flat, faded, shadow, and gost variants. This alone reduces the possible combinations from 126 to just 12 button states. We may even have the opinion that there will never be a Bordered Primary Button, and we can omit that type combination from the props to reduce the number of button states even further.
These examples cover in more concrete terms what I abstractly covered in my last article. We can reduce complexity of atom-level components by restricting the number of props, the size of those props, and the prop combinations that are invalid. The next section will cover a new technique that comes up when designing molecule-level components.
<h2>Reducing Props Complexity Via Composition</h2>
Imagine we have an Accordion component. This accordion can be open or closed, it can have a title, icon, description and content. When it has an icon, the size of the title and description must account for it. When there is no description, we want to ensure that the icon and title are centered vertically in the space. If there is a description, we want the icon, title, and description to be top aligned.
Rather than thinking a the Accordion as one giant component that takes in props for its open state, title, icon, description, and content, we can decompose the Accordion into smaller components with their own APIs.
If we try to write the Accordion as one large component, we have:
<ul>
<li><code>isOpen: boolean</code> - 2 states</li>
<li><code>title: string</code> - 1 state</li>
<li><code>description: string | undefined</code> - 2 states</li>
<li><code>icon: IconComponent | undefined</code> - 2 states</li>
<li><code>content: JSX.Element</code> - 1 state</li>
</ul>
Altogether, this has 8 state combinations.
If we split the component into an Accordion and an AccordionHeader, we have for the Accordion:
<ul>
<li><code>isOpen: boolean</code> - 2 states</li>
<li><code>header: AccordionHeader</code> - 1 state</li>
<li><code>content: JSX.Element</code> - 1 state</li>
</ul>
And AccordionHeader:
<ul>
<li><code>title: string</code> - 1 state</li>
<li><code>description: string | undefined</code> - 2 states</li>
<li><code>icon: IconComponent | undefined</code> - 2 states</li>
</ul>
Which when split up leads to 2 state combinations for the Accordion, and 4 state combinations for the AccordionHeader. Meaning that the composition of the two is:
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>C</mi><mo stretchy="false">(</mo><mi>S</mi><mo stretchy="false">)</mo><mo>=</mo><munderover><mo>∑</mo><mrow><mi>i</mi><mo>=</mo><mn>1</mn></mrow><mi>n</mi></munderover><mi>c</mi><mo stretchy="false">(</mo><msub><mi>f</mi><mi>i</mi></msub><mo stretchy="false">)</mo></mrow><annotation encoding="application/x-tex">C(S) = \sum_{i=1}^{n} c(f_i)</annotation></semantics></math>C(S)=i=1∑n​c(fi​)
This, we only have 6 state combinations as our API complexity for the split up components instead of 8. You can see how letting consumers compose smaller components instead of giving consumers a large complex componnent that does everything, we reduce the API complexity.
<h2>Takeaways</h2>
While restricting prop combinations can be extremely useful for reducing API complexity, it can be complemented by using composition to help break up molecules back into atom-size components. By pushing composition to the consumer, we can keep API complexity manageable.

In a previous article, I discussed [Surfaces](/blog/post/2025-01-12-api-surfaces) as an abstraction on APIs and how we could measure complexity as the size of that surfaces' perimeter – the "visible" part of the API to consumers. I shared this article with a colleague who I was actively working closely with on a new implementation of a design system. They has some interesting feedback on different ways of reducing complexity of certain APIs that I felt compelled to revisit this topic.



In the context of a design system, we have tokens, components, and combinations of lower level components that typically follow the [Brad Frost](https://atomicdesign.bradfrost.com/) pattern of attems, molecules, and organisms. At the atom level, a component's complexity follows the Surface API pattern I described very closely in the previous article. As the number of props increases, the component's complexity increases with it:

$$
C \propto |p|
$$

It also increases with the number of prop combinations that the type system allows:

$$
C \propto \prod_{n=1}^{|p|} p_n
$$

So the goal should be to keep the number of prop combinations as low as possible to avoid the possible cartiesian explosion in size, and therefor a dramatic increase to the component's complexity. My last article described a few ways to limit the combinations by using strict typings to reduce multiple props into a single prop. In this article, I'll explore some very specific examples of this and additional ways to reduce complexity.

## Reducing Prop Complexity

Before we dive into reducing prop complexity, I'd like to split the types of Design Systems I am going to discuss into two categories: those meant to serve many different projects, and those meant to serve a handful of projects.

HeroUI (formerly NextUI), Boostrap, Material Design, etc are the former. They are meant to be flexible enough to serve a wide range of use-cases. The components contained in these design systems will often exhibit the complexity explosion caused by the cartesian product of the props they have to support. For example, let's look at the prop types for just the button in HeroUI:

![HeroUI button props](/media/2026-02-01-api-complexity-revisited/heorui-button-props.png)

We'll focus on just the first three props after `children`: we have 7 different variants, 6 colors, and 3 sizes. Just these props alone means we already have 126 different ways the button can be styled. If we want to ensure a change does not break anything, I would expect the CI to take snapshots of these 126 different combinations. Which means 126 states to capture, snapshot, and review. We haven't even taken into account that these buttons can have normal, hovered, pressed, and disabled states. Or that they can have startContent, endContent, or loading states as well.

On the other hand, if we are designing for an internal design system, we can be much more discerning in the props we allow. We might use HeroUI, Boostrap, or another UI toolkit as a base, however, when constructing an internal design system, the mainainters should aim to reduce the API complexity as much as possible. This helps both the maintainers keep a consistent design without introducing breaking changes everytime there is an update, and helps the consumers be able to work with a straightfoward design system. The internal design system can act as a facade for the more generic component library, and in doing so will achieve two benefits: 1. it enables a layer to allow the internals of the design system to change without impacting the consumers, and 2. it provides a reduced API complexity to consumers which is our main goal in this article.

Most of the reduction in prop complexity from facading the general design system component in our internal design system is made by making strong opinions. If we can determine that there will only ever be two kinds of buttons on our site – DefaultButton and PrimaryButton – we can reduce the complexity of the API by omitting secondary, success, warning, danger, and other variants. Likewise, if we know we only want Solid and Bordered versions of buttons, we can mit light, flat, faded, shadow, and gost variants. This alone reduces the possible combinations from 126 to just 12 button states. We may even have the opinion that there will never be a Bordered Primary Button, and we can omit that type combination from the props to reduce the number of button states even further.

These examples cover in more concrete terms what I abstractly covered in my last article. We can reduce complexity of atom-level components by restricting the number of props, the size of those props, and the prop combinations that are invalid. The next section will cover a new technique that comes up when designing molecule-level components.

## Reducing Props Complexity Via Composition

Imagine we have an Accordion component. This accordion can be open or closed, it can have a title, icon, description and content. When it has an icon, the size of the title and description must account for it. When there is no description, we want to ensure that the icon and title are centered vertically in the space. If there is a description, we want the icon, title, and description to be top aligned.

Rather than thinking a the Accordion as one giant component that takes in props for its open state, title, icon, description, and content, we can *decompose* the Accordion into smaller components with their own APIs.

If we try to write the Accordion as one large component, we have:

* `isOpen: boolean` - 2 states
* `title: string` - 1 state
* `description: string | undefined` - 2 states
* `icon: IconComponent | undefined` - 2 states
* `content: JSX.Element` - 1 state

Altogether, this has 8 state combinations.

If we split the component into an Accordion and an AccordionHeader, we have for the Accordion:

* `isOpen: boolean` - 2 states
* `header: AccordionHeader` - 1 state
* `content: JSX.Element` - 1 state

And AccordionHeader:

* `title: string` - 1 state
* `description: string | undefined` - 2 states
* `icon: IconComponent | undefined` - 2 states

Which when split up leads to 2 state combinations for the Accordion, and 4 state combinations for the AccordionHeader. Meaning that the composition of the two is:

$$
C(S) = \sum_{i=1}^{n} c(f_i)
$$

This, we only have 6 state combinations as our API complexity for the split up components instead of 8. You can see how letting consumers compose smaller components instead of giving consumers a large complex componnent that does everything, we reduce the API complexity.


## Takeaways

While restricting prop combinations can be extremely useful for reducing API complexity, it can be complemented by using composition to help break up molecules back into atom-size components. By pushing composition to the consumer, we can keep API complexity manageable.

API Complexity Revisited

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
 const _components = {
 a: "a",
 code: "code",
 h2: "h2",
 h3: "h3",
 p: "p",
 pre: "pre",
 ...props.components
 };
 return _jsxs(_Fragment, {
 children: [_jsxs(_components.p, {
 children: ["I've discussed ", _jsx(_components.a, {
 href: "/blog/post/2023-08-14-partial-objects",
 children: "full and partial objects before on this blog"
 }), ", and in this article I'm going to investigate a common factory pattern\nin Typescript that can lead to type-holes.\nWhen writing tests or complex components, I'll often create prop factory utilities."]
 }), "\n", _jsx(_components.p, {
 children: "For tests, the goal is to create props with all the default values, except a few that may be\noveridden for a specific test case. The function signature typically looks like this:"
 }), "\n", _jsx(_components.pre, {
 children: _jsx(_components.code, {
 className: "language-jsx",
 children: "function makeFoo(partial?: Partial<Foo>): Foo;\n"
 })
 }), "\n", _jsxs(_components.p, {
 children: ["The expectation is that a software developer can call ", _jsx(_components.code, {
 children: "makeFoo"
 }), " and get a version of ", _jsx(_components.code, {
 children: "Foo"
 }), " that has all the defaults set to use in tests. Then, if the developer want to override a few fields to test an edge case, all they do is call ", _jsx(_components.code, {
 children: "makeFoo({ fieldA: 'special-case })"
 }), "."]
 }), "\n", _jsx(_components.p, {
 children: "I’ve seen developers try to implement this a few ways, each with its pros and cons."
 }), "\n", _jsx(_components.h3, {
 children: "Spreading"
 }), "\n", _jsx(_components.p, {
 children: "The easiest way to implement this function is to just provide defaults and spread the partial:"
 }), "\n", _jsx(_components.pre, {
 children: _jsx(_components.code, {
 className: "language-jsx",
 children: "interface Foo {\n fieldA: string;\n fieldB?: string;\n fieldC?: boolean | null;\n}\n\nfunction makeFoo(partial?: Partial<Foo>): Foo {\n return {\n\t fieldA: 'test',\n fieldB: 'example',\n fieldC: false,\n ...partial\n };\n}\n"
 })
 }), "\n", _jsxs(_components.p, {
 children: ["Here, we create a ", _jsx(_components.code, {
 children: "Foo"
 }), " mock with overrides for the defaults, which are provided by ", _jsx(_components.code, {
 children: "partial?: Partial<Foo>"
 }), " . However, even though ", _jsx(_components.code, {
 children: "fieldA"
 }), " is required, we can see a type-hole with the default Typescript compilation settings:"]
 }), "\n", _jsx(_components.pre, {
 children: _jsx(_components.code, {
 className: "language-jsx",
 children: "const instance = makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });\nconsole.log(instance.fieldA);\n\n// No type error, but this blows up\nconsole.log(instance.fieldA.toLowerCase());\n"
 })
 }), "\n", _jsxs(_components.p, {
 children: ["When we spread, ", _jsx(_components.code, {
 children: "undefined"
 }), " actually overrides the default! But why were we allowed to provide ", _jsx(_components.code, {
 children: "undefined"
 }), " in the first place?"]
 }), "\n", _jsxs(_components.p, {
 children: ["In Typescript, ", _jsx(_components.code, {
 children: "Partial<Foo>"
 }), " keeps all the fields, but makes them optional. In the default compilation settings, an optional field can be set to ", _jsx(_components.code, {
 children: "undefined"
 }), "."]
 }), "\n", _jsx(_components.p, {
 children: _jsx(_components.a, {
 href: "https://www.typescriptlang.org/play/?#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkyDohbGMgtOjyXSToTA5TYDMQXamUx-oA9O-IAHJYYACeThQ0Cg6CguRk6jAyDAAAtgLQZNcAO6I9ROXCnc6Xa63e6PZ5FChdMDoAAy6GR0HEcDaDhCxyAA",
 children: "Typescript Playground Link"
 })
 }), "\n", _jsxs(_components.p, {
 children: ["There is a Typescript compilation flag to throw a type-error and keep our sanity: ", _jsx(_components.code, {
 children: "exactOptionalPropertyTypes"
 }), ". Enabling this flag makes Typescript show an error for ", _jsx(_components.code, {
 children: "makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });"
 }), ". We can add the field to the call if it is set to a value."]
 }), "\n", _jsx(_components.p, {
 children: _jsx(_components.a, {
 href: "https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkuevFmyDbu-uHqRInZ6D7yDohbGMgtOjyXSToTA5TYDMQLpXChPUbjd6Ar4-P4AoFFChdMDoAAy6AA7tBxHA2g4Qk8gA",
 children: "Typescript Playground Link"
 })
 }), "\n", _jsxs(_components.p, {
 children: ["But this causes another problem: it is perfectly valid to create an initial instance of ", _jsx(_components.code, {
 children: "Foo"
 }), " without fieldB being set (and its value being ", _jsx(_components.code, {
 children: "undefined"
 }), "). But now our ", _jsx(_components.code, {
 children: "makeFoo"
 }), " object doesn’t allow us to pass ", _jsx(_components.code, {
 children: "fieldB: undefined"
 }), " anymore. Only when the interface explicitly defines fieldB as optional AND undefined does it allow us to so."]
 }), "\n", _jsx(_components.p, {
 children: _jsx(_components.a, {
 href: "https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQTZAB9kAVxBkIREBDJsCRUmQDCfZACNMJCHBCjkIcSRJsAvrlwxJCMMHQGAtnADWEDOgAUABzhR7OBINAAV-QJIAHk8APgBKGk8cdigIMHEoAzwASCVOShoAckh6QoAadjyVLiKIAA84Jx9dcsqOFVUaeBJaCAqCAgA6Yb8A4CD2cwsrBEd6ZFB6fSRkAF5kF3dPL2x27hpJaVl5ZHM4tlmQWnRdQZJ0Ji9FsGWIQeVyCnOZuZu3+8ez1e73yFEGYHQABl0AB3aCqOC9Lxxc5AA",
 children: "Typescript Playground Link"
 })
 }), "\n", _jsxs(_components.p, {
 children: ["Generally this pattern without the flag is fine for creating mock data, since any type-holes would only be scoped to tests and not real production code. But the question is: can we have ", _jsx(_components.code, {
 children: "makeFoo"
 }), " take a partial, return Foo without type-holes, and have allow ", _jsx(_components.code, {
 children: "undefined"
 }), " for partials?"]
 }), "\n", _jsx(_components.h2, {
 children: "Null-Coalescing Every Field"
 }), "\n", _jsx(_components.p, {
 children: "Another common implementation I have seen is to add nullish coalescing to every field:"
 }), "\n", _jsx(_components.pre, {
 children: _jsx(_components.code, {
 className: "language-jsx",
 children: "interface Foo {\n fieldA: string;\n fieldB?: string;\n fieldC?: boolean | null;\n}\n\nfunction makeFoo(partial?: Partial<Foo>): Foo {\n return {\n\t fieldA: partial?.fieldA ?? 'test',\n fieldB: partial?.fieldB ?? 'example',\n fieldC: partial?.fieldC ?? false,\n };\n} \n"
 })
 }), "\n", _jsxs(_components.p, {
 children: ["Let’s also turn off the ", _jsx(_components.code, {
 children: "exactOptionalPropertyTypes"
 }), " compilation flag for now."]
 }), "\n", _jsxs(_components.p, {
 children: ["We know every field will be set correctly, so there are no type-holes in ", _jsx(_components.code, {
 children: "Foo"
 }), ", however, we still have the problem where we cannot override a field to the ", _jsx(_components.code, {
 children: "unset"
 }), " value of ", _jsx(_components.code, {
 children: "undefined"
 }), " :"]
 }), "\n", _jsx(_components.p, {
 children: _jsx(_components.a, {
 href: "https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=false&ssl=13&ssc=2&pln=1&pc=1#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTILm7AHjwAdKmUyDw8yADkkPSlADTsKZxkXDSZfnkFXEUlpRAAHnAWTvLVtRxi4k2+2Z759eIdhB60EDUEOrr6COb0yKD0ikjIALzIVrb2DtgjaTRGZBBEIBBkVZcN1yC394-IOiFsGyC0dDyXIkdBMBw7MB7CDTMQUX64f6A4Gg8GQ6Gw7gIxGbIEw1EQgFQ4wwgoUXJgdAAGXQAHdoOI4IsHCEEUA",
 children: "Typescript Playground Link"
 })
 }), "\n", _jsxs(_components.p, {
 children: ["Turning on the ", _jsx(_components.code, {
 children: "exactOptionalPropertyTypes"
 }), " also doesn’t save us here since we didn’t have a type-issue anyway, but more of a logic issue. ", _jsx(_components.code, {
 children: "makeFoo({ fieldB: undefined })"
 }), " will still set ", _jsx(_components.code, {
 children: "fieldB"
 }), " to ", _jsx(_components.code, {
 children: "example"
 }), "."]
 }), "\n", _jsx(_components.h2, {
 children: "Allowing bad inputs"
 }), "\n", _jsxs(_components.p, {
 children: ["This last approach takes the first and second approaches above and combines them using a ", _jsx(_components.code, {
 children: "pickOrDefault"
 }), " function. Here if any value is passed into the partial, we will return it, except when that value would be incorrect in the output type:"]
 }), "\n", _jsx(_components.pre, {
 children: _jsx(_components.code, {
 className: "language-tsx",
 children: "function isValuePresent<T extends object>(obj: T, key: keyof T): boolean {\n return key in obj;\n}\n\nfunction pickOrDefault<T extends object, K extends keyof T>(partial: T, key: K, fallbackValue: T[K]): T[K] {\n if (key in partial) {\n return partial[key];\n }\n\n return fallbackValue\n}\n\ninterface Foo {\n fieldA: string;\n fieldB?: string;\n fieldC?: boolean | null;\n}\n\nfunction makeFoo(partial: Partial<Foo> = {}): Foo {\n return {\n\t fieldA: pickOrDefault(partial, 'fieldA', 'test') ?? 'test',\n fieldB: pickOrDefault(partial, 'fieldB', 'example'),\n fieldC: pickOrDefault(partial, 'fieldC', true),\n };\n}\n\nconst instance = makeFoo({ fieldA: undefined, fieldB: undefined });\nconsole.log(instance.fieldA);\nconsole.log(instance.fieldB);\n\nconsole.log(instance.fieldA.toLowerCase());\n\n"
 })
 }), "\n", _jsxs(_components.p, {
 children: ["For each field, we prefer the input partial, except here the type mismatch for ", _jsx(_components.code, {
 children: "fieldA"
 }), " forced us to add the default value twice, once if the partial didn’t have a value, and once if the partial had ", _jsx(_components.code, {
 children: "undefined"
 }), " which isn’t allows in the final version of ", _jsx(_components.code, {
 children: "type Foo"
 }), "."]
 }), "\n", _jsx(_components.p, {
 children: "While more verbose, this does eliminate the type holes the code!"
 })]
 });
}
function MDXContent(props = {}) {
 const {wrapper: MDXLayout} = props.components || ({});
 return MDXLayout ? _jsx(MDXLayout, {
 ...props,
 children: _jsx(_createMdxContent, {
 ...props
 })
 }) : _createMdxContent(props);
}
return {
 default: MDXContent
};

I&#x27;ve discussed <a href="/blog/post/2023-08-14-partial-objects">full and partial objects before on this blog</a>, and in this article I&#x27;m going to investigate a common factory pattern
in Typescript that can lead to type-holes.
When writing tests or complex components, I&#x27;ll often create prop factory utilities.
For tests, the goal is to create props with all the default values, except a few that may be
overidden for a specific test case. The function signature typically looks like this:
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-jsx">function makeFoo(partial?: Partial&lt;Foo&gt;): Foo;
</code></pre></div>
The expectation is that a software developer can call <code>makeFoo</code> and get a version of <code>Foo</code> that has all the defaults set to use in tests. Then, if the developer want to override a few fields to test an edge case, all they do is call <code>makeFoo({ fieldA: &#x27;special-case })</code>.
I’ve seen developers try to implement this a few ways, each with its pros and cons.
<h3>Spreading</h3>
The easiest way to implement this function is to just provide defaults and spread the partial:
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-jsx">interface Foo {
 fieldA: string;
 fieldB?: string;
 fieldC?: boolean | null;
}

function makeFoo(partial?: Partial&lt;Foo&gt;): Foo {
 return {
	 fieldA: &#x27;test&#x27;,
 fieldB: &#x27;example&#x27;,
 fieldC: false,
 ...partial
 };
}
</code></pre></div>
Here, we create a <code>Foo</code> mock with overrides for the defaults, which are provided by <code>partial?: Partial&lt;Foo&gt;</code> . However, even though <code>fieldA</code> is required, we can see a type-hole with the default Typescript compilation settings:
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-jsx">const instance = makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });
console.log(instance.fieldA);

// No type error, but this blows up
console.log(instance.fieldA.toLowerCase());
</code></pre></div>
When we spread, <code>undefined</code> actually overrides the default! But why were we allowed to provide <code>undefined</code> in the first place?
In Typescript, <code>Partial&lt;Foo&gt;</code> keeps all the fields, but makes them optional. In the default compilation settings, an optional field can be set to <code>undefined</code>.
<a href="https://www.typescriptlang.org/play/?#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkyDohbGMgtOjyXSToTA5TYDMQXamUx-oA9O-IAHJYYACeThQ0Cg6CguRk6jAyDAAAtgLQZNcAO6I9ROXCnc6Xa63e6PZ5FChdMDoAAy6GR0HEcDaDhCxyAA">Typescript Playground Link</a>
There is a Typescript compilation flag to throw a type-error and keep our sanity: <code>exactOptionalPropertyTypes</code>. Enabling this flag makes Typescript show an error for <code>makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });</code>. We can add the field to the call if it is set to a value.
<a href="https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkuevFmyDbu-uHqRInZ6D7yDohbGMgtOjyXSToTA5TYDMQLpXChPUbjd6Ar4-P4AoFFChdMDoAAy6AA7tBxHA2g4Qk8gA">Typescript Playground Link</a>
But this causes another problem: it is perfectly valid to create an initial instance of <code>Foo</code> without fieldB being set (and its value being <code>undefined</code>). But now our <code>makeFoo</code> object doesn’t allow us to pass <code>fieldB: undefined</code> anymore. Only when the interface explicitly defines fieldB as optional AND undefined does it allow us to so.
<a href="https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQTZAB9kAVxBkIREBDJsCRUmQDCfZACNMJCHBCjkIcSRJsAvrlwxJCMMHQGAtnADWEDOgAUABzhR7OBINAAV-QJIAHk8APgBKGk8cdigIMHEoAzwASCVOShoAckh6QoAadjyVLiKIAA84Jx9dcsqOFVUaeBJaCAqCAgA6Yb8A4CD2cwsrBEd6ZFB6fSRkAF5kF3dPL2x27hpJaVl5ZHM4tlmQWnRdQZJ0Ji9FsGWIQeVyCnOZuZu3+8ez1e73yFEGYHQABl0AB3aCqOC9Lxxc5AA">Typescript Playground Link</a>
Generally this pattern without the flag is fine for creating mock data, since any type-holes would only be scoped to tests and not real production code. But the question is: can we have <code>makeFoo</code> take a partial, return Foo without type-holes, and have allow <code>undefined</code> for partials?
<h2>Null-Coalescing Every Field</h2>
Another common implementation I have seen is to add nullish coalescing to every field:
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-jsx">interface Foo {
 fieldA: string;
 fieldB?: string;
 fieldC?: boolean | null;
}

function makeFoo(partial?: Partial&lt;Foo&gt;): Foo {
 return {
	 fieldA: partial?.fieldA ?? &#x27;test&#x27;,
 fieldB: partial?.fieldB ?? &#x27;example&#x27;,
 fieldC: partial?.fieldC ?? false,
 };
} 
</code></pre></div>
Let’s also turn off the <code>exactOptionalPropertyTypes</code> compilation flag for now.
We know every field will be set correctly, so there are no type-holes in <code>Foo</code>, however, we still have the problem where we cannot override a field to the <code>unset</code> value of <code>undefined</code> :
<a href="https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=false&amp;ssl=13&amp;ssc=2&amp;pln=1&amp;pc=1#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTILm7AHjwAdKmUyDw8yADkkPSlADTsKZxkXDSZfnkFXEUlpRAAHnAWTvLVtRxi4k2+2Z759eIdhB60EDUEOrr6COb0yKD0ikjIALzIVrb2DtgjaTRGZBBEIBBkVZcN1yC394-IOiFsGyC0dDyXIkdBMBw7MB7CDTMQUX64f6A4Gg8GQ6Gw7gIxGbIEw1EQgFQ4wwgoUXJgdAAGXQAHdoOI4IsHCEEUA">Typescript Playground Link</a>
Turning on the <code>exactOptionalPropertyTypes</code> also doesn’t save us here since we didn’t have a type-issue anyway, but more of a logic issue. <code>makeFoo({ fieldB: undefined })</code> will still set <code>fieldB</code> to <code>example</code>.
<h2>Allowing bad inputs</h2>
This last approach takes the first and second approaches above and combines them using a <code>pickOrDefault</code> function. Here if any value is passed into the partial, we will return it, except when that value would be incorrect in the output type:
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-tsx">function isValuePresent&lt;T extends object&gt;(obj: T, key: keyof T): boolean {
 return key in obj;
}

function pickOrDefault&lt;T extends object, K extends keyof T&gt;(partial: T, key: K, fallbackValue: T[K]): T[K] {
 if (key in partial) {
 return partial[key];
 }

 return fallbackValue
}

interface Foo {
 fieldA: string;
 fieldB?: string;
 fieldC?: boolean | null;
}

function makeFoo(partial: Partial&lt;Foo&gt; = {}): Foo {
 return {
	 fieldA: pickOrDefault(partial, &#x27;fieldA&#x27;, &#x27;test&#x27;) ?? &#x27;test&#x27;,
 fieldB: pickOrDefault(partial, &#x27;fieldB&#x27;, &#x27;example&#x27;),
 fieldC: pickOrDefault(partial, &#x27;fieldC&#x27;, true),
 };
}

const instance = makeFoo({ fieldA: undefined, fieldB: undefined });
console.log(instance.fieldA);
console.log(instance.fieldB);

console.log(instance.fieldA.toLowerCase());

</code></pre></div>
For each field, we prefer the input partial, except here the type mismatch for <code>fieldA</code> forced us to add the default value twice, once if the partial didn’t have a value, and once if the partial had <code>undefined</code> which isn’t allows in the final version of <code>type Foo</code>.
While more verbose, this does eliminate the type holes the code!

I've discussed [full and partial objects before on this blog](/blog/post/2023-08-14-partial-objects), and in this article I'm going to investigate a common factory pattern
in Typescript that can lead to type-holes.
When writing tests or complex components, I'll often create prop factory utilities.



For tests, the goal is to create props with all the default values, except a few that may be
overidden for a specific test case. The function signature typically looks like this:

```jsx
function makeFoo(partial?: Partial<Foo>): Foo;
```

The expectation is that a software developer can call `makeFoo` and get a version of `Foo` that has all the defaults set to use in tests. Then, if the developer want to override a few fields to test an edge case, all they do is call `makeFoo({ fieldA: 'special-case })`.

I’ve seen developers try to implement this a few ways, each with its pros and cons.

### Spreading

The easiest way to implement this function is to just provide defaults and spread the partial:

```jsx
interface Foo {
 fieldA: string;
 fieldB?: string;
 fieldC?: boolean | null;
}

function makeFoo(partial?: Partial<Foo>): Foo {
 return {
	 fieldA: 'test',
 fieldB: 'example',
 fieldC: false,
 ...partial
 };
}
```

Here, we create a `Foo` mock with overrides for the defaults, which are provided by `partial?: Partial<Foo>` . However, even though `fieldA` is required, we can see a type-hole with the default Typescript compilation settings:

```jsx
const instance = makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });
console.log(instance.fieldA);

// No type error, but this blows up
console.log(instance.fieldA.toLowerCase());
```

When we spread, `undefined` actually overrides the default! But why were we allowed to provide `undefined` in the first place?

In Typescript, `Partial<Foo>` keeps all the fields, but makes them optional. In the default compilation settings, an optional field can be set to `undefined`.

[Typescript Playground Link](https://www.typescriptlang.org/play/?#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkyDohbGMgtOjyXSToTA5TYDMQXamUx-oA9O-IAHJYYACeThQ0Cg6CguRk6jAyDAAAtgLQZNcAO6I9ROXCnc6Xa63e6PZ5FChdMDoAAy6GR0HEcDaDhCxyAA)

There is a Typescript compilation flag to throw a type-error and keep our sanity: `exactOptionalPropertyTypes`. Enabling this flag makes Typescript show an error for `makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });`. We can add the field to the call if it is set to a value.

[Typescript Playground Link](https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkuevFmyDbu-uHqRInZ6D7yDohbGMgtOjyXSToTA5TYDMQLpXChPUbjd6Ar4-P4AoFFChdMDoAAy6AA7tBxHA2g4Qk8gA)

But this causes another problem: it is perfectly valid to create an initial instance of `Foo` without fieldB being set (and its value being `undefined`). But now our `makeFoo` object doesn’t allow us to pass `fieldB: undefined` anymore. Only when the interface explicitly defines fieldB as optional AND undefined does it allow us to so.

[Typescript Playground Link](https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQTZAB9kAVxBkIREBDJsCRUmQDCfZACNMJCHBCjkIcSRJsAvrlwxJCMMHQGAtnADWEDOgAUABzhR7OBINAAV-QJIAHk8APgBKGk8cdigIMHEoAzwASCVOShoAckh6QoAadjyVLiKIAA84Jx9dcsqOFVUaeBJaCAqCAgA6Yb8A4CD2cwsrBEd6ZFB6fSRkAF5kF3dPL2x27hpJaVl5ZHM4tlmQWnRdQZJ0Ji9FsGWIQeVyCnOZuZu3+8ez1e73yFEGYHQABl0AB3aCqOC9Lxxc5AA)

Generally this pattern without the flag is fine for creating mock data, since any type-holes would only be scoped to tests and not real production code. But the question is: can we have `makeFoo` take a partial, return Foo without type-holes, and have allow `undefined` for partials?

## Null-Coalescing Every Field

Another common implementation I have seen is to add nullish coalescing to every field:

```jsx
interface Foo {
 fieldA: string;
 fieldB?: string;
 fieldC?: boolean | null;
}

function makeFoo(partial?: Partial<Foo>): Foo {
 return {
	 fieldA: partial?.fieldA ?? 'test',
 fieldB: partial?.fieldB ?? 'example',
 fieldC: partial?.fieldC ?? false,
 };
} 
```

Let’s also turn off the `exactOptionalPropertyTypes` compilation flag for now.

We know every field will be set correctly, so there are no type-holes in `Foo`, however, we still have the problem where we cannot override a field to the `unset` value of `undefined` :

[Typescript Playground Link](https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=false&ssl=13&ssc=2&pln=1&pc=1#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTILm7AHjwAdKmUyDw8yADkkPSlADTsKZxkXDSZfnkFXEUlpRAAHnAWTvLVtRxi4k2+2Z759eIdhB60EDUEOrr6COb0yKD0ikjIALzIVrb2DtgjaTRGZBBEIBBkVZcN1yC394-IOiFsGyC0dDyXIkdBMBw7MB7CDTMQUX64f6A4Gg8GQ6Gw7gIxGbIEw1EQgFQ4wwgoUXJgdAAGXQAHdoOI4IsHCEEUA)

Turning on the `exactOptionalPropertyTypes` also doesn’t save us here since we didn’t have a type-issue anyway, but more of a logic issue. `makeFoo({ fieldB: undefined })` will still set `fieldB` to `example`.

## Allowing bad inputs

This last approach takes the first and second approaches above and combines them using a `pickOrDefault` function. Here if any value is passed into the partial, we will return it, except when that value would be incorrect in the output type:

```tsx
function isValuePresent<T extends object>(obj: T, key: keyof T): boolean {
 return key in obj;
}

function pickOrDefault<T extends object, K extends keyof T>(partial: T, key: K, fallbackValue: T[K]): T[K] {
 if (key in partial) {
 return partial[key];
 }

 return fallbackValue
}

interface Foo {
 fieldA: string;
 fieldB?: string;
 fieldC?: boolean | null;
}

function makeFoo(partial: Partial<Foo> = {}): Foo {
 return {
	 fieldA: pickOrDefault(partial, 'fieldA', 'test') ?? 'test',
 fieldB: pickOrDefault(partial, 'fieldB', 'example'),
 fieldC: pickOrDefault(partial, 'fieldC', true),
 };
}

const instance = makeFoo({ fieldA: undefined, fieldB: undefined });
console.log(instance.fieldA);
console.log(instance.fieldB);

console.log(instance.fieldA.toLowerCase());

```

For each field, we prefer the input partial, except here the type mismatch for `fieldA` forced us to add the default value twice, once if the partial didn’t have a value, and once if the partial had `undefined` which isn’t allows in the final version of `type Foo`.

While more verbose, this does eliminate the type holes the code!

Forbidden Typescript: Spreading Type-holes

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    img: "img",
    li: "li",
    ol: "ol",
    p: "p",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "At the height of the GPU craze, around 2021, when everyone was holed up in their homes due to COVID, the 30 series of Nvidia GPUs was extremely difficult to purchase. The scarcity was due to a few factors: the COVID pandemic had disrupted supply chains across the world, Taiwan was experiencing a severe drought that was impacting chip production, and cryptocurrency, especially ETH, was gaining value, making mining it was the latest GPU series incredibly lucrative."
    }), "\n", _jsx(_components.p, {
      children: "Since the supply was low and demand was high, this created two types of markets: one was the second hand market for GPUs where an $800 GPU could go for $3500 in cash when sold to someone mining cryptocurrency. Because of the massive mark up, buying and selling software to automate the process of buying GPUs when they \"dropped\" on a site was also growing as a market. These were called \"bots\" in the community, where customers trying to get a single GPU for their gaming PC were competing against hundreds of not thousands of bots flooding websites when they dropped. Common sites like Nvidia, AMD, Best Buy, and Zotac would get flooded with millions of requests when they added GPU stock the site."
    }), "\n", _jsx(_components.p, {
      children: "To combat this, different market places tried different techniques to verify that humans were the ones trying to access the site. But due to time constraints, these never seemed to be properly implemented."
    }), "\n", _jsx(_components.p, {
      children: "Zotac added a Cloudflare verification to their site that would try to verify that a user was real. The setting they used though attempted to not disrupt real users, but only issue a challenge to visitors it deemed \"bots\". A puppeteer script could easily bypass this by first visiting other sites that used cloud flare (but didn't issue challenges) and then visiting the Zotac site. A fresh puppeteer instance would be issued a challenge, but one that visited other sites before would not."
    }), "\n", _jsx(_components.p, {
      children: "There were other tricks people used to help them attempt to secure GPUs. My favorite was adding a Zotac TShirt to your cart before a drop so that you could input all of your shipping and payment information. Then when a drop was detected, you'd simply issue the add to cart API call, and then the checkout API call. This would bypass the checkout walkthrough. When the website was flooded with millions of API calls, you only needed two API calls to succeed, rather than 10 or more."
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.img, {
        src: "/media/2025-06-16-gpus-best-buy-queues/do-something.jpg",
        alt: "Do something zotac"
      })
    }), "\n", _jsx(_components.p, {
      children: "Automating this way worked so well that a puppeteer script that I wrote was able to add 4 GPUs to one cart, send me a Pushbullet notification to wake me up in the middle of the night, and I just had to click one last step to verify the checkout manually since I didn't trust a script with actually making card payments on my behalf."
    }), "\n", _jsx(_components.p, {
      children: "Zotac did finally learn from this and finally upped the Cloudflare bot check to issue a challenge to all users during the rest of the 30 series release. They also released a new site that made it harder to track when GPU stock was released."
    }), "\n", _jsx(_components.p, {
      children: "Best Buy must have had many complaints about the terrible system they had. Any GPU stock they had would almost immediately be gone by the time s human would show up to try to purchase one. At the time, they had a graphql-like API that allowed anyone to request with any frequency the in-stock status of any number of skus on their system. If you used puppeteer to visit the site, grab the cookies, and then issue an API request to this API, you could consistently check the status of all GPU skus every 5 or so seconds for the entire day. No rate limits, no other form of authentication other than public cookies."
    }), "\n", _jsx(_components.p, {
      children: "So that explained how bots were able to detect GPUs so quickly and with no form of bot checking or challenge system, once the GPU was in someone's cart, it was very easy to checkout since the Best Buy site would continue to work even when flooded with requests."
    }), "\n", _jsx(_components.p, {
      children: "To mitigate this, some poor group of developers was tasked with creating a queue system. I'm guessing the time crunch was real because when I went to investigate how this queue worked, it was entirely determined by the user cookie that was issued."
    }), "\n", _jsx(_components.p, {
      children: "Here's how the queue worked for the end user: the user would get a notification from their favorite discord server that there was a drop (since the graphql-like endpoint was still available). They would go to the page for the GPU they wanted to purchase and click \"add to cart\". The button would then change to a \"waiting in queue\" message and be disabled. There was no indication how long that queue would be. Then after some time, the button would change back to \"add to cart\". The user clicks it, and if there was still stock, the GPU would be added to cart. Then the user needed to quickly checkout before the stock ran out."
    }), "\n", _jsx(_components.p, {
      children: "I was really curious on the part where there was no indication of how long the queue was. When testing using a 5950 AMD CPU that still had stock, but had the queue system enabled, I determined that the wait time was effectively random. It didn't matter if you were the first one to click that button, it would just assign a random queue time to you before you could cart the item."
    }), "\n", _jsx(_components.p, {
      children: "I ran more tests. I recorded a small sample of wait times and they would vary from a minute to over an hour."
    }), "\n", _jsx(_components.p, {
      children: "I decided to investigate what code determined when the button changed back to \"add to cart\". No API calls were made while waiting in queue. Huh okay so the browser code already knows how long the queue time is."
    }), "\n", _jsx(_components.p, {
      children: "The UI code on the Best Buy site is not just minified, but also mangled. This process will replace function names, introduce additional function calls to obfuscate what functions are doing, and generally makes it very difficult to debug. After tracing back what changed the button and the call stack, I was able to finally piece together how the queue time was determined."
    }), "\n", _jsx(_components.p, {
      children: "When a user visited the best buy site, they were issued a public cookie. It looked like a special UUID. The middle section of the UUID must have some special properties to meet some hash check value from what I could tell. The point is that I must have had some guaranteed randomness to it that gave the developers the idea to reuse this section to deterministically evaluate a queue time on both the browser and the server."
    }), "\n", _jsx(_components.p, {
      children: "I created a browser extension to test the hypothesis:"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Show the queue time for the current cookie on the page by injecting some HTML."
      }), "\n", _jsx(_components.li, {
        children: "Add a button to \"roll for a better queue time\". This would issue a request to get 20 new cookies, figure out which queue time was best, set the browser cookie to that cookies and display the new queue time."
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "I tested with the 5950 CPU and saw my queue time go from 30 minutes to 1 minute. Success!"
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.img, {
        src: "/media/2025-06-16-gpus-best-buy-queues/queue-times.png",
        alt: "Queue times"
      })
    }), "\n", _jsx(_components.p, {
      children: "I had a close group of friends that I rolled this out to. The next Best Buy drop happened and we were all able to get the founders edition cards. Finally!"
    }), "\n", _jsx(_components.p, {
      children: "There was a popular bot net that effectively did the same thing. I don't know if they knew how to calculate the queue times, but they would spin up 20+ browsers with the best buy site and wait for the first one to have the add to cart button, and then give the purchaser of the bot net subscription the cookies for that session."
    }), "\n", _jsx(_components.p, {
      children: "Times were dire and I thought this approach from best buy was garbage. It effectively made individuals - who might have stood a chance before - now have to wait some random amount of time against those with those who had hundreds of bots trying to get a good queue time."
    }), "\n", _jsx(_components.p, {
      children: "Conveniently someone reached out to me to commission a chrome extension related to getting GPUs. They wanted to know what was possible and I told them I figured out the queue system times, and how an average person could get a better queue time. We released a branded version of my extension and some 10,000 people downloaded it."
    }), "\n", _jsx(_components.p, {
      children: "And then I waited for the next Best Buy drop."
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.img, {
        src: "/media/2025-06-16-gpus-best-buy-queues/a-rare-occurence.png",
        alt: "A rare occurrence"
      })
    }), "\n", _jsx(_components.p, {
      children: "The alert went out that there was stock."
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.img, {
        src: "/media/2025-06-16-gpus-best-buy-queues/extension.png",
        alt: "extension"
      })
    }), "\n", _jsx(_components.p, {
      children: "And the website crashed 20 seconds into the drop."
    }), "\n", _jsx(_components.p, {
      children: "I was actually surprised since their site had done so well before. But I guess people rolling for new cookies 20 times in a second was enough to bring the site down momentarily."
    }), "\n", _jsx(_components.p, {
      children: "After that drop, Best Buy held off on GPU drops for over a month. When the next drop finally happened, they had changed the queue system slightly. The cookie was no longer the source for the queue time, and rolling for a new cookie did not give you a new queue time. Finally."
    }), "\n", _jsx(_components.p, {
      children: "Your queue position was still effectively random, but at least it could no longer be gamed by requesting new sessions. Nor could you know your queue time even if you did ask for new sessions."
    }), "\n", _jsx(_components.p, {
      children: "Props to Best Buy for continuing to experience with this too. Pokemon cards are the new drops and they force people to use the mobile app now to request a time in queue."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


At the height of the GPU craze, around 2021, when everyone was holed up in their homes due to COVID, the 30 series of Nvidia GPUs was extremely difficult to purchase. The scarcity was due to a few factors: the COVID pandemic had disrupted supply chains across the world, Taiwan was experiencing a severe drought that was impacting chip production, and cryptocurrency, especially ETH, was gaining value, making mining it was the latest GPU series incredibly lucrative.
Since the supply was low and demand was high, this created two types of markets: one was the second hand market for GPUs where an $800 GPU could go for $3500 in cash when sold to someone mining cryptocurrency. Because of the massive mark up, buying and selling software to automate the process of buying GPUs when they &quot;dropped&quot; on a site was also growing as a market. These were called &quot;bots&quot; in the community, where customers trying to get a single GPU for their gaming PC were competing against hundreds of not thousands of bots flooding websites when they dropped. Common sites like Nvidia, AMD, Best Buy, and Zotac would get flooded with millions of requests when they added GPU stock the site.
To combat this, different market places tried different techniques to verify that humans were the ones trying to access the site. But due to time constraints, these never seemed to be properly implemented.
Zotac added a Cloudflare verification to their site that would try to verify that a user was real. The setting they used though attempted to not disrupt real users, but only issue a challenge to visitors it deemed &quot;bots&quot;. A puppeteer script could easily bypass this by first visiting other sites that used cloud flare (but didn&#x27;t issue challenges) and then visiting the Zotac site. A fresh puppeteer instance would be issued a challenge, but one that visited other sites before would not.
There were other tricks people used to help them attempt to secure GPUs. My favorite was adding a Zotac TShirt to your cart before a drop so that you could input all of your shipping and payment information. Then when a drop was detected, you&#x27;d simply issue the add to cart API call, and then the checkout API call. This would bypass the checkout walkthrough. When the website was flooded with millions of API calls, you only needed two API calls to succeed, rather than 10 or more.
<img alt="Do something zotac" src="/media/2025-06-16-gpus-best-buy-queues/do-something.jpg" style="max-height:500px;margin:auto;text-align:center"/>
Automating this way worked so well that a puppeteer script that I wrote was able to add 4 GPUs to one cart, send me a Pushbullet notification to wake me up in the middle of the night, and I just had to click one last step to verify the checkout manually since I didn&#x27;t trust a script with actually making card payments on my behalf.
Zotac did finally learn from this and finally upped the Cloudflare bot check to issue a challenge to all users during the rest of the 30 series release. They also released a new site that made it harder to track when GPU stock was released.
Best Buy must have had many complaints about the terrible system they had. Any GPU stock they had would almost immediately be gone by the time s human would show up to try to purchase one. At the time, they had a graphql-like API that allowed anyone to request with any frequency the in-stock status of any number of skus on their system. If you used puppeteer to visit the site, grab the cookies, and then issue an API request to this API, you could consistently check the status of all GPU skus every 5 or so seconds for the entire day. No rate limits, no other form of authentication other than public cookies.
So that explained how bots were able to detect GPUs so quickly and with no form of bot checking or challenge system, once the GPU was in someone&#x27;s cart, it was very easy to checkout since the Best Buy site would continue to work even when flooded with requests.
To mitigate this, some poor group of developers was tasked with creating a queue system. I&#x27;m guessing the time crunch was real because when I went to investigate how this queue worked, it was entirely determined by the user cookie that was issued.
Here&#x27;s how the queue worked for the end user: the user would get a notification from their favorite discord server that there was a drop (since the graphql-like endpoint was still available). They would go to the page for the GPU they wanted to purchase and click &quot;add to cart&quot;. The button would then change to a &quot;waiting in queue&quot; message and be disabled. There was no indication how long that queue would be. Then after some time, the button would change back to &quot;add to cart&quot;. The user clicks it, and if there was still stock, the GPU would be added to cart. Then the user needed to quickly checkout before the stock ran out.
I was really curious on the part where there was no indication of how long the queue was. When testing using a 5950 AMD CPU that still had stock, but had the queue system enabled, I determined that the wait time was effectively random. It didn&#x27;t matter if you were the first one to click that button, it would just assign a random queue time to you before you could cart the item.
I ran more tests. I recorded a small sample of wait times and they would vary from a minute to over an hour.
I decided to investigate what code determined when the button changed back to &quot;add to cart&quot;. No API calls were made while waiting in queue. Huh okay so the browser code already knows how long the queue time is.
The UI code on the Best Buy site is not just minified, but also mangled. This process will replace function names, introduce additional function calls to obfuscate what functions are doing, and generally makes it very difficult to debug. After tracing back what changed the button and the call stack, I was able to finally piece together how the queue time was determined.
When a user visited the best buy site, they were issued a public cookie. It looked like a special UUID. The middle section of the UUID must have some special properties to meet some hash check value from what I could tell. The point is that I must have had some guaranteed randomness to it that gave the developers the idea to reuse this section to deterministically evaluate a queue time on both the browser and the server.
I created a browser extension to test the hypothesis:
<ol>
<li>Show the queue time for the current cookie on the page by injecting some HTML.</li>
<li>Add a button to &quot;roll for a better queue time&quot;. This would issue a request to get 20 new cookies, figure out which queue time was best, set the browser cookie to that cookies and display the new queue time.</li>
</ol>
I tested with the 5950 CPU and saw my queue time go from 30 minutes to 1 minute. Success!
<img alt="Queue times" src="/media/2025-06-16-gpus-best-buy-queues/queue-times.png" style="max-height:500px;margin:auto;text-align:center"/>
I had a close group of friends that I rolled this out to. The next Best Buy drop happened and we were all able to get the founders edition cards. Finally!
There was a popular bot net that effectively did the same thing. I don&#x27;t know if they knew how to calculate the queue times, but they would spin up 20+ browsers with the best buy site and wait for the first one to have the add to cart button, and then give the purchaser of the bot net subscription the cookies for that session.
Times were dire and I thought this approach from best buy was garbage. It effectively made individuals - who might have stood a chance before - now have to wait some random amount of time against those with those who had hundreds of bots trying to get a good queue time.
Conveniently someone reached out to me to commission a chrome extension related to getting GPUs. They wanted to know what was possible and I told them I figured out the queue system times, and how an average person could get a better queue time. We released a branded version of my extension and some 10,000 people downloaded it.
And then I waited for the next Best Buy drop.
<img alt="A rare occurrence" src="/media/2025-06-16-gpus-best-buy-queues/a-rare-occurence.png" style="max-height:500px;margin:auto;text-align:center"/>
The alert went out that there was stock.
<img alt="extension" src="/media/2025-06-16-gpus-best-buy-queues/extension.png" style="max-height:500px;margin:auto;text-align:center"/>
And the website crashed 20 seconds into the drop.
I was actually surprised since their site had done so well before. But I guess people rolling for new cookies 20 times in a second was enough to bring the site down momentarily.
After that drop, Best Buy held off on GPU drops for over a month. When the next drop finally happened, they had changed the queue system slightly. The cookie was no longer the source for the queue time, and rolling for a new cookie did not give you a new queue time. Finally.
Your queue position was still effectively random, but at least it could no longer be gamed by requesting new sessions. Nor could you know your queue time even if you did ask for new sessions.
Props to Best Buy for continuing to experience with this too. Pokemon cards are the new drops and they force people to use the mobile app now to request a time in queue.

At the height of the GPU craze, around 2021, when everyone was holed up in their homes due to COVID, the 30 series of Nvidia GPUs was extremely difficult to purchase. The scarcity was due to a few factors: the COVID pandemic had disrupted supply chains across the world, Taiwan was experiencing a severe drought that was impacting chip production, and cryptocurrency, especially ETH, was gaining value, making mining it was the latest GPU series incredibly lucrative.



Since the supply was low and demand was high, this created two types of markets: one was the second hand market for GPUs where an \$800 GPU could go for \$3500 in cash when sold to someone mining cryptocurrency. Because of the massive mark up, buying and selling software to automate the process of buying GPUs when they "dropped" on a site was also growing as a market. These were called "bots" in the community, where customers trying to get a single GPU for their gaming PC were competing against hundreds of not thousands of bots flooding websites when they dropped. Common sites like Nvidia, AMD, Best Buy, and Zotac would get flooded with millions of requests when they added GPU stock the site.

To combat this, different market places tried different techniques to verify that humans were the ones trying to access the site. But due to time constraints, these never seemed to be properly implemented.

Zotac added a Cloudflare verification to their site that would try to verify that a user was real. The setting they used though attempted to not disrupt real users, but only issue a challenge to visitors it deemed "bots". A puppeteer script could easily bypass this by first visiting other sites that used cloud flare (but didn't issue challenges) and then visiting the Zotac site. A fresh puppeteer instance would be issued a challenge, but one that visited other sites before would not.

There were other tricks people used to help them attempt to secure GPUs. My favorite was adding a Zotac TShirt to your cart before a drop so that you could input all of your shipping and payment information. Then when a drop was detected, you'd simply issue the add to cart API call, and then the checkout API call. This would bypass the checkout walkthrough. When the website was flooded with millions of API calls, you only needed two API calls to succeed, rather than 10 or more.

![Do something zotac](/media/2025-06-16-gpus-best-buy-queues/do-something.jpg)

Automating this way worked so well that a puppeteer script that I wrote was able to add 4 GPUs to one cart, send me a Pushbullet notification to wake me up in the middle of the night, and I just had to click one last step to verify the checkout manually since I didn't trust a script with actually making card payments on my behalf.

Zotac did finally learn from this and finally upped the Cloudflare bot check to issue a challenge to all users during the rest of the 30 series release. They also released a new site that made it harder to track when GPU stock was released.

Best Buy must have had many complaints about the terrible system they had. Any GPU stock they had would almost immediately be gone by the time s human would show up to try to purchase one. At the time, they had a graphql-like API that allowed anyone to request with any frequency the in-stock status of any number of skus on their system. If you used puppeteer to visit the site, grab the cookies, and then issue an API request to this API, you could consistently check the status of all GPU skus every 5 or so seconds for the entire day. No rate limits, no other form of authentication other than public cookies.

So that explained how bots were able to detect GPUs so quickly and with no form of bot checking or challenge system, once the GPU was in someone's cart, it was very easy to checkout since the Best Buy site would continue to work even when flooded with requests.

To mitigate this, some poor group of developers was tasked with creating a queue system. I'm guessing the time crunch was real because when I went to investigate how this queue worked, it was entirely determined by the user cookie that was issued.

Here's how the queue worked for the end user: the user would get a notification from their favorite discord server that there was a drop (since the graphql-like endpoint was still available). They would go to the page for the GPU they wanted to purchase and click "add to cart". The button would then change to a "waiting in queue" message and be disabled. There was no indication how long that queue would be. Then after some time, the button would change back to "add to cart". The user clicks it, and if there was still stock, the GPU would be added to cart. Then the user needed to quickly checkout before the stock ran out.

I was really curious on the part where there was no indication of how long the queue was. When testing using a 5950 AMD CPU that still had stock, but had the queue system enabled, I determined that the wait time was effectively random. It didn't matter if you were the first one to click that button, it would just assign a random queue time to you before you could cart the item.

I ran more tests. I recorded a small sample of wait times and they would vary from a minute to over an hour.

I decided to investigate what code determined when the button changed back to "add to cart". No API calls were made while waiting in queue. Huh okay so the browser code already knows how long the queue time is.

The UI code on the Best Buy site is not just minified, but also mangled. This process will replace function names, introduce additional function calls to obfuscate what functions are doing, and generally makes it very difficult to debug. After tracing back what changed the button and the call stack, I was able to finally piece together how the queue time was determined.

When a user visited the best buy site, they were issued a public cookie. It looked like a special UUID. The middle section of the UUID must have some special properties to meet some hash check value from what I could tell. The point is that I must have had some guaranteed randomness to it that gave the developers the idea to reuse this section to deterministically evaluate a queue time on both the browser and the server.

I created a browser extension to test the hypothesis:

1. Show the queue time for the current cookie on the page by injecting some HTML.
2. Add a button to "roll for a better queue time". This would issue a request to get 20 new cookies, figure out which queue time was best, set the browser cookie to that cookies and display the new queue time.

I tested with the 5950 CPU and saw my queue time go from 30 minutes to 1 minute. Success!

![Queue times](/media/2025-06-16-gpus-best-buy-queues/queue-times.png)

I had a close group of friends that I rolled this out to. The next Best Buy drop happened and we were all able to get the founders edition cards. Finally!

There was a popular bot net that effectively did the same thing. I don't know if they knew how to calculate the queue times, but they would spin up 20+ browsers with the best buy site and wait for the first one to have the add to cart button, and then give the purchaser of the bot net subscription the cookies for that session.

Times were dire and I thought this approach from best buy was garbage. It effectively made individuals - who might have stood a chance before - now have to wait some random amount of time against those with those who had hundreds of bots trying to get a good queue time.

Conveniently someone reached out to me to commission a chrome extension related to getting GPUs. They wanted to know what was possible and I told them I figured out the queue system times, and how an average person could get a better queue time. We released a branded version of my extension and some 10,000 people downloaded it.

And then I waited for the next Best Buy drop.

![A rare occurrence](/media/2025-06-16-gpus-best-buy-queues/a-rare-occurence.png)

The alert went out that there was stock.

![extension](/media/2025-06-16-gpus-best-buy-queues/extension.png)

And the website crashed 20 seconds into the drop.

I was actually surprised since their site had done so well before. But I guess people rolling for new cookies 20 times in a second was enough to bring the site down momentarily.

After that drop, Best Buy held off on GPU drops for over a month. When the next drop finally happened, they had changed the queue system slightly. The cookie was no longer the source for the queue time, and rolling for a new cookie did not give you a new queue time. Finally.

Your queue position was still effectively random, but at least it could no longer be gamed by requesting new sessions. Nor could you know your queue time even if you did ask for new sessions.

Props to Best Buy for continuing to experience with this too. Pokemon cards are the new drops and they force people to use the mobile app now to request a time in queue.

API Complexity Revisited

Forbidden Typescript: Spreading Type-holes

GPUs and Best Buy Queues