unthrown 5.2.0 → 5.3.0

package/dist/index.cjs

@@ -1288,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);
@@ -1542,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`;
@@ -1574,6 +1641,7 @@ const AsyncResult = {
 	Ok: OkAsync,
 	Err: ErrAsync,
 	Do: DoAsync,
+	fromExecutor,
 	fromPromise,
 	fromSafePromise,
 	all: allAsync,
@@ -1686,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

@@ -1720,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
@@ -1892,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`;
@@ -1924,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;
@@ -2052,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

@@ -1720,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
@@ -1892,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`;
@@ -1924,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;
@@ -2052,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

@@ -1287,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);
@@ -1541,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`;
@@ -1573,6 +1640,7 @@ const AsyncResult = {
 	Ok: OkAsync,
 	Err: ErrAsync,
 	Do: DoAsync,
+	fromExecutor,
 	fromPromise,
 	fromSafePromise,
 	all: allAsync,
@@ -1669,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.2.0",
+  "version": "5.3.0",
   "description": "Explicit errors as values, with a separate defect (panic) channel",
   "keywords": [
     "defect",