@fgv/ts-utils 5.0.0-22 → 5.0.0-24

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/lib/index.d.ts

@@ -2,10 +2,11 @@ import * as Collections from './packlets/collections';
 import * as Conversion from './packlets/conversion';
 import * as Hash from './packlets/hash';
 import * as FileTree from './packlets/file-tree';
+import * as Logging from './packlets/logging';
 import * as Validation from './packlets/validation';
 import { Collector, ICollectible, ConvertingCollector, IReadOnlyResultMap, ResultMap, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap } from './packlets/collections';
 import { Converter, Converters, ObjectConverter, StringConverter } from './packlets/conversion';
 import { Validator, Validators } from './packlets/validation';
 export * from './packlets/base';
-export { Collections, Collector, ConvertingCollector, Conversion, Converter, Converters, FileTree, Hash, ICollectible, IReadOnlyResultMap, ObjectConverter, ResultMap, StringConverter, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap, Validation, Validator, Validators };
+export { Collections, Collector, ConvertingCollector, Conversion, Converter, Converters, FileTree, Hash, ICollectible, IReadOnlyResultMap, Logging, ObjectConverter, ResultMap, StringConverter, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap, Validation, Validator, Validators };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -57,7 +57,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Validators = exports.Validation = exports.ValidatingResultMap = exports.ValidatingConvertingCollector = exports.ValidatingCollector = exports.StringConverter = exports.ResultMap = exports.ObjectConverter = exports.Hash = exports.FileTree = exports.Converters = exports.Conversion = exports.ConvertingCollector = exports.Collector = exports.Collections = void 0;
+exports.Validators = exports.Validation = exports.ValidatingResultMap = exports.ValidatingConvertingCollector = exports.ValidatingCollector = exports.StringConverter = exports.ResultMap = exports.ObjectConverter = exports.Logging = exports.Hash = exports.FileTree = exports.Converters = exports.Conversion = exports.ConvertingCollector = exports.Collector = exports.Collections = void 0;
 const Collections = __importStar(require("./packlets/collections"));
 exports.Collections = Collections;
 const Conversion = __importStar(require("./packlets/conversion"));
@@ -66,6 +66,8 @@ const Hash = __importStar(require("./packlets/hash"));
 exports.Hash = Hash;
 const FileTree = __importStar(require("./packlets/file-tree"));
 exports.FileTree = FileTree;
+const Logging = __importStar(require("./packlets/logging"));
+exports.Logging = Logging;
 const Validation = __importStar(require("./packlets/validation"));
 exports.Validation = Validation;
 const collections_1 = require("./packlets/collections");

package/lib/packlets/base/index.d.ts

@@ -1,9 +1,7 @@
-import * as Logging from './logger';
 export * from './brand';
 export * from './mapResults';
 export * from './messageAggregator';
 export { Normalizer } from './normalize';
 export * from './result';
 export * from './utils';
-export { Logging };
 //# sourceMappingURL=index.d.ts.map

package/lib/packlets/base/index.js

@@ -31,35 +31,11 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
 }));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logging = exports.Normalizer = void 0;
-const Logging = __importStar(require("./logger"));
-exports.Logging = Logging;
+exports.Normalizer = void 0;
 __exportStar(require("./brand"), exports);
 __exportStar(require("./mapResults"), exports);
 __exportStar(require("./messageAggregator"), exports);

package/lib/packlets/base/result.d.ts

@@ -41,6 +41,33 @@ export interface IResultLogger<TD = unknown> {
      */
     error(message: string, detail?: TD): void;
 }
+/**
+ * The severity level at which a message should be logged.
+ * @public
+ */
+export type MessageLogLevel = 'quiet' | 'detail' | 'info' | 'warning' | 'error';
+/**
+ * Options for reporting a result.
+ * @public
+ */
+export interface IResultReportOptions {
+    /**
+     * 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;
+}
+/**
+ * Interface for reporting a result.
+ * @public
+ */
+export interface IResultReporter<T, TD = unknown> {
+    reportSuccess(level: MessageLogLevel, value: T, detail?: TD): void;
+    reportFailure(level: MessageLogLevel, message: string, detail?: TD): void;
+}
 /**
  * Simple error aggregator to simplify collecting all errors in
  * a flow.
@@ -237,6 +264,12 @@ export interface IResult<T> {
      * 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;
 }
 /**
  * Reports a successful {@link IResult | result} from some operation and the
@@ -323,6 +356,10 @@ export declare class Success<T> implements IResult<T> {
      * {@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.
@@ -415,6 +452,10 @@ export declare class Failure<T> implements IResult<T> {
      * {@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
@@ -537,6 +578,10 @@ export declare class DetailedSuccess<T, TD> extends Success<T> {
      * {@inheritdoc Success.withErrorFormat}
      */
     withErrorFormat(cb: ErrorFormatter): DetailedResult<T, TD>;
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter: IResultReporter<T, TD>, options?: IResultReportOptions): this;
     /**
      * Creates a {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied value and
      * optional detail.
@@ -599,6 +644,10 @@ export declare class DetailedFailure<T, TD> extends Failure<T> {
      * {@inheritdoc IResult.withErrorFormat}
      */
     withErrorFormat(cb: ErrorFormatter<TD>): DetailedResult<T, TD>;
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter: IResultReporter<T, TD>, options?: IResultReportOptions): this;
     orThrow(logOrFormat?: IResultLogger<TD> | ErrorFormatter<TD>): never;
     orThrow(cb: ErrorFormatter): never;
     /**

package/lib/packlets/base/result.js

@@ -130,6 +130,15 @@ class Success {
     aggregateError(__errors) {
         return this;
     }
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter, options) {
+        var _a;
+        const level = (_a = options === null || options === void 0 ? void 0 : options.success) !== null && _a !== void 0 ? _a : 'quiet';
+        reporter.reportSuccess(level, this._value);
+        return this;
+    }
     /**
      * Creates a {@link Success | Success<T>} with the supplied value.
      * @param value - The value to be returned.
@@ -247,6 +256,15 @@ class Failure {
         errors.addMessage(this._message);
         return this;
     }
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter, options) {
+        var _a;
+        const level = (_a = options === null || options === void 0 ? void 0 : options.failure) !== null && _a !== void 0 ? _a : 'error';
+        reporter.reportFailure(level, this._message);
+        return this;
+    }
     /**
      * Get a 'friendly' string representation of this object.
      * @remarks
@@ -376,6 +394,15 @@ class DetailedSuccess extends Success {
     withErrorFormat(cb) {
         return this;
     }
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter, options) {
+        var _a;
+        const level = (_a = options === null || options === void 0 ? void 0 : options.success) !== null && _a !== void 0 ? _a : 'quiet';
+        reporter.reportSuccess(level, this._value, this._detail);
+        return this;
+    }
     /**
      * Creates a {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied value and
      * optional detail.
@@ -452,6 +479,15 @@ class DetailedFailure extends Failure {
     withErrorFormat(cb) {
         return failWithDetail(cb(this._message, this._detail), this._detail);
     }
+    /**
+     * {@inheritdoc IResult.report}
+     */
+    report(reporter, options) {
+        var _a;
+        const level = (_a = options === null || options === void 0 ? void 0 : options.failure) !== null && _a !== void 0 ? _a : 'error';
+        reporter.reportFailure(level, this._message, this._detail);
+        return this;
+    }
     orThrow(logOrFormat) {
         if (logOrFormat !== undefined) {
             if (typeof logOrFormat === 'function') {

package/lib/packlets/collections/collector.d.ts

@@ -19,6 +19,11 @@ export interface IReadOnlyCollector<TITEM extends ICollectible<any, any>> extend
      * 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>;
 }
 /**
  * Parameters for constructing a {@link Collections.Collector | ICollector}.
@@ -115,6 +120,10 @@ export declare class Collector<TITEM extends ICollectible<any, any>> implements
      * {@inheritdoc Collections.ResultMap.values}
      */
     values(): IterableIterator<TITEM>;
+    /**
+     * {@inheritdoc Collections.IReadOnlyCollector.valuesByIndex}
+     */
+    valuesByIndex(): ReadonlyArray<TITEM>;
     /**
      * Gets a read-only version of this collector.
      */

package/lib/packlets/collections/collector.js

@@ -157,6 +157,12 @@ class Collector {
     values() {
         return this._byKey.values();
     }
+    /**
+     * {@inheritdoc Collections.IReadOnlyCollector.valuesByIndex}
+     */
+    valuesByIndex() {
+        return this._byIndex;
+    }
     /**
      * Gets a read-only version of this collector.
      */

package/lib/packlets/collections/validatingCollector.d.ts

@@ -18,7 +18,11 @@ export interface IReadOnlyValidatingCollector<TITEM extends ICollectible<any, an
     /**
      * {@inheritdoc Collections.IReadOnlyValidatingCollector.getAt}
      */
-    readonly getAt: (index: number) => Result<TITEM>;
+    getAt(index: number): Result<TITEM>;
+    /**
+     * {@inheritdoc Collections.IReadOnlyCollector.valuesByIndex}
+     */
+    valuesByIndex(): ReadonlyArray<TITEM>;
 }
 /**
  * Parameters for constructing a {@link Collections.ValidatingCollector | ValidatingCollector}.

package/lib/packlets/hash/hashingNormalizer.js

@@ -51,13 +51,14 @@ class HashingNormalizer extends base_1.Normalizer {
                 }
                 else if (Array.isArray(from)) {
                     return (0, base_1.mapResults)(from.map((e) => this.computeHash(e))).onSuccess((a) => {
-                        return (0, base_1.captureResult)(() => this._hash(a));
+                        return (0, base_1.captureResult)(() => this._hash(['array', ...a]));
                     });
                 }
                 else if (from instanceof Map || from instanceof Set) {
-                    return this.computeHash(this.normalizeEntries(from.entries()));
+                    const type = from instanceof Map ? 'map' : 'set';
+                    return this.computeHash([type, ...this.normalizeEntries(from.entries())]);
                 }
-                return this.computeHash(this.normalizeEntries(Object.entries(from)));
+                return this.computeHash(['object', ...this.normalizeEntries(Object.entries(from))]);
         }
         return (0, base_1.fail)(`computeHash: Unexpected type - cannot hash '${typeof from}'`);
     }

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

@@ -0,0 +1,3 @@
+export * from './logger';
+export * from './logReporter';
+//# sourceMappingURL=index.d.ts.map

package/{src/packlets/base/index.ts → lib/packlets/logging/index.js}

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Copyright (c) 2020 Erik Fortune
  *
@@ -19,13 +20,21 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-
-import * as Logging from './logger';
-
-export * from './brand';
-export * from './mapResults';
-export * from './messageAggregator';
-export { Normalizer } from './normalize';
-export * from './result';
-export * from './utils';
-export { Logging };
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./logger"), exports);
+__exportStar(require("./logReporter"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,69 @@
+import { ILogger, ReporterLogLevel } from './logger';
+import { IResultReporter, MessageLogLevel, Success } from '../base';
+/**
+ * A function that formats a value for logging.
+ * @public
+ */
+export type LogValueFormatter<T, TD = unknown> = (value: T, detail?: TD) => string;
+/**
+ * A function that formats a message for logging.
+ * @public
+ */
+export type LogMessageFormatter<TD = unknown> = (message: string, detail?: TD) => string;
+/**
+ * Parameters for creating a {@link Logging.LogReporter | LogReporter}.
+ * @public
+ */
+export interface ILogReporterCreateParams<T, TD = unknown> {
+    logger: ILogger;
+    valueFormatter?: LogValueFormatter<T, TD>;
+    messageFormatter?: LogMessageFormatter<TD>;
+}
+/**
+ * Abstract base class which wraps an existing {@link Logging.ILogger | ILogger} to implement
+ * both {@link Logging.ILogger | ILogger} and {@link IResultReporter | IResultReporter}.
+ * @public
+ */
+export declare class LogReporter<T, TD = unknown> implements ILogger, IResultReporter<T, TD> {
+    protected readonly _logger: ILogger;
+    protected readonly _valueFormatter: LogValueFormatter<T, TD>;
+    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;
+}
+//# sourceMappingURL=logReporter.d.ts.map

package/lib/packlets/logging/logReporter.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogReporter = void 0;
+/**
+ * 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;
+        this._logger = params.logger;
+        this._valueFormatter = (_a = params.valueFormatter) !== null && _a !== void 0 ? _a : ((message, __detail) => String(message));
+        this._messageFormatter = (_b = params.messageFormatter) !== null && _b !== void 0 ? _b : ((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);
+    }
+}
+exports.LogReporter = LogReporter;
+//# sourceMappingURL=logReporter.js.map