@fgv/ts-extras 5.0.0-11 → 5.0.0-14

package/src/packlets/conversion/index.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import * as Converters from './converters';
+
+export { Converters };

package/src/packlets/csv/csvHelpers.ts

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Result, captureResult } from '@fgv/ts-utils';
+import * as fs from 'fs';
+import { parse } from 'papaparse';
+import * as path from 'path';
+
+/**
+ * Options for {@link Csv.readCsvFileSync | readCsvFileSync}
+ * @beta
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface CsvOptions {
+  delimiter?: 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
+ */
+export function readCsvFileSync(srcPath: string, options?: CsvOptions): Result<unknown> {
+  return captureResult(() => {
+    const fullPath = path.resolve(srcPath);
+    const body = fs.readFileSync(fullPath, 'utf8').toString();
+    options = options ?? {};
+    // eslint-disable-next-line
+    return parse(body, {
+      transform: (s: string) => s.trim(),
+      header: false,
+      dynamicTyping: false,
+      skipEmptyLines: 'greedy',
+      ...options
+    }).data.slice(1);
+  });
+}

package/src/packlets/csv/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export * from './csvHelpers';

package/src/packlets/experimental/extendedArray.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Result, fail, succeed } from '@fgv/ts-utils';
+
+/**
+ * An experimental array template which extend built-in `Array` to include a handful
+ * of predicates which return `Result<T>`.
+ * @beta
+ */
+export class ExtendedArray<T> extends Array<T> {
+  public 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.
+   */
+  public constructor(itemDescription: string, ...items: T[]) {
+    super(...items);
+    this.itemDescription = itemDescription;
+  }
+
+  /**
+   * 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.
+   */
+  public static isExtendedArray<T>(a?: T[]): a is ExtendedArray<T> {
+    return a instanceof ExtendedArray;
+  }
+
+  /**
+   * 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.
+   */
+  public single(predicate?: (item: T) => boolean): Result<T> {
+    const match = predicate ? this.filter(predicate) : this;
+    if (match.length === 1) {
+      return succeed(match[0]);
+    }
+    if (match.length === 0) {
+      return fail(`${this.itemDescription} not found`);
+    }
+    return fail(`${this.itemDescription} matches ${match.length} items`);
+  }
+
+  /**
+   * 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.
+   */
+  public first(failMessage?: string): Result<T> {
+    if (this.length > 0) {
+      return succeed(this[0]);
+    }
+    return fail(failMessage ?? `${this.itemDescription} not found`);
+  }
+
+  /**
+   * 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.
+   */
+  public atLeastOne(failMessage?: string): Result<T[]> {
+    if (this.length > 0) {
+      return succeed(Array.from(this));
+    }
+    return fail(failMessage ?? `${this.itemDescription} not found`);
+  }
+
+  /**
+   * Gets a new (non-extended) `Array` containing all of the elements from this
+   * {@link Experimental.ExtendedArray | ExtendedArray}.
+   * @returns A new (non-extended) `Array<T>`.
+   */
+  public all(): T[] {
+    return Array.from(this);
+  }
+}

package/src/packlets/experimental/formatter.ts

@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Result, captureResult, mapResults, succeed } from '@fgv/ts-utils';
+import Mustache from 'mustache';
+
+Mustache.escape = (s: string) => s;
+
+/**
+ * Destination format for some formatted string.
+ * @beta
+ */
+export type FormatTargets = 'text' | 'markdown' | 'embed';
+
+/**
+ * Interface for an object that can be formatted.
+ * @beta
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export 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
+ */
+export 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 {
+    if (value !== undefined) {
+      const padded = `  ${label}:`.padEnd(20, ' ');
+      details.push(`${padded} ${value}`);
+    }
+  }
+
+  /**
+   * {@inheritdoc Experimental.Formattable.format}
+   */
+  public format(template: string): Result<string> {
+    return captureResult(() => Mustache.render(template, this));
+  }
+}
+
+/**
+ * Type definition for a formatting function, which takes a `string` and an
+ * item and returns `Result<string>`.
+ * @beta
+ */
+export 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
+ */
+export 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
+ */
+export type FormattersByTarget<T> = FormattersByExtendedTarget<FormatTargets, T>;
+
+/**
+ * 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
+ */
+export function formatList<T>(format: string, items: T[], itemFormatter: Formatter<T>): Result<string> {
+  return mapResults(
+    items.map((item) => {
+      return itemFormatter(format, item);
+    })
+  ).onSuccess((results: string[]) => {
+    const filtered = results.filter((s) => s !== '');
+    return succeed(filtered.join('\n'));
+  });
+}

package/src/packlets/experimental/index.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export * from './extendedArray';
+export * from './formatter';
+export * from './rangeOf';

package/src/packlets/experimental/rangeOf.ts

@@ -0,0 +1,222 @@
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Result, captureResult } from '@fgv/ts-utils';
+import Mustache from 'mustache';
+
+/**
+ * Represents a generic range of some comparable type `<T>`.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface RangeOfProperties<T> {
+  readonly min?: T;
+  readonly max?: T;
+}
+
+/**
+ * Format strings (in mustache format) to
+ * use for both open-ended and complete
+ * {@link Experimental.RangeOf | RangeOf<T>}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface RangeOfFormats {
+  minOnly: string;
+  maxOnly: string;
+  minMax: string;
+}
+
+/**
+ * Default {@link Experimental.RangeOfFormats | formats} to use for both
+ * open-ended and complete {@link Experimental.RangeOf | RangeOf<T>}.
+ * @public
+ */
+export const DEFAULT_RANGEOF_FORMATS: RangeOfFormats = {
+  minOnly: '{{min}}-',
+  maxOnly: '-{{max}}',
+  minMax: '{{min}}-{{max}}'
+};
+
+/**
+ * Simple implementation of a possibly open-ended range of some comparable
+ * type `<T>` with test and formatting.
+ * @public
+ */
+export class RangeOf<T> implements RangeOfProperties<T> {
+  /**
+   * Minimum extent of the range.
+   */
+  public readonly min?: T;
+  /**
+   * Maximum extent of the range.
+   */
+  public 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.
+   */
+  public constructor(min?: T, max?: T) {
+    if (min !== undefined && max !== undefined && this._compare(min, max) === 'greater') {
+      throw new Error(`Inverted range - ${JSON.stringify(min)} must be <= ${JSON.stringify(max)}.`);
+    }
+    this.min = min;
+    this.max = max;
+  }
+
+  /**
+   * Static constructor for a {@link Experimental.RangeOf | RangeOf<T>}.
+   * @param init - {@link Experimental.RangeOfProperties | Range initializer}.
+   * @returns A new {@link Experimental.RangeOf | RangeOf<T>}.
+   */
+  public static createRange<T>(init?: RangeOfProperties<T>): Result<RangeOf<T>> {
+    return captureResult(() => new RangeOf<T>(init?.min, init?.max));
+  }
+
+  /**
+   * 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.
+   */
+  public static propertiesToString<T>(
+    range: RangeOfProperties<T>,
+    formats?: RangeOfFormats,
+    emptyValue?: T
+  ): string | undefined {
+    formats = formats ?? DEFAULT_RANGEOF_FORMATS;
+    if (range.min !== undefined && range.min !== emptyValue) {
+      if (range.max !== undefined && range.max !== emptyValue) {
+        return Mustache.render(formats.minMax, range);
+      } else {
+        return Mustache.render(formats.minOnly, range);
+      }
+    } else if (range.max !== undefined && range.max !== emptyValue) {
+      return Mustache.render(formats.maxOnly, range);
+    }
+    return 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' {
+    if (t1 < t2) {
+      return 'less';
+    } else if (t1 > t2) {
+      return 'greater';
+    }
+    return 'equal';
+  }
+
+  /**
+   * 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.
+   */
+  public check(t: T): 'less' | 'included' | 'greater' {
+    if (this.min !== undefined && this._compare(t, this.min) === 'less') {
+      return 'less';
+    }
+    if (this.max !== undefined && this._compare(t, this.max) !== 'less') {
+      return 'greater';
+    }
+    return 'included';
+  }
+
+  /**
+   * 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.
+   */
+  public includes(t: T): boolean {
+    return this.check(t) === 'included';
+  }
+
+  /**
+   * 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.
+   */
+  public findTransition(t: T): T | undefined {
+    switch (this.check(t)) {
+      case 'less':
+        return this.min;
+      case 'included':
+        return this.max;
+    }
+    return 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.
+   */
+  public toFormattedProperties(format: (value: T) => string | undefined): RangeOfProperties<string> {
+    return {
+      min: this.min !== undefined ? format(this.min) : undefined,
+      max: this.max !== undefined ? format(this.max) : undefined
+    };
+  }
+
+  /**
+   * 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.
+   */
+  public format(format: (value: T) => string | undefined, formats?: RangeOfFormats): string | undefined {
+    return RangeOf.propertiesToString(this.toFormattedProperties(format), formats);
+  }
+
+  /**
+   * 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' {
+    return RangeOf._defaultCompare(t1, t2);
+  }
+}

package/src/packlets/hash/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export * from './md5Normalizer';

package/src/packlets/hash/md5Normalizer.ts

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Hash } from '@fgv/ts-utils';
+import * as crypto from 'crypto';
+/**
+ * A hashing normalizer which computes object
+ * hash using the MD5 algorithm.
+ * @public
+ */
+export class Md5Normalizer extends Hash.HashingNormalizer {
+  public constructor() {
+    super(Md5Normalizer.md5Hash);
+  }
+
+  public static md5Hash(parts: string[]): string {
+    return crypto.createHash('md5').update(parts.join('|'), 'utf8').digest('hex');
+  }
+}

package/src/packlets/record-jar/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export * from './recordJarHelpers';