@fgv/ts-utils 5.0.1-9 → 5.0.1

package/dist/packlets/collections/validatingCollector.js

@@ -0,0 +1,63 @@
+/*
+ * 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 { Collector } from './collector';
+import { CollectorValidator } from './collectorValidator';
+/**
+ * A {@link Collections.Collector | Collector} with a {@link Collections.CollectorValidator | CollectorValidator}
+ * property that enables validated use of the underlying map with weakly-typed keys and values.
+ * @public
+ */
+export class ValidatingCollector extends Collector {
+    /**
+     * Constructs a new {@link Collections.ValidatingCollector | ValidatingConvertingCollector}
+     * from the supplied {@link Collections.IValidatingCollectorConstructorParams | parameters}.
+     * @param params - Required parameters for constructing the collector.
+     */
+    constructor(params) {
+        var _a;
+        super();
+        this._converters = params.converters;
+        this.validating = new CollectorValidator({ collector: this, converters: params.converters });
+        for (const item of (_a = params.items) !== null && _a !== void 0 ? _a : []) {
+            this.validating.getOrAdd(item).orThrow();
+        }
+    }
+    /**
+     * Creates a new {@link Collections.ValidatingCollector | ValidatingCollector} instance from
+     * the supplied {@link Collections.IValidatingCollectorConstructorParams | parameters}.
+     * @param params - Required parameters for constructing the collector.
+     * @returns {@link Success} with the new collector if successful, {@link Failure} otherwise.
+     */
+    static createValidatingCollector(params) {
+        return captureResult(() => new ValidatingCollector(params));
+    }
+    /**
+     * Gets a read-only version of this collector as a
+     * {@link Collections.IReadOnlyValidatingResultMap | read-only map}.
+     * @returns
+     */
+    toReadOnly() {
+        return this;
+    }
+}
+//# sourceMappingURL=validatingCollector.js.map

package/dist/packlets/collections/validatingConvertingCollector.js

@@ -0,0 +1,64 @@
+/*
+ * 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 { ConvertingCollector } from './convertingCollector';
+import { ConvertingCollectorValidator } from './convertingCollectorValidator';
+/**
+ * A {@link Collections.ConvertingCollector | ConvertingCollector} with a
+ * {@link Collections.ConvertingCollectorValidator | ConvertingCollectorValidator}
+ * property that enables validated use of the underlying map with weakly-typed keys and values.
+ * @public
+ */
+export class ValidatingConvertingCollector extends ConvertingCollector {
+    /**
+     * Constructs a new {@link Collections.ValidatingConvertingCollector | ValidatingConvertingCollector}
+     * from the supplied {@link Collections.IValidatingConvertingCollectorConstructorParams | parameters}.
+     * @param params - Required parameters for constructing the collector.
+     */
+    constructor(params) {
+        var _a;
+        super({ factory: params.factory });
+        this._converters = params.converters;
+        this.validating = new ConvertingCollectorValidator({ collector: this, converters: params.converters });
+        for (const entry of (_a = params.entries) !== null && _a !== void 0 ? _a : []) {
+            this.getOrAdd(entry[0], entry[1]).orThrow();
+        }
+    }
+    /**
+     * Creates a new {@link Collections.ValidatingConvertingCollector | ValidatingConvertingCollector} instance from
+     * the supplied {@link Collections.IValidatingConvertingCollectorConstructorParams | parameters}.
+     * @param params - Required parameters for constructing the collector.
+     * @returns {@link Success} with the new collector if successful, {@link Failure} otherwise.
+     */
+    static createValidatingCollector(params) {
+        return captureResult(() => new ValidatingConvertingCollector(params));
+    }
+    /**
+     * Gets a read-only version of this collector as a
+     * {@link Collections.IReadOnlyValidatingResultMap | read-only map}.
+     * @returns
+     */
+    toReadOnly() {
+        return this;
+    }
+}
+//# sourceMappingURL=validatingConvertingCollector.js.map

package/dist/packlets/collections/validatingResultMap.js

@@ -0,0 +1,57 @@
+/*
+ * 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 { ResultMap } from './resultMap';
+import { ResultMapValidator } from './resultMapValidator';
+/**
+ * A {@link Collections.ResultMap | ResultMap} with a {@link Collections.ResultMapValidator | validator}
+ * property that enables validated use of the underlying map with weakly-typed keys and values.
+ * @public
+ */
+export class ValidatingResultMap extends ResultMap {
+    /**
+     * Constructs a new {@link Collections.ValidatingResultMap | ValidatingResultMap}.
+     * @param params - Required parameters for constructing the map.
+     */
+    constructor(params) {
+        var _a;
+        const entries = params.converters.convertEntries([...((_a = params.entries) !== null && _a !== void 0 ? _a : [])]).orThrow();
+        super({ entries });
+        this.validating = new ResultMapValidator({ map: this, converters: params.converters });
+    }
+    /**
+     * Creates a new {@link Collections.ValidatingResultMap | ValidatingResultMap} instance.
+     * @param params - Required parameters for constructing the map.
+     * @returns `Success` with the new map if successful, `Failure` otherwise.
+     * @public
+     */
+    static createValidatingResultMap(params) {
+        return captureResult(() => new ValidatingResultMap(params));
+    }
+    /**
+     * Gets a read-only version of this map.
+     */
+    toReadOnly() {
+        return this;
+    }
+}
+//# sourceMappingURL=validatingResultMap.js.map

package/dist/packlets/conversion/baseConverter.js

@@ -0,0 +1,242 @@
+/*
+ * 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, mapResults, succeed } from '../base';
+import { GenericDefaultingConverter } from './defaultingConverter';
+/**
+ * Base templated wrapper to simplify creation of new {@link Converter}s.
+ * @public
+ */
+export 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' ? 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, this._context(context));
+            }
+            return 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, this._context(context));
+            }
+            return fail(innerResult.message);
+        })._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 mapResults(items.map((i) => mapper(i, this._context(context))));
+                }
+                return 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 mapResults(items.map((i) => mapConverter.convert(i, this._context(context))));
+                }
+                return fail('Cannot map items - not an array');
+            });
+        });
+    }
+    /**
+     * {@inheritdoc Converter.withAction}
+     */
+    withAction(action) {
+        return new BaseConverter((from, __self, context) => {
+            return action(this._converter(from, this, this._context(context)), this._context(context));
+        })._with(this._traits());
+    }
+    /**
+     * {@inheritdoc Converter.withTypeGuard}
+     */
+    withTypeGuard(guard, message) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onSuccess((inner) => {
+                message = message !== null && message !== void 0 ? message : 'invalid type';
+                return guard(inner, this._context(context))
+                    ? succeed(inner)
+                    : fail(`${message}: ${JSON.stringify(from)}`);
+            });
+        })._with(this._traits());
+    }
+    /**
+     * {@inheritdoc Converter.withItemTypeGuard}
+     */
+    withItemTypeGuard(guard, message) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onSuccess((items) => {
+                if (Array.isArray(items)) {
+                    return mapResults(items.map((i) => {
+                        message = message !== null && message !== void 0 ? message : 'invalid type';
+                        return guard(i, this._context(context))
+                            ? succeed(i)
+                            : fail(`${message}: ${JSON.stringify(from)}`);
+                    }));
+                }
+                return fail('Cannot guard item type - not an array');
+            });
+        })._with(this._traits());
+    }
+    /**
+     * {@inheritdoc Converter.withConstraint}
+     */
+    withConstraint(constraint, options) {
+        return new BaseConverter((from, __self, context) => {
+            var _a;
+            const result = this._converter(from, this, this._context(context));
+            if (result.isSuccess()) {
+                const constraintResult = constraint(result.value, this._context(context));
+                if (typeof constraintResult === 'boolean') {
+                    return constraintResult
+                        ? result
+                        : 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 succeed(v);
+            });
+        })._with(this._traits({ brand }));
+    }
+    /**
+     * {@inheritdoc Converter.withDefault}
+     */
+    withDefault(defaultValue) {
+        return new GenericDefaultingConverter(this, defaultValue);
+    }
+    /**
+     * @internal
+     */
+    _context(supplied) {
+        return supplied !== null && supplied !== void 0 ? supplied : this._defaultContext;
+    }
+    /**
+     * {@inheritdoc Converter.withFormattedError}
+     */
+    withFormattedError(formatter) {
+        return new BaseConverter((from, __self, context) => {
+            return this._converter(from, this, this._context(context)).onFailure((msg) => {
+                return fail(formatter(from, msg, this._context(context)));
+            });
+        })._with(this._traits());
+    }
+    /**
+     * @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;
+    }
+}
+//# sourceMappingURL=baseConverter.js.map

package/dist/packlets/conversion/converter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=converter.js.map