ts-data-forge 14.5.0 → 14.6.1

package/src/functional/async-result.test.mts

@@ -0,0 +1,291 @@
+import { isError } from '@sindresorhus/is';
+import { AsyncResult as AsyncResultFromEntryPoint } from '../entry-point.mjs';
+import { expectType } from '../expect-type.mjs';
+import { unknownToString } from '../others/index.mjs';
+import { AsyncResult } from './async-result/index.mjs';
+import { Result } from './result/index.mjs';
+
+// Fixtures are created through functions so that the success/error types stay
+// unions instead of being narrowed to literal types by const inference.
+const okFixture = (value: number): AsyncResult<number, string> =>
+  Promise.resolve(Result.ok(value));
+
+const errFixture = (message: string): AsyncResult<number, string> =>
+  Promise.resolve(Result.err(message));
+
+describe('AsyncResult test', () => {
+  describe('fromPromise', () => {
+    test('resolved promise becomes Ok', async () => {
+      const result = await AsyncResult.fromPromise(
+        Promise.resolve(42),
+        (error) => `mapped: ${unknownToString(error)}`,
+      );
+
+      assert.isTrue(Result.isOk(result));
+
+      assert.deepStrictEqual(result, Result.ok(42));
+    });
+
+    test('rejected promise becomes Err with mapError applied', async () => {
+      const result = await AsyncResult.fromPromise(
+        Promise.reject(new Error('boom')),
+        (error) => (isError(error) ? error.message : 'unknown'),
+      );
+
+      assert.isTrue(Result.isErr(result));
+
+      assert.deepStrictEqual(result, Result.err('boom'));
+    });
+
+    test('resolved promise becomes Ok when mapError is omitted', async () => {
+      const result = await AsyncResult.fromPromise(Promise.resolve(42));
+
+      assert.deepStrictEqual(result, Result.ok(42));
+
+      expectType<typeof result, Result<number, unknown>>('=');
+    });
+
+    test('rejection reason is carried as-is when mapError is omitted', async () => {
+      const error = new Error('boom');
+
+      const result = await AsyncResult.fromPromise(
+        Promise.reject(error).then(() => 42),
+      );
+
+      assert.isTrue(Result.isErr(result));
+
+      assert.deepStrictEqual(result, Result.err(error));
+    });
+  });
+
+  describe('fromThrowable', () => {
+    test('resolved async function becomes Ok', async () => {
+      const result = await AsyncResult.fromThrowable(
+        () => Promise.resolve('data'),
+        (error) => `mapped: ${unknownToString(error)}`,
+      );
+
+      assert.isTrue(Result.isOk(result));
+
+      assert.deepStrictEqual(result, Result.ok('data'));
+    });
+
+    test('synchronous throw becomes Err with mapError applied', async () => {
+      const result = await AsyncResult.fromThrowable(
+        (): Promise<number> => {
+          throw new Error('sync failure');
+        },
+        (error) => (isError(error) ? error.message : 'unknown'),
+      );
+
+      assert.isTrue(Result.isErr(result));
+
+      assert.deepStrictEqual(result, Result.err('sync failure'));
+    });
+
+    test('async rejection becomes Err with mapError applied', async () => {
+      const result = await AsyncResult.fromThrowable(
+        () => Promise.reject(new Error('async failure')),
+        (error) => (isError(error) ? error.message : 'unknown'),
+      );
+
+      assert.isTrue(Result.isErr(result));
+
+      assert.deepStrictEqual(result, Result.err('async failure'));
+    });
+
+    test('synchronous throw is carried as-is when mapError is omitted', async () => {
+      const error = new Error('sync failure');
+
+      const result = await AsyncResult.fromThrowable((): Promise<number> => {
+        throw error;
+      });
+
+      assert.deepStrictEqual(result, Result.err(error));
+
+      expectType<typeof result, Result<number, unknown>>('=');
+    });
+
+    test('async rejection is carried as-is when mapError is omitted', async () => {
+      const error = new Error('async failure');
+
+      const result = await AsyncResult.fromThrowable(() =>
+        Promise.reject(error).then(() => 42),
+      );
+
+      assert.deepStrictEqual(result, Result.err(error));
+    });
+  });
+
+  describe('map', () => {
+    test('maps Ok value with a synchronous function', async () => {
+      const result = await AsyncResult.map(okFixture(5), (value) => value * 2);
+
+      assert.deepStrictEqual(result, Result.ok(10));
+    });
+
+    test('maps Ok value with an asynchronous function', async () => {
+      const result = await AsyncResult.map(okFixture(5), (value) =>
+        Promise.resolve(value * 3),
+      );
+
+      assert.deepStrictEqual(result, Result.ok(15));
+    });
+
+    test('passes Err through unchanged', async () => {
+      let mut_called = false;
+
+      const result = await AsyncResult.map(errFixture('failure'), (value) => {
+        mut_called = true;
+
+        return value * 2;
+      });
+
+      assert.deepStrictEqual(result, Result.err('failure'));
+
+      assert.isFalse(mut_called);
+    });
+
+    test('curried version maps Ok value', async () => {
+      const double = AsyncResult.map((value: number) => value * 2);
+
+      const result = await double(okFixture(21));
+
+      assert.deepStrictEqual(result, Result.ok(42));
+    });
+
+    test('curried version passes Err through unchanged', async () => {
+      const double = AsyncResult.map((value: number) => value * 2);
+
+      const result = await double(errFixture('failure'));
+
+      assert.deepStrictEqual(result, Result.err('failure'));
+    });
+  });
+
+  describe('mapErr', () => {
+    test('maps Err value with a synchronous function', async () => {
+      const result = await AsyncResult.mapErr(errFixture('failure'), (error) =>
+        error.toUpperCase(),
+      );
+
+      assert.deepStrictEqual(result, Result.err('FAILURE'));
+    });
+
+    test('maps Err value with an asynchronous function', async () => {
+      const result = await AsyncResult.mapErr(
+        errFixture('failure'),
+        (message) => Promise.resolve(message.length),
+      );
+
+      assert.deepStrictEqual(result, Result.err(7));
+    });
+
+    test('passes Ok through unchanged', async () => {
+      let mut_called = false;
+
+      const result = await AsyncResult.mapErr(okFixture(1), (error) => {
+        mut_called = true;
+
+        return error.toUpperCase();
+      });
+
+      assert.deepStrictEqual(result, Result.ok(1));
+
+      assert.isFalse(mut_called);
+    });
+
+    test('curried version maps Err value', async () => {
+      const upper = AsyncResult.mapErr((error: string) => error.toUpperCase());
+
+      const result = await upper(errFixture('failure'));
+
+      assert.deepStrictEqual(result, Result.err('FAILURE'));
+    });
+  });
+
+  describe('flatMap', () => {
+    test('chains with a function returning a Result', async () => {
+      const result = await AsyncResult.flatMap(okFixture(4), (value) =>
+        value > 0 ? Result.ok(value * 10) : Result.err('non-positive'),
+      );
+
+      assert.deepStrictEqual(result, Result.ok(40));
+    });
+
+    test('chains with a function returning an AsyncResult', async () => {
+      const result = await AsyncResult.flatMap(okFixture(4), (value) =>
+        AsyncResult.fromPromise(Promise.resolve(value + 1), () => 'failed'),
+      );
+
+      assert.deepStrictEqual(result, Result.ok(5));
+    });
+
+    test('chains into Err returned by the function', async () => {
+      const result = await AsyncResult.flatMap(
+        okFixture(-1),
+        (value): Result<number, string> =>
+          value > 0 ? Result.ok(value * 10) : Result.err('non-positive'),
+      );
+
+      assert.deepStrictEqual(result, Result.err('non-positive'));
+    });
+
+    test('short-circuits on Err without calling the function', async () => {
+      let mut_called = false;
+
+      const result = await AsyncResult.flatMap(
+        errFixture('failure'),
+        (value) => {
+          mut_called = true;
+
+          return Result.ok(value * 2);
+        },
+      );
+
+      assert.deepStrictEqual(result, Result.err('failure'));
+
+      assert.isFalse(mut_called);
+    });
+
+    test('curried version chains with a function returning a Result', async () => {
+      const validate = AsyncResult.flatMap(
+        (value: number): Result<number, string> =>
+          value > 0 ? Result.ok(value) : Result.err('non-positive'),
+      );
+
+      const passed = await validate(okFixture(7));
+
+      const failed = await validate(okFixture(-7));
+
+      assert.deepStrictEqual(passed, Result.ok(7));
+
+      assert.deepStrictEqual(failed, Result.err('non-positive'));
+    });
+  });
+
+  describe('unwrapOr', () => {
+    test('returns the success value for Ok', async () => {
+      const value = await AsyncResult.unwrapOr(okFixture(10), 0);
+
+      expect(value).toBe(10);
+    });
+
+    test('returns the default value for Err', async () => {
+      const value = await AsyncResult.unwrapOr(errFixture('failure'), 0);
+
+      expect(value).toBe(0);
+    });
+  });
+
+  describe('entry point', () => {
+    test('AsyncResult is exported from the package entry point', async () => {
+      const result = await AsyncResultFromEntryPoint.fromPromise(
+        Promise.resolve(1),
+        () => 'failed',
+      );
+
+      assert.deepStrictEqual(result, Result.ok(1));
+    });
+  });
+});

package/src/functional/index.mts

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

package/src/functional/optional.test.mts

@@ -1,5 +1,6 @@
 import { expectType } from '../expect-type.mjs';
 import { Num } from '../number/index.mjs';
+import { unknownToString } from '../others/index.mjs';
 import { type None, type Some } from '../types.mjs';
 import { Optional, type UnknownOptional } from './optional/index.mjs';
 import { pipe } from './pipe.mjs';
@@ -872,7 +873,7 @@ describe('Optional test', () => {
       const makeOptional = (): Optional<undefined> => Optional.some(undefined);
 
       const result = Optional.match(makeOptional(), {
-        some: (value) => `some: ${String(value)}`,
+        some: (value) => `some: ${unknownToString(value)}`,
         none: () => 'none',
       });
 

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

@@ -17,6 +17,11 @@ type UnwrapPromise<P extends Promise<unknown>> =
  * input Promise rejects, the `Result` will be `Err` with the rejection
  * reason.
  *
+ * The error channel is `unknown`, since the rejection reason is carried
+ * through untouched. For a concrete error type, use `AsyncResult.fromPromise`
+ * with a `mapError` function; called without one it behaves exactly as this
+ * function does.
+ *
  * @example
  *
  * ```ts

package/src/functional/result.test.mts

@@ -963,14 +963,12 @@ describe('Result test', () => {
 
       const invalidJson = '{invalid json}';
 
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
       const validResult = Result.fromThrowable(() => JSON.parse(validJson));
 
       assert.isTrue(Result.isOk(validResult));
 
       assert.deepStrictEqual(Result.unwrapOk(validResult), { key: 'value' });
 
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
       const invalidResult = Result.fromThrowable(() => JSON.parse(invalidJson));
 
       assert.isTrue(Result.isErr(invalidResult));

package/src/guard/is-non-empty-string.test.mts

@@ -61,7 +61,7 @@ describe(isNonEmptyString, () => {
       // TypeScript knows it's a string
       expect(value.length).toBeGreaterThan(0);
 
-      expect(value.charAt(0)).toBe('t');
+      expect(value.at(0)).toBe('t');
     }
   });
 
@@ -109,7 +109,7 @@ describe(isNonEmptyString, () => {
 
   test('should not accept String objects', () => {
     // @ts-expect-error Testing non-string types
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isFalse(isNonEmptyString(new String('hello') as unknown));
   });
 });

package/src/guard/is-non-null-object.test.mts

@@ -43,13 +43,13 @@ describe(isNonNullObject, () => {
   });
 
   test('should return true for boxed primitives', () => {
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isTrue(isNonNullObject(new String('hello')));
 
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isTrue(isNonNullObject(new Number(42)));
 
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isTrue(isNonNullObject(new Boolean(true)));
   });
 

package/src/guard/is-primitive.test.mts

@@ -82,13 +82,13 @@ describe(isPrimitive, () => {
   });
 
   test('should return false for boxed primitives', () => {
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isFalse(isPrimitive(new String('hello')));
 
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isFalse(isPrimitive(new Number(42)));
 
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isFalse(isPrimitive(new Boolean(true)));
   });
 

package/src/guard/is-type.test.mts

@@ -136,7 +136,7 @@ describe(isString, () => {
 
     assert.isFalse(isString(undefined));
 
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isFalse(isString(new String('hello')));
   });
 
@@ -175,7 +175,7 @@ describe(isNumber, () => {
 
     assert.isFalse(isNumber(123n));
 
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isFalse(isNumber(new Number(42)));
   });
 
@@ -236,7 +236,7 @@ describe(isBoolean, () => {
 
     assert.isFalse(isBoolean(null));
 
-    // eslint-disable-next-line unicorn/new-for-builtins
+    // eslint-disable-next-line unicorn/new-for-builtins, @typescript-eslint/no-deprecated
     assert.isFalse(isBoolean(new Boolean(true)));
   });
 

package/src/json/json.test.mts

@@ -123,7 +123,7 @@ describe('parse', () => {
 
     expect(() => Json.parse('null null')).not.toThrow();
 
-    expect(() => Json.parse(String(undefined))).not.toThrow();
+    expect(() => Json.parse('undefined')).not.toThrow();
   });
 
   test('should use reviver function to transform values', () => {

package/src/number/enum/int8.mts

@@ -38,7 +38,7 @@ const castType = (x: number): Int8 =>
 const fromNumber = (a: number): Int8 => castType(fromNumberImpl(a));
 
 const abs = <N extends Int8>(x: N): AbsoluteValue<N> =>
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, @typescript-eslint/no-unnecessary-type-assertion -- unnecessary only under the strict standard library; the stock one types `Math.abs` as returning `number`
   Math.abs(x) as unknown as AbsoluteValue<N>;
 
 const min_ = (...values: readonly Int8[]): Int8 =>