ts-data-forge 14.5.0 → 14.6.0

package/dist/functional/async-result/impl/types.d.mts

@@ -0,0 +1,45 @@
+import { type Err, type Ok } from '../../../types.mjs';
+import { type UnknownResult } from '../../result/index.mjs';
+import { type AsyncResult } from '../async-result.mjs';
+/**
+ * Base type for any `AsyncResult`, used for generic constraints. Represents
+ * an `AsyncResult` with unknown success and error types.
+ */
+export type UnknownAsyncResult = AsyncResult<unknown, unknown>;
+/**
+ * Extracts the success value type `S` from a `Result.Ok<S>`, or from an
+ * `AsyncResult` resolving to one. Distributes over unions, so an
+ * `Ok<S> | Err<E>` union resolves to `S`.
+ *
+ * @template R The `Result` or `AsyncResult` type to unwrap.
+ */
+export type UnwrapOk<R extends UnknownAsyncResult | UnknownResult> = UnwrapOkImpl<SyncResultOf<R>>;
+/**
+ * Extracts the error value type `E` from a `Result.Err<E>`, or from an
+ * `AsyncResult` resolving to one. Distributes over unions, so an
+ * `Ok<S> | Err<E>` union resolves to `E`.
+ *
+ * @template R The `Result` or `AsyncResult` type to unwrap.
+ */
+export type UnwrapErr<R extends UnknownAsyncResult | UnknownResult> = UnwrapErrImpl<SyncResultOf<R>>;
+/**
+ * @template R The `Result` or `AsyncResult` type.
+ * @internal
+ * Resolves an `AsyncResult` to its `Result`, leaving a plain `Result`
+ * unchanged. Distributive.
+ */
+type SyncResultOf<R> = R extends Promise<infer P> ? P : R;
+/**
+ * @template R The `Result` type to unwrap.
+ * @internal
+ * Distributive extraction of the `Ok` value type.
+ */
+type UnwrapOkImpl<R> = R extends Ok<infer S> ? S : never;
+/**
+ * @template R The `Result` type to unwrap.
+ * @internal
+ * Distributive extraction of the `Err` value type.
+ */
+type UnwrapErrImpl<R> = R extends Err<infer E> ? E : never;
+export {};
+//# sourceMappingURL=types.d.mts.map

package/dist/functional/async-result/impl/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../../../src/functional/async-result/impl/types.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,EAAE,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,kBAAkB,GAAG,aAAa,IAC/D,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,kBAAkB,GAAG,aAAa,IAChE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjC;;;;;GAKG;AACH,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE1D;;;;GAIG;AACH,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEzD;;;;GAIG;AACH,KAAK,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC"}

package/dist/functional/async-result/impl/types.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=types.mjs.map

package/dist/functional/async-result/impl/types.mjs.map

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

package/dist/functional/async-result/index.d.mts

@@ -0,0 +1,2 @@
+export * from './async-result.mjs';
+//# sourceMappingURL=index.d.mts.map

package/dist/functional/async-result/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../src/functional/async-result/index.mts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/functional/async-result/index.mjs

@@ -0,0 +1,3 @@
+import * as index from './impl/index.mjs';
+export { index as AsyncResult };
+//# sourceMappingURL=index.mjs.map

package/dist/functional/async-result/index.mjs.map

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

package/dist/functional/index.d.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/dist/functional/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/functional/index.mts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/functional/index.mts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC"}

package/dist/functional/index.mjs

@@ -1,9 +1,11 @@
+import * as index from './async-result/impl/index.mjs';
+export { index as AsyncResult };
 export { match } from './match.mjs';
-import * as index from './optional/impl/index.mjs';
-export { index as Optional };
+import * as index$1 from './optional/impl/index.mjs';
+export { index$1 as Optional };
 export { pipe } from './pipe.mjs';
-import * as index$1 from './result/impl/index.mjs';
-export { index$1 as Result };
-import * as index$2 from './ternary-result/impl/index.mjs';
-export { index$2 as TernaryResult };
+import * as index$2 from './result/impl/index.mjs';
+export { index$2 as Result };
+import * as index$3 from './ternary-result/impl/index.mjs';
+export { index$3 as TernaryResult };
 //# sourceMappingURL=index.mjs.map

package/dist/functional/index.mjs.map

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

package/dist/functional/result/impl/result-from-promise.d.mts

@@ -11,6 +11,11 @@ type UnwrapPromise<P extends Promise<unknown>> = P extends Promise<infer V> ? V
  * 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/dist/functional/result/impl/result-from-promise.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"result-from-promise.d.mts","sourceRoot":"","sources":["../../../../src/functional/result/impl/result-from-promise.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAI5C;;;;GAIG;AACH,KAAK,aAAa,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,IAC3C,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,WAC3C,CAAC,KACT,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAEmB,CAAC"}
+{"version":3,"file":"result-from-promise.d.mts","sourceRoot":"","sources":["../../../../src/functional/result/impl/result-from-promise.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAI5C;;;;GAIG;AACH,KAAK,aAAa,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,IAC3C,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,WAC3C,CAAC,KACT,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAEmB,CAAC"}

package/dist/functional/result/impl/result-from-promise.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"result-from-promise.mjs","sources":["../../../../src/functional/result/impl/result-from-promise.mts"],"sourcesContent":["import { type Ok } from '../../../types.mjs';\nimport { type Result } from '../result.mjs';\nimport { err } from './result-err.mjs';\nimport { ok } from './result-ok.mjs';\n\n/**\n * @template P The Promise type.\n * @internal\n * Utility type to extract the resolved value type from a Promise.\n */\ntype UnwrapPromise<P extends Promise<unknown>> =\n  P extends Promise<infer V> ? V : never;\n\n/**\n * Converts a Promise into a Promise that resolves to a `Result`. If the input\n * Promise resolves, the `Result` will be `Ok` with the resolved value. If the\n * input Promise rejects, the `Result` will be `Err` with the rejection\n * reason.\n *\n * @example\n *\n * ```ts\n * const successPromise = Result.fromPromise(Promise.resolve('ok'));\n *\n * const failurePromise = Result.fromPromise(\n *   Promise.reject(new Error('fail')),\n * );\n *\n * const resolved = await successPromise;\n *\n * const rejected = await failurePromise;\n *\n * assert.deepStrictEqual(resolved, Result.ok('ok'));\n *\n * assert.isTrue(Result.isErr(rejected));\n * ```\n *\n * @template P The type of the input Promise.\n * @param promise The Promise to convert.\n * @returns A Promise that resolves to `Result<UnwrapPromise<P>, unknown>`.\n */\nexport const fromPromise = <P extends Promise<unknown>>(\n  promise: P,\n): Promise<Result<UnwrapPromise<P>, unknown>> =>\n  // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n  promise.then((v) => ok(v) as Ok<UnwrapPromise<P>>).catch(err);\n"],"names":[],"mappings":";;;AAyCO,MAAM,cAAc,CACzB,OAAA;AAAA;AAAA,EAGA,OAAA,CAAQ,KAAK,CAAC,CAAA,KAAM,GAAG,CAAC,CAAyB,CAAA,CAAE,KAAA,CAAM,GAAG;AAAA;;;;"}
+{"version":3,"file":"result-from-promise.mjs","sources":["../../../../src/functional/result/impl/result-from-promise.mts"],"sourcesContent":["import { type Ok } from '../../../types.mjs';\nimport { type Result } from '../result.mjs';\nimport { err } from './result-err.mjs';\nimport { ok } from './result-ok.mjs';\n\n/**\n * @template P The Promise type.\n * @internal\n * Utility type to extract the resolved value type from a Promise.\n */\ntype UnwrapPromise<P extends Promise<unknown>> =\n  P extends Promise<infer V> ? V : never;\n\n/**\n * Converts a Promise into a Promise that resolves to a `Result`. If the input\n * Promise resolves, the `Result` will be `Ok` with the resolved value. If the\n * input Promise rejects, the `Result` will be `Err` with the rejection\n * reason.\n *\n * The error channel is `unknown`, since the rejection reason is carried\n * through untouched. For a concrete error type, use `AsyncResult.fromPromise`\n * with a `mapError` function; called without one it behaves exactly as this\n * function does.\n *\n * @example\n *\n * ```ts\n * const successPromise = Result.fromPromise(Promise.resolve('ok'));\n *\n * const failurePromise = Result.fromPromise(\n *   Promise.reject(new Error('fail')),\n * );\n *\n * const resolved = await successPromise;\n *\n * const rejected = await failurePromise;\n *\n * assert.deepStrictEqual(resolved, Result.ok('ok'));\n *\n * assert.isTrue(Result.isErr(rejected));\n * ```\n *\n * @template P The type of the input Promise.\n * @param promise The Promise to convert.\n * @returns A Promise that resolves to `Result<UnwrapPromise<P>, unknown>`.\n */\nexport const fromPromise = <P extends Promise<unknown>>(\n  promise: P,\n): Promise<Result<UnwrapPromise<P>, unknown>> =>\n  // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n  promise.then((v) => ok(v) as Ok<UnwrapPromise<P>>).catch(err);\n"],"names":[],"mappings":";;;AA8CO,MAAM,cAAc,CACzB,OAAA;AAAA;AAAA,EAGA,OAAA,CAAQ,KAAK,CAAC,CAAA,KAAM,GAAG,CAAC,CAAyB,CAAA,CAAE,KAAA,CAAM,GAAG;AAAA;;;;"}

package/dist/json/json.mjs

@@ -34,13 +34,13 @@ import '../number/enum/int8.mjs';
 import '../number/enum/uint8.mjs';
 import '../number/num.mjs';
 import '../number/refined-number-utils.mjs';
-import { isRecord } from '../guard/is-record.mjs';
-import { pipe } from '../functional/pipe.mjs';
 import { err } from '../functional/result/impl/result-err.mjs';
 import { ok } from '../functional/result/impl/result-ok.mjs';
+import { isRecord } from '../guard/is-record.mjs';
 import '@sindresorhus/is';
 import { castMutable } from '../others/cast-mutable.mjs';
 import { unknownToString } from '../others/unknown-to-string.mjs';
+import { pipe } from '../functional/pipe.mjs';
 import '../collections/imap-mapped.mjs';
 import '../collections/imap.mjs';
 import '../collections/iset-mapped.mjs';

package/dist/number/refined-number-utils.mjs

@@ -1,5 +1,5 @@
-import { pipe } from '../functional/pipe.mjs';
 import '@sindresorhus/is';
+import { pipe } from '../functional/pipe.mjs';
 import { Num } from './num.mjs';
 
 var TsDataForgeInternals;

package/dist/object/object.mjs

@@ -34,9 +34,9 @@ import '../number/enum/int8.mjs';
 import '../number/enum/uint8.mjs';
 import '../number/num.mjs';
 import '../number/refined-number-utils.mjs';
+import { isSome } from '../functional/optional/impl/optional-is-some.mjs';
 import { hasKey } from '../guard/has-key.mjs';
 import { isRecord } from '../guard/is-record.mjs';
-import { isSome } from '../functional/optional/impl/optional-is-some.mjs';
 import '@sindresorhus/is';
 import { isNonEmpty } from '../array/impl/array-utils-length-bounded-array-guard.mjs';
 import '../collections/imap-mapped.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "14.5.0",
+  "version": "14.6.0",
   "private": false,
   "keywords": [
     "typescript",
@@ -46,20 +46,20 @@
     "@types/react": "19.2.18",
     "@vitest/browser-playwright": "4.1.11",
     "dedent": "1.7.2",
-    "eslint-config-typed": "5.10.0",
-    "eslint-plugin-ts-fortress": "1.0.5",
-    "eslint-plugin-ts-type-forge": "0.7.1",
+    "eslint-config-typed": "5.10.1",
+    "eslint-plugin-ts-fortress": "1.0.6",
+    "eslint-plugin-ts-type-forge": "0.7.2",
     "immer": "11.1.18",
     "playwright": "1.62.1",
     "prettier": "3.9.6",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
     "react": "19.2.8",
-    "rollup": "4.62.4",
-    "ts-repo-utils": "10.3.2",
+    "rollup": "4.62.5",
+    "ts-repo-utils": "10.3.3",
     "typedoc": "0.28.20",
     "typedoc-github-theme": "0.4.0",
-    "vite": "8.2.1"
+    "vite": "8.2.2"
   },
   "peerDependencies": {
     "typescript": ">=4.8"

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

@@ -0,0 +1,17 @@
+import { type Result } from '../result/index.mjs';
+
+/**
+ * Represents an asynchronous computation that can either succeed (`Ok`) or
+ * fail (`Err`) — a `Promise` that resolves to a `Result<S, E>`.
+ *
+ * Unlike a raw `Promise`, an `AsyncResult` never rejects for expected
+ * failures: errors are carried in the `Err` channel with a concrete type `E`,
+ * so they can be handled with the same combinators as a synchronous
+ * `Result`.
+ *
+ * @template S The type of the success value.
+ * @template E The type of the error value.
+ */
+export type AsyncResult<S, E> = Promise<Result<S, E>>;
+
+export * as AsyncResult from './impl/index.mjs';

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

@@ -0,0 +1,99 @@
+import { Result, type UnknownResult } from '../../result/index.mjs';
+import { type AsyncResult } from '../async-result.mjs';
+import {
+  type UnknownAsyncResult,
+  type UnwrapErr,
+  type UnwrapOk,
+} from './types.mjs';
+
+/**
+ * Applies a function that returns an `AsyncResult` or a `Result` to the
+ * success value of an `AsyncResult`. If the input resolves to `Err`, the
+ * original `Err` is passed through and the function is not called. This is
+ * the monadic bind operation for `AsyncResult`.
+ *
+ * @example
+ *
+ * ```ts
+ * const parseNumber = (input: string): Result<number, string> => {
+ *   const num = Number.parseInt(input, 10);
+ *
+ *   return Number.isNaN(num) ? Result.err('not a number') : Result.ok(num);
+ * };
+ *
+ * const input = AsyncResult.fromPromise(
+ *   Promise.resolve('42'),
+ *   () => 'failed',
+ * );
+ *
+ * const parsed = await AsyncResult.flatMap(input, parseNumber);
+ *
+ * assert.deepStrictEqual(parsed, Result.ok(42));
+ * ```
+ *
+ * @template S The type of the success value of the input.
+ * @template E The type of the error value of the input.
+ * @template R2 The `AsyncResult` or `Result` type returned by the function.
+ * @param asyncResult The `AsyncResult` to flat map.
+ * @param flatMapFn The function to apply that returns an `AsyncResult` or a
+ *   `Result`.
+ * @returns The result of applying the function, or the original `Err`.
+ */
+export function flatMap<S, E, R2 extends UnknownAsyncResult | UnknownResult>(
+  asyncResult: AsyncResult<S, E>,
+  flatMapFn: (value: S) => R2,
+): AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>;
+
+// Curried version
+//
+// The function's return type is captured as a whole (`R2`) and unwrapped with
+// `UnwrapOk` / `UnwrapErr`, instead of being written as
+// `AsyncResult<S2, E2> | Result<S2, E2>` with separate `S2` / `E2` type
+// parameters. With the union form, inference for `E2` collects a candidate
+// from matching `Ok<S2>` against `Err<E2>` (both have a `value` property), so
+// `E2` ends up as the success type and the call fails to type-check even for
+// a function annotated as returning `Result<S2, E2>`.
+export function flatMap<S, R2 extends UnknownAsyncResult | UnknownResult>(
+  flatMapFn: (value: S) => R2,
+): <E>(
+  asyncResult: AsyncResult<S, E>,
+) => AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>;
+
+export function flatMap<S, E, R2 extends UnknownAsyncResult | UnknownResult>(
+  ...args:
+    | readonly [asyncResult: AsyncResult<S, E>, flatMapFn: (value: S) => R2]
+    | readonly [flatMapFn: (value: S) => R2]
+):
+  | AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>
+  | ((
+      asyncResult: AsyncResult<S, E>,
+    ) => AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>) {
+  switch (args.length) {
+    case 2: {
+      // Direct version: first argument is asyncResult
+      const [asyncResult, flatMapFn] = args;
+
+      return flatMapImpl(asyncResult, flatMapFn);
+    }
+
+    case 1: {
+      // Curried version
+      const [flatMapFn] = args;
+
+      return (asyncResult: AsyncResult<S, E>) =>
+        flatMapImpl(asyncResult, flatMapFn);
+    }
+  }
+}
+
+const flatMapImpl = async <S, E, R2 extends UnknownAsyncResult | UnknownResult>(
+  asyncResult: AsyncResult<S, E>,
+  flatMapFn: (value: S) => R2,
+): AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>> => {
+  const result = await asyncResult;
+
+  return Result.isErr(result)
+    ? result
+    : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      ((await flatMapFn(result.value)) as Result<UnwrapOk<R2>, UnwrapErr<R2>>);
+};

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

@@ -0,0 +1,69 @@
+import { Result } from '../../result/index.mjs';
+import { type AsyncResult } from '../async-result.mjs';
+
+/**
+ * Converts a `Promise` into an `AsyncResult`. If the input Promise resolves,
+ * the `AsyncResult` resolves to `Ok` with the resolved value. If the input
+ * Promise rejects, the rejection reason is passed through `mapError` and the
+ * `AsyncResult` resolves to `Err` with the mapped error.
+ *
+ * Passing `mapError` is what gives the error channel a concrete type `E`.
+ * Omitting it carries the rejection reason through untouched, leaving the
+ * error channel as `unknown` — the same contract as `Result.fromPromise`.
+ *
+ * @example
+ *
+ * ```ts
+ * const resolved = await AsyncResult.fromPromise(
+ *   Promise.resolve('ok'),
+ *   (error) => `failed: ${String(error)}`,
+ * );
+ *
+ * const rejected = await AsyncResult.fromPromise(
+ *   Promise.reject(new Error('boom')),
+ *   (error) => (isError(error) ? error.message : 'unknown'),
+ * );
+ *
+ * assert.deepStrictEqual(resolved, Result.ok('ok'));
+ *
+ * assert.deepStrictEqual(rejected, Result.err('boom'));
+ *
+ * // Without `mapError`, the rejection reason is carried as-is.
+ * const untyped = await AsyncResult.fromPromise(
+ *   Promise.reject(new Error('boom')),
+ * );
+ *
+ * assert.isTrue(Result.isErr(untyped));
+ * ```
+ *
+ * @template S The type of the success value.
+ * @template E The type of the error value.
+ * @param promise The Promise to convert.
+ * @param mapError The function applied to the rejection reason to produce the
+ *   error value. Omit it to carry the rejection reason as `unknown`.
+ * @returns An `AsyncResult<S, E>` that never rejects for the input Promise's
+ *   failure.
+ */
+export function fromPromise<S>(promise: Promise<S>): AsyncResult<S, unknown>;
+
+export function fromPromise<S, E>(
+  promise: Promise<S>,
+  mapError: (error: unknown) => E,
+): AsyncResult<S, E>;
+
+export function fromPromise<S, E>(
+  promise: Promise<S>,
+  mapError?: (error: unknown) => E,
+): AsyncResult<S, E> | AsyncResult<S, unknown> {
+  return mapError === undefined
+    ? fromPromiseImpl(promise, (error: unknown) => error)
+    : fromPromiseImpl(promise, mapError);
+}
+
+const fromPromiseImpl = <S, E>(
+  promise: Promise<S>,
+  mapError: (error: unknown) => E,
+): AsyncResult<S, E> =>
+  promise
+    .then((value) => Result.ok(value))
+    .catch((error: unknown) => Result.err(mapError(error)));

package/src/functional/async-result/impl/async-result-from-throwable.mts

@@ -0,0 +1,78 @@
+import { Result } from '../../result/index.mjs';
+import { type AsyncResult } from '../async-result.mjs';
+
+/**
+ * Wraps a function returning a `Promise` in an `AsyncResult`. Both a
+ * synchronous `throw` while calling `fn` and an asynchronous rejection of the
+ * returned Promise are caught, passed through `mapError`, and carried as
+ * `Err`.
+ *
+ * Passing `mapError` is what gives the error channel a concrete type `E`.
+ * Omitting it carries the thrown value through untouched, leaving the error
+ * channel as `unknown`.
+ *
+ * @example
+ *
+ * ```ts
+ * const success = await AsyncResult.fromThrowable(
+ *   () => Promise.resolve(2),
+ *   (error) => `failed: ${String(error)}`,
+ * );
+ *
+ * const failure = await AsyncResult.fromThrowable(
+ *   (): Promise<number> => {
+ *     throw new Error('boom');
+ *   },
+ *   (error) => (isError(error) ? error.message : 'unknown'),
+ * );
+ *
+ * assert.deepStrictEqual(success, Result.ok(2));
+ *
+ * assert.deepStrictEqual(failure, Result.err('boom'));
+ *
+ * // Without `mapError`, the thrown value is carried as-is.
+ * const untyped = await AsyncResult.fromThrowable(
+ *   (): Promise<number> => {
+ *     throw new Error('boom');
+ *   },
+ * );
+ *
+ * assert.isTrue(Result.isErr(untyped));
+ * ```
+ *
+ * @template S The type of the success value.
+ * @template E The type of the error value.
+ * @param fn The function to execute; it may throw synchronously or return a
+ *   rejecting Promise.
+ * @param mapError The function applied to the thrown value or rejection
+ *   reason to produce the error value. Omit it to carry the thrown value as
+ *   `unknown`.
+ * @returns An `AsyncResult<S, E>` containing either the resolved value or the
+ *   mapped error.
+ */
+export function fromThrowable<S>(fn: () => Promise<S>): AsyncResult<S, unknown>;
+
+export function fromThrowable<S, E>(
+  fn: () => Promise<S>,
+  mapError: (error: unknown) => E,
+): AsyncResult<S, E>;
+
+export function fromThrowable<S, E>(
+  fn: () => Promise<S>,
+  mapError?: (error: unknown) => E,
+): AsyncResult<S, E> | AsyncResult<S, unknown> {
+  return mapError === undefined
+    ? fromThrowableImpl(fn, (error: unknown) => error)
+    : fromThrowableImpl(fn, mapError);
+}
+
+const fromThrowableImpl = async <S, E>(
+  fn: () => Promise<S>,
+  mapError: (error: unknown) => E,
+): AsyncResult<S, E> => {
+  try {
+    return Result.ok(await fn());
+  } catch (error) {
+    return Result.err(mapError(error));
+  }
+};

package/src/functional/async-result/impl/async-result-map-err.mts

@@ -0,0 +1,84 @@
+import { Result } from '../../result/index.mjs';
+import { type AsyncResult } from '../async-result.mjs';
+
+/**
+ * Maps an `AsyncResult<S, E>` to `AsyncResult<S, E2>` by applying a function
+ * to the error value. The mapping function may be synchronous or return a
+ * `Promise`; both are handled transparently. If the `AsyncResult` resolves to
+ * `Ok`, the original `Ok` is passed through and the function is not called.
+ *
+ * If `mapFn` throws or returns a rejecting Promise, the rejection propagates
+ * as-is — it is **not** caught and converted into an `Err`.
+ *
+ * @example
+ *
+ * ```ts
+ * const errValue = AsyncResult.fromPromise(
+ *   Promise.reject(new Error('boom')),
+ *   () => 'failure',
+ * );
+ *
+ * const uppercased = await AsyncResult.mapErr(errValue, (error) =>
+ *   error.toUpperCase(),
+ * );
+ *
+ * assert.deepStrictEqual(uppercased, Result.err('FAILURE'));
+ * ```
+ *
+ * @template S The type of the success value.
+ * @template E The type of the error value of the input.
+ * @template E2 The type of the error value returned by the mapping function.
+ * @param asyncResult The `AsyncResult` to map.
+ * @param mapFn The function to apply to the error value if present.
+ * @returns A new `AsyncResult<S, E2>`.
+ */
+export function mapErr<S, E, E2>(
+  asyncResult: AsyncResult<S, E>,
+  mapFn: (error: E) => E2 | Promise<E2>,
+): AsyncResult<S, E2>;
+
+// Curried version
+//
+// Unlike `Result.mapErr`, the returned function can simply be generic over
+// `S`: an `AsyncResult` is a `Promise`, not a discriminated union, so there
+// is no literal-narrowing problem that would require the whole-result
+// generic trick used by the synchronous combinators.
+export function mapErr<E, E2>(
+  mapFn: (error: E) => E2 | Promise<E2>,
+): <S>(asyncResult: AsyncResult<S, E>) => AsyncResult<S, E2>;
+
+export function mapErr<S, E, E2>(
+  ...args:
+    | readonly [
+        asyncResult: AsyncResult<S, E>,
+        mapFn: (error: E) => E2 | Promise<E2>,
+      ]
+    | readonly [mapFn: (error: E) => E2 | Promise<E2>]
+):
+  | AsyncResult<S, E2>
+  | ((asyncResult: AsyncResult<S, E>) => AsyncResult<S, E2>) {
+  switch (args.length) {
+    case 2: {
+      // Direct version: first argument is asyncResult
+      const [asyncResult, mapFn] = args;
+
+      return mapErrImpl(asyncResult, mapFn);
+    }
+
+    case 1: {
+      // Curried version: first argument is mapping function
+      const [mapFn] = args;
+
+      return (asyncResult: AsyncResult<S, E>) => mapErrImpl(asyncResult, mapFn);
+    }
+  }
+}
+
+const mapErrImpl = async <S, E, E2>(
+  asyncResult: AsyncResult<S, E>,
+  mapFn: (error: E) => E2 | Promise<E2>,
+): AsyncResult<S, E2> => {
+  const result = await asyncResult;
+
+  return Result.isOk(result) ? result : Result.err(await mapFn(result.value));
+};

package/src/functional/async-result/impl/async-result-map.mts

@@ -0,0 +1,94 @@
+import { Result } from '../../result/index.mjs';
+import { type AsyncResult } from '../async-result.mjs';
+
+/**
+ * Maps an `AsyncResult<S, E>` to `AsyncResult<S2, E>` by applying a function
+ * to the success value. The mapping function may be synchronous or return a
+ * `Promise`; both are handled transparently. If the `AsyncResult` resolves to
+ * `Err`, the original `Err` is passed through and the function is not called.
+ *
+ * If `mapFn` throws or returns a rejecting Promise, the rejection propagates
+ * as-is — it is **not** caught and converted into an `Err`. `map` performs no
+ * implicit error conversion; write a fallible step as
+ * `AsyncResult.flatMap` combined with `AsyncResult.fromThrowable` instead, so
+ * that the error type stays explicit.
+ *
+ * @example
+ *
+ * ```ts
+ * const okValue = AsyncResult.fromPromise(
+ *   Promise.resolve(5),
+ *   () => 'failed',
+ * );
+ *
+ * const doubled = await AsyncResult.map(okValue, (value) => value * 2);
+ *
+ * assert.deepStrictEqual(doubled, Result.ok(10));
+ *
+ * const double = AsyncResult.map((value: number) => value * 2);
+ *
+ * const curried = await double(
+ *   AsyncResult.fromPromise(Promise.resolve(21), () => 'failed'),
+ * );
+ *
+ * assert.deepStrictEqual(curried, Result.ok(42));
+ * ```
+ *
+ * @template S The type of the success value of the input.
+ * @template S2 The type of the success value returned by the mapping
+ *   function.
+ * @template E The type of the error value.
+ * @param asyncResult The `AsyncResult` to map.
+ * @param mapFn The function to apply to the success value if present.
+ * @returns A new `AsyncResult<S2, E>`.
+ */
+export function map<S, S2, E>(
+  asyncResult: AsyncResult<S, E>,
+  mapFn: (value: S) => Promise<S2> | S2,
+): AsyncResult<S2, E>;
+
+// Curried version
+//
+// Unlike `Result.map`, the returned function can simply be generic over `E`:
+// an `AsyncResult` is a `Promise`, not a discriminated union, so there is no
+// literal-narrowing problem that would require the whole-result generic
+// trick used by the synchronous combinators.
+export function map<S, S2>(
+  mapFn: (value: S) => Promise<S2> | S2,
+): <E>(asyncResult: AsyncResult<S, E>) => AsyncResult<S2, E>;
+
+export function map<S, S2, E>(
+  ...args:
+    | readonly [
+        asyncResult: AsyncResult<S, E>,
+        mapFn: (value: S) => Promise<S2> | S2,
+      ]
+    | readonly [mapFn: (value: S) => Promise<S2> | S2]
+):
+  | AsyncResult<S2, E>
+  | ((asyncResult: AsyncResult<S, E>) => AsyncResult<S2, E>) {
+  switch (args.length) {
+    case 2: {
+      // Direct version: first argument is asyncResult
+      const [asyncResult, mapFn] = args;
+
+      return mapImpl(asyncResult, mapFn);
+    }
+
+    case 1: {
+      // Curried version
+      const [mapFn] = args;
+
+      return (asyncResult: AsyncResult<S, E>) => mapImpl(asyncResult, mapFn);
+    }
+  }
+}
+
+const mapImpl = async <S, S2, E>(
+  asyncResult: AsyncResult<S, E>,
+  mapFn: (value: S) => Promise<S2> | S2,
+): AsyncResult<S2, E> => {
+  const result = await asyncResult;
+
+  return Result.isErr(result) ? result : Result.ok(await mapFn(result.value));
+};