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

package/lib/packlets/logging/retainingLogger.d.ts

@@ -62,40 +62,25 @@ export interface IGetRecordsOptions {
  * @public
  */
 export 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.
-     * @internal
-     */
-    private _buffer;
-    /**
-     * Index of the oldest retained record within `_buffer` once the ring is full.
+     * 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 _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
@@ -124,11 +109,6 @@ export declare class RetainingLogger extends LoggerBase {
      * 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

package/lib/packlets/logging/retainingLogger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retainingLogger.d.ts","sourceRoot":"","sources":["../../../src/packlets/logging/retainingLogger.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,eAAe,EAAE,OAAO,EAAW,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAa,MAAM,UAAU,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IAEpC;;;;;OAKG;IACH,OAAO,CAAC,OAAO,CAAoB;IAEnC;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAa;IAE1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAa;IAE3B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAa;IAE7B;;;;;;OAMG;gBAED,QAAQ,GAAE,gBAA2B,EACrC,UAAU,GAAE,MAAa,EACzB,GAAG,GAAE,MAAM,MAAyB;IAUtC;;OAEG;IACH,IAAW,OAAO,IAAI,aAAa,CAAC,UAAU,CAAC,CAE9C;IAED;;;OAGG;IACH,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED;;;;OAIG;IACI,UAAU,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,aAAa,CAAC,UAAU,CAAC;IAgB1E;;;OAGG;IACI,KAAK,IAAI,IAAI;IAMpB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAQvB;;;OAGG;IACH,SAAS,CAAC,cAAc,CACtB,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,SAAS,OAAO,EAAE,GAC7B,IAAI;IAoBP;;;OAGG;IACH,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAGvF"}
+{"version":3,"file":"retainingLogger.d.ts","sourceRoot":"","sources":["../../../src/packlets/logging/retainingLogger.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,eAAe,EAAE,OAAO,EAAW,MAAM,SAAS,CAAC;AAE5D,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAa,MAAM,UAAU,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IAEpC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAa;IAE7B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IAExD;;;;;;OAMG;gBAED,QAAQ,GAAE,gBAA2B,EACrC,UAAU,GAAE,MAAa,EACzB,GAAG,GAAE,MAAM,MAAyB;IAOtC;;OAEG;IACH,IAAW,OAAO,IAAI,aAAa,CAAC,UAAU,CAAC,CAE9C;IAED;;;OAGG;IACH,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED;;;;OAIG;IACI,UAAU,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,aAAa,CAAC,UAAU,CAAC;IAS1E;;;OAGG;IACI,KAAK,IAAI,IAAI;IAIpB;;;OAGG;IACH,SAAS,CAAC,cAAc,CACtB,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,SAAS,OAAO,EAAE,GAC7B,IAAI;IAYP;;;OAGG;IACH,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAGvF"}

package/lib/packlets/logging/retainingLogger.js

@@ -23,6 +23,7 @@ exports.RetainingLogger = void 0;
  * SOFTWARE.
  */
 const base_1 = require("../base");
+const collections_1 = require("../collections");
 const logger_1 = require("./logger");
 /**
  * An {@link Logging.ILogger | ILogger} that retains structured log records in a bounded
@@ -48,46 +49,27 @@ class RetainingLogger extends logger_1.LoggerBase {
     constructor(logLevel = 'detail', maxRecords = 1000, now = () => Date.now()) {
         super(logLevel);
         /**
-         * 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
          */
-        this._buffer = [];
-        /**
-         * Index of the oldest retained record within `_buffer` once the ring is full.
-         * @internal
-         */
-        this._head = 0;
-        /**
-         * The number of valid records currently retained (`<= _capacity`).
-         * @internal
-         */
-        this._count = 0;
-        /**
-         * The most recently assigned sequence number; monotonic, stable across eviction
-         * and {@link Logging.RetainingLogger.clear | clear()}.
-         * @internal
-         */
-        this._lastSeq = 0;
-        // The ring requires a positive integer capacity to be well-defined; a non-finite
-        // or sub-1 value would make the modular index arithmetic meaningless, so floor it
-        // to a sane minimum of 1 rather than crash on degenerate input.
-        this._capacity = Number.isFinite(maxRecords) && maxRecords >= 1 ? Math.floor(maxRecords) : 1;
+        this._nextSeq = 0;
         this._now = now;
+        this._ring = new collections_1.RetainingRingBuffer({ maxRecords });
     }
     /**
      * The retained records, oldest-first.
      */
     get records() {
-        return this._toOrderedArray();
+        return this._ring.records;
     }
     /**
      * The most recently assigned sequence number. A client can hold this value and
      * pass it as `sinceSeq` to page only records logged afterward.
      */
     get lastSeq() {
-        return this._lastSeq;
+        return this._ring.lastSeq;
     }
     /**
      * Returns retained records, oldest-first, optionally filtered.
@@ -95,63 +77,34 @@ class RetainingLogger extends logger_1.LoggerBase {
      * @returns The matching records, oldest-first.
      */
     getRecords(options) {
-        let result = this._toOrderedArray();
-        if ((options === null || options === void 0 ? void 0 : options.minLevel) !== undefined) {
-            const minLevel = options.minLevel;
-            result = result.filter((r) => (0, logger_1.shouldLog)(r.level, minLevel));
-        }
-        if ((options === null || options === void 0 ? void 0 : options.sinceSeq) !== undefined) {
-            const sinceSeq = options.sinceSeq;
-            result = result.filter((r) => r.seq > sinceSeq);
-        }
-        if ((options === null || options === void 0 ? void 0 : options.limit) !== undefined && result.length > options.limit) {
-            result = result.slice(result.length - options.limit);
-        }
-        return result;
+        const minLevel = options === null || options === void 0 ? void 0 : options.minLevel;
+        return this._ring.query({
+            sinceSeq: options === null || options === void 0 ? void 0 : options.sinceSeq,
+            filter: minLevel !== undefined ? (r) => (0, logger_1.shouldLog)(r.level, minLevel) : undefined,
+            limit: options === null || options === void 0 ? void 0 : options.limit
+        });
     }
     /**
      * Clears all retained records. Does NOT reset the sequence counter, so a client
      * holding a `sinceSeq` cursor never re-sees a sequence number.
      */
     clear() {
-        this._buffer = [];
-        this._head = 0;
-        this._count = 0;
-    }
-    /**
-     * Materializes the ring into a plain oldest-first array.
-     * @internal
-     */
-    _toOrderedArray() {
-        const result = [];
-        for (let i = 0; i < this._count; i++) {
-            result.push(this._buffer[(this._head + i) % this._capacity]);
-        }
-        return result;
+        this._ring.clear();
     }
     /**
      * {@inheritDoc Logging.LoggerBase._logStructured}
      * @internal
      */
     _logStructured(level, formatted, message, parameters) {
-        this._lastSeq += 1;
+        this._nextSeq += 1;
         const record = {
-            seq: this._lastSeq,
+            seq: this._nextSeq,
             timestamp: this._now(),
             level,
             message: formatted,
             args: [message, ...parameters]
         };
-        if (this._count < this._capacity) {
-            // Still filling: append to the next free slot (head stays 0 during this phase).
-            this._buffer.push(record);
-            this._count += 1;
-        }
-        else {
-            // Full: overwrite the oldest record in place and advance the head.
-            this._buffer[this._head] = record;
-            this._head = (this._head + 1) % this._capacity;
-        }
+        this._ring.push(record);
     }
     /**
      * {@inheritDoc Logging.LoggerBase._log}

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

@@ -1 +1 @@
-{"version":3,"file":"retainingLogger.js","sourceRoot":"","sources":["../../../src/packlets/logging/retainingLogger.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kCAA4D;AAC5D,qCAAmE;AAoDnE;;;;;;;;;;;;GAYG;AACH,MAAa,eAAgB,SAAQ,mBAAU;IAyC7C;;;;;;OAMG;IACH,YACE,WAA6B,QAAQ,EACrC,aAAqB,IAAI,EACzB,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QAEpC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAvClB;;;;;WAKG;QACK,YAAO,GAAiB,EAAE,CAAC;QAEnC;;;WAGG;QACK,UAAK,GAAW,CAAC,CAAC;QAE1B;;;WAGG;QACK,WAAM,GAAW,CAAC,CAAC;QAE3B;;;;WAIG;QACK,aAAQ,GAAW,CAAC,CAAC;QAe3B,iFAAiF;QACjF,kFAAkF;QAClF,gEAAgE;QAChE,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7F,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IAED;;OAEG;IACH,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACI,UAAU,CAAC,OAA4B;QAC5C,IAAI,MAAM,GAA8B,IAAI,CAAC,eAAe,EAAE,CAAC;QAC/D,IAAI,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ,MAAK,SAAS,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;YAClC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,kBAAS,EAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,QAAQ,MAAK,SAAS,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;YAClC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,KAAK,MAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;YAClE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACI,KAAK;QACV,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IAClB,CAAC;IAED;;;OAGG;IACK,eAAe;QACrB,MAAM,MAAM,GAAiB,EAAE,CAAC;QAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACrC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,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,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YACjC,gFAAgF;YAChF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1B,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,mEAAmE;YACnE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC;YAClC,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;;OAGG;IACO,IAAI,CAAC,OAAe,EAAE,OAAwB;QACtD,OAAO,IAAA,cAAO,EAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF;AA3JD,0CA2JC","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,kCAA4D;AAC5D,gDAAqD;AACrD,qCAAmE;AAoDnE;;;;;;;;;;;;GAYG;AACH,MAAa,eAAgB,SAAQ,mBAAU;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,iCAAmB,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,IAAA,kBAAS,EAAC,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,IAAA,cAAO,EAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF;AAzGD,0CAyGC","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/lib/packlets/logging-interface/index.d.ts

@@ -0,0 +1,87 @@
+import { MessageLogLevel, Success } from '../base';
+/**
+ * The level of logging to be used.
+ * @public
+ */
+export type ReporterLogLevel = 'all' | 'detail' | 'info' | 'warning' | 'error' | 'silent';
+/**
+ * Generic Result-aware logger interface with multiple levels of logging.
+ * @public
+ */
+export interface ILogger {
+    /**
+     * The level of logging to be used.
+     */
+    readonly logLevel: ReporterLogLevel;
+    /**
+     * Logs a message at the given level.
+     * @param level - The level of the message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * Logs a detail message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * Logs an info message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * Logs a warning message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+    /**
+     * Logs an error message.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+}
+/**
+ * Extended logger interface that supports logging a short summary message at a
+ * primary level (error/warn) while emitting the full detail at `detail` level.
+ *
+ * The detail is suppressed by default (requires log level `'detail'` or `'all'`),
+ * keeping the primary log clean while preserving the full context for debugging.
+ * @public
+ */
+export interface IDetailLogger extends ILogger {
+    /**
+     * Logs a short error summary at `error` level, then emits `detail` at `detail` level.
+     * @param message - Short human-readable summary.
+     * @param detail - Full detail (e.g. raw converter error) logged at `detail` level.
+     */
+    errorWithDetail(message: string, detail: unknown): Success<string | undefined>;
+    /**
+     * Logs a short warning summary at `warning` level, then emits `detail` at `detail` level.
+     * @param message - Short human-readable summary.
+     * @param detail - Full detail logged at `detail` level.
+     */
+    warnWithDetail(message: string, detail: unknown): Success<string | undefined>;
+}
+/**
+ * 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 declare function isDetailLogger(logger: ILogger): logger is IDetailLogger;
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/logging-interface/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/logging-interface/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1F;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAEpC;;;;;;;OAOG;IACH,GAAG,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAEtG;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAEjF;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE/E;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE/E;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACjF;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAc,SAAQ,OAAO;IAC5C;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE/E;;;;OAIG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC/E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,aAAa,CAKvE"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/logging-interface/index.ts"],"names":[],"mappings":";;AAoHA,wCAKC;AAXD;;;;;GAKG;AACH,SAAgB,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-utils",
-  "version": "5.1.0-33",
+  "version": "5.1.0-34",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "module": "dist/index.js",
@@ -54,8 +54,8 @@
     "@rushstack/heft-jest-plugin": "1.2.6",
     "eslint-plugin-tsdoc": "~0.5.2",
     "typedoc": "~0.28.16",
-    "@fgv/heft-dual-rig": "5.1.0-33",
-    "@fgv/typedoc-compact-theme": "5.1.0-33"
+    "@fgv/heft-dual-rig": "5.1.0-34",
+    "@fgv/typedoc-compact-theme": "5.1.0-34"
   },
   "repository": {
     "type": "git",