@fgv/ts-res-browser 1.0.0 → 5.0.0-2

package/src/utils/urlParams.ts

@@ -0,0 +1,238 @@
+/*
+ * 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.
+ */
+
+/**
+ * Configuration options that can be passed via URL parameters
+ */
+export interface IUrlConfigOptions {
+  /**
+   * Input file path
+   */
+  input?: string;
+
+  /**
+   * Configuration name or path
+   */
+  config?: string;
+
+  /**
+   * Context filter token (pipe-separated)
+   */
+  contextFilter?: string;
+
+  /**
+   * Qualifier defaults token (pipe-separated)
+   */
+  qualifierDefaults?: string;
+
+  /**
+   * Resource types filter (comma-separated)
+   */
+  resourceTypes?: string;
+
+  /**
+   * Maximum distance for language matching
+   */
+  maxDistance?: number;
+
+  /**
+   * Whether to reduce qualifiers
+   */
+  reduceQualifiers?: boolean;
+
+  /**
+   * Whether to launch in interactive mode
+   */
+  interactive?: boolean;
+
+  /**
+   * Starting directory for input file picker (derived from input path)
+   */
+  inputStartDir?: string;
+
+  /**
+   * Starting directory for config file picker (derived from config path)
+   */
+  configStartDir?: string;
+
+  /**
+   * Whether to use ZIP loading mode
+   */
+  loadZip?: boolean;
+
+  /**
+   * Path to ZIP file to load (for CLI-generated ZIPs)
+   */
+  zipPath?: string;
+
+  /**
+   * Name of ZIP file to load from Downloads (filename only)
+   */
+  zipFile?: string;
+}
+
+/**
+ * Parses URL parameters and extracts configuration options
+ */
+export function parseUrlParameters(): IUrlConfigOptions {
+  const params = new URLSearchParams(window.location.search);
+
+  const options: IUrlConfigOptions = {};
+
+  // Parse string parameters
+  const input = params.get('input');
+  if (input) {
+    options.input = input;
+    // Set starting directory for input file picker
+    if (isFilePath(input)) {
+      options.inputStartDir = extractDirectoryPath(input);
+    }
+  }
+
+  const config = params.get('config');
+  if (config) {
+    options.config = config;
+    // Set starting directory for config file picker
+    if (isFilePath(config)) {
+      options.configStartDir = extractDirectoryPath(config);
+    }
+  }
+
+  const contextFilter = params.get('contextFilter');
+  if (contextFilter) options.contextFilter = contextFilter;
+
+  const qualifierDefaults = params.get('qualifierDefaults');
+  if (qualifierDefaults) options.qualifierDefaults = qualifierDefaults;
+
+  const resourceTypes = params.get('resourceTypes');
+  if (resourceTypes) options.resourceTypes = resourceTypes;
+
+  // Parse numeric parameters
+  const maxDistance = params.get('maxDistance');
+  if (maxDistance) {
+    const parsed = parseInt(maxDistance, 10);
+    if (!isNaN(parsed)) options.maxDistance = parsed;
+  }
+
+  // Parse boolean parameters
+  const reduceQualifiers = params.get('reduceQualifiers');
+  if (reduceQualifiers === 'true') options.reduceQualifiers = true;
+
+  const interactive = params.get('interactive');
+  if (interactive === 'true') options.interactive = true;
+
+  // Parse ZIP loading parameters
+  const loadZip = params.get('loadZip');
+  if (loadZip === 'true') options.loadZip = true;
+
+  const zipPath = params.get('zipPath');
+  if (zipPath) options.zipPath = zipPath;
+
+  const zipFile = params.get('zipFile');
+  if (zipFile) options.zipFile = zipFile;
+
+  return options;
+}
+
+/**
+ * Converts context filter token to context object
+ * Example: "language=en-US|territory=US" -> { language: "en-US", territory: "US" }
+ */
+export function parseContextFilter(contextFilter: string): Record<string, string> {
+  const context: Record<string, string> = {};
+
+  const tokens = contextFilter.split('|');
+  for (const token of tokens) {
+    const [key, value] = token.split('=');
+    if (key && value) {
+      context[key.trim()] = value.trim();
+    }
+  }
+
+  return context;
+}
+
+/**
+ * Converts qualifier defaults token to structured format
+ * Example: "language=en-US,en-CA|territory=US" -> { language: ["en-US", "en-CA"], territory: ["US"] }
+ */
+export function parseQualifierDefaults(qualifierDefaults: string): Record<string, string[]> {
+  const defaults: Record<string, string[]> = {};
+
+  const tokens = qualifierDefaults.split('|');
+  for (const token of tokens) {
+    const [key, values] = token.split('=');
+    if (key && values) {
+      defaults[key.trim()] = values.split(',').map((v) => v.trim());
+    }
+  }
+
+  return defaults;
+}
+
+/**
+ * Converts resource types string to array
+ * Example: "json,string" -> ["json", "string"]
+ */
+export function parseResourceTypes(resourceTypes: string): string[] {
+  return resourceTypes
+    .split(',')
+    .map((t) => t.trim())
+    .filter((t) => t.length > 0);
+}
+
+/**
+ * Extracts the directory path from a file or directory path
+ * If the path appears to be a directory (no extension), returns it as-is
+ * If the path appears to be a file, returns the parent directory
+ */
+export function extractDirectoryPath(path: string): string {
+  if (!path) return '';
+
+  // Normalize path separators
+  const normalizedPath = path.replace(/\\/g, '/');
+
+  // Check if it looks like a file (has an extension)
+  const parts = normalizedPath.split('/');
+  const lastPart = parts[parts.length - 1];
+
+  // If the last part has an extension, treat as file and return directory
+  if (lastPart.includes('.') && !lastPart.startsWith('.')) {
+    return parts.slice(0, -1).join('/') || '/';
+  }
+
+  // Otherwise, treat as directory
+  return normalizedPath;
+}
+
+/**
+ * Determines if a path appears to be a file (has extension) or directory
+ */
+export function isFilePath(path: string): boolean {
+  if (!path) return false;
+
+  const parts = path.split('/');
+  const lastPart = parts[parts.length - 1];
+
+  // Has extension and doesn't start with dot (hidden files)
+  return lastPart.includes('.') && !lastPart.startsWith('.');
+}

package/src/utils/zip/browserZipFileTreeAccessors.ts

@@ -0,0 +1,385 @@
+/*
+ * 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 JSZip from 'jszip';
+import { Result, succeed, fail, captureResult, Converter, Validator, FileTree } from '@fgv/ts-utils';
+
+/**
+ * Implementation of {@link FileTree.IFileTreeFileItem} for files in a ZIP archive (browser version).
+ */
+export class BrowserZipFileItem implements FileTree.IFileTreeFileItem {
+  /**
+   * Indicates that this {@link 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: BrowserZipFileTreeAccessors;
+
+  /**
+   * Constructor for BrowserZipFileItem.
+   * @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: BrowserZipFileTreeAccessors) {
+    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);
+            } 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 {@link FileTree.IFileTreeDirectoryItem} for directories in a ZIP archive (browser version).
+ */
+export class BrowserZipDirectoryItem implements FileTree.IFileTreeDirectoryItem {
+  /**
+   * Indicates that this {@link 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: BrowserZipFileTreeAccessors;
+
+  /**
+   * Constructor for BrowserZipDirectoryItem.
+   * @param directoryPath - The path of the directory within the ZIP.
+   * @param accessors - The ZIP file tree accessors.
+   */
+  public constructor(directoryPath: string, accessors: BrowserZipFileTreeAccessors) {
+    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 (browser version using JSZip).
+ */
+export class BrowserZipFileTreeAccessors implements FileTree.IFileTreeAccessors {
+  /**
+   * The JSZip instance containing the archive.
+   */
+  private readonly _zip: JSZip;
+
+  /**
+   * 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();
+
+  /**
+   * Cache of all file contents pre-loaded from the ZIP.
+   */
+  private readonly _fileContents: Map<string, string> = new Map();
+
+  /**
+   * Constructor for BrowserZipFileTreeAccessors.
+   * @param zip - The JSZip instance.
+   * @param fileContents - Pre-loaded file contents.
+   * @param prefix - Optional prefix to prepend to paths.
+   */
+  private constructor(zip: JSZip, fileContents: Map<string, string>, prefix?: string) {
+    this._zip = zip;
+    this._fileContents = fileContents;
+    this._prefix = prefix || '';
+    this._buildItemCache();
+  }
+
+  /**
+   * Creates a new BrowserZipFileTreeAccessors 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 BrowserZipFileTreeAccessors instance.
+   */
+  public static async fromBuffer(
+    zipBuffer: ArrayBuffer | Uint8Array,
+    prefix?: string
+  ): Promise<Result<BrowserZipFileTreeAccessors>> {
+    try {
+      const zip = new JSZip();
+      await zip.loadAsync(zipBuffer);
+      const fileContents = new Map<string, string>();
+
+      // Pre-load all file contents
+      const promises: Promise<void>[] = [];
+      zip.forEach((relativePath, zipObject) => {
+        if (!zipObject.dir) {
+          const promise = zipObject.async('string').then((content) => {
+            fileContents.set(relativePath, content);
+          });
+          promises.push(promise);
+        }
+      });
+
+      await Promise.all(promises);
+      return succeed(new BrowserZipFileTreeAccessors(zip, fileContents, prefix));
+    } catch (error) {
+      return fail(`Failed to load ZIP archive: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Creates a new BrowserZipFileTreeAccessors 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 BrowserZipFileTreeAccessors instance.
+   */
+  public static async fromFile(file: File, prefix?: string): Promise<Result<BrowserZipFileTreeAccessors>> {
+    try {
+      const arrayBuffer = await file.arrayBuffer();
+      return await BrowserZipFileTreeAccessors.fromBuffer(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>();
+
+    // First pass: collect all directories from file paths
+    this._zip.forEach((relativePath, zipObject) => {
+      if (!zipObject.dir) {
+        // Extract directory path from file path
+        const pathParts = relativePath.split('/');
+        for (let i = 1; i < pathParts.length; i++) {
+          const dirPath = pathParts.slice(0, i).join('/');
+          directories.add(dirPath);
+        }
+      }
+    });
+
+    // Add directory items to cache
+    directories.forEach((dirPath) => {
+      const absolutePath = this.resolveAbsolutePath(dirPath);
+      const item = new BrowserZipDirectoryItem(dirPath, this);
+      this._itemCache.set(absolutePath, item);
+    });
+
+    // Add file items to cache
+    this._zip.forEach((relativePath, zipObject) => {
+      if (!zipObject.dir) {
+        const absolutePath = this.resolveAbsolutePath(relativePath);
+        const contents = this._fileContents.get(relativePath) || '';
+        const item = new BrowserZipFileItem(relativePath, 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('/');
+  }
+}

package/webpack.config.js

@@ -16,12 +16,18 @@ module.exports = {
       crypto: require.resolve('crypto-browserify'),
       stream: require.resolve('stream-browserify'),
       util: require.resolve('util'),
-      buffer: require.resolve('buffer'),
+      buffer: require.resolve('buffer/'),
       process: require.resolve('process/browser'),
+      zlib: require.resolve('browserify-zlib'),
+      assert: require.resolve('assert/'),
       // Remove fs and path since we're using in-memory FileTree
       fs: false,
       path: false,
       vm: false
+    },
+    alias: {
+      // Replace the Node.js ZIP implementation with empty module
+      'adm-zip': false
     }
   },
   module: {