event-sourced-collection 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to `event-sourced-collection` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.10] - 2026-09-08
+
+### Added
+
+- `recordLocalEchoes` option (default `true`). Set `false` to advance the pull
+  cursor past this device's own events without writing resolved inbox echo rows.
+
+## [0.0.9] - 2026-09-08
+
+### Added
+
+- `useSyncStatus` / `useEnsureDb` on `event-sourced-collection/react`
+- `useManualSync({ db })` so `syncing` follows `subscribeSyncStatus` (load sync + manual)
+
 ## [0.0.7] - 2026-08-09
 
 Reliability-focused release: dead-lettering, backend identity, retries, conflict detection, multi-tab locking, React helpers, and published examples.

package/dist/browser.d.mts

@@ -1,5 +1,5 @@
-import { L as SyncLock, P as SQLiteDriver, Q as InjectedModuleFn, Z as InjectedCreateCollection, p as EventSourcedSharedOptions } from "./types-BSdudVLh.mjs";
-import { r as ModulesInput, t as EventSourcedDBHandle } from "./create-event-sourced-db-handle-BAos-9pS.mjs";
+import { $ as InjectedCreateCollection, L as SyncLock, P as SQLiteDriver, et as InjectedModuleFn, p as EventSourcedSharedOptions } from "./types-CbOMv5E8.mjs";
+import { b as ModulesInput, v as EventSourcedDBHandle } from "./index-BkKizlCB.mjs";
 import { PersistedCollectionPersistence } from "@tanstack/db-sqlite-persistence-core";
 
 //#region src/platforms/browser-wa-sqlite-driver.d.ts

package/dist/browser.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.mts","names":[],"sources":["../src/platforms/browser-wa-sqlite-driver.ts","../src/platforms/browser-types.ts","../src/platforms/browser.ts","../src/platforms/browser-event-sourced-db.ts"],"mappings":";;;;;KAEY,uBAAA;EACV,OAAA,mBACE,GAAA,UACA,MAAA,GAAS,aAAA,cACN,OAAA,CAAQ,aAAA,CAAc,IAAA;EAC3B,KAAA,SAAc,OAAA;AAAA;;;KCJJ,0BAAA;EACV,OAAO;AAAA;;ADFT;;;KCSY,mBAAA;EACV,+BAAA,GAAkC,OAAA,YAAmB,OAAA,CAAQ,uBAAA;EAC7D,gCAAA,GAAmC,OAAA,YAAmB,8BAAA;EACtD,4BAAA,OAAmC,OAAA,YAAmB,0BAAA;AAAA;AAAA,KAG5C,qBAAA;EACV,YAAA;EACA,iBAAiB;AAAA;AAAA,KAGP,qBAAA;EACV,MAAA,EAD+B,YAAA;EAE/B,WAAA,EAAa,8BAAA;EACb,KAAA,QAAa,OAAA;AAAA;;;;;;ADvBf;;;;;;;;;;;;;;;;;;;;;AAKuB;;;iBEoCD,qBAAA,CACpB,IAAA,EAAM,mBAAA,EACN,MAAA,EAAQ,qBAAA,GACP,OAAA,CAAQ,qBAAA;;;KC9BN,uBAAA;EACH,MAAA,GAAS,KAAY;AAAA;AAAA,KAGX,0BAAA,GAA6B,mBAAA;EACvC,gBAAA,EAAkB,wBAAA;EAClB,0BAAA,EAA4B,gBAAA;AAAA;;;;;;KAQlB,2BAAA,eAA0C,MAAA,SAAe,uBAAA,KACnE,IAAA,CAAK,yBAAA;EH5BK;;;;EGiCR,WAAA,EAAa,KAAA;EH9BF;;;;EGmCX,YAAA;EHlCmB;;;;EGuCnB,iBAAA;EF3CkC;;;AAC7B;AAOT;;EE0CI,OAAA,EAAS,YAAA,CAAa,0BAAA;EFzCqC;;;;EE8C3D,IAAA,GAAO,QAAA;AAAA;;;;;;;;;;;AF5CuE;AAGlF;;;;AAEmB;AAGnB;;;;;;;;;;;;;;;AAGsB;;;;ACkBtB;;;;;;;iBC8DgB,2BAAA,qBACM,MAAA,SAAe,uBAAA,GACnC,MAAA,EAAQ,2BAAA,CAA4B,KAAA,IAAM,oBAAA,CAAA,KAAA"}
+{"version":3,"file":"browser.d.mts","names":[],"sources":["../src/platforms/browser-wa-sqlite-driver.ts","../src/platforms/browser-types.ts","../src/platforms/browser.ts","../src/platforms/browser-event-sourced-db.ts"],"mappings":";;;;;KAEY,uBAAA;EACV,OAAA,mBACE,GAAA,UACA,MAAA,GAAS,aAAA,cACN,OAAA,CAAQ,aAAA,CAAc,IAAA;EAC3B,KAAA,SAAc,OAAA;AAAA;;;KCJJ,0BAAA;EACV,OAAO;AAAA;ADFT;;;;AAAA,KCSY,mBAAA;EACV,+BAAA,GAAkC,OAAA,YAAmB,OAAA,CAAQ,uBAAA;EAC7D,gCAAA,GAAmC,OAAA,YAAmB,8BAAA;EACtD,4BAAA,OAAmC,OAAA,YAAmB,0BAAA;AAAA;AAAA,KAG5C,qBAAA;EACV,YAAA;EACA,iBAAiB;AAAA;AAAA,KAGP,qBAAA;EACV,MAAA,EAD+B,YAAA;EAE/B,WAAA,EAAa,8BAAA;EACb,KAAA,QAAa,OAAA;AAAA;;;;;ADvBf;;;;;;;;;;;;;;;;;;;;;AAKuB;;;;iBEoCD,qBAAA,CACpB,IAAA,EAAM,mBAAA,EACN,MAAA,EAAQ,qBAAA,GACP,OAAA,CAAQ,qBAAA;;;KC9BN,uBAAA;EACH,MAAA,GAAS,KAAY;AAAA;AAAA,KAGX,0BAAA,GAA6B,mBAAA;EACvC,gBAAA,EAAkB,wBAAA;EAClB,0BAAA,EAA4B,gBAAA;AAAA;;;;;;KAQlB,2BAAA,eAA0C,MAAA,SAAe,uBAAA,KACnE,IAAA,CAAK,yBAAA;EH3BH;;;;EGgCA,WAAA,EAAa,KAAA;EH9BY;;;;EGmCzB,YAAA;;;;AFtCJ;EE2CI,iBAAA;;;AF1CK;AAOT;;;EE0CI,OAAA,EAAS,YAAA,CAAa,0BAAA;EFzC6B;;;;EE8CnD,IAAA,GAAO,QAAA;AAAA;;;;;;;;;;AF5CuE;AAGlF;;;;AAEmB;AAGnB;;;;;;;;;;;;;;;AAGsB;;;;ACkBtB;;;;;;;;iBC8DgB,2BAAA,qBACM,MAAA,SAAe,uBAAA,GACnC,MAAA,EAAQ,2BAAA,CAA4B,KAAA,IAAM,oBAAA,CAAA,KAAA"}

package/dist/browser.mjs

@@ -1,4 +1,4 @@
-import { n as resolveModules, t as createEventSourcedDBHandle } from "./create-event-sourced-db-handle-BPsVV1x6.mjs";
+import { n as resolveModules, t as createEventSourcedDBHandle } from "./create-event-sourced-db-handle-D23nsV5c.mjs";
 import { t as createWebLocksSyncLock } from "./web-locks-Bi2f732X.mjs";
 //#region src/platforms/browser-wa-sqlite-driver.ts
 function assertTransactionCallbackHasDriverArg(fn) {
@@ -203,6 +203,9 @@ function createBrowserEventSourcedDB(config) {
 				upcastEvent: config.upcastEvent,
 				retry: config.retry,
 				pushBatchSize: config.pushBatchSize,
+				maxPushBytes: config.maxPushBytes,
+				syncPreset: config.syncPreset,
+				recordLocalEchoes: config.recordLocalEchoes,
 				backendMismatch: config.backendMismatch,
 				conflictDetection: config.conflictDetection,
 				hooks: config.hooks,

package/dist/browser.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"browser.mjs","names":[],"sources":["../src/platforms/browser-wa-sqlite-driver.ts","../src/platforms/browser.ts","../src/platforms/browser-event-sourced-db.ts"],"sourcesContent":["import type { SQLiteDriver } from \"../core/types\";\n\nexport type BrowserWASQLiteDatabase = {\n  execute: <TRow = unknown>(\n    sql: string,\n    params?: ReadonlyArray<unknown>,\n  ) => Promise<ReadonlyArray<TRow>>;\n  close?: () => Promise<void> | void;\n};\n\nfunction assertTransactionCallbackHasDriverArg(\n  fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,\n): void {\n  if (fn.length > 0) {\n    return;\n  }\n\n  throw new Error(\"SQLiteDriver.transaction callback must accept the transaction driver argument\");\n}\n\nfunction assertDatabaseShape(\n  database: BrowserWASQLiteDatabase,\n): asserts database is BrowserWASQLiteDatabase {\n  if (typeof database.execute !== \"function\") {\n    throw new Error(\"Browser wa-sqlite database handle must provide execute(sql, params?)\");\n  }\n}\n\nexport class BrowserWASQLiteDriver implements SQLiteDriver {\n  private readonly database: BrowserWASQLiteDatabase;\n  private queue: Promise<void> = Promise.resolve();\n  private nextSavepointId = 1;\n  private closed = false;\n\n  constructor(database: BrowserWASQLiteDatabase) {\n    assertDatabaseShape(database);\n    this.database = database;\n  }\n\n  async exec(sql: string): Promise<void> {\n    await this.enqueue(async () => {\n      await this.database.execute(sql);\n    });\n  }\n\n  async query<T>(sql: string, params: ReadonlyArray<unknown> = []): Promise<ReadonlyArray<T>> {\n    return this.enqueue(() => this.database.execute<T>(sql, params));\n  }\n\n  async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {\n    await this.enqueue(async () => {\n      await this.database.execute(sql, params);\n    });\n  }\n\n  async transaction<T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>): Promise<T> {\n    assertTransactionCallbackHasDriverArg(fn);\n\n    return this.enqueue(async () => {\n      await this.database.execute(`BEGIN IMMEDIATE`);\n      try {\n        const result = await fn(this.createTransactionDriver());\n        await this.database.execute(`COMMIT`);\n        return result;\n      } catch (error) {\n        try {\n          await this.database.execute(`ROLLBACK`);\n        } catch {}\n        throw error;\n      }\n    });\n  }\n\n  async transactionWithDriver<T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>): Promise<T> {\n    return this.transaction(fn);\n  }\n\n  async close(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n    this.closed = true;\n\n    if (typeof this.database.close === \"function\") {\n      await Promise.resolve(this.database.close());\n    }\n  }\n\n  private createTransactionDriver(): SQLiteDriver {\n    return {\n      exec: (sql) => this.database.execute(sql).then(() => undefined),\n      query: <T>(sql: string, params: ReadonlyArray<unknown> = []) =>\n        this.database.execute<T>(sql, params),\n      run: (sql: string, params: ReadonlyArray<unknown> = []) =>\n        this.database.execute(sql, params).then(() => undefined),\n      transaction: <T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>) =>\n        this.runNestedTransaction(fn),\n      transactionWithDriver: <T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>) =>\n        this.runNestedTransaction(fn),\n    };\n  }\n\n  private async runNestedTransaction<T>(\n    fn: (transactionDriver: SQLiteDriver) => Promise<T>,\n  ): Promise<T> {\n    assertTransactionCallbackHasDriverArg(fn);\n\n    const savepointName = `tsdb_sp_${this.nextSavepointId}`;\n    this.nextSavepointId++;\n    await this.database.execute(`SAVEPOINT ${savepointName}`);\n    try {\n      const result = await fn(this.createTransactionDriver());\n      await this.database.execute(`RELEASE SAVEPOINT ${savepointName}`);\n      return result;\n    } catch (error) {\n      await this.database.execute(`ROLLBACK TO SAVEPOINT ${savepointName}`);\n      await this.database.execute(`RELEASE SAVEPOINT ${savepointName}`);\n      throw error;\n    }\n  }\n\n  private enqueue<T>(operation: () => Promise<T> | T): Promise<T> {\n    const queuedOperation = this.queue.then(operation, operation);\n    this.queue = queuedOperation.then(\n      () => undefined,\n      () => undefined,\n    );\n    return queuedOperation;\n  }\n}\n","import { BrowserWASQLiteDriver } from \"./browser-wa-sqlite-driver\";\nimport type {\n  BrowserPlatformConfig,\n  BrowserPlatformDeps,\n  BrowserPlatformResult,\n} from \"./browser-types\";\n\nexport type {\n  BrowserCoordinatorInstance,\n  BrowserPlatformConfig,\n  BrowserPlatformDeps,\n  BrowserPlatformResult,\n} from \"./browser-types\";\n\nexport type { BrowserWASQLiteDatabase } from \"./browser-wa-sqlite-driver\";\n\n/**\n * Opens OPFS SQLite, a cross-tab coordinator, and TanStack persistence.\n * Prefer {@link createBrowserEventSourcedDB}; call this only when you need the\n * raw `persistence` / `close` pair (for example a custom handle).\n *\n * @example\n * ```ts\n * import { createBrowserPlatform } from \"event-sourced-collection/browser\"\n * import {\n *   BrowserCollectionCoordinator,\n *   createBrowserWASQLitePersistence,\n *   openBrowserWASQLiteOPFSDatabase,\n * } from \"@tanstack/browser-db-sqlite-persistence\"\n *\n * const platform = await createBrowserPlatform(\n *   {\n *     openBrowserWASQLiteOPFSDatabase,\n *     createBrowserWASQLitePersistence,\n *     BrowserCollectionCoordinator,\n *   },\n *   { databaseName: \"app.sqlite\" },\n * )\n *\n * // pass platform.persistence into createEventSourcedDB\n * await platform.close()\n * ```\n */\nexport async function createBrowserPlatform(\n  deps: BrowserPlatformDeps,\n  config: BrowserPlatformConfig,\n): Promise<BrowserPlatformResult> {\n  const database = await deps.openBrowserWASQLiteOPFSDatabase({\n    databaseName: config.databaseName,\n  } as never);\n\n  const coordinator = new deps.BrowserCollectionCoordinator({\n    dbName: config.coordinatorDbName ?? config.databaseName.replace(/\\.sqlite$/, \"\"),\n  } as never);\n\n  const persistence = deps.createBrowserWASQLitePersistence({\n    database,\n    coordinator,\n  } as never);\n\n  const driver = new BrowserWASQLiteDriver(database);\n\n  return {\n    driver,\n    persistence,\n    close: async () => {\n      coordinator.dispose();\n      await driver.close();\n    },\n  };\n}\n","import {\n  createEventSourcedDBHandle,\n  resolveModules,\n  type ModulesInput,\n} from \"../core/create-event-sourced-db-handle\";\nimport type {\n  CreateCollectionFn,\n  InjectedCreateCollection,\n  InjectedModuleFn,\n  PersistedCollectionOptionsFn,\n} from \"../core/persisted-collection\";\nimport type { EventSourcedSharedOptions, SyncLock } from \"../core/types\";\nimport { createBrowserPlatform } from \"./browser\";\nimport type { BrowserPlatformDeps } from \"./browser-types\";\nimport { createWebLocksSyncLock } from \"./web-locks\";\n\ntype CollectionDefConstraint = {\n  getKey: (state: never) => string | number;\n};\n\nexport type BrowserEventSourcedModules = BrowserPlatformDeps & {\n  createCollection: InjectedCreateCollection;\n  persistedCollectionOptions: InjectedModuleFn;\n};\n\n/**\n * Browser entry-point config. Shared sync/lifecycle fields come from\n * {@link EventSourcedSharedOptions} (hover those properties for docs).\n * Deep guide: `docs/usage.md`.\n */\nexport type BrowserEventSourcedDBConfig<TDefs extends Record<string, CollectionDefConstraint>> =\n  Omit<EventSourcedSharedOptions, \"lock\" | \"lockName\"> & {\n    /**\n     * User collection registry. Object keys become `db.collections.<key>` and\n     * the wire `collectionId`. Must not collide with reserved names.\n     */\n    collections: TDefs;\n    /**\n     * OPFS SQLite database file name (e.g. `\"my-app.sqlite\"`). Also used as the\n     * default sync lock namespace so only one tab syncs for this DB at a time.\n     */\n    databaseName: string;\n    /**\n     * Name for the cross-tab collection coordinator database. Defaults to\n     * `databaseName` with a trailing `.sqlite` stripped.\n     */\n    coordinatorDbName?: string;\n    /**\n     * Browser OPFS persistence modules from\n     * `@tanstack/browser-db-sqlite-persistence` plus `createCollection`.\n     * Pass the imported bindings directly, or a function to keep WASM off the\n     * critical path.\n     */\n    modules: ModulesInput<BrowserEventSourcedModules>;\n    /**\n     * Defaults to a Web Locks–backed lock so only one tab syncs at a time.\n     * Pass `null` to opt out and let every tab sync independently.\n     */\n    lock?: SyncLock | null;\n  };\n\nexport type { EventSourcedDBHandle as BrowserEventSourcedDBHandle } from \"../core/create-event-sourced-db-handle\";\n\n/**\n * Browser-flavoured event-sourced DB: OPFS SQLite + optional Web Locks sync\n * election, returned as a lazy singleton.\n *\n * @param config - See {@link BrowserEventSourcedDBConfig} for every option.\n *\n * @example\n * ```ts\n * import { createBrowserEventSourcedDB } from \"event-sourced-collection/browser\"\n * import type { CollectionDef, EventSourcedDB } from \"event-sourced-collection\"\n *\n * type Todo = { id: string; title: string }\n * type Defs = { todos: CollectionDef<Todo, string> }\n *\n * const { ensureDb, db } = createBrowserEventSourcedDB<Defs>({\n *   databaseName: \"app.sqlite\",\n *   collections: { todos: { getKey: (todo) => todo.id } },\n *   sync: { push: \"/api/sync/events\", pull: \"/api/sync/events\" },\n *   modules: async () => {\n *     const { createCollection } = await import(\"@tanstack/db\")\n *     const {\n *       BrowserCollectionCoordinator,\n *       createBrowserWASQLitePersistence,\n *       openBrowserWASQLiteOPFSDatabase,\n *       persistedCollectionOptions,\n *     } = await import(\"@tanstack/browser-db-sqlite-persistence\")\n *     return {\n *       createCollection,\n *       BrowserCollectionCoordinator,\n *       createBrowserWASQLitePersistence,\n *       openBrowserWASQLiteOPFSDatabase,\n *       persistedCollectionOptions,\n *     }\n *   },\n * })\n *\n * export async function start() {\n *   await ensureDb()\n * }\n * export { db }\n * ```\n */\nexport function createBrowserEventSourcedDB<\n  const TDefs extends Record<string, CollectionDefConstraint>,\n>(config: BrowserEventSourcedDBConfig<TDefs>) {\n  return createEventSourcedDBHandle<TDefs>({\n    guard: assertBrowserEnvironment,\n    setup: async () => {\n      const modules = await resolveModules(config.modules);\n\n      const platform = await createBrowserPlatform(\n        {\n          openBrowserWASQLiteOPFSDatabase: modules.openBrowserWASQLiteOPFSDatabase,\n          createBrowserWASQLitePersistence: modules.createBrowserWASQLitePersistence,\n          BrowserCollectionCoordinator: modules.BrowserCollectionCoordinator,\n        },\n        {\n          databaseName: config.databaseName,\n          coordinatorDbName: config.coordinatorDbName,\n        },\n      );\n\n      return {\n        persistence: platform.persistence,\n        createCollection: modules.createCollection as CreateCollectionFn,\n        persistedCollectionOptions:\n          modules.persistedCollectionOptions as PersistedCollectionOptionsFn,\n        collections: config.collections,\n        sync: config.sync,\n        syncEnabled: config.syncEnabled,\n        schemaVersion: config.schemaVersion,\n        debug: config.debug,\n        clientId: config.clientId,\n        unknownEventHandling: config.unknownEventHandling,\n        pullOverlap: config.pullOverlap,\n        eventSchemaVersion: config.eventSchemaVersion,\n        upcastEvent: config.upcastEvent,\n        retry: config.retry,\n        pushBatchSize: config.pushBatchSize,\n        backendMismatch: config.backendMismatch,\n        conflictDetection: config.conflictDetection,\n        hooks: config.hooks,\n        lock: config.lock === null ? undefined : (config.lock ?? createWebLocksSyncLock()),\n        lockName: config.databaseName,\n        close: platform.close,\n      };\n    },\n  });\n}\n\nfunction assertBrowserEnvironment(): void {\n  if (typeof window === \"undefined\") {\n    throw new Error(\"Event-sourced DB (browser) is only available in a browser environment.\");\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"browser.mjs","names":[],"sources":["../src/platforms/browser-wa-sqlite-driver.ts","../src/platforms/browser.ts","../src/platforms/browser-event-sourced-db.ts"],"sourcesContent":["import type { SQLiteDriver } from \"../core/types\";\n\nexport type BrowserWASQLiteDatabase = {\n  execute: <TRow = unknown>(\n    sql: string,\n    params?: ReadonlyArray<unknown>,\n  ) => Promise<ReadonlyArray<TRow>>;\n  close?: () => Promise<void> | void;\n};\n\nfunction assertTransactionCallbackHasDriverArg(\n  fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,\n): void {\n  if (fn.length > 0) {\n    return;\n  }\n\n  throw new Error(\"SQLiteDriver.transaction callback must accept the transaction driver argument\");\n}\n\nfunction assertDatabaseShape(\n  database: BrowserWASQLiteDatabase,\n): asserts database is BrowserWASQLiteDatabase {\n  if (typeof database.execute !== \"function\") {\n    throw new Error(\"Browser wa-sqlite database handle must provide execute(sql, params?)\");\n  }\n}\n\nexport class BrowserWASQLiteDriver implements SQLiteDriver {\n  private readonly database: BrowserWASQLiteDatabase;\n  private queue: Promise<void> = Promise.resolve();\n  private nextSavepointId = 1;\n  private closed = false;\n\n  constructor(database: BrowserWASQLiteDatabase) {\n    assertDatabaseShape(database);\n    this.database = database;\n  }\n\n  async exec(sql: string): Promise<void> {\n    await this.enqueue(async () => {\n      await this.database.execute(sql);\n    });\n  }\n\n  async query<T>(sql: string, params: ReadonlyArray<unknown> = []): Promise<ReadonlyArray<T>> {\n    return this.enqueue(() => this.database.execute<T>(sql, params));\n  }\n\n  async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {\n    await this.enqueue(async () => {\n      await this.database.execute(sql, params);\n    });\n  }\n\n  async transaction<T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>): Promise<T> {\n    assertTransactionCallbackHasDriverArg(fn);\n\n    return this.enqueue(async () => {\n      await this.database.execute(`BEGIN IMMEDIATE`);\n      try {\n        const result = await fn(this.createTransactionDriver());\n        await this.database.execute(`COMMIT`);\n        return result;\n      } catch (error) {\n        try {\n          await this.database.execute(`ROLLBACK`);\n        } catch {}\n        throw error;\n      }\n    });\n  }\n\n  async transactionWithDriver<T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>): Promise<T> {\n    return this.transaction(fn);\n  }\n\n  async close(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n    this.closed = true;\n\n    if (typeof this.database.close === \"function\") {\n      await Promise.resolve(this.database.close());\n    }\n  }\n\n  private createTransactionDriver(): SQLiteDriver {\n    return {\n      exec: (sql) => this.database.execute(sql).then(() => undefined),\n      query: <T>(sql: string, params: ReadonlyArray<unknown> = []) =>\n        this.database.execute<T>(sql, params),\n      run: (sql: string, params: ReadonlyArray<unknown> = []) =>\n        this.database.execute(sql, params).then(() => undefined),\n      transaction: <T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>) =>\n        this.runNestedTransaction(fn),\n      transactionWithDriver: <T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>) =>\n        this.runNestedTransaction(fn),\n    };\n  }\n\n  private async runNestedTransaction<T>(\n    fn: (transactionDriver: SQLiteDriver) => Promise<T>,\n  ): Promise<T> {\n    assertTransactionCallbackHasDriverArg(fn);\n\n    const savepointName = `tsdb_sp_${this.nextSavepointId}`;\n    this.nextSavepointId++;\n    await this.database.execute(`SAVEPOINT ${savepointName}`);\n    try {\n      const result = await fn(this.createTransactionDriver());\n      await this.database.execute(`RELEASE SAVEPOINT ${savepointName}`);\n      return result;\n    } catch (error) {\n      await this.database.execute(`ROLLBACK TO SAVEPOINT ${savepointName}`);\n      await this.database.execute(`RELEASE SAVEPOINT ${savepointName}`);\n      throw error;\n    }\n  }\n\n  private enqueue<T>(operation: () => Promise<T> | T): Promise<T> {\n    const queuedOperation = this.queue.then(operation, operation);\n    this.queue = queuedOperation.then(\n      () => undefined,\n      () => undefined,\n    );\n    return queuedOperation;\n  }\n}\n","import { BrowserWASQLiteDriver } from \"./browser-wa-sqlite-driver\";\nimport type {\n  BrowserPlatformConfig,\n  BrowserPlatformDeps,\n  BrowserPlatformResult,\n} from \"./browser-types\";\n\nexport type {\n  BrowserCoordinatorInstance,\n  BrowserPlatformConfig,\n  BrowserPlatformDeps,\n  BrowserPlatformResult,\n} from \"./browser-types\";\n\nexport type { BrowserWASQLiteDatabase } from \"./browser-wa-sqlite-driver\";\n\n/**\n * Opens OPFS SQLite, a cross-tab coordinator, and TanStack persistence.\n * Prefer {@link createBrowserEventSourcedDB}; call this only when you need the\n * raw `persistence` / `close` pair (for example a custom handle).\n *\n * @example\n * ```ts\n * import { createBrowserPlatform } from \"event-sourced-collection/browser\"\n * import {\n *   BrowserCollectionCoordinator,\n *   createBrowserWASQLitePersistence,\n *   openBrowserWASQLiteOPFSDatabase,\n * } from \"@tanstack/browser-db-sqlite-persistence\"\n *\n * const platform = await createBrowserPlatform(\n *   {\n *     openBrowserWASQLiteOPFSDatabase,\n *     createBrowserWASQLitePersistence,\n *     BrowserCollectionCoordinator,\n *   },\n *   { databaseName: \"app.sqlite\" },\n * )\n *\n * // pass platform.persistence into createEventSourcedDB\n * await platform.close()\n * ```\n */\nexport async function createBrowserPlatform(\n  deps: BrowserPlatformDeps,\n  config: BrowserPlatformConfig,\n): Promise<BrowserPlatformResult> {\n  const database = await deps.openBrowserWASQLiteOPFSDatabase({\n    databaseName: config.databaseName,\n  } as never);\n\n  const coordinator = new deps.BrowserCollectionCoordinator({\n    dbName: config.coordinatorDbName ?? config.databaseName.replace(/\\.sqlite$/, \"\"),\n  } as never);\n\n  const persistence = deps.createBrowserWASQLitePersistence({\n    database,\n    coordinator,\n  } as never);\n\n  const driver = new BrowserWASQLiteDriver(database);\n\n  return {\n    driver,\n    persistence,\n    close: async () => {\n      coordinator.dispose();\n      await driver.close();\n    },\n  };\n}\n","import {\n  createEventSourcedDBHandle,\n  resolveModules,\n  type ModulesInput,\n} from \"../core/create-event-sourced-db-handle\";\nimport type {\n  CreateCollectionFn,\n  InjectedCreateCollection,\n  InjectedModuleFn,\n  PersistedCollectionOptionsFn,\n} from \"../core/persisted-collection\";\nimport type { EventSourcedSharedOptions, SyncLock } from \"../core/types\";\nimport { createBrowserPlatform } from \"./browser\";\nimport type { BrowserPlatformDeps } from \"./browser-types\";\nimport { createWebLocksSyncLock } from \"./web-locks\";\n\ntype CollectionDefConstraint = {\n  getKey: (state: never) => string | number;\n};\n\nexport type BrowserEventSourcedModules = BrowserPlatformDeps & {\n  createCollection: InjectedCreateCollection;\n  persistedCollectionOptions: InjectedModuleFn;\n};\n\n/**\n * Browser entry-point config. Shared sync/lifecycle fields come from\n * {@link EventSourcedSharedOptions} (hover those properties for docs).\n * Deep guide: `docs/usage.md`.\n */\nexport type BrowserEventSourcedDBConfig<TDefs extends Record<string, CollectionDefConstraint>> =\n  Omit<EventSourcedSharedOptions, \"lock\" | \"lockName\"> & {\n    /**\n     * User collection registry. Object keys become `db.collections.<key>` and\n     * the wire `collectionId`. Must not collide with reserved names.\n     */\n    collections: TDefs;\n    /**\n     * OPFS SQLite database file name (e.g. `\"my-app.sqlite\"`). Also used as the\n     * default sync lock namespace so only one tab syncs for this DB at a time.\n     */\n    databaseName: string;\n    /**\n     * Name for the cross-tab collection coordinator database. Defaults to\n     * `databaseName` with a trailing `.sqlite` stripped.\n     */\n    coordinatorDbName?: string;\n    /**\n     * Browser OPFS persistence modules from\n     * `@tanstack/browser-db-sqlite-persistence` plus `createCollection`.\n     * Pass the imported bindings directly, or a function to keep WASM off the\n     * critical path.\n     */\n    modules: ModulesInput<BrowserEventSourcedModules>;\n    /**\n     * Defaults to a Web Locks–backed lock so only one tab syncs at a time.\n     * Pass `null` to opt out and let every tab sync independently.\n     */\n    lock?: SyncLock | null;\n  };\n\nexport type { EventSourcedDBHandle as BrowserEventSourcedDBHandle } from \"../core/create-event-sourced-db-handle\";\n\n/**\n * Browser-flavoured event-sourced DB: OPFS SQLite + optional Web Locks sync\n * election, returned as a lazy singleton.\n *\n * @param config - See {@link BrowserEventSourcedDBConfig} for every option.\n *\n * @example\n * ```ts\n * import { createBrowserEventSourcedDB } from \"event-sourced-collection/browser\"\n * import type { CollectionDef, EventSourcedDB } from \"event-sourced-collection\"\n *\n * type Todo = { id: string; title: string }\n * type Defs = { todos: CollectionDef<Todo, string> }\n *\n * const { ensureDb, db } = createBrowserEventSourcedDB<Defs>({\n *   databaseName: \"app.sqlite\",\n *   collections: { todos: { getKey: (todo) => todo.id } },\n *   sync: { push: \"/api/sync/events\", pull: \"/api/sync/events\" },\n *   modules: async () => {\n *     const { createCollection } = await import(\"@tanstack/db\")\n *     const {\n *       BrowserCollectionCoordinator,\n *       createBrowserWASQLitePersistence,\n *       openBrowserWASQLiteOPFSDatabase,\n *       persistedCollectionOptions,\n *     } = await import(\"@tanstack/browser-db-sqlite-persistence\")\n *     return {\n *       createCollection,\n *       BrowserCollectionCoordinator,\n *       createBrowserWASQLitePersistence,\n *       openBrowserWASQLiteOPFSDatabase,\n *       persistedCollectionOptions,\n *     }\n *   },\n * })\n *\n * export async function start() {\n *   await ensureDb()\n * }\n * export { db }\n * ```\n */\nexport function createBrowserEventSourcedDB<\n  const TDefs extends Record<string, CollectionDefConstraint>,\n>(config: BrowserEventSourcedDBConfig<TDefs>) {\n  return createEventSourcedDBHandle<TDefs>({\n    guard: assertBrowserEnvironment,\n    setup: async () => {\n      const modules = await resolveModules(config.modules);\n\n      const platform = await createBrowserPlatform(\n        {\n          openBrowserWASQLiteOPFSDatabase: modules.openBrowserWASQLiteOPFSDatabase,\n          createBrowserWASQLitePersistence: modules.createBrowserWASQLitePersistence,\n          BrowserCollectionCoordinator: modules.BrowserCollectionCoordinator,\n        },\n        {\n          databaseName: config.databaseName,\n          coordinatorDbName: config.coordinatorDbName,\n        },\n      );\n\n      return {\n        persistence: platform.persistence,\n        createCollection: modules.createCollection as CreateCollectionFn,\n        persistedCollectionOptions:\n          modules.persistedCollectionOptions as PersistedCollectionOptionsFn,\n        collections: config.collections,\n        sync: config.sync,\n        syncEnabled: config.syncEnabled,\n        schemaVersion: config.schemaVersion,\n        debug: config.debug,\n        clientId: config.clientId,\n        unknownEventHandling: config.unknownEventHandling,\n        pullOverlap: config.pullOverlap,\n        eventSchemaVersion: config.eventSchemaVersion,\n        upcastEvent: config.upcastEvent,\n        retry: config.retry,\n        pushBatchSize: config.pushBatchSize,\n        maxPushBytes: config.maxPushBytes,\n        syncPreset: config.syncPreset,\n        recordLocalEchoes: config.recordLocalEchoes,\n        backendMismatch: config.backendMismatch,\n        conflictDetection: config.conflictDetection,\n        hooks: config.hooks,\n        lock: config.lock === null ? undefined : (config.lock ?? createWebLocksSyncLock()),\n        lockName: config.databaseName,\n        close: platform.close,\n      };\n    },\n  });\n}\n\nfunction assertBrowserEnvironment(): void {\n  if (typeof window === \"undefined\") {\n    throw new Error(\"Event-sourced DB (browser) is only available in a browser environment.\");\n  }\n}\n"],"mappings":"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"}

package/dist/{create-event-sourced-db-handle-BPsVV1x6.mjs → create-event-sourced-db-handle-D23nsV5c.mjs}

@@ -14,6 +14,7 @@ const RESERVED_IDS = /* @__PURE__ */ new Set([
 	SYNCMETA_ID,
 	ROWVERSIONS_ID
 ]);
+const PAYLOAD_TOO_LARGE_ERROR_CODE = "PAYLOAD_TOO_LARGE";
 const SYNC_LOCK_PREFIX = "event-sourced-sync";
 //#endregion
 //#region src/internal/hooks.ts
@@ -480,7 +481,7 @@ var BackendMismatchError = class extends Error {
 	}
 };
 async function pullInbox(args) {
-	const { outbox, inbox, syncmeta, pull, clientId, pullOverlap, context } = args;
+	const { outbox, inbox, syncmeta, pull, clientId, pullOverlap, recordLocalEchoes, context } = args;
 	const { log } = context;
 	let pulled = 0;
 	let skipped = 0;
@@ -513,10 +514,11 @@ async function pullInbox(args) {
 		let halted = false;
 		for (const event of sorted) {
 			if (isLocalOrigin(event, outbox, clientId)) {
-				await markInboxEventResolved(inbox, event);
+				if (recordLocalEchoes) await markInboxEventResolved(inbox, event);
 				log.debug("pull skipped: event originated locally", {
 					eventId: event.eventId,
-					globalSeq: event.globalSeq
+					globalSeq: event.globalSeq,
+					recorded: recordLocalEchoes
 				});
 				continue;
 			}
@@ -945,56 +947,157 @@ async function deadLetter(deadletter, outbox, entry, reason, message, code, now,
 	});
 	emit("onDeadLetter", record);
 }
-/**
-* Splits events into batches of at most `size`, without ever separating events
-* that share a `txId`. The server is asked to commit each transaction
-* atomically, which it cannot do if we deliver half of one now and half later.
-* A single transaction larger than `size` is sent whole rather than split.
-*/
-function batchByTransaction(events, size) {
-	const batches = [];
-	let current = [];
+const utf8 = new TextEncoder();
+function jsonBytes(entry) {
+	return utf8.encode(JSON.stringify(toOutboundEvent(entry))).length;
+}
+/** Events are ordered by localSeq, so one transaction's events are adjacent. */
+function groupByTransaction(events, measure) {
+	const groups = [];
 	for (let index = 0; index < events.length;) {
 		const txId = events[index].txId;
-		const group = [];
+		const group = {
+			entries: [],
+			bytes: 0
+		};
 		while (index < events.length && events[index].txId === txId) {
-			group.push(events[index]);
+			const entry = events[index];
+			group.entries.push(entry);
+			if (measure) group.bytes += jsonBytes(entry) + 1;
 			index++;
 		}
-		if (current.length > 0 && current.length + group.length > size) {
-			batches.push(current);
-			current = [];
+		groups.push(group);
+	}
+	return groups;
+}
+/**
+* Packs transaction groups into batches of at most `size` events and
+* `maxBytes` of JSON, never separating events that share a `txId`: the server
+* commits each transaction atomically, which it cannot do if we deliver half
+* of one now and half later. A transaction with more than `size` events is
+* sent whole; one larger than `maxBytes` is returned in `oversized` instead.
+*/
+function packBatches(groups, size, maxBytes) {
+	const batches = [];
+	const oversized = [];
+	let current = {
+		groups: [],
+		count: 0,
+		bytes: 1
+	};
+	const close = () => {
+		if (current.count > 0) batches.push(current);
+		current = {
+			groups: [],
+			count: 0,
+			bytes: 1
+		};
+	};
+	for (const group of groups) {
+		if (maxBytes !== null && group.bytes + 1 > maxBytes) {
+			oversized.push(group);
+			continue;
+		}
+		const overCount = current.count + group.entries.length > size;
+		const overBytes = maxBytes !== null && current.bytes + group.bytes > maxBytes;
+		if (current.count > 0 && (overCount || overBytes)) close();
+		current.groups.push(group);
+		current.count += group.entries.length;
+		current.bytes += group.bytes;
+		if (current.count >= size) close();
+	}
+	close();
+	return {
+		batches,
+		oversized
+	};
+}
+function isPayloadTooLarge(err) {
+	return typeof err === "object" && err !== null && "status" in err && err.status === 413;
+}
+/**
+* Posts `groups` as one request. On HTTP 413 the request is halved along
+* transaction boundaries and each half posted in turn, down to a single
+* transaction, so one oversized event cannot hold the rest hostage.
+*/
+async function postGroups(push, groups, log) {
+	const entries = groups.flatMap((group) => group.entries);
+	try {
+		const response = normalizePushResponse(await push(entries.map(toOutboundEvent)));
+		return {
+			confirmed: [...response.confirmed],
+			failed: [...response.failed ?? []],
+			tooLarge: [],
+			unsent: []
+		};
+	} catch (err) {
+		if (!isPayloadTooLarge(err)) return {
+			confirmed: [],
+			failed: [],
+			tooLarge: [],
+			unsent: entries,
+			error: err
+		};
+		if (groups.length === 1) {
+			log.warn("push transaction too large for the server", { events: entries.length });
+			return {
+				confirmed: [],
+				failed: [],
+				tooLarge: entries,
+				unsent: []
+			};
 		}
-		current.push(...group);
-		if (current.length >= size) {
-			batches.push(current);
-			current = [];
+		const middle = Math.ceil(groups.length / 2);
+		log.info("push batch hit HTTP 413, splitting", {
+			groups: groups.length,
+			events: entries.length
+		});
+		const first = await postGroups(push, groups.slice(0, middle), log);
+		if (first.error !== void 0) {
+			const rest = groups.slice(middle).flatMap((group) => group.entries);
+			return {
+				...first,
+				unsent: [...first.unsent, ...rest]
+			};
 		}
+		const second = await postGroups(push, groups.slice(middle), log);
+		return {
+			confirmed: [...first.confirmed, ...second.confirmed],
+			failed: [...first.failed, ...second.failed],
+			tooLarge: [...first.tooLarge, ...second.tooLarge],
+			unsent: second.unsent,
+			error: second.error
+		};
 	}
-	if (current.length > 0) batches.push(current);
-	return batches;
+}
+async function deadLetterTooLarge(args, entries, message) {
+	for (const entry of entries) await deadLetter(args.deadletter, args.outbox, entry, "rejected", message, PAYLOAD_TOO_LARGE_ERROR_CODE, args.now, args.emit, args.log, args.rowversions);
+	return entries.length;
 }
 /**
-* Pushes due outbox events in batches. Each batch's result is persisted before
-* the next is sent, so a failure part-way through keeps the progress already
-* made instead of restarting from zero.
+* Pushes due outbox events in batches limited by event count and JSON bytes.
+* Each batch's result is persisted before the next is sent, so a failure
+* part-way through keeps the progress already made instead of restarting.
 */
 async function pushOutbox(args) {
-	const { outbox, push, batchSize, now, log } = args;
+	const { outbox, push, batchSize, maxBytes, now, log } = args;
 	const due = [...outbox.state.values()].filter((entry) => isDue(entry, now)).sort(byLocalSeq);
 	log.debug("push outbox", {
 		dueCount: due.length,
-		batchSize
+		batchSize,
+		maxBytes
 	});
 	if (due.length === 0) return {
 		pushed: 0,
 		deadLettered: 0
 	};
+	const { batches, oversized } = packBatches(groupByTransaction(due, maxBytes !== null), batchSize, maxBytes);
 	let pushed = 0;
 	let deadLettered = 0;
-	for (const batch of batchByTransaction(due, batchSize)) {
+	for (const group of oversized) deadLettered += await deadLetterTooLarge(args, group.entries, `Transaction is ${group.bytes} bytes, over maxPushBytes (${maxBytes})`);
+	for (const batch of batches) {
 		const attempted = [];
-		for (const entry of batch) {
+		for (const group of batch.groups) for (const entry of group.entries) {
 			const attemptCount = (entry.attemptCount ?? 0) + 1;
 			await outbox.update(entry.eventId, (draft) => {
 				draft.syncStatus = "pending";
@@ -1010,27 +1113,17 @@ async function pushOutbox(args) {
 				attemptCount
 			});
 		}
-		let response;
-		try {
-			response = normalizePushResponse(await push(attempted.map(toOutboundEvent)));
-		} catch (err) {
-			deadLettered += await backoffBatch(args, attempted, err);
-			const error = err instanceof Error ? err : new Error(String(err));
-			log.warn("push stopped after transport failure", {
-				message: error.message,
-				pushed,
-				remaining: due.length - pushed
-			});
-			return {
-				pushed,
-				deadLettered,
-				error
-			};
-		}
+		const byId = new Map(attempted.map((entry) => [entry.eventId, entry]));
+		const response = await postGroups(push, batch.groups.map((group) => ({
+			bytes: group.bytes,
+			entries: group.entries.map((entry) => byId.get(entry.eventId))
+		})), log);
 		log.info("push batch confirmed", {
 			sent: attempted.length,
+			bytes: batch.bytes,
 			confirmed: response.confirmed.length,
-			failed: response.failed?.length ?? 0
+			failed: response.failed.length,
+			tooLarge: response.tooLarge.length
 		});
 		for (const confirmation of response.confirmed) {
 			if (!outbox.has(confirmation.eventId)) continue;
@@ -1049,12 +1142,26 @@ async function pushOutbox(args) {
 				globalSeq: confirmation.globalSeq
 			});
 		}
-		const byId = new Map(attempted.map((entry) => [entry.eventId, entry]));
-		for (const failure of response.failed ?? []) {
+		for (const failure of response.failed) {
 			const entry = byId.get(failure.eventId);
 			if (!entry) continue;
 			deadLettered += await handleFailure(args, entry, failure);
 		}
+		deadLettered += await deadLetterTooLarge(args, response.tooLarge, "Server rejected the transaction as too large (HTTP 413)");
+		if (response.error !== void 0) {
+			deadLettered += await backoffBatch(args, response.unsent, response.error);
+			const error = response.error instanceof Error ? response.error : new Error(String(response.error));
+			log.warn("push stopped after transport failure", {
+				message: error.message,
+				pushed,
+				remaining: due.length - pushed
+			});
+			return {
+				pushed,
+				deadLettered,
+				error
+			};
+		}
 	}
 	return {
 		pushed,
@@ -1102,6 +1209,41 @@ async function backoffBatch(args, batch, err) {
 	return deadLettered;
 }
 //#endregion
+//#region src/core/sync-presets.ts
+/**
+* Push limits per hosting platform. Byte caps leave headroom under the
+* platform's request body limit (Vercel functions: 4.5 MB; AWS Lambda and
+* Netlify: 6 MB) for headers and JSON size estimation drift.
+*
+* @example
+* ```ts
+* createBrowserEventSourcedDB({ ..., syncPreset: "vercel" })
+* ```
+*/
+const SYNC_PUSH_PRESETS = {
+	default: {
+		pushBatchSize: 20,
+		maxPushBytes: null
+	},
+	serverless: {
+		pushBatchSize: 25,
+		maxPushBytes: 4e6
+	},
+	vercel: {
+		pushBatchSize: 10,
+		maxPushBytes: 35e5
+	}
+};
+function resolvePushLimits(config) {
+	const preset = SYNC_PUSH_PRESETS[config.syncPreset ?? "default"];
+	const size = Math.floor(config.pushBatchSize ?? preset.pushBatchSize);
+	const bytes = config.maxPushBytes ?? preset.maxPushBytes;
+	return {
+		pushBatchSize: Math.min(100, Math.max(1, size)),
+		maxPushBytes: bytes === null ? null : Math.max(1, Math.floor(bytes))
+	};
+}
+//#endregion
 //#region src/internal/serial-queue.ts
 /**
 * Serializes async work so overlapping callers run one after another instead of
@@ -1280,8 +1422,9 @@ async function createEventSourcedDB(config) {
 	const clientId = { value: config.clientId ?? generateEventId() };
 	const unknownEventHandling = config.unknownEventHandling ?? "skip";
 	const pullOverlap = Math.max(0, config.pullOverlap ?? 0);
+	const recordLocalEchoes = config.recordLocalEchoes ?? true;
 	const eventSchemaVersion = config.eventSchemaVersion ?? 1;
-	const pushBatchSize = Math.max(1, config.pushBatchSize ?? 100);
+	const { pushBatchSize, maxPushBytes } = resolvePushLimits(config);
 	const backendMismatch = config.backendMismatch ?? "resetCursor";
 	const conflictDetection = config.conflictDetection ?? false;
 	const lockName = `${SYNC_LOCK_PREFIX}:${config.lockName ?? "default"}`;
@@ -1297,7 +1440,9 @@ async function createEventSourcedDB(config) {
 		syncEnabled,
 		unknownEventHandling,
 		pullOverlap,
+		recordLocalEchoes,
 		pushBatchSize,
+		maxPushBytes,
 		backendMismatch,
 		conflictDetection,
 		eventSchemaVersion
@@ -1433,6 +1578,7 @@ async function createEventSourcedDB(config) {
 					rowversions,
 					push: transport.push,
 					batchSize: pushBatchSize,
+					maxBytes: maxPushBytes,
 					retry,
 					now: Date.now(),
 					emit,
@@ -1456,6 +1602,7 @@ async function createEventSourcedDB(config) {
 					pull: transport.pull,
 					clientId: clientId.value,
 					pullOverlap,
+					recordLocalEchoes,
 					backendMismatch,
 					context: replayContext
 				});
@@ -2024,6 +2171,6 @@ async function resolveModules(modules) {
 	return typeof modules === "function" ? await modules() : modules;
 }
 //#endregion
-export { generateEventId as a, SyncPushError as c, createEventSourcedDB as i, createHttpTransport as l, resolveModules as n, createEventSourcedLogger as o, createLazySingleton as r, SyncPullError as s, createEventSourcedDBHandle as t, BackendMismatchError as u };
+export { generateEventId as a, resolvePushLimits as c, createHttpTransport as d, BackendMismatchError as f, createEventSourcedDB as i, SyncPullError as l, resolveModules as n, createEventSourcedLogger as o, createLazySingleton as r, SYNC_PUSH_PRESETS as s, createEventSourcedDBHandle as t, SyncPushError as u };
 
-//# sourceMappingURL=create-event-sourced-db-handle-BPsVV1x6.mjs.map
+//# sourceMappingURL=create-event-sourced-db-handle-D23nsV5c.mjs.map