@fgv/ts-utils 4.1.0 → 4.2.1

package/lib/index.d.ts

@@ -1,8 +1,10 @@
+import * as Collections from './packlets/collections';
 import * as Conversion from './packlets/conversion';
 import * as Hash from './packlets/hash';
 import * as Validation from './packlets/validation';
+import { IReadOnlyResultMap, ResultMap, ValidatingResultMap } from './packlets/collections';
 import { Converter, Converters, ObjectConverter, StringConverter } from './packlets/conversion';
 import { Validator, Validators } from './packlets/validation';
 export * from './packlets/base';
-export { Conversion, Converter, Converters, Hash, ObjectConverter, StringConverter, Validation, Validator, Validators };
+export { Collections, Conversion, Converter, Converters, Hash, IReadOnlyResultMap, ObjectConverter, ResultMap, StringConverter, ValidatingResultMap, Validation, Validator, Validators };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

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

package/lib/index.js

@@ -57,13 +57,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Validators = exports.Validation = exports.StringConverter = exports.ObjectConverter = exports.Hash = exports.Converters = exports.Conversion = void 0;
+exports.Validators = exports.Validation = exports.ValidatingResultMap = exports.StringConverter = exports.ResultMap = exports.ObjectConverter = exports.Hash = exports.Converters = exports.Conversion = exports.Collections = void 0;
+const Collections = __importStar(require("./packlets/collections"));
+exports.Collections = Collections;
 const Conversion = __importStar(require("./packlets/conversion"));
 exports.Conversion = Conversion;
 const Hash = __importStar(require("./packlets/hash"));
 exports.Hash = Hash;
 const Validation = __importStar(require("./packlets/validation"));
 exports.Validation = Validation;
+const collections_1 = require("./packlets/collections");
+Object.defineProperty(exports, "ResultMap", { enumerable: true, get: function () { return collections_1.ResultMap; } });
+Object.defineProperty(exports, "ValidatingResultMap", { enumerable: true, get: function () { return collections_1.ValidatingResultMap; } });
 const conversion_1 = require("./packlets/conversion");
 Object.defineProperty(exports, "Converters", { enumerable: true, get: function () { return conversion_1.Converters; } });
 Object.defineProperty(exports, "ObjectConverter", { enumerable: true, get: function () { return conversion_1.ObjectConverter; } });

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,kEAAoD;AASlD,gCAAU;AARZ,sDAAwC;AAWtC,oBAAI;AAVN,kEAAoD;AAalD,gCAAU;AAXZ,sDAAgG;AAO9F,2FAPkB,uBAAU,OAOlB;AAEV,gGAT8B,4BAAe,OAS9B;AACf,gGAV+C,4BAAe,OAU/C;AATjB,sDAA8D;AAY5D,2FAZkB,uBAAU,OAYlB;AAVZ,kDAAgC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport * as Conversion from './packlets/conversion';\nimport * as Hash from './packlets/hash';\nimport * as Validation from './packlets/validation';\n\nimport { Converter, Converters, ObjectConverter, StringConverter } from './packlets/conversion';\nimport { Validator, Validators } from './packlets/validation';\n\nexport * from './packlets/base';\nexport {\n  Conversion,\n  Converter,\n  Converters,\n  Hash,\n  ObjectConverter,\n  StringConverter,\n  Validation,\n  Validator,\n  Validators\n};\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,oEAAsD;AAWpD,kCAAW;AAVb,kEAAoD;AAWlD,gCAAU;AAVZ,sDAAwC;AAatC,oBAAI;AAZN,kEAAoD;AAkBlD,gCAAU;AAhBZ,wDAA4F;AAa1F,0FAb2B,uBAAS,OAa3B;AAET,oGAfsC,iCAAmB,OAetC;AAdrB,sDAAgG;AAQ9F,2FARkB,uBAAU,OAQlB;AAGV,gGAX8B,4BAAe,OAW9B;AAEf,gGAb+C,4BAAe,OAa/C;AAZjB,sDAA8D;AAgB5D,2FAhBkB,uBAAU,OAgBlB;AAdZ,kDAAgC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport * as Collections from './packlets/collections';\nimport * as Conversion from './packlets/conversion';\nimport * as Hash from './packlets/hash';\nimport * as Validation from './packlets/validation';\n\nimport { IReadOnlyResultMap, ResultMap, ValidatingResultMap } from './packlets/collections';\nimport { Converter, Converters, ObjectConverter, StringConverter } from './packlets/conversion';\nimport { Validator, Validators } from './packlets/validation';\n\nexport * from './packlets/base';\nexport {\n  Collections,\n  Conversion,\n  Converter,\n  Converters,\n  Hash,\n  IReadOnlyResultMap,\n  ObjectConverter,\n  ResultMap,\n  StringConverter,\n  ValidatingResultMap,\n  Validation,\n  Validator,\n  Validators\n};\n"]}

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

@@ -0,0 +1,6 @@
+/**
+ * Generic key-value entry.
+ * @public
+ */
+export type KeyValueEntry<TK extends string = string, TV = unknown> = [TK, TV];
+//# sourceMappingURL=common.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/common.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,OAAO,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC"}

package/lib/packlets/collections/common.js

@@ -0,0 +1,24 @@
+"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 });
+//# sourceMappingURL=common.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../src/packlets/collections/common.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\n/**\n * Generic key-value entry.\n * @public\n */\nexport type KeyValueEntry<TK extends string = string, TV = unknown> = [TK, TV];\n"]}

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

@@ -0,0 +1,8 @@
+import * as Utils from './utils';
+export * from './common';
+export * from './readonlyResultMap';
+export * from './resultMap';
+export * from './resultMapValidator';
+export * from './validatingResultMap';
+export { Utils };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/collections/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/lib/packlets/collections/index.js

@@ -0,0 +1,68 @@
+"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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Utils = void 0;
+const Utils = __importStar(require("./utils"));
+exports.Utils = Utils;
+__exportStar(require("./common"), exports);
+__exportStar(require("./readonlyResultMap"), exports);
+__exportStar(require("./resultMap"), exports);
+__exportStar(require("./resultMapValidator"), exports);
+__exportStar(require("./validatingResultMap"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/collections/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,+CAAiC;AAOxB,sBAAK;AALd,2CAAyB;AACzB,sDAAoC;AACpC,8CAA4B;AAC5B,uDAAqC;AACrC,wDAAsC","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 * as Utils from './utils';\n\nexport * from './common';\nexport * from './readonlyResultMap';\nexport * from './resultMap';\nexport * from './resultMapValidator';\nexport * from './validatingResultMap';\nexport { Utils };\n"]}

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

@@ -0,0 +1,58 @@
+import { DetailedResult } from '../base';
+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';
+/**
+ * Callback for {@link Collections.ResultMap | ResultMap} `forEach` method.
+ * @public
+ */
+export type ResultMapForEachCb<TK extends string = string, TE = unknown> = (value: TE, key: TK, map: IReadOnlyResultMap<TK, TE>, thisArg?: unknown) => void;
+/**
+ * A readonly `ReadonlyMap<TK, TV>`-like object which reports success or failure
+ * with additional details using the
+ * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#the-result-pattern | result pattern}.
+ * @public
+ */
+export interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {
+    /**
+     * {@inheritdoc Collections.ResultMap.inner}
+     */
+    readonly inner: ReadonlyMap<TK, TV>;
+    /**
+     * {@inheritdoc Collections.ResultMap.size}
+     */
+    readonly size: number;
+    /**
+     * {@inheritdoc Collections.ResultMap.entries}
+     */
+    entries(): MapIterator<KeyValueEntry<TK, TV>>;
+    /**
+     * {@inheritdoc Collections.ResultMap.forEach}
+     */
+    forEach(cb: ResultMapForEachCb, arg?: unknown): void;
+    /**
+     * {@inheritdoc Collections.ResultMap.get}
+     */
+    get(key: TK): DetailedResult<TV, ResultMapResultDetail>;
+    /**
+     * {@inheritdoc Collections.ResultMap.has}
+     */
+    has(key: TK): boolean;
+    /**
+     * {@inheritdoc Collections.ResultMap.keys}
+     */
+    keys(): MapIterator<TK>;
+    /**
+     * {@inheritdoc Collections.ResultMap.values}
+     */
+    values(): MapIterator<TV>;
+    /**
+     * Gets an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TV>>;
+}
+//# sourceMappingURL=readonlyResultMap.d.ts.map

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,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

@@ -0,0 +1,24 @@
+"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 });
+//# sourceMappingURL=readonlyResultMap.js.map

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  | '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/resultMap.d.ts

@@ -0,0 +1,180 @@
+import { DetailedResult, Result } from '../base';
+import { KeyValueEntry } from './common';
+import { IReadOnlyResultMap, ResultMapForEachCb, ResultMapResultDetail } from './readonlyResultMap';
+/**
+ * Parameters for constructing a {@link Collections.ResultMap | ResultMap}.
+ * @public
+ */
+export interface IResultMapConstructorParams<TK extends string = string, TV = unknown> {
+    entries?: Iterable<KeyValueEntry<TK, TV>>;
+}
+/**
+ * Deferred constructor for the {@link Collections.ResultMap.(getOrAdd:2) | getOrAdd} method.
+ * @public
+ */
+export type ResultMapValueFactory<TK extends string = string, TV = unknown> = (key: TK) => Result<TV>;
+/**
+ * A {@link Collections.ResultMap | ResultMap} class as a `Map<TK, TV>`-like object which
+ * reports success or failure with additional details using the
+ * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#the-result-pattern | result pattern}.
+ * @public
+ */
+export declare class ResultMap<TK extends string = string, TV = unknown> implements IReadOnlyResultMap<TK, TV> {
+    /**
+     * Readonly raw access to the inner `Map<TK, TV>` object.
+     */
+    get inner(): ReadonlyMap<TK, TV>;
+    /**
+     * Protected raw access to the inner `Map<TK, TV>` object.
+     * @public
+     */
+    protected readonly _inner: Map<TK, TV>;
+    /**
+     * Constructs a new {@link Collections.ResultMap | ResultMap}.
+     * @param iterable - An iterable to initialize the map.
+     */
+    constructor(iterable?: Iterable<KeyValueEntry<TK, TV>>);
+    /**
+     * Constructs a new {@link Collections.ResultMap | ResultMap}.
+     * @param params - An optional set of parameters to configure the map.
+     */
+    constructor(params: IResultMapConstructorParams);
+    /**
+     * Creates a new {@link Collections.ResultMap | ResultMap}.
+     * @param elements - An optional iterable to initialize the map.
+     * @returns `Success` with the new map, or `Failure` with error details
+     * if an error occurred.
+     * @public
+     */
+    static create<TK extends string = string, TV = unknown>(elements: Iterable<KeyValueEntry<TK, TV>>): Result<ResultMap<TK, TV>>;
+    /**
+     * Creates a new {@link Collections.ResultMap | ResultMap}.
+     * @param params - An optional set of parameters to configure the map.
+     * @returns `Success` with the new map, or `Failure` with error details
+     * if an error occurred.
+     * @public
+     */
+    static create<TK extends string = string, TV = unknown>(params?: IResultMapConstructorParams<TK, TV>): Result<ResultMap<TK, TV>>;
+    /**
+     * Sets a key/value pair in the map if the key does not already exist.
+     * @param key - The key to set.
+     * @param value - The value to set.
+     * @returns `Success` with the value and detail `added` if the key was added,
+     * `Failure` with detail `exists` if the key already exists. Fails with detail
+     * 'invalid-key' or 'invalid-value' and an error message if either is invalid.
+     */
+    add(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+    /**
+     * Clears the map.
+     */
+    clear(): void;
+    /**
+     * Deletes a key from the map.
+     * @param key - The key to delete.
+     * @returns `Success` with the previous value and the detail 'deleted'
+     * if the key was found and deleted, `Failure` with detail 'not-found'
+     * if the key was not found, or with detail 'invalid-key' if the key is invalid.
+     */
+    delete(key: TK): DetailedResult<TV, ResultMapResultDetail>;
+    /**
+     * Returns an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    entries(): MapIterator<KeyValueEntry<TK, TV>>;
+    /**
+     * 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<TK, TV>, arg?: unknown): void;
+    /**
+     * 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>;
+    /**
+     * Gets a value from the map, or adds a supplied value it if it does not exist.
+     * @param key - The key to be retrieved or created.
+     * @param value - The value to add if the key does not exist.
+     * @returns `Success` with the value and detail `exists` if the key was found,
+     * `Success` with the value and detail `added` if the key was not found and added.
+     * Fails with detail 'invalid-key' or 'invalid-value' and an error message if either
+     * is invalid.
+     * {@label WITH_VALUE}
+     */
+    getOrAdd(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+    /**
+     * Gets a value from the map, or adds a value created by a factory function if it does not exist.
+     * @param key - The key of the element to be retrieved or created.
+     * @param factory - A {@link Collections.ResultMapValueFactory | factory function} to create the value if
+     * the key does not exist.
+     * @returns `Success` with the value and detail `exists` if the key was found, `Success` with
+     * the value and detail `added` if the key was not found and added. Fails with detail 'invalid-key'
+     * or 'invalid-value' and an error message if either is invalid.
+     * {@label WITH_FACTORY}
+     */
+    getOrAdd(key: TK, factory: ResultMapValueFactory<TK, TV>): DetailedResult<TV, ResultMapResultDetail>;
+    /**
+     * 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;
+    /**
+     * Returns an iterator over the map keys.
+     * @returns An iterator over the map keys.
+     */
+    keys(): MapIterator<TK>;
+    /**
+     * Sets a key/value pair in the map.
+     * @param key - The key to set.
+     * @param value - The value to set.
+     * @returns `Success` with the new value and the detail `updated` if the
+     * key was found and updated, `Success` with the new value and detail
+     * `added` if the key was not found and added.  Fails with detail
+     * 'invalid-key' or 'invalid-value' and an error message if either is invalid.
+     */
+    set(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+    /**
+     * Returns the number of entries in the map.
+     */
+    get size(): number;
+    /**
+     * Updates an existing key in the map - the map is not updated if the key does
+     * not exist.
+     * @param key - The key to update.
+     * @param value - The value to set.
+     * @returns `Success` with the value and detail 'exists' if the key was found
+     * and the value updated, `Failure` an error message and with detail `not-found`
+     * if the key was not found, or with detail 'invalid-key' or 'invalid-value'
+     * if either is invalid.
+     */
+    update(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+    /**
+     * Returns an iterator over the map values.
+     * @returns An iterator over the map values.
+     */
+    values(): MapIterator<TV>;
+    /**
+     * Gets an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TV>>;
+    /**
+     * Gets a readonly version of this map.
+     * @returns A readonly version of this map.
+     */
+    toReadOnly(): IReadOnlyResultMap<TK, TV>;
+    /**
+     * Determines if a value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory}.
+     * @param value - The value to check.
+     * @returns `true` if the value is a {@link Collections.ResultMapValueFactory | ResultMapValueFactory},
+     * `false` otherwise.
+     * @public
+     */
+    protected _isResultMapValueFactory<TK extends string, TV>(value: TV | ResultMapValueFactory<TK, TV>): value is ResultMapValueFactory<TK, TV>;
+}
+//# sourceMappingURL=resultMap.d.ts.map

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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"}