ts-data-forge 1.0.0 → 1.0.1

package/dist/expect-type.mjs

@@ -0,0 +1,201 @@
+/**
+ * Compile-time type assertion utility for TypeScript type testing.
+ *
+ * This function performs static type relationship checking at compile-time and has no runtime effect.
+ * It is primarily used in test files to verify that TypeScript's type inference and type relationships
+ * work as expected. The function will cause TypeScript compilation errors if the specified type
+ * relationship does not hold.
+ *
+ * ## Supported Type Relations
+ *
+ * ### Equality Relations
+ * - **`"="` (strict equality)**: Asserts that types `A` and `B` are exactly the same type.
+ *   Uses TypeScript's internal type equality checking.
+ * - **`"!="` (strict inequality)**: Asserts that types `A` and `B` are not exactly the same type.
+ *
+ * ### Assignability Relations
+ * - **`"~="` (mutual assignability)**: Asserts that `A` extends `B` AND `B` extends `A`.
+ *   Types are structurally equivalent and mutually assignable.
+ * - **`"<="` (subtype relation)**: Asserts that type `A` extends (is assignable to) type `B`.
+ *   Type `A` is a subtype of `B`.
+ * - **`">="` (supertype relation)**: Asserts that type `B` extends (is assignable to) type `A`.
+ *   Type `A` is a supertype of `B`.
+ *
+ * ### Negative Assignability Relations
+ * - **`"!<="` (not subtype)**: Asserts that type `A` does NOT extend type `B`.
+ * - **`"!>="` (not supertype)**: Asserts that type `B` does NOT extend type `A`.
+ *
+ * ## Type Parameter Constraints
+ *
+ * @template A - The first type for comparison. Can be any TypeScript type including:
+ *   - Primitive types (string, number, boolean, etc.)
+ *   - Object types and interfaces
+ *   - Union and intersection types
+ *   - Generic types and type parameters
+ *   - Literal types and branded types
+ *   - Function types and return types
+ * @template B - The second type for comparison. Same constraints as type `A`.
+ *
+ * @param _relation - A string literal representing the expected type relationship.
+ *   TypeScript's type system automatically infers and restricts the available operators
+ *   based on the actual relationship between types `A` and `B`. If an invalid relationship
+ *   is specified, TypeScript will show a compilation error.
+ *
+ * ## Usage Patterns
+ *
+ * ### Basic Type Testing
+ * @example
+ * ```typescript
+ * import { expectType } from './expect-type.mjs';
+ *
+ * // Primitive type equality
+ * expectType<string, string>("=");           // ✓ exact match
+ * expectType<number, string>("!=");          // ✓ different types
+ * expectType<42, number>("<=");              // ✓ literal extends primitive
+ * expectType<number, 42>(">=");              // ✓ primitive is supertype
+ *
+ * // Type assertions will cause compilation errors for wrong relationships:
+ * // expectType<string, number>("=");        // ❌ TypeScript error
+ * // expectType<number, string>("<=");       // ❌ TypeScript error
+ * ```
+ *
+ * ### Array and Tuple Type Validation
+ * @example
+ * ```typescript
+ * // Testing array utility function return types
+ * const zeros = Arr.zeros(3);
+ * expectType<typeof zeros, readonly [0, 0, 0]>("=");
+ *
+ * const sequence = Arr.seq(5);
+ * expectType<typeof sequence, readonly [0, 1, 2, 3, 4]>("=");
+ *
+ * // Dynamic length arrays
+ * const dynamicArray = Arr.zeros(someLength);
+ * expectType<typeof dynamicArray, readonly 0[]>("=");
+ * ```
+ *
+ * ### Function Return Type Testing
+ * @example
+ * ```typescript
+ * // Testing function return types
+ * const createUser = () => ({ id: 1, name: 'John' });
+ * expectType<ReturnType<typeof createUser>, { id: number; name: string }>("~=");
+ *
+ * // Generic function type inference
+ * const identity = <T>(x: T): T => x;
+ * const result = identity('hello');
+ * expectType<typeof result, string>("=");
+ * ```
+ *
+ * ### Union and Intersection Types
+ * @example
+ * ```typescript
+ * // Union type relationships
+ * expectType<string, string | number>("<=");     // string extends union
+ * expectType<string | number, string>(">=");     // union contains string
+ * expectType<string | number, number>(">=");     // union contains number
+ *
+ * // Intersection type relationships
+ * type A = { a: number };
+ * type B = { b: string };
+ * expectType<A & B, A>(">=");                    // intersection extends component
+ * expectType<A, A & B>("<=");                    // component extends intersection
+ * ```
+ *
+ * ### Branded Type Validation
+ * @example
+ * ```typescript
+ * // Testing branded number types
+ * expectType<PositiveInt, number>("<=");         // branded type extends base
+ * expectType<number, PositiveInt>(">=");         // base type is supertype
+ * expectType<PositiveInt, NegativeInt>("!=");    // different branded types
+ *
+ * // Type guard function validation
+ * if (isPositiveInt(value)) {
+ *   expectType<typeof value, PositiveInt>("<=");
+ * }
+ * ```
+ *
+ * ### Optional and Result Type Testing
+ * @example
+ * ```typescript
+ * // Optional type narrowing
+ * const optional: Optional<number> = Optional.some(42);
+ * if (Optional.isSome(optional)) {
+ *   expectType<typeof optional, Optional.Some<number>>("<=");
+ * }
+ * if (Optional.isNone(optional)) {
+ *   expectType<typeof optional, Optional.None>("<=");
+ * }
+ *
+ * // Result type validation
+ * const result: Result<string, Error> = Result.ok('success');
+ * expectType<typeof result, Result<string, Error>>("<=");
+ * ```
+ *
+ * ### Type Guard and Validation Testing
+ * @example
+ * ```typescript
+ * // Testing type guard functions
+ * if (isRecord(value)) {
+ *   expectType<typeof value, UnknownRecord>("<=");
+ * }
+ *
+ * // Testing compile-time type predicates
+ * const obj = { key: 'value' };
+ * if (hasKey(obj, 'key')) {
+ *   expectType<typeof obj.key, unknown>("<=");
+ * }
+ * ```
+ *
+ * ## Common Testing Patterns
+ *
+ * ### Dual Testing Strategy
+ * Combine `expectType` with runtime assertions for comprehensive testing:
+ *
+ * @example
+ * ```typescript
+ * describe('Arr.zeros', () => {
+ *   test('should create array of zeros with correct type', () => {
+ *     const result = Arr.zeros(3);
+ *
+ *     // Compile-time type assertion
+ *     expectType<typeof result, readonly [0, 0, 0]>("=");
+ *
+ *     // Runtime behavior assertion
+ *     expect(result).toStrictEqual([0, 0, 0]);
+ *   });
+ * });
+ * ```
+ *
+ * ### Type Relationship Validation
+ * Test complex type hierarchies and relationships:
+ *
+ * @example
+ * ```typescript
+ * // Ensure proper type hierarchy
+ * expectType<PositiveInt, Int>("<=");           // positive is subset of int
+ * expectType<Int, FiniteNumber>("<=");          // int is subset of finite
+ * expectType<FiniteNumber, number>("<=");       // finite is subset of number
+ *
+ * // Verify mutual exclusion
+ * expectType<PositiveInt, NegativeInt>("!=");   // different int types
+ * expectType<PositiveInt, NegativeInt>("!<=");  // neither extends the other
+ * expectType<NegativeInt, PositiveInt>("!<=");
+ * ```
+ *
+ * ## Important Notes
+ *
+ * - **Compile-time only**: This function has no runtime behavior and will be optimized away.
+ * - **Type inference**: The available relation operators are automatically inferred by TypeScript
+ *   based on the actual type relationship between `A` and `B`.
+ * - **Error feedback**: Invalid type relationships will cause clear TypeScript compilation errors.
+ * - **Test organization**: Typically used in `.test.mts` files alongside runtime assertions.
+ * - **Performance**: Has zero runtime overhead as it's purely a compile-time construct.
+ *
+ * @since 1.0.0
+ */
+const expectType = (_relation) => undefined;
+
+export { expectType };
+//# sourceMappingURL=expect-type.mjs.map

package/dist/expect-type.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"expect-type.mjs","sources":["../src/expect-type.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoMG;AACI,MAAM,UAAU,GAAG,CACxB,SAMoE,KAC3D;;;;"}

package/dist/functional/index.d.mts

@@ -0,0 +1,5 @@
+export * from './match.mjs';
+export * from './optional.mjs';
+export * from './pipe.mjs';
+export * from './result.mjs';
+//# sourceMappingURL=index.d.mts.map

package/dist/functional/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/functional/index.mts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/functional/index.mjs

@@ -0,0 +1,5 @@
+export { match } from './match.mjs';
+export { Optional } from './optional.mjs';
+export { pipe } from './pipe.mjs';
+export { Result } from './result.mjs';
+//# sourceMappingURL=index.mjs.map

package/dist/functional/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}

package/dist/functional/match.d.mts

@@ -0,0 +1,215 @@
+/**
+ * @internal
+ * Utility type to extract the union of all values from a record type.
+ * @template T The record type to extract values from.
+ */
+type ValueOf<T> = T[keyof T];
+/**
+ * @internal
+ * Represents a record with unknown value types.
+ */
+type UnknownRecord = Record<PropertyKey, unknown>;
+/**
+ * @internal
+ * Represents a readonly record mapping keys of type K to values of type V.
+ * @template K The type of keys.
+ * @template V The type of values.
+ */
+type ReadonlyRecord<K extends PropertyKey, V> = Readonly<Record<K, V>>;
+/**
+ * @internal
+ * A relaxed version of Exclude that handles edge cases with property keys.
+ * @template T The type to exclude from.
+ * @template U The type to exclude.
+ */
+type RelaxedExclude<T, U> = T extends U ? never : T;
+/**
+ * @internal
+ * Checks if two types are exactly equal.
+ * @template T First type to compare.
+ * @template U Second type to compare.
+ */
+type TypeEq<T, U> = [T] extends [U] ? ([U] extends [T] ? true : false) : false;
+/**
+ * Type-safe pattern matching function for string-based discriminated unions.
+ *
+ * Provides compile-time guarantees for exhaustive case handling when working with
+ * literal string unions. Automatically enforces completeness checking when all
+ * cases are covered, and requires a default value when cases are incomplete.
+ *
+ * ## Key Features:
+ * - **Exhaustive Matching**: When all cases of a literal union are handled, no default value is needed
+ * - **Partial Matching**: When cases are incomplete or working with general string types, a default value is required
+ * - **Type Safety**: Prevents extra cases and ensures only valid keys are used
+ * - **Strict Property Checking**: Rejects objects with unexpected properties
+ *
+ * @param target - The value to match against
+ * @param cases - Object mapping possible values to their corresponding results
+ * @param defaultValue - Fallback value (required when not all cases are covered)
+ * @returns The matched result or default value
+ *
+ * @example
+ * Exhaustive matching (no default needed):
+ * ```typescript
+ * type Status = 'loading' | 'success' | 'error';
+ * const status: Status = 'loading';
+ *
+ * const message = match(status, {
+ *   loading: 'Please wait...',
+ *   success: 'Operation completed!',
+ *   error: 'Something went wrong'
+ * });
+ * // Type: string
+ * // Result: 'Please wait...'
+ * ```
+ *
+ * @example
+ * Partial matching (default required):
+ * ```typescript
+ * type Priority = 'low' | 'medium' | 'high' | 'critical';
+ * const priority: Priority = 'medium';
+ *
+ * const color = match(priority, {
+ *   high: 'red',
+ *   critical: 'darkred'
+ * }, 'gray'); // Default required for uncovered cases
+ * // Type: 'red' | 'darkred' | 'gray'
+ * // Result: 'gray'
+ * ```
+ *
+ * @example
+ * Working with general string types:
+ * ```typescript
+ * const userInput: string = getUserInput();
+ *
+ * const route = match(userInput, {
+ *   'home': '/',
+ *   'about': '/about',
+ *   'contact': '/contact'
+ * }, '/404'); // Default required for string type
+ * // Type: '/' | '/about' | '/contact' | '/404'
+ * ```
+ *
+ * @example
+ * HTTP status code handling:
+ * ```typescript
+ * type HttpStatus = 200 | 404 | 500;
+ * const status: HttpStatus = 404;
+ *
+ * const response = match(String(status), {
+ *   '200': { ok: true, message: 'Success' },
+ *   '404': { ok: false, message: 'Not Found' },
+ *   '500': { ok: false, message: 'Server Error' }
+ * });
+ * // All cases covered, no default needed
+ * // Result: { ok: false, message: 'Not Found' }
+ * ```
+ *
+ * @example
+ * Complex discriminated union handling:
+ * ```typescript
+ * type ApiResponse =
+ *   | { status: 'loading' }
+ *   | { status: 'success'; data: string }
+ *   | { status: 'error'; error: string };
+ *
+ * const handleResponse = (response: ApiResponse) =>
+ *   match(response.status, {
+ *     loading: 'Please wait...',
+ *     success: 'Data loaded successfully!',
+ *     error: 'Failed to load data'
+ *   });
+ * ```
+ *
+ * @example
+ * Advanced usage with functional composition:
+ * ```typescript
+ * // Creating reusable matchers
+ * const logLevelToColor = (level: string) => match(level, {
+ *   'debug': 'gray',
+ *   'info': 'blue',
+ *   'warn': 'yellow',
+ *   'error': 'red'
+ * }, 'black'); // Default for unknown levels
+ *
+ * const logLevelToIcon = (level: string) => match(level, {
+ *   'debug': '🐛',
+ *   'info': 'ℹ️',
+ *   'warn': '⚠️',
+ *   'error': '❌'
+ * }, '📝');
+ *
+ * // Combining matchers
+ * const formatLogEntry = (level: string, message: string) => ({
+ *   color: logLevelToColor(level),
+ *   icon: logLevelToIcon(level),
+ *   text: `${logLevelToIcon(level)} ${message}`
+ * });
+ * ```
+ */
+export declare const match: MatchFnOverload;
+/**
+ * @internal
+ * Overloaded function type for the match function.
+ * Provides different signatures based on whether exhaustive matching is possible.
+ * @template Case The string literal union type to match against.
+ * @template R The record type containing the case mappings.
+ * @template D The type of the default value.
+ */
+type MatchFnOverload = {
+    /**
+     * Exhaustive matching signature - used when all cases in a literal union are covered.
+     * No default value is required or allowed.
+     * @template Case The string literal union type.
+     * @template R The record type with mappings for all cases.
+     * @param target The value to match.
+     * @param cases Object mapping all possible case values to results.
+     * @returns The matched result value.
+     */
+    <const Case extends string, const R extends ReadonlyRecord<Case, unknown>>(target: Case, cases: StrictPropertyCheck<R, Case>): R[Case];
+    /**
+     * Partial matching signature - used when not all cases are covered or when dealing with general string types.
+     * A default value is required.
+     * @template Case The string type (may be literal union or general string).
+     * @template R The record type with partial case mappings.
+     * @template D The type of the default value.
+     * @param target The value to match.
+     * @param cases Object mapping some case values to results.
+     * @param defaultValue Required fallback value for unmatched cases.
+     * @returns The matched result value or the default value.
+     */
+    <const Case extends string, const R extends UnknownRecord, const D>(target: Case, cases: StrictPropertyCheck<R, Case>, defaultValue: IsLiteralUnionFullyCovered<Case, R> extends true ? never : D): ValueOf<R> | D;
+};
+/**
+ * @internal
+ * Helper type to ensure that an object `T` only contains keys specified in `ExpectedKeys`.
+ * If `T` has any keys not in `ExpectedKeys`, this type resolves to `never`.
+ * @template T The object type to check.
+ * @template ExpectedKeys The union of string literal types representing the allowed keys.
+ */
+type StrictPropertyCheck<T, ExpectedKeys extends PropertyKey> = RelaxedExclude<keyof T, ExpectedKeys> extends never ? T : never;
+/**
+ * @internal
+ * Helper type to check if all cases in `Case` union are fully covered by keys in `R`.
+ * This checks bidirectional coverage: all Case members are in R, and no extra keys.
+ * @template Case A union of string literal types representing the possible cases.
+ * @template R A record type.
+ */
+type AllCasesCovered<Case extends PropertyKey, R> = TypeEq<Case, keyof R> extends true ? true : false;
+/**
+ * @internal
+ * Helper type to check if Case is a literal union type and all cases are covered.
+ * @template Case A union of string literal types.
+ * @template R A record type.
+ */
+type IsLiteralUnionFullyCovered<Case extends PropertyKey, R extends UnknownRecord> = TypeEq<IsLiteralType<Case>, true> extends true ? AllCasesCovered<Case, R> : false;
+/**
+ * @internal
+ * Helper type to determine if a given PropertyKey `T` is a literal type (e.g., 'a', 1)
+ * or a general type (e.g., string, number).
+ * @template T The PropertyKey type to check.
+ * @returns `true` if `T` is a literal type, `false` otherwise.
+ */
+type IsLiteralType<T extends PropertyKey> = string extends T ? false : number extends T ? false : symbol extends T ? false : true;
+export {};
+//# sourceMappingURL=match.d.mts.map

package/dist/functional/match.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.mts","sourceRoot":"","sources":["../../src/functional/match.mts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAE7B;;;GAGG;AACH,KAAK,aAAa,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAElD;;;;;GAKG;AACH,KAAK,cAAc,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAEvE;;;;;GAKG;AACH,KAAK,cAAc,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoHG;AACH,eAAO,MAAM,KAAK,EAAE,eAuBC,CAAC;AAEtB;;;;;;;GAOG;AACH,KAAK,eAAe,GAAG;IACrB;;;;;;;;OAQG;IACH,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,EACvE,MAAM,EAAE,IAAI,EACZ,KAAK,EAAE,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAAC,GAClC,CAAC,CAAC,IAAI,CAAC,CAAC;IAEX;;;;;;;;;;OAUG;IACH,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,aAAa,EAAE,KAAK,CAAC,CAAC,EAChE,MAAM,EAAE,IAAI,EACZ,KAAK,EAAE,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAAC,EACnC,YAAY,EAAE,0BAA0B,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,GACzE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,KAAK,mBAAmB,CAAC,CAAC,EAAE,YAAY,SAAS,WAAW,IAC1D,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,SAAS,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC;AAElE;;;;;;GAMG;AACH,KAAK,eAAe,CAAC,IAAI,SAAS,WAAW,EAAE,CAAC,IAC9C,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,SAAS,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;AAOpD;;;;;GAKG;AACH,KAAK,0BAA0B,CAC7B,IAAI,SAAS,WAAW,EACxB,CAAC,SAAS,aAAa,IAEvB,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,GAC1C,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,GACxB,KAAK,CAAC;AAkBZ;;;;;;GAMG;AACH,KAAK,aAAa,CAAC,CAAC,SAAS,WAAW,IAAI,MAAM,SAAS,CAAC,GACxD,KAAK,GACL,MAAM,SAAS,CAAC,GACd,KAAK,GACL,MAAM,SAAS,CAAC,GACd,KAAK,GACL,IAAI,CAAC"}

package/dist/functional/match.mjs

@@ -0,0 +1,139 @@
+import { keyIsIn } from '../guard/key-is-in.mjs';
+
+/**
+ * Type-safe pattern matching function for string-based discriminated unions.
+ *
+ * Provides compile-time guarantees for exhaustive case handling when working with
+ * literal string unions. Automatically enforces completeness checking when all
+ * cases are covered, and requires a default value when cases are incomplete.
+ *
+ * ## Key Features:
+ * - **Exhaustive Matching**: When all cases of a literal union are handled, no default value is needed
+ * - **Partial Matching**: When cases are incomplete or working with general string types, a default value is required
+ * - **Type Safety**: Prevents extra cases and ensures only valid keys are used
+ * - **Strict Property Checking**: Rejects objects with unexpected properties
+ *
+ * @param target - The value to match against
+ * @param cases - Object mapping possible values to their corresponding results
+ * @param defaultValue - Fallback value (required when not all cases are covered)
+ * @returns The matched result or default value
+ *
+ * @example
+ * Exhaustive matching (no default needed):
+ * ```typescript
+ * type Status = 'loading' | 'success' | 'error';
+ * const status: Status = 'loading';
+ *
+ * const message = match(status, {
+ *   loading: 'Please wait...',
+ *   success: 'Operation completed!',
+ *   error: 'Something went wrong'
+ * });
+ * // Type: string
+ * // Result: 'Please wait...'
+ * ```
+ *
+ * @example
+ * Partial matching (default required):
+ * ```typescript
+ * type Priority = 'low' | 'medium' | 'high' | 'critical';
+ * const priority: Priority = 'medium';
+ *
+ * const color = match(priority, {
+ *   high: 'red',
+ *   critical: 'darkred'
+ * }, 'gray'); // Default required for uncovered cases
+ * // Type: 'red' | 'darkred' | 'gray'
+ * // Result: 'gray'
+ * ```
+ *
+ * @example
+ * Working with general string types:
+ * ```typescript
+ * const userInput: string = getUserInput();
+ *
+ * const route = match(userInput, {
+ *   'home': '/',
+ *   'about': '/about',
+ *   'contact': '/contact'
+ * }, '/404'); // Default required for string type
+ * // Type: '/' | '/about' | '/contact' | '/404'
+ * ```
+ *
+ * @example
+ * HTTP status code handling:
+ * ```typescript
+ * type HttpStatus = 200 | 404 | 500;
+ * const status: HttpStatus = 404;
+ *
+ * const response = match(String(status), {
+ *   '200': { ok: true, message: 'Success' },
+ *   '404': { ok: false, message: 'Not Found' },
+ *   '500': { ok: false, message: 'Server Error' }
+ * });
+ * // All cases covered, no default needed
+ * // Result: { ok: false, message: 'Not Found' }
+ * ```
+ *
+ * @example
+ * Complex discriminated union handling:
+ * ```typescript
+ * type ApiResponse =
+ *   | { status: 'loading' }
+ *   | { status: 'success'; data: string }
+ *   | { status: 'error'; error: string };
+ *
+ * const handleResponse = (response: ApiResponse) =>
+ *   match(response.status, {
+ *     loading: 'Please wait...',
+ *     success: 'Data loaded successfully!',
+ *     error: 'Failed to load data'
+ *   });
+ * ```
+ *
+ * @example
+ * Advanced usage with functional composition:
+ * ```typescript
+ * // Creating reusable matchers
+ * const logLevelToColor = (level: string) => match(level, {
+ *   'debug': 'gray',
+ *   'info': 'blue',
+ *   'warn': 'yellow',
+ *   'error': 'red'
+ * }, 'black'); // Default for unknown levels
+ *
+ * const logLevelToIcon = (level: string) => match(level, {
+ *   'debug': '🐛',
+ *   'info': 'ℹ️',
+ *   'warn': '⚠️',
+ *   'error': '❌'
+ * }, '📝');
+ *
+ * // Combining matchers
+ * const formatLogEntry = (level: string, message: string) => ({
+ *   color: logLevelToColor(level),
+ *   icon: logLevelToIcon(level),
+ *   text: `${logLevelToIcon(level)} ${message}`
+ * });
+ * ```
+ */
+const match = ((...args) => {
+    switch (args.length) {
+        case 2: {
+            const [target, cases] = args;
+            return cases[target];
+        }
+        case 3: {
+            const [target, cases, defaultValue] = args;
+            if (keyIsIn(target, cases)) {
+                return cases[target];
+            }
+            else {
+                return defaultValue;
+            }
+        }
+    }
+});
+
+export { match };
+//# sourceMappingURL=match.mjs.map

package/dist/functional/match.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.mjs","sources":["../../src/functional/match.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAwCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoHG;MACU,KAAK,IAAqB,CAKrC,GAAG,IAEmD,KACpC;AAClB,IAAA,QAAQ,IAAI,CAAC,MAAM;QACjB,KAAK,CAAC,EAAE;AACN,YAAA,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,IAAI;AAC5B,YAAA,OAAO,KAAK,CAAC,MAAM,CAAC;;QAEtB,KAAK,CAAC,EAAE;YACN,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,IAAI;AAC1C,YAAA,IAAI,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE;AAC1B,gBAAA,OAAO,KAAK,CAAC,MAAM,CAAC;;iBACf;AACL,gBAAA,OAAO,YAAY;;;;AAI3B,CAAC;;;;"}