tinybase 3.2.0-beta.0 → 4.0.0-beta.1

package/lib/types/with-schemas/persister-remote.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The persister-remote module of the TinyBase project lets you save and load
+ * Store data to and from a remote server.
+ *
+ * @see Persisting Data guide
+ * @packageDocumentation
+ * @module persister-remote
+ */
+
+import {OptionalSchemas, Store} from './store';
+import {Persister} from './persisters';
+
+/**
+ * The createRemotePersister function creates a Persister object that can
+ * persist the Store to a remote server.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createRemotePersister(
+ *   store: Store,
+ *   loadUrl: string,
+ *   saveUrl: string,
+ *   autoLoadIntervalSeconds: number,
+ * ): Persister;
+ * ```
+ *
+ * As well as providing a reference to the Store to persist, you must provide
+ * `loadUrl` and `saveUrl` parameters. These identify the endpoints of the
+ * server that support the `GET` method (to fetch the Store JSON to load) and
+ * the `POST` method (to send the Store JSON to save) respectively.
+ *
+ * For when you choose to enable automatic loading for the Persister (with the
+ * startAutoLoad method), it will poll the loadUrl for changes. The
+ * `autoLoadIntervalSeconds` method is used to indicate how often to do this.
+ *
+ * @param store The Store to persist.
+ * @param loadUrl The endpoint that supports a `GET` method to load JSON.
+ * @param saveUrl The endpoint that supports a `POST` method to save JSON.
+ * @param autoLoadIntervalSeconds How often to poll the `loadUrl` when
+ * automatically loading changes from the server.
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to a remote
+ * server.
+ *
+ * ```js yolo
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createRemotePersister(
+ *   store,
+ *   'https://example.com/load',
+ *   'https://example.com/save',
+ *   5,
+ * );
+ *
+ * await persister.save();
+ * // Store JSON will be sent to server in a POST request.
+ *
+ * await persister.load();
+ * // Store JSON will be fetched from server with a GET request.
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ */
+export function createRemotePersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  loadUrl: string,
+  saveUrl: string,
+  autoLoadIntervalSeconds: number,
+): Persister<Schemas>;

package/lib/types/with-schemas/persister-yjs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The persister-yjs module of the TinyBase project provides a way to save and
+ * load Store data, to and from a Yjs document.
+ *
+ * A single entry point, the createYjsPersister function, is provided, which
+ * returns a new Persister object that can load and save a Store.:
+ *
+ * @packageDocumentation
+ * @module persister-yjs
+ */
+
+import * as Y from 'yjs';
+import {OptionalSchemas, Store} from './store.d';
+import {Persister} from './persisters.d';
+
+/**
+ * The createYjsPersister function creates a Persister object that can persist
+ * the Store to a Yjs document.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createYjsPersister(store: Store, yDoc: Y.Doc): Persister;
+ * ```
+ *
+ * As well as providing a reference to the Store to persist, you must provide
+ * the Yjs document to persist it to.
+ *
+ * @param store The Store to persist.
+ * @param yDoc The Yjs document to persist the Store to.
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to a Yjs
+ * document.
+ *
+ * ```js yolo
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createYjsPersister(store, yDoc);
+ *
+ * await persister.save();
+ * // Store JSON will be saved to the document.
+ *
+ * await persister.load();
+ * // Store JSON will be loaded from the document.
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ */
+export function createYjsPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  yDoc: Y.Doc,
+): Persister<Schemas>;

package/lib/types/with-schemas/persisters.d.ts

@@ -3,21 +3,21 @@
  * saving and loading Store data, to and from different destinations, or
  * underlying storage types.
  *
- * Several 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 createRemotePersister function returns a Persister that uses a remote
- *   server.
- * - The createFilePersister function returns a Persister that uses a local file
- *   (in an appropriate environment).
+ * Several entry points are provided (in separately installed modules), each of
+ * which returns a new Persister object that can load and save a Store:
+ *
+ * - The createSessionPersister function (in the persister-browser module)
+ *   returns a Persister that uses the browser's session storage.
+ * - The createLocalPersister function (in the persister-browser module) returns
+ *   a Persister that uses the browser's local storage.
+ * - The createRemotePersister function (in the persister-remote module) returns
+ *   a Persister that uses a remote server.
+ * - The createFilePersister function (in the persister-file module) returns a
+ *   Persister that uses a local file (in an appropriate environment).
  *
  * Since persistence requirements can be different for every app, the
- * createCustomPersister function can also be used to easily create a fully
- * customized way to save and load Store data.
+ * createCustomPersister function in this module can also be used to easily
+ * create a fully customized way to save and load Store data.
  *
  * @see Persisting Data guide
  * @see Countries demo
@@ -28,7 +28,6 @@
  */
 
 import {OptionalSchemas, Store, Tables, Values} from './store.d';
-import {Callback} from './common.d';
 
 /**
  * The PersisterStats type describes the number of times a Persister object has
@@ -50,6 +49,14 @@ export type PersisterStats = {
   saves?: number;
 };
 
+/**
+ * A PersisterListener is a callback that lets a Persister inform the Store that
+ * a change has happened to the underlying data.
+ */
+export type PersisterListener<Schemas extends OptionalSchemas> = (
+  content?: [Tables<Schemas[0], true>, Values<Schemas[1], true>],
+) => void;
+
 /**
  * A Persister object lets you save and load Store data to and from different
  * locations, or underlying storage types.
@@ -514,12 +521,12 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * const persister = createSessionPersister(store, 'pets');
    * await persister.startAutoSave();
    *
-   * console.log(store.getListenerStats().tables);
+   * console.log(store.getListenerStats().transaction);
    * // -> 1
    *
    * persister.destroy();
    *
-   * console.log(store.getListenerStats().tables);
+   * console.log(store.getListenerStats().transaction);
    * // -> 0
    * ```
    * @category Lifecycle
@@ -572,189 +579,6 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
   getStats(): PersisterStats;
 }
 
-/**
- * The createSessionPersister function creates a Persister object that can
- * persist the Store to the browser's session storage.
- *
- * This has schema-based typing. The following is a simplified representation:
- *
- * ```ts override
- * createSessionPersister(
- *   store: Store,
- *   storageName: string,
- * ): Persister;
- * ```
- *
- * As well as providing a reference to the Store to persist, you must provide a
- * `storageName` parameter which is unique to your application. This is the key
- * that the browser uses to identify the storage location.
- *
- * @param store The Store to persist.
- * @param storageName The unique key to identify the storage location.
- * @returns A reference to the new Persister object.
- * @example
- * This example creates a Persister object and persists the Store to the
- * browser's session storage.
- *
- * ```js
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createSessionPersister(store, 'pets');
- *
- * await persister.save();
- * console.log(sessionStorage.getItem('pets'));
- * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
- *
- * persister.destroy();
- * sessionStorage.clear();
- * ```
- * @category Creation
- */
-export function createSessionPersister<Schemas extends OptionalSchemas>(
-  store: Store<Schemas>,
-  storageName: string,
-): Persister<Schemas>;
-
-/**
- * The createLocalPersister function creates a Persister object that can
- * persist the Store to the browser's local storage.
- *
- * This has schema-based typing. The following is a simplified representation:
- *
- * ```ts override
- * createLocalPersister(
- *   store: Store,
- *   storageName: string,
- * ): Persister;
- * ```
- *
- * As well as providing a reference to the Store to persist, you must provide a
- * `storageName` parameter which is unique to your application. This is the key
- * that the browser uses to identify the storage location.
- *
- * @param store The Store to persist.
- * @param storageName The unique key to identify the storage location.
- * @returns A reference to the new Persister object.
- * @example
- * This example creates a Persister object and persists the Store to the
- * browser's local storage.
- *
- * ```js
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createLocalPersister(store, 'pets');
- *
- * await persister.save();
- * console.log(localStorage.getItem('pets'));
- * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
- *
- * persister.destroy();
- * localStorage.clear();
- * ```
- * @category Creation
- */
-export function createLocalPersister<Schemas extends OptionalSchemas>(
-  store: Store<Schemas>,
-  storageName: string,
-): Persister<Schemas>;
-
-/**
- * The createRemotePersister function creates a Persister object that can
- * persist the Store to a remote server.
- *
- * This has schema-based typing. The following is a simplified representation:
- *
- * ```ts override
- * createRemotePersister(
- *   store: Store,
- *   loadUrl: string,
- *   saveUrl: string,
- *   autoLoadIntervalSeconds: number,
- * ): Persister;
- * ```
- *
- * As well as providing a reference to the Store to persist, you must provide
- * `loadUrl` and `saveUrl` parameters. These identify the endpoints of the
- * server that support the `GET` method (to fetch the Store JSON to load) and
- * the `POST` method (to send the Store JSON to save) respectively.
- *
- * For when you choose to enable automatic loading for the Persister (with the
- * startAutoLoad method), it will poll the loadUrl for changes. The
- * `autoLoadIntervalSeconds` method is used to indicate how often to do this.
- *
- * @param store The Store to persist.
- * @param loadUrl The endpoint that supports a `GET` method to load JSON.
- * @param saveUrl The endpoint that supports a `POST` method to save JSON.
- * @param autoLoadIntervalSeconds How often to poll the `loadUrl` when
- * automatically loading changes from the server.
- * @returns A reference to the new Persister object.
- * @example
- * This example creates a Persister object and persists the Store to a remote
- * server.
- *
- * ```js yolo
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createRemotePersister(
- *   store,
- *   'https://example.com/load',
- *   'https://example.com/save',
- *   5,
- * );
- *
- * await persister.save();
- * // Store JSON will be sent to server in a POST request.
- *
- * await persister.load();
- * // Store JSON will be fetched from server with a GET request.
- *
- * persister.destroy();
- * ```
- * @category Creation
- */
-export function createRemotePersister<Schemas extends OptionalSchemas>(
-  store: Store<Schemas>,
-  loadUrl: string,
-  saveUrl: string,
-  autoLoadIntervalSeconds: number,
-): Persister<Schemas>;
-
-/**
- * The createFilePersister function creates a Persister object that can persist
- * the Store to a local file (in an appropriate environment).
- *
- * This has schema-based typing. The following is a simplified representation:
- *
- * ```ts override
- * createFilePersister(store: Store, filePath: string): Persister;
- * ```
- *
- * As well as providing a reference to the Store to persist, you must provide
- * `filePath` parameter which identifies the file to persist it to.
- *
- * @param store The Store to persist.
- * @param filePath The location of the local file to persist the Store to.
- * @returns A reference to the new Persister object.
- * @example
- * This example creates a Persister object and persists the Store to a local
- * file.
- *
- * ```js yolo
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createFilePersister(store, '/app/persisted.json');
- *
- * await persister.save();
- * // Store JSON will be saved to the file.
- *
- * await persister.load();
- * // Store JSON will be loaded from the file.
- *
- * persister.destroy();
- * ```
- * @category Creation
- */
-export function createFilePersister<Schemas extends OptionalSchemas>(
-  store: Store<Schemas>,
-  filePath: string,
-): Persister<Schemas>;
-
 /**
  * The createCustomPersister function creates a Persister object that you can
  * configure to persist the Store in any way you wish.
@@ -762,12 +586,12 @@ export function createFilePersister<Schemas extends OptionalSchemas>(
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * createCustomPersister(
+ * createCustomPersister<ListeningHandle>(
  *   store: Store,
  *   getPersisted: () => Promise<string | null | undefined>,
- *   setPersisted: (json: string) => Promise<void>,
- *   startListeningToPersisted: (didChange: Callback) => void,
- *   stopListeningToPersisted: Callback,
+ *   setPersisted: (getContent: () => [Tables, Values]) => Promise<void>,
+ *   addPersisterListener: (listener: PersisterListener) => ListeningHandle,
+ *   delPersisterListener: (listeningHandle: ListeningHandle) => void,
  * ): Persister;
  * ```
  *
@@ -780,15 +604,25 @@ export function createFilePersister<Schemas extends OptionalSchemas>(
  * covers. See those implementations for ideas on how to implement your own
  * Persister types.
  *
+ * This API changed in v4.0.0. Any custom persisters created on previous
+ * versions should be upgraded. Most notably, the `setPersisted` function
+ * parameter is provided with a `getContent` function to get the content from
+ * the Store itself, rather than being passed pre-serialized JSON.
+ * `addPersisterListener` has been renamed `addPersisterListener`, and
+ * `addPersisterListener` has been renamed `delPersisterListener`.
+ *
  * @param store The Store to persist.
- * @param getPersisted An asynchronous function which will fetch JSON from the
- * persistence layer (or `null` or `undefined` if not present).
- * @param setPersisted An asynchronous function which will send JSON to the
+ * @param getPersisted An asynchronous function which will fetch content from
+ * the persistence layer (or `null` or `undefined` if not present).
+ * @param setPersisted An asynchronous function which will send content to the
  * persistence layer.
- * @param startListeningToPersisted A function that will register a `didChange`
- * listener on underlying changes to the persistence layer.
- * @param stopListeningToPersisted A function that will unregister the listener
- * from the underlying changes to the persistence layer.
+ * @param addPersisterListener A function that will register a `listener`
+ * listener on underlying changes to the persistence layer. You can return a
+ * listening handle that will be provided again when `delPersisterListener`
+ * is called.
+ * @param delPersisterListener A function that will unregister the listener
+ * from the underlying changes to the persistence layer. It receives whatever
+ * was returned from your `addPersisterListener` implementation.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a custom Persister object and persists the Store to a
@@ -798,14 +632,13 @@ export function createFilePersister<Schemas extends OptionalSchemas>(
  * ```js
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
  * let storeJson;
- * let interval;
  *
  * const persister = createCustomPersister(
  *   store,
  *   async () => storeJson,
- *   async (json) => (storeJson = json),
- *   (didChange) => (interval = setInterval(didChange, 1000)),
- *   () => clearInterval(interval),
+ *   async (getContent) => (storeJson = JSON.stringify(getContent())),
+ *   (listener) => setInterval(listener, 1000),
+ *   (interval) => clearInterval(interval),
  * );
  *
  * await persister.save();
@@ -822,10 +655,17 @@ export function createFilePersister<Schemas extends OptionalSchemas>(
  * ```
  * @category Creation
  */
-export function createCustomPersister<Schemas extends OptionalSchemas>(
+export function createCustomPersister<
+  Schemas extends OptionalSchemas,
+  ListeningHandle,
+>(
   store: Store<Schemas>,
   getPersisted: () => Promise<string | null | undefined>,
-  setPersisted: (json: string) => Promise<void>,
-  startListeningToPersisted: (didChange: Callback) => void,
-  stopListeningToPersisted: Callback,
+  setPersisted: (
+    getContent: () => [Tables<Schemas[0]>, Values<Schemas[1]>],
+  ) => Promise<void>,
+  addPersisterListener: (
+    listener: PersisterListener<Schemas>,
+  ) => ListeningHandle,
+  delPersisterListener: (listeningHandle: ListeningHandle) => void,
 ): Persister<Schemas>;