@fgv/ts-utils 5.0.2-0 → 5.1.0-0

package/dist/packlets/collections/resultMapValidator.js

@@ -20,6 +20,50 @@
  * SOFTWARE.
  */
 import { failWithDetail, succeedWithDetail } from '../base';
+/**
+ * A read-only validator for any {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}
+ * that validates weakly-typed keys before accessing values.
+ * @public
+ */
+export class ReadOnlyResultMapValidator {
+    /**
+     * The underlying map.
+     */
+    get map() {
+        return this._map;
+    }
+    /**
+     * Constructs a new {@link Collections.ReadOnlyResultMapValidator | ReadOnlyResultMapValidator}.
+     * @param map - The map to validate access to.
+     * @param converters - The key-value converters for validation.
+     */
+    constructor(map, converters) {
+        this._map = map;
+        this.converters = converters;
+    }
+    /**
+     * Gets a value from the map by key, validating the key first.
+     * @param key - The key to retrieve (will be validated).
+     * @returns `Success` with the value if found, `Failure` otherwise.
+     */
+    get(key) {
+        return this.converters.convertKey(key).onSuccess((validKey) => {
+            return this._map.get(validKey);
+        });
+    }
+    /**
+     * Checks if the map contains a key, validating the key first.
+     * @param key - The key to check (will be validated).
+     * @returns `true` if the key exists and is valid, `false` otherwise.
+     */
+    has(key) {
+        const result = this.converters.convertKey(key);
+        if (result.isFailure()) {
+            return false;
+        }
+        return this._map.has(result.value);
+    }
+}
 /**
  * A {@link Collections.ResultMap | ResultMap} wrapper which validates weakly-typed keys
  * before calling the wrapped result map.
@@ -38,7 +82,7 @@ export class ResultMapValidator {
         this.converters = params.converters;
     }
     /**
-     * {@inheritdoc Collections.ResultMap.add}
+     * {@inheritDoc Collections.ResultMap.add}
      */
     add(key, value) {
         return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {
@@ -46,7 +90,7 @@ export class ResultMapValidator {
         });
     }
     /**
-     * {@inheritdoc Collections.ResultMap.delete}
+     * {@inheritDoc Collections.ResultMap.delete}
      */
     delete(key) {
         return this.converters.convertKey(key).onSuccess((k) => {
@@ -54,7 +98,7 @@ export class ResultMapValidator {
         });
     }
     /**
-     * {@inheritdoc Collections.ResultMap.get}
+     * {@inheritDoc Collections.ResultMap.get}
      */
     get(key) {
         return this.converters.convertKey(key).onSuccess((k) => {
@@ -81,13 +125,13 @@ export class ResultMapValidator {
         }
     }
     /**
-     * {@inheritdoc Collections.ResultMap.has}
+     * {@inheritDoc Collections.ResultMap.has}
      */
     has(key) {
         return this._map.has(key);
     }
     /**
-     * {@inheritdoc Collections.ResultMap.set}
+     * {@inheritDoc Collections.ResultMap.set}
      */
     set(key, value) {
         return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {
@@ -95,7 +139,7 @@ export class ResultMapValidator {
         });
     }
     /**
-     * {@inheritdoc Collections.ResultMap.update}
+     * {@inheritDoc Collections.ResultMap.update}
      */
     update(key, value) {
         return this.converters.convertEntry([key, value]).onSuccess(([vk, vv]) => {

package/dist/packlets/collections/validatingConvertingResultMap.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2025 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 { captureResult } from '../base';
+import { ReadOnlyConvertingResultMap } from './readOnlyConvertingResultMap';
+import { ConvertingResultMap } from './convertingResultMap';
+import { ReadOnlyResultMapValidator } from './resultMapValidator';
+/**
+ * A read-only result map that wraps an inner {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}
+ * of source type and returns lazily-converted, cached values of a target type, with a
+ * {@link Collections.ReadOnlyResultMapValidator | validating} property for weakly-typed access.
+ * @public
+ */
+export class ValidatingReadOnlyConvertingResultMap extends ReadOnlyConvertingResultMap {
+    /**
+     * Constructs a new {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.
+     * @param params - Parameters for constructing the map.
+     */
+    constructor(params) {
+        super({ inner: params.inner, converter: params.converter });
+        this._converters = params.converters;
+        this.validating = new ReadOnlyResultMapValidator(this, params.converters);
+    }
+    /**
+     * Creates a new {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.
+     * @param params - Parameters for constructing the map.
+     * @returns `Success` with the new map, or `Failure` with error details if an error occurred.
+     */
+    static create(params) {
+        return captureResult(() => new ValidatingReadOnlyConvertingResultMap(params));
+    }
+}
+/**
+ * A result map that wraps an inner {@link Collections.IResultMap | IResultMap} of source type
+ * and returns lazily-converted, cached values of a target type, with a
+ * {@link Collections.ReadOnlyResultMapValidator | validating} property for weakly-typed access
+ * and a {@link Collections.CacheInvalidatingResultMapWrapper | source} property for mutable access
+ * to the underlying source map.
+ * @public
+ */
+export class ValidatingConvertingResultMap extends ConvertingResultMap {
+    /**
+     * Constructs a new {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.
+     * @param params - Parameters for constructing the map.
+     */
+    constructor(params) {
+        super({ inner: params.inner, converter: params.converter });
+        this._converters = params.converters;
+        this.validating = new ReadOnlyResultMapValidator(this, params.converters);
+    }
+    /**
+     * Creates a new {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.
+     * @param params - Parameters for constructing the map.
+     * @returns `Success` with the new map, or `Failure` with error details if an error occurred.
+     */
+    static create(params) {
+        return captureResult(() => new ValidatingConvertingResultMap(params));
+    }
+}
+//# sourceMappingURL=validatingConvertingResultMap.js.map

package/dist/packlets/conversion/advancedConverters.js

@@ -0,0 +1,249 @@
+/*
+ * 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, mapResults, succeed, Success } from '../base';
+import { BaseConverter } from './baseConverter';
+import { literal } from './basicConverters';
+import { ObjectConverter } from './objectConverter';
+/**
+ * Creates an {@link ObjectConverter | ObjectConverter} for a strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @param collectionIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns An {@link ObjectConverter | ObjectConverter} for the strongly-typed composite ICompositeId.
+ * @public
+ */
+export function compositeIdFromObject(collectionIdValidator, separator, itemIdValidator) {
+    return new ObjectConverter({
+        collectionId: collectionIdValidator,
+        separator: literal(separator).optional(),
+        itemId: itemIdValidator
+    }).map((obj) => {
+        var _a;
+        return Success.with({
+            collectionId: obj.collectionId,
+            separator: (_a = obj.separator) !== null && _a !== void 0 ? _a : separator,
+            itemId: obj.itemId
+        });
+    });
+}
+/**
+ * Converts a composite ID string into a strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @public
+ */
+export function compositeIdFromString(collectionIdConverter, separator, itemIdConverter) {
+    return new BaseConverter((from, __self, context) => {
+        if (typeof from !== 'string') {
+            return fail(`${from}: invalid non-string composite ID.`);
+        }
+        const parts = from.split(separator);
+        if (parts.length < 2) {
+            return fail(`${from}: invalid composite ID - separator '${separator}' not found.`);
+        }
+        else if (parts.length > 2) {
+            return fail(`${from}: invalid composite ID - multiple separators '${separator}.' found.`);
+        }
+        return collectionIdConverter.convert(parts[0], context).onSuccess((collectionId) => {
+            return itemIdConverter.convert(parts[1], context).onSuccess((itemId) => {
+                return succeed({
+                    collectionId,
+                    separator,
+                    itemId
+                });
+            });
+        });
+    });
+}
+/**
+ * Creates a {@link Converter | Converter} for a strongly-typed {@link Converters.ICompositeId | CompositeId} from
+ * either a string or an object representation.
+ * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.
+ * @public
+ */
+export function compositeId(collectionIdConverter, separator, itemIdConverter) {
+    return compositeIdFromObject(collectionIdConverter, separator, itemIdConverter).or(compositeIdFromString(collectionIdConverter, separator, itemIdConverter));
+}
+/**
+ * Converts a strongly-typed {@link Converters.ICompositeId | CompositeId} into a string.
+ * @param compositeIdConverter - {@link Converter | Converter} or {@link Validator | Validator} that validates/converts the composite ID string.
+ * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+ * @param separator - The separator string.
+ * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+ * @returns A {@link Converter | Converter} which produces a composite ID string.
+ * @public
+ */
+export function compositeIdString(compositeIdConverter, collectionIdConverter, separator, itemIdConverter) {
+    const objectConverter = compositeIdFromObject(collectionIdConverter, separator, itemIdConverter);
+    return new BaseConverter((from, __self, context) => {
+        if (typeof from === 'string') {
+            return compositeIdConverter.convert(from, context);
+        }
+        return objectConverter.convert(from, context).onSuccess((compositeId) => {
+            return compositeIdConverter.convert(`${compositeId.collectionId}${separator}${compositeId.itemId}`);
+        });
+    });
+}
+/**
+ * Helper to create a {@link Converter | Converter} which converts a source object to a new object with a
+ * different shape.
+ *
+ * @remarks
+ * On successful conversion, the resulting {@link Converter | Converter} returns {@link Success | Success} with a new
+ * object, which contains the converted values under the key names specified at initialization time.
+ * It returns {@link Failure | 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 | Converter} with the specified conversion behavior.
+ * @public
+ */
+export function transform(properties) {
+    return new BaseConverter((from, __self, context) => {
+        // eslint bug thinks key is used before defined
+        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 ? succeed(converted) : fail(errors.join('\n'));
+    });
+}
+/**
+ * Helper to create a strongly-typed {@link Converter | Converter} which converts a source object to a
+ * new object with a different shape.
+ *
+ * @remarks
+ * On successful conversion, the resulting {@link Converter | Converter} returns {@link Success | Success} with a new
+ * object, which contains the converted values under the key names specified at initialization time.
+ *
+ * It returns {@link Failure | 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 or validator used for each source
+ * property and any other configuration to guide the conversion.
+ * @param options - Options which affect the transformation.
+ *
+ * @returns A {@link Converter | Converter} with the specified conversion behavior.
+ * @public
+ */
+export function transformObject(destinationFields, options) {
+    return new BaseConverter((from, __self, context) => {
+        // eslint bug thinks key is used before defined
+        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 (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 (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
+            ? succeed(converted)
+            : fail((options === null || options === void 0 ? void 0 : options.description) ? `${options.description}:\n  ${errors.join('\n  ')}` : errors.join('\n'));
+    });
+}
+/**
+ * Creates a {@link Converter | Converter} that converts an array to a strongly-typed tuple,
+ * using the supplied tuple of {@link Converter | Converters} to convert each element.
+ *
+ * @remarks
+ * The resulting {@link Converter | Converter} returns {@link Success | Success} with a tuple
+ * containing the converted values if all conversions succeed. Returns {@link Failure | Failure}
+ * with an error message if the source is not an array, has the wrong number of elements, or
+ * any element conversion fails.
+ *
+ * @example
+ * ```typescript
+ * const converter = tuple([Converters.string, Converters.number, Converters.boolean]);
+ * // Type is Converter<[string, number, boolean]>
+ *
+ * converter.convert(['hello', 42, true]);
+ * // Returns Success with ['hello', 42, true]
+ * ```
+ *
+ * @param converters - A tuple of {@link Converter | Converters} defining the expected types
+ * for each element of the tuple.
+ * @returns A {@link Converter | Converter} that returns a strongly-typed tuple.
+ * @public
+ */
+export function tuple(converters) {
+    return new BaseConverter((from, __self, context) => {
+        if (!Array.isArray(from)) {
+            return fail(`Not an array: ${JSON.stringify(from)}`);
+        }
+        if (from.length !== converters.length) {
+            return fail(`Expected array of length ${converters.length}, got ${from.length}: ${JSON.stringify(from)}`);
+        }
+        const results = converters.map((converter, index) => {
+            return converter.convert(from[index], context);
+        });
+        return mapResults(results);
+    });
+}
+//# sourceMappingURL=advancedConverters.js.map

package/dist/packlets/conversion/baseConverter.js

@@ -44,25 +44,25 @@ export class BaseConverter {
         this._brand = traits === null || traits === void 0 ? void 0 : traits.brand;
     }
     /**
-     * {@inheritdoc Converter.isOptional}
+     * {@inheritDoc Converter.isOptional}
      */
     get isOptional() {
         return this._isOptional;
     }
     /**
-     * {@inheritdoc Converter.brand}
+     * {@inheritDoc Converter.brand}
      */
     get brand() {
         return this._brand;
     }
     /**
-     * {@inheritdoc Converter.convert}
+     * {@inheritDoc Converter.convert}
      */
     convert(from, context) {
         return this._converter(from, this, context !== null && context !== void 0 ? context : this._defaultContext);
     }
     /**
-     * {@inheritdoc Converter.convertOptional}
+     * {@inheritDoc Converter.convertOptional}
      */
     convertOptional(from, context, onError) {
         const result = this._converter(from, this, this._context(context));
@@ -73,7 +73,7 @@ export class BaseConverter {
         return result;
     }
     /**
-     * {@inheritdoc Converter.optional}
+     * {@inheritDoc Converter.optional}
      */
     optional(onError) {
         return new BaseConverter((from, __self, context) => {
@@ -82,7 +82,7 @@ export class BaseConverter {
         })._with(this._traits({ isOptional: true }));
     }
     /**
-     * {@inheritdoc Converter.map}
+     * {@inheritDoc Converter.map}
      */
     map(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -94,7 +94,7 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.mapConvert}
+     * {@inheritDoc Converter.mapConvert}
      */
     mapConvert(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -106,7 +106,7 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.mapItems}
+     * {@inheritDoc Converter.mapItems}
      */
     mapItems(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -119,7 +119,7 @@ export class BaseConverter {
         });
     }
     /**
-     * {@inheritdoc Converter.mapConvertItems}
+     * {@inheritDoc Converter.mapConvertItems}
      */
     mapConvertItems(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -132,7 +132,7 @@ export class BaseConverter {
         });
     }
     /**
-     * {@inheritdoc Converter.withAction}
+     * {@inheritDoc Converter.withAction}
      */
     withAction(action) {
         return new BaseConverter((from, __self, context) => {
@@ -140,7 +140,7 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.withTypeGuard}
+     * {@inheritDoc Converter.withTypeGuard}
      */
     withTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -153,7 +153,7 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.withItemTypeGuard}
+     * {@inheritDoc Converter.withItemTypeGuard}
      */
     withItemTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -171,7 +171,7 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.withConstraint}
+     * {@inheritDoc Converter.withConstraint}
      */
     withConstraint(constraint, options) {
         return new BaseConverter((from, __self, context) => {
@@ -190,7 +190,7 @@ export class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritdoc Converter.withBrand}
+     * {@inheritDoc Converter.withBrand}
      */
     withBrand(brand) {
         if (this._brand) {
@@ -203,11 +203,18 @@ export class BaseConverter {
         })._with(this._traits({ brand }));
     }
     /**
-     * {@inheritdoc Converter.withDefault}
+     * {@inheritDoc Converter.withDefault}
      */
     withDefault(defaultValue) {
         return new GenericDefaultingConverter(this, defaultValue);
     }
+    or(other) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onFailure(() => {
+                return other.convert(from, this._context(context));
+            });
+        });
+    }
     /**
      * @internal
      */
@@ -215,7 +222,7 @@ export class BaseConverter {
         return supplied !== null && supplied !== void 0 ? supplied : this._defaultContext;
     }
     /**
-     * {@inheritdoc Converter.withFormattedError}
+     * {@inheritDoc Converter.withFormattedError}
      */
     withFormattedError(formatter) {
         return new BaseConverter((from, __self, context) => {