@fgv/ts-utils 5.0.2 → 5.1.0-0

package/dist/packlets/conversion/basicConverters.js

@@ -0,0 +1,571 @@
+/*
+ * 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.
+ */
+import { fail, isKeyOf, succeed } from '../base';
+import { Base as ValidationBase } from '../validation';
+import { BaseConverter } from './baseConverter';
+import { ObjectConverter } from './objectConverter';
+import { StringConverter } from './stringConverter';
+/**
+ * A converter to convert unknown to string. Values of type
+ * string succeed.  Anything else fails.
+ * @public
+ */
+export const string = new StringConverter();
+/**
+ * Helper function to create a {@link Converter | 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 | Converter} returning `<T>`.
+ * @public
+ */
+export function enumeratedValue(values) {
+    return new BaseConverter((from, __self, context) => {
+        const v = context !== null && context !== void 0 ? context : values;
+        const index = v.indexOf(from);
+        return index >= 0 ? succeed(v[index]) : fail(`Invalid enumerated value ${JSON.stringify(from)}`);
+    });
+}
+/**
+ * Helper function to create a {@link Converter | 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 | Converter} which applies the mapping and yields `<T>` on success.
+ * @public
+ */
+export function mappedEnumeratedValue(map, message) {
+    return new BaseConverter((from, __self, __context) => {
+        for (const item of map) {
+            if (item[1].includes(from)) {
+                return succeed(item[0]);
+            }
+        }
+        return fail(message
+            ? `${JSON.stringify(from)}: ${message}`
+            : `Cannot map '${JSON.stringify(from)}' to a supported value`);
+    });
+}
+/**
+ * Helper function to create a {@link Converter | 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 | Converter} which returns the supplied value on success.
+ * @public
+ */
+export function literal(value) {
+    return new BaseConverter((from, __self, __context) => {
+        return from === value
+            ? succeed(value)
+            : fail(`${JSON.stringify(from)}: does not match ${JSON.stringify(value)}`);
+    });
+}
+/**
+ * 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
+export const value = literal;
+/**
+ * A {@link Converter | Converter} which converts `unknown` to a `number`.
+ * @remarks
+ * Numbers and strings with a numeric format succeed. Anything else fails.
+ * @public
+ */
+export const number = new BaseConverter((from) => {
+    if (typeof from !== 'number') {
+        const num = typeof from === 'string' ? Number(from) : NaN;
+        return isNaN(num) ? fail(`Not a number: ${JSON.stringify(from)}`) : succeed(num);
+    }
+    return succeed(from);
+});
+const booleanConverter = new BaseConverter((from) => {
+    if (typeof from === 'boolean') {
+        return succeed(from);
+    }
+    else if (typeof from === 'string') {
+        switch (from.toLowerCase()) {
+            case 'true':
+                return succeed(true);
+            case 'false':
+                return succeed(false);
+        }
+    }
+    return fail(`Not a boolean: ${JSON.stringify(from)}`);
+});
+/**
+ * A {@link Converter | Converter} which converts `unknown` to `boolean`.
+ * @remarks
+ * Boolean values or the case-insensitive strings `'true'` and `'false'` succeed.
+ * Anything else fails.
+ * @public
+ */
+export const boolean = booleanConverter;
+/**
+ * A {@link Converter | Converter} which converts an optional `string` value. Values of type
+ * `string` are returned.  Anything else returns {@link Success | Success} with value `undefined`.
+ * @public
+ */
+export const optionalString = string.optional();
+/**
+ * Helper function to create a {@link Converter | 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 | Converter} returning `string[]`.
+ * @public
+ */
+export function delimitedString(delimiter, options = 'filtered') {
+    return new BaseConverter((from, __self, context) => {
+        const result = 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 succeed(strings);
+        }
+        return fail(result.message);
+    });
+}
+/**
+ * Determines if a supplied {@link Conversion.Converter | Converter} or {@link Validation.Validator | Validator} is
+ * a {@link Validation.Validator | Validator}.
+ * @param converterOrValidator - The {@link Conversion.Converter | Converter} or {@link Validation.Validator | Validator} to be tested.
+ * @returns `true` if `converterOrValidator` is a {@link Validation.Validator | Validator}, `false` otherwise.
+ * @public
+ */
+export function isValidator(converterOrValidator) {
+    return 'validate' in converterOrValidator;
+}
+/**
+ * Helper function to create a {@link Converter | Converter} from any {@link Validation.Validator}
+ * @param converterOrValidator - the {@link Validation.Validator} to be wrapped or {@link Converter | Converter}
+ * to be used directly.
+ * @returns A {@link Converter | Converter} which uses the supplied validator.
+ * @public
+ */
+export function validated(converterOrValidator) {
+    if (!isValidator(converterOrValidator)) {
+        return converterOrValidator;
+    }
+    return new BaseConverter((from, __self, context) => {
+        return converterOrValidator.validate(from, context);
+    });
+}
+/**
+ * Helper function to create a {@link Validation.Validator | Validator} from any {@link Conversion.Converter | Converter}
+ * or {@link Validation.Validator | Validator}.
+ * @param converterOrValidator - the {@link Conversion.Converter | Converter} to be wrappped or {@link Validation.Validator | Validator} to be used directly.
+ * @returns A {@link Validation.Validator | Validator} which uses the supplied converter or validator.
+ * @public
+ */
+export function asValidator(converterOrValidator) {
+    if (isValidator(converterOrValidator)) {
+        return converterOrValidator;
+    }
+    return new ValidationBase.GenericValidator({
+        validator: (from, context) => {
+            const result = converterOrValidator.convert(from, context);
+            return result.isSuccess() ? true : fail(result.message);
+        }
+    });
+}
+/**
+ * Helper function to create a {@link Converter | Converter} from a supplied {@link Conversion.ConverterFunc | ConverterFunc}.
+ * @param convert - the function to be wrapped
+ * @returns A {@link Converter | Converter} which uses the supplied function.
+ * @public
+ */
+export function generic(convert) {
+    return new BaseConverter(convert);
+}
+/**
+ * Helper function to create a {@link Converter | 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 | Converter} which validates the values using the supplied type guard
+ * and returns them in place.
+ * @public
+ */
+export function isA(description, guard) {
+    return new BaseConverter((from, __self, context) => {
+        if (guard(from, context)) {
+            return succeed(from);
+        }
+        return fail(`invalid ${description} (${JSON.stringify(from)})`);
+    });
+}
+/**
+ * A {@link Converter | Converter} which converts an optional `number` value.
+ * @remarks
+ * Values of type `number` or numeric strings are converted and returned.
+ * Anything else returns {@link Success | Success} with value `undefined`.
+ * @public
+ */
+export const optionalNumber = number.optional();
+/**
+ * A {@link Converter | 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 | Success}
+ * with value `undefined`.
+ * @public
+ */
+export const optionalBoolean = booleanConverter.optional();
+/**
+ * A helper function to create a {@link Converter | 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} or {@link Validator | validators}
+ * to be considered.
+ * @param onError - Specifies treatment of unconvertible elements.
+ * @returns A new {@link Converter | Converter} which yields a value from the union of the types returned
+ * by the wrapped converters.
+ * @public
+ */
+export function oneOf(converters, onError = 'ignoreErrors') {
+    return new 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 fail(`No matching converter for ${JSON.stringify(from)}: ${errors.join('\n')}`);
+    });
+}
+/**
+ * A helper function to create a {@link Converter | 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 | Converter} or {@link Validator | Validator} used to convert each
+ * item in the array.
+ * @param onError - Specifies treatment of unconvertible elements.
+ * @returns A {@link Converter | Converter} which returns an array of `<T>`.
+ * @public
+ */
+export function arrayOf(converter, onError = 'failOnError') {
+    return new BaseConverter((from, __self, context) => {
+        if (!Array.isArray(from)) {
+            return 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' ? succeed(successes) : fail(errors.join('\n'));
+    });
+}
+/**
+ * {@link Converter | Converter} to convert an `unknown` to an array of `string`.
+ * @remarks
+ * Returns {@link Success | Success} with the the supplied value if it as an array
+ * of strings, returns {@link Failure | Failure} with an error message otherwise.
+ * @public
+ */
+export const stringArray = arrayOf(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
+ */
+export const numberArray = arrayOf(number);
+/**
+ * Concrete implementation of {@link Converters.(recordOf:1) | Converters.recordOf(Converter<T, TC>)},
+ * {@link Converters.(recordOf:2) | Converters.recordOf(Converter<T, TC>, 'fail' or 'ignore')}, and
+ * {@link Converters.recordOf | Converters.recordOf(Converter<T, TC>, KeyedConverterOptions)}.
+ * @internal
+ */
+export function recordOf(converter, option = 'fail') {
+    const options = typeof option === 'string' ? { onError: option } : Object.assign({ onError: 'fail' }, option);
+    return new BaseConverter((from, __self, context) => {
+        var _a, _b;
+        if (typeof from !== 'object' || from === null || Array.isArray(from)) {
+            return fail(`Not a string-keyed object: ${JSON.stringify(from)}`);
+        }
+        const record = {};
+        const errors = [];
+        for (const key in from) {
+            if (isKeyOf(key, from)) {
+                const writeKeyResult = (_b = (_a = options.keyConverter) === null || _a === void 0 ? void 0 : _a.convert(key, context)) !== null && _b !== void 0 ? _b : succeed(key);
+                writeKeyResult
+                    .onSuccess((writeKey) => {
+                    return converter.convert(from[key], context).onSuccess((value) => {
+                        record[writeKey] = value;
+                        return succeed(true);
+                    });
+                })
+                    .onFailure((message) => {
+                    errors.push(message);
+                    return fail(message);
+                });
+            }
+        }
+        return errors.length === 0 || options.onError === 'ignore' ? succeed(record) : fail(errors.join('\n'));
+    });
+}
+/**
+ * Concrete implementation of {@link Converters.(mapOf:1) | Converters.mapOf(Converter<T, TC>)},
+ * {@link Converters.(mapOf:2) | Converters.mapOf(Converter<T, TC>, 'fail' or 'ignore')}, and
+ * {@link Converters.mapOf | Converters.mapOf(Converter<T, TC>, KeyedConverterOptions)}.
+ * @internal
+ */
+export function mapOf(converter, option = 'fail') {
+    const options = typeof option === 'string' ? { onError: option } : Object.assign({ onError: 'fail' }, option);
+    return new BaseConverter((from, __self, context) => {
+        var _a, _b;
+        if (typeof from !== 'object' || from === null || Array.isArray(from)) {
+            return fail(`Not a string-keyed object: ${JSON.stringify(from)}`);
+        }
+        const map = new Map();
+        const errors = [];
+        for (const key in from) {
+            if (isKeyOf(key, from)) {
+                const writeKeyResult = (_b = (_a = options.keyConverter) === null || _a === void 0 ? void 0 : _a.convert(key, context)) !== null && _b !== void 0 ? _b : succeed(key);
+                writeKeyResult
+                    .onSuccess((writeKey) => {
+                    return converter.convert(from[key], context).onSuccess((value) => {
+                        map.set(writeKey, value);
+                        return succeed(true);
+                    });
+                })
+                    .onFailure((message) => {
+                    errors.push(message);
+                    return fail(message);
+                });
+            }
+        }
+        return errors.length === 0 || options.onError === 'ignore' ? succeed(map) : fail(errors.join('\n'));
+    });
+}
+/**
+ * Helper function to create  a {@link Converter | 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 | Converter} returns {@link Success | Success} with the supplied
+ * value of `from` coerced to type `<T>`.  Returns a {@link Failure | 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, TC>} which applies the supplied validation.
+ * @public
+ */
+export function validateWith(validator, description) {
+    return new BaseConverter((from, __self, __context) => {
+        if (validator(from)) {
+            return succeed(from);
+        }
+        return fail(`${JSON.stringify(from)}: invalid ${description !== null && description !== void 0 ? description : 'value'}`);
+    });
+}
+/**
+ * A helper function to create a {@link Converter | Converter} which extracts and converts an element from an array.
+ * @remarks
+ * The returned {@link Converter | Converter} returns {@link Success | Success} with the converted value if the element exists
+ * in the supplied array and can be converted. Returns {@link Failure | Failure} with an error message otherwise.
+ * @param index - The index of the element to be extracted.
+ * @param converter - A {@link Converter | Converter} or {@link Validator | Validator} for the extracted element.
+ * @returns A {@link Converter | Converter<T, TC>} which extracts the specified element from an array.
+ * @public
+ */
+export function element(index, converter) {
+    return new BaseConverter((from, __self, context) => {
+        if (index < 0) {
+            return fail(`${index}: cannot convert for a negative element index`);
+        }
+        else if (!Array.isArray(from)) {
+            return fail('element converter: source is not an array');
+        }
+        else if (index >= from.length) {
+            return fail(`${index}: element converter index out of range (0..${from.length - 1})`);
+        }
+        return converter.convert(from[index], context);
+    });
+}
+/**
+ * A helper function to create a {@link Converter | Converter} which extracts and converts an optional element from an array.
+ * @remarks
+ * The resulting {@link Converter | Converter} returns {@link Success | Success} with the converted value if the element exists
+ * in the supplied array and can be converted. Returns {@link Success | Success} with value `undefined` if the parameter
+ * is an array but the index is out of range. Returns {@link Failure | 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 | Converter} or {@link Validator | Validator} used for the extracted element.
+ * @returns A {@link Converter | Converter<T, TC>} which extracts the specified element from an array.
+ * @public
+ */
+export function optionalElement(index, converter) {
+    return new BaseConverter((from, __self, context) => {
+        if (index < 0) {
+            return fail(`${index}: cannot convert for a negative element index`);
+        }
+        else if (!Array.isArray(from)) {
+            return fail('element converter: source is not an array');
+        }
+        else if (index >= from.length) {
+            return succeed(undefined);
+        }
+        return converter.convert(from[index], context);
+    });
+}
+/**
+ * A helper function to create a {@link Converter | Converter} which extracts and convert a property specified
+ * by name from an object.
+ * @remarks
+ * The resulting {@link Converter | Converter} returns {@link Success | Success} with the converted value of the corresponding
+ * object property if the field exists and can be converted. Returns {@link Failure | Failure} with an error message
+ * otherwise.
+ * @param name - The name of the field to be extracted.
+ * @param converter - {@link Converter | Converter}  or {@link Validator | Validator} to use for the extracted
+ * field.
+ * @public
+ */
+export function field(name, converter) {
+    return new BaseConverter((from, __self, context) => {
+        if (typeof from === 'object' && !Array.isArray(from) && from !== null) {
+            if (isKeyOf(name, from)) {
+                return converter.convert(from[name], context).onFailure((message) => {
+                    return fail(`Field ${name}: ${message}`);
+                });
+            }
+            return fail(`Field ${name} not found in: ${JSON.stringify(from)}`);
+        }
+        return fail(`Cannot convert field "${name}" from non-object ${JSON.stringify(from)}`);
+    });
+}
+/**
+ * A helper function to create a {@link Converter | Converter} which extracts and convert a property specified
+ * by name from an object.
+ * @remarks
+ * The resulting {@link Converter | Converter} returns {@link Success | Success} with the converted value of
+ * the corresponding object property if the field exists and can be converted. Returns {@link Success | Success}
+ * with `undefined` if the supplied parameter is an object but the named field is not present.
+ * Returns {@link Failure | Failure} with an error message otherwise.
+ * @param name - The name of the field to be extracted.
+ * @param converter - {@link Converter | Converter} or {@link Validator | Validator} to use for the extracted field.
+ * @public
+ */
+export function optionalField(name, converter) {
+    return new BaseConverter((from, __self, context) => {
+        if (typeof from === 'object' && !Array.isArray(from) && from !== null) {
+            if (isKeyOf(name, from)) {
+                const result = converter.convert(from[name], context).onFailure((message) => {
+                    return 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 succeed(undefined);
+        }
+        return fail(`Cannot convert field "${name}" from non-object ${JSON.stringify(from)}`);
+    }, undefined, { isOptional: true });
+}
+/**
+ * Concrete implementation of {@link Converters.(object:1) | Converters.object(fields, options)}
+ * and {@link Converters.(object:2) | Converters.objects(fields, optionalKeys)}.
+ * @internal
+ */
+export function object(properties, options) {
+    return new ObjectConverter(properties, options);
+}
+/**
+ * Concrete implementation for {@link Converters.strictObject | Converters.strictObject(fields, options)}
+ * and {@link Converters.strictObject | Converters.strictObject(fields, optional)}.
+ * @internal
+ */
+export function strictObject(properties, opt) {
+    /* c8 ignore next 2 */
+    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(properties, options);
+}
+/**
+ * Helper to create a {@link Converter | 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 and validators}. During conversion,
+ * the resulting {@link Converter | 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 | Failure} with more information.
+ * @param discriminatorProp - Name of the property used to discriminate types.
+ * @param converters - {@link Converters.DiscriminatedObjectConverters | String-keyed record of converters and validators}
+ * to invoke, where each key corresponds to a value of the discriminator property.
+ * @returns A {@link Converter | Converter} which converts the corresponding discriminated object.
+ * @public
+ */
+export function discriminatedObject(discriminatorProp, converters) {
+    return new BaseConverter((from) => {
+        if (typeof from !== 'object' || Array.isArray(from) || from === null) {
+            return fail(`Not a discriminated object: "${JSON.stringify(from)}"`);
+        }
+        if (!isKeyOf(discriminatorProp, from) || !from[discriminatorProp]) {
+            return fail(`Discriminator property ${discriminatorProp} not present in "${JSON.stringify(from)}"`);
+        }
+        const discriminatorValue = from[discriminatorProp];
+        const converter = converters[discriminatorValue];
+        if (converter === undefined) {
+            return fail(`No converter for discriminator ${discriminatorProp}="${discriminatorValue}"`);
+        }
+        return converter.convert(from);
+    });
+}
+//# sourceMappingURL=basicConverters.js.map