@bendyline/docblocks 2.0.0 → 2.1.0

package/src/filesystem/indexeddb-provider.ts

@@ -1,171 +0,0 @@
-/**
- * Legacy FileSystemProvider facade over the revisioned IndexedDB authority.
- *
- * The old `fs:*` namespace is migration input only. Keeping this facade as an
- * adapter prevents current callers from recreating a second persistent source
- * of truth while the workspace moves to FileSystemProviderV2.
- */
-
-import type { FileCommitResult, FileMeta, FileSystemEntry, FileSystemProvider } from './types.js';
-import { FsError, type FsOperation } from './fs-error.js';
-import { parseWorkspacePath, type WorkspacePath } from './workspace-path.js';
-import { RawIndexedDBFileSystemStore, type IndexedDBFileSystemStore } from './indexeddb-store.js';
-import { IndexedDBFileSystemProviderV2 } from './indexeddb-provider-v2.js';
-
-export interface IndexedDBFileSystemProviderOptions {
-  /** Injectable transaction store for deterministic fault/concurrency tests. */
-  store?: IndexedDBFileSystemStore;
-  /** Injectable metadata clock. */
-  now?: () => Date;
-}
-
-export class IndexedDBFileSystemProvider implements FileSystemProvider {
-  public readonly id: string;
-  public readonly label: string;
-  public readonly v2: IndexedDBFileSystemProviderV2;
-
-  private disposed = false;
-
-  public constructor(id: string, label: string, options: IndexedDBFileSystemProviderOptions = {}) {
-    this.id = id;
-    this.label = label;
-    const store = options.store ?? new RawIndexedDBFileSystemStore(`docblocks-fs-${id}`, 'files');
-    this.v2 = new IndexedDBFileSystemProviderV2(id, label, {
-      store,
-      now: options.now,
-      closeStoreOnDispose: true,
-    });
-  }
-
-  /** Release the underlying database connection after accepted work settles. */
-  public dispose(): Promise<void> {
-    this.disposed = true;
-    return this.v2.dispose();
-  }
-
-  public async readFile(path: string): Promise<string | null> {
-    this.assertOpen('read');
-    const read = await this.v2.readFile(this.path(path, false, 'read'));
-    return read ? new TextDecoder().decode(read.data) : null;
-  }
-
-  public async writeFile(path: string, content: string): Promise<void> {
-    this.assertOpen('write');
-    await this.v2.writeFile(this.path(path, false, 'write'), new TextEncoder().encode(content), {
-      createParents: true,
-    });
-  }
-
-  public async commitFile(
-    path: string,
-    content: string,
-    expectedContent: string | null,
-  ): Promise<FileCommitResult> {
-    this.assertOpen('write');
-    const canonical = this.path(path, false, 'write');
-    const current = await this.v2.readFile(canonical);
-    const currentContent = current ? new TextDecoder().decode(current.data) : null;
-    if (currentContent !== expectedContent && currentContent !== content) {
-      return {
-        status: 'conflict',
-        content: currentContent,
-        version: current?.entry.version ?? null,
-      };
-    }
-
-    try {
-      const committed = await this.v2.writeFile(canonical, new TextEncoder().encode(content), {
-        createParents: true,
-        expectedVersion: current?.entry.version ?? null,
-      });
-      return { status: 'committed', version: committed.version };
-    } catch (error: unknown) {
-      if (!(error instanceof FsError) || error.code !== 'conflict') throw error;
-      const latest = await this.v2.readFile(canonical);
-      return {
-        status: 'conflict',
-        content: latest ? new TextDecoder().decode(latest.data) : null,
-        version: latest?.entry.version ?? null,
-      };
-    }
-  }
-
-  public async delete(path: string): Promise<void> {
-    this.assertOpen('remove');
-    await this.v2.remove(this.path(path, false, 'remove'), {
-      recursive: true,
-      missing: 'ignore',
-    });
-  }
-
-  public async rename(oldPath: string, newPath: string): Promise<void> {
-    this.assertOpen('move');
-    await this.v2.move(this.path(oldPath, false, 'move'), this.path(newPath, false, 'move'), {
-      createParents: true,
-    });
-  }
-
-  public async readDirectory(path: string): Promise<FileSystemEntry[]> {
-    this.assertOpen('list');
-    try {
-      const entries = await this.v2.readDirectory(this.path(path, true, 'list'));
-      return entries.map((entry) => ({
-        kind: entry.kind,
-        name: entry.name,
-        path: entry.path,
-      }));
-    } catch (error: unknown) {
-      if (error instanceof FsError && error.code === 'not-found') return [];
-      throw error;
-    }
-  }
-
-  public async exists(path: string): Promise<boolean> {
-    this.assertOpen('stat');
-    return (await this.v2.stat(this.path(path, true, 'stat'))) !== null;
-  }
-
-  public async createDirectory(path: string): Promise<void> {
-    this.assertOpen('create-directory');
-    await this.v2.createDirectory(this.path(path, false, 'create-directory'), {
-      createParents: true,
-      mode: 'ensure',
-    });
-  }
-
-  public async stat(path: string): Promise<FileMeta | null> {
-    this.assertOpen('stat');
-    const entry = await this.v2.stat(this.path(path, false, 'stat'));
-    if (!entry || entry.kind !== 'file') return null;
-    return {
-      name: entry.name,
-      path: entry.path,
-      size: entry.size,
-      lastModified: entry.lastModified,
-    };
-  }
-
-  public async readBinary(path: string): Promise<ArrayBuffer | null> {
-    this.assertOpen('read');
-    return (await this.v2.readFile(this.path(path, false, 'read')))?.data ?? null;
-  }
-
-  public async writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void> {
-    this.assertOpen('write');
-    await this.v2.writeFile(this.path(path, false, 'write'), data, { createParents: true });
-  }
-
-  private path(path: string, allowRoot: boolean, operation: FsOperation): WorkspacePath {
-    const canonical = parseWorkspacePath(path);
-    if (canonical || allowRoot) return canonical;
-    throw new FsError('invalid-path', 'The filesystem root cannot be used as a mutation target.', {
-      operation,
-      path,
-    });
-  }
-
-  private assertOpen(operation: FsOperation): void {
-    if (!this.disposed) return;
-    throw new FsError('closed', 'The IndexedDB filesystem provider is disposed.', { operation });
-  }
-}

package/src/filesystem/indexeddb-store.ts

@@ -1,207 +0,0 @@
-/**
- * Minimal, error-propagating IndexedDB store used by the virtual filesystem.
- *
- * The previous Squisq LocalForage adapter intentionally converted failed
- * reads/enumerations/removals into null/empty/success. Those semantics are
- * unsuitable for filesystem mutations: an unavailable database must never be
- * interpreted as an absent file. This layer opens the old database and object
- * store directly so existing data can be migrated in one transaction.
- */
-
-export type IndexedDBFileSystemTransactionMode = 'readonly' | 'readwrite';
-
-export interface IndexedDBFileSystemTransaction {
-  get<T>(key: string): Promise<T | null>;
-  put<T>(key: string, value: T): Promise<void>;
-  delete(key: string): Promise<void>;
-  keys(): Promise<string[]>;
-  /** O(log n) namespace probe in the concrete IndexedDB implementation. */
-  hasKeyWithPrefix(prefix: string): Promise<boolean>;
-}
-
-export interface IndexedDBFileSystemStore {
-  transaction<T>(
-    mode: IndexedDBFileSystemTransactionMode,
-    operation: (transaction: IndexedDBFileSystemTransaction) => Promise<T>,
-  ): Promise<T>;
-  close?(): void;
-}
-
-export class RawIndexedDBFileSystemStore implements IndexedDBFileSystemStore {
-  private database: IDBDatabase | null = null;
-  private opening: Promise<IDBDatabase> | null = null;
-  private closed = false;
-
-  public constructor(
-    private readonly databaseName: string,
-    private readonly storeName: string,
-  ) {}
-
-  public async transaction<T>(
-    mode: IndexedDBFileSystemTransactionMode,
-    operation: (transaction: IndexedDBFileSystemTransaction) => Promise<T>,
-  ): Promise<T> {
-    const database = await this.getDatabase();
-    const nativeTransaction = database.transaction(this.storeName, mode);
-    const completion = waitForTransaction(nativeTransaction);
-    const transaction = new RawIndexedDBFileSystemTransaction(
-      nativeTransaction.objectStore(this.storeName),
-    );
-
-    let result: T;
-    try {
-      result = await operation(transaction);
-    } catch (error: unknown) {
-      try {
-        nativeTransaction.abort();
-      } catch {
-        // The request failure may already have aborted the transaction.
-      }
-      await completion.catch(() => undefined);
-      throw error;
-    }
-
-    await completion;
-    return result;
-  }
-
-  public close(): void {
-    if (this.closed) return;
-    this.closed = true;
-    this.database?.close();
-    this.database = null;
-    this.opening = null;
-  }
-
-  private getDatabase(): Promise<IDBDatabase> {
-    if (this.closed) {
-      return Promise.reject(new Error('The IndexedDB filesystem store is closed.'));
-    }
-    if (this.database) return Promise.resolve(this.database);
-    if (this.opening) return this.opening;
-    if (typeof indexedDB === 'undefined') {
-      return Promise.reject(new Error('IndexedDB is not available in this environment.'));
-    }
-
-    this.opening = openDatabaseWithStore(this.databaseName, this.storeName)
-      .then((database) => {
-        if (this.closed) {
-          database.close();
-          throw new Error('The IndexedDB filesystem store is closed.');
-        }
-        this.database = database;
-        this.opening = null;
-        database.onversionchange = () => {
-          database.close();
-          if (this.database === database) this.database = null;
-        };
-        return database;
-      })
-      .catch((error: unknown) => {
-        this.opening = null;
-        throw error;
-      });
-    return this.opening;
-  }
-}
-
-class RawIndexedDBFileSystemTransaction implements IndexedDBFileSystemTransaction {
-  public constructor(private readonly store: IDBObjectStore) {}
-
-  public async get<T>(key: string): Promise<T | null> {
-    const value = await requestResult(this.store.get(key));
-    return value === undefined ? null : (value as T);
-  }
-
-  public async put<T>(key: string, value: T): Promise<void> {
-    await requestResult(this.store.put(value, key));
-  }
-
-  public async delete(key: string): Promise<void> {
-    await requestResult(this.store.delete(key));
-  }
-
-  public async keys(): Promise<string[]> {
-    const keys = await requestResult(this.store.getAllKeys());
-    return keys.map((key) => {
-      if (typeof key !== 'string') {
-        throw new Error('The DocBlocks filesystem store contains a non-string key.');
-      }
-      return key;
-    });
-  }
-
-  public async hasKeyWithPrefix(prefix: string): Promise<boolean> {
-    const cursor = await requestResult(this.store.openKeyCursor(IDBKeyRange.lowerBound(prefix)));
-    return cursor !== null && typeof cursor.key === 'string' && cursor.key.startsWith(prefix);
-  }
-}
-
-async function openDatabaseWithStore(
-  databaseName: string,
-  storeName: string,
-): Promise<IDBDatabase> {
-  const database = await openDatabase(databaseName, undefined, (upgradeDatabase) => {
-    if (!upgradeDatabase.objectStoreNames.contains(storeName)) {
-      upgradeDatabase.createObjectStore(storeName);
-    }
-  });
-  if (database.objectStoreNames.contains(storeName)) return database;
-
-  const nextVersion = database.version + 1;
-  database.close();
-  return openDatabase(databaseName, nextVersion, (upgradeDatabase) => {
-    if (!upgradeDatabase.objectStoreNames.contains(storeName)) {
-      upgradeDatabase.createObjectStore(storeName);
-    }
-  });
-}
-
-function openDatabase(
-  databaseName: string,
-  version: number | undefined,
-  upgrade: (database: IDBDatabase) => void,
-): Promise<IDBDatabase> {
-  return new Promise((resolve, reject) => {
-    const request =
-      version === undefined ? indexedDB.open(databaseName) : indexedDB.open(databaseName, version);
-    let settled = false;
-
-    request.onupgradeneeded = () => upgrade(request.result);
-    request.onsuccess = () => {
-      if (settled) {
-        request.result.close();
-        return;
-      }
-      settled = true;
-      resolve(request.result);
-    };
-    request.onerror = () => {
-      if (settled) return;
-      settled = true;
-      reject(request.error ?? new Error(`Could not open IndexedDB database ${databaseName}.`));
-    };
-    request.onblocked = () => {
-      if (settled) return;
-      settled = true;
-      reject(new Error(`IndexedDB database ${databaseName} is blocked by another open page.`));
-    };
-  });
-}
-
-function requestResult<T>(request: IDBRequest<T>): Promise<T> {
-  return new Promise((resolve, reject) => {
-    request.onsuccess = () => resolve(request.result);
-    request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed.'));
-  });
-}
-
-function waitForTransaction(transaction: IDBTransaction): Promise<void> {
-  return new Promise((resolve, reject) => {
-    transaction.oncomplete = () => resolve();
-    transaction.onabort = () =>
-      reject(transaction.error ?? new Error('IndexedDB transaction was aborted.'));
-    transaction.onerror = () =>
-      reject(transaction.error ?? new Error('IndexedDB transaction failed.'));
-  });
-}

package/src/filesystem/indexeddb.ts

@@ -1,12 +0,0 @@
-/** Browser-local persistent filesystem provider entry point. */
-export { IndexedDBFileSystemProvider } from './indexeddb-provider.js';
-export {
-  IndexedDBFileSystemProviderV2,
-  type IndexedDBFileSystemProviderV2Options,
-  type IndexedDBLegacyConflictReason,
-  type IndexedDBLegacyConflictResolution,
-  type IndexedDBLegacyMigrationConflict,
-  type IndexedDBLegacyRecoveryCandidate,
-  type IndexedDBLegacyRecoveryKind,
-} from './indexeddb-provider-v2.js';
-export { IndexedDBContentContainer } from './indexeddb-content-container.js';