tinybase 7.0.0-beta.0 → 7.0.0-beta.2

package/@types/mergeable-store/index.d.ts

@@ -1115,6 +1115,7 @@ export interface MergeableStore extends Store {
  * ];
  * ```
  * @category Creation
+ * @essential Creating stores
  * @since v5.0.0
  */
 export function createMergeableStore(

package/@types/mergeable-store/with-schemas/index.d.ts

@@ -436,8 +436,9 @@ export type MergeableChanges<
  * @category Mergeable
  * @since v5.0.0
  */
-export interface MergeableStore<Schemas extends OptionalSchemas>
-  extends Store<Schemas> {
+export interface MergeableStore<
+  Schemas extends OptionalSchemas,
+> extends Store<Schemas> {
   //
   /**
    * The getMergeableContent method returns the full content of a
@@ -1607,6 +1608,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
  * ];
  * ```
  * @category Creation
+ * @essential Creating stores
  * @since v5.0.0
  */
 export function createMergeableStore(

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

@@ -23,6 +23,7 @@ export * from '../persisters/index.d.ts';
 export * from '../persisters/persister-automerge/index.d.ts';
 export * from '../persisters/persister-browser/index.d.ts';
 export * from '../persisters/persister-cr-sqlite-wasm/index.d.ts';
+export * from '../persisters/persister-durable-object-sql-storage/index.d.ts';
 export * from '../persisters/persister-durable-object-storage/index.d.ts';
 export * from '../persisters/persister-electric-sql/index.d.ts';
 export * from '../persisters/persister-expo-sqlite/index.d.ts';
@@ -34,6 +35,8 @@ export * from '../persisters/persister-partykit-server/index.d.ts';
 export * from '../persisters/persister-pglite/index.d.ts';
 export * from '../persisters/persister-postgres/index.d.ts';
 export * from '../persisters/persister-powersync/index.d.ts';
+export * from '../persisters/persister-react-native-mmkv/index.d.ts';
+export * from '../persisters/persister-react-native-sqlite/index.d.ts';
 export * from '../persisters/persister-remote/index.d.ts';
 export * from '../persisters/persister-sqlite-bun/index.d.ts';
 export * from '../persisters/persister-sqlite-wasm/index.d.ts';

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

@@ -22,6 +22,7 @@ export * from '../../metrics/with-schemas/index.d.ts';
 export * from '../../persisters/persister-automerge/with-schemas/index.d.ts';
 export * from '../../persisters/persister-browser/with-schemas/index.d.ts';
 export * from '../../persisters/persister-cr-sqlite-wasm/with-schemas/index.d.ts';
+export * from '../../persisters/persister-durable-object-sql-storage/with-schemas/index.d.ts';
 export * from '../../persisters/persister-durable-object-storage/with-schemas/index.d.ts';
 export * from '../../persisters/persister-electric-sql/with-schemas/index.d.ts';
 export * from '../../persisters/persister-expo-sqlite/with-schemas/index.d.ts';
@@ -33,6 +34,8 @@ export * from '../../persisters/persister-partykit-server/with-schemas/index.d.t
 export * from '../../persisters/persister-pglite/with-schemas/index.d.ts';
 export * from '../../persisters/persister-postgres/with-schemas/index.d.ts';
 export * from '../../persisters/persister-powersync/with-schemas/index.d.ts';
+export * from '../../persisters/persister-react-native-mmkv/with-schemas/index.d.ts';
+export * from '../../persisters/persister-react-native-sqlite/with-schemas/index.d.ts';
 export * from '../../persisters/persister-remote/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite-bun/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite-wasm/with-schemas/index.d.ts';

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

@@ -6,20 +6,25 @@
  * Many entry points are provided (in separately installed modules), each of
  * which returns different types of Persister that can load and save a Store.
  * Between them, these allow you to store your TinyBase data locally, remotely,
- * to SQLite and PostgreSQL databases, and across synchronization boundaries
- * with CRDT frameworks.
+ * to a Durable Object, to SQLite and PostgreSQL databases, and across
+ * synchronization boundaries with CRDT frameworks.
  *
  * |Persister|Storage|Store|MergeableStore
  * |-|-|-|-|
  * |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
+ * |ReactNativeMmkvPersister|MMKV in React Native, via [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv)|Yes|Yes
+ * |DurableObjectStoragePersister|Cloudflare Durable Object (KV)|No|Yes
+ * |DurableObjectSqlStoragePersister|Cloudflare Durable Object (SQLite)|No|Yes
  * |Sqlite3Persister|SQLite in Node, via [sqlite3](https://github.com/TryGhost/node-sqlite3)|Yes|Yes*
  * |SqliteBunPersister| SQLite in Bun, via [bun:sqlite](https://bun.sh/docs/api/sqlite)|Yes|Yes*
  * |SqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|Yes|Yes*
  * |ExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|Yes|Yes*
+ * |ReactNativeSqlitePersister|SQLite in React Native, via [react-native-sqlite-storage](https://github.com/andpor/react-native-sqlite-storage)|Yes|Yes*
  * |PostgresPersister|PostgreSQL, via [postgres](https://github.com/porsager/postgres)|Yes|Yes*
  * |PglitePersister|PostgreSQL, via [PGlite](https://github.com/electric-sql/pglite)|Yes|Yes*
  * |CrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|Yes|No
@@ -954,6 +959,7 @@ export type DpcTabularValues = {
  * sessionStorage.clear();
  * ```
  * @category Persister
+ * @essential Persisting stores
  * @since v1.0.0
  */
 export interface Persister<Persist extends Persists = Persists.StoreOnly> {

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

@@ -89,7 +89,7 @@ export interface AutomergePersister extends Persister {
  * await persister.save();
  * // Store will be saved to the document.
  *
- * console.log(await docHandler.doc());
+ * console.log(docHandler.doc());
  * // -> {tinybase: {t: {pets: {fido: {species: 'dog'}}}, v: {}}}
  *
  * await persister.destroy();
@@ -110,7 +110,6 @@ export interface AutomergePersister extends Persister {
  *   network: [new BroadcastChannelNetworkAdapter()],
  * });
  * const docHandler1 = repo1.create();
- * await docHandler1.doc();
  * const store1 = createStore();
  * const persister1 = createAutomergePersister(store1, docHandler1);
  * await persister1.startAutoLoad();
@@ -120,8 +119,7 @@ export interface AutomergePersister extends Persister {
  * const repo2 = new Repo({
  *   network: [new BroadcastChannelNetworkAdapter()],
  * });
- * const docHandler2 = repo2.find(docHandler1.documentId);
- * await docHandler2.doc();
+ * const docHandler2 = await repo2.find(docHandler1.documentId);
  * const store2 = createStore();
  * const persister2 = createAutomergePersister(store2, docHandler2);
  * await persister2.startAutoLoad();
@@ -131,8 +129,8 @@ export interface AutomergePersister extends Persister {
  * // with each other, merely for the purposes of sequentiality in this example.
  * const syncDocsWait = async () => {
  *   await new Promise((resolve) => setTimeout(() => resolve(0), 100));
- *   await docHandler1.doc();
- *   await docHandler2.doc();
+ *   docHandler1.doc();
+ *   docHandler2.doc();
  * };
  *
  * // Wait for the documents to synchronize in their initial state.

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

@@ -30,8 +30,9 @@ import type {Persister} from '../../with-schemas/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface AutomergePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface AutomergePersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getDocHandle method returns the Automerge document handler the Store is
    * being persisted to.
@@ -104,7 +105,7 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  * await persister.save();
  * // Store will be saved to the document.
  *
- * console.log(await docHandler.doc());
+ * console.log(docHandler.doc());
  * // -> {tinybase: {t: {pets: {fido: {species: 'dog'}}}, v: {}}}
  *
  * await persister.destroy();
@@ -125,7 +126,6 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  *   network: [new BroadcastChannelNetworkAdapter()],
  * });
  * const docHandler1 = repo1.create();
- * await docHandler1.doc();
  * const store1 = createStore();
  * const persister1 = createAutomergePersister(store1, docHandler1);
  * await persister1.startAutoLoad();
@@ -135,8 +135,7 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  * const repo2 = new Repo({
  *   network: [new BroadcastChannelNetworkAdapter()],
  * });
- * const docHandler2 = repo2.find(docHandler1.documentId);
- * await docHandler2.doc();
+ * const docHandler2 = await repo2.find(docHandler1.documentId);
  * const store2 = createStore();
  * const persister2 = createAutomergePersister(store2, docHandler2);
  * await persister2.startAutoLoad();
@@ -146,8 +145,8 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  * // with each other, merely for the purposes of sequentiality in this example.
  * const syncDocsWait = async () => {
  *   await new Promise((resolve) => setTimeout(() => resolve(0), 100));
- *   await docHandler1.doc();
- *   await docHandler2.doc();
+ *   docHandler1.doc();
+ *   docHandler2.doc();
  * };
  *
  * // Wait for the documents to synchronize in their initial state.

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
@@ -31,8 +34,7 @@ import type {Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface SessionPersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+export interface SessionPersister extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getStorageName method returns the unique key of the storage location
    * the Store is being persisted to.
@@ -72,8 +74,7 @@ export interface SessionPersister
  * @category Persister
  * @since v4.3.14
  */
-export interface LocalPersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+export interface LocalPersister extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getStorageName method returns the unique key of the storage location
    * the Store is being persisted to.
@@ -134,6 +135,7 @@ export interface LocalPersister
  * sessionStorage.clear();
  * ```
  * @category Creation
+ * @essential Persisting stores
  * @since v1.0.0
  */
 export function createSessionPersister(
@@ -176,6 +178,7 @@ export function createSessionPersister(
  * localStorage.clear();
  * ```
  * @category Creation
+ * @essential Persisting stores
  * @since v1.0.0
  */
 export function createLocalPersister(
@@ -183,3 +186,91 @@ 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
@@ -34,8 +37,9 @@ import type {Persister, Persists} from '../../with-schemas/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface SessionPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface SessionPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getStorageName method returns the unique key of the storage location
    * the Store is being persisted to.
@@ -75,8 +79,9 @@ export interface SessionPersister<Schemas extends OptionalSchemas>
  * @category Persister
  * @since v4.3.14
  */
-export interface LocalPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface LocalPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getStorageName method returns the unique key of the storage location
    * the Store is being persisted to.
@@ -103,6 +108,51 @@ 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.
@@ -147,6 +197,7 @@ export interface LocalPersister<Schemas extends OptionalSchemas>
  * sessionStorage.clear();
  * ```
  * @category Creation
+ * @essential Persisting stores
  * @since v1.0.0
  */
 export function createSessionPersister<Schemas extends OptionalSchemas>(
@@ -199,6 +250,7 @@ export function createSessionPersister<Schemas extends OptionalSchemas>(
  * localStorage.clear();
  * ```
  * @category Creation
+ * @essential Persisting stores
  * @since v1.0.0
  */
 export function createLocalPersister<Schemas extends OptionalSchemas>(
@@ -206,3 +258,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/persister-cr-sqlite-wasm/with-schemas/index.d.ts

@@ -30,8 +30,9 @@ import type {
  * @category Persister
  * @since v4.3.14
  */
-export interface CrSqliteWasmPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface CrSqliteWasmPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.