programming posts - idmontie's Portfolio

"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
};


<p>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.</p>
<p>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:</p>
<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>
<p>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>.</p>
<p>I’ve seen developers try to implement this a few ways, each with its pros and cons.</p>
<h3>Spreading</h3>
<p>The easiest way to implement this function is to just provide defaults and spread the partial:</p>
<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>
<p>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:</p>
<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>
<p>When we spread, <code>undefined</code> actually overrides the default! But why were we allowed to provide <code>undefined</code> in the first place?</p>
<p>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>.</p>
<p><a href="https://www.typescriptlang.org/play/?#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkyDohbGMgtOjyXSToTA5TYDMQXamUx-oA9O-IAHJYYACeThQ0Cg6CguRk6jAyDAAAtgLQZNcAO6I9ROXCnc6Xa63e6PZ5FChdMDoAAy6GR0HEcDaDhCxyAA">Typescript Playground Link</a></p>
<p>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.</p>
<p><a href="https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkuevFmyDbu-uHqRInZ6D7yDohbGMgtOjyXSToTA5TYDMQLpXChPUbjd6Ar4-P4AoFFChdMDoAAy6AA7tBxHA2g4Qk8gA">Typescript Playground Link</a></p>
<p>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.</p>
<p><a href="https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQTZAB9kAVxBkIREBDJsCRUmQDCfZACNMJCHBCjkIcSRJsAvrlwxJCMMHQGAtnADWEDOgAUABzhR7OBINAAV-QJIAHk8APgBKGk8cdigIMHEoAzwASCVOShoAckh6QoAadjyVLiKIAA84Jx9dcsqOFVUaeBJaCAqCAgA6Yb8A4CD2cwsrBEd6ZFB6fSRkAF5kF3dPL2x27hpJaVl5ZHM4tlmQWnRdQZJ0Ji9FsGWIQeVyCnOZuZu3+8ez1e73yFEGYHQABl0AB3aCqOC9Lxxc5AA">Typescript Playground Link</a></p>
<p>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?</p>
<h2>Null-Coalescing Every Field</h2>
<p>Another common implementation I have seen is to add nullish coalescing to every field:</p>
<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>
<p>Let’s also turn off the <code>exactOptionalPropertyTypes</code> compilation flag for now.</p>
<p>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> :</p>
<p><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></p>
<p>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>.</p>
<h2>Allowing bad inputs</h2>
<p>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:</p>
<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>
<p>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>.</p>
<p>While more verbose, this does eliminate the type holes the code!</p>

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 = {
    code: "code",
    li: "li",
    p: "p",
    ul: "ul",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "We all know that naming things is right up there in the top three most difficult things about programming, right next to concurrency and caching."
    }), "\n", _jsx(_components.p, {
      children: "For common utility functions, I typically follow a few rules to at least prefix the function names in a consistent and meaningful way. Some of these are borrowed from React Testing Library, whose naming scheme I like very much as it is internally consistent with the return types that certain classes of functions return, but also easy to memorize how they behave."
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "getFoo"
        }), " - “get” as a utility function prefix name should indicate that the function will return ", _jsx(_components.code, {
          children: "type Foo"
        }), " and that it is meant to be synchronous and without side-effects. Typically a ", _jsx(_components.code, {
          children: "getFoo"
        }), " would always return Foo from the current context or in-memory synchronous data store."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "queryFoo"
        }), " - functions with the prefix “query” should return ", _jsx(_components.code, {
          children: "type Promise<Foo>"
        }), ". Querying usually implies getting data asynchronously from an external data store and may have side-effects, let alone caching that data in a synchronous store for easier data-fetching in the future. I have also seen ", _jsx(_components.code, {
          children: "fetchFoo"
        }), " to indicate that the function will retrieve data from an external store, but I typically reserve ", _jsx(_components.code, {
          children: "fetch"
        }), " for low-level wrappers of the ", _jsx(_components.code, {
          children: "fetch"
        }), " utility."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "createFoo"
        }), " - similar to ", _jsx(_components.code, {
          children: "getXYZ"
        }), ", this creates a local, synchronously made instance of ", _jsx(_components.code, {
          children: "Foo"
        }), ". There may be side-effects here, but typically this function is idempotent. Following the pattern of ", _jsx(_components.code, {
          children: "typeOrm"
        }), " , creating an instance of ", _jsx(_components.code, {
          children: "Foo"
        }), " is NOT the same as making an instance with nice defaults. This instance of ", _jsx(_components.code, {
          children: "Foo"
        }), " might not have any data initialized, but may only come with the instance methods and unset variables."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "mutateFoo"
        }), " or ", _jsx(_components.code, {
          children: "saveFoo"
        }), " - create or update an instance of ", _jsx(_components.code, {
          children: "type Foo"
        }), ". Typically the only side-effect in these functions is storing the data in a cache, database, file, etc."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "makeFoo"
        }), " - this is very similar to ", _jsx(_components.code, {
          children: "createFoo"
        }), ", but this is typically reserved for mocks and default versions of ", _jsx(_components.code, {
          children: "Foo"
        }), ". For example, if you have a form with a lot of presets that a user is filling out, you might have a default version of the ", _jsx(_components.code, {
          children: "Foo"
        }), " object that you want to represent in your view state. When you extract that default, it would be returned in a ", _jsx(_components.code, {
          children: "makeFoo"
        }), " function (that might call ", _jsx(_components.code, {
          children: "createFoo"
        }), " in its internals to make an instance of ", _jsx(_components.code, {
          children: "Foo"
        }), "). Likewise, for mocks, you may want to make the process of creating a mock with a bunch of defaults simple, and have a function named ", _jsx(_components.code, {
          children: "createMockFoo"
        }), " with signature: ", _jsx(_components.code, {
          children: "createMockFoo(overrides?: Partial<Foo>): Foo"
        }), "."]
      }), "\n"]
    }), "\n", _jsxs(_components.p, {
      children: ["This is by no means an exhaustive list, but I do find it helpful to follow this pattern for code consistency and setting expectations with other software developers. If I write a function called ", _jsx(_components.code, {
        children: "getFoo"
      }), ", it shouldn’t query a database. If I write a ", _jsx(_components.code, {
        children: "makeFoo"
      }), " function, I would expect a nicely initialized ", _jsx(_components.code, {
        children: "Foo"
      }), " to pop out."]
    }), "\n", _jsxs(_components.p, {
      children: ["To me, following these conventions is similar to legalistic words like “must” and “can”. If we were to use these words in programming conventions, then ", _jsx(_components.code, {
        children: "mustXYZ"
      }), " would mean a function will ALWAYS return a value, no matter what, while ", _jsx(_components.code, {
        children: "canXYZ"
      }), " would mean the function could return ", _jsx(_components.code, {
        children: "null | undefined"
      }), " as well. Similarly, having some standard naming convention helps teams write code that others will understand without having to read jsdocs or dive deeper into the code every single time."]
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>We all know that naming things is right up there in the top three most difficult things about programming, right next to concurrency and caching.</p>
<p>For common utility functions, I typically follow a few rules to at least prefix the function names in a consistent and meaningful way. Some of these are borrowed from React Testing Library, whose naming scheme I like very much as it is internally consistent with the return types that certain classes of functions return, but also easy to memorize how they behave.</p>
<ul>
<li><code>getFoo</code> - “get” as a utility function prefix name should indicate that the function will return <code>type Foo</code> and that it is meant to be synchronous and without side-effects. Typically a <code>getFoo</code> would always return Foo from the current context or in-memory synchronous data store.</li>
<li><code>queryFoo</code> - functions with the prefix “query” should return <code>type Promise&lt;Foo&gt;</code>. Querying usually implies getting data asynchronously from an external data store and may have side-effects, let alone caching that data in a synchronous store for easier data-fetching in the future. I have also seen <code>fetchFoo</code> to indicate that the function will retrieve data from an external store, but I typically reserve <code>fetch</code> for low-level wrappers of the <code>fetch</code> utility.</li>
<li><code>createFoo</code> - similar to <code>getXYZ</code>, this creates a local, synchronously made instance of <code>Foo</code>. There may be side-effects here, but typically this function is idempotent. Following the pattern of <code>typeOrm</code> , creating an instance of <code>Foo</code> is NOT the same as making an instance with nice defaults. This instance of <code>Foo</code> might not have any data initialized, but may only come with the instance methods and unset variables.</li>
<li><code>mutateFoo</code> or <code>saveFoo</code> - create or update an instance of <code>type Foo</code>. Typically the only side-effect in these functions is storing the data in a cache, database, file, etc.</li>
<li><code>makeFoo</code> - this is very similar to <code>createFoo</code>, but this is typically reserved for mocks and default versions of <code>Foo</code>. For example, if you have a form with a lot of presets that a user is filling out, you might have a default version of the <code>Foo</code> object that you want to represent in your view state. When you extract that default, it would be returned in a <code>makeFoo</code> function (that might call <code>createFoo</code> in its internals to make an instance of <code>Foo</code>). Likewise, for mocks, you may want to make the process of creating a mock with a bunch of defaults simple, and have a function named <code>createMockFoo</code> with signature: <code>createMockFoo(overrides?: Partial&lt;Foo&gt;): Foo</code>.</li>
</ul>
<p>This is by no means an exhaustive list, but I do find it helpful to follow this pattern for code consistency and setting expectations with other software developers. If I write a function called <code>getFoo</code>, it shouldn’t query a database. If I write a <code>makeFoo</code> function, I would expect a nicely initialized <code>Foo</code> to pop out.</p>
<p>To me, following these conventions is similar to legalistic words like “must” and “can”. If we were to use these words in programming conventions, then <code>mustXYZ</code> would mean a function will ALWAYS return a value, no matter what, while <code>canXYZ</code> would mean the function could return <code>null | undefined</code> as well. Similarly, having some standard naming convention helps teams write code that others will understand without having to read jsdocs or dive deeper into the code every single time.</p>


We all know that naming things is right up there in the top three most difficult things about programming, right next to concurrency and caching.

For common utility functions, I typically follow a few rules to at least prefix the function names in a consistent and meaningful way. Some of these are borrowed from React Testing Library, whose naming scheme I like very much as it is internally consistent with the return types that certain classes of functions return, but also easy to memorize how they behave.

- `getFoo` - “get” as a utility function prefix name should indicate that the function will return `type Foo` and that it is meant to be synchronous and without side-effects. Typically a `getFoo` would always return Foo from the current context or in-memory synchronous data store.
- `queryFoo` - functions with the prefix “query” should return `type Promise<Foo>`. Querying usually implies getting data asynchronously from an external data store and may have side-effects, let alone caching that data in a synchronous store for easier data-fetching in the future. I have also seen `fetchFoo` to indicate that the function will retrieve data from an external store, but I typically reserve `fetch` for low-level wrappers of the `fetch` utility.
- `createFoo` - similar to `getXYZ`, this creates a local, synchronously made instance of `Foo`. There may be side-effects here, but typically this function is idempotent. Following the pattern of `typeOrm` , creating an instance of `Foo` is NOT the same as making an instance with nice defaults. This instance of `Foo` might not have any data initialized, but may only come with the instance methods and unset variables.
- `mutateFoo` or `saveFoo` - create or update an instance of `type Foo`. Typically the only side-effect in these functions is storing the data in a cache, database, file, etc.
- `makeFoo` - this is very similar to `createFoo`, but this is typically reserved for mocks and default versions of `Foo`. For example, if you have a form with a lot of presets that a user is filling out, you might have a default version of the `Foo` object that you want to represent in your view state. When you extract that default, it would be returned in a `makeFoo` function (that might call `createFoo` in its internals to make an instance of `Foo`). Likewise, for mocks, you may want to make the process of creating a mock with a bunch of defaults simple, and have a function named `createMockFoo` with signature: `createMockFoo(overrides?: Partial<Foo>): Foo`.

This is by no means an exhaustive list, but I do find it helpful to follow this pattern for code consistency and setting expectations with other software developers. If I write a function called `getFoo`, it shouldn’t query a database. If I write a `makeFoo` function, I would expect a nicely initialized `Foo` to pop out.

To me, following these conventions is similar to legalistic words like “must” and “can”. If we were to use these words in programming conventions, then `mustXYZ` would mean a function will ALWAYS return a value, no matter what, while `canXYZ` would mean the function could return `null | undefined` as well. Similarly, having some standard naming convention helps teams write code that others will understand without having to read jsdocs or dive deeper into the code every single time.


Thoughts on Naming Utility Functions

Maintaining growing software is challenging. Poorly architected APIs and
incorrect abstractions can significantly impact the ability for engineering
teams to deliver new features in a timely manner. If we consider an
API's complexity as being a significant contributor to its overhead,
maintainability, and ease of use, then it becomes a question of how
do we best measure this complexity so that we can make informed decisions
about how to refactor and improve our APIs.



We will consider an API as an abstract set of functions, each with a
defined set of input parameters and outputs. An API can represent a library,
an interface, or a set of functions in a design system.

## An API as a Surface

A good API minimizes the complexity that a consumer needs to understand
in order to use it. If we think of an  API as an abstract two dimensional
surface, then the complexity of the internals of the API - all the code
that is required to implement the API - is the area of that surface.
The API that is exposed as functions, input parameters, and outputs is
the perimeter of that surface. This follows from the concept that an
API should act as a "black box" - the consumer should not need to know
how the API is implemented in order to use it.

From this metaphor, we can also think of the "best" API as one that
minimizes the perimeter of the surface while maximizing the necessary
area of the surface.

## The Complexity of a Surface

The perceived complexity of an API can be influenced by the number of functions,
the number of parameters, and the number of return values.

We will not be considering the internal state of the services that consumers
may need to manage. Instead, we will focus on "idempotent" functions - those
that do not have side effects and do not require any state to be managed.

Abstractly, we can denote the API Surface $S$ as a set of functions $f_i$,
where the complexity of each function $f_i$ is given by $c(f_i)$, and the
overall complexity of the surface is given by:

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

where $n$ is the number of functions in the surface.

As we increase the number of functions in the surface, the complexity of the
surface is also expected to increase.

## The Complexity of a Function

The complexity of a function $f_i$ can be influenced by the number of input
parameters, their values, and the number of return values.

Take for example a function $f(x: boolean): boolean$ that takes a single
boolean input and returns a boolean value. The complexity of this function
is relatively low - there are only two possible input values and two possible
output values.

If we jump to a function $f(x: boolean, y: boolean, z: boolean): boolean$
then the complexity of this function is higher - there are now $2^3 = 8$
possible input values and two possible output values.

As we increase the number of input parameters, we increase the number
of combinations of input values that the function can accept. This
increases the complexity of the function:

$$
c(f_i) = \prod_{p} |p| + |r|
$$

where $p$ is the set of input parameters, $r$ is the set of return values,
and $|p|$ is size of the set of input parameters and $|r|$ is the size of
the set of return values. By "size" we  mean the number of "meaningful"
values that a parameter type has. For example, a boolean has two meaningful values,
but an integer may have an infinite range of non-meaningful values. In some
languages, like C, it is common for an integer to have meaningful values
of -1 and 0, and non-meaningful values of all other integers. In the case where
the integer is simply a number, we would consider the size of the parameter
to be 1, while the size of a C-like integer to be the number of "special" cases
the integer has.

Aaron Luu, in his article [Don't use boolean](https://www.luu.io/posts/dont-use-booleans)
alludes to this exponential potential for complexity when using boolean
values.

## Tests as Consumers

Interestingly, the tests for an API already act as a consumer and can demonstrate
the complexity of an API as it strives to cover all possible branches and use-cases.
For our function with 3 boolean inputs, we would need to write 8 tests to cover
all possible input combinations. A suite of tests that check tons of combinations
of inputs and outputs is a good indicator that the API is complex.

## Techniques for Reducing Complexity

This is by no means an exhaustive list, but here are some techniques that
can help reduce complexity.

First is to identify if the parameters are truly independent. For example, let's take
the example:

```
f(x: boolean, y: Data | undefined): boolean
```

If the value of $y$ is only meaningful when $x$ is true, then we can consider
$y$ to be a dependent parameter. If we write out a matrix of possible inputs:

- x: true, y: Data
- x: false, y: Data
- x: true, y: undefined
- x: false, y: undefined

We can see that the value of $y$ is only meaningful when $x$ is true.

When we have dependent parameters, we can consider using the type-system to
help us manage the complexity. For example, we could just simplify the
function to allow only valid inputs:

```
f(x: Data | false): boolean
```

Depending on the values of Data, this simplifies the complexity of the function by
half.

Another technique is to consider reducing boolean inputs to a single enum-like
input type. For example, simplifying 3 boolean parameters into a single
enum-like parameter:

```
f(x: 'all'  | 'none' | 'some'): boolean
```

This reduces the number of possible input combinations from 8 to 3.

## Conclusion

This is one simple way to measure the complexity of an API, which shows
that the bigger the surface area, the more complex the API. The majority
of this complexity comes from the combinations of input parameters and
return values. By reducing the number of input parameters and return values,
we can reduce the complexity of the API.

This is by no means the only way to measure the complexity of an API, but
it is a useful way to think about the complexity of an API in terms of
the number of possible input and output combinations.

Forbidden Typescript: Spreading Type-holes

Thoughts on Naming Utility Functions

APIs, Complexity, and Surfaces