tinybase 6.6.0 → 6.7.0

package/@types/persisters/index.d.ts

@@ -13,6 +13,7 @@
  * |-|-|-|-|
  * |SessionPersister|Browser session storage|Yes|Yes
  * |LocalPersister|Browser local storage|Yes|Yes
+ * |OpfsPersister|Browser origin private file system (OPFS)|Yes|Yes
  * |FilePersister|Local file (where possible)|Yes|Yes
  * |IndexedDbPersister|Browser IndexedDB|Yes|No
  * |RemotePersister|Remote server|Yes|No

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

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

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

@@ -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
@@ -103,6 +106,50 @@ export interface LocalPersister<Schemas extends OptionalSchemas>
   getStorageName(): string;
 }
 
+/**
+ * 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
+ */
+export interface OpfsPersister<Schemas extends OptionalSchemas>
+  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+  /**
+   * 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
+   */
+  getHandle(): string;
+}
+
 /**
  * The createSessionPersister function creates a SessionPersister object that
  * can persist the Store to the browser's session storage.
@@ -208,3 +255,58 @@ export function createLocalPersister<Schemas extends OptionalSchemas>(
   storageName: string,
   onIgnoredError?: (error: any) => void,
 ): LocalPersister<Schemas>;
+
+/**
+ * The createOpfsPersister function creates an OpfsPersister object that can
+ * persist the Store to a file in an origin private file system (OPFS).
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createOpfsPersister(
+ *   store: Store | MergeableStore,
+ *   handle: FileSystemFileHandle,
+ *   onIgnoredError?: (error: any) => void,
+ * ): OpfsPersister;
+ * ```
+ *
+ * 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
+ */
+export function createOpfsPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas> | MergeableStore<Schemas>,
+  handle: FileSystemFileHandle,
+  onIgnoredError?: (error: any) => void,
+): OpfsPersister<Schemas>;

package/@types/persisters/with-schemas/index.d.ts

@@ -13,6 +13,7 @@
  * |-|-|-|-|
  * |SessionPersister|Browser session storage|Yes|Yes
  * |LocalPersister|Browser local storage|Yes|Yes
+ * |OpfsPersister|Browser origin private file system (OPFS)|Yes|Yes
  * |FilePersister|Local file (where possible)|Yes|Yes
  * |IndexedDbPersister|Browser IndexedDB|Yes|No
  * |RemotePersister|Remote server|Yes|No