tinybase 5.0.0-beta.1 → 5.0.0-beta.11

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

@@ -22,6 +22,8 @@
  * |persister-expo-sqlite|createExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|
  * |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)|
  *
@@ -39,15 +41,97 @@
  */
 
 import {
-  GetTransactionChanges,
+  Changes,
+  Content,
   OptionalSchemas,
   OptionalTablesSchema,
   Store,
-  Tables,
-  Values,
-} from './store.d';
+} from './store.d.ts';
+import {
+  MergeableChanges,
+  MergeableContent,
+  MergeableStore,
+} from './mergeable-store';
 import {TableIdFromSchema} from './internal/store';
 
+/**
+ * The StoreTypes type
+ */
+export type StoreTypes =
+  | 1 // Store only
+  | 2 // MergeableStore only
+  | 3; // Store and MergeableStore
+
+/**
+ * The PersistedStore type
+ */
+export type PersistedStore<
+  Schemas extends OptionalSchemas,
+  StoreType extends StoreTypes = 1,
+> = StoreType extends 3
+  ? Store<Schemas> | MergeableStore<Schemas>
+  : StoreType extends 2
+    ? MergeableStore<Schemas>
+    : Store<Schemas>;
+
+/**
+ * The PersistedContent type
+ */
+export type PersistedContent<
+  Schemas extends OptionalSchemas,
+  StoreType extends StoreTypes = 1,
+> = StoreType extends 3
+  ? Content<Schemas> | MergeableContent<Schemas>
+  : StoreType extends 2
+    ? MergeableContent<Schemas>
+    : Content<Schemas>;
+
+/**
+ * The PersistedChanges type
+ */
+export type PersistedChanges<
+  Schemas extends OptionalSchemas,
+  StoreType extends StoreTypes = 1,
+> = StoreType extends 3
+  ? Changes<Schemas> | MergeableChanges<Schemas>
+  : StoreType extends 2
+    ? MergeableChanges<Schemas>
+    : Changes<Schemas>;
+
+/**
+ * A PersisterListener is a callback that lets a Persister inform the Store that
+ * a change has happened to the underlying data.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * export type PersisterListener<StoreType extends StoreTypes = 1> = (
+ *   content?: PersistedContent<StoreType>,
+ *   changes?: PersistedChanges<StoreType>,
+ * ) => void;
+ * ```
+ *
+ * If the listener is called with the `changes` parameter, it will be used to
+ * make an incremental change to the Store. If not, but the `content` parameter
+ * is available, that will be used to make a wholesale change to the Store. If
+ * neither are present, the content will be loaded using the Persister's load
+ * method. Prior to v5.0, these parameters were callbacks.
+ * @param content If provided, this is a Content object from the the Persister
+ * that will be used to immediately wholesale update the Store.
+ * @param changes If provided, this is a Changes object from the the Persister
+ * that will be used to immediately incrementally update the Store. This takes
+ * priority over the content argument above if present.
+ * @category Creation
+ * @since v4.0.0
+ */
+export type PersisterListener<
+  Schemas extends OptionalSchemas,
+  StoreType extends StoreTypes = 1,
+> = (
+  content?: PersistedContent<Schemas, StoreType>,
+  changes?: PersistedChanges<Schemas, StoreType>,
+) => void;
+
 /**
  * The PersisterStats type describes the number of times a Persister object has
  * loaded or saved data.
@@ -67,37 +151,6 @@ export type PersisterStats = {
   saves?: number;
 };
 
-/**
- * A PersisterListener is a callback that lets a Persister inform the Store that
- * a change has happened to the underlying data.
- *
- * This has schema-based typing. The following is a simplified representation:
- *
- * ```ts override
- * (
- *   getContent?: () => [Tables, Values],
- *   getTransactionChanges?: GetTransactionChanges,
- * ) => void;
- * ```
- *
- * If the listener has the `getTransactionChanges` parameter, it will be used to
- * make an incremental change to the Store. If not, but the `getContent`
- * function _is_ available, that will be used to make a wholesale change to the
- * Store. If neither are present, the content will be loaded from the
- * Persister's load method.
- * @param getContent An optional function that, if provided, returns an array of
- * Store content and can be used to immediately wholesale update the Store.
- * @param getTransactionChanges An optional function that, if provided, returns
- * a TransactionChanges object and can be used to immediately incrementally
- * update the Store.
- * @category Creation
- * @since v4.0.0
- */
-export type PersisterListener<Schemas extends OptionalSchemas> = (
-  getContent?: () => [Tables<Schemas[0], true>, Values<Schemas[1], true>],
-  getTransactionChanges?: GetTransactionChanges<Schemas>,
-) => void;
-
 /**
  * The DatabasePersisterConfig type describes the configuration of a
  * database-oriented Persister, such as those for SQLite.
@@ -572,9 +625,9 @@ export type DpcTabularValues = {
  *
  * Creating a Persister depends on the choice of underlying storage where the
  * data is to be stored. Options include the createSessionPersister function,
- * the createLocalPersister, the createRemotePersister function, and the
- * createFilePersister function. The createCustomPersister function can also be
- * used to easily create a fully customized way to save and load Store data.
+ * the createLocalPersister function, the createRemotePersister function, and
+ * the createFilePersister function. The createCustomPersister function can also
+ * be used to easily create a fully customized way to save and load Store data.
  *
  * A Persister lets you explicit save or load data, with the save method and the
  * load method respectively. These methods are both asynchronous (since the
@@ -643,7 +696,7 @@ export type DpcTabularValues = {
  * const store = createStore();
  * const persister = createSessionPersister(store, 'pets');
  *
- * await persister.startAutoLoad({pets: {fido: {species: 'dog'}}});
+ * await persister.startAutoLoad([{pets: {fido: {species: 'dog'}}}, {}]);
  * await persister.startAutoSave();
  *
  * store.setTables({pets: {felix: {species: 'cat'}}});
@@ -664,7 +717,10 @@ export type DpcTabularValues = {
  * ```
  * @category Persister
  */
-export interface Persister<in out Schemas extends OptionalSchemas> {
+export interface Persister<
+  in out Schemas extends OptionalSchemas,
+  StoreType extends StoreTypes = 1,
+> {
   /**
    * The load method gets persisted data from storage, and loads it into the
    * Store with which the Persister is associated, once.
@@ -672,10 +728,10 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * load(initialTables?: Tables, initialValues?: Values): Promise<Persister>;
+   * load(initialContent?: Content): Promise<this>;
    * ```
    *
-   * The optional parameters allow you to specify what the initial content for
+   * The optional parameter allows you to specify what the initial content for
    * the Store will be if there is nothing currently persisted or if the load
    * fails (for example when the Persister is remote and the environment is
    * offline). This allows you to fallback or instantiate a Store whether it's
@@ -685,10 +741,8 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * machine or a filesystem. Even for those storage types that are synchronous
    * (like browser storage) it is still recommended that you `await` calls to
    * this method or handle the return type natively as a Promise.
-   * @param initialTables An optional Tables object used when the underlying
+   * @param initialContent An optional Content object used when the underlying
    * storage has not previously been populated.
-   * @param initialValues An optional Values object used when the underlying
-   * storage has not previously been populated, since v3.0.
    * @returns A Promise containing a reference to the Persister object.
    * @example
    * This example creates an empty Store, and loads data into it from the
@@ -717,7 +771,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * const store = createStore();
    * const persister = createSessionPersister(store, 'pets');
    *
-   * await persister.load({pets: {fido: {species: 'dog'}}});
+   * await persister.load([{pets: {fido: {species: 'dog'}}}, {}]);
    * console.log(store.getTables());
    * // -> {pets: {fido: {species: 'dog'}}}
    *
@@ -730,10 +784,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Load
    */
-  load(
-    initialTables?: Tables<Schemas[0], true>,
-    initialValues?: Values<Schemas[1], true>,
-  ): Promise<Persister<Schemas>>;
+  load(initialContent?: Content<Schemas, true>): Promise<this>;
 
   /**
    * The startAutoLoad method gets persisted data from storage, and loads it
@@ -743,13 +794,10 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * startAutoLoad(
-   *   initialTables?: Tables,
-   *   initialValues?: Values,
-   * ): Promise<Persister>;
+   * startAutoLoad(initialContent?: Content): Promise<this>;
    * ```
    *
-   * The optional parameters allow you to specify what the initial content for
+   * The optional parameter allows you to specify what the initial content for
    * the Store will be if there is nothing currently persisted or if the load
    * fails (for example when the Persister is remote and the environment is
    * offline). This allows you to fallback or instantiate a Store whether it's
@@ -764,10 +812,8 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * the asynchronous load method. Even for those storage types that are
    * synchronous (like browser storage) it is still recommended that you `await`
    * calls to this method or handle the return type natively as a Promise.
-   * @param initialTables An optional Tables object used when the underlying
+   * @param initialContent An optional Content object used when the underlying
    * storage has not previously been populated.
-   * @param initialValues An optional Values object used when the underlying
-   * storage has not previously been populated, since v3.0.
    * @returns A Promise containing a reference to the Persister object.
    * @example
    * This example creates an empty Store, and loads data into it from the
@@ -780,7 +826,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * const store = createStore();
    * const persister = createSessionPersister(store, 'pets');
    *
-   * await persister.startAutoLoad({pets: {fido: {species: 'dog'}}});
+   * await persister.startAutoLoad([{pets: {fido: {species: 'dog'}}}, {}]);
    * console.log(store.getTables());
    * // -> {pets: {fido: {species: 'dog'}}}
    *
@@ -797,21 +843,12 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Load
    */
-  startAutoLoad(
-    initialTables?: Tables<Schemas[0], true>,
-    initialValues?: Values<Schemas[1], true>,
-  ): Promise<Persister<Schemas>>;
+  startAutoLoad(initialContent?: Content<Schemas, true>): 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;
-   * ```
-   *
    * If the Persister is not currently set to automatically load, this method
    * has no effect.
    * @returns A reference to the Persister object.
@@ -850,17 +887,38 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Load
    */
-  stopAutoLoad(): Persister<Schemas>;
+  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>;
+   * 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
@@ -884,18 +942,12 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Save
    */
-  save(): Promise<Persister<Schemas>>;
+  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>;
-   * ```
-   *
    * 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.
@@ -927,18 +979,12 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Save
    */
-  startAutoSave(): Promise<Persister<Schemas>>;
+  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;
-   * ```
-   *
    * If the Persister is not currently set to automatically save, this method
    * has no effect.
    * @returns A reference to the Persister object.
@@ -970,17 +1016,38 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Save
    */
-  stopAutoSave(): Persister<Schemas>;
+  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>;
+   * 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
@@ -1019,7 +1086,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * @category Lifecycle
    * @since v4.0.0
    */
-  schedule(...actions: Promise<any>[]): Promise<Persister<Schemas>>;
+  schedule(...actions: Promise<any>[]): Promise<this>;
 
   /**
    * The getStore method returns a reference to the underlying Store that is
@@ -1032,7 +1099,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * getStore(): Store;
+   * getStore(): PersistedStore<StoreType>;
    * ```
    *
    * ```js
@@ -1048,18 +1115,12 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Getter
    */
-  getStore(): Store<Schemas>;
+  getStore(): PersistedStore<Schemas, StoreType>;
 
   /**
    * 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;
-   * ```
-   *
    * 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
@@ -1084,7 +1145,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Lifecycle
    */
-  destroy(): Persister<Schemas>;
+  destroy(): this;
 
   /**
    * The getStats method provides a set of statistics about the Persister, and
@@ -1138,17 +1199,23 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * createCustomPersister<ListeningHandle>(
- *   store: Store,
- *   getPersisted: () => Promise<[Tables, Values] | undefined>,
+ * createCustomPersister<
+ *   ListeningHandle,
+ *   StoreType extends StoreTypes = 1,
+ * >(
+ *   store: PersistedStore<StoreType>,
+ *   getPersisted: () => Promise<PersistedContent<StoreType> | undefined>,
  *   setPersisted: (
- *     getContent: () => [Tables, Values],
- *     getTransactionChanges?: GetTransactionChanges,
+ *     getContent: () => PersistedContent<StoreType>,
+ *     changes?: PersistedChanges<StoreType>,
  *   ) => Promise<void>,
- *   addPersisterListener: (listener: PersisterListener) => ListeningHandle,
+ *   addPersisterListener: (
+ *     listener: PersisterListener<StoreType>,
+ *   ) => ListeningHandle,
  *   delPersisterListener: (listeningHandle: ListeningHandle) => void,
  *   onIgnoredError?: (error: any) => void,
- * ): Persister;
+ *   supportedStoreType?: StoreType,
+ * ): Persister<StoreType>;
  * ```
  *
  * As well as providing a reference to the Store to persist, you must provide
@@ -1173,7 +1240,9 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
  * the persistence layer (or `undefined` if not present).
  * @param setPersisted An asynchronous function which will send content to the
  * persistence layer. Since v4.0, it receives functions for getting the Store
- * content and information about the changes made during a transaction.
+ * content and information about the changes made during a transaction. Since
+ * v5.0, the changes are received directly by reference, rather than an
+ * accessor.
  * @param addPersisterListener A function that will register a `listener`
  * listener on underlying changes to the persistence layer. You can return a
  * listening handle that will be provided again when `delPersisterListener` is
@@ -1184,6 +1253,9 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
  * @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, since v4.0.4.
+ * @param supportsMergeableStore An optional boolean to indicate that this
+ * Persister will be able to handle MergeableStore persistence as well as
+ * regular Store persistence, since v5.0.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a custom Persister object and persists the Store to a
@@ -1225,18 +1297,18 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
 export function createCustomPersister<
   Schemas extends OptionalSchemas,
   ListeningHandle,
+  StoreType extends StoreTypes = 1,
 >(
-  store: Store<Schemas>,
-  getPersisted: () => Promise<
-    [Tables<Schemas[0]>, Values<Schemas[1]>] | undefined
-  >,
+  store: PersistedStore<Schemas, StoreType>,
+  getPersisted: () => Promise<PersistedContent<Schemas, StoreType> | undefined>,
   setPersisted: (
-    getContent: () => [Tables<Schemas[0]>, Values<Schemas[1]>],
-    getTransactionChanges?: GetTransactionChanges<Schemas>,
+    getContent: () => PersistedContent<Schemas, StoreType>,
+    changes?: PersistedChanges<Schemas, StoreType>,
   ) => Promise<void>,
   addPersisterListener: (
-    listener: PersisterListener<Schemas>,
+    listener: PersisterListener<Schemas, StoreType>,
   ) => ListeningHandle,
   delPersisterListener: (listeningHandle: ListeningHandle) => void,
   onIgnoredError?: (error: any) => void,
-): Persister<Schemas>;
+  supportedStoreType?: StoreType,
+): Persister<Schemas, StoreType>;

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