tinybase 5.0.0-beta.5 → 5.0.0-beta.7

package/lib/types/with-schemas/persisters.d.ts

@@ -23,6 +23,7 @@
  * |persister-expo-sqlite-next|createExpoSqliteNextPersister|SQLite in React Native, via [expo-sqlite/next](https://github.com/expo/expo/tree/main/packages/expo-sqlite/next)|
  * |persister-electric-sql|createElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|
  * |persister-libsql|createLibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|
+ * |persister-powersync|createPowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|
  * |persister-yjs|createYjsPersister|Yjs CRDTs, via [yjs](https://github.com/yjs/yjs)|
  * |persister-automerge|createSqliteWasmPersister|Automerge CRDTs, via [automerge-repo](https://github.com/automerge/automerge-repo)|
  *
@@ -47,8 +48,12 @@ import {
   Store,
   Tables,
   Values,
-} from './store.d';
-import {MergeableContent, MergeableStore} from './mergeable-store';
+} from './store.d.ts';
+import {
+  MergeableChanges,
+  MergeableContent,
+  MergeableStore,
+} from './mergeable-store';
 import {TableIdFromSchema} from './internal/store';
 
 /**
@@ -100,9 +105,16 @@ export type PersisterStats = {
  * @category Creation
  * @since v4.0.0
  */
-export type PersisterListener<Schemas extends OptionalSchemas> = (
-  getContent?: () => Content<Schemas, true>,
-  getChanges?: () => Changes<Schemas>,
+export type PersisterListener<
+  Schemas extends OptionalSchemas,
+  SupportsMergeableStore extends boolean = false,
+> = (
+  getContent?: () =>
+    | Content<Schemas, true>
+    | (SupportsMergeableStore extends true ? MergeableContent<Schemas> : never),
+  getChanges?: () =>
+    | Changes<Schemas>
+    | (SupportsMergeableStore extends true ? MergeableChanges<Schemas> : never),
 ) => void;
 
 /**
@@ -682,10 +694,7 @@ export interface Persister<
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * load(
-   *   initialTables?: Tables,
-   *   initialValues?: Values,
-   * ): Promise<Persister<SupportsMergeableStore>>;
+   * load(initialTables?: Tables, initialValues?: Values): Promise<this>;
    * ```
    *
    * The optional parameters allow you to specify what the initial content for
@@ -746,7 +755,7 @@ export interface Persister<
   load(
     initialTables?: Tables<Schemas[0], true>,
     initialValues?: Values<Schemas[1], true>,
-  ): Promise<Persister<Schemas, SupportsMergeableStore>>;
+  ): Promise<this>;
 
   /**
    * The startAutoLoad method gets persisted data from storage, and loads it
@@ -756,10 +765,7 @@ export interface Persister<
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * startAutoLoad(
-   *   initialTables?: Tables,
-   *   initialValues?: Values,
-   * ): Promise<Persister<SupportsMergeableStore>>;
+   * startAutoLoad(initialTables?: Tables, initialValues?: Values): Promise<this>;
    * ```
    *
    * The optional parameters allow you to specify what the initial content for
@@ -813,18 +819,12 @@ export interface Persister<
   startAutoLoad(
     initialTables?: Tables<Schemas[0], true>,
     initialValues?: Values<Schemas[1], true>,
-  ): Promise<Persister<Schemas, SupportsMergeableStore>>;
+  ): Promise<this>;
 
   /**
    * The stopAutoLoad method stops the automatic loading of data from storage
    * previously started with the startAutoLoad method.
    *
-   * This has schema-based typing. The following is a simplified representation:
-   *
-   * ```ts override
-   * stopAutoLoad(): Persister<SupportsMergeableStore>;
-   * ```
-   *
    * If the Persister is not currently set to automatically load, this method
    * has no effect.
    * @returns A reference to the Persister object.
@@ -863,17 +863,38 @@ export interface Persister<
    * ```
    * @category Load
    */
-  stopAutoLoad(): Persister<Schemas, SupportsMergeableStore>;
+  stopAutoLoad(): this;
 
   /**
-   * The save method takes data from the Store with which the Persister is
-   * associated and persists it into storage, once.
+   * The isAutoLoading method lets you find out if the Persister is currently
+   * automatically loading its content.
+   * @returns A boolean indicating whether the Persister is currently
+   * autoLoading.
+   * @example
+   * This example creates a Persister and queries whether it is autoLoading.
    *
-   * This has schema-based typing. The following is a simplified representation:
+   * ```js
+   * const persister = createSessionPersister(createStore(), 'pets');
    *
-   * ```ts override
-   * save(): Promise<Persister<SupportsMergeableStore>>;
+   * console.log(persister.isAutoLoading());
+   * // -> false
+   *
+   * await persister.startAutoLoad();
+   * console.log(persister.isAutoLoading());
+   * // -> true
+   *
+   * await persister.stopAutoLoad();
+   * console.log(persister.isAutoLoading());
+   * // -> false
    * ```
+   * @category Load
+   * @since v5.0.0
+   */
+  isAutoLoading(): boolean;
+
+  /**
+   * The save method takes data from the Store with which the Persister is
+   * associated and persists it into storage, once.
    *
    * This method is asynchronous because the persisted data may be on a remote
    * machine or a filesystem. Even for those storage types that are synchronous
@@ -897,18 +918,12 @@ export interface Persister<
    * ```
    * @category Save
    */
-  save(): Promise<Persister<Schemas, SupportsMergeableStore>>;
+  save(): Promise<this>;
 
   /**
    * The save method takes data from the Store with which the Persister is
    * associated and persists it into storage, once, and then continuously.
    *
-   * This has schema-based typing. The following is a simplified representation:
-   *
-   * ```ts override
-   * startAutoSave(): Promise<Persister<SupportsMergeableStore>>;
-   * ```
-   *
    * This method first runs a single call to the save method to ensure the data
    * is in sync with the persisted storage. It then continues to watch for
    * changes to the Store, automatically saving the data to storage.
@@ -940,18 +955,12 @@ export interface Persister<
    * ```
    * @category Save
    */
-  startAutoSave(): Promise<Persister<Schemas, SupportsMergeableStore>>;
+  startAutoSave(): Promise<this>;
 
   /**
    * The stopAutoSave method stops the automatic save of data to storage
    * previously started with the startAutoSave method.
    *
-   * This has schema-based typing. The following is a simplified representation:
-   *
-   * ```ts override
-   * stopAutoSave(): Persister<SupportsMergeableStore>;
-   * ```
-   *
    * If the Persister is not currently set to automatically save, this method
    * has no effect.
    * @returns A reference to the Persister object.
@@ -983,19 +992,38 @@ export interface Persister<
    * ```
    * @category Save
    */
-  stopAutoSave(): Persister<Schemas, SupportsMergeableStore>;
+  stopAutoSave(): this;
 
   /**
-   * The schedule method allows you to queue up a series of asynchronous actions
-   * that must run in sequence during persistence.
+   * The isAutoSaving method lets you find out if the Persister is currently
+   * automatically saving its content.
+   * @returns A boolean indicating whether the Persister is currently
+   * autoSaving.
+   * @example
+   * This example creates a Persister and queries whether it is autoSaving.
    *
-   * This has schema-based typing. The following is a simplified representation:
+   * ```js
+   * const persister = createSessionPersister(createStore(), 'pets');
    *
-   * ```ts override
-   * schedule(
-   *   ...actions: Promise<any>[]
-   * ): Promise<Persister<SupportsMergeableStore>>;
+   * console.log(persister.isAutoSaving());
+   * // -> false
+   *
+   * await persister.startAutoSave();
+   * console.log(persister.isAutoSaving());
+   * // -> true
+   *
+   * await persister.stopAutoSave();
+   * console.log(persister.isAutoSaving());
+   * // -> false
    * ```
+   * @category Save
+   * @since v5.0.0
+   */
+  isAutoSaving(): boolean;
+
+  /**
+   * The schedule method allows you to queue up a series of asynchronous actions
+   * that must run in sequence during persistence.
    *
    * For example, a database Persister may need to ensure that multiple
    * asynchronous tasks to check and update the database schema are completed
@@ -1034,9 +1062,7 @@ export interface Persister<
    * @category Lifecycle
    * @since v4.0.0
    */
-  schedule(
-    ...actions: Promise<any>[]
-  ): Promise<Persister<Schemas, SupportsMergeableStore>>;
+  schedule(...actions: Promise<any>[]): Promise<this>;
 
   /**
    * The getStore method returns a reference to the underlying Store that is
@@ -1067,18 +1093,14 @@ export interface Persister<
    * ```
    * @category Getter
    */
-  getStore(): Store<Schemas>;
+  getStore(): SupportsMergeableStore extends true
+    ? Store<Schemas> | MergeableStore<Schemas>
+    : Store<Schemas>;
 
   /**
    * The destroy method should be called when this Persister object is no longer
    * used.
    *
-   * This has schema-based typing. The following is a simplified representation:
-   *
-   * ```ts override
-   * destroy(): Persister<SupportsMergeableStore>;
-   * ```
-   *
    * This guarantees that all of the listeners that the object registered with
    * the underlying Store and storage are removed and it can be correctly
    * garbage collected. It is equivalent to running the stopAutoLoad method and
@@ -1103,7 +1125,7 @@ export interface Persister<
    * ```
    * @category Lifecycle
    */
-  destroy(): Persister<Schemas, SupportsMergeableStore>;
+  destroy(): this;
 
   /**
    * The getStats method provides a set of statistics about the Persister, and
@@ -1171,7 +1193,9 @@ export interface Persister<
  *     getContent: () =>
  *       | Content
  *       | (SupportsMergeableStore extends true ? MergeableContent : never),
- *     getChanges?: () => Changes,
+ *     getChanges?: () =>
+ *       | Changes
+ *       | (SupportsMergeableStore extends true ? MergeableChanges : never),
  *   ) => Promise<void>,
  *   addPersisterListener: (
  *     listener: PersisterListener<SupportsMergeableStore>,
@@ -1275,7 +1299,11 @@ export function createCustomPersister<
       | (SupportsMergeableStore extends true
           ? MergeableContent<Schemas>
           : never),
-    getChanges?: () => Changes<Schemas>,
+    getChanges?: () =>
+      | Changes<Schemas>
+      | (SupportsMergeableStore extends true
+          ? MergeableChanges<Schemas>
+          : never),
   ) => Promise<void>,
   addPersisterListener: (
     listener: PersisterListener<Schemas>,

package/lib/types/with-schemas/queries.d.ts

@@ -19,11 +19,11 @@ import {
   OptionalSchemas,
   OptionalTablesSchema,
   Store,
-} from './store.d';
+} from './store.d.ts';
 import {CellIdFromSchema, TableIdFromSchema} from './internal/store';
 import {GetResultCell, JoinedCellIdOrId} from './internal/queries';
-import {Id, IdOrNull, Ids} from './common.d';
-import {GetIdChanges} from '../store.d';
+import {Id, IdOrNull, Ids} from './common.d.ts';
+import {GetIdChanges} from '../store.d.ts';
 
 /**
  * The ResultTable type is the data structure representing the results of a

package/lib/types/with-schemas/relationships.d.ts

@@ -17,8 +17,8 @@ import {
   OptionalTablesSchema,
   RowCallback,
   Store,
-} from './store.d';
-import {Id, IdOrNull, Ids} from './common.d';
+} from './store.d.ts';
+import {Id, IdOrNull, Ids} from './common.d.ts';
 
 /**
  * The Relationship type represents the concept of a map that connects one Row

package/lib/types/with-schemas/store.d.ts

@@ -22,7 +22,7 @@ import {
   Truncate,
   ValueIdFromSchema,
 } from './internal/store';
-import {Id, IdOrNull, Ids, Json} from './common.d';
+import {Id, IdOrNull, Ids, Json} from './common.d.ts';
 
 /**
  * The TablesSchema type describes the tabular structure of a Store in terms of
@@ -167,7 +167,41 @@ export type OptionalSchemas = [OptionalTablesSchema, OptionalValuesSchema];
  */
 export type NoSchemas = [NoTablesSchema, NoValuesSchema];
 
-// Content
+/**
+ * The Content type describes both the Tables and Values in a Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * [Tables, Values];
+ * ```
+ *
+ * It is an array of two objects, representing tabular and keyed value content.
+ * @example
+ * The following is a valid Content array:
+ * ```json
+ * [
+ *   {
+ *     "pets": {
+ *       "fido": {
+ *         "sold": false,
+ *         "price": 4,
+ *       },
+ *       "felix": {
+ *         "sold": true,
+ *         "price": 5,
+ *       },
+ *     },
+ *   },
+ *   {
+ *     open: true,
+ *     employees: 3,
+ *   },
+ * ]
+ * ```
+ * @category Store
+ * @since v5.0.0
+ */
 export type Content<
   Schemas extends OptionalSchemas,
   WhenSet extends boolean = false,
@@ -2207,7 +2241,69 @@ export type ChangedValue<
  */
 export type InvalidValues = {[valueId: Id]: any[]};
 
-//
+/**
+ * The Changes type describes the net meaningful changes that were made to a
+ * Store during a transaction.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * [
+ *   changedTables: {
+ *     [tableId: Id]:
+ *       | {[rowId: Id]: {[cellId: Id]: CellOrUndefined} | undefined}
+ *       | undefined;
+ *   },
+ *   changedValues: {[valueId: Id]: ValueOrUndefined},
+ *   isChanges: 1,
+ * ];
+ * ```
+ *
+ * This contains mostly equivalent information to a TransactionLog, but in a
+ * form that can be more efficiently parsed and serialized (for example in the
+ * case of synchronization between systems).
+ *
+ * It is an array of two objects, representing tabular and keyed value changes.
+ * If the first item is an empty object, it means no tabular changes were made.
+ * If the second item is an empty object, it means no keyed value changes were
+ * made.
+ *
+ * If not empty, the first object has an entry for each Table in a Store that
+ * has had a change within it. If the entry is null, it means that whole Table
+ * was deleted. Otherwise, the entry will be an object with an entry for each
+ * Row in that Table that had a change within it. In turn, if that entry is
+ * null, it means the Row was deleted. Otherwise, the entry will be an object
+ * with an entry for each Cell in that Row that had a change within it. If the
+ * entry is null, the Cell was deleted, otherwise it will contain the new value
+ * the Cell was changed to during the transaction.
+ *
+ * If not empty, the second object has an entry for each Value in a Store that
+ * has had a change. If the entry is null, the Value was deleted, otherwise it
+ * will contain the new Value it was changed to during the transaction.
+ *
+ * A third, required, item in the array is the digit `1`, so that instances of
+ * Content and Changes types can be disambiguated.
+ * @example
+ * The following is a valid Changes array that conveys the following:
+ * ```json
+ * [
+ *   {                     // changes to tabular data in the Store
+ *     "pets": {             // this Table was changed
+ *       "fido": null,         // this Row was deleted
+ *       "felix": {            // this Row was changed
+ *         "sold": true,         // this Cell was changed
+ *         "price": null,        // this Cell was deleted
+ *       },
+ *     },
+ *     "pendingSales": null, // this Table was deleted
+ *   },
+ *   {},                   // no changes to keyed value data in the Store
+ *   1,                    // indicates that this is a Changes array
+ * ]
+ * ```
+ * @category Transaction
+ * @since v4.0.0
+ */
 export type Changes<Schemas extends OptionalSchemas> = [
   {
     [TableId in TableIdFromSchema<Schemas[0]>]?:
@@ -2226,6 +2322,7 @@ export type Changes<Schemas extends OptionalSchemas> = [
   {
     [ValueId in ValueIdFromSchema<Schemas[1]>]?: Value<Schemas[1], ValueId>;
   },
+  isChanges: 1,
 ];
 
 /**

package/lib/types/with-schemas/synchronizers/synchronizer-local.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The synchronizer-local module of the TinyBase project lets you synchronize
+ * MergeableStore data to and from other MergeableStore instances on the same
+ * local machine.
+ * @see Synchronizing Data guide
+ * @packageDocumentation
+ * @module synchronizer-local
+ * @since v5.0.0
+ */
+
+import {MergeableStore} from '../mergeable-store';
+import {OptionalSchemas} from '../store';
+import {Synchronizer} from '../synchronizers';
+
+/**
+ * The LocalSynchronizer interface
+ * @category Synchronizer
+ */
+export interface LocalSynchronizer<Schemas extends OptionalSchemas>
+  extends Synchronizer<Schemas> {}
+
+/**
+ * The createLocalSynchronizer function
+ * @category Creation
+ */
+export function createLocalSynchronizer<Schemas extends OptionalSchemas>(
+  store: MergeableStore<Schemas>,
+  onIgnoredError?: (error: any) => void,
+): LocalSynchronizer<Schemas>;

package/lib/types/with-schemas/synchronizers/synchronizer-ws-client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The synchronizer-ws module of the TinyBase project lets you synchronize
+ * MergeableStore data to and from other MergeableStore instances via WebSockets
+ * facilitated by a server.
+ * @see Synchronizing Data guide
+ * @packageDocumentation
+ * @module synchronizer-ws-client
+ * @since v5.0.0
+ */
+
+import {MergeableStore} from '../mergeable-store';
+import {OptionalSchemas} from '../store';
+import {Synchronizer} from '../synchronizers';
+import {WebSocket} from 'ws';
+
+/**
+ * The WsSynchronizer interface
+ * @category Synchronizer
+ */
+export interface WsSynchronizer<Schemas extends OptionalSchemas>
+  extends Synchronizer<Schemas> {}
+
+/**
+ * The createWsSynchronizer function
+ * @category Creation
+ */
+export function createWsSynchronizer<Schemas extends OptionalSchemas>(
+  store: MergeableStore<Schemas>,
+  webSocket: WebSocket,
+  requestTimeoutSeconds?: number,
+  onIgnoredError?: (error: any) => void,
+): Promise<WsSynchronizer<Schemas>>;

package/lib/types/with-schemas/synchronizers/synchronizer-ws-server.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The synchronizer-ws-server module of the TinyBase project lets you create
+ * a server that facilitates synchronization between clients.
+ * @see Synchronizing Data guide
+ * @packageDocumentation
+ * @module synchronizer-ws-server
+ * @since v5.0.0
+ */
+
+import {WebSocketServer} from 'ws';
+
+/**
+ * The WsServer interface
+ */
+export interface WsServer {
+  getWebSocketServer: () => WebSocketServer;
+  destroy: () => void;
+}
+
+/**
+ * The createWsServer function
+ * @category Creation
+ */
+export function createWsServer(WebSocketServer: WebSocketServer): WsServer;

package/lib/types/with-schemas/synchronizers.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The persister-sync module of the TinyBase project lets you synchronize
+ * MergeableStore data to and from other MergeableStore instances.
+ * @see Synchronizing Data guide
+ * @packageDocumentation
+ * @module synchronizers
+ * @since v5.0.0
+ */
+
+import {Id, IdOrNull} from './common';
+import {MergeableStore} from './mergeable-store';
+import {OptionalSchemas} from './store';
+import {Persister} from './persisters';
+
+/**
+ * The MessageType type
+ * @category Synchronization
+ */
+export type MessageType = number;
+
+/**
+ * The Receive type
+ * @category Synchronization
+ */
+export type Receive = (
+  fromClientId: Id,
+  requestId: Id,
+  messageType: MessageType,
+  messageBody: any,
+) => void;
+
+/**
+ * The Send type
+ * @category Synchronization
+ */
+export type Send = (
+  toClientId: IdOrNull,
+  requestId: Id,
+  messageType: MessageType,
+  messageBody: any,
+) => void;
+
+/**
+ * The SynchronizerStats type
+ * @category Development
+ */
+export type SynchronizerStats = {
+  sends?: number;
+  receives?: number;
+};
+
+/**
+ * The Synchronizer interface is a minor extension to the Persister interface.
+ *
+ * It provides extra convenience methods for starting and stopping the
+ * synchronization.
+ *
+ * You should use the createCustomSynchronizer function to create a Synchronizer
+ * object.
+ * @category Synchronizer
+ * @since v5.0.0
+ */
+export interface Synchronizer<Schemas extends OptionalSchemas>
+  extends Persister<Schemas, true> {
+  /**
+   * The startSync method
+   * @category Synchronization
+   */
+  startSync(): Promise<this>;
+  /**
+   * The stopSync method
+   * @category Synchronization
+   */
+  stopSync(): this;
+  /**
+   * The getSynchronizerStats method
+   * @category Synchronization
+   */
+  getSynchronizerStats(): SynchronizerStats;
+}
+
+/**
+ * The createCustomSynchronizer function creates a Synchronizer object that can
+ * persist one MergeableStore to another.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createCustomSynchronizer(
+ *   store: MergeableStore,
+ *   send: Send,
+ *   onReceive: (receive: Receive) => void,
+ *   destroy: () => void,
+ *   requestTimeoutSeconds?: number,
+ *   onIgnoredError?: (error: any) => void,
+ * ): Synchronizer;
+ * ```
+ *
+ * As well as providing a reference to the MergeableStore to synchronize, you
+ * must provide a `client` parameter which identifies the Client that is used to
+ * transmit changes to and from this MergeableStore and its peers.
+ * @param store The MergeableStore to synchronize.
+ * @param client The reference of the Client.
+ * @param requestTimeoutSeconds An optional number of seconds before a request
+ * to the Client times out, defaulting to 5.
+ * @param onIgnoredError An optional handler for the errors that the
+ * Synchronizer would otherwise ignore when trying to save or load data. This is
+ * suitable for debugging synchronization issues in a development environment.
+ * @returns A reference to the new Synchronizer object.
+ * @example
+ * This example creates a Synchronizer object and synchronizes one
+ * MergeableStore to another.
+ *
+ * ```js
+ * const store1 = createMergeableStore('store1').setTables({
+ *   pets: {fido: {species: 'dog'}},
+ * });
+ * const synchronizer1 = createLocalSynchronizer(store1);
+ *
+ * const store2 = createMergeableStore('store2');
+ * const synchronizer2 = createLocalSynchronizer(store2);
+ * await synchronizer2.startSync();
+ *
+ * await synchronizer1.save();
+ * // ...
+ * // Store2 will be synced with Store1.
+ *
+ * console.log(store2.getTables());
+ * // -> {pets: {fido: {species: 'dog'}}}
+ *
+ * await synchronizer1.load();
+ * // Store1 will be synced with Store2.
+ *
+ * synchronizer1.destroy();
+ * synchronizer2.destroy();
+ * ```
+ * @category Creation
+ */
+export function createCustomSynchronizer<Schemas extends OptionalSchemas>(
+  store: MergeableStore<Schemas>,
+  send: Send,
+  onReceive: (receive: Receive) => void,
+  destroy: () => void,
+  requestTimeoutSeconds?: number,
+  onIgnoredError?: (error: any) => void,
+): Synchronizer<Schemas>;