ts-data-forge 5.0.0 → 5.1.0

package/src/functional/result.test.mts

@@ -9,7 +9,9 @@ describe('Result test', () => {
       const result = Result.ok(42);
 
       expect(Result.isOk(result)).toBe(true);
+
       expect(Result.isErr(result)).toBe(false);
+
       expect(result.value).toBe(42);
 
       expectType<typeof result, Result<number, never>>('<=');
@@ -19,6 +21,7 @@ describe('Result test', () => {
       const result = Result.ok('success');
 
       expect(Result.isOk(result)).toBe(true);
+
       expect(result.value).toBe('success');
 
       expectType<typeof result, Result<string, never>>('<=');
@@ -30,7 +33,9 @@ describe('Result test', () => {
       const result = Result.err('error message');
 
       expect(Result.isErr(result)).toBe(true);
+
       expect(Result.isOk(result)).toBe(false);
+
       expect(result.value).toBe('error message');
 
       expectType<typeof result, Result<never, string>>('<=');
@@ -40,6 +45,7 @@ describe('Result test', () => {
       const result = Result.err(404);
 
       expect(Result.isErr(result)).toBe(true);
+
       expect(result.value).toBe(404);
 
       expectType<typeof result, Result<never, number>>('<=');
@@ -49,6 +55,7 @@ describe('Result test', () => {
   describe('isOk', () => {
     test('type guard for Ok results', () => {
       const result: Result<number, string> = Result.ok(42);
+
       if (Result.isOk(result)) {
         expectType<typeof result, Ok<number>>('<=');
 
@@ -66,6 +73,7 @@ describe('Result test', () => {
   describe('isErr', () => {
     test('type guard for Err results', () => {
       const result: Result<number, string> = Result.err('error');
+
       if (Result.isErr(result)) {
         expectType<typeof result, Err<string>>('<=');
 
@@ -95,10 +103,15 @@ describe('Result test', () => {
 
     test('rejects non-Result values', () => {
       expect(Result.isResult(42)).toBe(false);
+
       expect(Result.isResult('string')).toBe(false);
+
       expect(Result.isResult(null)).toBe(false);
+
       expect(Result.isResult(undefined)).toBe(false);
+
       expect(Result.isResult({})).toBe(false);
+
       expect(Result.isResult({ type: 'unknown', value: 42 })).toBe(false);
     });
   });
@@ -106,6 +119,7 @@ describe('Result test', () => {
   describe('map', () => {
     test('maps Ok result', () => {
       const result = Result.ok(5);
+
       const mapped = Result.map(result, (x) => x * 2);
 
       expect(Result.isOk(mapped)).toBe(true);
@@ -113,11 +127,13 @@ describe('Result test', () => {
       if (Result.isOk(mapped)) {
         expect(mapped.value).toBe(10);
       }
+
       expectType<typeof mapped, Result<number, never>>('<=');
     });
 
     test('preserves Err result', () => {
       const result: Result<number, string> = Result.err('error');
+
       const mapped = Result.map(result, (x) => x * 2);
 
       expect(Result.isErr(mapped)).toBe(true);
@@ -125,6 +141,7 @@ describe('Result test', () => {
       if (Result.isErr(mapped)) {
         expect(mapped.value).toBe('error');
       }
+
       expectType<typeof mapped, Result<number, string>>('<=');
     });
 
@@ -132,6 +149,7 @@ describe('Result test', () => {
       const doubler = Result.map((x: number) => x * 2);
 
       const okResult = Result.ok(5);
+
       const mapped = doubler(okResult);
 
       expect(Result.isOk(mapped)).toBe(true);
@@ -141,6 +159,7 @@ describe('Result test', () => {
       }
 
       const errResult: Result<number, string> = Result.err('error');
+
       const mappedErr = doubler(errResult);
 
       expect(Result.isErr(mappedErr)).toBe(true);
@@ -152,6 +171,7 @@ describe('Result test', () => {
 
     test('should work with pipe when curried', () => {
       const doubler = Result.map((x: number) => x * 2);
+
       const toStringFn = Result.map((x: number) => x.toString());
 
       const result = pipe(Result.ok(5)).map(doubler).map(toStringFn).value;
@@ -167,6 +187,7 @@ describe('Result test', () => {
   describe('mapErr', () => {
     test('maps Err result', () => {
       const result: Result<number, string> = Result.err('error');
+
       const mapped = Result.mapErr(result, (e) => e.toUpperCase());
 
       expect(Result.isErr(mapped)).toBe(true);
@@ -174,11 +195,13 @@ describe('Result test', () => {
       if (Result.isErr(mapped)) {
         expect(mapped.value).toBe('ERROR');
       }
+
       expectType<typeof mapped, Result<number, string>>('<=');
     });
 
     test('preserves Ok result', () => {
       const result: Result<number, string> = Result.ok(42);
+
       const mapped = Result.mapErr(result, (e: string) => e.toUpperCase());
 
       expect(Result.isOk(mapped)).toBe(true);
@@ -186,6 +209,7 @@ describe('Result test', () => {
       if (Result.isOk(mapped)) {
         expect(mapped.value).toBe(42);
       }
+
       expectType<typeof mapped, Result<number, string>>('~=');
     });
 
@@ -193,6 +217,7 @@ describe('Result test', () => {
       const errorUppercase = Result.mapErr((e: string) => e.toUpperCase());
 
       const errResult: Result<number, string> = Result.err('error');
+
       const mapped = errorUppercase(errResult);
 
       expect(Result.isErr(mapped)).toBe(true);
@@ -202,6 +227,7 @@ describe('Result test', () => {
       }
 
       const okResult: Result<number, string> = Result.ok(42);
+
       const mappedOk = errorUppercase(okResult);
 
       expect(Result.isOk(mappedOk)).toBe(true);
@@ -213,6 +239,7 @@ describe('Result test', () => {
 
     test('should work with pipe when curried', () => {
       const errorUppercase = Result.mapErr((e: string) => e.toUpperCase());
+
       const errorPrefix = Result.mapErr((e: string) => `ERROR: ${e}`);
 
       const result = pipe(Result.err('failed'))
@@ -230,6 +257,7 @@ describe('Result test', () => {
   describe('unwrapThrow', () => {
     test('unwraps Ok result', () => {
       const result = Result.ok(42);
+
       const value = Result.unwrapThrow(result);
 
       expect(value).toBe(42);
@@ -247,6 +275,7 @@ describe('Result test', () => {
   describe('unwrapOkOr', () => {
     test('unwraps Ok result', () => {
       const result = Result.ok(42);
+
       const value = Result.unwrapOkOr(result, 0);
 
       expect(value).toBe(42);
@@ -256,6 +285,7 @@ describe('Result test', () => {
 
     test('returns default for Err result', () => {
       const result: Result<number, string> = Result.err('error');
+
       const value = Result.unwrapOkOr(result, 0);
 
       expect(value).toBe(0);
@@ -267,11 +297,13 @@ describe('Result test', () => {
       const unwrapWithDefault = Result.unwrapOkOr(42);
 
       const okResult = Result.ok(100);
+
       const successValue = unwrapWithDefault(okResult);
 
       expect(successValue).toBe(100);
 
       const errResult: Result<number, string> = Result.err('failed');
+
       const defaultValue = unwrapWithDefault(errResult);
 
       expect(defaultValue).toBe(42);
@@ -295,6 +327,7 @@ describe('Result test', () => {
   describe('unwrapErr', () => {
     test('unwraps Err result', () => {
       const result: Result<number, string> = Result.err('error');
+
       const value = Result.unwrapErr(result);
 
       expect(value).toBe('error');
@@ -317,6 +350,7 @@ describe('Result test', () => {
   describe('fold', () => {
     test('folds Ok result', () => {
       const result = Result.ok(42);
+
       const folded = Result.fold(
         result,
         (x) => x * 2,
@@ -328,11 +362,13 @@ describe('Result test', () => {
       if (Result.isOk(folded)) {
         expect(folded.value).toBe(84);
       }
+
       expectType<typeof folded, Result<number, number>>('=');
     });
 
     test('folds Err result', () => {
       const result: Result<number, string> = Result.err('error');
+
       const folded = Result.fold(
         result,
         (x) => x * 2,
@@ -344,6 +380,7 @@ describe('Result test', () => {
       if (Result.isErr(folded)) {
         expect(folded.value).toBe(5); // length of 'error'
       }
+
       expectType<typeof folded, Result<number, number>>('=');
     });
 
@@ -354,6 +391,7 @@ describe('Result test', () => {
       );
 
       const okResult = Result.ok(42);
+
       const foldedOk = folder(okResult);
 
       expect(Result.isOk(foldedOk)).toBe(true);
@@ -363,6 +401,7 @@ describe('Result test', () => {
       }
 
       const errResult: Result<number, string> = Result.err('error');
+
       const foldedErr = folder(errResult);
 
       expect(Result.isErr(foldedErr)).toBe(true);
@@ -404,22 +443,26 @@ describe('Result test', () => {
       const result = await Result.fromPromise(asyncFn());
 
       expect(Result.isOk(result)).toBe(true);
+
       expect(Result.unwrapOk(result)).toBe(42);
     });
 
     test('handles async functions that reject', async () => {
       const error = new Error('Async error');
+
       const asyncFn = async (): Promise<number> =>
         Promise.reject(error).then(() => 42);
 
       const result = await Result.fromPromise(asyncFn());
 
       expect(Result.isErr(result)).toBe(true);
+
       expect(Result.unwrapErr(result)).toBe(error);
     });
 
     test('works with different promise types', async () => {
       const stringPromise = Promise.resolve('hello');
+
       const result = await Result.fromPromise(stringPromise);
 
       expect(Result.unwrapOk(result)).toBe('hello');
@@ -456,6 +499,7 @@ describe('Result test', () => {
     test('should support chaining multiple flatMaps', () => {
       const parseNumber = (s: string): Result<number, string> => {
         const n = Number(s);
+
         return Number.isNaN(n) ? Result.err('Not a number') : Result.ok(n);
       };
 
@@ -481,6 +525,7 @@ describe('Result test', () => {
       const divideBy2 = Result.flatMap((x: number) => divide(x, 2));
 
       const okResult = Result.ok(10);
+
       const result = divideBy2(okResult);
 
       expect(Result.isOk(result)).toBe(true);
@@ -490,6 +535,7 @@ describe('Result test', () => {
       }
 
       const divideByZero = Result.flatMap((x: number) => divide(x, 0));
+
       const errorResult = divideByZero(Result.ok(10));
 
       expect(Result.isErr(errorResult)).toBe(true);
@@ -510,6 +556,7 @@ describe('Result test', () => {
     test('should work with pipe when curried', () => {
       const parseNumber = (s: string): Result<number, string> => {
         const n = Number(s);
+
         return Number.isNaN(n) ? Result.err('Not a number') : Result.ok(n);
       };
 
@@ -517,6 +564,7 @@ describe('Result test', () => {
         n > 0 ? Result.ok(n * 2) : Result.err('Not positive');
 
       const parser = Result.flatMap(parseNumber);
+
       const doubler = Result.flatMap(doubleIfPositive);
 
       const result = pipe(Result.ok('42')).map(parser).map(doubler).value;
@@ -532,17 +580,21 @@ describe('Result test', () => {
   describe('swap', () => {
     test('should swap Ok to Err', () => {
       const okResult = Result.ok(42);
+
       const swapped = Result.swap(okResult);
 
       expect(Result.isErr(swapped)).toBe(true);
+
       expect(Result.unwrapErr(swapped)).toBe(42);
     });
 
     test('should swap Err to Ok', () => {
       const errResult = Result.err('error');
+
       const swapped = Result.swap(errResult);
 
       expect(Result.isOk(swapped)).toBe(true);
+
       expect(Result.unwrapOk(swapped)).toBe('error');
     });
   });
@@ -550,14 +602,17 @@ describe('Result test', () => {
   describe('toOptional', () => {
     test('should convert Ok to Some-like', () => {
       const okResult = Result.ok(42);
+
       const optional = Result.toOptional(okResult);
 
       expect(Optional.isSome(optional)).toBe(true);
+
       expect(Optional.unwrapThrow(optional)).toBe(42);
     });
 
     test('should convert Err to None-like', () => {
       const errResult = Result.err('error');
+
       const optional = Result.toOptional(errResult);
 
       expect(Optional.isNone(optional)).toBe(true);
@@ -591,6 +646,7 @@ describe('Result test', () => {
   describe('unwrapErrOr', () => {
     test('should return error value for Err result', () => {
       const result = Result.err('error message');
+
       const value = Result.unwrapErrOr(result, 'default');
 
       expect(value).toBe('error message');
@@ -598,6 +654,7 @@ describe('Result test', () => {
 
     test('should return default value for Ok result', () => {
       const result = Result.ok(42);
+
       const value = Result.unwrapErrOr(result, 'default');
 
       expect(value).toBe('default');
@@ -607,11 +664,13 @@ describe('Result test', () => {
       const unwrapErrorWithDefault = Result.unwrapErrOr('unknown error');
 
       const errResult: Result<number, string> = Result.err('failed');
+
       const errorValue = unwrapErrorWithDefault(errResult);
 
       expect(errorValue).toBe('failed');
 
       const okResult: Result<number, string> = Result.ok(42);
+
       const defaultValue = unwrapErrorWithDefault(okResult);
 
       expect(defaultValue).toBe('unknown error');
@@ -637,6 +696,7 @@ describe('Result test', () => {
   describe('expectToBe', () => {
     test('should return value for Ok result', () => {
       const result = Result.ok(42);
+
       const value = Result.expectToBe(result, 'Expected valid number');
 
       expect(value).toBe(42);
@@ -654,6 +714,7 @@ describe('Result test', () => {
       const mustBeOk = Result.expectToBe('Expected successful result');
 
       const okResult = Result.ok('success');
+
       const value = mustBeOk(okResult);
 
       expect(value).toBe('success');
@@ -679,7 +740,9 @@ describe('Result test', () => {
   describe('orElse', () => {
     test('should return the first Result if it is Ok', () => {
       const primary = Result.ok(42);
+
       const fallback = Result.ok(100);
+
       const result = Result.orElse(primary, fallback);
 
       expect(Result.unwrapOk(result)).toBe(42);
@@ -687,7 +750,9 @@ describe('Result test', () => {
 
     test('should return the alternative if the first is Err', () => {
       const primary = Result.err('error');
+
       const fallback = Result.ok('default');
+
       const result = Result.orElse(primary, fallback);
 
       expect(Result.unwrapOk(result)).toBe('default');
@@ -695,7 +760,9 @@ describe('Result test', () => {
 
     test('should return Err if both are Err', () => {
       const primary = Result.err('error1');
+
       const fallback = Result.err('error2');
+
       const result = Result.orElse(primary, fallback);
 
       expect(Result.unwrapErr(result)).toBe('error2');
@@ -705,6 +772,7 @@ describe('Result test', () => {
       const fallbackTo = Result.orElse(Result.ok('fallback'));
 
       const okResult = Result.ok('primary');
+
       const result = fallbackTo(okResult);
 
       expect(Result.isOk(result)).toBe(true);
@@ -714,6 +782,7 @@ describe('Result test', () => {
       }
 
       const errResult: Result<string, string> = Result.err('failed');
+
       const fallbackResult = fallbackTo(errResult);
 
       expect(Result.isOk(fallbackResult)).toBe(true);
@@ -747,7 +816,9 @@ describe('Result test', () => {
   describe('zip', () => {
     test('should combine two Ok values into a tuple', () => {
       const a = Result.ok(1);
+
       const b = Result.ok('hello');
+
       const zipped = Result.zip(a, b);
 
       assert.deepStrictEqual(Result.unwrapOk(zipped), [1, 'hello']);
@@ -755,7 +826,9 @@ describe('Result test', () => {
 
     test('should return first Err if first is Err', () => {
       const a = Result.err('error1');
+
       const b = Result.ok('hello');
+
       const zipped = Result.zip(a, b);
 
       expect(Result.unwrapErr(zipped)).toBe('error1');
@@ -763,7 +836,9 @@ describe('Result test', () => {
 
     test('should return second Err if second is Err', () => {
       const a = Result.ok(1);
+
       const b = Result.err('error2');
+
       const zipped = Result.zip(a, b);
 
       expect(Result.unwrapErr(zipped)).toBe('error2');
@@ -771,7 +846,9 @@ describe('Result test', () => {
 
     test('should return first Err if both are Err', () => {
       const a = Result.err('error1');
+
       const b = Result.err('error2');
+
       const zipped = Result.zip(a, b);
 
       expect(Result.unwrapErr(zipped)).toBe('error1');
@@ -783,6 +860,7 @@ describe('Result test', () => {
       const result = Result.fromThrowable(() => 42);
 
       expect(Result.isOk(result)).toBe(true);
+
       expect(Result.unwrapOk(result)).toBe(42);
 
       expectType<typeof result, Result<number, Error>>('<=');
@@ -790,6 +868,7 @@ describe('Result test', () => {
 
     test('should return Ok with object when function succeeds', () => {
       const obj = { name: 'test', value: 123 };
+
       const result = Result.fromThrowable(() => obj);
 
       expect(Result.isOk(result)).toBe(true);
@@ -799,6 +878,7 @@ describe('Result test', () => {
 
     test('should return Err when function throws Error', () => {
       const errorMessage = 'Something went wrong';
+
       const result = Result.fromThrowable(() => {
         throw new Error(errorMessage);
       });
@@ -809,12 +889,14 @@ describe('Result test', () => {
         const error = result.value;
 
         expect(error).toBeInstanceOf(Error);
+
         expect(error.message).toBe(errorMessage);
       }
     });
 
     test('should return Err when function throws string', () => {
       const errorMessage = 'String error';
+
       const result = Result.fromThrowable(() => {
         // eslint-disable-next-line @typescript-eslint/only-throw-error
         throw errorMessage;
@@ -826,6 +908,7 @@ describe('Result test', () => {
         const error = result.value;
 
         expect(error).toBeInstanceOf(Error);
+
         expect(error.message).toBe(errorMessage);
       }
     });
@@ -842,12 +925,14 @@ describe('Result test', () => {
         const error = result.value;
 
         expect(error).toBeInstanceOf(Error);
+
         expect(error.message).toBe('404');
       }
     });
 
     test('should work with JSON.parse', () => {
       const validJson = '{"key": "value"}';
+
       const invalidJson = '{invalid json}';
 
       // eslint-disable-next-line @typescript-eslint/no-unsafe-return
@@ -875,10 +960,13 @@ describe('Result test', () => {
       // This won't throw, but demonstrates the pattern
       const result = Result.fromThrowable(() => {
         const index = 5;
+
         const value = arr[index];
+
         if (value === undefined) {
           throw new Error('Index out of bounds');
         }
+
         return value;
       });
 

package/src/functional/ternary-result/impl/ternary-result-err.mts

@@ -9,10 +9,11 @@ import { ErrTypeTagName } from './tag.mjs';
  * const failure = TernaryResult.err(new Error('missing data'));
  *
  * assert.strictEqual(failure.$$tag, 'ts-data-forge::Result.err');
+ *
  * assert.ok(TernaryResult.isErr(failure));
  * ```
  */
-export const err = <E,>(value: E): TernaryErr<E> => ({
+export const err = <const E,>(value: E): TernaryErr<E> => ({
   $$tag: ErrTypeTagName,
   value,
 });

package/src/functional/ternary-result/impl/ternary-result-expect-to-be.mts

@@ -11,6 +11,7 @@ import { type UnwrapOk } from './types.mjs';
  * const okValue = TernaryResult.ok('ready');
  *
  * assert.strictEqual(TernaryResult.expectToBe(okValue, 'missing'), 'ready');
+ *
  * const expectResult = TernaryResult.expectToBe<string>('needs value');
  *
  * assert.throws(() => expectResult(TernaryResult.err('oops')), /needs value/u);
@@ -32,10 +33,13 @@ export function expectToBe<R extends UnknownTernaryResult>(
   switch (args.length) {
     case 2: {
       const [result, message] = args;
+
       return expectImpl(result, message);
     }
+
     case 1: {
       const [message] = args;
+
       return (result: R) => expectImpl(result, message);
     }
   }

package/src/functional/ternary-result/impl/ternary-result-flat-map.mts

@@ -17,14 +17,18 @@ import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
  * const doubled = TernaryResult.flatMap(TernaryResult.ok('3'), (text) =>
  *   TernaryResult.map(parse(text), (num) => num * 2),
  * );
+ *
  * const warnPassthrough = TernaryResult.flatMap(
  *   TernaryResult.warn('3', 'retry'),
  *   parse,
  * );
+ *
  * const errPassthrough = TernaryResult.flatMap(TernaryResult.err('oops'), parse);
  *
  * assert.deepStrictEqual(doubled, TernaryResult.ok(6));
+ *
  * assert.deepStrictEqual(warnPassthrough, TernaryResult.warn(3, 'retry'));
+ *
  * assert.deepStrictEqual(errPassthrough, TernaryResult.err('oops'));
  * ```
  */
@@ -51,10 +55,13 @@ export function flatMap<R extends UnknownTernaryResult, S2, W2, E2>(
   switch (args.length) {
     case 2: {
       const [result, flatMapFn] = args;
+
       return flatMapImpl(result, flatMapFn);
     }
+
     case 1: {
       const [flatMapFn] = args;
+
       return (result: R) => flatMapImpl(result, flatMapFn);
     }
   }

package/src/functional/ternary-result/impl/ternary-result-fold.mts

@@ -17,6 +17,7 @@ import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
  *   (warn: string) => warn.length,
  *   (error: string) => error.toUpperCase(),
  * );
+ *
  * const warnFold = TernaryResult.fold(
  *   TernaryResult.warn(2, 'spike'),
  *   (value: number) => value,
@@ -25,6 +26,7 @@ import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
  * );
  *
  * assert.deepStrictEqual(okFold, TernaryResult.ok(4));
+ *
  * assert.deepStrictEqual(warnFold, TernaryResult.warn(2, 'SPIKE'));
  * ```
  */
@@ -59,10 +61,13 @@ export function fold<R extends UnknownTernaryResult, S2, W2, E2>(
   switch (args.length) {
     case 4: {
       const [result, mapOk, mapWarn, mapErr] = args;
+
       return foldImpl(result, mapOk, mapWarn, mapErr);
     }
+
     case 3: {
       const [mapOk, mapWarn, mapErr] = args;
+
       return (result: R) => foldImpl(result, mapOk, mapWarn, mapErr);
     }
   }

package/src/functional/ternary-result/impl/ternary-result-from-promise.mts

@@ -12,11 +12,13 @@ type UnwrapPromise<P extends Promise<unknown>> =
  *
  * ```ts
  * const resolved = await TernaryResult.fromPromise(Promise.resolve('ok'));
+ *
  * const rejected = await TernaryResult.fromPromise(
  *   Promise.reject(new Error('fail')),
  * );
  *
  * assert.deepStrictEqual(resolved, TernaryResult.ok('ok'));
+ *
  * assert.ok(TernaryResult.isErr(rejected));
  * ```
  */