@fgv/ts-utils 1.9.4 → 2.0.0

package/lib/packlets/base/result.js

@@ -0,0 +1,571 @@
+"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 = exports.captureResult = exports.propagateWithDetail = exports.failWithDetail = exports.succeedWithDetail = exports.DetailedFailure = exports.DetailedSuccess = exports.fail = exports.succeed = exports.Failure = exports.Success = void 0;
+/**
+ * Reports a successful {@link IResult | result} from some operation and the
+ * corresponding value.
+ * @public
+ */
+class Success {
+    /**
+     * Constructs a {@link Success} with the supplied value.
+     * @param value - The value to be returned.
+     */
+    constructor(value) {
+        /**
+         * {@inheritdoc IResult.success}
+         */
+        this.success = true;
+        this._value = value;
+    }
+    /**
+     * The result value returned by the successful operation.
+     */
+    get value() {
+        return this._value;
+    }
+    /**
+     * {@inheritdoc IResult.isSuccess}
+     */
+    isSuccess() {
+        return true;
+    }
+    /**
+     * {@inheritdoc IResult.isFailure}
+     */
+    isFailure() {
+        return false;
+    }
+    /**
+     * {@inheritdoc IResult.orThrow}
+     */
+    orThrow(__logger) {
+        return this._value;
+    }
+    /**
+     * {@inheritdoc IResult.orDefault}
+     */
+    orDefault(dflt) {
+        var _a;
+        return (_a = this._value) !== null && _a !== void 0 ? _a : dflt;
+    }
+    /**
+     * {@inheritdoc IResult.getValueOrThrow}
+     */
+    getValueOrThrow(__logger) {
+        return this._value;
+    }
+    /**
+     * {@inheritdoc IResult.getValueOrDefault}
+     */
+    getValueOrDefault(dflt) {
+        var _a;
+        return (_a = this._value) !== null && _a !== void 0 ? _a : dflt;
+    }
+    /**
+     * {@inheritdoc IResult.onSuccess}
+     */
+    onSuccess(cb) {
+        return cb(this.value);
+    }
+    /**
+     * {@inheritdoc IResult.onFailure}
+     */
+    onFailure(__) {
+        return this;
+    }
+    /**
+     * {@inheritdoc IResult.withFailureDetail}
+     */
+    withFailureDetail(__detail) {
+        return succeedWithDetail(this.value);
+    }
+    /**
+     * {@inheritdoc IResult.withDetail}
+     */
+    withDetail(detail, successDetail) {
+        return succeedWithDetail(this.value, successDetail !== null && successDetail !== void 0 ? successDetail : detail);
+    }
+}
+exports.Success = Success;
+/**
+ * Reports a failed {@link IResult | result} from some operation, with an error message.
+ * @public
+ */
+class Failure {
+    /**
+     * Constructs a {@link Failure} with the supplied message.
+     * @param message - Error message to be reported.
+     */
+    constructor(message) {
+        /**
+         * {@inheritdoc IResult.success}
+         */
+        this.success = false;
+        this._message = message;
+    }
+    /**
+     * Gets the error message associated with this error.
+     */
+    get message() {
+        return this._message;
+    }
+    /**
+     * {@inheritdoc IResult.isSuccess}
+     */
+    isSuccess() {
+        return false;
+    }
+    /**
+     * {@inheritdoc IResult.isFailure}
+     */
+    isFailure() {
+        return true;
+    }
+    /**
+     * {@inheritdoc IResult.orThrow}
+     */
+    orThrow(logger) {
+        if (logger !== undefined) {
+            logger.error(this._message);
+        }
+        throw new Error(this._message);
+    }
+    /**
+     * {@inheritdoc IResult.orDefault}
+     */
+    orDefault(dflt) {
+        return dflt;
+    }
+    /**
+     * {@inheritdoc IResult.getValueOrThrow}
+     */
+    getValueOrThrow(logger) {
+        if (logger !== undefined) {
+            logger.error(this._message);
+        }
+        throw new Error(this._message);
+    }
+    /**
+     * {@inheritdoc IResult.getValueOrDefault}
+     */
+    getValueOrDefault(dflt) {
+        return dflt;
+    }
+    /**
+     * {@inheritdoc IResult.onSuccess}
+     */
+    onSuccess(__) {
+        return new Failure(this.message);
+    }
+    /**
+     * {@inheritdoc IResult.onFailure}
+     */
+    onFailure(cb) {
+        return cb(this.message);
+    }
+    /**
+     * {@inheritdoc IResult.withFailureDetail}
+     */
+    withFailureDetail(detail) {
+        return failWithDetail(this.message, detail);
+    }
+    /**
+     * {@inheritdoc IResult.withDetail}
+     */
+    withDetail(detail, __successDetail) {
+        return failWithDetail(this.message, detail);
+    }
+    /**
+     * Get a 'friendly' string representation of this object.
+     * @remarks
+     * The string representation of a {@link Failure} value is the error message.
+     * @returns A string representing this object.
+     */
+    toString() {
+        return this.message;
+    }
+}
+exports.Failure = Failure;
+/**
+ * Returns {@link Success | Success<T>} with the supplied result value.
+ * @param value - The successful result value to be returned
+ * @public
+ */
+function succeed(value) {
+    return new Success(value);
+}
+exports.succeed = succeed;
+/**
+ * Returns {@link Failure | Failure<T>} with the supplied error message.
+ * @param message - Error message to be returned.
+ * @public
+ */
+function fail(message) {
+    return new Failure(message);
+}
+exports.fail = fail;
+/**
+ * A {@link DetailedSuccess} extends {@link Success} to report optional success details in
+ * addition to the error message.
+ * @public
+ */
+class DetailedSuccess extends Success {
+    /**
+     * Constructs a new {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied
+     * value and detail.
+     * @param value - The value to be returned.
+     * @param detail - An optional successful detail to be returned.  If omitted, detail
+     * will be `undefined`.
+     */
+    constructor(value, detail) {
+        super(value);
+        this._detail = detail;
+    }
+    /**
+     * The success detail associated with this {@link DetailedSuccess}, or `undefined` if
+     * no detail was supplied.
+     */
+    get detail() {
+        return this._detail;
+    }
+    /**
+     * Reports that this {@link DetailedSuccess} is a success.
+     * @remarks
+     * Always true for {@link DetailedSuccess} but can be used as type guard
+     * to discriminate {@link DetailedSuccess} from {@link DetailedFailure} in
+     * a {@link DetailedResult}.
+     * @returns `true`
+     */
+    isSuccess() {
+        return true;
+    }
+    /**
+     * Invokes the supplied {@link DetailedSuccessContinuation | success callback} and propagates
+     * its returned {@link DetailedResult | DetailedResult<TN, TD>}.
+     * @remarks
+     * The success callback mutates the return type from `<T>` to `<TN>`.
+     * @param cb - The {@link DetailedSuccessContinuation | success callback} to be invoked.
+     * @returns The {@link DetailedResult | DetailedResult<T, TD>} returned by the success callback.
+     */
+    onSuccess(cb) {
+        return cb(this.value, this._detail);
+    }
+    /**
+     * Propagates this {@link DetailedSuccess}.
+     * @remarks
+     * Failure does not mutate return type so we can return this event directly.
+     * @param _cb - {@link DetailedFailureContinuation | Failure callback} to be called
+     * on a {@link DetailedResult} in case of failure (ignored).
+     * @returns `this`
+     */
+    onFailure(__cb) {
+        return this;
+    }
+}
+exports.DetailedSuccess = DetailedSuccess;
+/**
+ * A {@link DetailedFailure} extends {@link Failure} to report optional failure details in
+ * addition to the error message.
+ * @public
+ */
+class DetailedFailure extends Failure {
+    /**
+     * Constructs a new {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied
+     * message and detail.
+     * @param message - The message to be returned.
+     * @param detail - The error detail to be returned.
+     */
+    constructor(message, detail) {
+        super(message);
+        this._detail = detail;
+    }
+    /**
+     * The error detail associated with this {@link DetailedFailure}.
+     */
+    get detail() {
+        return this._detail;
+    }
+    /**
+     * Reports that this {@link DetailedFailure} is a failure.
+     * @remarks
+     * Always true for {@link DetailedFailure} but can be used as type guard
+     * to discriminate {@link DetailedSuccess} from {@link DetailedFailure} in
+     * a {@link DetailedResult}.
+     * @returns `true`
+     */
+    isFailure() {
+        return true;
+    }
+    /**
+     * Propagates the error message and detail from this result.
+     * @remarks
+     * Mutates the success type as the success callback would have, but does not
+     * call the success callback.
+     * @param _cb - {@link DetailedSuccessContinuation | Success callback} to be called
+     * on a {@link DetailedResult} in case of success (ignored).
+     * @returns A new {@link DetailedFailure | DetailedFailure<TN, TD>} which contains
+     * the error message and detail from this one.
+     */
+    onSuccess(__cb) {
+        return new DetailedFailure(this.message, this._detail);
+    }
+    /**
+     * Invokes the supplied {@link DetailedFailureContinuation | failure callback} and propagates
+     * its returned {@link DetailedResult | DetailedResult<T, TD>}.
+     * @param cb - The {@link DetailedFailureContinuation | failure callback} to be invoked.
+     * @returns The {@link DetailedResult | DetailedResult<T, TD>} returned by the failure callback.
+     */
+    onFailure(cb) {
+        return cb(this.message, this._detail);
+    }
+}
+exports.DetailedFailure = DetailedFailure;
+/**
+ * Returns {@link DetailedSuccess | DetailedSuccess<T, TD>} with a supplied value and optional
+ * detail.
+ * @param value - The value of type `<T>` to be returned.
+ * @param detail - An optional detail of type `<TD>` to be returned.
+ * @returns A {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied value
+ * and detail, if supplied.
+ * @public
+ */
+function succeedWithDetail(value, detail) {
+    return new DetailedSuccess(value, detail);
+}
+exports.succeedWithDetail = succeedWithDetail;
+/**
+ * Returns {@link DetailedFailure | DetailedFailure<T, TD>} with a supplied error message and detail.
+ * @param message - The error message to be returned.
+ * @param detail - The event detail to be returned.
+ * @returns An {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied error
+ * message and detail.
+ * @public
+ */
+function failWithDetail(message, detail) {
+    return new DetailedFailure(message, detail);
+}
+exports.failWithDetail = failWithDetail;
+/**
+ * Propagates a {@link Success} or {@link Failure} {@link Result}, adding supplied
+ * event details as appropriate.
+ * @param result - The {@link Result} to be propagated.
+ * @param detail - The event detail (type `<TD>`) to be added to the {@link Result | result}.
+ * @param successDetail - An optional distinct event detail to be added to {@link Success} results.  If `successDetail`
+ * is omitted or `undefined`, then `detail` will be applied to {@link Success} results.
+ * @returns A new {@link DetailedResult | DetailedResult<T, TD>} with the success value or error
+ * message from the original `result` but with the specified detail added.
+ * @public
+ */
+function propagateWithDetail(result, detail, successDetail) {
+    return result.isSuccess()
+        ? succeedWithDetail(result.value, successDetail !== null && successDetail !== void 0 ? successDetail : detail)
+        : failWithDetail(result.message, detail);
+}
+exports.propagateWithDetail = propagateWithDetail;
+/**
+ * Wraps a function which might throw to convert exception results
+ * to {@link Failure}.
+ * @param func - The function to be captured.
+ * @returns Returns {@link Success} with a value of type `<T>` on
+ * success , or {@link Failure} with the thrown error message if
+ * `func` throws an `Error`.
+ * @public
+ */
+function captureResult(func) {
+    try {
+        return succeed(func());
+    }
+    catch (err) {
+        return fail(err.message);
+    }
+}
+exports.captureResult = captureResult;
+/**
+ * Aggregates successful result values from a collection of {@link Result | Result<T>}.
+ * @param results - The collection of {@link Result | Result<T>} to be mapped.
+ * @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) {
+    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) {
+        return fail(errors.join('\n'));
+    }
+    return 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.
+ * @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) {
+    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) {
+        return fail(errors.join('\n'));
+    }
+    return 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.
+ * @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) {
+    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) {
+        return fail(errors.join('\n'));
+    }
+    return 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.
+ * @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) {
+    const errors = [];
+    for (const result of results) {
+        if (result.isFailure()) {
+            errors.push(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.
+ * @returns Returns {@link Success} with `true` if all {@link Result | results} are successful.
+ * If any are unsuccessful, returns {@link Failure} with a concatenated summary the error
+ * messages from all failed elements.
+ * @public
+ */
+function allSucceed(results, successValue) {
+    const errors = [];
+    // istanbul ignore else
+    if (results !== undefined) {
+        for (const result of results) {
+            if (result.isFailure()) {
+                errors.push(result.message);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return fail(errors.join('\n'));
+    }
+    return succeed(successValue);
+}
+exports.allSucceed = allSucceed;
+function populateObject(initializers, optionsOrOrder) {
+    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) {
+        return fail(errors.join('\n'));
+    }
+    return succeed(state);
+}
+exports.populateObject = populateObject;
+//# sourceMappingURL=result.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../../src/packlets/base/result.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\n/* eslint-disable no-use-before-define */\n/**\n * Represents the {@link IResult | result} of some operation or sequence of operations.\n * @remarks\n * {@link Success | Success<T>} and {@link Failure | Failure<T>} share the common\n * contract {@link IResult}, enabling commingled discriminated usage.\n * @public\n */\nexport type Result<T> = Success<T> | Failure<T>;\n/**\n * Continuation callback to be called in the event that an\n * {@link Result} is successful.\n * @public\n */\nexport type SuccessContinuation<T, TN> = (value: T) => Result<TN>;\n/**\n * Continuation callback to be called in the event that an\n * {@link Result} fails.\n * @public\n */\nexport type FailureContinuation<T> = (message: string) => Result<T>;\n/**\n * Type inference to determine the result type of an {@link Result}.\n * @beta\n */\nexport type ResultValueType<T> = T extends Result<infer TV> ? TV : never;\n\n/**\n * Simple logger interface used by {@link IResult.orThrow}.\n * @public\n */\nexport interface IResultLogger {\n  /**\n   * Log an error message.\n   * @param message - The message to be logged.\n   */\n  error(message: string): void;\n}\n\n/**\n * Represents the result of some operation of sequence of operations.\n * @remarks\n * This common contract enables commingled discriminated usage of {@link Success | Success<T>}\n * and {@link Failure | Failure<T>}.\n * @public\n */\nexport interface IResult<T> {\n  /**\n   * Indicates whether the operation was successful.\n   */\n  readonly success: boolean;\n\n  /**\n   * Indicates whether this operation was successful.  Functions\n   * as a type guard for {@link Success | Success<T>}.\n   */\n  isSuccess(): this is Success<T>;\n\n  /**\n   * Indicates whether this operation failed.  Functions\n   * as a type guard for {@link Failure | Failure<T>}.\n   */\n  isFailure(): this is Failure<T>;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or throws the error message if the corresponding operation failed.\n   *\n   * Note that `getValueOrThrow` is being superseded by `orThrow` and\n   * will eventually be deprecated.  Please use orDefault instead.\n   *\n   * @param logger - An optional {@link IResultLogger | logger} to which the\n   * error will also be reported.\n   * @returns The return value, if the operation was successful.\n   * @throws The error message if the operation failed.\n   */\n  getValueOrThrow(logger?: IResultLogger): T;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or a default value if the corresponding operation failed.\n   * @param dflt - The value to be returned if the operation failed (default is\n   * `undefined`).\n   *\n   * Note that `getValueOrDefault` is being superseded by `orDefault` and\n   * will eventually be deprecated.  Please use orDefault instead.\n   *\n   * @returns The return value, if the operation was successful.  Returns\n   * the supplied default value or `undefined` if no default is supplied.\n   */\n  getValueOrDefault(dflt?: T): T | undefined;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or throws the error message if the corresponding operation failed.\n   * @param logger - An optional {@link IResultLogger | logger} to which the\n   * error will also be reported.\n   * @returns The return value, if the operation was successful.\n   * @throws The error message if the operation failed.\n   */\n  orThrow(logger?: IResultLogger): T;\n\n  /**\n   * Gets the value associated with a successful {@link IResult | result},\n   * or a default value if the corresponding operation failed.\n   * @param dflt - The value to be returned if the operation failed (default is\n   * `undefined`).\n   * @returns The return value, if the operation was successful.  Returns\n   * the supplied default value or `undefined` if no default is supplied.\n   */\n  orDefault(dflt?: T): T | undefined;\n\n  /**\n   * Calls a supplied {@link SuccessContinuation | success continuation} if\n   * the operation was a success.\n   * @remarks\n   * The {@link SuccessContinuation | success continuation} might return a\n   * different result type than {@link IResult} on which it is invoked. This\n   * enables chaining of operations with heterogenous return types.\n   *\n   * @param cb - The {@link SuccessContinuation | success continuation} to\n   * be called in the event of success.\n   * @returns If this operation was successful, returns the value returned\n   * by the {@link SuccessContinuation | success continuation}.  If this result\n   * failed, propagates the error message from this failure.\n   */\n  onSuccess<TN>(cb: SuccessContinuation<T, TN>): Result<TN>;\n\n  /**\n   * Calls a supplied {@link FailureContinuation | failed continuation} if\n   * the operation failed.\n   * @param cb - The {@link FailureContinuation | failure continuation} to\n   * be called in the event of failure.\n   * @returns If this operation failed, returns the value returned by the\n   * {@link FailureContinuation | failure continuation}.  If this result\n   * was successful, propagates the result value from the successful event.\n   */\n  onFailure(cb: FailureContinuation<T>): Result<T>;\n\n  /**\n   * Converts a {@link IResult | IResult<T>} to a {@link DetailedResult | DetailedResult<T, TD>},\n   * adding a supplied detail if the operation failed.\n   * @param detail - The detail to be added if this operation failed.\n   * @returns A new {@link DetailedResult | DetailedResult<T, TD>} with either\n   * the success result or the error message from this {@link IResult}, with\n   * the supplied detail (if this event failed) or detail `undefined` (if\n   * this result succeeded).\n   */\n  withFailureDetail<TD>(detail: TD): DetailedResult<T, TD>;\n\n  /**\n   * Converts a {@link IResult | IResult<T>} to a {@link DetailedResult | DetailedResult<T, TD>},\n   * adding supplied details.\n   * @param detail - The default detail to be added to the new {@link DetailedResult}.\n   * @param successDetail - An optional detail to be added if this result was successful.\n   * @returns A new {@link DetailedResult | DetailedResult<T, TD>} with either\n   * the success result or the error message from this {@link IResult} and the\n   * appropriate added detail.\n   */\n  withDetail<TD>(detail: TD, successDetail?: TD): DetailedResult<T, TD>;\n}\n\n/**\n * Reports a successful {@link IResult | result} from some operation and the\n * corresponding value.\n * @public\n */\nexport class Success<T> implements IResult<T> {\n  /**\n   * {@inheritdoc IResult.success}\n   */\n  public readonly success: true = true;\n  /**\n   * @internal\n   */\n  private readonly _value: T;\n\n  /**\n   * Constructs a {@link Success} with the supplied value.\n   * @param value - The value to be returned.\n   */\n  public constructor(value: T) {\n    this._value = value;\n  }\n\n  /**\n   * The result value returned by the successful operation.\n   */\n  public get value(): T {\n    return this._value;\n  }\n\n  /**\n   * {@inheritdoc IResult.isSuccess}\n   */\n  public isSuccess(): this is Success<T> {\n    return true;\n  }\n\n  /**\n   * {@inheritdoc IResult.isFailure}\n   */\n  public isFailure(): this is Failure<T> {\n    return false;\n  }\n\n  /**\n   * {@inheritdoc IResult.orThrow}\n   */\n  public orThrow(__logger?: IResultLogger): T {\n    return this._value;\n  }\n\n  /**\n   * {@inheritdoc IResult.orDefault}\n   */\n  public orDefault(dflt?: T): T | undefined {\n    return this._value ?? dflt;\n  }\n\n  /**\n   * {@inheritdoc IResult.getValueOrThrow}\n   */\n  public getValueOrThrow(__logger?: IResultLogger): T {\n    return this._value;\n  }\n\n  /**\n   * {@inheritdoc IResult.getValueOrDefault}\n   */\n  public getValueOrDefault(dflt?: T): T | undefined {\n    return this._value ?? dflt;\n  }\n\n  /**\n   * {@inheritdoc IResult.onSuccess}\n   */\n  public onSuccess<TN>(cb: SuccessContinuation<T, TN>): Result<TN> {\n    return cb(this.value);\n  }\n\n  /**\n   * {@inheritdoc IResult.onFailure}\n   */\n  public onFailure(__: FailureContinuation<T>): Result<T> {\n    return this;\n  }\n\n  /**\n   * {@inheritdoc IResult.withFailureDetail}\n   */\n  public withFailureDetail<TD>(__detail: TD): DetailedResult<T, TD> {\n    return succeedWithDetail(this.value);\n  }\n\n  /**\n   * {@inheritdoc IResult.withDetail}\n   */\n  public withDetail<TD>(detail: TD, successDetail?: TD): DetailedResult<T, TD> {\n    return succeedWithDetail(this.value, successDetail ?? detail);\n  }\n}\n\n/**\n * Reports a failed {@link IResult | result} from some operation, with an error message.\n * @public\n */\nexport class Failure<T> implements IResult<T> {\n  /**\n   * {@inheritdoc IResult.success}\n   */\n  public readonly success: false = false;\n\n  /**\n   * @internal\n   */\n  private readonly _message: string;\n\n  /**\n   * Constructs a {@link Failure} with the supplied message.\n   * @param message - Error message to be reported.\n   */\n  public constructor(message: string) {\n    this._message = message;\n  }\n\n  /**\n   * Gets the error message associated with this error.\n   */\n  public get message(): string {\n    return this._message;\n  }\n\n  /**\n   * {@inheritdoc IResult.isSuccess}\n   */\n  public isSuccess(): this is Success<T> {\n    return false;\n  }\n\n  /**\n   * {@inheritdoc IResult.isFailure}\n   */\n  public isFailure(): this is Failure<T> {\n    return true;\n  }\n\n  /**\n   * {@inheritdoc IResult.orThrow}\n   */\n  public orThrow(logger?: IResultLogger): never {\n    if (logger !== undefined) {\n      logger.error(this._message);\n    }\n    throw new Error(this._message);\n  }\n\n  /**\n   * {@inheritdoc IResult.orDefault}\n   */\n  public orDefault(dflt?: T): T | undefined {\n    return dflt;\n  }\n\n  /**\n   * {@inheritdoc IResult.getValueOrThrow}\n   */\n  public getValueOrThrow(logger?: IResultLogger): never {\n    if (logger !== undefined) {\n      logger.error(this._message);\n    }\n    throw new Error(this._message);\n  }\n\n  /**\n   * {@inheritdoc IResult.getValueOrDefault}\n   */\n  public getValueOrDefault(dflt?: T): T | undefined {\n    return dflt;\n  }\n\n  /**\n   * {@inheritdoc IResult.onSuccess}\n   */\n  public onSuccess<TN>(__: SuccessContinuation<T, TN>): Result<TN> {\n    return new Failure(this.message);\n  }\n\n  /**\n   * {@inheritdoc IResult.onFailure}\n   */\n  public onFailure(cb: FailureContinuation<T>): Result<T> {\n    return cb(this.message);\n  }\n\n  /**\n   * {@inheritdoc IResult.withFailureDetail}\n   */\n  public withFailureDetail<TD>(detail: TD): DetailedResult<T, TD> {\n    return failWithDetail(this.message, detail);\n  }\n\n  /**\n   * {@inheritdoc IResult.withDetail}\n   */\n  public withDetail<TD>(detail: TD, __successDetail?: TD): DetailedResult<T, TD> {\n    return failWithDetail(this.message, detail);\n  }\n\n  /**\n   * Get a 'friendly' string representation of this object.\n   * @remarks\n   * The string representation of a {@link Failure} value is the error message.\n   * @returns A string representing this object.\n   */\n  public toString(): string {\n    return this.message;\n  }\n}\n\n/**\n * Returns {@link Success | Success<T>} with the supplied result value.\n * @param value - The successful result value to be returned\n * @public\n */\nexport function succeed<T>(value: T): Success<T> {\n  return new Success<T>(value);\n}\n\n/**\n * Returns {@link Failure | Failure<T>} with the supplied error message.\n * @param message - Error message to be returned.\n * @public\n */\nexport function fail<T>(message: string): Failure<T> {\n  return new Failure<T>(message);\n}\n\n/**\n * Callback to be called when a {@link DetailedResult} encounters success.\n * @remarks\n * A success callback can return a different result type than it receives, allowing\n * success results to chain through intermediate result types.\n * @public\n */\nexport type DetailedSuccessContinuation<T, TD, TN> = (value: T, detail?: TD) => DetailedResult<TN, TD>;\n\n/**\n * Callback to be called when a {@link DetailedResult} encounters a failure.\n * @remarks\n * A failure callback can change {@link Failure} to {@link Success} (e.g. by returning a default value)\n * or it can change or embellish the error message, but it cannot change the success return type.\n * @public\n */\nexport type DetailedFailureContinuation<T, TD> = (message: string, detail: TD) => DetailedResult<T, TD>;\n\n/**\n * A {@link DetailedSuccess} extends {@link Success} to report optional success details in\n * addition to the error message.\n * @public\n */\nexport class DetailedSuccess<T, TD> extends Success<T> {\n  /**\n   * @internal\n   */\n  protected _detail?: TD;\n\n  /**\n   * Constructs a new {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied\n   * value and detail.\n   * @param value - The value to be returned.\n   * @param detail - An optional successful detail to be returned.  If omitted, detail\n   * will be `undefined`.\n   */\n  public constructor(value: T, detail?: TD) {\n    super(value);\n    this._detail = detail;\n  }\n\n  /**\n   * The success detail associated with this {@link DetailedSuccess}, or `undefined` if\n   * no detail was supplied.\n   */\n  public get detail(): TD | undefined {\n    return this._detail;\n  }\n\n  /**\n   * Reports that this {@link DetailedSuccess} is a success.\n   * @remarks\n   * Always true for {@link DetailedSuccess} but can be used as type guard\n   * to discriminate {@link DetailedSuccess} from {@link DetailedFailure} in\n   * a {@link DetailedResult}.\n   * @returns `true`\n   */\n  public isSuccess(): this is DetailedSuccess<T, TD> {\n    return true;\n  }\n\n  /**\n   * Invokes the supplied {@link DetailedSuccessContinuation | success callback} and propagates\n   * its returned {@link DetailedResult | DetailedResult<TN, TD>}.\n   * @remarks\n   * The success callback mutates the return type from `<T>` to `<TN>`.\n   * @param cb - The {@link DetailedSuccessContinuation | success callback} to be invoked.\n   * @returns The {@link DetailedResult | DetailedResult<T, TD>} returned by the success callback.\n   */\n  public onSuccess<TN>(cb: DetailedSuccessContinuation<T, TD, TN>): DetailedResult<TN, TD> {\n    return cb(this.value, this._detail);\n  }\n\n  /**\n   * Propagates this {@link DetailedSuccess}.\n   * @remarks\n   * Failure does not mutate return type so we can return this event directly.\n   * @param _cb - {@link DetailedFailureContinuation | Failure callback} to be called\n   * on a {@link DetailedResult} in case of failure (ignored).\n   * @returns `this`\n   */\n  public onFailure(__cb: DetailedFailureContinuation<T, TD>): DetailedResult<T, TD> {\n    return this;\n  }\n}\n\n/**\n * A {@link DetailedFailure} extends {@link Failure} to report optional failure details in\n * addition to the error message.\n * @public\n */\nexport class DetailedFailure<T, TD> extends Failure<T> {\n  /**\n   * @internal\n   */\n  protected _detail: TD;\n\n  /**\n   * Constructs a new {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied\n   * message and detail.\n   * @param message - The message to be returned.\n   * @param detail - The error detail to be returned.\n   */\n  public constructor(message: string, detail: TD) {\n    super(message);\n    this._detail = detail;\n  }\n\n  /**\n   * The error detail associated with this {@link DetailedFailure}.\n   */\n  public get detail(): TD {\n    return this._detail;\n  }\n\n  /**\n   * Reports that this {@link DetailedFailure} is a failure.\n   * @remarks\n   * Always true for {@link DetailedFailure} but can be used as type guard\n   * to discriminate {@link DetailedSuccess} from {@link DetailedFailure} in\n   * a {@link DetailedResult}.\n   * @returns `true`\n   */\n  public isFailure(): this is DetailedFailure<T, TD> {\n    return true;\n  }\n\n  /**\n   * Propagates the error message and detail from this result.\n   * @remarks\n   * Mutates the success type as the success callback would have, but does not\n   * call the success callback.\n   * @param _cb - {@link DetailedSuccessContinuation | Success callback} to be called\n   * on a {@link DetailedResult} in case of success (ignored).\n   * @returns A new {@link DetailedFailure | DetailedFailure<TN, TD>} which contains\n   * the error message and detail from this one.\n   */\n  public onSuccess<TN>(__cb: DetailedSuccessContinuation<T, TD, TN>): DetailedResult<TN, TD> {\n    return new DetailedFailure<TN, TD>(this.message, this._detail);\n  }\n\n  /**\n   * Invokes the supplied {@link DetailedFailureContinuation | failure callback} and propagates\n   * its returned {@link DetailedResult | DetailedResult<T, TD>}.\n   * @param cb - The {@link DetailedFailureContinuation | failure callback} to be invoked.\n   * @returns The {@link DetailedResult | DetailedResult<T, TD>} returned by the failure callback.\n   */\n  public onFailure(cb: DetailedFailureContinuation<T, TD>): DetailedResult<T, TD> {\n    return cb(this.message, this._detail);\n  }\n}\n\n/**\n * Type inference to determine the result type `T` of a {@link DetailedResult | DetailedResult<T, TD>}.\n * @beta\n */\nexport type DetailedResult<T, TD> = DetailedSuccess<T, TD> | DetailedFailure<T, TD>;\n\n/**\n * Type inference to determine the detail type `TD` of a {@link DetailedResult | DetailedResult<T, TD>}.\n * @beta\n */\nexport type ResultDetailType<T> = T extends DetailedResult<unknown, infer TD> ? TD : never;\n\n/**\n * Returns {@link DetailedSuccess | DetailedSuccess<T, TD>} with a supplied value and optional\n * detail.\n * @param value - The value of type `<T>` to be returned.\n * @param detail - An optional detail of type `<TD>` to be returned.\n * @returns A {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied value\n * and detail, if supplied.\n * @public\n */\nexport function succeedWithDetail<T, TD>(value: T, detail?: TD): DetailedSuccess<T, TD> {\n  return new DetailedSuccess<T, TD>(value, detail);\n}\n\n/**\n * Returns {@link DetailedFailure | DetailedFailure<T, TD>} with a supplied error message and detail.\n * @param message - The error message to be returned.\n * @param detail - The event detail to be returned.\n * @returns An {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied error\n * message and detail.\n * @public\n */\nexport function failWithDetail<T, TD>(message: string, detail: TD): DetailedFailure<T, TD> {\n  return new DetailedFailure<T, TD>(message, detail);\n}\n\n/**\n * Propagates a {@link Success} or {@link Failure} {@link Result}, adding supplied\n * event details as appropriate.\n * @param result - The {@link Result} to be propagated.\n * @param detail - The event detail (type `<TD>`) to be added to the {@link Result | result}.\n * @param successDetail - An optional distinct event detail to be added to {@link Success} results.  If `successDetail`\n * is omitted or `undefined`, then `detail` will be applied to {@link Success} results.\n * @returns A new {@link DetailedResult | DetailedResult<T, TD>} with the success value or error\n * message from the original `result` but with the specified detail added.\n * @public\n */\nexport function propagateWithDetail<T, TD>(\n  result: Result<T>,\n  detail: TD,\n  successDetail?: TD\n): DetailedResult<T, TD> {\n  return result.isSuccess()\n    ? succeedWithDetail(result.value, successDetail ?? detail)\n    : failWithDetail(result.message, detail);\n}\n\n/**\n * Wraps a function which might throw to convert exception results\n * to {@link Failure}.\n * @param func - The function to be captured.\n * @returns Returns {@link Success} with a value of type `<T>` on\n * success , or {@link Failure} with the thrown error message if\n * `func` throws an `Error`.\n * @public\n */\nexport function captureResult<T>(func: () => T): Result<T> {\n  try {\n    return succeed(func());\n  } catch (err) {\n    return fail((err as Error).message);\n  }\n}\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 * @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>(results: Iterable<Result<T>>): 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    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 * @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): 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    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 * @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>(results: Iterable<Result<T>>): 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    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 * @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>(results: Iterable<Result<T>>): string[] {\n  const errors: string[] = [];\n  for (const result of results) {\n    if (result.isFailure()) {\n      errors.push(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 * @returns Returns {@link Success} with `true` if all {@link Result | results} are successful.\n * If any are unsuccessful, returns {@link Failure} with a concatenated summary the error\n * messages from all failed elements.\n * @public\n */\nexport function allSucceed<T>(results: Iterable<Result<unknown>>, successValue: T): Result<T> {\n  const errors: string[] = [];\n\n  // istanbul ignore else\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    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 * {@label WITH_OPTIONS}\n * @public\n */\nexport function populateObject<T>(\n  initializers: FieldInitializers<T>,\n  options?: PopulateObjectOptions<T>\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 * @public\n * {@label WITH_ORDER}\n * @deprecated Pass {@link PopulateObjectOptions} instead.\n */\nexport function populateObject<T>(initializers: FieldInitializers<T>, order: (keyof T)[]): Result<T>;\nexport function populateObject<T>(\n  initializers: FieldInitializers<T>,\n  optionsOrOrder?: PopulateObjectOptions<T> | (keyof T)[]\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    return fail(errors.join('\\n'));\n  }\n  return succeed(state as T);\n}\n"]}

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

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