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

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

@@ -5,60 +5,70 @@
  */
 
 import {
-  Cell,
+  CellIdFromSchema,
+  TableIdFromSchema,
+  ValueIdFromSchema,
+} from './internal/store';
+import {
+  CellOrUndefined,
   NoSchemas,
+  NoTablesSchema,
+  NoValuesSchema,
   OptionalSchemas,
   OptionalTablesSchema,
   OptionalValuesSchema,
   Store,
-  Value,
+  TablesSchema,
+  ValueOrUndefined,
+  ValuesSchema,
 } 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<Schema extends OptionalTablesSchema> = Stamp<Cell<
-  Schema,
-  any,
-  any
-> | null>;
-type MergeableRow<Schema extends OptionalTablesSchema> = Stamp<IdObj<
-  MergeableCell<Schema>
-> | null>;
-type MergeableTable<Schema extends OptionalTablesSchema> = Stamp<IdObj<
-  MergeableRow<Schema>
-> | null>;
-type MergeableTables<Schema extends OptionalTablesSchema> = Stamp<
-  IdObj<MergeableTable<Schema>>
->;
-type MergeableValue<Schema extends OptionalValuesSchema> = Stamp<Value<
-  Schema,
-  any,
-  any
-> | null>;
-type MergeableValues<Schema extends OptionalValuesSchema> = Stamp<
-  IdObj<MergeableValue<Schema>>
->;
-
 /**
  * The MergeableContent type
  * @category Mergeable
  */
-export type MergeableContent<Schemas extends OptionalSchemas> = Stamp<
+export type MergeableContent<Schemas extends OptionalSchemas> = HashStamp<
   [
-    mergeableTables: MergeableTables<Schemas[0]>,
-    mergeableValues: MergeableValues<Schemas[1]>,
+    mergeableTables: HashStamp<{
+      [TableId in TableIdFromSchema<Schemas[0]>]?: HashStamp<{
+        [rowId: Id]: HashStamp<{
+          [CellId in CellIdFromSchema<Schemas[0], TableId>]?: HashStamp<
+            CellOrUndefined<Schemas[0], TableId, CellId>
+          >;
+        }>;
+      }>;
+    }>,
+    mergeableValues: HashStamp<{
+      [ValueId in ValueIdFromSchema<Schemas[1]>]?: HashStamp<
+        ValueOrUndefined<Schemas[1], ValueId>
+      >;
+    }>,
   ]
 >;
 
@@ -66,8 +76,26 @@ export type MergeableContent<Schemas extends OptionalSchemas> = Stamp<
  * The MergeableChanges type
  * @category Mergeable
  */
-export type MergeableChanges<Schemas extends OptionalSchemas> =
-  MergeableContent<Schemas>;
+export type MergeableChanges<Schemas extends OptionalSchemas> = Stamp<
+  [
+    mergeableTables: Stamp<{
+      [TableId in TableIdFromSchema<Schemas[0]>]?: Stamp<
+        IdObj<
+          Stamp<{
+            [CellId in CellIdFromSchema<Schemas[0], TableId>]?: Stamp<
+              CellOrUndefined<Schemas[0], TableId, CellId>
+            >;
+          }>
+        >
+      >;
+    }>,
+    mergeableValues: Stamp<{
+      [ValueId in ValueIdFromSchema<Schemas[1]>]?: Stamp<
+        ValueOrUndefined<Schemas[1], ValueId>
+      >;
+    }>,
+  ]
+>;
 
 /**
  * The MergeableStore type
@@ -96,13 +124,268 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
     mergeableContent: MergeableContent<Schemas>,
   ): MergeableStore<Schemas>;
 
+  /**
+   * The getTransactionMergeableChanges method
+   * @category Merging
+   */
+  getTransactionMergeableChanges(): MergeableChanges<Schemas>;
+
   /**
    * The applyMergeableChanges method
    * @category Merging
    */
   applyMergeableChanges(
-    mergeableChanges: MergeableChanges<Schemas>,
+    mergeableChanges: MergeableChanges<Schemas> | MergeableContent<Schemas>,
   ): MergeableStore<Schemas>;
+
+  /**
+   * The getContentHash method
+   * @category Hashes
+   */
+  getContentHash(): Hash;
+
+  /**
+   * The getTablesHash method
+   * @category Hashes
+   */
+  getTablesHash(): Hash;
+
+  /**
+   * The getTableHash method
+   * @category Hashes
+   */
+  getTableHash(tableId: TableIdFromSchema<Schemas[0]>): Hash;
+
+  /**
+   * The getRowHash method
+   * @category Hashes
+   */
+  getRowHash<TableId extends TableIdFromSchema<Schemas[0]>>(
+    tableId: TableId,
+    rowId: Id,
+  ): Hash;
+
+  /**
+   * The getCellHash method
+   * @category Hashes
+   */
+  getCellHash<TableId extends TableIdFromSchema<Schemas[0]>>(
+    tableId: TableId,
+    rowId: Id,
+    cellId: CellIdFromSchema<Schemas[0], TableId>,
+  ): Hash;
+
+  /**
+   * The getValuesHash method
+   * @category Hashes
+   */
+  getValuesHash(): Hash;
+
+  /**
+   * The getValueHash method
+   * @category Hashes
+   */
+  getValueHash(valueId: ValueIdFromSchema<Schemas[1]>): Hash;
+
+  /**
+   * The setTablesSchema method lets you specify the TablesSchema of the tabular
+   * part of the Store.
+   *
+   * Note that this may result in a change to data in the Store, as defaults are
+   * applied or as invalid Table, Row, or Cell objects are removed. These
+   * changes will fire any listeners to that data, as expected.
+   *
+   * When no longer needed, you can also completely remove an existing
+   * TablesSchema with the delTablesSchema method.
+   * @param tablesSchema The TablesSchema to be set for the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example sets the TablesSchema of a Store after it has been created.
+   *
+   * ```js
+   * const store = createStore().setTablesSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     sold: {type: 'boolean', default: false},
+   *   },
+   * });
+   * store.addRow('pets', {species: 'dog', color: 'brown', sold: 'maybe'});
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {0: {species: 'dog', sold: false}}}
+   * ```
+   * @category Setter
+   * @since v3.0.0
+   */
+  setTablesSchema<TS extends TablesSchema>(
+    tablesSchema: TS,
+  ): MergeableStore<[typeof tablesSchema, Schemas[1]]>;
+
+  /**
+   * The setValuesSchema method lets you specify the ValuesSchema of the keyed
+   * Values part of the Store.
+   *
+   * Note that this may result in a change to data in the Store, as defaults are
+   * applied or as invalid Values are removed. These changes will fire any
+   * listeners to that data, as expected.
+   *
+   * When no longer needed, you can also completely remove an existing
+   * ValuesSchema with the delValuesSchema method.
+   * @param valuesSchema The ValuesSchema to be set for the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example sets the ValuesSchema of a Store after it has been created.
+   *
+   * ```js
+   * const store = createStore().setValuesSchema({
+   *   open: {type: 'boolean', default: false},
+   * });
+   * store.setValue('open', 'maybe');
+   *
+   * console.log(store.getValues());
+   * // -> {open: false}
+   * ```
+   * @category Setter
+   * @since v3.0.0
+   */
+  setValuesSchema<VS extends ValuesSchema>(
+    valuesSchema: VS,
+  ): MergeableStore<[Schemas[0], typeof valuesSchema]>;
+
+  /**
+   * The setSchema method lets you specify the TablesSchema and ValuesSchema of
+   * the Store.
+   *
+   * Note that this may result in a change to data in the Store, as defaults are
+   * applied or as invalid Table, Row, Cell, or Value objects are removed. These
+   * changes will fire any listeners to that data, as expected.
+   *
+   * From v3.0 onwards, this method takes two arguments. The first is the
+   * TablesSchema object, the second the ValuesSchema. In previous versions
+   * (before the existence of the ValuesSchema data structure), only the first
+   * was present. For backwards compatibility the new second parameter is
+   * optional.
+   * @param tablesSchema The TablesSchema to be set for the Store.
+   * @param valuesSchema The ValuesSchema to be set for the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example sets the TablesSchema and ValuesSchema of a Store after it has
+   * been created.
+   *
+   * ```js
+   * const store = createStore().setSchema(
+   *   {
+   *     pets: {
+   *       species: {type: 'string'},
+   *       sold: {type: 'boolean', default: false},
+   *     },
+   *   },
+   *   {open: {type: 'boolean', default: false}},
+   * );
+   * store.addRow('pets', {species: 'dog', color: 'brown', sold: 'maybe'});
+   * store.setValue('open', 'maybe');
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {0: {species: 'dog', sold: false}}}
+   * console.log(store.getValues());
+   * // -> {open: false}
+   * ```
+   * @example
+   * This example sets just the TablesSchema of a Store after it has been
+   * created.
+   *
+   * ```js
+   * const store = createStore().setSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     sold: {type: 'boolean', default: false},
+   *   },
+   * });
+   * store.addRow('pets', {species: 'dog', color: 'brown', sold: 'maybe'});
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {0: {species: 'dog', sold: false}}}
+   * ```
+   * @category Setter
+   */
+  setSchema<TS extends TablesSchema, VS extends ValuesSchema>(
+    tablesSchema: TS,
+    valuesSchema?: VS,
+  ): MergeableStore<
+    [
+      typeof tablesSchema,
+      Exclude<ValuesSchema, typeof valuesSchema> extends never
+        ? NoValuesSchema
+        : NonNullable<typeof valuesSchema>,
+    ]
+  >;
+
+  /**
+   * The delTablesSchema method lets you remove the TablesSchema of the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example removes the TablesSchema of a Store.
+   *
+   * ```js
+   * const store = createStore().setTablesSchema({
+   *   pets: {species: {type: 'string'}},
+   * });
+   * store.delTablesSchema();
+   * console.log(store.getTablesSchemaJson());
+   * // -> '{}'
+   * ```
+   * @category Deleter
+   */
+  delTablesSchema<
+    ValuesSchema extends OptionalValuesSchema = Schemas[1],
+  >(): MergeableStore<[NoTablesSchema, ValuesSchema]>;
+
+  /**
+   * The delValuesSchema method lets you remove the ValuesSchema of the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example removes the ValuesSchema of a Store.
+   *
+   * ```js
+   * const store = createStore().setValuesSchema({
+   *   sold: {type: 'boolean', default: false},
+   * });
+   * store.delValuesSchema();
+   * console.log(store.getValuesSchemaJson());
+   * // -> '{}'
+   * ```
+   * @category Deleter
+   * @since v3.0.0
+   */
+  delValuesSchema<
+    TablesSchema extends OptionalTablesSchema = Schemas[0],
+  >(): MergeableStore<[TablesSchema, NoValuesSchema]>;
+
+  /**
+   * The delSchema method lets you remove both the TablesSchema and ValuesSchema
+   * of the Store.
+   *
+   * Prior to v3.0, this method removed the TablesSchema only.
+   * @returns A reference to the Store.
+   * @example
+   * This example removes the TablesSchema and ValuesSchema of a Store.
+   *
+   * ```js
+   * const store = createStore()
+   *   .setTablesSchema({
+   *     pets: {species: {type: 'string'}},
+   *   })
+   *   .setValuesSchema({
+   *     sold: {type: 'boolean', default: false},
+   *   });
+   * store.delSchema();
+   * console.log(store.getSchemaJson());
+   * // -> '[{},{}]'
+   * ```
+   * @category Deleter
+   * @since v3.0.0
+   */
+  delSchema(): MergeableStore<NoSchemas>;
 }
 
 /**

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

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

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

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

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

@@ -0,0 +1,152 @@
+/**
+ * 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 {OptionalSchemas, Store} from '../store';
+import {Client} from '@libsql/client';
+
+/**
+ * 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<Schemas extends OptionalSchemas>
+  extends Persister<Schemas> {
+  /**
+   * 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).
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createLibSqlPersister(
+ *   store: Store,
+ *   client: Client,
+ *   configOrStoreTableName?: DatabasePersisterConfig | string,
+ *   onSqlCommand?: (sql: string, args?: any[]) => void,
+ *   onIgnoredError?: (error: any) => void,
+ * ): LibSqlPersister;
+ * ```
+ *
+ * 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<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  client: Client,
+  configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): LibSqlPersister<Schemas>;

package/lib/types/with-schemas/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)|
  *
@@ -76,10 +77,15 @@ export type PersisterStats = {
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * (
- *   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;
  * ```
  *
  * If the listener has the `getChanges` parameter, it will be used to make an
@@ -1153,7 +1159,7 @@ export interface Persister<
  * ```ts override
  * createCustomPersister<
  *   ListeningHandle,
- *   SupportsMergeableStore extends boolean,
+ *   SupportsMergeableStore extends boolean = false,
  * >(
  *   store: Store | (SupportsMergeableStore extends true ? MergeableStore : never),
  *   getPersisted: () => Promise<
@@ -1167,7 +1173,9 @@ export interface Persister<
  *       | (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,