tinybase 5.2.0-beta.4 → 5.2.0

package/@types/persisters/persister-sqlite-wasm/index.d.ts

@@ -171,6 +171,6 @@ export function createSqliteWasmPersister(
   sqlite3: any,
   db: any,
   configOrStoreTableName?: DatabasePersisterConfig | string,
-  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
   onIgnoredError?: (error: any) => void,
 ): SqliteWasmPersister;

package/@types/persisters/persister-sqlite-wasm/with-schemas/index.d.cts

@@ -80,7 +80,7 @@ export interface SqliteWasmPersister<Schemas extends OptionalSchemas>
  *   sqlite3: any,
  *   db: any,
  *   configOrStoreTableName?: DatabasePersisterConfig | string,
- *   onSqlCommand?: (sql: string, args?: any[]) => void,
+ *   onSqlCommand?: (sql: string, params?: any[]) => void,
  *   onIgnoredError?: (error: any) => void,
  * ): SqliteWasmPersister;
  * ```
@@ -191,6 +191,6 @@ export function createSqliteWasmPersister<Schemas extends OptionalSchemas>(
   sqlite3: any,
   db: any,
   configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
-  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
   onIgnoredError?: (error: any) => void,
 ): SqliteWasmPersister<Schemas>;

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

@@ -80,7 +80,7 @@ export interface SqliteWasmPersister<Schemas extends OptionalSchemas>
  *   sqlite3: any,
  *   db: any,
  *   configOrStoreTableName?: DatabasePersisterConfig | string,
- *   onSqlCommand?: (sql: string, args?: any[]) => void,
+ *   onSqlCommand?: (sql: string, params?: any[]) => void,
  *   onIgnoredError?: (error: any) => void,
  * ): SqliteWasmPersister;
  * ```
@@ -191,6 +191,6 @@ export function createSqliteWasmPersister<Schemas extends OptionalSchemas>(
   sqlite3: any,
   db: any,
   configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
-  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
   onIgnoredError?: (error: any) => void,
 ): SqliteWasmPersister<Schemas>;

package/@types/persisters/persister-sqlite3/index.d.cts

@@ -172,6 +172,6 @@ export function createSqlite3Persister(
   store: Store | MergeableStore,
   db: Database,
   configOrStoreTableName?: DatabasePersisterConfig | string,
-  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
   onIgnoredError?: (error: any) => void,
 ): Sqlite3Persister;

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

@@ -172,6 +172,6 @@ export function createSqlite3Persister(
   store: Store | MergeableStore,
   db: Database,
   configOrStoreTableName?: DatabasePersisterConfig | string,
-  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
   onIgnoredError?: (error: any) => void,
 ): Sqlite3Persister;

package/@types/persisters/persister-sqlite3/with-schemas/index.d.cts

@@ -74,7 +74,7 @@ export interface Sqlite3Persister<Schemas extends OptionalSchemas>
  *   store: Store | MergeableStore,
  *   db: Database,
  *   configOrStoreTableName?: DatabasePersisterConfig | string,
- *   onSqlCommand?: (sql: string, args?: any[]) => void,
+ *   onSqlCommand?: (sql: string, params?: any[]) => void,
  *   onIgnoredError?: (error: any) => void,
  * ): Sqlite3Persister;
  * ```
@@ -191,6 +191,6 @@ export function createSqlite3Persister<Schemas extends OptionalSchemas>(
   store: Store<Schemas> | MergeableStore<Schemas>,
   db: Database,
   configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
-  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
   onIgnoredError?: (error: any) => void,
 ): Sqlite3Persister<Schemas>;

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

@@ -74,7 +74,7 @@ export interface Sqlite3Persister<Schemas extends OptionalSchemas>
  *   store: Store | MergeableStore,
  *   db: Database,
  *   configOrStoreTableName?: DatabasePersisterConfig | string,
- *   onSqlCommand?: (sql: string, args?: any[]) => void,
+ *   onSqlCommand?: (sql: string, params?: any[]) => void,
  *   onIgnoredError?: (error: any) => void,
  * ): Sqlite3Persister;
  * ```
@@ -191,6 +191,6 @@ export function createSqlite3Persister<Schemas extends OptionalSchemas>(
   store: Store<Schemas> | MergeableStore<Schemas>,
   db: Database,
   configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
-  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
   onIgnoredError?: (error: any) => void,
 ): Sqlite3Persister<Schemas>;

package/@types/persisters/with-schemas/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
@@ -1312,7 +1317,8 @@ export interface Persister<
    *   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(
@@ -1451,6 +1457,46 @@ export interface Persister<
   getStats(): PersisterStats;
 }
 
+/**
+ * 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.
@@ -1459,7 +1505,7 @@ export interface Persister<
  *
  * ```ts override
  * createCustomPersister<
- *   ListeningHandle,
+ *   ListenerHandle,
  *   Persist extends Persists = Persists.StoreOnly,
  * >(
  *   store: PersistedStore<Persist>,
@@ -1470,13 +1516,16 @@ export interface Persister<
  *   ) => 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>;
  * ```
  *
+ * 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.
@@ -1525,7 +1574,8 @@ export interface Persister<
  * 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;
@@ -1564,12 +1614,8 @@ export interface Persister<
  * 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) =>
@@ -1630,7 +1676,7 @@ export interface Persister<
  */
 export function createCustomPersister<
   Schemas extends OptionalSchemas,
-  ListeningHandle,
+  ListenerHandle,
   Persist extends Persists = Persists.StoreOnly,
 >(
   store: PersistedStore<Schemas, Persist>,
@@ -1641,8 +1687,170 @@ export function createCustomPersister<
   ) => Promise<void>,
   addPersisterListener: (
     listener: PersisterListener<Schemas, Persist>,
-  ) => ListeningHandle | Promise<ListeningHandle>,
-  delPersisterListener: (listeningHandle: ListeningHandle) => void,
+  ) => ListenerHandle | Promise<ListenerHandle>,
+  delPersisterListener: (listenerHandle: ListenerHandle) => void,
   onIgnoredError?: (error: any) => void,
   persist?: Persist,
 ): Persister<Schemas, Persist>;
+
+/**
+ * The createCustomSqlitePersister function creates a Persister object that you
+ * can configure to persist the Store to a SQLite database.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * 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>;
+ * ```
+ *
+ * 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<
+  Schemas extends OptionalSchemas,
+  ListenerHandle,
+  Persist extends Persists = Persists.StoreOnly,
+>(
+  store: PersistedStore<Schemas, Persist>,
+  configOrStoreTableName: DatabasePersisterConfig<Schemas> | 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<Schemas, Persist>;
+
+/**
+ * The createCustomSqlitePersister function creates a Persister object that you
+ * can configure to persist the Store to a PostgreSQL database.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * 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>;
+ * ```
+ *
+ * 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<
+  Schemas extends OptionalSchemas,
+  ListenerHandle,
+  Persist extends Persists = Persists.StoreOnly,
+>(
+  store: PersistedStore<Schemas, Persist>,
+  configOrStoreTableName: DatabasePersisterConfig<Schemas> | 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<Schemas, Persist>;