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

package/lib/packlets/collections/readOnlyConvertingResultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readOnlyConvertingResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/readOnlyConvertingResultMap.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\nimport { captureResult, DetailedResult, failWithDetail, Result, succeedWithDetail } from '../base';\nimport { Converter, Converters } from '../conversion';\nimport { ILogger } from '../logging-interface';\nimport { KeyValueEntry } from './common';\nimport { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';\n\n/**\n * A function that converts a source value to a target value.\n * @public\n */\nexport type ConvertingResultMapValueConverter<TK extends string, TSRC, TTARGET> = (\n  src: TSRC,\n  key: TK\n) => Result<TTARGET>;\n\n/**\n * Error handling behavior for conversion failures during iteration.\n * - `'ignore'`: Silently skip failed conversions (default behavior)\n * - `'warn'`: Log warning and skip failed conversions\n * - `'fail'`: Throw error on first conversion failure\n * @public\n */\nexport type ConversionErrorHandling = 'ignore' | 'warn' | 'fail';\n\n// Untyped (literal-tuple-inferred) source of truth for allConversionErrorHandling, kept separate from\n// the widened public export below so the exhaustiveness check actually inspects the literal values\n// instead of being widened away to {@link Collections.ConversionErrorHandling | ConversionErrorHandling} before the check runs.\nconst conversionErrorHandlingValues = ['ignore', 'warn', 'fail'] as const;\n\n/**\n * Compile-time exhaustiveness guard ensuring {@link conversionErrorHandlingValues} exactly matches every\n * member of {@link Collections.ConversionErrorHandling | ConversionErrorHandling}. Adding or removing a\n * union member without updating the array fails the build.\n * Deliberately not exported - this exists only to force the compiler to evaluate the check below.\n */\ntype _ConversionErrorHandlingExhaustivenessCheck = [\n  Exclude<ConversionErrorHandling, (typeof conversionErrorHandlingValues)[number]>,\n  Exclude<(typeof conversionErrorHandlingValues)[number], ConversionErrorHandling>\n] extends [never, never]\n  ? true\n  : never;\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nconst _conversionErrorHandlingExhaustivenessCheck: _ConversionErrorHandlingExhaustivenessCheck = true;\n\n/**\n * Exhaustive list of all {@link Collections.ConversionErrorHandling | ConversionErrorHandling} values.\n * @public\n */\nexport const allConversionErrorHandling: readonly ConversionErrorHandling[] = conversionErrorHandlingValues;\n\n/**\n * A ready-made {@link Converter | Converter} for\n * {@link Collections.ConversionErrorHandling | ConversionErrorHandling} values.\n * @public\n */\nexport const conversionErrorHandling: Converter<\n  ConversionErrorHandling,\n  ReadonlyArray<ConversionErrorHandling>\n> = Converters.enumeratedValue<ConversionErrorHandling>(allConversionErrorHandling);\n\n/**\n * Parameters for constructing a {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.\n * @public\n */\nexport interface IReadOnlyConvertingResultMapConstructorParams<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   * Error handling behavior for conversion failures during iteration.\n   * Defaults to `'ignore'` (silently skip failed conversions).\n   */\n  onConversionError?: ConversionErrorHandling;\n\n  /**\n   * Optional logger for warnings when `onConversionError` is `'warn'`.\n   */\n  logger?: ILogger;\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.\n * @public\n */\nexport class ReadOnlyConvertingResultMap<TK extends string, TSRC, TTARGET>\n  implements IReadOnlyResultMap<TK, TTARGET>\n{\n  /**\n   * The inner map containing source values.\n   */\n  protected readonly _inner: IReadOnlyResultMap<TK, TSRC>;\n\n  /**\n   * The converter function to transform source values to target values.\n   */\n  protected readonly _converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;\n\n  /**\n   * Cache of converted target values.\n   */\n  protected readonly _cache: Map<TK, TTARGET>;\n\n  /**\n   * Error handling behavior for conversion failures during iteration.\n   */\n  protected readonly _onConversionError: ConversionErrorHandling;\n\n  /**\n   * Optional logger for warnings.\n   */\n  protected readonly _logger?: ILogger;\n\n  /**\n   * Constructs a new {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.\n   * @param params - Parameters for constructing the map.\n   */\n  public constructor(params: IReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>) {\n    this._inner = params.inner;\n    this._converter = params.converter;\n    this._cache = new Map<TK, TTARGET>();\n    this._onConversionError = params.onConversionError ?? 'ignore';\n    this._logger = params.logger;\n  }\n\n  /**\n   * Creates a new {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.\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 create<TK extends string, TSRC, TTARGET>(\n    params: IReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>\n  ): Result<ReadOnlyConvertingResultMap<TK, TSRC, TTARGET>> {\n    return captureResult(() => new ReadOnlyConvertingResultMap(params));\n  }\n\n  /**\n   * The number of entries in the map.\n   */\n  public get size(): number {\n    return this._inner.size;\n  }\n\n  /**\n   * Gets a converted value from the map by key.\n   * @param key - The key to retrieve.\n   * @returns `Success` with the converted value and detail `exists` if the key was found,\n   * `Failure` with detail `not-found` if the key was not found, or `Failure` with\n   * detail `invalid-value` if conversion failed.\n   */\n  public get(key: TK): DetailedResult<TTARGET, ResultMapResultDetail> {\n    const cached = this._cache.get(key);\n    if (cached !== undefined) {\n      return succeedWithDetail(cached, 'exists');\n    }\n\n    return this._inner.get(key).onSuccess((src) => {\n      return this._convertAndCache(key, src);\n    });\n  }\n\n  /**\n   * Checks if the map contains a key.\n   * @param key - The key to check.\n   * @returns `true` if the key exists, `false` otherwise.\n   */\n  public has(key: TK): boolean {\n    return this._inner.has(key);\n  }\n\n  /**\n   * Returns an iterator over the map entries with converted values.\n   * @returns An iterator over the map entries.\n   */\n  public *entries(): IterableIterator<KeyValueEntry<TK, TTARGET>> {\n    for (const [key, src] of this._inner.entries()) {\n      const target = this._getOrConvert(key, src);\n      if (target !== undefined) {\n        yield [key, target];\n      }\n    }\n  }\n\n  /**\n   * Returns an iterator over the map keys.\n   * @returns An iterator over the map keys.\n   */\n  public keys(): IterableIterator<TK> {\n    return this._inner.keys();\n  }\n\n  /**\n   * Returns an iterator over the converted map values.\n   * @returns An iterator over the map values.\n   */\n  public *values(): IterableIterator<TTARGET> {\n    for (const [key, src] of this._inner.entries()) {\n      const target = this._getOrConvert(key, src);\n      if (target !== undefined) {\n        yield target;\n      }\n    }\n  }\n\n  /**\n   * Calls a callback for each entry in the map with converted values.\n   * @param cb - The callback to call for each entry.\n   * @param thisArg - Optional `this` argument for the callback.\n   */\n  public forEach(cb: ResultMapForEachCb<TK, TTARGET>, thisArg?: unknown): void {\n    for (const [key, src] of this._inner.entries()) {\n      const target = this._getOrConvert(key, src);\n      if (target !== undefined) {\n        cb.call(thisArg, target, key, this);\n      }\n    }\n  }\n\n  /**\n   * Gets an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  public [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TTARGET>> {\n    return this.entries();\n  }\n\n  /**\n   * Gets a read-only version of this map.\n   * @returns A read-only version of this map.\n   */\n  public toReadOnly(): IReadOnlyResultMap<TK, TTARGET> {\n    return this;\n  }\n\n  /**\n   * Converts a source value to a target value and caches the result.\n   * @param key - The key of the value.\n   * @param src - The source value to convert.\n   * @returns `Success` with the converted value if successful, `Failure` otherwise.\n   */\n  protected _convertAndCache(key: TK, src: TSRC): DetailedResult<TTARGET, ResultMapResultDetail> {\n    const result = this._converter(src, key);\n    if (result.isFailure()) {\n      return failWithDetail(result.message, 'invalid-value');\n    }\n    this._cache.set(key, result.value);\n    return succeedWithDetail(result.value, 'exists');\n  }\n\n  /**\n   * Gets a cached value or converts and caches a source value.\n   * Used by iterators. Handles conversion failures according to `_onConversionError`.\n   * @param key - The key of the value.\n   * @param src - The source value to convert if not cached.\n   * @returns The converted value, or `undefined` if conversion failed.\n   * @throws Error if `_onConversionError` is `'fail'` and conversion fails.\n   */\n  protected _getOrConvert(key: TK, src: TSRC): TTARGET | undefined {\n    const cached = this._cache.get(key);\n    if (cached !== undefined) {\n      return cached;\n    }\n\n    const result = this._converter(src, key);\n    if (result.isSuccess()) {\n      this._cache.set(key, result.value);\n      return result.value;\n    }\n\n    switch (this._onConversionError) {\n      case 'fail':\n        throw new Error(`Conversion failed for key '${key}': ${result.message}`);\n      case 'warn':\n        this._logger?.log('warning', `Conversion failed for key '${key}': ${result.message}`);\n        break;\n    }\n    return undefined;\n  }\n\n  /**\n   * Clears a single entry from the cache.\n   * @param key - The key to clear from the cache.\n   */\n  protected _clearCacheEntry(key: TK): void {\n    this._cache.delete(key);\n  }\n\n  /**\n   * Clears all entries from the cache.\n   */\n  protected _clearCache(): void {\n    this._cache.clear();\n  }\n}\n"]}

package/lib/packlets/collections/readonlyResultMap.d.ts

@@ -18,31 +18,42 @@ export type ResultMapForEachCb<TK extends string = string, TE = unknown> = (valu
  */
 export interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {
     /**
-     * {@inheritDoc Collections.ResultMap.size}
+     * Returns the number of entries in the map.
      */
     readonly size: number;
     /**
-     * {@inheritDoc Collections.ResultMap.entries}
+     * Returns an iterator over the map entries.
+     * @returns An iterator over the map entries.
      */
     entries(): IterableIterator<KeyValueEntry<TK, TV>>;
     /**
-     * {@inheritDoc Collections.ResultMap.forEach}
+     * Calls a function for each entry in the map.
+     * @param cb - The function to call for each entry.
+     * @param arg - An optional argument to pass to the callback.
      */
     forEach(cb: ResultMapForEachCb, arg?: unknown): void;
     /**
-     * {@inheritDoc Collections.ResultMap.get}
+     * Gets a value from the map.
+     * @param key - The key to retrieve.
+     * @returns `Success` with the value and detail `exists` if the key was found,
+     * `Failure` with detail `not-found` if the key was not found or with detail
+     * `invalid-key` if the key is invalid.
      */
     get(key: TK): DetailedResult<TV, ResultMapResultDetail>;
     /**
-     * {@inheritDoc Collections.ResultMap.has}
+     * Returns `true` if the map contains a key.
+     * @param key - The key to check.
+     * @returns `true` if the key exists, `false` otherwise.
      */
     has(key: TK): boolean;
     /**
-     * {@inheritDoc Collections.ResultMap.keys}
+     * Returns an iterator over the map keys.
+     * @returns An iterator over the map keys.
      */
     keys(): IterableIterator<TK>;
     /**
-     * {@inheritDoc Collections.ResultMap.values}
+     * Returns an iterator over the map values.
+     * @returns An iterator over the map values.
      */
     values(): IterableIterator<TV>;
     /**

package/lib/packlets/collections/readonlyResultMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readonlyResultMap.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/readonlyResultMap.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAC7B,OAAO,GACP,SAAS,GACT,QAAQ,GACR,SAAS,GACT,aAAa,GACb,eAAe,GACf,WAAW,GACX,SAAS,GACT,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO,IAAI,CACzE,KAAK,EAAE,EAAE,EACT,GAAG,EAAE,EAAE,EACP,GAAG,EAAE,kBAAkB,CAAC,EAAE,EAAE,EAAE,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,KACd,IAAI,CAAC;AAEV;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO;IAC1E;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,OAAO,IAAI,gBAAgB,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAEnD;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,kBAAkB,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAErD;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,cAAc,CAAC,EAAE,EAAE,qBAAqB,CAAC,CAAC;IAExD;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAEtB;;;OAGG;IACH,IAAI,IAAI,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAE7B;;;OAGG;IACH,MAAM,IAAI,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAE/B;;;OAGG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;CAC9D"}

package/lib/packlets/collections/readonlyResultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readonlyResultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/readonlyResultMap.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","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 { DetailedResult } from '../base';\nimport { KeyValueEntry } from './common';\n\n/**\n * Additional success or failure details for {@link Collections.ResultMap | ResultMap} calls.\n * @public\n */\nexport type ResultMapResultDetail =\n  | 'added'\n  | 'deleted'\n  | 'exists'\n  | 'failure'\n  | 'invalid-key'\n  | 'invalid-value'\n  | 'not-found'\n  | 'success'\n  | 'updated';\n\n/**\n * Callback for {@link Collections.ResultMap | ResultMap} `forEach` method.\n * @public\n */\nexport type ResultMapForEachCb<TK extends string = string, TE = unknown> = (\n  value: TE,\n  key: TK,\n  map: IReadOnlyResultMap<TK, TE>,\n  thisArg?: unknown\n) => void;\n\n/**\n * A readonly `ReadonlyMap<TK, TV>`-like object which reports success or failure\n * with additional details using the\n * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#the-result-pattern | result pattern}.\n * @public\n */\nexport interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {\n  /**\n   * Returns the number of entries in the map.\n   */\n  readonly size: number;\n\n  /**\n   * Returns an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  entries(): IterableIterator<KeyValueEntry<TK, TV>>;\n\n  /**\n   * Calls a function for each entry in the map.\n   * @param cb - The function to call for each entry.\n   * @param arg - An optional argument to pass to the callback.\n   */\n  forEach(cb: ResultMapForEachCb, arg?: unknown): void;\n\n  /**\n   * Gets a value from the map.\n   * @param key - The key to retrieve.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Failure` with detail `not-found` if the key was not found or with detail\n   * `invalid-key` if the key is invalid.\n   */\n  get(key: TK): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Returns `true` if the map contains a key.\n   * @param key - The key to check.\n   * @returns `true` if the key exists, `false` otherwise.\n   */\n  has(key: TK): boolean;\n\n  /**\n   * Returns an iterator over the map keys.\n   * @returns An iterator over the map keys.\n   */\n  keys(): IterableIterator<TK>;\n\n  /**\n   * Returns an iterator over the map values.\n   * @returns An iterator over the map values.\n   */\n  values(): IterableIterator<TV>;\n\n  /**\n   * Gets an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TV>>;\n}\n"]}

package/lib/packlets/collections/resultMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resultMap.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/resultMap.ts"],"names":[],"mappings":"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"}

package/lib/packlets/collections/resultMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resultMap.js","sourceRoot":"","sources":["../../../src/packlets/collections/resultMap.ts"],"names":[],"mappings":"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","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, DetailedResult, failWithDetail, Result, succeed, succeedWithDetail } from '../base';\nimport { KeyValueEntry } from './common';\nimport { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';\nimport { isIterable } from './utils';\n\n/**\n * Parameters for constructing a {@link Collections.ResultMap | ResultMap}.\n * @public\n */\nexport interface IResultMapConstructorParams<TK extends string = string, TV = unknown> {\n  entries?: Iterable<KeyValueEntry<TK, TV>>;\n}\n\n/**\n * Deferred constructor for the {@link Collections.ResultMap.getOrAdd | getOrAdd} method.\n * @public\n */\nexport type ResultMapValueFactory<TK extends string = string, TV = unknown> = (key: TK) => Result<TV>;\n\n/**\n * Interface for a mutable {@link Collections.ResultMap | ResultMap}.\n * @public\n */\nexport interface IResultMap<TK extends string = string, TV = unknown> extends IReadOnlyResultMap<TK, TV> {\n  /**\n   * Sets a key/value pair in the map if the key does not already exist.\n   * @param key - The key to set.\n   * @param value - The value to set.\n   * @returns `Success` with the value and detail `added` if the key was added,\n   * `Failure` with detail `exists` if the key already exists. Fails with detail\n   * 'invalid-key' or 'invalid-value' and an error message if either is invalid.\n   */\n  add(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Sets a key/value pair in the map regardless of whether the key already exists.\n   * @param key - The key to set.\n   * @param value - The value to set.\n   * @returns `Success` with the new value and the detail `updated` if the\n   * key was found and updated, `Success` with the new value and detail\n   * `added` if the key was not found and added.  Fails with detail\n   * 'invalid-key' or 'invalid-value' and an error message if either is invalid.\n   */\n  set(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Updates the value associated with a key in the map.\n   * @param key - The key to update.\n   * @param value - The value to set.\n   * @returns `Success` with the value and detail 'updated' if the key was found\n   * and the value updated, `Failure` an error message and with detail `not-found`\n   * if the key was not found, or with detail 'invalid-key' or 'invalid-value'\n   * if either is invalid.\n   */\n  update(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Deletes a key from the map.\n   * @param key - The key to delete.\n   * @returns `Success` with the previous value and the detail 'deleted'\n   * if the key was found and deleted, `Failure` with detail 'not-found'\n   * if the key was not found, or with detail 'invalid-key' if the key is invalid.\n   */\n  delete(key: TK): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Gets a value from the map.\n   * @param key - The key to retrieve.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Failure` with detail `not-found` if the key was not found or with detail\n   * `invalid-key` if the key is invalid.\n   */\n  get(key: TK): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Gets a value from the map, or adds a supplied value if it does not exist.\n   * @param key - The key to be retrieved or created.\n   * @param value - The value to add if the key does not exist.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Success` with the value and detail `added` if the key was not found and added.\n   * Fails with detail 'invalid-key' or 'invalid-value' and an error message if either\n   * is invalid.\n   * {@label WITH_VALUE}\n   */\n  getOrAdd(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Gets a value from the map, or adds a value created by a factory function if it does not exist.\n   * @param key - The key of the element to be retrieved or created.\n   * @param factory - A {@link Collections.ResultMapValueFactory | factory function} to create the value if\n   * the key does not exist.\n   * @returns `Success` with the value and detail `exists` if the key was found, `Success` with\n   * the value and detail `added` if the key was not found and added. Fails with detail 'invalid-key'\n   * or 'invalid-value' and an error message if either is invalid.\n   * {@label WITH_FACTORY}\n   */\n  getOrAdd(key: TK, factory: ResultMapValueFactory<TK, TV>): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Returns an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  entries(): IterableIterator<KeyValueEntry<TK, TV>>;\n\n  /**\n   * Returns the number of entries in the map.\n   */\n  readonly size: number;\n\n  /**\n   * Returns an iterator over the map keys.\n   * @returns An iterator over the map keys.\n   */\n  keys(): IterableIterator<TK>;\n\n  /**\n   * Returns an iterator over the map values.\n   * @returns An iterator over the map values.\n   */\n  values(): IterableIterator<TV>;\n\n  /**\n   * Calls a function for each entry in the map.\n   * @param cb - The function to call for each entry.\n   * @param arg - An optional argument to pass to the callback.\n   */\n  forEach(cb: ResultMapForEachCb<TK, TV>, arg?: unknown): void;\n\n  /**\n   * Clears all entries from the map.\n   */\n  clear(): void;\n\n  /**\n   * Gets a readonly version of this map.\n   */\n  toReadOnly(): IReadOnlyResultMap<TK, TV>;\n}\n\n/**\n * A {@link Collections.ResultMap | ResultMap} class as a `Map<TK, TV>`-like object which\n * reports success or failure with additional details using the\n * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#the-result-pattern | result pattern}.\n * @public\n */\nexport class ResultMap<TK extends string = string, TV = unknown> implements IResultMap<TK, TV> {\n  /**\n   * Protected raw access to the inner `Map<TK, TV>` object.\n   * @public\n   */\n  protected readonly _inner: Map<TK, TV>;\n\n  /**\n   * Constructs a new {@link Collections.ResultMap | ResultMap}.\n   * @param iterable - An iterable to initialize the map.\n   */\n  public constructor(iterable?: Iterable<KeyValueEntry<TK, TV>>);\n\n  /**\n   * Constructs a new {@link Collections.ResultMap | ResultMap}.\n   * @param params - An optional set of parameters to configure the map.\n   */\n  public constructor(params: IResultMapConstructorParams);\n\n  /**\n   * Constructs a new {@link Collections.ResultMap | ResultMap}.\n   * @param iterableOrParams - An iterable to initialize the map, or a set of parameters\n   * to configure the map.\n   */\n  public constructor(\n    iterableOrParams?: Iterable<KeyValueEntry<TK, TV>> | IResultMapConstructorParams<TK, TV>\n  ) {\n    const params = isIterable(iterableOrParams) ? { entries: iterableOrParams } : iterableOrParams ?? {};\n    this._inner = new Map(params.entries);\n  }\n\n  /**\n   * Creates a new {@link Collections.ResultMap | ResultMap}.\n   * @param elements - An optional iterable to initialize the map.\n   * @returns `Success` with the new map, or `Failure` with error details\n   * if an error occurred.\n   * @public\n   */\n  public static create<TK extends string = string, TV = unknown>(\n    elements: Iterable<KeyValueEntry<TK, TV>>\n  ): Result<ResultMap<TK, TV>>;\n\n  /**\n   * Creates a new {@link Collections.ResultMap | ResultMap}.\n   * @param params - An optional set of parameters to configure the map.\n   * @returns `Success` with the new map, or `Failure` with error details\n   * if an error occurred.\n   * @public\n   */\n  public static create<TK extends string = string, TV = unknown>(\n    params?: IResultMapConstructorParams<TK, TV>\n  ): Result<ResultMap<TK, TV>>;\n\n  /**\n   * Creates a new {@link Collections.ResultMap | ResultMap}.\n   * @param elementsOrParams - An optional iterable to initialize the map, or a set of parameters\n   * to configure the map.\n   * @returns `Success` with the new map, or `Failure` with error details\n   * if an error occurred.\n   * @public\n   */\n  public static create<TK extends string = string, TV = unknown>(\n    elementsOrParams?: Iterable<KeyValueEntry<TK, TV>> | IResultMapConstructorParams<TK, TV>\n  ): Result<ResultMap<TK, TV>> {\n    return captureResult(() => new ResultMap(elementsOrParams as IResultMapConstructorParams<TK, TV>));\n  }\n\n  /**\n   * Sets a key/value pair in the map if the key does not already exist.\n   * @param key - The key to set.\n   * @param value - The value to set.\n   * @returns `Success` with the value and detail `added` if the key was added,\n   * `Failure` with detail `exists` if the key already exists. Fails with detail\n   * 'invalid-key' or 'invalid-value' and an error message if either is invalid.\n   */\n  public add(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail> {\n    if (this._inner.has(key)) {\n      return failWithDetail(`${key}: already exists.`, 'exists');\n    }\n    this._inner.set(key, value);\n    return succeedWithDetail(value, 'added');\n  }\n\n  /**\n   * Clears the map.\n   */\n  public clear(): void {\n    this._inner.clear();\n  }\n\n  /**\n   * Deletes a key from the map.\n   * @param key - The key to delete.\n   * @returns `Success` with the previous value and the detail 'deleted'\n   * if the key was found and deleted, `Failure` with detail 'not-found'\n   * if the key was not found, or with detail 'invalid-key' if the key is invalid.\n   */\n  public delete(key: TK): DetailedResult<TV, ResultMapResultDetail> {\n    const was = this._inner.get(key);\n    if (this._inner.delete(key)) {\n      return succeedWithDetail(was!, 'deleted');\n    }\n    return failWithDetail(`${key}: not found.`, 'not-found');\n  }\n\n  /**\n   * Returns an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  public entries(): IterableIterator<KeyValueEntry<TK, TV>> {\n    return this._inner.entries();\n  }\n\n  /**\n   * Calls a function for each entry in the map.\n   * @param cb - The function to call for each entry.\n   * @param arg - An optional argument to pass to the callback.\n   */\n  public forEach(cb: ResultMapForEachCb<TK, TV>, arg?: unknown): void {\n    for (const [key, value] of this._inner.entries()) {\n      cb(value, key as TK, this, arg);\n    }\n  }\n\n  /**\n   * Gets a value from the map.\n   * @param key - The key to retrieve.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Failure` with detail `not-found` if the key was not found or with detail\n   * `invalid-key` if the key is invalid.\n   */\n  public get(key: TK): DetailedResult<TV, ResultMapResultDetail> {\n    if (this._inner.has(key)) {\n      return succeedWithDetail(this._inner.get(key)!, 'exists');\n    }\n    return failWithDetail(`${key}: not found.`, 'not-found');\n  }\n\n  /**\n   * Gets a value from the map, or adds a supplied value it if it does not exist.\n   * @param key - The key to be retrieved or created.\n   * @param value - The value to add if the key does not exist.\n   * @returns `Success` with the value and detail `exists` if the key was found,\n   * `Success` with the value and detail `added` if the key was not found and added.\n   * Fails with detail 'invalid-key' or 'invalid-value' and an error message if either\n   * is invalid.\n   * {@label WITH_VALUE}\n   */\n  public getOrAdd(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * Gets a value from the map, or adds a value created by a factory function if it does not exist.\n   * @param key - The key of the element to be retrieved or created.\n   * @param factory - A {@link Collections.ResultMapValueFactory | factory function} to create the value if\n   * the key does not exist.\n   * @returns `Success` with the value and detail `exists` if the key was found, `Success` with\n   * the value and detail `added` if the key was not found and added. Fails with detail 'invalid-key'\n   * or 'invalid-value' and an error message if either is invalid.\n   * {@label WITH_FACTORY}\n   */\n  public getOrAdd(key: TK, factory: ResultMapValueFactory<TK, TV>): DetailedResult<TV, ResultMapResultDetail>;\n  public getOrAdd(\n    key: TK,\n    valueOrFactory: TV | ResultMapValueFactory<TK, TV>\n  ): DetailedResult<TV, ResultMapResultDetail> {\n    if (this._inner.has(key)) {\n      return succeedWithDetail(this._inner.get(key)!, 'exists');\n    }\n\n    const factory: ResultMapValueFactory<TK, TV> = this._isResultMapValueFactory(valueOrFactory)\n      ? valueOrFactory\n      : () => succeed(valueOrFactory);\n\n    return factory(key)\n      .onSuccess((val) => {\n        this._inner.set(key, val);\n        return succeedWithDetail(val, 'added');\n      })\n      .withDetail('invalid-value', 'added');\n  }\n\n  /**\n   * Returns `true` if the map contains a key.\n   * @param key - The key to check.\n   * @returns `true` if the key exists, `false` otherwise.\n   */\n  public has(key: TK): boolean {\n    return this._inner.has(key);\n  }\n\n  /**\n   * Returns an iterator over the map keys.\n   * @returns An iterator over the map keys.\n   */\n  public keys(): IterableIterator<TK> {\n    return this._inner.keys();\n  }\n\n  /**\n   * Sets a key/value pair in the map.\n   * @param key - The key to set.\n   * @param value - The value to set.\n   * @returns `Success` with the new value and the detail `updated` if the\n   * key was found and updated, `Success` with the new value and detail\n   * `added` if the key was not found and added.  Fails with detail\n   * 'invalid-key' or 'invalid-value' and an error message if either is invalid.\n   */\n  public set(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail> {\n    const detail: ResultMapResultDetail = this._inner.has(key) ? 'updated' : 'added';\n    this._inner.set(key, value);\n    return succeedWithDetail(value, detail);\n  }\n\n  /**\n   * Returns the number of entries in the map.\n   */\n  public get size(): number {\n    return this._inner.size;\n  }\n\n  /**\n   * Updates an existing key in the map - the map is not updated if the key does\n   * not exist.\n   * @param key - The key to update.\n   * @param value - The value to set.\n   * @returns `Success` with the value and detail 'exists' if the key was found\n   * and the value updated, `Failure` an error message and with detail `not-found`\n   * if the key was not found, or with detail 'invalid-key' or 'invalid-value'\n   * if either is invalid.\n   */\n  public update(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail> {\n    if (this._inner.has(key)) {\n      this._inner.set(key, value);\n      return succeedWithDetail(value, 'updated');\n    }\n    return failWithDetail(`${key}: not found.`, 'not-found');\n  }\n\n  /**\n   * Returns an iterator over the map values.\n   * @returns An iterator over the map values.\n   */\n  public values(): IterableIterator<TV> {\n    return this._inner.values();\n  }\n\n  /**\n   * Gets an iterator over the map entries.\n   * @returns An iterator over the map entries.\n   */\n  public [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TV>> {\n    return this._inner[Symbol.iterator]();\n  }\n\n  /**\n   * Gets a readonly version of this map.\n   * @returns A readonly version of this map.\n   */\n  public toReadOnly(): IReadOnlyResultMap<TK, TV> {\n    return this;\n  }\n\n  /**\n   * Determines if a value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory}.\n   * @param value - The value to check.\n   * @returns `true` if the value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory},\n   * `false` otherwise.\n   * @public\n   */\n  protected _isResultMapValueFactory<TK extends string, TV>(\n    value: TV | ResultMapValueFactory<TK, TV>\n  ): value is ResultMapValueFactory<TK, TV> {\n    return typeof value === 'function';\n  }\n}\n"]}

package/lib/packlets/collections/resultMapValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resultMapValidator.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/resultMapValidator.ts"],"names":[],"mappings":"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"}

package/lib/packlets/collections/resultMapValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resultMapValidator.js","sourceRoot":"","sources":["../../../src/packlets/collections/resultMapValidator.ts"],"names":[],"mappings":"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","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 { DetailedResult, failWithDetail, succeedWithDetail } from '../base';\nimport { IReadOnlyResultMap, ResultMapResultDetail } from './readonlyResultMap';\nimport { ResultMap, ResultMapValueFactory } from './resultMap';\nimport { KeyValueConverters } from './keyValueConverters';\n\n/**\n * A read-only interface exposing non-mutating methods of a {@link Collections.ResultMapValidator | ResultMapValidator}.\n * @public\n */\nexport interface IReadOnlyResultMapValidator<TK extends string = string, TV = unknown> {\n  /**\n   * {@inheritDoc Collections.ReadOnlyResultMapValidator.map}\n   */\n  readonly map: IReadOnlyResultMap<TK, TV>;\n\n  /**\n   * {@inheritDoc Collections.ResultMap.get}\n   */\n  get(key: string): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * {@inheritDoc Collections.ResultMap.has}\n   */\n  has(key: string): boolean;\n}\n\n/**\n * Parameters for constructing a {@link Collections.ResultMapValidator | ResultMapValidator}.\n * @public\n */\nexport interface IResultMapValidatorCreateParams<TK extends string = string, TV = unknown> {\n  map: ResultMap<TK, TV>;\n  converters: KeyValueConverters<TK, TV>;\n}\n\n/**\n * A read-only validator for any {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}\n * that validates weakly-typed keys before accessing values.\n * @public\n */\nexport class ReadOnlyResultMapValidator<TK extends string = string, TV = unknown>\n  implements IReadOnlyResultMapValidator<TK, TV>\n{\n  /**\n   * The key-value converters used for validation.\n   */\n  public readonly converters: KeyValueConverters<TK, TV>;\n\n  /**\n   * The underlying map.\n   */\n  public get map(): IReadOnlyResultMap<TK, TV> {\n    return this._map;\n  }\n\n  private readonly _map: IReadOnlyResultMap<TK, TV>;\n\n  /**\n   * Constructs a new {@link Collections.ReadOnlyResultMapValidator | ReadOnlyResultMapValidator}.\n   * @param map - The map to validate access to.\n   * @param converters - The key-value converters for validation.\n   */\n  public constructor(map: IReadOnlyResultMap<TK, TV>, converters: KeyValueConverters<TK, TV>) {\n    this._map = map;\n    this.converters = converters;\n  }\n\n  /**\n   * Gets a value from the map by key, validating the key first.\n   * @param key - The key to retrieve (will be validated).\n   * @returns `Success` with the value if found, `Failure` otherwise.\n   */\n  public get(key: string): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((validKey) => {\n      return this._map.get(validKey);\n    });\n  }\n\n  /**\n   * Checks if the map contains a key, validating the key first.\n   * @param key - The key to check (will be validated).\n   * @returns `true` if the key exists and is valid, `false` otherwise.\n   */\n  public has(key: string): boolean {\n    const result = this.converters.convertKey(key);\n    if (result.isFailure()) {\n      return false;\n    }\n    return this._map.has(result.value);\n  }\n}\n\n/**\n * A {@link Collections.ResultMap | ResultMap} wrapper which validates weakly-typed keys\n * before calling the wrapped result map.\n * @public\n */\nexport class ResultMapValidator<TK extends string = string, TV = unknown>\n  implements IReadOnlyResultMapValidator<TK, TV>\n{\n  public readonly converters: KeyValueConverters<TK, TV>;\n  public get map(): IReadOnlyResultMap<TK, TV> {\n    return this._map;\n  }\n\n  protected _map: ResultMap<TK, TV>;\n\n  /**\n   * Constructs a new {@link Collections.ResultMapValidator | ResultMapValidator}.\n   * @param params - Required parameters for constructing the result map validator.\n   */\n  public constructor(params: IResultMapValidatorCreateParams<TK, TV>) {\n    this._map = params.map;\n    this.converters = params.converters;\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.add}\n   */\n  public add(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {\n      return this._map.add(vk, vv);\n    });\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.delete}\n   */\n  public delete(key: string): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((k) => {\n      return this._map.delete(k);\n    });\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.get}\n   */\n  public get(key: string): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertKey(key).onSuccess((k) => {\n      return this._map.get(k);\n    });\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.getOrAdd}\n   */\n  public getOrAdd(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * {@inheritDoc Collections.ResultMap.getOrAdd}\n   */\n  public getOrAdd(\n    key: string,\n    factory: ResultMapValueFactory<TK, TV>\n  ): DetailedResult<TV, ResultMapResultDetail>;\n  public getOrAdd(\n    key: string,\n    valueOrFactory: unknown | ResultMapValueFactory<TK, TV>\n  ): DetailedResult<TV, ResultMapResultDetail> {\n    if (!this._isResultMapValueFactory(valueOrFactory)) {\n      return this.converters.convertEntry([key, valueOrFactory]).onSuccess(([vk, vv]) => {\n        return this._map.getOrAdd(vk, vv);\n      });\n    } else {\n      return this.converters.convertKey(key).onSuccess((k) => {\n        return this._map.get(k).onFailure(() => {\n          const value = valueOrFactory(k)\n            .onSuccess((value) => this.converters.convertEntry([k, value]))\n            .onSuccess(([__key, value]) => succeedWithDetail(value, 'added'));\n\n          return value.success\n            ? this._map.add(k, value.value)\n            : failWithDetail<TV, ResultMapResultDetail>(value.message, 'invalid-value');\n        });\n      });\n    }\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.has}\n   */\n  public has(key: string): boolean {\n    return this._map.has(key as TK);\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.set}\n   */\n  public set(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {\n      return this._map.set(vk, vv);\n    });\n  }\n\n  /**\n   * {@inheritDoc Collections.ResultMap.update}\n   */\n  public update(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail> {\n    return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {\n      return this._map.update(vk, vv);\n    });\n  }\n\n  /**\n   * Gets a read-only version of this validator.\n   */\n  public toReadOnly(): IReadOnlyResultMapValidator<TK, TV> {\n    return this;\n  }\n\n  /**\n   * Determines if a value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory}.\n   * @param value - The value to check.\n   * @returns `true` if the value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory},\n   * `false` otherwise.\n   * @public\n   */\n  protected _isResultMapValueFactory<TK extends string, TV>(\n    value: TV | ResultMapValueFactory<TK, TV>\n  ): value is ResultMapValueFactory<TK, TV> {\n    return typeof value === 'function';\n  }\n}\n"]}

package/lib/packlets/collections/retainingRingBuffer.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Minimal structural contract a {@link RetainingRingBuffer} record must satisfy:
+ * a monotonic `seq` the buffer pages on. Records carry their own `seq` (assigned
+ * by the caller) so the buffer is agnostic about how records are minted — a logger
+ * assigns `seq` from its own counter, an observability layer assigns a library-global
+ * `seq` shared across several buffers, etc.
+ * @public
+ */
+export interface IRetainedRecord {
+    /**
+     * Monotonic sequence number, assigned by the caller. The buffer requires
+     * **strictly increasing** `seq` across successive {@link RetainingRingBuffer.push | push}
+     * calls — `sinceSeq` cursor paging uses a strict `seq > sinceSeq` filter, so
+     * duplicate `seq` values held by a consumer cursor would never be re-yielded
+     * if pushed afterward. {@link RetainingRingBuffer.lastSeq | lastSeq} likewise
+     * advances only past values strictly greater than its current value.
+     */
+    readonly seq: number;
+}
+/**
+ * Query options for {@link RetainingRingBuffer.query}.
+ * @public
+ */
+export interface IRetainingRingBufferQuery<T extends IRetainedRecord> {
+    /**
+     * If supplied, only records with `seq > sinceSeq` are returned, enabling
+     * incremental paging from a previously-held cursor.
+     */
+    readonly sinceSeq?: number;
+    /**
+     * If supplied, returns at most this many records — the most recent N (tail),
+     * still ordered oldest-first.
+     */
+    readonly limit?: number;
+    /**
+     * If supplied, only records for which the predicate returns `true` are
+     * returned. Applied before `limit`, so `limit` bounds the filtered tail.
+     */
+    readonly filter?: (record: T) => boolean;
+}
+/**
+ * Construction options for {@link RetainingRingBuffer}.
+ * @public
+ */
+export interface IRetainingRingBufferCreateParams {
+    /**
+     * The maximum number of records retained before the oldest is overwritten.
+     * Defaults to `1000`. Normalized to a positive integer: a fractional value is
+     * floored toward the integer below (`2.9` → `2`), and a non-finite or sub-1
+     * value is floored to `1` (the ring requires a positive integer capacity to
+     * be well-defined).
+     */
+    readonly maxRecords?: number;
+}
+/**
+ * A generic bounded most-recent-N ring of records, with monotonic-`seq` cursor
+ * paging and predicate filtering.
+ *
+ * @remarks
+ * The buffer is a pure storage substrate: the caller mints each record (assigning
+ * its own `seq` and any other fields) and {@link RetainingRingBuffer.push | push}es
+ * it. The buffer never reshapes a record — it only retains, evicts the oldest when
+ * full (O(1), no `shift()` re-indexing regardless of capacity), and answers queries.
+ *
+ * Separating record minting from retention lets one `seq` authority feed several
+ * buffers consistently (e.g. an observability layer that assigns a library-global
+ * `seq` and fans the same record out to multiple retaining stores), and lets a
+ * single-authority consumer (e.g. a logger) own its own `seq` counter. It is the
+ * shared mechanism beneath `RetainingLogger` and
+ * any schema-aware observation store.
+ *
+ * @public
+ */
+export declare class RetainingRingBuffer<T extends IRetainedRecord> {
+    /**
+     * The fixed ring capacity — the maximum number of records retained before the
+     * oldest is overwritten. A positive integer (see the constructor normalization).
+     * @internal
+     */
+    private readonly _capacity;
+    /**
+     * The backing store, used as a circular buffer. Grows lazily up to `_capacity`,
+     * after which records overwrite the oldest slot in place — eviction is O(1), with
+     * no `shift()` re-indexing regardless of capacity.
+     * @internal
+     */
+    private _buffer;
+    /**
+     * Index of the oldest retained record within `_buffer` once the ring is full.
+     * @internal
+     */
+    private _head;
+    /**
+     * The number of valid records currently retained (`<= _capacity`).
+     * @internal
+     */
+    private _count;
+    /**
+     * The highest `seq` ever pushed; monotonic, stable across eviction and
+     * {@link RetainingRingBuffer.clear | clear()}.
+     * @internal
+     */
+    private _lastSeq;
+    /**
+     * Creates a new retaining ring buffer.
+     * @param params - {@link IRetainingRingBufferCreateParams | Construction options}.
+     */
+    constructor(params?: IRetainingRingBufferCreateParams);
+    /**
+     * The number of records currently retained.
+     */
+    get size(): number;
+    /**
+     * The highest `seq` pushed so far. A client can hold this value and pass it as
+     * `sinceSeq` to page only records pushed afterward. Stable across eviction and
+     * {@link RetainingRingBuffer.clear | clear()}.
+     */
+    get lastSeq(): number;
+    /**
+     * The retained records, oldest-first.
+     */
+    get records(): ReadonlyArray<T>;
+    /**
+     * Retains a record, evicting the oldest if the ring is full.
+     * @param record - The record to retain. Its `seq` should be greater than the
+     * `seq` of the previously-pushed record so cursor paging stays monotonic.
+     * @returns The same record, for call-site chaining.
+     */
+    push(record: T): T;
+    /**
+     * Returns retained records, oldest-first, optionally filtered and paged.
+     * @param query - {@link IRetainingRingBufferQuery | Filtering and paging options}.
+     * @returns The matching records, oldest-first.
+     */
+    query(query?: IRetainingRingBufferQuery<T>): ReadonlyArray<T>;
+    /**
+     * Clears all retained records. Does NOT reset {@link RetainingRingBuffer.lastSeq | lastSeq},
+     * so a client holding a `sinceSeq` cursor never re-sees a sequence number.
+     */
+    clear(): void;
+    /**
+     * Materializes the ring into a plain oldest-first array.
+     * @internal
+     */
+    private _toOrderedArray;
+}
+//# sourceMappingURL=retainingRingBuffer.d.ts.map

package/lib/packlets/collections/retainingRingBuffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retainingRingBuffer.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/retainingRingBuffer.ts"],"names":[],"mappings":"AAsBA;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC,SAAS,eAAe;IAClE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAmB,CAAC,CAAC,SAAS,eAAe;IACxD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;;;;OAKG;IACH,OAAO,CAAC,OAAO,CAAW;IAE1B;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAa;IAE1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAa;IAE3B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAa;IAE7B;;;OAGG;gBACgB,MAAM,CAAC,EAAE,gCAAgC;IAQ5D;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACH,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,aAAa,CAAC,CAAC,CAAC,CAErC;IAED;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC;IAgBzB;;;;OAIG;IACI,KAAK,CAAC,KAAK,CAAC,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC;IAepE;;;OAGG;IACI,KAAK,IAAI,IAAI;IAMpB;;;OAGG;IACH,OAAO,CAAC,eAAe;CAOxB"}

package/lib/packlets/collections/retainingRingBuffer.js

@@ -0,0 +1,163 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetainingRingBuffer = void 0;
+/**
+ * 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
+ */
+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;
+    }
+}
+exports.RetainingRingBuffer = RetainingRingBuffer;
+//# sourceMappingURL=retainingRingBuffer.js.map

package/lib/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/lib/packlets/collections/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/utils.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EAAE,GAAG,OAAO,EAAE,EAAE,SAAS,QAAQ,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,EAC3F,KAAK,EAAE,EAAE,GAAG,EAAE,GACb,KAAK,IAAI,EAAE,CAEb"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/packlets/collections/utils.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAQH,gCAIC;AAVD;;;;;GAKG;AACH,SAAgB,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/lib/packlets/collections/validatingCollector.d.ts

@@ -12,15 +12,19 @@ import { CollectorValidator } from './collectorValidator';
  */
 export interface IReadOnlyValidatingCollector<TITEM extends ICollectible<any, any>> extends IReadOnlyValidatingResultMap<CollectibleKey<TITEM>, TITEM> {
     /**
-     * {@inheritDoc Collections.ValidatingCollector.validating}
+     * A {@link Collections.CollectorValidator | CollectorValidator} which validates keys and values
+     * before inserting them into this collector.
      */
     readonly validating: IReadOnlyCollectorValidator<TITEM>;
     /**
-     * {@inheritDoc Collections.IReadOnlyCollector.getAt}
+     * Gets the item at a specified index.
+     * @param index - The index of the item to retrieve.
+     * @returns `Success` with the item if it exists, or `Failure` with an error if the index is out of range.
      */
     getAt(index: number): Result<TITEM>;
     /**
-     * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
+     * Gets all items in the collection, ordered by index.
+     * @returns An array of items in the collection, ordered by index.
      */
     valuesByIndex(): ReadonlyArray<TITEM>;
 }

package/lib/packlets/collections/validatingCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingCollector.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/validatingCollector.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAiB,MAAM,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;GAIG;AAEH,MAAM,WAAW,4BAA4B,CAE3C,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,CACpC,SAAQ,4BAA4B,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAClE;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC,KAAK,CAAC,CAAC;IAExD;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEpC;;;OAGG;IACH,aAAa,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,qCAAqC,CAEpD,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC;IAEpC;;OAEG;IACH,UAAU,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAE7D;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,mBAAmB,CAE9B,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,CACpC,SAAQ,SAAS,CAAC,KAAK,CAAC;IACxB;;;OAGG;IACH,SAAgB,UAAU,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAEtD,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAEjF;;;;OAIG;gBACgB,MAAM,EAAE,qCAAqC,CAAC,KAAK,CAAC;IASvE;;;;;OAKG;WACW,yBAAyB,CAErC,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,MAAM,EAAE,qCAAqC,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAI3F;;;;OAIG;IACI,UAAU,IAAI,4BAA4B,CAAC,KAAK,CAAC;CAGzD"}

package/lib/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,kCAAgD;AAKhD,2CAAwC;AACxC,6DAA0D;AAmD1D;;;;GAIG;AACH,MAAa,mBAGX,SAAQ,qBAAgB;IASxB;;;;OAIG;IACH,YAAmB,MAAoD;;QACrE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,uCAAkB,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,IAAA,oBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;;;OAIG;IACI,UAAU;QACf,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AA/CD,kDA+CC","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/lib/packlets/collections/validatingConvertingCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validatingConvertingCollector.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/validatingConvertingCollector.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAiB,MAAM,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAErE;;;GAGG;AACH,MAAM,WAAW,+CAA+C,CAE9D,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,IAAI,GAAG,KAAK;IAEZ;;OAEG;IACH,OAAO,EAAE,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,UAAU,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IAE5D;;OAEG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;CACxD;AAED;;;;;GAKG;AACH,qBAAa,6BAA6B,CAExC,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,IAAI,GAAG,KAAK,CACZ,SAAQ,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC;IACxC;;;OAGG;IACH,SAAgB,UAAU,EAAE,4BAA4B,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAEtE,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IAEhF;;;;OAIG;gBACgB,MAAM,EAAE,+CAA+C,CAAC,KAAK,EAAE,IAAI,CAAC;IASvF;;;;;OAKG;WACW,yBAAyB,CAErC,KAAK,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,IAAI,GAAG,KAAK,EAEZ,MAAM,EAAE,+CAA+C,CAAC,KAAK,EAAE,IAAI,CAAC,GACnE,MAAM,CAAC,6BAA6B,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAIrD;;;;OAIG;IACI,UAAU,IAAI,4BAA4B,CAAC,KAAK,CAAC;CAGzD"}