@fgv/ts-extras 5.0.0-12 → 5.0.0-15

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

@@ -0,0 +1,278 @@
+/*
+ * Copyright (c) 2022 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 fs from 'fs';
+import * as path from 'path';
+
+import { Result, captureResult, fail, isKeyOf, succeed } from '@fgv/ts-utils';
+
+interface IRecordBody {
+  body: string;
+  isContinuation: boolean;
+}
+
+/**
+ * Represents a single record in a JAR file
+ * @public
+ */
+export type JarRecord = Record<string, string | string[]>;
+
+/**
+ * @public
+ */
+export type JarFieldPicker<T extends JarRecord = JarRecord> = (record: T) => (keyof T)[];
+
+/**
+ * Options for a JAR record parser.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface JarRecordParserOptions {
+  readonly arrayFields?: string[] | JarFieldPicker;
+  readonly fixedContinuationSize?: number;
+}
+
+class RecordParser {
+  public readonly records: JarRecord[] = [];
+  public readonly options: JarRecordParserOptions;
+
+  protected _fields: JarRecord = {};
+  protected _name: string | undefined = undefined;
+  protected _body: IRecordBody | undefined = undefined;
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor(options?: JarRecordParserOptions) {
+    this.options = options ?? {};
+  }
+
+  public static parse(lines: string[], options?: JarRecordParserOptions): Result<JarRecord[]> {
+    return new RecordParser(options)._parse(lines);
+  }
+
+  protected static _parseRecordBody(body: string): Result<IRecordBody> {
+    const isContinuation = body.endsWith('\\');
+    if (isContinuation) {
+      body = body.slice(0, body.length - 1);
+    }
+    if (this._hasEscapes(body)) {
+      const result = this._replaceEscapes(body);
+      if (result.isFailure()) {
+        return fail(result.message);
+      }
+      body = result.value;
+    }
+    return succeed({ body, isContinuation });
+  }
+
+  protected static _hasEscapes(from: string): boolean {
+    return from.includes('\\') || from.includes('&');
+  }
+
+  protected static _replaceEscapes(body: string): Result<string> {
+    const invalid: string[] = [];
+    const escaped = body.replace(/(\\.)|(&#x[a-fA-F0-9]{2,6};)/g, (match) => {
+      switch (match) {
+        case '\\\\':
+          return '\\';
+        case '\\&':
+          return '&';
+        case '\\r':
+          return '\r';
+        case '\\n':
+          return '\n';
+        case '\\t':
+          return '\t';
+      }
+      if (match.startsWith('&')) {
+        const hexCode = `0x${match.slice(3, match.length - 1)}`;
+        const charCode = Number.parseInt(hexCode, 16);
+        return String.fromCharCode(charCode);
+      }
+      invalid.push(match);
+      return '\\';
+    });
+    if (invalid.length > 0) {
+      return fail(`unrecognized escape "${invalid.join(', ')}" in record-jar body`);
+    }
+    return succeed(escaped);
+  }
+
+  protected static _applyOptions(record: JarRecord, options: JarRecordParserOptions): JarRecord {
+    if (options.arrayFields) {
+      record = { ...record }; // don't edit incoming values
+      const arrayFields = Array.isArray(options.arrayFields)
+        ? options.arrayFields
+        : options.arrayFields(record);
+
+      for (const field of arrayFields) {
+        if (isKeyOf(field, record) && typeof record[field] === 'string') {
+          const current = record[field] as string;
+          record[field] = [current];
+        }
+      }
+    }
+    return record;
+  }
+
+  protected _parse(lines: string[]): Result<JarRecord[]> {
+    for (let n = 0; n < lines.length; n++) {
+      const line = lines[n];
+      if (line.startsWith('%%') && !this._body?.isContinuation) {
+        const result = this._writePendingRecord();
+        if (result.isFailure()) {
+          return fail(`${n}: ${result.message}`);
+        }
+      } else if (/^\s*$/.test(line)) {
+        // ignore blank lines but cancel continuation
+        if (this._body) {
+          this._body.isContinuation = false;
+        }
+        continue;
+      } else if (this._body?.isContinuation || /^\s+/.test(line)) {
+        // explicit continuation on previous line or implicit starts with whitespace
+        if (this._body === undefined) {
+          return fail(`${n}: continuation ("${line}") without prior value.`);
+        }
+        const result = this._parseContinuation(line);
+        if (result.isFailure()) {
+          return fail(`${n}: ${result.message}`);
+        }
+        this._body = result.value;
+      } else {
+        const result = this._parseField(line);
+        if (result.isFailure()) {
+          return fail(`${n}: ${result.message}`);
+        }
+      }
+    }
+
+    const result = this._writePendingRecord();
+    if (result.isFailure()) {
+      return fail(`${lines.length}: ${result.message}`);
+    }
+    return succeed(this.records);
+  }
+
+  protected _parseField(line: string): Result<boolean> {
+    const separatorIndex = line.indexOf(':');
+    if (separatorIndex < 1) {
+      return fail(`malformed line ("${line}") in record-jar.`);
+    }
+    const parts = [line.slice(0, separatorIndex), line.slice(separatorIndex + 1)];
+
+    return this._writePendingField().onSuccess(() => {
+      this._name = parts[0].trimEnd();
+      return RecordParser._parseRecordBody(parts[1].trim()).onSuccess((body) => {
+        this._body = body;
+        return succeed(true);
+      });
+    });
+  }
+
+  protected _parseContinuation(line: string): Result<IRecordBody> {
+    let trimmed = line.trim();
+    if (!this._body!.isContinuation) {
+      /* c8 ignore next */
+      const fixedSize = this.options?.fixedContinuationSize ?? 0;
+      if (fixedSize > 0) {
+        if (trimmed.length < line.length - fixedSize) {
+          // oops, took too much
+          trimmed = line.slice(fixedSize);
+        }
+      }
+    }
+    return RecordParser._parseRecordBody(trimmed).onSuccess((newBody) => {
+      return succeed({
+        body: `${this._body!.body}${newBody.body}`,
+        isContinuation: newBody.isContinuation
+      });
+    });
+  }
+
+  protected _havePendingRecord(): boolean {
+    return Object.keys(this._fields).length > 0;
+  }
+
+  protected _writePendingRecord(): Result<JarRecord | undefined> {
+    return this._writePendingField().onSuccess(() => {
+      let record = this._havePendingRecord() ? this._fields : undefined;
+      if (record !== undefined) {
+        record = RecordParser._applyOptions(record, this.options);
+        this.records.push(record);
+        this._fields = {};
+      }
+      return succeed(undefined);
+    });
+  }
+
+  protected _writePendingField(): Result<boolean> {
+    if (this._name !== undefined) {
+      if (this._body!.body.length < 1) {
+        return fail('empty body value not allowed');
+      }
+      if (!isKeyOf(this._name, this._fields)) {
+        this._fields[this._name] = this._body!.body;
+      } else if (typeof this._fields[this._name] === 'string') {
+        const current = this._fields[this._name] as string;
+        this._fields[this._name] = [current, this._body!.body];
+      } else {
+        const current = this._fields[this._name] as string[];
+        current.push(this._body!.body);
+      }
+      this._name = undefined;
+      this._body = undefined;
+    }
+    return succeed(true);
+  }
+}
+
+/**
+ * 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
+ */
+export function parseRecordJarLines(lines: string[], options?: JarRecordParserOptions): Result<JarRecord[]> {
+  return RecordParser.parse(lines, options);
+}
+
+/**
+ * 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
+ */
+export function readRecordJarFileSync(
+  srcPath: string,
+  options?: JarRecordParserOptions
+): Result<JarRecord[]> {
+  return captureResult(() => {
+    const fullPath = path.resolve(srcPath);
+    return fs.readFileSync(fullPath, 'utf8').toString().split(/\r?\n/);
+  }).onSuccess((lines) => {
+    return parseRecordJarLines(lines, options);
+  });
+}

package/src/packlets/zip-file-tree/index.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2025 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.
+ */
+
+/**
+ * ZIP-based FileTree implementation for ts-extras.
+ *
+ * This packlet provides a FileTree accessor implementation that can read from ZIP archives,
+ * making it useful for browser environments where files need to be bundled and transferred
+ * as a single archive.
+ *
+ * @packageDocumentation
+ */
+
+export { ZipFileTreeAccessors, ZipFileItem, ZipDirectoryItem } from './zipFileTreeAccessors';

package/src/packlets/zip-file-tree/zipFileTreeAccessors.ts

@@ -0,0 +1,375 @@
+/*
+ * Copyright (c) 2025 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 AdmZip from 'adm-zip';
+import { Result, succeed, fail, captureResult, Converter, Validator, FileTree } from '@fgv/ts-utils';
+
+/**
+ * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * @public
+ */
+export class ZipFileItem implements FileTree.IFileTreeFileItem {
+  /**
+   * Indicates that this `FileTree.FileTreeItem` is a file.
+   */
+  public readonly type: 'file' = 'file';
+
+  /**
+   * The absolute path of the file within the ZIP archive.
+   */
+  public readonly absolutePath: string;
+
+  /**
+   * The name of the file
+   */
+  public readonly name: string;
+
+  /**
+   * The base name of the file (without extension)
+   */
+  public readonly baseName: string;
+
+  /**
+   * The extension of the file
+   */
+  public readonly extension: string;
+
+  /**
+   * The pre-loaded contents of the file.
+   */
+  private readonly _contents: string;
+
+  /**
+   * The ZIP file tree accessors that created this item.
+   */
+  private readonly _accessors: ZipFileTreeAccessors;
+
+  /**
+   * 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.
+   */
+  public constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors) {
+    this._contents = contents;
+    this._accessors = accessors;
+    this.absolutePath = '/' + zipFilePath;
+    this.name = accessors.getBaseName(zipFilePath);
+    this.extension = accessors.getExtension(zipFilePath);
+    this.baseName = accessors.getBaseName(zipFilePath, this.extension);
+  }
+
+  /**
+   * Gets the contents of the file as parsed JSON.
+   */
+  public getContents(): Result<unknown>;
+  public getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;
+  public getContents<T>(converter?: Validator<T> | Converter<T>): Result<T | unknown> {
+    return this.getRawContents()
+      .onSuccess((contents) => {
+        return captureResult(() => {
+          const parsed = JSON.parse(contents);
+          if (converter) {
+            if ('convert' in converter) {
+              return converter.convert(parsed);
+            } /* c8 ignore next 3 - validator branch functionally tested but coverage tool misses due to interface complexity */ else {
+              return (converter as Validator<T>).validate(parsed);
+            }
+          }
+          return succeed(parsed);
+        }).onFailure(() => {
+          return fail(`Failed to parse JSON from file: ${this.absolutePath}`);
+        });
+      })
+      .onFailure((error) => {
+        return fail(`Failed to get contents from file: ${error}`);
+      });
+  }
+
+  /**
+   * Gets the raw contents of the file as a string.
+   */
+  public getRawContents(): Result<string> {
+    return succeed(this._contents);
+  }
+}
+
+/**
+ * Implementation of `IFileTreeDirectoryItem` for directories in a ZIP archive.
+ * @public
+ */
+export class ZipDirectoryItem implements FileTree.IFileTreeDirectoryItem {
+  /**
+   * Indicates that this `FileTree.FileTreeItem` is a directory.
+   */
+  public readonly type: 'directory' = 'directory';
+
+  /**
+   * The absolute path of the directory within the ZIP archive.
+   */
+  public readonly absolutePath: string;
+
+  /**
+   * The name of the directory
+   */
+  public readonly name: string;
+
+  /**
+   * The ZIP file tree accessors that created this item.
+   */
+  private readonly _accessors: ZipFileTreeAccessors;
+
+  /**
+   * Constructor for ZipDirectoryItem.
+   * @param directoryPath - The path of the directory within the ZIP.
+   * @param accessors - The ZIP file tree accessors.
+   */
+  public constructor(directoryPath: string, accessors: ZipFileTreeAccessors) {
+    this._accessors = accessors;
+    this.absolutePath = '/' + directoryPath.replace(/\/$/, ''); // Normalize path
+    this.name = accessors.getBaseName(directoryPath);
+  }
+
+  /**
+   * Gets the children of the directory.
+   */
+  public getChildren(): Result<ReadonlyArray<FileTree.FileTreeItem>> {
+    return this._accessors.getChildren(this.absolutePath);
+  }
+}
+
+/**
+ * File tree accessors for ZIP archives.
+ * @public
+ */
+export class ZipFileTreeAccessors implements FileTree.IFileTreeAccessors {
+  /**
+   * The AdmZip instance containing the archive.
+   */
+  private readonly _zip: AdmZip;
+
+  /**
+   * Optional prefix to prepend to paths.
+   */
+  private readonly _prefix: string;
+
+  /**
+   * Cache of all items in the ZIP for efficient lookups.
+   */
+  private readonly _itemCache: Map<string, FileTree.FileTreeItem> = new Map();
+
+  /**
+   * Constructor for ZipFileTreeAccessors.
+   * @param zip - The AdmZip instance.
+   * @param prefix - Optional prefix to prepend to paths.
+   */
+  private constructor(zip: AdmZip, prefix?: string) {
+    this._zip = zip;
+    this._prefix = prefix || '';
+    this._buildItemCache();
+  }
+
+  /**
+   * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer.
+   * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
+   * @param prefix - Optional prefix to prepend to paths.
+   * @returns Result containing the ZipFileTreeAccessors instance.
+   */
+  public static fromBuffer(
+    zipBuffer: ArrayBuffer | Uint8Array,
+    prefix?: string
+  ): Result<ZipFileTreeAccessors> {
+    try {
+      const buffer = Buffer.from(zipBuffer);
+      const zip = new AdmZip(buffer);
+      return succeed(new ZipFileTreeAccessors(zip, prefix));
+    } catch (error) {
+      /* c8 ignore next 1 - defensive coding: AdmZip always throws Error objects in practice */
+      return fail(`Failed to load ZIP archive: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public static async fromFile(file: File, prefix?: string): Promise<Result<ZipFileTreeAccessors>> {
+    try {
+      const arrayBuffer = await file.arrayBuffer();
+      return ZipFileTreeAccessors.fromBuffer(new Uint8Array(arrayBuffer), prefix);
+    } catch (error) {
+      return fail(`Failed to read file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Builds the cache of all items in the ZIP archive.
+   */
+  private _buildItemCache(): void {
+    const directories = new Set<string>();
+    const entries = this._zip.getEntries();
+
+    // First pass: collect all directories from file paths
+    entries.forEach((entry) => {
+      if (!entry.isDirectory) {
+        // Extract directory path from file path
+        const pathParts = entry.entryName.split('/');
+        for (let i = 1; i < pathParts.length; i++) {
+          const dirPath = pathParts.slice(0, i).join('/');
+          directories.add(dirPath);
+        }
+      } else {
+        // Also add explicit directories
+        const dirPath = entry.entryName.replace(/\/$/, ''); // Remove trailing slash
+        if (dirPath) {
+          directories.add(dirPath);
+        }
+      }
+    });
+
+    // Add directory items to cache
+    directories.forEach((dirPath) => {
+      const absolutePath = this.resolveAbsolutePath(dirPath);
+      const item = new ZipDirectoryItem(dirPath, this);
+      this._itemCache.set(absolutePath, item);
+    });
+
+    // Add file items to cache
+    entries.forEach((entry) => {
+      if (!entry.isDirectory) {
+        const absolutePath = this.resolveAbsolutePath(entry.entryName);
+        const contents = entry.getData().toString('utf8');
+        const item = new ZipFileItem(entry.entryName, contents, this);
+        this._itemCache.set(absolutePath, item);
+      }
+    });
+  }
+
+  /**
+   * Resolves paths to an absolute path.
+   */
+  public resolveAbsolutePath(...paths: string[]): string {
+    const joinedPath = this.joinPaths(...paths);
+    const prefixed = this._prefix ? this.joinPaths(this._prefix, joinedPath) : joinedPath;
+    return prefixed.startsWith('/') ? prefixed : '/' + prefixed;
+  }
+
+  /**
+   * Gets the extension of a path.
+   */
+  public getExtension(path: string): string {
+    const name = this.getBaseName(path);
+    const lastDotIndex = name.lastIndexOf('.');
+    return lastDotIndex >= 0 ? name.substring(lastDotIndex) : '';
+  }
+
+  /**
+   * Gets the base name of a path.
+   */
+  public getBaseName(path: string, suffix?: string): string {
+    const normalizedPath = path.replace(/\/$/, ''); // Remove trailing slash
+    const parts = normalizedPath.split('/');
+    let baseName = parts[parts.length - 1] || '';
+
+    if (suffix && baseName.endsWith(suffix)) {
+      baseName = baseName.substring(0, baseName.length - suffix.length);
+    }
+
+    return baseName;
+  }
+
+  /**
+   * Joins paths together.
+   */
+  public joinPaths(...paths: string[]): string {
+    return paths
+      .filter((p) => p && p.length > 0)
+      .map((p) => p.replace(/^\/+|\/+$/g, '')) // Remove leading/trailing slashes
+      .join('/')
+      .replace(/\/+/g, '/'); // Normalize multiple slashes
+  }
+
+  /**
+   * Gets an item from the file tree.
+   */
+  public getItem(path: string): Result<FileTree.FileTreeItem> {
+    const absolutePath = this.resolveAbsolutePath(path);
+    const item = this._itemCache.get(absolutePath);
+
+    if (item) {
+      return succeed(item);
+    }
+
+    return fail(`Item not found: ${absolutePath}`);
+  }
+
+  /**
+   * Gets the contents of a file in the file tree.
+   */
+  public getFileContents(path: string): Result<string> {
+    return this.getItem(path).onSuccess((item) => {
+      if (item.type !== 'file') {
+        return fail(`Path is not a file: ${path}`);
+      }
+      return item.getRawContents();
+    });
+  }
+
+  /**
+   * Gets the children of a directory in the file tree.
+   */
+  public getChildren(path: string): Result<ReadonlyArray<FileTree.FileTreeItem>> {
+    const absolutePath = this.resolveAbsolutePath(path);
+    const children: FileTree.FileTreeItem[] = [];
+
+    // Find all items that are direct children of this directory
+    for (const [itemPath, item] of this._itemCache) {
+      if (this._isDirectChild(absolutePath, itemPath)) {
+        children.push(item);
+      }
+    }
+
+    return succeed(children);
+  }
+
+  /**
+   * Checks if childPath is a direct child of parentPath.
+   */
+  private _isDirectChild(parentPath: string, childPath: string): boolean {
+    // Normalize paths
+    const normalizedParent = parentPath.replace(/\/$/, '');
+    const normalizedChild = childPath.replace(/\/$/, '');
+
+    // Child must start with parent path
+    if (!normalizedChild.startsWith(normalizedParent + '/')) {
+      return false;
+    }
+
+    // Get the relative path from parent to child
+    const relativePath = normalizedChild.substring(normalizedParent.length + 1);
+
+    // Direct child means no additional slashes in the relative path
+    return !relativePath.includes('/');
+  }
+}