@fgv/ts-utils 1.9.4 → 2.0.1-alpha.0

package/lib/packlets/base/utils.js

@@ -0,0 +1,200 @@
+"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.optionalMapToPossiblyEmptyRecord = exports.optionalMapToRecord = exports.mapToRecord = exports.optionalRecordToPossiblyEmptyMap = exports.optionalRecordToMap = exports.recordToMap = exports.getTypeOfProperty = exports.getValueOfPropertyOrDefault = exports.omit = exports.pick = exports.isKeyOf = void 0;
+const result_1 = require("./result");
+/**
+ * Helper type-guard function to report whether a specified key is present in
+ * a supplied object.
+ * @param key - The key to be tested.
+ * @param item - The object to be tested.
+ * @returns Returns `true` if the key is present, `false` otherwise.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+function isKeyOf(key, item) {
+    return item.hasOwnProperty(key);
+}
+exports.isKeyOf = isKeyOf;
+/**
+ * Simple implicit pick function, which picks a set of properties from a supplied
+ * object.  Ignores picked properties that do not exist regardless of type signature.
+ * @param from - The object from which keys are to be picked.
+ * @param include - The keys of the properties to be picked from `from`.
+ * @returns A new object containing the requested properties from `from`, where present.
+ * @public
+ */
+function pick(from, include) {
+    const rtrn = {};
+    for (const key of include) {
+        if (key in from) {
+            rtrn[key] = from[key];
+        }
+    }
+    return rtrn;
+}
+exports.pick = pick;
+/**
+ * Simple implicit omit function, which picks all of the properties from a supplied
+ * object except those specified for exclusion.
+ * @param from - The object from which keys are to be picked.
+ * @param exclude - The keys of the properties to be excluded from the returned object.
+ * @returns A new object containing all of the properties from `from` that were not
+ * explicitly excluded.
+ * @public
+ */
+function omit(from, exclude) {
+    const rtrn = {};
+    for (const entry of Object.entries(from).filter((e) => !exclude.includes(e[0]))) {
+        rtrn[entry[0]] = entry[1];
+    }
+    return rtrn;
+}
+exports.omit = omit;
+/**
+ * Gets the value of a property specified by key from an arbitrary object,
+ * or a default value if the property does not exist.
+ * @param key - The key specifying the property to be retrieved.
+ * @param item - The object from which the property is to be retrieved.
+ * @param defaultValue - An optional default value to be returned if the property
+ * is not present (default `undefined`).
+ * @returns The value of the requested property, or the default value if the
+ * requested property does not exist.
+ * @public
+ */
+function getValueOfPropertyOrDefault(key, item, defaultValue) {
+    return isKeyOf(key, item) ? item[key] : defaultValue;
+}
+exports.getValueOfPropertyOrDefault = getValueOfPropertyOrDefault;
+/**
+ * Gets the type of a property specified by key from an arbitrary object.
+ * @param key - The key specifying the property to be tested.
+ * @param item - The object from which the property is to be tested.
+ * @returns The type of the requested property, or `undefined` if the
+ * property does not exist.
+ * @example
+ * Returns `'undefined'` (a string) if the property exists but has the value
+ * undefined but `undefined` (the literal) if the property does not exist.
+ * @public
+ */
+function getTypeOfProperty(key, item) {
+    return isKeyOf(key, item) ? typeof item[key] : undefined;
+}
+exports.getTypeOfProperty = getTypeOfProperty;
+/**
+ * Applies a factory method to convert a `Record<TK, TS>` into a `Map<TK, TD>`.
+ * @param src - The `Record` to be converted.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting map on success, or {@link Failure} with a
+ * message if an error occurs.
+ * @public
+ */
+function recordToMap(src, factory) {
+    const map = new Map();
+    for (const key in src) {
+        if (src[key] !== undefined) {
+            const itemResult = factory(key, src[key]);
+            if (itemResult.isSuccess()) {
+                map.set(key, itemResult.value);
+            }
+            else {
+                return (0, result_1.fail)(`${key}: ${itemResult.message}`);
+            }
+        }
+    }
+    return (0, result_1.succeed)(map);
+}
+exports.recordToMap = recordToMap;
+/**
+ * Applies a factory method to convert an optional `Record<TK, TS>` into a `Map<TK, TD>`, or `undefined`.
+ * @param src - The `Record` to be converted, or undefined.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting map if conversion succeeds, or {@link Success} with `undefined`
+ * if `src` is `undefined`. Returns {@link Failure} with a message if an error occurs.
+ * @public
+ */
+function optionalRecordToMap(src, factory) {
+    return src === undefined ? (0, result_1.succeed)(undefined) : recordToMap(src, factory);
+}
+exports.optionalRecordToMap = optionalRecordToMap;
+/**
+ * Applies a factory method to convert an optional `Record<TK, TS>` into a `Map<TK, TD>`
+ * @param src - The `Record` to be converted, or `undefined`.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting map (empty if `src` is `undefined`) if conversion succeeds.
+ * Returns {@link Failure} with a message if an error occurs.
+ * @public
+ */
+function optionalRecordToPossiblyEmptyMap(src, factory) {
+    return src === undefined ? (0, result_1.succeed)(new Map()) : recordToMap(src, factory);
+}
+exports.optionalRecordToPossiblyEmptyMap = optionalRecordToPossiblyEmptyMap;
+/**
+ * Applies a factory method to convert a `Map<TK, TS>` into a `Record<TK, TD>`.
+ * @param src - The `Map` object to be converted.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting `Record<TK, TD>` if conversion succeeds, or
+ * {@link Failure} with an error message if an error occurs.
+ * @public
+ */
+function mapToRecord(src, factory) {
+    const record = {};
+    for (const kvp of src) {
+        if (kvp[1] !== undefined) {
+            const itemResult = factory(kvp[0], kvp[1]);
+            if (itemResult.isSuccess()) {
+                record[kvp[0]] = itemResult.value;
+            }
+            else {
+                return (0, result_1.fail)(`${kvp[0]}: ${itemResult.message}`);
+            }
+        }
+    }
+    return (0, result_1.succeed)(record);
+}
+exports.mapToRecord = mapToRecord;
+/**
+ * Applies a factory method to convert an optional `Map<string, TS>` into a `Record<string, TD>` or `undefined`.
+ * @param src - The `Map` object to be converted, or `undefined`.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting record if conversion succeeds, or {@link Success} with `undefined` if
+ * `src` is `undefined`. Returns {@link Failure} with a message if an error occurs.
+ * @public
+ */
+function optionalMapToRecord(src, factory) {
+    return src === undefined ? (0, result_1.succeed)(undefined) : mapToRecord(src, factory);
+}
+exports.optionalMapToRecord = optionalMapToRecord;
+/**
+ * Applies a factory method to convert an optional `Map<string, TS>` into a `Record<string, TD>`
+ * @param src - The `Map` object to be converted, or `undefined`.
+ * @param factory - The factory method used to convert elements.
+ * @returns {@link Success} with the resulting record (empty if `src` is `undefined`) if conversion succeeds.
+ * Returns {@link Failure} with a message if an error occurs.
+ * @public
+ */
+function optionalMapToPossiblyEmptyRecord(src, factory) {
+    return src === undefined ? (0, result_1.succeed)({}) : mapToRecord(src, factory);
+}
+exports.optionalMapToPossiblyEmptyRecord = optionalMapToPossiblyEmptyRecord;
+//# sourceMappingURL=utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/packlets/base/utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\r\n * Copyright (c) 2020 Erik Fortune\r\n *\r\n * Permission is hereby granted, free of charge, to any person obtaining a copy\r\n * of this software and associated documentation files (the \"Software\"), to deal\r\n * in the Software without restriction, including without limitation the rights\r\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n * copies of the Software, and to permit persons to whom the Software is\r\n * furnished to do so, subject to the following conditions:\r\n *\r\n * The above copyright notice and this permission notice shall be included in all\r\n * copies or substantial portions of the Software.\r\n *\r\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n * SOFTWARE.\r\n */\r\n\r\nimport { Result, fail, succeed } from './result';\r\n\r\n/**\r\n * Helper type-guard function to report whether a specified key is present in\r\n * a supplied object.\r\n * @param key - The key to be tested.\r\n * @param item - The object to be tested.\r\n * @returns Returns `true` if the key is present, `false` otherwise.\r\n * @public\r\n */\r\n// eslint-disable-next-line @typescript-eslint/ban-types\r\nexport function isKeyOf<T extends object>(key: string | number | symbol, item: T): key is keyof T {\r\n  return item.hasOwnProperty(key);\r\n}\r\n\r\n/**\r\n * Simple implicit pick function, which picks a set of properties from a supplied\r\n * object.  Ignores picked properties that do not exist regardless of type signature.\r\n * @param from - The object from which keys are to be picked.\r\n * @param include - The keys of the properties to be picked from `from`.\r\n * @returns A new object containing the requested properties from `from`, where present.\r\n * @public\r\n */\r\nexport function pick<T extends object, K extends keyof T>(from: T, include: K[]): Pick<T, K> {\r\n  const rtrn: Partial<Pick<T, K>> = {};\r\n  for (const key of include) {\r\n    if (key in from) {\r\n      rtrn[key] = from[key];\r\n    }\r\n  }\r\n  return rtrn as Pick<T, K>;\r\n}\r\n\r\n/**\r\n * Simple implicit omit function, which picks all of the properties from a supplied\r\n * object except those specified for exclusion.\r\n * @param from - The object from which keys are to be picked.\r\n * @param exclude - The keys of the properties to be excluded from the returned object.\r\n * @returns A new object containing all of the properties from `from` that were not\r\n * explicitly excluded.\r\n * @public\r\n */\r\nexport function omit<T extends object, K extends keyof T>(from: T, exclude: K[]): Omit<T, K> {\r\n  const rtrn: Partial<Omit<T, K>> = {};\r\n  for (const entry of Object.entries(from).filter((e) => !exclude.includes(e[0] as keyof T as K))) {\r\n    rtrn[entry[0] as unknown as keyof Omit<T, K>] = entry[1];\r\n  }\r\n\r\n  return rtrn as Omit<T, K>;\r\n}\r\n\r\n/**\r\n * Gets the value of a property specified by key from an arbitrary object,\r\n * or a default value if the property does not exist.\r\n * @param key - The key specifying the property to be retrieved.\r\n * @param item - The object from which the property is to be retrieved.\r\n * @param defaultValue - An optional default value to be returned if the property\r\n * is not present (default `undefined`).\r\n * @returns The value of the requested property, or the default value if the\r\n * requested property does not exist.\r\n * @public\r\n */\r\nexport function getValueOfPropertyOrDefault<T extends object>(\r\n  key: string | number | symbol,\r\n  item: T,\r\n  defaultValue?: unknown\r\n): unknown | undefined {\r\n  return isKeyOf(key, item) ? item[key] : defaultValue;\r\n}\r\n\r\n/**\r\n * Gets the type of a property specified by key from an arbitrary object.\r\n * @param key - The key specifying the property to be tested.\r\n * @param item - The object from which the property is to be tested.\r\n * @returns The type of the requested property, or `undefined` if the\r\n * property does not exist.\r\n * @example\r\n * Returns `'undefined'` (a string) if the property exists but has the value\r\n * undefined but `undefined` (the literal) if the property does not exist.\r\n * @public\r\n */\r\nexport function getTypeOfProperty<T extends object>(\r\n  key: string | number | symbol,\r\n  item: T\r\n):\r\n  | 'string'\r\n  | 'number'\r\n  | 'bigint'\r\n  | 'boolean'\r\n  | 'symbol'\r\n  | 'undefined'\r\n  | 'undefined'\r\n  | 'object'\r\n  | 'function'\r\n  | undefined {\r\n  return isKeyOf(key, item) ? typeof item[key] : undefined;\r\n}\r\n\r\n/**\r\n * Type for factory methods which convert a key-value pair to a new unique value.\r\n * @public\r\n */\r\ntype KeyedThingFactory<TS, TD, TK extends string = string> = (key: TK, thing: TS) => Result<TD>;\r\n\r\n/**\r\n * Applies a factory method to convert a `Record<TK, TS>` into a `Map<TK, TD>`.\r\n * @param src - The `Record` to be converted.\r\n * @param factory - The factory method used to convert elements.\r\n * @returns {@link Success} with the resulting map on success, or {@link Failure} with a\r\n * message if an error occurs.\r\n * @public\r\n */\r\nexport function recordToMap<TS, TD, TK extends string = string>(\r\n  src: Record<TK, TS>,\r\n  factory: KeyedThingFactory<TS, TD, TK>\r\n): Result<Map<TK, TD>> {\r\n  const map = new Map<TK, TD>();\r\n  for (const key in src) {\r\n    if (src[key] !== undefined) {\r\n      const itemResult = factory(key, src[key]);\r\n      if (itemResult.isSuccess()) {\r\n        map.set(key, itemResult.value);\r\n      } else {\r\n        return fail(`${key}: ${itemResult.message}`);\r\n      }\r\n    }\r\n  }\r\n  return succeed(map);\r\n}\r\n\r\n/**\r\n * Applies a factory method to convert an optional `Record<TK, TS>` into a `Map<TK, TD>`, or `undefined`.\r\n * @param src - The `Record` to be converted, or undefined.\r\n * @param factory - The factory method used to convert elements.\r\n * @returns {@link Success} with the resulting map if conversion succeeds, or {@link Success} with `undefined`\r\n * if `src` is `undefined`. Returns {@link Failure} with a message if an error occurs.\r\n * @public\r\n */\r\nexport function optionalRecordToMap<TS, TD, TK extends string = string>(\r\n  src: Record<TK, TS> | undefined,\r\n  factory: KeyedThingFactory<TS, TD, TK>\r\n): Result<Map<TK, TD> | undefined> {\r\n  return src === undefined ? succeed(undefined) : recordToMap(src, factory);\r\n}\r\n\r\n/**\r\n * Applies a factory method to convert an optional `Record<TK, TS>` into a `Map<TK, TD>`\r\n * @param src - The `Record` to be converted, or `undefined`.\r\n * @param factory - The factory method used to convert elements.\r\n * @returns {@link Success} with the resulting map (empty if `src` is `undefined`) if conversion succeeds.\r\n * Returns {@link Failure} with a message if an error occurs.\r\n * @public\r\n */\r\nexport function optionalRecordToPossiblyEmptyMap<TS, TD, TK extends string = string>(\r\n  src: Record<TK, TS> | undefined,\r\n  factory: KeyedThingFactory<TS, TD, TK>\r\n): Result<Map<TK, TD>> {\r\n  return src === undefined ? succeed(new Map<TK, TD>()) : recordToMap(src, factory);\r\n}\r\n\r\n/**\r\n * Applies a factory method to convert a `Map<TK, TS>` into a `Record<TK, TD>`.\r\n * @param src - The `Map` object to be converted.\r\n * @param factory - The factory method used to convert elements.\r\n * @returns {@link Success} with the resulting `Record<TK, TD>` if conversion succeeds, or\r\n * {@link Failure} with an error message if an error occurs.\r\n * @public\r\n */\r\nexport function mapToRecord<TS, TD, TK extends string = string>(\r\n  src: Map<TK, TS>,\r\n  factory: KeyedThingFactory<TS, TD, TK>\r\n): Result<Record<TK, TD>> {\r\n  const record: Record<TK, TD> = {} as Record<TK, TD>;\r\n  for (const kvp of src) {\r\n    if (kvp[1] !== undefined) {\r\n      const itemResult = factory(kvp[0], kvp[1]);\r\n      if (itemResult.isSuccess()) {\r\n        record[kvp[0]] = itemResult.value;\r\n      } else {\r\n        return fail(`${kvp[0]}: ${itemResult.message}`);\r\n      }\r\n    }\r\n  }\r\n  return succeed(record);\r\n}\r\n\r\n/**\r\n * Applies a factory method to convert an optional `Map<string, TS>` into a `Record<string, TD>` or `undefined`.\r\n * @param src - The `Map` object to be converted, or `undefined`.\r\n * @param factory - The factory method used to convert elements.\r\n * @returns {@link Success} with the resulting record if conversion succeeds, or {@link Success} with `undefined` if\r\n * `src` is `undefined`. Returns {@link Failure} with a message if an error occurs.\r\n * @public\r\n */\r\nexport function optionalMapToRecord<TS, TD, TK extends string = string>(\r\n  src: Map<TK, TS> | undefined,\r\n  factory: KeyedThingFactory<TS, TD, TK>\r\n): Result<Record<TK, TD> | undefined> {\r\n  return src === undefined ? succeed(undefined) : mapToRecord(src, factory);\r\n}\r\n\r\n/**\r\n * Applies a factory method to convert an optional `Map<string, TS>` into a `Record<string, TD>`\r\n * @param src - The `Map` object to be converted, or `undefined`.\r\n * @param factory - The factory method used to convert elements.\r\n * @returns {@link Success} with the resulting record (empty if `src` is `undefined`) if conversion succeeds.\r\n * Returns {@link Failure} with a message if an error occurs.\r\n * @public\r\n */\r\nexport function optionalMapToPossiblyEmptyRecord<TS, TD, TK extends string = string>(\r\n  src: Map<TK, TS> | undefined,\r\n  factory: KeyedThingFactory<TS, TD, TK>\r\n): Result<Record<TK, TD>> {\r\n  return src === undefined ? succeed({} as Record<TK, TD>) : mapToRecord(src, factory);\r\n}\r\n"]}

package/{converter.d.ts → lib/packlets/conversion/converter.d.ts}

@@ -1,5 +1,4 @@
-import { Result } from './result';
-import { Brand } from './brand';
+import { Brand, Result } from '../base';
 type OnError = 'failOnError' | 'ignoreErrors';
 /**
  * Converter traits.
@@ -36,13 +35,13 @@ export interface Converter<T, TC = undefined> extends ConverterTraits {
      */
     readonly brand?: string;
     /**
-    * Converts from `unknown` to `<T>`.
-    * @param from - The `unknown` to be converted
-    * @param context - An optional conversion context of type `<TC>` to be used in
-    * the conversion.
-    * @returns A {@link Result} with a {@link Success} and a value on success or an
-    * {@link Failure} with a a message on failure.
-    */
+     * Converts from `unknown` to `<T>`.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
+     */
     convert(from: unknown, context?: TC): Result<T>;
     /**
      * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
@@ -146,7 +145,7 @@ export interface Converter<T, TC = undefined> extends ConverterTraits {
      * {@link Failure | Failure<T>}.
      *
      * @param constraint - Constraint evaluation function.
-     * @param options - {@link ConstraintOptions | Options} for constraint evaluation.
+     * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.
      * @returns A new {@link Converter} returning `<T>`.
      */
     withConstraint(constraint: (val: T) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
@@ -161,7 +160,7 @@ export interface Converter<T, TC = undefined> extends ConverterTraits {
 /**
  * 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);
+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.
@@ -197,7 +196,7 @@ export declare class BaseConverter<T, TC = undefined> implements Converter<T, TC
      * 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 ConverterTraits | traits} to be assigned to the resulting
+     * @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);

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

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

package/lib/packlets/conversion/converter.js

@@ -0,0 +1,218 @@
+"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");
+/**
+ * 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.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)}`);
+            });
+        });
+    }
+    /**
+     * {@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');
+            });
+        });
+    }
+    /**
+     * {@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 }));
+    }
+    /**
+     * @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=converter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"converter.js","sourceRoot":"","sources":["../../../src/packlets/conversion/converter.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kCAAmE;AA6MnE;;;GAGG;AACH,MAAa,aAAa;IAgBxB;;;;;;OAMG;IACH,YACE,SAA6E,EAC7E,cAAmB,EACnB,MAAwB;QArB1B;;WAEG;QACO,gBAAW,GAAY,KAAK,CAAC;QAoBrC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,CAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,UAAU,MAAK,IAAI,CAAC;QAC/C,IAAI,CAAC,MAAM,GAAG,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAW,UAAU;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACI,OAAO,CAAC,IAAa,EAAE,OAAY;QACxC,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,IAAI,CAAC,eAAe,CAAC,CAAC;IACtE,CAAC;IAED;;OAEG;IACI,eAAe,CAAC,IAAa,EAAE,OAAY,EAAE,OAAiB;QACnE,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QACnE,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE;YACtB,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,cAAc,CAAC;YACpC,OAAO,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,cAAc,CAAC,CAAC,CAAC,IAAA,cAAO,EAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;SACvF;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACI,QAAQ,CAAC,OAAiB;QAC/B,OAAO,IAAI,aAAa,CAAC,CAAC,IAAa,EAAE,MAAoC,EAAE,OAAY,EAAE,EAAE;YAC7F,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,aAAa,CAAC;YACnC,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACI,GAAG,CAAK,MAA+B;QAC5C,OAAO,IAAI,aAAa,CAAS,CAAC,IAAa,EAAE,MAAyB,EAAE,OAAY,EAAE,EAAE;YAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACxE,IAAI,WAAW,CAAC,SAAS,EAAE,EAAE;gBAC3B,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;aAClC;YACD,OAAO,IAAA,WAAI,EAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACI,UAAU,CAAK,YAA2B;QAC/C,OAAO,IAAI,aAAa,CAAS,CAAC,IAAa,EAAE,MAAyB,EAAE,OAAY,EAAE,EAAE;YAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACxE,IAAI,WAAW,CAAC,SAAS,EAAE,EAAE;gBAC3B,OAAO,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;aAChD;YACD,OAAO,IAAA,WAAI,EAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YACjC,4CAA4C;QAC9C,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACI,QAAQ,CAAK,MAAqC;QACvD,OAAO,IAAI,aAAa,CAAW,CAAC,IAAa,EAAE,MAA2B,EAAE,OAAY,EAAE,EAAE;YAC9F,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC7E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;oBACxB,OAAO,IAAA,iBAAU,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;iBAChD;gBACD,OAAO,IAAA,WAAI,EAAC,iCAAiC,CAAC,CAAC;YACjD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACI,eAAe,CAAK,YAAoC;QAC7D,OAAO,IAAI,aAAa,CAAW,CAAC,IAAa,EAAE,MAA2B,EAAE,OAAY,EAAE,EAAE;YAC9F,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC7E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;oBACxB,OAAO,IAAA,iBAAU,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;iBAC9D;gBACD,OAAO,IAAA,WAAI,EAAC,iCAAiC,CAAC,CAAC;YACjD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACI,aAAa,CAAK,KAAoC,EAAE,OAAgB;QAC7E,OAAO,IAAI,aAAa,CAAS,CAAC,IAAa,EAAE,MAAyB,EAAE,OAAY,EAAE,EAAE;YAC1F,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC7E,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,cAAc,CAAC;gBACpC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAA,cAAO,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAA,WAAI,EAAC,GAAG,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACrF,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACI,iBAAiB,CAAK,KAAoC,EAAE,OAAgB;QACjF,OAAO,IAAI,aAAa,CAAW,CAAC,IAAa,EAAE,MAA2B,EAAE,OAAY,EAAE,EAAE;YAC9F,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC7E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;oBACxB,OAAO,IAAA,iBAAU,EACf,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;wBACd,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,cAAc,CAAC;wBACpC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAA,cAAO,EAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAA,WAAI,EAAC,GAAG,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBAC7E,CAAC,CAAC,CACH,CAAC;iBACH;gBACD,OAAO,IAAA,WAAI,EAAC,uCAAuC,CAAC,CAAC;YACvD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACI,cAAc,CACnB,UAA2C,EAC3C,OAA2B;QAE3B,OAAO,IAAI,aAAa,CAAQ,CAAC,IAAa,EAAE,MAAwB,EAAE,OAAY,EAAE,EAAE;;YACxF,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACnE,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE;gBACtB,MAAM,gBAAgB,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAClD,IAAI,OAAO,gBAAgB,KAAK,SAAS,EAAE;oBACzC,OAAO,gBAAgB;wBACrB,CAAC,CAAC,MAAM;wBACR,CAAC,CAAC,IAAA,WAAI,EACF,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,WAAW,mCAAI,0BAA0B,EAAE,CAC3F,CAAC;iBACP;gBACD,OAAO,gBAAgB,CAAC;aACzB;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACI,SAAS,CAAmB,KAAQ;QACzC,IAAI,IAAI,CAAC,MAAM,EAAE;YACf,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,CAAC,MAAM,WAAW,KAAK,IAAI,CAAC,CAAC;SACpF;QAED,OAAO,IAAI,aAAa,CAAkB,CAAC,IAAa,EAAE,MAAwB,EAAE,OAAY,EAAE,EAAE;YAClG,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;gBACzE,OAAO,IAAA,cAAO,EAAC,CAAgB,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACO,QAAQ,CAAC,QAAa;QAC9B,OAAO,QAAQ,aAAR,QAAQ,cAAR,QAAQ,GAAI,IAAI,CAAC,eAAe,CAAC;IAC1C,CAAC;IAED;;OAEG;IACO,OAAO,CAAC,MAAiC;QACjD,uBACE,UAAU,EAAE,IAAI,CAAC,UAAU,EAC3B,KAAK,EAAE,IAAI,CAAC,KAAK,IACd,CAAC,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,EAAE,CAAC,EACjB;IACJ,CAAC;IAED;;OAEG;IACO,KAAK,CAAC,MAAgC;QAC9C,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AApOD,sCAoOC","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';\n\ntype OnError = 'failOnError' | 'ignoreErrors';\n\n/**\n * Converter traits.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface ConverterTraits {\n  readonly isOptional: boolean;\n  readonly brand?: string;\n}\n\n/**\n * Options for {@link Converter.withConstraint}.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface ConstraintOptions {\n  /**\n   * Optional description for error messages when constraint\n   * function returns false.\n   */\n  readonly description: string;\n}\n\n/**\n * Generic converter to convert unknown to a templated type `<T>`, using\n * intrinsic rules or as modified by an optional conversion context\n * of optional templated type `<TC>` (default `undefined`).\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface Converter<T, TC = undefined> extends ConverterTraits {\n  /**\n   * Indicates whether this element is explicitly optional.\n   */\n  readonly isOptional: boolean;\n\n  /**\n   * Returns the brand for a branded type.\n   */\n  readonly brand?: string;\n\n  /**\n   * Converts from `unknown` to `<T>`.\n   * @param from - The `unknown` to be converted\n   * @param context - An optional conversion context of type `<TC>` to be used in\n   * the conversion.\n   * @returns A {@link Result} with a {@link Success} and a value on success or an\n   * {@link Failure} with a a message on failure.\n   */\n  convert(from: unknown, context?: TC): Result<T>;\n\n  /**\n   * Converts from `unknown` to `<T>` or `undefined`, as appropriate.\n   *\n   * @remarks\n   * If `onError` is `failOnError`, the converter succeeds for\n   * `undefined` or any convertible value, but reports an error\n   * if it encounters a value that cannot be converted.\n   *\n   * If `onError` is `ignoreErrors` (default) then values that\n   * cannot be converted result in a successful return of `undefined`.\n   * @param from - The `unknown` to be converted\n   * @param context - An optional conversion context of type `<TC>` to be used in\n   * the conversion.\n   * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).\n   * @returns A {@link Result} with a {@link Success} and a value on success or an\n   * {@link Failure} with a a message on failure.\n   */\n  convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;\n\n  /**\n   * Creates a {@link Converter} for an optional value.\n   *\n   * @remarks\n   * If `onError` is `failOnError`, the resulting converter will accept `undefined`\n   * or a convertible value, but report an error if it encounters a value that cannot be\n   * converted.\n   *\n   * If `onError` is `ignoreErrors` (default) then values that cannot be converted will\n   * result in a successful return of `undefined`.\n   *\n   * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).\n   * @returns A new {@link Converter} returning `<T|undefined>`.\n   * */\n  optional(onError?: OnError): Converter<T | undefined, TC>;\n\n  /**\n   * Creates a {@link Converter} which applies a (possibly) mapping conversion to\n   * the converted value of this {@link Converter}.\n   * @param mapper - A function which maps from the the result type `<T>` of this\n   * converter to a new result type `<T2>`.\n   * @returns A new {@link Converter} returning `<T2>`.\n   */\n  map<T2>(mapper: (from: T) => Result<T2>): Converter<T2, TC>;\n\n  /**\n   * Creates a {@link Converter} which applies an additional supplied\n   * converter to the result of this converter.\n   *\n   * @param mapConverter - The {@link Converter} to be applied to the\n   * converted result from this {@link Converter}.\n   * @returns A new {@link Converter} returning `<T2>`.\n   */\n  mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;\n\n  /**\n   * Creates a {@link Converter} which maps the individual items of a collection\n   * resulting from this {@link Converter} using the supplied map function.\n   *\n   * @remarks\n   * Fails if `from` is not an array.\n   *\n   * @param mapper - The map function to be applied to each element of the\n   * result of this {@link Converter}.\n   * @returns A new {@link Converter} returning `<TI[]>`.\n   */\n  mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC>;\n\n  /**\n   * Creates a {@link Converter} which maps the individual items of a collection\n   * resulting from this {@link Converter} using the supplied {@link Converter}.\n   *\n   * @remarks\n   * Fails if `from` is not an array.\n   *\n   * @param mapConverter - The {@link Converter} to be applied to each element of the\n   * result of this {@link Converter}.\n   * @returns A new {@link Converter} returning `<TI[]>`.\n   */\n  mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;\n\n  /**\n   * Creates a {@link Converter} which applies a supplied type guard to the conversion\n   * result.\n   * @param guard - The type guard function to apply.\n   * @param message - Optional message to be reported if the type guard fails.\n   * @returns A new {@link Converter} returning `<TI>`.\n   */\n  withTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI, TC>;\n\n  /**\n   * Creates a {@link Converter} which applies a supplied type guard to each member of\n   * the conversion result from this converter.\n   *\n   * @remarks\n   * Fails if the conversion result is not an array or if any member fails the\n   * type guard.\n   * @param guard - The type guard function to apply to each element.\n   * @param message - Optional message to be reported if the type guard fails.\n   * @returns A new {@link Converter} returning `<TI>`.\n   */\n  withItemTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string): Converter<TI[], TC>;\n\n  /**\n   * Creates a {@link Converter} which applies an optional constraint to the result\n   * of this conversion.  If this {@link Converter} (the base converter) succeeds, the new\n   * converter calls a supplied constraint evaluation function with the conversion, which\n   * fails the entire conversion if the constraint function returns either `false` or\n   * {@link Failure | Failure<T>}.\n   *\n   * @param constraint - Constraint evaluation function.\n   * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.\n   * @returns A new {@link Converter} returning `<T>`.\n   */\n  withConstraint(constraint: (val: T) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;\n\n  /**\n   * returns a converter which adds a brand to the type to prevent mismatched usage\n   * of simple types.\n   * @param brand - The brand to be applied to the result value.\n   * @returns A {@link Converter} returning `Brand<T, B>`.\n   */\n  withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;\n}\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.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    });\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    });\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   * @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"]}