tinybase 5.2.0-beta.3 → 5.2.0-beta.5

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

@@ -24,6 +24,7 @@
  * |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|
@@ -344,8 +345,8 @@ export type DpcJson = {
  *
  * This configuration can only be used when the Persister is persisting a
  * regular Store. For those database-oriented Persister types that support
- * MergeableStore data, you will need to use JSON-serialization, es described
- * in the DpcJson section.
+ * MergeableStore data, you will need to use JSON-serialization, es described in
+ * the DpcJson section.
  *
  * It is important to note that both the tabular mapping in ('save') and out
  * ('load') of an underlying database are disabled by default. This is to ensure
@@ -378,6 +379,15 @@ export type DpcJson = {
  * DpcTabularValues types for more details on how to configure the tabular
  * mapping mode.
  *
+ * Columns in SQLite database have no type, and so in this mode, the table can
+ * contain strings and numbers for Cells and Values, just as TinyBase does.
+ * Booleans, unfortunately, are stored as 0 or 1 in SQLite, and cannot be
+ * distinguished from numbers.
+ *
+ * In PostgreSQL databases, all Cell and Value columns are expected to be typed
+ * as `text`, and the strings, booleans, and numbers are all JSON-encoded by the
+ * Persister.
+ *
  * The 'Dpc' prefix indicates that this type is used within the
  * DatabasePersisterConfig type.
  * @example
@@ -522,6 +532,11 @@ export type DpcTabular = {
  *   },
  * }
  * ```
+ *
+ * The example above represents what happens with a SQLite Persister. In
+ * PostgreSQL databases, all Cell and Value columns are expected to be
+ * typed as `text`, and the strings, booleans, and numbers would be JSON-encoded
+ * if you queried them.
  * @category Configuration
  * @since v4.0.0
  */
@@ -635,6 +650,10 @@ export type DpcTabularLoad = {
  * | cat  | 4     |
  * +------+-------+
  * ```
+ * The example above represents what happens with a SQLite Persister. In
+ * PostgreSQL databases, all Cell and Value columns are expected to be
+ * typed as `text`, and the strings, booleans, and numbers would be JSON-encoded
+ * if you queried them.
  * @category Configuration
  * @since v4.0.0
  */
@@ -1214,7 +1233,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(
@@ -1348,10 +1368,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.
@@ -1400,7 +1463,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;
@@ -1439,12 +1503,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) =>
@@ -1504,7 +1564,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>,
@@ -1515,8 +1575,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>;