@fgv/ts-utils 4.2.2 → 4.4.0

package/lib/packlets/collections/keyValueConverters.js

@@ -0,0 +1,104 @@
+"use strict";
+/*
+ * Copyright (c) 2025 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.KeyValueConverters = void 0;
+const base_1 = require("../base");
+const conversion_1 = require("../conversion");
+/**
+ * Helper class for converting strongly-typed keys, values, or entries
+ * from unknown values.
+ * @public
+ */
+class KeyValueConverters {
+    /**
+     * Constructs a new key-value validator.
+     * @param key - Required key {@link Validator | validator}, {@link Converter | converter},
+     * or {@link Conversion.ConverterFunc | converter function}.
+     * @param value - Required value {@link Validator | validator}, {@link Converter | converter},
+     * or {@link Conversion.ConverterFunc | converter function}.
+     */
+    constructor({ key, value }) {
+        this.key = typeof key === 'function' ? conversion_1.Converters.generic(key) : key;
+        this.value = typeof value === 'function' ? conversion_1.Converters.generic(value) : value;
+    }
+    /**
+     * Converts a supplied unknown to a valid key value of type `<TK>`.
+     * @param key - The unknown to be converted.
+     * @returns `Success` with the converted key value and 'success' detail if the key is valid,
+     * or `Failure` with an error message and 'invalid-key' detail if the key is invalid.
+     */
+    convertKey(key) {
+        return this.key.convert(key).withFailureDetail('invalid-key');
+    }
+    /**
+     * Converts a supplied unknown to a valid value of type `<TV>`.
+     * @param key - The unknown to be converted.
+     * @returns `Success` with the converted value and 'success' detail if the value is valid,
+     * or `Failure` with an error message and 'invalid-value' detail if the value is invalid.
+     */
+    convertValue(key) {
+        return this.value.convert(key).withFailureDetail('invalid-value');
+    }
+    /**
+     * Converts a supplied unknown to a valid entry of type `[<TK>, <TV>]`.
+     * @param entry - The unknown to be converted.
+     * @returns `Success` with the converted entry and 'success' detail if the entry
+     * is valid, or `Failure` with an error message and 'invalid-key' or 'invalid-value' detail if
+     * the entry is invalid
+     */
+    convertEntry(entry) {
+        if (Array.isArray(entry) && entry.length === 2) {
+            const errors = new base_1.MessageAggregator();
+            const key = this.convertKey(entry[0]).aggregateError(errors).orDefault();
+            const value = this.convertValue(entry[1]).aggregateError(errors).orDefault();
+            if (key && value) {
+                return (0, base_1.succeedWithDetail)([key, value], 'success');
+            }
+            const detail = key ? 'invalid-value' : 'invalid-key';
+            return (0, base_1.failWithDetail)(`invalid entry: ${errors.toString()}`, detail);
+        }
+        /* c8 ignore next 2 */
+        return (0, base_1.failWithDetail)(`malformed entry: "${JSON.stringify(entry)}"`, 'invalid-value');
+    }
+    /**
+     * Converts a supplied iterable of unknowns to valid key-value pairs.
+     * @param entries - The iterable of unknowns to be converted.
+     * @returns `Success` with an array of converted key-value pairs if all entries are valid,
+     * or `Failure` with an error message if any entry is invalid.
+     */
+    convertEntries(entries) {
+        const errors = new base_1.MessageAggregator();
+        const converted = [];
+        for (const element of entries) {
+            this.convertEntry(element)
+                .onSuccess((e) => {
+                converted.push(e);
+                return (0, base_1.succeedWithDetail)(e, 'success');
+            })
+                .aggregateError(errors);
+        }
+        return errors.returnOrReport((0, base_1.succeed)(converted));
+    }
+}
+exports.KeyValueConverters = KeyValueConverters;
+//# sourceMappingURL=keyValueConverters.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyValueConverters.js","sourceRoot":"","sources":["../../../src/packlets/collections/keyValueConverters.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,kCAOiB;AACjB,8CAAqE;AAuBrE;;;;GAIG;AACH,MAAa,kBAAkB;IAU7B;;;;;;OAMG;IACH,YAAmB,EAAE,GAAG,EAAE,KAAK,EAA+C;QAC5E,IAAI,CAAC,GAAG,GAAG,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,uBAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QACrE,IAAI,CAAC,KAAK,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,uBAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC/E,CAAC;IAED;;;;;OAKG;IACI,UAAU,CAAC,GAAY;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAChE,CAAC;IAED;;;;;OAKG;IACI,YAAY,CAAC,GAAY;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,eAAe,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;OAMG;IACI,YAAY,CAAC,KAAc;QAChC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/C,MAAM,MAAM,GAAG,IAAI,wBAAiB,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC;YACzE,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC;YAC7E,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;gBACjB,OAAO,IAAA,wBAAiB,EAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;YACpD,CAAC;YACD,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,aAAa,CAAC;YACrD,OAAO,IAAA,qBAAc,EAAC,kBAAkB,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;QACvE,CAAC;QACD,sBAAsB;QACtB,OAAO,IAAA,qBAAc,EAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IACxF,CAAC;IAED;;;;;OAKG;IACI,cAAc,CAAC,OAA0B;QAC9C,MAAM,MAAM,GAAG,IAAI,wBAAiB,EAAE,CAAC;QACvC,MAAM,SAAS,GAA4B,EAAE,CAAC;QAC9C,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;iBACvB,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;gBACf,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,OAAO,IAAA,wBAAiB,EAAC,CAAC,EAAE,SAAS,CAAC,CAAC;YACzC,CAAC,CAAC;iBACD,cAAc,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,MAAM,CAAC,cAAc,CAAC,IAAA,cAAO,EAAC,SAAS,CAAC,CAAC,CAAC;IACnD,CAAC;CACF;AAnFD,gDAmFC","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 {\n  DetailedResult,\n  failWithDetail,\n  MessageAggregator,\n  Result,\n  succeed,\n  succeedWithDetail\n} from '../base';\nimport { Converter, ConverterFunc, Converters } from '../conversion';\nimport { Validator } from '../validation';\nimport { KeyValueEntry } from './common';\nimport { ResultMapResultDetail } from './readonlyResultMap';\n\n/**\n * Parameters for constructing a {@link Collections.KeyValueConverters | KeyValueConverters} instance.\n * @public\n */\nexport interface IKeyValueConverterConstructorParams<TK extends string = string, TV = unknown> {\n  /**\n   * Required key {@link Validator | validator}, {@link Converter | converter},\n   * or {@link Conversion.ConverterFunc | converter function}.\n   */\n  key: Validator<TK, unknown> | Converter<TK, unknown> | ConverterFunc<TK, unknown>;\n\n  /**\n   * Required value {@link Validator | validator}, {@link Converter | converter},\n   * or {@link Conversion.ConverterFunc | converter function}.\n   */\n  value: Validator<TV, unknown> | Converter<TV, unknown> | ConverterFunc<TV, unknown>;\n}\n\n/**\n * Helper class for converting strongly-typed keys, values, or entries\n * from unknown values.\n * @public\n */\nexport class KeyValueConverters<TK extends string = string, TV = unknown> {\n  /**\n   * Required key {@link Validator | validator} or {@link Converter | converter}.\n   */\n  public readonly key: Validator<TK, unknown> | Converter<TK, unknown>;\n  /**\n   * Required value {@link Validator | validator} or {@link Converter | converter}.\n   */\n  public readonly value: Validator<TV, unknown> | Converter<TV, unknown>;\n\n  /**\n   * Constructs a new key-value validator.\n   * @param key - Required key {@link Validator | validator}, {@link Converter | converter},\n   * or {@link Conversion.ConverterFunc | converter function}.\n   * @param value - Required value {@link Validator | validator}, {@link Converter | converter},\n   * or {@link Conversion.ConverterFunc | converter function}.\n   */\n  public constructor({ key, value }: IKeyValueConverterConstructorParams<TK, TV>) {\n    this.key = typeof key === 'function' ? Converters.generic(key) : key;\n    this.value = typeof value === 'function' ? Converters.generic(value) : value;\n  }\n\n  /**\n   * Converts a supplied unknown to a valid key value of type `<TK>`.\n   * @param key - The unknown to be converted.\n   * @returns `Success` with the converted key value and 'success' detail if the key is valid,\n   * or `Failure` with an error message and 'invalid-key' detail if the key is invalid.\n   */\n  public convertKey(key: unknown): DetailedResult<TK, ResultMapResultDetail> {\n    return this.key.convert(key).withFailureDetail('invalid-key');\n  }\n\n  /**\n   * Converts a supplied unknown to a valid value of type `<TV>`.\n   * @param key - The unknown to be converted.\n   * @returns `Success` with the converted value and 'success' detail if the value is valid,\n   * or `Failure` with an error message and 'invalid-value' detail if the value is invalid.\n   */\n  public convertValue(key: unknown): DetailedResult<TV, ResultMapResultDetail> {\n    return this.value.convert(key).withFailureDetail('invalid-value');\n  }\n\n  /**\n   * Converts a supplied unknown to a valid entry of type `[<TK>, <TV>]`.\n   * @param entry - The unknown to be converted.\n   * @returns `Success` with the converted entry and 'success' detail if the entry\n   * is valid, or `Failure` with an error message and 'invalid-key' or 'invalid-value' detail if\n   * the entry is invalid\n   */\n  public convertEntry(entry: unknown): DetailedResult<KeyValueEntry<TK, TV>, ResultMapResultDetail> {\n    if (Array.isArray(entry) && entry.length === 2) {\n      const errors = new MessageAggregator();\n      const key = this.convertKey(entry[0]).aggregateError(errors).orDefault();\n      const value = this.convertValue(entry[1]).aggregateError(errors).orDefault();\n      if (key && value) {\n        return succeedWithDetail([key, value], 'success');\n      }\n      const detail = key ? 'invalid-value' : 'invalid-key';\n      return failWithDetail(`invalid entry: ${errors.toString()}`, detail);\n    }\n    /* c8 ignore next 2 */\n    return failWithDetail(`malformed entry: \"${JSON.stringify(entry)}\"`, 'invalid-value');\n  }\n\n  /**\n   * Converts a supplied iterable of unknowns to valid key-value pairs.\n   * @param entries - The iterable of unknowns to be converted.\n   * @returns `Success` with an array of converted key-value pairs if all entries are valid,\n   * or `Failure` with an error message if any entry is invalid.\n   */\n  public convertEntries(entries: Iterable<unknown>): Result<KeyValueEntry<TK, TV>[]> {\n    const errors = new MessageAggregator();\n    const converted: KeyValueEntry<TK, TV>[] = [];\n    for (const element of entries) {\n      this.convertEntry(element)\n        .onSuccess((e) => {\n          converted.push(e);\n          return succeedWithDetail(e, 'success');\n        })\n        .aggregateError(errors);\n    }\n    return errors.returnOrReport(succeed(converted));\n  }\n}\n"]}

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

@@ -4,7 +4,7 @@ import { KeyValueEntry } from './common';
  * Additional success or failure details for {@link Collections.ResultMap | ResultMap} calls.
  * @public
  */
-export type ResultMapResultDetail = 'added' | 'deleted' | 'exists' | 'invalid-key' | 'invalid-value' | 'not-found' | 'success' | 'updated';
+export type ResultMapResultDetail = 'added' | 'deleted' | 'exists' | 'failure' | 'invalid-key' | 'invalid-value' | 'not-found' | 'success' | 'updated';
 /**
  * Callback for {@link Collections.ResultMap | ResultMap} `forEach` method.
  * @public

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

@@ -1 +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,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,KAAK,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,OAAO,IAAI,WAAW,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAE9C;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,kBAAkB,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAErD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,cAAc,CAAC,EAAE,EAAE,qBAAqB,CAAC,CAAC;IAExD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAEtB;;OAEG;IACH,IAAI,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC;IAExB;;OAEG;IACH,MAAM,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC;IAE1B;;;OAGG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;CAC9D"}
+{"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,KAAK,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,OAAO,IAAI,WAAW,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAE9C;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,kBAAkB,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAErD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,cAAc,CAAC,EAAE,EAAE,qBAAqB,CAAC,CAAC;IAExD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAEtB;;OAEG;IACH,IAAI,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC;IAExB;;OAEG;IACH,MAAM,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC;IAE1B;;;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

@@ -1 +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  | '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   * {@inheritdoc Collections.ResultMap.inner}\n   */\n  readonly inner: ReadonlyMap<TK, TV>;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.size}\n   */\n  readonly size: number;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.entries}\n   */\n  entries(): MapIterator<KeyValueEntry<TK, TV>>;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.forEach}\n   */\n  forEach(cb: ResultMapForEachCb, arg?: unknown): void;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.get}\n   */\n  get(key: TK): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.has}\n   */\n  has(key: TK): boolean;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.keys}\n   */\n  keys(): MapIterator<TK>;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.values}\n   */\n  values(): MapIterator<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"]}
+{"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   * {@inheritdoc Collections.ResultMap.inner}\n   */\n  readonly inner: ReadonlyMap<TK, TV>;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.size}\n   */\n  readonly size: number;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.entries}\n   */\n  entries(): MapIterator<KeyValueEntry<TK, TV>>;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.forEach}\n   */\n  forEach(cb: ResultMapForEachCb, arg?: unknown): void;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.get}\n   */\n  get(key: TK): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.has}\n   */\n  has(key: TK): boolean;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.keys}\n   */\n  keys(): MapIterator<TK>;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.values}\n   */\n  values(): MapIterator<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/{resultMapValidator.d.ts → resultMapConverter.d.ts}

@@ -1,18 +1,14 @@
 import { DetailedResult } from '../base';
 import { IReadOnlyResultMap, ResultMapResultDetail } from './readonlyResultMap';
 import { ResultMap, ResultMapValueFactory } from './resultMap';
-import { KeyValueValidators } from './utils';
+import { KeyValueConverters } from './keyValueConverters';
 /**
- * A read-only interface exposing non-mutating methods of a {@link Collections.ResultMapValidator | ResultMapValidator}.
+ * A read-only interface exposing non-mutating methods of a {@link Collections.ResultMapConverter | ResultMapConverter}.
  * @public
  */
-export interface IReadOnlyResultMapValidator<TK extends string = string, TV = unknown> {
+export interface IReadOnlyResultMapConverter<TK extends string = string, TV = unknown> {
     /**
-     * {@inheritdoc Collections.ResultMapValidator.validators}
-     */
-    readonly validators: KeyValueValidators<TK, TV>;
-    /**
-     * {@inheritdoc Collections.ResultMapValidator.map}
+     * {@inheritdoc Collections.ResultMapConverter.map}
      */
     readonly map: IReadOnlyResultMap<TK, TV>;
     /**
@@ -25,27 +21,27 @@ export interface IReadOnlyResultMapValidator<TK extends string = string, TV = un
     has(key: string): boolean;
 }
 /**
- * Parameters for constructing a {@link Collections.ResultMapValidator | ResultMapValidator}.
+ * Parameters for constructing a {@link Collections.ResultMapConverter | ResultMapConverter}.
  * @public
  */
-export interface IResultMapValidatorCreateParams<TK extends string = string, TV = unknown> {
+export interface IResultMapConverterCreateParams<TK extends string = string, TV = unknown> {
     map: ResultMap<TK, TV>;
-    validators: KeyValueValidators<TK, TV>;
+    converters: KeyValueConverters<TK, TV>;
 }
 /**
  * A {@link Collections.ResultMap | ResultMap} wrapper which validates weakly-typed keys
  * before calling the wrapped result map.
  * @public
  */
-export declare class ResultMapValidator<TK extends string = string, TV = unknown> implements IReadOnlyResultMapValidator<TK, TV> {
-    readonly validators: KeyValueValidators<TK, TV>;
+export declare class ResultMapConverter<TK extends string = string, TV = unknown> implements IReadOnlyResultMapConverter<TK, TV> {
+    readonly converters: KeyValueConverters<TK, TV>;
     get map(): IReadOnlyResultMap<TK, TV>;
     protected _map: ResultMap<TK, TV>;
     /**
-     * Constructs a new {@link Collections.ValidatingResultMap | ValidatingResultMap}.
-     * @param params - Required parameters for constructing the map.
+     * Constructs a new {@link Collections.ResultMapConverter | ResultMapConverter}.
+     * @param params - Required parameters for constructing the result map converter.
      */
-    constructor(params: IResultMapValidatorCreateParams<TK, TV>);
+    constructor(params: IResultMapConverterCreateParams<TK, TV>);
     /**
      * {@inheritdoc Collections.ResultMap.add}
      */
@@ -81,7 +77,7 @@ export declare class ResultMapValidator<TK extends string = string, TV = unknown
     /**
      * Gets a read-only version of this validator.
      */
-    toReadOnly(): IReadOnlyResultMapValidator<TK, TV>;
+    toReadOnly(): IReadOnlyResultMapConverter<TK, TV>;
     /**
      * Determines if a value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory}.
      * @param value - The value to check.
@@ -91,4 +87,4 @@ export declare class ResultMapValidator<TK extends string = string, TV = unknown
      */
     protected _isResultMapValueFactory<TK extends string, TV>(value: TV | ResultMapValueFactory<TK, TV>): value is ResultMapValueFactory<TK, TV>;
 }
-//# sourceMappingURL=resultMapValidator.d.ts.map
+//# sourceMappingURL=resultMapConverter.d.ts.map

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

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

package/lib/packlets/collections/{resultMapValidator.js → resultMapConverter.js}

@@ -21,30 +21,30 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResultMapValidator = void 0;
+exports.ResultMapConverter = void 0;
 const base_1 = require("../base");
 /**
  * A {@link Collections.ResultMap | ResultMap} wrapper which validates weakly-typed keys
  * before calling the wrapped result map.
  * @public
  */
-class ResultMapValidator {
+class ResultMapConverter {
     get map() {
         return this._map;
     }
     /**
-     * Constructs a new {@link Collections.ValidatingResultMap | ValidatingResultMap}.
-     * @param params - Required parameters for constructing the map.
+     * Constructs a new {@link Collections.ResultMapConverter | ResultMapConverter}.
+     * @param params - Required parameters for constructing the result map converter.
      */
     constructor(params) {
         this._map = params.map;
-        this.validators = params.validators;
+        this.converters = params.converters;
     }
     /**
      * {@inheritdoc Collections.ResultMap.add}
      */
     add(key, value) {
-        return this.validators.validateEntry([key, value]).onSuccess(([vk, vv]) => {
+        return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {
             return this._map.add(vk, vv);
         });
     }
@@ -52,7 +52,7 @@ class ResultMapValidator {
      * {@inheritdoc Collections.ResultMap.delete}
      */
     delete(key) {
-        return this.validators.validateKey(key).onSuccess((k) => {
+        return this.converters.convertKey(key).onSuccess((k) => {
             return this._map.delete(k);
         });
     }
@@ -60,21 +60,21 @@ class ResultMapValidator {
      * {@inheritdoc Collections.ResultMap.get}
      */
     get(key) {
-        return this.validators.validateKey(key).onSuccess((k) => {
+        return this.converters.convertKey(key).onSuccess((k) => {
             return this._map.get(k);
         });
     }
     getOrAdd(key, valueOrFactory) {
         if (!this._isResultMapValueFactory(valueOrFactory)) {
-            return this.validators.validateEntry([key, valueOrFactory]).onSuccess(([vk, vv]) => {
+            return this.converters.convertEntry([key, valueOrFactory]).onSuccess(([vk, vv]) => {
                 return this._map.getOrAdd(vk, vv);
             });
         }
         else {
-            return this.validators.validateKey(key).onSuccess((k) => {
+            return this.converters.convertKey(key).onSuccess((k) => {
                 return this._map.get(k).onFailure(() => {
                     const value = valueOrFactory(k)
-                        .onSuccess((value) => this.validators.validateEntry([k, value]))
+                        .onSuccess((value) => this.converters.convertEntry([k, value]))
                         .onSuccess(([__key, value]) => (0, base_1.succeedWithDetail)(value, 'added'));
                     return value.success
                         ? this._map.add(k, value.value)
@@ -93,7 +93,7 @@ class ResultMapValidator {
      * {@inheritdoc Collections.ResultMap.set}
      */
     set(key, value) {
-        return this.validators.validateEntry([key, value]).onSuccess(([vk, vv]) => {
+        return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {
             return this._map.set(vk, vv);
         });
     }
@@ -101,7 +101,7 @@ class ResultMapValidator {
      * {@inheritdoc Collections.ResultMap.update}
      */
     update(key, value) {
-        return this.validators.validateEntry([key, value]).onSuccess(([vk, vv]) => {
+        return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {
             return this._map.update(vk, vv);
         });
     }
@@ -122,5 +122,5 @@ class ResultMapValidator {
         return typeof value === 'function';
     }
 }
-exports.ResultMapValidator = ResultMapValidator;
-//# sourceMappingURL=resultMapValidator.js.map
+exports.ResultMapConverter = ResultMapConverter;
+//# sourceMappingURL=resultMapConverter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resultMapConverter.js","sourceRoot":"","sources":["../../../src/packlets/collections/resultMapConverter.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.ResultMapConverter | ResultMapConverter}.\n * @public\n */\nexport interface IReadOnlyResultMapConverter<TK extends string = string, TV = unknown> {\n  /**\n   * {@inheritdoc Collections.ResultMapConverter.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.ResultMapConverter | ResultMapConverter}.\n * @public\n */\nexport interface IResultMapConverterCreateParams<TK extends string = string, TV = unknown> {\n  map: ResultMap<TK, TV>;\n  converters: KeyValueConverters<TK, TV>;\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 ResultMapConverter<TK extends string = string, TV = unknown>\n  implements IReadOnlyResultMapConverter<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.ResultMapConverter | ResultMapConverter}.\n   * @param params - Required parameters for constructing the result map converter.\n   */\n  public constructor(params: IResultMapConverterCreateParams<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:1)}\n   */\n  public getOrAdd(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;\n\n  /**\n   * {@inheritdoc Collections.ResultMap.(getOrAdd:2)}\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(): IReadOnlyResultMapConverter<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/utils.d.ts

@@ -1,8 +1,3 @@
-import { DetailedResult, Result } from '../base';
-import { Converter } from '../conversion';
-import { Validator } from '../validation';
-import { KeyValueEntry } from './common';
-import { ResultMapResultDetail } from './readonlyResultMap';
 /**
  * Determines if a supplied value is an iterable object or some other type.
  * @param value - The value to be tested.
@@ -10,60 +5,4 @@ import { ResultMapResultDetail } from './readonlyResultMap';
  * @public
  */
 export declare function isIterable<TE = unknown, TI extends Iterable<TE> = Iterable<TE>, TO = unknown>(value: TI | TO): value is TI;
-/**
- * Helper class for validating key-value pairs.
- * @public
- */
-export declare class KeyValueValidators<TK extends string = string, TV = unknown> {
-    /**
-     * Required key validator or converter.
-     */
-    readonly key: Validator<TK, unknown> | Converter<TK, unknown>;
-    /**
-     * Required value validator or converter.
-     */
-    readonly value: Validator<TV, unknown> | Converter<TV, unknown>;
-    /**
-     * Optional entry validator or converter.  If no entry validator is provided,
-     * an entry is considered valid if both key and value are valid.
-     */
-    readonly entry?: Validator<KeyValueEntry<TK, TV>, unknown> | Converter<KeyValueEntry<TK, TV>, unknown>;
-    /**
-     * Constructs a new key-value validator.
-     * @param key - Required key validator or converter.
-     * @param value - Required value validator or converter.
-     * @param entry - Optional entry validator or converter.  If no entry validator is provided,
-     * an entry is considered valid if both key and value are valid.
-     */
-    constructor(key: Validator<TK, unknown> | Converter<TK, unknown>, value: Validator<TV, unknown> | Converter<TV, unknown>, entry?: Validator<KeyValueEntry<TK, TV>, unknown> | Converter<KeyValueEntry<TK, TV>, unknown>);
-    /**
-     * Validates a supplied unknown as a valid key value.
-     * @param key - The unknown to be validated.
-     * @returns `Success` with the validated key value and 'success' detail if the key is valid,
-     * or `Failure` with an error message and 'invalid-key' detail if the key is invalid.
-     */
-    validateKey(key: unknown): DetailedResult<TK, ResultMapResultDetail>;
-    /**
-     * Validates a supplied unknown as a valid value.
-     * @param key - The unknown to be validated.
-     * @returns `Success` with the validated value and 'success' detail if the value is valid,
-     * or `Failure` with an error message and 'invalid-value' detail if the value is invalid.
-     */
-    validateValue(key: unknown): DetailedResult<TV, ResultMapResultDetail>;
-    /**
-     * Validates a supplied unknown as a valid key-value pair.
-     * @param entry - The unknown to be validated.
-     * @returns `Success` with the validated key-value pair and 'success' detail if the entry
-     * is valid, or `Failure` with an error message and 'invalid-key' or 'invalid-value' detail if
-     * the entry is invalid
-     */
-    validateEntry(entry: unknown): DetailedResult<KeyValueEntry<TK, TV>, ResultMapResultDetail>;
-    /**
-     * Validates a supplied iterable of unknowns as valid key-value pairs.
-     * @param entries - The iterable of unknowns to be validated.
-     * @returns `Success` with an array of validated key-value pairs if all entries are valid,
-     * or `Failure` with an error message if any entry is invalid.
-     */
-    validateEntries(entries: Iterable<unknown>): Result<KeyValueEntry<TK, TV>[]>;
-}
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/utils.ts"],"names":[],"mappings":"AAsBA,OAAO,EACL,cAAc,EAGd,MAAM,EAGP,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;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;AAED;;;GAGG;AACH,qBAAa,kBAAkB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO;IACtE;;OAEG;IACH,SAAgB,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAErE;;OAEG;IACH,SAAgB,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAEvE;;;OAGG;IACH,SAAgB,KAAK,CAAC,EAClB,SAAS,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,GACzC,SAAS,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;IAE9C;;;;;;OAMG;gBAED,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,EACpD,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,EACtD,KAAK,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC;IAO/F;;;;;OAKG;IACI,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAAC,EAAE,EAAE,qBAAqB,CAAC;IAI3E;;;;;OAKG;IACI,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAAC,EAAE,EAAE,qBAAqB,CAAC;IAI7E;;;;;;OAMG;IACI,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,qBAAqB,CAAC;IAkBlG;;;;;OAKG;IACI,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;CAapF"}
+{"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

@@ -21,9 +21,7 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyValueValidators = void 0;
 exports.isIterable = isIterable;
-const base_1 = require("../base");
 /**
  * Determines if a supplied value is an iterable object or some other type.
  * @param value - The value to be tested.
@@ -33,84 +31,4 @@ const base_1 = require("../base");
 function isIterable(value) {
     return (value && typeof value === 'object' && Symbol.iterator in value) === true;
 }
-/**
- * Helper class for validating key-value pairs.
- * @public
- */
-class KeyValueValidators {
-    /**
-     * Constructs a new key-value validator.
-     * @param key - Required key validator or converter.
-     * @param value - Required value validator or converter.
-     * @param entry - Optional entry validator or converter.  If no entry validator is provided,
-     * an entry is considered valid if both key and value are valid.
-     */
-    constructor(key, value, entry) {
-        this.key = key;
-        this.value = value;
-        this.entry = entry;
-    }
-    /**
-     * Validates a supplied unknown as a valid key value.
-     * @param key - The unknown to be validated.
-     * @returns `Success` with the validated key value and 'success' detail if the key is valid,
-     * or `Failure` with an error message and 'invalid-key' detail if the key is invalid.
-     */
-    validateKey(key) {
-        return this.key.convert(key).withFailureDetail('invalid-key');
-    }
-    /**
-     * Validates a supplied unknown as a valid value.
-     * @param key - The unknown to be validated.
-     * @returns `Success` with the validated value and 'success' detail if the value is valid,
-     * or `Failure` with an error message and 'invalid-value' detail if the value is invalid.
-     */
-    validateValue(key) {
-        return this.value.convert(key).withFailureDetail('invalid-value');
-    }
-    /**
-     * Validates a supplied unknown as a valid key-value pair.
-     * @param entry - The unknown to be validated.
-     * @returns `Success` with the validated key-value pair and 'success' detail if the entry
-     * is valid, or `Failure` with an error message and 'invalid-key' or 'invalid-value' detail if
-     * the entry is invalid
-     */
-    validateEntry(entry) {
-        if (this.entry) {
-            return this.entry.convert(entry).withFailureDetail('invalid-value');
-        }
-        if (Array.isArray(entry) && entry.length === 2) {
-            const errors = new base_1.MessageAggregator();
-            const key = this.validateKey(entry[0]).aggregateError(errors).orDefault();
-            const value = this.validateValue(entry[1]).aggregateError(errors).orDefault();
-            if (key && value) {
-                return (0, base_1.succeedWithDetail)([key, value], 'success');
-            }
-            const detail = key ? 'invalid-value' : 'invalid-key';
-            return (0, base_1.failWithDetail)(`invalid entry: ${errors.toString()}`, detail);
-        }
-        /* c8 ignore next 2 */
-        return (0, base_1.failWithDetail)(`malformed entry: "${JSON.stringify(entry)}"`, 'invalid-value');
-    }
-    /**
-     * Validates a supplied iterable of unknowns as valid key-value pairs.
-     * @param entries - The iterable of unknowns to be validated.
-     * @returns `Success` with an array of validated key-value pairs if all entries are valid,
-     * or `Failure` with an error message if any entry is invalid.
-     */
-    validateEntries(entries) {
-        const errors = new base_1.MessageAggregator();
-        const validated = [];
-        for (const element of entries) {
-            this.validateEntry(element)
-                .onSuccess((e) => {
-                validated.push(e);
-                return (0, base_1.succeedWithDetail)(e, 'success');
-            })
-                .aggregateError(errors);
-        }
-        return errors.returnOrReport((0, base_1.succeed)(validated));
-    }
-}
-exports.KeyValueValidators = KeyValueValidators;
 //# sourceMappingURL=utils.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/packlets/collections/utils.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 {\n  DetailedResult,\n  failWithDetail,\n  MessageAggregator,\n  Result,\n  succeed,\n  succeedWithDetail\n} from '../base';\nimport { Converter } from '../conversion';\nimport { Validator } from '../validation';\nimport { KeyValueEntry } from './common';\nimport { ResultMapResultDetail } from './readonlyResultMap';\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\n/**\n * Helper class for validating key-value pairs.\n * @public\n */\nexport class KeyValueValidators<TK extends string = string, TV = unknown> {\n  /**\n   * Required key validator or converter.\n   */\n  public readonly key: Validator<TK, unknown> | Converter<TK, unknown>;\n\n  /**\n   * Required value validator or converter.\n   */\n  public readonly value: Validator<TV, unknown> | Converter<TV, unknown>;\n\n  /**\n   * Optional entry validator or converter.  If no entry validator is provided,\n   * an entry is considered valid if both key and value are valid.\n   */\n  public readonly entry?:\n    | Validator<KeyValueEntry<TK, TV>, unknown>\n    | Converter<KeyValueEntry<TK, TV>, unknown>;\n\n  /**\n   * Constructs a new key-value validator.\n   * @param key - Required key validator or converter.\n   * @param value - Required value validator or converter.\n   * @param entry - Optional entry validator or converter.  If no entry validator is provided,\n   * an entry is considered valid if both key and value are valid.\n   */\n  public constructor(\n    key: Validator<TK, unknown> | Converter<TK, unknown>,\n    value: Validator<TV, unknown> | Converter<TV, unknown>,\n    entry?: Validator<KeyValueEntry<TK, TV>, unknown> | Converter<KeyValueEntry<TK, TV>, unknown>\n  ) {\n    this.key = key;\n    this.value = value;\n    this.entry = entry;\n  }\n\n  /**\n   * Validates a supplied unknown as a valid key value.\n   * @param key - The unknown to be validated.\n   * @returns `Success` with the validated key value and 'success' detail if the key is valid,\n   * or `Failure` with an error message and 'invalid-key' detail if the key is invalid.\n   */\n  public validateKey(key: unknown): DetailedResult<TK, ResultMapResultDetail> {\n    return this.key.convert(key).withFailureDetail('invalid-key');\n  }\n\n  /**\n   * Validates a supplied unknown as a valid value.\n   * @param key - The unknown to be validated.\n   * @returns `Success` with the validated value and 'success' detail if the value is valid,\n   * or `Failure` with an error message and 'invalid-value' detail if the value is invalid.\n   */\n  public validateValue(key: unknown): DetailedResult<TV, ResultMapResultDetail> {\n    return this.value.convert(key).withFailureDetail('invalid-value');\n  }\n\n  /**\n   * Validates a supplied unknown as a valid key-value pair.\n   * @param entry - The unknown to be validated.\n   * @returns `Success` with the validated key-value pair and 'success' detail if the entry\n   * is valid, or `Failure` with an error message and 'invalid-key' or 'invalid-value' detail if\n   * the entry is invalid\n   */\n  public validateEntry(entry: unknown): DetailedResult<KeyValueEntry<TK, TV>, ResultMapResultDetail> {\n    if (this.entry) {\n      return this.entry.convert(entry).withFailureDetail('invalid-value');\n    }\n    if (Array.isArray(entry) && entry.length === 2) {\n      const errors = new MessageAggregator();\n      const key = this.validateKey(entry[0]).aggregateError(errors).orDefault();\n      const value = this.validateValue(entry[1]).aggregateError(errors).orDefault();\n      if (key && value) {\n        return succeedWithDetail([key, value], 'success');\n      }\n      const detail = key ? 'invalid-value' : 'invalid-key';\n      return failWithDetail(`invalid entry: ${errors.toString()}`, detail);\n    }\n    /* c8 ignore next 2 */\n    return failWithDetail(`malformed entry: \"${JSON.stringify(entry)}\"`, 'invalid-value');\n  }\n\n  /**\n   * Validates a supplied iterable of unknowns as valid key-value pairs.\n   * @param entries - The iterable of unknowns to be validated.\n   * @returns `Success` with an array of validated key-value pairs if all entries are valid,\n   * or `Failure` with an error message if any entry is invalid.\n   */\n  public validateEntries(entries: Iterable<unknown>): Result<KeyValueEntry<TK, TV>[]> {\n    const errors = new MessageAggregator();\n    const validated: KeyValueEntry<TK, TV>[] = [];\n    for (const element of entries) {\n      this.validateEntry(element)\n        .onSuccess((e) => {\n          validated.push(e);\n          return succeedWithDetail(e, 'success');\n        })\n        .aggregateError(errors);\n    }\n    return errors.returnOrReport(succeed(validated));\n  }\n}\n"]}
+{"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/conversion/baseConverter.d.ts

@@ -17,6 +17,11 @@ export type Infer<TCONV> = TCONV extends Converter<infer TTO, unknown> ? InnerIn
  * @internal
  */
 export type ConvertedToType<TCONV> = Infer<TCONV>;
+/**
+ * Function signature for a converter function.
+ * @public
+ */
+export type ConverterFunc<T, TC> = (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>;
 /**
  * Base templated wrapper to simplify creation of new {@link Converter}s.
  * @public
@@ -42,7 +47,7 @@ export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC>
      * @param traits - Optional {@link Conversion.ConverterTraits | traits} to be assigned to the resulting
      * converter.
      */
-    constructor(converter: (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>, defaultContext?: TC, traits?: ConverterTraits);
+    constructor(converter: ConverterFunc<T, TC>, defaultContext?: TC, traits?: ConverterTraits);
     /**
      * {@inheritdoc Converter.isOptional}
      */
@@ -66,7 +71,7 @@ export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC>
     /**
      * {@inheritdoc Converter.map}
      */
-    map<T2>(mapper: (from: T) => Result<T2>): Converter<T2, TC>;
+    map<T2>(mapper: (from: T, context?: TC) => Result<T2>): Converter<T2, TC>;
     /**
      * {@inheritdoc Converter.mapConvert}
      */
@@ -74,7 +79,7 @@ export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC>
     /**
      * {@inheritdoc Converter.mapItems}
      */
-    mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC>;
+    mapItems<TI>(mapper: (from: unknown, context?: TC) => Result<TI>): Converter<TI[], TC>;
     /**
      * {@inheritdoc Converter.mapConvertItems}
      */
@@ -82,19 +87,19 @@ export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC>
     /**
      * {@inheritdoc Converter.withAction}
      */
-    withAction<TI>(action: (result: Result<T>) => Result<TI>): Converter<TI, TC>;
+    withAction<TI>(action: (result: Result<T>, context?: TC) => Result<TI>): Converter<TI, TC>;
     /**
      * {@inheritdoc Converter.withTypeGuard}
      */
-    withTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI, TC>;
+    withTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI, TC>;
     /**
      * {@inheritdoc Converter.withItemTypeGuard}
      */
-    withItemTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI[], TC>;
+    withItemTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI[], TC>;
     /**
      * {@inheritdoc Converter.withConstraint}
      */
-    withConstraint(constraint: (val: T) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
+    withConstraint(constraint: (val: T, context?: TC) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
     /**
      * {@inheritdoc Converter.withBrand}
      */