@fgv/ts-utils 3.0.0 → 3.0.1-alpha.1

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.39.1"
+      "packageVersion": "7.39.4"
     }
   ]
 }

package/lib/packlets/conversion/baseConverter.d.ts

@@ -0,0 +1,120 @@
+import { Brand, Result } from '../base';
+import { ConstraintOptions, Converter, ConverterTraits, DefaultingConverter, OnError } from './converter';
+/**
+ * internal
+ */
+type InnerInferredType<TCONV> = TCONV extends Converter<infer TTO> ? TTO extends Array<infer TTOELEM> ? InnerInferredType<TTOELEM>[] : TTO : TCONV extends Array<infer TELEM> ? InnerInferredType<TELEM>[] : TCONV;
+/**
+ * Infers the type that will be returned by an instantiated converter.  Works
+ * for complex as well as simple types.
+ * @example `Infer<typeof Converters.mapOf(Converters.stringArray)>` is `Map<string, string[]>`
+ * @beta
+ */
+export type Infer<TCONV> = TCONV extends Converter<infer TTO> ? InnerInferredType<TTO> : never;
+/**
+ * Deprecated name for Infer<T> retained for compatibility
+ * @deprecated use @see Infer instead
+ * @internal
+ */
+export type ConvertedToType<TCONV> = Infer<TCONV>;
+/**
+ * Base templated wrapper to simplify creation of new {@link Converter}s.
+ * @public
+ */
+export declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
+    /**
+     * @internal
+     */
+    protected readonly _defaultContext?: TC;
+    /**
+     * @internal
+     */
+    protected _isOptional: boolean;
+    /**
+     * @internal
+     */
+    protected _brand?: string;
+    private readonly _converter;
+    /**
+     * Constructs a new {@link Converter} which uses the supplied function to perform the conversion.
+     * @param converter - The conversion function to be applied.
+     * @param defaultContext - Optional conversion context to be used by default.
+     * @param traits - Optional {@link Conversion.ConverterTraits | traits} to be assigned to the resulting
+     * converter.
+     */
+    constructor(converter: (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>, defaultContext?: TC, traits?: ConverterTraits);
+    /**
+     * {@inheritdoc Converter.isOptional}
+     */
+    get isOptional(): boolean;
+    /**
+     * {@inheritdoc Converter.brand}
+     */
+    get brand(): string | undefined;
+    /**
+     * {@inheritdoc Converter.convert}
+     */
+    convert(from: unknown, context?: TC): Result<T>;
+    /**
+     * {@inheritdoc Converter.convertOptional}
+     */
+    convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
+    /**
+     * {@inheritdoc Converter.optional}
+     */
+    optional(onError?: OnError): Converter<T | undefined, TC>;
+    /**
+     * {@inheritdoc Converter.map}
+     */
+    map<T2>(mapper: (from: T) => Result<T2>): Converter<T2, TC>;
+    /**
+     * {@inheritdoc Converter.mapConvert}
+     */
+    mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
+    /**
+     * {@inheritdoc Converter.mapItems}
+     */
+    mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC>;
+    /**
+     * {@inheritdoc Converter.mapConvertItems}
+     */
+    mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
+    /**
+     * {@inheritdoc Converter.withAction}
+     */
+    withAction<TI>(action: (result: Result<T>) => Result<TI>): Converter<TI, TC>;
+    /**
+     * {@inheritdoc Converter.withTypeGuard}
+     */
+    withTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI, TC>;
+    /**
+     * {@inheritdoc Converter.withItemTypeGuard}
+     */
+    withItemTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI[], TC>;
+    /**
+     * {@inheritdoc Converter.withConstraint}
+     */
+    withConstraint(constraint: (val: T) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
+    /**
+     * {@inheritdoc Converter.withBrand}
+     */
+    withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
+    /**
+     * {@inheritdoc Converter.withDefault}
+     */
+    withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC>;
+    /**
+     * @internal
+     */
+    protected _context(supplied?: TC): TC | undefined;
+    /**
+     * @internal
+     */
+    protected _traits(traits?: Partial<ConverterTraits>): ConverterTraits;
+    /**
+     * @internal
+     */
+    protected _with(traits: Partial<ConverterTraits>): this;
+}
+export {};
+//# sourceMappingURL=baseConverter.d.ts.map

package/lib/packlets/conversion/baseConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseConverter.d.ts","sourceRoot":"","sources":["../../../src/packlets/conversion/baseConverter.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,KAAK,EAAE,MAAM,EAA6B,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG1G;;GAEG;AACH,KAAK,iBAAiB,CAAC,KAAK,IAAI,KAAK,SAAS,SAAS,CAAC,MAAM,GAAG,CAAC,GAC9D,GAAG,SAAS,KAAK,CAAC,MAAM,OAAO,CAAC,GAC9B,iBAAiB,CAAC,OAAO,CAAC,EAAE,GAC5B,GAAG,GACL,KAAK,SAAS,KAAK,CAAC,MAAM,KAAK,CAAC,GAChC,iBAAiB,CAAC,KAAK,CAAC,EAAE,GAC1B,KAAK,CAAC;AAEV;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,KAAK,IAAI,KAAK,SAAS,SAAS,CAAC,MAAM,GAAG,CAAC,GAAG,iBAAiB,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE/F;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;AAElD;;;GAGG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,EAAE,GAAG,SAAS,CAAE,YAAW,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;IACvE;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,EAAE,CAAC;IACxC;;OAEG;IACH,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;IACvC;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqE;IAEhG;;;;;;OAMG;gBAED,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,EAC7E,cAAc,CAAC,EAAE,EAAE,EACnB,MAAM,CAAC,EAAE,eAAe;IAQ1B;;OAEG;IACH,IAAW,UAAU,IAAI,OAAO,CAE/B;IAED;;OAEG;IACH,IAAW,KAAK,IAAI,MAAM,GAAG,SAAS,CAErC;IAED;;OAEG;IACI,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;IAItD;;OAEG;IACI,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAS7F;;OAEG;IACI,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,EAAE,EAAE,CAAC;IAOhE;;OAEG;IACI,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;IAUlE;;OAEG;IACI,UAAU,CAAC,EAAE,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;IAWrE;;OAEG;IACI,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAW/E;;OAEG;IACI,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAWrF;;OAEG;IACI,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;IAMnF;;OAEG;IACI,aAAa,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,IAAI,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;IASnG;;OAEG;IACI,iBAAiB,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,IAAI,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAgBzG;;OAEG;IACI,cAAc,CACnB,UAAU,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,EAC3C,OAAO,CAAC,EAAE,iBAAiB,GAC1B,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;IAkBnB;;OAEG;IACI,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;IAYxE;;OAEG;IACI,WAAW,CAAC,EAAE,GAAG,CAAC,EAAE,YAAY,EAAE,EAAE,GAAG,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAI5E;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,SAAS;IAIjD;;OAEG;IACH,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe;IAQrE;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;CAKxD"}

package/lib/packlets/conversion/baseConverter.js

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseConverter = void 0;
+/*
+ * 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.
+ */
+const base_1 = require("../base");
+const defaultingConverter_1 = require("./defaultingConverter");
+/**
+ * Base templated wrapper to simplify creation of new {@link Converter}s.
+ * @public
+ */
+class BaseConverter {
+    /**
+     * Constructs a new {@link Converter} which uses the supplied function to perform the conversion.
+     * @param converter - The conversion function to be applied.
+     * @param defaultContext - Optional conversion context to be used by default.
+     * @param traits - Optional {@link Conversion.ConverterTraits | traits} to be assigned to the resulting
+     * converter.
+     */
+    constructor(converter, defaultContext, traits) {
+        /**
+         * @internal
+         */
+        this._isOptional = false;
+        this._converter = converter;
+        this._defaultContext = defaultContext;
+        this._isOptional = (traits === null || traits === void 0 ? void 0 : traits.isOptional) === true;
+        this._brand = traits === null || traits === void 0 ? void 0 : traits.brand;
+    }
+    /**
+     * {@inheritdoc Converter.isOptional}
+     */
+    get isOptional() {
+        return this._isOptional;
+    }
+    /**
+     * {@inheritdoc Converter.brand}
+     */
+    get brand() {
+        return this._brand;
+    }
+    /**
+     * {@inheritdoc Converter.convert}
+     */
+    convert(from, context) {
+        return this._converter(from, this, context !== null && context !== void 0 ? context : this._defaultContext);
+    }
+    /**
+     * {@inheritdoc Converter.convertOptional}
+     */
+    convertOptional(from, context, onError) {
+        const result = this._converter(from, this, this._context(context));
+        if (result.isFailure()) {
+            onError = onError !== null && onError !== void 0 ? onError : 'ignoreErrors';
+            return from === undefined || onError === 'ignoreErrors' ? (0, base_1.succeed)(undefined) : result;
+        }
+        return result;
+    }
+    /**
+     * {@inheritdoc Converter.optional}
+     */
+    optional(onError) {
+        return new BaseConverter((from, __self, context) => {
+            onError = onError !== null && onError !== void 0 ? onError : 'failOnError';
+            return this.convertOptional(from, this._context(context), onError);
+        })._with(this._traits({ isOptional: true }));
+    }
+    /**
+     * {@inheritdoc Converter.map}
+     */
+    map(mapper) {
+        return new BaseConverter((from, __self, context) => {
+            const innerResult = this._converter(from, this, this._context(context));
+            if (innerResult.isSuccess()) {
+                return mapper(innerResult.value);
+            }
+            return (0, base_1.fail)(innerResult.message);
+        })._with(this._traits());
+    }
+    /**
+     * {@inheritdoc Converter.mapConvert}
+     */
+    mapConvert(mapConverter) {
+        return new BaseConverter((from, __self, context) => {
+            const innerResult = this._converter(from, this, this._context(context));
+            if (innerResult.isSuccess()) {
+                return mapConverter.convert(innerResult.value);
+            }
+            return (0, base_1.fail)(innerResult.message);
+            // eslint-disable-next-line no-return-assign
+        })._with(this._traits());
+    }
+    /**
+     * {@inheritdoc Converter.mapItems}
+     */
+    mapItems(mapper) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onSuccess((items) => {
+                if (Array.isArray(items)) {
+                    return (0, base_1.mapResults)(items.map((i) => mapper(i)));
+                }
+                return (0, base_1.fail)('Cannot map items - not an array');
+            });
+        });
+    }
+    /**
+     * {@inheritdoc Converter.mapConvertItems}
+     */
+    mapConvertItems(mapConverter) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onSuccess((items) => {
+                if (Array.isArray(items)) {
+                    return (0, base_1.mapResults)(items.map((i) => mapConverter.convert(i)));
+                }
+                return (0, base_1.fail)('Cannot map items - not an array');
+            });
+        });
+    }
+    /**
+     * {@inheritdoc Converter.withAction}
+     */
+    withAction(action) {
+        return new BaseConverter((from, __self, context) => {
+            return action(this._converter(from, this, this._context(context)));
+        })._with(this._traits());
+    }
+    /**
+     * {@inheritdoc Converter.withTypeGuard}
+     */
+    withTypeGuard(guard, message) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onSuccess((inner) => {
+                message = message !== null && message !== void 0 ? message : 'invalid type';
+                return guard(inner) ? (0, base_1.succeed)(inner) : (0, base_1.fail)(`${message}: ${JSON.stringify(from)}`);
+            });
+        })._with(this._traits());
+    }
+    /**
+     * {@inheritdoc Converter.withItemTypeGuard}
+     */
+    withItemTypeGuard(guard, message) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onSuccess((items) => {
+                if (Array.isArray(items)) {
+                    return (0, base_1.mapResults)(items.map((i) => {
+                        message = message !== null && message !== void 0 ? message : 'invalid type';
+                        return guard(i) ? (0, base_1.succeed)(i) : (0, base_1.fail)(`${message}: ${JSON.stringify(from)}`);
+                    }));
+                }
+                return (0, base_1.fail)('Cannot guard item type - not an array');
+            });
+        })._with(this._traits());
+    }
+    /**
+     * {@inheritdoc Converter.withConstraint}
+     */
+    withConstraint(constraint, options) {
+        return new BaseConverter((from, __self, context) => {
+            var _a;
+            const result = this._converter(from, this, this._context(context));
+            if (result.isSuccess()) {
+                const constraintResult = constraint(result.value);
+                if (typeof constraintResult === 'boolean') {
+                    return constraintResult
+                        ? result
+                        : (0, base_1.fail)(`"${JSON.stringify(result.value)}": ${(_a = options === null || options === void 0 ? void 0 : options.description) !== null && _a !== void 0 ? _a : 'does not meet constraint'}`);
+                }
+                return constraintResult;
+            }
+            return result;
+        })._with(this._traits());
+    }
+    /**
+     * {@inheritdoc Converter.withBrand}
+     */
+    withBrand(brand) {
+        if (this._brand) {
+            throw new Error(`Cannot replace existing brand "${this._brand}" with "${brand}".`);
+        }
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onSuccess((v) => {
+                return (0, base_1.succeed)(v);
+            });
+        })._with(this._traits({ brand }));
+    }
+    /**
+     * {@inheritdoc Converter.withDefault}
+     */
+    withDefault(defaultValue) {
+        return new defaultingConverter_1.GenericDefaultingConverter(this, defaultValue);
+    }
+    /**
+     * @internal
+     */
+    _context(supplied) {
+        return supplied !== null && supplied !== void 0 ? supplied : this._defaultContext;
+    }
+    /**
+     * @internal
+     */
+    _traits(traits) {
+        return Object.assign({ isOptional: this.isOptional, brand: this.brand }, (traits !== null && traits !== void 0 ? traits : {}));
+    }
+    /**
+     * @internal
+     */
+    _with(traits) {
+        this._isOptional = traits.isOptional === true;
+        this._brand = traits.brand;
+        return this;
+    }
+}
+exports.BaseConverter = BaseConverter;
+//# sourceMappingURL=baseConverter.js.map

package/lib/packlets/conversion/baseConverter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseConverter.js","sourceRoot":"","sources":["../../../src/packlets/conversion/baseConverter.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 */\nimport { Brand, Result, fail, mapResults, succeed } from '../base';\nimport { ConstraintOptions, Converter, ConverterTraits, DefaultingConverter, OnError } from './converter';\nimport { GenericDefaultingConverter } from './defaultingConverter';\n\n/**\n * internal\n */\ntype InnerInferredType<TCONV> = TCONV extends Converter<infer TTO>\n  ? TTO extends Array<infer TTOELEM>\n    ? InnerInferredType<TTOELEM>[]\n    : TTO\n  : TCONV extends Array<infer TELEM>\n  ? InnerInferredType<TELEM>[]\n  : TCONV;\n\n/**\n * Infers the type that will be returned by an instantiated converter.  Works\n * for complex as well as simple types.\n * @example `Infer<typeof Converters.mapOf(Converters.stringArray)>` is `Map<string, string[]>`\n * @beta\n */\nexport type Infer<TCONV> = TCONV extends Converter<infer TTO> ? InnerInferredType<TTO> : never;\n\n/**\n * Deprecated name for Infer<T> retained for compatibility\n * @deprecated use @see Infer instead\n * @internal\n */\nexport type ConvertedToType<TCONV> = Infer<TCONV>;\n\n/**\n * Base templated wrapper to simplify creation of new {@link Converter}s.\n * @public\n */\nexport class BaseConverter<T, TC = undefined> implements Converter<T, TC> {\n  /**\n   * @internal\n   */\n  protected readonly _defaultContext?: TC;\n  /**\n   * @internal\n   */\n  protected _isOptional: boolean = false;\n  /**\n   * @internal\n   */\n  protected _brand?: string;\n\n  private readonly _converter: (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>;\n\n  /**\n   * Constructs a new {@link Converter} which uses the supplied function to perform the conversion.\n   * @param converter - The conversion function to be applied.\n   * @param defaultContext - Optional conversion context to be used by default.\n   * @param traits - Optional {@link Conversion.ConverterTraits | traits} to be assigned to the resulting\n   * converter.\n   */\n  public constructor(\n    converter: (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>,\n    defaultContext?: TC,\n    traits?: ConverterTraits\n  ) {\n    this._converter = converter;\n    this._defaultContext = defaultContext;\n    this._isOptional = traits?.isOptional === true;\n    this._brand = traits?.brand;\n  }\n\n  /**\n   * {@inheritdoc Converter.isOptional}\n   */\n  public get isOptional(): boolean {\n    return this._isOptional;\n  }\n\n  /**\n   * {@inheritdoc Converter.brand}\n   */\n  public get brand(): string | undefined {\n    return this._brand;\n  }\n\n  /**\n   * {@inheritdoc Converter.convert}\n   */\n  public convert(from: unknown, context?: TC): Result<T> {\n    return this._converter(from, this, context ?? this._defaultContext);\n  }\n\n  /**\n   * {@inheritdoc Converter.convertOptional}\n   */\n  public convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined> {\n    const result = this._converter(from, this, this._context(context));\n    if (result.isFailure()) {\n      onError = onError ?? 'ignoreErrors';\n      return from === undefined || onError === 'ignoreErrors' ? succeed(undefined) : result;\n    }\n    return result;\n  }\n\n  /**\n   * {@inheritdoc Converter.optional}\n   */\n  public optional(onError?: OnError): Converter<T | undefined, TC> {\n    return new BaseConverter((from: unknown, __self: Converter<T | undefined, TC>, context?: TC) => {\n      onError = onError ?? 'failOnError';\n      return this.convertOptional(from, this._context(context), onError);\n    })._with(this._traits({ isOptional: true }));\n  }\n\n  /**\n   * {@inheritdoc Converter.map}\n   */\n  public map<T2>(mapper: (from: T) => Result<T2>): Converter<T2, TC> {\n    return new BaseConverter<T2, TC>((from: unknown, __self: Converter<T2, TC>, context?: TC) => {\n      const innerResult = this._converter(from, this, this._context(context));\n      if (innerResult.isSuccess()) {\n        return mapper(innerResult.value);\n      }\n      return fail(innerResult.message);\n    })._with(this._traits());\n  }\n\n  /**\n   * {@inheritdoc Converter.mapConvert}\n   */\n  public mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC> {\n    return new BaseConverter<T2, TC>((from: unknown, __self: Converter<T2, TC>, context?: TC) => {\n      const innerResult = this._converter(from, this, this._context(context));\n      if (innerResult.isSuccess()) {\n        return mapConverter.convert(innerResult.value);\n      }\n      return fail(innerResult.message);\n      // eslint-disable-next-line no-return-assign\n    })._with(this._traits());\n  }\n\n  /**\n   * {@inheritdoc Converter.mapItems}\n   */\n  public mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC> {\n    return new BaseConverter<TI[], TC>((from: unknown, __self: Converter<TI[], TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((items) => {\n        if (Array.isArray(items)) {\n          return mapResults(items.map((i) => mapper(i)));\n        }\n        return fail('Cannot map items - not an array');\n      });\n    });\n  }\n\n  /**\n   * {@inheritdoc Converter.mapConvertItems}\n   */\n  public mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC> {\n    return new BaseConverter<TI[], TC>((from: unknown, __self: Converter<TI[], TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((items) => {\n        if (Array.isArray(items)) {\n          return mapResults(items.map((i) => mapConverter.convert(i)));\n        }\n        return fail('Cannot map items - not an array');\n      });\n    });\n  }\n\n  /**\n   * {@inheritdoc Converter.withAction}\n   */\n  public withAction<TI>(action: (result: Result<T>) => Result<TI>): Converter<TI, TC> {\n    return new BaseConverter<TI, TC>((from: unknown, __self: Converter<TI, TC>, context?: TC) => {\n      return action(this._converter(from, this, this._context(context)));\n    })._with(this._traits());\n  }\n\n  /**\n   * {@inheritdoc Converter.withTypeGuard}\n   */\n  public withTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI, TC> {\n    return new BaseConverter<TI, TC>((from: unknown, __self: Converter<TI, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((inner) => {\n        message = message ?? 'invalid type';\n        return guard(inner) ? succeed(inner) : fail(`${message}: ${JSON.stringify(from)}`);\n      });\n    })._with(this._traits());\n  }\n\n  /**\n   * {@inheritdoc Converter.withItemTypeGuard}\n   */\n  public withItemTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI[], TC> {\n    return new BaseConverter<TI[], TC>((from: unknown, __self: Converter<TI[], TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((items) => {\n        if (Array.isArray(items)) {\n          return mapResults(\n            items.map((i) => {\n              message = message ?? 'invalid type';\n              return guard(i) ? succeed(i) : fail(`${message}: ${JSON.stringify(from)}`);\n            })\n          );\n        }\n        return fail('Cannot guard item type - not an array');\n      });\n    })._with(this._traits());\n  }\n\n  /**\n   * {@inheritdoc Converter.withConstraint}\n   */\n  public withConstraint(\n    constraint: (val: T) => boolean | Result<T>,\n    options?: ConstraintOptions\n  ): Converter<T, TC> {\n    return new BaseConverter<T, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      const result = this._converter(from, this, this._context(context));\n      if (result.isSuccess()) {\n        const constraintResult = constraint(result.value);\n        if (typeof constraintResult === 'boolean') {\n          return constraintResult\n            ? result\n            : fail(\n                `\"${JSON.stringify(result.value)}\": ${options?.description ?? 'does not meet constraint'}`\n              );\n        }\n        return constraintResult;\n      }\n      return result;\n    })._with(this._traits());\n  }\n\n  /**\n   * {@inheritdoc Converter.withBrand}\n   */\n  public withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC> {\n    if (this._brand) {\n      throw new Error(`Cannot replace existing brand \"${this._brand}\" with \"${brand}\".`);\n    }\n\n    return new BaseConverter<Brand<T, B>, TC>((from: unknown, __self: Converter<T, TC>, context?: TC) => {\n      return this._converter(from, this, this._context(context)).onSuccess((v) => {\n        return succeed(v as Brand<T, B>);\n      });\n    })._with(this._traits({ brand }));\n  }\n\n  /**\n   * {@inheritdoc Converter.withDefault}\n   */\n  public withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC> {\n    return new GenericDefaultingConverter<T, TD, TC>(this, defaultValue);\n  }\n\n  /**\n   * @internal\n   */\n  protected _context(supplied?: TC): TC | undefined {\n    return supplied ?? this._defaultContext;\n  }\n\n  /**\n   * @internal\n   */\n  protected _traits(traits?: Partial<ConverterTraits>): ConverterTraits {\n    return {\n      isOptional: this.isOptional,\n      brand: this.brand,\n      ...(traits ?? {})\n    };\n  }\n\n  /**\n   * @internal\n   */\n  protected _with(traits: Partial<ConverterTraits>): this {\n    this._isOptional = traits.isOptional === true;\n    this._brand = traits.brand;\n    return this;\n  }\n}\n"]}

package/lib/packlets/conversion/converter.d.ts

@@ -1,5 +1,9 @@
-import { Brand, Result } from '../base';
-type OnError = 'failOnError' | 'ignoreErrors';
+import { Brand, Result, Success } from '../base';
+/**
+ * Action to take on conversion failures.
+ * @public
+ */
+export type OnError = 'failOnError' | 'ignoreErrors';
 /**
  * Converter traits.
  * @public
@@ -35,7 +39,8 @@ export interface Converter<T, TC = undefined> extends ConverterTraits {
      */
     readonly brand?: string;
     /**
-     * Converts from `unknown` to `<T>`.
+     * Converts from `unknown` to `<T>`.  For objects and arrays, is guaranteed
+     * to return a new entity, with any unrecognized properties removed.
      * @param from - The `unknown` to be converted
      * @param context - An optional conversion context of type `<TC>` to be used in
      * the conversion.
@@ -117,6 +122,13 @@ export interface Converter<T, TC = undefined> extends ConverterTraits {
      * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
+    /**
+     * Creates a {@link Converter | Converter} which applies a supplied action after
+     * conversion.  The supplied action is always called regardless of success or failure
+     * of the base conversion and is allowed to mutate the return type.
+     * @param action - The action to be applied.
+     */
+    withAction<T2>(action: (result: Result<T>) => Result<T2>): Converter<T2, TC>;
     /**
      * Creates a {@link Converter} which applies a supplied type guard to the conversion
      * result.
@@ -156,114 +168,25 @@ export interface Converter<T, TC = undefined> extends ConverterTraits {
      * @returns A {@link Converter} returning `Brand<T, B>`.
      */
     withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
+    /**
+     * Returns a Converter which always succeeds with a default value rather than failing.
+     */
+    withDefault<TD = T>(dflt: TD): DefaultingConverter<T, TD, TC>;
 }
 /**
- * internal
- */
-type InnerInferredType<TCONV> = TCONV extends Converter<infer TTO> ? TTO extends Array<infer TTOELEM> ? InnerInferredType<TTOELEM>[] : TTO : TCONV extends Array<infer TELEM> ? InnerInferredType<TELEM>[] : TCONV;
-/**
- * Infers the type that will be returned by an instantiated converter.  Works
- * for complex as well as simple types.
- * @example `Infer<typeof Converters.mapOf(Converters.stringArray)>` is `Map<string, string[]>`
- * @beta
- */
-export type Infer<TCONV> = TCONV extends Converter<infer TTO> ? InnerInferredType<TTO> : never;
-/**
- * Deprecated name for Infer<T> retained for compatibility
- * @deprecated use @see Infer instead
- * @internal
- */
-export type ConvertedToType<TCONV> = Infer<TCONV>;
-/**
- * Base templated wrapper to simplify creation of new {@link Converter}s.
  * @public
  */
-export declare class BaseConverter<T, TC = undefined> implements Converter<T, TC> {
-    /**
-     * @internal
-     */
-    protected readonly _defaultContext?: TC;
-    /**
-     * @internal
-     */
-    protected _isOptional: boolean;
-    /**
-     * @internal
-     */
-    protected _brand?: string;
-    private readonly _converter;
-    /**
-     * Constructs a new {@link Converter} which uses the supplied function to perform the conversion.
-     * @param converter - The conversion function to be applied.
-     * @param defaultContext - Optional conversion context to be used by default.
-     * @param traits - Optional {@link Conversion.ConverterTraits | traits} to be assigned to the resulting
-     * converter.
-     */
-    constructor(converter: (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>, defaultContext?: TC, traits?: ConverterTraits);
-    /**
-     * {@inheritdoc Converter.isOptional}
-     */
-    get isOptional(): boolean;
-    /**
-     * {@inheritdoc Converter.brand}
-     */
-    get brand(): string | undefined;
-    /**
-     * {@inheritdoc Converter.convert}
-     */
-    convert(from: unknown, context?: TC): Result<T>;
-    /**
-     * {@inheritdoc Converter.convertOptional}
-     */
-    convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
-    /**
-     * {@inheritdoc Converter.optional}
-     */
-    optional(onError?: OnError): Converter<T | undefined, TC>;
-    /**
-     * {@inheritdoc Converter.map}
-     */
-    map<T2>(mapper: (from: T) => Result<T2>): Converter<T2, TC>;
-    /**
-     * {@inheritdoc Converter.mapConvert}
-     */
-    mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
-    /**
-     * {@inheritdoc Converter.mapItems}
-     */
-    mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC>;
-    /**
-     * {@inheritdoc Converter.mapConvertItems}
-     */
-    mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
-    /**
-     * {@inheritdoc Converter.withTypeGuard}
-     */
-    withTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI, TC>;
-    /**
-     * {@inheritdoc Converter.withItemTypeGuard}
-     */
-    withItemTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI[], TC>;
-    /**
-     * {@inheritdoc Converter.withConstraint}
-     */
-    withConstraint(constraint: (val: T) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
-    /**
-     * {@inheritdoc Converter.withBrand}
-     */
-    withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
-    /**
-     * @internal
-     */
-    protected _context(supplied?: TC): TC | undefined;
+export interface DefaultingConverter<T, TD = T, TC = undefined> extends Converter<T | TD, TC> {
     /**
-     * @internal
+     * Default value to use if the conversion fails.
      */
-    protected _traits(traits?: Partial<ConverterTraits>): ConverterTraits;
+    readonly defaultValue: TD;
     /**
-     * @internal
+     * Convert the supplied `unknown` to `Success<T>` or to the `Success` with the default value
+     * if conversion is not possible.
+     * @param from - the value to be converted.
+     * @param ctx - optional context for the conversion.
      */
-    protected _with(traits: Partial<ConverterTraits>): this;
+    convert(from: unknown, ctx?: TC): Success<T | TD>;
 }
-export {};
 //# sourceMappingURL=converter.d.ts.map

package/lib/packlets/conversion/converter.d.ts.map

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