tinybase 6.6.1 → 6.7.1

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

package/@types/synchronizers/synchronizer-ws-server/index.d.ts

@@ -537,7 +537,7 @@ export interface WsServer {
  * import {createMergeableStore} from 'tinybase';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
  * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
- * import {WebSocketServer} from 'ws';
+ * import {WebSocket, WebSocketServer} from 'ws';
  *
  * // Server
  * const server = createWsServer(new WebSocketServer({port: 8047}));
@@ -583,7 +583,7 @@ export interface WsServer {
  * import {createFilePersister} from 'tinybase/persisters/persister-file';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
  * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
- * import {WebSocketServer} from 'ws';
+ * import {WebSocket, WebSocketServer} from 'ws';
  *
  * // Server
  * const server = createWsServer(
@@ -591,7 +591,7 @@ export interface WsServer {
  *   (pathId) =>
  *     createFilePersister(
  *       createMergeableStore(),
- *       pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *       './tmp/' + pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
  *     ),
  * );
  *
@@ -641,7 +641,7 @@ export interface WsServer {
  * await server.destroy();
  *
  * // Remove file for the purposes of this demo.
- * rmSync('petShop.json');
+ * rmSync('./tmp/petShop.json');
  * ```
  * @example
  * This example creates a WsServer that persists a MergeableStore to file that
@@ -654,7 +654,7 @@ export interface WsServer {
  * import {createFilePersister} from 'tinybase/persisters/persister-file';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
  * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
- * import {WebSocketServer} from 'ws';
+ * import {WebSocket, WebSocketServer} from 'ws';
  *
  * // Server
  * const server = createWsServer(
@@ -662,7 +662,7 @@ export interface WsServer {
  *   (pathId) => [
  *     createFilePersister(
  *       createMergeableStore(),
- *       pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *       './tmp/' + pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
  *     ),
  *     (store) => store.setValue('pathId', pathId),
  *   ],
@@ -684,7 +684,7 @@ export interface WsServer {
  * await server.destroy();
  *
  * // Remove file for the purposes of this demo.
- * rmSync('petShop.json');
+ * rmSync('./tmp/petShop.json');
  * ```
  * @example
  * This example creates a WsServer with a custom listener that displays

package/@types/synchronizers/synchronizer-ws-server/with-schemas/index.d.ts

@@ -564,7 +564,7 @@ export interface WsServer {
  * import {createMergeableStore} from 'tinybase';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
  * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
- * import {WebSocketServer} from 'ws';
+ * import {WebSocket, WebSocketServer} from 'ws';
  *
  * // Server
  * const server = createWsServer(new WebSocketServer({port: 8047}));
@@ -610,7 +610,7 @@ export interface WsServer {
  * import {createFilePersister} from 'tinybase/persisters/persister-file';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
  * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
- * import {WebSocketServer} from 'ws';
+ * import {WebSocket, WebSocketServer} from 'ws';
  *
  * // Server
  * const server = createWsServer(
@@ -618,7 +618,7 @@ export interface WsServer {
  *   (pathId) =>
  *     createFilePersister(
  *       createMergeableStore(),
- *       pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *       './tmp/' + pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
  *     ),
  * );
  *
@@ -668,7 +668,7 @@ export interface WsServer {
  * await server.destroy();
  *
  * // Remove file for the purposes of this demo.
- * rmSync('petShop.json');
+ * rmSync('./tmp/petShop.json');
  * ```
  * @example
  * This example creates a WsServer that persists a MergeableStore to file that
@@ -681,7 +681,7 @@ export interface WsServer {
  * import {createFilePersister} from 'tinybase/persisters/persister-file';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
  * import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
- * import {WebSocketServer} from 'ws';
+ * import {WebSocket, WebSocketServer} from 'ws';
  *
  * // Server
  * const server = createWsServer(
@@ -689,7 +689,7 @@ export interface WsServer {
  *   (pathId) => [
  *     createFilePersister(
  *       createMergeableStore(),
- *       pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
+ *       './tmp/' + pathId.replace(/[^a-zA-Z0-9]/g, '-') + '.json',
  *     ),
  *     (store) => store.setValue('pathId', pathId),
  *   ],
@@ -711,7 +711,7 @@ export interface WsServer {
  * await server.destroy();
  *
  * // Remove file for the purposes of this demo.
- * rmSync('petShop.json');
+ * rmSync('./tmp/petShop.json');
  * ```
  * @example
  * This example creates a WsServer with a custom listener that displays

package/@types/synchronizers/synchronizer-ws-server-simple/index.d.ts

@@ -101,7 +101,7 @@ export interface WsServerSimple {
  * import {createMergeableStore} from 'tinybase';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
  * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
- * import {WebSocketServer} from 'ws';
+ * import {WebSocket, WebSocketServer} from 'ws';
  *
  * // Server
  * const server = createWsServerSimple(new WebSocketServer({port: 8053}));

package/@types/synchronizers/synchronizer-ws-server-simple/with-schemas/index.d.ts

@@ -101,7 +101,7 @@ export interface WsServerSimple {
  * import {createMergeableStore} from 'tinybase';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
  * import {createWsServerSimple} from 'tinybase/synchronizers/synchronizer-ws-server-simple';
- * import {WebSocketServer} from 'ws';
+ * import {WebSocket, WebSocketServer} from 'ws';
  *
  * // Server
  * const server = createWsServerSimple(new WebSocketServer({port: 8053}));

package/@types/ui-react/index.d.ts

@@ -12562,6 +12562,7 @@ export function usePersisterStatusListener(
  *
  * ```jsx
  * import React from 'react';
+ * import {WebSocket, WebSocketServer} from 'ws';
  * import {createRoot} from 'react-dom/client';
  * import {createMergeableStore} from 'tinybase';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
@@ -12571,7 +12572,6 @@ export function usePersisterStatusListener(
  *   useCreateSynchronizer,
  *   useTables,
  * } from 'tinybase/ui-react';
- * import {WebSocketServer} from 'ws';
  *
  * const server1 = createWsServer(new WebSocketServer({port: 8044}));
  * const server2 = createWsServer(new WebSocketServer({port: 8045}));

package/@types/ui-react/with-schemas/index.d.ts

@@ -13654,6 +13654,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * ```jsx
  * import React from 'react';
+ * import {WebSocket, WebSocketServer} from 'ws';
  * import {createRoot} from 'react-dom/client';
  * import {createMergeableStore} from 'tinybase';
  * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
@@ -13663,7 +13664,6 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *   useCreateSynchronizer,
  *   useTables,
  * } from 'tinybase/ui-react';
- * import {WebSocketServer} from 'ws';
  *
  * const server1 = createWsServer(new WebSocketServer({port: 8044}));
  * const server2 = createWsServer(new WebSocketServer({port: 8045}));