@fgv/ts-extras 2.1.1-alpha.2 → 3.0.0-alpha.1

package/CHANGELOG.json

@@ -1,6 +1,24 @@
 {
   "name": "@fgv/ts-extras",
   "entries": [
+    {
+      "version": "3.0.0",
+      "tag": "@fgv/ts-extras_v3.0.0",
+      "date": "Mon, 22 Jan 2024 07:00:18 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "refactor hash implementation"
+          },
+          {
+            "comment": "refactor and cleanup"
+          },
+          {
+            "comment": "Factor extras into their own package"
+          }
+        ]
+      }
+    },
     {
       "version": "2.2.0",
       "tag": "@fgv/ts-extras_v2.2.0",

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 # Change Log - @fgv/ts-extras
 
-This log was last generated on Thu, 18 Jan 2024 05:45:04 GMT and should not be manually modified.
+This log was last generated on Mon, 22 Jan 2024 07:00:18 GMT and should not be manually modified.
+
+## 3.0.0
+Mon, 22 Jan 2024 07:00:18 GMT
+
+### Updates
+
+- refactor hash implementation
+- refactor and cleanup
+- Factor extras into their own package
 
 ## 2.2.0
 Thu, 18 Jan 2024 05:45:04 GMT

package/dist/ts-extras.d.ts

@@ -21,7 +21,7 @@ declare namespace Csv {
 export { Csv }
 
 /**
- * Options for {@link Csv.readCsvFileSync}
+ * Options for {@link Csv.readCsvFileSync | readCsvFileSync}
  * @beta
  */
 declare interface CsvOptions {
@@ -55,13 +55,13 @@ export { Experimental }
 
 /**
  * An experimental array template which extend built-in `Array` to include a handful
- * of predicates which return {@link Result | Result<T>}.
+ * of predicates which return `Result<T>`.
  * @beta
  */
 declare class ExtendedArray<T> extends Array<T> {
     readonly itemDescription: string;
     /**
-     * Constructs an {@link Experimental.ExtendedArray}.
+     * Constructs an {@link Experimental.ExtendedArray | ExtendedArray}.
      * @param itemDescription - Brief description of the type of each item in this array.
      * @param items - The initial contents of the array.
      */
@@ -70,7 +70,7 @@ declare class ExtendedArray<T> extends Array<T> {
      * Type guard to determine if some arbitrary array is an
      * {@link Experimental.ExtendedArray}
      * @param a - The `Array` to be tested.
-     * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray},
+     * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray | ExtendedArray},
      * `false` otherwise.
      */
     static isExtendedArray<T>(a?: T[]): a is ExtendedArray<T>;
@@ -78,42 +78,42 @@ declare class ExtendedArray<T> extends Array<T> {
      * Determines if this array contains exactly one element which matches
      * a supplied predicate.
      * @param predicate - The predicate function to be applied.
-     * @returns Returns {@link Success | Success<T>} with the single matching
-     * result if exactly one item matches `predicate`.  Returns {@link Failure}
+     * @returns Returns `Success<T>` with the single matching
+     * result if exactly one item matches `predicate`.  Returns `Failure<T>`
      * with an error message if there are no matches or more than one match.
      */
     single(predicate?: (item: T) => boolean): Result<T>;
     /**
-     * Returns the first element of an {@link Experimental.ExtendedArray}. Fails with an
+     * Returns the first element of an {@link Experimental.ExtendedArray | ExtendedArray}. Fails with an
      * error message if the array is empty.
      * @param failMessage - Optional message to be displayed in the event of failure.
-     * @returns Returns {@link Success | Success<T>} with the value of the first element
-     * in the array, or {@link Failure} with an error message if the array is empty.
+     * @returns Returns `Success<T>` with the value of the first element
+     * in the array, or `Failure<T>` with an error message if the array is empty.
      */
     first(failMessage?: string): Result<T>;
     /**
-     * Returns an array containing all elements of an {@link Experimental.ExtendedArray}. Fails with
-     * an error message if the array is empty.
+     * Returns an array containing all elements of an {@link Experimental.ExtendedArray | ExtendedArray}.
+     * Fails with an error message if the array is empty.
      * @param failMessage - Optional message to be displayed in the event of failure.
-     * @returns Returns {@link Success | Success<T[]>} with a new (non-extended) `Array`
-     * containing the elements of this array, or {@link Failure} with an error message
+     * @returns Returns `Success<T>` with a new (non-extended) `Array`
+     * containing the elements of this array, or `Failure<T>` with an error message
      * if the array is empty.
      */
     atLeastOne(failMessage?: string): Result<T[]>;
     /**
      * Gets a new (non-extended) `Array` containing all of the elements from this
-     * {@link Experimental.ExtendedArray}.
+     * {@link Experimental.ExtendedArray | ExtendedArray}.
      * @returns A new (non-extended) `Array<T>`.
      */
     all(): T[];
 }
 
 /**
- * A helper function to create a {@link Converter} which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
+ * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
  * @remarks
  * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
  * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
- * @param converter - {@link Converter} used to convert each item in the array
+ * @param converter - `Converter` used to convert each item in the array
  * @param ignoreErrors - Specifies treatment of unconvertible elements
  * @beta
  */
@@ -138,267 +138,267 @@ declare interface Formattable {
     /**
      * Formats an object using the supplied mustache template.
      * @param format - A mustache template used to format the object.
-     * @returns {@link Success} with the resulting string, or {@link Failure}
-         * with an error message if an error occurs.
-         */
-     format(format: string): Result<string>;
-    }
-
-    /**
-     * Base class which adds common formatting.
-     * @beta
+     * @returns `Success<string>` with the resulting string, or `Failure<string>`
+     * with an error message if an error occurs.
      */
-    declare class FormattableBase {
-        /**
-         * Helper enables derived classes to add named details to a formatted presentation.
-         * @param details - An array of detail description strings.
-         * @param label - Label to use for the new detail.
-         * @param value - Value to use for the new detail.
-         * @internal
-         */
-        protected static _tryAddDetail(details: string[], label: string, value: string | undefined): void;
-        /**
-         * {@inheritdoc Experimental.Formattable.format}
-         */
-        format(template: string): Result<string>;
-    }
+    format(format: string): Result<string>;
+}
 
+/**
+ * Base class which adds common formatting.
+ * @beta
+ */
+declare class FormattableBase {
     /**
-     * Destination format for some formatted string.
-     * @beta
+     * Helper enables derived classes to add named details to a formatted presentation.
+     * @param details - An array of detail description strings.
+     * @param label - Label to use for the new detail.
+     * @param value - Value to use for the new detail.
+     * @internal
      */
-    declare type FormatTargets = 'text' | 'markdown' | 'embed';
-
+    protected static _tryAddDetail(details: string[], label: string, value: string | undefined): void;
     /**
-     * Type definition for a formatting function, which takes a `string` and an
-     * item and returns {@link Result | Result<string>}.
-     * @beta
+     * {@inheritdoc Experimental.Formattable.format}
      */
-    declare type Formatter<T> = (format: string, item: T) => Result<string>;
+    format(template: string): Result<string>;
+}
 
-    /**
-     * A collection of {@link Experimental.Formatter | formatters} indexed by target name, to enable
-     * different format methods per output target.
-     * @beta
-     */
-    declare type FormattersByExtendedTarget<TFT extends FormatTargets, T> = Record<TFT, Formatter<T>>;
+/**
+ * Destination format for some formatted string.
+ * @beta
+ */
+declare type FormatTargets = 'text' | 'markdown' | 'embed';
 
-    /**
-     * A collection of {@link Experimental.Formatter | formatters} indexed by the
-     * {@link Experimental.FormatTargets | default supported target formats}.
-     * @beta
-     */
-    declare type FormattersByTarget<T> = FormattersByExtendedTarget<FormatTargets, T>;
+/**
+ * Type definition for a formatting function, which takes a `string` and an
+ * item and returns `Result<string>`.
+ * @beta
+ */
+declare type Formatter<T> = (format: string, item: T) => Result<string>;
+
+/**
+ * A collection of {@link Experimental.Formatter | formatters} indexed by target name, to enable
+ * different format methods per output target.
+ * @beta
+ */
+declare type FormattersByExtendedTarget<TFT extends FormatTargets, T> = Record<TFT, Formatter<T>>;
+
+/**
+ * A collection of {@link Experimental.Formatter | formatters} indexed by the
+ * {@link Experimental.FormatTargets | default supported target formats}.
+ * @beta
+ */
+declare type FormattersByTarget<T> = FormattersByExtendedTarget<FormatTargets, T>;
 
-    declare namespace Hash {
-        export {
-            Md5Normalizer
-        }
+declare namespace Hash {
+    export {
+        Md5Normalizer
     }
-    export { Hash }
+}
+export { Hash }
+
+/**
+ * @public
+ */
+declare type JarFieldPicker<T extends JarRecord = JarRecord> = (record: T) => (keyof T)[];
+
+/**
+ * Represents a single record in a JAR file
+ * @public
+ */
+declare type JarRecord = Record<string, string | string[]>;
+
+/**
+ * Options for a JAR record parser.
+ * @public
+ */
+declare interface JarRecordParserOptions {
+    readonly arrayFields?: string[] | JarFieldPicker;
+    readonly fixedContinuationSize?: number;
+}
+
+/**
+ * A hashing normalizer which computes object
+ * hash using the MD5 algorithm.
+ * @public
+ */
+declare class Md5Normalizer extends Hash_2.HashingNormalizer {
+    constructor();
+    static md5Hash(parts: string[]): string;
+}
+
+/**
+ * Reads a record-jar from an array of strings, each of which represents one
+ * line in the source file.
+ * @param lines - the array of strings to be parsed
+ * @param options - Optional parser configuration
+ * @returns a corresponding array of `Record<string, string>`
+ * @public
+ */
+declare function parseRecordJarLines(lines: string[], options?: JarRecordParserOptions): Result<JarRecord[]>;
 
+/**
+ * Simple implementation of a possibly open-ended range of some comparable
+ * type `<T>` with test and formatting.
+ * @public
+ */
+declare class RangeOf<T> implements RangeOfProperties<T> {
     /**
-     * @public
+     * Minimum extent of the range.
      */
-    declare type JarFieldPicker<T extends JarRecord = JarRecord> = (record: T) => (keyof T)[];
-
+    readonly min?: T;
     /**
-     * Represents a single record in a JAR file
-     * @public
+     * Maximum extent of the range.
      */
-    declare type JarRecord = Record<string, string | string[]>;
-
+    readonly max?: T;
     /**
-     * Options for a JAR record parser.
-     * @public
+     * Creates a new {@link Experimental.RangeOf | RangeOf<T>}.
+     * @param min - Optional minimum extent of the range.
+     * @param max - Optional maximum extent of the range.
      */
-    declare interface JarRecordParserOptions {
-        readonly arrayFields?: string[] | JarFieldPicker;
-        readonly fixedContinuationSize?: number;
-    }
-
+    constructor(min?: T, max?: T);
     /**
-     * A {@link Hash.HashingNormalizer | hashing normalizer} which computes object
-     * hash using the MD5 algorithm.
-     * @public
+     * Static constructor for a {@link Experimental.RangeOf | RangeOf<T>}.
+     * @param init - {@link Experimental.RangeOfProperties | Range initializer}.
+     * @returns A new {@link Experimental.RangeOf | RangeOf<T>}.
      */
-    declare class Md5Normalizer extends Hash_2.HashingNormalizer {
-        constructor();
-        static md5Hash(parts: string[]): string;
-    }
-
+    static createRange<T>(init?: RangeOfProperties<T>): Result<RangeOf<T>>;
     /**
-     * Reads a record-jar from an array of strings, each of which represents one
-     * line in the source file.
-     * @param lines - the array of strings to be parsed
-     * @param options - Optional parser configuration
-     * @returns a corresponding array of `Record<string, string>`
-     * @public
+     * Gets a formatted description of a {@link Experimental.RangeOfProperties | RangeOfProperties<T>} given an
+     * optional set of formats and 'empty' value to use.
+     * @param range - The {@link Experimental.RangeOfProperties | RangeOfProperties<T>} to be formatted.
+     * @param formats - Optional {@link Experimental.RangeOfFormats | formats} to use. Default is
+     * {@link Experimental.DEFAULT_RANGEOF_FORMATS | DEFAULT_RANGEOF_FORMATS}.
+     * @param emptyValue - Value which represents unbounded minimum or maximum for this range. Default is `undefined`.
+     * @returns A string representation of the range.
      */
-    declare function parseRecordJarLines(lines: string[], options?: JarRecordParserOptions): Result<JarRecord[]>;
-
+    static propertiesToString<T>(range: RangeOfProperties<T>, formats?: RangeOfFormats, emptyValue?: T): string | undefined;
     /**
-     * Simple implementation of a possibly open-ended range of some comparable
-     * type `<T>` with test and formatting.
-     * @public
+     * Default comparison uses javascript built-in comparison.
+     * @param t1 - First value to be compared.
+     * @param t2 - Second value to be compared.
+     * @returns `'less'` if `t1` is less than `t2`, `'greater'` if `t1` is larger
+     * and `'equal'` if `t1` and `t2` are equal.
+     * @internal
      */
-    declare class RangeOf<T> implements RangeOfProperties<T> {
-        /**
-         * Minimum extent of the range.
-         */
-        readonly min?: T;
-        /**
-         * Maximum extent of the range.
-         */
-        readonly max?: T;
-        /**
-         * Creates a new {@link Experimental.RangeOf | RangeOf<T>}.
-         * @param min - Optional minimum extent of the range.
-         * @param max - Optional maximum extent of the range.
-         */
-        constructor(min?: T, max?: T);
-        /**
-         * Static constructor for a {@link Experimental.RangeOf | RangeOf<T>}.
-         * @param init - {@link Experimental.RangeOfProperties | Range initializer}.
-         * @returns A new {@link Experimental.RangeOf | RangeOf<T>}.
-         */
-        static createRange<T>(init?: RangeOfProperties<T>): Result<RangeOf<T>>;
-        /**
-         * Gets a formatted description of a {@link Experimental.RangeOfProperties | RangeOfProperties<T>} given an
-         * optional set of formats and 'empty' value to use.
-         * @param range - The {@link Experimental.RangeOfProperties | RangeOfProperties<T>} to be formatted.
-         * @param formats - Optional {@link Experimental.RangeOfFormats | formats} to use. Default is
-         * {@link Experimental.DEFAULT_RANGEOF_FORMATS | DEFAULT_RANGEOF_FORMATS}.
-         * @param emptyValue - Value which represents unbounded minimum or maximum for this range. Default is `undefined`.
-         * @returns A string representation of the range.
-         */
-        static propertiesToString<T>(range: RangeOfProperties<T>, formats?: RangeOfFormats, emptyValue?: T): string | undefined;
-        /**
-         * Default comparison uses javascript built-in comparison.
-         * @param t1 - First value to be compared.
-         * @param t2 - Second value to be compared.
-         * @returns `'less'` if `t1` is less than `t2`, `'greater'` if `t1` is larger
-         * and `'equal'` if `t1` and `t2` are equal.
-         * @internal
-         */
-        protected static _defaultCompare<T>(t1: T, t2: T): 'less' | 'equal' | 'greater';
-        /**
-         * Checks if a supplied value is within this range.
-         * @param t - The value to be tested.
-         * @returns `'included'` if `t` falls within the range, `'less'` if `t` falls
-         * below the minimum extent of the range and `'greater'` if `t` is above the
-         * maximum extent.
-         */
-        check(t: T): 'less' | 'included' | 'greater';
-        /**
-         * Determines if a supplied value is within this range.
-         * @param t - The value to be tested.
-         * @returns Returns `true` if `t` falls within the range, `false` otherwise.
-         */
-        includes(t: T): boolean;
-        /**
-         * Finds the transition value that would bring a supplied value `t` into
-         * range.
-         * @param t - The value to be tested.
-         * @returns The minimum extent of the range if `t` is below the range or
-         * the maximum extent of the range if `t` is above the range.  Returns
-         * `undefined` if `t` already falls within the range.
-         */
-        findTransition(t: T): T | undefined;
-        /**
-         * Formats the minimum and maximum values of this range.
-         * @param format - A format function used to format the values.
-         * @returns A {@link Experimental.RangeOfProperties | RangeOfProperties<string>} containing the
-         * formatted representation of the {@link Experimental.RangeOf.min | minimum} and
-         * {@link Experimental.RangeOf.max | maximum}
-         * extent of the range, or `undefined` for an extent that is not present.
-         */
-        toFormattedProperties(format: (value: T) => string | undefined): RangeOfProperties<string>;
-        /**
-         * Formats this range using the supplied format function.
-         * @param format - Format function used to format minimum and maximum extent values.
-         * @param formats - The {@link Experimental.RangeOfFormats | format strings} used to format the range
-         * (default {@link Experimental.DEFAULT_RANGEOF_FORMATS}).
-         * @returns Returns a formatted representation of this range.
-         */
-        format(format: (value: T) => string | undefined, formats?: RangeOfFormats): string | undefined;
-        /**
-         * Inner compare method can be overridden by a derived class.
-         * @param t1 - First value to compare.
-         * @param t2 - Second value to compare.
-         * @returns `'less'` if `t1` is less than `t2`, `'greater'` if `t1` is larger
-         * and `'equal'` if `t1` and `t2` are equal.
-         * @internal
-         */
-        protected _compare(t1: T, t2: T): 'less' | 'equal' | 'greater';
-    }
-
+    protected static _defaultCompare<T>(t1: T, t2: T): 'less' | 'equal' | 'greater';
     /**
-     * A helper wrapper to construct a {@link Converter} which converts to {@link Experimental.RangeOf | RangeOf<T>}
-     * where `<T>` is some comparable type.
-     * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.
-     * @public
+     * Checks if a supplied value is within this range.
+     * @param t - The value to be tested.
+     * @returns `'included'` if `t` falls within the range, `'less'` if `t` falls
+     * below the minimum extent of the range and `'greater'` if `t` is above the
+     * maximum extent.
      */
-    declare function rangeOf<T, TC = unknown>(converter: Converter<T, TC>): Converter<RangeOf<T>, TC>;
-
+    check(t: T): 'less' | 'included' | 'greater';
     /**
-     * Format strings (in mustache format) to
-     * use for both open-ended and complete
-     * {@link Experimental.RangeOf | RangeOf<T>}.
-     * @public
+     * Determines if a supplied value is within this range.
+     * @param t - The value to be tested.
+     * @returns Returns `true` if `t` falls within the range, `false` otherwise.
      */
-    declare interface RangeOfFormats {
-        minOnly: string;
-        maxOnly: string;
-        minMax: string;
-    }
-
+    includes(t: T): boolean;
     /**
-     * Represents a generic range of some comparable type `<T>`.
-     * @public
+     * Finds the transition value that would bring a supplied value `t` into
+     * range.
+     * @param t - The value to be tested.
+     * @returns The minimum extent of the range if `t` is below the range or
+     * the maximum extent of the range if `t` is above the range.  Returns
+     * `undefined` if `t` already falls within the range.
      */
-    declare interface RangeOfProperties<T> {
-        readonly min?: T;
-        readonly max?: T;
-    }
-
+    findTransition(t: T): T | undefined;
     /**
-     * A helper wrapper to construct a {@link Converter} which converts to an arbitrary strongly-typed
-     * range of some comparable type.
-     * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.
-     * @param constructor - Static constructor to instantiate the object.
-     * @public
+     * Formats the minimum and maximum values of this range.
+     * @param format - A format function used to format the values.
+     * @returns A {@link Experimental.RangeOfProperties | RangeOfProperties<string>} containing the
+     * formatted representation of the {@link Experimental.RangeOf.min | minimum} and
+     * {@link Experimental.RangeOf.max | maximum}
+     * extent of the range, or `undefined` for an extent that is not present.
      */
-    declare function rangeTypeOf<T, RT extends RangeOf<T>, TC = unknown>(converter: Converter<T, TC>, constructor: (init: RangeOfProperties<T>) => Result<RT>): Converter<RT, TC>;
-
+    toFormattedProperties(format: (value: T) => string | undefined): RangeOfProperties<string>;
     /**
-     * Reads a CSV file from a supplied path.
-     * @param srcPath - Source path from which the file is read.
-     * @param options - optional parameters to control the processing
-     * @returns The contents of the file.
-     * @beta
+     * Formats this range using the supplied format function.
+     * @param format - Format function used to format minimum and maximum extent values.
+     * @param formats - The {@link Experimental.RangeOfFormats | format strings} used to format the range
+     * (default {@link Experimental.DEFAULT_RANGEOF_FORMATS}).
+     * @returns Returns a formatted representation of this range.
      */
-    declare function readCsvFileSync(srcPath: string, options?: CsvOptions): Result<unknown>;
-
+    format(format: (value: T) => string | undefined, formats?: RangeOfFormats): string | undefined;
     /**
-     * Reads a record-jar file from a supplied path.
-     * @param srcPath - Source path from which the file is read.
-     * @param options - Optional parser configuration
-     * @returns The contents of the file as an array of `Record<string, string>`
-     * @see https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01
-     * @public
+     * Inner compare method can be overridden by a derived class.
+     * @param t1 - First value to compare.
+     * @param t2 - Second value to compare.
+     * @returns `'less'` if `t1` is less than `t2`, `'greater'` if `t1` is larger
+     * and `'equal'` if `t1` and `t2` are equal.
+     * @internal
      */
-    declare function readRecordJarFileSync(srcPath: string, options?: JarRecordParserOptions): Result<JarRecord[]>;
+    protected _compare(t1: T, t2: T): 'less' | 'equal' | 'greater';
+}
+
+/**
+ * A helper wrapper to construct a `Converter` which converts to {@link Experimental.RangeOf | RangeOf<T>}
+ * where `<T>` is some comparable type.
+ * @param converter - `Converter` used to convert `min` and `max` extent of the range.
+ * @public
+ */
+declare function rangeOf<T, TC = unknown>(converter: Converter<T, TC>): Converter<RangeOf<T>, TC>;
 
-    declare namespace RecordJar {
-        export {
-            parseRecordJarLines,
-            readRecordJarFileSync,
-            JarRecord,
-            JarFieldPicker,
-            JarRecordParserOptions
-        }
+/**
+ * Format strings (in mustache format) to
+ * use for both open-ended and complete
+ * {@link Experimental.RangeOf | RangeOf<T>}.
+ * @public
+ */
+declare interface RangeOfFormats {
+    minOnly: string;
+    maxOnly: string;
+    minMax: string;
+}
+
+/**
+ * Represents a generic range of some comparable type `<T>`.
+ * @public
+ */
+declare interface RangeOfProperties<T> {
+    readonly min?: T;
+    readonly max?: T;
+}
+
+/**
+ * A helper wrapper to construct a `Converter` which converts to an arbitrary strongly-typed
+ * range of some comparable type.
+ * @param converter - `Converter` used to convert `min` and `max` extent of the range.
+ * @param constructor - Static constructor to instantiate the object.
+ * @public
+ */
+declare function rangeTypeOf<T, RT extends RangeOf<T>, TC = unknown>(converter: Converter<T, TC>, constructor: (init: RangeOfProperties<T>) => Result<RT>): Converter<RT, TC>;
+
+/**
+ * Reads a CSV file from a supplied path.
+ * @param srcPath - Source path from which the file is read.
+ * @param options - optional parameters to control the processing
+ * @returns The contents of the file.
+ * @beta
+ */
+declare function readCsvFileSync(srcPath: string, options?: CsvOptions): Result<unknown>;
+
+/**
+ * Reads a record-jar file from a supplied path.
+ * @param srcPath - Source path from which the file is read.
+ * @param options - Optional parser configuration
+ * @returns The contents of the file as an array of `Record<string, string>`
+ * @see https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01
+ * @public
+ */
+declare function readRecordJarFileSync(srcPath: string, options?: JarRecordParserOptions): Result<JarRecord[]>;
+
+declare namespace RecordJar {
+    export {
+        parseRecordJarLines,
+        readRecordJarFileSync,
+        JarRecord,
+        JarFieldPicker,
+        JarRecordParserOptions
     }
-    export { RecordJar }
+}
+export { RecordJar }
 
-    export { }
+export { }

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

@@ -1,27 +1,27 @@
 import { Converter, Converters, Result } from '@fgv/ts-utils';
 import { ExtendedArray, RangeOf, RangeOfProperties } from '../experimental';
 /**
- * A helper function to create a {@link Converter} which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
+ * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
  * @remarks
  * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
  * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
- * @param converter - {@link Converter} used to convert each item in the array
+ * @param converter - `Converter` used to convert each item in the array
  * @param ignoreErrors - Specifies treatment of unconvertible elements
  * @beta
  */
 export declare function extendedArrayOf<T, TC = undefined>(label: string, converter: Converter<T, TC>, onError?: Converters.OnError): Converter<ExtendedArray<T>, TC>;
 /**
- * A helper wrapper to construct a {@link Converter} which converts to an arbitrary strongly-typed
+ * A helper wrapper to construct a `Converter` which converts to an arbitrary strongly-typed
  * range of some comparable type.
- * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.
+ * @param converter - `Converter` used to convert `min` and `max` extent of the range.
  * @param constructor - Static constructor to instantiate the object.
  * @public
  */
 export declare function rangeTypeOf<T, RT extends RangeOf<T>, TC = unknown>(converter: Converter<T, TC>, constructor: (init: RangeOfProperties<T>) => Result<RT>): Converter<RT, TC>;
 /**
- * A helper wrapper to construct a {@link Converter} which converts to {@link Experimental.RangeOf | RangeOf<T>}
+ * A helper wrapper to construct a `Converter` which converts to {@link Experimental.RangeOf | RangeOf<T>}
  * where `<T>` is some comparable type.
- * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.
+ * @param converter - `Converter` used to convert `min` and `max` extent of the range.
  * @public
  */
 export declare function rangeOf<T, TC = unknown>(converter: Converter<T, TC>): Converter<RangeOf<T>, TC>;

package/lib/packlets/conversion/converters.js

@@ -25,11 +25,11 @@ exports.rangeOf = exports.rangeTypeOf = exports.extendedArrayOf = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const experimental_1 = require("../experimental");
 /**
- * A helper function to create a {@link Converter} which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
+ * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
  * @remarks
  * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
  * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
- * @param converter - {@link Converter} used to convert each item in the array
+ * @param converter - `Converter` used to convert each item in the array
  * @param ignoreErrors - Specifies treatment of unconvertible elements
  * @beta
  */
@@ -40,9 +40,9 @@ function extendedArrayOf(label, converter, onError = 'failOnError') {
 }
 exports.extendedArrayOf = extendedArrayOf;
 /**
- * A helper wrapper to construct a {@link Converter} which converts to an arbitrary strongly-typed
+ * A helper wrapper to construct a `Converter` which converts to an arbitrary strongly-typed
  * range of some comparable type.
- * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.
+ * @param converter - `Converter` used to convert `min` and `max` extent of the range.
  * @param constructor - Static constructor to instantiate the object.
  * @public
  */
@@ -60,9 +60,9 @@ function rangeTypeOf(converter, constructor) {
 }
 exports.rangeTypeOf = rangeTypeOf;
 /**
- * A helper wrapper to construct a {@link Converter} which converts to {@link Experimental.RangeOf | RangeOf<T>}
+ * A helper wrapper to construct a `Converter` which converts to {@link Experimental.RangeOf | RangeOf<T>}
  * where `<T>` is some comparable type.
- * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.
+ * @param converter - `Converter` used to convert `min` and `max` extent of the range.
  * @public
  */
 function rangeOf(converter) {

package/lib/packlets/conversion/converters.js.map

@@ -1 +1 @@
-{"version":3,"file":"converters.js","sourceRoot":"","sources":["../../../src/packlets/conversion/converters.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAA+F;AAC/F,kDAA4E;AAE5E;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAC7B,KAAa,EACb,SAA2B,EAC3B,UAA8B,aAAa;IAE3C,OAAO,qBAAU,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAU,EAAE,EAAE;QAC/D,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,4BAAa,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;AACL,CAAC;AARD,0CAQC;AAED;;;;;;GAMG;AACH,SAAgB,WAAW,CACzB,SAA2B,EAC3B,WAAuD;IAEvD,OAAO,IAAI,qBAAU,CAAC,aAAa,CAAC,CAAC,IAAa,EAAE,MAAM,EAAE,OAAY,EAAE,EAAE;QAC1E,MAAM,MAAM,GAAG,qBAAU,CAAC,MAAM,CAC9B;YACE,GAAG,EAAE,SAAS;YACd,GAAG,EAAE,SAAS;SACf,EACD,EAAE,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CACnC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACzB,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,OAAO,WAAW,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACL,CAAC;AAjBD,kCAiBC;AAED;;;;;GAKG;AACH,SAAgB,OAAO,CAAkB,SAA2B;IAClE,OAAO,WAAW,CAAoB,SAAS,EAAE,sBAAO,CAAC,WAAW,CAAC,CAAC;AACxE,CAAC;AAFD,0BAEC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Conversion, Converter, Converters, Result, captureResult, fail } from '@fgv/ts-utils';\nimport { ExtendedArray, RangeOf, RangeOfProperties } from '../experimental';\n\n/**\n * A helper function to create a {@link Converter} which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.\n * @remarks\n * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot\n * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.\n * @param converter - {@link Converter} used to convert each item in the array\n * @param ignoreErrors - Specifies treatment of unconvertible elements\n * @beta\n */\nexport function extendedArrayOf<T, TC = undefined>(\n  label: string,\n  converter: Converter<T, TC>,\n  onError: Converters.OnError = 'failOnError'\n): Converter<ExtendedArray<T>, TC> {\n  return Converters.arrayOf(converter, onError).map((items: T[]) => {\n    return captureResult(() => new ExtendedArray(label, ...items));\n  });\n}\n\n/**\n * A helper wrapper to construct a {@link Converter} which converts to an arbitrary strongly-typed\n * range of some comparable type.\n * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.\n * @param constructor - Static constructor to instantiate the object.\n * @public\n */\nexport function rangeTypeOf<T, RT extends RangeOf<T>, TC = unknown>(\n  converter: Converter<T, TC>,\n  constructor: (init: RangeOfProperties<T>) => Result<RT>\n): Converter<RT, TC> {\n  return new Conversion.BaseConverter((from: unknown, __self, context?: TC) => {\n    const result = Converters.object(\n      {\n        min: converter,\n        max: converter\n      },\n      { optionalFields: ['min', 'max'] }\n    ).convert(from, context);\n    if (result.isSuccess()) {\n      return constructor({ min: result.value.min, max: result.value.max });\n    }\n    return fail(result.message);\n  });\n}\n\n/**\n * A helper wrapper to construct a {@link Converter} which converts to {@link Experimental.RangeOf | RangeOf<T>}\n * where `<T>` is some comparable type.\n * @param converter - {@link Converter} used to convert `min` and `max` extent of the range.\n * @public\n */\nexport function rangeOf<T, TC = unknown>(converter: Converter<T, TC>): Converter<RangeOf<T>, TC> {\n  return rangeTypeOf<T, RangeOf<T>, TC>(converter, RangeOf.createRange);\n}\n"]}
+{"version":3,"file":"converters.js","sourceRoot":"","sources":["../../../src/packlets/conversion/converters.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAA+F;AAC/F,kDAA4E;AAE5E;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAC7B,KAAa,EACb,SAA2B,EAC3B,UAA8B,aAAa;IAE3C,OAAO,qBAAU,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAU,EAAE,EAAE;QAC/D,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,4BAAa,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;AACL,CAAC;AARD,0CAQC;AAED;;;;;;GAMG;AACH,SAAgB,WAAW,CACzB,SAA2B,EAC3B,WAAuD;IAEvD,OAAO,IAAI,qBAAU,CAAC,aAAa,CAAC,CAAC,IAAa,EAAE,MAAM,EAAE,OAAY,EAAE,EAAE;QAC1E,MAAM,MAAM,GAAG,qBAAU,CAAC,MAAM,CAC9B;YACE,GAAG,EAAE,SAAS;YACd,GAAG,EAAE,SAAS;SACf,EACD,EAAE,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CACnC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACzB,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACvB,OAAO,WAAW,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACL,CAAC;AAjBD,kCAiBC;AAED;;;;;GAKG;AACH,SAAgB,OAAO,CAAkB,SAA2B;IAClE,OAAO,WAAW,CAAoB,SAAS,EAAE,sBAAO,CAAC,WAAW,CAAC,CAAC;AACxE,CAAC;AAFD,0BAEC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Conversion, Converter, Converters, Result, captureResult, fail } from '@fgv/ts-utils';\nimport { ExtendedArray, RangeOf, RangeOfProperties } from '../experimental';\n\n/**\n * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.\n * @remarks\n * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot\n * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.\n * @param converter - `Converter` used to convert each item in the array\n * @param ignoreErrors - Specifies treatment of unconvertible elements\n * @beta\n */\nexport function extendedArrayOf<T, TC = undefined>(\n  label: string,\n  converter: Converter<T, TC>,\n  onError: Converters.OnError = 'failOnError'\n): Converter<ExtendedArray<T>, TC> {\n  return Converters.arrayOf(converter, onError).map((items: T[]) => {\n    return captureResult(() => new ExtendedArray(label, ...items));\n  });\n}\n\n/**\n * A helper wrapper to construct a `Converter` which converts to an arbitrary strongly-typed\n * range of some comparable type.\n * @param converter - `Converter` used to convert `min` and `max` extent of the range.\n * @param constructor - Static constructor to instantiate the object.\n * @public\n */\nexport function rangeTypeOf<T, RT extends RangeOf<T>, TC = unknown>(\n  converter: Converter<T, TC>,\n  constructor: (init: RangeOfProperties<T>) => Result<RT>\n): Converter<RT, TC> {\n  return new Conversion.BaseConverter((from: unknown, __self, context?: TC) => {\n    const result = Converters.object(\n      {\n        min: converter,\n        max: converter\n      },\n      { optionalFields: ['min', 'max'] }\n    ).convert(from, context);\n    if (result.isSuccess()) {\n      return constructor({ min: result.value.min, max: result.value.max });\n    }\n    return fail(result.message);\n  });\n}\n\n/**\n * A helper wrapper to construct a `Converter` which converts to {@link Experimental.RangeOf | RangeOf<T>}\n * where `<T>` is some comparable type.\n * @param converter - `Converter` used to convert `min` and `max` extent of the range.\n * @public\n */\nexport function rangeOf<T, TC = unknown>(converter: Converter<T, TC>): Converter<RangeOf<T>, TC> {\n  return rangeTypeOf<T, RangeOf<T>, TC>(converter, RangeOf.createRange);\n}\n"]}

package/lib/packlets/csv/csvHelpers.d.ts

@@ -1,6 +1,6 @@
 import { Result } from '@fgv/ts-utils';
 /**
- * Options for {@link Csv.readCsvFileSync}
+ * Options for {@link Csv.readCsvFileSync | readCsvFileSync}
  * @beta
  */
 export interface CsvOptions {

package/lib/packlets/csv/csvHelpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"csvHelpers.js","sourceRoot":"","sources":["../../../src/packlets/csv/csvHelpers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,4CAAsD;AACtD,uCAAyB;AACzB,yCAAkC;AAClC,2CAA6B;AAW7B;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,OAAe,EAAE,OAAoB;IACnE,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE;QACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC1D,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC;QACxB,2BAA2B;QAC3B,OAAO,IAAA,iBAAK,EAAC,IAAI,kBACf,SAAS,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAClC,MAAM,EAAE,KAAK,EACb,aAAa,EAAE,KAAK,EACpB,cAAc,EAAE,QAAQ,IACrB,OAAO,EACV,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC;AAdD,0CAcC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, captureResult } from '@fgv/ts-utils';\nimport * as fs from 'fs';\nimport { parse } from 'papaparse';\nimport * as path from 'path';\n\n/**\n * Options for {@link Csv.readCsvFileSync}\n * @beta\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface CsvOptions {\n  delimiter?: string;\n}\n\n/**\n * Reads a CSV file from a supplied path.\n * @param srcPath - Source path from which the file is read.\n * @param options - optional parameters to control the processing\n * @returns The contents of the file.\n * @beta\n */\nexport function readCsvFileSync(srcPath: string, options?: CsvOptions): Result<unknown> {\n  return captureResult(() => {\n    const fullPath = path.resolve(srcPath);\n    const body = fs.readFileSync(fullPath, 'utf8').toString();\n    options = options ?? {};\n    // eslint-disable-next-line\n    return parse(body, {\n      transform: (s: string) => s.trim(),\n      header: false,\n      dynamicTyping: false,\n      skipEmptyLines: 'greedy',\n      ...options\n    }).data.slice(1);\n  });\n}\n"]}
+{"version":3,"file":"csvHelpers.js","sourceRoot":"","sources":["../../../src/packlets/csv/csvHelpers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,4CAAsD;AACtD,uCAAyB;AACzB,yCAAkC;AAClC,2CAA6B;AAW7B;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,OAAe,EAAE,OAAoB;IACnE,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE;QACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC1D,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC;QACxB,2BAA2B;QAC3B,OAAO,IAAA,iBAAK,EAAC,IAAI,kBACf,SAAS,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAClC,MAAM,EAAE,KAAK,EACb,aAAa,EAAE,KAAK,EACpB,cAAc,EAAE,QAAQ,IACrB,OAAO,EACV,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC;AAdD,0CAcC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, captureResult } from '@fgv/ts-utils';\nimport * as fs from 'fs';\nimport { parse } from 'papaparse';\nimport * as path from 'path';\n\n/**\n * Options for {@link Csv.readCsvFileSync | readCsvFileSync}\n * @beta\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface CsvOptions {\n  delimiter?: string;\n}\n\n/**\n * Reads a CSV file from a supplied path.\n * @param srcPath - Source path from which the file is read.\n * @param options - optional parameters to control the processing\n * @returns The contents of the file.\n * @beta\n */\nexport function readCsvFileSync(srcPath: string, options?: CsvOptions): Result<unknown> {\n  return captureResult(() => {\n    const fullPath = path.resolve(srcPath);\n    const body = fs.readFileSync(fullPath, 'utf8').toString();\n    options = options ?? {};\n    // eslint-disable-next-line\n    return parse(body, {\n      transform: (s: string) => s.trim(),\n      header: false,\n      dynamicTyping: false,\n      skipEmptyLines: 'greedy',\n      ...options\n    }).data.slice(1);\n  });\n}\n"]}

package/lib/packlets/experimental/extendedArray.d.ts

@@ -1,13 +1,13 @@
 import { Result } from '@fgv/ts-utils';
 /**
  * An experimental array template which extend built-in `Array` to include a handful
- * of predicates which return {@link Result | Result<T>}.
+ * of predicates which return `Result<T>`.
  * @beta
  */
 export declare class ExtendedArray<T> extends Array<T> {
     readonly itemDescription: string;
     /**
-     * Constructs an {@link Experimental.ExtendedArray}.
+     * Constructs an {@link Experimental.ExtendedArray | ExtendedArray}.
      * @param itemDescription - Brief description of the type of each item in this array.
      * @param items - The initial contents of the array.
      */
@@ -16,7 +16,7 @@ export declare class ExtendedArray<T> extends Array<T> {
      * Type guard to determine if some arbitrary array is an
      * {@link Experimental.ExtendedArray}
      * @param a - The `Array` to be tested.
-     * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray},
+     * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray | ExtendedArray},
      * `false` otherwise.
      */
     static isExtendedArray<T>(a?: T[]): a is ExtendedArray<T>;
@@ -24,31 +24,31 @@ export declare class ExtendedArray<T> extends Array<T> {
      * Determines if this array contains exactly one element which matches
      * a supplied predicate.
      * @param predicate - The predicate function to be applied.
-     * @returns Returns {@link Success | Success<T>} with the single matching
-     * result if exactly one item matches `predicate`.  Returns {@link Failure}
+     * @returns Returns `Success<T>` with the single matching
+     * result if exactly one item matches `predicate`.  Returns `Failure<T>`
      * with an error message if there are no matches or more than one match.
      */
     single(predicate?: (item: T) => boolean): Result<T>;
     /**
-     * Returns the first element of an {@link Experimental.ExtendedArray}. Fails with an
+     * Returns the first element of an {@link Experimental.ExtendedArray | ExtendedArray}. Fails with an
      * error message if the array is empty.
      * @param failMessage - Optional message to be displayed in the event of failure.
-     * @returns Returns {@link Success | Success<T>} with the value of the first element
-     * in the array, or {@link Failure} with an error message if the array is empty.
+     * @returns Returns `Success<T>` with the value of the first element
+     * in the array, or `Failure<T>` with an error message if the array is empty.
      */
     first(failMessage?: string): Result<T>;
     /**
-     * Returns an array containing all elements of an {@link Experimental.ExtendedArray}. Fails with
-     * an error message if the array is empty.
+     * Returns an array containing all elements of an {@link Experimental.ExtendedArray | ExtendedArray}.
+     * Fails with an error message if the array is empty.
      * @param failMessage - Optional message to be displayed in the event of failure.
-     * @returns Returns {@link Success | Success<T[]>} with a new (non-extended) `Array`
-     * containing the elements of this array, or {@link Failure} with an error message
+     * @returns Returns `Success<T>` with a new (non-extended) `Array`
+     * containing the elements of this array, or `Failure<T>` with an error message
      * if the array is empty.
      */
     atLeastOne(failMessage?: string): Result<T[]>;
     /**
      * Gets a new (non-extended) `Array` containing all of the elements from this
-     * {@link Experimental.ExtendedArray}.
+     * {@link Experimental.ExtendedArray | ExtendedArray}.
      * @returns A new (non-extended) `Array<T>`.
      */
     all(): T[];

package/lib/packlets/experimental/extendedArray.js

@@ -25,12 +25,12 @@ exports.ExtendedArray = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 /**
  * An experimental array template which extend built-in `Array` to include a handful
- * of predicates which return {@link Result | Result<T>}.
+ * of predicates which return `Result<T>`.
  * @beta
  */
 class ExtendedArray extends Array {
     /**
-     * Constructs an {@link Experimental.ExtendedArray}.
+     * Constructs an {@link Experimental.ExtendedArray | ExtendedArray}.
      * @param itemDescription - Brief description of the type of each item in this array.
      * @param items - The initial contents of the array.
      */
@@ -42,7 +42,7 @@ class ExtendedArray extends Array {
      * Type guard to determine if some arbitrary array is an
      * {@link Experimental.ExtendedArray}
      * @param a - The `Array` to be tested.
-     * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray},
+     * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray | ExtendedArray},
      * `false` otherwise.
      */
     static isExtendedArray(a) {
@@ -52,8 +52,8 @@ class ExtendedArray extends Array {
      * Determines if this array contains exactly one element which matches
      * a supplied predicate.
      * @param predicate - The predicate function to be applied.
-     * @returns Returns {@link Success | Success<T>} with the single matching
-     * result if exactly one item matches `predicate`.  Returns {@link Failure}
+     * @returns Returns `Success<T>` with the single matching
+     * result if exactly one item matches `predicate`.  Returns `Failure<T>`
      * with an error message if there are no matches or more than one match.
      */
     single(predicate) {
@@ -67,11 +67,11 @@ class ExtendedArray extends Array {
         return (0, ts_utils_1.fail)(`${this.itemDescription} matches ${match.length} items`);
     }
     /**
-     * Returns the first element of an {@link Experimental.ExtendedArray}. Fails with an
+     * Returns the first element of an {@link Experimental.ExtendedArray | ExtendedArray}. Fails with an
      * error message if the array is empty.
      * @param failMessage - Optional message to be displayed in the event of failure.
-     * @returns Returns {@link Success | Success<T>} with the value of the first element
-     * in the array, or {@link Failure} with an error message if the array is empty.
+     * @returns Returns `Success<T>` with the value of the first element
+     * in the array, or `Failure<T>` with an error message if the array is empty.
      */
     first(failMessage) {
         if (this.length > 0) {
@@ -80,11 +80,11 @@ class ExtendedArray extends Array {
         return (0, ts_utils_1.fail)(failMessage !== null && failMessage !== void 0 ? failMessage : `${this.itemDescription} not found`);
     }
     /**
-     * Returns an array containing all elements of an {@link Experimental.ExtendedArray}. Fails with
-     * an error message if the array is empty.
+     * Returns an array containing all elements of an {@link Experimental.ExtendedArray | ExtendedArray}.
+     * Fails with an error message if the array is empty.
      * @param failMessage - Optional message to be displayed in the event of failure.
-     * @returns Returns {@link Success | Success<T[]>} with a new (non-extended) `Array`
-     * containing the elements of this array, or {@link Failure} with an error message
+     * @returns Returns `Success<T>` with a new (non-extended) `Array`
+     * containing the elements of this array, or `Failure<T>` with an error message
      * if the array is empty.
      */
     atLeastOne(failMessage) {
@@ -95,7 +95,7 @@ class ExtendedArray extends Array {
     }
     /**
      * Gets a new (non-extended) `Array` containing all of the elements from this
-     * {@link Experimental.ExtendedArray}.
+     * {@link Experimental.ExtendedArray | ExtendedArray}.
      * @returns A new (non-extended) `Array<T>`.
      */
     all() {

package/lib/packlets/experimental/extendedArray.js.map

@@ -1 +1 @@
-{"version":3,"file":"extendedArray.js","sourceRoot":"","sources":["../../../src/packlets/experimental/extendedArray.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAAsD;AAEtD;;;;GAIG;AACH,MAAa,aAAiB,SAAQ,KAAQ;IAG5C;;;;OAIG;IACH,YAAmB,eAAuB,EAAE,GAAG,KAAU;QACvD,KAAK,CAAC,GAAG,KAAK,CAAC,CAAC;QAChB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,eAAe,CAAI,CAAO;QACtC,OAAO,CAAC,YAAY,aAAa,CAAC;IACpC,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,SAAgC;QAC5C,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,IAAA,kBAAO,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,IAAA,eAAI,EAAC,GAAG,IAAI,CAAC,eAAe,YAAY,CAAC,CAAC;QACnD,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,GAAG,IAAI,CAAC,eAAe,YAAY,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,WAAoB;QAC/B,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO,IAAA,kBAAO,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,WAAW,aAAX,WAAW,cAAX,WAAW,GAAI,GAAG,IAAI,CAAC,eAAe,YAAY,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;OAOG;IACI,UAAU,CAAC,WAAoB;QACpC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO,IAAA,kBAAO,EAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,WAAW,aAAX,WAAW,cAAX,WAAW,GAAI,GAAG,IAAI,CAAC,eAAe,YAAY,CAAC,CAAC;IAClE,CAAC;IAED;;;;OAIG;IACI,GAAG;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF;AAhFD,sCAgFC","sourcesContent":["/*\r\n * Copyright (c) 2020 Erik Fortune\r\n *\r\n * Permission is hereby granted, free of charge, to any person obtaining a copy\r\n * of this software and associated documentation files (the \"Software\"), to deal\r\n * in the Software without restriction, including without limitation the rights\r\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n * copies of the Software, and to permit persons to whom the Software is\r\n * furnished to do so, subject to the following conditions:\r\n *\r\n * The above copyright notice and this permission notice shall be included in all\r\n * copies or substantial portions of the Software.\r\n *\r\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n * SOFTWARE.\r\n */\r\n\r\nimport { Result, fail, succeed } from '@fgv/ts-utils';\r\n\r\n/**\r\n * An experimental array template which extend built-in `Array` to include a handful\r\n * of predicates which return {@link Result | Result<T>}.\r\n * @beta\r\n */\r\nexport class ExtendedArray<T> extends Array<T> {\r\n  public readonly itemDescription: string;\r\n\r\n  /**\r\n   * Constructs an {@link Experimental.ExtendedArray}.\r\n   * @param itemDescription - Brief description of the type of each item in this array.\r\n   * @param items - The initial contents of the array.\r\n   */\r\n  public constructor(itemDescription: string, ...items: T[]) {\r\n    super(...items);\r\n    this.itemDescription = itemDescription;\r\n  }\r\n\r\n  /**\r\n   * Type guard to determine if some arbitrary array is an\r\n   * {@link Experimental.ExtendedArray}\r\n   * @param a - The `Array` to be tested.\r\n   * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray},\r\n   * `false` otherwise.\r\n   */\r\n  public static isExtendedArray<T>(a?: T[]): a is ExtendedArray<T> {\r\n    return a instanceof ExtendedArray;\r\n  }\r\n\r\n  /**\r\n   * Determines if this array contains exactly one element which matches\r\n   * a supplied predicate.\r\n   * @param predicate - The predicate function to be applied.\r\n   * @returns Returns {@link Success | Success<T>} with the single matching\r\n   * result if exactly one item matches `predicate`.  Returns {@link Failure}\r\n   * with an error message if there are no matches or more than one match.\r\n   */\r\n  public single(predicate?: (item: T) => boolean): Result<T> {\r\n    const match = predicate ? this.filter(predicate) : this;\r\n    if (match.length === 1) {\r\n      return succeed(match[0]);\r\n    }\r\n    if (match.length === 0) {\r\n      return fail(`${this.itemDescription} not found`);\r\n    }\r\n    return fail(`${this.itemDescription} matches ${match.length} items`);\r\n  }\r\n\r\n  /**\r\n   * Returns the first element of an {@link Experimental.ExtendedArray}. Fails with an\r\n   * error message if the array is empty.\r\n   * @param failMessage - Optional message to be displayed in the event of failure.\r\n   * @returns Returns {@link Success | Success<T>} with the value of the first element\r\n   * in the array, or {@link Failure} with an error message if the array is empty.\r\n   */\r\n  public first(failMessage?: string): Result<T> {\r\n    if (this.length > 0) {\r\n      return succeed(this[0]);\r\n    }\r\n    return fail(failMessage ?? `${this.itemDescription} not found`);\r\n  }\r\n\r\n  /**\r\n   * Returns an array containing all elements of an {@link Experimental.ExtendedArray}. Fails with\r\n   * an error message if the array is empty.\r\n   * @param failMessage - Optional message to be displayed in the event of failure.\r\n   * @returns Returns {@link Success | Success<T[]>} with a new (non-extended) `Array`\r\n   * containing the elements of this array, or {@link Failure} with an error message\r\n   * if the array is empty.\r\n   */\r\n  public atLeastOne(failMessage?: string): Result<T[]> {\r\n    if (this.length > 0) {\r\n      return succeed(Array.from(this));\r\n    }\r\n    return fail(failMessage ?? `${this.itemDescription} not found`);\r\n  }\r\n\r\n  /**\r\n   * Gets a new (non-extended) `Array` containing all of the elements from this\r\n   * {@link Experimental.ExtendedArray}.\r\n   * @returns A new (non-extended) `Array<T>`.\r\n   */\r\n  public all(): T[] {\r\n    return Array.from(this);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"extendedArray.js","sourceRoot":"","sources":["../../../src/packlets/experimental/extendedArray.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAAsD;AAEtD;;;;GAIG;AACH,MAAa,aAAiB,SAAQ,KAAQ;IAG5C;;;;OAIG;IACH,YAAmB,eAAuB,EAAE,GAAG,KAAU;QACvD,KAAK,CAAC,GAAG,KAAK,CAAC,CAAC;QAChB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,eAAe,CAAI,CAAO;QACtC,OAAO,CAAC,YAAY,aAAa,CAAC;IACpC,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,SAAgC;QAC5C,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,IAAA,kBAAO,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,IAAA,eAAI,EAAC,GAAG,IAAI,CAAC,eAAe,YAAY,CAAC,CAAC;QACnD,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,GAAG,IAAI,CAAC,eAAe,YAAY,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,WAAoB;QAC/B,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO,IAAA,kBAAO,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,WAAW,aAAX,WAAW,cAAX,WAAW,GAAI,GAAG,IAAI,CAAC,eAAe,YAAY,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;OAOG;IACI,UAAU,CAAC,WAAoB;QACpC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO,IAAA,kBAAO,EAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,WAAW,aAAX,WAAW,cAAX,WAAW,GAAI,GAAG,IAAI,CAAC,eAAe,YAAY,CAAC,CAAC;IAClE,CAAC;IAED;;;;OAIG;IACI,GAAG;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF;AAhFD,sCAgFC","sourcesContent":["/*\r\n * Copyright (c) 2020 Erik Fortune\r\n *\r\n * Permission is hereby granted, free of charge, to any person obtaining a copy\r\n * of this software and associated documentation files (the \"Software\"), to deal\r\n * in the Software without restriction, including without limitation the rights\r\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n * copies of the Software, and to permit persons to whom the Software is\r\n * furnished to do so, subject to the following conditions:\r\n *\r\n * The above copyright notice and this permission notice shall be included in all\r\n * copies or substantial portions of the Software.\r\n *\r\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n * SOFTWARE.\r\n */\r\n\r\nimport { Result, fail, succeed } from '@fgv/ts-utils';\r\n\r\n/**\r\n * An experimental array template which extend built-in `Array` to include a handful\r\n * of predicates which return `Result<T>`.\r\n * @beta\r\n */\r\nexport class ExtendedArray<T> extends Array<T> {\r\n  public readonly itemDescription: string;\r\n\r\n  /**\r\n   * Constructs an {@link Experimental.ExtendedArray | ExtendedArray}.\r\n   * @param itemDescription - Brief description of the type of each item in this array.\r\n   * @param items - The initial contents of the array.\r\n   */\r\n  public constructor(itemDescription: string, ...items: T[]) {\r\n    super(...items);\r\n    this.itemDescription = itemDescription;\r\n  }\r\n\r\n  /**\r\n   * Type guard to determine if some arbitrary array is an\r\n   * {@link Experimental.ExtendedArray}\r\n   * @param a - The `Array` to be tested.\r\n   * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray | ExtendedArray},\r\n   * `false` otherwise.\r\n   */\r\n  public static isExtendedArray<T>(a?: T[]): a is ExtendedArray<T> {\r\n    return a instanceof ExtendedArray;\r\n  }\r\n\r\n  /**\r\n   * Determines if this array contains exactly one element which matches\r\n   * a supplied predicate.\r\n   * @param predicate - The predicate function to be applied.\r\n   * @returns Returns `Success<T>` with the single matching\r\n   * result if exactly one item matches `predicate`.  Returns `Failure<T>`\r\n   * with an error message if there are no matches or more than one match.\r\n   */\r\n  public single(predicate?: (item: T) => boolean): Result<T> {\r\n    const match = predicate ? this.filter(predicate) : this;\r\n    if (match.length === 1) {\r\n      return succeed(match[0]);\r\n    }\r\n    if (match.length === 0) {\r\n      return fail(`${this.itemDescription} not found`);\r\n    }\r\n    return fail(`${this.itemDescription} matches ${match.length} items`);\r\n  }\r\n\r\n  /**\r\n   * Returns the first element of an {@link Experimental.ExtendedArray | ExtendedArray}. Fails with an\r\n   * error message if the array is empty.\r\n   * @param failMessage - Optional message to be displayed in the event of failure.\r\n   * @returns Returns `Success<T>` with the value of the first element\r\n   * in the array, or `Failure<T>` with an error message if the array is empty.\r\n   */\r\n  public first(failMessage?: string): Result<T> {\r\n    if (this.length > 0) {\r\n      return succeed(this[0]);\r\n    }\r\n    return fail(failMessage ?? `${this.itemDescription} not found`);\r\n  }\r\n\r\n  /**\r\n   * Returns an array containing all elements of an {@link Experimental.ExtendedArray | ExtendedArray}.\r\n   * Fails with an error message if the array is empty.\r\n   * @param failMessage - Optional message to be displayed in the event of failure.\r\n   * @returns Returns `Success<T>` with a new (non-extended) `Array`\r\n   * containing the elements of this array, or `Failure<T>` with an error message\r\n   * if the array is empty.\r\n   */\r\n  public atLeastOne(failMessage?: string): Result<T[]> {\r\n    if (this.length > 0) {\r\n      return succeed(Array.from(this));\r\n    }\r\n    return fail(failMessage ?? `${this.itemDescription} not found`);\r\n  }\r\n\r\n  /**\r\n   * Gets a new (non-extended) `Array` containing all of the elements from this\r\n   * {@link Experimental.ExtendedArray | ExtendedArray}.\r\n   * @returns A new (non-extended) `Array<T>`.\r\n   */\r\n  public all(): T[] {\r\n    return Array.from(this);\r\n  }\r\n}\r\n"]}

package/lib/packlets/experimental/formatter.d.ts

@@ -12,7 +12,7 @@ export interface Formattable {
     /**
      * Formats an object using the supplied mustache template.
      * @param format - A mustache template used to format the object.
-     * @returns {@link Success} with the resulting string, or {@link Failure}
+     * @returns `Success<string>` with the resulting string, or `Failure<string>`
      * with an error message if an error occurs.
      */
     format(format: string): Result<string>;
@@ -37,7 +37,7 @@ export declare class FormattableBase {
 }
 /**
  * Type definition for a formatting function, which takes a `string` and an
- * item and returns {@link Result | Result<string>}.
+ * item and returns `Result<string>`.
  * @beta
  */
 export type Formatter<T> = (format: string, item: T) => Result<string>;

package/lib/packlets/experimental/formatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../../src/packlets/experimental/formatter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;AAEH,4CAA2E;AAC3E,wDAAgC;AAEhC,kBAAQ,CAAC,MAAM,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC;AAuBnC;;;GAGG;AACH,MAAa,eAAe;IAC1B;;;;;;OAMG;IACO,MAAM,CAAC,aAAa,CAAC,OAAiB,EAAE,KAAa,EAAE,KAAyB;QACxF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,KAAK,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YAC7C,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,QAAgB;QAC5B,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CAAC,kBAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9D,CAAC;CACF;AArBD,0CAqBC;AAsBD;;;;;;;;GAQG;AACH,SAAgB,UAAU,CAAI,MAAc,EAAE,KAAU,EAAE,aAA2B;IACnF,OAAO,IAAA,qBAAU,EACf,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACjB,OAAO,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC,CAAC,CACH,CAAC,SAAS,CAAC,CAAC,OAAiB,EAAE,EAAE;QAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QACjD,OAAO,IAAA,kBAAO,EAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC;AATD,gCASC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, captureResult, mapResults, succeed } from '@fgv/ts-utils';\nimport Mustache from 'mustache';\n\nMustache.escape = (s: string) => s;\n\n/**\n * Destination format for some formatted string.\n * @beta\n */\nexport type FormatTargets = 'text' | 'markdown' | 'embed';\n\n/**\n * Interface for an object that can be formatted.\n * @beta\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface Formattable {\n  /**\n   * Formats an object using the supplied mustache template.\n   * @param format - A mustache template used to format the object.\n   * @returns {@link Success} with the resulting string, or {@link Failure}\n   * with an error message if an error occurs.\n   */\n  format(format: string): Result<string>;\n}\n\n/**\n * Base class which adds common formatting.\n * @beta\n */\nexport class FormattableBase {\n  /**\n   * Helper enables derived classes to add named details to a formatted presentation.\n   * @param details - An array of detail description strings.\n   * @param label - Label to use for the new detail.\n   * @param value - Value to use for the new detail.\n   * @internal\n   */\n  protected static _tryAddDetail(details: string[], label: string, value: string | undefined): void {\n    if (value !== undefined) {\n      const padded = `  ${label}:`.padEnd(20, ' ');\n      details.push(`${padded} ${value}`);\n    }\n  }\n\n  /**\n   * {@inheritdoc Experimental.Formattable.format}\n   */\n  public format(template: string): Result<string> {\n    return captureResult(() => Mustache.render(template, this));\n  }\n}\n\n/**\n * Type definition for a formatting function, which takes a `string` and an\n * item and returns {@link Result | Result<string>}.\n * @beta\n */\nexport type Formatter<T> = (format: string, item: T) => Result<string>;\n\n/**\n * A collection of {@link Experimental.Formatter | formatters} indexed by target name, to enable\n * different format methods per output target.\n * @beta\n */\nexport type FormattersByExtendedTarget<TFT extends FormatTargets, T> = Record<TFT, Formatter<T>>;\n/**\n * A collection of {@link Experimental.Formatter | formatters} indexed by the\n * {@link Experimental.FormatTargets | default supported target formats}.\n * @beta\n */\nexport type FormattersByTarget<T> = FormattersByExtendedTarget<FormatTargets, T>;\n\n/**\n * Formats a list of items using the supplied template and formatter, one result\n * per output line.\n * @param format - A mustache template used to format each item.\n * @param items - The items to be formatted.\n * @param itemFormatter - The {@link Experimental.Formatter | Formatter<T>} used to format each item.\n * @returns The resulting string.\n * @beta\n */\nexport function formatList<T>(format: string, items: T[], itemFormatter: Formatter<T>): Result<string> {\n  return mapResults(\n    items.map((item) => {\n      return itemFormatter(format, item);\n    })\n  ).onSuccess((results: string[]) => {\n    const filtered = results.filter((s) => s !== '');\n    return succeed(filtered.join('\\n'));\n  });\n}\n"]}
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../../src/packlets/experimental/formatter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;AAEH,4CAA2E;AAC3E,wDAAgC;AAEhC,kBAAQ,CAAC,MAAM,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC;AAuBnC;;;GAGG;AACH,MAAa,eAAe;IAC1B;;;;;;OAMG;IACO,MAAM,CAAC,aAAa,CAAC,OAAiB,EAAE,KAAa,EAAE,KAAyB;QACxF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,KAAK,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YAC7C,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,QAAgB;QAC5B,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CAAC,kBAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9D,CAAC;CACF;AArBD,0CAqBC;AAsBD;;;;;;;;GAQG;AACH,SAAgB,UAAU,CAAI,MAAc,EAAE,KAAU,EAAE,aAA2B;IACnF,OAAO,IAAA,qBAAU,EACf,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACjB,OAAO,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC,CAAC,CACH,CAAC,SAAS,CAAC,CAAC,OAAiB,EAAE,EAAE;QAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QACjD,OAAO,IAAA,kBAAO,EAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC;AATD,gCASC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, captureResult, mapResults, succeed } from '@fgv/ts-utils';\nimport Mustache from 'mustache';\n\nMustache.escape = (s: string) => s;\n\n/**\n * Destination format for some formatted string.\n * @beta\n */\nexport type FormatTargets = 'text' | 'markdown' | 'embed';\n\n/**\n * Interface for an object that can be formatted.\n * @beta\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface Formattable {\n  /**\n   * Formats an object using the supplied mustache template.\n   * @param format - A mustache template used to format the object.\n   * @returns `Success<string>` with the resulting string, or `Failure<string>`\n   * with an error message if an error occurs.\n   */\n  format(format: string): Result<string>;\n}\n\n/**\n * Base class which adds common formatting.\n * @beta\n */\nexport class FormattableBase {\n  /**\n   * Helper enables derived classes to add named details to a formatted presentation.\n   * @param details - An array of detail description strings.\n   * @param label - Label to use for the new detail.\n   * @param value - Value to use for the new detail.\n   * @internal\n   */\n  protected static _tryAddDetail(details: string[], label: string, value: string | undefined): void {\n    if (value !== undefined) {\n      const padded = `  ${label}:`.padEnd(20, ' ');\n      details.push(`${padded} ${value}`);\n    }\n  }\n\n  /**\n   * {@inheritdoc Experimental.Formattable.format}\n   */\n  public format(template: string): Result<string> {\n    return captureResult(() => Mustache.render(template, this));\n  }\n}\n\n/**\n * Type definition for a formatting function, which takes a `string` and an\n * item and returns `Result<string>`.\n * @beta\n */\nexport type Formatter<T> = (format: string, item: T) => Result<string>;\n\n/**\n * A collection of {@link Experimental.Formatter | formatters} indexed by target name, to enable\n * different format methods per output target.\n * @beta\n */\nexport type FormattersByExtendedTarget<TFT extends FormatTargets, T> = Record<TFT, Formatter<T>>;\n/**\n * A collection of {@link Experimental.Formatter | formatters} indexed by the\n * {@link Experimental.FormatTargets | default supported target formats}.\n * @beta\n */\nexport type FormattersByTarget<T> = FormattersByExtendedTarget<FormatTargets, T>;\n\n/**\n * Formats a list of items using the supplied template and formatter, one result\n * per output line.\n * @param format - A mustache template used to format each item.\n * @param items - The items to be formatted.\n * @param itemFormatter - The {@link Experimental.Formatter | Formatter<T>} used to format each item.\n * @returns The resulting string.\n * @beta\n */\nexport function formatList<T>(format: string, items: T[], itemFormatter: Formatter<T>): Result<string> {\n  return mapResults(\n    items.map((item) => {\n      return itemFormatter(format, item);\n    })\n  ).onSuccess((results: string[]) => {\n    const filtered = results.filter((s) => s !== '');\n    return succeed(filtered.join('\\n'));\n  });\n}\n"]}

package/lib/packlets/hash/md5Normalizer.d.ts

@@ -1,6 +1,6 @@
 import { Hash } from '@fgv/ts-utils';
 /**
- * A {@link Hash.HashingNormalizer | hashing normalizer} which computes object
+ * A hashing normalizer which computes object
  * hash using the MD5 algorithm.
  * @public
  */

package/lib/packlets/hash/md5Normalizer.js

@@ -48,7 +48,7 @@ exports.Md5Normalizer = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const crypto = __importStar(require("crypto"));
 /**
- * A {@link Hash.HashingNormalizer | hashing normalizer} which computes object
+ * A hashing normalizer which computes object
  * hash using the MD5 algorithm.
  * @public
  */

package/lib/packlets/hash/md5Normalizer.js.map

@@ -1 +1 @@
-{"version":3,"file":"md5Normalizer.js","sourceRoot":"","sources":["../../../src/packlets/hash/md5Normalizer.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,4CAAqC;AACrC,+CAAiC;AACjC;;;;GAIG;AACH,MAAa,aAAc,SAAQ,eAAI,CAAC,iBAAiB;IACvD;QACE,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAEM,MAAM,CAAC,OAAO,CAAC,KAAe;QACnC,OAAO,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChF,CAAC;CACF;AARD,sCAQC","sourcesContent":["/*\n * Copyright (c) 2023 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Hash } from '@fgv/ts-utils';\nimport * as crypto from 'crypto';\n/**\n * A {@link Hash.HashingNormalizer | hashing normalizer} which computes object\n * hash using the MD5 algorithm.\n * @public\n */\nexport class Md5Normalizer extends Hash.HashingNormalizer {\n  public constructor() {\n    super(Md5Normalizer.md5Hash);\n  }\n\n  public static md5Hash(parts: string[]): string {\n    return crypto.createHash('md5').update(parts.join('|'), 'utf8').digest('hex');\n  }\n}\n"]}
+{"version":3,"file":"md5Normalizer.js","sourceRoot":"","sources":["../../../src/packlets/hash/md5Normalizer.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,4CAAqC;AACrC,+CAAiC;AACjC;;;;GAIG;AACH,MAAa,aAAc,SAAQ,eAAI,CAAC,iBAAiB;IACvD;QACE,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAEM,MAAM,CAAC,OAAO,CAAC,KAAe;QACnC,OAAO,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChF,CAAC;CACF;AARD,sCAQC","sourcesContent":["/*\n * Copyright (c) 2023 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Hash } from '@fgv/ts-utils';\nimport * as crypto from 'crypto';\n/**\n * A hashing normalizer which computes object\n * hash using the MD5 algorithm.\n * @public\n */\nexport class Md5Normalizer extends Hash.HashingNormalizer {\n  public constructor() {\n    super(Md5Normalizer.md5Hash);\n  }\n\n  public static md5Hash(parts: string[]): string {\n    return crypto.createHash('md5').update(parts.join('|'), 'utf8').digest('hex');\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fgv/ts-extras",
-	"version": "2.1.1-alpha.2",
+	"version": "3.0.0-alpha.1",
 	"description": "Assorted Typescript Utilities",
 	"main": "lib/index.js",
 	"types": "dist/ts-extras.d.ts",
@@ -46,8 +46,8 @@
 		"@types/heft-jest": "1.0.6",
 		"@rushstack/heft-jest-plugin": "~0.11.0",
 		"eslint-plugin-tsdoc": "~0.2.17",
-		"@fgv/ts-utils-jest": "2.1.1-alpha.2",
-		"@fgv/ts-utils": "2.1.1-alpha.2"
+		"@fgv/ts-utils-jest": "3.0.0-alpha.1",
+		"@fgv/ts-utils": "3.0.0-alpha.1"
 	},
 	"dependencies": {
 		"luxon": "^3.4.4",
@@ -55,7 +55,7 @@
 		"papaparse": "^5.4.1"
 	},
 	"peerDependencies": {
-		"@fgv/ts-utils": "2.1.1-alpha.2"
+		"@fgv/ts-utils": "3.0.0-alpha.1"
 	},
 	"scripts": {
 		"build": "heft test --clean",