@fgv/ts-web-extras 5.0.1-1 → 5.0.1-10

package/dist/index.browser.js

@@ -0,0 +1,24 @@
+/*
+ * 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.
+ */
+// Browser entry point - re-exports everything from main index
+export * from './index';
+//# sourceMappingURL=index.browser.js.map

package/dist/index.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,8DAA8D;AAC9D,cAAc,SAAS,CAAC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n// Browser entry point - re-exports everything from main index\nexport * from './index';\n"]}

package/dist/index.js

@@ -0,0 +1,42 @@
+/*
+ * 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.
+ */
+/**
+ * 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
+ */
+// Export crypto functionality
+export * from './packlets/crypto';
+// Export file tree functionality
+export * from './packlets/file-tree';
+// Export helper functions
+export * from './packlets/helpers';
+// Export File System Access API types
+export * from './packlets/file-api-types';
+// Export URL utilities
+export * from './packlets/url-utils';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;GASG;AAEH,8BAA8B;AAC9B,cAAc,mBAAmB,CAAC;AAElC,iCAAiC;AACjC,cAAc,sBAAsB,CAAC;AAErC,0BAA0B;AAC1B,cAAc,oBAAoB,CAAC;AAEnC,sCAAsC;AACtC,cAAc,2BAA2B,CAAC;AAE1C,uBAAuB;AACvB,cAAc,sBAAsB,CAAC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Browser-compatible utilities and FileTree implementations.\n *\n * This library provides browser-compatible alternatives to Node.js-specific functionality,\n * including Web Crypto API-based hashing, File API-based file tree implementations,\n * and URL parameter parsing utilities.\n * All exports are designed to be tree-shakeable for optimal bundle size.\n *\n * @packageDocumentation\n */\n\n// Export crypto functionality\nexport * from './packlets/crypto';\n\n// Export file tree functionality\nexport * from './packlets/file-tree';\n\n// Export helper functions\nexport * from './packlets/helpers';\n\n// Export File System Access API types\nexport * from './packlets/file-api-types';\n\n// Export URL utilities\nexport * from './packlets/url-utils';\n"]}

package/dist/packlets/crypto/browserHashProvider.js

@@ -0,0 +1,66 @@
+/*
+ * 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 { succeed, fail } from '@fgv/ts-utils';
+/**
+ * Browser-compatible hash provider using the Web Crypto API.
+ * Supports common hash algorithms available in browsers.
+ * @public
+ */
+export 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 async hashString(data, algorithm = 'SHA-256') {
+        try {
+            /* c8 ignore next 3 - defense in depth */
+            if (!crypto.subtle) {
+                return fail('Web Crypto API not available in this environment');
+            }
+            const encoder = new TextEncoder();
+            const dataBuffer = encoder.encode(data);
+            const hashBuffer = await crypto.subtle.digest(algorithm, dataBuffer);
+            const hashArray = new Uint8Array(hashBuffer);
+            const hashHex = Array.from(hashArray)
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join('');
+            return succeed(hashHex);
+        }
+        catch (error) {
+            return fail(`Hash computation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * 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 async hashParts(parts, algorithm = 'SHA-256', separator = '|') {
+        const combined = parts.join(separator);
+        return this.hashString(combined, algorithm);
+    }
+}
+//# sourceMappingURL=browserHashProvider.js.map

package/dist/packlets/crypto/browserHashProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserHashProvider.js","sourceRoot":"","sources":["../../../src/packlets/crypto/browserHashProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAU,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;GAIG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAY,EAAE,YAAoB,SAAS;QACxE,IAAI,CAAC;YACH,yCAAyC;YACzC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBACnB,OAAO,IAAI,CAAC,kDAAkD,CAAC,CAAC;YAClE,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACxC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;YACrE,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;YAC7C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;iBAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;iBAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;YAEZ,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAI,CAAC,4BAA4B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpG,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,SAAS,CAC3B,KAAe,EACf,YAAoB,SAAS,EAC7B,YAAoB,GAAG;QAEvB,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, succeed, fail } from '@fgv/ts-utils';\n\n/**\n * Browser-compatible hash provider using the Web Crypto API.\n * Supports common hash algorithms available in browsers.\n * @public\n */\nexport class BrowserHashProvider {\n  /**\n   * Hash a string using the specified algorithm.\n   * @param data - The string to hash\n   * @param algorithm - The hash algorithm to use\n   * @returns Promise resolving to the hex-encoded hash\n   */\n  public static async hashString(data: string, algorithm: string = 'SHA-256'): Promise<Result<string>> {\n    try {\n      /* c8 ignore next 3 - defense in depth */\n      if (!crypto.subtle) {\n        return fail('Web Crypto API not available in this environment');\n      }\n\n      const encoder = new TextEncoder();\n      const dataBuffer = encoder.encode(data);\n      const hashBuffer = await crypto.subtle.digest(algorithm, dataBuffer);\n      const hashArray = new Uint8Array(hashBuffer);\n      const hashHex = Array.from(hashArray)\n        .map((b) => b.toString(16).padStart(2, '0'))\n        .join('');\n\n      return succeed(hashHex);\n    } catch (error) {\n      return fail(`Hash computation failed: ${error instanceof Error ? error.message : String(error)}`);\n    }\n  }\n\n  /**\n   * Hash multiple strings concatenated with a separator.\n   * @param parts - Array of strings to concatenate and hash\n   * @param algorithm - The hash algorithm to use\n   * @param separator - Separator to use between parts (default: '|')\n   * @returns Promise resolving to the hex-encoded hash\n   */\n  public static async hashParts(\n    parts: string[],\n    algorithm: string = 'SHA-256',\n    separator: string = '|'\n  ): Promise<Result<string>> {\n    const combined = parts.join(separator);\n    return this.hashString(combined, algorithm);\n  }\n}\n"]}

package/dist/packlets/crypto/index.js

@@ -0,0 +1,27 @@
+/*
+ * 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.
+ */
+/**
+ * Browser-compatible cryptographic utilities using the Web Crypto API.
+ * @packageDocumentation
+ */
+export * from './browserHashProvider';
+//# sourceMappingURL=index.js.map

package/dist/packlets/crypto/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/crypto/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;GAGG;AAEH,cAAc,uBAAuB,CAAC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Browser-compatible cryptographic utilities using the Web Crypto API.\n * @packageDocumentation\n */\n\nexport * from './browserHashProvider';\n"]}

package/dist/packlets/file-api-types/index.js

@@ -0,0 +1,156 @@
+/*
+ * 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.
+ */
+/**
+ * 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 function supportsFileSystemAccess(window) {
+    return 'showOpenFilePicker' in window && 'showSaveFilePicker' in window && 'showDirectoryPicker' in window;
+}
+/**
+ * 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 function isFileHandle(handle) {
+    return handle.kind === 'file';
+}
+/**
+ * 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 function isDirectoryHandle(handle) {
+    return handle.kind === 'directory';
+}
+/**
+ * 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 async function safeShowOpenFilePicker(window, options) {
+    if (supportsFileSystemAccess(window)) {
+        return window.showOpenFilePicker(options);
+    }
+    return 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 async function safeShowSaveFilePicker(window, options) {
+    if (supportsFileSystemAccess(window)) {
+        return window.showSaveFilePicker(options);
+    }
+    return null;
+}
+/**
+ * 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 async function safeShowDirectoryPicker(window, options) {
+    if (supportsFileSystemAccess(window)) {
+        return window.showDirectoryPicker(options);
+    }
+    return null;
+}
+/**
+ * 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 function exportAsJson(data, filename) {
+    const json = JSON.stringify(data, null, 2);
+    const blob = new Blob([json], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}
+/**
+ * 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 async function exportUsingFileSystemAPI(data, suggestedName, description = 'JSON files', window = globalThis.window) {
+    if (!supportsFileSystemAccess(window)) {
+        // Fallback to blob download
+        exportAsJson(data, suggestedName);
+        return false;
+    }
+    try {
+        const fileHandle = await safeShowSaveFilePicker(window, {
+            suggestedName,
+            types: [
+                {
+                    description,
+                    accept: {
+                        'application/json': ['.json']
+                    }
+                }
+            ]
+        });
+        if (!fileHandle) {
+            // User cancelled - fallback to blob download
+            exportAsJson(data, suggestedName);
+            return false;
+        }
+        const json = JSON.stringify(data, null, 2);
+        const writable = await fileHandle.createWritable();
+        await writable.write(json);
+        await writable.close();
+        return true;
+    }
+    catch (error) {
+        // Handle errors by falling back to blob download
+        if (error.name === 'AbortError') {
+            // User cancelled - fallback
+            exportAsJson(data, suggestedName);
+            return false;
+        }
+        // Other errors - re-throw as they indicate a real problem
+        throw error;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/packlets/file-api-types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/file-api-types/index.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * File System Access API type definitions and utilities for browser compatibility.\n * @packageDocumentation\n */\n\n// Local type definitions for File System Access API\n// Based on https://wicg.github.io/file-system-access/\n\n/**\n * File System Access API methods available on Window\n * @public\n */\nexport interface IFsAccessApis {\n  showDirectoryPicker(options?: ShowDirectoryPickerOptions): Promise<FileSystemDirectoryHandle>;\n  showOpenFilePicker(options?: ShowOpenFilePickerOptions): Promise<FileSystemFileHandle[]>;\n  showSaveFilePicker(options?: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle>;\n}\n\n/**\n * Window interface extended with File System Access API\n * @public\n */\nexport type WindowWithFsAccess = Window & IFsAccessApis;\n\n/**\n * Base interface for file system handles\n * @public\n */\nexport interface FileSystemHandle {\n  readonly kind: 'file' | 'directory';\n  readonly name: string;\n  isSameEntry(other: FileSystemHandle): Promise<boolean>;\n  queryPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;\n  requestPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;\n}\n\n/**\n * File handle interface\n * @public\n */\nexport interface FileSystemFileHandle extends FileSystemHandle {\n  readonly kind: 'file';\n  getFile(): Promise<File>;\n  createWritable(options?: FileSystemCreateWritableOptions): Promise<FileSystemWritableFileStream>;\n}\n\n/**\n * Directory handle interface\n * @public\n */\nexport interface FileSystemDirectoryHandle extends FileSystemHandle {\n  readonly kind: 'directory';\n  getDirectoryHandle(\n    name: string,\n    options?: FileSystemGetDirectoryOptions\n  ): Promise<FileSystemDirectoryHandle>;\n  getFileHandle(name: string, options?: FileSystemGetFileOptions): Promise<FileSystemFileHandle>;\n  removeEntry(name: string, options?: FileSystemRemoveOptions): Promise<void>;\n  resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;\n  keys(): AsyncIterableIterator<string>;\n  values(): AsyncIterableIterator<FileSystemHandle>;\n  entries(): AsyncIterableIterator<[string, FileSystemHandle]>;\n  [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;\n}\n\n/**\n * Permission descriptor for file system handles\n * @public\n */\nexport interface FileSystemHandlePermissionDescriptor {\n  mode?: 'read' | 'readwrite';\n}\n\n/**\n * Options for creating writable file streams\n * @public\n */\nexport interface FileSystemCreateWritableOptions {\n  keepExistingData?: boolean;\n}\n\n/**\n * Options for getting directory handles\n * @public\n */\nexport interface FileSystemGetDirectoryOptions {\n  create?: boolean;\n}\n\n/**\n * Options for getting file handles\n * @public\n */\nexport interface FileSystemGetFileOptions {\n  create?: boolean;\n}\n\n/**\n * Options for removing entries\n * @public\n */\nexport interface FileSystemRemoveOptions {\n  recursive?: boolean;\n}\n\n/**\n * Writable file stream interface\n * @public\n */\nexport interface FileSystemWritableFileStream extends WritableStream {\n  write(data: BufferSource | Blob | string): Promise<void>;\n  seek(position: number): Promise<void>;\n  truncate(size: number): Promise<void>;\n}\n\n/**\n * Directory picker options\n * @public\n */\nexport interface ShowDirectoryPickerOptions {\n  id?: string;\n  mode?: 'read' | 'readwrite';\n  startIn?: FileSystemHandle | WellKnownDirectory;\n}\n\n/**\n * File picker options\n * @public\n */\nexport interface ShowOpenFilePickerOptions {\n  multiple?: boolean;\n  excludeAcceptAllOption?: boolean;\n  id?: string;\n  startIn?: FileSystemHandle | WellKnownDirectory;\n  types?: FilePickerAcceptType[];\n}\n\n/**\n * Save file picker options\n * @public\n */\nexport interface ShowSaveFilePickerOptions {\n  excludeAcceptAllOption?: boolean;\n  id?: string;\n  startIn?: FileSystemHandle | WellKnownDirectory;\n  suggestedName?: string;\n  types?: FilePickerAcceptType[];\n}\n\n/**\n * File picker accept type\n * @public\n */\nexport interface FilePickerAcceptType {\n  description?: string;\n  accept: Record<string, string | string[]>;\n}\n\n/**\n * Well-known directory type\n * @public\n */\nexport type WellKnownDirectory = 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos';\n\n/**\n * Type guard to check if the browser supports the File System Access API\n * @param window - The window object to check\n * @returns True if the window supports File System Access API\n * @public\n */\nexport function supportsFileSystemAccess(window: Window): window is WindowWithFsAccess {\n  return 'showOpenFilePicker' in window && 'showSaveFilePicker' in window && 'showDirectoryPicker' in window;\n}\n\n/**\n * Type guard to check if a FileSystemHandle is a file handle\n * @param handle - The handle to check\n * @returns True if the handle is a FileSystemFileHandle\n * @public\n */\nexport function isFileHandle(handle: FileSystemHandle): handle is FileSystemFileHandle {\n  return handle.kind === 'file';\n}\n\n/**\n * Type guard to check if a FileSystemHandle is a directory handle\n * @param handle - The handle to check\n * @returns True if the handle is a FileSystemDirectoryHandle\n * @public\n */\nexport function isDirectoryHandle(handle: FileSystemHandle): handle is FileSystemDirectoryHandle {\n  return handle.kind === 'directory';\n}\n\n/**\n * Safely access showOpenFilePicker with proper type checking\n * @param window - The window object\n * @param options - Options for the file picker\n * @returns Promise with file handles or null if not supported\n * @public\n */\nexport async function safeShowOpenFilePicker(\n  window: Window,\n  options?: ShowOpenFilePickerOptions\n): Promise<FileSystemFileHandle[] | null> {\n  if (supportsFileSystemAccess(window)) {\n    return window.showOpenFilePicker(options);\n  }\n  return null;\n}\n\n/**\n * Safely access showSaveFilePicker with proper type checking\n * @param window - The window object\n * @param options - Options for the file picker\n * @returns Promise with file handle or null if not supported\n * @public\n */\nexport async function safeShowSaveFilePicker(\n  window: Window,\n  options?: ShowSaveFilePickerOptions\n): Promise<FileSystemFileHandle | null> {\n  if (supportsFileSystemAccess(window)) {\n    return window.showSaveFilePicker(options);\n  }\n  return null;\n}\n\n/**\n * Safely access showDirectoryPicker with proper type checking\n * @param window - The window object\n * @param options - Options for the directory picker\n * @returns Promise with directory handle or null if not supported\n * @public\n */\nexport async function safeShowDirectoryPicker(\n  window: Window,\n  options?: ShowDirectoryPickerOptions\n): Promise<FileSystemDirectoryHandle | null> {\n  if (supportsFileSystemAccess(window)) {\n    return window.showDirectoryPicker(options);\n  }\n  return null;\n}\n\n/**\n * Export data as JSON file using legacy blob download method.\n * Creates a temporary download link and triggers file download.\n * @param data - Data to export as JSON\n * @param filename - Name for the downloaded file\n * @public\n */\nexport function exportAsJson(data: unknown, filename: string): void {\n  const json = JSON.stringify(data, null, 2);\n  const blob = new Blob([json], { type: 'application/json' });\n  const url = URL.createObjectURL(blob);\n\n  const a = document.createElement('a');\n  a.href = url;\n  a.download = filename;\n  document.body.appendChild(a);\n  a.click();\n  document.body.removeChild(a);\n  URL.revokeObjectURL(url);\n}\n\n/**\n * Export data using File System Access API with fallback to blob download.\n * @param data - Data to export as JSON\n * @param suggestedName - Suggested filename for the save dialog\n * @param description - Description for file type filter (default: 'JSON files')\n * @param window - Window object for API access (default: globalThis.window)\n * @returns Promise resolving to true if saved via File System Access API, false if fallback used\n * @public\n */\nexport async function exportUsingFileSystemAPI(\n  data: unknown,\n  suggestedName: string,\n  description: string = 'JSON files',\n  window: Window = globalThis.window\n): Promise<boolean> {\n  if (!supportsFileSystemAccess(window)) {\n    // Fallback to blob download\n    exportAsJson(data, suggestedName);\n    return false;\n  }\n\n  try {\n    const fileHandle = await safeShowSaveFilePicker(window, {\n      suggestedName,\n      types: [\n        {\n          description,\n          accept: {\n            'application/json': ['.json']\n          }\n        }\n      ]\n    });\n\n    if (!fileHandle) {\n      // User cancelled - fallback to blob download\n      exportAsJson(data, suggestedName);\n      return false;\n    }\n\n    const json = JSON.stringify(data, null, 2);\n    const writable = await fileHandle.createWritable();\n    await writable.write(json);\n    await writable.close();\n\n    return true;\n  } catch (error) {\n    // Handle errors by falling back to blob download\n    if ((error as Error).name === 'AbortError') {\n      // User cancelled - fallback\n      exportAsJson(data, suggestedName);\n      return false;\n    }\n    // Other errors - re-throw as they indicate a real problem\n    throw error;\n  }\n}\n"]}