@fgv/ts-utils 3.0.1-alpha.3 → 3.0.1-alpha.5

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

@@ -1,5 +1,7 @@
 import * as Logging from './logger';
 export * from './brand';
+export * from './mapResults';
+export * from './messageAggregator';
 export { Normalizer } from './normalize';
 export * from './result';
 export * from './utils';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/base/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,OAAO,MAAM,UAAU,CAAC;AAEpC,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/base/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,OAAO,MAAM,UAAU,CAAC;AAEpC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/lib/packlets/base/index.js

@@ -51,6 +51,8 @@ exports.Logging = exports.Normalizer = void 0;
 const Logging = __importStar(require("./logger"));
 exports.Logging = Logging;
 __exportStar(require("./brand"), exports);
+__exportStar(require("./mapResults"), exports);
+__exportStar(require("./messageAggregator"), exports);
 var normalize_1 = require("./normalize");
 Object.defineProperty(exports, "Normalizer", { enumerable: true, get: function () { return normalize_1.Normalizer; } });
 __exportStar(require("./result"), exports);

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/base/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,kDAAoC;AAM3B,0BAAO;AAJhB,0CAAwB;AACxB,yCAAyC;AAAhC,uGAAA,UAAU,OAAA;AACnB,2CAAyB;AACzB,0CAAwB","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 Logging from './logger';\n\nexport * from './brand';\nexport { Normalizer } from './normalize';\nexport * from './result';\nexport * from './utils';\nexport { Logging };\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/base/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,kDAAoC;AAQ3B,0BAAO;AANhB,0CAAwB;AACxB,+CAA6B;AAC7B,sDAAoC;AACpC,yCAAyC;AAAhC,uGAAA,UAAU,OAAA;AACnB,2CAAyB;AACzB,0CAAwB","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 Logging from './logger';\n\nexport * from './brand';\nexport * from './mapResults';\nexport * from './messageAggregator';\nexport { Normalizer } from './normalize';\nexport * from './result';\nexport * from './utils';\nexport { Logging };\n"]}

package/lib/packlets/base/mapResults.d.ts

@@ -0,0 +1,120 @@
+import { DetailedResult, IMessageAggregator, Result } from './result';
+/**
+ * Aggregates successful result values from a collection of {@link Result | Result<T>}.
+ * @param results - The collection of {@link Result | Result<T>} to be mapped.
+ * @param aggregatedErrors  - Optional string array to which any error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns  If all {@link Result | results} are successful, returns {@link Success} with an
+ * array containing all returned values.  If any {@link Result | results} failed, returns
+ * {@link Failure} with a concatenated summary of all error messages.
+ * @public
+ */
+export declare function mapResults<T>(results: Iterable<Result<T>>, aggregatedErrors?: IMessageAggregator): Result<T[]>;
+/**
+ * Aggregates successful results from a collection of {@link DetailedResult | DetailedResult<T, TD>},
+ * optionally ignoring certain error details.
+ * @param results - The collection of {@link DetailedResult | DetailedResult<T, TD>} to be mapped.
+ * @param ignore - An array of error detail values (of type `<TD>`) that should be ignored.
+ * @param aggregatedErrors  - Optional string array to which any non-ignorable error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns {@link Success} with an array containing all successful results if all results either
+ * succeeded or returned error details listed in `ignore`.  If any results failed with details
+ * that cannot be ignored, returns {@link Failure} with an concatenated summary of all non-ignorable
+ * error messages.
+ * @public
+ */
+export declare function mapDetailedResults<T, TD>(results: Iterable<DetailedResult<T, TD>>, ignore: TD[], aggregatedErrors?: IMessageAggregator): Result<T[]>;
+/**
+ * Aggregates successful results from a a collection of {@link Result | Result<T>}.
+ * @param results - An `Iterable` of {@link Result | Result<T>} from which success
+ * results are to be aggregated.
+ * @param aggregatedErrors  - Optional string array to which any returned error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns {@link Success} with an array of `<T>` if any results were successful. If
+ * all {@link Result | results} failed, returns {@link Failure} with a concatenated
+ * summary of all error messages.
+ * @public
+ */
+export declare function mapSuccess<T>(results: Iterable<Result<T>>, aggregatedErrors?: IMessageAggregator): Result<T[]>;
+/**
+ * Aggregates error messages from a collection of {@link Result | Result<T>}.
+ * @param results - An iterable collection of {@link Result | Result<T>} for which
+ * error messages are aggregated.
+ * @param aggregatedErrors  - Optional string array to which any returned error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns An array of strings consisting of all error messages returned by
+ * {@link Result | results} in the source collection. Ignores {@link Success}
+ * results and returns an empty array if there were no errors.
+ * @public
+ */
+export declare function mapFailures<T>(results: Iterable<Result<T>>, aggregatedErrors?: IMessageAggregator): string[];
+/**
+ * Determines if an iterable collection of {@link Result | Result<T>} were all successful.
+ * @param results - The collection of {@link Result | Result<T>} to be tested.
+ * @param successValue - The value to be returned if results are successful.
+ * @param aggregatedErrors  - Optional string array to which any returned error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns Returns {@link Success} with `successValue` if all {@link Result | results} are successful.
+ * If any are unsuccessful, returns {@link Failure} with a concatenated summary of the error
+ * messages from all failed elements.
+ * @public
+ */
+export declare function allSucceed<T>(results: Iterable<Result<unknown>>, successValue: T, aggregatedErrors?: IMessageAggregator): Result<T>;
+/**
+ * String-keyed record of initialization functions to be passed to {@link (populateObject:1)}
+ * or {@link (populateObject:2)}.
+ * @public
+ */
+export type FieldInitializers<T> = {
+    [key in keyof T]: (state: Partial<T>) => Result<T[key]>;
+};
+/**
+ * Options for the {@link (populateObject:1)} function.
+ * @public
+ */
+export interface PopulateObjectOptions<T> {
+    /**
+     * If present, specifies the order in which property values should
+     * be evaluated.  Any keys not listed are evaluated after all listed
+     * keys in indeterminate order.  If 'order' is not present, keys
+     * are evaluated in indeterminate order.
+     */
+    order?: (keyof T)[];
+    /**
+     * Specify handling of `undefined` values.  By default, successful
+     * `undefined` results are written to the result object.  If this value
+     * is `true` then `undefined` results are suppressed for all properties.
+     * If this value is an array of property keys then `undefined` results
+     * are suppressed for those properties only.
+     */
+    suppressUndefined?: boolean | (keyof T)[];
+}
+/**
+ * Populates an an object based on a prototype full of field initializers that return {@link Result | Result<T[key]>}.
+ * Returns {@link Success} with the populated object if all initializers succeed, or {@link Failure} with a
+ * concatenated list of all error messages.
+ * @param initializers - An object with the shape of the target but with initializer functions for
+ * each property.
+ * @param options - An optional {@link PopulateObjectOptions | set of options} which
+ * modify the behavior of this call.
+ * @param aggregatedErrors  - Optional string array to which any returned error messages will be
+ * appended.  Each error is appended as an individual string.
+ * {@label WITH_OPTIONS}
+ * @public
+ */
+export declare function populateObject<T>(initializers: FieldInitializers<T>, options?: PopulateObjectOptions<T>, aggregatedErrors?: IMessageAggregator): Result<T>;
+/**
+ * Populates an an object based on a prototype full of field initializers that return {@link Result | Result<T[key]>}.
+ * Returns {@link Success} with the populated object if all initializers succeed, or {@link Failure} with a
+ * concatenated list of all error messages.
+ * @param initializers - An object with the shape of the target but with initializer functions for
+ * each property.
+ * @param order - Optional order in which keys should be written.
+ * @param aggregatedErrors  - Optional string array to which any returned error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @public
+ * {@label WITH_ORDER}
+ * @deprecated Pass {@link PopulateObjectOptions} instead.
+ */
+export declare function populateObject<T>(initializers: FieldInitializers<T>, order: (keyof T)[] | undefined, aggregatedErrors?: IMessageAggregator): Result<T>;
+//# sourceMappingURL=mapResults.d.ts.map

package/lib/packlets/base/mapResults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapResults.d.ts","sourceRoot":"","sources":["../../../src/packlets/base/mapResults.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,EAAiB,MAAM,UAAU,CAAC;AAErF;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAC5B,gBAAgB,CAAC,EAAE,kBAAkB,GACpC,MAAM,CAAC,CAAC,EAAE,CAAC,CAiBb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,EAAE,EACtC,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EACxC,MAAM,EAAE,EAAE,EAAE,EACZ,gBAAgB,CAAC,EAAE,kBAAkB,GACpC,MAAM,CAAC,CAAC,EAAE,CAAC,CAiBb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAC5B,gBAAgB,CAAC,EAAE,kBAAkB,GACpC,MAAM,CAAC,CAAC,EAAE,CAAC,CAiBb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAC5B,gBAAgB,CAAC,EAAE,kBAAkB,GACpC,MAAM,EAAE,CASV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAClC,YAAY,EAAE,CAAC,EACf,gBAAgB,CAAC,EAAE,kBAAkB,GACpC,MAAM,CAAC,CAAC,CAAC,CAgBX;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;KAAG,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CAAE,CAAC;AAE/F;;;GAGG;AAEH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;IAEpB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;CAC3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAClC,OAAO,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,EAClC,gBAAgB,CAAC,EAAE,kBAAkB,GACpC,MAAM,CAAC,CAAC,CAAC,CAAC;AAEb;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAClC,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,SAAS,EAC9B,gBAAgB,CAAC,EAAE,kBAAkB,GACpC,MAAM,CAAC,CAAC,CAAC,CAAC"}

package/lib/packlets/base/mapResults.js

@@ -0,0 +1,208 @@
+"use strict";
+/*
+ * Copyright (c) 2020 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.populateObject = exports.allSucceed = exports.mapFailures = exports.mapSuccess = exports.mapDetailedResults = exports.mapResults = void 0;
+const result_1 = require("./result");
+/**
+ * Aggregates successful result values from a collection of {@link Result | Result<T>}.
+ * @param results - The collection of {@link Result | Result<T>} to be mapped.
+ * @param aggregatedErrors  - Optional string array to which any error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns  If all {@link Result | results} are successful, returns {@link Success} with an
+ * array containing all returned values.  If any {@link Result | results} failed, returns
+ * {@link Failure} with a concatenated summary of all error messages.
+ * @public
+ */
+function mapResults(results, aggregatedErrors) {
+    const errors = [];
+    const elements = [];
+    for (const result of results) {
+        if (result.isSuccess()) {
+            elements.push(result.value);
+        }
+        else {
+            errors.push(result.message);
+        }
+    }
+    if (errors.length > 0) {
+        aggregatedErrors === null || aggregatedErrors === void 0 ? void 0 : aggregatedErrors.addMessages(errors);
+        return (0, result_1.fail)(errors.join('\n'));
+    }
+    return (0, result_1.succeed)(elements);
+}
+exports.mapResults = mapResults;
+/**
+ * Aggregates successful results from a collection of {@link DetailedResult | DetailedResult<T, TD>},
+ * optionally ignoring certain error details.
+ * @param results - The collection of {@link DetailedResult | DetailedResult<T, TD>} to be mapped.
+ * @param ignore - An array of error detail values (of type `<TD>`) that should be ignored.
+ * @param aggregatedErrors  - Optional string array to which any non-ignorable error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns {@link Success} with an array containing all successful results if all results either
+ * succeeded or returned error details listed in `ignore`.  If any results failed with details
+ * that cannot be ignored, returns {@link Failure} with an concatenated summary of all non-ignorable
+ * error messages.
+ * @public
+ */
+function mapDetailedResults(results, ignore, aggregatedErrors) {
+    const errors = [];
+    const elements = [];
+    for (const result of results) {
+        if (result.isSuccess()) {
+            elements.push(result.value);
+        }
+        else if (!ignore.includes(result.detail)) {
+            errors.push(result.message);
+        }
+    }
+    if (errors.length > 0) {
+        aggregatedErrors === null || aggregatedErrors === void 0 ? void 0 : aggregatedErrors.addMessages(errors);
+        return (0, result_1.fail)(errors.join('\n'));
+    }
+    return (0, result_1.succeed)(elements);
+}
+exports.mapDetailedResults = mapDetailedResults;
+/**
+ * Aggregates successful results from a a collection of {@link Result | Result<T>}.
+ * @param results - An `Iterable` of {@link Result | Result<T>} from which success
+ * results are to be aggregated.
+ * @param aggregatedErrors  - Optional string array to which any returned error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns {@link Success} with an array of `<T>` if any results were successful. If
+ * all {@link Result | results} failed, returns {@link Failure} with a concatenated
+ * summary of all error messages.
+ * @public
+ */
+function mapSuccess(results, aggregatedErrors) {
+    const errors = [];
+    const elements = [];
+    for (const result of results) {
+        if (result.isSuccess()) {
+            elements.push(result.value);
+        }
+        else {
+            errors.push(result.message);
+        }
+    }
+    if (elements.length === 0 && errors.length > 0) {
+        aggregatedErrors === null || aggregatedErrors === void 0 ? void 0 : aggregatedErrors.addMessages(errors);
+        return (0, result_1.fail)(errors.join('\n'));
+    }
+    return (0, result_1.succeed)(elements);
+}
+exports.mapSuccess = mapSuccess;
+/**
+ * Aggregates error messages from a collection of {@link Result | Result<T>}.
+ * @param results - An iterable collection of {@link Result | Result<T>} for which
+ * error messages are aggregated.
+ * @param aggregatedErrors  - Optional string array to which any returned error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns An array of strings consisting of all error messages returned by
+ * {@link Result | results} in the source collection. Ignores {@link Success}
+ * results and returns an empty array if there were no errors.
+ * @public
+ */
+function mapFailures(results, aggregatedErrors) {
+    const errors = [];
+    for (const result of results) {
+        if (result.isFailure()) {
+            errors.push(result.message);
+            aggregatedErrors === null || aggregatedErrors === void 0 ? void 0 : aggregatedErrors.addMessage(result.message);
+        }
+    }
+    return errors;
+}
+exports.mapFailures = mapFailures;
+/**
+ * Determines if an iterable collection of {@link Result | Result<T>} were all successful.
+ * @param results - The collection of {@link Result | Result<T>} to be tested.
+ * @param successValue - The value to be returned if results are successful.
+ * @param aggregatedErrors  - Optional string array to which any returned error messages will be
+ * appended.  Each error is appended as an individual string.
+ * @returns Returns {@link Success} with `successValue` if all {@link Result | results} are successful.
+ * If any are unsuccessful, returns {@link Failure} with a concatenated summary of the error
+ * messages from all failed elements.
+ * @public
+ */
+function allSucceed(results, successValue, aggregatedErrors) {
+    const errors = [];
+    if (results !== undefined) {
+        for (const result of results) {
+            if (result.isFailure()) {
+                errors.push(result.message);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        aggregatedErrors === null || aggregatedErrors === void 0 ? void 0 : aggregatedErrors.addMessages(errors);
+        return (0, result_1.fail)(errors.join('\n'));
+    }
+    return (0, result_1.succeed)(successValue);
+}
+exports.allSucceed = allSucceed;
+function populateObject(initializers, optionsOrOrder, aggregatedErrors) {
+    var _a;
+    const options = optionsOrOrder
+        ? Array.isArray(optionsOrOrder)
+            ? { order: optionsOrOrder }
+            : optionsOrOrder
+        : {};
+    const state = {};
+    const errors = [];
+    const keys = Array.from((_a = options.order) !== null && _a !== void 0 ? _a : []);
+    const foundKeys = new Set(options.order);
+    // start with the supplied order then append anything else we find
+    for (const key in initializers) {
+        if (!foundKeys.has(key)) {
+            keys.push(key);
+            foundKeys.add(key);
+        }
+    }
+    for (const key of keys) {
+        if (initializers[key]) {
+            const result = initializers[key](state);
+            if (result.isSuccess()) {
+                if (result.value === undefined) {
+                    if (options.suppressUndefined === true ||
+                        (Array.isArray(options.suppressUndefined) && options.suppressUndefined.includes(key))) {
+                        continue;
+                    }
+                }
+                state[key] = result.value;
+            }
+            else {
+                errors.push(result.message);
+            }
+        }
+        else {
+            errors.push(`populateObject: Key ${String(key)} is present but has no initializer`);
+        }
+    }
+    if (errors.length > 0) {
+        aggregatedErrors === null || aggregatedErrors === void 0 ? void 0 : aggregatedErrors.addMessages(errors);
+        return (0, result_1.fail)(errors.join('\n'));
+    }
+    return (0, result_1.succeed)(state);
+}
+exports.populateObject = populateObject;
+//# sourceMappingURL=mapResults.js.map

package/lib/packlets/base/mapResults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapResults.js","sourceRoot":"","sources":["../../../src/packlets/base/mapResults.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { DetailedResult, IMessageAggregator, Result, fail, succeed } from './result';\n\n/**\n * Aggregates successful result values from a collection of {@link Result | Result<T>}.\n * @param results - The collection of {@link Result | Result<T>} to be mapped.\n * @param aggregatedErrors  - Optional string array to which any error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns  If all {@link Result | results} are successful, returns {@link Success} with an\n * array containing all returned values.  If any {@link Result | results} failed, returns\n * {@link Failure} with a concatenated summary of all error messages.\n * @public\n */\nexport function mapResults<T>(\n  results: Iterable<Result<T>>,\n  aggregatedErrors?: IMessageAggregator\n): Result<T[]> {\n  const errors: string[] = [];\n  const elements: T[] = [];\n\n  for (const result of results) {\n    if (result.isSuccess()) {\n      elements.push(result.value);\n    } else {\n      errors.push(result.message);\n    }\n  }\n\n  if (errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(elements);\n}\n\n/**\n * Aggregates successful results from a collection of {@link DetailedResult | DetailedResult<T, TD>},\n * optionally ignoring certain error details.\n * @param results - The collection of {@link DetailedResult | DetailedResult<T, TD>} to be mapped.\n * @param ignore - An array of error detail values (of type `<TD>`) that should be ignored.\n * @param aggregatedErrors  - Optional string array to which any non-ignorable error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns {@link Success} with an array containing all successful results if all results either\n * succeeded or returned error details listed in `ignore`.  If any results failed with details\n * that cannot be ignored, returns {@link Failure} with an concatenated summary of all non-ignorable\n * error messages.\n * @public\n */\nexport function mapDetailedResults<T, TD>(\n  results: Iterable<DetailedResult<T, TD>>,\n  ignore: TD[],\n  aggregatedErrors?: IMessageAggregator\n): Result<T[]> {\n  const errors: string[] = [];\n  const elements: T[] = [];\n\n  for (const result of results) {\n    if (result.isSuccess()) {\n      elements.push(result.value);\n    } else if (!ignore.includes(result.detail)) {\n      errors.push(result.message);\n    }\n  }\n\n  if (errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(elements);\n}\n\n/**\n * Aggregates successful results from a a collection of {@link Result | Result<T>}.\n * @param results - An `Iterable` of {@link Result | Result<T>} from which success\n * results are to be aggregated.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns {@link Success} with an array of `<T>` if any results were successful. If\n * all {@link Result | results} failed, returns {@link Failure} with a concatenated\n * summary of all error messages.\n * @public\n */\nexport function mapSuccess<T>(\n  results: Iterable<Result<T>>,\n  aggregatedErrors?: IMessageAggregator\n): Result<T[]> {\n  const errors: string[] = [];\n  const elements: T[] = [];\n\n  for (const result of results) {\n    if (result.isSuccess()) {\n      elements.push(result.value);\n    } else {\n      errors.push(result.message);\n    }\n  }\n\n  if (elements.length === 0 && errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(elements);\n}\n\n/**\n * Aggregates error messages from a collection of {@link Result | Result<T>}.\n * @param results - An iterable collection of {@link Result | Result<T>} for which\n * error messages are aggregated.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns An array of strings consisting of all error messages returned by\n * {@link Result | results} in the source collection. Ignores {@link Success}\n * results and returns an empty array if there were no errors.\n * @public\n */\nexport function mapFailures<T>(\n  results: Iterable<Result<T>>,\n  aggregatedErrors?: IMessageAggregator\n): string[] {\n  const errors: string[] = [];\n  for (const result of results) {\n    if (result.isFailure()) {\n      errors.push(result.message);\n      aggregatedErrors?.addMessage(result.message);\n    }\n  }\n  return errors;\n}\n\n/**\n * Determines if an iterable collection of {@link Result | Result<T>} were all successful.\n * @param results - The collection of {@link Result | Result<T>} to be tested.\n * @param successValue - The value to be returned if results are successful.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * @returns Returns {@link Success} with `successValue` if all {@link Result | results} are successful.\n * If any are unsuccessful, returns {@link Failure} with a concatenated summary of the error\n * messages from all failed elements.\n * @public\n */\nexport function allSucceed<T>(\n  results: Iterable<Result<unknown>>,\n  successValue: T,\n  aggregatedErrors?: IMessageAggregator\n): Result<T> {\n  const errors: string[] = [];\n\n  if (results !== undefined) {\n    for (const result of results) {\n      if (result.isFailure()) {\n        errors.push(result.message);\n      }\n    }\n  }\n\n  if (errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(successValue);\n}\n\n/**\n * String-keyed record of initialization functions to be passed to {@link (populateObject:1)}\n * or {@link (populateObject:2)}.\n * @public\n */\nexport type FieldInitializers<T> = { [key in keyof T]: (state: Partial<T>) => Result<T[key]> };\n\n/**\n * Options for the {@link (populateObject:1)} function.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface PopulateObjectOptions<T> {\n  /**\n   * If present, specifies the order in which property values should\n   * be evaluated.  Any keys not listed are evaluated after all listed\n   * keys in indeterminate order.  If 'order' is not present, keys\n   * are evaluated in indeterminate order.\n   */\n  order?: (keyof T)[];\n\n  /**\n   * Specify handling of `undefined` values.  By default, successful\n   * `undefined` results are written to the result object.  If this value\n   * is `true` then `undefined` results are suppressed for all properties.\n   * If this value is an array of property keys then `undefined` results\n   * are suppressed for those properties only.\n   */\n  suppressUndefined?: boolean | (keyof T)[];\n}\n\n/**\n * Populates an an object based on a prototype full of field initializers that return {@link Result | Result<T[key]>}.\n * Returns {@link Success} with the populated object if all initializers succeed, or {@link Failure} with a\n * concatenated list of all error messages.\n * @param initializers - An object with the shape of the target but with initializer functions for\n * each property.\n * @param options - An optional {@link PopulateObjectOptions | set of options} which\n * modify the behavior of this call.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * {@label WITH_OPTIONS}\n * @public\n */\nexport function populateObject<T>(\n  initializers: FieldInitializers<T>,\n  options?: PopulateObjectOptions<T>,\n  aggregatedErrors?: IMessageAggregator\n): Result<T>;\n\n/**\n * Populates an an object based on a prototype full of field initializers that return {@link Result | Result<T[key]>}.\n * Returns {@link Success} with the populated object if all initializers succeed, or {@link Failure} with a\n * concatenated list of all error messages.\n * @param initializers - An object with the shape of the target but with initializer functions for\n * each property.\n * @param order - Optional order in which keys should be written.\n * @param aggregatedErrors  - Optional string array to which any returned error messages will be\n * appended.  Each error is appended as an individual string.\n * @public\n * {@label WITH_ORDER}\n * @deprecated Pass {@link PopulateObjectOptions} instead.\n */\nexport function populateObject<T>(\n  initializers: FieldInitializers<T>,\n  order: (keyof T)[] | undefined,\n  aggregatedErrors?: IMessageAggregator\n): Result<T>;\n\nexport function populateObject<T>(\n  initializers: FieldInitializers<T>,\n  optionsOrOrder?: PopulateObjectOptions<T> | (keyof T)[],\n  aggregatedErrors?: IMessageAggregator\n): Result<T> {\n  const options: PopulateObjectOptions<T> = optionsOrOrder\n    ? Array.isArray(optionsOrOrder)\n      ? { order: optionsOrOrder }\n      : optionsOrOrder\n    : {};\n  const state = {} as { [key in keyof T]: T[key] };\n  const errors: string[] = [];\n  const keys: (keyof T)[] = Array.from(options.order ?? []);\n  const foundKeys = new Set<keyof T>(options.order);\n\n  // start with the supplied order then append anything else we find\n  for (const key in initializers) {\n    if (!foundKeys.has(key)) {\n      keys.push(key);\n      foundKeys.add(key);\n    }\n  }\n\n  for (const key of keys) {\n    if (initializers[key]) {\n      const result = initializers[key](state);\n      if (result.isSuccess()) {\n        if (result.value === undefined) {\n          if (\n            options.suppressUndefined === true ||\n            (Array.isArray(options.suppressUndefined) && options.suppressUndefined.includes(key))\n          ) {\n            continue;\n          }\n        }\n        state[key] = result.value;\n      } else {\n        errors.push(result.message);\n      }\n    } else {\n      errors.push(`populateObject: Key ${String(key)} is present but has no initializer`);\n    }\n  }\n\n  if (errors.length > 0) {\n    aggregatedErrors?.addMessages(errors);\n    return fail(errors.join('\\n'));\n  }\n  return succeed(state as T);\n}\n"]}

package/lib/packlets/base/messageAggregator.d.ts

@@ -0,0 +1,56 @@
+import { IMessageAggregator, Result } from './result';
+/**
+ * A simple error aggregator to simplify collecting and reporting all errors in
+ * a flow.
+ * @public
+ */
+export declare class MessageAggregator implements IMessageAggregator {
+    private readonly _messages;
+    /**
+     * Constructs a new {@link MessageAggregator | ErrorAggregator} with an
+     * optionally specified initial set of error messages.
+     * @param errors - optional array of errors to be included
+     * in the aggregation.
+     */
+    constructor(errors?: string[]);
+    /**
+     * {@inheritdoc IMessageAggregator.hasMessages}
+     */
+    get hasMessages(): boolean;
+    /**
+     * {@inheritdoc IMessageAggregator.messages}
+     */
+    get messages(): string[];
+    /**
+     * {@inheritdoc IMessageAggregator.addMessage}
+     */
+    addMessage(message: string | undefined): this;
+    /**
+     * {@inheritdoc IMessageAggregator.addMessages}
+     */
+    addMessages(messages: string[] | undefined): this;
+    /**
+     * {@inheritdoc IMessageAggregator.toString}
+     */
+    toString(separator?: string): string;
+    /**
+     * If any error messages have been aggregated, returns
+     * {@link Failure | Failure<T>} with the aggregated
+     * messages concatenated using the optionally-supplied
+     * separator, or newline.   If the supplied {@link Result | Result<T>}
+     * contains an error message that has not already been aggregated,
+     * it will be included in the aggregated messages.
+     *
+     * If no error messages have been aggregated, returns
+     * the supplied {@link Result | Result<T>}.
+     * @param result - The {@link Result | Result<T>} to be returned
+     * if no messages have been aggregated.
+     * @param separator - Optional string separator used to construct
+     * the error message.
+     * @returns {@link Failure | Failure<T>} with an aggregated message
+     * if any error messages were collected, the supplied
+     * {@link Result | Result<T>} otherwise.
+     */
+    returnOrReport<T>(result: Result<T>, separator?: string): Result<T>;
+}
+//# sourceMappingURL=messageAggregator.d.ts.map

package/lib/packlets/base/messageAggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageAggregator.d.ts","sourceRoot":"","sources":["../../../src/packlets/base/messageAggregator.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAQ,MAAM,UAAU,CAAC;AAE5D;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IAErC;;;;;OAKG;gBACgB,MAAM,CAAC,EAAE,MAAM,EAAE;IAIpC;;OAEG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;OAEG;IACH,IAAW,QAAQ,IAAI,MAAM,EAAE,CAE9B;IAED;;OAEG;IACI,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAOpD;;OAEG;IACI,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI;IAOxD;;OAEG;IACI,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAI3C;;;;;;;;;;;;;;;;;OAiBG;IACI,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;CAW3E"}

package/lib/packlets/base/messageAggregator.js

@@ -0,0 +1,108 @@
+"use strict";
+/*
+ * Copyright (c) 2024 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.MessageAggregator = void 0;
+const result_1 = require("./result");
+/**
+ * A simple error aggregator to simplify collecting and reporting all errors in
+ * a flow.
+ * @public
+ */
+class MessageAggregator {
+    /**
+     * Constructs a new {@link MessageAggregator | ErrorAggregator} with an
+     * optionally specified initial set of error messages.
+     * @param errors - optional array of errors to be included
+     * in the aggregation.
+     */
+    constructor(errors) {
+        this._messages = errors ? Array.from(errors) : [];
+    }
+    /**
+     * {@inheritdoc IMessageAggregator.hasMessages}
+     */
+    get hasMessages() {
+        return this._messages.length > 0;
+    }
+    /**
+     * {@inheritdoc IMessageAggregator.messages}
+     */
+    get messages() {
+        return this._messages;
+    }
+    /**
+     * {@inheritdoc IMessageAggregator.addMessage}
+     */
+    addMessage(message) {
+        if (message) {
+            this._messages.push(message);
+        }
+        return this;
+    }
+    /**
+     * {@inheritdoc IMessageAggregator.addMessages}
+     */
+    addMessages(messages) {
+        if (messages && messages.length > 0) {
+            this._messages.push(...messages);
+        }
+        return this;
+    }
+    /**
+     * {@inheritdoc IMessageAggregator.toString}
+     */
+    toString(separator) {
+        return this._messages.join(separator !== null && separator !== void 0 ? separator : '\n');
+    }
+    /**
+     * If any error messages have been aggregated, returns
+     * {@link Failure | Failure<T>} with the aggregated
+     * messages concatenated using the optionally-supplied
+     * separator, or newline.   If the supplied {@link Result | Result<T>}
+     * contains an error message that has not already been aggregated,
+     * it will be included in the aggregated messages.
+     *
+     * If no error messages have been aggregated, returns
+     * the supplied {@link Result | Result<T>}.
+     * @param result - The {@link Result | Result<T>} to be returned
+     * if no messages have been aggregated.
+     * @param separator - Optional string separator used to construct
+     * the error message.
+     * @returns {@link Failure | Failure<T>} with an aggregated message
+     * if any error messages were collected, the supplied
+     * {@link Result | Result<T>} otherwise.
+     */
+    returnOrReport(result, separator) {
+        if (!this.hasMessages) {
+            return result;
+        }
+        if (!result.success) {
+            if (!this._messages.find((s) => s === result.message)) {
+                return (0, result_1.fail)([...this._messages, result.message].join(separator !== null && separator !== void 0 ? separator : '\n'));
+            }
+        }
+        return (0, result_1.fail)(this.toString(separator));
+    }
+}
+exports.MessageAggregator = MessageAggregator;
+//# sourceMappingURL=messageAggregator.js.map

package/lib/packlets/base/messageAggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageAggregator.js","sourceRoot":"","sources":["../../../src/packlets/base/messageAggregator.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,qCAA4D;AAE5D;;;;GAIG;AACH,MAAa,iBAAiB;IAG5B;;;;;OAKG;IACH,YAAmB,MAAiB;QAClC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,IAAW,WAAW;QACpB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACI,UAAU,CAAC,OAA2B;QAC3C,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,WAAW,CAAC,QAA8B;QAC/C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,QAAQ,CAAC,SAAkB;QAChC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,aAAT,SAAS,cAAT,SAAS,GAAI,IAAI,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACI,cAAc,CAAI,MAAiB,EAAE,SAAkB;QAC5D,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;gBACtD,OAAO,IAAA,aAAI,EAAC,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,aAAT,SAAS,cAAT,SAAS,GAAI,IAAI,CAAC,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;QACD,OAAO,IAAA,aAAI,EAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IACxC,CAAC;CACF;AAnFD,8CAmFC","sourcesContent":["/*\n * Copyright (c) 2024 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 { IMessageAggregator, Result, fail } from './result';\n\n/**\n * A simple error aggregator to simplify collecting and reporting all errors in\n * a flow.\n * @public\n */\nexport class MessageAggregator implements IMessageAggregator {\n  private readonly _messages: string[];\n\n  /**\n   * Constructs a new {@link MessageAggregator | ErrorAggregator} with an\n   * optionally specified initial set of error messages.\n   * @param errors - optional array of errors to be included\n   * in the aggregation.\n   */\n  public constructor(errors?: string[]) {\n    this._messages = errors ? Array.from(errors) : [];\n  }\n\n  /**\n   * {@inheritdoc IMessageAggregator.hasMessages}\n   */\n  public get hasMessages(): boolean {\n    return this._messages.length > 0;\n  }\n\n  /**\n   * {@inheritdoc IMessageAggregator.messages}\n   */\n  public get messages(): string[] {\n    return this._messages;\n  }\n\n  /**\n   * {@inheritdoc IMessageAggregator.addMessage}\n   */\n  public addMessage(message: string | undefined): this {\n    if (message) {\n      this._messages.push(message);\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritdoc IMessageAggregator.addMessages}\n   */\n  public addMessages(messages: string[] | undefined): this {\n    if (messages && messages.length > 0) {\n      this._messages.push(...messages);\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritdoc IMessageAggregator.toString}\n   */\n  public toString(separator?: string): string {\n    return this._messages.join(separator ?? '\\n');\n  }\n\n  /**\n   * If any error messages have been aggregated, returns\n   * {@link Failure | Failure<T>} with the aggregated\n   * messages concatenated using the optionally-supplied\n   * separator, or newline.   If the supplied {@link Result | Result<T>}\n   * contains an error message that has not already been aggregated,\n   * it will be included in the aggregated messages.\n   *\n   * If no error messages have been aggregated, returns\n   * the supplied {@link Result | Result<T>}.\n   * @param result - The {@link Result | Result<T>} to be returned\n   * if no messages have been aggregated.\n   * @param separator - Optional string separator used to construct\n   * the error message.\n   * @returns {@link Failure | Failure<T>} with an aggregated message\n   * if any error messages were collected, the supplied\n   * {@link Result | Result<T>} otherwise.\n   */\n  public returnOrReport<T>(result: Result<T>, separator?: string): Result<T> {\n    if (!this.hasMessages) {\n      return result;\n    }\n    if (!result.success) {\n      if (!this._messages.find((s) => s === result.message)) {\n        return fail([...this._messages, result.message].join(separator ?? '\\n'));\n      }\n    }\n    return fail(this.toString(separator));\n  }\n}\n"]}

package/lib/packlets/base/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/packlets/base/normalize.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,MAAM,EAA6B,MAAM,UAAU,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnE;;;GAGG;AACH,qBAAa,UAAU;IACrB;;;;;OAKG;IACI,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IA4BvC;;;;;;;OAOG;IACH,SAAS,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,MAAM;IAaxD;;;;;;OAMG;IACI,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE;IAQ7E,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IAI7D;;;;OAIG;IACI,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;CAwB/C"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/packlets/base/normalize.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,MAAM,EAAiB,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnE;;;GAGG;AACH,qBAAa,UAAU;IACrB;;;;;OAKG;IACI,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IA4BvC;;;;;;;OAOG;IACH,SAAS,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,MAAM;IAaxD;;;;;;OAMG;IACI,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE;IAQ7E,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IAI7D;;;;OAIG;IACI,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;CAwB/C"}

package/lib/packlets/base/normalize.js

@@ -22,6 +22,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Normalizer = void 0;
+const mapResults_1 = require("./mapResults");
 const result_1 = require("./result");
 /**
  * Normalizes an arbitrary JSON object
@@ -99,7 +100,7 @@ class Normalizer {
             .map((e) => [e[0], e[1].orThrow()]);
     }
     _normalizeArray(from) {
-        return (0, result_1.mapResults)(from.map((v) => this.normalize(v)));
+        return (0, mapResults_1.mapResults)(from.map((v) => this.normalize(v)));
     }
     /**
      * Normalizes the supplied literal value