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

package/lib/packlets/conversion/converters.js

@@ -0,0 +1,739 @@
+"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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rangeOf = exports.rangeTypeOf = exports.transformObject = exports.transform = exports.discriminatedObject = exports.strictObject = exports.object = exports.optionalField = exports.field = exports.optionalElement = exports.element = exports.validateWith = exports.mapOf = exports.recordOf = exports.numberArray = exports.stringArray = exports.extendedArrayOf = exports.arrayOf = exports.oneOf = exports.optionalBoolean = exports.optionalNumber = exports.isA = exports.validated = exports.isoDate = exports.delimitedString = exports.optionalString = exports.boolean = exports.number = exports.value = exports.literal = exports.mappedEnumeratedValue = exports.enumeratedValue = exports.templateString = exports.string = void 0;
+const base_1 = require("../base");
+const experimental_1 = require("../experimental");
+const converter_1 = require("./converter");
+const objectConverter_1 = require("./objectConverter");
+const stringConverter_1 = require("./stringConverter");
+const luxon_1 = require("luxon");
+const mustache_1 = __importDefault(require("mustache"));
+/**
+ * A converter to convert unknown to string. Values of type
+ * string succeed.  Anything else fails.
+ * @public
+ */
+exports.string = new stringConverter_1.StringConverter();
+/**
+ * Helper function to create a {@link Conversion.StringConverter | StringConverter} which converts
+ * `unknown` to `string`, applying template conversions supplied at construction time or at
+ * runtime as context.
+ * @remarks
+ * Template conversions are applied using `mustache` syntax.
+ * @param defaultContext - Optional default context to use for template values.
+ * @returns A new {@link Converter} returning `string`.
+ * @public
+ */
+function templateString(defaultContext) {
+    return new stringConverter_1.StringConverter(defaultContext, undefined, (from, __self, context) => {
+        if (typeof from !== 'string') {
+            return (0, base_1.fail)(`Not a string: ${JSON.stringify(from)}`);
+        }
+        return (0, base_1.captureResult)(() => mustache_1.default.render(from, context));
+    });
+}
+exports.templateString = templateString;
+/**
+ * Helper function to create a {@link Converter} which converts `unknown` to one of a set of supplied
+ * enumerated values. Anything else fails.
+ *
+ * @remarks
+ * Allowed enumerated values can also be supplied as context at conversion time.
+ * @param values - Array of allowed values.
+ * @returns A new {@link Converter} returning `<T>`.
+ * @public
+ */
+function enumeratedValue(values) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        const v = context !== null && context !== void 0 ? context : values;
+        const index = v.indexOf(from);
+        return index >= 0 ? (0, base_1.succeed)(v[index]) : (0, base_1.fail)(`Invalid enumerated value ${JSON.stringify(from)}`);
+    });
+}
+exports.enumeratedValue = enumeratedValue;
+/**
+ * Helper function to create a {@link Converter} which converts `unknown` to one of a set of supplied enumerated
+ * values, mapping any of multiple supplied values to the enumeration.
+ * @remarks
+ * Enables mapping of multiple input values to a consistent internal representation (so e.g. `'y'`, `'yes'`,
+ * `'true'`, `1` and `true` can all map to boolean `true`)
+ * @param map - An array of tuples describing the mapping. The first element of each tuple is the result
+ * value, the second is the set of values that map to the result.  Tuples are evaluated in the order
+ * supplied and are not checked for duplicates.
+ * @param message - An optional error message.
+ * @returns A {@link Converter} which applies the mapping and yields `<T>` on success.
+ * @public
+ */
+function mappedEnumeratedValue(map, message) {
+    return new converter_1.BaseConverter((from, __self, __context) => {
+        for (const item of map) {
+            if (item[1].includes(from)) {
+                return (0, base_1.succeed)(item[0]);
+            }
+        }
+        return (0, base_1.fail)(message
+            ? `${JSON.stringify(from)}: ${message}`
+            : `Cannot map '${JSON.stringify(from)}' to a supported value`);
+    });
+}
+exports.mappedEnumeratedValue = mappedEnumeratedValue;
+/**
+ * Helper function to create a {@link Converter} which converts `unknown` to some supplied literal value. Succeeds with
+ * the supplied value if an identity comparison succeeds, fails otherwise.
+ * @param value - The value to be compared.
+ * @returns A {@link Converter} which returns the supplied value on success.
+ * @public
+ */
+function literal(value) {
+    return new converter_1.BaseConverter((from, __self, __context) => {
+        return from === value
+            ? (0, base_1.succeed)(value)
+            : (0, base_1.fail)(`${JSON.stringify(from)}: does not match ${JSON.stringify(value)}`);
+    });
+}
+exports.literal = literal;
+/**
+ * Deprecated alias for @see literal
+ * @param value - The value to be compared.
+ * @deprecated Use {@link Converters.literal} instead.
+ * @internal
+ */
+// eslint-disable-next-line @rushstack/typedef-var
+exports.value = literal;
+/**
+ * A {@link Converter} which converts `unknown` to a `number`.
+ * @remarks
+ * Numbers and strings with a numeric format succeed. Anything else fails.
+ * @public
+ */
+exports.number = new converter_1.BaseConverter((from) => {
+    if (typeof from !== 'number') {
+        const num = typeof from === 'string' ? Number(from) : NaN;
+        return isNaN(num) ? (0, base_1.fail)(`Not a number: ${JSON.stringify(from)}`) : (0, base_1.succeed)(num);
+    }
+    return (0, base_1.succeed)(from);
+});
+/**
+ * A {@link Converter} which converts `unknown` to `boolean`.
+ * @remarks
+ * Boolean values or the case-insensitive strings `'true'` and `'false'` succeed.
+ * Anything else fails.
+ * @public
+ */
+exports.boolean = new converter_1.BaseConverter((from) => {
+    if (typeof from === 'boolean') {
+        return (0, base_1.succeed)(from);
+    }
+    else if (typeof from === 'string') {
+        switch (from.toLowerCase()) {
+            case 'true':
+                return (0, base_1.succeed)(true);
+            case 'false':
+                return (0, base_1.succeed)(false);
+        }
+    }
+    return (0, base_1.fail)(`Not a boolean: ${JSON.stringify(from)}`);
+});
+/**
+ * A {@link Converter} which converts an optional `string` value. Values of type
+ * `string` are returned.  Anything else returns {@link Success} with value `undefined`.
+ * @public
+ */
+exports.optionalString = exports.string.optional();
+/**
+ * Helper function to create a {@link Converter} which converts any `string` into an
+ * array of `string`, by separating at a supplied delimiter.
+ * @remarks
+ * Delimiter may also be supplied as context at conversion time.
+ * @param delimiter - The delimiter at which to split.
+ * @returns A new {@link Converter} returning `string[]`.
+ * @public
+ */
+function delimitedString(delimiter, options = 'filtered') {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        const result = exports.string.convert(from);
+        if (result.isSuccess()) {
+            let strings = result.value.split(context !== null && context !== void 0 ? context : delimiter);
+            if (options !== 'all') {
+                strings = strings.filter((s) => s.trim().length > 0);
+            }
+            return (0, base_1.succeed)(strings);
+        }
+        return (0, base_1.fail)(result.message);
+    });
+}
+exports.delimitedString = delimitedString;
+/**
+ * A {@link Converter} which converts an iso formatted string, a number or a `Date` object to
+ * a `Date` object.
+ * @public
+ */
+exports.isoDate = new converter_1.BaseConverter((from) => {
+    if (typeof from === 'string') {
+        const dt = luxon_1.DateTime.fromISO(from);
+        if (dt.isValid) {
+            return (0, base_1.succeed)(dt.toJSDate());
+        }
+        return (0, base_1.fail)(`Invalid date: ${dt.invalidExplanation}`);
+    }
+    else if (typeof from === 'number') {
+        return (0, base_1.succeed)(new Date(from));
+    }
+    else if (from instanceof Date) {
+        return (0, base_1.succeed)(from);
+    }
+    return (0, base_1.fail)(`Cannot convert ${JSON.stringify(from)} to Date`);
+});
+/**
+ * Helper function to create a {@link Converter} from any {@link Validation.Validator}
+ * @param validator - the validator to be wrapped
+ * @returns A {@link Converter} which uses the supplied validator.
+ * @public
+ */
+function validated(validator) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        return validator.validate(from, context);
+    });
+}
+exports.validated = validated;
+/**
+ * Helper function to create a {@link Converter} from a supplied type guard function.
+ * @param description - a description of the thing to be validated for use in error messages
+ * @param guard - a {@link Validation.TypeGuardWithContext} which performs the validation.
+ * @returns A new {@link Converter} which validates the values using the supplied type guard
+ * and returns them in place.
+ * @public
+ */
+function isA(description, guard) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        if (guard(from, context)) {
+            return (0, base_1.succeed)(from);
+        }
+        return (0, base_1.fail)(`invalid ${description} (${JSON.stringify(from)})`);
+    });
+}
+exports.isA = isA;
+/**
+ * A {@link Converter} which converts an optional `number` value.
+ * @remarks
+ * Values of type `number` or numeric strings are converted and returned.
+ * Anything else returns {@link Success} with value `undefined`.
+ * @public
+ */
+exports.optionalNumber = exports.number.optional();
+/**
+ * A {@link Converter} to convert an optional `boolean` value.
+ * @remarks
+ * Values of type `boolean` or strings that match (case-insensitive) `'true'`
+ * or `'false'` are converted and returned.  Anything else returns {@link Success}
+ * with value `undefined`.
+ * @public
+ */
+exports.optionalBoolean = exports.boolean.optional();
+/**
+ * A helper function to create a {@link Converter} for polymorphic values.  Returns a
+ * converter which Invokes the wrapped converters in sequence, returning the first successful
+ * result.  Returns an error if none of the supplied converters can convert the value.
+ * @remarks
+ * If `onError` is `ignoreErrors` (default), then errors from any of the
+ * converters are ignored provided that some converter succeeds.  If
+ * onError is `failOnError`, then an error from any converter fails the entire
+ * conversion.
+ *
+ * @param converters - An ordered list of {@link Converter | converters} to be considered.
+ * @param onError - Specifies treatment of unconvertible elements.
+ * @returns A new {@link Converter} which yields a value from the union of the types returned
+ * by the wrapped converters.
+ * @public
+ */
+function oneOf(converters, onError = 'ignoreErrors') {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        const errors = [];
+        for (const converter of converters) {
+            const result = converter.convert(from, context);
+            if (result.isSuccess() && result.value !== undefined) {
+                return result;
+            }
+            if (result.isFailure()) {
+                if (onError === 'failOnError') {
+                    return result;
+                }
+                errors.push(result.message);
+            }
+        }
+        return (0, base_1.fail)(`No matching converter for ${JSON.stringify(from)}: ${errors.join('\n')}`);
+    });
+}
+exports.oneOf = oneOf;
+/**
+ * A helper function to create a {@link Converter} which converts `unknown` to an array of `<T>`.
+ * @remarks
+ * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
+ * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
+ * @param converter - {@link Converter} used to convert each item in the array.
+ * @param ignoreErrors - Specifies treatment of unconvertible elements.
+ * @returns A {@link Converter} which returns an array of `<T>`.
+ * @public
+ */
+function arrayOf(converter, onError = 'failOnError') {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        if (!Array.isArray(from)) {
+            return (0, base_1.fail)(`Not an array: ${JSON.stringify(from)}`);
+        }
+        const successes = [];
+        const errors = [];
+        for (const item of from) {
+            const result = converter.convert(item, context);
+            if (result.isSuccess() && result.value !== undefined) {
+                successes.push(result.value);
+            }
+            else if (result.isFailure()) {
+                errors.push(result.message);
+            }
+        }
+        return errors.length === 0 || onError === 'ignoreErrors' ? (0, base_1.succeed)(successes) : (0, base_1.fail)(errors.join('\n'));
+    });
+}
+exports.arrayOf = arrayOf;
+/**
+ * A helper function to create a {@link Converter} which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
+ * @remarks
+ * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
+ * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
+ * @param converter - {@link Converter} used to convert each item in the array
+ * @param ignoreErrors - Specifies treatment of unconvertible elements
+ * @beta
+ */
+function extendedArrayOf(label, converter, onError = 'failOnError') {
+    return arrayOf(converter, onError).map((items) => {
+        return (0, base_1.captureResult)(() => new experimental_1.ExtendedArray(label, ...items));
+    });
+}
+exports.extendedArrayOf = extendedArrayOf;
+/**
+ * {@link Converter} to convert an `unknown` to an array of `string`.
+ * @remarks
+ * Returns {@link Success} with the the supplied value if it as an array
+ * of strings, returns {@link Failure} with an error message otherwise.
+ * @public
+ */
+exports.stringArray = arrayOf(exports.string);
+/**
+ * {@link Converter | Converter} to convert an `unknown` to an array of `number`.
+ * @remarks
+ * Returns {@link Success | Success} with the the supplied value if it as an array
+ * of numbers, returns {@link Failure | Failure} with an error message otherwise.
+ * @public
+ */
+exports.numberArray = arrayOf(exports.number);
+/**
+ * Concrete implementation of {@link Converters.(recordOf:1) | Converters.recordOf(Converter<T>)},
+ * {@link Converters.(recordOf:2) | Converters.recordOf(Converter<T>, 'fail' or 'ignore')}, and
+ * {@link Converters.(recordOf:3) | Converters.recordOf(Converter<T>, KeyedConverterOptions)}.
+ * @internal
+ */
+function recordOf(converter, option = 'fail') {
+    const options = typeof option === 'string' ? { onError: option } : Object.assign({ onError: 'fail' }, option);
+    return new converter_1.BaseConverter((from, __self, context) => {
+        var _a, _b;
+        if (typeof from !== 'object' || from === null || Array.isArray(from)) {
+            return (0, base_1.fail)(`Not a string-keyed object: ${JSON.stringify(from)}`);
+        }
+        const record = {};
+        const errors = [];
+        for (const key in from) {
+            if ((0, base_1.isKeyOf)(key, from)) {
+                const writeKeyResult = (_b = (_a = options.keyConverter) === null || _a === void 0 ? void 0 : _a.convert(key, context)) !== null && _b !== void 0 ? _b : (0, base_1.succeed)(key);
+                writeKeyResult
+                    .onSuccess((writeKey) => {
+                    return converter.convert(from[key], context).onSuccess((value) => {
+                        record[writeKey] = value;
+                        return (0, base_1.succeed)(true);
+                    });
+                })
+                    .onFailure((message) => {
+                    errors.push(message);
+                    return (0, base_1.fail)(message);
+                });
+            }
+        }
+        return errors.length === 0 || options.onError === 'ignore' ? (0, base_1.succeed)(record) : (0, base_1.fail)(errors.join('\n'));
+    });
+}
+exports.recordOf = recordOf;
+/**
+ * Concrete implementation of {@link Converters.(mapOf:1) | Converters.mapOf(Converter<T>)},
+ * {@link Converters.(mapOf:2) | Converters.mapOf(Converter<T>, 'fail' or 'ignore')}, and
+ * {@link Converters.(mapOf:3) | Converters.mapOf(Converter<T>, KeyedConverterOptions)}.
+ * @internal
+ */
+function mapOf(converter, option = 'fail') {
+    const options = typeof option === 'string' ? { onError: option } : Object.assign({ onError: 'fail' }, option);
+    return new converter_1.BaseConverter((from, __self, context) => {
+        var _a, _b;
+        if (typeof from !== 'object' || from === null || Array.isArray(from)) {
+            return (0, base_1.fail)(`Not a string-keyed object: ${JSON.stringify(from)}`);
+        }
+        const map = new Map();
+        const errors = [];
+        for (const key in from) {
+            if ((0, base_1.isKeyOf)(key, from)) {
+                const writeKeyResult = (_b = (_a = options.keyConverter) === null || _a === void 0 ? void 0 : _a.convert(key, context)) !== null && _b !== void 0 ? _b : (0, base_1.succeed)(key);
+                writeKeyResult
+                    .onSuccess((writeKey) => {
+                    return converter.convert(from[key], context).onSuccess((value) => {
+                        map.set(writeKey, value);
+                        return (0, base_1.succeed)(true);
+                    });
+                })
+                    .onFailure((message) => {
+                    errors.push(message);
+                    return (0, base_1.fail)(message);
+                });
+            }
+        }
+        return errors.length === 0 || options.onError === 'ignore' ? (0, base_1.succeed)(map) : (0, base_1.fail)(errors.join('\n'));
+    });
+}
+exports.mapOf = mapOf;
+/**
+ * Helper function to create  a {@link Converter} which validates that a supplied value is
+ * of a type validated by a supplied validator function and returns it.
+ * @remarks
+ * If `validator` succeeds, this {@link Converter} returns {@link Success} with the supplied
+ * value of `from` coerced to type `<T>`.  Returns a {@link Failure} with additional
+ * information otherwise.
+ * @param validator - A validator function to determine if the converted value is valid.
+ * @param description - A description of the validated type for use in error messages.
+ * @returns A new {@link Converter | Converter<T>} which applies the supplied validation.
+ * @public
+ */
+function validateWith(validator, description) {
+    return new converter_1.BaseConverter((from, __self, __context) => {
+        if (validator(from)) {
+            return (0, base_1.succeed)(from);
+        }
+        return (0, base_1.fail)(`${JSON.stringify(from)}: invalid ${description !== null && description !== void 0 ? description : 'value'}`);
+    });
+}
+exports.validateWith = validateWith;
+/**
+ * A helper function to create a {@link Converter} which extracts and converts an element from an array.
+ * @remarks
+ * The returned {@link Converter} returns {@link Success} with the converted value if the element exists
+ * in the supplied array and can be converted. Returns {@link Failure} with an error message otherwise.
+ * @param index - The index of the element to be extracted.
+ * @param converter - A {@link Converter} used to convert the extracted element.
+ * @returns A {@link Converter | Converter<T>} which extracts the specified element from an array.
+ * @public
+ */
+function element(index, converter) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        if (index < 0) {
+            return (0, base_1.fail)(`${index}: cannot convert for a negative element index`);
+        }
+        else if (!Array.isArray(from)) {
+            return (0, base_1.fail)('element converter: source is not an array');
+        }
+        else if (index >= from.length) {
+            return (0, base_1.fail)(`${index}: element converter index out of range (0..${from.length - 1})`);
+        }
+        return converter.convert(from[index], context);
+    });
+}
+exports.element = element;
+/**
+ * A helper function to create a {@link Converter} which extracts and converts an optional element from an array.
+ * @remarks
+ * The resulting {@link Converter} returns {@link Success} with the converted value if the element exists
+ * in the supplied array and can be converted. Returns {@link Success} with value `undefined` if the parameter
+ * is an array but the index is out of range. Returns {@link Failure} with a message if the supplied parameter
+ * is not an array, if the requested index is negative, or if the element cannot be converted.
+ * @param index - The index of the element to be extracted.
+ * @param converter - A {@link Converter} used to convert the extracted element.
+ * @returns A {@link Converter | Converter<T>} which extracts the specified element from an array.
+ * @public
+ */
+function optionalElement(index, converter) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        if (index < 0) {
+            return (0, base_1.fail)(`${index}: cannot convert for a negative element index`);
+        }
+        else if (!Array.isArray(from)) {
+            return (0, base_1.fail)('element converter: source is not an array');
+        }
+        else if (index >= from.length) {
+            return (0, base_1.succeed)(undefined);
+        }
+        return converter.convert(from[index], context);
+    });
+}
+exports.optionalElement = optionalElement;
+/**
+ * A helper function to create a {@link Converter} which extracts and convert a property specified
+ * by name from an object.
+ * @remarks
+ * The resulting {@link Converter} returns {@link Success} with the converted value of the corresponding
+ * object property if the field exists and can be converted. Returns {@link Failure} with an error message
+ * otherwise.
+ * @param name - The name of the field to be extracted.
+ * @param converter - {@link Converter} used to convert the extracted field.
+ * @public
+ */
+function field(name, converter) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        if (typeof from === 'object' && !Array.isArray(from) && from !== null) {
+            if ((0, base_1.isKeyOf)(name, from)) {
+                return converter.convert(from[name], context).onFailure((message) => {
+                    return (0, base_1.fail)(`Field ${name}: ${message}`);
+                });
+            }
+            return (0, base_1.fail)(`Field ${name} not found in: ${JSON.stringify(from)}`);
+        }
+        return (0, base_1.fail)(`Cannot convert field "${name}" from non-object ${JSON.stringify(from)}`);
+    });
+}
+exports.field = field;
+/**
+ * A helper function to create a {@link Converter} which extracts and convert a property specified
+ * by name from an object.
+ * @remarks
+ * The resulting {@link Converter} returns {@link Success} with the converted value of the corresponding
+ * object property if the field exists and can be converted. Returns {@link Success} with value `undefined`
+ * if the supplied parameter is an object but the named field is not present.  Returns {@link Failure} with
+ * an error message otherwise.
+ * @param name - The name of the field to be extracted.
+ * @param converter - {@link Converter} used to convert the extracted field.
+ * @public
+ */
+function optionalField(name, converter) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        if (typeof from === 'object' && !Array.isArray(from) && from !== null) {
+            if ((0, base_1.isKeyOf)(name, from)) {
+                const result = converter.convert(from[name], context).onFailure((message) => {
+                    return (0, base_1.fail)(`${name}: ${message}`);
+                });
+                // if conversion was successful or input was undefined we
+                // succeed with 'undefined', but we propagate actual
+                // failures.
+                if (result.isSuccess() || from[name] !== undefined) {
+                    return result;
+                }
+            }
+            return (0, base_1.succeed)(undefined);
+        }
+        return (0, base_1.fail)(`Cannot convert field "${name}" from non-object ${JSON.stringify(from)}`);
+    }, undefined, { isOptional: true });
+}
+exports.optionalField = optionalField;
+/**
+ * Concrete implementation of {@link Converters.(object:1) | Converters.object(fields, options)}
+ * and {@link Converters.(object:2) | Converters.objects(fields, optionalKeys)}.
+ * @internal
+ */
+function object(properties, options) {
+    return new objectConverter_1.ObjectConverter(properties, options);
+}
+exports.object = object;
+/**
+ * Concrete implementation for {@link Converters.(strictObject:1) | Converters.strictObject(fields, options)}
+ * and {@link Converters.strictObject | Converters.strictObject(fields, optional)}.
+ * @internal
+ */
+function strictObject(properties, opt) {
+    const options = opt && Array.isArray(opt) ? { strict: true, optionalFields: opt } : Object.assign(Object.assign({}, (opt !== null && opt !== void 0 ? opt : {})), { strict: true });
+    return new objectConverter_1.ObjectConverter(properties, options);
+}
+exports.strictObject = strictObject;
+/**
+ * Helper to create a {@link Converter} which converts a discriminated object without changing shape.
+ * @remarks
+ * Takes the name of the discriminator property and a
+ * {@link Converters.DiscriminatedObjectConverters | string-keyed Record of converters}. During conversion,
+ * the resulting {@link Converter} invokes the converter from `converters` that corresponds to the value of
+ * the discriminator property in the source object.
+ *
+ * If the source is not an object, the discriminator property is missing, or the discriminator has
+ * a value not present in the converters, conversion fails and returns {@link Failure} with more information.
+ * @param discriminatorProp - Name of the property used to discriminate types.
+ * @param converters - {@link Converters.DiscriminatedObjectConverters | String-keyed record of converters} to
+ * invoke, where each key corresponds to a value of the discriminator property.
+ * @returns A {@link Converter} which converts the corresponding discriminated object.
+ * @public
+ */
+function discriminatedObject(discriminatorProp, converters) {
+    return new converter_1.BaseConverter((from) => {
+        if (typeof from !== 'object' || Array.isArray(from) || from === null) {
+            return (0, base_1.fail)(`Not a discriminated object: "${JSON.stringify(from)}"`);
+        }
+        if (!(0, base_1.isKeyOf)(discriminatorProp, from) || !from[discriminatorProp]) {
+            return (0, base_1.fail)(`Discriminator property ${discriminatorProp} not present in "${JSON.stringify(from)}"`);
+        }
+        const discriminatorValue = from[discriminatorProp];
+        const converter = converters[discriminatorValue];
+        if (converter === undefined) {
+            return (0, base_1.fail)(`No converter for discriminator ${discriminatorProp}="${discriminatorValue}"`);
+        }
+        return converter.convert(from);
+    });
+}
+exports.discriminatedObject = discriminatedObject;
+/**
+ * Helper to create a {@link Converter} which converts a source object to a new object with a
+ * different shape.
+ *
+ * @remarks
+ * On successful conversion, the resulting {@link Converter} returns {@link Success} with a new
+ * object, which contains the converted values under the key names specified at initialization time.
+ * It returns {@link Failure} with an error message if any fields to be extracted do not exist
+ * or cannot be converted.
+ *
+ * Fields that succeed but convert to undefined are omitted from the result object but do not
+ * fail the conversion.
+ *
+ * @param properties - An object with key names that correspond to the target object and an
+ * appropriate {@link Conversion.FieldConverters | FieldConverter} which extracts and converts
+ * a single filed from the source object.
+ * @returns A {@link Converter} with the specified conversion behavior.
+ * @public
+ */
+function transform(properties) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        // eslint bug thinks key is used before defined
+        // eslint-disable-next-line no-use-before-define
+        const converted = {};
+        const errors = [];
+        for (const key in properties) {
+            if (properties[key]) {
+                const result = properties[key].convert(from, context);
+                if (result.isSuccess() && result.value !== undefined) {
+                    converted[key] = result.value;
+                }
+                else if (result.isFailure()) {
+                    errors.push(result.message);
+                }
+            }
+        }
+        return errors.length === 0 ? (0, base_1.succeed)(converted) : (0, base_1.fail)(errors.join('\n'));
+    });
+}
+exports.transform = transform;
+/**
+ * Helper to create a strongly-typed {@link Converter} which converts a source object to a
+ * new object with a different shape.
+ *
+ * @remarks
+ * On successful conversion, the resulting {@link Converter} returns {@link Success} with a new
+ * object, which contains the converted values under the key names specified at initialization time.
+ *
+ * It returns {@link Failure} with an error message if any fields to be extracted do not exist
+ * or cannot be converted.
+ *
+ * @param destinationFields - An object with key names that correspond to the target object and an
+ * appropriate {@link Converters.FieldTransformers | FieldTransformers} which specifies the name
+ * of the corresponding property in the source object, the converter used to convert the source
+ * property and any configuration to guide the conversion.
+ * @param options - Options which affect the transformation.
+ *
+ * @returns A {@link Converter} with the specified conversion behavior.
+ * @public
+ */
+function transformObject(destinationFields, options) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        // eslint bug thinks key is used before defined
+        // eslint-disable-next-line no-use-before-define
+        const converted = {};
+        const errors = [];
+        const used = new Set(options === null || options === void 0 ? void 0 : options.ignore);
+        if (typeof from === 'object' && !Array.isArray(from) && from !== null) {
+            for (const destinationKey in destinationFields) {
+                if (destinationFields[destinationKey]) {
+                    const srcKey = destinationFields[destinationKey].from;
+                    const converter = destinationFields[destinationKey].converter;
+                    if ((0, base_1.isKeyOf)(srcKey, from)) {
+                        const result = converter.convert(from[srcKey], context);
+                        if (result.isSuccess() && result.value !== undefined) {
+                            converted[destinationKey] = result.value;
+                        }
+                        else if (result.isFailure()) {
+                            errors.push(`${srcKey}->${destinationKey}: ${result.message}`);
+                        }
+                        used.add(srcKey);
+                    }
+                    else if (destinationFields[destinationKey].optional !== true) {
+                        errors.push(`${String(srcKey)}: required property missing in source object.`);
+                    }
+                }
+            }
+            if ((options === null || options === void 0 ? void 0 : options.strict) === true) {
+                for (const key in from) {
+                    if ((0, base_1.isKeyOf)(key, from) && !used.has(key)) {
+                        errors.push(`${key}: unexpected property in source object`);
+                    }
+                }
+            }
+        }
+        else {
+            errors.push('source is not an object');
+        }
+        return errors.length === 0
+            ? (0, base_1.succeed)(converted)
+            : (0, base_1.fail)((options === null || options === void 0 ? void 0 : options.description) ? `${options.description}:\n  ${errors.join('\n  ')}` : errors.join('\n'));
+    });
+}
+exports.transformObject = transformObject;
+/**
+ * A helper wrapper to construct a {@link Converter} which converts to an arbitrary strongly-typed
+ * range of some comparable type.
+ * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.
+ * @param constructor - Static constructor to instantiate the object.
+ * @public
+ */
+function rangeTypeOf(converter, constructor) {
+    return new converter_1.BaseConverter((from, __self, context) => {
+        const result = object({
+            min: converter,
+            max: converter
+        }, { optionalFields: ['min', 'max'] }).convert(from, context);
+        if (result.isSuccess()) {
+            return constructor({ min: result.value.min, max: result.value.max });
+        }
+        return (0, base_1.fail)(result.message);
+    });
+}
+exports.rangeTypeOf = rangeTypeOf;
+/**
+ * A helper wrapper to construct a {@link Converter} which converts to {@link Experimental.RangeOf | RangeOf<T>}
+ * where `<T>` is some comparable type.
+ * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.
+ * @public
+ */
+function rangeOf(converter) {
+    return rangeTypeOf(converter, experimental_1.RangeOf.createRange);
+}
+exports.rangeOf = rangeOf;
+//# sourceMappingURL=converters.js.map