tinybase 5.2.0-beta.4 → 5.2.0

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

@@ -86,10 +86,38 @@ export type Stamp<Thing, Hashed extends boolean = false> = Hashed extends true
   ? [thing: Thing, time: Time, hash: Hash]
   : [thing: Thing, time?: Time];
 
-// ContentHashes
+/**
+ * The ContentHashes type is used to quickly compare the content of two
+ * MergeableStore objects.
+ *
+ * It is simply an array of two Hash types, one for the MergeableStore's Tables
+ * and one for its Values.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Syncing
+ * @since v5.0.0
+ */
 export type ContentHashes = [tablesHash: Hash, valuesHash: Hash];
 
-// TablesStamp
+/**
+ * The TablesStamp type is used as metadata to decide how to merge two different
+ * sets of Tables together.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type TablesStamp<Hashed extends boolean = false> = Stamp<
+ *   {[tableId: Id]: TableStamp<Hashed>},
+ *   Hashed
+ * >;
+ * ```
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Stamps
+ * @since v5.0.0
+ */
 export type TablesStamp<
   Schema extends OptionalTablesSchema,
   Hashed extends boolean = false,
@@ -104,24 +132,92 @@ export type TablesStamp<
   Hashed
 >;
 
-// TableHashes
+/**
+ * The TableHashes type is used to quickly compare the content of two sets of
+ * Table objects.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * {[tableId: Id]: Hash};
+ * ```
+ *
+ * It is simply an object of Hash types, one for each Table Id in the
+ * MergeableStore.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Syncing
+ * @since v5.0.0
+ */
 export type TableHashes<Schema extends OptionalTablesSchema> = {
   [TableId in TableIdFromSchema<Schema>]?: Hash;
 };
 
-// TableStamp
+/**
+ * The TableStamp type is used as metadata to decide how to merge two different
+ * Table objects together.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type TableStamp<Hashed extends boolean = false> = Stamp<
+ *   {[rowId: Id]: RowStamp<Hashed>},
+ *   Hashed
+ * >;
+ * ```
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Stamps
+ * @since v5.0.0
+ */
 export type TableStamp<
   Schema extends OptionalTablesSchema,
   TableId extends TableIdFromSchema<Schema>,
   Hashed extends boolean = false,
 > = Stamp<{[rowId: Id]: RowStamp<Schema, TableId, Hashed>}, Hashed>;
 
-// RowHashes
+/**
+ * The RowHashes type is used to quickly compare the content of two sets of Row
+ * objects.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * {[tableId: Id]: {[rowId: Id]: Hash}};
+ * ```
+ *
+ * It is simply a nested object of Hash types, one for each Row Id, for each
+ * TableId, in the MergeableStore.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Syncing
+ * @since v5.0.0
+ */
 export type RowHashes<Schema extends OptionalTablesSchema> = {
   [TableId in TableIdFromSchema<Schema>]?: {[rowId: Id]: Hash};
 };
 
-// RowStamp
+/**
+ * The RowStamp type is used as metadata to decide how to merge two different
+ * Row objects together.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type RowStamp<Hashed extends boolean = false> = Stamp<
+ *   {[cellId: Id]: CellStamp<Hashed>},
+ *   Hashed
+ * >;
+ * ```
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Stamps
+ * @since v5.0.0
+ */
 export type RowStamp<
   Schema extends OptionalTablesSchema,
   TableId extends TableIdFromSchema<Schema>,
@@ -138,14 +234,48 @@ export type RowStamp<
   Hashed
 >;
 
-// CellHashes
+/**
+ * The CellHashes type is used to quickly compare the content of two sets of
+ * Cell objects.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * {[tableId: Id]: {[rowId: Id]: {[cellId: Id]: Hash}}};
+ * ```
+ *
+ * It is simply a nested object of Hash types, one for each Cell Id, for each
+ * Row Id, for each TableId, in the MergeableStore.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Syncing
+ * @since v5.0.0
+ */
 export type CellHashes<Schema extends OptionalTablesSchema> = {
   [TableId in TableIdFromSchema<Schema>]?: {
     [rowId: Id]: {[CellId in CellIdFromSchema<Schema, TableId>]?: Hash};
   };
 };
 
-// CellStamp
+/**
+ * The CellStamp type is used as metadata to decide how to merge two different
+ * Cell objects together.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type CellStamp<Hashed extends boolean = false> = Stamp<
+ *   CellOrUndefined,
+ *   Hashed
+ * >;
+ * ```
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Stamps
+ * @since v5.0.0
+ */
 export type CellStamp<
   Schema extends OptionalTablesSchema,
   TableId extends TableIdFromSchema<Schema>,
@@ -153,7 +283,24 @@ export type CellStamp<
   Hashed extends boolean = false,
 > = Stamp<CellOrUndefined<Schema, TableId, CellId>, Hashed>;
 
-// ValuesStamp
+/**
+ * The ValuesStamp type is used as metadata to decide how to merge two different
+ * sets of Values together.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type ValuesStamp<Hashed extends boolean = false> = Stamp<
+ *   {[valueId: Id]: ValueStamp<Hashed>},
+ *   Hashed
+ * >;
+ * ```
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Stamps
+ * @since v5.0.0
+ */
 export type ValuesStamp<
   Schema extends OptionalValuesSchema,
   Hashed extends boolean = false,
@@ -168,12 +315,46 @@ export type ValuesStamp<
   Hashed
 >;
 
-// ValueHashes
+/**
+ * The ValueHashes type is used to quickly compare the content of two sets of
+ * Value objects.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * {[valueId: Id]: Hash};
+ * ```
+ *
+ * It is simply an object of Hash types, one for each Value Id in the
+ * MergeableStore.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Syncing
+ * @since v5.0.0
+ */
 export type ValueHashes<Schema extends OptionalValuesSchema> = {
   [ValueId in ValueIdFromSchema<Schema>]?: Hash;
 };
 
-// ValueStamp
+/**
+ * The ValueStamp type is used as metadata to decide how to merge two different
+ * Value objects together.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type ValueStamp<Hashed extends boolean = false> = Stamp<
+ *   ValueOrUndefined,
+ *   Hashed
+ * >;
+ * ```
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
+ * @category Stamps
+ * @since v5.0.0
+ */
 export type ValueStamp<
   Schema extends OptionalValuesSchema,
   ValueId extends ValueIdFromSchema<Schema>,

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

@@ -19,23 +19,28 @@
  * |Sqlite3Persister|SQLite in Node, via [sqlite3](https://github.com/TryGhost/node-sqlite3)|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*
+ * |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
  * |ElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|Yes|No
  * |LibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|Yes|No
  * |PowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|Yes|No
- * |PostgresPersister|PostgreSQL, via [postgres](https://github.com/porsager/postgres)|Yes|No
- * |PglitePersister|PostgreSQL, via [PGlite](https://github.com/electric-sql/pglite)|Yes|No
  * |YjsPersister|Yjs CRDTs, via [yjs](https://github.com/yjs/yjs)|Yes|No
  * |AutomergePersister|Automerge CRDTs, via [automerge-repo](https://github.com/automerge/automerge-repo)|Yes|No
  * |PartyKitPersister|[PartyKit](https://www.partykit.io/), via the persister-partykit-server module|Yes|No|
  *
- * (*) Note that SQLite-based Persisters can currently only persist
- * MergeableStore data when using the JSON-based DpcJson mode, and not in a
- * tabular fashion.
+ * (*) Note that SQLite- and PostgreSQL-based Persisters can currently only
+ * persist MergeableStore data when used with the JSON-based DpcJson mode, and
+ * not when using the DpcTabular mode.
  *
  * Since persistence requirements can be different for every app, the
  * createCustomPersister function in this module can also be used to easily
  * create a fully customized way to save and load Store data.
+ *
+ * Similarly, the createCustomSqlitePersister function and
+ * createCustomPostgreSqlPersister function can be used to build Persister objects
+ * against SQLite and PostgreSQL SDKs (or forks) that are not already included
+ * with TinyBase.
  * @see Persistence guides
  * @see Countries demo
  * @see Todo App demos
@@ -1233,7 +1238,8 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    *   getDataFromRemoteSystem,
    *   sendDataToRemoteSystem,
    * } from 'custom-remote-handlers';
-   * import {createCustomPersister, createStore} from 'tinybase';
+   * import {createCustomPersister} from 'tinybase/persisters';
+   * import {createStore} from 'tinybase';
    *
    * const store = createStore();
    * const persister = createCustomPersister(
@@ -1367,10 +1373,53 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
   //
 }
 
+/**
+ * The DatabaseExecuteCommand type describes a function that is used to execute
+ * commands against a database.
+ *
+ * This is only used when developing custom database-oriented Persisters, and
+ * most TinyBase users will not need to be particularly aware of it.
+ *
+ * It is modelled around the common pattern of database SDKs being able to
+ * execute commands with parameters, and have those (probably asynchronous)
+ * command executions return an array of objects, where each object represents a
+ * row.
+ * @param sql The SQL string to execute, which may include positional parameter
+ * placeholders.
+ * @param params An array of parameters to pass to the SQL command.
+ * @returns An promise of an array of objects, where each object represents a
+ * database result row (if the command was a query).
+ * @category Creation
+ * @since v5.2.0
+ */
+export type DatabaseExecuteCommand = (
+  sql: string,
+  params?: any[],
+) => Promise<{[field: string]: any}[]>;
+
+/**
+ * The DatabaseChangeListener type describes a function that is used to listen
+ * for changes to the data in a database.
+ *
+ * This is only used when developing custom database-oriented Persisters, and
+ * most TinyBase users will not need to be particularly aware of it.
+ *
+ * This function should be called with the name of a relevant table that has
+ * changed, possible through the use of events, triggers, or notifications,
+ * dependent on the specific database implementation.
+ * @param tableName The name of the table that has changed.
+ * @category Creation
+ * @since v5.2.0
+ */
+export type DatabaseChangeListener = (tableName: string) => void;
+
 /**
  * The createCustomPersister function creates a Persister object that you can
  * configure to persist the Store in any way you wish.
  *
+ * This is only used when developing custom Persisters, and most TinyBase users
+ * will not need to be particularly aware of it.
+ *
  * As well as providing a reference to the Store to persist, you must provide
  * functions that handle how to fetch, write, and listen to, the persistence
  * layer.
@@ -1419,7 +1468,8 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
  * Store.
  *
  * ```js
- * import {createCustomPersister, createStore} from 'tinybase';
+ * import {createCustomPersister} from 'tinybase/persisters';
+ * import {createStore} from 'tinybase';
  *
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
  * let persistedJson;
@@ -1458,12 +1508,8 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
  * MergeableStore.
  *
  * ```js
- * import {
- *   Persists,
- *   createCustomPersister,
- *   createMergeableStore,
- *   createStore,
- * } from 'tinybase';
+ * import {Persists, createCustomPersister} from 'tinybase/persisters';
+ * import {createMergeableStore, createStore} from 'tinybase';
  *
  * let persistedJson;
  * const createJsonPersister = (storeOrMergeableStore) =>
@@ -1523,7 +1569,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
  * @since v1.0.0
  */
 export function createCustomPersister<
-  ListeningHandle,
+  ListenerHandle,
   Persist extends Persists = Persists.StoreOnly,
 >(
   store: PersistedStore<Persist>,
@@ -1534,8 +1580,123 @@ export function createCustomPersister<
   ) => Promise<void>,
   addPersisterListener: (
     listener: PersisterListener<Persist>,
-  ) => ListeningHandle | Promise<ListeningHandle>,
-  delPersisterListener: (listeningHandle: ListeningHandle) => void,
+  ) => ListenerHandle | Promise<ListenerHandle>,
+  delPersisterListener: (listenerHandle: ListenerHandle) => void,
   onIgnoredError?: (error: any) => void,
   persist?: Persist,
 ): Persister<Persist>;
+
+/**
+ * The createCustomSqlitePersister function creates a Persister object that you
+ * can configure to persist the Store to a SQLite database.
+ *
+ * This is only used when developing custom database-oriented Persisters, and
+ * most TinyBase users will not need to be particularly aware of it.
+ *
+ * All of the TinyBase SQLite-oriented Persister functions use this function
+ * under the covers, and so you may wish to look at those implementations for
+ * ideas on how to build your own Persister type, and as functional examples.
+ * Examine the implementation of the createSqlite3Persister function as a good
+ * starting point, for example.
+ * @param store The Store to persist.
+ * @param configOrStoreTableName A DatabasePersisterConfig object, or a string
+ * that will be used as the name of the Store's table in the database.
+ * @param executeCommand A function that will execute a command against the
+ * database.
+ * @param addChangeListener A function that will register a listener for changes
+ * to the database.
+ * @param delChangeListener A function that will unregister the listener for
+ * changes to the database.
+ * @param onSqlCommand A function that will be called for each SQL command
+ * executed against the database.
+ * @param onIgnoredError A function that will be called for errors that are
+ * ignored by the Persister.
+ * @param destroy A function that will be called to perform any extra clean up
+ * on the Persister.
+ * @param persist An integer from the Persists enum to indicate which types of
+ * Store are supported by this Persister: `1` indicates only a regular Store is
+ * supported, `2` indicates only a MergeableStore is supported, and `3`
+ * indicates that both Store and MergeableStore are supported.
+ * @param thing A reference to the database or connection that can be returned
+ * with a method, by default called `getDb`.
+ * @param getThing An optional string that will be used to get the reference to
+ * the database or connection from the Persister, defaulting to `getDb`.
+ * @returns A reference to the new SQLite-oriented Persister object.
+ * @category Creation
+ * @since v5.2.0
+ */
+export function createCustomSqlitePersister<
+  ListenerHandle,
+  Persist extends Persists = Persists.StoreOnly,
+>(
+  store: PersistedStore<Persist>,
+  configOrStoreTableName: DatabasePersisterConfig | string | undefined,
+  executeCommand: DatabaseExecuteCommand,
+  addChangeListener: (listener: DatabaseChangeListener) => ListenerHandle,
+  delChangeListener: (listenerHandle: ListenerHandle) => void,
+  onSqlCommand: ((sql: string, params?: any[]) => void) | undefined,
+  onIgnoredError: ((error: any) => void) | undefined,
+  destroy: () => void,
+  persist: Persist,
+  thing: any,
+  getThing?: string,
+): Persister<Persist>;
+
+/**
+ * The createCustomSqlitePersister function creates a Persister object that you
+ * can configure to persist the Store to a PostgreSQL database.
+ *
+ * This is only used when developing custom database-oriented Persisters, and
+ * most TinyBase users will not need to be particularly aware of it.
+ *
+ * All of the TinyBase PostgreSQL-oriented Persister functions use this function
+ * under the covers, and so you may wish to look at those implementations for
+ * ideas on how to build your own Persister type, and as functional
+ * examples. Examine the implementation of the createPostgresPersister function
+ * as a good starting point, for example.
+ * @param store The Store to persist.
+ * @param configOrStoreTableName A DatabasePersisterConfig object, or a string
+ * that will be used as the name of the Store's table in the database.
+ * @param executeCommand A function that will execute a command against the
+ * database.
+ * @param addChangeListener A function that will register a listener for changes
+ * to the database.
+ * @param delChangeListener A function that will unregister the listener for
+ * changes to the database.
+ * @param onSqlCommand A function that will be called for each SQL command
+ * executed against the database.
+ * @param onIgnoredError A function that will be called for errors that are
+ * ignored by the Persister.
+ * @param destroy A function that will be called to perform any extra clean up
+ * on the Persister.
+ * @param persist An integer from the Persists enum to indicate which types of
+ * Store are supported by this Persister: `1` indicates only a regular Store is
+ * supported, `2` indicates only a MergeableStore is supported, and `3`
+ * indicates that both Store and MergeableStore are supported.
+ * @param thing A reference to the database or connection that can be returned
+ * with a method, by default called `getDb`.
+ * @param getThing An optional string that will be used to get the reference to
+ * the database or connection from the Persister, defaulting to `getDb`.
+ * @returns A reference to the new Persister object.
+ * @category Creation
+ * @since v5.2.0
+ */
+export function createCustomPostgreSqlPersister<
+  ListenerHandle,
+  Persist extends Persists = Persists.StoreOnly,
+>(
+  store: PersistedStore<Persist>,
+  configOrStoreTableName: DatabasePersisterConfig | string | undefined,
+  executeCommand: DatabaseExecuteCommand,
+  addChangeListener: (
+    channel: string,
+    listener: DatabaseChangeListener,
+  ) => Promise<ListenerHandle>,
+  delChangeListener: (listenerHandle: ListenerHandle) => void,
+  onSqlCommand: ((sql: string, params?: any[]) => void) | undefined,
+  onIgnoredError: ((error: any) => void) | undefined,
+  destroy: () => void,
+  persist: Persist,
+  thing: any,
+  getThing?: string,
+): Persister<Persist>;