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

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

@@ -0,0 +1,221 @@
+/**
+ * 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/with-schemas/index.d.ts';
+import type {
+  OptionalSchemas,
+  Store,
+} from '../../../store/with-schemas/index.d.ts';
+import type {
+  DatabasePersisterConfig,
+  DpcJson,
+  Persister,
+  Persists,
+} from '../../with-schemas/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<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, 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.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * 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;
+ * ```
+ *
+ * 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<Schemas extends OptionalSchemas>(
+  store: MergeableStore<Schemas>,
+  tinyJoin: Client,
+  configOrStoreTableName?: DpcJson | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): TinyJoinPersister<Schemas>;
+export function createTinyJoinPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas> & {getMergeableContent?: never},
+  tinyJoin: Client,
+  configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): TinyJoinPersister<Schemas>;

package/@types/persisters/with-schemas/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/queries/index.d.ts

@@ -3272,6 +3272,7 @@ export interface Queries {
    * with a reference to the Queries object.
    * @param listener The function that will be called whenever a Query
    * 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 Queries object, and then registers a
    * listener that responds to the addition and the removal of a Query
@@ -3321,6 +3322,7 @@ export interface Queries {
    * @param queryId The Id of the query to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the param values
    * of the query change.
+   * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers two listeners that respond to changes to the param
    * values of a specific query, or any query respectively.
@@ -3392,6 +3394,7 @@ export interface Queries {
    * @param paramId The Id of the param to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the specific
    * param value of the query changes.
+   * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers two listeners that respond to changes to a specific
    * param value of a specific query, or any param value of any query

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

@@ -3582,6 +3582,7 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * with a reference to the Queries object.
    * @param listener The function that will be called whenever a Query
    * 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 Queries object, and then registers a
    * listener that responds to the addition and the removal of a Query
@@ -3637,6 +3638,7 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * @param queryId The Id of the query to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the param values
    * of the query change.
+   * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers two listeners that respond to changes to the param
    * values of a specific query, or any query respectively.
@@ -3721,6 +3723,7 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * @param paramId The Id of the param to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the specific
    * param value of the query changes.
+   * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers two listeners that respond to changes to a specific
    * param value of a specific query, or any param value of any query

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

@@ -755,6 +755,7 @@ export interface Relationships {
    * called with a reference to the Relationships object.
    * @param listener The function that will be called whenever a Relationship
    * 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 Relationships object, and then registers a
    * listener that responds to the addition and the removal of a Relationship

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

@@ -866,6 +866,7 @@ export interface Relationships<in out Schemas extends OptionalSchemas> {
    * called with a reference to the Relationships object.
    * @param listener The function that will be called whenever a Relationship
    * 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 Relationships object, and then registers a
    * listener that responds to the addition and the removal of a Relationship

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

@@ -739,6 +739,7 @@ export type ValueCallback = (valueId: Id, value: Value) => void;
  * new one, such as when incrementing a number. See that method for specific
  * examples.
  * @param cell The current value of the Cell to map to a new value.
+ * @returns The new value of the Cell.
  * @category Callback
  * @since v1.0.0
  */
@@ -752,6 +753,7 @@ export type MapCell = (cell: CellOrUndefined) => Cell;
  * a new one, such as when incrementing a number. See that method for specific
  * examples.
  * @param value The current Value to map to a new Value.
+ * @returns The new Value.
  * @category Callback
  * @since v3.0.0
  */
@@ -765,6 +767,7 @@ export type MapValue = (value: ValueOrUndefined) => Value;
  * setMetricDefinition method of a Metrics object, or the setIndexDefinition
  * method of an Indexes object. See those methods for specific examples.
  * @param cellId The Id of the Cell to fetch the value for.
+ * @returns The value of the Cell, or `undefined`.
  * @category Callback
  * @since v1.0.0
  */
@@ -871,6 +874,7 @@ export type ChangedValueIds = {[valueId: Id]: IdAddedOrRemoved};
  * can use the getTransactionChanges method and getTransactionLog method of the
  * Store directly to decide whether to do the rollback.
  * @param store A reference to the Store that is completing a transaction.
+ * @returns Whether to rollback the transaction.
  * @category Callback
  * @since v1.0.0
  */

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

@@ -1000,6 +1000,7 @@ export type ValueCallback<
  * new one, such as when incrementing a number. See that method for specific
  * examples.
  * @param cell The current value of the Cell to map to a new value.
+ * @returns The new value of the Cell.
  * @category Callback
  * @since v1.0.0
  */
@@ -1025,6 +1026,7 @@ export type MapCell<
  * a new one, such as when incrementing a number. See that method for specific
  * examples.
  * @param value The current Value to map to a new Value.
+ * @returns The new Value.
  * @category Callback
  * @since v3.0.0
  */
@@ -1047,6 +1049,7 @@ export type MapValue<
  * setMetricDefinition method of a Metrics object, or the setIndexDefinition
  * method of an Indexes object. See those methods for specific examples.
  * @param cellId The Id of the Cell to fetch the value for.
+ * @returns The value of the Cell, or `undefined`.
  * @category Callback
  * @since v1.0.0
  */
@@ -1200,6 +1203,7 @@ export type ChangedValueIds<Schema extends OptionalValuesSchema> = {
  * can use the getTransactionChanges method and getTransactionLog method of the
  * Store directly to decide whether to do the rollback.
  * @param store A reference to the Store that is completing a transaction.
+ * @returns Whether to rollback the transaction.
  * @category Callback
  * @since v1.0.0
  */

package/@types/ui-react/index.d.ts

@@ -288,6 +288,7 @@ export type UndoOrRedoInformation = [boolean, Callback, Id | undefined, string];
  * useSetTableCallback hook or useSetRowCallback hook - so that the Id arguments
  * of the object to set can also be dependent on the event or parameter provided
  * (as well as the object itself being set).
+ * @returns The Id, determined from the parameter and Store.
  * @category Identity
  * @since v1.0.0
  */
@@ -392,6 +393,7 @@ export function useCreateStore(
 
 /**
  * The useCreateMergeableStore hook.
+ * @returns A reference to the MergeableStore.
  * @category Store hooks
  * @since v1.0.0
  */

package/@types/ui-react/with-schemas/index.d.ts

@@ -491,6 +491,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
 
   /**
  * The useCreateMergeableStore hook.
+ * @returns A reference to the MergeableStore.
  * @category Store hooks
  * @since v1.0.0
  */

package/@types/ui-react-dom-charts/index.d.ts

@@ -489,6 +489,7 @@ export type YAxisProps = {
  * The series children declare their own xCellId and yCellId bindings. The
  * optional XAxis component and YAxis component children can be used to
  * configure axis titles, bounds, ticks, and tick formatting.
+ * @returns A rendering of the chart frame and its series.
  * @category Store components
  * @since v8.5.0
  * @example
@@ -544,6 +545,7 @@ export function CartesianChart(
  *
  * ![XAxis component example](https://beta.tinybase.org/shots/axis-overrides-react-demo.png
  * "XAxis component example")
+ * @returns Nothing, since this component only configures the x axis.
  * @category Store components
  * @since v8.5.0
  */
@@ -560,6 +562,7 @@ export function XAxis(props: XAxisProps): ComponentReturnType;
  *
  * ![YAxis component example](https://beta.tinybase.org/shots/axis-overrides-react-demo.png
  * "YAxis component example")
+ * @returns Nothing, since this component only configures the y axis.
  * @category Store components
  * @since v8.5.0
  */
@@ -576,6 +579,7 @@ export function YAxis(props: YAxisProps): ComponentReturnType;
  *
  * ![LineSeries component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
  * "LineSeries component example")
+ * @returns A rendering of the line series.
  * @category Store components
  * @since v8.5.0
  */
@@ -592,6 +596,7 @@ export function LineSeries(props: SeriesProps): ComponentReturnType;
  *
  * ![BarSeries component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
  * "BarSeries component example")
+ * @returns A rendering of the bar series.
  * @category Store components
  * @since v8.5.0
  */
@@ -609,6 +614,7 @@ export function BarSeries(props: SeriesProps): ComponentReturnType;
  *
  * ![LineChart component example](https://beta.tinybase.org/shots/basic-chart-react-demo.png "LineChart
  * component example")
+ * @returns A rendering of the line chart.
  * @category Store components
  * @since v8.5.0
  * @example
@@ -662,6 +668,7 @@ export function LineChart(
  *
  * ![BarChart component example](https://beta.tinybase.org/shots/sorting-and-types-react-demo.png
  * "BarChart component example")
+ * @returns A rendering of the bar chart.
  * @category Store components
  * @since v8.5.0
  * @example

package/@types/ui-react-dom-charts/with-schemas/index.d.ts

@@ -550,6 +550,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * The series children declare their own xCellId and yCellId bindings. The
  * optional XAxis component and YAxis component children can be used to
  * configure axis titles, bounds, ticks, and tick formatting.
+ * @returns A rendering of the chart frame and its series.
  * @category Store components
  * @since v8.5.0
  * @example
@@ -611,6 +612,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * ![XAxis component example](https://beta.tinybase.org/shots/axis-overrides-react-demo.png
  * "XAxis component example")
+ * @returns Nothing, since this component only configures the x axis.
  * @category Store components
  * @since v8.5.0
  */
@@ -627,6 +629,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * ![YAxis component example](https://beta.tinybase.org/shots/axis-overrides-react-demo.png
  * "YAxis component example")
+ * @returns Nothing, since this component only configures the y axis.
  * @category Store components
  * @since v8.5.0
  */
@@ -643,6 +646,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * ![LineSeries component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
  * "LineSeries component example")
+ * @returns A rendering of the line series.
  * @category Store components
  * @since v8.5.0
  */
@@ -659,6 +663,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * ![BarSeries component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
  * "BarSeries component example")
+ * @returns A rendering of the bar series.
  * @category Store components
  * @since v8.5.0
  */
@@ -686,6 +691,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * ![LineChart component example](https://beta.tinybase.org/shots/basic-chart-react-demo.png "LineChart
  * component example")
+ * @returns A rendering of the line chart.
  * @category Store components
  * @since v8.5.0
  * @example
@@ -752,6 +758,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * ![BarChart component example](https://beta.tinybase.org/shots/sorting-and-types-react-demo.png
  * "BarChart component example")
+ * @returns A rendering of the bar chart.
  * @category Store components
  * @since v8.5.0
  * @example

package/@types/ui-solid/index.d.ts

@@ -315,6 +315,7 @@ export type UndoOrRedoInformation = [
  * useSetTableCallback primitive or useSetRowCallback primitive - so that the Id
  * arguments of the object to set can also be dependent on the event or
  * parameter provided (as well as the object itself being set).
+ * @returns The Id, determined from the parameter and Store.
  * @category Identity
  * @since v8.3.0
  */
@@ -357,6 +358,7 @@ export function useCreateStore(create: () => Store): Accessor<Store>;
 
 /**
  * The useCreateMergeableStore primitive.
+ * @returns A reference to the MergeableStore.
  * @category Store primitives
  * @since v8.3.0
  */

package/@types/ui-solid/with-schemas/index.d.ts

@@ -449,6 +449,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
 
   /**
  * The useCreateMergeableStore primitive.
+ * @returns A reference to the MergeableStore.
  * @category Store primitives
  * @since v8.3.0
  */