tinybase 5.0.0-beta.3 → 5.0.0-beta.5

package/lib/types/mergeable-store.d.ts

@@ -8,38 +8,55 @@ import {CellOrUndefined, Store, ValueOrUndefined} from './store.d';
 import {Id} from './common';
 import {IdObj} from '../common/obj';
 
+/**
+ * The Hash type
+ * @category Stamps
+ */
+export type Hash = number;
+
 /**
  * The Time type
  * @category Stamps
  */
 export type Time = string;
 
+/**
+ * The HashStamp type
+ * @category Stamps
+ */
+export type HashStamp<Thing> = [time: Time, thing: Thing, hash: Hash];
+
 /**
  * The Stamp type
  * @category Stamps
  */
 export type Stamp<Thing> = [time: Time, thing: Thing];
 
-type MergeableCell = Stamp<CellOrUndefined>;
-type MergeableRow = Stamp<IdObj<MergeableCell>>;
-type MergeableTable = Stamp<IdObj<MergeableRow>>;
-type MergeableTables = Stamp<IdObj<MergeableTable>>;
-type MergeableValue = Stamp<ValueOrUndefined>;
-type MergeableValues = Stamp<IdObj<MergeableValue>>;
-
 /**
  * The MergeableContent type
  * @category Mergeable
  */
-export type MergeableContent = Stamp<
-  [mergeableTables: MergeableTables, mergeableValues: MergeableValues]
+export type MergeableContent = HashStamp<
+  [
+    mergeableTables: HashStamp<
+      IdObj<HashStamp<IdObj<HashStamp<IdObj<HashStamp<CellOrUndefined>>>>>>
+    >,
+    mergeableValues: HashStamp<IdObj<HashStamp<ValueOrUndefined>>>,
+  ]
 >;
 
 /**
  * The MergeableChanges type
  * @category Mergeable
  */
-export type MergeableChanges = MergeableContent;
+export type MergeableChanges = Stamp<
+  [
+    mergeableTables: Stamp<
+      IdObj<Stamp<IdObj<Stamp<IdObj<Stamp<CellOrUndefined>>>>>>
+    >,
+    mergeableValues: Stamp<IdObj<Stamp<ValueOrUndefined>>>,
+  ]
+>;
 
 /**
  * The MergeableStore type
@@ -65,11 +82,61 @@ export interface MergeableStore extends Store {
    */
   setMergeableContent(mergeableContent: MergeableContent): MergeableStore;
 
+  /**
+   * The getTransactionMergeableChanges method
+   * @category Merging
+   */
+  getTransactionMergeableChanges(): MergeableChanges;
+
   /**
    * The applyMergeableChanges method
    * @category Merging
    */
-  applyMergeableChanges(mergeableChanges: MergeableChanges): MergeableStore;
+  applyMergeableChanges(
+    mergeableChanges: MergeableChanges | MergeableContent,
+  ): MergeableStore;
+
+  /**
+   * The getContentHash method
+   * @category Hashes
+   */
+  getContentHash(): Hash;
+
+  /**
+   * The getTablesHash method
+   * @category Hashes
+   */
+  getTablesHash(): Hash;
+
+  /**
+   * The getTableHash method
+   * @category Hashes
+   */
+  getTableHash(tableId: Id): Hash;
+
+  /**
+   * The getRowHash method
+   * @category Hashes
+   */
+  getRowHash(tableId: Id, rowId: Id): Hash;
+
+  /**
+   * The getCellHash method
+   * @category Hashes
+   */
+  getCellHash(tableId: Id, rowId: Id, cellId: Id): Hash;
+
+  /**
+   * The getValuesHash method
+   * @category Hashes
+   */
+  getValuesHash(): Hash;
+
+  /**
+   * The getValueHash method
+   * @category Hashes
+   */
+  getValueHash(valueId: Id): Hash;
 }
 
 /**

package/lib/types/persisters/persister-browser.d.ts

@@ -26,7 +26,7 @@ import {Store} from '../store';
  * @category Persister
  * @since v4.3.14
  */
-export interface SessionPersister extends Persister {
+export interface SessionPersister extends Persister<true> {
   /**
    * The getStorageName method returns the unique key of the storage location
    * the Store is being persisted to.
@@ -58,7 +58,7 @@ export interface SessionPersister extends Persister {
  * @category Persister
  * @since v4.3.14
  */
-export interface LocalPersister extends Persister {
+export interface LocalPersister extends Persister<true> {
   /**
    * The getStorageName method returns the unique key of the storage location
    * the Store is being persisted to.

package/lib/types/persisters/persister-file.d.ts

@@ -17,7 +17,7 @@ import {Store} from '../store';
  * @category Persister
  * @since v4.3.14
  */
-export interface FilePersister extends Persister {
+export interface FilePersister extends Persister<true> {
   /**
    * The getFilePath method returns the location of the local file the Store is
    * being persisted to.

package/lib/types/persisters/persister-libsql.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The persister-libsql module of the TinyBase project lets you save and load
+ * Store data to and from a local LibSQL database (in an appropriate
+ * environment).
+ * @see Persisting Data guide
+ * @packageDocumentation
+ * @module persister-libsql
+ * @since v4.7.0
+ */
+
+import {DatabasePersisterConfig, Persister} from '../persisters';
+import {Client} from '@libsql/client';
+import {Store} from '../store';
+
+/**
+ * The LibSqlPersister interface is a minor extension to the Persister
+ * interface.
+ *
+ * It simply provides an extra getClient method for accessing a reference to the
+ * database client the Store is being persisted to.
+ * @since v4.7.0
+ */
+export interface LibSqlPersister extends Persister {
+  /**
+   * The getClient method returns a reference to the database client the Store
+   * is being persisted to.
+   * @returns A reference to the database client.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the database client back out again.
+   *
+   * ```js yolo
+   * const client = createClient({url: 'file:my.db'});
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createLibSqlPersister(store, client, 'my_tinybase');
+   *
+   * console.log(persister.getClient() == client);
+   * // -> true
+   *
+   * persister.destroy();
+   * ```
+   * @category Getter
+   * @since v4.7.0
+   */
+  getClient(): Client;
+}
+
+/**
+ * The createLibSqlPersister function creates a Persister object that can
+ * persist the Store to a local LibSQL database (in an appropriate environment).
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `client` parameter which identifies the database client.
+ *
+ * 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.
+ * @param store The Store to persist.
+ * @param db The database client that was returned from `createClient(...)`.
+ * @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 LibSqlPersister object.
+ * @example
+ * This example creates a LibSqlPersister object and persists the Store to a
+ * local SQLite 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 yolo
+ * const client = createClient({url: 'file:my.db'});
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createLibSqlPersister(store, client, 'my_tinybase');
+ *
+ * await persister.save();
+ * // Store will be saved to the database.
+ *
+ * console.log((await client.execute('SELECT * FROM my_tinybase;')).rows);
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * await client.execute(
+ *   'UPDATE my_tinybase SET store = ' +
+ *     `'[{"pets":{"felix":{"species":"cat"}}},{}]' WHERE _id = '_';`,
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @example
+ * This example creates a LibSqlPersister object and persists the Store to a
+ * local SQLite database with tabular mapping.
+ *
+ * ```js yolo
+ * const client = createClient({url: 'file:my.db'});
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createLibSqlPersister(store, client, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log((await client.execute('SELECT * FROM pets;')).rows);
+ * // -> [{_id: 'fido', species: 'dog'}]
+ *
+ * await client.execute(
+ *   `INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`,
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ * @since v4.7.0
+ */
+export function createLibSqlPersister(
+  store: Store,
+  client: Client,
+  configOrStoreTableName?: DatabasePersisterConfig | string,
+  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): LibSqlPersister;

package/lib/types/persisters.d.ts

@@ -22,6 +22,7 @@
  * |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-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,7 +40,11 @@
  */
 
 import {Changes, Content, Store, Tables, Values} from './store.d';
-import {MergeableContent, MergeableStore} from './mergeable-store';
+import {
+  MergeableChanges,
+  MergeableContent,
+  MergeableStore,
+} from './mergeable-store';
 import {Id} from './common.d';
 
 /**
@@ -77,10 +82,15 @@ export type PersisterStats = {
  * @category Creation
  * @since v4.0.0
  */
-export type PersisterListener = (
-  getContent?: () => Content,
-  getChanges?: () => Changes,
-) => void;
+export type PersisterListener<SupportsMergeableStore extends boolean = false> =
+  (
+    getContent?: () =>
+      | Content
+      | (SupportsMergeableStore extends true ? MergeableContent : never),
+    getChanges?: () =>
+      | Changes
+      | (SupportsMergeableStore extends true ? MergeableChanges : never),
+  ) => void;
 
 /**
  * The DatabasePersisterConfig type describes the configuration of a
@@ -1136,7 +1146,7 @@ export interface Persister<SupportsMergeableStore extends boolean = false> {
  */
 export function createCustomPersister<
   ListeningHandle,
-  SupportsMergeableStore extends boolean,
+  SupportsMergeableStore extends boolean = false,
 >(
   store: Store | (SupportsMergeableStore extends true ? MergeableStore : never),
   getPersisted: () => Promise<
@@ -1150,7 +1160,9 @@ export function createCustomPersister<
       | (SupportsMergeableStore extends true ? MergeableContent : never),
     getChanges?: () => Changes,
   ) => Promise<void>,
-  addPersisterListener: (listener: PersisterListener) => ListeningHandle,
+  addPersisterListener: (
+    listener: PersisterListener<SupportsMergeableStore>,
+  ) => ListeningHandle,
   delPersisterListener: (listeningHandle: ListeningHandle) => void,
   onIgnoredError?: (error: any) => void,
   supportsMergeableStore?: SupportsMergeableStore,