@fgv/ts-utils 5.1.0-32 → 5.1.0-34

package/dist/packlets/logging/retainingLogger.js.map

@@ -1 +1 @@
-{"version":3,"file":"retainingLogger.js","sourceRoot":"","sources":["../../../src/packlets/logging/retainingLogger.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 */\nimport { MessageLogLevel, Success, succeed } from '../base';\nimport { LoggerBase, ReporterLogLevel, shouldLog } from './logger';\n\n/**\n * A retained log record. Preserves the level and an ordering cursor so consumers\n * can filter by severity and page incrementally.\n * @public\n */\nexport interface ILogRecord {\n  /**\n   * Monotonic 1-based sequence number, stable across ring eviction.\n   */\n  readonly seq: number;\n  /**\n   * Milliseconds since epoch when the record was logged (from the injected clock).\n   */\n  readonly timestamp: number;\n  /**\n   * The level the record was logged at.\n   */\n  readonly level: MessageLogLevel;\n  /**\n   * The formatted message (same formatting {@link Logging.LoggerBase._format | LoggerBase._format} produces).\n   */\n  readonly message: string;\n  /**\n   * The raw structured inputs `[message, ...parameters]` before formatting.\n   */\n  readonly args?: readonly unknown[];\n}\n\n/**\n * Options for {@link Logging.RetainingLogger.getRecords | RetainingLogger.getRecords}.\n * @public\n */\nexport interface IGetRecordsOptions {\n  /**\n   * If supplied, only records whose level would be emitted at this threshold\n   * (per {@link Logging.shouldLog | shouldLog}) are returned.\n   */\n  readonly minLevel?: ReporterLogLevel;\n  /**\n   * If supplied, only records with `seq > sinceSeq` are returned, enabling\n   * incremental paging from a previously-held cursor.\n   */\n  readonly sinceSeq?: number;\n  /**\n   * If supplied, returns at most this many records — the most recent N (tail),\n   * still ordered oldest-first.\n   */\n  readonly limit?: number;\n}\n\n/**\n * An {@link Logging.ILogger | ILogger} that retains structured log records in a bounded\n * most-recent-N ring, with a query API supporting min-severity filtering and\n * since-cursor incremental paging.\n *\n * @remarks\n * Records are captured via the {@link Logging.LoggerBase._logStructured | _logStructured} hook,\n * so the full structured form (`level` + formatted `message` + raw `args`) is retained.\n * The logger emits nowhere itself — pair it with a {@link Logging.MultiLogger | MultiLogger}\n * to also feed a {@link Logging.ConsoleLogger | ConsoleLogger} or other durable sink.\n *\n * @public\n */\nexport class RetainingLogger extends LoggerBase {\n  /**\n   * The fixed ring capacity — the maximum number of records retained before the\n   * oldest is overwritten. A positive integer (see the constructor normalization).\n   * @internal\n   */\n  private readonly _capacity: number;\n\n  /**\n   * Injected clock used to timestamp records.\n   * @internal\n   */\n  private readonly _now: () => number;\n\n  /**\n   * The backing store, used as a circular buffer. Grows lazily up to `_capacity`,\n   * after which records overwrite the oldest slot in place — eviction is O(1), with\n   * no `shift()` re-indexing regardless of capacity.\n   * @internal\n   */\n  private _buffer: ILogRecord[] = [];\n\n  /**\n   * Index of the oldest retained record within `_buffer` once the ring is full.\n   * @internal\n   */\n  private _head: number = 0;\n\n  /**\n   * The number of valid records currently retained (`<= _capacity`).\n   * @internal\n   */\n  private _count: number = 0;\n\n  /**\n   * The most recently assigned sequence number; monotonic, stable across eviction\n   * and {@link Logging.RetainingLogger.clear | clear()}.\n   * @internal\n   */\n  private _lastSeq: number = 0;\n\n  /**\n   * Creates a new retaining logger.\n   * @param logLevel - The level of logging to retain. Defaults to `'detail'` to capture\n   * broadly and filter at query time.\n   * @param maxRecords - The maximum number of records to retain. Defaults to `1000`.\n   * @param now - Injected clock returning milliseconds since epoch. Defaults to `Date.now`.\n   */\n  public constructor(\n    logLevel: ReporterLogLevel = 'detail',\n    maxRecords: number = 1000,\n    now: () => number = () => Date.now()\n  ) {\n    super(logLevel);\n    // The ring requires a positive integer capacity to be well-defined; a non-finite\n    // or sub-1 value would make the modular index arithmetic meaningless, so floor it\n    // to a sane minimum of 1 rather than crash on degenerate input.\n    this._capacity = Number.isFinite(maxRecords) && maxRecords >= 1 ? Math.floor(maxRecords) : 1;\n    this._now = now;\n  }\n\n  /**\n   * The retained records, oldest-first.\n   */\n  public get records(): ReadonlyArray<ILogRecord> {\n    return this._toOrderedArray();\n  }\n\n  /**\n   * The most recently assigned sequence number. A client can hold this value and\n   * pass it as `sinceSeq` to page only records logged afterward.\n   */\n  public get lastSeq(): number {\n    return this._lastSeq;\n  }\n\n  /**\n   * Returns retained records, oldest-first, optionally filtered.\n   * @param options - {@link Logging.IGetRecordsOptions | Filtering and paging options}.\n   * @returns The matching records, oldest-first.\n   */\n  public getRecords(options?: IGetRecordsOptions): ReadonlyArray<ILogRecord> {\n    let result: ReadonlyArray<ILogRecord> = this._toOrderedArray();\n    if (options?.minLevel !== undefined) {\n      const minLevel = options.minLevel;\n      result = result.filter((r) => shouldLog(r.level, minLevel));\n    }\n    if (options?.sinceSeq !== undefined) {\n      const sinceSeq = options.sinceSeq;\n      result = result.filter((r) => r.seq > sinceSeq);\n    }\n    if (options?.limit !== undefined && result.length > options.limit) {\n      result = result.slice(result.length - options.limit);\n    }\n    return result;\n  }\n\n  /**\n   * Clears all retained records. Does NOT reset the sequence counter, so a client\n   * holding a `sinceSeq` cursor never re-sees a sequence number.\n   */\n  public clear(): void {\n    this._buffer = [];\n    this._head = 0;\n    this._count = 0;\n  }\n\n  /**\n   * Materializes the ring into a plain oldest-first array.\n   * @internal\n   */\n  private _toOrderedArray(): ILogRecord[] {\n    const result: ILogRecord[] = [];\n    for (let i = 0; i < this._count; i++) {\n      result.push(this._buffer[(this._head + i) % this._capacity]);\n    }\n    return result;\n  }\n\n  /**\n   * {@inheritDoc Logging.LoggerBase._logStructured}\n   * @internal\n   */\n  protected _logStructured(\n    level: MessageLogLevel,\n    formatted: string,\n    message: unknown,\n    parameters: readonly unknown[]\n  ): void {\n    this._lastSeq += 1;\n    const record: ILogRecord = {\n      seq: this._lastSeq,\n      timestamp: this._now(),\n      level,\n      message: formatted,\n      args: [message, ...parameters]\n    };\n    if (this._count < this._capacity) {\n      // Still filling: append to the next free slot (head stays 0 during this phase).\n      this._buffer.push(record);\n      this._count += 1;\n    } else {\n      // Full: overwrite the oldest record in place and advance the head.\n      this._buffer[this._head] = record;\n      this._head = (this._head + 1) % this._capacity;\n    }\n  }\n\n  /**\n   * {@inheritDoc Logging.LoggerBase._log}\n   * @internal\n   */\n  protected _log(message: string, __level: MessageLogLevel): Success<string | undefined> {\n    return succeed(message);\n  }\n}\n"]}
+{"version":3,"file":"retainingLogger.js","sourceRoot":"","sources":["../../../src/packlets/logging/retainingLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAA4B,OAAO,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAoB,SAAS,EAAE,MAAM,UAAU,CAAC;AAoDnE;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAAgB,SAAQ,UAAU;IAuB7C;;;;;;OAMG;IACH,YACE,WAA6B,QAAQ,EACrC,aAAqB,IAAI,EACzB,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QAEpC,KAAK,CAAC,QAAQ,CAAC,CAAC;QA5BlB;;;;;WAKG;QACK,aAAQ,GAAW,CAAC,CAAC;QAuB3B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,KAAK,GAAG,IAAI,mBAAmB,CAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACnE,CAAC;IAED;;OAEG;IACH,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACI,UAAU,CAAC,OAA4B;QAC5C,MAAM,QAAQ,GAAG,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ,CAAC;QACnC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;YACtB,QAAQ,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ;YAC3B,MAAM,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;YAChF,KAAK,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,KAAK;SACtB,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACI,KAAK;QACV,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;OAGG;IACO,cAAc,CACtB,KAAsB,EACtB,SAAiB,EACjB,OAAgB,EAChB,UAA8B;QAE9B,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnB,MAAM,MAAM,GAAe;YACzB,GAAG,EAAE,IAAI,CAAC,QAAQ;YAClB,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE;YACtB,KAAK;YACL,OAAO,EAAE,SAAS;YAClB,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,UAAU,CAAC;SAC/B,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACO,IAAI,CAAC,OAAe,EAAE,OAAwB;QACtD,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF","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 */\nimport { MessageLogLevel, Success, succeed } from '../base';\nimport { RetainingRingBuffer } from '../collections';\nimport { LoggerBase, ReporterLogLevel, shouldLog } from './logger';\n\n/**\n * A retained log record. Preserves the level and an ordering cursor so consumers\n * can filter by severity and page incrementally.\n * @public\n */\nexport interface ILogRecord {\n  /**\n   * Monotonic 1-based sequence number, stable across ring eviction.\n   */\n  readonly seq: number;\n  /**\n   * Milliseconds since epoch when the record was logged (from the injected clock).\n   */\n  readonly timestamp: number;\n  /**\n   * The level the record was logged at.\n   */\n  readonly level: MessageLogLevel;\n  /**\n   * The formatted message (same formatting {@link Logging.LoggerBase._format | LoggerBase._format} produces).\n   */\n  readonly message: string;\n  /**\n   * The raw structured inputs `[message, ...parameters]` before formatting.\n   */\n  readonly args?: readonly unknown[];\n}\n\n/**\n * Options for {@link Logging.RetainingLogger.getRecords | RetainingLogger.getRecords}.\n * @public\n */\nexport interface IGetRecordsOptions {\n  /**\n   * If supplied, only records whose level would be emitted at this threshold\n   * (per {@link Logging.shouldLog | shouldLog}) are returned.\n   */\n  readonly minLevel?: ReporterLogLevel;\n  /**\n   * If supplied, only records with `seq > sinceSeq` are returned, enabling\n   * incremental paging from a previously-held cursor.\n   */\n  readonly sinceSeq?: number;\n  /**\n   * If supplied, returns at most this many records — the most recent N (tail),\n   * still ordered oldest-first.\n   */\n  readonly limit?: number;\n}\n\n/**\n * An {@link Logging.ILogger | ILogger} that retains structured log records in a bounded\n * most-recent-N ring, with a query API supporting min-severity filtering and\n * since-cursor incremental paging.\n *\n * @remarks\n * Records are captured via the {@link Logging.LoggerBase._logStructured | _logStructured} hook,\n * so the full structured form (`level` + formatted `message` + raw `args`) is retained.\n * The logger emits nowhere itself — pair it with a {@link Logging.MultiLogger | MultiLogger}\n * to also feed a {@link Logging.ConsoleLogger | ConsoleLogger} or other durable sink.\n *\n * @public\n */\nexport class RetainingLogger extends LoggerBase {\n  /**\n   * Injected clock used to timestamp records.\n   * @internal\n   */\n  private readonly _now: () => number;\n\n  /**\n   * The monotonic sequence counter. The logger owns `seq` assignment and\n   * increments this before each push so the buffer receives strictly increasing\n   * sequence numbers.\n   * @internal\n   */\n  private _nextSeq: number = 0;\n\n  /**\n   * The backing ring buffer. Retains up to `maxRecords` log records, evicting\n   * the oldest when full. The buffer is a pure seq-ring — it does not assign\n   * `seq`; the logger does.\n   * @internal\n   */\n  private readonly _ring: RetainingRingBuffer<ILogRecord>;\n\n  /**\n   * Creates a new retaining logger.\n   * @param logLevel - The level of logging to retain. Defaults to `'detail'` to capture\n   * broadly and filter at query time.\n   * @param maxRecords - The maximum number of records to retain. Defaults to `1000`.\n   * @param now - Injected clock returning milliseconds since epoch. Defaults to `Date.now`.\n   */\n  public constructor(\n    logLevel: ReporterLogLevel = 'detail',\n    maxRecords: number = 1000,\n    now: () => number = () => Date.now()\n  ) {\n    super(logLevel);\n    this._now = now;\n    this._ring = new RetainingRingBuffer<ILogRecord>({ maxRecords });\n  }\n\n  /**\n   * The retained records, oldest-first.\n   */\n  public get records(): ReadonlyArray<ILogRecord> {\n    return this._ring.records;\n  }\n\n  /**\n   * The most recently assigned sequence number. A client can hold this value and\n   * pass it as `sinceSeq` to page only records logged afterward.\n   */\n  public get lastSeq(): number {\n    return this._ring.lastSeq;\n  }\n\n  /**\n   * Returns retained records, oldest-first, optionally filtered.\n   * @param options - {@link Logging.IGetRecordsOptions | Filtering and paging options}.\n   * @returns The matching records, oldest-first.\n   */\n  public getRecords(options?: IGetRecordsOptions): ReadonlyArray<ILogRecord> {\n    const minLevel = options?.minLevel;\n    return this._ring.query({\n      sinceSeq: options?.sinceSeq,\n      filter: minLevel !== undefined ? (r) => shouldLog(r.level, minLevel) : undefined,\n      limit: options?.limit\n    });\n  }\n\n  /**\n   * Clears all retained records. Does NOT reset the sequence counter, so a client\n   * holding a `sinceSeq` cursor never re-sees a sequence number.\n   */\n  public clear(): void {\n    this._ring.clear();\n  }\n\n  /**\n   * {@inheritDoc Logging.LoggerBase._logStructured}\n   * @internal\n   */\n  protected _logStructured(\n    level: MessageLogLevel,\n    formatted: string,\n    message: unknown,\n    parameters: readonly unknown[]\n  ): void {\n    this._nextSeq += 1;\n    const record: ILogRecord = {\n      seq: this._nextSeq,\n      timestamp: this._now(),\n      level,\n      message: formatted,\n      args: [message, ...parameters]\n    };\n    this._ring.push(record);\n  }\n\n  /**\n   * {@inheritDoc Logging.LoggerBase._log}\n   * @internal\n   */\n  protected _log(message: string, __level: MessageLogLevel): Success<string | undefined> {\n    return succeed(message);\n  }\n}\n"]}

package/dist/packlets/logging-interface/index.js

@@ -0,0 +1,11 @@
+/**
+ * Type guard that checks whether a logger implements {@link IDetailLogger}.
+ * @param logger - The logger to check.
+ * @returns `true` if the logger implements `IDetailLogger`.
+ * @public
+ */
+export function isDetailLogger(logger) {
+    return (typeof logger.errorWithDetail === 'function' &&
+        typeof logger.warnWithDetail === 'function');
+}
+//# sourceMappingURL=index.js.map

package/dist/packlets/logging-interface/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/logging-interface/index.ts"],"names":[],"mappings":"AA8GA;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe;IAC5C,OAAO,CACL,OAAQ,MAAwB,CAAC,eAAe,KAAK,UAAU;QAC/D,OAAQ,MAAwB,CAAC,cAAc,KAAK,UAAU,CAC/D,CAAC;AACJ,CAAC","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 */\nimport { MessageLogLevel, Success } from '../base';\n\n/**\n * The level of logging to be used.\n * @public\n */\nexport type ReporterLogLevel = 'all' | 'detail' | 'info' | 'warning' | 'error' | 'silent';\n\n/**\n * Generic Result-aware logger interface with multiple levels of logging.\n * @public\n */\nexport interface ILogger {\n  /**\n   * The level of logging to be used.\n   */\n  readonly logLevel: ReporterLogLevel;\n\n  /**\n   * Logs a message at the given level.\n   * @param level - The level of the message.\n   * @param message - The message to log.\n   * @param parameters - The parameters to log.\n   * @returns `Success` with the logged message if the level is enabled, or\n   * `Success` with `undefined` if the message is suppressed.\n   */\n  log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;\n\n  /**\n   * Logs a detail message.\n   * @param message - The message to log.\n   * @param parameters - The parameters to log.\n   * @returns `Success` with the logged message if the level is enabled, or\n   * `Success` with `undefined` if the message is suppressed.\n   */\n  detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;\n\n  /**\n   * Logs an info message.\n   * @param message - The message to log.\n   * @param parameters - The parameters to log.\n   * @returns `Success` with the logged message if the level is enabled, or\n   * `Success` with `undefined` if the message is suppressed.\n   */\n  info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;\n\n  /**\n   * Logs a warning message.\n   * @param message - The message to log.\n   * @param parameters - The parameters to log.\n   * @returns `Success` with the logged message if the level is enabled, or\n   * `Success` with `undefined` if the message is suppressed.\n   */\n  warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;\n\n  /**\n   * Logs an error message.\n   * @param message - The message to log.\n   * @param parameters - The parameters to log.\n   * @returns `Success` with the logged message if the level is enabled, or\n   * `Success` with `undefined` if the message is suppressed.\n   */\n  error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;\n}\n\n/**\n * Extended logger interface that supports logging a short summary message at a\n * primary level (error/warn) while emitting the full detail at `detail` level.\n *\n * The detail is suppressed by default (requires log level `'detail'` or `'all'`),\n * keeping the primary log clean while preserving the full context for debugging.\n * @public\n */\nexport interface IDetailLogger extends ILogger {\n  /**\n   * Logs a short error summary at `error` level, then emits `detail` at `detail` level.\n   * @param message - Short human-readable summary.\n   * @param detail - Full detail (e.g. raw converter error) logged at `detail` level.\n   */\n  errorWithDetail(message: string, detail: unknown): Success<string | undefined>;\n\n  /**\n   * Logs a short warning summary at `warning` level, then emits `detail` at `detail` level.\n   * @param message - Short human-readable summary.\n   * @param detail - Full detail logged at `detail` level.\n   */\n  warnWithDetail(message: string, detail: unknown): Success<string | undefined>;\n}\n\n/**\n * Type guard that checks whether a logger implements {@link IDetailLogger}.\n * @param logger - The logger to check.\n * @returns `true` if the logger implements `IDetailLogger`.\n * @public\n */\nexport function isDetailLogger(logger: ILogger): logger is IDetailLogger {\n  return (\n    typeof (logger as IDetailLogger).errorWithDetail === 'function' &&\n    typeof (logger as IDetailLogger).warnWithDetail === 'function'\n  );\n}\n"]}

package/dist/ts-utils.d.ts

@@ -422,10 +422,13 @@ declare function asValidator<T, TC = unknown>(converterOrValidator: Converter<T,
 
 /**
  * Async continuation callback to be called in the event that a
- * {@link Result} fails, returning a `Promise` of a new {@link Result}.
+ * {@link Result} fails, returning a `PromiseLike` of a new {@link Result}.
+ * @remarks
+ * See {@link AsyncSuccessContinuation} for the rationale behind accepting
+ * any `PromiseLike<Result<T>>` rather than only a `Promise<Result<T>>`.
  * @public
  */
-export declare type AsyncFailureContinuation<T> = (message: string) => Promise<Result<T>>;
+export declare type AsyncFailureContinuation<T> = (message: string) => PromiseLike<Result<T>>;
 
 /**
  * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both
@@ -450,14 +453,17 @@ export declare type AsyncFailureContinuation<T> = (message: string) => Promise<R
 export declare class AsyncResult<T> implements PromiseLike<Result<T>> {
     private readonly _promise;
     /**
-     * Constructs an {@link AsyncResult} wrapping the supplied promise.
+     * 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` that resolves to a {@link Result}.
+     * @param promise - A `Promise` (or `PromiseLike`) that resolves to a
+     * {@link Result}.
      */
-    constructor(promise: Promise<Result<T>>);
+    constructor(promise: PromiseLike<Result<T>>);
     /**
      * Calls a supplied {@link SuccessContinuation | success continuation} if
      * the wrapped result is successful.
@@ -540,10 +546,18 @@ export declare class AsyncResult<T> implements PromiseLike<Result<T>> {
 
 /**
  * Async continuation callback to be called in the event that a
- * {@link Result} is successful, returning a `Promise` of a new {@link Result}.
+ * {@link Result} is successful, returning a `PromiseLike` of a new
+ * {@link Result}.
+ * @remarks
+ * Typed as `PromiseLike<Result<TN>>` rather than `Promise<Result<TN>>` so
+ * callers can return the result of {@link captureAsyncResult} (which is an
+ * {@link AsyncResult}, itself a `PromiseLike<Result<TN>>`) directly from a
+ * `thenOnSuccess` callback without an `async` wrapper to coerce the
+ * contextual return type back through `Awaited<>`. The continuation result
+ * is always wrapped into an {@link AsyncResult}, so chaining is unaffected.
  * @public
  */
-export declare type AsyncSuccessContinuation<T, TN> = (value: T) => Promise<Result<TN>>;
+export declare type AsyncSuccessContinuation<T, TN> = (value: T) => PromiseLike<Result<TN>>;
 
 declare namespace Base {
     export {
@@ -592,10 +606,13 @@ declare class BaseConverter<T, TC = unknown> implements Converter<T, TC> {
      * @param from - The `unknown` to be converted
      * @param context - An optional conversion context of type `<TC>` to be used in
      * the conversion.
+     * @param selfOverride - An optional override for the `self` reference passed to the
+     * converter function, enabling outer converters (e.g. discriminated-object) to thread
+     * themselves through to per-arm converters for recursive parsing.
      * @returns A {@link Result} with a {@link Success} and a value on success or an
      * {@link Failure} with a a message on failure.
      */
-    convert(from: unknown, context?: TC): Result<T>;
+    convert(from: unknown, context?: TC, selfOverride?: Converter<T, TC>): Result<T>;
     /**
      * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
      *
@@ -992,12 +1009,25 @@ declare class CacheInvalidatingResultMapWrapper<TK extends string, TSRC, TTARGET
 /**
  * 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 Returns a `Promise` of {@link Success} with a value of type `<T>` on
- * success, or {@link Failure} with the thrown error message if `func` throws or rejects.
+ * @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
  */
-export declare function captureAsyncResult<T>(func: () => Promise<T>): Promise<Result<T>>;
+export declare function captureAsyncResult<T>(func: () => Promise<T>): AsyncResult<T>;
 
 /**
  * Wraps a function which might throw to convert exception results
@@ -1161,6 +1191,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               ConversionErrorHandling,
               IReadOnlyConvertingResultMapConstructorParams,
               ReadOnlyConvertingResultMap,
+              IRetainedRecord,
+              IRetainingRingBufferQuery,
+              IRetainingRingBufferCreateParams,
+              RetainingRingBuffer,
               IResultMapConstructorParams,
               ResultMapValueFactory,
               IResultMap,
@@ -1584,10 +1618,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * @param from - The `unknown` to be converted
                * @param context - An optional conversion context of type `<TC>` to be used in
                * the conversion.
+               * @param selfOverride - An optional override for the `self` reference passed to the
+               * converter function, enabling outer converters (e.g. discriminated-object) to thread
+               * themselves through to per-arm converters for recursive parsing.
                * @returns A {@link Result} with a {@link Success} and a value on success or an
                * {@link Failure} with a a message on failure.
                */
-              convert(from: unknown, context?: TC): Result<T>;
+              convert(from: unknown, context?: TC, selfOverride?: Converter<T, TC>): Result<T>;
               /**
                * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
                *
@@ -2276,6 +2313,9 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            *
            * If the source is not an object, the discriminator property is missing, or the discriminator has
            * a value not present in the converters, conversion fails and returns {@link Failure | Failure} with more information.
+           *
+           * The `self` reference of the outer converter is threaded through to per-arm converter invocations,
+           * enabling recursive discriminated-union parsers where arms recurse via `self`.
            * @param discriminatorProp - Name of the property used to discriminate types.
            * @param converters - {@link Converters.DiscriminatedObjectConverters | String-keyed record of converters and validators}
            * to invoke, where each key corresponds to a value of the discriminator property.
@@ -4005,6 +4045,63 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare type IResultValueType<T> = T extends IResult<infer TV> ? TV : never;
 
+          /**
+           * Minimal structural contract a {@link RetainingRingBuffer} record must satisfy:
+           * a monotonic `seq` the buffer pages on. Records carry their own `seq` (assigned
+           * by the caller) so the buffer is agnostic about how records are minted — a logger
+           * assigns `seq` from its own counter, an observability layer assigns a library-global
+           * `seq` shared across several buffers, etc.
+           * @public
+           */
+          export declare interface IRetainedRecord {
+              /**
+               * Monotonic sequence number, assigned by the caller. The buffer requires
+               * **strictly increasing** `seq` across successive {@link RetainingRingBuffer.push | push}
+               * calls — `sinceSeq` cursor paging uses a strict `seq > sinceSeq` filter, so
+               * duplicate `seq` values held by a consumer cursor would never be re-yielded
+               * if pushed afterward. {@link RetainingRingBuffer.lastSeq | lastSeq} likewise
+               * advances only past values strictly greater than its current value.
+               */
+              readonly seq: number;
+          }
+
+          /**
+           * Construction options for {@link RetainingRingBuffer}.
+           * @public
+           */
+          export declare interface IRetainingRingBufferCreateParams {
+              /**
+               * The maximum number of records retained before the oldest is overwritten.
+               * Defaults to `1000`. Normalized to a positive integer: a fractional value is
+               * floored toward the integer below (`2.9` → `2`), and a non-finite or sub-1
+               * value is floored to `1` (the ring requires a positive integer capacity to
+               * be well-defined).
+               */
+              readonly maxRecords?: number;
+          }
+
+          /**
+           * Query options for {@link RetainingRingBuffer.query}.
+           * @public
+           */
+          export declare interface IRetainingRingBufferQuery<T extends IRetainedRecord> {
+              /**
+               * If supplied, only records with `seq > sinceSeq` are returned, enabling
+               * incremental paging from a previously-held cursor.
+               */
+              readonly sinceSeq?: number;
+              /**
+               * If supplied, returns at most this many records — the most recent N (tail),
+               * still ordered oldest-first.
+               */
+              readonly limit?: number;
+              /**
+               * If supplied, only records for which the predicate returns `true` are
+               * returned. Applied before `limit`, so `limit` bounds the filtered tail.
+               */
+              readonly filter?: (record: T) => boolean;
+          }
+
           /**
            * Helper function to create a {@link Converter | Converter} from a supplied type guard function.
            * @param description - a description of the thing to be validated for use in error messages
@@ -5958,40 +6055,25 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                        * @public
                        */
                       declare class RetainingLogger extends LoggerBase {
-                          /**
-                           * The fixed ring capacity — the maximum number of records retained before the
-                           * oldest is overwritten. A positive integer (see the constructor normalization).
-                           * @internal
-                           */
-                          private readonly _capacity;
                           /**
                            * Injected clock used to timestamp records.
                            * @internal
                            */
                           private readonly _now;
                           /**
-                           * The backing store, used as a circular buffer. Grows lazily up to `_capacity`,
-                           * after which records overwrite the oldest slot in place — eviction is O(1), with
-                           * no `shift()` re-indexing regardless of capacity.
+                           * The monotonic sequence counter. The logger owns `seq` assignment and
+                           * increments this before each push so the buffer receives strictly increasing
+                           * sequence numbers.
                            * @internal
                            */
-                          private _buffer;
-                          /**
-                           * Index of the oldest retained record within `_buffer` once the ring is full.
-                           * @internal
-                           */
-                          private _head;
+                          private _nextSeq;
                           /**
-                           * The number of valid records currently retained (`<= _capacity`).
+                           * The backing ring buffer. Retains up to `maxRecords` log records, evicting
+                           * the oldest when full. The buffer is a pure seq-ring — it does not assign
+                           * `seq`; the logger does.
                            * @internal
                            */
-                          private _count;
-                          /**
-                           * The most recently assigned sequence number; monotonic, stable across eviction
-                           * and {@link Logging.RetainingLogger.clear | clear()}.
-                           * @internal
-                           */
-                          private _lastSeq;
+                          private readonly _ring;
                           /**
                            * Creates a new retaining logger.
                            * @param logLevel - The level of logging to retain. Defaults to `'detail'` to capture
@@ -6020,11 +6102,6 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                            * holding a `sinceSeq` cursor never re-sees a sequence number.
                            */
                           clear(): void;
-                          /**
-                           * Materializes the ring into a plain oldest-first array.
-                           * @internal
-                           */
-                          private _toOrderedArray;
                           /**
                            * {@inheritDoc Logging.LoggerBase._logStructured}
                            * @internal
@@ -6037,6 +6114,99 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                           protected _log(message: string, __level: MessageLogLevel): Success<string | undefined>;
                       }
 
+                      /**
+                       * A generic bounded most-recent-N ring of records, with monotonic-`seq` cursor
+                       * paging and predicate filtering.
+                       *
+                       * @remarks
+                       * The buffer is a pure storage substrate: the caller mints each record (assigning
+                       * its own `seq` and any other fields) and {@link RetainingRingBuffer.push | push}es
+                       * it. The buffer never reshapes a record — it only retains, evicts the oldest when
+                       * full (O(1), no `shift()` re-indexing regardless of capacity), and answers queries.
+                       *
+                       * Separating record minting from retention lets one `seq` authority feed several
+                       * buffers consistently (e.g. an observability layer that assigns a library-global
+                       * `seq` and fans the same record out to multiple retaining stores), and lets a
+                       * single-authority consumer (e.g. a logger) own its own `seq` counter. It is the
+                       * shared mechanism beneath `RetainingLogger` and
+                       * any schema-aware observation store.
+                       *
+                       * @public
+                       */
+                      export declare class RetainingRingBuffer<T extends IRetainedRecord> {
+                          /**
+                           * The fixed ring capacity — the maximum number of records retained before the
+                           * oldest is overwritten. A positive integer (see the constructor normalization).
+                           * @internal
+                           */
+                          private readonly _capacity;
+                          /**
+                           * The backing store, used as a circular buffer. Grows lazily up to `_capacity`,
+                           * after which records overwrite the oldest slot in place — eviction is O(1), with
+                           * no `shift()` re-indexing regardless of capacity.
+                           * @internal
+                           */
+                          private _buffer;
+                          /**
+                           * Index of the oldest retained record within `_buffer` once the ring is full.
+                           * @internal
+                           */
+                          private _head;
+                          /**
+                           * The number of valid records currently retained (`<= _capacity`).
+                           * @internal
+                           */
+                          private _count;
+                          /**
+                           * The highest `seq` ever pushed; monotonic, stable across eviction and
+                           * {@link RetainingRingBuffer.clear | clear()}.
+                           * @internal
+                           */
+                          private _lastSeq;
+                          /**
+                           * Creates a new retaining ring buffer.
+                           * @param params - {@link IRetainingRingBufferCreateParams | Construction options}.
+                           */
+                          constructor(params?: IRetainingRingBufferCreateParams);
+                          /**
+                           * The number of records currently retained.
+                           */
+                          get size(): number;
+                          /**
+                           * The highest `seq` pushed so far. A client can hold this value and pass it as
+                           * `sinceSeq` to page only records pushed afterward. Stable across eviction and
+                           * {@link RetainingRingBuffer.clear | clear()}.
+                           */
+                          get lastSeq(): number;
+                          /**
+                           * The retained records, oldest-first.
+                           */
+                          get records(): ReadonlyArray<T>;
+                          /**
+                           * Retains a record, evicting the oldest if the ring is full.
+                           * @param record - The record to retain. Its `seq` should be greater than the
+                           * `seq` of the previously-pushed record so cursor paging stays monotonic.
+                           * @returns The same record, for call-site chaining.
+                           */
+                          push(record: T): T;
+                          /**
+                           * Returns retained records, oldest-first, optionally filtered and paged.
+                           * @param query - {@link IRetainingRingBufferQuery | Filtering and paging options}.
+                           * @returns The matching records, oldest-first.
+                           */
+                          query(query?: IRetainingRingBufferQuery<T>): ReadonlyArray<T>;
+                          /**
+                           * Clears all retained records. Does NOT reset {@link RetainingRingBuffer.lastSeq | lastSeq},
+                           * so a client holding a `sinceSeq` cursor never re-sees a sequence number.
+                           */
+                          clear(): void;
+                          /**
+                           * Materializes the ring into a plain oldest-first array.
+                           * @internal
+                           */
+                          private _toOrderedArray;
+                      }
+
                       /**
                        * Compares two log levels.
                        * @param message - The first log level.

package/lib/index.d.ts

@@ -3,9 +3,9 @@ import * as Conversion from './packlets/conversion';
 import * as Hash from './packlets/hash';
 import * as Logging from './packlets/logging';
 import * as Validation from './packlets/validation';
-import { AggregatedResultMap, Collector, ICollectible, ConvertingCollector, IReadOnlyResultMap, ResultMap, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap } from './packlets/collections';
+import { AggregatedResultMap, Collector, ICollectible, ConvertingCollector, IReadOnlyResultMap, IRetainedRecord, IRetainingRingBufferCreateParams, IRetainingRingBufferQuery, ResultMap, RetainingRingBuffer, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap } from './packlets/collections';
 import { Converter, Converters, ObjectConverter, StringConverter } from './packlets/conversion';
 import { Validator, Validators } from './packlets/validation';
 export * from './packlets/base';
-export { AggregatedResultMap, Collections, Collector, ConvertingCollector, Conversion, Converter, Converters, Hash, ICollectible, IReadOnlyResultMap, Logging, ObjectConverter, ResultMap, StringConverter, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap, Validation, Validator, Validators };
+export { AggregatedResultMap, Collections, Collector, ConvertingCollector, Conversion, Converter, Converters, Hash, ICollectible, IReadOnlyResultMap, Logging, IRetainedRecord, IRetainingRingBufferCreateParams, IRetainingRingBufferQuery, ObjectConverter, ResultMap, RetainingRingBuffer, StringConverter, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap, Validation, Validator, Validators };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,WAAW,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,SAAS,EACT,mBAAmB,EACnB,6BAA6B,EAC7B,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE9D,cAAc,iBAAiB,CAAC;AAChC,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,UAAU,EACV,IAAI,EACJ,YAAY,EACZ,kBAAkB,EAClB,OAAO,EACP,eAAe,EACf,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,6BAA6B,EAC7B,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,UAAU,EACX,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,WAAW,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,gCAAgC,EAChC,yBAAyB,EACzB,SAAS,EACT,mBAAmB,EACnB,mBAAmB,EACnB,6BAA6B,EAC7B,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE9D,cAAc,iBAAiB,CAAC;AAChC,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,UAAU,EACV,IAAI,EACJ,YAAY,EACZ,kBAAkB,EAClB,OAAO,EACP,eAAe,EACf,gCAAgC,EAChC,yBAAyB,EACzB,eAAe,EACf,SAAS,EACT,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,6BAA6B,EAC7B,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,UAAU,EACX,CAAC"}

package/lib/index.js

@@ -57,7 +57,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Validators = exports.Validation = exports.ValidatingResultMap = exports.ValidatingConvertingCollector = exports.ValidatingCollector = exports.StringConverter = exports.ResultMap = exports.ObjectConverter = exports.Logging = exports.Hash = exports.Converters = exports.Conversion = exports.ConvertingCollector = exports.Collector = exports.Collections = exports.AggregatedResultMap = void 0;
+exports.Validators = exports.Validation = exports.ValidatingResultMap = exports.ValidatingConvertingCollector = exports.ValidatingCollector = exports.StringConverter = exports.RetainingRingBuffer = exports.ResultMap = exports.ObjectConverter = exports.Logging = exports.Hash = exports.Converters = exports.Conversion = exports.ConvertingCollector = exports.Collector = exports.Collections = exports.AggregatedResultMap = void 0;
 const Collections = __importStar(require("./packlets/collections"));
 exports.Collections = Collections;
 const Conversion = __importStar(require("./packlets/conversion"));
@@ -73,6 +73,7 @@ Object.defineProperty(exports, "AggregatedResultMap", { enumerable: true, get: f
 Object.defineProperty(exports, "Collector", { enumerable: true, get: function () { return collections_1.Collector; } });
 Object.defineProperty(exports, "ConvertingCollector", { enumerable: true, get: function () { return collections_1.ConvertingCollector; } });
 Object.defineProperty(exports, "ResultMap", { enumerable: true, get: function () { return collections_1.ResultMap; } });
+Object.defineProperty(exports, "RetainingRingBuffer", { enumerable: true, get: function () { return collections_1.RetainingRingBuffer; } });
 Object.defineProperty(exports, "ValidatingCollector", { enumerable: true, get: function () { return collections_1.ValidatingCollector; } });
 Object.defineProperty(exports, "ValidatingConvertingCollector", { enumerable: true, get: function () { return collections_1.ValidatingConvertingCollector; } });
 Object.defineProperty(exports, "ValidatingResultMap", { enumerable: true, get: function () { return collections_1.ValidatingResultMap; } });

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,oEAAsD;AAuBpD,kCAAW;AAtBb,kEAAoD;AAyBlD,gCAAU;AAxBZ,sDAAwC;AA2BtC,oBAAI;AA1BN,4DAA8C;AA6B5C,0BAAO;AA5BT,kEAAoD;AAmClD,gCAAU;AAjCZ,wDAUgC;AAM9B,oGAfA,iCAAmB,OAeA;AAEnB,0FAhBA,uBAAS,OAgBA;AACT,oGAfA,iCAAmB,OAeA;AASnB,0FAtBA,uBAAS,OAsBA;AAET,oGAvBA,iCAAmB,OAuBA;AACnB,8GAvBA,2CAA6B,OAuBA;AAC7B,oGAvBA,iCAAmB,OAuBA;AArBrB,sDAAgG;AAW9F,2FAXkB,uBAAU,OAWlB;AAKV,gGAhB8B,4BAAe,OAgB9B;AAEf,gGAlB+C,4BAAe,OAkB/C;AAjBjB,sDAA8D;AAuB5D,2FAvBkB,uBAAU,OAuBlB;AArBZ,kDAAgC","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 * as Collections from './packlets/collections';\nimport * as Conversion from './packlets/conversion';\nimport * as Hash from './packlets/hash';\nimport * as Logging from './packlets/logging';\nimport * as Validation from './packlets/validation';\n\nimport {\n  AggregatedResultMap,\n  Collector,\n  ICollectible,\n  ConvertingCollector,\n  IReadOnlyResultMap,\n  ResultMap,\n  ValidatingCollector,\n  ValidatingConvertingCollector,\n  ValidatingResultMap\n} from './packlets/collections';\nimport { Converter, Converters, ObjectConverter, StringConverter } from './packlets/conversion';\nimport { Validator, Validators } from './packlets/validation';\n\nexport * from './packlets/base';\nexport {\n  AggregatedResultMap,\n  Collections,\n  Collector,\n  ConvertingCollector,\n  Conversion,\n  Converter,\n  Converters,\n  Hash,\n  ICollectible,\n  IReadOnlyResultMap,\n  Logging,\n  ObjectConverter,\n  ResultMap,\n  StringConverter,\n  ValidatingCollector,\n  ValidatingConvertingCollector,\n  ValidatingResultMap,\n  Validation,\n  Validator,\n  Validators\n};\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,oEAAsD;AA2BpD,kCAAW;AA1Bb,kEAAoD;AA6BlD,gCAAU;AA5BZ,sDAAwC;AA+BtC,oBAAI;AA9BN,4DAA8C;AAiC5C,0BAAO;AAhCT,kEAAoD;AA2ClD,gCAAU;AAzCZ,wDAcgC;AAM9B,oGAnBA,iCAAmB,OAmBA;AAEnB,0FApBA,uBAAS,OAoBA;AACT,oGAnBA,iCAAmB,OAmBA;AAYnB,0FA1BA,uBAAS,OA0BA;AACT,oGA1BA,iCAAmB,OA0BA;AAEnB,oGA3BA,iCAAmB,OA2BA;AACnB,8GA3BA,2CAA6B,OA2BA;AAC7B,oGA3BA,iCAAmB,OA2BA;AAzBrB,sDAAgG;AAW9F,2FAXkB,uBAAU,OAWlB;AAQV,gGAnB8B,4BAAe,OAmB9B;AAGf,gGAtB+C,4BAAe,OAsB/C;AArBjB,sDAA8D;AA2B5D,2FA3BkB,uBAAU,OA2BlB;AAzBZ,kDAAgC","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 * as Collections from './packlets/collections';\nimport * as Conversion from './packlets/conversion';\nimport * as Hash from './packlets/hash';\nimport * as Logging from './packlets/logging';\nimport * as Validation from './packlets/validation';\n\nimport {\n  AggregatedResultMap,\n  Collector,\n  ICollectible,\n  ConvertingCollector,\n  IReadOnlyResultMap,\n  IRetainedRecord,\n  IRetainingRingBufferCreateParams,\n  IRetainingRingBufferQuery,\n  ResultMap,\n  RetainingRingBuffer,\n  ValidatingCollector,\n  ValidatingConvertingCollector,\n  ValidatingResultMap\n} from './packlets/collections';\nimport { Converter, Converters, ObjectConverter, StringConverter } from './packlets/conversion';\nimport { Validator, Validators } from './packlets/validation';\n\nexport * from './packlets/base';\nexport {\n  AggregatedResultMap,\n  Collections,\n  Collector,\n  ConvertingCollector,\n  Conversion,\n  Converter,\n  Converters,\n  Hash,\n  ICollectible,\n  IReadOnlyResultMap,\n  Logging,\n  IRetainedRecord,\n  IRetainingRingBufferCreateParams,\n  IRetainingRingBufferQuery,\n  ObjectConverter,\n  ResultMap,\n  RetainingRingBuffer,\n  StringConverter,\n  ValidatingCollector,\n  ValidatingConvertingCollector,\n  ValidatingResultMap,\n  Validation,\n  Validator,\n  Validators\n};\n"]}

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

@@ -915,16 +915,27 @@ export declare function _errorMessage(err: unknown): string;
 export declare function captureResult<T>(func: () => T): Result<T>;
 /**
  * Async continuation callback to be called in the event that a
- * {@link Result} is successful, returning a `Promise` of a new {@link Result}.
+ * {@link Result} is successful, returning a `PromiseLike` of a new
+ * {@link Result}.
+ * @remarks
+ * Typed as `PromiseLike<Result<TN>>` rather than `Promise<Result<TN>>` so
+ * callers can return the result of {@link captureAsyncResult} (which is an
+ * {@link AsyncResult}, itself a `PromiseLike<Result<TN>>`) directly from a
+ * `thenOnSuccess` callback without an `async` wrapper to coerce the
+ * contextual return type back through `Awaited<>`. The continuation result
+ * is always wrapped into an {@link AsyncResult}, so chaining is unaffected.
  * @public
  */
-export type AsyncSuccessContinuation<T, TN> = (value: T) => Promise<Result<TN>>;
+export type AsyncSuccessContinuation<T, TN> = (value: T) => PromiseLike<Result<TN>>;
 /**
  * Async continuation callback to be called in the event that a
- * {@link Result} fails, returning a `Promise` of a new {@link Result}.
+ * {@link Result} fails, returning a `PromiseLike` of a new {@link Result}.
+ * @remarks
+ * See {@link AsyncSuccessContinuation} for the rationale behind accepting
+ * any `PromiseLike<Result<T>>` rather than only a `Promise<Result<T>>`.
  * @public
  */
-export type AsyncFailureContinuation<T> = (message: string) => Promise<Result<T>>;
+export type AsyncFailureContinuation<T> = (message: string) => PromiseLike<Result<T>>;
 /**
  * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both
  * synchronous and asynchronous operations.
@@ -948,14 +959,17 @@ export type AsyncFailureContinuation<T> = (message: string) => Promise<Result<T>
 export declare class AsyncResult<T> implements PromiseLike<Result<T>> {
     private readonly _promise;
     /**
-     * Constructs an {@link AsyncResult} wrapping the supplied promise.
+     * 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` that resolves to a {@link Result}.
+     * @param promise - A `Promise` (or `PromiseLike`) that resolves to a
+     * {@link Result}.
      */
-    constructor(promise: Promise<Result<T>>);
+    constructor(promise: PromiseLike<Result<T>>);
     /**
      * Calls a supplied {@link SuccessContinuation | success continuation} if
      * the wrapped result is successful.
@@ -1038,10 +1052,23 @@ export declare class AsyncResult<T> implements PromiseLike<Result<T>> {
 /**
  * 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 Returns a `Promise` of {@link Success} with a value of type `<T>` on
- * success, or {@link Failure} with the thrown error message if `func` throws or rejects.
+ * @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
  */
-export declare function captureAsyncResult<T>(func: () => Promise<T>): Promise<Result<T>>;
+export declare function captureAsyncResult<T>(func: () => Promise<T>): AsyncResult<T>;
 //# sourceMappingURL=result.d.ts.map