@fgv/ts-utils 5.1.0-4 → 5.1.0-40

package/lib/packlets/base/result.js

@@ -21,7 +21,7 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DetailedFailure = exports.DetailedSuccess = exports.Failure = exports.Success = void 0;
+exports.AsyncResult = exports.DetailedFailure = exports.DetailedSuccess = exports.Failure = exports.Success = exports.allMessageLogLevels = void 0;
 exports.isDeferredResult = isDeferredResult;
 exports.succeed = succeed;
 exports.succeeds = succeeds;
@@ -33,7 +33,10 @@ exports.succeedsWithDetail = succeedsWithDetail;
 exports.failWithDetail = failWithDetail;
 exports.failsWithDetail = failsWithDetail;
 exports.propagateWithDetail = propagateWithDetail;
+exports._errorMessage = _errorMessage;
 exports.captureResult = captureResult;
+exports.captureAsyncResult = captureAsyncResult;
+const shouldNotFail_1 = require("./shouldNotFail");
 /**
  * Checks if a result is a deferred result.
  * @param result - The result to check.
@@ -43,6 +46,17 @@ exports.captureResult = captureResult;
 function isDeferredResult(result) {
     return typeof result === 'function';
 }
+// Untyped (literal-tuple-inferred) source of truth for allMessageLogLevels, kept separate from the
+// widened public export below so the exhaustiveness check actually inspects the literal values instead
+// of being widened away to `MessageLogLevel` before the check runs.
+const messageLogLevelValues = ['quiet', 'detail', 'info', 'warning', 'error'];
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _messageLogLevelExhaustivenessCheck = true;
+/**
+ * Exhaustive list of all {@link MessageLogLevel} values.
+ * @public
+ */
+exports.allMessageLogLevels = messageLogLevelValues;
 /**
  * Reports a successful {@link IResult | result} from some operation and the
  * corresponding value.
@@ -85,6 +99,12 @@ class Success {
     orThrow(__logger) {
         return this._value;
     }
+    /**
+     * {@inheritDoc IResult.shouldNotFail}
+     */
+    shouldNotFail(__label, __frameDepth) {
+        return this._value;
+    }
     orDefault(dflt) {
         var _a;
         return (_a = this._value) !== null && _a !== void 0 ? _a : dflt;
@@ -116,6 +136,26 @@ class Success {
     onFailure(__) {
         return this;
     }
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess(cb) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return new AsyncResult(cb(this._value));
+        }
+        catch (err) {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return AsyncResult.from(fail(_errorMessage(err)));
+        }
+    }
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(__) {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        return AsyncResult.from(this);
+    }
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -210,6 +250,32 @@ class Failure {
         }
         throw new Error(this._message);
     }
+    /**
+     * {@inheritDoc IResult.shouldNotFail}
+     */
+    shouldNotFail(label, frameDepth = 1) {
+        // Parse a probe Error's stack to identify the caller frame for message
+        // composition. We must NOT reuse this probe as the thrown Error: in V8,
+        // `.stack` is materialized lazily on first access (which happens below in
+        // `_findShouldNotFailFrame`), and once materialized the cached stack
+        // header carries whatever message was set at that moment. Mutating
+        // `.message` afterwards does not refresh the cached `.stack` header.
+        const probe = new Error();
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(probe, this.shouldNotFail);
+        }
+        const frame = (0, shouldNotFail_1._findShouldNotFailFrame)(probe.stack, frameDepth);
+        const message = (0, shouldNotFail_1._formatShouldNotFailMessage)(this._message, label, frame);
+        // Build the final Error with the formatted message and re-elide
+        // `shouldNotFail` from its stack, so the thrown error's `.stack` shows
+        // both the formatted message in its header and the caller as its top
+        // frame.
+        const err = new Error(message);
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(err, this.shouldNotFail);
+        }
+        throw err;
+    }
     orDefault(dflt) {
         return dflt;
     }
@@ -242,6 +308,26 @@ class Failure {
     onFailure(cb) {
         return cb(this._message);
     }
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess(__) {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        return AsyncResult.from(fail(this._message));
+    }
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(cb) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return new AsyncResult(cb(this._message));
+        }
+        catch (err) {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return AsyncResult.from(fail(_errorMessage(err)));
+        }
+    }
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -279,6 +365,45 @@ class Failure {
         reporter === null || reporter === void 0 ? void 0 : reporter.reportFailure(level, message);
         return this;
     }
+    /**
+     * Re-types this {@link Failure | Failure<T>} as {@link Failure | Failure<U>} for
+     * propagation under a different success type.
+     * @remarks
+     * Supports the canonical Result early-return-after-`isFailure()` pattern when the
+     * outer function's success type differs from the inner Result's success type:
+     *
+     * ```ts
+     * const storeResult = await PromptStoreFixture.build(seed);
+     * if (storeResult.isFailure()) {
+     *   return storeResult.withType<PromptLibrary>();
+     * }
+     * return PromptLibrary.create({ store: storeResult.value, ... });
+     * ```
+     *
+     * Without this helper, TypeScript rejects `return storeResult` because
+     * `Failure<IPromptStore>` is invariant in `T` and not assignable to
+     * `Result<PromptLibrary>`. The workaround `return fail<U>(r.message)` is
+     * semantically equivalent but allocates a new {@link Failure} instance;
+     * `withType` returns `this` and only retypes statically.
+     *
+     * This method is sound because a {@link Failure} variant carries no `T`-shaped
+     * data — only an error message — so re-typing it as `Failure<U>` cannot
+     * misrepresent any value. The same operation is NOT exposed on {@link Success}
+     * because `Success<T>` carries `T`-shaped data and re-typing would be a lie.
+     *
+     * For `DetailedResult` propagation that preserves a typed `detail`, consider
+     * propagating the {@link DetailedFailure} directly through `onSuccess` (which
+     * already re-types the success arm) rather than reaching for `withType`.
+     *
+     * @returns This same {@link Failure} instance, statically retyped as
+     * {@link Failure | Failure<U>}.
+     * @public
+     */
+    withType() {
+        // Safe by construction: Failure carries no T-shaped data, only a message.
+        // Re-typing the static T parameter cannot misrepresent any value.
+        return this;
+    }
     /**
      * Get a 'friendly' string representation of this object.
      * @remarks
@@ -610,13 +735,25 @@ function propagateWithDetail(result, detail, successDetail) {
         ? succeedWithDetail(result.value, successDetail !== null && successDetail !== void 0 ? successDetail : detail)
         : failWithDetail(result.message, detail);
 }
+/**
+ * Extracts a message string from an unknown thrown/rejected value.
+ * @param err - The caught error value.
+ * @returns The error message string.
+ * @internal
+ */
+function _errorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
 /**
  * Wraps a function which might throw to convert exception results
  * to {@link Failure}.
  * @param func - The function to be captured.
  * @returns Returns {@link Success} with a value of type `<T>` on
  * success , or {@link Failure} with the thrown error message if
- * `func` throws an `Error`.
+ * `func` throws an `Error` or string.
  * @public
  */
 function captureResult(func) {
@@ -624,7 +761,197 @@ function captureResult(func) {
         return succeed(func());
     }
     catch (err) {
-        return fail(err.message);
+        return fail(_errorMessage(err));
+    }
+}
+/**
+ * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both
+ * synchronous and asynchronous operations.
+ *
+ * @remarks
+ * `AsyncResult<T>` implements `PromiseLike` so it can be directly `await`ed.
+ * Use the `thenOnSuccess` and `thenOnFailure` methods on {@link Result} to bridge
+ * from synchronous to asynchronous result chains.
+ *
+ * @example
+ * ```typescript
+ * const result: Result<Final> = await parseInput(input)
+ *   .thenOnSuccess(async (parsed) => fetchData(parsed))
+ *   .onSuccess((data) => transform(data))
+ *   .thenOnSuccess(async (transformed) => saveData(transformed))
+ *   .withErrorFormat((msg) => `pipeline failed: ${msg}`);
+ * ```
+ *
+ * @public
+ */
+class AsyncResult {
+    /**
+     * Constructs an {@link AsyncResult} wrapping the supplied promise (or any
+     * `PromiseLike` that resolves to a {@link Result}, such as another
+     * {@link AsyncResult}).
+     * @remarks
+     * If the supplied promise rejects, the rejection is caught and converted
+     * to a {@link Failure}, ensuring that awaiting an {@link AsyncResult} always
+     * yields a {@link Result}.
+     * @param promise - A `Promise` (or `PromiseLike`) that resolves to a
+     * {@link Result}.
+     */
+    constructor(promise) {
+        this._promise = Promise.resolve(promise).catch((err) => fail(_errorMessage(err)));
+    }
+    /**
+     * Calls a supplied {@link SuccessContinuation | success continuation} if
+     * the wrapped result is successful.
+     * @param cb - The synchronous {@link SuccessContinuation | success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onSuccess(cb) {
+        return new AsyncResult(this._promise.then((r) => r.onSuccess(cb)));
+    }
+    /**
+     * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+     * the wrapped result is successful.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncSuccessContinuation | async success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnSuccess(cb) {
+        return new AsyncResult(this._promise.then(async (r) => {
+            if (r.isFailure()) {
+                return fail(r.message);
+            }
+            try {
+                return await cb(r.value);
+            }
+            catch (err) {
+                return fail(_errorMessage(err));
+            }
+        }));
+    }
+    /**
+     * Calls a supplied {@link FailureContinuation | failure continuation} if
+     * the wrapped result is a failure.
+     * @param cb - The synchronous {@link FailureContinuation | failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onFailure(cb) {
+        return new AsyncResult(this._promise.then((r) => r.onFailure(cb)));
+    }
+    /**
+     * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+     * the wrapped result is a failure.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncFailureContinuation | async failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnFailure(cb) {
+        return new AsyncResult(this._promise.then(async (r) => {
+            if (r.isSuccess()) {
+                return r;
+            }
+            try {
+                return await cb(r.message);
+            }
+            catch (err) {
+                return fail(_errorMessage(err));
+            }
+        }));
+    }
+    /**
+     * Calls a supplied {@link ErrorFormatter | error formatter} if
+     * the wrapped result is a failure.
+     * @param cb - The {@link ErrorFormatter | error formatter} to
+     * be called in the event of failure.
+     * @returns A new {@link AsyncResult} with the formatted error message,
+     * or the original success result.
+     */
+    withErrorFormat(cb) {
+        return new AsyncResult(this._promise.then((r) => r.withErrorFormat(cb)));
+    }
+    /**
+     * Propagates the wrapped result, appending any error message to the
+     * supplied errors aggregator.
+     * @param errors - {@link IMessageAggregator | Error aggregator} in which
+     * errors will be aggregated.
+     * @param formatter - An optional {@link ErrorFormatter | error formatter}
+     * to be used to format the error message.
+     * @returns A new {@link AsyncResult} wrapping the result after aggregation.
+     */
+    aggregateError(errors, formatter) {
+        return new AsyncResult(this._promise.then((r) => {
+            r.aggregateError(errors, formatter);
+            return r;
+        }));
+    }
+    /**
+     * Reports the wrapped result to the supplied reporter.
+     * @param reporter - The {@link IResultReporter | reporter} to which the result
+     * will be reported.
+     * @param options - The {@link IResultReportOptions | options} for reporting the result.
+     * @returns A new {@link AsyncResult} wrapping the result after reporting.
+     */
+    report(reporter, options) {
+        return new AsyncResult(this._promise.then((r) => {
+            r.report(reporter, options);
+            return r;
+        }));
+    }
+    /**
+     * Implementation of `PromiseLike.then` enabling `await` on {@link AsyncResult}.
+     * @param onfulfilled - Callback invoked when the promise resolves.
+     * @param onrejected - Callback invoked when the promise rejects.
+     * @returns A `Promise` resolving to the callback result.
+     */
+    /* eslint-disable @rushstack/no-new-null */
+    then(onfulfilled, onrejected) {
+        /* eslint-enable @rushstack/no-new-null */
+        return this._promise.then(onfulfilled, onrejected);
+    }
+    /**
+     * Creates an {@link AsyncResult} from a {@link Result}.
+     * @param result - The {@link Result} to wrap.
+     * @returns A new {@link AsyncResult} wrapping the supplied result.
+     */
+    static from(result) {
+        return new AsyncResult(Promise.resolve(result));
+    }
+}
+exports.AsyncResult = AsyncResult;
+/**
+ * Wraps an async function which might throw to convert exception results
+ * to {@link Failure}.
+ * @remarks
+ * Returns an {@link AsyncResult} so callers can fluently chain
+ * (`.onSuccess` / `.thenOnSuccess` / `.withErrorFormat`) directly off the
+ * captured result. Because {@link AsyncResult} implements
+ * `PromiseLike<Result<T>>`, existing `await captureAsyncResult(...)` call
+ * sites continue to work unchanged and yield the same {@link Result}.
+ *
+ * Synchronous throws from `func` (before it returns its `Promise`), promise
+ * rejections, and successful resolutions are all funneled through the
+ * returned {@link AsyncResult}, which resolves to a {@link Failure} for the
+ * throw/reject cases and a {@link Success} wrapping the resolved value
+ * otherwise.
+ * @param func - The async function to be captured.
+ * @returns An {@link AsyncResult} resolving to {@link Success} with a value
+ * of type `<T>` on success, or {@link Failure} with the thrown error message
+ * if `func` throws or rejects.
+ * @public
+ */
+function captureAsyncResult(func) {
+    try {
+        return new AsyncResult(func().then((value) => succeed(value)));
+    }
+    catch (err) {
+        return AsyncResult.from(fail(_errorMessage(err)));
     }
 }
 //# sourceMappingURL=result.js.map

package/lib/packlets/base/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../../src/packlets/base/result.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { _findShouldNotFailFrame, _formatShouldNotFailMessage } from './shouldNotFail';\n\n/**\n * Represents the {@link IResult | result} of some operation or sequence of operations.\n * @remarks\n * {@link Success | Success<T>} and {@link Failure | Failure<T>} share the common\n * contract {@link IResult}, enabling commingled discriminated usage.\n * @public\n */\nexport type Result<T> = Success<T> | Failure<T>;\n\n/**\n * Represents a deferred result that will be evaluated if needed.\n * @public\n */\nexport type DeferredResult<T> = () => Result<T>;\n\n/**\n * Checks if a result is a deferred result.\n * @param result - The result to check.\n * @returns `true` if the result is a deferred result, `false` otherwise.\n * @public\n */\nexport function isDeferredResult<T>(result: Result<T> | DeferredResult<T>): result is DeferredResult<T> {\n  return typeof result === 'function';\n}\n\n/**\n * Continuation callback to be called in the event that an\n * {@link Result} is successful.\n * @public\n */\nexport type SuccessContinuation<T, TN> = (value: T) => Result<TN>;\n\n/**\n * Continuation callback to be called in the event that an\n * {@link Result} fails.\n * @public\n */\nexport type FailureContinuation<T> = (message: string) => Result<T>;\n\n/**\n * Type inference to determine the result type of an {@link Result}.\n * @beta\n */\nexport type ResultValueType<T> = T extends Result<infer TV> ? TV : never;\n\n/**\n * Type inference to determine the result type of an {@link IResult}.\n * @beta\n */\nexport type IResultValueType<T> = T extends IResult<infer TV> ? TV : never;\n\n/**\n * Type inference to determine the value type returned from a result-map style\n * `get` method.\n * @remarks\n * Useful for extracting collection entry types from maps whose `get` method\n * returns an {@link IResult}.\n * @beta\n */\nexport type ResultMapValueType<TCollection extends { get: (...args: readonly unknown[]) => unknown }> =\n  Exclude<IResultValueType<ReturnType<TCollection['get']>>, undefined>;\n\n/**\n * Formats an error message.\n * @param message - The error message to be formatted.\n * @param detail - An optional detail to be included in the formatted message.\n * @public\n */\nexport type ErrorFormatter<TD = unknown> = (message: string, detail?: TD) => string;\n\n/**\n * Simple logger interface used by {@link IResult.orThrow | orThrow(logger)} and {@link IResult.orThrow | orThrow(formatter)}.\n * @public\n */\nexport interface IResultLogger<TD = unknown> {\n  /**\n   * Log an error message.\n   * @param message - The message to be logged.\n   */\n  error(message: string, detail?: TD): void;\n}\n\n/**\n * The severity level at which a message should be logged.\n * @public\n */\nexport type MessageLogLevel = 'quiet' | 'detail' | 'info' | 'warning' | 'error';\n\n// Untyped (literal-tuple-inferred) source of truth for allMessageLogLevels, kept separate from the\n// widened public export below so the exhaustiveness check actually inspects the literal values instead\n// of being widened away to `MessageLogLevel` before the check runs.\nconst messageLogLevelValues = ['quiet', 'detail', 'info', 'warning', 'error'] as const;\n\n/**\n * Compile-time exhaustiveness guard ensuring {@link messageLogLevelValues} exactly matches every member of\n * {@link MessageLogLevel}. Adding or removing a union member without updating the array fails the build.\n * Deliberately not exported - this exists only to force the compiler to evaluate the check below.\n */\ntype _MessageLogLevelExhaustivenessCheck = [\n  Exclude<MessageLogLevel, (typeof messageLogLevelValues)[number]>,\n  Exclude<(typeof messageLogLevelValues)[number], MessageLogLevel>\n] extends [never, never]\n  ? true\n  : never;\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nconst _messageLogLevelExhaustivenessCheck: _MessageLogLevelExhaustivenessCheck = true;\n\n/**\n * Exhaustive list of all {@link MessageLogLevel} values.\n * @public\n */\nexport const allMessageLogLevels: readonly MessageLogLevel[] = messageLogLevelValues;\n\n/**\n * Details for reporting a message.\n * @public\n */\nexport interface IMessageReportDetail<TD = unknown> {\n  level?: MessageLogLevel;\n  message?: ErrorFormatter<TD>;\n  detail?: TD;\n}\n\n/**\n * Options for reporting a result.\n * @public\n */\nexport interface IResultReportOptions<TD = unknown> {\n  /**\n   * The level of reporting to be used for failure results.  Default is 'error'.\n   */\n  failure?: MessageLogLevel | IMessageReportDetail<TD>;\n\n  /**\n   * The level of reporting to be used for success results.  Default is 'quiet'.\n   */\n  success?: MessageLogLevel | IMessageReportDetail<TD>;\n}\n\n/**\n * Interface for reporting a result.\n * @public\n */\nexport interface IResultReporter<T, TD = unknown> {\n  /** Reports a successful result at the specified log level. */\n  reportSuccess(level: MessageLogLevel, value: T, detail?: TD, message?: ErrorFormatter<TD>): void;\n  /** Reports a failed result at the specified log level. */\n  reportFailure(level: MessageLogLevel, message: string, detail?: TD): void;\n}\n\n/**\n * Simple error aggregator to simplify collecting all errors in\n * a flow.\n * @public\n */\nexport interface IMessageAggregator {\n  /**\n   * Indicates whether any messages have been aggregated.\n   */\n  readonly hasMessages: boolean;\n\n  /**\n   * The number of messages aggregated.\n   */\n  readonly numMessages: number;\n\n  /**\n   * The aggregated messages.\n   */\n  readonly messages: ReadonlyArray<string>;\n\n  /**\n   * Adds a message to the aggregator, if defined.\n   * @param message - The message to add - pass `undefined`\n   * or the empty string to continue without adding a message.\n   */\n  addMessage(message: string | undefined): this;\n\n  /**\n   * Adds multiple messages to the aggregator.\n   * @param messages - the messages to add.\n   */\n  addMessages(messages: string[] | undefined): this;\n\n  /**\n   * Returns all messages as a single string joined\n   * using the optionally-supplied `separator`, or\n   * newline if no separator is specified.\n   * @param separator - The optional separator used\n   * to join strings.\n   */\n  toString(separator?: string): string;\n}\n\n/**\n * Represents the result of some operation of sequence of operations.\n * @remarks\n * This common contract enables commingled discriminated usage of {@link Success | Success<T>}\n * and {@link Failure | Failure<T>}.\n * @public\n */\nexport interface IResult<T> {\n  /**\n   * Indicates whether the operation was successful.\n   */\n  readonly success: boolean;\n\n  /**\n   * Value returned by a successful operation, undefined\n   * for a failed operation.\n   */\n  readonly value: T | undefined;\n\n  /**\n   * Error message returned by a failed operation, undefined\n   * for a successful operation.\n   */\n  readonly message: string | undefined;\n\n  /**\n   * Indicates whether this operation was successful.  Functions\n   * as a type guard for {@link Success | Success<T>}.\n   */\n  isSuccess(): this is Success<T>;\n\n  /**\n   * Indicates whether this operation failed.  Functions\n   * as a type guard for {@link Failure | Failure<T>}.\n   */\n  isFailure(): this is Failure<T>;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or throws the error message if the corresponding operation failed.\n   *\n   * Note that `getValueOrThrow` is being superseded by `orThrow` and\n   * will eventually be deprecated.  Please use orDefault instead.\n   *\n   * @param logger - An optional {@link IResultLogger | logger} to which the\n   * error will also be reported.\n   * @returns The return value, if the operation was successful.\n   * @throws The error message if the operation failed.\n   * @deprecated Use {@link IResult.orThrow | orThrow(logger)} or {@link IResult.orThrow | orThrow(formatter)} instead.\n   */\n  getValueOrThrow(logger?: IResultLogger): T;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or a default value if the corresponding operation failed.\n   * @param dflt - The value to be returned if the operation failed (default is\n   * `undefined`).\n   *\n   * Note that `getValueOrDefault` is being superseded by `orDefault` and\n   * will eventually be deprecated.  Please use orDefault instead.\n   *\n   * @returns The return value, if the operation was successful.  Returns\n   * the supplied default value or `undefined` if no default is supplied.\n   * @deprecated Use {@link IResult.orDefault | orDefault(T)} or {@link IResult.orDefault | orDefault()} instead.\n   */\n  getValueOrDefault(dflt?: T): T | undefined;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or throws the error message if the corresponding operation failed.\n   * @param logger - An optional {@link IResultLogger | logger} to which the\n   * error will also be reported.\n   * @returns The return value, if the operation was successful.\n   * @throws The error message if the operation failed.\n   * {@label logger}\n   */\n  orThrow(logger?: IResultLogger): T;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or throws the error message if the corresponding operation failed.\n   * @param cb - The {@link ErrorFormatter | error formatter} to be called in the event of failure.\n   * @returns The return value, if the operation was successful.\n   * @throws The error message if the operation failed.\n   * {@label formatter}\n   */\n  orThrow(cb: ErrorFormatter): T;\n\n  /**\n   * Asserts at the call site that this {@link IResult | result} MUST be a success.\n   * Returns the value on success; on failure, throws an `Error` whose message\n   * is composed from the original failure message and the captured call-site\n   * location (file, line, and where useful function name).\n   *\n   * @remarks\n   * Use for declaration-time / setup-time invariants — module-level `const`\n   * initializers, static class properties, static initialization blocks, and\n   * test fixtures — where a failure indicates a coding bug that should\n   * surface at the call site rather than propagate as a `Result`. For chains\n   * where the throw is intentional control flow, prefer `orThrow`.\n   *\n   * On V8 (Node + Chromium) `Error.captureStackTrace` is used to elide\n   * `shouldNotFail` itself from the captured stack so the parsed frame is\n   * the user's call site directly. On WebKit (where `captureStackTrace` is\n   * unavailable) the stack is parsed manually and frames whose **parsed\n   * function name** contains `shouldNotFail` are filtered out — the raw\n   * stack-line text (including the file path) is deliberately NOT inspected,\n   * so consumer files named after `shouldNotFail` are not collateral damage.\n   * Function names and exact line numbers depend on source-map availability\n   * in the runtime. When no caller frame is recoverable (e.g. `frameDepth`\n   * out of range, or `frameDepth: 0`) the message falls back to the\n   * label-only form (or the bare original message when no label is given).\n   *\n   * Error message format (depending on whether a label and a usable function\n   * name are available):\n   * - both: `<label> (at <fn> in <file>:<line>): <original>`\n   * - label only: `<label> (at <file>:<line>): <original>`\n   * - fn only: `<fn> at <file>:<line>: <original>`\n   * - neither: `<file>:<line>: <original>`\n   *\n   * @param label - Optional human-meaningful identifier (e.g. the constant\n   * name) prefixed to the error message.\n   * @param frameDepth - Optional 1-indexed depth into the caller stack.\n   * Default `1` (immediate caller). Library authors wrapping `shouldNotFail`\n   * inside their own helper pass `2` to attribute to their caller.\n   * @returns The result value, if the operation was successful.\n   * @throws `Error` if the result was a failure.\n   */\n  shouldNotFail(label?: string, frameDepth?: number): T;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or a default value if the corresponding operation failed.\n   * @param dflt - The value to be returned if the operation failed.\n   * @returns The return value, if the operation was successful.  Returns\n   * the supplied default if an error occurred.\n   * {@label SUPPLIED}\n   */\n  orDefault(dflt: T): T;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or a default value if the corresponding operation failed.\n   * @returns The return value, if the operation was successful, or\n   * `undefined` if an error occurs.\n   * {@label MISSING}\n   */\n  orDefault(): T | undefined;\n\n  /**\n   * Calls a supplied {@link SuccessContinuation | success continuation} if\n   * the operation was a success.\n   * @remarks\n   * The {@link SuccessContinuation | success continuation} might return a\n   * different result type than {@link IResult} on which it is invoked. This\n   * enables chaining of operations with heterogenous return types.\n   *\n   * @param cb - The {@link SuccessContinuation | success continuation} to\n   * be called in the event of success.\n   * @returns If this operation was successful, returns the value returned\n   * by the {@link SuccessContinuation | success continuation}.  If this result\n   * failed, propagates the error message from this failure.\n   */\n  onSuccess<TN>(cb: SuccessContinuation<T, TN>): Result<TN>;\n\n  /**\n   * Calls a supplied {@link FailureContinuation | failed continuation} if\n   * the operation failed.\n   * @param cb - The {@link FailureContinuation | failure continuation} to\n   * be called in the event of failure.\n   * @returns If this operation failed, returns the value returned by the\n   * {@link FailureContinuation | failure continuation}.  If this result\n   * was successful, propagates the result value from the successful event.\n   */\n  onFailure(cb: FailureContinuation<T>): Result<T>;\n\n  /**\n   * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if\n   * the operation was a success, bridging into an {@link AsyncResult} chain.\n   * @remarks\n   * If the async callback rejects, the rejection is caught and converted\n   * to a {@link Failure}.\n   * @param cb - The {@link AsyncSuccessContinuation | async success continuation} to\n   * be called in the event of success.\n   * @returns An {@link AsyncResult} wrapping the async continuation result, or\n   * propagating the error message from this failure.\n   */\n  thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;\n\n  /**\n   * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if\n   * the operation failed, bridging into an {@link AsyncResult} chain.\n   * @remarks\n   * If the async callback rejects, the rejection is caught and converted\n   * to a {@link Failure}.\n   * @param cb - The {@link AsyncFailureContinuation | async failure continuation} to\n   * be called in the event of failure.\n   * @returns An {@link AsyncResult} wrapping the async continuation result, or\n   * propagating the success value from this result.\n   */\n  thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;\n\n  /**\n   * Calls a supplied {@link ErrorFormatter | error formatter} if\n   * the operation failed.\n   * @param cb - The {@link ErrorFormatter | error formatter} to\n   * be called in the event of failure.\n   * @returns If this operation failed, returns the returns {@link Failure | Failure}\n   * with the message returned by the formatter.  If this result\n   * was successful, propagates the result value from the successful event.\n   */\n  withErrorFormat(cb: ErrorFormatter): Result<T>;\n\n  /**\n   * Converts a {@link IResult | IResult<T>} to a {@link DetailedResult | DetailedResult<T, TD>},\n   * adding a supplied detail if the operation failed.\n   * @param detail - The detail to be added if this operation failed.\n   * @returns A new {@link DetailedResult | DetailedResult<T, TD>} with either\n   * the success result or the error message from this {@link IResult}, with\n   * the supplied detail (if this event failed) or detail `undefined` (if\n   * this result succeeded).\n   */\n  withFailureDetail<TD>(detail: TD): DetailedResult<T, TD>;\n\n  /**\n   * Converts a {@link IResult | IResult<T>} to a {@link DetailedResult | DetailedResult<T, TD>},\n   * adding supplied details.\n   * @param detail - The default detail to be added to the new {@link DetailedResult}.\n   * @param successDetail - An optional detail to be added if this result was successful.\n   * @returns A new {@link DetailedResult | DetailedResult<T, TD>} with either\n   * the success result or the error message from this {@link IResult} and the\n   * appropriate added detail.\n   */\n  withDetail<TD>(detail: TD, successDetail?: TD): DetailedResult<T, TD>;\n\n  /**\n   * Propagates interior result, appending any error message to the\n   * supplied errors array.\n   * @param errors - {@link IMessageAggregator | Error aggregator} in which\n   * errors will be aggregated.\n   * @param formatter - An optional {@link ErrorFormatter | error formatter} to be used to format the error message.\n   */\n  aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter): this;\n\n  /**\n   * Reports the result to the supplied reporter\n   * @param reporter - The {@link IResultReporter | reporter} to which the result will be reported.\n   * @param options - The {@link IResultReportOptions | options} for reporting the result.\n   */\n  report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): Result<T>;\n}\n\n/**\n * Reports a successful {@link IResult | result} from some operation and the\n * corresponding value.\n * @public\n */\nexport class Success<out T> implements IResult<T> {\n  /**\n   * {@inheritDoc IResult.success}\n   */\n  public readonly success: true = true;\n\n  /**\n   * For a successful operation, the error message is always `undefined`.\n   */\n  public readonly message: undefined = undefined;\n\n  /**\n   * @internal\n   */\n  protected readonly _value: T;\n\n  /**\n   * Constructs a {@link Success} with the supplied value.\n   * @param value - The value to be returned.\n   */\n  public constructor(value: T) {\n    this._value = value;\n  }\n\n  /**\n   * The result value returned by the successful operation.\n   */\n  public get value(): T {\n    return this._value;\n  }\n\n  /**\n   * {@inheritDoc IResult.isSuccess}\n   */\n  public isSuccess(): this is Success<T> {\n    return true;\n  }\n\n  /**\n   * {@inheritDoc IResult.isFailure}\n   */\n  public isFailure(): this is Failure<T> {\n    return false;\n  }\n\n  /**\n   * {@inheritDoc IResult.orThrow}\n   */\n  public orThrow(logger?: IResultLogger): T;\n\n  /**\n   * {@inheritDoc IResult.orThrow}\n   */\n  public orThrow(cb: ErrorFormatter): T;\n  public orThrow(__logger?: IResultLogger | ErrorFormatter): T {\n    return this._value;\n  }\n\n  /**\n   * {@inheritDoc IResult.shouldNotFail}\n   */\n  public shouldNotFail(__label?: string, __frameDepth?: number): T {\n    return this._value;\n  }\n\n  /**\n   * {@inheritDoc IResult.orDefault}\n   */\n  public orDefault(dflt: T): T;\n  /**\n   * {@inheritDoc IResult.orDefault}\n   */\n  public orDefault(): T | undefined;\n  public orDefault(dflt?: T): T | undefined {\n    return this._value ?? dflt;\n  }\n\n  /**\n   * {@inheritDoc IResult.getValueOrThrow}\n   * @deprecated Use {@link Success.orThrow | orThrow(logger)} or {@link Success.orThrow | orThrow(formatter)} instead.\n   */\n  public getValueOrThrow(__logger?: IResultLogger): T {\n    return this._value;\n  }\n\n  /**\n   * {@inheritDoc IResult.getValueOrDefault}\n   * @deprecated Use {@link Success.orDefault | orDefault(T)} or {@link Success.orDefault | orDefault()} instead.\n   */\n  public getValueOrDefault(dflt?: T): T | undefined {\n    return this._value ?? dflt;\n  }\n\n  /**\n   * {@inheritDoc IResult.onSuccess}\n   */\n  public onSuccess<TN>(cb: SuccessContinuation<T, TN>): Result<TN> {\n    return cb(this._value);\n  }\n\n  /**\n   * {@inheritDoc IResult.onFailure}\n   */\n  public onFailure(__: FailureContinuation<T>): Result<T> {\n    return this;\n  }\n\n  /**\n   * {@inheritDoc IResult.thenOnSuccess}\n   */\n  public thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN> {\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-use-before-define\n      return new AsyncResult(cb(this._value));\n    } catch (err: unknown) {\n      // eslint-disable-next-line @typescript-eslint/no-use-before-define\n      return AsyncResult.from(fail<TN>(_errorMessage(err)));\n    }\n  }\n\n  /**\n   * {@inheritDoc IResult.thenOnFailure}\n   */\n  public thenOnFailure(__: AsyncFailureContinuation<T>): AsyncResult<T> {\n    // eslint-disable-next-line @typescript-eslint/no-use-before-define\n    return AsyncResult.from(this);\n  }\n\n  /**\n   * {@inheritDoc IResult.withErrorFormat}\n   */\n  public withErrorFormat(__cb: ErrorFormatter): Result<T> {\n    return this;\n  }\n\n  /**\n   * {@inheritDoc IResult.withFailureDetail}\n   */\n  public withFailureDetail<TD>(__detail: TD): DetailedResult<T, TD> {\n    return succeedWithDetail(this._value);\n  }\n\n  /**\n   * {@inheritDoc IResult.withDetail}\n   */\n  public withDetail<TD>(detail: TD, successDetail?: TD): DetailedResult<T, TD> {\n    return succeedWithDetail(this._value, successDetail ?? detail);\n  }\n\n  /**\n   * {@inheritDoc IResult.aggregateError}\n   */\n  public aggregateError(__errors: IMessageAggregator, __formatter?: ErrorFormatter): this {\n    return this;\n  }\n\n  /**\n   * {@inheritDoc IResult.report}\n   */\n  public report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): Success<T> {\n    const successOptions =\n      typeof options?.success === 'object' ? options.success : { level: options?.success };\n    const level = successOptions.level ?? 'quiet';\n    reporter?.reportSuccess(level, this._value, undefined, successOptions.message);\n    return this;\n  }\n\n  /**\n   * Creates a {@link Success | Success<T>} with the supplied value.\n   * @param value - The value to be returned.\n   * @returns The resulting {@link Success | Success<T>} with the supplied value.\n   * @public\n   */\n  public static with<T>(value: T): Success<T> {\n    return new Success<T>(value);\n  }\n}\n\n/**\n * Reports a failed {@link IResult | result} from some operation, with an error message.\n * @public\n */\nexport class Failure<out T> implements IResult<T> {\n  /**\n   * {@inheritDoc IResult.success}\n   */\n  public readonly success: false = false;\n  /**\n   * Failed operation always returns undefined for value.\n   */\n  public readonly value: undefined = undefined;\n\n  /**\n   * @internal\n   */\n  protected readonly _message: string;\n\n  /**\n   * Constructs a {@link Failure} with the supplied message.\n   * @param message - Error message to be reported.\n   */\n  public constructor(message: string) {\n    this._message = message;\n  }\n\n  /**\n   * Gets the error message associated with this error.\n   */\n  public get message(): string {\n    return this._message;\n  }\n\n  /**\n   * {@inheritDoc IResult.isSuccess}\n   */\n  public isSuccess(): this is Success<T> {\n    return false;\n  }\n\n  /**\n   * {@inheritDoc IResult.isFailure}\n   */\n  public isFailure(): this is Failure<T> {\n    return true;\n  }\n\n  /**\n   * {@inheritDoc IResult.orThrow}\n   */\n  public orThrow(logger?: IResultLogger): never;\n\n  /**\n   * {@inheritDoc IResult.orThrow}\n   */\n  public orThrow(cb: ErrorFormatter): never;\n  public orThrow(logOrFormat?: IResultLogger | ErrorFormatter): never {\n    if (logOrFormat !== undefined) {\n      if (typeof logOrFormat === 'function') {\n        throw new Error(logOrFormat(this._message));\n      } else {\n        logOrFormat.error(this._message);\n      }\n    }\n    throw new Error(this._message);\n  }\n\n  /**\n   * {@inheritDoc IResult.shouldNotFail}\n   */\n  public shouldNotFail(label?: string, frameDepth: number = 1): never {\n    // Parse a probe Error's stack to identify the caller frame for message\n    // composition. We must NOT reuse this probe as the thrown Error: in V8,\n    // `.stack` is materialized lazily on first access (which happens below in\n    // `_findShouldNotFailFrame`), and once materialized the cached stack\n    // header carries whatever message was set at that moment. Mutating\n    // `.message` afterwards does not refresh the cached `.stack` header.\n    const probe = new Error();\n    if (typeof Error.captureStackTrace === 'function') {\n      Error.captureStackTrace(probe, this.shouldNotFail);\n    }\n    const frame = _findShouldNotFailFrame(probe.stack, frameDepth);\n    const message = _formatShouldNotFailMessage(this._message, label, frame);\n    // Build the final Error with the formatted message and re-elide\n    // `shouldNotFail` from its stack, so the thrown error's `.stack` shows\n    // both the formatted message in its header and the caller as its top\n    // frame.\n    const err = new Error(message);\n    if (typeof Error.captureStackTrace === 'function') {\n      Error.captureStackTrace(err, this.shouldNotFail);\n    }\n    throw err;\n  }\n\n  /**\n   * {@inheritDoc IResult.orDefault}\n   */\n  public orDefault(dflt: T): T;\n  /**\n   * {@inheritDoc IResult.orDefault}\n   */\n  public orDefault(): T | undefined;\n  public orDefault(dflt?: T): T | undefined {\n    return dflt;\n  }\n\n  /**\n   * {@inheritDoc IResult.getValueOrThrow}\n   * @deprecated Use {@link Failure.orThrow | orThrow(logger)} or {@link Failure.orThrow | orThrow(formatter)} instead.\n   */\n  public getValueOrThrow(logger?: IResultLogger): never {\n    if (logger !== undefined) {\n      logger.error(this._message);\n    }\n    throw new Error(this._message);\n  }\n\n  /**\n   * {@inheritDoc IResult.getValueOrDefault}\n   * @deprecated Use {@link Failure.orDefault | orDefault(T)} or {@link Failure.orDefault | orDefault()} instead.\n   */\n  public getValueOrDefault(dflt?: T): T | undefined {\n    return dflt;\n  }\n\n  /**\n   * {@inheritDoc IResult.onSuccess}\n   */\n  public onSuccess<TN>(__: SuccessContinuation<T, TN>): Result<TN> {\n    return new Failure(this._message);\n  }\n\n  /**\n   * {@inheritDoc IResult.onFailure}\n   */\n  public onFailure(cb: FailureContinuation<T>): Result<T> {\n    return cb(this._message);\n  }\n\n  /**\n   * {@inheritDoc IResult.thenOnSuccess}\n   */\n  public thenOnSuccess<TN>(__: AsyncSuccessContinuation<T, TN>): AsyncResult<TN> {\n    // eslint-disable-next-line @typescript-eslint/no-use-before-define\n    return AsyncResult.from(fail<TN>(this._message));\n  }\n\n  /**\n   * {@inheritDoc IResult.thenOnFailure}\n   */\n  public thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T> {\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-use-before-define\n      return new AsyncResult(cb(this._message));\n    } catch (err: unknown) {\n      // eslint-disable-next-line @typescript-eslint/no-use-before-define\n      return AsyncResult.from(fail<T>(_errorMessage(err)));\n    }\n  }\n\n  /**\n   * {@inheritDoc IResult.withErrorFormat}\n   */\n  public withErrorFormat(cb: ErrorFormatter): Result<T> {\n    return fail(cb(this._message));\n  }\n\n  /**\n   * {@inheritDoc IResult.withFailureDetail}\n   */\n  public withFailureDetail<TD>(detail: TD): DetailedResult<T, TD> {\n    return failWithDetail(this._message, detail);\n  }\n\n  /**\n   * {@inheritDoc IResult.withDetail}\n   */\n  public withDetail<TD>(detail: TD, __successDetail?: TD): DetailedResult<T, TD> {\n    return failWithDetail(this._message, detail);\n  }\n\n  /**\n   * {@inheritDoc IResult.aggregateError}\n   */\n  public aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter): this {\n    const message = formatter ? formatter(this._message) : this._message;\n    errors.addMessage(message);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc IResult.report}\n   */\n  public report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): Failure<T> {\n    const failureOptions =\n      typeof options?.failure === 'object' ? options.failure : { level: options?.failure };\n    const level = failureOptions.level ?? 'error';\n    const message = failureOptions.message?.(this._message) ?? this._message;\n    reporter?.reportFailure(level, message);\n    return this;\n  }\n\n  /**\n   * Re-types this {@link Failure | Failure<T>} as {@link Failure | Failure<U>} for\n   * propagation under a different success type.\n   * @remarks\n   * Supports the canonical Result early-return-after-`isFailure()` pattern when the\n   * outer function's success type differs from the inner Result's success type:\n   *\n   * ```ts\n   * const storeResult = await PromptStoreFixture.build(seed);\n   * if (storeResult.isFailure()) {\n   *   return storeResult.withType<PromptLibrary>();\n   * }\n   * return PromptLibrary.create({ store: storeResult.value, ... });\n   * ```\n   *\n   * Without this helper, TypeScript rejects `return storeResult` because\n   * `Failure<IPromptStore>` is invariant in `T` and not assignable to\n   * `Result<PromptLibrary>`. The workaround `return fail<U>(r.message)` is\n   * semantically equivalent but allocates a new {@link Failure} instance;\n   * `withType` returns `this` and only retypes statically.\n   *\n   * This method is sound because a {@link Failure} variant carries no `T`-shaped\n   * data — only an error message — so re-typing it as `Failure<U>` cannot\n   * misrepresent any value. The same operation is NOT exposed on {@link Success}\n   * because `Success<T>` carries `T`-shaped data and re-typing would be a lie.\n   *\n   * For `DetailedResult` propagation that preserves a typed `detail`, consider\n   * propagating the {@link DetailedFailure} directly through `onSuccess` (which\n   * already re-types the success arm) rather than reaching for `withType`.\n   *\n   * @returns This same {@link Failure} instance, statically retyped as\n   * {@link Failure | Failure<U>}.\n   * @public\n   */\n  public withType<U>(): Failure<U> {\n    // Safe by construction: Failure carries no T-shaped data, only a message.\n    // Re-typing the static T parameter cannot misrepresent any value.\n    return this as unknown as Failure<U>;\n  }\n\n  /**\n   * Get a 'friendly' string representation of this object.\n   * @remarks\n   * The string representation of a {@link Failure} value is the error message.\n   * @returns A string representing this object.\n   */\n  public toString(): string {\n    return this._message;\n  }\n\n  /**\n   * Creates a {@link Failure | Failure<T>} with the supplied error message.\n   * @param message - The error message to be returned.\n   * @returns The resulting {@link Failure | Failure<T>} with the supplied error message.\n   */\n  public static with<T>(message: string): Failure<T> {\n    return new Failure<T>(message);\n  }\n}\n\n/**\n * Returns {@link Success | Success<T>} with the supplied result value.\n * @param value - The successful result value to be returned\n * @remarks\n * A `succeeds` alias was added in release 5.0 for\n * naming consistency with {@link fails | fails}, which was added\n * to avoid conflicts with test frameworks and libraries.\n * @public\n */\nexport function succeed<T>(value: T): Success<T> {\n  return new Success<T>(value);\n}\n\n/**\n * {@inheritDoc succeed}\n * @public\n */\nexport function succeeds<T>(value: T): Success<T> {\n  return new Success<T>(value);\n}\n\n/**\n * Returns {@link Failure | Failure<T>} with the supplied error message.\n * @param message - Error message to be returned.\n * @remarks\n * A `fails` alias was added in release 5.0 due to\n * issues with the name `fail` being used test frameworks and libraries.\n * @public\n */\nexport function fail<T>(message: string): Failure<T> {\n  return new Failure<T>(message);\n}\n\n/**\n * {@inheritDoc fail}\n * @public\n */\nexport function fails<T>(message: string): Failure<T> {\n  return new Failure<T>(message);\n}\n\n/**\n * Uses a value or calls a supplied initializer if the supplied value is undefined.\n * @param value - the value\n * @param initializer - a function that initializes the value if it is undefined\n * @returns `Success` with the value if it is defined, or the result of calling the initializer function.\n * @public\n */\nexport function useOrInitialize<T>(value: T | undefined, initializer: () => Result<T>): Result<T> {\n  return value !== undefined ? succeed(value) : initializer();\n}\n\n/**\n * Callback to be called when a {@link DetailedResult | DetailedResult} encounters success.\n * @remarks\n * A success callback can return a different result type than it receives, allowing\n * success results to chain through intermediate result types.\n * @public\n */\nexport type DetailedSuccessContinuation<T, TD, TN> = (value: T, detail?: TD) => DetailedResult<TN, TD>;\n\n/**\n * Callback to be called when a {@link DetailedResult | DetailedResult} encounters a failure.\n * @remarks\n * A failure callback can change {@link DetailedFailure | DetailedFailure<T, TD>} to\n * {@link DetailedSuccess | DetailedSuccess<T, TD>} (e.g. by returning a default value)\n * or it can change or embellish the error message, but it cannot change the success return type.\n * @public\n */\nexport type DetailedFailureContinuation<T, TD> = (message: string, detail?: TD) => DetailedResult<T, TD>;\n\n/**\n * A {@link DetailedSuccess | DetailedSuccess} extends {@link Success | Success} to report optional success\n * details in addition to the error message.\n * @public\n */\nexport class DetailedSuccess<out T, out TD> extends Success<T> {\n  /**\n   * @internal\n   */\n  protected _detail?: TD;\n\n  /**\n   * Constructs a new {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied\n   * value and detail.\n   * @param value - The value to be returned.\n   * @param detail - An optional successful detail to be returned.  If omitted, detail\n   * will be `undefined`.\n   */\n  public constructor(value: T, detail?: TD) {\n    super(value);\n    this._detail = detail;\n  }\n\n  /**\n   * The success detail associated with this {@link DetailedSuccess}, or `undefined` if\n   * no detail was supplied.\n   */\n  public get detail(): TD | undefined {\n    return this._detail;\n  }\n\n  /**\n   * Reports that this {@link DetailedSuccess} is a success.\n   * @remarks\n   * Always true for {@link DetailedSuccess} but can be used as type guard\n   * to discriminate {@link DetailedSuccess} from {@link DetailedFailure} in\n   * a {@link DetailedResult}.\n   * @returns `true`\n   */\n  public isSuccess(): this is DetailedSuccess<T, TD> {\n    return true;\n  }\n\n  /**\n   * Invokes the supplied {@link DetailedSuccessContinuation | success callback} and propagates\n   * its returned {@link DetailedResult | DetailedResult<TN, TD>}.\n   * @remarks\n   * The success callback mutates the return type from `<T>` to `<TN>`.\n   * @param cb - The {@link DetailedSuccessContinuation | success callback} to be invoked.\n   * @returns The {@link DetailedResult | DetailedResult<T, TD>} returned by the success callback.\n   */\n  public onSuccess<TN>(cb: DetailedSuccessContinuation<T, TD, TN>): DetailedResult<TN, TD> {\n    return cb(this._value, this._detail);\n  }\n\n  /**\n   * Propagates this {@link DetailedSuccess}.\n   * @remarks\n   * Failure does not mutate return type so we can return this event directly.\n   * @param __cb - {@link DetailedFailureContinuation | Failure callback} to be called\n   * on a {@link DetailedResult} in case of failure (ignored).\n   * @returns `this`\n   */\n  public onFailure(__cb: DetailedFailureContinuation<T, TD>): DetailedResult<T, TD> {\n    return this;\n  }\n\n  /**\n   * {@inheritDoc Success.withErrorFormat}\n   */\n  public withErrorFormat(cb: ErrorFormatter): DetailedResult<T, TD> {\n    return this;\n  }\n\n  /**\n   * {@inheritDoc IResult.report}\n   */\n  public report(\n    reporter?: IResultReporter<T, unknown>,\n    options?: IResultReportOptions<unknown>\n  ): DetailedSuccess<T, TD> {\n    const successOptions =\n      typeof options?.success === 'object' ? options.success : { level: options?.success };\n    const level = successOptions.level ?? 'quiet';\n    // Cast reporter to preserve detail type when calling reportSuccess\n    const detailedReporter = reporter as IResultReporter<T, TD> | undefined;\n    detailedReporter?.reportSuccess(level, this._value, this._detail, successOptions.message);\n    return this;\n  }\n\n  /**\n   * Creates a {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied value and\n   * optional detail.\n   */\n  public static with<T, TD>(value: T, detail?: TD): DetailedSuccess<T, TD> {\n    return new DetailedSuccess<T, TD>(value, detail);\n  }\n\n  /**\n   * Returns this {@link DetailedSuccess} as a {@link Result}.\n   */\n  public get asResult(): Result<T> {\n    return this;\n  }\n}\n\n/**\n * A {@link DetailedFailure | DetailedFailure<T, TD>} extends {@link Failure | Failure<T>} to report optional\n * failure details in addition to the error message.\n * @public\n */\nexport class DetailedFailure<out T, out TD> extends Failure<T> {\n  /**\n   * @internal\n   */\n  protected _detail?: TD;\n\n  /**\n   * Constructs a new {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied\n   * message and detail.\n   * @param message - The message to be returned.\n   * @param detail - The error detail to be returned.\n   */\n  public constructor(message: string, detail?: TD) {\n    super(message);\n    this._detail = detail;\n  }\n\n  /**\n   * The error detail associated with this {@link DetailedFailure}.\n   */\n  public get detail(): TD | undefined {\n    return this._detail;\n  }\n\n  /**\n   * Reports that this {@link DetailedFailure} is a failure.\n   * @remarks\n   * Always true for {@link DetailedFailure} but can be used as type guard\n   * to discriminate {@link DetailedSuccess} from {@link DetailedFailure} in\n   * a {@link DetailedResult}.\n   * @returns `true`\n   */\n  public isFailure(): this is DetailedFailure<T, TD> {\n    return true;\n  }\n\n  /**\n   * Propagates the error message and detail from this result.\n   * @remarks\n   * Mutates the success type as the success callback would have, but does not\n   * call the success callback.\n   * @param __cb - {@link DetailedSuccessContinuation | Success callback} to be called\n   * on a {@link DetailedResult} in case of success (ignored).\n   * @returns A new {@link DetailedFailure | DetailedFailure<TN, TD>} which contains\n   * the error message and detail from this one.\n   */\n  public onSuccess<TN>(__cb: DetailedSuccessContinuation<T, TD, TN>): DetailedResult<TN, TD> {\n    return new DetailedFailure<TN, TD>(this._message, this._detail);\n  }\n\n  /**\n   * Invokes the supplied {@link DetailedFailureContinuation | failure callback} and propagates\n   * its returned {@link DetailedResult | DetailedResult<T, TD>}.\n   * @param cb - The {@link DetailedFailureContinuation | failure callback} to be invoked.\n   * @returns The {@link DetailedResult | DetailedResult<T, TD>} returned by the failure callback.\n   */\n  public onFailure(cb: DetailedFailureContinuation<T, TD>): DetailedResult<T, TD> {\n    return cb(this._message, this._detail);\n  }\n\n  /**\n   * {@inheritDoc IResult.withErrorFormat}\n   */\n  public withErrorFormat(cb: ErrorFormatter<TD>): DetailedResult<T, TD> {\n    return failWithDetail(cb(this._message, this._detail), this._detail);\n  }\n\n  /**\n   * {@inheritDoc IResult.aggregateError}\n   */\n  public aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter<TD>): this {\n    const message = formatter ? formatter(this._message, this._detail) : this._message;\n    errors.addMessage(message);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc IResult.report}\n   */\n  public report(\n    reporter?: IResultReporter<T, unknown>,\n    options?: IResultReportOptions<unknown>\n  ): DetailedFailure<T, TD> {\n    const failureOptions =\n      typeof options?.failure === 'object' ? options.failure : { level: options?.failure };\n    const level = failureOptions.level ?? 'error';\n    // Cast formatter to handle detail type properly\n    const formatter = failureOptions.message as ErrorFormatter<TD> | undefined;\n    const message = formatter?.(this._message, this._detail) ?? this._message;\n    // Cast reporter to preserve detail type when calling reportFailure\n    const detailedReporter = reporter as IResultReporter<T, TD> | undefined;\n    detailedReporter?.reportFailure(level, message, this._detail);\n    return this;\n  }\n\n  public orThrow(logOrFormat?: IResultLogger<TD> | ErrorFormatter<TD>): never;\n  public orThrow(cb: ErrorFormatter): never;\n  public orThrow(logOrFormat?: IResultLogger<TD> | ErrorFormatter<TD>): never {\n    if (logOrFormat !== undefined) {\n      if (typeof logOrFormat === 'function') {\n        throw new Error(logOrFormat(this._message, this._detail));\n      } else {\n        logOrFormat.error(this._message, this._detail);\n      }\n    }\n    throw new Error(this._message);\n  }\n\n  /**\n   * Returns this {@link DetailedFailure} as a {@link Result}.\n   */\n  public get asResult(): Result<T> {\n    return this;\n  }\n\n  /**\n   * Creates a {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied error message\n   * and optional detail.\n   * @param message - The error message to be returned.\n   * @param detail - The error detail to be returned.\n   * @returns The resulting {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied\n   * error message and detail.\n   * @public\n   */\n  public static with<T, TD>(message: string, detail?: TD): DetailedFailure<T, TD> {\n    return new DetailedFailure<T, TD>(message, detail);\n  }\n}\n\n/**\n * Represents a result with additional detail.\n * @beta\n */\nexport type DetailedResult<T, TD> = DetailedSuccess<T, TD> | DetailedFailure<T, TD>;\n\n/**\n * Type inference to determine the result type `T` of a {@link DetailedResult | DetailedResult<T, TD>}.\n * @beta\n */\nexport type DetailedResultValueType<T> = T extends DetailedResult<infer TV, unknown> ? TV : never;\n\n/**\n * Type inference to determine the detail type `TD` of a {@link DetailedResult | DetailedResult<T, TD>}.\n * @beta\n */\nexport type ResultDetailType<T> = T extends DetailedResult<unknown, infer TD> ? TD : never;\n\n/**\n * Returns {@link DetailedSuccess | DetailedSuccess<T, TD>} with a supplied value and optional\n * detail.\n * @param value - The value of type `<T>` to be returned.\n * @param detail - An optional detail of type `<TD>` to be returned.\n * @returns A {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied value\n * and detail, if supplied.\n * @remarks\n * The `succeedsWithDetail` alias was added in release 5.0 for\n * naming consistency with {@link fails | fails}, which was added to avoid conflicts\n * with test frameworks and libraries.\n * @public\n */\nexport function succeedWithDetail<T, TD>(value: T, detail?: TD): DetailedSuccess<T, TD> {\n  return new DetailedSuccess<T, TD>(value, detail);\n}\n\n/**\n * {@inheritDoc succeedWithDetail}\n * @public\n */\nexport function succeedsWithDetail<T, TD>(value: T, detail?: TD): DetailedSuccess<T, TD> {\n  return new DetailedSuccess<T, TD>(value, detail);\n}\n\n/**\n * Returns {@link DetailedFailure | DetailedFailure<T, TD>} with a supplied error message and detail.\n * @param message - The error message to be returned.\n * @param detail - The event detail to be returned.\n * @returns An {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied error\n * message and detail.\n * @remarks\n * The `failsWithDetail` alias was added in release 5.0 for naming consistency\n * with {@link fails | fails}, which was added to avoid conflicts with test frameworks and libraries.\n * @public\n */\nexport function failWithDetail<T, TD>(message: string, detail?: TD): DetailedFailure<T, TD> {\n  return new DetailedFailure<T, TD>(message, detail);\n}\n\n/**\n * {@inheritDoc failWithDetail}\n * @public\n */\nexport function failsWithDetail<T, TD>(message: string, detail?: TD): DetailedFailure<T, TD> {\n  return new DetailedFailure<T, TD>(message, detail);\n}\n\n/**\n * Propagates a {@link Success} or {@link Failure} {@link Result}, adding supplied\n * event details as appropriate.\n * @param result - The {@link Result} to be propagated.\n * @param detail - The event detail (type `<TD>`) to be added to the {@link Result | result}.\n * @param successDetail - An optional distinct event detail to be added to {@link Success} results.  If `successDetail`\n * is omitted or `undefined`, then `detail` will be applied to {@link Success} results.\n * @returns A new {@link DetailedResult | DetailedResult<T, TD>} with the success value or error\n * message from the original `result` but with the specified detail added.\n * @public\n */\nexport function propagateWithDetail<T, TD>(\n  result: Result<T>,\n  detail: TD,\n  successDetail?: TD\n): DetailedResult<T, TD> {\n  return result.isSuccess()\n    ? succeedWithDetail(result.value, successDetail ?? detail)\n    : failWithDetail(result.message, detail);\n}\n\n/**\n * Extracts a message string from an unknown thrown/rejected value.\n * @param err - The caught error value.\n * @returns The error message string.\n * @internal\n */\nexport function _errorMessage(err: unknown): string {\n  if (err instanceof Error) {\n    return err.message;\n  }\n  return String(err);\n}\n\n/**\n * Wraps a function which might throw to convert exception results\n * to {@link Failure}.\n * @param func - The function to be captured.\n * @returns Returns {@link Success} with a value of type `<T>` on\n * success , or {@link Failure} with the thrown error message if\n * `func` throws an `Error` or string.\n * @public\n */\nexport function captureResult<T>(func: () => T): Result<T> {\n  try {\n    return succeed(func());\n  } catch (err) {\n    return fail(_errorMessage(err));\n  }\n}\n\n/**\n * Async continuation callback to be called in the event that a\n * {@link Result} is successful, returning a `PromiseLike` of a new\n * {@link Result}.\n * @remarks\n * Typed as `PromiseLike<Result<TN>>` rather than `Promise<Result<TN>>` so\n * callers can return the result of {@link captureAsyncResult} (which is an\n * {@link AsyncResult}, itself a `PromiseLike<Result<TN>>`) directly from a\n * `thenOnSuccess` callback without an `async` wrapper to coerce the\n * contextual return type back through `Awaited<>`. The continuation result\n * is always wrapped into an {@link AsyncResult}, so chaining is unaffected.\n * @public\n */\nexport type AsyncSuccessContinuation<T, TN> = (value: T) => PromiseLike<Result<TN>>;\n\n/**\n * Async continuation callback to be called in the event that a\n * {@link Result} fails, returning a `PromiseLike` of a new {@link Result}.\n * @remarks\n * See {@link AsyncSuccessContinuation} for the rationale behind accepting\n * any `PromiseLike<Result<T>>` rather than only a `Promise<Result<T>>`.\n * @public\n */\nexport type AsyncFailureContinuation<T> = (message: string) => PromiseLike<Result<T>>;\n\n/**\n * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both\n * synchronous and asynchronous operations.\n *\n * @remarks\n * `AsyncResult<T>` implements `PromiseLike` so it can be directly `await`ed.\n * Use the `thenOnSuccess` and `thenOnFailure` methods on {@link Result} to bridge\n * from synchronous to asynchronous result chains.\n *\n * @example\n * ```typescript\n * const result: Result<Final> = await parseInput(input)\n *   .thenOnSuccess(async (parsed) => fetchData(parsed))\n *   .onSuccess((data) => transform(data))\n *   .thenOnSuccess(async (transformed) => saveData(transformed))\n *   .withErrorFormat((msg) => `pipeline failed: ${msg}`);\n * ```\n *\n * @public\n */\nexport class AsyncResult<T> implements PromiseLike<Result<T>> {\n  private readonly _promise: Promise<Result<T>>;\n\n  /**\n   * Constructs an {@link AsyncResult} wrapping the supplied promise (or any\n   * `PromiseLike` that resolves to a {@link Result}, such as another\n   * {@link AsyncResult}).\n   * @remarks\n   * If the supplied promise rejects, the rejection is caught and converted\n   * to a {@link Failure}, ensuring that awaiting an {@link AsyncResult} always\n   * yields a {@link Result}.\n   * @param promise - A `Promise` (or `PromiseLike`) that resolves to a\n   * {@link Result}.\n   */\n  public constructor(promise: PromiseLike<Result<T>>) {\n    this._promise = Promise.resolve(promise).catch((err: unknown) => fail<T>(_errorMessage(err)));\n  }\n\n  /**\n   * Calls a supplied {@link SuccessContinuation | success continuation} if\n   * the wrapped result is successful.\n   * @param cb - The synchronous {@link SuccessContinuation | success continuation}\n   * to be called in the event of success.\n   * @returns A new {@link AsyncResult} wrapping the continuation result.\n   */\n  public onSuccess<TN>(cb: SuccessContinuation<T, TN>): AsyncResult<TN> {\n    return new AsyncResult(this._promise.then((r) => r.onSuccess(cb)));\n  }\n\n  /**\n   * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if\n   * the wrapped result is successful.\n   * @remarks\n   * Both synchronous throws and async rejections from the callback are caught\n   * and converted to a {@link Failure}.\n   * @param cb - The {@link AsyncSuccessContinuation | async success continuation}\n   * to be called in the event of success.\n   * @returns A new {@link AsyncResult} wrapping the async continuation result.\n   */\n  public thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN> {\n    return new AsyncResult(\n      this._promise.then(async (r) => {\n        if (r.isFailure()) {\n          return fail<TN>(r.message);\n        }\n        try {\n          return await cb(r.value);\n        } catch (err: unknown) {\n          return fail<TN>(_errorMessage(err));\n        }\n      })\n    );\n  }\n\n  /**\n   * Calls a supplied {@link FailureContinuation | failure continuation} if\n   * the wrapped result is a failure.\n   * @param cb - The synchronous {@link FailureContinuation | failure continuation}\n   * to be called in the event of failure.\n   * @returns A new {@link AsyncResult} wrapping the continuation result.\n   */\n  public onFailure(cb: FailureContinuation<T>): AsyncResult<T> {\n    return new AsyncResult(this._promise.then((r) => r.onFailure(cb)));\n  }\n\n  /**\n   * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if\n   * the wrapped result is a failure.\n   * @remarks\n   * Both synchronous throws and async rejections from the callback are caught\n   * and converted to a {@link Failure}.\n   * @param cb - The {@link AsyncFailureContinuation | async failure continuation}\n   * to be called in the event of failure.\n   * @returns A new {@link AsyncResult} wrapping the async continuation result.\n   */\n  public thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T> {\n    return new AsyncResult(\n      this._promise.then(async (r) => {\n        if (r.isSuccess()) {\n          return r;\n        }\n        try {\n          return await cb(r.message);\n        } catch (err: unknown) {\n          return fail<T>(_errorMessage(err));\n        }\n      })\n    );\n  }\n\n  /**\n   * Calls a supplied {@link ErrorFormatter | error formatter} if\n   * the wrapped result is a failure.\n   * @param cb - The {@link ErrorFormatter | error formatter} to\n   * be called in the event of failure.\n   * @returns A new {@link AsyncResult} with the formatted error message,\n   * or the original success result.\n   */\n  public withErrorFormat(cb: ErrorFormatter): AsyncResult<T> {\n    return new AsyncResult(this._promise.then((r) => r.withErrorFormat(cb)));\n  }\n\n  /**\n   * Propagates the wrapped result, appending any error message to the\n   * supplied errors aggregator.\n   * @param errors - {@link IMessageAggregator | Error aggregator} in which\n   * errors will be aggregated.\n   * @param formatter - An optional {@link ErrorFormatter | error formatter}\n   * to be used to format the error message.\n   * @returns A new {@link AsyncResult} wrapping the result after aggregation.\n   */\n  public aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter): AsyncResult<T> {\n    return new AsyncResult(\n      this._promise.then((r) => {\n        r.aggregateError(errors, formatter);\n        return r;\n      })\n    );\n  }\n\n  /**\n   * Reports the wrapped result to the supplied reporter.\n   * @param reporter - The {@link IResultReporter | reporter} to which the result\n   * will be reported.\n   * @param options - The {@link IResultReportOptions | options} for reporting the result.\n   * @returns A new {@link AsyncResult} wrapping the result after reporting.\n   */\n  public report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): AsyncResult<T> {\n    return new AsyncResult(\n      this._promise.then((r) => {\n        r.report(reporter, options);\n        return r;\n      })\n    );\n  }\n\n  /**\n   * Implementation of `PromiseLike.then` enabling `await` on {@link AsyncResult}.\n   * @param onfulfilled - Callback invoked when the promise resolves.\n   * @param onrejected - Callback invoked when the promise rejects.\n   * @returns A `Promise` resolving to the callback result.\n   */\n  /* eslint-disable @rushstack/no-new-null */\n  public then<TResult1 = Result<T>, TResult2 = never>(\n    onfulfilled?: ((value: Result<T>) => TResult1 | PromiseLike<TResult1>) | null,\n    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null\n  ): Promise<TResult1 | TResult2> {\n    /* eslint-enable @rushstack/no-new-null */\n    return this._promise.then(onfulfilled, onrejected);\n  }\n\n  /**\n   * Creates an {@link AsyncResult} from a {@link Result}.\n   * @param result - The {@link Result} to wrap.\n   * @returns A new {@link AsyncResult} wrapping the supplied result.\n   */\n  public static from<T>(result: Result<T>): AsyncResult<T> {\n    return new AsyncResult(Promise.resolve(result));\n  }\n}\n\n/**\n * Wraps an async function which might throw to convert exception results\n * to {@link Failure}.\n * @remarks\n * Returns an {@link AsyncResult} so callers can fluently chain\n * (`.onSuccess` / `.thenOnSuccess` / `.withErrorFormat`) directly off the\n * captured result. Because {@link AsyncResult} implements\n * `PromiseLike<Result<T>>`, existing `await captureAsyncResult(...)` call\n * sites continue to work unchanged and yield the same {@link Result}.\n *\n * Synchronous throws from `func` (before it returns its `Promise`), promise\n * rejections, and successful resolutions are all funneled through the\n * returned {@link AsyncResult}, which resolves to a {@link Failure} for the\n * throw/reject cases and a {@link Success} wrapping the resolved value\n * otherwise.\n * @param func - The async function to be captured.\n * @returns An {@link AsyncResult} resolving to {@link Success} with a value\n * of type `<T>` on success, or {@link Failure} with the thrown error message\n * if `func` throws or rejects.\n * @public\n */\nexport function captureAsyncResult<T>(func: () => Promise<T>): AsyncResult<T> {\n  try {\n    return new AsyncResult(func().then((value) => succeed(value)));\n  } catch (err: unknown) {\n    return AsyncResult.from(fail<T>(_errorMessage(err)));\n  }\n}\n"]}

package/lib/packlets/base/shouldNotFail.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Internal helpers for `Result<T>.shouldNotFail()`. Parsing and message
+ * composition live here so the `Result` class file stays focused on the
+ * Result hierarchy itself; the helpers are exported with the `_` prefix
+ * convention and `@internal` tag so unit tests can cover them directly
+ * without adding test-only public exports.
+ */
+/**
+ * Parsed stack-frame information used by `Result<T>.shouldNotFail`.
+ * All fields are optional — runtimes that don't expose stack traces produce
+ * an empty frame and the call site is omitted from the message.
+ * @internal
+ */
+export interface _IShouldNotFailFrame {
+    fn?: string;
+    file?: string;
+    line?: number;
+}
+/**
+ * Parses a single stack-trace line in either V8 or WebKit format.
+ *
+ * V8: `    at <fn> (<file>:<line>:<col>)` or `    at <file>:<line>:<col>`
+ * WebKit: `<fn>@<file>:<line>:<col>` or `@<file>:<line>:<col>`
+ * @internal
+ */
+export declare function _parseStackFrame(line: string): _IShouldNotFailFrame;
+/**
+ * Finds the caller frame at the supplied depth in a stack string.
+ *
+ * Filters out frames whose **parsed function name** contains `shouldNotFail`
+ * (the file path is deliberately NOT inspected — consumer test files may
+ * themselves be named after `shouldNotFail` and their frames must not be
+ * filtered out). Covers both the V8 path — where `Error.captureStackTrace`
+ * should have done this already but the extra filter is harmless — and the
+ * WebKit fallback path where `captureStackTrace` is unavailable. `frameDepth`
+ * is 1-indexed: `1` selects the immediate caller.
+ * @internal
+ */
+export declare function _findShouldNotFailFrame(stack: string | undefined, frameDepth: number): _IShouldNotFailFrame;
+/**
+ * Normalizes a function name from a stack frame, returning `undefined` when
+ * the name is empty or one of the well-known anonymous-IIFE noise patterns
+ * (typically emitted by V8 for module-top-level code).
+ * @internal
+ */
+export declare function _normalizeShouldNotFailFnName(fn: string | undefined): string | undefined;
+/**
+ * Composes the error message thrown by `Result<T>.shouldNotFail` from the
+ * captured frame and optional label.
+ * @internal
+ */
+export declare function _formatShouldNotFailMessage(originalMessage: string, label: string | undefined, frame: _IShouldNotFailFrame): string;
+//# sourceMappingURL=shouldNotFail.d.ts.map

package/lib/packlets/base/shouldNotFail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shouldNotFail.d.ts","sourceRoot":"","sources":["../../../src/packlets/base/shouldNotFail.ts"],"names":[],"mappings":"AAsBA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAenE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,oBAAoB,CAqB3G;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKxF;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,oBAAoB,GAC1B,MAAM,CA2BR"}