@prairielearn/utils 2.0.5 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @prairielearn/utils
 
+## 3.1.0
+
+### Minor Changes
+
+- 5b466e0: Add type utilities: `WithRequiredKeys`, `ExpandRecursively`, `assertNever`, `Result`, `Brand`, `withBrand`, `IsUnion`, `Prettify`, and `MergeUnion`
+
+## 3.0.0
+
+### Major Changes
+
+- 3914bb4: Upgrade to Node 24
+
 ## 2.0.5
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,3 +1,99 @@
+/**
+ * Produces a type that only includes the nullable properties of T.
+ */
+type NullableProperties<T> = {
+    [K in keyof T as null extends T[K] ? K : never]: T[K];
+};
+/**
+ * Produces a type containing the keys of T that are nullable.
+ */
+type NullableKeys<T> = keyof NullableProperties<T>;
+/**
+ * Produces a type with the same keys as T. All properties are marked as required,
+ * non-nullable, and not undefined.
+ */
+type RequiredProperty<T> = {
+    [P in keyof T]-?: NonNullable<T[P]>;
+};
+/**
+ * Produces a type with the same keys as T. If a key is in `RequiredKeys`, it will
+ * be marked as non-optional and non-nullable. Otherwise, it will be marked as
+ * optional with a type of `undefined`.
+ *
+ * ```ts
+ * type Foo = { a: string; b?: number; c: null };
+ * type Bar = WithRequiredKeys<Foo, 'a' | 'b'>;
+ * // Bar is equivalent to { a: string; b: number; c?: undefined; }
+ * ```
+ */
+export type WithRequiredKeys<T, RequiredKeys extends keyof T> = Omit<T, RequiredKeys | NullableKeys<T>> & RequiredProperty<Pick<T, RequiredKeys>> & Partial<Record<NullableKeys<Omit<T, RequiredKeys>>, undefined>>;
+/**
+ * Useful for convincing an IDE to show the expansion of a type.
+ *
+ * ```ts
+ * type Foo = { a: string; b?: number; c: null };
+ * type Bar = ExpandRecursively<Foo>;
+ * ```
+ */
+export type ExpandRecursively<T> = T extends object ? T extends infer O ? {
+    [K in keyof O]: ExpandRecursively<O[K]>;
+} : never : T;
+export declare function assertNever(value: never): never;
+export type Result<T, E = Error> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: E;
+};
+declare const __brand: unique symbol;
+export type Brand<K, T> = K & {
+    [__brand]: T;
+};
+/**
+ * Applies a brand to a value. This is a type-safe identity function that
+ * allows you to create branded types from their underlying values.
+ *
+ * ```ts
+ * type UserId = Brand<string, 'UserId'>;
+ * const userId = withBrand<UserId>('123'); // userId has type UserId
+ * ```
+ */
+export declare function withBrand<B extends Brand<any, any>>(value: B extends Brand<infer K, any> ? Omit<K, typeof __brand> : never): B;
+/**
+ * Detects if T is a union type (e.g., 'a' | 'b') vs a single literal (e.g., 'a')
+ */
+export type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+/**
+ * The Prettify helper is a utility type that takes an object type and makes the hover overlay more readable.
+ *
+ * https://www.totaltypescript.com/concepts/the-prettify-helper
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type UnionKeys<T> = T extends any ? keyof T : never;
+type KeysInAllMembers<T> = {
+    [K in UnionKeys<T>]: [T] extends [Record<K, any>] ? K : never;
+}[UnionKeys<T>];
+type KeysInSomeMembers<T> = Exclude<UnionKeys<T>, KeysInAllMembers<T>>;
+type UnionPropValue<T, K extends PropertyKey> = T extends any ? K extends keyof T ? T[K] : never : never;
+/**
+ * Merges a union of object types into a single object type.
+ * Keys present in all members become required, keys present in some become optional.
+ *
+ * ```ts
+ * type A = { id: string; name: string };
+ * type B = { id: string; age: number };
+ * type Merged = MergeUnion<A | B>;
+ * // Merged is { id: string } & { name?: string; age?: number }
+ * ```
+ */
+export type MergeUnion<T> = {
+    [K in KeysInAllMembers<T>]: UnionPropValue<T, K>;
+} & {
+    [K in KeysInSomeMembers<T>]?: UnionPropValue<T, K>;
+};
 /**
  * An object containing a promise and its resolve/reject methods.
  */
@@ -16,4 +112,5 @@ export interface PromiseWithResolvers<T> {
  * @returns An object containing the promise, resolve, and reject.
  */
 export declare function withResolvers<T>(): PromiseWithResolvers<T>;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,4BAA4B;IAC5B,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC7C,2BAA2B;IAC3B,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,KAAK,oBAAoB,CAAC,CAAC,CAAC,CAQ1D","sourcesContent":["/**\n * An object containing a promise and its resolve/reject methods.\n */\nexport interface PromiseWithResolvers<T> {\n  /** The promise instance. */\n  promise: Promise<T>;\n  /** Resolves the promise. */\n  resolve: (value: T | PromiseLike<T>) => void;\n  /** Rejects the promise. */\n  reject: (reason?: any) => void;\n}\n\n/**\n * Returns an object with a promise and its resolve/reject methods exposed.\n * This is similar to Node.js's util.withResolvers (Node 21+).\n *\n * @returns An object containing the promise, resolve, and reject.\n */\nexport function withResolvers<T>(): PromiseWithResolvers<T> {\n  let resolve: (value: T | PromiseLike<T>) => void;\n  let reject: (reason?: any) => void;\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n  return { promise, resolve: resolve!, reject: reject! };\n}\n"]}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Produces a type that only includes the nullable properties of T.\n */\ntype NullableProperties<T> = {\n  [K in keyof T as null extends T[K] ? K : never]: T[K];\n};\n\n/**\n * Produces a type containing the keys of T that are nullable.\n */\ntype NullableKeys<T> = keyof NullableProperties<T>;\n\n/**\n * Produces a type with the same keys as T. All properties are marked as required,\n * non-nullable, and not undefined.\n */\ntype RequiredProperty<T> = { [P in keyof T]-?: NonNullable<T[P]> };\n\n/**\n * Produces a type with the same keys as T. If a key is in `RequiredKeys`, it will\n * be marked as non-optional and non-nullable. Otherwise, it will be marked as\n * optional with a type of `undefined`.\n *\n * ```ts\n * type Foo = { a: string; b?: number; c: null };\n * type Bar = WithRequiredKeys<Foo, 'a' | 'b'>;\n * // Bar is equivalent to { a: string; b: number; c?: undefined; }\n * ```\n */\nexport type WithRequiredKeys<T, RequiredKeys extends keyof T> = Omit<\n  T,\n  RequiredKeys | NullableKeys<T>\n> &\n  RequiredProperty<Pick<T, RequiredKeys>> &\n  Partial<Record<NullableKeys<Omit<T, RequiredKeys>>, undefined>>;\n\n/**\n * Useful for convincing an IDE to show the expansion of a type.\n *\n * ```ts\n * type Foo = { a: string; b?: number; c: null };\n * type Bar = ExpandRecursively<Foo>;\n * ```\n */\nexport type ExpandRecursively<T> = T extends object\n  ? T extends infer O\n    ? { [K in keyof O]: ExpandRecursively<O[K]> }\n    : never\n  : T;\n\nexport function assertNever(value: never): never {\n  throw new Error(`Unexpected value: ${value}`);\n}\n\nexport type Result<T, E = Error> = { success: true; value: T } | { success: false; error: E };\n\ndeclare const __brand: unique symbol;\nexport type Brand<K, T> = K & { [__brand]: T };\n\n/**\n * Applies a brand to a value. This is a type-safe identity function that\n * allows you to create branded types from their underlying values.\n *\n * ```ts\n * type UserId = Brand<string, 'UserId'>;\n * const userId = withBrand<UserId>('123'); // userId has type UserId\n * ```\n */\nexport function withBrand<B extends Brand<any, any>>(\n  value: B extends Brand<infer K, any> ? Omit<K, typeof __brand> : never,\n): B {\n  return value as B;\n}\n\n/**\n * Detects if T is a union type (e.g., 'a' | 'b') vs a single literal (e.g., 'a')\n */\nexport type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;\n\n/**\n * The Prettify helper is a utility type that takes an object type and makes the hover overlay more readable.\n *\n * https://www.totaltypescript.com/concepts/the-prettify-helper\n */\nexport type Prettify<T> = {\n  [K in keyof T]: T[K];\n} & {};\n\n// All keys from any member of union T\ntype UnionKeys<T> = T extends any ? keyof T : never;\n\n// Keys that exist in ALL members of union T\ntype KeysInAllMembers<T> = {\n  [K in UnionKeys<T>]: [T] extends [Record<K, any>] ? K : never;\n}[UnionKeys<T>];\n\n// Keys that exist in SOME but not ALL members\ntype KeysInSomeMembers<T> = Exclude<UnionKeys<T>, KeysInAllMembers<T>>;\n\n// Value type for key K across all members that have it\ntype UnionPropValue<T, K extends PropertyKey> = T extends any\n  ? K extends keyof T\n    ? T[K]\n    : never\n  : never;\n\n/**\n * Merges a union of object types into a single object type.\n * Keys present in all members become required, keys present in some become optional.\n *\n * ```ts\n * type A = { id: string; name: string };\n * type B = { id: string; age: number };\n * type Merged = MergeUnion<A | B>;\n * // Merged is { id: string } & { name?: string; age?: number }\n * ```\n */\nexport type MergeUnion<T> = {\n  [K in KeysInAllMembers<T>]: UnionPropValue<T, K>;\n} & {\n  [K in KeysInSomeMembers<T>]?: UnionPropValue<T, K>;\n};\n\n/**\n * An object containing a promise and its resolve/reject methods.\n */\nexport interface PromiseWithResolvers<T> {\n  /** The promise instance. */\n  promise: Promise<T>;\n  /** Resolves the promise. */\n  resolve: (value: T | PromiseLike<T>) => void;\n  /** Rejects the promise. */\n  reject: (reason?: any) => void;\n}\n\n/**\n * Returns an object with a promise and its resolve/reject methods exposed.\n * This is similar to Node.js's util.withResolvers (Node 21+).\n *\n * @returns An object containing the promise, resolve, and reject.\n */\nexport function withResolvers<T>(): PromiseWithResolvers<T> {\n  let resolve: (value: T | PromiseLike<T>) => void;\n  let reject: (reason?: any) => void;\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n  return { promise, resolve: resolve!, reject: reject! };\n}\n"]}

package/dist/index.js

@@ -1,3 +1,18 @@
+export function assertNever(value) {
+    throw new Error(`Unexpected value: ${value}`);
+}
+/**
+ * Applies a brand to a value. This is a type-safe identity function that
+ * allows you to create branded types from their underlying values.
+ *
+ * ```ts
+ * type UserId = Brand<string, 'UserId'>;
+ * const userId = withBrand<UserId>('123'); // userId has type UserId
+ * ```
+ */
+export function withBrand(value) {
+    return value;
+}
 /**
  * Returns an object with a promise and its resolve/reject methods exposed.
  * This is similar to Node.js's util.withResolvers (Node 21+).

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,MAAM,UAAU,aAAa,GAA+B;IAC1D,IAAI,OAA4C,CAAC;IACjD,IAAI,MAA8B,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC;QAC3C,OAAO,GAAG,GAAG,CAAC;QACd,MAAM,GAAG,GAAG,CAAC;IAAA,CACd,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAQ,EAAE,MAAM,EAAE,MAAO,EAAE,CAAC;AAAA,CACxD","sourcesContent":["/**\n * An object containing a promise and its resolve/reject methods.\n */\nexport interface PromiseWithResolvers<T> {\n  /** The promise instance. */\n  promise: Promise<T>;\n  /** Resolves the promise. */\n  resolve: (value: T | PromiseLike<T>) => void;\n  /** Rejects the promise. */\n  reject: (reason?: any) => void;\n}\n\n/**\n * Returns an object with a promise and its resolve/reject methods exposed.\n * This is similar to Node.js's util.withResolvers (Node 21+).\n *\n * @returns An object containing the promise, resolve, and reject.\n */\nexport function withResolvers<T>(): PromiseWithResolvers<T> {\n  let resolve: (value: T | PromiseLike<T>) => void;\n  let reject: (reason?: any) => void;\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n  return { promise, resolve: resolve!, reject: reject! };\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkDA,MAAM,UAAU,WAAW,CAAC,KAAY,EAAS;IAC/C,MAAM,IAAI,KAAK,CAAC,qBAAqB,KAAK,EAAE,CAAC,CAAC;AAAA,CAC/C;AAOD;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CACvB,KAAsE,EACnE;IACH,OAAO,KAAU,CAAC;AAAA,CACnB;AA+DD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,GAA+B;IAC1D,IAAI,OAA4C,CAAC;IACjD,IAAI,MAA8B,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC;QAC3C,OAAO,GAAG,GAAG,CAAC;QACd,MAAM,GAAG,GAAG,CAAC;IAAA,CACd,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAQ,EAAE,MAAM,EAAE,MAAO,EAAE,CAAC;AAAA,CACxD","sourcesContent":["/**\n * Produces a type that only includes the nullable properties of T.\n */\ntype NullableProperties<T> = {\n  [K in keyof T as null extends T[K] ? K : never]: T[K];\n};\n\n/**\n * Produces a type containing the keys of T that are nullable.\n */\ntype NullableKeys<T> = keyof NullableProperties<T>;\n\n/**\n * Produces a type with the same keys as T. All properties are marked as required,\n * non-nullable, and not undefined.\n */\ntype RequiredProperty<T> = { [P in keyof T]-?: NonNullable<T[P]> };\n\n/**\n * Produces a type with the same keys as T. If a key is in `RequiredKeys`, it will\n * be marked as non-optional and non-nullable. Otherwise, it will be marked as\n * optional with a type of `undefined`.\n *\n * ```ts\n * type Foo = { a: string; b?: number; c: null };\n * type Bar = WithRequiredKeys<Foo, 'a' | 'b'>;\n * // Bar is equivalent to { a: string; b: number; c?: undefined; }\n * ```\n */\nexport type WithRequiredKeys<T, RequiredKeys extends keyof T> = Omit<\n  T,\n  RequiredKeys | NullableKeys<T>\n> &\n  RequiredProperty<Pick<T, RequiredKeys>> &\n  Partial<Record<NullableKeys<Omit<T, RequiredKeys>>, undefined>>;\n\n/**\n * Useful for convincing an IDE to show the expansion of a type.\n *\n * ```ts\n * type Foo = { a: string; b?: number; c: null };\n * type Bar = ExpandRecursively<Foo>;\n * ```\n */\nexport type ExpandRecursively<T> = T extends object\n  ? T extends infer O\n    ? { [K in keyof O]: ExpandRecursively<O[K]> }\n    : never\n  : T;\n\nexport function assertNever(value: never): never {\n  throw new Error(`Unexpected value: ${value}`);\n}\n\nexport type Result<T, E = Error> = { success: true; value: T } | { success: false; error: E };\n\ndeclare const __brand: unique symbol;\nexport type Brand<K, T> = K & { [__brand]: T };\n\n/**\n * Applies a brand to a value. This is a type-safe identity function that\n * allows you to create branded types from their underlying values.\n *\n * ```ts\n * type UserId = Brand<string, 'UserId'>;\n * const userId = withBrand<UserId>('123'); // userId has type UserId\n * ```\n */\nexport function withBrand<B extends Brand<any, any>>(\n  value: B extends Brand<infer K, any> ? Omit<K, typeof __brand> : never,\n): B {\n  return value as B;\n}\n\n/**\n * Detects if T is a union type (e.g., 'a' | 'b') vs a single literal (e.g., 'a')\n */\nexport type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;\n\n/**\n * The Prettify helper is a utility type that takes an object type and makes the hover overlay more readable.\n *\n * https://www.totaltypescript.com/concepts/the-prettify-helper\n */\nexport type Prettify<T> = {\n  [K in keyof T]: T[K];\n} & {};\n\n// All keys from any member of union T\ntype UnionKeys<T> = T extends any ? keyof T : never;\n\n// Keys that exist in ALL members of union T\ntype KeysInAllMembers<T> = {\n  [K in UnionKeys<T>]: [T] extends [Record<K, any>] ? K : never;\n}[UnionKeys<T>];\n\n// Keys that exist in SOME but not ALL members\ntype KeysInSomeMembers<T> = Exclude<UnionKeys<T>, KeysInAllMembers<T>>;\n\n// Value type for key K across all members that have it\ntype UnionPropValue<T, K extends PropertyKey> = T extends any\n  ? K extends keyof T\n    ? T[K]\n    : never\n  : never;\n\n/**\n * Merges a union of object types into a single object type.\n * Keys present in all members become required, keys present in some become optional.\n *\n * ```ts\n * type A = { id: string; name: string };\n * type B = { id: string; age: number };\n * type Merged = MergeUnion<A | B>;\n * // Merged is { id: string } & { name?: string; age?: number }\n * ```\n */\nexport type MergeUnion<T> = {\n  [K in KeysInAllMembers<T>]: UnionPropValue<T, K>;\n} & {\n  [K in KeysInSomeMembers<T>]?: UnionPropValue<T, K>;\n};\n\n/**\n * An object containing a promise and its resolve/reject methods.\n */\nexport interface PromiseWithResolvers<T> {\n  /** The promise instance. */\n  promise: Promise<T>;\n  /** Resolves the promise. */\n  resolve: (value: T | PromiseLike<T>) => void;\n  /** Rejects the promise. */\n  reject: (reason?: any) => void;\n}\n\n/**\n * Returns an object with a promise and its resolve/reject methods exposed.\n * This is similar to Node.js's util.withResolvers (Node 21+).\n *\n * @returns An object containing the promise, resolve, and reject.\n */\nexport function withResolvers<T>(): PromiseWithResolvers<T> {\n  let resolve: (value: T | PromiseLike<T>) => void;\n  let reject: (reason?: any) => void;\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n  return { promise, resolve: resolve!, reject: reject! };\n}\n"]}

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@prairielearn/utils",
-  "version": "2.0.5",
+  "version": "3.1.0",
   "type": "module",
   "repository": {
     "type": "git",
     "url": "https://github.com/PrairieLearn/PrairieLearn.git",
     "directory": "packages/utils"
   },
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "main": "./dist/index.js",
   "scripts": {
     "build": "tsgo",
@@ -15,7 +18,7 @@
   },
   "devDependencies": {
     "@prairielearn/tsconfig": "^0.0.0",
-    "@types/node": "^22.19.5",
+    "@types/node": "^24.10.9",
     "@typescript/native-preview": "^7.0.0-dev.20260106.1",
     "@vitest/coverage-v8": "^4.0.17",
     "tsx": "^4.21.0",

package/src/index.ts

@@ -1,3 +1,126 @@
+/**
+ * Produces a type that only includes the nullable properties of T.
+ */
+type NullableProperties<T> = {
+  [K in keyof T as null extends T[K] ? K : never]: T[K];
+};
+
+/**
+ * Produces a type containing the keys of T that are nullable.
+ */
+type NullableKeys<T> = keyof NullableProperties<T>;
+
+/**
+ * Produces a type with the same keys as T. All properties are marked as required,
+ * non-nullable, and not undefined.
+ */
+type RequiredProperty<T> = { [P in keyof T]-?: NonNullable<T[P]> };
+
+/**
+ * Produces a type with the same keys as T. If a key is in `RequiredKeys`, it will
+ * be marked as non-optional and non-nullable. Otherwise, it will be marked as
+ * optional with a type of `undefined`.
+ *
+ * ```ts
+ * type Foo = { a: string; b?: number; c: null };
+ * type Bar = WithRequiredKeys<Foo, 'a' | 'b'>;
+ * // Bar is equivalent to { a: string; b: number; c?: undefined; }
+ * ```
+ */
+export type WithRequiredKeys<T, RequiredKeys extends keyof T> = Omit<
+  T,
+  RequiredKeys | NullableKeys<T>
+> &
+  RequiredProperty<Pick<T, RequiredKeys>> &
+  Partial<Record<NullableKeys<Omit<T, RequiredKeys>>, undefined>>;
+
+/**
+ * Useful for convincing an IDE to show the expansion of a type.
+ *
+ * ```ts
+ * type Foo = { a: string; b?: number; c: null };
+ * type Bar = ExpandRecursively<Foo>;
+ * ```
+ */
+export type ExpandRecursively<T> = T extends object
+  ? T extends infer O
+    ? { [K in keyof O]: ExpandRecursively<O[K]> }
+    : never
+  : T;
+
+export function assertNever(value: never): never {
+  throw new Error(`Unexpected value: ${value}`);
+}
+
+export type Result<T, E = Error> = { success: true; value: T } | { success: false; error: E };
+
+declare const __brand: unique symbol;
+export type Brand<K, T> = K & { [__brand]: T };
+
+/**
+ * Applies a brand to a value. This is a type-safe identity function that
+ * allows you to create branded types from their underlying values.
+ *
+ * ```ts
+ * type UserId = Brand<string, 'UserId'>;
+ * const userId = withBrand<UserId>('123'); // userId has type UserId
+ * ```
+ */
+export function withBrand<B extends Brand<any, any>>(
+  value: B extends Brand<infer K, any> ? Omit<K, typeof __brand> : never,
+): B {
+  return value as B;
+}
+
+/**
+ * Detects if T is a union type (e.g., 'a' | 'b') vs a single literal (e.g., 'a')
+ */
+export type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+
+/**
+ * The Prettify helper is a utility type that takes an object type and makes the hover overlay more readable.
+ *
+ * https://www.totaltypescript.com/concepts/the-prettify-helper
+ */
+export type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+// All keys from any member of union T
+type UnionKeys<T> = T extends any ? keyof T : never;
+
+// Keys that exist in ALL members of union T
+type KeysInAllMembers<T> = {
+  [K in UnionKeys<T>]: [T] extends [Record<K, any>] ? K : never;
+}[UnionKeys<T>];
+
+// Keys that exist in SOME but not ALL members
+type KeysInSomeMembers<T> = Exclude<UnionKeys<T>, KeysInAllMembers<T>>;
+
+// Value type for key K across all members that have it
+type UnionPropValue<T, K extends PropertyKey> = T extends any
+  ? K extends keyof T
+    ? T[K]
+    : never
+  : never;
+
+/**
+ * Merges a union of object types into a single object type.
+ * Keys present in all members become required, keys present in some become optional.
+ *
+ * ```ts
+ * type A = { id: string; name: string };
+ * type B = { id: string; age: number };
+ * type Merged = MergeUnion<A | B>;
+ * // Merged is { id: string } & { name?: string; age?: number }
+ * ```
+ */
+export type MergeUnion<T> = {
+  [K in KeysInAllMembers<T>]: UnionPropValue<T, K>;
+} & {
+  [K in KeysInSomeMembers<T>]?: UnionPropValue<T, K>;
+};
+
 /**
  * An object containing a promise and its resolve/reject methods.
  */