ts-data-forge 5.0.0 → 5.1.0

package/src/collections/stack.test.mts

@@ -9,15 +9,22 @@ describe('Stack test', () => {
     const stack = createStack<number>();
 
     expectType<typeof stack, Stack<number>>('=');
+
     expectType<typeof stack.isEmpty, boolean>('=');
+
     expectType<typeof stack.size, SizeType.Arr>('=');
+
     expectType<typeof stack.pop, () => Optional<number>>('=');
+
     expectType<typeof stack.push, (value: number) => void>('=');
 
     // Verify the type checking works at runtime too
     expectTypeOf(stack.isEmpty).toBeBoolean();
+
     expectTypeOf(stack.size).toBeNumber();
+
     expectTypeOf(stack.pop).toBeFunction();
+
     expectTypeOf(stack.push).toBeFunction();
   });
 
@@ -25,6 +32,7 @@ describe('Stack test', () => {
     const stack = createStack<string>();
 
     expect(stack.isEmpty).toBe(true);
+
     expect(stack.size).toBe(0);
   });
 
@@ -32,12 +40,16 @@ describe('Stack test', () => {
     const stack = createStack<number>([1, 2, 3]);
 
     expect(stack.isEmpty).toBe(false);
+
     expect(stack.size).toBe(3);
 
     // Last element should be on top (LIFO)
     expect(Optional.unwrap(stack.pop())).toBe(3);
+
     expect(Optional.unwrap(stack.pop())).toBe(2);
+
     expect(Optional.unwrap(stack.pop())).toBe(1);
+
     expect(stack.isEmpty).toBe(true);
   });
 
@@ -45,20 +57,26 @@ describe('Stack test', () => {
     const stack = createStack<string>();
 
     stack.push('first');
+
     // eslint-disable-next-line unicorn/prefer-single-call
     stack.push('second');
+
     // eslint-disable-next-line unicorn/prefer-single-call
     stack.push('third');
 
     expect(stack.size).toBe(3);
+
     expect(stack.isEmpty).toBe(false);
 
     // LIFO: Last In, First Out
     expect(Optional.unwrap(stack.pop())).toBe('third');
+
     expect(Optional.unwrap(stack.pop())).toBe('second');
+
     expect(Optional.unwrap(stack.pop())).toBe('first');
 
     expect(stack.isEmpty).toBe(true);
+
     expect(stack.size).toBe(0);
   });
 
@@ -68,7 +86,9 @@ describe('Stack test', () => {
     const result = stack.pop();
 
     expect(Optional.isNone(result)).toBe(true);
+
     expect(stack.isEmpty).toBe(true);
+
     expect(stack.size).toBe(0);
   });
 
@@ -100,6 +120,7 @@ describe('Stack test', () => {
     Optional.unwrap(stack.pop());
 
     expect(stack.size).toBe(0);
+
     expect(stack.isEmpty).toBe(true);
   });
 
@@ -107,17 +128,21 @@ describe('Stack test', () => {
     const stack = createStack<string>();
 
     stack.push('a');
+
     // eslint-disable-next-line unicorn/prefer-single-call
     stack.push('b');
 
     expect(Optional.unwrap(stack.pop())).toBe('b');
 
     stack.push('c');
+
     // eslint-disable-next-line unicorn/prefer-single-call
     stack.push('d');
 
     expect(Optional.unwrap(stack.pop())).toBe('d');
+
     expect(Optional.unwrap(stack.pop())).toBe('c');
+
     expect(Optional.unwrap(stack.pop())).toBe('a');
 
     expect(stack.isEmpty).toBe(true);
@@ -125,16 +150,20 @@ describe('Stack test', () => {
 
   test('should work with object types', () => {
     type Item = Readonly<{ id: number; name: string }>;
+
     const stack = createStack<Item>();
 
     const item1: Item = { id: 1, name: 'first' };
+
     const item2: Item = { id: 2, name: 'second' };
 
     stack.push(item1);
+
     // eslint-disable-next-line unicorn/prefer-single-call
     stack.push(item2);
 
     assert.deepStrictEqual(Optional.unwrap(stack.pop()), item2);
+
     assert.deepStrictEqual(Optional.unwrap(stack.pop()), item1);
 
     expect(stack.isEmpty).toBe(true);
@@ -142,6 +171,7 @@ describe('Stack test', () => {
 
   test('should handle large number of operations efficiently', () => {
     const stack = createStack<number>();
+
     const n = asPositiveSafeInt(10_000);
 
     // Push many elements
@@ -150,6 +180,7 @@ describe('Stack test', () => {
     }
 
     expect(stack.size).toBe(n);
+
     expect(stack.isEmpty).toBe(false);
 
     // Pop all elements and verify LIFO order
@@ -157,21 +188,25 @@ describe('Stack test', () => {
       const result = stack.pop();
 
       expect(Optional.isSome(result)).toBe(true);
+
       expect(Optional.unwrap(result)).toBe(i);
     }
 
     expect(stack.isEmpty).toBe(true);
+
     expect(stack.size).toBe(0);
   });
 
   test('should not mutate initial values array', () => {
     const initialValues = [1, 2, 3];
+
     const originalLength = initialValues.length;
 
     const stack = createStack(initialValues);
 
     // Modify stack
     stack.push(4);
+
     Optional.unwrap(stack.pop());
 
     // Original array should be unchanged
@@ -184,17 +219,24 @@ describe('Stack test', () => {
     const stack = createStack<string | null | undefined>();
 
     stack.push('value');
+
     // eslint-disable-next-line unicorn/prefer-single-call
     stack.push(null);
+
     // eslint-disable-next-line unicorn/prefer-single-call
     stack.push(undefined);
+
     // eslint-disable-next-line unicorn/prefer-single-call
     stack.push('another');
 
     expect(Optional.unwrap(stack.pop())).toBe('another');
+
     expect(Optional.unwrap(stack.pop())).toBeUndefined();
+
     expect(Optional.unwrap(stack.pop())).toBeNull();
+
     expect(Optional.unwrap(stack.pop())).toBe('value');
+
     expect(stack.isEmpty).toBe(true);
   });
 
@@ -215,6 +257,7 @@ describe('Stack test', () => {
     }
 
     const endTime = performance.now();
+
     const duration = endTime - startTime;
 
     // Should complete in reasonable time (much less than 100ms for 512 operations)
@@ -226,6 +269,7 @@ describe('Stack test', () => {
 
     for (const i of range(100)) {
       stack.push(i);
+
       if (i % 2 === 1) {
         // Pop every other time
         const result = stack.pop();

package/src/functional/match.mts

@@ -70,10 +70,13 @@ export function match<
   switch (args.length) {
     case 2: {
       const [target, cases] = args;
+
       return cases[target];
     }
+
     case 3: {
       const [target, cases, defaultValue] = args;
+
       return keyIsIn(target, cases) ? cases[target] : defaultValue;
     }
   }
@@ -102,8 +105,11 @@ type AllCasesCovered<Case extends PropertyKey, R> =
   TypeEq<Case, keyof R> extends true ? true : false;
 
 expectType<AllCasesCovered<'a' | 'b', { a: 1; b: 2 }>, true>('=');
+
 expectType<AllCasesCovered<'a' | 'b' | 'c', { a: 1; b: 2 }>, false>('=');
+
 expectType<AllCasesCovered<'a' | 'b', { a: 1; b: 2; c: 3 }>, false>('=');
+
 expectType<AllCasesCovered<string, Record<string, string>>, true>('=');
 
 /**
@@ -121,15 +127,19 @@ type IsLiteralUnionFullyCovered<
     : false;
 
 expectType<IsLiteralUnionFullyCovered<'a' | 'b', { a: 1; b: 2 }>, true>('=');
+
 expectType<IsLiteralUnionFullyCovered<'a' | 'b' | 'c', { a: 1; b: 2 }>, false>(
   '=',
 );
+
 expectType<IsLiteralUnionFullyCovered<'a' | 'b', { a: 1; b: 2; c: 3 }>, false>(
   '=',
 );
+
 expectType<IsLiteralUnionFullyCovered<string, Record<string, string>>, false>(
   '=',
 );
+
 expectType<
   // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
   IsLiteralUnionFullyCovered<'a' | 'b' | string, { a: 1; b: 2 }>,
@@ -152,9 +162,15 @@ type IsLiteralType<T extends PropertyKey> = string extends T
       : true;
 
 expectType<IsLiteralType<'a' | 'b'>, true>('=');
+
 expectType<IsLiteralType<'a'>, true>('=');
+
 expectType<IsLiteralType<string>, false>('=');
+
 expectType<IsLiteralType<number>, false>('=');
+
 expectType<IsLiteralType<1>, true>('=');
+
 expectType<IsLiteralType<number | 'aa'>, false>('=');
+
 expectType<IsLiteralType<'aa' | 32>, true>('=');

package/src/functional/match.test.mts

@@ -3,6 +3,7 @@ import { match } from './match.mjs';
 
 describe(match, () => {
   type Direction = 'E' | 'N' | 'S' | 'W';
+
   const direction: Direction = 'N' as Direction;
 
   test('literal union', () => {
@@ -159,6 +160,7 @@ describe(match, () => {
 
   test('with default case - string key missing', () => {
     const unknownDirection = 'X' as string;
+
     const res = match(
       unknownDirection,
       {

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

@@ -16,6 +16,7 @@ import { type Unwrap } from './types.mjs';
  * const expectValue = Optional.expectToBe<string>('missing optional');
  *
  * assert.throws(() => expectValue(Optional.none), /missing optional/u);
+ *
  * assert(expectValue(Optional.some('present')) === 'present');
  * ```
  *
@@ -41,12 +42,14 @@ export function expectToBe<O extends UnknownOptional>(
   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);
     }

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

@@ -13,14 +13,17 @@ import { type Unwrap } from './types.mjs';
  *
  * ```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);
  * ```
  *
@@ -47,12 +50,14 @@ export function filter<O extends UnknownOptional>(
   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);
     }
   }
@@ -64,6 +69,7 @@ const filterImpl = <O extends UnknownOptional>(
 ): Optional<Unwrap<O>> => {
   if (isSome(optional)) {
     const value = unwrap(optional);
+
     return predicate(value) ? some(value) : none;
   }
 

package/src/functional/optional/impl/optional-flat-map.mts

@@ -13,6 +13,7 @@ import { type Unwrap } from './types.mjs';
  * ```ts
  * const parseNumber = (input: string): Optional<number> => {
  *   const num = Number.parseInt(input, 10);
+ *
  *   return Number.isNaN(num) ? Optional.none : Optional.some(num);
  * };
  *
@@ -23,6 +24,7 @@ import { type Unwrap } from './types.mjs';
  * const flatMapParse = Optional.flatMap(parseNumber);
  *
  * assert.deepStrictEqual(flatMapParse(Optional.some('5')), Optional.some(5));
+ *
  * assert.deepStrictEqual(flatMapParse(Optional.some('invalid')), Optional.none);
  * ```
  *
@@ -50,12 +52,14 @@ export function flatMap<O extends UnknownOptional, S2>(
   switch (args.length) {
     case 2: {
       const [optional, flatMapFn] = args;
+
       return flatMapImpl(optional, flatMapFn);
     }
 
     case 1: {
       // Curried version
       const [flatMapFn] = args;
+
       return (optional: O) => flatMapImpl(optional, flatMapFn);
     }
   }

package/src/functional/optional/impl/optional-from-nullable.mts

@@ -12,9 +12,11 @@ import { some } from './optional-some.mjs';
  *
  * ```ts
  * const present = Optional.fromNullable('hello');
+ *
  * const absent = Optional.fromNullable<string | null>(null);
  *
  * assert.deepStrictEqual(present, Optional.some('hello'));
+ *
  * assert.deepStrictEqual(absent, Optional.none);
  * ```
  *

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

@@ -8,9 +8,11 @@ import { NoneTypeTagName, SomeTypeTagName } from './tag.mjs';
  *
  * ```ts
  * const maybeOptional = Optional.some('value');
+ *
  * const notOptional = { $$tag: 'ts-data-forge::Optional.some' };
  *
  * assert.ok(Optional.isOptional(maybeOptional));
+ *
  * assert.notOk(Optional.isOptional(notOptional));
  * ```
  *

package/src/functional/optional/impl/optional-is-some.mts

@@ -11,6 +11,7 @@ import { type NarrowToSome } from './types.mjs';
  *
  * if (Optional.isSome(optionalNumber)) {
  *   const value: number = optionalNumber.value;
+ *
  *   assert(value === 42);
  * }
  * ```

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

@@ -14,6 +14,7 @@ import { type Unwrap } from './types.mjs';
  *
  * ```ts
  * const numberOptional = Optional.some(21);
+ *
  * const mapped = Optional.map(numberOptional, (value) => value * 2);
  *
  * assert.deepStrictEqual(mapped, Optional.some(42));
@@ -21,6 +22,7 @@ import { type Unwrap } from './types.mjs';
  * const mapToLength = Optional.map((text: string) => text.length);
  *
  * assert.deepStrictEqual(mapToLength(Optional.some('abc')), Optional.some(3));
+ *
  * assert.deepStrictEqual(mapToLength(Optional.none), Optional.none);
  * ```
  *
@@ -49,11 +51,14 @@ export function map<O extends UnknownOptional, S2>(
   switch (args.length) {
     case 2: {
       const [optional, mapFn] = args;
+
       return mapImpl(optional, mapFn);
     }
+
     case 1: {
       // Curried version: first argument is mapping function
       const [mapFn] = args;
+
       return (optional: O) => mapImpl(optional, mapFn);
     }
   }

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

@@ -8,9 +8,11 @@ import { NoneTypeTagName } from './tag.mjs';
  *
  * ```ts
  * const someValue = Optional.some({ id: 1 });
+ *
  * const noneValue = Optional.none;
  *
  * assert.ok(Optional.isSome(someValue));
+ *
  * assert.ok(Optional.isNone(noneValue));
  * ```
  */

package/src/functional/optional/impl/optional-or-else.mts

@@ -12,15 +12,19 @@ import { type Unwrap } from './types.mjs';
  *
  * ```ts
  * const preferred = Optional.some('primary');
+ *
  * const fallback = Optional.some('secondary');
+ *
  * const noneValue = Optional.none as Optional<string>;
  *
  * assert.deepStrictEqual(Optional.orElse(preferred, fallback), preferred);
+ *
  * assert.deepStrictEqual(Optional.orElse(noneValue, fallback), fallback);
  *
  * const orElseFallback = Optional.orElse(Optional.some('default'));
  *
  * assert.deepStrictEqual(orElseFallback(Optional.none), Optional.some('default'));
+ *
  * assert.deepStrictEqual(
  *   orElseFallback(Optional.some('value')),
  *   Optional.some('value'),
@@ -52,12 +56,14 @@ export function orElse<
   switch (args.length) {
     case 2: {
       const [optional, alternative] = args;
+
       return orElseImpl(optional, alternative);
     }
 
     case 1: {
       // Curried version
       const [alternative] = args;
+
       return (optional: Optional<Unwrap<O>>) =>
         orElseImpl(optional, alternative);
     }

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

@@ -7,9 +7,11 @@ import { SomeTypeTagName } from './tag.mjs';
  *
  * ```ts
  * const someValue = Optional.some({ id: 1 });
+ *
  * const noneValue = Optional.none;
  *
  * assert.ok(Optional.isSome(someValue));
+ *
  * assert.ok(Optional.isNone(noneValue));
  * ```
  *
@@ -17,7 +19,7 @@ import { SomeTypeTagName } from './tag.mjs';
  * @param value The value to wrap in an {@link Some}.
  * @returns An {@link Some}<S> containing the value.
  */
-export const some = <S,>(value: S): Some<S> => ({
+export const some = <const S,>(value: S): Some<S> => ({
   $$tag: SomeTypeTagName,
   value,
 });

package/src/functional/optional/impl/optional-to-nullable.mts

@@ -16,9 +16,11 @@ import { type Unwrap } from './types.mjs';
  *
  * ```ts
  * const someNumber = Optional.some(42);
+ *
  * const noneNumber = Optional.none as Optional<number>;
  *
  * assert(Optional.toNullable(someNumber) === 42);
+ *
  * assert(Optional.toNullable(noneNumber) === undefined);
  * ```
  *

package/src/functional/optional/impl/optional-unwrap-or.mts

@@ -13,14 +13,17 @@ import { type Unwrap } from './types.mjs';
  *
  * ```ts
  * const withValue = Optional.some(5);
+ *
  * const withoutValue = Optional.none as Optional<number>;
  *
  * assert(Optional.unwrapOr(withValue, 0) === 5);
+ *
  * assert(Optional.unwrapOr(withoutValue, 0) === 0);
  *
  * const unwrapWithDefault = Optional.unwrapOr(10);
  *
  * assert(unwrapWithDefault(Optional.some(3)) === 3);
+ *
  * assert(unwrapWithDefault(Optional.none) === 10);
  * ```
  *
@@ -46,12 +49,14 @@ export function unwrapOr<O extends UnknownOptional, D>(
   switch (args.length) {
     case 2: {
       const [optional, defaultValue] = args;
+
       return unwrapOrImpl(optional, defaultValue);
     }
 
     case 1: {
       // Curried version: first argument is default value
       const [defaultValue] = args;
+
       return (optional: Optional<Unwrap<O>>) =>
         unwrapOrImpl(optional, defaultValue);
     }

package/src/functional/optional/impl/optional-unwrap-throw.mts

@@ -15,6 +15,7 @@ import { type Unwrap } from './types.mjs';
  * const present = Optional.some('available');
  *
  * assert(Optional.unwrapThrow(present) === 'available');
+ *
  * assert.throws(
  *   () => Optional.unwrapThrow(Optional.none),
  *   /has failed because it is `None`/u,

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

@@ -15,9 +15,11 @@ import { type Unwrap } from './types.mjs';
  *
  * ```ts
  * const someString = Optional.some('text');
+ *
  * const noneString = Optional.none as Optional<string>;
  *
  * assert(Optional.unwrap(someString) === 'text');
+ *
  * assert(Optional.unwrap(noneString) === undefined);
  * ```
  *

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

@@ -12,8 +12,10 @@ import { some } from './optional-some.mjs';
  * const zipped = Optional.zip(Optional.some('left'), Optional.some(1));
  *
  * assert.ok(Optional.isSome(zipped));
+ *
  * if (Optional.isSome(zipped)) {
  *   const expected: readonly [string, number] = ['left', 1];
+ *
  *   assert.deepStrictEqual(zipped.value, expected);
  * }
  *