tinybase 5.4.0-beta.2 → 5.4.0-beta.4

package/@types/mergeable-store/index.d.cts

@@ -258,9 +258,9 @@ export type MergeableContent = [
  * @category Mergeable
  * @since v5.0.0
  */
-export type MergeableChanges = [
-  mergeableTables: TablesStamp,
-  mergeableValues: ValuesStamp,
+export type MergeableChanges<Hashed extends boolean = false> = [
+  mergeableTables: TablesStamp<Hashed>,
+  mergeableValues: ValuesStamp<Hashed>,
   isChanges: 1,
 ];
 
@@ -858,7 +858,9 @@ export interface MergeableStore extends Store {
    * The method is generally intended to be used internally within TinyBase
    * itself and the return type is assumed to be opaque to applications that use
    * it.
-   * @returns A MergeableChanges object representing the changes.
+   * @param withHashes Whether to include hashes in the output, defaulting to
+   * false.
+   * @returns A MergeableChanges object representing the changes, with hashes.
    * @example
    * This example makes changes to the MergeableStore. At the end of the
    * transaction, detail about what changed is enumerated.
@@ -887,7 +889,7 @@ export interface MergeableStore extends Store {
    * @category Transaction
    * @since v5.0.0
    */
-  getTransactionMergeableChanges(): MergeableChanges;
+  getTransactionMergeableChanges(withHashes?: boolean): MergeableChanges<true>;
 
   /**
    * The applyMergeableChanges method applies a set of mergeable changes or
@@ -1016,13 +1018,14 @@ export interface MergeableStore extends Store {
   merge(mergeableStore: MergeableStore): MergeableStore;
 
   /**
-   * The isMergeable methods lets you know if the Store is mergeable.
+   * The isMergeable method lets you know if the Store is mergeable.
    *
-   * This will always be false for a Store, and true for a MergeableStore.
-   * @category Information
+   * This will always return false for a Store, and true for a MergeableStore.
+   * @returns Whether the Store is mergeable.
+   * @category Getter
    * @since v5.0.0
    */
-  isMergeable: () => boolean;
+  isMergeable(): boolean;
 }
 
 /**

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

@@ -258,9 +258,9 @@ export type MergeableContent = [
  * @category Mergeable
  * @since v5.0.0
  */
-export type MergeableChanges = [
-  mergeableTables: TablesStamp,
-  mergeableValues: ValuesStamp,
+export type MergeableChanges<Hashed extends boolean = false> = [
+  mergeableTables: TablesStamp<Hashed>,
+  mergeableValues: ValuesStamp<Hashed>,
   isChanges: 1,
 ];
 
@@ -858,7 +858,9 @@ export interface MergeableStore extends Store {
    * The method is generally intended to be used internally within TinyBase
    * itself and the return type is assumed to be opaque to applications that use
    * it.
-   * @returns A MergeableChanges object representing the changes.
+   * @param withHashes Whether to include hashes in the output, defaulting to
+   * false.
+   * @returns A MergeableChanges object representing the changes, with hashes.
    * @example
    * This example makes changes to the MergeableStore. At the end of the
    * transaction, detail about what changed is enumerated.
@@ -887,7 +889,7 @@ export interface MergeableStore extends Store {
    * @category Transaction
    * @since v5.0.0
    */
-  getTransactionMergeableChanges(): MergeableChanges;
+  getTransactionMergeableChanges(withHashes?: boolean): MergeableChanges<true>;
 
   /**
    * The applyMergeableChanges method applies a set of mergeable changes or
@@ -1016,13 +1018,14 @@ export interface MergeableStore extends Store {
   merge(mergeableStore: MergeableStore): MergeableStore;
 
   /**
-   * The isMergeable methods lets you know if the Store is mergeable.
+   * The isMergeable method lets you know if the Store is mergeable.
    *
-   * This will always be false for a Store, and true for a MergeableStore.
-   * @category Information
+   * This will always return false for a Store, and true for a MergeableStore.
+   * @returns Whether the Store is mergeable.
+   * @category Getter
    * @since v5.0.0
    */
-  isMergeable: () => boolean;
+  isMergeable(): boolean;
 }
 
 /**

package/@types/mergeable-store/with-schemas/index.d.cts

@@ -395,9 +395,9 @@ export type MergeableContent<Schemas extends OptionalSchemas> = [
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * [
- *   mergeableTables: TablesStamp,
- *   mergeableValues: ValuesStamp,
+ * export type MergeableChanges<Hashed extends boolean = false> = [
+ *   mergeableTables: TablesStamp<Hashed>,
+ *   mergeableValues: ValuesStamp<Hashed>,
  *   isChanges: 1,
  * ];
  * ```
@@ -411,9 +411,12 @@ export type MergeableContent<Schemas extends OptionalSchemas> = [
  * @category Mergeable
  * @since v5.0.0
  */
-export type MergeableChanges<Schemas extends OptionalSchemas> = [
-  mergeableTables: TablesStamp<Schemas[0]>,
-  mergeableValues: ValuesStamp<Schemas[1]>,
+export type MergeableChanges<
+  Schemas extends OptionalSchemas,
+  Hashed extends boolean = false,
+> = [
+  mergeableTables: TablesStamp<Schemas[0], Hashed>,
+  mergeableValues: ValuesStamp<Schemas[1], Hashed>,
   isChanges: 1,
 ];
 
@@ -1098,13 +1101,15 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * getTransactionMergeableChanges(): MergeableChanges;
+   * getTransactionMergeableChanges(withHashes?: boolean): MergeableChanges<true>;
    * ```
    *
    * The method is generally intended to be used internally within TinyBase
    * itself and the return type is assumed to be opaque to applications that use
    * it.
-   * @returns A MergeableChanges object representing the changes.
+   * @param withHashes Whether to include hashes in the output, defaulting to
+   * false.
+   * @returns A MergeableChanges object representing the changes, with hashes.
    * @example
    * This example makes changes to the MergeableStore. At the end of the
    * transaction, detail about what changed is enumerated.
@@ -1133,7 +1138,9 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
    * @category Transaction
    * @since v5.0.0
    */
-  getTransactionMergeableChanges(): MergeableChanges<Schemas>;
+  getTransactionMergeableChanges(
+    withHashes?: boolean,
+  ): MergeableChanges<Schemas, true>;
 
   /**
    * The applyMergeableChanges method applies a set of mergeable changes or
@@ -1276,13 +1283,14 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   merge(mergeableStore: MergeableStore<Schemas>): MergeableStore<Schemas>;
 
   /**
-   * The isMergeable methods lets you know if the Store is mergeable.
+   * The isMergeable method lets you know if the Store is mergeable.
    *
-   * This will always be false for a Store, and true for a MergeableStore.
-   * @category Information
+   * This will always return false for a Store, and true for a MergeableStore.
+   * @returns Whether the Store is mergeable.
+   * @category Getter
    * @since v5.0.0
    */
-  isMergeable: () => boolean;
+  isMergeable(): boolean;
 
   /**
    * The setTablesSchema method lets you specify the TablesSchema of the tabular

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

@@ -395,9 +395,9 @@ export type MergeableContent<Schemas extends OptionalSchemas> = [
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * [
- *   mergeableTables: TablesStamp,
- *   mergeableValues: ValuesStamp,
+ * export type MergeableChanges<Hashed extends boolean = false> = [
+ *   mergeableTables: TablesStamp<Hashed>,
+ *   mergeableValues: ValuesStamp<Hashed>,
  *   isChanges: 1,
  * ];
  * ```
@@ -411,9 +411,12 @@ export type MergeableContent<Schemas extends OptionalSchemas> = [
  * @category Mergeable
  * @since v5.0.0
  */
-export type MergeableChanges<Schemas extends OptionalSchemas> = [
-  mergeableTables: TablesStamp<Schemas[0]>,
-  mergeableValues: ValuesStamp<Schemas[1]>,
+export type MergeableChanges<
+  Schemas extends OptionalSchemas,
+  Hashed extends boolean = false,
+> = [
+  mergeableTables: TablesStamp<Schemas[0], Hashed>,
+  mergeableValues: ValuesStamp<Schemas[1], Hashed>,
   isChanges: 1,
 ];
 
@@ -1098,13 +1101,15 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * getTransactionMergeableChanges(): MergeableChanges;
+   * getTransactionMergeableChanges(withHashes?: boolean): MergeableChanges<true>;
    * ```
    *
    * The method is generally intended to be used internally within TinyBase
    * itself and the return type is assumed to be opaque to applications that use
    * it.
-   * @returns A MergeableChanges object representing the changes.
+   * @param withHashes Whether to include hashes in the output, defaulting to
+   * false.
+   * @returns A MergeableChanges object representing the changes, with hashes.
    * @example
    * This example makes changes to the MergeableStore. At the end of the
    * transaction, detail about what changed is enumerated.
@@ -1133,7 +1138,9 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
    * @category Transaction
    * @since v5.0.0
    */
-  getTransactionMergeableChanges(): MergeableChanges<Schemas>;
+  getTransactionMergeableChanges(
+    withHashes?: boolean,
+  ): MergeableChanges<Schemas, true>;
 
   /**
    * The applyMergeableChanges method applies a set of mergeable changes or
@@ -1276,13 +1283,14 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   merge(mergeableStore: MergeableStore<Schemas>): MergeableStore<Schemas>;
 
   /**
-   * The isMergeable methods lets you know if the Store is mergeable.
+   * The isMergeable method lets you know if the Store is mergeable.
    *
-   * This will always be false for a Store, and true for a MergeableStore.
-   * @category Information
+   * This will always return false for a Store, and true for a MergeableStore.
+   * @returns Whether the Store is mergeable.
+   * @category Getter
    * @since v5.0.0
    */
-  isMergeable: () => boolean;
+  isMergeable(): boolean;
 
   /**
    * The setTablesSchema method lets you specify the TablesSchema of the tabular

package/@types/persisters/index.d.cts

@@ -177,12 +177,14 @@ export type PersistedContent<Persist extends Persists = Persists.StoreOnly> =
  * @category Mergeable
  * @since v5.0.0
  */
-export type PersistedChanges<Persist extends Persists = Persists.StoreOnly> =
-  Persist extends Persists.StoreOrMergeableStore
-    ? Changes | MergeableChanges
-    : Persist extends Persists.MergeableStoreOnly
-      ? MergeableChanges
-      : Changes;
+export type PersistedChanges<
+  Persist extends Persists = Persists.StoreOnly,
+  Hashed extends boolean = false,
+> = Persist extends Persists.StoreOrMergeableStore
+  ? Changes | MergeableChanges<Hashed>
+  : Persist extends Persists.MergeableStoreOnly
+    ? MergeableChanges<Hashed>
+    : Changes;
 
 /**
  * A PersisterListener is a generic representation of the callback that lets a
@@ -1458,6 +1460,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * the underlying Store and storage are removed and it can be correctly
    * garbage collected. It is equivalent to running the stopAutoLoad method and
    * the stopAutoSave method in succession.
+   * @returns A reference to the Persister object.
    * @example
    * This example creates a Store, associates a Persister object with it (that
    * registers a TablesListener with the underlying Store), and then destroys it
@@ -1776,8 +1779,9 @@ export function createCustomPersister<
  * changes to the database.
  * @param onSqlCommand A function that will be called for each SQL command
  * executed against the database.
- * @param onIgnoredError A function that will be called for errors that are
- * ignored by the Persister.
+ * @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.
  * @param destroy A function that will be called to perform any extra clean up
  * on the Persister.
  * @param persist An integer from the Persists enum to indicate which types of
@@ -1832,8 +1836,9 @@ export function createCustomSqlitePersister<
  * changes to the database.
  * @param onSqlCommand A function that will be called for each SQL command
  * executed against the database.
- * @param onIgnoredError A function that will be called for errors that are
- * ignored by the Persister.
+ * @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.
  * @param destroy A function that will be called to perform any extra clean up
  * on the Persister.
  * @param persist An integer from the Persists enum to indicate which types of

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

@@ -177,12 +177,14 @@ export type PersistedContent<Persist extends Persists = Persists.StoreOnly> =
  * @category Mergeable
  * @since v5.0.0
  */
-export type PersistedChanges<Persist extends Persists = Persists.StoreOnly> =
-  Persist extends Persists.StoreOrMergeableStore
-    ? Changes | MergeableChanges
-    : Persist extends Persists.MergeableStoreOnly
-      ? MergeableChanges
-      : Changes;
+export type PersistedChanges<
+  Persist extends Persists = Persists.StoreOnly,
+  Hashed extends boolean = false,
+> = Persist extends Persists.StoreOrMergeableStore
+  ? Changes | MergeableChanges<Hashed>
+  : Persist extends Persists.MergeableStoreOnly
+    ? MergeableChanges<Hashed>
+    : Changes;
 
 /**
  * A PersisterListener is a generic representation of the callback that lets a
@@ -1458,6 +1460,7 @@ export interface Persister<Persist extends Persists = Persists.StoreOnly> {
    * the underlying Store and storage are removed and it can be correctly
    * garbage collected. It is equivalent to running the stopAutoLoad method and
    * the stopAutoSave method in succession.
+   * @returns A reference to the Persister object.
    * @example
    * This example creates a Store, associates a Persister object with it (that
    * registers a TablesListener with the underlying Store), and then destroys it
@@ -1776,8 +1779,9 @@ export function createCustomPersister<
  * changes to the database.
  * @param onSqlCommand A function that will be called for each SQL command
  * executed against the database.
- * @param onIgnoredError A function that will be called for errors that are
- * ignored by the Persister.
+ * @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.
  * @param destroy A function that will be called to perform any extra clean up
  * on the Persister.
  * @param persist An integer from the Persists enum to indicate which types of
@@ -1832,8 +1836,9 @@ export function createCustomSqlitePersister<
  * changes to the database.
  * @param onSqlCommand A function that will be called for each SQL command
  * executed against the database.
- * @param onIgnoredError A function that will be called for errors that are
- * ignored by the Persister.
+ * @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.
  * @param destroy A function that will be called to perform any extra clean up
  * on the Persister.
  * @param persist An integer from the Persists enum to indicate which types of

package/@types/persisters/persister-durable-object-storage/index.d.cts

@@ -0,0 +1,116 @@
+/**
+ * The persister-durable-object-storage module of the TinyBase project lets you
+ * save and load Store data to and from Cloudflare Durable Object storage (in an
+ * appropriate environment).
+ * @see Persistence guides
+ * @packageDocumentation
+ * @module persister-durable-object-storage
+ * @since v5.4.0
+ */
+
+import type {Persister, Persists} from '../index.d.cts';
+import type {MergeableStore} from '../../mergeable-store/index.d.cts';
+
+/**
+ * The DurableObjectStoragePersister interface represents a Persister that lets
+ * you save and load Store data to and from Cloudflare Durable Object storage.
+ *
+ * You should use the createDurableObjectStoragePersister function to create a
+ * DurableObjectStoragePersister object, most likely within the createPersister
+ * method of a WsServerDurableObject.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getStorage method for accessing a reference to the storage that the
+ * Store is being persisted to.
+ * @category Persister
+ * @since v5.4.0
+ */
+export interface DurableObjectStoragePersister
+  extends Persister<Persists.MergeableStoreOnly> {
+  /**
+   * The getStorage method returns a reference to the storage that the Store is
+   * being persisted to.
+   * @returns The reference to the storage.
+   * @example
+   * This example creates a Persister object against a newly-created Store
+   * (within the createPersister method of a WsServerDurableObject instance) and
+   * then gets the storage reference back out again.
+   *
+   * ```js yolo
+   * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+   * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * export class MyDurableObject extends WsServerDurableObject {
+   *   createPersister() {
+   *     const store = createMergeableStore();
+   *     const persister = createDurableObjectStoragePersister(
+   *       store,
+   *       this.ctx.storage,
+   *     );
+   *     console.log(persister.getStorage() == this.ctx.storage);
+   *     // -> true
+   *
+   *     return persister;
+   *   }
+   * }
+   * ```
+   * @category Getter
+   * @since v5.4.0
+   */
+  getStorage(): DurableObjectStorage;
+}
+
+/**
+ * The createDurableObjectStoragePersister function creates a
+ * DurableObjectStoragePersister object that can persist the Store to and from
+ * Cloudflare Durable Object storage.
+ *
+ * You will mostly use this within the createPersister method of a
+ * WsServerDurableObject.
+ *
+ * A DurableObjectStoragePersister only supports MergeableStore objects, and
+ * cannot be used to persist a regular Store.
+ *
+ * As well as providing a reference to the MergeableStore to persist, you must
+ * provide a `storage` parameter which identifies the Durable Object storage to
+ * persist it to.
+ * @param store The MergeableStore to persist.
+ * @param storage The Durable Object storage to persist the Store to.
+ * @param storagePrefix An optional prefix to use on the keys in storage, which
+ * is useful if you want to ensure the Persister will not affect unrelated
+ * Durable Object storage. Defaults to an empty string.
+ * @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 DurableObjectStoragePersister object.
+ * @example
+ * This example creates a Persister object against a newly-created
+ * MergeableStore (within the createPersister method of a WsServerDurableObject
+ * instance) and then gets the storage reference back out again.
+ *
+ * ```js yolo
+ * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+ * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * export class MyDurableObject extends WsServerDurableObject {
+ *   createPersister() {
+ *     const store = createMergeableStore();
+ *     const persister = createDurableObjectStoragePersister(
+ *       store,
+ *       this.ctx.storage,
+ *     );
+ *     return persister;
+ *   }
+ * }
+ * ```
+ * @category Creation
+ * @since v5.4.0
+ */
+export function createDurableObjectStoragePersister(
+  store: MergeableStore,
+  storage: DurableObjectStorage,
+  storagePrefix?: string,
+  onIgnoredError?: (error: any) => void,
+): DurableObjectStoragePersister;

package/@types/persisters/persister-durable-object-storage/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The persister-durable-object-storage module of the TinyBase project lets you
+ * save and load Store data to and from Cloudflare Durable Object storage (in an
+ * appropriate environment).
+ * @see Persistence guides
+ * @packageDocumentation
+ * @module persister-durable-object-storage
+ * @since v5.4.0
+ */
+
+import type {Persister, Persists} from '../index.d.ts';
+import type {MergeableStore} from '../../mergeable-store/index.d.ts';
+
+/**
+ * The DurableObjectStoragePersister interface represents a Persister that lets
+ * you save and load Store data to and from Cloudflare Durable Object storage.
+ *
+ * You should use the createDurableObjectStoragePersister function to create a
+ * DurableObjectStoragePersister object, most likely within the createPersister
+ * method of a WsServerDurableObject.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getStorage method for accessing a reference to the storage that the
+ * Store is being persisted to.
+ * @category Persister
+ * @since v5.4.0
+ */
+export interface DurableObjectStoragePersister
+  extends Persister<Persists.MergeableStoreOnly> {
+  /**
+   * The getStorage method returns a reference to the storage that the Store is
+   * being persisted to.
+   * @returns The reference to the storage.
+   * @example
+   * This example creates a Persister object against a newly-created Store
+   * (within the createPersister method of a WsServerDurableObject instance) and
+   * then gets the storage reference back out again.
+   *
+   * ```js yolo
+   * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+   * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * export class MyDurableObject extends WsServerDurableObject {
+   *   createPersister() {
+   *     const store = createMergeableStore();
+   *     const persister = createDurableObjectStoragePersister(
+   *       store,
+   *       this.ctx.storage,
+   *     );
+   *     console.log(persister.getStorage() == this.ctx.storage);
+   *     // -> true
+   *
+   *     return persister;
+   *   }
+   * }
+   * ```
+   * @category Getter
+   * @since v5.4.0
+   */
+  getStorage(): DurableObjectStorage;
+}
+
+/**
+ * The createDurableObjectStoragePersister function creates a
+ * DurableObjectStoragePersister object that can persist the Store to and from
+ * Cloudflare Durable Object storage.
+ *
+ * You will mostly use this within the createPersister method of a
+ * WsServerDurableObject.
+ *
+ * A DurableObjectStoragePersister only supports MergeableStore objects, and
+ * cannot be used to persist a regular Store.
+ *
+ * As well as providing a reference to the MergeableStore to persist, you must
+ * provide a `storage` parameter which identifies the Durable Object storage to
+ * persist it to.
+ * @param store The MergeableStore to persist.
+ * @param storage The Durable Object storage to persist the Store to.
+ * @param storagePrefix An optional prefix to use on the keys in storage, which
+ * is useful if you want to ensure the Persister will not affect unrelated
+ * Durable Object storage. Defaults to an empty string.
+ * @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 DurableObjectStoragePersister object.
+ * @example
+ * This example creates a Persister object against a newly-created
+ * MergeableStore (within the createPersister method of a WsServerDurableObject
+ * instance) and then gets the storage reference back out again.
+ *
+ * ```js yolo
+ * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+ * import {createDurableObjectStoragePersister} from 'tinybase/persisters/persister-durable-object-storage';
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * export class MyDurableObject extends WsServerDurableObject {
+ *   createPersister() {
+ *     const store = createMergeableStore();
+ *     const persister = createDurableObjectStoragePersister(
+ *       store,
+ *       this.ctx.storage,
+ *     );
+ *     return persister;
+ *   }
+ * }
+ * ```
+ * @category Creation
+ * @since v5.4.0
+ */
+export function createDurableObjectStoragePersister(
+  store: MergeableStore,
+  storage: DurableObjectStorage,
+  storagePrefix?: string,
+  onIgnoredError?: (error: any) => void,
+): DurableObjectStoragePersister;