unthrown 5.1.0 → 5.3.0

package/dist/index.cjs

@@ -538,7 +538,11 @@ function defectRes(cause) {
 *   // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
 *   // so the `P._` escape hatch is the only arm that can terminate the match:
 *   // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
-*   x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
+*   x.match({
+*     ok: () => 1,
+*     errCases: (m) => m.with(P._, () => 0),
+*     defect: () => -1,
+*   });
 * ```
 *
 * @category Guards
@@ -1284,6 +1288,72 @@ function fromPromise(promise, qualify, ..._guard) {
 function fromSafePromise(promise) {
 	return new AsyncRes((typeof promise === "function" ? Promise.resolve().then(promise) : Promise.resolve(promise)).then((value) => okRes(value), (cause) => defectRes(cause)));
 }
+/**
+* Build an {@link AsyncResult} from a callback-style API — this library's
+* answer to `new Promise((resolve, reject) => …)`.
+*
+* @remarks
+* The settler takes a **`Result`**, not a value-or-reason pair: the caller names
+* the variant, so no `unknown` can enter `E` and there is no `qualify` to pass.
+* For a failure that is *not* modeled, settle the injected `defect` helper's
+* marker — the same injection `qualify` receives, and the only way to reach the
+* defect channel from inside an asynchronous callback (a `throw` there runs in
+* its own turn, long after the executor body returned).
+*
+* `T` and `E` cannot be inferred from the body, since `settle` is a parameter.
+* Supply them explicitly, or let them flow from an annotated target. Absent
+* either, both default to `never` (Thesis #3: no path may produce `unknown` in
+* `E`) — so an unannotated call is a compile error at the `settle(...)` call
+* site, not a silently-`unknown` channel.
+*
+* An executor that never settles yields an `AsyncResult` that never resolves —
+* the one hazard {@link fromPromise} does not have, and identical to
+* `new Promise`.
+*
+* @typeParam T - the success type.
+* @typeParam E - the modeled error type.
+* @param executor - runs immediately; receives the settler and the `defect` helper.
+*
+* @category Interop
+*
+* @example
+* ```ts
+* import { fromExecutor, Err, Ok } from "unthrown";
+*
+* const listen = (port: number) =>
+*   fromExecutor<Server, PortInUse>((settle, defect) => {
+*     server.once("error", (cause) =>
+*       isAddrInUse(cause) ? settle(Err(new PortInUse(port))) : settle(defect(cause)),
+*     );
+*     server.listen(port, () => settle(Ok(server)));
+*   });
+* ```
+*/
+function fromExecutor(executor) {
+	let resolve;
+	const promise = new Promise((r) => {
+		resolve = r;
+	});
+	const settle = (result) => {
+		if (isDefectMarker(result)) {
+			resolve(defectRes(result.cause));
+			return;
+		}
+		if (!isResult(result)) {
+			if (isThenable(result)) Promise.resolve(result).then(void 0, () => void 0);
+			resolve(defectRes(/* @__PURE__ */ new TypeError("unthrown: fromExecutor's settle received a non-Result value")));
+			return;
+		}
+		resolve(result);
+	};
+	try {
+		const returned = executor(settle, defect);
+		if (isThenable(returned)) Promise.resolve(returned).then(void 0, (cause) => settle(defect(cause)));
+	} catch (cause) {
+		settle(defect(cause));
+	}
+	return new AsyncRes(promise);
+}
 function qualifyToResult(cause, qualify) {
 	try {
 		const q = qualify(cause, defect);
@@ -1452,7 +1522,10 @@ function allFromDict(results) {
 * ```ts
 * import { allAsync, fromSafePromise } from "unthrown";
 *
-* const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+* const both = allAsync([
+*   fromSafePromise(Promise.resolve(1)),
+*   fromSafePromise(Promise.resolve(2)),
+* ]);
 * (await both).get(); // => [1, 2]
 * ```
 */
@@ -1535,14 +1608,15 @@ const Result = {
 /**
 * Companion object grouping the **`AsyncResult`-producing** entry points under
 * the matching namespace: {@link AsyncResult.Ok}, {@link AsyncResult.Err},
-* {@link AsyncResult.Do}, {@link AsyncResult.fromPromise},
-* {@link AsyncResult.fromSafePromise}, {@link AsyncResult.all},
-* {@link AsyncResult.allFromDict}.
+* {@link AsyncResult.Do}, {@link AsyncResult.fromExecutor},
+* {@link AsyncResult.fromPromise}, {@link AsyncResult.fromSafePromise},
+* {@link AsyncResult.all}, {@link AsyncResult.allFromDict}.
 *
 * @remarks
 * The async sibling of {@link Result}. Statics are grouped by what they
-* **return**, so the pre-lifted constructors, `fromPromise`/`fromSafePromise`,
-* and the async aggregates sit here rather than on {@link Result}; the namespace
+* **return**, so the pre-lifted constructors, `fromExecutor`,
+* `fromPromise`/`fromSafePromise`, and the async aggregates sit here rather
+* than on {@link Result}; the namespace
 * already conveys "async", so the members drop the `Async` suffix their free
 * functions carry (`AsyncResult.Ok` is `OkAsync`; `AsyncResult.Err` is
 * `ErrAsync`; `AsyncResult.Do` is `DoAsync`; `AsyncResult.all` is `allAsync`;
@@ -1556,7 +1630,10 @@ const Result = {
 * @example
 * ```ts
 * import { AsyncResult } from "unthrown";
-* const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+* const user = await AsyncResult.fromPromise(
+*   fetchUser(id),
+*   (c, defect) => defect(c),
+* );
 * user.get(); // => the fetched user (on success)
 * ```
 */
@@ -1564,6 +1641,7 @@ const AsyncResult = {
 	Ok: OkAsync,
 	Err: ErrAsync,
 	Do: DoAsync,
+	fromExecutor,
 	fromPromise,
 	fromSafePromise,
 	all: allAsync,
@@ -1676,6 +1754,7 @@ exports.all = all;
 exports.allAsync = allAsync;
 exports.allFromDict = allFromDict;
 exports.allFromDictAsync = allFromDictAsync;
+exports.fromExecutor = fromExecutor;
 exports.fromNullable = fromNullable;
 exports.fromPromise = fromPromise;
 exports.fromSafePromise = fromSafePromise;

package/dist/index.d.cts

@@ -766,12 +766,20 @@ type ResultMethods<out T, out E> = {
    *
    * @remarks
    * A deliberate escape hatch off the errors-as-values model — it **throws the
-   * `Err` value as-is** at the call site. Its purpose is to move a literal
-   * `throw` behind a method, so a `no-throw` lint rule can ban raw throws while
-   * this one sanctioned extraction remains — _not_ to replace principled
-   * handling. When you can keep the error a value, prefer
-   * {@link ResultMethods.match | match} / {@link ResultMethods.recoverErrCases | recoverErrCases} /
-   * {@link ResultMethods.flatMapErrCases | flatMapErrCases}.
+   * `Err` value as-is** at the call site, so a caller of the enclosing function
+   * sees a throw rather than a channel. Its home is **tests and scripts**,
+   * where "this `Result` had better be `Ok`" is the assertion and a throw is
+   * the correct failure mode.
+   *
+   * In production code, fold the error channel instead:
+   * {@link ResultMethods.recoverErrCases | recoverErrCases} empties `E`, so
+   * {@link ResultMethods.get | get} compiles and a case routed to the injected
+   * `defect(...)` panics with its original cause — with every case still named.
+   * {@link ResultMethods.match | match} and
+   * {@link ResultMethods.flatMapErrCases | flatMapErrCases} are the other two
+   * ways to keep the error a value. `@unthrown/oxlint`'s opt-in
+   * `no-get-or-throw` rule enforces this, exempting test files through an
+   * oxlint `overrides` entry.
    *
    * Type-gated as the **complement** of {@link ResultMethods.get | get}: it
    * compiles only when the error channel is **non-empty** (`E` is not `never`) —
@@ -1450,7 +1458,11 @@ declare class GetError<E = unknown> extends Error {
  *   // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
  *   // so the `P._` escape hatch is the only arm that can terminate the match:
  *   // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
- *   x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
+ *   x.match({
+ *     ok: () => 1,
+ *     errCases: (m) => m.with(P._, () => 0),
+ *     defect: () => -1,
+ *   });
  * ```
  *
  * @category Guards
@@ -1708,6 +1720,59 @@ declare function fromPromise<T, R>(promise: Promise<T> | (() => Promise<T>), qua
  * ```
  */
 declare function fromSafePromise<T>(promise: Promise<T> | (() => Promise<T>)): AsyncResult$1<T, never>;
+/**
+ * The settler a {@link fromExecutor} executor receives. Settles the pending
+ * `AsyncResult` **once** — later calls are no-ops, exactly as `resolve` is on a
+ * `Promise`.
+ *
+ * @typeParam T - the success type.
+ * @typeParam E - the modeled error type.
+ *
+ * @category Types
+ */
+type Settle<T, E> = (result: Result$1<T, E> | Defect) => void;
+/**
+ * Build an {@link AsyncResult} from a callback-style API — this library's
+ * answer to `new Promise((resolve, reject) => …)`.
+ *
+ * @remarks
+ * The settler takes a **`Result`**, not a value-or-reason pair: the caller names
+ * the variant, so no `unknown` can enter `E` and there is no `qualify` to pass.
+ * For a failure that is *not* modeled, settle the injected `defect` helper's
+ * marker — the same injection `qualify` receives, and the only way to reach the
+ * defect channel from inside an asynchronous callback (a `throw` there runs in
+ * its own turn, long after the executor body returned).
+ *
+ * `T` and `E` cannot be inferred from the body, since `settle` is a parameter.
+ * Supply them explicitly, or let them flow from an annotated target. Absent
+ * either, both default to `never` (Thesis #3: no path may produce `unknown` in
+ * `E`) — so an unannotated call is a compile error at the `settle(...)` call
+ * site, not a silently-`unknown` channel.
+ *
+ * An executor that never settles yields an `AsyncResult` that never resolves —
+ * the one hazard {@link fromPromise} does not have, and identical to
+ * `new Promise`.
+ *
+ * @typeParam T - the success type.
+ * @typeParam E - the modeled error type.
+ * @param executor - runs immediately; receives the settler and the `defect` helper.
+ *
+ * @category Interop
+ *
+ * @example
+ * ```ts
+ * import { fromExecutor, Err, Ok } from "unthrown";
+ *
+ * const listen = (port: number) =>
+ *   fromExecutor<Server, PortInUse>((settle, defect) => {
+ *     server.once("error", (cause) =>
+ *       isAddrInUse(cause) ? settle(Err(new PortInUse(port))) : settle(defect(cause)),
+ *     );
+ *     server.listen(port, () => settle(Ok(server)));
+ *   });
+ * ```
+ */
+declare function fromExecutor<T = never, E = never>(executor: (settle: Settle<T, E>, defect: (cause: unknown) => Defect) => void): AsyncResult$1<T, E>;
 /**
  * The success channel of {@link all} / {@link allAsync}: a **positional tuple**
  * for a fixed-length input (including the empty tuple), or a homogeneous
@@ -1790,7 +1855,10 @@ declare function allFromDict<R extends ResultRecord>(results: R): Result$1<{ [K
  * ```ts
  * import { allAsync, fromSafePromise } from "unthrown";
  *
- * const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+ * const both = allAsync([
+ *   fromSafePromise(Promise.resolve(1)),
+ *   fromSafePromise(Promise.resolve(2)),
+ * ]);
  * (await both).get(); // => [1, 2]
  * ```
  */
@@ -1877,14 +1945,15 @@ type Result<T, E> = Result$1<T, E>;
 /**
  * Companion object grouping the **`AsyncResult`-producing** entry points under
  * the matching namespace: {@link AsyncResult.Ok}, {@link AsyncResult.Err},
- * {@link AsyncResult.Do}, {@link AsyncResult.fromPromise},
- * {@link AsyncResult.fromSafePromise}, {@link AsyncResult.all},
- * {@link AsyncResult.allFromDict}.
+ * {@link AsyncResult.Do}, {@link AsyncResult.fromExecutor},
+ * {@link AsyncResult.fromPromise}, {@link AsyncResult.fromSafePromise},
+ * {@link AsyncResult.all}, {@link AsyncResult.allFromDict}.
  *
  * @remarks
  * The async sibling of {@link Result}. Statics are grouped by what they
- * **return**, so the pre-lifted constructors, `fromPromise`/`fromSafePromise`,
- * and the async aggregates sit here rather than on {@link Result}; the namespace
+ * **return**, so the pre-lifted constructors, `fromExecutor`,
+ * `fromPromise`/`fromSafePromise`, and the async aggregates sit here rather
+ * than on {@link Result}; the namespace
  * already conveys "async", so the members drop the `Async` suffix their free
  * functions carry (`AsyncResult.Ok` is `OkAsync`; `AsyncResult.Err` is
  * `ErrAsync`; `AsyncResult.Do` is `DoAsync`; `AsyncResult.all` is `allAsync`;
@@ -1898,7 +1967,10 @@ type Result<T, E> = Result$1<T, E>;
  * @example
  * ```ts
  * import { AsyncResult } from "unthrown";
- * const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+ * const user = await AsyncResult.fromPromise(
+ *   fetchUser(id),
+ *   (c, defect) => defect(c),
+ * );
  * user.get(); // => the fetched user (on success)
  * ```
  */
@@ -1906,6 +1978,7 @@ declare const AsyncResult: {
   readonly Ok: typeof OkAsync;
   readonly Err: typeof ErrAsync;
   readonly Do: typeof DoAsync;
+  readonly fromExecutor: typeof fromExecutor;
   readonly fromPromise: typeof fromPromise;
   readonly fromSafePromise: typeof fromSafePromise;
   readonly all: typeof allAsync;
@@ -2034,4 +2107,4 @@ declare function TaggedError<Tag extends string>(tag: Tag, options?: {
   readonly name?: string;
 }): TaggedErrorConstructor<Tag>;
 //#endregion
-export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, DoAsync, Err, ErrAsync, type ErrMatcher, type ErrOf, type ErrView, type FailureView, GetError, type Matcher, NonExhaustiveError, type NotThenable, Ok, OkAsync, type OkOf, type OkView, P, type PatternMatcher, Result, type ResultMethods, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, type UniversalPattern, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match };
+export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, DoAsync, Err, ErrAsync, type ErrMatcher, type ErrOf, type ErrView, type FailureView, GetError, type Matcher, NonExhaustiveError, type NotThenable, Ok, OkAsync, type OkOf, type OkView, P, type PatternMatcher, Result, type ResultMethods, type Settle, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, type UniversalPattern, all, allAsync, allFromDict, allFromDictAsync, fromExecutor, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match };

package/dist/index.d.mts

@@ -766,12 +766,20 @@ type ResultMethods<out T, out E> = {
    *
    * @remarks
    * A deliberate escape hatch off the errors-as-values model — it **throws the
-   * `Err` value as-is** at the call site. Its purpose is to move a literal
-   * `throw` behind a method, so a `no-throw` lint rule can ban raw throws while
-   * this one sanctioned extraction remains — _not_ to replace principled
-   * handling. When you can keep the error a value, prefer
-   * {@link ResultMethods.match | match} / {@link ResultMethods.recoverErrCases | recoverErrCases} /
-   * {@link ResultMethods.flatMapErrCases | flatMapErrCases}.
+   * `Err` value as-is** at the call site, so a caller of the enclosing function
+   * sees a throw rather than a channel. Its home is **tests and scripts**,
+   * where "this `Result` had better be `Ok`" is the assertion and a throw is
+   * the correct failure mode.
+   *
+   * In production code, fold the error channel instead:
+   * {@link ResultMethods.recoverErrCases | recoverErrCases} empties `E`, so
+   * {@link ResultMethods.get | get} compiles and a case routed to the injected
+   * `defect(...)` panics with its original cause — with every case still named.
+   * {@link ResultMethods.match | match} and
+   * {@link ResultMethods.flatMapErrCases | flatMapErrCases} are the other two
+   * ways to keep the error a value. `@unthrown/oxlint`'s opt-in
+   * `no-get-or-throw` rule enforces this, exempting test files through an
+   * oxlint `overrides` entry.
    *
    * Type-gated as the **complement** of {@link ResultMethods.get | get}: it
    * compiles only when the error channel is **non-empty** (`E` is not `never`) —
@@ -1450,7 +1458,11 @@ declare class GetError<E = unknown> extends Error {
  *   // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
  *   // so the `P._` escape hatch is the only arm that can terminate the match:
  *   // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
- *   x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
+ *   x.match({
+ *     ok: () => 1,
+ *     errCases: (m) => m.with(P._, () => 0),
+ *     defect: () => -1,
+ *   });
  * ```
  *
  * @category Guards
@@ -1708,6 +1720,59 @@ declare function fromPromise<T, R>(promise: Promise<T> | (() => Promise<T>), qua
  * ```
  */
 declare function fromSafePromise<T>(promise: Promise<T> | (() => Promise<T>)): AsyncResult$1<T, never>;
+/**
+ * The settler a {@link fromExecutor} executor receives. Settles the pending
+ * `AsyncResult` **once** — later calls are no-ops, exactly as `resolve` is on a
+ * `Promise`.
+ *
+ * @typeParam T - the success type.
+ * @typeParam E - the modeled error type.
+ *
+ * @category Types
+ */
+type Settle<T, E> = (result: Result$1<T, E> | Defect) => void;
+/**
+ * Build an {@link AsyncResult} from a callback-style API — this library's
+ * answer to `new Promise((resolve, reject) => …)`.
+ *
+ * @remarks
+ * The settler takes a **`Result`**, not a value-or-reason pair: the caller names
+ * the variant, so no `unknown` can enter `E` and there is no `qualify` to pass.
+ * For a failure that is *not* modeled, settle the injected `defect` helper's
+ * marker — the same injection `qualify` receives, and the only way to reach the
+ * defect channel from inside an asynchronous callback (a `throw` there runs in
+ * its own turn, long after the executor body returned).
+ *
+ * `T` and `E` cannot be inferred from the body, since `settle` is a parameter.
+ * Supply them explicitly, or let them flow from an annotated target. Absent
+ * either, both default to `never` (Thesis #3: no path may produce `unknown` in
+ * `E`) — so an unannotated call is a compile error at the `settle(...)` call
+ * site, not a silently-`unknown` channel.
+ *
+ * An executor that never settles yields an `AsyncResult` that never resolves —
+ * the one hazard {@link fromPromise} does not have, and identical to
+ * `new Promise`.
+ *
+ * @typeParam T - the success type.
+ * @typeParam E - the modeled error type.
+ * @param executor - runs immediately; receives the settler and the `defect` helper.
+ *
+ * @category Interop
+ *
+ * @example
+ * ```ts
+ * import { fromExecutor, Err, Ok } from "unthrown";
+ *
+ * const listen = (port: number) =>
+ *   fromExecutor<Server, PortInUse>((settle, defect) => {
+ *     server.once("error", (cause) =>
+ *       isAddrInUse(cause) ? settle(Err(new PortInUse(port))) : settle(defect(cause)),
+ *     );
+ *     server.listen(port, () => settle(Ok(server)));
+ *   });
+ * ```
+ */
+declare function fromExecutor<T = never, E = never>(executor: (settle: Settle<T, E>, defect: (cause: unknown) => Defect) => void): AsyncResult$1<T, E>;
 /**
  * The success channel of {@link all} / {@link allAsync}: a **positional tuple**
  * for a fixed-length input (including the empty tuple), or a homogeneous
@@ -1790,7 +1855,10 @@ declare function allFromDict<R extends ResultRecord>(results: R): Result$1<{ [K
  * ```ts
  * import { allAsync, fromSafePromise } from "unthrown";
  *
- * const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+ * const both = allAsync([
+ *   fromSafePromise(Promise.resolve(1)),
+ *   fromSafePromise(Promise.resolve(2)),
+ * ]);
  * (await both).get(); // => [1, 2]
  * ```
  */
@@ -1877,14 +1945,15 @@ type Result<T, E> = Result$1<T, E>;
 /**
  * Companion object grouping the **`AsyncResult`-producing** entry points under
  * the matching namespace: {@link AsyncResult.Ok}, {@link AsyncResult.Err},
- * {@link AsyncResult.Do}, {@link AsyncResult.fromPromise},
- * {@link AsyncResult.fromSafePromise}, {@link AsyncResult.all},
- * {@link AsyncResult.allFromDict}.
+ * {@link AsyncResult.Do}, {@link AsyncResult.fromExecutor},
+ * {@link AsyncResult.fromPromise}, {@link AsyncResult.fromSafePromise},
+ * {@link AsyncResult.all}, {@link AsyncResult.allFromDict}.
  *
  * @remarks
  * The async sibling of {@link Result}. Statics are grouped by what they
- * **return**, so the pre-lifted constructors, `fromPromise`/`fromSafePromise`,
- * and the async aggregates sit here rather than on {@link Result}; the namespace
+ * **return**, so the pre-lifted constructors, `fromExecutor`,
+ * `fromPromise`/`fromSafePromise`, and the async aggregates sit here rather
+ * than on {@link Result}; the namespace
  * already conveys "async", so the members drop the `Async` suffix their free
  * functions carry (`AsyncResult.Ok` is `OkAsync`; `AsyncResult.Err` is
  * `ErrAsync`; `AsyncResult.Do` is `DoAsync`; `AsyncResult.all` is `allAsync`;
@@ -1898,7 +1967,10 @@ type Result<T, E> = Result$1<T, E>;
  * @example
  * ```ts
  * import { AsyncResult } from "unthrown";
- * const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+ * const user = await AsyncResult.fromPromise(
+ *   fetchUser(id),
+ *   (c, defect) => defect(c),
+ * );
  * user.get(); // => the fetched user (on success)
  * ```
  */
@@ -1906,6 +1978,7 @@ declare const AsyncResult: {
   readonly Ok: typeof OkAsync;
   readonly Err: typeof ErrAsync;
   readonly Do: typeof DoAsync;
+  readonly fromExecutor: typeof fromExecutor;
   readonly fromPromise: typeof fromPromise;
   readonly fromSafePromise: typeof fromSafePromise;
   readonly all: typeof allAsync;
@@ -2034,4 +2107,4 @@ declare function TaggedError<Tag extends string>(tag: Tag, options?: {
   readonly name?: string;
 }): TaggedErrorConstructor<Tag>;
 //#endregion
-export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, DoAsync, Err, ErrAsync, type ErrMatcher, type ErrOf, type ErrView, type FailureView, GetError, type Matcher, NonExhaustiveError, type NotThenable, Ok, OkAsync, type OkOf, type OkView, P, type PatternMatcher, Result, type ResultMethods, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, type UniversalPattern, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match };
+export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, DoAsync, Err, ErrAsync, type ErrMatcher, type ErrOf, type ErrView, type FailureView, GetError, type Matcher, NonExhaustiveError, type NotThenable, Ok, OkAsync, type OkOf, type OkView, P, type PatternMatcher, Result, type ResultMethods, type Settle, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, type UniversalPattern, all, allAsync, allFromDict, allFromDictAsync, fromExecutor, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match };

package/dist/index.mjs

@@ -537,7 +537,11 @@ function defectRes(cause) {
 *   // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
 *   // so the `P._` escape hatch is the only arm that can terminate the match:
 *   // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
-*   x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
+*   x.match({
+*     ok: () => 1,
+*     errCases: (m) => m.with(P._, () => 0),
+*     defect: () => -1,
+*   });
 * ```
 *
 * @category Guards
@@ -1283,6 +1287,72 @@ function fromPromise(promise, qualify, ..._guard) {
 function fromSafePromise(promise) {
 	return new AsyncRes((typeof promise === "function" ? Promise.resolve().then(promise) : Promise.resolve(promise)).then((value) => okRes(value), (cause) => defectRes(cause)));
 }
+/**
+* Build an {@link AsyncResult} from a callback-style API — this library's
+* answer to `new Promise((resolve, reject) => …)`.
+*
+* @remarks
+* The settler takes a **`Result`**, not a value-or-reason pair: the caller names
+* the variant, so no `unknown` can enter `E` and there is no `qualify` to pass.
+* For a failure that is *not* modeled, settle the injected `defect` helper's
+* marker — the same injection `qualify` receives, and the only way to reach the
+* defect channel from inside an asynchronous callback (a `throw` there runs in
+* its own turn, long after the executor body returned).
+*
+* `T` and `E` cannot be inferred from the body, since `settle` is a parameter.
+* Supply them explicitly, or let them flow from an annotated target. Absent
+* either, both default to `never` (Thesis #3: no path may produce `unknown` in
+* `E`) — so an unannotated call is a compile error at the `settle(...)` call
+* site, not a silently-`unknown` channel.
+*
+* An executor that never settles yields an `AsyncResult` that never resolves —
+* the one hazard {@link fromPromise} does not have, and identical to
+* `new Promise`.
+*
+* @typeParam T - the success type.
+* @typeParam E - the modeled error type.
+* @param executor - runs immediately; receives the settler and the `defect` helper.
+*
+* @category Interop
+*
+* @example
+* ```ts
+* import { fromExecutor, Err, Ok } from "unthrown";
+*
+* const listen = (port: number) =>
+*   fromExecutor<Server, PortInUse>((settle, defect) => {
+*     server.once("error", (cause) =>
+*       isAddrInUse(cause) ? settle(Err(new PortInUse(port))) : settle(defect(cause)),
+*     );
+*     server.listen(port, () => settle(Ok(server)));
+*   });
+* ```
+*/
+function fromExecutor(executor) {
+	let resolve;
+	const promise = new Promise((r) => {
+		resolve = r;
+	});
+	const settle = (result) => {
+		if (isDefectMarker(result)) {
+			resolve(defectRes(result.cause));
+			return;
+		}
+		if (!isResult(result)) {
+			if (isThenable(result)) Promise.resolve(result).then(void 0, () => void 0);
+			resolve(defectRes(/* @__PURE__ */ new TypeError("unthrown: fromExecutor's settle received a non-Result value")));
+			return;
+		}
+		resolve(result);
+	};
+	try {
+		const returned = executor(settle, defect);
+		if (isThenable(returned)) Promise.resolve(returned).then(void 0, (cause) => settle(defect(cause)));
+	} catch (cause) {
+		settle(defect(cause));
+	}
+	return new AsyncRes(promise);
+}
 function qualifyToResult(cause, qualify) {
 	try {
 		const q = qualify(cause, defect);
@@ -1451,7 +1521,10 @@ function allFromDict(results) {
 * ```ts
 * import { allAsync, fromSafePromise } from "unthrown";
 *
-* const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+* const both = allAsync([
+*   fromSafePromise(Promise.resolve(1)),
+*   fromSafePromise(Promise.resolve(2)),
+* ]);
 * (await both).get(); // => [1, 2]
 * ```
 */
@@ -1534,14 +1607,15 @@ const Result = {
 /**
 * Companion object grouping the **`AsyncResult`-producing** entry points under
 * the matching namespace: {@link AsyncResult.Ok}, {@link AsyncResult.Err},
-* {@link AsyncResult.Do}, {@link AsyncResult.fromPromise},
-* {@link AsyncResult.fromSafePromise}, {@link AsyncResult.all},
-* {@link AsyncResult.allFromDict}.
+* {@link AsyncResult.Do}, {@link AsyncResult.fromExecutor},
+* {@link AsyncResult.fromPromise}, {@link AsyncResult.fromSafePromise},
+* {@link AsyncResult.all}, {@link AsyncResult.allFromDict}.
 *
 * @remarks
 * The async sibling of {@link Result}. Statics are grouped by what they
-* **return**, so the pre-lifted constructors, `fromPromise`/`fromSafePromise`,
-* and the async aggregates sit here rather than on {@link Result}; the namespace
+* **return**, so the pre-lifted constructors, `fromExecutor`,
+* `fromPromise`/`fromSafePromise`, and the async aggregates sit here rather
+* than on {@link Result}; the namespace
 * already conveys "async", so the members drop the `Async` suffix their free
 * functions carry (`AsyncResult.Ok` is `OkAsync`; `AsyncResult.Err` is
 * `ErrAsync`; `AsyncResult.Do` is `DoAsync`; `AsyncResult.all` is `allAsync`;
@@ -1555,7 +1629,10 @@ const Result = {
 * @example
 * ```ts
 * import { AsyncResult } from "unthrown";
-* const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+* const user = await AsyncResult.fromPromise(
+*   fetchUser(id),
+*   (c, defect) => defect(c),
+* );
 * user.get(); // => the fetched user (on success)
 * ```
 */
@@ -1563,6 +1640,7 @@ const AsyncResult = {
 	Ok: OkAsync,
 	Err: ErrAsync,
 	Do: DoAsync,
+	fromExecutor,
 	fromPromise,
 	fromSafePromise,
 	all: allAsync,
@@ -1659,4 +1737,4 @@ function TaggedError(tag, options) {
 	return TaggedErrorBase;
 }
 //#endregion
-export { AsyncResult, Do, DoAsync, Err, ErrAsync, GetError, NonExhaustiveError, Ok, OkAsync, P, Result, TaggedError, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match };
+export { AsyncResult, Do, DoAsync, Err, ErrAsync, GetError, NonExhaustiveError, Ok, OkAsync, P, Result, TaggedError, all, allAsync, allFromDict, allFromDictAsync, fromExecutor, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unthrown",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "description": "Explicit errors as values, with a separate defect (panic) channel",
   "keywords": [
     "defect",
@@ -47,13 +47,10 @@
   },
   "devDependencies": {
     "@btravstack/tsconfig": "0.2.0",
-    "@btravstack/typedoc": "0.1.0",
-    "@types/node": "26.1.1",
+    "@types/node": "26.1.2",
     "@vitest/coverage-v8": "4.1.10",
-    "tsdown": "0.22.12",
-    "typedoc": "0.28.20",
-    "typedoc-plugin-markdown": "4.12.0",
-    "typescript": "6.0.3",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
     "vitest": "4.1.10"
   },
   "engines": {
@@ -61,7 +58,6 @@
   },
   "scripts": {
     "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
-    "build:docs": "typedoc",
     "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
     "test:types": "tsc --noEmit -p tsconfig.test-d.json",