@fgv/ts-utils 5.1.0-15 → 5.1.0-17

package/lib/packlets/conversion/baseConverter.js

@@ -47,25 +47,45 @@ class BaseConverter {
         this._brand = traits === null || traits === void 0 ? void 0 : traits.brand;
     }
     /**
-     * {@inheritDoc Converter.isOptional}
+     * Indicates whether this element is explicitly optional.
      */
     get isOptional() {
         return this._isOptional;
     }
     /**
-     * {@inheritDoc Converter.brand}
+     * Returns the brand for a branded type.
      */
     get brand() {
         return this._brand;
     }
     /**
-     * {@inheritDoc Converter.convert}
+     * Converts from `unknown` to `<T>`. For objects and arrays, is guaranteed
+     * to return a new entity, with any unrecognized properties removed.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
     convert(from, context) {
         return this._converter(from, this, context !== null && context !== void 0 ? context : this._defaultContext);
     }
     /**
-     * {@inheritDoc Converter.convertOptional}
+     * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the converter succeeds for
+     * `undefined` or any convertible value, but reports an error
+     * if it encounters a value that cannot be converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that
+     * cannot be converted result in a successful return of `undefined`.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
     convertOptional(from, context, onError) {
         const result = this._converter(from, this, this._context(context));
@@ -76,7 +96,18 @@ class BaseConverter {
         return result;
     }
     /**
-     * {@inheritDoc Converter.optional}
+     * Creates a {@link Converter} for an optional value.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the resulting converter will accept `undefined`
+     * or a convertible value, but report an error if it encounters a value that cannot be
+     * converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that cannot be converted will
+     * result in a successful return of `undefined`.
+     *
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A new {@link Converter} returning `<T|undefined>`.
      */
     optional(onError) {
         return new BaseConverter((from, __self, context) => {
@@ -85,7 +116,11 @@ class BaseConverter {
         })._with(this._traits({ isOptional: true }));
     }
     /**
-     * {@inheritDoc Converter.map}
+     * Creates a {@link Converter} which applies a (possibly) mapping conversion to
+     * the converted value of this {@link Converter}.
+     * @param mapper - A function which maps from the the result type `<T>` of this
+     * converter to a new result type `<T2>`.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     map(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -97,7 +132,12 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.mapConvert}
+     * Creates a {@link Converter} which applies an additional supplied
+     * converter to the result of this converter.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to the
+     * converted result from this {@link Converter}.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     mapConvert(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -109,7 +149,15 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.mapItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied map function.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapper - The map function to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapItems(mapper) {
         return new BaseConverter((from, __self, context) => {
@@ -122,7 +170,15 @@ class BaseConverter {
         });
     }
     /**
-     * {@inheritDoc Converter.mapConvertItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied {@link Converter}.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapConvertItems(mapConverter) {
         return new BaseConverter((from, __self, context) => {
@@ -135,7 +191,10 @@ class BaseConverter {
         });
     }
     /**
-     * {@inheritDoc Converter.withAction}
+     * Creates a {@link Converter | Converter} which applies a supplied action after
+     * conversion. The supplied action is always called regardless of success or failure
+     * of the base conversion and is allowed to mutate the return type.
+     * @param action - The action to be applied.
      */
     withAction(action) {
         return new BaseConverter((from, __self, context) => {
@@ -143,7 +202,11 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to the conversion
+     * result.
+     * @param guard - The type guard function to apply.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -156,7 +219,15 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withItemTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to each member of
+     * the conversion result from this converter.
+     *
+     * @remarks
+     * Fails if the conversion result is not an array or if any member fails the
+     * type guard.
+     * @param guard - The type guard function to apply to each element.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withItemTypeGuard(guard, message) {
         return new BaseConverter((from, __self, context) => {
@@ -174,7 +245,15 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withConstraint}
+     * Creates a {@link Converter} which applies an optional constraint to the result
+     * of this conversion. If this {@link Converter} (the base converter) succeeds, the new
+     * converter calls a supplied constraint evaluation function with the conversion, which
+     * fails the entire conversion if the constraint function returns either `false` or
+     * {@link Failure | Failure<T>}.
+     *
+     * @param constraint - Constraint evaluation function.
+     * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withConstraint(constraint, options) {
         return new BaseConverter((from, __self, context) => {
@@ -193,7 +272,10 @@ class BaseConverter {
         })._with(this._traits());
     }
     /**
-     * {@inheritDoc Converter.withBrand}
+     * Returns a converter which adds a brand to the type to prevent mismatched usage
+     * of simple types.
+     * @param brand - The brand to be applied to the result value.
+     * @returns A {@link Converter} returning `Brand<T, B>`.
      */
     withBrand(brand) {
         if (this._brand) {
@@ -206,7 +288,8 @@ class BaseConverter {
         })._with(this._traits({ brand }));
     }
     /**
-     * {@inheritDoc Converter.withDefault}
+     * Returns a Converter which always succeeds with a default value rather than failing.
+     * @param defaultValue - The default value to use if conversion fails.
      */
     withDefault(defaultValue) {
         return new defaultingConverter_1.GenericDefaultingConverter(this, defaultValue);
@@ -225,7 +308,10 @@ class BaseConverter {
         return supplied !== null && supplied !== void 0 ? supplied : this._defaultContext;
     }
     /**
-     * {@inheritDoc Converter.withFormattedError}
+     * Creates a new {@link Converter} which is derived from this one but which returns an
+     * error message formatted by the supplied formatter if the conversion fails.
+     * @param formatter - The formatter to be applied.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withFormattedError(formatter) {
         return new BaseConverter((from, __self, context) => {

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

@@ -106,36 +106,61 @@ export declare function isDetailLogger(logger: ILogger): logger is IDetailLogger
  */
 export declare abstract class LoggerBase implements IDetailLogger {
     /**
-     * {@inheritDoc Logging.ILogger.logLevel}
+     * The level of logging to be used.
      */
     logLevel: ReporterLogLevel;
     protected constructor(logLevel?: ReporterLogLevel);
     /**
-     * {@inheritDoc Logging.ILogger.detail}
+     * 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>;
     /**
-     * {@inheritDoc Logging.ILogger.info}
+     * 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>;
     /**
-     * {@inheritDoc Logging.ILogger.warn}
+     * 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>;
     /**
-     * {@inheritDoc Logging.ILogger.error}
+     * 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>;
     /**
-     * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+     * Logs a short error summary at `error` level, then emits `detail` at `detail` level.
+     * @param message - Short human-readable summary.
+     * @param detail - Full detail (e.g. raw converter error) logged at `detail` level.
      */
     errorWithDetail(message: string, detail: unknown): Success<string | undefined>;
     /**
-     * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+     * Logs a short warning summary at `warning` level, then emits `detail` at `detail` level.
+     * @param message - Short human-readable summary.
+     * @param detail - Full detail logged at `detail` level.
      */
     warnWithDetail(message: string, detail: unknown): Success<string | undefined>;
     /**
-     * {@inheritDoc Logging.ILogger.log}
+     * 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>;
     /**

package/lib/packlets/logging/logger.js

@@ -92,51 +92,76 @@ function isDetailLogger(logger) {
 class LoggerBase {
     constructor(logLevel) {
         /**
-         * {@inheritDoc Logging.ILogger.logLevel}
+         * The level of logging to be used.
          */
         this.logLevel = 'info';
         this.logLevel = logLevel !== null && logLevel !== void 0 ? logLevel : 'info';
     }
     /**
-     * {@inheritDoc Logging.ILogger.detail}
+     * 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, ...parameters) {
         return this.log('detail', message, ...parameters);
     }
     /**
-     * {@inheritDoc Logging.ILogger.info}
+     * 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, ...parameters) {
         return this.log('info', message, ...parameters);
     }
     /**
-     * {@inheritDoc Logging.ILogger.warn}
+     * 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, ...parameters) {
         return this.log('warning', message, ...parameters);
     }
     /**
-     * {@inheritDoc Logging.ILogger.error}
+     * 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, ...parameters) {
         return this.log('error', message, ...parameters);
     }
     /**
-     * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+     * Logs a short error summary at `error` level, then emits `detail` at `detail` level.
+     * @param message - Short human-readable summary.
+     * @param detail - Full detail (e.g. raw converter error) logged at `detail` level.
      */
     errorWithDetail(message, detail) {
         this.detail(detail);
         return this.error(message);
     }
     /**
-     * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+     * Logs a short warning summary at `warning` level, then emits `detail` at `detail` level.
+     * @param message - Short human-readable summary.
+     * @param detail - Full detail logged at `detail` level.
      */
     warnWithDetail(message, detail) {
         this.detail(detail);
         return this.warn(message);
     }
     /**
-     * {@inheritDoc Logging.ILogger.log}
+     * 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, message, ...parameters) {
         if (shouldLog(level, this.logLevel)) {

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

@@ -1,4 +1,5 @@
 import { GenericValidator, GenericValidatorConstructorParams } from './genericValidator';
+import { Validator } from './validator';
 import { Failure } from '../base';
 /**
  * @internal
@@ -24,6 +25,6 @@ export declare abstract class ValidatorBase<T, TC = unknown> extends GenericVali
      * with an error message if `from` is invalid.
      * @internal
      */
-    protected abstract _validate(from: unknown, context?: TC, self?: import('./validator').Validator<T, TC>): boolean | Failure<T>;
+    protected abstract _validate(from: unknown, context?: TC, self?: Validator<T, TC>): boolean | Failure<T>;
 }
 //# sourceMappingURL=validatorBase.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-utils",
-  "version": "5.1.0-15",
+  "version": "5.1.0-17",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "module": "dist/index.js",
@@ -54,8 +54,8 @@
     "@rushstack/heft-jest-plugin": "1.2.6",
     "eslint-plugin-tsdoc": "~0.5.2",
     "typedoc": "~0.28.16",
-    "@fgv/typedoc-compact-theme": "5.1.0-15",
-    "@fgv/heft-dual-rig": "5.1.0-15"
+    "@fgv/heft-dual-rig": "5.1.0-17",
+    "@fgv/typedoc-compact-theme": "5.1.0-17"
   },
   "repository": {
     "type": "git",