@fgv/ts-web-extras 5.0.0

package/src/packlets/url-utils/urlParams.ts

@@ -0,0 +1,245 @@
+/*
+ * 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
+ * @public
+ */
+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
+ * @public
+ */
+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" \}
+ * @public
+ */
+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"] \}
+ * @public
+ */
+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"]
+ * @public
+ */
+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
+ * @public
+ */
+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
+ * @public
+ */
+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/test/setupTests.ts

@@ -0,0 +1,87 @@
+/*
+ * 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 { webcrypto } from 'crypto';
+import { TextEncoder, TextDecoder } from 'util';
+
+// Setup Web Crypto API using Node.js webcrypto
+Object.defineProperty(global, 'crypto', {
+  value: webcrypto,
+  writable: true,
+  configurable: true
+});
+
+// Setup TextEncoder/TextDecoder for Node environment
+Object.defineProperty(global, 'TextEncoder', {
+  value: TextEncoder,
+  writable: true,
+  configurable: true
+});
+
+Object.defineProperty(global, 'TextDecoder', {
+  value: TextDecoder,
+  writable: true,
+  configurable: true
+});
+
+// Mock DataTransfer for File API testing
+class MockDataTransfer {
+  items: { add: (file: File) => void };
+  files: FileList;
+
+  constructor() {
+    const fileArray: File[] = [];
+
+    this.items = {
+      add: (file: File) => {
+        fileArray.push(file);
+        this.files = createFileList(fileArray);
+      }
+    };
+
+    this.files = createFileList([]);
+  }
+}
+
+function createFileList(files: File[]): FileList {
+  const fileList = {
+    length: files.length,
+    item: (index: number) => files[index] || null,
+    [Symbol.iterator]: function* () {
+      for (const file of files) {
+        yield file;
+      }
+    }
+  };
+
+  for (let i = 0; i < files.length; i++) {
+    (fileList as unknown as Record<number, File>)[i] = files[i];
+  }
+
+  return fileList as unknown as FileList;
+}
+
+Object.defineProperty(global, 'DataTransfer', {
+  value: MockDataTransfer,
+  writable: true,
+  configurable: true
+});

package/src/test/unit/browserHashProvider.test.ts

@@ -0,0 +1,155 @@
+/*
+ * 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 '@fgv/ts-utils-jest';
+import { BrowserHashProvider } from '../../packlets/crypto';
+
+describe('BrowserHashProvider', () => {
+  describe('hashString', () => {
+    test('successfully hashes a string with SHA-256', async () => {
+      const result = await BrowserHashProvider.hashString('test data', 'SHA-256');
+      expect(result).toSucceedAndSatisfy((hash) => {
+        expect(typeof hash).toBe('string');
+        expect(hash).toMatch(/^[a-f0-9]{64}$/); // SHA-256 produces 64 hex characters
+      });
+    });
+
+    test('successfully hashes a string with SHA-1', async () => {
+      const result = await BrowserHashProvider.hashString('test data', 'SHA-1');
+      expect(result).toSucceedAndSatisfy((hash) => {
+        expect(typeof hash).toBe('string');
+        expect(hash).toMatch(/^[a-f0-9]{40}$/); // SHA-1 produces 40 hex characters
+      });
+    });
+
+    test('successfully hashes a string with SHA-512', async () => {
+      const result = await BrowserHashProvider.hashString('test data', 'SHA-512');
+      expect(result).toSucceedAndSatisfy((hash) => {
+        expect(typeof hash).toBe('string');
+        expect(hash).toMatch(/^[a-f0-9]{128}$/); // SHA-512 produces 128 hex characters
+      });
+    });
+
+    test('uses SHA-256 as default algorithm', async () => {
+      const result = await BrowserHashProvider.hashString('test data');
+      expect(result).toSucceedAndSatisfy((hash) => {
+        expect(hash).toMatch(/^[a-f0-9]{64}$/); // SHA-256 produces 64 hex characters
+      });
+    });
+
+    test('produces consistent hash for same input', async () => {
+      const input = 'consistent input';
+      const result1 = await BrowserHashProvider.hashString(input);
+      const result2 = await BrowserHashProvider.hashString(input);
+      expect(result1).toSucceed();
+      expect(result2).toSucceed();
+      if (result1.isSuccess() && result2.isSuccess()) {
+        expect(result1.value).toBe(result2.value);
+      }
+    });
+
+    test('produces different hashes for different inputs', async () => {
+      const result1 = await BrowserHashProvider.hashString('input1');
+      const result2 = await BrowserHashProvider.hashString('input2');
+      expect(result1).toSucceed();
+      expect(result2).toSucceed();
+      if (result1.isSuccess() && result2.isSuccess()) {
+        expect(result1.value).not.toBe(result2.value);
+      }
+    });
+
+    test('handles empty string input', async () => {
+      const result = await BrowserHashProvider.hashString('');
+      expect(result).toSucceed();
+    });
+
+    test('handles unicode input', async () => {
+      const result = await BrowserHashProvider.hashString('🚀 Unicode test 测试');
+      expect(result).toSucceedAndSatisfy((hash) => {
+        expect(hash).toMatch(/^[a-f0-9]{64}$/);
+      });
+    });
+
+    test('fails when crypto.subtle is unavailable', async () => {
+      const originalCrypto = global.crypto;
+      // @ts-ignore - Intentionally removing crypto for test
+      delete global.crypto;
+      const result = await BrowserHashProvider.hashString('test');
+      expect(result).toFailWith(/Hash computation failed/);
+      global.crypto = originalCrypto;
+    });
+
+    test('handles invalid algorithm gracefully', async () => {
+      const result = await BrowserHashProvider.hashString('test', 'INVALID-ALG');
+      expect(result).toFailWith(/Hash computation failed/);
+    });
+  });
+
+  describe('hashParts', () => {
+    test('hashes multiple parts with default separator', async () => {
+      const parts = ['part1', 'part2', 'part3'];
+      const result = await BrowserHashProvider.hashParts(parts);
+      expect(result).toSucceedAndSatisfy((hash) => {
+        expect(hash).toMatch(/^[a-f0-9]{64}$/);
+      });
+    });
+
+    test('hashes multiple parts with custom separator', async () => {
+      const parts = ['part1', 'part2', 'part3'];
+      const result1 = await BrowserHashProvider.hashParts(parts, 'SHA-256', '|');
+      const result2 = await BrowserHashProvider.hashParts(parts, 'SHA-256', ',');
+      expect(result1).toSucceed();
+      expect(result2).toSucceed();
+      if (result1.isSuccess() && result2.isSuccess()) {
+        expect(result1.value).not.toBe(result2.value);
+      }
+    });
+
+    test('produces same hash as hashString for joined parts', async () => {
+      const parts = ['a', 'b', 'c'];
+      const separator = '-';
+      const joined = parts.join(separator);
+      const partsResult = await BrowserHashProvider.hashParts(parts, 'SHA-256', separator);
+      const stringResult = await BrowserHashProvider.hashString(joined);
+      expect(partsResult).toSucceed();
+      expect(stringResult).toSucceed();
+      if (partsResult.isSuccess() && stringResult.isSuccess()) {
+        expect(partsResult.value).toBe(stringResult.value);
+      }
+    });
+
+    test('handles empty array', async () => {
+      const result = await BrowserHashProvider.hashParts([]);
+      expect(result).toSucceed();
+    });
+
+    test('handles single part', async () => {
+      const result = await BrowserHashProvider.hashParts(['single']);
+      const stringResult = await BrowserHashProvider.hashString('single');
+      expect(result).toSucceed();
+      expect(stringResult).toSucceed();
+      if (result.isSuccess() && stringResult.isSuccess()) {
+        expect(result.value).toBe(stringResult.value);
+      }
+    });
+  });
+});