tinybase 10.0.0-beta.0 → 10.0.0-beta.2

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

@@ -121,6 +121,7 @@ export type Sorter = (sortKey1: SortKey, sortKey2: SortKey) => number;
  * This is used internally within the mergeable-store module, but is used for
  * the createMergeableStore function's second optional argument to allow
  * applications to override the clock used to generate timestamps.
+ * @returns The current time, in milliseconds.
  * @category Stamps
  * @since v6.2.0
  */

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

@@ -134,6 +134,7 @@ export type Sorter = (sortKey1: SortKey, sortKey2: SortKey) => number;
  * This is used internally within the mergeable-store module, but is used for
  * the createMergeableStore function's second optional argument to allow
  * applications to override the clock used to generate timestamps.
+ * @returns The current time, in milliseconds.
  * @category Stamps
  * @since v6.2.0
  */

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

@@ -553,9 +553,9 @@ export interface Indexes {
    * Slice in a specified Index.
    *
    * This method is useful for iterating over the Slice structure of the Index
-   * in a functional style. The `rowCallback` parameter is a RowCallback
-   * function that will be called with the Id and value of each Row in the
-   * Slice.
+   * in a functional style. The `sliceCallback` parameter is a SliceCallback
+   * function that will be called with the Id of each Slice and a function for
+   * iterating over its Rows.
    * @param indexId The Id of the Index to iterate over.
    * @param sliceCallback The function that should be called for every Slice.
    * @example
@@ -828,6 +828,7 @@ export interface Indexes {
    * with a reference to the Indexes object.
    * @param listener The function that will be called whenever an Index
    * definition is added or removed.
+   * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example creates a Store, an Indexes object, and then registers a
    * listener that responds to the addition and the removal of an Index

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

@@ -674,9 +674,9 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * ```
    *
    * This method is useful for iterating over the Slice structure of the Index
-   * in a functional style. The `rowCallback` parameter is a RowCallback
-   * function that will be called with the Id and value of each Row in the
-   * Slice.
+   * in a functional style. The `sliceCallback` parameter is a SliceCallback
+   * function that will be called with the Id of each Slice and a function for
+   * iterating over its Rows.
    * @param indexId The Id of the Index to iterate over.
    * @param sliceCallback The function that should be called for every Slice.
    * @example
@@ -882,6 +882,7 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * with a reference to the Indexes object.
    * @param listener The function that will be called whenever an Index
    * definition is added or removed.
+   * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example creates a Store, an Indexes object, and then registers a
    * listener that responds to the addition and the removal of an Index

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

@@ -656,6 +656,7 @@ export interface Metrics {
    * with a reference to the Metrics object.
    * @param listener The function that will be called whenever a Metric
    * definition is added or removed.
+   * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example creates a Store, a Metrics object, and then registers a
    * listener that responds to the addition and the removal of a Metric

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

@@ -724,6 +724,7 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    * with a reference to the Metrics object.
    * @param listener The function that will be called whenever a Metric
    * definition is added or removed.
+   * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example creates a Store, a Metrics object, and then registers a
    * listener that responds to the addition and the removal of a Metric

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

@@ -47,6 +47,7 @@ export * from '../persisters/persister-sqlite-node/index.d.ts';
 export * from '../persisters/persister-sqlite-wasm/index.d.ts';
 export * from '../persisters/persister-sqlite3/index.d.ts';
 export * from '../persisters/persister-supabase/index.d.ts';
+export * from '../persisters/persister-tinyjoin/index.d.ts';
 export * from '../persisters/persister-yjs/index.d.ts';
 export * from '../queries/index.d.ts';
 export * from '../relationships/index.d.ts';

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

@@ -46,6 +46,7 @@ export * from '../../persisters/persister-sqlite-node/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite-wasm/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite3/with-schemas/index.d.ts';
 export * from '../../persisters/persister-supabase/with-schemas/index.d.ts';
+export * from '../../persisters/persister-tinyjoin/with-schemas/index.d.ts';
 export * from '../../persisters/persister-yjs/with-schemas/index.d.ts';
 export * from '../../persisters/with-schemas/index.d.ts';
 export * from '../../queries/with-schemas/index.d.ts';

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

@@ -27,6 +27,7 @@
  * |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*
+ * |TinyJoinPersister|PostgreSQL-shaped SQL in a browser, via [TinyJoin](https://tinyjoin.org)|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

package/@types/persisters/persister-partykit-server/index.d.ts

@@ -201,6 +201,7 @@ export class TinyBasePartyKitServer implements Server {
    * See the [PartyKit server API
    * documentation](https://docs.partykit.io/reference/partyserver-api/) for
    * more details.
+   * @returns A Promise containing the Response to the request.
    * @category Connection
    * @since v4.3.0
    */
@@ -256,6 +257,8 @@ export class TinyBasePartyKitServer implements Server {
    * server, or `true` to allow them (subject to subsequent canSetRow method,
    * canDelRow method, canSetCell method, and canDelCell method checks). The
    * default implementation returns `true` to allow all changes.
+   * @returns A promised boolean indicating whether to allow the changes to the
+   * Table.
    * @example
    * The following implementation will strip out any attempts by the client to
    * update any 'user' tabular data after the initial save:
@@ -295,6 +298,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow this Table from being deleted
    * on the server, or `true` to allow it. The default implementation returns
    * `true` to allow deletion.
+   * @returns A promised boolean indicating whether to allow the deletion of the
+   * Table.
    * @example
    * The following implementation will strip out any attempts by the client to
    * delete the 'user' Table:
@@ -336,6 +341,8 @@ export class TinyBasePartyKitServer implements Server {
    * server, or `true` to allow them (subject to subsequent canSetCell method
    * and canDelCell method checks). The default implementation returns `true` to
    * allow all changes.
+   * @returns A promised boolean indicating whether to allow the changes to the
+   * Row.
    * @example
    * The following implementation will strip out any attempts by the client to
    * update the 'me' Row of the 'user' Table after the initial save:
@@ -377,6 +384,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow this Row from being deleted
    * on the server, or `true` to allow it. The default implementation returns
    * `true` to allow deletion.
+   * @returns A promised boolean indicating whether to allow the deletion of the
+   * Row.
    * @example
    * The following implementation will strip out any attempts by the client to
    * delete the 'me' Row of the 'user' Table:
@@ -422,6 +431,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow changes to this Cell on the
    * server, or `true` to allow them. The default implementation returns `true`
    * to allow all changes.
+   * @returns A promised boolean indicating whether to allow the changes to the
+   * Cell.
    * @example
    * The following implementation will strip out any attempts by the client to
    * update the 'name' Cell of the 'me' Row of the 'user' Table after the
@@ -469,6 +480,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow this Cell from being deleted on
    * the server, or `true` to allow it. The default implementation returns
    * `true` to allow deletion.
+   * @returns A promised boolean indicating whether to allow the deletion of the
+   * Cell.
    * @example
    * The following implementation will strip out any attempts by the client to
    * delete the 'name' Cell of the 'me' Row of the 'user' Table:
@@ -518,6 +531,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow changes to this Value on the
    * server, or `true` to allow them. The default implementation returns `true`
    * to allow all changes.
+   * @returns A promised boolean indicating whether to allow the changes to the
+   * Value.
    * @example
    * The following implementation will strip out any attempts by the client to
    * update the 'userId' Value after the initial save:
@@ -559,6 +574,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow this Value from being deleted
    * on the server, or `true` to allow it. The default implementation returns
    * `true` to allow deletion.
+   * @returns A promised boolean indicating whether to allow the deletion of the
+   * Value.
    * @example
    * The following implementation will strip out any attempts by the client to
    * delete the 'userId' Value:

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

@@ -201,6 +201,7 @@ export class TinyBasePartyKitServer implements Server {
    * See the [PartyKit server API
    * documentation](https://docs.partykit.io/reference/partyserver-api/) for
    * more details.
+   * @returns A Promise containing the Response to the request.
    * @category Connection
    * @since v4.3.0
    */
@@ -256,6 +257,8 @@ export class TinyBasePartyKitServer implements Server {
    * server, or `true` to allow them (subject to subsequent canSetRow method,
    * canDelRow method, canSetCell method, and canDelCell method checks). The
    * default implementation returns `true` to allow all changes.
+   * @returns A promised boolean indicating whether to allow the changes to the
+   * Table.
    * @example
    * The following implementation will strip out any attempts by the client to
    * update any 'user' tabular data after the initial save:
@@ -295,6 +298,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow this Table from being deleted
    * on the server, or `true` to allow it. The default implementation returns
    * `true` to allow deletion.
+   * @returns A promised boolean indicating whether to allow the deletion of the
+   * Table.
    * @example
    * The following implementation will strip out any attempts by the client to
    * delete the 'user' Table:
@@ -336,6 +341,8 @@ export class TinyBasePartyKitServer implements Server {
    * server, or `true` to allow them (subject to subsequent canSetCell method
    * and canDelCell method checks). The default implementation returns `true` to
    * allow all changes.
+   * @returns A promised boolean indicating whether to allow the changes to the
+   * Row.
    * @example
    * The following implementation will strip out any attempts by the client to
    * update the 'me' Row of the 'user' Table after the initial save:
@@ -377,6 +384,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow this Row from being deleted
    * on the server, or `true` to allow it. The default implementation returns
    * `true` to allow deletion.
+   * @returns A promised boolean indicating whether to allow the deletion of the
+   * Row.
    * @example
    * The following implementation will strip out any attempts by the client to
    * delete the 'me' Row of the 'user' Table:
@@ -436,6 +445,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow changes to this Cell on the
    * server, or `true` to allow them. The default implementation returns `true`
    * to allow all changes.
+   * @returns A promised boolean indicating whether to allow the changes to the
+   * Cell.
    * @example
    * The following implementation will strip out any attempts by the client to
    * update the 'name' Cell of the 'me' Row of the 'user' Table after the
@@ -483,6 +494,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow this Cell from being deleted on
    * the server, or `true` to allow it. The default implementation returns
    * `true` to allow deletion.
+   * @returns A promised boolean indicating whether to allow the deletion of the
+   * Cell.
    * @example
    * The following implementation will strip out any attempts by the client to
    * delete the 'name' Cell of the 'me' Row of the 'user' Table:
@@ -544,6 +557,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow changes to this Value on the
    * server, or `true` to allow them. The default implementation returns `true`
    * to allow all changes.
+   * @returns A promised boolean indicating whether to allow the changes to the
+   * Value.
    * @example
    * The following implementation will strip out any attempts by the client to
    * update the 'userId' Value after the initial save:
@@ -585,6 +600,8 @@ export class TinyBasePartyKitServer implements Server {
    * Return `false` from this method to disallow this Value from being deleted
    * on the server, or `true` to allow it. The default implementation returns
    * `true` to allow deletion.
+   * @returns A promised boolean indicating whether to allow the deletion of the
+   * Value.
    * @example
    * The following implementation will strip out any attempts by the client to
    * delete the 'userId' Value:

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

@@ -0,0 +1,197 @@
+/**
+ * The persister-tinyjoin module of the TinyBase project lets you save and load
+ * Store data to and from a TinyJoin database in a browser.
+ * @see Database Persistence guide
+ * @packageDocumentation
+ * @module persister-tinyjoin
+ * @since 10.0.0
+ */
+import type {Client} from 'tinyjoin';
+import type {MergeableStore} from '../../mergeable-store/index.d.ts';
+import type {Store} from '../../store/index.d.ts';
+import type {
+  DatabasePersisterConfig,
+  DpcJson,
+  Persister,
+  Persists,
+} from '../index.d.ts';
+
+/**
+ * The TinyJoinPersister interface represents a Persister that lets you save and
+ * load Store data to and from a [TinyJoin](https://tinyjoin.org) database.
+ *
+ * You should use the createTinyJoinPersister function to create a
+ * TinyJoinPersister object.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getTinyJoin method for accessing a reference to the TinyJoin client the
+ * Store is being persisted to.
+ * @category Persister
+ * @since 10.0.0
+ */
+export interface TinyJoinPersister extends Persister<Persists.StoreOrMergeableStore> {
+  /**
+   * The getTinyJoin method returns a reference to the TinyJoin client the Store
+   * is being persisted to.
+   * @returns A reference to the TinyJoin client.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the TinyJoin client back out again.
+   *
+   * ```js ignore
+   * import {createStore} from 'tinybase';
+   * import {createTinyJoinPersister} from 'tinybase/persisters/persister-tinyjoin';
+   * import {create} from 'tinyjoin';
+   *
+   * const tinyJoin = await create();
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createTinyJoinPersister(store, tinyJoin, 'my_tinybase');
+   *
+   * console.log(persister.getTinyJoin() == tinyJoin);
+   * // -> true
+   *
+   * await persister.destroy();
+   * await tinyJoin.close();
+   * ```
+   * @category Getter
+   * @since 10.0.0
+   */
+  getTinyJoin(): Client;
+}
+
+/**
+ * The createTinyJoinPersister function creates a TinyJoinPersister object that
+ * can persist the Store to a [TinyJoin](https://tinyjoin.org) database in a
+ * browser.
+ *
+ * TinyJoin is a tiny, worker-first relational database that runs entirely in
+ * the browser, either in memory or - with an `opfs://` data directory - saved
+ * across reloads. This Persister therefore gives you a SQL-shaped local
+ * database to keep a Store in, without a server or a native dependency. Its
+ * `tinyjoin/node` entry point opens an ephemeral in-memory database in a Node
+ * worker thread, which makes this Persister testable outside a browser.
+ *
+ * A TinyJoinPersister supports regular Store objects, and can also be used to
+ * persist the metadata of a MergeableStore when using the JSON serialization
+ * mode, as described below.
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `tinyJoin` parameter which identifies the TinyJoin client that was returned
+ * from its own `create` function.
+ *
+ * A database Persister uses one of two modes: either a JSON serialization of
+ * the whole Store stored in a single row of a table (the default), or a tabular
+ * mapping of Table Ids to database table names and vice-versa).
+ *
+ * The third argument is a DatabasePersisterConfig object that configures which
+ * of those modes to use, and settings for each. If the third argument is simply
+ * a string, it is used as the `storeTableName` property of the JSON
+ * serialization.
+ *
+ * See the documentation for the DpcJson and DpcTabular types for more
+ * information on how both of those modes can be configured.
+ *
+ * Note: When using tabular mode, SQL NULL values are loaded as TinyBase null
+ * values, making tables dense (every Row has every Cell). See the Database
+ * Persistence guide for details.
+ *
+ * TinyJoin implements a deliberately bounded SQL dialect, and two of its
+ * boundaries are worth knowing about. It has no `ALTER TABLE ... DROP COLUMN`,
+ * so the table used for the JSON serialization should not have columns beyond
+ * the two it manages, and tabular mode should be left with its default of not
+ * deleting empty columns. It also has no SQL transaction
+ * statements, and rejects schema changes inside its own callback transactions,
+ * so each of the Persister's commands is atomic on its own rather than a save
+ * being atomic as a whole.
+ * @param store The Store or MergeableStore to persist.
+ * @param tinyJoin The TinyJoin client that was returned from `create(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @param onSqlCommand An optional handler called every time the Persister
+ * executes a SQL command or query. This is suitable for logging persistence
+ * behavior in a development environment.
+ * @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 TinyJoinPersister object.
+ * @example
+ * This example creates a TinyJoinPersister object and persists the Store to a
+ * TinyJoin database as a JSON serialization into the `my_tinybase` table. It
+ * makes a change to the database directly and then reloads it back into the
+ * Store.
+ *
+ * ```js ignore
+ * import {createStore} from 'tinybase';
+ * import {createTinyJoinPersister} from 'tinybase/persisters/persister-tinyjoin';
+ * import {create} from 'tinyjoin';
+ *
+ * const tinyJoin = await create();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createTinyJoinPersister(store, tinyJoin, 'my_tinybase');
+ *
+ * await persister.save();
+ * // Store will be saved to the database.
+ *
+ * console.log((await tinyJoin.query('SELECT * FROM my_tinybase')).rows);
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * await tinyJoin.query('UPDATE my_tinybase SET store = $1 WHERE _id = $2', [
+ *   '[{"pets":{"felix":{"species":"cat"}}},{}]',
+ *   '_',
+ * ]);
+ *
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * await tinyJoin.close();
+ * ```
+ * @example
+ * This example creates a TinyJoinPersister object and persists the Store to a
+ * TinyJoin database with tabular mapping.
+ *
+ * ```js ignore
+ * import {createStore} from 'tinybase';
+ * import {createTinyJoinPersister} from 'tinybase/persisters/persister-tinyjoin';
+ * import {create} from 'tinyjoin';
+ *
+ * const tinyJoin = await create();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createTinyJoinPersister(store, tinyJoin, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log((await tinyJoin.query('SELECT * FROM pets')).rows);
+ * // -> [{_id: 'fido', species: '"dog"'}]
+ * // Note that Cells and Values are JSON-encoded, as they are in PostgreSQL.
+ *
+ * await tinyJoin.query('INSERT INTO pets (_id, species) VALUES ($1, $2)', [
+ *   'felix',
+ *   '"cat"',
+ * ]);
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * await tinyJoin.close();
+ * ```
+ * @category Creation
+ * @essential Persisting stores
+ * @since 10.0.0
+ */
+export function createTinyJoinPersister<StoreType extends Store>(
+  store: StoreType,
+  tinyJoin: Client,
+  configOrStoreTableName?:
+    | (NoInfer<StoreType> extends MergeableStore
+        ? DpcJson
+        : DatabasePersisterConfig)
+    | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): TinyJoinPersister;