[joker-777]

Problem

On the web, LokiJSAdapter can lose data without the app ever finding out:

• Save failures are swallowed. With autosave, Loki saves without a callback, so when an IndexedDB save fails (quota exceeded, aborted transaction, connection closing), nothing reaches WatermelonDB. onQuotaExceededError only fires when the pre-open checker database fails, which a full disk does not trigger. database.write() resolving therefore does not mean the data is on disk (see Save database from in-memory loki db to IndexedDB manually on web Nozbe/WatermelonDB#1329).
• The in-memory fallback is silent. When IndexedDB is unavailable or fails to open, the adapter falls back to LokiMemoryAdapter with only a log line. Setup succeeds, onSetUpError is not called, and the app cannot tell that everything will be lost when the page is closed.
• A deleted database comes back. When another tab deletes the database (e.g. on logout), IncrementalIndexedDBAdapter closes its connection on versionchange. The next autosave in this tab silently re-opens and re-creates the database from this tab's memory. Related multi-tab issue: Schema migration issue - multiple tabs Nozbe/WatermelonDB#1865.

Changes

All new options are additive. Defaults keep today's behaviour, except for the deleted-database case.

• onPersistenceError(error) is wired to Loki's autosaveCallback. It is called once per failure, not on every 500 ms autosave retry, and again if saving fails after it succeeded in the meantime. Raw IDB Events are unwrapped to event.target.error. QuotaExceededErrors are also passed to onQuotaExceededError. Save failures are now always logged, not only in the adapter's debug mode.
• allowInMemoryFallback defaults to true. With false, a missing or unusable IndexedDB fails setup, so onSetUpError is called. The error's cause is the original IDB error.
• onInMemoryFallback(reason) lets an app that keeps the default learn about the fallback, for example to warn the user. It is called once per adapter, even though setting up an empty database opens it twice.
• versionchange: Loki saving is disabled through the existing lokiFatalError path instead of re-creating the database. The driver is put in the broken state, so further changes are rejected while reads still work. onPersistenceError is called with a VersionChangeError, and the app's own onversionchange is still called afterwards. Breaking the driver was factored out of DatabaseDriver._fatalError into _breakDriver, which does not depend on experimentalAllowsFatalError.
• Synchronous access and open errors: if reading indexedDB or calling indexedDB.open throws (e.g. SecurityError when storage access is denied, or in a sandboxed iframe), it is handled like other open failures. It falls back to memory by default, where setup used to fail, or fails setup with allowInMemoryFallback: false.
• Errors thrown by the app's callbacks on these paths are logged, so one failing callback can't skip the others or change the fallback policy.
• Flow types, index.d.ts, the web adapter section of the Setup docs, and the changelog are updated.

Remaining multi-tab caveats (documented, not addressed here)

• Two tabs writing concurrently still overwrite each other's saves, and onDidOverwrite is called. Coordinating writers, for example with Web Locks, is out of scope.
• After versionchange, the tab must be reloaded. There is no in-place recovery.
• The non-incremental LokiIndexedAdapter has no versionchange handling.
• The callbacks only work with useWebWorker: false, like the existing ones.

Usage

const adapter = new LokiJSAdapter({
  schema,
  useWebWorker: false,
  useIncrementalIndexedDB: true,
  onSetUpError: (error) => { /* now also called when IndexedDB is unusable */ },
  allowInMemoryFallback: false,
  onPersistenceError: (error) => { /* warn that recent changes are not saved */ },
})

Tests

src/adapters/lokijs/persistence.test.js uses a fake incremental persistence adapter through _testLokiAdapter and a stubbed indexedDB global. It covers:

• reporting once per failure, unwrapping the event, routing quota errors, and reporting again after a recovery;
• versionchange stopping saves and rejecting writes;
• the fallback with and without allowInMemoryFallback, and the checker open failure.

Jest for src/adapters/lokijs and src/adapters/__tests__ passes, with 150 tests. ESLint, TSLint and Flow are clean.

Validation against a real IndexedDB implementation

The unit tests use a fake persistence adapter. In addition, the cross-tab deletion path was checked once with the real LokiJSAdapter and lokijs IncrementalIndexedDBAdapter on top of fake-indexeddb 6.0.1, a spec-compliant IndexedDB implementation. That check is not committed, because adding a dev dependency would grow the diff.

• Deleted after a save: another connection calls indexedDB.deleteDatabase(). The deletion is not blocked, onversionchange and onPersistenceError are each called once, later writes are rejected, and after several autosave intervals the database still does not exist.
• Deleted while a save is pending: a write is made, then the database is deleted before autosave runs. The database is still not re-created.
• Control: with this PR's versionchange handling disabled, the same scenario re-creates the deleted database.

Jest's sandbox can't simulate a global indexedDB getter that throws. That case was checked with a plain Node script that loads the adapter through Babel. With the fix, the default setup falls back to memory and allowInMemoryFallback: false fails setup, both with the original error as cause. Before the fix, setup failed in both modes.

Validation in a real browser with multiple tabs

This PR's code (commit 9d8c920) was transpiled with the repo's Babel config, bundled with esbuild into a test page, and served from localhost. Each tab of Chromium 152 ran its own LokiJSAdapter on real IndexedDB, with useIncrementalIndexedDB: true, useWebWorker: false and allowInMemoryFallback: false. The test page is not committed.

Scenario	Result
Tab B deletes the database after tab A saved	The deletion is not blocked. Tab A gets onPersistenceError with a VersionChangeError, then onversionchange. Tab A rejects batch and unsafeExecute, and 3 s later the database still does not exist.
Tab B deletes the database while tab A's save is in flight, coordinated over a BroadcastChannel so the delete starts 1 ms after the save	Tab A gets versionchange mid-save and reports once, with no second error for the aborted save. The database is still gone 4 s later.
Logout: tab A resets the database while tab B has it open with 5 records	Tab B is broken and rejects writes. A third tab opening the database finds only tab A's one post-reset record.
Control for the logout scenario, with this PR's versionchange handling disabled	Tab B's next autosave writes its records back: 7 records, including the 5 logged-out ones. Tab A's new record is overwritten.
Tab B deletes the database while tab A is setting up, at delays from 0 to 80 ms	At 0 ms the delete runs before the database exists, and setup creates a fresh one. At 2 and 5 ms, setup fails through onSetUpError after a VersionChangeError. From 10 to 80 ms, setup succeeds, then the driver is broken. In every case where the database existed, it stayed deleted.

The result does not depend on event order. Saving is disabled synchronously in the versionchange handler, and closing the connection lets an in-flight transaction finish before the deletion proceeds. So whichever finishes first, nothing writes to the database after it has been deleted.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The persistence-error handler runs before the driver is marked broken, allowing in-memory writes and thrown callbacks to bypass the broken state and version-change notification; shared options also suppress fallback notifications for separate adapters.

2 open issues

• Mark driver broken before callbacks and preserve version-change handling · New
• Deduplicate fallback notifications per adapter, not per options object · New

What changed in this PR

This PR makes LokiJS persistence failures visible to applications and adds control over in-memory fallback. It also stops saving and rejects further changes when another connection deletes or upgrades the IndexedDB database.

Changes:

• Adds persistence-error reporting, quota-error routing, and configurable in-memory fallback.
• Handles IndexedDB version changes by disabling saves and breaking the driver.
• Adds regression tests, public types, and documentation for the new behavior.

File	Description
src/​adapters/​lokijs/​worker/​lokiExtensions.js	Implements persistence reporting, fallback controls, and version-change handling.
src/​adapters/​lokijs/​worker/​DatabaseDriver.js	Extracts the broken-state transition and connects it to persistence loss.
src/​adapters/​lokijs/​persistence.test.js	Tests save failures, recovery, fallback, and version changes.
src/​adapters/​lokijs/​index.js	Adds Flow options and documents callback behavior.
src/​adapters/​lokijs/​index.d.ts	Adds matching TypeScript option declarations.
docs-website/​docs/​docs/​Setup.md	Documents configuration, durability limits, and multi-tab behavior.
CHANGELOG-Unreleased.md	Records the new options and persistence fixes.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

unsafeResetDatabase() can delete and recreate persistence after versionchange without checking the broken-driver state, while throwing error handlers can suppress required persistence notifications.

1 open issue

• Reject unsafe database resets after the driver is broken · New

2 previously missed issues

In code that hasn't changed since last review

Report persistence errors even when the quota callback throws

src/​adapters/​lokijs/​worker/​lokiExtensions.js:132

A throwing onQuotaExceededError prevents onPersistenceError from receiving the save failure. Since isFailing is already set, subsequent failed retries also skip reporting, leaving the new persistence callback unnotified until a successful save occurs. Invoke onPersistenceError in a finally block so the two callbacks are independent.

Ensure public notifications run when the fatal-error handler throws

src/​adapters/​lokijs/​worker/​lokiExtensions.js:203

If _onFatalError throws, onPersistenceLost(error) propagates that exception from _breakDriver before entering the try block. Both onPersistenceError and the app's onversionchange callback are then skipped, even though persistence has already been permanently disabled. Put this call inside an outer try/finally so both public notifications still run when the fatal-error handler throws.

2 resolved since last review

• Mark driver broken before callbacks and preserve version-change handling
• Deduplicate fallback notifications per adapter, not per options object

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Synchronous IndexedDB access errors and exceptions from the fallback notification can bypass the configured fallback policy, causing setup to fail despite allowing in-memory storage.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Route synchronous IndexedDB access errors through fallback handling

src/​adapters/​lokijs/​worker/​lokiExtensions.js:67

IndexedDB access can throw synchronously (for example, a SecurityError when storage access is denied). In that case, checkIDB() rejects instead of returning an error, so this await bypasses the fallback handling below: allowInMemoryFallback: true fails setup without notifying onInMemoryFallback, and false receives an unwrapped error without the promised original cause. Convert the rejection into the error result so both cases use the same fallback/refusal path.

Guard fallback notification so callback errors do not prevent memory setup

src/​adapters/​lokijs/​worker/​lokiExtensions.js:95

If onInMemoryFallback throws (for example, while displaying the warning), getLokiAdapter() rejects before constructing the memory adapter, so setup fails even with allowInMemoryFallback: true. Invoke this notification through callSafely, like the persistence notifications, so an application callback failure does not change the configured fallback policy.

1 resolved since last review

• Reject unsafe database resets after the driver is broken

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Human review is needed to assess a quota-callback path that can hang setup and a regression test that does not actually exercise shared options.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Fake-adapter tests leave the real LokiJS/IndexedDB cross-tab deletion and pending-save lifecycle unverified, requiring browser integration validation to confirm deleted databases cannot be recreated.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

After a version change breaks the driver, unsafeExecute() still permits raw writes that modify memory while persistence is permanently disabled.

1 open issue

• Reject unsafeExecute writes after the driver is broken · New

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

A critical database-reset race and a storage-denial fallback issue omitted from the published review require human assessment.

No open issues 🎉

1 resolved since last review

• Reject unsafeExecute writes after the driver is broken

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Permanent persistence shutdown on cross-tab deletion depends on IndexedDB event ordering, and fake-adapter tests leave real-browser two-tab validation during in-flight saves and setup/reset unresolved.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

A critical race in DatabaseDriver.js can reopen persistence after a versionchange breaks the driver during deletion, leaving autosave enabled and allowing the deleted database to be recreated.

1 open issue

• Recheck broken driver state before reopening persistence · New

_{Review effort: Balanced}

[joker-777]

Offered upstream as Nozbe#1979, rebuilt on upstream master.