@fgv/ts-utils 5.0.1-9 → 5.0.1

package/dist/packlets/base/result.js

@@ -0,0 +1,611 @@
+/*
+ * 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.
+ */
+/**
+ * Checks if a result is a deferred result.
+ * @param result - The result to check.
+ * @returns `true` if the result is a deferred result, `false` otherwise.
+ * @public
+ */
+export function isDeferredResult(result) {
+    return typeof result === 'function';
+}
+/**
+ * Reports a successful {@link IResult | result} from some operation and the
+ * corresponding value.
+ * @public
+ */
+export 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;
+        /**
+         * For a successful operation, the error message is always `undefined`.
+         */
+        this.message = undefined;
+        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;
+    }
+    orThrow(__logger) {
+        return this._value;
+    }
+    orDefault(dflt) {
+        var _a;
+        return (_a = this._value) !== null && _a !== void 0 ? _a : dflt;
+    }
+    /**
+     * {@inheritdoc IResult.getValueOrThrow}
+     * @deprecated Use {@link Success.(orThrow:1) | orThrow(logger)} or {@link Success.(orThrow:2) | orThrow(formatter)} instead.
+     */
+    getValueOrThrow(__logger) {
+        return this._value;
+    }
+    /**
+     * {@inheritdoc IResult.getValueOrDefault}
+     * @deprecated Use {@link Success.(orDefault:1) | orDefault(T)} or {@link Success.(orDefault:2) | orDefault()} instead.
+     */
+    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.withErrorFormat}
+     */
+    withErrorFormat(__cb) {
+        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);
+    }
+    /**
+     * {@inheritdoc IResult.aggregateError}
+     */
+    aggregateError(__errors, __formatter) {
+        return this;
+    }
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter, options) {
+        var _a;
+        const successOptions = typeof (options === null || options === void 0 ? void 0 : options.success) === 'object' ? options.success : { level: options === null || options === void 0 ? void 0 : options.success };
+        const level = (_a = successOptions.level) !== null && _a !== void 0 ? _a : 'quiet';
+        reporter === null || reporter === void 0 ? void 0 : reporter.reportSuccess(level, this._value, undefined, successOptions.message);
+        return this;
+    }
+    /**
+     * Creates a {@link Success | Success<T>} with the supplied value.
+     * @param value - The value to be returned.
+     * @returns The resulting {@link Success | Success<T>} with the supplied value.
+     * @public
+     */
+    static with(value) {
+        return new Success(value);
+    }
+}
+/**
+ * Reports a failed {@link IResult | result} from some operation, with an error message.
+ * @public
+ */
+export 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;
+        /**
+         * Failed operation always returns undefined for value.
+         */
+        this.value = undefined;
+        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;
+    }
+    orThrow(logOrFormat) {
+        if (logOrFormat !== undefined) {
+            if (typeof logOrFormat === 'function') {
+                throw new Error(logOrFormat(this._message));
+            }
+            else {
+                logOrFormat.error(this._message);
+            }
+        }
+        throw new Error(this._message);
+    }
+    orDefault(dflt) {
+        return dflt;
+    }
+    /**
+     * {@inheritdoc IResult.getValueOrThrow}
+     * @deprecated Use {@link Failure.(orThrow:1) | orThrow(logger)} or {@link Failure.(orThrow:2) | orThrow(formatter)} instead.
+     */
+    getValueOrThrow(logger) {
+        if (logger !== undefined) {
+            logger.error(this._message);
+        }
+        throw new Error(this._message);
+    }
+    /**
+     * {@inheritdoc IResult.getValueOrDefault}
+     * @deprecated Use {@link Failure.(orDefault:1) | orDefault(T)} or {@link Failure.(orDefault:2) | orDefault()} instead.
+     */
+    getValueOrDefault(dflt) {
+        return dflt;
+    }
+    /**
+     * {@inheritdoc IResult.onSuccess}
+     */
+    onSuccess(__) {
+        return new Failure(this._message);
+    }
+    /**
+     * {@inheritdoc IResult.onFailure}
+     */
+    onFailure(cb) {
+        return cb(this._message);
+    }
+    /**
+     * {@inheritdoc IResult.withErrorFormat}
+     */
+    withErrorFormat(cb) {
+        return fail(cb(this._message));
+    }
+    /**
+     * {@inheritdoc IResult.withFailureDetail}
+     */
+    withFailureDetail(detail) {
+        return failWithDetail(this._message, detail);
+    }
+    /**
+     * {@inheritdoc IResult.withDetail}
+     */
+    withDetail(detail, __successDetail) {
+        return failWithDetail(this._message, detail);
+    }
+    /**
+     * {@inheritdoc IResult.aggregateError}
+     */
+    aggregateError(errors, formatter) {
+        const message = formatter ? formatter(this._message) : this._message;
+        errors.addMessage(message);
+        return this;
+    }
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter, options) {
+        var _a, _b, _c;
+        const failureOptions = typeof (options === null || options === void 0 ? void 0 : options.failure) === 'object' ? options.failure : { level: options === null || options === void 0 ? void 0 : options.failure };
+        const level = (_a = failureOptions.level) !== null && _a !== void 0 ? _a : 'error';
+        const message = (_c = (_b = failureOptions.message) === null || _b === void 0 ? void 0 : _b.call(failureOptions, this._message)) !== null && _c !== void 0 ? _c : this._message;
+        reporter === null || reporter === void 0 ? void 0 : reporter.reportFailure(level, message);
+        return this;
+    }
+    /**
+     * 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;
+    }
+    /**
+     * Creates a {@link Failure | Failure<T>} with the supplied error message.
+     * @param message - The error message to be returned.
+     * @returns The resulting {@link Failure | Failure<T>} with the supplied error message.
+     */
+    static with(message) {
+        return new Failure(message);
+    }
+}
+/**
+ * Returns {@link Success | Success<T>} with the supplied result value.
+ * @param value - The successful result value to be returned
+ * @remarks
+ * A `succeeds` alias was added in release 5.0 for
+ * naming consistency with {@link fails | fails}, which was added
+ * to avoid conflicts with test frameworks and libraries.
+ * @public
+ */
+export function succeed(value) {
+    return new Success(value);
+}
+/**
+ * {@inheritdoc succeed}
+ * @public
+ */
+export function succeeds(value) {
+    return new Success(value);
+}
+/**
+ * Returns {@link Failure | Failure<T>} with the supplied error message.
+ * @param message - Error message to be returned.
+ * @remarks
+ * A `fails` alias was added in release 5.0 due to
+ * issues with the name `fail` being used test frameworks and libraries.
+ * @public
+ */
+export function fail(message) {
+    return new Failure(message);
+}
+/**
+ * {@inheritdoc fail}
+ * @public
+ */
+export function fails(message) {
+    return new Failure(message);
+}
+/**
+ * Uses a value or calls a supplied initializer if the supplied value is undefined.
+ * @param value - the value
+ * @param initializer - a function that initializes the value if it is undefined
+ * @returns `Success` with the value if it is defined, or the result of calling the initializer function.
+ * @public
+ */
+export function useOrInitialize(value, initializer) {
+    return value !== undefined ? succeed(value) : initializer();
+}
+/**
+ * A {@link DetailedSuccess | DetailedSuccess} extends {@link Success | Success} to report optional success
+ * details in addition to the error message.
+ * @public
+ */
+export 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;
+    }
+    /**
+     * {@inheritdoc Success.withErrorFormat}
+     */
+    withErrorFormat(cb) {
+        return this;
+    }
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter, options) {
+        var _a;
+        const successOptions = typeof (options === null || options === void 0 ? void 0 : options.success) === 'object' ? options.success : { level: options === null || options === void 0 ? void 0 : options.success };
+        const level = (_a = successOptions.level) !== null && _a !== void 0 ? _a : 'quiet';
+        // Cast reporter to preserve detail type when calling reportSuccess
+        const detailedReporter = reporter;
+        detailedReporter === null || detailedReporter === void 0 ? void 0 : detailedReporter.reportSuccess(level, this._value, this._detail, successOptions.message);
+        return this;
+    }
+    /**
+     * Creates a {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied value and
+     * optional detail.
+     */
+    static with(value, detail) {
+        return new DetailedSuccess(value, detail);
+    }
+    /**
+     * Returns this {@link DetailedSuccess} as a {@link Result}.
+     */
+    get asResult() {
+        return this;
+    }
+}
+/**
+ * A {@link DetailedFailure | DetailedFailure<T, TD>} extends {@link Failure | Failure<T>} to report optional
+ * failure details in addition to the error message.
+ * @public
+ */
+export 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);
+    }
+    /**
+     * {@inheritdoc IResult.withErrorFormat}
+     */
+    withErrorFormat(cb) {
+        return failWithDetail(cb(this._message, this._detail), this._detail);
+    }
+    /**
+     * {@inheritdoc IResult.aggregateError}
+     */
+    aggregateError(errors, formatter) {
+        const message = formatter ? formatter(this._message, this._detail) : this._message;
+        errors.addMessage(message);
+        return this;
+    }
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter, options) {
+        var _a, _b;
+        const failureOptions = typeof (options === null || options === void 0 ? void 0 : options.failure) === 'object' ? options.failure : { level: options === null || options === void 0 ? void 0 : options.failure };
+        const level = (_a = failureOptions.level) !== null && _a !== void 0 ? _a : 'error';
+        // Cast formatter to handle detail type properly
+        const formatter = failureOptions.message;
+        const message = (_b = formatter === null || formatter === void 0 ? void 0 : formatter(this._message, this._detail)) !== null && _b !== void 0 ? _b : this._message;
+        // Cast reporter to preserve detail type when calling reportFailure
+        const detailedReporter = reporter;
+        detailedReporter === null || detailedReporter === void 0 ? void 0 : detailedReporter.reportFailure(level, message, this._detail);
+        return this;
+    }
+    orThrow(logOrFormat) {
+        if (logOrFormat !== undefined) {
+            if (typeof logOrFormat === 'function') {
+                throw new Error(logOrFormat(this._message, this._detail));
+            }
+            else {
+                logOrFormat.error(this._message, this._detail);
+            }
+        }
+        throw new Error(this._message);
+    }
+    /**
+     * Returns this {@link DetailedFailure} as a {@link Result}.
+     */
+    get asResult() {
+        return this;
+    }
+    /**
+     * Creates a {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied error message
+     * and optional detail.
+     * @param message - The error message to be returned.
+     * @param detail - The error detail to be returned.
+     * @returns The resulting {@link DetailedFailure | DetailedFailure<T, TD>} with the supplied
+     * error message and detail.
+     * @public
+     */
+    static with(message, detail) {
+        return new DetailedFailure(message, detail);
+    }
+}
+/**
+ * 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.
+ * @remarks
+ * The `succeedsWithDetail` alias was added in release 5.0 for
+ * naming consistency with {@link fails | fails}, which was added to avoid conflicts
+ * with test frameworks and libraries.
+ * @public
+ */
+export function succeedWithDetail(value, detail) {
+    return new DetailedSuccess(value, detail);
+}
+/**
+ * {@inheritdoc succeedWithDetail}
+ * @public
+ */
+export function succeedsWithDetail(value, detail) {
+    return new DetailedSuccess(value, detail);
+}
+/**
+ * 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.
+ * @remarks
+ * The `failsWithDetail` alias was added in release 5.0 for naming consistency
+ * with {@link fails | fails}, which was added to avoid conflicts with test frameworks and libraries.
+ * @public
+ */
+export function failWithDetail(message, detail) {
+    return new DetailedFailure(message, detail);
+}
+/**
+ * {@inheritdoc failWithDetail}
+ * @public
+ */
+export function failsWithDetail(message, detail) {
+    return new DetailedFailure(message, detail);
+}
+/**
+ * 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
+ */
+export function propagateWithDetail(result, detail, successDetail) {
+    return result.isSuccess()
+        ? succeedWithDetail(result.value, successDetail !== null && successDetail !== void 0 ? successDetail : detail)
+        : failWithDetail(result.message, detail);
+}
+/**
+ * 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
+ */
+export function captureResult(func) {
+    try {
+        return succeed(func());
+    }
+    catch (err) {
+        return fail(err.message);
+    }
+}
+//# sourceMappingURL=result.js.map