@fgv/ts-utils 5.0.2 → 5.1.0-1

package/dist/packlets/conversion/defaultingConverter.js

@@ -27,13 +27,13 @@ import { succeed } from '../base';
  */
 export class GenericDefaultingConverter {
     /**
-     * {@inheritdoc Converter.isOptional}
+     * {@inheritDoc Converter.isOptional}
      */
     get isOptional() {
         return this._converter.isOptional;
     }
     /**
-     * {@inheritdoc Converter.isOptional}
+     * {@inheritDoc Converter.isOptional}
      */
     get brand() {
         return this._converter.brand;
@@ -48,13 +48,13 @@ export class GenericDefaultingConverter {
         this._converter = converter;
     }
     /**
-     * {@inheritdoc Converter.convert}
+     * {@inheritDoc Converter.convert}
      */
     convert(from, ctx) {
         return this._applyDefault(this._converter.convert(from, ctx));
     }
     /**
-     * {@inheritdoc Converter.convertOptional}
+     * {@inheritDoc Converter.convertOptional}
      */
     convertOptional(from, context, onError) {
         const converted = this._converter.convertOptional(from, context, onError);
@@ -64,7 +64,7 @@ export class GenericDefaultingConverter {
         return converted;
     }
     /**
-     * {@inheritdoc Converter.optional}
+     * {@inheritDoc Converter.optional}
      */
     optional(onError) {
         // need to let the inner converter do its optional thing first or our default
@@ -72,61 +72,61 @@ export class GenericDefaultingConverter {
         return this._converter.optional(onError).withAction((result) => this._applyDefault(result));
     }
     /**
-     * {@inheritdoc Converter.map}
+     * {@inheritDoc Converter.map}
      */
     map(mapper) {
         return this._converter.withAction((result) => this._applyDefault(result)).map(mapper);
     }
     /**
-     * {@inheritdoc Converter.mapConvert}
+     * {@inheritDoc Converter.mapConvert}
      */
     mapConvert(mapConverter) {
         return this._converter.withAction((result) => this._applyDefault(result)).mapConvert(mapConverter);
     }
     /**
-     * {@inheritdoc Converter.mapItems}
+     * {@inheritDoc Converter.mapItems}
      */
     mapItems(mapper) {
         return this._converter.withAction((result) => this._applyDefault(result)).mapItems(mapper);
     }
     /**
-     * {@inheritdoc Converter.mapConvertItems}
+     * {@inheritDoc Converter.mapConvertItems}
      */
     mapConvertItems(mapConverter) {
         return this._converter.withAction((result) => this._applyDefault(result)).mapConvertItems(mapConverter);
     }
     /**
-     * {@inheritdoc Converter.withAction}
+     * {@inheritDoc Converter.withAction}
      */
     withAction(action) {
         return this._converter.withAction((result) => this._applyDefault(result)).withAction(action);
     }
     /**
-     * {@inheritdoc Converter.withTypeGuard}
+     * {@inheritDoc Converter.withTypeGuard}
      */
     withTypeGuard(guard, message) {
         return this._converter.withAction((result) => this._applyDefault(result)).withTypeGuard(guard);
     }
     /**
-     * {@inheritdoc Converter.withItemTypeGuard}
+     * {@inheritDoc Converter.withItemTypeGuard}
      */
     withItemTypeGuard(guard, message) {
         return this._converter.withAction((result) => this._applyDefault(result)).withItemTypeGuard(guard);
     }
     /**
-     * {@inheritdoc Converter.withConstraint}
+     * {@inheritDoc Converter.withConstraint}
      */
     withConstraint(constraint, options) {
         return this._converter.withAction((result) => this._applyDefault(result)).withConstraint(constraint);
     }
     /**
-     * {@inheritdoc Converter.withBrand}
+     * {@inheritDoc Converter.withBrand}
      */
     withBrand(brand) {
         return this._converter.withAction((result) => this._applyDefault(result)).withBrand(brand);
     }
     /**
-     * {@inheritdoc Converter.withFormattedError}
+     * {@inheritDoc Converter.withFormattedError}
      */
     withFormattedError(formatter) {
         // formatter should never actually be invoked for a defaulting converter
@@ -142,6 +142,12 @@ export class GenericDefaultingConverter {
     withDefault(dflt) {
         return new GenericDefaultingConverter(this._converter, dflt);
     }
+    /**
+     * {@inheritDoc Converter.or}
+     */
+    or(__converter) {
+        return this;
+    }
     _applyDefault(converted) {
         return converted.success ? converted : succeed(this.defaultValue);
     }

package/dist/packlets/logging/bootLogger.js

@@ -0,0 +1,122 @@
+import { InMemoryLogger, isDetailLogger } from './logger';
+/**
+ * A logger that buffers log entries during startup, then replays them
+ * to a real logger once it becomes available.
+ *
+ * @remarks
+ * During application bootstrap, the real logger (e.g. one backed by
+ * toast notifications) may not be available yet. `BootLogger` solves
+ * this by:
+ * 1. Buffering all log calls in memory during the boot phase.
+ * 2. When {@link BootLogger.ready | ready()} is called with the real
+ *    logger, replaying all buffered entries and then forwarding all
+ *    subsequent calls directly.
+ *
+ * @example
+ * ```typescript
+ * // Create early, before the real logger exists
+ * const bootLogger = new BootLogger('detail');
+ * bootLogger.info('Starting up...');
+ *
+ * // Later, when the real logger is available
+ * bootLogger.ready(realLogger);
+ * // 'Starting up...' is replayed to realLogger
+ * // All future calls go directly to realLogger
+ * ```
+ *
+ * @public
+ */
+export class BootLogger {
+    /**
+     * Creates a new boot logger.
+     * @param logLevel - The log level for the initial in-memory buffer phase.
+     * Defaults to 'detail' to capture everything during boot.
+     */
+    constructor(logLevel) {
+        this._buffer = [];
+        this._isReady = false;
+        this._delegate = new InMemoryLogger(logLevel !== null && logLevel !== void 0 ? logLevel : 'detail');
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.logLevel}
+     */
+    get logLevel() {
+        return this._delegate.logLevel;
+    }
+    /**
+     * Whether the boot logger has been connected to a real logger.
+     */
+    get isReady() {
+        return this._isReady;
+    }
+    /**
+     * Connects this boot logger to a real logger.
+     * All buffered entries are replayed to the new logger in order,
+     * and all subsequent calls are forwarded directly.
+     * @param logger - The real logger to forward to.
+     */
+    ready(logger) {
+        // Replay buffered entries
+        for (const entry of this._buffer) {
+            logger.log(entry.level, entry.message, ...entry.parameters);
+        }
+        // Switch to the real logger and discard the buffer
+        this._delegate = logger;
+        this._buffer = [];
+        this._isReady = true;
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.log}
+     */
+    log(level, message, ...parameters) {
+        if (!this._isReady) {
+            this._buffer.push({ level, message, parameters });
+        }
+        return this._delegate.log(level, message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.detail}
+     */
+    detail(message, ...parameters) {
+        return this.log('detail', message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.info}
+     */
+    info(message, ...parameters) {
+        return this.log('info', message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.warn}
+     */
+    warn(message, ...parameters) {
+        return this.log('warning', message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.error}
+     */
+    error(message, ...parameters) {
+        return this.log('error', message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+     */
+    errorWithDetail(message, detail) {
+        if (isDetailLogger(this._delegate)) {
+            return this._delegate.errorWithDetail(message, detail);
+        }
+        this.log('detail', detail);
+        return this.log('error', message);
+    }
+    /**
+     * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+     */
+    warnWithDetail(message, detail) {
+        if (isDetailLogger(this._delegate)) {
+            return this._delegate.warnWithDetail(message, detail);
+        }
+        this.log('detail', detail);
+        return this.log('warning', message);
+    }
+}
+//# sourceMappingURL=bootLogger.js.map

package/dist/packlets/logging/index.js

@@ -19,6 +19,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
+export * from './bootLogger';
 export * from './logger';
 export * from './logReporter';
 //# sourceMappingURL=index.js.map

package/dist/packlets/logging/logReporter.js

@@ -19,7 +19,8 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { NoOpLogger, stringifyLogValue } from './logger';
+import { isDetailLogger, NoOpLogger, stringifyLogValue } from './logger';
+import { captureResult } from '../base';
 /**
  * Abstract base class which wraps an existing {@link Logging.ILogger | ILogger} to implement
  * both {@link Logging.ILogger | ILogger} and {@link IResultReporter | IResultReporter}.
@@ -38,6 +39,16 @@ export class LogReporter {
         this._valueFormatter = (_b = params.valueFormatter) !== null && _b !== void 0 ? _b : LogReporter.tryFormatObject;
         this._messageFormatter = (_c = params.messageFormatter) !== null && _c !== void 0 ? _c : ((message, __detail) => message);
     }
+    /**
+     * Creates a default {@link Logging.LogReporter | LogReporter} with a {@link Logging.NoOpLogger | NoOpLogger} with the
+     * supplied parameters, returning both the logger and reporter.
+     * @param logger - Optional logger to use; defaults to a new {@link Logging.NoOpLogger | NoOpLogger} if not provided.
+     * @returns
+     */
+    static createDefault(logger) {
+        logger = logger !== null && logger !== void 0 ? logger : new NoOpLogger();
+        return captureResult(() => new LogReporter({ logger }));
+    }
     /**
      * {@inheritDoc Logging.ILogger.logLevel}
      */
@@ -68,6 +79,26 @@ export class LogReporter {
     error(message, ...parameters) {
         return this.logger.error(message, ...parameters);
     }
+    /**
+     * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+     */
+    errorWithDetail(message, detail) {
+        if (isDetailLogger(this.logger)) {
+            return this.logger.errorWithDetail(message, detail);
+        }
+        this.logger.detail(detail);
+        return this.logger.error(message);
+    }
+    /**
+     * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+     */
+    warnWithDetail(message, detail) {
+        if (isDetailLogger(this.logger)) {
+            return this.logger.warnWithDetail(message, detail);
+        }
+        this.logger.detail(detail);
+        return this.logger.warn(message);
+    }
     /**
      * {@inheritDoc Logging.ILogger.log}
      */

package/dist/packlets/logging/logger.js

@@ -70,7 +70,17 @@ export function stringifyLogValue(value, maxLength) {
     return str;
 }
 /**
- * Abstract base class which implements {@link Logging.ILogger | ILogger}.
+ * Type guard that checks whether a logger implements {@link IDetailLogger}.
+ * @param logger - The logger to check.
+ * @returns `true` if the logger implements `IDetailLogger`.
+ * @public
+ */
+export function isDetailLogger(logger) {
+    return (typeof logger.errorWithDetail === 'function' &&
+        typeof logger.warnWithDetail === 'function');
+}
+/**
+ * Abstract base class which implements {@link Logging.IDetailLogger | IDetailLogger}.
  * @public
  */
 export class LoggerBase {
@@ -105,6 +115,20 @@ export class LoggerBase {
     error(message, ...parameters) {
         return this.log('error', message, ...parameters);
     }
+    /**
+     * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+     */
+    errorWithDetail(message, detail) {
+        this.detail(detail);
+        return this.error(message);
+    }
+    /**
+     * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+     */
+    warnWithDetail(message, detail) {
+        this.detail(detail);
+        return this.warn(message);
+    }
     /**
      * {@inheritDoc Logging.ILogger.log}
      */
@@ -188,10 +212,6 @@ export class InMemoryLogger extends LoggerBase {
     }
     /**
      * {@inheritDoc Logging.LoggerBase._suppressLog}
-     * @param level - The level of the message.
-     * @param message - The message to suppress.
-     * @param parameters - The parameters to suppress.
-     * @returns `Success` with `undefined` if the message is suppressed.
      * @internal
      */
     _suppressLog(level, message, ...parameters) {

package/dist/packlets/validation/classes.js

@@ -22,6 +22,7 @@
 /* c8 ignore start */
 export { ArrayValidator } from './array';
 export { BooleanValidator } from './boolean';
+export { CompositeIdValidator } from './compositeId';
 export { NumberValidator } from './number';
 export { ObjectValidator } from './object';
 export { OneOfValidator } from './oneOf';

package/dist/packlets/validation/compositeId.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2026 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 { Failure, fail } from '../base';
+import { ValidatorBase } from './validatorBase';
+/**
+ * An in-place {@link Validation.Validator | Validator} for a strongly-typed composite ID.
+ * @public
+ */
+export class CompositeIdValidator extends ValidatorBase {
+    /**
+     * Constructs a new {@link Validation.Classes.StringValidator | StringValidator}.
+     * @param params - Optional {@link Validation.Classes.StringValidatorConstructorParams | init params}
+     * for the new {@link Validation.Classes.StringValidator | StringValidator}.
+     */
+    constructor(params) {
+        /* c8 ignore next */
+        super(Object.assign({}, params));
+        const { collectionId, separator, itemId } = params;
+        this._collectionIdValidator = collectionId.withFormattedError((value, err) => `${value}: invalid composite collection ID (${err}).`);
+        this._itemIdValidator = itemId.withFormattedError((value, err) => `${value}: invalid composite item ID (${err}).`);
+        this._separator = separator;
+    }
+    _validate(value, context) {
+        if (typeof value !== 'string') {
+            return fail(`${value}: invalid non-string composite ID.`);
+        }
+        const parts = value.split(this._separator);
+        if (parts.length < 2) {
+            return fail(`${value}: invalid composite ID - separator '${this._separator}' not found.`);
+        }
+        else if (parts.length > 2) {
+            return fail(`${value}: invalid composite ID - multiple separators '${this._separator}.' found.`);
+        }
+        const [collectionId, itemId] = parts;
+        const result = this._collectionIdValidator
+            .validate(collectionId, context)
+            .onSuccess(() => this._itemIdValidator.validate(itemId, context));
+        return result.isSuccess() ? true : Failure.with(`${value}: invalid composite ID - ${result.message}`);
+    }
+}
+//# sourceMappingURL=compositeId.js.map

package/dist/packlets/validation/field.js

@@ -43,7 +43,7 @@ export class FieldValidator extends ValidatorBase {
         this._fieldOptions = options !== null && options !== void 0 ? options : {};
     }
     /**
-     * {@inheritdoc Validation.ValidatorBase._validate}
+     * {@inheritDoc Validation.ValidatorBase._validate}
      */
     _validate(from, context, self) {
         if (typeof from === 'object' && !Array.isArray(from) && from !== null) {

package/dist/packlets/validation/genericValidator.js

@@ -41,19 +41,19 @@ export class GenericValidator {
         this.traits = new ValidatorTraits(params.traits);
     }
     /**
-     * {@inheritdoc Validation.Validator.isOptional}
+     * {@inheritDoc Validation.Validator.isOptional}
      */
     get isOptional() {
         return this.traits.isOptional;
     }
     /**
-     * {@inheritdoc Validation.Validator.brand}
+     * {@inheritDoc Validation.Validator.brand}
      */
     get brand() {
         return this.traits.brand;
     }
     /**
-     * {@inheritdoc Validation.Validator.validate}
+     * {@inheritDoc Validation.Validator.validate}
      */
     validate(from, context) {
         const result = this._validator(from, this._context(context), this);
@@ -63,7 +63,7 @@ export class GenericValidator {
         return result;
     }
     /**
-     * {@inheritdoc Validation.Validator.convert}
+     * {@inheritDoc Validation.Validator.convert}
      */
     convert(from, context) {
         const result = this._validator(from, this._context(context), this);
@@ -73,19 +73,19 @@ export class GenericValidator {
         return result;
     }
     /**
-     * {@inheritdoc Validation.Validator.validateOptional}
+     * {@inheritDoc Validation.Validator.validateOptional}
      */
     validateOptional(from, context) {
         return from === undefined ? succeed(undefined) : this.validate(from, context);
     }
     /**
-     * {@inheritdoc Validation.Validator.guard}
+     * {@inheritDoc Validation.Validator.guard}
      */
     guard(from, context) {
         return this._validator(from, this._context(context), this) === true;
     }
     /**
-     * {@inheritdoc Validation.Validator.optional}
+     * {@inheritDoc Validation.Validator.optional}
      */
     optional() {
         return new GenericValidator({
@@ -96,7 +96,7 @@ export class GenericValidator {
         });
     }
     /**
-     * {@inheritdoc Validation.Validator.withConstraint}
+     * {@inheritDoc Validation.Validator.withConstraint}
      */
     withConstraint(constraint, trait) {
         trait = trait !== null && trait !== void 0 ? trait : { type: 'function' };
@@ -118,7 +118,7 @@ export class GenericValidator {
         });
     }
     /**
-     * {@inheritdoc Validation.Validator.brand}
+     * {@inheritDoc Validation.Validator.brand}
      */
     withBrand(brand) {
         if (this.brand) {
@@ -132,7 +132,7 @@ export class GenericValidator {
         });
     }
     /**
-     * {@inheritdoc Validation.Validator.withFormattedError}
+     * {@inheritDoc Validation.Validator.withFormattedError}
      */
     withFormattedError(formatter) {
         return new GenericValidator({
@@ -147,6 +147,20 @@ export class GenericValidator {
             }
         });
     }
+    /**
+     * {@inheritDoc Validation.Validator.or}
+     */
+    or(other) {
+        return new GenericValidator({
+            validator: (from, context, __self) => {
+                if (this._validator(from, this._context(context), this) === true) {
+                    return true;
+                }
+                const otherResult = other.validate(from, this._context(context));
+                return otherResult.isSuccess() ? true : otherResult;
+            }
+        });
+    }
     /**
      * Gets a default or explicit context.
      * @param explicitContext - Optional explicit context.

package/dist/packlets/validation/object.js

@@ -33,10 +33,7 @@ import { FieldValidator } from './field';
 export class ObjectValidator extends ValidatorBase {
     /**
      * Constructs a new {@link Validation.Classes.ObjectValidator | ObjectValidator<T>}.
-     * @param fields - A {@link Validation.Classes.FieldValidators | FieldValidators<T>} containing
-     * a {@link Validation.Validator | Validator} for each field.
-     * @param options - An optional {@link Validation.Classes.ObjectValidatorOptions} to configure
-     * validation.
+     * @param params - Construction parameters including field validators and options.
      */
     constructor(params) {
         var _a;
@@ -92,7 +89,7 @@ export class ObjectValidator extends ValidatorBase {
     /**
      * Creates a new {@link Validation.Classes.ObjectValidator | ObjectValidator} derived from this one but with
      * new optional properties as specified by a supplied array of `keyof T`.
-     * @param addOptionalProperties - The keys to be made optional.
+     * @param addOptionalFields - The keys to be made optional.
      * @returns A new {@link Validation.Classes.ObjectValidator | ObjectValidator} with the additional optional
      * source properties.
      */
@@ -103,7 +100,7 @@ export class ObjectValidator extends ValidatorBase {
         });
     }
     /**
-     * {@inheritdoc Validation.ValidatorBase._validate}
+     * {@inheritDoc Validation.ValidatorBase._validate}
      * @internal
      */
     _validate(from, context, self) {

package/dist/packlets/validation/validators.js

@@ -21,6 +21,7 @@
  */
 import { fail, isKeyOf, MessageAggregator } from '../base';
 import { ArrayValidator } from './array';
+import { CompositeIdValidator } from './compositeId';
 import { ObjectValidator } from './object';
 import { TypeGuardValidator } from './typeGuard';
 import { BooleanValidator } from './boolean';
@@ -152,6 +153,17 @@ export function literal(value) {
         }
     });
 }
+/** Helper function to create a {@link Validation.Validator | Validator} which validates a
+ * strongly-typed composite ID.
+ * @param params - {@link Validation.Classes.CompositeIdValidatorConstructorParams | params}
+ * used to construct the validator.
+ * @returns A new {@link Validation.Validator | Validator} which validates the desired
+ * composite ID in place.
+ * @public
+ */
+export function compositeId(params) {
+    return new CompositeIdValidator(params);
+}
 /**
  * Helper function to create a {@link Validation.Validator | Validator} which validates one
  * of several possible validated values.