@fgv/ts-extras 5.0.0-2 → 5.0.0-21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.0.0-2",
+  "version": "5.0.0-21",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-extras.d.ts",
@@ -17,10 +17,10 @@
   "homepage": "https://github.com/ErikFortune/fgv/tree/main/libraries/ts-extras#ts-utils",
   "devDependencies": {
     "@jest/expect-utils": "^29.7.0",
-    "@microsoft/api-documenter": "^7.26.29",
-    "@microsoft/api-extractor": "^7.49.1",
+    "@microsoft/api-documenter": "^7.26.31",
+    "@microsoft/api-extractor": "^7.52.10",
     "@types/jest": "^29.5.14",
-    "@types/luxon": "^3.6.2",
+    "@types/luxon": "^3.7.1",
     "@types/mustache": "^4.2.5",
     "@types/node": "^20.14.9",
     "@types/papaparse": "^5.3.14",
@@ -34,29 +34,28 @@
     "jest-extended": "^4.0.2",
     "jest-matcher-utils": "^29.7.0",
     "rimraf": "^5.0.7",
-    "ts-jest": "^29.4.0",
+    "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.7.3",
+    "typescript": "^5.8.3",
     "eslint-plugin-n": "^16.6.2",
     "jest-snapshot": "~29.7.0",
-    "@rushstack/heft": "~0.74.0",
-    "@rushstack/heft-node-rig": "~2.9.0",
+    "@rushstack/heft": "~0.74.2",
+    "@rushstack/heft-node-rig": "~2.9.3",
     "@rushstack/eslint-config": "~4.4.0",
     "@types/heft-jest": "1.0.6",
-    "@rushstack/heft-jest-plugin": "~0.16.9",
+    "@rushstack/heft-jest-plugin": "~0.16.11",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils-jest": "5.0.0-2",
-    "@fgv/ts-utils": "5.0.0-2"
+    "@fgv/ts-utils-jest": "5.0.0-21",
+    "@fgv/ts-utils": "5.0.0-21"
   },
   "dependencies": {
-    "luxon": "^3.6.1",
+    "luxon": "^3.7.1",
     "mustache": "^4.2.0",
     "papaparse": "^5.4.1",
-    "@types/adm-zip": "~0.5.7",
-    "adm-zip": "~0.5.16"
+    "fflate": "~0.8.2"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-2"
+    "@fgv/ts-utils": "5.0.0-21"
   },
   "scripts": {
     "build": "heft test --clean",

package/src/index.ts

@@ -0,0 +1,31 @@
+/*
+ * 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 * as Csv from './packlets/csv';
+import * as Experimental from './packlets/experimental';
+import * as Hash from './packlets/hash';
+import * as RecordJar from './packlets/record-jar';
+import * as ZipFileTree from './packlets/zip-file-tree';
+
+import { Converters } from './packlets/conversion';
+
+export { Converters, Csv, Experimental, Hash, RecordJar, ZipFileTree };

package/src/packlets/conversion/converters.ts

@@ -0,0 +1,124 @@
+/*
+ * 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 { Conversion, Converter, Converters, Result, captureResult, fail, succeed } from '@fgv/ts-utils';
+import { DateTime } from 'luxon';
+import Mustache from 'mustache';
+import { ExtendedArray, RangeOf, RangeOfProperties } from '../experimental';
+
+/**
+ * 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
+ */
+export function templateString(defaultContext?: unknown): Conversion.StringConverter<string, unknown> {
+  return new Conversion.StringConverter<string, unknown>(
+    defaultContext,
+    undefined,
+    (from: unknown, __self: Converter<string, unknown>, context?: unknown) => {
+      if (typeof from !== 'string') {
+        return fail(`Not a string: ${JSON.stringify(from)}`);
+      }
+      return captureResult(() => Mustache.render(from, context));
+    }
+  );
+}
+
+/**
+ * A `Converter` which converts an iso formatted string, a number or a `Date` object to
+ * a `Date` object.
+ * @public
+ */
+export const isoDate: Converter<Date, unknown> = new Conversion.BaseConverter<Date>((from: unknown) => {
+  if (typeof from === 'string') {
+    const dt = DateTime.fromISO(from);
+    if (dt.isValid) {
+      return succeed(dt.toJSDate());
+    }
+    return fail(`Invalid date: ${dt.invalidExplanation}`);
+  } else if (typeof from === 'number') {
+    return succeed(new Date(from));
+  } else if (from instanceof Date) {
+    return succeed(from);
+  }
+  return fail(`Cannot convert ${JSON.stringify(from)} to Date`);
+});
+
+/**
+ * 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
+ */
+export function extendedArrayOf<T, TC = undefined>(
+  label: string,
+  converter: Converter<T, TC>,
+  onError: Conversion.OnError = 'failOnError'
+): Converter<ExtendedArray<T>, TC> {
+  return Converters.arrayOf(converter, onError).map((items: T[]) => {
+    return captureResult(() => new ExtendedArray(label, ...items));
+  });
+}
+
+/**
+ * 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
+ */
+export function rangeTypeOf<T, RT extends RangeOf<T>, TC = unknown>(
+  converter: Converter<T, TC>,
+  constructor: (init: RangeOfProperties<T>) => Result<RT>
+): Converter<RT, TC> {
+  return new Conversion.BaseConverter((from: unknown, __self, context?: TC) => {
+    const result = Converters.object(
+      {
+        min: converter,
+        max: converter
+      },
+      { optionalFields: ['min', 'max'] }
+    ).convert(from, context);
+    if (result.isSuccess()) {
+      return constructor({ min: result.value.min, max: result.value.max });
+    }
+    return fail(result.message);
+  });
+}
+
+/**
+ * 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
+ */
+export function rangeOf<T, TC = unknown>(converter: Converter<T, TC>): Converter<RangeOf<T>, TC> {
+  return rangeTypeOf<T, RangeOf<T>, TC>(converter, RangeOf.createRange);
+}

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';