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

package/lib/packlets/collections/collector.js

@@ -34,7 +34,7 @@ const base_1 = require("../base");
  */
 class Collector {
     /**
-     * {@inheritDoc Collections.ResultMap.size}
+     * Returns the number of entries in the map.
      */
     get size() {
         return this._byIndex.length;
@@ -90,13 +90,16 @@ class Collector {
         return (0, base_1.succeedWithDetail)(item, 'added');
     }
     /**
-     * {@inheritDoc Collections.ResultMap.entries}
+     * Returns an iterator over the map entries.
+     * @returns An iterator over the map entries.
      */
     entries() {
         return this._byKey.entries();
     }
     /**
-     * {@inheritDoc Collections.ResultMap.forEach}
+     * Calls a function for each entry in the map.
+     * @param callback - The function to call for each entry.
+     * @param arg - An optional argument to pass to the callback.
      */
     forEach(callback, arg) {
         for (const [key, value] of this._byKey.entries()) {
@@ -104,14 +107,20 @@ class Collector {
         }
     }
     /**
-     * {@inheritDoc Collections.ResultMap.get}
+     * Gets a value by key.
+     * @param key - The key to look up.
+     * @returns Returns {@link DetailedSuccess | Success} with the value and detail `exists` if found,
+     * or {@link DetailedFailure | Failure} with detail `not-found` if the key does not exist.
      */
     get(key) {
         const item = this._byKey.get(key);
         return item ? (0, base_1.succeedWithDetail)(item, 'exists') : (0, base_1.failWithDetail)(`${key}: not found`, 'not-found');
     }
     /**
-     * {@inheritDoc Collections.IReadOnlyCollector.getAt}
+     * Gets the item at a specified index.
+     * @param index - The index of the item to retrieve.
+     * @returns Returns {@link Success | Success} with the item if it exists, or {@link Failure | Failure}
+     * with an error if the index is out of range.
      */
     getAt(index) {
         if (typeof index !== 'number') {
@@ -149,25 +158,30 @@ class Collector {
         });
     }
     /**
-     * {@inheritDoc Collections.ResultMap.has}
+     * Returns true if the map contains an entry with the given key.
+     * @param key - The key to check for.
+     * @returns `true` if the key exists, `false` otherwise.
      */
     has(key) {
         return this._byKey.has(key);
     }
     /**
-     * {@inheritDoc Collections.ResultMap.keys}
+     * Returns an iterator over the map keys.
+     * @returns An iterator over the map keys.
      */
     keys() {
         return this._byKey.keys();
     }
     /**
-     * {@inheritDoc Collections.ResultMap.values}
+     * Returns an iterator over the map values.
+     * @returns An iterator over the map values.
      */
     values() {
         return this._byKey.values();
     }
     /**
-     * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
+     * Gets all items in the collection, ordered by index.
+     * @returns An array of items in the collection, ordered by index.
      */
     valuesByIndex() {
         return this._byIndex;

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

@@ -24,7 +24,14 @@ export interface IReadOnlyCollectorValidator<TITEM extends ICollectible<any, any
      */
     has(key: string): boolean;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * using a factory callback if no item with that key exists.
+     * @param key - The weakly-typed key of the item to get or add.
+     * @param factory - The factory callback to create the item.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
 }
@@ -53,7 +60,12 @@ export declare class CollectorValidator<TITEM extends ICollectible<any, any>> im
      */
     constructor(params: ICollectorValidatorCreateParams<TITEM>);
     /**
-     * {@inheritDoc Collections.Collector.add}
+     * Adds an item to the collection, failing if a different item with the same key already exists. Note
+     * that adding an object that is already in the collection again will succeed without updating the collection.
+     * @param item - The item to add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+     * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+     * an error message and appropriate detail if the item could not be added.
      */
     add(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
     /**
@@ -61,12 +73,24 @@ export declare class CollectorValidator<TITEM extends ICollectible<any, any>> im
      */
     get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * using a factory callback if no item with that key exists.
+     * @param key - The weakly-typed key of the item to get or add.
+     * @param factory - The factory callback to create the item.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
-     * @param item - The item to add to the collector.
+     * Gets an existing item with a key matching that of the supplied item, or adds the supplied
+     * item to the collector if no item with that key exists.
+     * @param item - The weakly-typed item to get or add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
     /**

package/lib/packlets/collections/collectorValidator.js

@@ -40,7 +40,12 @@ class CollectorValidator {
         this.converters = params.converters;
     }
     /**
-     * {@inheritDoc Collections.Collector.add}
+     * Adds an item to the collection, failing if a different item with the same key already exists. Note
+     * that adding an object that is already in the collection again will succeed without updating the collection.
+     * @param item - The item to add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+     * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+     * an error message and appropriate detail if the item could not be added.
      */
     add(item) {
         return this._convertValue(item).onSuccess((i) => {

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

@@ -37,7 +37,12 @@ export declare class ConvertingCollector<TITEM extends ICollectible<any, any>, T
      */
     static createConvertingCollector<TITEM extends ICollectible<any, any>, TSRC = TITEM>(params: IConvertingCollectorConstructorParams<TITEM, TSRC>): Result<ConvertingCollector<TITEM, TSRC>>;
     /**
-     * {@inheritDoc Collections.Collector.add}
+     * Adds an item to the collection, failing if a different item with the same key already exists. Note
+     * that adding an object that is already in the collection again will succeed without updating the collection.
+     * @param item - The item to add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+     * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+     * an error message and appropriate detail if the item could not be added.
      */
     add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
     /**
@@ -60,11 +65,24 @@ export declare class ConvertingCollector<TITEM extends ICollectible<any, any>, T
      */
     add(key: CollectibleKey<TITEM>, cb: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching that of the supplied item, or adds the supplied
+     * item to the collector if no item with that key exists.
+     * @param item - The item to get or add.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * using a factory callback if no item with that key exists.
+     * @param key - The key of the item to get or add.
+     * @param callback - The factory callback to create the item.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: CollectibleKey<TITEM>, callback: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**

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

@@ -32,7 +32,12 @@ export declare class ConvertingCollectorValidator<TITEM extends ICollectible<any
      */
     constructor(params: IConvertingCollectorValidatorCreateParams<TITEM, TSRC>);
     /**
-     * {@inheritDoc Collections.ConvertingCollector.add}
+     * Adds an item to the collector using the default factory at a specified key,
+     * failing if an item with that key already exists.
+     * @param key - The weakly-typed key of the item to add.
+     * @param value - The source representation of the item to be added.
+     * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with
+     * an error if the item cannot be created and indexed.
      */
     add(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
     /**
@@ -45,11 +50,25 @@ export declare class ConvertingCollectorValidator<TITEM extends ICollectible<any
      */
     get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
     /**
-     * {@inheritDoc Collections.ConvertingCollector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * by converting the supplied weakly-typed value if no item with that key exists.
+     * @param key - The weakly-typed key of the item to get or add.
+     * @param value - The weakly-typed source value to convert and add if the key does not exist.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
     /**
-     * {@inheritDoc Collections.Collector.getOrAdd}
+     * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+     * using a factory callback if no item with that key exists.
+     * @param key - The weakly-typed key of the item to get or add.
+     * @param factory - The factory callback to create the item.
+     * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+     * detail `exists` indicates that an existing item was returned and detail `added` indicates
+     * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+     * appropriate detail if the item could not be added.
      */
     getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
     /**

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

@@ -18,31 +18,42 @@ export type ResultMapForEachCb<TK extends string = string, TE = unknown> = (valu
  */
 export interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {
     /**
-     * {@inheritDoc Collections.ResultMap.size}
+     * Returns the number of entries in the map.
      */
     readonly size: number;
     /**
-     * {@inheritDoc Collections.ResultMap.entries}
+     * Returns an iterator over the map entries.
+     * @returns An iterator over the map entries.
      */
     entries(): IterableIterator<KeyValueEntry<TK, TV>>;
     /**
-     * {@inheritDoc Collections.ResultMap.forEach}
+     * Calls a function for each entry in the map.
+     * @param cb - The function to call for each entry.
+     * @param arg - An optional argument to pass to the callback.
      */
     forEach(cb: ResultMapForEachCb, arg?: unknown): void;
     /**
-     * {@inheritDoc Collections.ResultMap.get}
+     * Gets a value from the map.
+     * @param key - The key to retrieve.
+     * @returns `Success` with the value and detail `exists` if the key was found,
+     * `Failure` with detail `not-found` if the key was not found or with detail
+     * `invalid-key` if the key is invalid.
      */
     get(key: TK): DetailedResult<TV, ResultMapResultDetail>;
     /**
-     * {@inheritDoc Collections.ResultMap.has}
+     * Returns `true` if the map contains a key.
+     * @param key - The key to check.
+     * @returns `true` if the key exists, `false` otherwise.
      */
     has(key: TK): boolean;
     /**
-     * {@inheritDoc Collections.ResultMap.keys}
+     * Returns an iterator over the map keys.
+     * @returns An iterator over the map keys.
      */
     keys(): IterableIterator<TK>;
     /**
-     * {@inheritDoc Collections.ResultMap.values}
+     * Returns an iterator over the map values.
+     * @returns An iterator over the map values.
      */
     values(): IterableIterator<TV>;
     /**

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

@@ -12,15 +12,19 @@ import { CollectorValidator } from './collectorValidator';
  */
 export interface IReadOnlyValidatingCollector<TITEM extends ICollectible<any, any>> extends IReadOnlyValidatingResultMap<CollectibleKey<TITEM>, TITEM> {
     /**
-     * {@inheritDoc Collections.ValidatingCollector.validating}
+     * A {@link Collections.CollectorValidator | CollectorValidator} which validates keys and values
+     * before inserting them into this collector.
      */
     readonly validating: IReadOnlyCollectorValidator<TITEM>;
     /**
-     * {@inheritDoc Collections.IReadOnlyCollector.getAt}
+     * Gets the item at a specified index.
+     * @param index - The index of the item to retrieve.
+     * @returns `Success` with the item if it exists, or `Failure` with an error if the index is out of range.
      */
     getAt(index: number): Result<TITEM>;
     /**
-     * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
+     * Gets all items in the collection, ordered by index.
+     * @returns An array of items in the collection, ordered by index.
      */
     valuesByIndex(): ReadonlyArray<TITEM>;
 }

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

@@ -10,7 +10,8 @@ import { IReadOnlyResultMapValidator, ResultMapValidator } from './resultMapVali
  */
 export interface IReadOnlyValidatingResultMap<TK extends string = string, TV = unknown> extends IReadOnlyResultMap<TK, TV> {
     /**
-     * {@inheritDoc Collections.ValidatingResultMap.validating}
+     * A {@link Collections.ResultMapValidator | ResultMapValidator} which validates keys and values
+     * before inserting them into this collection.
      */
     readonly validating: IReadOnlyResultMapValidator<TK, TV>;
 }

package/lib/packlets/conversion/baseConverter.d.ts

@@ -64,63 +64,146 @@ export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC>
      */
     constructor(converter: ConverterFunc<T, TC>, defaultContext?: TC, traits?: ConverterTraits);
     /**
-     * {@inheritDoc Converter.isOptional}
+     * Indicates whether this element is explicitly optional.
      */
     get isOptional(): boolean;
     /**
-     * {@inheritDoc Converter.brand}
+     * Returns the brand for a branded type.
      */
     get brand(): string | undefined;
     /**
-     * {@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: unknown, context?: TC): Result<T>;
     /**
-     * {@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: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
     /**
-     * {@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?: OnError): Converter<T | undefined, TC>;
     /**
-     * {@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<T2>(mapper: (from: T, context?: TC) => Result<T2>): Converter<T2, TC>;
     /**
-     * {@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<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
     /**
-     * {@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<TI>(mapper: (from: unknown, context?: TC) => Result<TI>): Converter<TI[], TC>;
     /**
-     * {@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<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
     /**
-     * {@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<TI>(action: (result: Result<T>, context?: TC) => Result<TI>): Converter<TI, TC>;
     /**
-     * {@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<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI, TC>;
     /**
-     * {@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<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI[], TC>;
     /**
-     * {@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: (val: T, context?: TC) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
     /**
-     * {@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<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
     /**
-     * {@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<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC>;
     or(other: Converter<T, TC>): Converter<T, TC>;
@@ -129,7 +212,10 @@ export declare class BaseConverter<T, TC = unknown> implements Converter<T, TC>
      */
     protected _context(supplied?: TC): TC | undefined;
     /**
-     * {@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: ConversionErrorFormatter<TC>): Converter<T, TC>;
     /**