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

package/dist/packlets/collections/retainingRingBuffer.js

@@ -0,0 +1,159 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * 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 class RetainingRingBuffer {
+    /**
+     * Creates a new retaining ring buffer.
+     * @param params - {@link IRetainingRingBufferCreateParams | Construction options}.
+     */
+    constructor(params) {
+        var _a;
+        /**
+         * 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
+         */
+        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 highest `seq` ever pushed; monotonic, stable across eviction and
+         * {@link RetainingRingBuffer.clear | clear()}.
+         * @internal
+         */
+        this._lastSeq = 0;
+        const maxRecords = (_a = params === null || params === void 0 ? void 0 : params.maxRecords) !== null && _a !== void 0 ? _a : 1000;
+        // 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;
+    }
+    /**
+     * The number of records currently retained.
+     */
+    get size() {
+        return this._count;
+    }
+    /**
+     * 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() {
+        return this._lastSeq;
+    }
+    /**
+     * The retained records, oldest-first.
+     */
+    get records() {
+        return this._toOrderedArray();
+    }
+    /**
+     * 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) {
+        if (record.seq > this._lastSeq) {
+            this._lastSeq = record.seq;
+        }
+        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;
+        }
+        return record;
+    }
+    /**
+     * 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) {
+        let result = this._toOrderedArray();
+        if ((query === null || query === void 0 ? void 0 : query.sinceSeq) !== undefined) {
+            const sinceSeq = query.sinceSeq;
+            result = result.filter((r) => r.seq > sinceSeq);
+        }
+        if ((query === null || query === void 0 ? void 0 : query.filter) !== undefined) {
+            result = result.filter(query.filter);
+        }
+        if ((query === null || query === void 0 ? void 0 : query.limit) !== undefined && result.length > query.limit) {
+            result = result.slice(result.length - query.limit);
+        }
+        return result;
+    }
+    /**
+     * 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() {
+        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;
+    }
+}
+//# sourceMappingURL=retainingRingBuffer.js.map

package/dist/packlets/collections/retainingRingBuffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retainingRingBuffer.js","sourceRoot":"","sources":["../../../src/packlets/collections/retainingRingBuffer.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 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\n/**\n * Minimal structural contract a {@link RetainingRingBuffer} record must satisfy:\n * a monotonic `seq` the buffer pages on. Records carry their own `seq` (assigned\n * by the caller) so the buffer is agnostic about how records are minted — a logger\n * assigns `seq` from its own counter, an observability layer assigns a library-global\n * `seq` shared across several buffers, etc.\n * @public\n */\nexport interface IRetainedRecord {\n  /**\n   * Monotonic sequence number, assigned by the caller. The buffer requires\n   * **strictly increasing** `seq` across successive {@link RetainingRingBuffer.push | push}\n   * calls — `sinceSeq` cursor paging uses a strict `seq > sinceSeq` filter, so\n   * duplicate `seq` values held by a consumer cursor would never be re-yielded\n   * if pushed afterward. {@link RetainingRingBuffer.lastSeq | lastSeq} likewise\n   * advances only past values strictly greater than its current value.\n   */\n  readonly seq: number;\n}\n\n/**\n * Query options for {@link RetainingRingBuffer.query}.\n * @public\n */\nexport interface IRetainingRingBufferQuery<T extends IRetainedRecord> {\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   * If supplied, only records for which the predicate returns `true` are\n   * returned. Applied before `limit`, so `limit` bounds the filtered tail.\n   */\n  readonly filter?: (record: T) => boolean;\n}\n\n/**\n * Construction options for {@link RetainingRingBuffer}.\n * @public\n */\nexport interface IRetainingRingBufferCreateParams {\n  /**\n   * The maximum number of records retained before the oldest is overwritten.\n   * Defaults to `1000`. Normalized to a positive integer: a fractional value is\n   * floored toward the integer below (`2.9` → `2`), and a non-finite or sub-1\n   * value is floored to `1` (the ring requires a positive integer capacity to\n   * be well-defined).\n   */\n  readonly maxRecords?: number;\n}\n\n/**\n * A generic bounded most-recent-N ring of records, with monotonic-`seq` cursor\n * paging and predicate filtering.\n *\n * @remarks\n * The buffer is a pure storage substrate: the caller mints each record (assigning\n * its own `seq` and any other fields) and {@link RetainingRingBuffer.push | push}es\n * it. The buffer never reshapes a record — it only retains, evicts the oldest when\n * full (O(1), no `shift()` re-indexing regardless of capacity), and answers queries.\n *\n * Separating record minting from retention lets one `seq` authority feed several\n * buffers consistently (e.g. an observability layer that assigns a library-global\n * `seq` and fans the same record out to multiple retaining stores), and lets a\n * single-authority consumer (e.g. a logger) own its own `seq` counter. It is the\n * shared mechanism beneath `RetainingLogger` and\n * any schema-aware observation store.\n *\n * @public\n */\nexport class RetainingRingBuffer<T extends IRetainedRecord> {\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   * 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: T[] = [];\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 highest `seq` ever pushed; monotonic, stable across eviction and\n   * {@link RetainingRingBuffer.clear | clear()}.\n   * @internal\n   */\n  private _lastSeq: number = 0;\n\n  /**\n   * Creates a new retaining ring buffer.\n   * @param params - {@link IRetainingRingBufferCreateParams | Construction options}.\n   */\n  public constructor(params?: IRetainingRingBufferCreateParams) {\n    const maxRecords = params?.maxRecords ?? 1000;\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  }\n\n  /**\n   * The number of records currently retained.\n   */\n  public get size(): number {\n    return this._count;\n  }\n\n  /**\n   * The highest `seq` pushed so far. A client can hold this value and pass it as\n   * `sinceSeq` to page only records pushed afterward. Stable across eviction and\n   * {@link RetainingRingBuffer.clear | clear()}.\n   */\n  public get lastSeq(): number {\n    return this._lastSeq;\n  }\n\n  /**\n   * The retained records, oldest-first.\n   */\n  public get records(): ReadonlyArray<T> {\n    return this._toOrderedArray();\n  }\n\n  /**\n   * Retains a record, evicting the oldest if the ring is full.\n   * @param record - The record to retain. Its `seq` should be greater than the\n   * `seq` of the previously-pushed record so cursor paging stays monotonic.\n   * @returns The same record, for call-site chaining.\n   */\n  public push(record: T): T {\n    if (record.seq > this._lastSeq) {\n      this._lastSeq = record.seq;\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    return record;\n  }\n\n  /**\n   * Returns retained records, oldest-first, optionally filtered and paged.\n   * @param query - {@link IRetainingRingBufferQuery | Filtering and paging options}.\n   * @returns The matching records, oldest-first.\n   */\n  public query(query?: IRetainingRingBufferQuery<T>): ReadonlyArray<T> {\n    let result: ReadonlyArray<T> = this._toOrderedArray();\n    if (query?.sinceSeq !== undefined) {\n      const sinceSeq = query.sinceSeq;\n      result = result.filter((r) => r.seq > sinceSeq);\n    }\n    if (query?.filter !== undefined) {\n      result = result.filter(query.filter);\n    }\n    if (query?.limit !== undefined && result.length > query.limit) {\n      result = result.slice(result.length - query.limit);\n    }\n    return result;\n  }\n\n  /**\n   * Clears all retained records. Does NOT reset {@link RetainingRingBuffer.lastSeq | lastSeq},\n   * so a client 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(): T[] {\n    const result: T[] = [];\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"]}

package/dist/packlets/collections/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/packlets/collections/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,KAAc;IAEd,OAAO,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC;AACnF,CAAC","sourcesContent":["/*\n * Copyright (c) 2025 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\n/**\n * Determines if a supplied value is an iterable object or some other type.\n * @param value - The value to be tested.\n * @returns `true` if the value is an iterable object, `false` otherwise.\n * @public\n */\nexport function isIterable<TE = unknown, TI extends Iterable<TE> = Iterable<TE>, TO = unknown>(\n  value: TI | TO\n): value is TI {\n  return (value && typeof value === 'object' && Symbol.iterator in value) === true;\n}\n"]}

package/dist/packlets/collections/validatingCollector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingCollector.js","sourceRoot":"","sources":["../../../src/packlets/collections/validatingCollector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAU,MAAM,SAAS,CAAC;AAKhD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAmD1D;;;;GAIG;AACH,MAAM,OAAO,mBAGX,SAAQ,SAAgB;IASxB;;;;OAIG;IACH,YAAmB,MAAoD;;QACrE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,kBAAkB,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QAC7F,KAAK,MAAM,IAAI,IAAI,MAAA,MAAM,CAAC,KAAK,mCAAI,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,yBAAyB,CAGrC,MAAoD;QACpD,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;;;OAIG;IACI,UAAU;QACf,OAAO,IAAI,CAAC;IACd,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2025 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 { captureResult, Result } from '../base';\nimport { CollectibleKey, ICollectible } from './collectible';\nimport { IReadOnlyCollectorValidator } from './collectorValidator';\nimport { IReadOnlyValidatingResultMap } from './validatingResultMap';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { Collector } from './collector';\nimport { CollectorValidator } from './collectorValidator';\n\n/**\n * A read-only interface exposing non-mutating methods of a\n * {@link Collections.ValidatingCollector | ValidatingCollector}.\n * @public\n */\n\nexport interface IReadOnlyValidatingCollector<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>\n> extends IReadOnlyValidatingResultMap<CollectibleKey<TITEM>, TITEM> {\n  /**\n   * A {@link Collections.CollectorValidator | CollectorValidator} which validates keys and values\n   * before inserting them into this collector.\n   */\n  readonly validating: IReadOnlyCollectorValidator<TITEM>;\n\n  /**\n   * Gets the item at a specified index.\n   * @param index - The index of the item to retrieve.\n   * @returns `Success` with the item if it exists, or `Failure` with an error if the index is out of range.\n   */\n  getAt(index: number): Result<TITEM>;\n\n  /**\n   * Gets all items in the collection, ordered by index.\n   * @returns An array of items in the collection, ordered by index.\n   */\n  valuesByIndex(): ReadonlyArray<TITEM>;\n}\n\n/**\n * Parameters for constructing a {@link Collections.ValidatingCollector | ValidatingCollector}.\n * @public\n */\nexport interface IValidatingCollectorConstructorParams<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>\n> {\n  /**\n   * {@inheritDoc Collections.ICollectorValidatorCreateParams.converters}\n   */\n  converters: KeyValueConverters<CollectibleKey<TITEM>, TITEM>;\n\n  /**\n   * {@inheritDoc Collections.ICollectorConstructorParams.items}\n   */\n  items?: unknown[];\n}\n\n/**\n * A {@link Collections.Collector | Collector} with a {@link Collections.CollectorValidator | CollectorValidator}\n * property that enables validated use of the underlying map with weakly-typed keys and values.\n * @public\n */\nexport class ValidatingCollector<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>\n> extends Collector<TITEM> {\n  /**\n   * A {@link Collections.CollectorValidator | CollectorValidator} which validates keys and values\n   * before inserting them into this collector.\n   */\n  public readonly validating: CollectorValidator<TITEM>;\n\n  protected readonly _converters: KeyValueConverters<CollectibleKey<TITEM>, TITEM>;\n\n  /**\n   * Constructs a new {@link Collections.ValidatingCollector | ValidatingConvertingCollector}\n   * from the supplied {@link Collections.IValidatingCollectorConstructorParams | parameters}.\n   * @param params - Required parameters for constructing the collector.\n   */\n  public constructor(params: IValidatingCollectorConstructorParams<TITEM>) {\n    super();\n    this._converters = params.converters;\n    this.validating = new CollectorValidator({ collector: this, converters: params.converters });\n    for (const item of params.items ?? []) {\n      this.validating.getOrAdd(item).orThrow();\n    }\n  }\n\n  /**\n   * Creates a new {@link Collections.ValidatingCollector | ValidatingCollector} instance from\n   * the supplied {@link Collections.IValidatingCollectorConstructorParams | parameters}.\n   * @param params - Required parameters for constructing the collector.\n   * @returns {@link Success} with the new collector if successful, {@link Failure} otherwise.\n   */\n  public static createValidatingCollector<\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    TITEM extends ICollectible<any, any>\n  >(params: IValidatingCollectorConstructorParams<TITEM>): Result<ValidatingCollector<TITEM>> {\n    return captureResult(() => new ValidatingCollector(params));\n  }\n\n  /**\n   * Gets a read-only version of this collector as a\n   * {@link Collections.IReadOnlyValidatingResultMap | read-only map}.\n   * @returns\n   */\n  public toReadOnly(): IReadOnlyValidatingCollector<TITEM> {\n    return this;\n  }\n}\n"]}

package/dist/packlets/collections/validatingConvertingCollector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingConvertingCollector.js","sourceRoot":"","sources":["../../../src/packlets/collections/validatingConvertingCollector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAU,MAAM,SAAS,CAAC;AAEhD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AA8B9E;;;;;GAKG;AACH,MAAM,OAAO,6BAIX,SAAQ,mBAAgC;IASxC;;;;OAIG;IACH,YAAmB,MAAoE;;QACrF,KAAK,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,4BAA4B,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QACvG,KAAK,MAAM,KAAK,IAAI,MAAA,MAAM,CAAC,OAAO,mCAAI,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC9C,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,yBAAyB,CAKrC,MAAoE;QAEpE,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,6BAA6B,CAAC,MAAM,CAAC,CAAC,CAAC;IACxE,CAAC;IAED;;;;OAIG;IACI,UAAU;QACf,OAAO,IAAI,CAAC;IACd,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2025 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 { captureResult, Result } from '../base';\nimport { CollectibleFactory, CollectibleKey, ICollectible } from './collectible';\nimport { ConvertingCollector } from './convertingCollector';\nimport { ConvertingCollectorValidator } from './convertingCollectorValidator';\nimport { KeyValueEntry } from './common';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { IReadOnlyValidatingCollector } from './validatingCollector';\n\n/**\n * Parameters for constructing a {@link Collections.ValidatingConvertingCollector | ValidatingConvertingCollector}.\n * @public\n */\nexport interface IValidatingConvertingCollectorConstructorParams<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>,\n  TSRC = TITEM\n> {\n  /**\n   * {@inheritDoc Collections.IConvertingCollectorConstructorParams.factory}\n   */\n  factory: CollectibleFactory<TITEM, TSRC>;\n\n  /**\n   * {@inheritDoc Collections.IConvertingCollectorValidatorCreateParams.converters}\n   */\n  converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;\n\n  /**\n   * {@inheritDoc Collections.IConvertingCollectorConstructorParams.entries}\n   */\n  entries?: KeyValueEntry<CollectibleKey<TITEM>, TSRC>[];\n}\n\n/**\n * A {@link Collections.ConvertingCollector | ConvertingCollector} with a\n * {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}\n * property that enables validated use of the underlying map with weakly-typed keys and values.\n * @public\n */\nexport class ValidatingConvertingCollector<\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  TITEM extends ICollectible<any, any>,\n  TSRC = TITEM\n> extends ConvertingCollector<TITEM, TSRC> {\n  /**\n   * A {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator} which validates keys and values\n   * before inserting them into this collector.\n   */\n  public readonly validating: ConvertingCollectorValidator<TITEM, TSRC>;\n\n  protected readonly _converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;\n\n  /**\n   * Constructs a new {@link Collections.ValidatingConvertingCollector | ValidatingConvertingCollector}\n   * from the supplied {@link Collections.IValidatingConvertingCollectorConstructorParams | parameters}.\n   * @param params - Required parameters for constructing the collector.\n   */\n  public constructor(params: IValidatingConvertingCollectorConstructorParams<TITEM, TSRC>) {\n    super({ factory: params.factory });\n    this._converters = params.converters;\n    this.validating = new ConvertingCollectorValidator({ collector: this, converters: params.converters });\n    for (const entry of params.entries ?? []) {\n      this.getOrAdd(entry[0], entry[1]).orThrow();\n    }\n  }\n\n  /**\n   * Creates a new {@link Collections.ValidatingConvertingCollector | ValidatingConvertingCollector} instance from\n   * the supplied {@link Collections.IValidatingConvertingCollectorConstructorParams | parameters}.\n   * @param params - Required parameters for constructing the collector.\n   * @returns {@link Success} with the new collector if successful, {@link Failure} otherwise.\n   */\n  public static createValidatingCollector<\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    TITEM extends ICollectible<any, any>,\n    TSRC = TITEM\n  >(\n    params: IValidatingConvertingCollectorConstructorParams<TITEM, TSRC>\n  ): Result<ValidatingConvertingCollector<TITEM, TSRC>> {\n    return captureResult(() => new ValidatingConvertingCollector(params));\n  }\n\n  /**\n   * Gets a read-only version of this collector as a\n   * {@link Collections.IReadOnlyValidatingResultMap | read-only map}.\n   * @returns\n   */\n  public toReadOnly(): IReadOnlyValidatingCollector<TITEM> {\n    return this;\n  }\n}\n"]}

package/dist/packlets/collections/validatingConvertingResultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingConvertingResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/validatingConvertingResultMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAU,MAAM,SAAS,CAAC;AAGhD,OAAO,EACL,2BAA2B,EAE5B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAwBlE;;;;;GAKG;AACH,MAAM,OAAO,qCAIX,SAAQ,2BAA8C;IAWtD;;;OAGG;IACH,YAAmB,MAAkF;QACnG,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC5E,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAU,MAAM,CAC3B,MAAkF;QAElF,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,qCAAqC,CAAC,MAAM,CAAC,CAAC,CAAC;IAChF,CAAC;CACF;AA6BD;;;;;;;GAOG;AACH,MAAM,OAAO,6BAKX,SAAQ,mBAA+C;IAWvD;;;OAGG;IACH,YAAmB,MAAmF;QACpG,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC5E,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAU,MAAM,CAM3B,MAAmF;QAEnF,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,6BAA6B,CAAC,MAAM,CAAC,CAAC,CAAC;IACxE,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2025 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 { captureResult, Result } from '../base';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { IReadOnlyResultMap } from './readonlyResultMap';\nimport {\n  ReadOnlyConvertingResultMap,\n  ConvertingResultMapValueConverter\n} from './readOnlyConvertingResultMap';\nimport { ConvertingResultMap } from './convertingResultMap';\nimport { IResultMap } from './resultMap';\nimport { ReadOnlyResultMapValidator } from './resultMapValidator';\n\n/**\n * Parameters for constructing a\n * {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.\n * @public\n */\nexport interface IValidatingReadOnlyConvertingResultMapConstructorParams<TK extends string, TSRC, TTARGET> {\n  /**\n   * The inner map containing source values.\n   */\n  inner: IReadOnlyResultMap<TK, TSRC>;\n\n  /**\n   * The converter function to transform source values to target values.\n   */\n  converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;\n\n  /**\n   * The key-value converters for validating weakly-typed access.\n   */\n  converters: KeyValueConverters<TK, TTARGET>;\n}\n\n/**\n * A read-only result map that wraps an inner {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}\n * of source type and returns lazily-converted, cached values of a target type, with a\n * {@link Collections.ReadOnlyResultMapValidator | validating} property for weakly-typed access.\n * @public\n */\nexport class ValidatingReadOnlyConvertingResultMap<\n  TK extends string,\n  TSRC,\n  TTARGET\n> extends ReadOnlyConvertingResultMap<TK, TSRC, TTARGET> {\n  /**\n   * A validator for weakly-typed access to the map.\n   */\n  public readonly validating: ReadOnlyResultMapValidator<TK, TTARGET>;\n\n  /**\n   * The key-value converters used for validation.\n   */\n  protected readonly _converters: KeyValueConverters<TK, TTARGET>;\n\n  /**\n   * Constructs a new {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   */\n  public constructor(params: IValidatingReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>) {\n    super({ inner: params.inner, converter: params.converter });\n    this._converters = params.converters;\n    this.validating = new ReadOnlyResultMapValidator(this, params.converters);\n  }\n\n  /**\n   * Creates a new {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   * @returns `Success` with the new map, or `Failure` with error details if an error occurred.\n   */\n  public static override create<TK extends string, TSRC, TTARGET>(\n    params: IValidatingReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>\n  ): Result<ValidatingReadOnlyConvertingResultMap<TK, TSRC, TTARGET>> {\n    return captureResult(() => new ValidatingReadOnlyConvertingResultMap(params));\n  }\n}\n\n/**\n * Parameters for constructing a\n * {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.\n * @public\n */\nexport interface IValidatingConvertingResultMapConstructorParams<\n  TK extends string,\n  TSRC,\n  TTARGET,\n  TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n> {\n  /**\n   * The inner map containing source values.\n   */\n  inner: TSRCMAP;\n\n  /**\n   * The converter function to transform source values to target values.\n   */\n  converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;\n\n  /**\n   * The key-value converters for validating weakly-typed access.\n   */\n  converters: KeyValueConverters<TK, TTARGET>;\n}\n\n/**\n * A result map that wraps an inner {@link Collections.IResultMap | IResultMap} of source type\n * and returns lazily-converted, cached values of a target type, with a\n * {@link Collections.ReadOnlyResultMapValidator | validating} property for weakly-typed access\n * and a {@link Collections.CacheInvalidatingResultMapWrapper | source} property for mutable access\n * to the underlying source map.\n * @public\n */\nexport class ValidatingConvertingResultMap<\n  TK extends string,\n  TSRC,\n  TTARGET,\n  TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n> extends ConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP> {\n  /**\n   * A validator for weakly-typed access to the map.\n   */\n  public readonly validating: ReadOnlyResultMapValidator<TK, TTARGET>;\n\n  /**\n   * The key-value converters used for validation.\n   */\n  protected readonly _converters: KeyValueConverters<TK, TTARGET>;\n\n  /**\n   * Constructs a new {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   */\n  public constructor(params: IValidatingConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>) {\n    super({ inner: params.inner, converter: params.converter });\n    this._converters = params.converters;\n    this.validating = new ReadOnlyResultMapValidator(this, params.converters);\n  }\n\n  /**\n   * Creates a new {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   * @returns `Success` with the new map, or `Failure` with error details if an error occurred.\n   */\n  public static override create<\n    TK extends string,\n    TSRC,\n    TTARGET,\n    TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>\n  >(\n    params: IValidatingConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>\n  ): Result<ValidatingConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP>> {\n    return captureResult(() => new ValidatingConvertingResultMap(params));\n  }\n}\n"]}

package/dist/packlets/collections/validatingResultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/validatingResultMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAU,MAAM,SAAS,CAAC;AAIhD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAA+B,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAwBvF;;;;GAIG;AACH,MAAM,OAAO,mBACX,SAAQ,SAAiB;IASzB;;;OAGG;IACH,YAAmB,MAAqD;;QACtE,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,MAAA,MAAM,CAAC,OAAO,mCAAI,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACxF,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,IAAI,kBAAkB,CAAS,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IACjG,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,yBAAyB,CACrC,MAAqD;QAErD,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACI,UAAU;QACf,OAAO,IAAI,CAAC;IACd,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2025 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 { captureResult, Result } from '../base';\nimport { KeyValueEntry } from './common';\nimport { KeyValueConverters } from './keyValueConverters';\nimport { IReadOnlyResultMap } from './readonlyResultMap';\nimport { ResultMap } from './resultMap';\nimport { IReadOnlyResultMapValidator, ResultMapValidator } from './resultMapValidator';\n\n/**\n * A read-only interface exposing non-mutating methods of a {@link Collections.ValidatingResultMap | ValidatingResultMap}.\n * @public\n */\nexport interface IReadOnlyValidatingResultMap<TK extends string = string, TV = unknown>\n  extends IReadOnlyResultMap<TK, TV> {\n  /**\n   * A {@link Collections.ResultMapValidator | ResultMapValidator} which validates keys and values\n   * before inserting them into this collection.\n   */\n  readonly validating: IReadOnlyResultMapValidator<TK, TV>;\n}\n\n/**\n * Parameters for constructing a {@link Collections.ResultMap | ResultMap}.\n * @public\n */\nexport interface IValidatingResultMapConstructorParams<TK extends string = string, TV = unknown> {\n  entries?: Iterable<KeyValueEntry<string, unknown>>;\n  converters: KeyValueConverters<TK, TV>;\n}\n\n/**\n * A {@link Collections.ResultMap | ResultMap} with a {@link Collections.ResultMapValidator | validator}\n * property that enables validated use of the underlying map with weakly-typed keys and values.\n * @public\n */\nexport class ValidatingResultMap<TK extends string = string, TV = unknown>\n  extends ResultMap<TK, TV>\n  implements IReadOnlyValidatingResultMap<TK, TV>\n{\n  /**\n   * A {@link Collections.ResultMapValidator | ResultMapValidator} which validates keys and values\n   * before inserting them into this collection.\n   */\n  public readonly validating: ResultMapValidator<TK, TV>;\n\n  /**\n   * Constructs a new {@link Collections.ValidatingResultMap | ValidatingResultMap}.\n   * @param params - Required parameters for constructing the map.\n   */\n  public constructor(params: IValidatingResultMapConstructorParams<TK, TV>) {\n    const entries = params.converters.convertEntries([...(params.entries ?? [])]).orThrow();\n    super({ entries });\n    this.validating = new ResultMapValidator<TK, TV>({ map: this, converters: params.converters });\n  }\n\n  /**\n   * Creates a new {@link Collections.ValidatingResultMap | ValidatingResultMap} instance.\n   * @param params - Required parameters for constructing the map.\n   * @returns `Success` with the new map if successful, `Failure` otherwise.\n   * @public\n   */\n  public static createValidatingResultMap<TK extends string = string, TV = unknown>(\n    params: IValidatingResultMapConstructorParams<TK, TV>\n  ): Result<ValidatingResultMap<TK, TV>> {\n    return captureResult(() => new ValidatingResultMap(params));\n  }\n\n  /**\n   * Gets a read-only version of this map.\n   */\n  public toReadOnly(): IReadOnlyValidatingResultMap<TK, TV> {\n    return this;\n  }\n}\n"]}

package/dist/packlets/conversion/advancedConverters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advancedConverters.js","sourceRoot":"","sources":["../../../src/packlets/conversion/advancedConverters.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { fail, isKeyOf, mapResults, succeed, Success } from '../base';\nimport { Validator } from '../validation';\nimport { BaseConverter, ConverterResultTypes } from './baseConverter';\nimport { Converter } from './converter';\nimport { literal } from './basicConverters';\nimport { FieldConverters, ObjectConverter } from './objectConverter';\n\n/**\n * Represents a composite ID constructed of two strongly-typed string IDs\n * separated by a delimiter.\n * @public\n */\nexport interface ICompositeId<TCOLLECTIONID extends string, TITEMID extends string> {\n  readonly collectionId: TCOLLECTIONID;\n  readonly separator: string;\n  readonly itemId: TITEMID;\n}\n\n/**\n * Represents a partial composite ID, where separator is optional.\n * @public\n */\nexport interface IPartialCompositeId<TCOLLECTIONID extends string, TITEMID extends string> {\n  readonly collectionId: TCOLLECTIONID;\n  readonly separator?: string;\n  readonly itemId: TITEMID;\n}\n\n/**\n * Creates an {@link ObjectConverter | ObjectConverter} for a strongly-typed {@link Converters.ICompositeId | CompositeId}.\n * @param collectionIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.\n * @param separator - The separator string.\n * @param itemIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.\n * @returns An {@link ObjectConverter | ObjectConverter} for the strongly-typed composite ICompositeId.\n * @public\n */\nexport function compositeIdFromObject<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(\n  collectionIdValidator: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>,\n  separator: string,\n  itemIdValidator: Converter<TITEMID, TC> | Validator<TITEMID, TC>\n): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC> {\n  return new ObjectConverter<IPartialCompositeId<TCOLLECTIONID, TITEMID>, TC>({\n    collectionId: collectionIdValidator,\n    separator: literal(separator).optional(),\n    itemId: itemIdValidator\n  }).map<ICompositeId<TCOLLECTIONID, TITEMID>>((obj) =>\n    Success.with({\n      collectionId: obj.collectionId,\n      separator: obj.separator ?? separator,\n      itemId: obj.itemId\n    })\n  );\n}\n\n/**\n * Converts a composite ID string into a strongly-typed {@link Converters.ICompositeId | CompositeId}.\n * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.\n * @param separator - The separator string.\n * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.\n * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.\n * @public\n */\nexport function compositeIdFromString<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(\n  collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>,\n  separator: string,\n  itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>\n): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC> {\n  return new BaseConverter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>(\n    (from: unknown, __self?: Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>, context?: TC) => {\n      if (typeof from !== 'string') {\n        return fail(`${from}: invalid non-string composite ID.`);\n      }\n      const parts = from.split(separator);\n      if (parts.length < 2) {\n        return fail(`${from}: invalid composite ID - separator '${separator}' not found.`);\n      } else if (parts.length > 2) {\n        return fail(`${from}: invalid composite ID - multiple separators '${separator}.' found.`);\n      }\n      return collectionIdConverter.convert(parts[0], context).onSuccess((collectionId) => {\n        return itemIdConverter.convert(parts[1], context).onSuccess((itemId) => {\n          return succeed({\n            collectionId,\n            separator,\n            itemId\n          });\n        });\n      });\n    }\n  );\n}\n\n/**\n * Creates a {@link Converter | Converter} for a strongly-typed {@link Converters.ICompositeId | CompositeId} from\n * either a string or an object representation.\n * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.\n * @param separator - The separator string.\n * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.\n * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.\n * @public\n */\nexport function compositeId<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(\n  collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>,\n  separator: string,\n  itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>\n): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC> {\n  return compositeIdFromObject(collectionIdConverter, separator, itemIdConverter).or(\n    compositeIdFromString(collectionIdConverter, separator, itemIdConverter)\n  );\n}\n\n/**\n * Converts a strongly-typed {@link Converters.ICompositeId | CompositeId} into a string.\n * @param compositeIdConverter - {@link Converter | Converter} or {@link Validator | Validator} that validates/converts the composite ID string.\n * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.\n * @param separator - The separator string.\n * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.\n * @returns A {@link Converter | Converter} which produces a composite ID string.\n * @public\n */\nexport function compositeIdString<\n  T extends string,\n  TCOLLECTIONID extends string,\n  TITEMID extends string,\n  TC = unknown\n>(\n  compositeIdConverter: Validator<T, TC> | Converter<T, TC>,\n  collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>,\n  separator: string,\n  itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>\n): Converter<T, TC> {\n  const objectConverter = compositeIdFromObject(collectionIdConverter, separator, itemIdConverter);\n  return new BaseConverter<T, TC>((from: unknown, __self?: Converter<T, TC>, context?: TC) => {\n    if (typeof from === 'string') {\n      return compositeIdConverter.convert(from, context);\n    }\n    return objectConverter.convert(from, context).onSuccess((compositeId) => {\n      return compositeIdConverter.convert(`${compositeId.collectionId}${separator}${compositeId.itemId}`);\n    });\n  });\n}\n\n/**\n * Helper to create a {@link Converter | Converter} which converts a source object to a new object with a\n * different shape.\n *\n * @remarks\n * On successful conversion, the resulting {@link Converter | Converter} returns {@link Success | Success} with a new\n * object, which contains the converted values under the key names specified at initialization time.\n * It returns {@link Failure | Failure} with an error message if any fields to be extracted do not exist\n * or cannot be converted.\n *\n * Fields that succeed but convert to undefined are omitted from the result object but do not\n * fail the conversion.\n *\n * @param properties - An object with key names that correspond to the target object and an\n * appropriate {@link Conversion.FieldConverters | FieldConverter} which extracts and converts\n * a single filed from the source object.\n * @returns A {@link Converter | Converter} with the specified conversion behavior.\n * @public\n */\nexport function transform<T, TC = unknown>(properties: FieldConverters<T, TC>): Converter<T, TC> {\n  return new BaseConverter((from: unknown, __self, context?: TC) => {\n    // eslint bug thinks key is used before defined\n\n    const converted = {} as { [key in keyof T]: T[key] };\n    const errors: string[] = [];\n\n    for (const key in properties) {\n      if (properties[key]) {\n        const result = properties[key].convert(from, context);\n        if (result.isSuccess() && result.value !== undefined) {\n          converted[key] = result.value;\n        } else if (result.isFailure()) {\n          errors.push(result.message);\n        }\n      }\n    }\n\n    return errors.length === 0 ? succeed(converted) : fail(errors.join('\\n'));\n  });\n}\n\n/**\n * Per-property converters and configuration for each field in the destination object of\n * a {@link Converters.transformObject} call.\n * @public\n */\nexport type FieldTransformers<TSRC, TDEST, TC = unknown> = {\n  [key in keyof TDEST]: {\n    /**\n     * The name of the property in the source object to be converted.\n     */\n    from: keyof TSRC;\n    /**\n     * The converter or validator used to convert the property.\n     */\n    converter: Converter<TDEST[key], TC> | Validator<TDEST[key], TC>;\n    /**\n     * If `true` then a missing source property is ignored.  If `false` or omitted\n     * then a missing source property causes an error.\n     */\n    optional?: boolean;\n  };\n};\n\n/**\n * Options for a {@link Converters.transformObject} call.\n * @public\n */\n\nexport interface TransformObjectOptions<TSRC> {\n  /**\n   * If `strict` is `true` then unused properties in the source object cause\n   * an error, otherwise they are ignored.\n   */\n  strict: true;\n\n  /**\n   * An optional list of source properties to be ignored when strict mode\n   * is enabled.\n   */\n  ignore?: (keyof TSRC)[];\n\n  /**\n   * An optional description of this transform to be used for error messages.\n   */\n  description?: string;\n}\n\n/**\n * Helper to create a strongly-typed {@link Converter | Converter} which converts a source object to a\n * new object with a different shape.\n *\n * @remarks\n * On successful conversion, the resulting {@link Converter | Converter} returns {@link Success | Success} with a new\n * object, which contains the converted values under the key names specified at initialization time.\n *\n * It returns {@link Failure | Failure} with an error message if any fields to be extracted do not exist\n * or cannot be converted.\n *\n * @param destinationFields - An object with key names that correspond to the target object and an\n * appropriate {@link Converters.FieldTransformers | FieldTransformers} which specifies the name\n * of the corresponding property in the source object, the converter or validator used for each source\n * property and any other configuration to guide the conversion.\n * @param options - Options which affect the transformation.\n *\n * @returns A {@link Converter | Converter} with the specified conversion behavior.\n * @public\n */\nexport function transformObject<TSRC, TDEST, TC = unknown>(\n  destinationFields: FieldTransformers<TSRC, TDEST, TC>,\n  options?: TransformObjectOptions<TSRC>\n): Converter<TDEST, TC> {\n  return new BaseConverter((from: unknown, __self, context?: TC) => {\n    // eslint bug thinks key is used before defined\n\n    const converted = {} as { [key in keyof TDEST]: TDEST[key] };\n    const errors: string[] = [];\n    const used: Set<keyof TSRC> = new Set(options?.ignore);\n\n    if (typeof from === 'object' && !Array.isArray(from) && from !== null) {\n      for (const destinationKey in destinationFields) {\n        if (destinationFields[destinationKey]) {\n          const srcKey = destinationFields[destinationKey].from;\n          const converter = destinationFields[destinationKey].converter;\n\n          if (isKeyOf(srcKey, from)) {\n            const result = converter.convert(from[srcKey], context);\n            if (result.isSuccess() && result.value !== undefined) {\n              converted[destinationKey] = result.value;\n            } else if (result.isFailure()) {\n              errors.push(`${srcKey}->${destinationKey}: ${result.message}`);\n            }\n            used.add(srcKey);\n          } else if (destinationFields[destinationKey].optional !== true) {\n            errors.push(`${String(srcKey)}: required property missing in source object.`);\n          }\n        }\n      }\n\n      if (options?.strict === true) {\n        for (const key in from) {\n          if (isKeyOf(key, from) && !used.has(key as keyof TSRC)) {\n            errors.push(`${key}: unexpected property in source object`);\n          }\n        }\n      }\n    } else {\n      errors.push('source is not an object');\n    }\n\n    return errors.length === 0\n      ? succeed(converted)\n      : fail(options?.description ? `${options.description}:\\n  ${errors.join('\\n  ')}` : errors.join('\\n'));\n  });\n}\n\n/**\n * Creates a {@link Converter | Converter} that converts an array to a strongly-typed tuple,\n * using the supplied tuple of {@link Converter | Converters} to convert each element.\n *\n * @remarks\n * The resulting {@link Converter | Converter} returns {@link Success | Success} with a tuple\n * containing the converted values if all conversions succeed. Returns {@link Failure | Failure}\n * with an error message if the source is not an array, has the wrong number of elements, or\n * any element conversion fails.\n *\n * @example\n * ```typescript\n * const converter = tuple([Converters.string, Converters.number, Converters.boolean]);\n * // Type is Converter<[string, number, boolean]>\n *\n * converter.convert(['hello', 42, true]);\n * // Returns Success with ['hello', 42, true]\n * ```\n *\n * @param converters - A tuple of {@link Converter | Converters} defining the expected types\n * for each element of the tuple.\n * @returns A {@link Converter | Converter} that returns a strongly-typed tuple.\n * @public\n */\nexport function tuple<T extends readonly Converter<unknown, TC>[], TC = unknown>(\n  converters: [...T]\n): Converter<ConverterResultTypes<T>, TC> {\n  return new BaseConverter<ConverterResultTypes<T>, TC>(\n    (from: unknown, __self: Converter<ConverterResultTypes<T>, TC>, context?: TC) => {\n      if (!Array.isArray(from)) {\n        return fail(`Not an array: ${JSON.stringify(from)}`);\n      }\n\n      if (from.length !== converters.length) {\n        return fail(\n          `Expected array of length ${converters.length}, got ${from.length}: ${JSON.stringify(from)}`\n        );\n      }\n\n      const results = converters.map((converter, index) => {\n        return converter.convert(from[index], context);\n      });\n\n      return mapResults(results) as ReturnType<Converter<ConverterResultTypes<T>, TC>['convert']>;\n    }\n  );\n}\n"]}

package/dist/packlets/conversion/baseConverter.js

@@ -44,25 +44,48 @@ export class BaseConverter {
         this._brand = traits === null || traits === void 0 ? void 0 : traits.brand;
     }
     /**
-     * {@inheritDoc Converter.isOptional}
+     * Indicates whether this element is explicitly optional.
      */
     get isOptional() {
         return this._isOptional;
     }
     /**
-     * {@inheritDoc Converter.brand}
+     * Returns the brand for a branded type.
      */
     get brand() {
         return this._brand;
     }
     /**
-     * {@inheritDoc Converter.convert}
+     * Converts from `unknown` to `<T>`. For objects and arrays, is guaranteed
+     * to return a new entity, with any unrecognized properties removed.
+     * @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, context) {
-        return this._converter(from, this, context !== null && context !== void 0 ? context : this._defaultContext);
+    convert(from, context, selfOverride) {
+        return this._converter(from, selfOverride !== null && selfOverride !== void 0 ? selfOverride : this, context !== null && context !== void 0 ? context : this._defaultContext);
     }
     /**
-     * {@inheritDoc Converter.convertOptional}
+     * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the converter succeeds for
+     * `undefined` or any convertible value, but reports an error
+     * if it encounters a value that cannot be converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that
+     * cannot be converted result in a successful return of `undefined`.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
     convertOptional(from, context, onError) {
         const result = this._converter(from, this, this._context(context));
@@ -73,7 +96,18 @@ export class BaseConverter {
         return result;
     }
     /**
-     * {@inheritDoc Converter.optional}
+     * Creates a {@link Converter} for an optional value.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the resulting converter will accept `undefined`
+     * or a convertible value, but report an error if it encounters a value that cannot be
+     * converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that cannot be converted will
+     * result in a successful return of `undefined`.
+     *
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A new {@link Converter} returning `<T|undefined>`.
      */
     optional(onError) {
         return new BaseConverter((from, __self, context) => {
@@ -82,7 +116,11 @@ export class BaseConverter {
         })._with(this._traits({ isOptional: true }));
     }
     /**
-     * {@inheritDoc Converter.map}
+     * Creates a {@link Converter} which applies a (possibly) mapping conversion to
+     * the converted value of this {@link Converter}.
+     * @param mapper - A function which maps from the the result type `<T>` of this
+     * converter to a new result type `<T2>`.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     map(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -94,7 +132,12 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.mapConvert}
+     * Creates a {@link Converter} which applies an additional supplied
+     * converter to the result of this converter.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to the
+     * converted result from this {@link Converter}.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     mapConvert(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -106,7 +149,15 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.mapItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied map function.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapper - The map function to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapItems(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -119,7 +170,15 @@ export class BaseConverter {
         });
     }
     /**
-     * {@inheritDoc Converter.mapConvertItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied {@link Converter}.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapConvertItems(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -132,7 +191,10 @@ export class BaseConverter {
         });
     }
     /**
-     * {@inheritDoc Converter.withAction}
+     * Creates a {@link Converter | Converter} which applies a supplied action after
+     * conversion. The supplied action is always called regardless of success or failure
+     * of the base conversion and is allowed to mutate the return type.
+     * @param action - The action to be applied.
      */
     withAction(action) {
         return new BaseConverter((from, __self, context) => {
@@ -140,7 +202,11 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to the conversion
+     * result.
+     * @param guard - The type guard function to apply.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -153,7 +219,15 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withItemTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to each member of
+     * the conversion result from this converter.
+     *
+     * @remarks
+     * Fails if the conversion result is not an array or if any member fails the
+     * type guard.
+     * @param guard - The type guard function to apply to each element.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withItemTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -171,7 +245,15 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withConstraint}
+     * Creates a {@link Converter} which applies an optional constraint to the result
+     * of this conversion. If this {@link Converter} (the base converter) succeeds, the new
+     * converter calls a supplied constraint evaluation function with the conversion, which
+     * fails the entire conversion if the constraint function returns either `false` or
+     * {@link Failure | Failure<T>}.
+     *
+     * @param constraint - Constraint evaluation function.
+     * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withConstraint(constraint, options) {
         return new BaseConverter((from, __self, context) => {
@@ -190,7 +272,10 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withBrand}
+     * Returns a converter which adds a brand to the type to prevent mismatched usage
+     * of simple types.
+     * @param brand - The brand to be applied to the result value.
+     * @returns A {@link Converter} returning `Brand<T, B>`.
      */
     withBrand(brand) {
         if (this._brand) {
@@ -203,7 +288,8 @@ export class BaseConverter {
         })._with(this._traits({ brand }));
     }
     /**
-     * {@inheritDoc Converter.withDefault}
+     * Returns a Converter which always succeeds with a default value rather than failing.
+     * @param defaultValue - The default value to use if conversion fails.
      */
     withDefault(defaultValue) {
         return new GenericDefaultingConverter(this, defaultValue);
@@ -222,7 +308,10 @@ export class BaseConverter {
         return supplied !== null && supplied !== void 0 ? supplied : this._defaultContext;
     }
     /**
-     * {@inheritDoc Converter.withFormattedError}
+     * Creates a new {@link Converter} which is derived from this one but which returns an
+     * error message formatted by the supplied formatter if the conversion fails.
+     * @param formatter - The formatter to be applied.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withFormattedError(formatter) {
         return new BaseConverter((from, __self, context) => {

package/dist/packlets/conversion/baseConverter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseConverter.js","sourceRoot":"","sources":["../../../src/packlets/conversion/baseConverter.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 { Brand, Result, fail, mapResults, succeed } from '../base';\nimport {\n  ConstraintOptions,\n  ConversionErrorFormatter,\n  Converter,\n  ConverterTraits,\n  DefaultingConverter,\n  OnError\n} from './converter';\nimport { GenericDefaultingConverter } from './defaultingConverter';\n\n/**\n * Internal helper that recursively unwraps converter and array types.\n * @internal\n */\ntype InnerInferredType<TCONV> = TCONV extends Converter<infer TTO>\n  ? TTO extends Array<infer TTOELEM>\n    ? InnerInferredType<TTOELEM>[]\n    : TTO\n  : TCONV extends Array<infer TELEM>\n  ? InnerInferredType<TELEM>[]\n  : TCONV;\n\n/**\n * Infers the type that will be returned by an instantiated converter. Works\n * for complex as well as simple types, including nested arrays.\n * @example `Infer<typeof Converters.mapOf(Converters.stringArray)>` is `Map<string, string[]>`\n * @public\n */\nexport type Infer<TCONV> = TCONV extends Converter<infer TTO, unknown> ? InnerInferredType<TTO> : never;\n\n/**\n * Deprecated name for {@link Conversion.Infer | Infer\n * } retained for compatibility.\n * @deprecated Use {@link Conversion.Infer | Infer} instead.\n * @public\n */\nexport type ConvertedToType<TCONV> = Infer<TCONV>;\n\n/**\n * Helper type to extract the result type from a {@link Converter | Converter}.\n * For simple single-level extraction. For complex nested types, use {@link Conversion.Infer | Infer}.\n * @public\n */\nexport type ConverterResultType<C> = C extends Converter<infer T, unknown> ? T : never;\n\n/**\n * Helper type to map a tuple of {@link Converter | Converters} to a tuple of their result types.\n * @public\n */\nexport type ConverterResultTypes<T extends readonly Converter<unknown, unknown>[]> = {\n  [K in keyof T]: T[K] extends Converter<infer R, unknown> ? R : never;\n};\n\n/**\n * Function signature for a converter function.\n * @public\n */\nexport type ConverterFunc<T, TC> = (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>;\n\n/**\n * Base templated wrapper to simplify creation of new {@link Converter}s.\n * @public\n */\nexport class BaseConverter<T, TC = unknown> implements Converter<T, TC> {\n  /**\n   * @internal\n   */\n  protected readonly _defaultContext?: TC;\n  /**\n   * @internal\n   */\n  protected _isOptional: boolean = false;\n  /**\n   * @internal\n   */\n  protected _brand?: string;\n\n  private readonly _converter: (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>;\n\n  /**\n   * Constructs a new {@link Converter} which uses the supplied function to perform the conversion.\n   * @param converter - The conversion function to be applied.\n   * @param defaultContext - Optional conversion context to be used by default.\n   * @param traits - Optional {@link Conversion.ConverterTraits | traits} to be assigned to the resulting\n   * converter.\n   */\n  public constructor(converter: ConverterFunc<T, TC>, defaultContext?: TC, traits?: ConverterTraits) {\n    this._converter = converter;\n    this._defaultContext = defaultContext;\n    this._isOptional = traits?.isOptional === true;\n    this._brand = traits?.brand;\n  }\n\n  /**\n   * Indicates whether this element is explicitly optional.\n   */\n  public get isOptional(): boolean {\n    return this._isOptional;\n  }\n\n  /**\n   * Returns the brand for a branded type.\n   */\n  public get brand(): string | undefined {\n    return this._brand;\n  }\n\n  /**\n   * Converts from `unknown` to `<T>`. For objects and arrays, is guaranteed\n   * to return a new entity, with any unrecognized properties removed.\n   * @param from - The `unknown` to be converted\n   * @param context - An optional conversion context of type `<TC>` to be used in\n   * the conversion.\n   * @param selfOverride - An optional override for the `self` reference passed to the\n   * converter function, enabling outer converters (e.g. discriminated-object) to thread\n   * themselves through to per-arm converters for recursive parsing.\n   * @returns A {@link Result} with a {@link Success} and a value on success or an\n   * {@link Failure} with a a message on failure.\n   */\n  public convert(from: unknown, context?: TC, selfOverride?: Converter<T, TC>): Result<T> {\n    return this._converter(from, selfOverride ?? this, context ?? this._defaultContext);\n  }\n\n  /**\n   * Converts from `unknown` to `<T>` or `undefined`, as appropriate.\n   *\n   * @remarks\n   * If `onError` is `failOnError`, the converter succeeds for\n   * `undefined` or any convertible value, but reports an error\n   * if it encounters a value that cannot be converted.\n   *\n   * If `onError` is `ignoreErrors` (default) then values that\n   * cannot be converted result in a successful return of `undefined`.\n   * @param from - The `unknown` to be converted\n   * @param context - An optional conversion context of type `<TC>` to be used in\n   * the conversion.\n   * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).\n   * @returns A {@link Result} with a {@link Success} and a value on success or an\n   * {@link Failure} with a a message on failure.\n   */\n  public convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined> {\n    const result = this._converter(from, this, this._context(context));\n    if (result.isFailure()) {\n      onError = onError ?? 'ignoreErrors';\n      return from === undefined || onError === 'ignoreErrors' ? succeed(undefined) : result;\n    }\n    return result;\n  }\n\n  /**\n   * Creates a {@link Converter} for an optional value.\n   *\n   * @remarks\n   * If `onError` is `failOnError`, the resulting converter will accept `undefined`\n   * or a convertible value, but report an error if it encounters a value that cannot be\n   * converted.\n   *\n   * If `onError` is `ignoreErrors` (default) then values that cannot be converted will\n   * result in a successful return of `undefined`.\n   *\n   * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).\n   * @returns A new {@link Converter} returning `<T|undefined>`.\n   */\n  public optional(onError?: OnError): Converter<T | undefined, TC> {\n    return new BaseConverter((from: unknown, __self: Converter<T | undefined, TC>, context?: TC) => {\n      onError = onError ?? 'failOnError';\n      return this.convertOptional(from, this._context(context), onError);\n    })._with(this._traits({ isOptional: true }));\n  }\n\n  /**\n   * Creates a {@link Converter} which applies a (possibly) mapping conversion to\n   * the converted value of this {@link Converter}.\n   * @param mapper - A function which maps from the the result type `<T>` of this\n   * converter to a new result type `<T2>`.\n   * @returns A new {@link Converter} returning `<T2>`.\n   */\n  public map<T2>(mapper: (from: T, context?: TC) => Result<T2>): Converter<T2, TC> {\n    return new BaseConverter<T2, TC>((from: unknown, __self: Converter<T2, TC>, context?: TC) => {\n      const innerResult = this._converter(from, this, this._context(context));\n      if (innerResult.isSuccess()) {\n        return mapper(innerResult.value, this._context(context));\n      }\n      return fail(innerResult.message);\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which applies an additional supplied\n   * converter to the result of this converter.\n   *\n   * @param mapConverter - The {@link Converter} to be applied to the\n   * converted result from this {@link Converter}.\n   * @returns A new {@link Converter} returning `<T2>`.\n   */\n  public mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC> {\n    return new BaseConverter<T2, TC>((from: unknown, __self: Converter<T2, TC>, context?: TC) => {\n      const innerResult = this._converter(from, this, this._context(context));\n      if (innerResult.isSuccess()) {\n        return mapConverter.convert(innerResult.value, this._context(context));\n      }\n      return fail(innerResult.message);\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which maps the individual items of a collection\n   * resulting from this {@link Converter} using the supplied map function.\n   *\n   * @remarks\n   * Fails if `from` is not an array.\n   *\n   * @param mapper - The map function to be applied to each element of the\n   * result of this {@link Converter}.\n   * @returns A new {@link Converter} returning `<TI[]>`.\n   */\n  public mapItems<TI>(mapper: (from: unknown, context?: TC) => Result<TI>): Converter<TI[], TC> {\n    return new BaseConverter<TI[], TC>((from: unknown, __self: Converter<TI[], TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((items) => {\n        if (Array.isArray(items)) {\n          return mapResults(items.map((i) => mapper(i, this._context(context))));\n        }\n        return fail('Cannot map items - not an array');\n      });\n    });\n  }\n\n  /**\n   * Creates a {@link Converter} which maps the individual items of a collection\n   * resulting from this {@link Converter} using the supplied {@link Converter}.\n   *\n   * @remarks\n   * Fails if `from` is not an array.\n   *\n   * @param mapConverter - The {@link Converter} to be applied to each element of the\n   * result of this {@link Converter}.\n   * @returns A new {@link Converter} returning `<TI[]>`.\n   */\n  public mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC> {\n    return new BaseConverter<TI[], TC>((from: unknown, __self: Converter<TI[], TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((items) => {\n        if (Array.isArray(items)) {\n          return mapResults(items.map((i) => mapConverter.convert(i, this._context(context))));\n        }\n        return fail('Cannot map items - not an array');\n      });\n    });\n  }\n\n  /**\n   * Creates a {@link Converter | Converter} which applies a supplied action after\n   * conversion. The supplied action is always called regardless of success or failure\n   * of the base conversion and is allowed to mutate the return type.\n   * @param action - The action to be applied.\n   */\n  public withAction<TI>(action: (result: Result<T>, context?: TC) => Result<TI>): Converter<TI, TC> {\n    return new BaseConverter<TI, TC>((from: unknown, __self: Converter<TI, TC>, context?: TC) => {\n      return action(this._converter(from, this, this._context(context)), this._context(context));\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which applies a supplied type guard to the conversion\n   * result.\n   * @param guard - The type guard function to apply.\n   * @param message - Optional message to be reported if the type guard fails.\n   * @returns A new {@link Converter} returning `<TI>`.\n   */\n  public withTypeGuard<TI>(\n    guard: (from: unknown, context?: TC) => from is TI,\n    message?: string\n  ): Converter<TI, TC> {\n    return new BaseConverter<TI, TC>((from: unknown, __self: Converter<TI, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((inner) => {\n        message = message ?? 'invalid type';\n        return guard(inner, this._context(context))\n          ? succeed(inner)\n          : fail(`${message}: ${JSON.stringify(from)}`);\n      });\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which applies a supplied type guard to each member of\n   * the conversion result from this converter.\n   *\n   * @remarks\n   * Fails if the conversion result is not an array or if any member fails the\n   * type guard.\n   * @param guard - The type guard function to apply to each element.\n   * @param message - Optional message to be reported if the type guard fails.\n   * @returns A new {@link Converter} returning `<TI>`.\n   */\n  public withItemTypeGuard<TI>(\n    guard: (from: unknown, context?: TC) => from is TI,\n    message?: string\n  ): Converter<TI[], TC> {\n    return new BaseConverter<TI[], TC>((from: unknown, __self: Converter<TI[], TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((items) => {\n        if (Array.isArray(items)) {\n          return mapResults(\n            items.map((i) => {\n              message = message ?? 'invalid type';\n              return guard(i, this._context(context))\n                ? succeed(i)\n                : fail(`${message}: ${JSON.stringify(from)}`);\n            })\n          );\n        }\n        return fail('Cannot guard item type - not an array');\n      });\n    })._with(this._traits());\n  }\n\n  /**\n   * Creates a {@link Converter} which applies an optional constraint to the result\n   * of this conversion. If this {@link Converter} (the base converter) succeeds, the new\n   * converter calls a supplied constraint evaluation function with the conversion, which\n   * fails the entire conversion if the constraint function returns either `false` or\n   * {@link Failure | Failure<T>}.\n   *\n   * @param constraint - Constraint evaluation function.\n   * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.\n   * @returns A new {@link Converter} returning `<T>`.\n   */\n  public withConstraint(\n    constraint: (val: T, context?: TC) => boolean | Result<T>,\n    options?: ConstraintOptions\n  ): Converter<T, TC> {\n    return new BaseConverter<T, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      const result = this._converter(from, this, this._context(context));\n      if (result.isSuccess()) {\n        const constraintResult = constraint(result.value, this._context(context));\n        if (typeof constraintResult === 'boolean') {\n          return constraintResult\n            ? result\n            : fail(\n                `\"${JSON.stringify(result.value)}\": ${options?.description ?? 'does not meet constraint'}`\n              );\n        }\n        return constraintResult;\n      }\n      return result;\n    })._with(this._traits());\n  }\n\n  /**\n   * Returns a converter which adds a brand to the type to prevent mismatched usage\n   * of simple types.\n   * @param brand - The brand to be applied to the result value.\n   * @returns A {@link Converter} returning `Brand<T, B>`.\n   */\n  public withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC> {\n    if (this._brand) {\n      throw new Error(`Cannot replace existing brand \"${this._brand}\" with \"${brand}\".`);\n    }\n\n    return new BaseConverter<Brand<T, B>, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((v) => {\n        return succeed(v as Brand<T, B>);\n      });\n    })._with(this._traits({ brand }));\n  }\n\n  /**\n   * Returns a Converter which always succeeds with a default value rather than failing.\n   * @param defaultValue - The default value to use if conversion fails.\n   */\n  public withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC> {\n    return new GenericDefaultingConverter<T, TD, TC>(this, defaultValue);\n  }\n\n  public or(other: Converter<T, TC>): Converter<T, TC> {\n    return new BaseConverter<T, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onFailure(() => {\n        return other.convert(from, this._context(context));\n      });\n    });\n  }\n\n  /**\n   * @internal\n   */\n  protected _context(supplied?: TC): TC | undefined {\n    return supplied ?? this._defaultContext;\n  }\n\n  /**\n   * Creates a new {@link Converter} which is derived from this one but which returns an\n   * error message formatted by the supplied formatter if the conversion fails.\n   * @param formatter - The formatter to be applied.\n   * @returns A new {@link Converter} returning `<T>`.\n   */\n  public withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC> {\n    return new BaseConverter<T, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onFailure((msg) => {\n        return fail(formatter(from, msg, this._context(context)));\n      });\n    })._with(this._traits());\n  }\n\n  /**\n   * @internal\n   */\n  protected _traits(traits?: Partial<ConverterTraits>): ConverterTraits {\n    return {\n      isOptional: this.isOptional,\n      brand: this.brand,\n      ...(traits ?? {})\n    };\n  }\n\n  /**\n   * @internal\n   */\n  protected _with(traits: Partial<ConverterTraits>): this {\n    this._isOptional = traits.isOptional === true;\n    this._brand = traits.brand;\n    return this;\n  }\n}\n"]}