@fgv/ts-web-extras 5.0.0

package/dist/ts-web-extras.d.ts

@@ -0,0 +1,574 @@
+/**
+ * Browser-compatible utilities and FileTree implementations.
+ *
+ * This library provides browser-compatible alternatives to Node.js-specific functionality,
+ * including Web Crypto API-based hashing, File API-based file tree implementations,
+ * and URL parameter parsing utilities.
+ * All exports are designed to be tree-shakeable for optimal bundle size.
+ *
+ * @packageDocumentation
+ */
+
+import { FileTree } from '@fgv/ts-json-base';
+import { Result } from '@fgv/ts-utils';
+
+/**
+ * Browser-compatible hash provider using the Web Crypto API.
+ * Supports common hash algorithms available in browsers.
+ * @public
+ */
+export declare class BrowserHashProvider {
+    /**
+     * Hash a string using the specified algorithm.
+     * @param data - The string to hash
+     * @param algorithm - The hash algorithm to use
+     * @returns Promise resolving to the hex-encoded hash
+     */
+    static hashString(data: string, algorithm?: string): Promise<Result<string>>;
+    /**
+     * Hash multiple strings concatenated with a separator.
+     * @param parts - Array of strings to concatenate and hash
+     * @param algorithm - The hash algorithm to use
+     * @param separator - Separator to use between parts (default: '|')
+     * @returns Promise resolving to the hex-encoded hash
+     */
+    static hashParts(parts: string[], algorithm?: string, separator?: string): Promise<Result<string>>;
+}
+
+/**
+ * Default initialization parameters for a `FileTree` using {@link FileApiTreeAccessors}.
+ * @public
+ */
+declare const defaultFileApiTreeInitParams: FileTree.IFileTreeInitParams<string>;
+
+/**
+ * Export data as JSON file using legacy blob download method.
+ * Creates a temporary download link and triggers file download.
+ * @param data - Data to export as JSON
+ * @param filename - Name for the downloaded file
+ * @public
+ */
+export declare function exportAsJson(data: unknown, filename: string): void;
+
+/**
+ * Export data using File System Access API with fallback to blob download.
+ * @param data - Data to export as JSON
+ * @param suggestedName - Suggested filename for the save dialog
+ * @param description - Description for file type filter (default: 'JSON files')
+ * @param window - Window object for API access (default: globalThis.window)
+ * @returns Promise resolving to true if saved via File System Access API, false if fallback used
+ * @public
+ */
+export declare function exportUsingFileSystemAPI(data: unknown, suggestedName: string, description?: string, window?: Window): Promise<boolean>;
+
+/**
+ * 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 declare function extractDirectoryPath(path: string): string;
+
+/**
+ * Helper function to extract metadata from a `FileList`.
+ * @param fileList - The `FileList` to extract metadata from
+ * @returns Array of {@link IFileMetadata | file metadata} objects
+ * @public
+ */
+declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadata>;
+
+/**
+ * Helper function to extract metadata from a `File`.
+ * @param file - The File to extract metadata from
+ * @returns {@link IFileMetadata | file metadata} object
+     * @public
+     */
+ declare function extractFileMetadata(file: File): IFileMetadata;
+
+ /**
+  * Helper class to create FileTree instances from various file sources.
+  * Supports File API (FileList) and File System Access API handles.
+  * @public
+  */
+ export declare class FileApiTreeAccessors<TCT extends string = string> {
+     /**
+      * Create FileTree from various file sources using TreeInitializer array.
+      * @param initializers - Array of TreeInitializer objects specifying file sources
+      * @param params - Optional `IFileTreeInitParams` for the file tree.
+      * @returns Promise resolving to a FileTree with all content pre-loaded
+      */
+     static create<TCT extends string = string>(initializers: TreeInitializer[], params?: FileTree.IFileTreeInitParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
+     /**
+      * Create FileTree from FileList (e.g., from input[type="file"]).
+      * @param fileList - FileList from a file input element
+      * @param params - Optional `IFileTreeInitParams` for the file tree.
+      * @returns Promise resolving to a FileTree with all content pre-loaded
+      */
+     static fromFileList<TCT extends string = string>(fileList: FileList, params?: FileTree.IFileTreeInitParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
+     /**
+      * Create FileTree from directory upload with webkitRelativePath.
+      * @param fileList - FileList from a directory upload (input with webkitdirectory)
+      * @param params - Optional `IFileTreeInitParams` for the file tree.
+      * @returns Promise resolving to a FileTree with all content pre-loaded
+      */
+     static fromDirectoryUpload<TCT extends string = string>(fileList: FileList, params?: FileTree.IFileTreeInitParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
+     /**
+      * Get the File object for a specific path from the original FileList.
+      * This is useful for accessing the original File API object for operations
+      * like getting file metadata, MIME type, etc.
+      * @param fileList - The original FileList
+      * @param targetPath - The path to find
+      * @returns Result containing the File object if found
+      */
+     static getOriginalFile(fileList: FileList, targetPath: string): Result<File>;
+     /**
+      * Extract file metadata from a File.
+      * @param fileList - The File to extract metadata from
+      * @returns The {@link IFileMetadata | file metadata}
+      */
+     static extractFileMetadata(file: File): IFileMetadata;
+     /**
+      * Process a single TreeInitializer and return the resulting files.
+      * @param initializer - The TreeInitializer to process
+      * @param params - Optional `IFileTreeInitParams` for the file tree.
+      * @returns Promise resolving to an array of `IInMemoryFile` objects
+      * @internal
+      */
+     private static _processInitializer;
+     /**
+      * Process a FileList and return IInMemoryFile array.
+      * @param fileList - The FileList to process
+      * @param params - Optional `IFileTreeInitParams` for the file tree.
+      * @returns Promise resolving to an array of `IInMemoryFile` objects
+      * @internal
+      */
+     private static _processFileList;
+     /**
+      * Process FileSystemFileHandles and return IInMemoryFile array.
+      * @internal
+      */
+     private static _processFileHandles;
+     /**
+      * Process FileSystemDirectoryHandles and return IInMemoryFile array.
+      * @param handles - The FileSystemDirectoryHandle[] to process
+      * @param prefix - The prefix to use for the file paths
+      * @param recursive - Whether to process the directory recursively
+      * @param params - Optional `IFileTreeInitParams` for the file tree.
+      * @returns Promise resolving to an array of `IInMemoryFile` objects
+      * @internal
+      */
+     private static _processDirectoryHandles;
+     /**
+      * Process a single FileSystemDirectoryHandle recursively.
+      * @param handle - The FileSystemDirectoryHandle to process
+      * @param basePath - The base path to use for the file paths
+      * @param recursive - Whether to process the directory recursively
+      * @param params - Optional `IFileTreeInitParams` for the file tree.
+      * @returns Promise resolving to an array of `IInMemoryFile` objects
+      * @internal
+      */
+     private static _processDirectoryHandle;
+     private static _normalizePath;
+ }
+
+ /**
+  * File picker accept type
+  * @public
+  */
+ export declare interface FilePickerAcceptType {
+     description?: string;
+     accept: Record<string, string | string[]>;
+ }
+
+ /**
+  * Options for creating writable file streams
+  * @public
+  */
+ declare interface FileSystemCreateWritableOptions_2 {
+     keepExistingData?: boolean;
+ }
+ export { FileSystemCreateWritableOptions_2 as FileSystemCreateWritableOptions }
+
+ /**
+  * Directory handle interface
+  * @public
+  */
+ declare interface FileSystemDirectoryHandle_2 extends FileSystemHandle_2 {
+     readonly kind: 'directory';
+     getDirectoryHandle(name: string, options?: FileSystemGetDirectoryOptions_2): Promise<FileSystemDirectoryHandle_2>;
+     getFileHandle(name: string, options?: FileSystemGetFileOptions_2): Promise<FileSystemFileHandle_2>;
+     removeEntry(name: string, options?: FileSystemRemoveOptions_2): Promise<void>;
+     resolve(possibleDescendant: FileSystemHandle_2): Promise<string[] | null>;
+     keys(): AsyncIterableIterator<string>;
+     values(): AsyncIterableIterator<FileSystemHandle_2>;
+     entries(): AsyncIterableIterator<[string, FileSystemHandle_2]>;
+     [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle_2]>;
+ }
+ export { FileSystemDirectoryHandle_2 as FileSystemDirectoryHandle }
+
+ /**
+  * File handle interface
+  * @public
+  */
+ declare interface FileSystemFileHandle_2 extends FileSystemHandle_2 {
+     readonly kind: 'file';
+     getFile(): Promise<File>;
+     createWritable(options?: FileSystemCreateWritableOptions_2): Promise<FileSystemWritableFileStream_2>;
+ }
+ export { FileSystemFileHandle_2 as FileSystemFileHandle }
+
+ /**
+  * Options for getting directory handles
+  * @public
+  */
+ declare interface FileSystemGetDirectoryOptions_2 {
+     create?: boolean;
+ }
+ export { FileSystemGetDirectoryOptions_2 as FileSystemGetDirectoryOptions }
+
+ /**
+  * Options for getting file handles
+  * @public
+  */
+ declare interface FileSystemGetFileOptions_2 {
+     create?: boolean;
+ }
+ export { FileSystemGetFileOptions_2 as FileSystemGetFileOptions }
+
+ /**
+  * Base interface for file system handles
+  * @public
+  */
+ declare interface FileSystemHandle_2 {
+     readonly kind: 'file' | 'directory';
+     readonly name: string;
+     isSameEntry(other: FileSystemHandle_2): Promise<boolean>;
+     queryPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
+     requestPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
+ }
+ export { FileSystemHandle_2 as FileSystemHandle }
+
+ /**
+  * Permission descriptor for file system handles
+  * @public
+  */
+ export declare interface FileSystemHandlePermissionDescriptor {
+     mode?: 'read' | 'readwrite';
+ }
+
+ /**
+  * Options for removing entries
+  * @public
+  */
+ declare interface FileSystemRemoveOptions_2 {
+     recursive?: boolean;
+ }
+ export { FileSystemRemoveOptions_2 as FileSystemRemoveOptions }
+
+ /**
+  * Writable file stream interface
+  * @public
+  */
+ declare interface FileSystemWritableFileStream_2 extends WritableStream {
+     write(data: BufferSource | Blob | string): Promise<void>;
+     seek(position: number): Promise<void>;
+     truncate(size: number): Promise<void>;
+ }
+ export { FileSystemWritableFileStream_2 as FileSystemWritableFileStream }
+
+ export declare namespace FileTreeHelpers {
+     export {
+         fromFileList,
+         fromDirectoryUpload,
+         getOriginalFile,
+         extractFileListMetadata,
+         extractFileMetadata,
+         defaultFileApiTreeInitParams
+     }
+ }
+
+ /**
+  * Helper function to create a new FileTree instance
+  * from a directory upload with webkitRelativePath support.
+  * @param fileList - FileList from a directory upload (input with webkitdirectory)
+  * @param params - Optional `IFileTreeInitParams` for the file tree.
+  * @returns Promise resolving to a successful Result with the new FileTree instance
+  * if successful, or a failed Result with an error message otherwise
+  * @remarks The content type of the files is always `string` and the default
+  * accept contentType function (`FileTree.FileItem.defaultAcceptContentType`) is
+  * is used, so content type is derived from the mime type of the file, when
+  * available.
+  * @public
+  */
+ declare function fromDirectoryUpload(fileList: FileList, params?: FileTree.IFileTreeInitParams<string>): Promise<Result<FileTree.FileTree<string>>>;
+
+ /**
+  * Helper function to create a new FileTree instance
+  * from a browser FileList (e.g., from input[type="file"]).
+  * @param fileList - FileList from a file input element
+  * @param params - Optional `IFileTreeInitParams` for the file tree.
+  * @returns Promise resolving to a successful Result with the new FileTree instance
+  * if successful, or a failed Result with an error message otherwise
+  * @remarks The content type of the files is always `string` and the default
+  * accept contentType function (`FileTree.FileItem.defaultAcceptContentType`) is
+  * used, so content type is derived from the mime type of the file, when
+  * available.
+  * @public
+  */
+ declare function fromFileList(fileList: FileList, params?: FileTree.IFileTreeInitParams<string>): Promise<Result<FileTree.FileTree<string>>>;
+
+ /**
+  * Helper function to get the original File object from a FileList by path.
+  * @param fileList - The original FileList
+  * @param path - The path to the file
+  * @returns A successful Result with the File object if found,
+  * or a failed Result with an error message otherwise
+  * @public
+  */
+ declare function getOriginalFile(fileList: FileList, path: string): Result<File>;
+
+ /**
+  * Tree initializer for File System Access API directory handles.
+  * @public
+  */
+ export declare interface IDirectoryHandleTreeInitializer {
+     readonly prefix?: string;
+     readonly dirHandles: FileSystemDirectoryHandle_2[];
+     readonly nonRecursive?: boolean;
+ }
+
+ /**
+  * Tree initializer for File System Access API file handles.
+  * @public
+  */
+ export declare interface IFileHandleTreeInitializer {
+     readonly prefix?: string;
+     readonly fileHandles: FileSystemFileHandle_2[];
+ }
+
+ /**
+  * Tree initializer for FileList objects (from File API).
+  * @public
+  */
+ export declare interface IFileListTreeInitializer {
+     readonly fileList: FileList;
+ }
+
+ /**
+  * Interface for file metadata.
+  * @public
+  */
+ export declare interface IFileMetadata {
+     path: string;
+     name: string;
+     size: number;
+     type: string;
+     lastModified: number;
+ }
+
+ /**
+  * File System Access API methods available on Window
+  * @public
+  */
+ export declare interface IFsAccessApis {
+     showDirectoryPicker(options?: ShowDirectoryPickerOptions): Promise<FileSystemDirectoryHandle_2>;
+     showOpenFilePicker(options?: ShowOpenFilePickerOptions): Promise<FileSystemFileHandle_2[]>;
+     showSaveFilePicker(options?: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle_2>;
+ }
+
+ /**
+  * Type guard to check if a FileSystemHandle is a directory handle
+  * @param handle - The handle to check
+  * @returns True if the handle is a FileSystemDirectoryHandle
+  * @public
+  */
+ export declare function isDirectoryHandle(handle: FileSystemHandle_2): handle is FileSystemDirectoryHandle_2;
+
+ /**
+  * Type guard to check if a FileSystemHandle is a file handle
+  * @param handle - The handle to check
+  * @returns True if the handle is a FileSystemFileHandle
+  * @public
+  */
+ export declare function isFileHandle(handle: FileSystemHandle_2): handle is FileSystemFileHandle_2;
+
+ /**
+  * Determines if a path appears to be a file (has extension) or directory
+  * @public
+  */
+ export declare function isFilePath(path: string): boolean;
+
+ /**
+  * Configuration options that can be passed via URL parameters
+  * @public
+  */
+ export declare 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;
+ }
+
+ /**
+  * Converts context filter token to context object
+  * Example: "language=en-US|territory=US" -\> \{ language: "en-US", territory: "US" \}
+  * @public
+  */
+ export declare function parseContextFilter(contextFilter: string): Record<string, string>;
+
+ /**
+  * Converts qualifier defaults token to structured format
+  * Example: "language=en-US,en-CA|territory=US" -\> \{ language: ["en-US", "en-CA"], territory: ["US"] \}
+  * @public
+  */
+ export declare function parseQualifierDefaults(qualifierDefaults: string): Record<string, string[]>;
+
+ /**
+  * Converts resource types string to array
+  * Example: "json,string" -\> ["json", "string"]
+  * @public
+  */
+ export declare function parseResourceTypes(resourceTypes: string): string[];
+
+ /**
+  * Parses URL parameters and extracts configuration options
+  * @public
+  */
+ export declare function parseUrlParameters(): IUrlConfigOptions;
+
+ /**
+  * Safely access showDirectoryPicker with proper type checking
+  * @param window - The window object
+  * @param options - Options for the directory picker
+  * @returns Promise with directory handle or null if not supported
+  * @public
+  */
+ export declare function safeShowDirectoryPicker(window: Window, options?: ShowDirectoryPickerOptions): Promise<FileSystemDirectoryHandle_2 | null>;
+
+ /**
+  * Safely access showOpenFilePicker with proper type checking
+  * @param window - The window object
+  * @param options - Options for the file picker
+  * @returns Promise with file handles or null if not supported
+  * @public
+  */
+ export declare function safeShowOpenFilePicker(window: Window, options?: ShowOpenFilePickerOptions): Promise<FileSystemFileHandle_2[] | null>;
+
+ /**
+  * Safely access showSaveFilePicker with proper type checking
+  * @param window - The window object
+  * @param options - Options for the file picker
+  * @returns Promise with file handle or null if not supported
+  * @public
+  */
+ export declare function safeShowSaveFilePicker(window: Window, options?: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle_2 | null>;
+
+ /**
+  * Directory picker options
+  * @public
+  */
+ export declare interface ShowDirectoryPickerOptions {
+     id?: string;
+     mode?: 'read' | 'readwrite';
+     startIn?: FileSystemHandle_2 | WellKnownDirectory;
+ }
+
+ /**
+  * File picker options
+  * @public
+  */
+ export declare interface ShowOpenFilePickerOptions {
+     multiple?: boolean;
+     excludeAcceptAllOption?: boolean;
+     id?: string;
+     startIn?: FileSystemHandle_2 | WellKnownDirectory;
+     types?: FilePickerAcceptType[];
+ }
+
+ /**
+  * Save file picker options
+  * @public
+  */
+ export declare interface ShowSaveFilePickerOptions {
+     excludeAcceptAllOption?: boolean;
+     id?: string;
+     startIn?: FileSystemHandle_2 | WellKnownDirectory;
+     suggestedName?: string;
+     types?: FilePickerAcceptType[];
+ }
+
+ /**
+  * Type guard to check if the browser supports the File System Access API
+  * @param window - The window object to check
+  * @returns True if the window supports File System Access API
+  * @public
+  */
+ export declare function supportsFileSystemAccess(window: Window): window is WindowWithFsAccess;
+
+ /**
+  * Union type for all supported tree initializers.
+  * @public
+  */
+ export declare type TreeInitializer = IFileListTreeInitializer | IFileHandleTreeInitializer | IDirectoryHandleTreeInitializer;
+
+ /**
+  * Well-known directory type
+  * @public
+  */
+ export declare type WellKnownDirectory = 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos';
+
+ /**
+  * Window interface extended with File System Access API
+  * @public
+  */
+ export declare type WindowWithFsAccess = Window & IFsAccessApis;
+
+ export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.52.12"
+    }
+  ]
+}

package/docs/index.md

@@ -0,0 +1,34 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+<table><thead><tr><th>
+
+Package
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[@fgv/ts-web-extras](./ts-web-extras.md)
+
+
+</td><td>
+
+Browser-compatible utilities and FileTree implementations.
+
+This library provides browser-compatible alternatives to Node.js-specific functionality, including Web Crypto API-based hashing, File API-based file tree implementations, and URL parameter parsing utilities. All exports are designed to be tree-shakeable for optimal bundle size.
+
+
+</td></tr>
+</tbody></table>
+

package/docs/ts-web-extras.browserhashprovider.hashparts.md

@@ -0,0 +1,88 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@fgv/ts-web-extras](./ts-web-extras.md) &gt; [BrowserHashProvider](./ts-web-extras.browserhashprovider.md) &gt; [hashParts](./ts-web-extras.browserhashprovider.hashparts.md)
+
+## BrowserHashProvider.hashParts() method
+
+Hash multiple strings concatenated with a separator.
+
+**Signature:**
+
+```typescript
+static hashParts(parts: string[], algorithm?: string, separator?: string): Promise<Result<string>>;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+parts
+
+
+</td><td>
+
+string\[\]
+
+
+</td><td>
+
+Array of strings to concatenate and hash
+
+
+</td></tr>
+<tr><td>
+
+algorithm
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+_(Optional)_ The hash algorithm to use
+
+
+</td></tr>
+<tr><td>
+
+separator
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+_(Optional)_ Separator to use between parts (default: '\|')
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;string&gt;&gt;
+
+Promise resolving to the hex-encoded hash
+