[opfs] Move into browser module

Author: jamesgpearce

gulpfile.mjs

@@ -31,7 +31,6 @@ const ALL_MODULES = [
   'persisters/persister-file',
   'persisters/persister-indexed-db',
   'persisters/persister-libsql',
-  'persisters/persister-opfs',
   'persisters/persister-partykit-client',
   'persisters/persister-partykit-server',
   'persisters/persister-pglite',

site/build.ts

@@ -247,7 +247,6 @@ const addApi = (docs: Docs): Docs =>
     .addApiFile('dist/@types/persisters/persister-file/index.d.ts')
     .addApiFile('dist/@types/persisters/persister-indexed-db/index.d.ts')
     .addApiFile('dist/@types/persisters/persister-libsql/index.d.ts')
-    .addApiFile('dist/@types/persisters/persister-opfs/index.d.ts')
     .addApiFile('dist/@types/persisters/persister-partykit-client/index.d.ts')
     .addApiFile('dist/@types/persisters/persister-partykit-server/index.d.ts')
     .addApiFile('dist/@types/persisters/persister-pglite/index.d.ts')

src/@types/persisters/persister-browser/docs.js

@@ -1,14 +1,17 @@
 /**
  * The persister-browser module of the TinyBase project lets you save and load
- * Store data to and from browser storage.
+ * Store data to and from browser storage, including the origin private file
+ * system (OPFS).
  *
- * Two entry points are provided, each of which returns a new Persister object
+ * Three entry points are provided, each of which returns a new Persister object
  * that can load and save a Store:
  *
  * - The createSessionPersister function returns a Persister that uses the
  *   browser's session storage.
  * - The createLocalPersister function returns a Persister that uses the
  *   browser's local storage.
+ * - The createOpfsPersister function returns a Persister that uses a file in
+ *   an origin private file system (OPFS).
  * @see Persistence guides
  * @packageDocumentation
  * @module persister-browser
@@ -95,6 +98,49 @@
    */
   /// LocalPersister.getStorageName
 }
+/**
+ * The OpfsPersister interface represents a Persister that lets you save and
+ * load Store data to and from a file in an origin private file system (OPFS).
+ *
+ * You should use the createOpfsPersister function to create an OpfsPersister
+ * object.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getHandle method for accessing the file the Store is being
+ * persisted to.
+ * @category Persister
+ * @since v6.7.0
+ */
+/// OpfsPersister
+{
+  /**
+   * The getHandle method returns the handle of the file the Store is being
+   * persisted to.
+   * @returns The handle of the file.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the file handle back out again.
+   *
+   * ```js
+   * import {createStore} from 'tinybase';
+   * import {createOpfsPersister} from 'tinybase/persisters/persister-browser';
+   *
+   * const opfs = await navigator.storage.getDirectory();
+   * const handle = await opfs.getFileHandle('tinybase.json', {create: true});
+   *
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createOpfsPersister(store, handle);
+   *
+   * console.log(persister.getHandle().name);
+   * // -> 'tinybase.json'
+   *
+   * await persister.destroy();
+   * ```
+   * @category Getter
+   * @since v6.7.0
+   */
+  /// OpfsPersister.getHandle
+}
 /**
  * The createSessionPersister function creates a SessionPersister object that
  * can persist the Store to the browser's session storage.
@@ -171,3 +217,43 @@
  * @since v1.0.0
  */
 /// createLocalPersister
+/**
+ * The createOpfsPersister function creates an OpfsPersister object that can
+ * persist the Store to a file in an origin private file system (OPFS).
+ *
+ * An OpfsPersister supports both regular Store and MergeableStore objects.
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `handle` parameter which identifies an existing OPFS file to persist it to.
+ * @param store The Store or MergeableStore to persist.
+ * @param handle The handle of an existing OPFS file to persist the Store to.
+ * @param onIgnoredError An optional handler for the errors that the Persister
+ * would otherwise ignore when trying to save or load data. This is suitable for
+ * debugging persistence issues in a development environment.
+ * @returns A reference to the new OpfsPersister object.
+ * @example
+ * This example creates an OpfsPersister object and persists the Store to a
+ * local file.
+ *
+ * ```js
+ * import {createStore} from 'tinybase';
+ * import {createOpfsPersister} from 'tinybase/persisters/persister-browser';
+ *
+ * const opfs = await navigator.storage.getDirectory();
+ * const handle = await opfs.getFileHandle('tinybase.json', {create: true});
+ *
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createOpfsPersister(store, handle);
+ *
+ * await persister.save();
+ * // Store JSON will be saved to the file.
+ *
+ * await persister.load();
+ * // Store JSON will be loaded from the file.
+ *
+ * await persister.destroy();
+ * ```
+ * @category Creation
+ * @since v6.7.0
+ */
+/// createOpfsPersister

src/@types/persisters/persister-browser/index.d.ts

@@ -30,3 +30,17 @@ export function createLocalPersister(
   storageName: string,
   onIgnoredError?: (error: any) => void,
 ): LocalPersister;
+
+/// OpfsPersister
+export interface OpfsPersister
+  extends Persister<Persists.StoreOrMergeableStore> {
+  /// OpfsPersister.getHandle
+  getHandle(): FileSystemFileHandle;
+}
+
+/// createOpfsPersister
+export function createOpfsPersister(
+  store: Store | MergeableStore,
+  handle: FileSystemFileHandle,
+  onIgnoredError?: (error: any) => void,
+): OpfsPersister;

src/@types/persisters/persister-browser/with-schemas/index.d.ts

@@ -20,6 +20,13 @@ export interface LocalPersister<Schemas extends OptionalSchemas>
   getStorageName(): string;
 }
 
+/// OpfsPersister
+export interface OpfsPersister<Schemas extends OptionalSchemas>
+  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+  /// OpfsPersister.getHandle
+  getHandle(): string;
+}
+
 /// createSessionPersister
 export function createSessionPersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas> | MergeableStore<Schemas>,
@@ -33,3 +40,10 @@ export function createLocalPersister<Schemas extends OptionalSchemas>(
   storageName: string,
   onIgnoredError?: (error: any) => void,
 ): LocalPersister<Schemas>;
+
+/// createOpfsPersister
+export function createOpfsPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas> | MergeableStore<Schemas>,
+  handle: FileSystemFileHandle,
+  onIgnoredError?: (error: any) => void,
+): OpfsPersister<Schemas>;

src/@types/persisters/persister-opfs/docs.js

@@ -7,8 +7,10 @@ import type {
 } from '../../@types/persisters/index.d.ts';
 import type {
   createLocalPersister as createLocalPersisterDecl,
+  createOpfsPersister as createOpfsPersisterDecl,
   createSessionPersister as createSessionPersisterDecl,
   LocalPersister,
+  OpfsPersister,
   SessionPersister,
 } from '../../@types/persisters/persister-browser/index.d.ts';
 import type {Store} from '../../@types/store/index.d.ts';
@@ -20,6 +22,11 @@ import {tryCatch, WINDOW} from '../../common/other.ts';
 import {createCustomPersister} from '../common/create.ts';
 
 type StorageListener = (event: StorageEvent) => void;
+type FileSystemObserver = {
+  observe: (handle: FileSystemFileHandle) => Promise<void>;
+  disconnect: () => void;
+};
+
 const STORAGE = 'storage';
 
 const createStoragePersister = (
@@ -90,3 +97,44 @@ export const createSessionPersister = ((
     sessionStorage,
     onIgnoredError,
   ) as SessionPersister) as typeof createSessionPersisterDecl;
+
+export const createOpfsPersister = ((
+  store: Store | MergeableStore,
+  handle: FileSystemFileHandle,
+  onIgnoredError?: (error: any) => void,
+): OpfsPersister => {
+  const getPersisted = async (): Promise<
+    PersistedContent<PersistsType.StoreOrMergeableStore>
+  > => jsonParseWithUndefined(await (await handle.getFile()).text());
+
+  const setPersisted = async (
+    getContent: () => PersistedContent<PersistsType.StoreOrMergeableStore>,
+  ): Promise<void> => {
+    const writable = await handle.createWritable();
+    await writable.write(jsonStringWithUndefined(getContent()));
+    await writable.close();
+  };
+
+  const addPersisterListener = async (
+    listener: PersisterListener<PersistsType.StoreOrMergeableStore>,
+  ): Promise<FileSystemObserver> => {
+    // @ts-expect-error FileSystemObserver is not yet typed
+    const observer = new FileSystemObserver(() => listener());
+    await observer.observe(handle);
+    return observer;
+  };
+
+  const delPersisterListener = (observer: FileSystemObserver) =>
+    observer?.disconnect();
+
+  return createCustomPersister(
+    store,
+    getPersisted,
+    setPersisted,
+    addPersisterListener,
+    delPersisterListener,
+    onIgnoredError,
+    3, // StoreOrMergeableStore,
+    {getHandle: () => handle},
+  ) as OpfsPersister;
+}) as typeof createOpfsPersisterDecl;