@peerigon/typescript-toolkit 1.1.0 → 2.0.0

package/README.md

@@ -39,7 +39,11 @@ import { assert } from "@peerigon/typescript-toolkit/assert";
 
 | Module                             | Description                                                                      | Docs                        |
 | ---------------------------------- | -------------------------------------------------------------------------------- | --------------------------- |
-| [`assert`](./src/assert/README.md) | Assert a value is not `null`, `undefined`, or `false`, with TypeScript narrowing | [→](./src/assert/README.md) |
+| [`assert`](./src/assert/README.md) | Assert a value is not `null` or `undefined`, with TypeScript narrowing           | [→](./src/assert/README.md) |
+| [`need`](./src/need/README.md)     | Assert a value is not `null` or `undefined` and return it with a narrowed type   | [→](./src/need/README.md)   |
+| [`dedupe`](./src/dedupe/README.md) | Remove duplicate values from an array while preserving first-occurrence order    | [→](./src/dedupe/README.md) |
+| [`enums`](./src/enums/README.md)   | Lightweight string-enum alternative for `erasableSyntaxOnly` TypeScript projects | [→](./src/enums/README.md)  |
+| [`match`](./src/match/README.md)   | Exhaustive pattern matching with compile-time case checks, similar to `switch`   | [→](./src/match/README.md)  |
 
 ## License
 

package/dist/assert/assert.d.ts

@@ -1,16 +1,15 @@
 import { type ErrorMessage } from "../lib/error-message.ts";
 /**
- * Asserts that a given `value` is not `null`, `undefined`, or `false`,
- * and narrows its type.
+ * Asserts that a given `value` is not `null` or `undefined`, and narrows its type.
  *
- * Unlike regular truthiness checks, `assert` only rejects `null`, `undefined`,
- * and `false` while allowing other falsy values like `0`, `""`, and `NaN` to pass through.
+ * Unlike regular truthiness checks, `assert` only rejects `null` and `undefined`
+ * while allowing other falsy values like `false`, `0`, `""`, and `NaN` to pass through.
  *
- * @param value - The value that shouldn't be `null`, `undefined`, or `false`.
- * @param errorMessage - The error message to throw if the value is `null`, `undefined`, or `false`.
+ * @param value - The value that shouldn't be `null` or `undefined`.
+ * @param errorMessage - The error message to throw if the value is `null` or `undefined`.
  */
 export declare const assert: {
-    <Value>(value: Value, errorMessage?: ErrorMessage): asserts value is NonNullable<Value> & Exclude<Value, false>;
+    <Value>(value: Value, errorMessage?: ErrorMessage): asserts value is NonNullable<Value>;
     truthy(value: unknown, errorMessage?: ErrorMessage): asserts value;
 };
 //# sourceMappingURL=assert.d.ts.map

package/dist/assert/assert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/assert/assert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG7E;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM;KAAI,KAAK,SACnB,KAAK,iBACG,YAAY,GAC1B,QAAQ,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;kBAiBrD,OAAO,iBACC,YAAY,GAC1B,QAAQ,KAAK;CAff,CAAC"}
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/assert/assert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG7E;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM;KAAI,KAAK,SACnB,KAAK,iBACG,YAAY,GAC1B,QAAQ,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC;kBAiB7B,OAAO,iBACC,YAAY,GAC1B,QAAQ,KAAK;CAff,CAAC"}

package/dist/assert/assert.js

@@ -1,18 +1,17 @@
 import { getErrorMessage } from "../lib/error-message.js";
 import { simpleStringify } from "../lib/string.js";
 /**
- * Asserts that a given `value` is not `null`, `undefined`, or `false`,
- * and narrows its type.
+ * Asserts that a given `value` is not `null` or `undefined`, and narrows its type.
  *
- * Unlike regular truthiness checks, `assert` only rejects `null`, `undefined`,
- * and `false` while allowing other falsy values like `0`, `""`, and `NaN` to pass through.
+ * Unlike regular truthiness checks, `assert` only rejects `null` and `undefined`
+ * while allowing other falsy values like `false`, `0`, `""`, and `NaN` to pass through.
  *
- * @param value - The value that shouldn't be `null`, `undefined`, or `false`.
- * @param errorMessage - The error message to throw if the value is `null`, `undefined`, or `false`.
+ * @param value - The value that shouldn't be `null` or `undefined`.
+ * @param errorMessage - The error message to throw if the value is `null` or `undefined`.
  */
 export const assert = (value, errorMessage) => {
-    if (value === undefined || value === null || value === false) {
-        throwTypeError(value, errorMessage, "neither null, undefined, nor false");
+    if (value === undefined || value === null) {
+        throwTypeError(value, errorMessage, "neither null nor undefined");
     }
 };
 /**

package/dist/assert/assert.js.map

@@ -1 +1 @@
-{"version":3,"file":"assert.js","sourceRoot":"","sources":["../../src/assert/assert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqB,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,KAAY,EACZ,YAA2B,EACkC,EAAE;IAC/D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QAC7D,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,oCAAoC,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,GAAG,CACd,KAAc,EACd,YAA2B,EACZ,EAAE;IACjB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,cAAc,CAAC,CAAC;IACtD,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CACrB,KAAc,EACd,YAA0B,EAC1B,WAAmB,EACnB,EAAE;IACF,MAAM,IAAI,SAAS,CACjB,eAAe,CACb,YAAY,EACZ,GAAG,EAAE,CACH,8BAA8B,WAAW,aAAa,eAAe,CAAC,KAAK,CAAC,EAAE,CACjF,CACF,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { getErrorMessage, type ErrorMessage } from \"../lib/error-message.ts\";\nimport { simpleStringify } from \"../lib/string.ts\";\n\n/**\n * Asserts that a given `value` is not `null`, `undefined`, or `false`,\n * and narrows its type.\n *\n * Unlike regular truthiness checks, `assert` only rejects `null`, `undefined`,\n * and `false` while allowing other falsy values like `0`, `\"\"`, and `NaN` to pass through.\n *\n * @param value - The value that shouldn't be `null`, `undefined`, or `false`.\n * @param errorMessage - The error message to throw if the value is `null`, `undefined`, or `false`.\n */\nexport const assert = <Value>(\n  value: Value,\n  errorMessage?: ErrorMessage,\n): asserts value is NonNullable<Value> & Exclude<Value, false> => {\n  if (value === undefined || value === null || value === false) {\n    throwTypeError(value, errorMessage, \"neither null, undefined, nor false\");\n  }\n};\n\n/**\n * Asserts that a given `value` is truthy,\n * and narrows its type to exclude falsy values.\n *\n * This function performs a standard truthiness check, rejecting\n * all falsy values: `false`, `0`, `-0`, `0n`, `\"\"`, `null`, `undefined`, and `NaN`.\n *\n * @param value - The value to assert the truthy check on.\n * @param errorMessage - The error message to throw if the value is falsy.\n */\nassert.truthy = (\n  value: unknown,\n  errorMessage?: ErrorMessage,\n): asserts value => {\n  if (!value) {\n    throwTypeError(value, errorMessage, \"truthy value\");\n  }\n};\n\nconst throwTypeError = (\n  value: unknown,\n  errorMessage: ErrorMessage,\n  expectation: string,\n) => {\n  throw new TypeError(\n    getErrorMessage(\n      errorMessage,\n      () =>\n        `Assertion failed: expected ${expectation}, but got ${simpleStringify(value)}`,\n    ),\n  );\n};\n"]}
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../../src/assert/assert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqB,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,KAAY,EACZ,YAA2B,EACU,EAAE;IACvC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,4BAA4B,CAAC,CAAC;IACpE,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,GAAG,CACd,KAAc,EACd,YAA2B,EACZ,EAAE;IACjB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,cAAc,CAAC,CAAC;IACtD,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CACrB,KAAc,EACd,YAA0B,EAC1B,WAAmB,EACnB,EAAE;IACF,MAAM,IAAI,SAAS,CACjB,eAAe,CACb,YAAY,EACZ,GAAG,EAAE,CACH,8BAA8B,WAAW,aAAa,eAAe,CAAC,KAAK,CAAC,EAAE,CACjF,CACF,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { getErrorMessage, type ErrorMessage } from \"../lib/error-message.ts\";\nimport { simpleStringify } from \"../lib/string.ts\";\n\n/**\n * Asserts that a given `value` is not `null` or `undefined`, and narrows its type.\n *\n * Unlike regular truthiness checks, `assert` only rejects `null` and `undefined`\n * while allowing other falsy values like `false`, `0`, `\"\"`, and `NaN` to pass through.\n *\n * @param value - The value that shouldn't be `null` or `undefined`.\n * @param errorMessage - The error message to throw if the value is `null` or `undefined`.\n */\nexport const assert = <Value>(\n  value: Value,\n  errorMessage?: ErrorMessage,\n): asserts value is NonNullable<Value> => {\n  if (value === undefined || value === null) {\n    throwTypeError(value, errorMessage, \"neither null nor undefined\");\n  }\n};\n\n/**\n * Asserts that a given `value` is truthy,\n * and narrows its type to exclude falsy values.\n *\n * This function performs a standard truthiness check, rejecting\n * all falsy values: `false`, `0`, `-0`, `0n`, `\"\"`, `null`, `undefined`, and `NaN`.\n *\n * @param value - The value to assert the truthy check on.\n * @param errorMessage - The error message to throw if the value is falsy.\n */\nassert.truthy = (\n  value: unknown,\n  errorMessage?: ErrorMessage,\n): asserts value => {\n  if (!value) {\n    throwTypeError(value, errorMessage, \"truthy value\");\n  }\n};\n\nconst throwTypeError = (\n  value: unknown,\n  errorMessage: ErrorMessage,\n  expectation: string,\n) => {\n  throw new TypeError(\n    getErrorMessage(\n      errorMessage,\n      () =>\n        `Assertion failed: expected ${expectation}, but got ${simpleStringify(value)}`,\n    ),\n  );\n};\n"]}

package/dist/dedupe/dedupe.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Remove duplicates from an array using a Set.
+ *
+ * @param array - The array to remove duplicates from
+ * @returns A new array with duplicate values removed, preserving order of first occurrence
+ *
+ * @example
+ * ```ts
+ * const numbers = [1, 2, 2, 3, 1, 4];
+ * const unique = dedupe(numbers); // [1, 2, 3, 4]
+ *
+ * const strings = ["a", "b", "a", "c"];
+ * const uniqueStrings = dedupe(strings); // ["a", "b", "c"]
+ * ```
+ */
+export declare const dedupe: <Item>(array: Array<Item>) => Array<Item>;
+//# sourceMappingURL=dedupe.d.ts.map

package/dist/dedupe/dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../src/dedupe/dedupe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,GAAI,IAAI,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAG,KAAK,CAAC,IAAI,CAE3D,CAAC"}

package/dist/dedupe/dedupe.js

@@ -0,0 +1,19 @@
+/**
+ * Remove duplicates from an array using a Set.
+ *
+ * @param array - The array to remove duplicates from
+ * @returns A new array with duplicate values removed, preserving order of first occurrence
+ *
+ * @example
+ * ```ts
+ * const numbers = [1, 2, 2, 3, 1, 4];
+ * const unique = dedupe(numbers); // [1, 2, 3, 4]
+ *
+ * const strings = ["a", "b", "a", "c"];
+ * const uniqueStrings = dedupe(strings); // ["a", "b", "c"]
+ * ```
+ */
+export const dedupe = (array) => [
+    ...new Set(array),
+];
+//# sourceMappingURL=dedupe.js.map

package/dist/dedupe/dedupe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../../src/dedupe/dedupe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAO,KAAkB,EAAe,EAAE,CAAC;IAC/D,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC;CAClB,CAAC","sourcesContent":["/**\n * Remove duplicates from an array using a Set.\n *\n * @param array - The array to remove duplicates from\n * @returns A new array with duplicate values removed, preserving order of first occurrence\n *\n * @example\n * ```ts\n * const numbers = [1, 2, 2, 3, 1, 4];\n * const unique = dedupe(numbers); // [1, 2, 3, 4]\n *\n * const strings = [\"a\", \"b\", \"a\", \"c\"];\n * const uniqueStrings = dedupe(strings); // [\"a\", \"b\", \"c\"]\n * ```\n */\nexport const dedupe = <Item>(array: Array<Item>): Array<Item> => [\n  ...new Set(array),\n];\n"]}

package/dist/enums/enums.d.ts

@@ -0,0 +1,96 @@
+type EnumDefinition<Brand extends symbol, Definition extends Record<string, unknown>> = {
+    [Key in keyof Definition]: (Definition[Key] extends true ? Key : Definition[Key]) & {
+        readonly brand: Brand;
+    };
+};
+declare const enumsBrand: unique symbol;
+/**
+ * Extract the union type of all enum values from an enum definition.
+ *
+ * @template Definition - The enum definition object type
+ *
+ * @example
+ * ```ts
+ * const Color = enums.define({ Red: true, Green: true, Blue: true });
+ * type Color = Enums<typeof Color>; // "Red" | "Green" | "Blue"
+ * ```
+ */
+export type Enums<Definition> = Definition[keyof Definition];
+/**
+ * Utilities for creating type-safe enums with branded types to prevent mixing different enums.
+ */
+export declare const enums: {
+    /**
+     * Define a type-safe enum from an object definition.
+     *
+     * When a property value is `true`, the property key becomes the enum value.
+     * Otherwise, the provided value is used as the enum value.
+     *
+     * @param definition - Object defining the enum keys and values
+     * @returns A frozen enum object with type-safe values
+     *
+     * @example
+     * ```ts
+     * // Using property keys as values
+     * const Direction = enums.define({
+     *   North: true,
+     *   South: true,
+     *   East: true,
+     *   West: true
+     * });
+     * console.log(Direction.North); // "North"
+     *
+     * // Using custom values
+     * const Status = enums.define({
+     *   Inactive: 0,
+     *   Pending: 1,
+     *   Active: 2,
+     * });
+     * ```
+     */
+    define: {
+        <const Definition extends Record<string, unknown>>(definition: Definition): EnumDefinition<typeof enumsBrand, Definition>;
+        branded: <const Brand extends symbol, const Definition extends Record<string, unknown>>(brand: Brand, definition: Definition) => EnumDefinition<Brand, Definition>;
+    };
+    /**
+     * Parse a value to ensure it's a valid enum value.
+     *
+     * @param definition - The enum object created with enums.define
+     * @param value - The value to parse
+     * @returns The value typed as the enum type
+     * @throws {TypeError} If the value is not a valid enum value
+     *
+     * @example
+     * ```ts
+     * const Direction = enums.define({
+     *   North: true,
+     *   South: true
+     * });
+     *
+     * const dir = enums.parse(Direction, "North"); // Returns Direction.North
+     * const invalid = enums.parse(Direction, "West"); // Throws TypeError
+     * ```
+     */
+    parse: <Definition extends Record<string, unknown>>(definition: Definition, value: unknown) => Enums<Definition>;
+    /**
+     * Get an array of [key, value] tuples from an enum definition.
+     *
+     * @param definition - The enum object created with enums.define
+     * @returns Array of [key, value] tuples
+     *
+     * @example
+     * ```ts
+     * const Direction = enums.define({
+     *   North: true,
+     *   South: true,
+     *   East: "east-value",
+     * });
+     *
+     * const entries = enums.entries(Direction);
+     * // [["North", "North"], ["South", "South"], ["East", "east-value"]]
+     * ```
+     */
+    entries: <Definition extends Record<string, unknown>>(definition: Definition) => Array<[keyof Definition, Enums<Definition>]>;
+};
+export {};
+//# sourceMappingURL=enums.d.ts.map

package/dist/enums/enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/enums/enums.ts"],"names":[],"mappings":"AAEA,KAAK,cAAc,CACjB,KAAK,SAAS,MAAM,EACpB,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACxC;KACD,GAAG,IAAI,MAAM,UAAU,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,IAAI,GACpD,GAAG,GACH,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG;QACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;KACvB;CACF,CAAC;AAqBF,QAAA,MAAM,UAAU,eAAkB,CAAC;AAUnC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,KAAK,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,UAAU,CAAC,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;;eApDsB,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,cACvD,UAAU,GACrB,cAAc,CAAC,OAAO,UAAU,EAAE,UAAU,CAAC;wBAtBxC,KAAK,SAAS,MAAM,QACpB,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAEzC,KAAK,cACA,UAAU,KACrB,cAAc,CAAC,KAAK,EAAE,UAAU,CAAC;;IAsElC;;;;;;;;;;;;;;;;;;OAkBG;YACK,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,cACpC,UAAU,SACf,OAAO,KACb,KAAK,CAAC,UAAU,CAAC;IAepB;;;;;;;;;;;;;;;;;OAiBG;cACO,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,cACtC,UAAU,KACrB,KAAK,CAAC,CAAC,MAAM,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;CAKhD,CAAC"}

package/dist/enums/enums.js

@@ -0,0 +1,98 @@
+import { stringify } from "../lib/string.js";
+const defineBrandedEnums = (brand, definition) => {
+    const enumsDefinition = Object.fromEntries(Object.entries(definition).map(([key, value]) => [
+        key,
+        value === true ? key : value,
+    ]));
+    Object.freeze(enumsDefinition);
+    return enumsDefinition;
+};
+const enumsBrand = Symbol("enums");
+const defineEnums = (definition) => {
+    return defineBrandedEnums(enumsBrand, definition);
+};
+defineEnums.branded = defineBrandedEnums;
+/**
+ * Utilities for creating type-safe enums with branded types to prevent mixing different enums.
+ */
+export const enums = {
+    /**
+     * Define a type-safe enum from an object definition.
+     *
+     * When a property value is `true`, the property key becomes the enum value.
+     * Otherwise, the provided value is used as the enum value.
+     *
+     * @param definition - Object defining the enum keys and values
+     * @returns A frozen enum object with type-safe values
+     *
+     * @example
+     * ```ts
+     * // Using property keys as values
+     * const Direction = enums.define({
+     *   North: true,
+     *   South: true,
+     *   East: true,
+     *   West: true
+     * });
+     * console.log(Direction.North); // "North"
+     *
+     * // Using custom values
+     * const Status = enums.define({
+     *   Inactive: 0,
+     *   Pending: 1,
+     *   Active: 2,
+     * });
+     * ```
+     */
+    define: defineEnums,
+    /**
+     * Parse a value to ensure it's a valid enum value.
+     *
+     * @param definition - The enum object created with enums.define
+     * @param value - The value to parse
+     * @returns The value typed as the enum type
+     * @throws {TypeError} If the value is not a valid enum value
+     *
+     * @example
+     * ```ts
+     * const Direction = enums.define({
+     *   North: true,
+     *   South: true
+     * });
+     *
+     * const dir = enums.parse(Direction, "North"); // Returns Direction.North
+     * const invalid = enums.parse(Direction, "West"); // Throws TypeError
+     * ```
+     */
+    parse: (definition, value) => {
+        const enumValues = Object.values(definition);
+        if (enumValues.includes(value)) {
+            return value;
+        }
+        throw new TypeError(`Invalid enum value ${stringify(value)}. Expected one of: ${enumValues.map((value) => stringify(value)).join(", ")}`, {
+            cause: { enum: definition, value },
+        });
+    },
+    /**
+     * Get an array of [key, value] tuples from an enum definition.
+     *
+     * @param definition - The enum object created with enums.define
+     * @returns Array of [key, value] tuples
+     *
+     * @example
+     * ```ts
+     * const Direction = enums.define({
+     *   North: true,
+     *   South: true,
+     *   East: "east-value",
+     * });
+     *
+     * const entries = enums.entries(Direction);
+     * // [["North", "North"], ["South", "South"], ["East", "east-value"]]
+     * ```
+     */
+    entries: (definition) => {
+        return Object.entries(definition);
+    },
+};
+//# sourceMappingURL=enums.js.map

package/dist/enums/enums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../src/enums/enums.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAa7C,MAAM,kBAAkB,GAAG,CAIzB,KAAY,EACZ,UAAsB,EACa,EAAE;IACrC,MAAM,eAAe,GAAG,MAAM,CAAC,WAAW,CACxC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;QAC/C,GAAG;QACH,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK;KAC7B,CAAC,CACkC,CAAC;IAEvC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAE/B,OAAO,eAAe,CAAC;AACzB,CAAC,CAAC;AAEF,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;AAEnC,MAAM,WAAW,GAAG,CAClB,UAAsB,EACyB,EAAE;IACjD,OAAO,kBAAkB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;AACpD,CAAC,CAAC;AAEF,WAAW,CAAC,OAAO,GAAG,kBAAkB,CAAC;AAezC;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,EAAE,WAAW;IAEnB;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,EAAE,CACL,UAAsB,EACtB,KAAc,EACK,EAAE;QACrB,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAE7C,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,KAA0B,CAAC;QACpC,CAAC;QAED,MAAM,IAAI,SAAS,CACjB,sBAAsB,SAAS,CAAC,KAAK,CAAC,sBAAsB,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACpH;YACE,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE;SACnC,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,EAAE,CACP,UAAsB,EACwB,EAAE;QAChD,OAAO,MAAM,CAAC,OAAO,CAAC,UAAU,CAE/B,CAAC;IACJ,CAAC;CACF,CAAC","sourcesContent":["import { stringify } from \"../lib/string.ts\";\n\ntype EnumDefinition<\n  Brand extends symbol,\n  Definition extends Record<string, unknown>,\n> = {\n  [Key in keyof Definition]: (Definition[Key] extends true\n    ? Key\n    : Definition[Key]) & {\n    readonly brand: Brand;\n  };\n};\n\nconst defineBrandedEnums = <\n  const Brand extends symbol,\n  const Definition extends Record<string, unknown>,\n>(\n  brand: Brand,\n  definition: Definition,\n): EnumDefinition<Brand, Definition> => {\n  const enumsDefinition = Object.fromEntries(\n    Object.entries(definition).map(([key, value]) => [\n      key,\n      value === true ? key : value,\n    ]),\n  ) as EnumDefinition<Brand, Definition>;\n\n  Object.freeze(enumsDefinition);\n\n  return enumsDefinition;\n};\n\nconst enumsBrand = Symbol(\"enums\");\n\nconst defineEnums = <const Definition extends Record<string, unknown>>(\n  definition: Definition,\n): EnumDefinition<typeof enumsBrand, Definition> => {\n  return defineBrandedEnums(enumsBrand, definition);\n};\n\ndefineEnums.branded = defineBrandedEnums;\n\n/**\n * Extract the union type of all enum values from an enum definition.\n *\n * @template Definition - The enum definition object type\n *\n * @example\n * ```ts\n * const Color = enums.define({ Red: true, Green: true, Blue: true });\n * type Color = Enums<typeof Color>; // \"Red\" | \"Green\" | \"Blue\"\n * ```\n */\nexport type Enums<Definition> = Definition[keyof Definition];\n\n/**\n * Utilities for creating type-safe enums with branded types to prevent mixing different enums.\n */\nexport const enums = {\n  /**\n   * Define a type-safe enum from an object definition.\n   *\n   * When a property value is `true`, the property key becomes the enum value.\n   * Otherwise, the provided value is used as the enum value.\n   *\n   * @param definition - Object defining the enum keys and values\n   * @returns A frozen enum object with type-safe values\n   *\n   * @example\n   * ```ts\n   * // Using property keys as values\n   * const Direction = enums.define({\n   *   North: true,\n   *   South: true,\n   *   East: true,\n   *   West: true\n   * });\n   * console.log(Direction.North); // \"North\"\n   *\n   * // Using custom values\n   * const Status = enums.define({\n   *   Inactive: 0,\n   *   Pending: 1,\n   *   Active: 2,\n   * });\n   * ```\n   */\n  define: defineEnums,\n\n  /**\n   * Parse a value to ensure it's a valid enum value.\n   *\n   * @param definition - The enum object created with enums.define\n   * @param value - The value to parse\n   * @returns The value typed as the enum type\n   * @throws {TypeError} If the value is not a valid enum value\n   *\n   * @example\n   * ```ts\n   * const Direction = enums.define({\n   *   North: true,\n   *   South: true\n   * });\n   *\n   * const dir = enums.parse(Direction, \"North\"); // Returns Direction.North\n   * const invalid = enums.parse(Direction, \"West\"); // Throws TypeError\n   * ```\n   */\n  parse: <Definition extends Record<string, unknown>>(\n    definition: Definition,\n    value: unknown,\n  ): Enums<Definition> => {\n    const enumValues = Object.values(definition);\n\n    if (enumValues.includes(value)) {\n      return value as Enums<Definition>;\n    }\n\n    throw new TypeError(\n      `Invalid enum value ${stringify(value)}. Expected one of: ${enumValues.map((value) => stringify(value)).join(\", \")}`,\n      {\n        cause: { enum: definition, value },\n      },\n    );\n  },\n\n  /**\n   * Get an array of [key, value] tuples from an enum definition.\n   *\n   * @param definition - The enum object created with enums.define\n   * @returns Array of [key, value] tuples\n   *\n   * @example\n   * ```ts\n   * const Direction = enums.define({\n   *   North: true,\n   *   South: true,\n   *   East: \"east-value\",\n   * });\n   *\n   * const entries = enums.entries(Direction);\n   * // [[\"North\", \"North\"], [\"South\", \"South\"], [\"East\", \"east-value\"]]\n   * ```\n   */\n  entries: <Definition extends Record<string, unknown>>(\n    definition: Definition,\n  ): Array<[keyof Definition, Enums<Definition>]> => {\n    return Object.entries(definition) as Array<\n      [keyof Definition, Enums<Definition>]\n    >;\n  },\n};\n"]}

package/dist/main.d.ts

@@ -1,2 +1,6 @@
 export * from "./assert/assert.ts";
+export * from "./dedupe/dedupe.ts";
+export * from "./enums/enums.ts";
+export * from "./match/match.ts";
+export * from "./need/need.ts";
 //# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}

package/dist/main.js

@@ -1,2 +1,6 @@
 export * from "./assert/assert.js";
+export * from "./dedupe/dedupe.js";
+export * from "./enums/enums.js";
+export * from "./match/match.js";
+export * from "./need/need.js";
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC","sourcesContent":["export * from \"./assert/assert.ts\";\n"]}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC","sourcesContent":["export * from \"./assert/assert.ts\";\nexport * from \"./dedupe/dedupe.ts\";\nexport * from \"./enums/enums.ts\";\nexport * from \"./match/match.ts\";\nexport * from \"./need/need.ts\";\n"]}

package/dist/match/match.d.ts

@@ -0,0 +1,72 @@
+declare const defaultSymbol: unique symbol;
+declare const catchSymbol: unique symbol;
+/**
+ * Match the given `value` against `cases` and return the matching `Result`.
+ *
+ * This function provides exhaustive pattern matching with TypeScript, ensuring all cases
+ * are handled at compile time. It works similarly to a regular `switch`/`case` statement,
+ * but has a decisive advantage: TypeScript issues a type error if not all cases have been
+ * implemented. An error is also thrown at runtime if a value doesn't match any case.
+ *
+ * ## Usage:
+ *
+ * Match uses tuple-based matching, ideal for enums or any type of values:
+ * @example
+ * ```ts
+ * const Direction = enums.define({ Up: "North", Down: "South" });
+ * type Direction = Enums<typeof Direction>;
+ * match(Direction.Up).case([
+ *   [Direction.Up, "going up"],
+ *   [Direction.Down, "going down"],
+ * ]); // "going up"
+ * ```
+ *
+ * ## Special symbols:
+ *
+ * `match.default` - Provides a default case. When used, TypeScript no longer requires
+ * all cases to be specified, allowing partial matches with a fallback.
+ *
+ * @example
+ * ```ts
+ * match<"A" | "B">("A").case([
+ *   ["B", "result B"],
+ *   [match.default, "default result"],
+ * ]); // "default result"
+ * ```
+ *
+ * `match.catch` - Handles unexpected runtime values while still requiring all compile-time
+ * cases to be specified. Use this when you need type safety but want to handle edge cases
+ * at runtime without throwing errors.
+ *
+ * @example
+ * ```ts
+ * match("C" as "A" | "B").case([
+ *   ["A", "result A"],
+ *   ["B", "result B"],
+ *   [match.catch, "unknown value"],
+ * ]); // "unknown value"
+ * ```
+ */
+declare function match<const Value>(value: Value): {
+    case: {
+        <const Result>(cases: Cases<readonly [Value, Result], readonly [typeof defaultSymbol, Result]>): Result;
+        <const Result, const GivenCases extends Cases<readonly [Value, Result], readonly [typeof catchSymbol | Value, Result]>>(cases: If<IsExact<Exclude<ExtractValueFromCases<GivenCases>, typeof catchSymbol>, Value>, {
+            then: GivenCases;
+            else: never;
+        }>): Result;
+    };
+};
+declare namespace match {
+    var _a: typeof defaultSymbol;
+    var _b: typeof catchSymbol;
+    export { _a as default, _b as catch };
+}
+type Cases<Tuple extends readonly [any, any] = readonly [any, any], LastTuple extends readonly [any, any] = Tuple> = readonly [...ReadonlyArray<Tuple>, LastTuple];
+type If<ValueToTest, Body extends {
+    then: any;
+    else: any;
+}> = ValueToTest extends true ? Body["then"] : Body["else"];
+type IsExact<Type1, Type2> = [Type1] extends [Type2] ? [Type2] extends [Type1] ? true : false : false;
+type ExtractValueFromCases<GivenCases extends Cases> = GivenCases[number][0];
+export { match };
+//# sourceMappingURL=match.d.ts.map

package/dist/match/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/match/match.ts"],"names":[],"mappings":"AAKA,QAAA,MAAM,aAAa,eAA0B,CAAC;AAC9C,QAAA,MAAM,WAAW,eAAwB,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,iBAAS,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG;IACzC,IAAI,EAAE;QACJ,CAAC,KAAK,CAAC,MAAM,EACX,KAAK,EAAE,KAAK,CACV,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,EACxB,SAAS,CAAC,OAAO,aAAa,EAAE,MAAM,CAAC,CACxC,GACA,MAAM,CAAC;QACV,CACE,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,SAAS,KAAK,CAC5B,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,EACxB,SAAS,CAAC,OAAO,WAAW,GAAG,KAAK,EAAE,MAAM,CAAC,CAC9C,EAED,KAAK,EAAE,EAAE,CACP,OAAO,CACL,OAAO,CAAC,qBAAqB,CAAC,UAAU,CAAC,EAAE,OAAO,WAAW,CAAC,EAC9D,KAAK,CACN,EACD;YACE,IAAI,EAAE,UAAU,CAAC;YACjB,IAAI,EAAE,KAAK,CAAC;SACb,CACF,GACA,MAAM,CAAC;KACX,CAAC;CACH,CAAC;kBA3BO,KAAK;;;;;AA6Dd,KAAK,KAAK,CACR,KAAK,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,EACvD,SAAS,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,KAAK,IAC3C,SAAS,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;AAElD,KAAK,EAAE,CACL,WAAW,EACX,IAAI,SAAS;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,GAAG,CAAA;CAAE,IACnC,WAAW,SAAS,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;AAE3D,KAAK,OAAO,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAChD,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GACrB,IAAI,GACJ,KAAK,GACP,KAAK,CAAC;AAEV,KAAK,qBAAqB,CAAC,UAAU,SAAS,KAAK,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAK7E,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/match/match.js

@@ -0,0 +1,28 @@
+/* eslint-disable prefer-arrow/prefer-arrow-functions */
+import { stringify } from "../lib/string.js";
+import { need } from "./../need/need.js";
+const defaultSymbol = Symbol("match.default");
+const catchSymbol = Symbol("match.catch");
+function match(value) {
+    return {
+        case: (cases) => {
+            for (let i = 0; i < cases.length - 1; i++) {
+                const [valueInCase, resultInCase] = cases[i];
+                if (Object.is(value, valueInCase)) {
+                    return resultInCase;
+                }
+            }
+            const [valueInLastCase, resultInLastCase] = need(cases.at(-1));
+            if (Object.is(value, valueInLastCase) ||
+                valueInLastCase === defaultSymbol ||
+                valueInLastCase === catchSymbol) {
+                return resultInLastCase;
+            }
+            throw new Error(`No match found for ${stringify(value)}. Expected one of: ${cases.map(([possibleValue]) => stringify(possibleValue)).join(", ")}`);
+        },
+    };
+}
+match.default = defaultSymbol;
+match.catch = catchSymbol;
+export { match };
+//# sourceMappingURL=match.js.map

package/dist/match/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../src/match/match.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAExD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEzC,MAAM,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAC9C,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;AA6E1C,SAAS,KAAK,CAAc,KAAY;IACtC,OAAO;QACL,IAAI,EAAE,CACJ,KAGC,EACO,EAAE;YACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC1C,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;gBAE9C,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC;oBAClC,OAAO,YAAY,CAAC;gBACtB,CAAC;YACH,CAAC;YAED,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAE/D,IACE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC;gBACjC,eAAe,KAAK,aAAa;gBACjC,eAAe,KAAK,WAAW,EAC/B,CAAC;gBACD,OAAO,gBAAgB,CAAC;YAC1B,CAAC;YAED,MAAM,IAAI,KAAK,CACb,sBAAsB,SAAS,CAAC,KAAK,CAAC,sBAAsB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAClI,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAoBD,KAAK,CAAC,OAAO,GAAG,aAAa,CAAC;AAC9B,KAAK,CAAC,KAAK,GAAG,WAAW,CAAC;AAE1B,OAAO,EAAE,KAAK,EAAE,CAAC","sourcesContent":["/* eslint-disable prefer-arrow/prefer-arrow-functions */\n\nimport { stringify } from \"../lib/string.ts\";\nimport { need } from \"./../need/need.ts\";\n\nconst defaultSymbol = Symbol(\"match.default\");\nconst catchSymbol = Symbol(\"match.catch\");\n\n/**\n * Match the given `value` against `cases` and return the matching `Result`.\n *\n * This function provides exhaustive pattern matching with TypeScript, ensuring all cases\n * are handled at compile time. It works similarly to a regular `switch`/`case` statement,\n * but has a decisive advantage: TypeScript issues a type error if not all cases have been\n * implemented. An error is also thrown at runtime if a value doesn't match any case.\n *\n * ## Usage:\n *\n * Match uses tuple-based matching, ideal for enums or any type of values:\n * @example\n * ```ts\n * const Direction = enums.define({ Up: \"North\", Down: \"South\" });\n * type Direction = Enums<typeof Direction>;\n * match(Direction.Up).case([\n *   [Direction.Up, \"going up\"],\n *   [Direction.Down, \"going down\"],\n * ]); // \"going up\"\n * ```\n *\n * ## Special symbols:\n *\n * `match.default` - Provides a default case. When used, TypeScript no longer requires\n * all cases to be specified, allowing partial matches with a fallback.\n *\n * @example\n * ```ts\n * match<\"A\" | \"B\">(\"A\").case([\n *   [\"B\", \"result B\"],\n *   [match.default, \"default result\"],\n * ]); // \"default result\"\n * ```\n *\n * `match.catch` - Handles unexpected runtime values while still requiring all compile-time\n * cases to be specified. Use this when you need type safety but want to handle edge cases\n * at runtime without throwing errors.\n *\n * @example\n * ```ts\n * match(\"C\" as \"A\" | \"B\").case([\n *   [\"A\", \"result A\"],\n *   [\"B\", \"result B\"],\n *   [match.catch, \"unknown value\"],\n * ]); // \"unknown value\"\n * ```\n */\nfunction match<const Value>(value: Value): {\n  case: {\n    <const Result>(\n      cases: Cases<\n        readonly [Value, Result],\n        readonly [typeof defaultSymbol, Result]\n      >,\n    ): Result;\n    <\n      const Result,\n      const GivenCases extends Cases<\n        readonly [Value, Result],\n        readonly [typeof catchSymbol | Value, Result]\n      >,\n    >(\n      cases: If<\n        IsExact<\n          Exclude<ExtractValueFromCases<GivenCases>, typeof catchSymbol>,\n          Value\n        >,\n        {\n          then: GivenCases;\n          else: never;\n        }\n      >,\n    ): Result;\n  };\n};\nfunction match<const Value>(value: Value): any {\n  return {\n    case: <const Result>(\n      cases: Cases<\n        readonly [Value, Result],\n        readonly [typeof defaultSymbol | typeof catchSymbol | Value, Result]\n      >,\n    ): Result => {\n      for (let i = 0; i < cases.length - 1; i++) {\n        const [valueInCase, resultInCase] = cases[i]!;\n\n        if (Object.is(value, valueInCase)) {\n          return resultInCase;\n        }\n      }\n\n      const [valueInLastCase, resultInLastCase] = need(cases.at(-1));\n\n      if (\n        Object.is(value, valueInLastCase) ||\n        valueInLastCase === defaultSymbol ||\n        valueInLastCase === catchSymbol\n      ) {\n        return resultInLastCase;\n      }\n\n      throw new Error(\n        `No match found for ${stringify(value)}. Expected one of: ${cases.map(([possibleValue]) => stringify(possibleValue)).join(\", \")}`,\n      );\n    },\n  };\n}\n\ntype Cases<\n  Tuple extends readonly [any, any] = readonly [any, any],\n  LastTuple extends readonly [any, any] = Tuple,\n> = readonly [...ReadonlyArray<Tuple>, LastTuple];\n\ntype If<\n  ValueToTest,\n  Body extends { then: any; else: any },\n> = ValueToTest extends true ? Body[\"then\"] : Body[\"else\"];\n\ntype IsExact<Type1, Type2> = [Type1] extends [Type2]\n  ? [Type2] extends [Type1]\n    ? true\n    : false\n  : false;\n\ntype ExtractValueFromCases<GivenCases extends Cases> = GivenCases[number][0];\n\nmatch.default = defaultSymbol;\nmatch.catch = catchSymbol;\n\nexport { match };\n"]}

package/dist/need/need.d.ts

@@ -0,0 +1,22 @@
+import { type ErrorMessage } from "../lib/error-message.ts";
+/**
+ * Assert that a given value is not `null` or `undefined`, and narrow its type.
+ *
+ * Like `assert`, this function only handles nullish values (`null`, `undefined`)
+ * and does not reject other falsy values. Unlike `assert`, it returns the value
+ * so it can be used in expressions.
+ *
+ * @param value - The value to check for nullish values
+ * @param errorMessage - Custom error message or function that returns an error message
+ * @returns The value with nullish types removed from its type signature
+ * @throws {TypeError} When value is `null` or `undefined`
+ *
+ * @example
+ * ```ts
+ * const maybeString: string | null = getValue();
+ * const definiteString = need(maybeString); // throws if null
+ * // TypeScript now knows definiteString is string, not string | null
+ * ```
+ */
+export declare const need: <Value>(value: Value, errorMessage?: ErrorMessage) => NonNullable<Value>;
+//# sourceMappingURL=need.d.ts.map

package/dist/need/need.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"need.d.ts","sourceRoot":"","sources":["../../src/need/need.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG7E;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,EACxB,OAAO,KAAK,EACZ,eAAe,YAAY,KAC1B,WAAW,CAAC,KAAK,CAUnB,CAAC"}

package/dist/need/need.js

@@ -0,0 +1,28 @@
+import { getErrorMessage } from "../lib/error-message.js";
+import { simpleStringify } from "../lib/string.js";
+/**
+ * Assert that a given value is not `null` or `undefined`, and narrow its type.
+ *
+ * Like `assert`, this function only handles nullish values (`null`, `undefined`)
+ * and does not reject other falsy values. Unlike `assert`, it returns the value
+ * so it can be used in expressions.
+ *
+ * @param value - The value to check for nullish values
+ * @param errorMessage - Custom error message or function that returns an error message
+ * @returns The value with nullish types removed from its type signature
+ * @throws {TypeError} When value is `null` or `undefined`
+ *
+ * @example
+ * ```ts
+ * const maybeString: string | null = getValue();
+ * const definiteString = need(maybeString); // throws if null
+ * // TypeScript now knows definiteString is string, not string | null
+ * ```
+ */
+export const need = (value, errorMessage) => {
+    if (value === undefined || value === null) {
+        throw new TypeError(getErrorMessage(errorMessage, () => `Expected value to be defined, but got ${simpleStringify(value)}`));
+    }
+    return value;
+};
+//# sourceMappingURL=need.js.map

package/dist/need/need.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"need.js","sourceRoot":"","sources":["../../src/need/need.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqB,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,KAAY,EACZ,YAA2B,EACP,EAAE;IACtB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,SAAS,CACjB,eAAe,CACb,YAAY,EACZ,GAAG,EAAE,CAAC,yCAAyC,eAAe,CAAC,KAAK,CAAC,EAAE,CACxE,CACF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC","sourcesContent":["import { getErrorMessage, type ErrorMessage } from \"../lib/error-message.ts\";\nimport { simpleStringify } from \"../lib/string.ts\";\n\n/**\n * Assert that a given value is not `null` or `undefined`, and narrow its type.\n *\n * Like `assert`, this function only handles nullish values (`null`, `undefined`)\n * and does not reject other falsy values. Unlike `assert`, it returns the value\n * so it can be used in expressions.\n *\n * @param value - The value to check for nullish values\n * @param errorMessage - Custom error message or function that returns an error message\n * @returns The value with nullish types removed from its type signature\n * @throws {TypeError} When value is `null` or `undefined`\n *\n * @example\n * ```ts\n * const maybeString: string | null = getValue();\n * const definiteString = need(maybeString); // throws if null\n * // TypeScript now knows definiteString is string, not string | null\n * ```\n */\nexport const need = <Value>(\n  value: Value,\n  errorMessage?: ErrorMessage,\n): NonNullable<Value> => {\n  if (value === undefined || value === null) {\n    throw new TypeError(\n      getErrorMessage(\n        errorMessage,\n        () => `Expected value to be defined, but got ${simpleStringify(value)}`,\n      ),\n    );\n  }\n  return value;\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peerigon/typescript-toolkit",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "🔧✨ Tiny helpers for TypeScript applications",
   "keywords": [],
   "homepage": "https://github.com/peerigon/typescript-toolkit#readme",
@@ -17,7 +17,11 @@
   "type": "module",
   "exports": {
     ".": "./dist/main.js",
-    "./add": "./dist/add.js"
+    "./assert": "./dist/assert/assert.js",
+    "./dedupe": "./dist/dedupe/dedupe.js",
+    "./enums": "./dist/enums/enums.js",
+    "./match": "./dist/match/match.js",
+    "./need": "./dist/need/need.js"
   },
   "main": "./dist/main.js",
   "files": [