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

package/lib/packlets/logging/logReporter.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogReporter = void 0;
+/*
+ * 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.
+ */
+const logger_1 = require("./logger");
+/**
+ * Abstract base class which wraps an existing {@link Logging.ILogger | ILogger} to implement
+ * both {@link Logging.ILogger | ILogger} and {@link IResultReporter | IResultReporter}.
+ * @public
+ */
+class LogReporter {
+    /**
+     * Creates a new {@link Logging.LogReporter | LogReporter}.
+     * @param params - The parameters for creating the {@link Logging.LogReporter | LogReporter}.
+     */
+    constructor(params) {
+        var _a, _b, _c;
+        /* c8 ignore next 1 */
+        params = params !== null && params !== void 0 ? params : {};
+        this._logger = (_a = params.logger) !== null && _a !== void 0 ? _a : new logger_1.NoOpLogger();
+        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);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.logLevel}
+     */
+    get logLevel() {
+        return this._logger.logLevel;
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.detail}
+     */
+    detail(message, ...parameters) {
+        return this._logger.detail(message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.info}
+     */
+    info(message, ...parameters) {
+        return this._logger.info(message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.warn}
+     */
+    warn(message, ...parameters) {
+        return this._logger.warn(message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.error}
+     */
+    error(message, ...parameters) {
+        return this._logger.error(message, ...parameters);
+    }
+    /**
+     * {@inheritDoc Logging.ILogger.log}
+     */
+    log(level, message, ...parameters) {
+        return this._logger.log(level, message, ...parameters);
+    }
+    /**
+     * {@inheritDoc IResultReporter.reportSuccess}
+     */
+    reportSuccess(level, value, detail) {
+        const formatted = this._valueFormatter(value, detail);
+        this.log(level, formatted);
+    }
+    /**
+     * {@inheritDoc IResultReporter.reportFailure}
+     */
+    reportFailure(level, message, detail) {
+        const formatted = this._messageFormatter(message, detail);
+        this.log(level, formatted);
+    }
+    /**
+     * 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(value, detail) {
+        const message = String(value);
+        if (message === '[object Object]') {
+            try {
+                return JSON.stringify(value);
+            }
+            catch (error) {
+                return message;
+            }
+        }
+        return message;
+    }
+}
+exports.LogReporter = LogReporter;
+//# sourceMappingURL=logReporter.js.map

package/lib/packlets/logging/logger.d.ts

@@ -0,0 +1,197 @@
+import { MessageLogLevel, Success } from '../base';
+/**
+ * The level of logging to be used.
+ * @public
+ */
+export type ReporterLogLevel = 'all' | 'detail' | 'info' | 'warning' | 'error' | 'silent';
+/**
+ * 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
+ */
+export declare function shouldLog(message: MessageLogLevel, reporter: ReporterLogLevel): boolean;
+/**
+ * Generic Result-aware logger interface with multiple levels of logging.
+ * @public
+ */
+export 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>;
+}
+/**
+ * Abstract base class which implements {@link Logging.ILogger | ILogger}.
+ * @public
+ */
+export 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>;
+    /**
+     * {@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;
+    /**
+     * 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>;
+}
+/**
+ * An in-memory logger that stores logged and suppressed messages.
+ * @public
+ */
+export declare class InMemoryLogger extends LoggerBase {
+    /**
+     * 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;
+    /**
+     * {@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>;
+}
+/**
+ * A console logger that outputs messages to the console.
+ * @public
+ */
+export 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 no-op {@link Logging.LoggerBase | LoggerBase} that does not log anything.
+ * @public
+ */
+export declare class NoOpLogger extends LoggerBase {
+    /**
+     * 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>;
+}
+//# sourceMappingURL=logger.d.ts.map

package/lib/packlets/logging/logger.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoOpLogger = exports.ConsoleLogger = exports.InMemoryLogger = exports.LoggerBase = void 0;
+exports.shouldLog = shouldLog;
+/*
+ * 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.
+ */
+const base_1 = require("../base");
+/**
+ * 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
+ */
+function shouldLog(message, reporter) {
+    if (reporter === 'all') {
+        return true; // 'all' logs everything, including 'quiet'
+    }
+    if (reporter === 'silent') {
+        return false; // 'silent' suppresses everything
+    }
+    if (message === 'quiet') {
+        return false; // 'quiet' messages only show when reporter is 'all'
+    }
+    switch (reporter) {
+        case 'error':
+            return message === 'error';
+        case 'warning':
+            return message === 'warning' || message === 'error';
+        case 'info':
+            return message !== 'detail';
+    }
+    return true;
+}
+/**
+ * Abstract base class which implements {@link Logging.ILogger | ILogger}.
+ * @public
+ */
+class LoggerBase {
+    constructor(logLevel) {
+        /**
+         * {@inheritDoc Logging.ILogger.logLevel}
+         */
+        this.logLevel = 'info';
+        this.logLevel = logLevel !== null && logLevel !== void 0 ? logLevel : 'info';
+    }
+    /**
+     * {@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.ILogger.log}
+     */
+    log(level, message, ...parameters) {
+        if (shouldLog(level, this.logLevel)) {
+            const formatted = this._format(message, ...parameters);
+            return this._log(formatted, level);
+        }
+        return this._suppressLog(level, message, ...parameters);
+    }
+    /**
+     * 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
+     */
+    _format(message, ...parameters) {
+        const raw = [message, ...parameters];
+        const filtered = raw.filter((m) => m !== undefined);
+        const strings = filtered.map((m) => m.toString());
+        const joined = strings.join('');
+        return joined;
+    }
+    /**
+     * Inner method called for suppressed log messages.
+     * @public
+     */
+    _suppressLog(__level, __message, ...__parameters) {
+        return (0, base_1.succeed)(undefined);
+    }
+}
+exports.LoggerBase = LoggerBase;
+/**
+ * An in-memory logger that stores logged and suppressed messages.
+ * @public
+ */
+class InMemoryLogger extends LoggerBase {
+    /**
+     * Creates a new in-memory logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel) {
+        super(logLevel);
+        /**
+         * The messages that have been logged.
+         * @internal
+         */
+        this._logged = [];
+        /**
+         * The messages that have been suppressed.
+         * @internal
+         */
+        this._suppressed = [];
+    }
+    /**
+     * The messages that have been logged.
+     */
+    get logged() {
+        return this._logged;
+    }
+    /**
+     * The messages that have been suppressed.
+     */
+    get suppressed() {
+        return this._suppressed;
+    }
+    /**
+     * Clears the logged and suppressed messages.
+     */
+    clear() {
+        this._logged = [];
+        this._suppressed = [];
+    }
+    /**
+     * {@inheritDoc Logging.LoggerBase._log}
+     * @internal
+     */
+    _log(message, __level) {
+        this._logged.push(message);
+        return (0, base_1.succeed)(message);
+    }
+    /**
+     * {@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) {
+        const formatted = this._format(message, ...parameters);
+        this._suppressed.push(formatted);
+        return (0, base_1.succeed)(undefined);
+    }
+}
+exports.InMemoryLogger = InMemoryLogger;
+/**
+ * A console logger that outputs messages to the console.
+ * @public
+ */
+class ConsoleLogger extends LoggerBase {
+    /**
+     * Creates a new console logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel) {
+        super(logLevel);
+    }
+    /**
+     * {@inheritDoc Logging.LoggerBase._log}
+     * @internal
+     */
+    _log(message, level) {
+        switch (level) {
+            case 'error':
+                console.error(message);
+                break;
+            case 'warning':
+                console.warn(message);
+                break;
+            case 'info':
+                console.info(message);
+                break;
+            default:
+                console.log(message);
+                break;
+        }
+        return (0, base_1.succeed)(message);
+    }
+}
+exports.ConsoleLogger = ConsoleLogger;
+/**
+ * A no-op {@link Logging.LoggerBase | LoggerBase} that does not log anything.
+ * @public
+ */
+class NoOpLogger extends LoggerBase {
+    /**
+     * Creates a new no-op logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel) {
+        super(logLevel);
+    }
+    /**
+     * {@inheritDoc Logging.LoggerBase._log}
+     * @internal
+     */
+    _log(message, __level) {
+        // no-op
+        return (0, base_1.succeed)(message);
+    }
+}
+exports.NoOpLogger = NoOpLogger;
+//# sourceMappingURL=logger.js.map

package/lib/packlets/validation/array.d.ts

@@ -32,9 +32,10 @@ export declare class ArrayValidator<T, TC = unknown> extends ValidatorBase<T[],
      * 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[]>;
 }
 //# sourceMappingURL=array.d.ts.map

package/lib/packlets/validation/array.js

@@ -47,10 +47,11 @@ class ArrayValidator extends validatorBase_1.ValidatorBase {
      * 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.
      */
-    _validate(from, context) {
+    _validate(from, context, self) {
         if (Array.isArray(from)) {
             for (const elem of from) {
                 const result = this._validateElement.validate(elem, context);

package/lib/packlets/validation/common.d.ts

@@ -1,15 +1,7 @@
-import { Failure } from '../base';
 /**
  * A type guard function which validates a specific type, with an optional context
  * that can be used to shape the validation.
  * @public
  */
 export type TypeGuardWithContext<T, TC = unknown> = (from: unknown, context?: TC) => from is T;
-/**
- * Type for a validation function, which validates that a supplied `unknown`
- * value is a valid value of type `<T>`, possibly as influenced by
- * an optionally-supplied validation context of type `<TC>`.
- * @public
- */
-export type ValidatorFunc<T, TC> = (from: unknown, context?: TC) => boolean | Failure<T>;
 //# sourceMappingURL=common.d.ts.map

package/lib/packlets/validation/field.d.ts

@@ -38,6 +38,6 @@ export declare class FieldValidator<T, TC = unknown> extends ValidatorBase<T, TC
     /**
      * {@inheritdoc Validation.ValidatorBase._validate}
      */
-    protected _validate(from: unknown, context?: TC): boolean | Failure<T>;
+    protected _validate(from: unknown, context?: TC, self?: Validator<T, TC>): boolean | Failure<T>;
 }
 //# sourceMappingURL=field.d.ts.map

package/lib/packlets/validation/field.js

@@ -48,7 +48,7 @@ class FieldValidator extends validatorBase_1.ValidatorBase {
     /**
      * {@inheritdoc Validation.ValidatorBase._validate}
      */
-    _validate(from, context) {
+    _validate(from, context, self) {
         if (typeof from === 'object' && !Array.isArray(from) && from !== null) {
             const optional = this._fieldOptions.optional === true;
             if ((0, base_1.isKeyOf)(this.fieldName, from)) {

package/lib/packlets/validation/genericValidator.d.ts

@@ -1,11 +1,6 @@
 import { Brand, Result } from '../base';
 import { ConstraintTrait, ValidatorTraits } from './traits';
-import { Constraint, ValidationErrorFormatter, Validator, ValidatorOptions } from './validator';
-import { ValidatorFunc } from './common';
-/**
- * @deprecated Use {@link Validation.Common.ValidatorFunc | Validation.Common.ValidatorFunc} instead.
- */
-export { ValidatorFunc };
+import { Constraint, ValidationErrorFormatter, Validator, ValidatorFunc, ValidatorOptions } from './validator';
 /**
  * Options used to initialize a {@link Validation.Base.GenericValidator | GenericValidator}.
  * @public