@fgv/ts-web-extras 5.0.2 → 5.1.0-0

package/rush-logs/ts-web-extras.build.log

@@ -2,41 +2,51 @@ Invoking: heft test --clean
  ---- build started ---- 
 [build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
 [build:typescript] Using TypeScript version 5.9.3
-[build:api-extractor] Using API Extractor version 7.54.0
+[build:api-extractor] Using API Extractor version 7.57.6
 [build:api-extractor] Analysis will use the bundled TypeScript version 5.8.2
 [build:api-extractor] *** The target project appears to use TypeScript 5.9.3 which is newer than the bundled compiler engine; consider upgrading API Extractor.
- ---- build finished (22.824s) ---- 
+ ---- build finished (18.627s) ---- 
  ---- test started ---- 
 [test:jest] Using Jest version 29.5.0
 [test:jest] 
-[test:jest] Run start. 5 test suites
+[test:jest] Run start. 8 test suites
 [test:jest] START lib/test/unit/fileApiTreeAccessors.test.js
 [test:jest] START lib/test/unit/fileTreeHelpers.test.js
+[test:jest] START lib/test/unit/fileSystemAccessTreeAccessors.test.js
+[test:jest] START lib/test/unit/localStorageTreeAccessors.test.js
+[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 2.344s, 63 passed, 0 failed)
 [test:jest] START lib/test/unit/fileApiTypes.test.js
+[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 2.029s, 35 passed, 0 failed)
 [test:jest] START lib/test/unit/urlParams.test.js
-[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 2.655s, 35 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 2.580s, 38 passed, 0 failed)
+[test:jest] START lib/test/unit/directoryHandleStore.test.js
+[test:jest] PASS lib/test/unit/localStorageTreeAccessors.test.js (duration: 1.053s, 33 passed, 0 failed)
 [test:jest] START lib/test/unit/browserHashProvider.test.js
-[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 2.813s, 33 passed, 0 failed)
-[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 2.987s, 63 passed, 0 failed)
-[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 1.119s, 60 passed, 0 failed)
-[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.312s, 15 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 1.302s, 36 passed, 0 failed)
+[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 1.269s, 60 passed, 0 failed)
+[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 1.234s, 19 passed, 0 failed)
+[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.305s, 15 passed, 0 failed)
 [test:jest] 
 [test:jest] Tests finished:
-[test:jest]   Successes: 206
+[test:jest]   Successes: 299
 [test:jest]   Failures: 0
-[test:jest]   Total: 207
---------------------------|---------|----------|---------|---------|-------------------
-File                      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
---------------------------|---------|----------|---------|---------|-------------------
-All files                 |     100 |      100 |     100 |     100 |                   
- crypto                   |     100 |      100 |     100 |     100 |                   
-  browserHashProvider.ts  |     100 |      100 |     100 |     100 |                   
- file-tree                |     100 |      100 |     100 |     100 |                   
-  fileApiTreeAccessors.ts |     100 |      100 |     100 |     100 |                   
- helpers                  |     100 |      100 |     100 |     100 |                   
-  fileTreeHelpers.ts      |     100 |      100 |     100 |     100 |                   
- url-utils                |     100 |      100 |     100 |     100 |                   
-  urlParams.ts            |     100 |      100 |     100 |     100 |                   
---------------------------|---------|----------|---------|---------|-------------------
- ---- test finished (7.278s) ---- 
--------------------- Finished (30.108s) --------------------
+[test:jest]   Total: 300
+-----------------------------------|---------|----------|---------|---------|------------------------------------
+File                               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s                  
+-----------------------------------|---------|----------|---------|---------|------------------------------------
+All files                          |     100 |    95.68 |     100 |     100 |                                    
+ crypto-utils                      |     100 |      100 |     100 |     100 |                                    
+  browserCryptoProvider.ts         |     100 |      100 |     100 |     100 |                                    
+  browserHashProvider.ts           |     100 |      100 |     100 |     100 |                                    
+ file-tree                         |     100 |     94.9 |     100 |     100 |                                    
+  directoryHandleStore.ts          |     100 |      100 |     100 |     100 |                                    
+  fileApiTreeAccessors.ts          |     100 |      100 |     100 |     100 |                                    
+  fileSystemAccessTreeAccessors.ts |     100 |    93.06 |     100 |     100 | 90,152,160,169,176                 
+  localStorageTreeAccessors.ts     |     100 |     88.6 |     100 |     100 | 92,107,163-164,196-197,210,245-249 
+ helpers                           |     100 |      100 |     100 |     100 |                                    
+  fileTreeHelpers.ts               |     100 |      100 |     100 |     100 |                                    
+ url-utils                         |     100 |      100 |     100 |     100 |                                    
+  urlParams.ts                     |     100 |      100 |     100 |     100 |                                    
+-----------------------------------|---------|----------|---------|---------|------------------------------------
+ ---- test finished (7.440s) ---- 
+-------------------- Finished (26.073s) --------------------

package/src/index.ts

@@ -31,8 +31,8 @@
  * @packageDocumentation
  */
 
-// Export crypto functionality
-export * from './packlets/crypto';
+import * as CryptoUtils from './packlets/crypto-utils';
+export { CryptoUtils };
 
 // Export file tree functionality
 export * from './packlets/file-tree';

package/src/packlets/crypto-utils/browserCryptoProvider.ts

@@ -0,0 +1,311 @@
+// Copyright (c) 2024 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.
+
+/* c8 ignore start - Browser-only implementation cannot be tested in Node.js environment */
+import { captureResult, Failure, Result, Success } from '@fgv/ts-utils';
+import { CryptoUtils } from '@fgv/ts-extras';
+
+type ICryptoProvider = CryptoUtils.ICryptoProvider;
+type IEncryptionResult = CryptoUtils.IEncryptionResult;
+const CryptoConstants = CryptoUtils.Constants;
+
+/**
+ * Extracts an `ArrayBuffer` from a Uint8Array, handling the potential SharedArrayBuffer case.
+ * @param arr - The Uint8Array to extract from
+ * @returns An `ArrayBuffer` containing a copy of the data.
+ */
+function toArrayBuffer(arr: Uint8Array): ArrayBuffer {
+  // Create a new ArrayBuffer and copy the data - this handles both ArrayBuffer and SharedArrayBuffer
+  const buffer = new ArrayBuffer(arr.byteLength);
+  new Uint8Array(buffer).set(arr);
+  return buffer;
+}
+
+/**
+ * Browser implementation of `ICryptoProvider` using the Web Crypto API.
+ * Uses AES-256-GCM for authenticated encryption.
+ *
+ * Note: This provider requires a browser environment with Web Crypto API support.
+ * In Node.js 15+, Web Crypto is available via globalThis.crypto or require('crypto').webcrypto.
+ *
+ * @public
+ */
+export class BrowserCryptoProvider implements ICryptoProvider {
+  private readonly _crypto: Crypto;
+
+  /**
+   * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.
+   * @param cryptoApi - Optional Crypto instance (defaults to globalThis.crypto)
+   */
+  public constructor(cryptoApi?: Crypto) {
+    if (cryptoApi) {
+      this._crypto = cryptoApi;
+    } else if (typeof globalThis !== 'undefined' && globalThis.crypto) {
+      this._crypto = globalThis.crypto;
+    } else if (typeof window !== 'undefined' && window.crypto) {
+      this._crypto = window.crypto;
+    } else {
+      throw new Error('Web Crypto API not available');
+    }
+  }
+
+  /**
+   * Encrypts plaintext using AES-256-GCM.
+   * @param plaintext - UTF-8 string to encrypt
+   * @param key - 32-byte encryption key
+   * @returns `Success` with encryption result, or `Failure` with an error.
+   */
+  public async encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>> {
+    if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {
+      return Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+    }
+
+    try {
+      // Generate random IV
+      const iv = this._crypto.getRandomValues(new Uint8Array(CryptoConstants.GCM_IV_SIZE));
+
+      // Import the key
+      const cryptoKey = await this._crypto.subtle.importKey(
+        'raw',
+        toArrayBuffer(key),
+        { name: 'AES-GCM' },
+        false,
+        ['encrypt']
+      );
+
+      // Encode plaintext to bytes
+      const encoder = new TextEncoder();
+      const plaintextBytes = encoder.encode(plaintext);
+
+      // Encrypt (Web Crypto appends auth tag to ciphertext)
+      const encryptedWithTag = await this._crypto.subtle.encrypt(
+        {
+          name: 'AES-GCM',
+          iv: iv,
+          tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+        },
+        cryptoKey,
+        plaintextBytes
+      );
+
+      // Split ciphertext and auth tag (auth tag is last 16 bytes)
+      const encryptedArray = new Uint8Array(encryptedWithTag);
+      const encryptedData = encryptedArray.slice(
+        0,
+        encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE
+      );
+      const authTag = encryptedArray.slice(encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE);
+      return Success.with({
+        iv,
+        authTag,
+        encryptedData
+      });
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return Failure.with(`Encryption failed: ${message}`);
+    }
+  }
+
+  /**
+   * Decrypts ciphertext using AES-256-GCM.
+   * @param encryptedData - Encrypted bytes
+   * @param key - 32-byte decryption key
+   * @param iv - Initialization vector (12 bytes)
+   * @param authTag - GCM authentication tag (16 bytes)
+   * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.
+   */
+  public async decrypt(
+    encryptedData: Uint8Array,
+    key: Uint8Array,
+    iv: Uint8Array,
+    authTag: Uint8Array
+  ): Promise<Result<string>> {
+    if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {
+      return Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+    }
+    if (iv.length !== CryptoConstants.GCM_IV_SIZE) {
+      return Failure.with(`IV must be ${CryptoConstants.GCM_IV_SIZE} bytes, got ${iv.length}`);
+    }
+    if (authTag.length !== CryptoConstants.GCM_AUTH_TAG_SIZE) {
+      return Failure.with(
+        `Auth tag must be ${CryptoConstants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`
+      );
+    }
+
+    try {
+      // Import the key
+      const cryptoKey = await this._crypto.subtle.importKey(
+        'raw',
+        toArrayBuffer(key),
+        { name: 'AES-GCM' },
+        false,
+        ['decrypt']
+      );
+
+      // Web Crypto expects ciphertext + auth tag concatenated
+      const encryptedWithTag = new Uint8Array(encryptedData.length + authTag.length);
+      encryptedWithTag.set(encryptedData);
+      encryptedWithTag.set(authTag, encryptedData.length);
+
+      // Decrypt
+      const decrypted = await this._crypto.subtle.decrypt(
+        {
+          name: 'AES-GCM',
+          iv: toArrayBuffer(iv),
+          tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+        },
+        cryptoKey,
+        encryptedWithTag
+      );
+
+      // Decode to string
+      const decoder = new TextDecoder();
+      return Success.with(decoder.decode(decrypted));
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return Failure.with(`Decryption failed: ${message}`);
+    }
+  }
+
+  /**
+   * Generates a random 32-byte key suitable for AES-256.
+   * @returns Success with generated key, or Failure with error
+   */
+  public async generateKey(): Promise<Result<Uint8Array>> {
+    try {
+      return Success.with(this._crypto.getRandomValues(new Uint8Array(CryptoConstants.AES_256_KEY_SIZE)));
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return Failure.with(`Key generation failed: ${message}`);
+    }
+  }
+
+  /**
+   * Derives a key from a password using PBKDF2.
+   * @param password - Password string
+   * @param salt - Salt bytes (should be at least 16 bytes)
+   * @param iterations - Number of iterations (recommend 100000+)
+   * @returns Success with derived 32-byte key, or Failure with error
+   */
+  public async deriveKey(
+    password: string,
+    salt: Uint8Array,
+    iterations: number
+  ): Promise<Result<Uint8Array>> {
+    if (iterations < 1) {
+      return Failure.with('Iterations must be at least 1');
+    }
+    if (salt.length < 8) {
+      return Failure.with('Salt should be at least 8 bytes');
+    }
+
+    try {
+      // Encode password
+      const encoder = new TextEncoder();
+      const passwordBytes = encoder.encode(password);
+
+      // Import password as key material
+      const keyMaterial = await this._crypto.subtle.importKey('raw', passwordBytes, 'PBKDF2', false, [
+        'deriveBits'
+      ]);
+
+      // Derive key bits
+      const derivedBits = await this._crypto.subtle.deriveBits(
+        {
+          name: 'PBKDF2',
+          salt: toArrayBuffer(salt),
+          iterations: iterations,
+          hash: 'SHA-256'
+        },
+        keyMaterial,
+        CryptoConstants.AES_256_KEY_SIZE * 8 // bits
+      );
+
+      return Success.with(new Uint8Array(derivedBits));
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return Failure.with(`Key derivation failed: ${message}`);
+    }
+  }
+
+  // ============================================================================
+  // Platform Utility Methods
+  // ============================================================================
+
+  /**
+   * Generates cryptographically secure random bytes.
+   * @param length - Number of bytes to generate
+   * @returns Success with random bytes, or Failure with error
+   */
+  public generateRandomBytes(length: number): Result<Uint8Array> {
+    if (length < 1) {
+      return Failure.with('Length must be at least 1');
+    }
+    try {
+      return Success.with(this._crypto.getRandomValues(new Uint8Array(length)));
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return Failure.with(`Random bytes generation failed: ${message}`);
+    }
+  }
+
+  /**
+   * Encodes binary data to base64 string.
+   * @param data - Binary data to encode
+   * @returns Base64-encoded string
+   */
+  public toBase64(data: Uint8Array): string {
+    // Convert Uint8Array to binary string, then to base64
+    let binary = '';
+    for (let i = 0; i < data.length; i++) {
+      binary += String.fromCharCode(data[i]);
+    }
+    return btoa(binary);
+  }
+
+  /**
+   * Decodes base64 string to binary data.
+   * @param base64 - Base64-encoded string
+   * @returns Success with decoded bytes, or Failure if invalid base64
+   */
+  public fromBase64(base64: string): Result<Uint8Array> {
+    try {
+      const binary = atob(base64);
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+      }
+      return Success.with(bytes);
+    } catch (e) {
+      return Failure.with('Invalid base64 string');
+    }
+  }
+}
+
+/**
+ * Creates a {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider} if Web
+ * Crypto API is available.
+ * @returns `Success` with provider, or `Failure` if not available
+ * @public
+ */
+export function createBrowserCryptoProvider(): Result<BrowserCryptoProvider> {
+  return captureResult(() => new BrowserCryptoProvider());
+}
+/* c8 ignore stop */

package/src/packlets/{crypto → crypto-utils}/index.ts

@@ -26,3 +26,4 @@
  */
 
 export * from './browserHashProvider';
+export * from './browserCryptoProvider';

package/src/packlets/file-api-types/index.ts

@@ -226,7 +226,14 @@ export async function safeShowOpenFilePicker(
   options?: ShowOpenFilePickerOptions
 ): Promise<FileSystemFileHandle[] | null> {
   if (supportsFileSystemAccess(window)) {
-    return window.showOpenFilePicker(options);
+    try {
+      return await window.showOpenFilePicker(options);
+    } catch (error) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        return null;
+      }
+      throw error;
+    }
   }
   return null;
 }
@@ -243,7 +250,14 @@ export async function safeShowSaveFilePicker(
   options?: ShowSaveFilePickerOptions
 ): Promise<FileSystemFileHandle | null> {
   if (supportsFileSystemAccess(window)) {
-    return window.showSaveFilePicker(options);
+    try {
+      return await window.showSaveFilePicker(options);
+    } catch (error) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        return null;
+      }
+      throw error;
+    }
   }
   return null;
 }
@@ -260,7 +274,14 @@ export async function safeShowDirectoryPicker(
   options?: ShowDirectoryPickerOptions
 ): Promise<FileSystemDirectoryHandle | null> {
   if (supportsFileSystemAccess(window)) {
-    return window.showDirectoryPicker(options);
+    try {
+      return await window.showDirectoryPicker(options);
+    } catch (error) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        return null;
+      }
+      throw error;
+    }
   }
   return null;
 }

package/src/packlets/file-tree/directoryHandleStore.ts

@@ -0,0 +1,136 @@
+// Copyright (c) 2026 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.
+
+/**
+ * Persistent storage for FileSystemDirectoryHandle objects using IndexedDB.
+ * Allows directory handles to survive page reloads without re-prompting the user.
+ * @packageDocumentation
+ */
+
+import { fail, Result, succeed } from '@fgv/ts-utils';
+import { createStore, del, get, keys, set } from 'idb-keyval';
+import { FileSystemDirectoryHandle } from '../file-api-types';
+
+/**
+ * Default IndexedDB database name for directory handles.
+ * @public
+ */
+export const DEFAULT_DIRECTORY_HANDLE_DB = 'chocolate-lab-storage';
+
+/**
+ * Default IndexedDB store name for directory handles.
+ * @public
+ */
+export const DEFAULT_DIRECTORY_HANDLE_STORE = 'directory-handles';
+
+/**
+ * Manages persistence of {@link FileSystemDirectoryHandle} objects in IndexedDB.
+ * Keyed by a label (typically the directory name).
+ * @public
+ */
+export class DirectoryHandleStore {
+  private readonly _store: ReturnType<typeof createStore>;
+
+  public constructor(
+    dbName: string = DEFAULT_DIRECTORY_HANDLE_DB,
+    storeName: string = DEFAULT_DIRECTORY_HANDLE_STORE
+  ) {
+    this._store = createStore(dbName, storeName);
+  }
+
+  /**
+   * Saves a directory handle to IndexedDB under the given label.
+   * @param label - Key to store the handle under (typically dirHandle.name)
+   * @param handle - The FileSystemDirectoryHandle to persist
+   * @returns Success or Failure
+   */
+  public async save(label: string, handle: FileSystemDirectoryHandle): Promise<Result<void>> {
+    try {
+      await set(label, handle, this._store);
+      return succeed(undefined);
+    } catch (e) {
+      return fail(`DirectoryHandleStore.save "${label}": ${String(e)}`);
+    }
+  }
+
+  /**
+   * Retrieves a directory handle by label.
+   * @param label - Key to look up
+   * @returns Success with handle (or undefined if not found), or Failure on error
+   */
+  public async load(label: string): Promise<Result<FileSystemDirectoryHandle | undefined>> {
+    try {
+      const handle = await get<FileSystemDirectoryHandle>(label, this._store);
+      return succeed(handle);
+    } catch (e) {
+      return fail(`DirectoryHandleStore.load "${label}": ${String(e)}`);
+    }
+  }
+
+  /**
+   * Removes a directory handle from IndexedDB.
+   * @param label - Key to remove
+   * @returns Success or Failure
+   */
+  public async remove(label: string): Promise<Result<void>> {
+    try {
+      await del(label, this._store);
+      return succeed(undefined);
+    } catch (e) {
+      return fail(`DirectoryHandleStore.remove "${label}": ${String(e)}`);
+    }
+  }
+
+  /**
+   * Returns all stored labels (keys).
+   * @returns Success with array of labels, or Failure
+   */
+  public async getAllLabels(): Promise<Result<string[]>> {
+    try {
+      const allKeys = await keys<string>(this._store);
+      return succeed(allKeys);
+    } catch (e) {
+      return fail(`DirectoryHandleStore.getAllLabels: ${String(e)}`);
+    }
+  }
+
+  /**
+   * Returns all stored handles as label/handle pairs.
+   * @returns Success with array of entries, or Failure
+   */
+  public async getAll(): Promise<Result<Array<{ label: string; handle: FileSystemDirectoryHandle }>>> {
+    const labelsResult = await this.getAllLabels();
+    if (labelsResult.isFailure()) {
+      return fail(labelsResult.message);
+    }
+
+    const entries: Array<{ label: string; handle: FileSystemDirectoryHandle }> = [];
+    for (const label of labelsResult.value) {
+      const handleResult = await this.load(label);
+      if (handleResult.isFailure()) {
+        return fail(handleResult.message);
+      }
+      if (handleResult.value !== undefined) {
+        entries.push({ label, handle: handleResult.value });
+      }
+    }
+    return succeed(entries);
+  }
+}