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

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.52.10"
+    }
+  ]
+}

package/eslint.config.js

@@ -0,0 +1,37 @@
+// ESLint 9 flat config for ts-utils
+const nodeProfile = require('@rushstack/eslint-config/flat/profile/node');
+const packletsPlugin = require('@rushstack/eslint-config/flat/mixins/packlets');
+const tsdocPlugin = require('@rushstack/eslint-config/flat/mixins/tsdoc');
+
+module.exports = [
+  ...nodeProfile,
+  packletsPlugin,
+  ...tsdocPlugin,
+  {
+    // Override specific rules if needed
+    rules: {
+      '@rushstack/packlets/mechanics': 'warn',
+
+      // Tighten naming conventions for interface properties
+      '@typescript-eslint/naming-convention': [
+        'warn',
+        // Keep all the base rules from rushstack but add stricter property rules
+        {
+          selector: 'property',
+          format: ['camelCase', 'UPPER_CASE'],
+          leadingUnderscore: 'allow',
+          filter: {
+            // Only allow quoted identifiers that truly need special chars (not just hyphens)
+            regex: '^__',
+            match: false
+          }
+        },
+        {
+          selector: 'method',
+          format: ['camelCase', 'PascalCase'],
+          leadingUnderscore: 'allow'
+        }
+      ]
+    }
+  }
+];

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

@@ -50,7 +50,7 @@ export type MessageLogLevel = 'quiet' | 'detail' | 'info' | 'warning' | 'error';
  * Options for reporting a result.
  * @public
  */
-export interface IResultReportOptions {
+export interface IResultReportOptions<TD = unknown> {
     /**
      * The level of reporting to be used for failure results.  Default is 'error'.
      */
@@ -59,6 +59,10 @@ export interface IResultReportOptions {
      * 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>;
 }
 /**
  * Interface for reporting a result.
@@ -269,7 +273,7 @@ export interface IResult<T> {
      * @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;
+    report(reporter?: IResultReporter<T>, options?: IResultReportOptions): this;
 }
 /**
  * Reports a successful {@link IResult | result} from some operation and the
@@ -359,7 +363,7 @@ export declare class Success<T> implements IResult<T> {
     /**
      * {@inheritdoc IResult.report}
      */
-    report(reporter: IResultReporter<T>, options?: IResultReportOptions): this;
+    report(reporter?: IResultReporter<T>, options?: IResultReportOptions): this;
     /**
      * Creates a {@link Success | Success<T>} with the supplied value.
      * @param value - The value to be returned.
@@ -455,7 +459,7 @@ export declare class Failure<T> implements IResult<T> {
     /**
      * {@inheritdoc IResult.report}
      */
-    report(reporter: IResultReporter<T>, options?: IResultReportOptions): this;
+    report(reporter?: IResultReporter<T>, options?: IResultReportOptions): this;
     /**
      * Get a 'friendly' string representation of this object.
      * @remarks
@@ -581,7 +585,7 @@ export declare class DetailedSuccess<T, TD> extends Success<T> {
     /**
      * {@inheritdoc IResult.report}
      */
-    report(reporter: IResultReporter<T, TD>, options?: IResultReportOptions): this;
+    report(reporter?: IResultReporter<T, TD>, options?: IResultReportOptions<TD>): this;
     /**
      * Creates a {@link DetailedSuccess | DetailedSuccess<T, TD>} with the supplied value and
      * optional detail.
@@ -647,7 +651,7 @@ export declare class DetailedFailure<T, TD> extends Failure<T> {
     /**
      * {@inheritdoc IResult.report}
      */
-    report(reporter: IResultReporter<T, TD>, options?: IResultReportOptions): this;
+    report(reporter?: IResultReporter<T, TD>, options?: IResultReportOptions<TD>): this;
     orThrow(logOrFormat?: IResultLogger<TD> | ErrorFormatter<TD>): never;
     orThrow(cb: ErrorFormatter): never;
     /**

package/lib/packlets/base/result.js

@@ -136,7 +136,7 @@ class Success {
     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);
+        reporter === null || reporter === void 0 ? void 0 : reporter.reportSuccess(level, this._value);
         return this;
     }
     /**
@@ -260,9 +260,10 @@ class Failure {
      * {@inheritdoc IResult.report}
      */
     report(reporter, options) {
-        var _a;
+        var _a, _b, _c;
         const level = (_a = options === null || options === void 0 ? void 0 : options.failure) !== null && _a !== void 0 ? _a : 'error';
-        reporter.reportFailure(level, this._message);
+        const message = (_c = (_b = options === null || options === void 0 ? void 0 : options.message) === null || _b === void 0 ? void 0 : _b.call(options, this._message)) !== null && _c !== void 0 ? _c : this._message;
+        reporter === null || reporter === void 0 ? void 0 : reporter.reportFailure(level, message);
         return this;
     }
     /**
@@ -400,7 +401,7 @@ class DetailedSuccess extends Success {
     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);
+        reporter === null || reporter === void 0 ? void 0 : reporter.reportSuccess(level, this._value, this._detail);
         return this;
     }
     /**
@@ -483,9 +484,10 @@ class DetailedFailure extends Failure {
      * {@inheritdoc IResult.report}
      */
     report(reporter, options) {
-        var _a;
+        var _a, _b, _c;
         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);
+        const message = (_c = (_b = options === null || options === void 0 ? void 0 : options.message) === null || _b === void 0 ? void 0 : _b.call(options, this._message, this._detail)) !== null && _c !== void 0 ? _c : this._message;
+        reporter === null || reporter === void 0 ? void 0 : reporter.reportFailure(level, message, this._detail);
         return this;
     }
     orThrow(logOrFormat) {

package/lib/packlets/conversion/baseConverter.js

@@ -106,7 +106,6 @@ class BaseConverter {
                 return mapConverter.convert(innerResult.value, this._context(context));
             }
             return (0, base_1.fail)(innerResult.message);
-            // eslint-disable-next-line no-return-assign
         })._with(this._traits());
     }
     /**

package/lib/packlets/conversion/converters.js

@@ -580,7 +580,6 @@ function discriminatedObject(discriminatorProp, converters) {
 function transform(properties) {
     return new baseConverter_1.BaseConverter((from, __self, context) => {
         // eslint bug thinks key is used before defined
-        // eslint-disable-next-line no-use-before-define
         const converted = {};
         const errors = [];
         for (const key in properties) {
@@ -620,7 +619,6 @@ function transform(properties) {
 function transformObject(destinationFields, options) {
     return new baseConverter_1.BaseConverter((from, __self, context) => {
         // eslint bug thinks key is used before defined
-        // eslint-disable-next-line no-use-before-define
         const converted = {};
         const errors = [];
         const used = new Set(options === null || options === void 0 ? void 0 : options.ignore);

package/lib/packlets/conversion/objectConverter.js

@@ -104,9 +104,8 @@ class ObjectConverter extends baseConverter_1.BaseConverter {
         return new ObjectConverter(this.fields, options)._with(this._traits());
     }
     static _convert(from, context, fields, options) {
-        var _a;
         // eslint bug thinks key is used before defined
-        // eslint-disable-next-line no-use-before-define
+        var _a;
         const converted = {};
         const errors = [];
         for (const key in fields) {

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

@@ -15,7 +15,7 @@ export type LogMessageFormatter<TD = unknown> = (message: string, detail?: TD) =
  * @public
  */
 export interface ILogReporterCreateParams<T, TD = unknown> {
-    logger: ILogger;
+    logger?: ILogger;
     valueFormatter?: LogValueFormatter<T, TD>;
     messageFormatter?: LogMessageFormatter<TD>;
 }
@@ -25,14 +25,26 @@ export interface ILogReporterCreateParams<T, TD = unknown> {
  * @public
  */
 export 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>);
+    constructor(params?: ILogReporterCreateParams<T, TD>);
     /**
      * {@inheritDoc Logging.ILogger.logLevel}
      */
@@ -65,5 +77,12 @@ export declare class LogReporter<T, TD = unknown> implements ILogger, IResultRep
      * {@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;
 }
 //# sourceMappingURL=logReporter.d.ts.map

package/lib/packlets/logging/logReporter.js

@@ -1,6 +1,28 @@
 "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}.
@@ -12,10 +34,12 @@ class 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);
+        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}
@@ -67,6 +91,24 @@ class LogReporter {
         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

@@ -103,8 +103,16 @@ export declare abstract class LoggerBase implements ILogger {
     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>;
 }
 /**
@@ -114,12 +122,14 @@ export declare abstract class LoggerBase implements ILogger {
 export declare class InMemoryLogger extends LoggerBase {
     /**
      * The messages that have been logged.
+     * @internal
      */
-    protected _logged: string[];
+    private _logged;
     /**
      * The messages that have been suppressed.
+     * @internal
      */
-    protected _suppressed: string[];
+    private _suppressed;
     /**
      * Creates a new in-memory logger.
      * @param logLevel - The level of logging to be used.
@@ -139,6 +149,7 @@ export declare class InMemoryLogger extends LoggerBase {
     clear(): void;
     /**
      * {@inheritDoc Logging.LoggerBase._log}
+     * @internal
      */
     protected _log(message: string, __level: MessageLogLevel): Success<string | undefined>;
     /**
@@ -147,6 +158,7 @@ export declare class InMemoryLogger extends LoggerBase {
      * @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>;
 }
@@ -162,6 +174,7 @@ export declare class ConsoleLogger extends LoggerBase {
     constructor(logLevel?: ReporterLogLevel);
     /**
      * {@inheritDoc Logging.LoggerBase._log}
+     * @internal
      */
     protected _log(message: string, level: MessageLogLevel): Success<string | undefined>;
 }
@@ -177,6 +190,7 @@ export declare class NoOpLogger extends LoggerBase {
     constructor(logLevel?: ReporterLogLevel);
     /**
      * {@inheritDoc Logging.LoggerBase._log}
+     * @internal
      */
     protected _log(message: string, __level: MessageLogLevel): Success<string | undefined>;
 }

package/lib/packlets/logging/logger.js

@@ -113,6 +113,7 @@ class LoggerBase {
     }
     /**
      * Inner method called for suppressed log messages.
+     * @public
      */
     _suppressLog(__level, __message, ...__parameters) {
         return (0, base_1.succeed)(undefined);
@@ -132,10 +133,12 @@ class InMemoryLogger extends LoggerBase {
         super(logLevel);
         /**
          * The messages that have been logged.
+         * @internal
          */
         this._logged = [];
         /**
          * The messages that have been suppressed.
+         * @internal
          */
         this._suppressed = [];
     }
@@ -160,6 +163,7 @@ class InMemoryLogger extends LoggerBase {
     }
     /**
      * {@inheritDoc Logging.LoggerBase._log}
+     * @internal
      */
     _log(message, __level) {
         this._logged.push(message);
@@ -171,6 +175,7 @@ class InMemoryLogger extends LoggerBase {
      * @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);
@@ -193,6 +198,7 @@ class ConsoleLogger extends LoggerBase {
     }
     /**
      * {@inheritDoc Logging.LoggerBase._log}
+     * @internal
      */
     _log(message, level) {
         switch (level) {
@@ -227,6 +233,7 @@ class NoOpLogger extends LoggerBase {
     }
     /**
      * {@inheritDoc Logging.LoggerBase._log}
+     * @internal
      */
     _log(message, __level) {
         // no-op

package/lib/packlets/validation/object.js

@@ -114,7 +114,6 @@ class ObjectValidator extends validatorBase_1.ValidatorBase {
             return (0, base_1.fail)('source is not an object');
         }
         // eslint bug thinks key is used before defined
-        // eslint-disable-next-line no-use-before-define
         const converted = {};
         const errors = [];
         for (const key in this._innerValidators) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-utils",
-  "version": "5.0.0-24",
+  "version": "5.0.0-26",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-utils.d.ts",
@@ -23,20 +23,20 @@
     "@types/luxon": "^3.7.1",
     "@types/mustache": "^4.2.5",
     "@types/node": "^20.14.9",
-    "@typescript-eslint/eslint-plugin": "^7.14.1",
-    "@typescript-eslint/parser": "^7.14.1",
-    "eslint": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^8.42.0",
+    "@typescript-eslint/parser": "^8.42.0",
+    "eslint": "^9.35.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^6.2.0",
+    "eslint-plugin-promise": "^7.2.1",
     "jest": "^29.7.0",
     "jest-extended": "^4.0.2",
     "jest-matcher-utils": "^29.7.0",
-    "rimraf": "^5.0.7",
+    "rimraf": "^6.0.1",
     "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
     "typescript": "5.8.3",
-    "eslint-plugin-n": "^16.6.2",
+    "eslint-plugin-n": "^17.21.3",
     "jest-snapshot": "~29.7.0",
     "@rushstack/heft": "0.74.3",
     "@rushstack/heft-node-rig": "2.9.4",