tinybase 7.0.0-beta.0 → 7.0.0-beta.2

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

@@ -0,0 +1,382 @@
+/**
+ * The persister-durable-object-sql-storage module of the TinyBase project lets
+ * you save and load Store data to and from Cloudflare Durable Object SQLite
+ * storage (in an appropriate environment).
+ *
+ * Cloudflare's SQLite storage backend for Durable Objects offers significantly
+ * better pricing compared to the key-value storage backend. The SQLite storage
+ * backend is Cloudflare's recommended storage option for new Durable Object
+ * namespaces.
+ *
+ * **Important:** Before using this persister, you must configure your Durable
+ * Object class to use SQLite storage by adding a migration to your
+ * `wrangler.toml` or `wrangler.json` configuration file. Use
+ * `new_sqlite_classes` in your migration configuration to enable SQLite storage
+ * for your Durable Object class.
+ *
+ * See [Cloudflare's
+ * documentation](https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/)
+ * for more details.
+ * @see Cloudflare Durable Objects guide
+ * @see Persistence guides
+ * @packageDocumentation
+ * @module persister-durable-object-sql-storage
+ * @since v6.3.0
+ */
+import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.ts';
+import type {
+  OptionalSchemas,
+  Store,
+} from '../../../store/with-schemas/index.d.ts';
+import type {
+  DatabasePersisterConfig,
+  Persister,
+  Persists,
+} from '../../with-schemas/index.d.ts';
+
+/**
+ * The DpcFragmented type represents the configuration for fragmented
+ * persistence mode in a DurableObjectSqlStoragePersister.
+ *
+ * This mode stores each table, row, cell, and value as separate database rows,
+ * avoiding Cloudflare's 2MB row limit that can be hit with large stores in JSON
+ * mode. While this creates more database writes, it provides better scalability
+ * for larger datasets.
+ * @example
+ * This example shows how to configure a DurableObjectSqlStoragePersister to use
+ * fragmented mode with a custom storage prefix.
+ *
+ * ```js yolo
+ * import {createMergeableStore} from 'tinybase';
+ * import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
+ * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+ *
+ * const config = {
+ *   mode: 'fragmented',
+ *   storagePrefix: 'my_app_',
+ * };
+ *
+ * export class MyDurableObject extends WsServerDurableObject {
+ *   createPersister() {
+ *     const store = createMergeableStore();
+ *     const persister = createDurableObjectSqlStoragePersister(
+ *       store,
+ *       this.ctx.storage.sql,
+ *       config,
+ *     );
+ *     return persister;
+ *   }
+ * }
+ * ```
+ * @category Configuration
+ * @since v6.3.0
+ */
+export type DpcFragmented = {
+  /**
+   * The mode property must be set to 'fragmented' to enable fragmented
+   * persistence mode.
+   * @category Configuration
+   * @since v6.3.0
+   */
+  mode: 'fragmented';
+  /**
+   * The storagePrefix property lets you specify an optional prefix for the
+   * database table names used in fragmented mode.
+   *
+   * This is useful when you have multiple stores or applications sharing the
+   * same Durable Object SQL storage and want to avoid table name conflicts.
+   *
+   * The prefix will be sanitized to only include alphanumeric characters and
+   * underscores. For example, a prefix of 'my-app!' becomes 'my_app_'.
+   * @example
+   * This example shows a configuration using the storagePrefix setting. With a
+   * `storagePrefix` of 'user_data_', it creates `user_data_tinybase_tables` and
+   * `user_data_tinybase_values` tables.
+   * ```json
+   * {
+   *   mode: 'fragmented',
+   *   storagePrefix: 'user_data_',
+   * };
+   * ```
+   * @category Configuration
+   * @since v6.3.0
+   */
+  storagePrefix?: string;
+};
+
+/**
+ * The DurableObjectSqlDatabasePersisterConfig type represents the union of all
+ * possible configuration types for a DurableObjectSqlStoragePersister.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * DpcJson | DpcFragmented;
+ * ```
+ *
+ * This allows the persister to support multiple persistence modes.
+ * - JSON mode (via DpcJson): Stores the entire Store as JSON in a single row.
+ * - Fragmented mode (via DpcFragmented): Stores each piece of data as separate
+ *   rows.
+ * @example
+ * These examples show some different configuration options.
+ * ```json
+ * // JSON mode (default)
+ * {
+ *   mode: 'json',
+ *   storeTableName: 'my_store',
+ * };
+ *
+ * // Fragmented mode
+ * {
+ *   mode: 'fragmented',
+ *   storagePrefix: 'app_',
+ * };
+ * ```
+ * @category Configuration
+ * @since v6.3.0
+ */
+export type DurableObjectSqlDatabasePersisterConfig<
+  Schemas extends OptionalSchemas,
+> = DatabasePersisterConfig<Schemas> | DpcFragmented;
+
+/**
+ * The DurableObjectSqlStoragePersister interface represents a Persister that
+ * lets you save and load Store data to and from Cloudflare Durable Object SQL
+ * storage.
+ *
+ * You should use the createDurableObjectSqlStoragePersister function to create
+ * a DurableObjectSqlStoragePersister object, most likely within the
+ * createPersister method of a WsServerDurableObject.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getSqlStorage method for accessing a reference to the SQL storage that
+ * the Store is being persisted to.
+ * @category Persister
+ * @since v6.3.0
+ */
+export interface DurableObjectSqlStoragePersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.MergeableStoreOnly> {
+  /**
+   * The getSqlStorage method returns a reference to the SQL storage that the
+   * Store is being persisted to.
+   * @returns The reference to the SQL 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 SQL storage reference back out again.
+   *
+   * ```js yolo
+   * import {createMergeableStore} from 'tinybase';
+   * import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
+   * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+   *
+   * export class MyDurableObject extends WsServerDurableObject {
+   *   createPersister() {
+   *     const store = createMergeableStore();
+   *     const persister = createDurableObjectSqlStoragePersister(
+   *       store,
+   *       this.ctx.storage.sql,
+   *     );
+   *     console.log(persister.getSqlStorage() == this.ctx.storage.sql);
+   *     // -> true
+   *
+   *     return persister;
+   *   }
+   * }
+   * ```
+   * @category Getter
+   * @since v6.3.0
+   */
+  getSqlStorage(): SqlStorage;
+}
+
+/**
+ * The createDurableObjectSqlStoragePersister function creates a
+ * DurableObjectSqlStoragePersister object that can persist the Store to and
+ * from Cloudflare Durable Object SQLite storage.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createDurableObjectSqlStoragePersister(
+ *   store: MergeableStore,
+ *   sqlStorage: SqlStorage,
+ *   configOrStoreTableName?: DurableObjectSqlDatabasePersisterConfig | string,
+ *   onSqlCommand?: (sql: string, params?: any[]) => void,
+ *   onIgnoredError?: (error: any) => void,
+ * ): DurableObjectSqlStoragePersister;
+ * ```
+ *
+ * You will mostly use this within the createPersister method of a
+ * WsServerDurableObject.
+ *
+ * This persister uses Cloudflare's SQLite storage backend, which provides
+ * better pricing and performance compared to the legacy Key-value storage
+ * backend.
+ *
+ * **Important Prerequisites:** Before using this persister, you must configure
+ * your Durable Object class to use SQLite storage by adding a migration to your
+ * Wrangler configuration file. In your `wrangler.toml`, add the following.
+ * ```toml
+ * [[migrations]]
+ * tag = "v1"
+ * new_sqlite_classes = ["YourDurableObjectClass"]
+ * ```
+ *
+ * Or in your `wrangler.json`, add:
+ *
+ * ```json
+ * {
+ *   "migrations": [
+ *     {
+ *       "tag": "v1",
+ *       "new_sqlite_classes": ["YourDurableObjectClass"]
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * For more details on Durable Object migrations, see the [Cloudflare
+ * documentation](https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/).
+ *
+ * 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), a fragmented
+ * mode that stores each piece of data separately to avoid Cloudflare's 2MB row
+ * limit.
+ *
+ * - **JSON Mode (Default)**: Stores the entire Store as JSON in a single
+ *   database row. This is efficient for smaller stores but may hit Cloudflare's
+ *   2MB row limit for very large stores and uses fewer database writes.
+ *
+ * - **Fragmented Mode**: Stores each table, row, cell, and value as separate
+ *   database rows. Use this mode if you're concerned about hitting Cloudflare's
+ *   2MB row limit with large stores in JSON mode. This mode creates more
+ *   database writes but avoids row size limitations.
+ *
+ * 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. If it is the string 'fragmented', it enables fragmented mode.
+ *
+ * See the documentation for the DpcJson, DpcFragmented, and DpcTabular types
+ * for more information on how all of those modes can be configured.
+ *
+ * As well as providing a reference to the Store or MergeableStore to persist,
+ * you must provide a `sqlStorage` parameter which identifies the Durable Object
+ * SQLite storage to persist it to.
+ * @param store The Store or MergeableStore to persist.
+ * @param sqlStorage The Durable Object SQL storage to persist the Store to.
+ * @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 DurableObjectSqlStoragePersister object.
+ * @example
+ * This example creates a DurableObjectSqlStoragePersister object and persists
+ * the Store to Durable Object SQLite storage as a JSON serialization into the
+ * default `tinybase` table. It uses this within the createPersister method of a
+ * WsServerDurableObject instance.
+ *
+ * ```js yolo
+ * import {createMergeableStore} from 'tinybase';
+ * import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
+ * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+ *
+ * export class MyDurableObject extends WsServerDurableObject {
+ *   createPersister() {
+ *     const store = createMergeableStore();
+ *     const persister = createDurableObjectSqlStoragePersister(
+ *       store,
+ *       this.ctx.storage.sql,
+ *     );
+ *     return persister;
+ *   }
+ * }
+ * ```
+ * @example
+ * This example creates a DurableObjectSqlStoragePersister object with a custom
+ * table name and SQL command logging for debugging.
+ *
+ * ```js yolo
+ * import {createMergeableStore} from 'tinybase';
+ * import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
+ * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+ *
+ * export class MyDurableObject extends WsServerDurableObject {
+ *   createPersister() {
+ *     const store = createMergeableStore();
+ *     const persister = createDurableObjectSqlStoragePersister(
+ *       store,
+ *       this.ctx.storage.sql,
+ *       'my_app_store',
+ *       (sql, params) => console.log('SQL:', sql, params),
+ *       (error) => console.error('Persistence error:', error),
+ *     );
+ *     return persister;
+ *   }
+ * }
+ * ```
+ * @example
+ * This example creates a DurableObjectSqlStoragePersister object using
+ * fragmented mode to avoid Cloudflare's 2MB row limit for large stores.
+ *
+ * ```js yolo
+ * import {createMergeableStore} from 'tinybase';
+ * import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
+ * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+ *
+ * export class MyDurableObject extends WsServerDurableObject {
+ *   createPersister() {
+ *     const store = createMergeableStore();
+ *     const persister = createDurableObjectSqlStoragePersister(
+ *       store,
+ *       this.ctx.storage.sql,
+ *       {mode: 'fragmented'},
+ *     );
+ *     return persister;
+ *   }
+ * }
+ * ```
+ * @example
+ * This example creates a DurableObjectSqlStoragePersister object using
+ * fragmented mode with a custom storage prefix.
+ *
+ * ```js yolo
+ * import {createMergeableStore} from 'tinybase';
+ * import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
+ * import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
+ *
+ * export class MyDurableObject extends WsServerDurableObject {
+ *   createPersister() {
+ *     const store = createMergeableStore();
+ *     const persister = createDurableObjectSqlStoragePersister(
+ *       store,
+ *       this.ctx.storage.sql,
+ *       {mode: 'fragmented', storagePrefix: 'my_app_'},
+ *     );
+ *     return persister;
+ *   }
+ * }
+ * ```
+ * @category Creation
+ * @essential Persisting stores
+ * @since v6.3.0
+ */
+export function createDurableObjectSqlStoragePersister<
+  Schemas extends OptionalSchemas,
+>(
+  store: Store<Schemas> | MergeableStore<Schemas>,
+  sqlStorage: SqlStorage,
+  configOrStoreTableName?:
+    | DurableObjectSqlDatabasePersisterConfig<Schemas>
+    | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): DurableObjectSqlStoragePersister<Schemas>;

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

@@ -25,8 +25,7 @@ import type {Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since v5.4.0
  */
-export interface DurableObjectStoragePersister
-  extends Persister<Persists.MergeableStoreOnly> {
+export interface DurableObjectStoragePersister extends Persister<Persists.MergeableStoreOnly> {
   /**
    * The getStorage method returns a reference to the storage that the Store is
    * being persisted to.

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

@@ -26,8 +26,9 @@ import type {Persister, Persists} from '../../with-schemas/index.d.ts';
  * @category Persister
  * @since v5.4.0
  */
-export interface DurableObjectStoragePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.MergeableStoreOnly> {
+export interface DurableObjectStoragePersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.MergeableStoreOnly> {
   /**
    * The getStorage method returns a reference to the storage that the Store is
    * being persisted to.

package/@types/persisters/persister-electric-sql/with-schemas/index.d.ts

@@ -30,8 +30,9 @@ import type {
  * @category Persister
  * @since v4.6.0
  */
-export interface ElectricSqlPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface ElectricSqlPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getElectricClient method returns a reference to the Electric client the
    * Store is being persisted to.

package/@types/persisters/persister-expo-sqlite/index.d.ts

@@ -32,8 +32,7 @@ import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since v4.5.0
  */
-export interface ExpoSqlitePersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+export interface ExpoSqlitePersister extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

package/@types/persisters/persister-expo-sqlite/with-schemas/index.d.ts

@@ -39,8 +39,9 @@ import type {
  * @category Persister
  * @since v4.5.0
  */
-export interface ExpoSqlitePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface ExpoSqlitePersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getDb method returns a reference to the database instance the Store is
    * being persisted to.

package/@types/persisters/persister-file/index.d.ts

@@ -23,8 +23,7 @@ import type {Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface FilePersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+export interface FilePersister extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getFilePath method returns the location of the local file the Store is
    * being persisted to.

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

@@ -26,8 +26,9 @@ import type {Persister, Persists} from '../../with-schemas/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface FilePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface FilePersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getFilePath method returns the location of the local file the Store is
    * being persisted to.

package/@types/persisters/persister-indexed-db/with-schemas/index.d.ts

@@ -25,8 +25,9 @@ import type {Persister} from '../../with-schemas/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface IndexedDbPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface IndexedDbPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getDbName method returns the unique key of the IndexedDB the Store is
    * being persisted to.

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

@@ -30,8 +30,9 @@ import type {
  * @category Persister
  * @since v4.7.0
  */
-export interface LibSqlPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+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.

package/@types/persisters/persister-partykit-client/with-schemas/index.d.ts

@@ -38,8 +38,9 @@ import type {Persister} from '../../with-schemas/index.d.ts';
  * @category Persister
  * @since v4.3.14
  */
-export interface PartyKitPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface PartyKitPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getConnection method returns the PartySocket the Store is being
    * persisted to.

package/@types/persisters/persister-pglite/index.d.ts

@@ -24,8 +24,7 @@ import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since 5.2.0
  */
-export interface PglitePersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+export interface PglitePersister extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getPglite method returns a reference to the database connection the
    * Store is being persisted to.
@@ -166,6 +165,7 @@ export interface PglitePersister
  * await pglite.close();
  * ```
  * @category Creation
+ * @essential Persisting stores
  * @since 5.2.0
  */
 export function createPglitePersister(

package/@types/persisters/persister-pglite/with-schemas/index.d.ts

@@ -31,8 +31,9 @@ import type {
  * @category Persister
  * @since 5.2.0
  */
-export interface PglitePersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface PglitePersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getPglite method returns a reference to the database connection the
    * Store is being persisted to.
@@ -185,6 +186,7 @@ export interface PglitePersister<Schemas extends OptionalSchemas>
  * await pglite.close();
  * ```
  * @category Creation
+ * @essential Persisting stores
  * @since 5.2.0
  */
 export function createPglitePersister<Schemas extends OptionalSchemas>(

package/@types/persisters/persister-postgres/index.d.ts

@@ -24,8 +24,7 @@ import type {DatabasePersisterConfig, Persister, Persists} from '../index.d.ts';
  * @category Persister
  * @since 5.2.0
  */
-export interface PostgresPersister
-  extends Persister<Persists.StoreOrMergeableStore> {
+export interface PostgresPersister extends Persister<Persists.StoreOrMergeableStore> {
   /**
    * The getSql method returns a reference to the database connection the Store
    * is being persisted to.

package/@types/persisters/persister-postgres/with-schemas/index.d.ts

@@ -31,8 +31,9 @@ import type {
  * @category Persister
  * @since 5.2.0
  */
-export interface PostgresPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+export interface PostgresPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
   /**
    * The getSql method returns a reference to the database connection the Store
    * is being persisted to.

package/@types/persisters/persister-powersync/with-schemas/index.d.ts

@@ -31,8 +31,9 @@ import type {
  * @category Persister
  * @since v4.8.0
  */
-export interface PowerSyncPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+export interface PowerSyncPersister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas> {
   /**
    * The getPowerSync method returns a reference to the PowerSync instance the
    * Store is being persisted to.