ts-data-forge 3.3.0 → 4.0.0

package/src/expect-type.mts

@@ -1,199 +1,70 @@
 /**
  * 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
+ * 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.
+ *
+ * - **`"="` (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`.
+ *
+ * - **`"~="` (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:
+ * @since 1.0.0
+ * @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
+ * @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.
+ *
+ *   Combine `expectType` with runtime assertions for comprehensive testing:
+ *
+ *   ## 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.
  */
 export const expectType = <A, B>(
   _relation: TypeEq<A, B> extends true

package/src/functional/index.mts

@@ -1,4 +1,4 @@
 export * from './match.mjs';
-export * from './optional.mjs';
+export * from './optional/index.mjs';
 export * from './pipe.mjs';
-export * from './result.mjs';
+export * from './result/index.mjs';

package/src/functional/match.mts

@@ -1,159 +1,47 @@
 import { expectType } from '../expect-type.mjs';
 import { keyIsIn } from '../guard/index.mjs';
 
-/**
- * @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.
+ * 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
+ *
+ * - **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...'
- * ```
+ * ```ts
+ * type Status = 'draft' | 'review' | 'published';
  *
- * @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'
- * ```
+ * const status: Status = 'draft';
  *
- * @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' }
+ * const message = match<
+ *   Status,
+ *   { draft: string; review: string; published: string }
+ * >(status, {
+ *   draft: 'Work in progress',
+ *   review: 'Awaiting feedback',
+ *   published: 'Complete',
  * });
- * // 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'
- *   });
+ * assert(message === 'Work in progress');
  * ```
  *
- * @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}`
- * });
- * ```
+ * @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
  */
 export function match<
   const Case extends string,
@@ -192,21 +80,23 @@ export function match<
 }
 
 /**
+ * @template T The object type to check.
+ * @template ExpectedKeys The union of string literal types representing the
+ *   allowed keys.
  * @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;
 
 /**
+ * @template Case A union of string literal types representing the possible
+ *   cases.
+ * @template R A record type.
  * @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;
@@ -217,10 +107,10 @@ expectType<AllCasesCovered<'a' | 'b', { a: 1; b: 2; c: 3 }>, false>('=');
 expectType<AllCasesCovered<string, Record<string, string>>, true>('=');
 
 /**
- * @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.
+ * @internal
+ * Helper type to check if Case is a literal union type and all cases are covered.
  */
 type IsLiteralUnionFullyCovered<
   Case extends PropertyKey,
@@ -247,11 +137,11 @@ expectType<
 >('=');
 
 /**
+ * @template T The PropertyKey type to check.
+ * @returns `true` if `T` is a literal type, `false` otherwise.
  * @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

package/src/functional/optional/impl/index.mts

@@ -0,0 +1,17 @@
+export * from './optional-expect-to-be.mjs';
+export * from './optional-filter.mjs';
+export * from './optional-flat-map.mjs';
+export * from './optional-from-nullable.mjs';
+export * from './optional-is-none.mjs';
+export * from './optional-is-optional.mjs';
+export * from './optional-is-some.mjs';
+export * from './optional-map.mjs';
+export * from './optional-none.mjs';
+export * from './optional-or-else.mjs';
+export * from './optional-some.mjs';
+export * from './optional-to-nullable.mjs';
+export * from './optional-unwrap-or.mjs';
+export * from './optional-unwrap-throw.mjs';
+export * from './optional-unwrap.mjs';
+export * from './optional-zip.mjs';
+export * from './types.mjs';

package/src/functional/optional/impl/optional-expect-to-be.mts

@@ -0,0 +1,65 @@
+import { isSome } from './optional-is-some.mjs';
+import { unwrap } from './optional-unwrap.mjs';
+import { type Unwrap } from './types.mjs';
+
+/**
+ * Unwraps an `Optional`, returning the contained value or throwing an error
+ * with the provided message.
+ *
+ * @example
+ *
+ * ```ts
+ * const optionalValue = Optional.some('data');
+ *
+ * assert(Optional.expectToBe(optionalValue, 'value expected') === 'data');
+ *
+ * const expectValue = Optional.expectToBe<string>('missing optional');
+ *
+ * assert.throws(() => expectValue(Optional.none), /missing optional/u);
+ * assert(expectValue(Optional.some('present')) === 'present');
+ * ```
+ *
+ * @template O The `UnknownOptional` type to unwrap.
+ * @param optional The `Optional` to unwrap.
+ * @param message The error message to throw if the `Optional` is
+ *   `None`.
+ * @returns The contained value if `Some`.
+ * @throws Error with the provided message if the `Optional` is
+ *   `None`.
+ */
+export function expectToBe<O extends UnknownOptional>(
+  optional: O,
+  message: string,
+): Unwrap<O>;
+
+// Curried version
+export function expectToBe<S>(message: string): (optional: Optional<S>) => S;
+
+export function expectToBe<O extends UnknownOptional>(
+  ...args: readonly [optional: O, message: string] | readonly [message: string]
+): Unwrap<O> | ((optional: Optional<Unwrap<O>>) => Unwrap<O>) {
+  switch (args.length) {
+    case 2: {
+      const [optional, message] = args;
+      return expectToBeImpl(optional, message);
+    }
+
+    case 1: {
+      // Curried version: first argument is message
+      const [message] = args;
+      return (optional: Optional<Unwrap<O>>): Unwrap<O> =>
+        expectToBeImpl(optional, message);
+    }
+  }
+}
+
+const expectToBeImpl = <O extends UnknownOptional>(
+  optional: O,
+  message: string,
+): Unwrap<O> => {
+  if (isSome(optional)) {
+    return unwrap(optional);
+  }
+
+  throw new Error(message);
+};

package/src/functional/optional/impl/optional-filter.mts

@@ -0,0 +1,71 @@
+import { isSome } from './optional-is-some.mjs';
+import { none } from './optional-none.mjs';
+import { some } from './optional-some.mjs';
+import { unwrap } from './optional-unwrap.mjs';
+import { type Unwrap } from './types.mjs';
+
+/**
+ * Filters an `Optional` based on a predicate. If the `Optional` is `Some` and
+ * the predicate returns true, returns the original `Optional`. Otherwise
+ * returns `None`.
+ *
+ * @example
+ *
+ * ```ts
+ * const even = Optional.filter(Optional.some(4), (value) => value % 2 === 0);
+ * const odd = Optional.filter(Optional.some(3), (value) => value % 2 === 0);
+ *
+ * assert.deepStrictEqual(even, Optional.some(4));
+ * assert.deepStrictEqual(odd, Optional.none);
+ *
+ * const filterEven = Optional.filter((value: number) => value % 2 === 0);
+ *
+ * assert.deepStrictEqual(filterEven(Optional.some(6)), Optional.some(6));
+ * assert.deepStrictEqual(filterEven(Optional.some(5)), Optional.none);
+ * ```
+ *
+ * @template O The input `UnknownOptional` type.
+ * @param optional The `Optional` to filter.
+ * @param predicate The predicate function.
+ * @returns The filtered `Optional`.
+ */
+export function filter<O extends UnknownOptional>(
+  optional: O,
+  predicate: (value: Unwrap<O>) => boolean,
+): Optional<Unwrap<O>>;
+
+// Curried version
+export function filter<S>(
+  predicate: (value: S) => boolean,
+): (optional: Optional<S>) => Optional<S>;
+
+export function filter<O extends UnknownOptional>(
+  ...args:
+    | readonly [optional: O, predicate: (value: Unwrap<O>) => boolean]
+    | readonly [predicate: (value: Unwrap<O>) => boolean]
+): Optional<Unwrap<O>> | ((optional: O) => Optional<Unwrap<O>>) {
+  switch (args.length) {
+    case 2: {
+      const [optional, predicate] = args;
+      return filterImpl(optional, predicate);
+    }
+
+    case 1: {
+      // Curried version: first argument is predicate function
+      const [predicate] = args;
+      return (optional: O) => filterImpl(optional, predicate);
+    }
+  }
+}
+
+const filterImpl = <O extends UnknownOptional>(
+  optional: O,
+  predicate: (value: Unwrap<O>) => boolean,
+): Optional<Unwrap<O>> => {
+  if (isSome(optional)) {
+    const value = unwrap(optional);
+    return predicate(value) ? some(value) : none;
+  }
+
+  return none;
+};