@fgv/ts-utils 5.0.0-3 → 5.0.0-30

package/CHANGELOG.json

@@ -1,27 +1,6 @@
 {
   "name": "@fgv/ts-utils",
   "entries": [
-    {
-      "version": "5.0.0",
-      "tag": "@fgv/ts-utils_v5.0.0",
-      "date": "Thu, 17 Jul 2025 00:13:24 GMT",
-      "comments": {
-        "none": [
-          {
-            "comment": "add result helpers, clean up object converter"
-          },
-          {
-            "comment": "object converter partial/required helpers"
-          },
-          {
-            "comment": "add Result.withErrorFormat"
-          },
-          {
-            "comment": "bump version"
-          }
-        ]
-      }
-    },
     {
       "version": "4.6.0",
       "tag": "@fgv/ts-utils_v4.6.0",

package/dist/ts-utils.d.ts

@@ -58,10 +58,11 @@ declare class ArrayValidator<T, TC = unknown> extends ValidatorBase<T[], TC> {
      * validator.
      * @param from - The `unknown` value to be tested.
      * @param context - Optional validation context will be propagated to element validator.
+     * @param self - Optional self-reference for recursive validation.
      * @returns Returns `true` if `from` is an `array` of valid elements, or
      * {@link Failure} with an error message if not.
      */
-    protected _validate<T>(from: unknown, context?: TC): boolean | Failure<T>;
+    protected _validate(from: unknown, context?: TC, self?: Validator<T[], TC>): boolean | Failure<T[]>;
 }
 
 /**
@@ -74,7 +75,6 @@ declare interface ArrayValidatorConstructorParams<T, TC = unknown> extends Valid
 
 declare namespace Base {
     export {
-        ValidatorFunc,
         GenericValidatorConstructorParams,
         GenericValidator
     }
@@ -490,6 +490,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            * {@inheritdoc Collections.ResultMap.values}
            */
           values(): IterableIterator<TITEM>;
+          /**
+           * {@inheritdoc Collections.IReadOnlyCollector.valuesByIndex}
+           */
+          valuesByIndex(): ReadonlyArray<TITEM>;
           /**
            * Gets a read-only version of this collector.
            */
@@ -559,6 +563,23 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            protected _convertValue(value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
           }
 
+          /**
+           * A console logger that outputs messages to the console.
+           * @public
+           */
+          declare class ConsoleLogger extends LoggerBase {
+              /**
+               * Creates a new console logger.
+               * @param logLevel - The level of logging to be used.
+               */
+              constructor(logLevel?: ReporterLogLevel);
+              /**
+               * {@inheritDoc Logging.LoggerBase._log}
+               * @internal
+               */
+              protected _log(message: string, level: MessageLogLevel): Success<string | undefined>;
+          }
+
           /**
            * A {@link Validation.Constraint | Constraint<T>} function returns
            * `true` if the supplied value meets the constraint. Can return
@@ -1080,6 +1101,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@inheritdoc IResult.withErrorFormat}
                */
               withErrorFormat(cb: ErrorFormatter<TD>): DetailedResult<T, TD>;
+              /**
+               * {@inheritdoc IResult.report}
+               */
+              report(reporter?: IResultReporter<T, TD>, options?: IResultReportOptions<TD>): this;
               orThrow(logOrFormat?: IResultLogger<TD> | ErrorFormatter<TD>): never;
               orThrow(cb: ErrorFormatter): never;
               /**
@@ -1168,6 +1193,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@inheritdoc Success.withErrorFormat}
                */
               withErrorFormat(cb: ErrorFormatter): DetailedResult<T, TD>;
+              /**
+               * {@inheritdoc IResult.report}
+               */
+              report(reporter?: IResultReporter<T, TD>, options?: IResultReportOptions<TD>): this;
               /**
                * Creates a {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied value and
                * optional detail.
@@ -1409,6 +1438,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@inheritdoc IResult.aggregateError}
                */
               aggregateError(errors: IMessageAggregator): this;
+              /**
+               * {@inheritdoc IResult.report}
+               */
+              report(reporter?: IResultReporter<T>, options?: IResultReportOptions): this;
               /**
                * Get a 'friendly' string representation of this object.
                * @remarks
@@ -2204,6 +2237,68 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                value: Validator<TV, unknown> | Converter<TV, unknown> | ConverterFunc<TV, unknown>;
                            }
 
+                           /**
+                            * Generic Result-aware logger interface with multiple levels of logging.
+                            * @public
+                            */
+                           declare interface ILogger {
+                               /**
+                                * The level of logging to be used.
+                                */
+                               readonly logLevel: ReporterLogLevel;
+                               /**
+                                * Logs a message at the given level.
+                                * @param level - The level of the message.
+                                * @param message - The message to log.
+                                * @param parameters - The parameters to log.
+                                * @returns `Success` with the logged message if the level is enabled, or
+                                * `Success` with `undefined` if the message is suppressed.
+                                */
+                               log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                               /**
+                                * Logs a detail message.
+                                * @param message - The message to log.
+                                * @param parameters - The parameters to log.
+                                * @returns `Success` with the logged message if the level is enabled, or
+                                * `Success` with `undefined` if the message is suppressed.
+                                */
+                               detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                               /**
+                                * Logs an info message.
+                                * @param message - The message to log.
+                                * @param parameters - The parameters to log.
+                                * @returns `Success` with the logged message if the level is enabled, or
+                                * `Success` with `undefined` if the message is suppressed.
+                                */
+                               info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                               /**
+                                * Logs a warning message.
+                                * @param message - The message to log.
+                                * @param parameters - The parameters to log.
+                                * @returns `Success` with the logged message if the level is enabled, or
+                                * `Success` with `undefined` if the message is suppressed.
+                                */
+                               warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                               /**
+                                * Logs an error message.
+                                * @param message - The message to log.
+                                * @param parameters - The parameters to log.
+                                * @returns `Success` with the logged message if the level is enabled, or
+                                * `Success` with `undefined` if the message is suppressed.
+                                */
+                               error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                           }
+
+                           /**
+                            * Parameters for creating a {@link Logging.LogReporter | LogReporter}.
+                            * @public
+                            */
+                           declare interface ILogReporterCreateParams<T, TD = unknown> {
+                               logger?: ILogger;
+                               valueFormatter?: LogValueFormatter<T, TD>;
+                               messageFormatter?: LogMessageFormatter<TD>;
+                           }
+
                            /**
                             * Simple error aggregator to simplify collecting all errors in
                             * a flow.
@@ -2263,17 +2358,51 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                             declare function inMemory(files: IInMemoryFile[], prefix?: string): Result<FileTree_2>;
 
                             /**
+                             * An in-memory logger that stores logged and suppressed messages.
                              * @public
                              */
                             declare class InMemoryLogger extends LoggerBase {
-                                protected _messages: string[];
-                                protected _silent: string[];
-                                constructor(logLevel?: LogLevel);
-                                get messages(): string[];
-                                get silent(): string[];
+                                /**
+                                 * The messages that have been logged.
+                                 * @internal
+                                 */
+                                private _logged;
+                                /**
+                                 * The messages that have been suppressed.
+                                 * @internal
+                                 */
+                                private _suppressed;
+                                /**
+                                 * Creates a new in-memory logger.
+                                 * @param logLevel - The level of logging to be used.
+                                 */
+                                constructor(logLevel?: ReporterLogLevel);
+                                /**
+                                 * The messages that have been logged.
+                                 */
+                                get logged(): string[];
+                                /**
+                                 * The messages that have been suppressed.
+                                 */
+                                get suppressed(): string[];
+                                /**
+                                 * Clears the logged and suppressed messages.
+                                 */
                                 clear(): void;
-                                protected _innerLog(message: string): Success<string | undefined>;
-                                protected _innerSilent(message: string): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc Logging.LoggerBase._log}
+                                 * @internal
+                                 */
+                                protected _log(message: string, __level: MessageLogLevel): Success<string | undefined>;
+                                /**
+                                 * {@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
+                                 */
+                                protected _suppressLog(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<undefined>;
                             }
 
                             /**
@@ -2344,6 +2473,11 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                  * with an error if the index is out of range.
                                  */
                                 getAt(index: number): Result<TITEM>;
+                                /**
+                                 * Gets all items in the collection, ordered by index.
+                                 * @returns An array of items in the collection, ordered by index.
+                                 */
+                                valuesByIndex(): ReadonlyArray<TITEM>;
                             }
 
                             /**
@@ -2444,7 +2578,11 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                 /**
                                  * {@inheritdoc Collections.IReadOnlyValidatingCollector.getAt}
                                  */
-                                readonly getAt: (index: number) => Result<TITEM>;
+                                getAt(index: number): Result<TITEM>;
+                                /**
+                                 * {@inheritdoc Collections.IReadOnlyCollector.valuesByIndex}
+                                 */
+                                valuesByIndex(): ReadonlyArray<TITEM>;
                             }
 
                             /**
@@ -2634,6 +2772,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                  * errors will be aggregated.
                                  */
                                 aggregateError(errors: IMessageAggregator): this;
+                                /**
+                                 * Reports the result to the supplied reporter
+                                 * @param reporter - The {@link IResultReporter | reporter} to which the result will be reported.
+                                 * @param options - The {@link IResultReportOptions | options} for reporting the result.
+                                 */
+                                report(reporter?: IResultReporter<T>, options?: IResultReportOptions): this;
                             }
 
                             /**
@@ -2665,6 +2809,34 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                 converters: KeyValueConverters<TK, TV>;
                             }
 
+                            /**
+                             * Interface for reporting a result.
+                             * @public
+                             */
+                            export declare interface IResultReporter<T, TD = unknown> {
+                                reportSuccess(level: MessageLogLevel, value: T, detail?: TD): void;
+                                reportFailure(level: MessageLogLevel, message: string, detail?: TD): void;
+                            }
+
+                            /**
+                             * Options for reporting a result.
+                             * @public
+                             */
+                            export declare interface IResultReportOptions<TD = unknown> {
+                                /**
+                                 * The level of reporting to be used for failure results.  Default is 'error'.
+                                 */
+                                failure?: MessageLogLevel;
+                                /**
+                                 * The level of reporting to be used for success results.  Default is 'quiet'.
+                                 */
+                                success?: MessageLogLevel;
+                                /**
+                                 * The error formatter to be used for reporting an error result.
+                                 */
+                                message?: ErrorFormatter<TD>;
+                            }
+
                             /**
                              * 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
@@ -2850,49 +3022,153 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                             declare function literal_2<T extends string | number | boolean | symbol | null | undefined>(value: T): Validator<T>;
 
                             /**
+                             * Abstract base class which implements {@link Logging.ILogger | ILogger}.
                              * @public
                              */
-                            declare interface Logger {
-                                log(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
-                                detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
-                                info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
-                                warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
-                                warnAndFail<T>(message?: unknown, ...parameters: unknown[]): Failure<T>;
-                                error<T>(message?: unknown, ...parameters: unknown[]): Failure<T>;
-                            }
-
-                            /**
-                             * @public
-                             */
-                            declare abstract class LoggerBase {
-                                logLevel: LogLevel;
-                                constructor(logLevel?: LogLevel);
+                            declare abstract class LoggerBase implements ILogger {
+                                /**
+                                 * {@inheritDoc Logging.ILogger.logLevel}
+                                 */
+                                logLevel: ReporterLogLevel;
+                                protected constructor(logLevel?: ReporterLogLevel);
+                                /**
+                                 * {@inheritDoc Logging.ILogger.detail}
+                                 */
                                 detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc Logging.ILogger.info}
+                                 */
                                 info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc Logging.ILogger.warn}
+                                 */
                                 warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
-                                warnAndFail<T>(message?: unknown, ...parameters: unknown[]): Failure<T>;
-                                error<T>(message?: unknown, ...parameters: unknown[]): Failure<T>;
-                                log(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc Logging.ILogger.error}
+                                 */
+                                error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc Logging.ILogger.log}
+                                 */
+                                log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * Formats a message and parameters into a string.
+                                 * @param message - The message to format.
+                                 * @param parameters - The parameters to format.
+                                 * @returns The formatted message.
+                                 * @public
+                                 */
                                 protected _format(message?: unknown, ...parameters: unknown[]): string;
-                                protected _innerSilent(__message: string): Success<string | undefined>;
-                                protected abstract _innerLog(message: string): Success<string | undefined>;
+                                /**
+                                 * Inner method called for suppressed log messages.
+                                 * @public
+                                 */
+                                protected _suppressLog(__level: MessageLogLevel, __message?: unknown, ...__parameters: unknown[]): Success<undefined>;
+                                /**
+                                 * Inner method called for logged messages. Should be implemented by derived classes.
+                                 * @param message - The message to log.
+                                 * @param level - The {@link MessageLogLevel | level} of the message.
+                                 * @returns `Success` with the logged message, or `Success` with `undefined` if the message is suppressed.
+                                 * @public
+                                 */
+                                protected abstract _log(message: string, level: MessageLogLevel): Success<string | undefined>;
                             }
 
                             declare namespace Logging {
                                 export {
-                                    LogLevel,
-                                    Logger,
+                                    shouldLog,
+                                    ReporterLogLevel,
+                                    ILogger,
                                     LoggerBase,
                                     InMemoryLogger,
-                                    NoOpLogger
+                                    ConsoleLogger,
+                                    NoOpLogger,
+                                    LogValueFormatter,
+                                    LogMessageFormatter,
+                                    ILogReporterCreateParams,
+                                    LogReporter
                                 }
                             }
                             export { Logging }
 
                             /**
+                             * A function that formats a message for logging.
                              * @public
                              */
-                            declare type LogLevel = 'detail' | 'info' | 'warning' | 'error' | 'silent';
+                            declare type LogMessageFormatter<TD = unknown> = (message: string, detail?: TD) => string;
+
+                            /**
+                             * Abstract base class which wraps an existing {@link Logging.ILogger | ILogger} to implement
+                             * both {@link Logging.ILogger | ILogger} and {@link IResultReporter | IResultReporter}.
+                             * @public
+                             */
+                            declare class LogReporter<T, TD = unknown> implements ILogger, IResultReporter<T, TD> {
+                                /**
+                                 * The logger to wrap.
+                                 * @internal
+                                 */
+                                protected readonly _logger: ILogger;
+                                /**
+                                 * The formatter to use for values.
+                                 * @internal
+                                 */
+                                protected readonly _valueFormatter: LogValueFormatter<T, TD>;
+                                /**
+                                 * The formatter to use for messages.
+                                 * @internal
+                                 */
+                                protected readonly _messageFormatter: LogMessageFormatter<TD>;
+                                /**
+                                 * Creates a new {@link Logging.LogReporter | LogReporter}.
+                                 * @param params - The parameters for creating the {@link Logging.LogReporter | LogReporter}.
+                                 */
+                                constructor(params?: ILogReporterCreateParams<T, TD>);
+                                /**
+                                 * {@inheritDoc Logging.ILogger.logLevel}
+                                 */
+                                get logLevel(): ReporterLogLevel;
+                                /**
+                                 * {@inheritDoc Logging.ILogger.detail}
+                                 */
+                                detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc Logging.ILogger.info}
+                                 */
+                                info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc Logging.ILogger.warn}
+                                 */
+                                warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc Logging.ILogger.error}
+                                 */
+                                error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc Logging.ILogger.log}
+                                 */
+                                log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                                /**
+                                 * {@inheritDoc IResultReporter.reportSuccess}
+                                 */
+                                reportSuccess(level: MessageLogLevel, value: T, detail?: TD): void;
+                                /**
+                                 * {@inheritDoc IResultReporter.reportFailure}
+                                 */
+                                reportFailure(level: MessageLogLevel, message: string, detail?: TD): void;
+                                /**
+                                 * Generic method to try to format an object for logging.
+                                 * @param value - The value to format.
+                                 * @param detail - The detail to format.
+                                 * @returns
+                                 */
+                                static tryFormatObject<T = unknown, TD = unknown>(value: T, detail?: TD): string;
+                            }
+
+                            /**
+                             * A function that formats a value for logging.
+                             * @public
+                             */
+                            declare type LogValueFormatter<T, TD = unknown> = (value: T, detail?: TD) => string;
 
                             /**
                              * Aggregates successful results from a collection of {@link DetailedResult | DetailedResult<T, TD>},
@@ -3078,10 +3354,26 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                    }
 
                                    /**
+                                    * The severity level at which a message should be logged.
+                                    * @public
+                                    */
+                                   export declare type MessageLogLevel = 'quiet' | 'detail' | 'info' | 'warning' | 'error';
+
+                                   /**
+                                    * A no-op {@link Logging.LoggerBase | LoggerBase} that does not log anything.
                                     * @public
                                     */
                                    declare class NoOpLogger extends LoggerBase {
-                                       protected _innerLog(message: string): Success<string | undefined>;
+                                       /**
+                                        * Creates a new no-op logger.
+                                        * @param logLevel - The level of logging to be used.
+                                        */
+                                       constructor(logLevel?: ReporterLogLevel);
+                                       /**
+                                        * {@inheritDoc Logging.LoggerBase._log}
+                                        * @internal
+                                        */
+                                       protected _log(message: string, __level: MessageLogLevel): Success<string | undefined>;
                                    }
 
                                    /**
@@ -3420,7 +3712,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                         * {@inheritdoc Validation.ValidatorBase._validate}
                                         * @internal
                                         */
-                                       protected _validate(from: unknown, context?: TC): boolean | Failure<T>;
+                                       protected _validate(from: unknown, context?: TC, self?: Validator<T, TC>): boolean | Failure<T>;
                                    }
 
                                    /**
@@ -3522,10 +3814,11 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                         * of the configured validators.
                                         * @param from - The `unknown` value to be tested.
                                         * @param context - Optional validation context will be propagated to element validator.
+                                        * @param self - Optional self-reference for recursive validation.
                                         * @returns Returns `true` if `from` is an `array` of valid elements, or
                                         * {@link Failure} with an error message if not.
                                         */
-                                       protected _validate<T>(from: unknown, context?: TC): boolean | Failure<T>;
+                                       protected _validate<T>(from: unknown, context?: TC, self?: Validator<T, TC>): boolean | Failure<T>;
                                    }
 
                                    /**
@@ -3780,6 +4073,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                             */
                                         export declare function recordToMap<TS, TD, TK extends string = string>(src: Record<TK, TS>, factory: KeyedThingFactory<TS, TD, TK>): Result<Map<TK, TD>>;
 
+                                        /**
+                                         * The level of logging to be used.
+                                         * @public
+                                         */
+                                        declare type ReporterLogLevel = 'all' | 'detail' | 'info' | 'warning' | 'error' | 'silent';
+
                                         /**
                                          * Represents the {@link IResult | result} of some operation or sequence of operations.
                                          * @remarks
@@ -4040,6 +4339,15 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                          */
                                         export declare type ResultValueType<T> = T extends Result<infer TV> ? TV : never;
 
+                                        /**
+                                         * Compares two log levels.
+                                         * @param message - The first log level.
+                                         * @param reporter - The second log level.
+                                         * @returns `true` if the message should be logged, `false` if it should be suppressed.
+                                         * @public
+                                         */
+                                        declare function shouldLog(message: MessageLogLevel, reporter: ReporterLogLevel): boolean;
+
                                         /**
                                          * Helper function to create a {@link Conversion.ObjectConverter | ObjectConverter} which converts an object
                                          * without changing shape, a {@link Conversion.FieldConverters | FieldConverters<T, TC>} and an optional
@@ -4335,6 +4643,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                                     * {@inheritdoc IResult.aggregateError}
                                                     */
                                                    aggregateError(__errors: IMessageAggregator): this;
+                                                   /**
+                                                    * {@inheritdoc IResult.report}
+                                                    */
+                                                   report(reporter?: IResultReporter<T>, options?: IResultReportOptions): this;
                                                    /**
                                                     * Creates a {@link Success | Success<T>} with the supplied value.
                                                     * @param value - The value to be returned.
@@ -4439,11 +4751,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                                     * type guard, returning a `Failure<T>` containing more information about a failure.
                                                     * @param from - Value to be converted.
                                                     * @param context - Optional validation context.
+                                                    * @param self - Optional self-reference for recursive validation.
                                                     * @returns `true` if `from` is valid, {@link Failure | Failure<T>}
                                                     * with an error message if `from` is invalid.
                                                     * @internal
                                                     */
-                                                   protected _validate(from: unknown, context?: TC): boolean | Failure<T>;
+                                                   protected _validate(from: unknown, context?: TC, self?: Validator<T, TC>): boolean | Failure<T>;
                                                }
 
                                                /**
@@ -4462,6 +4775,15 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                                 */
                                                declare type TypeGuardWithContext<T, TC = unknown> = (from: unknown, context?: TC) => from is T;
 
+                                               /**
+                                                * Uses a value or calls a supplied initializer if the supplied value is undefined.
+                                                * @param value - the value
+                                                * @param initializer - a function that initializes the value if it is undefined
+                                                * @returns `Success` with the value if it is defined, or the result of calling the initializer function.
+                                                * @public
+                                                */
+                                               export declare function useOrInitialize<T>(value: T | undefined, initializer: () => Result<T>): Result<T>;
+
                                                declare namespace Utils {
                                                    export {
                                                        isIterable
@@ -4592,12 +4914,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                                                Classes,
                                                                Validators,
                                                                TypeGuardWithContext,
-                                                               ValidatorFunc,
                                                                FunctionConstraintTrait,
                                                                ConstraintTrait,
                                                                ValidatorTraitValues,
                                                                defaultValidatorTraits,
                                                                ValidatorTraits,
+                                                               ValidatorFunc,
                                                                ValidatorOptions,
                                                                Constraint,
                                                                ValidationErrorFormatter,
@@ -4713,11 +5035,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                                                   * Abstract validation method to me implemented by derived classes.
                                                                   * @param from - Value to be converted.
                                                                   * @param context - Optional validation context.
+                                                                  * @param self - Optional self-reference for recursive validation.
                                                                   * @returns `true` if `from` is valid, {@link Failure | Failure<T>}
                                                                   * with an error message if `from` is invalid.
                                                                   * @internal
                                                                   */
-                                                                 protected abstract _validate(from: unknown, context?: TC): boolean | Failure<T>;
+                                                                 protected abstract _validate(from: unknown, context?: TC, self?: Validator<T, TC>): boolean | Failure<T>;
                                                              }
 
                                                              /**
@@ -4731,7 +5054,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                                               * an optionally-supplied validation context of type `<TC>`.
                                                               * @public
                                                               */
-                                                             declare type ValidatorFunc<T, TC> = (from: unknown, context?: TC) => boolean | Failure<T>;
+                                                             declare type ValidatorFunc<T, TC> = (from: unknown, context?: TC, self?: Validator<T, TC>) => boolean | Failure<T>;
 
                                                              /**
                                                               * Options that apply to any {@link Validation.Validator | Validator}.