@fgv/ts-utils 5.0.1-0 → 5.0.1-10

package/dist/index.js

@@ -0,0 +1,32 @@
+/*
+ * 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.
+ */
+import * as Collections from './packlets/collections';
+import * as Conversion from './packlets/conversion';
+import * as Hash from './packlets/hash';
+import * as Logging from './packlets/logging';
+import * as Validation from './packlets/validation';
+import { Collector, ConvertingCollector, ResultMap, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap } from './packlets/collections';
+import { Converters, ObjectConverter, StringConverter } from './packlets/conversion';
+import { Validators } from './packlets/validation';
+export * from './packlets/base';
+export { Collections, Collector, ConvertingCollector, Conversion, Converters, Hash, Logging, ObjectConverter, ResultMap, StringConverter, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap, Validation, Validators };
+//# sourceMappingURL=index.js.map

package/dist/packlets/base/brand.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2021 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.
+ */
+export {};
+//# sourceMappingURL=brand.js.map

package/dist/packlets/base/index.js

@@ -0,0 +1,28 @@
+/*
+ * 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.
+ */
+export * from './brand';
+export * from './mapResults';
+export * from './messageAggregator';
+export { Normalizer } from './normalize';
+export * from './result';
+export * from './utils';
+//# sourceMappingURL=index.js.map

package/dist/packlets/base/mapResults.js

@@ -0,0 +1,217 @@
+/*
+ * 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.
+ */
+import { MessageAggregator } from './messageAggregator';
+import { fail, isDeferredResult, succeed } 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 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 fail(errors.join('\n'));
+    }
+    return succeed(elements);
+}
+/**
+ * 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 function mapDetailedResults(results, ignore, aggregatedErrors) {
+    const errors = [];
+    const elements = [];
+    for (const result of results) {
+        if (result.isSuccess()) {
+            elements.push(result.value);
+        }
+        else if (result.detail && !ignore.includes(result.detail)) {
+            errors.push(result.message);
+        }
+    }
+    if (errors.length > 0) {
+        aggregatedErrors === null || aggregatedErrors === void 0 ? void 0 : aggregatedErrors.addMessages(errors);
+        return fail(errors.join('\n'));
+    }
+    return succeed(elements);
+}
+/**
+ * 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 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 fail(errors.join('\n'));
+    }
+    return succeed(elements);
+}
+/**
+ * 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 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;
+}
+/**
+ * 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 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 fail(errors.join('\n'));
+    }
+    return succeed(successValue);
+}
+/**
+ * Returns the first successful result from a collection of {@link Result | Result<T>} or {@link DeferredResult | DeferredResult<T>}.
+ * @param results - The collection of {@link Result | Result<T>} or {@link DeferredResult | DeferredResult<T>} to be tested.
+ * @returns The first successful result, or {@link Failure} with a concatenated summary of all error messages.
+ * @public
+ */
+export function firstSuccess(results) {
+    const errors = new MessageAggregator();
+    for (const r of results) {
+        const result = isDeferredResult(r) ? r() : r;
+        if (result.isSuccess()) {
+            return result;
+        }
+        errors.addMessage(result.message);
+    }
+    return errors.returnOrReport(fail('no results found'));
+}
+export 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 fail(errors.join('\n'));
+    }
+    return succeed(state);
+}
+//# sourceMappingURL=mapResults.js.map

package/dist/packlets/base/messageAggregator.js

@@ -0,0 +1,110 @@
+/*
+ * 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.
+ */
+import { fail } from './result';
+/**
+ * A simple error aggregator to simplify collecting and reporting all errors in
+ * a flow.
+ * @public
+ */
+export 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.numMessages}
+     */
+    get numMessages() {
+        return this._messages.length;
+    }
+    /**
+     * {@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 fail([...this._messages, result.message].join(separator !== null && separator !== void 0 ? separator : '\n'));
+            }
+        }
+        return fail(this.toString(separator));
+    }
+}
+//# sourceMappingURL=messageAggregator.js.map

package/dist/packlets/base/normalize.js

@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) 2021 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.
+ */
+import { mapResults } from './mapResults';
+import { fail, succeed } from './result';
+/**
+ * Normalizes an arbitrary JSON object
+ * @public
+ */
+export class Normalizer {
+    /**
+     * Normalizes the supplied value
+     *
+     * @param from - The value to be normalized
+     * @returns A normalized version of the value
+     */
+    normalize(from) {
+        switch (typeof from) {
+            case 'string':
+            case 'bigint':
+            case 'boolean':
+            case 'number':
+            case 'symbol':
+            case 'undefined':
+                return this.normalizeLiteral(from);
+            case 'object':
+                if (from === null || from instanceof Date || from instanceof RegExp) {
+                    return this.normalizeLiteral(from);
+                }
+                else if (Array.isArray(from)) {
+                    return this._normalizeArray(from);
+                }
+                else if (from instanceof Map) {
+                    return succeed(new Map(this.normalizeEntries(from.entries())));
+                }
+                else if (from instanceof Set) {
+                    return succeed(new Set(this.normalizeEntries(from.entries())));
+                }
+                const obj = {};
+                for (const e of this.normalizeEntries(Object.entries(from))) {
+                    obj[e[0]] = e[1];
+                }
+                return succeed(obj);
+        }
+        return fail(`normalize: Unexpected type - cannot normalize '${typeof from}'`);
+    }
+    /**
+     * Compares two property names from some object being normalized.
+     * @param k1 - First key to be compared.
+     * @param k2 - Second key to be compared.
+     * @returns `1` if `k1` is greater, `-1` if `k2` is greater and
+     * `0` if they are equal.
+     * @internal
+     */
+    _compareKeys(k1, k2) {
+        const cs1 = String(k1);
+        const cs2 = String(k2);
+        if (cs1 > cs2) {
+            return 1;
+        }
+        if (cs2 > cs1) {
+            return -1;
+        }
+        /* c8 ignore next 2 */
+        return 0;
+    }
+    /**
+     * Normalizes an array of object property entries (e.g. as returned by `Object.entries()`).
+     * @remarks
+     * Converts property names (entry key) to string and then sorts as string.
+     * @param entries - The entries to be normalized.
+     * @returns A normalized sorted array of entries.
+     */
+    normalizeEntries(entries) {
+        return Array.from(entries)
+            .sort((e1, e2) => this._compareKeys(e1[0], e2[0]))
+            .map((e) => [e[0], this.normalize(e[1])])
+            .filter((e) => e[1].isSuccess())
+            .map((e) => [e[0], e[1].orThrow()]);
+    }
+    _normalizeArray(from) {
+        return mapResults(from.map((v) => this.normalize(v)));
+    }
+    /**
+     * Normalizes the supplied literal value
+     * @param from - The literal value to be normalized.
+     * @returns A normalized value for the literal.
+     */
+    normalizeLiteral(from) {
+        // TODO: Apply configurable normalization rules
+        switch (typeof from) {
+            case 'string':
+                return succeed(from);
+            case 'bigint':
+            case 'boolean':
+            case 'number':
+            case 'symbol':
+            case 'undefined':
+                return succeed(from);
+        }
+        if (from === null) {
+            return succeed(from);
+        }
+        if (from instanceof Date) {
+            return succeed(from);
+        }
+        if (from instanceof RegExp) {
+            return succeed(from);
+        }
+        /* c8 ignore next 2 */
+        return fail(`cannot normalize ${JSON.stringify(from)}`);
+    }
+}
+//# sourceMappingURL=normalize.js.map