@fgv/ts-utils 5.0.2 → 5.1.0-1

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.54.0"
+      "packageVersion": "7.57.6"
     }
   ]
 }

package/lib/index.d.ts

@@ -3,9 +3,9 @@ import * as Conversion from './packlets/conversion';
 import * as Hash from './packlets/hash';
 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 { AggregatedResultMap, 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, Hash, ICollectible, IReadOnlyResultMap, Logging, ObjectConverter, ResultMap, StringConverter, ValidatingCollector, ValidatingConvertingCollector, ValidatingResultMap, Validation, Validator, Validators };
+export { AggregatedResultMap, Collections, Collector, ConvertingCollector, Conversion, Converter, Converters, 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.Logging = exports.Hash = 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.Converters = exports.Conversion = exports.ConvertingCollector = exports.Collector = exports.Collections = exports.AggregatedResultMap = void 0;
 const Collections = __importStar(require("./packlets/collections"));
 exports.Collections = Collections;
 const Conversion = __importStar(require("./packlets/conversion"));
@@ -69,6 +69,7 @@ exports.Logging = Logging;
 const Validation = __importStar(require("./packlets/validation"));
 exports.Validation = Validation;
 const collections_1 = require("./packlets/collections");
+Object.defineProperty(exports, "AggregatedResultMap", { enumerable: true, get: function () { return collections_1.AggregatedResultMap; } });
 Object.defineProperty(exports, "Collector", { enumerable: true, get: function () { return collections_1.Collector; } });
 Object.defineProperty(exports, "ConvertingCollector", { enumerable: true, get: function () { return collections_1.ConvertingCollector; } });
 Object.defineProperty(exports, "ResultMap", { enumerable: true, get: function () { return collections_1.ResultMap; } });

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

@@ -68,15 +68,15 @@ export declare function allSucceed<T>(results: Iterable<Result<unknown>>, succes
  */
 export declare function firstSuccess<T>(results: Iterable<Result<T> | DeferredResult<T>>): Result<T>;
 /**
- * String-keyed record of initialization functions to be passed to {@link (populateObject:1)}
- * or {@link (populateObject:2)}.
+ * String-keyed record of initialization functions to be passed to {@link populateObject}
+ * or {@link populateObject}.
  * @public
  */
 export type FieldInitializers<T> = {
     [key in keyof T]: (state: Partial<T>) => Result<T[key]>;
 };
 /**
- * Options for the {@link (populateObject:1)} function.
+ * Options for the {@link populateObject} function.
  * @public
  */
 export interface PopulateObjectOptions<T> {

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

@@ -14,27 +14,27 @@ export declare class MessageAggregator implements IMessageAggregator {
      */
     constructor(errors?: string[]);
     /**
-     * {@inheritdoc IMessageAggregator.hasMessages}
+     * {@inheritDoc IMessageAggregator.hasMessages}
      */
     get hasMessages(): boolean;
     /**
-     * {@inheritdoc IMessageAggregator.numMessages}
+     * {@inheritDoc IMessageAggregator.numMessages}
      */
     get numMessages(): number;
     /**
-     * {@inheritdoc IMessageAggregator.messages}
+     * {@inheritDoc IMessageAggregator.messages}
      */
     get messages(): string[];
     /**
-     * {@inheritdoc IMessageAggregator.addMessage}
+     * {@inheritDoc IMessageAggregator.addMessage}
      */
     addMessage(message: string | undefined): this;
     /**
-     * {@inheritdoc IMessageAggregator.addMessages}
+     * {@inheritDoc IMessageAggregator.addMessages}
      */
     addMessages(messages: string[] | undefined): this;
     /**
-     * {@inheritdoc IMessageAggregator.toString}
+     * {@inheritDoc IMessageAggregator.toString}
      */
     toString(separator?: string): string;
     /**

package/lib/packlets/base/messageAggregator.js

@@ -39,25 +39,25 @@ class MessageAggregator {
         this._messages = errors ? Array.from(errors) : [];
     }
     /**
-     * {@inheritdoc IMessageAggregator.hasMessages}
+     * {@inheritDoc IMessageAggregator.hasMessages}
      */
     get hasMessages() {
         return this._messages.length > 0;
     }
     /**
-     * {@inheritdoc IMessageAggregator.numMessages}
+     * {@inheritDoc IMessageAggregator.numMessages}
      */
     get numMessages() {
         return this._messages.length;
     }
     /**
-     * {@inheritdoc IMessageAggregator.messages}
+     * {@inheritDoc IMessageAggregator.messages}
      */
     get messages() {
         return this._messages;
     }
     /**
-     * {@inheritdoc IMessageAggregator.addMessage}
+     * {@inheritDoc IMessageAggregator.addMessage}
      */
     addMessage(message) {
         if (message) {
@@ -66,7 +66,7 @@ class MessageAggregator {
         return this;
     }
     /**
-     * {@inheritdoc IMessageAggregator.addMessages}
+     * {@inheritDoc IMessageAggregator.addMessages}
      */
     addMessages(messages) {
         if (messages && messages.length > 0) {
@@ -75,7 +75,7 @@ class MessageAggregator {
         return this;
     }
     /**
-     * {@inheritdoc IMessageAggregator.toString}
+     * {@inheritDoc IMessageAggregator.toString}
      */
     toString(separator) {
         return this._messages.join(separator !== null && separator !== void 0 ? separator : '\n');

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

@@ -35,6 +35,22 @@ export type FailureContinuation<T> = (message: string) => Result<T>;
  * @beta
  */
 export type ResultValueType<T> = T extends Result<infer TV> ? TV : never;
+/**
+ * Type inference to determine the result type of an {@link IResult}.
+ * @beta
+ */
+export type IResultValueType<T> = T extends IResult<infer TV> ? TV : never;
+/**
+ * Type inference to determine the value type returned from a result-map style
+ * `get` method.
+ * @remarks
+ * Useful for extracting collection entry types from maps whose `get` method
+ * returns an {@link IResult}.
+ * @beta
+ */
+export type ResultMapValueType<TCollection extends {
+    get: (...args: readonly unknown[]) => unknown;
+}> = Exclude<IResultValueType<ReturnType<TCollection['get']>>, undefined>;
 /**
  * Formats an error message.
  * @param message - The error message to be formatted.
@@ -43,7 +59,7 @@ export type ResultValueType<T> = T extends Result<infer TV> ? TV : never;
  */
 export type ErrorFormatter<TD = unknown> = (message: string, detail?: TD) => string;
 /**
- * Simple logger interface used by {@link IResult.(orThrow:1) | orThrow(logger)} and {@link IResult.(orThrow:2) | orThrow(formatter)}.
+ * Simple logger interface used by {@link IResult.orThrow | orThrow(logger)} and {@link IResult.orThrow | orThrow(formatter)}.
  * @public
  */
 export interface IResultLogger<TD = unknown> {
@@ -86,7 +102,9 @@ export interface IResultReportOptions<TD = unknown> {
  * @public
  */
 export interface IResultReporter<T, TD = unknown> {
+    /** Reports a successful result at the specified log level. */
     reportSuccess(level: MessageLogLevel, value: T, detail?: TD, message?: ErrorFormatter<TD>): void;
+    /** Reports a failed result at the specified log level. */
     reportFailure(level: MessageLogLevel, message: string, detail?: TD): void;
 }
 /**
@@ -170,7 +188,7 @@ export interface IResult<T> {
      * error will also be reported.
      * @returns The return value, if the operation was successful.
      * @throws The error message if the operation failed.
-     * @deprecated Use {@link IResult.(orThrow:1) | orThrow(logger)} or {@link IResult.(orThrow:2) | orThrow(formatter)} instead.
+     * @deprecated Use {@link IResult.orThrow | orThrow(logger)} or {@link IResult.orThrow | orThrow(formatter)} instead.
      */
     getValueOrThrow(logger?: IResultLogger): T;
     /**
@@ -184,7 +202,7 @@ export interface IResult<T> {
      *
      * @returns The return value, if the operation was successful.  Returns
      * the supplied default value or `undefined` if no default is supplied.
-     * @deprecated Use {@link IResult.(orDefault:1) | orDefault(T)} or {@link IResult.(orDefault:2) | orDefault()} instead.
+     * @deprecated Use {@link IResult.orDefault | orDefault(T)} or {@link IResult.orDefault | orDefault()} instead.
      */
     getValueOrDefault(dflt?: T): T | undefined;
     /**
@@ -300,7 +318,7 @@ export interface IResult<T> {
  */
 export declare class Success<out T> implements IResult<T> {
     /**
-     * {@inheritdoc IResult.success}
+     * {@inheritDoc IResult.success}
      */
     readonly success: true;
     /**
@@ -321,65 +339,65 @@ export declare class Success<out T> implements IResult<T> {
      */
     get value(): T;
     /**
-     * {@inheritdoc IResult.isSuccess}
+     * {@inheritDoc IResult.isSuccess}
      */
     isSuccess(): this is Success<T>;
     /**
-     * {@inheritdoc IResult.isFailure}
+     * {@inheritDoc IResult.isFailure}
      */
     isFailure(): this is Failure<T>;
     /**
-     * {@inheritdoc IResult.(orThrow:1)}
+     * {@inheritDoc IResult.orThrow}
      */
     orThrow(logger?: IResultLogger): T;
     /**
-     * {@inheritdoc IResult.(orThrow:2)}
+     * {@inheritDoc IResult.orThrow}
      */
     orThrow(cb: ErrorFormatter): T;
     /**
-     * {@inheritdoc IResult.(orDefault:1)}
+     * {@inheritDoc IResult.orDefault}
      */
     orDefault(dflt: T): T;
     /**
-     * {@inheritdoc IResult.(orDefault:2)}
+     * {@inheritDoc IResult.orDefault}
      */
     orDefault(): T | undefined;
     /**
-     * {@inheritdoc IResult.getValueOrThrow}
-     * @deprecated Use {@link Success.(orThrow:1) | orThrow(logger)} or {@link Success.(orThrow:2) | orThrow(formatter)} instead.
+     * {@inheritDoc IResult.getValueOrThrow}
+     * @deprecated Use {@link Success.orThrow | orThrow(logger)} or {@link Success.orThrow | orThrow(formatter)} instead.
      */
     getValueOrThrow(__logger?: IResultLogger): T;
     /**
-     * {@inheritdoc IResult.getValueOrDefault}
-     * @deprecated Use {@link Success.(orDefault:1) | orDefault(T)} or {@link Success.(orDefault:2) | orDefault()} instead.
+     * {@inheritDoc IResult.getValueOrDefault}
+     * @deprecated Use {@link Success.orDefault | orDefault(T)} or {@link Success.orDefault | orDefault()} instead.
      */
     getValueOrDefault(dflt?: T): T | undefined;
     /**
-     * {@inheritdoc IResult.onSuccess}
+     * {@inheritDoc IResult.onSuccess}
      */
     onSuccess<TN>(cb: SuccessContinuation<T, TN>): Result<TN>;
     /**
-     * {@inheritdoc IResult.onFailure}
+     * {@inheritDoc IResult.onFailure}
      */
     onFailure(__: FailureContinuation<T>): Result<T>;
     /**
-     * {@inheritdoc IResult.withErrorFormat}
+     * {@inheritDoc IResult.withErrorFormat}
      */
     withErrorFormat(__cb: ErrorFormatter): Result<T>;
     /**
-     * {@inheritdoc IResult.withFailureDetail}
+     * {@inheritDoc IResult.withFailureDetail}
      */
     withFailureDetail<TD>(__detail: TD): DetailedResult<T, TD>;
     /**
-     * {@inheritdoc IResult.withDetail}
+     * {@inheritDoc IResult.withDetail}
      */
     withDetail<TD>(detail: TD, successDetail?: TD): DetailedResult<T, TD>;
     /**
-     * {@inheritdoc IResult.aggregateError}
+     * {@inheritDoc IResult.aggregateError}
      */
     aggregateError(__errors: IMessageAggregator, __formatter?: ErrorFormatter): this;
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): Success<T>;
     /**
@@ -396,7 +414,7 @@ export declare class Success<out T> implements IResult<T> {
  */
 export declare class Failure<out T> implements IResult<T> {
     /**
-     * {@inheritdoc IResult.success}
+     * {@inheritDoc IResult.success}
      */
     readonly success: false;
     /**
@@ -417,65 +435,65 @@ export declare class Failure<out T> implements IResult<T> {
      */
     get message(): string;
     /**
-     * {@inheritdoc IResult.isSuccess}
+     * {@inheritDoc IResult.isSuccess}
      */
     isSuccess(): this is Success<T>;
     /**
-     * {@inheritdoc IResult.isFailure}
+     * {@inheritDoc IResult.isFailure}
      */
     isFailure(): this is Failure<T>;
     /**
-     * {@inheritdoc IResult.(orThrow:1)}
+     * {@inheritDoc IResult.orThrow}
      */
     orThrow(logger?: IResultLogger): never;
     /**
-     * {@inheritdoc IResult.(orThrow:2)}
+     * {@inheritDoc IResult.orThrow}
      */
     orThrow(cb: ErrorFormatter): never;
     /**
-     * {@inheritdoc IResult.(orDefault:1)}
+     * {@inheritDoc IResult.orDefault}
      */
     orDefault(dflt: T): T;
     /**
-     * {@inheritdoc IResult.(orDefault:2)}
+     * {@inheritDoc IResult.orDefault}
      */
     orDefault(): T | undefined;
     /**
-     * {@inheritdoc IResult.getValueOrThrow}
-     * @deprecated Use {@link Failure.(orThrow:1) | orThrow(logger)} or {@link Failure.(orThrow:2) | orThrow(formatter)} instead.
+     * {@inheritDoc IResult.getValueOrThrow}
+     * @deprecated Use {@link Failure.orThrow | orThrow(logger)} or {@link Failure.orThrow | orThrow(formatter)} instead.
      */
     getValueOrThrow(logger?: IResultLogger): never;
     /**
-     * {@inheritdoc IResult.getValueOrDefault}
-     * @deprecated Use {@link Failure.(orDefault:1) | orDefault(T)} or {@link Failure.(orDefault:2) | orDefault()} instead.
+     * {@inheritDoc IResult.getValueOrDefault}
+     * @deprecated Use {@link Failure.orDefault | orDefault(T)} or {@link Failure.orDefault | orDefault()} instead.
      */
     getValueOrDefault(dflt?: T): T | undefined;
     /**
-     * {@inheritdoc IResult.onSuccess}
+     * {@inheritDoc IResult.onSuccess}
      */
     onSuccess<TN>(__: SuccessContinuation<T, TN>): Result<TN>;
     /**
-     * {@inheritdoc IResult.onFailure}
+     * {@inheritDoc IResult.onFailure}
      */
     onFailure(cb: FailureContinuation<T>): Result<T>;
     /**
-     * {@inheritdoc IResult.withErrorFormat}
+     * {@inheritDoc IResult.withErrorFormat}
      */
     withErrorFormat(cb: ErrorFormatter): Result<T>;
     /**
-     * {@inheritdoc IResult.withFailureDetail}
+     * {@inheritDoc IResult.withFailureDetail}
      */
     withFailureDetail<TD>(detail: TD): DetailedResult<T, TD>;
     /**
-     * {@inheritdoc IResult.withDetail}
+     * {@inheritDoc IResult.withDetail}
      */
     withDetail<TD>(detail: TD, __successDetail?: TD): DetailedResult<T, TD>;
     /**
-     * {@inheritdoc IResult.aggregateError}
+     * {@inheritDoc IResult.aggregateError}
      */
     aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter): this;
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): Failure<T>;
     /**
@@ -503,7 +521,7 @@ export declare class Failure<out T> implements IResult<T> {
  */
 export declare function succeed<T>(value: T): Success<T>;
 /**
- * {@inheritdoc succeed}
+ * {@inheritDoc succeed}
  * @public
  */
 export declare function succeeds<T>(value: T): Success<T>;
@@ -517,7 +535,7 @@ export declare function succeeds<T>(value: T): Success<T>;
  */
 export declare function fail<T>(message: string): Failure<T>;
 /**
- * {@inheritdoc fail}
+ * {@inheritDoc fail}
  * @public
  */
 export declare function fails<T>(message: string): Failure<T>;
@@ -591,17 +609,17 @@ export declare class DetailedSuccess<out T, out TD> extends Success<T> {
      * Propagates this {@link DetailedSuccess}.
      * @remarks
      * Failure does not mutate return type so we can return this event directly.
-     * @param _cb - {@link DetailedFailureContinuation | Failure callback} to be called
+     * @param __cb - {@link DetailedFailureContinuation | Failure callback} to be called
      * on a {@link DetailedResult} in case of failure (ignored).
      * @returns `this`
      */
     onFailure(__cb: DetailedFailureContinuation<T, TD>): DetailedResult<T, TD>;
     /**
-     * {@inheritdoc Success.withErrorFormat}
+     * {@inheritDoc Success.withErrorFormat}
      */
     withErrorFormat(cb: ErrorFormatter): DetailedResult<T, TD>;
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter?: IResultReporter<T, unknown>, options?: IResultReportOptions<unknown>): DetailedSuccess<T, TD>;
     /**
@@ -649,7 +667,7 @@ export declare class DetailedFailure<out T, out TD> extends Failure<T> {
      * @remarks
      * Mutates the success type as the success callback would have, but does not
      * call the success callback.
-     * @param _cb - {@link DetailedSuccessContinuation | Success callback} to be called
+     * @param __cb - {@link DetailedSuccessContinuation | Success callback} to be called
      * on a {@link DetailedResult} in case of success (ignored).
      * @returns A new {@link DetailedFailure | DetailedFailure<TN, TD>} which contains
      * the error message and detail from this one.
@@ -663,15 +681,15 @@ export declare class DetailedFailure<out T, out TD> extends Failure<T> {
      */
     onFailure(cb: DetailedFailureContinuation<T, TD>): DetailedResult<T, TD>;
     /**
-     * {@inheritdoc IResult.withErrorFormat}
+     * {@inheritDoc IResult.withErrorFormat}
      */
     withErrorFormat(cb: ErrorFormatter<TD>): DetailedResult<T, TD>;
     /**
-     * {@inheritdoc IResult.aggregateError}
+     * {@inheritDoc IResult.aggregateError}
      */
     aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter<TD>): this;
     /**
-     * {@inheritdoc IResult.report}
+     * {@inheritDoc IResult.report}
      */
     report(reporter?: IResultReporter<T, unknown>, options?: IResultReportOptions<unknown>): DetailedFailure<T, TD>;
     orThrow(logOrFormat?: IResultLogger<TD> | ErrorFormatter<TD>): never;
@@ -692,10 +710,15 @@ export declare class DetailedFailure<out T, out TD> extends Failure<T> {
     static with<T, TD>(message: string, detail?: TD): DetailedFailure<T, TD>;
 }
 /**
- * Type inference to determine the result type `T` of a {@link DetailedResult | DetailedResult<T, TD>}.
+ * Represents a result with additional detail.
  * @beta
  */
 export type DetailedResult<T, TD> = DetailedSuccess<T, TD> | DetailedFailure<T, TD>;
+/**
+ * Type inference to determine the result type `T` of a {@link DetailedResult | DetailedResult<T, TD>}.
+ * @beta
+ */
+export type DetailedResultValueType<T> = T extends DetailedResult<infer TV, unknown> ? TV : never;
 /**
  * Type inference to determine the detail type `TD` of a {@link DetailedResult | DetailedResult<T, TD>}.
  * @beta
@@ -716,7 +739,7 @@ export type ResultDetailType<T> = T extends DetailedResult<unknown, infer TD> ?
  */
 export declare function succeedWithDetail<T, TD>(value: T, detail?: TD): DetailedSuccess<T, TD>;
 /**
- * {@inheritdoc succeedWithDetail}
+ * {@inheritDoc succeedWithDetail}
  * @public
  */
 export declare function succeedsWithDetail<T, TD>(value: T, detail?: TD): DetailedSuccess<T, TD>;
@@ -733,7 +756,7 @@ export declare function succeedsWithDetail<T, TD>(value: T, detail?: TD): Detail
  */
 export declare function failWithDetail<T, TD>(message: string, detail?: TD): DetailedFailure<T, TD>;
 /**
- * {@inheritdoc failWithDetail}
+ * {@inheritDoc failWithDetail}
  * @public
  */
 export declare function failsWithDetail<T, TD>(message: string, detail?: TD): DetailedFailure<T, TD>;