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

package/dist/ts-extras.d.ts

@@ -0,0 +1,602 @@
+import { Conversion } from '@fgv/ts-utils';
+import { Converter } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-utils';
+import { Hash as Hash_2 } from '@fgv/ts-utils';
+import { Result } from '@fgv/ts-utils';
+import { Validator } from '@fgv/ts-utils';
+
+declare namespace Converters {
+    export {
+        templateString,
+        extendedArrayOf,
+        rangeTypeOf,
+        rangeOf,
+        isoDate
+    }
+}
+export { Converters }
+
+declare namespace Csv {
+    export {
+        readCsvFileSync,
+        CsvOptions
+    }
+}
+export { Csv }
+
+/**
+ * Options for {@link Csv.readCsvFileSync | readCsvFileSync}
+ * @beta
+ */
+declare interface CsvOptions {
+    delimiter?: string;
+}
+
+/**
+ * Default {@link Experimental.RangeOfFormats | formats} to use for both
+ * open-ended and complete {@link Experimental.RangeOf | RangeOf<T>}.
+ * @public
+ */
+declare const DEFAULT_RANGEOF_FORMATS: RangeOfFormats;
+
+declare namespace Experimental {
+    export {
+        ExtendedArray,
+        formatList,
+        FormatTargets,
+        Formattable,
+        FormattableBase,
+        Formatter,
+        FormattersByExtendedTarget,
+        FormattersByTarget,
+        RangeOfProperties,
+        RangeOfFormats,
+        DEFAULT_RANGEOF_FORMATS,
+        RangeOf
+    }
+}
+export { Experimental }
+
+/**
+ * An experimental array template which extend built-in `Array` to include a handful
+ * of predicates which return `Result<T>`.
+ * @beta
+ */
+declare class ExtendedArray<T> extends Array<T> {
+    readonly itemDescription: string;
+    /**
+     * 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.
+     */
+    constructor(itemDescription: string, ...items: 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 | ExtendedArray},
+     * `false` otherwise.
+     */
+    static isExtendedArray<T>(a?: T[]): a is ExtendedArray<T>;
+    /**
+     * Determines if this array contains exactly one element which matches
+     * a supplied predicate.
+     * @param predicate - The predicate function to be applied.
+     * @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 | 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 `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 | 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 `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 | ExtendedArray}.
+     * @returns A new (non-extended) `Array<T>`.
+     */
+    all(): 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 - `Converter` used to convert each item in the array
+ * @param ignoreErrors - Specifies treatment of unconvertible elements
+ * @beta
+ */
+declare function extendedArrayOf<T, TC = undefined>(label: string, converter: Converter<T, TC>, onError?: Conversion.OnError): Converter<ExtendedArray<T>, TC>;
+
+/**
+ * Formats a list of items using the supplied template and formatter, one result
+ * per output line.
+ * @param format - A mustache template used to format each item.
+ * @param items - The items to be formatted.
+ * @param itemFormatter - The {@link Experimental.Formatter | Formatter<T>} used to format each item.
+ * @returns The resulting string.
+ * @beta
+ */
+declare function formatList<T>(format: string, items: T[], itemFormatter: Formatter<T>): Result<string>;
+
+/**
+ * Interface for an object that can be formatted.
+ * @beta
+ */
+declare interface Formattable {
+    /**
+     * Formats an object using the supplied mustache template.
+     * @param format - A mustache template used to format the object.
+     * @returns `Success<string>` with the resulting string, or `Failure<string>`
+     * with an error message if an error occurs.
+     */
+    format(format: string): Result<string>;
+}
+
+/**
+ * Base class which adds common formatting.
+ * @beta
+ */
+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>;
+}
+
+/**
+ * Destination format for some formatted string.
+ * @beta
+ */
+declare type FormatTargets = 'text' | 'markdown' | 'embed';
+
+/**
+ * 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
+    }
+}
+export { Hash }
+
+/**
+ * A `Converter` which converts an iso formatted string, a number or a `Date` object to
+ * a `Date` object.
+ * @public
+ */
+declare const isoDate: Converter<Date, unknown>;
+
+/**
+ * @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> {
+    /**
+     * 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';
+}
+
+/**
+ * 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>;
+
+/**
+ * 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 }
+
+/**
+ * Helper function to create a `StringConverter` which converts
+ * `unknown` to `string`, applying template conversions supplied at construction time or at
+ * runtime as context.
+ * @remarks
+ * Template conversions are applied using `mustache` syntax.
+ * @param defaultContext - Optional default context to use for template values.
+ * @returns A new `Converter` returning `string`.
+ * @public
+ */
+declare function templateString(defaultContext?: unknown): Conversion.StringConverter<string, unknown>;
+
+/**
+ * Implementation of `IFileTreeDirectoryItem` for directories in a ZIP archive.
+ * @public
+ */
+declare class ZipDirectoryItem implements FileTree.IFileTreeDirectoryItem {
+    /**
+     * Indicates that this `FileTree.FileTreeItem` is a directory.
+     */
+    readonly type: 'directory';
+    /**
+     * The absolute path of the directory within the ZIP archive.
+     */
+    readonly absolutePath: string;
+    /**
+     * The name of the directory
+     */
+    readonly name: string;
+    /**
+     * The ZIP file tree accessors that created this item.
+     */
+    private readonly _accessors;
+    /**
+     * Constructor for ZipDirectoryItem.
+     * @param directoryPath - The path of the directory within the ZIP.
+     * @param accessors - The ZIP file tree accessors.
+     */
+    constructor(directoryPath: string, accessors: ZipFileTreeAccessors);
+    /**
+     * Gets the children of the directory.
+     */
+    getChildren(): Result<ReadonlyArray<FileTree.FileTreeItem>>;
+}
+
+/**
+ * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * @public
+ */
+declare class ZipFileItem implements FileTree.IFileTreeFileItem {
+    /**
+     * Indicates that this `FileTree.FileTreeItem` is a file.
+     */
+    readonly type: 'file';
+    /**
+     * The absolute path of the file within the ZIP archive.
+     */
+    readonly absolutePath: string;
+    /**
+     * The name of the file
+     */
+    readonly name: string;
+    /**
+     * The base name of the file (without extension)
+     */
+    readonly baseName: string;
+    /**
+     * The extension of the file
+     */
+    readonly extension: string;
+    /**
+     * The pre-loaded contents of the file.
+     */
+    private readonly _contents;
+    /**
+     * The ZIP file tree accessors that created this item.
+     */
+    private readonly _accessors;
+    /**
+     * Constructor for ZipFileItem.
+     * @param zipFilePath - The path of the file within the ZIP.
+     * @param contents - The pre-loaded contents of the file.
+     * @param accessors - The ZIP file tree accessors.
+     */
+    constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors);
+    /**
+     * Gets the contents of the file as parsed JSON.
+     */
+    getContents(): Result<unknown>;
+    getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;
+    /**
+     * Gets the raw contents of the file as a string.
+     */
+    getRawContents(): Result<string>;
+}
+
+declare namespace ZipFileTree {
+    export {
+        ZipFileTreeAccessors,
+        ZipFileItem,
+        ZipDirectoryItem
+    }
+}
+export { ZipFileTree }
+
+/**
+ * File tree accessors for ZIP archives.
+ * @public
+ */
+declare class ZipFileTreeAccessors implements FileTree.IFileTreeAccessors {
+    /**
+     * The unzipped file data.
+     */
+    private readonly _files;
+    /**
+     * Optional prefix to prepend to paths.
+     */
+    private readonly _prefix;
+    /**
+     * Cache of all items in the ZIP for efficient lookups.
+     */
+    private readonly _itemCache;
+    /**
+     * Constructor for ZipFileTreeAccessors.
+     * @param files - The unzipped file data from fflate.
+     * @param prefix - Optional prefix to prepend to paths.
+     */
+    private constructor();
+    /**
+     * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer (synchronous).
+     * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
+     * @param prefix - Optional prefix to prepend to paths.
+     * @returns Result containing the ZipFileTreeAccessors instance.
+     */
+    static fromBuffer(zipBuffer: ArrayBuffer | Uint8Array, prefix?: string): Result<ZipFileTreeAccessors>;
+    /**
+     * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer (asynchronous).
+     * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
+     * @param prefix - Optional prefix to prepend to paths.
+     * @returns Promise containing Result with the ZipFileTreeAccessors instance.
+     */
+    static fromBufferAsync(zipBuffer: ArrayBuffer | Uint8Array, prefix?: string): Promise<Result<ZipFileTreeAccessors>>;
+    /**
+     * Creates a new ZipFileTreeAccessors instance from a File object (browser environment).
+     * @param file - The File object containing ZIP data.
+     * @param prefix - Optional prefix to prepend to paths.
+     * @returns Result containing the ZipFileTreeAccessors instance.
+     */
+    static fromFile(file: File, prefix?: string): Promise<Result<ZipFileTreeAccessors>>;
+    /**
+     * Builds the cache of all items in the ZIP archive.
+     */
+    private _buildItemCache;
+    /**
+     * Resolves paths to an absolute path.
+     */
+    resolveAbsolutePath(...paths: string[]): string;
+    /**
+     * Gets the extension of a path.
+     */
+    getExtension(path: string): string;
+    /**
+     * Gets the base name of a path.
+     */
+    getBaseName(path: string, suffix?: string): string;
+    /**
+     * Joins paths together.
+     */
+    joinPaths(...paths: string[]): string;
+    /**
+     * Gets an item from the file tree.
+     */
+    getItem(path: string): Result<FileTree.FileTreeItem>;
+    /**
+     * Gets the contents of a file in the file tree.
+     */
+    getFileContents(path: string): Result<string>;
+    /**
+     * Gets the children of a directory in the file tree.
+     */
+    getChildren(path: string): Result<ReadonlyArray<FileTree.FileTreeItem>>;
+    /**
+     * Checks if childPath is a direct child of parentPath.
+     */
+    private _isDirectChild;
+}
+
+export { }

package/dist/tsdoc-metadata.json

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

package/eslint.config.js

@@ -0,0 +1,16 @@
+// ESLint 9 flat config
+const nodeProfile = require('@rushstack/eslint-config/flat/profile/node');
+const packletsPlugin = require('@rushstack/eslint-config/flat/mixins/packlets');
+const tsdocPlugin = require('@rushstack/eslint-config/flat/mixins/tsdoc');
+
+module.exports = [
+  ...nodeProfile,
+  packletsPlugin,
+  ...tsdocPlugin,
+  {
+    // Override specific rules if needed
+    rules: {
+      '@rushstack/packlets/mechanics': 'warn'
+    }
+  }
+];

package/lib/packlets/csv/csvHelpers.js

@@ -71,7 +71,6 @@ function readCsvFileSync(srcPath, options) {
         const fullPath = path.resolve(srcPath);
         const body = fs.readFileSync(fullPath, 'utf8').toString();
         options = options !== null && options !== void 0 ? options : {};
-        // eslint-disable-next-line
         return (0, papaparse_1.parse)(body, Object.assign({ transform: (s) => s.trim(), header: false, dynamicTyping: false, skipEmptyLines: 'greedy' }, options)).data.slice(1);
     });
 }

package/lib/packlets/record-jar/recordJarHelpers.js

@@ -60,7 +60,6 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const ts_utils_1 = require("@fgv/ts-utils");
 class RecordParser {
-    // eslint-disable-next-line @typescript-eslint/no-empty-function
     constructor(options) {
         this.records = [];
         this._fields = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.0.0-24",
+  "version": "5.0.0-26",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-extras.d.ts",
@@ -24,20 +24,20 @@
     "@types/mustache": "^4.2.5",
     "@types/node": "^20.14.9",
     "@types/papaparse": "^5.3.14",
-    "@typescript-eslint/eslint-plugin": "^7.14.1",
-    "@typescript-eslint/parser": "^7.14.1",
-    "eslint": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^8.42.0",
+    "@typescript-eslint/parser": "^8.42.0",
+    "eslint": "^9.35.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^6.2.0",
+    "eslint-plugin-promise": "^7.2.1",
     "jest": "^29.7.0",
     "jest-extended": "^4.0.2",
     "jest-matcher-utils": "^29.7.0",
-    "rimraf": "^5.0.7",
+    "rimraf": "^6.0.1",
     "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
     "typescript": "5.8.3",
-    "eslint-plugin-n": "^16.6.2",
+    "eslint-plugin-n": "^17.21.3",
     "jest-snapshot": "~29.7.0",
     "@rushstack/heft": "0.74.3",
     "@rushstack/heft-node-rig": "2.9.4",
@@ -45,17 +45,17 @@
     "@types/heft-jest": "1.0.6",
     "@rushstack/heft-jest-plugin": "0.16.12",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.0-24",
-    "@fgv/ts-utils-jest": "5.0.0-24"
+    "@fgv/ts-utils": "5.0.0-26",
+    "@fgv/ts-utils-jest": "5.0.0-26"
   },
   "dependencies": {
-    "luxon": "^3.7.1",
+    "luxon": "^3.7.2",
     "mustache": "^4.2.0",
     "papaparse": "^5.4.1",
     "fflate": "~0.8.2"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-24"
+    "@fgv/ts-utils": "5.0.0-26"
   },
   "scripts": {
     "build": "heft test --clean",

package/config/api-extractor.json

@@ -1,343 +0,0 @@
-/**
- * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
- */
-{
-  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-  /**
-   * Optionally specifies another JSON config file that this file extends from.  This provides a way for
-   * standard settings to be shared across multiple projects.
-   *
-   * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
-   * the "extends" field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
-   * resolved using NodeJS require().
-   *
-   * SUPPORTED TOKENS: none
-   * DEFAULT VALUE: ""
-   */
-  // "extends": "./shared/api-extractor-base.json"
-  // "extends": "my-package/include/api-extractor-base.json"
-  /**
-   * Determines the "<projectFolder>" token that can be used with other config file settings.  The project folder
-   * typically contains the tsconfig.json and package.json config files, but the path is user-defined.
-   *
-   * The path is resolved relative to the folder of the config file that contains the setting.
-   *
-   * The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
-   * parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
-   * that contains a tsconfig.json file.  If a tsconfig.json file cannot be found in this way, then an error
-   * will be reported.
-   *
-   * SUPPORTED TOKENS: <lookup>
-   * DEFAULT VALUE: "<lookup>"
-   */
-  "projectFolder": "..",
-  /**
-   * (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis.  API Extractor
-   * analyzes the symbols exported by this module.
-   *
-   * The file extension must be ".d.ts" and not ".ts".
-   *
-   * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-   * prepend a folder token such as "<projectFolder>".
-   *
-   * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-   */
-  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
-  /**
-   * A list of NPM package names whose exports should be treated as part of this package.
-   *
-   * For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
-   * and another NPM package "library2" is embedded in this bundle.  Some types from library2 may become part
-   * of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
-   * imports library2.  To avoid this, we can specify:
-   *
-   *   "bundledPackages": [ "library2" ],
-   *
-   * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
-   * local files for library1.
-   */
-  "bundledPackages": [],
-  /**
-   * Determines how the TypeScript compiler engine will be invoked by API Extractor.
-   */
-  "compiler": {
-    /**
-     * Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * Note: This setting will be ignored if "overrideTsconfig" is used.
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/tsconfig.json"
-     */
-    // "tsconfigFilePath": "<projectFolder>/tsconfig.json",
-    /**
-     * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
-     * The object must conform to the TypeScript tsconfig schema:
-     *
-     * http://json.schemastore.org/tsconfig
-     *
-     * If omitted, then the tsconfig.json file will be read from the "projectFolder".
-     *
-     * DEFAULT VALUE: no overrideTsconfig section
-     */
-    // "overrideTsconfig": {
-    //   . . .
-    // }
-    /**
-     * This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
-     * and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
-     * dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
-     * for its analysis.  Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
-     *
-     * DEFAULT VALUE: false
-     */
-    // "skipLibCheck": true,
-  },
-  /**
-   * Configures how the API report file (*.api.md) will be generated.
-   */
-  "apiReport": {
-    /**
-     * (REQUIRED) Whether to generate an API report.
-     */
-    "enabled": true
-    /**
-     * The filename for the API report files.  It will be combined with "reportFolder" or "reportTempFolder" to produce
-     * a full file path.
-     *
-     * The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
-     *
-     * SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<unscopedPackageName>.api.md"
-     */
-    // "reportFileName": "<unscopedPackageName>.api.md",
-    /**
-     * Specifies the folder where the API report file is written.  The file name portion is determined by
-     * the "reportFileName" setting.
-     *
-     * The API report file is normally tracked by Git.  Changes to it can be used to trigger a branch policy,
-     * e.g. for an API review.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/etc/"
-     */
-    // "reportFolder": "<projectFolder>/etc/",
-    /**
-     * Specifies the folder where the temporary report file is written.  The file name portion is determined by
-     * the "reportFileName" setting.
-     *
-     * After the temporary file is written to disk, it is compared with the file in the "reportFolder".
-     * If they are different, a production build will fail.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/temp/"
-     */
-    // "reportTempFolder": "<projectFolder>/temp/"
-  },
-  /**
-   * Configures how the doc model file (*.api.json) will be generated.
-   */
-  "docModel": {
-    /**
-     * (REQUIRED) Whether to generate a doc model file.
-     */
-    "enabled": true
-    /**
-     * The output path for the doc model file.  The file extension should be ".api.json".
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
-     */
-    // "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json"
-  },
-  /**
-   * Configures how the .d.ts rollup file will be generated.
-   */
-  "dtsRollup": {
-    /**
-     * (REQUIRED) Whether to generate the .d.ts rollup file.
-     */
-    "enabled": true
-    /**
-     * Specifies the output path for a .d.ts rollup file to be generated without any trimming.
-     * This file will include all declarations that are exported by the main entry point.
-     *
-     * If the path is an empty string, then this file will not be written.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
-     */
-    // "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
-    /**
-     * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
-     * This file will include only declarations that are marked as "@public" or "@beta".
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: ""
-     */
-    // "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
-    /**
-     * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
-     * This file will include only declarations that are marked as "@public".
-     *
-     * If the path is an empty string, then this file will not be written.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: ""
-     */
-    // "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
-    /**
-     * When a declaration is trimmed, by default it will be replaced by a code comment such as
-     * "Excluded from this release type: exampleMember".  Set "omitTrimmingComments" to true to remove the
-     * declaration completely.
-     *
-     * DEFAULT VALUE: false
-     */
-    // "omitTrimmingComments": true
-  },
-  /**
-   * Configures how the tsdoc-metadata.json file will be generated.
-   */
-  "tsdocMetadata": {
-    /**
-     * Whether to generate the tsdoc-metadata.json file.
-     *
-     * DEFAULT VALUE: true
-     */
-    // "enabled": true,
-    /**
-     * Specifies where the TSDoc metadata file should be written.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
-     * "typings" or "main" fields of the project's package.json.  If none of these fields are set, the lookup
-     * falls back to "tsdoc-metadata.json" in the package folder.
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<lookup>"
-     */
-    // "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
-  },
-  /**
-   * Specifies what type of newlines API Extractor should use when writing output files.  By default, the output files
-   * will be written with Windows-style newlines.  To use POSIX-style newlines, specify "lf" instead.
-   * To use the OS's default newline kind, specify "os".
-   *
-   * DEFAULT VALUE: "crlf"
-   */
-  // "newlineKind": "crlf",
-  /**
-   * Configures how API Extractor reports error and warning messages produced during analysis.
-   *
-   * There are three sources of messages:  compiler messages, API Extractor messages, and TSDoc messages.
-   */
-  "messages": {
-    /**
-     * Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
-     * the input .d.ts files.
-     *
-     * TypeScript message identifiers start with "TS" followed by an integer.  For example: "TS2551"
-     *
-     * DEFAULT VALUE:  A single "default" entry with logLevel=warning.
-     */
-    "compilerMessageReporting": {
-      /**
-       * Configures the default routing for messages that don't match an explicit rule in this table.
-       */
-      "default": {
-        /**
-         * Specifies whether the message should be written to the the tool's output log.  Note that
-         * the "addToApiReportFile" property may supersede this option.
-         *
-         * Possible values: "error", "warning", "none"
-         *
-         * Errors cause the build to fail and return a nonzero exit code.  Warnings cause a production build fail
-         * and return a nonzero exit code.  For a non-production build (e.g. when "api-extractor run" includes
-         * the "--local" option), the warning is displayed but the build will not fail.
-         *
-         * DEFAULT VALUE: "warning"
-         */
-        "logLevel": "warning"
-        /**
-         * When addToApiReportFile is true:  If API Extractor is configured to write an API report file (.api.md),
-         * then the message will be written inside that file; otherwise, the message is instead logged according to
-         * the "logLevel" option.
-         *
-         * DEFAULT VALUE: false
-         */
-        // "addToApiReportFile": false
-      }
-      // "TS2551": {
-      //   "logLevel": "warning",
-      //   "addToApiReportFile": true
-      // },
-      //
-      // . . .
-    },
-    /**
-     * Configures handling of messages reported by API Extractor during its analysis.
-     *
-     * API Extractor message identifiers start with "ae-".  For example: "ae-extra-release-tag"
-     *
-     * DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
-     */
-    "extractorMessageReporting": {
-      "default": {
-        "logLevel": "warning"
-        // "addToApiReportFile": false
-      },
-      "ae-unresolved-link": {
-        "logLevel": "none",
-        "addToApiReportFile": true
-      }
-      // "ae-extra-release-tag": {
-      //   "logLevel": "warning",
-      //   "addToApiReportFile": true
-      // },
-      //
-      // . . .
-    },
-    /**
-     * Configures handling of messages reported by the TSDoc parser when analyzing code comments.
-     *
-     * TSDoc message identifiers start with "tsdoc-".  For example: "tsdoc-link-tag-unescaped-text"
-     *
-     * DEFAULT VALUE:  A single "default" entry with logLevel=warning.
-     */
-    "tsdocMessageReporting": {
-      "default": {
-        "logLevel": "warning"
-        // "addToApiReportFile": false
-      }
-      // "tsdoc-link-tag-unescaped-text": {
-      //   "logLevel": "warning",
-      //   "addToApiReportFile": true
-      // },
-      //
-      // . . .
-    }
-  }
-}

package/config/rig.json

@@ -1,16 +0,0 @@
-// The "rig.json" file directs tools to look for their config files in an external package.
-// Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
-{
-  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
-  /**
-   * (Required) The name of the rig package to inherit from.
-   * It should be an NPM package name with the "-rig" suffix.
-   */
-  "rigPackageName": "@rushstack/heft-node-rig"
-  /**
-   * (Optional) Selects a config profile from the rig package.  The name must consist of
-   * lowercase alphanumeric words separated by hyphens, for example "sample-profile".
-   * If omitted, then the "default" profile will be used."
-   */
-  // "rigProfile": "your-profile-name"
-}