Skip to content

feat(persistence): report every persistence failure with its flow and operation - #14

Merged
bcheung merged 1 commit into
mainfrom
feat/persistence-error-context
Nov 6, 2026
Merged

bcheung merged 1 commit into
mainfrom
feat/persistence-error-context

Conversation

@bcheung

@bcheung bcheung commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Description

Persistence failures are hard to report reliably today:

  • createPersister catches store errors itself and only calls its own onError, so onPersistenceError on <Flow>/FlowProvider never hears about a failed localStorage write or AsyncStorage read.
  • onPersistenceError gets only the error, with no way to tell which flow or operation failed.
  • incompatible_state is reported twice: once to onDiscard and again to onPersistenceError.
  • kvStorageAdapter.get turns read failures and corrupted data into null, so they look exactly like "nothing saved".

After this change, one handler sees every failure, once, with context:

<FlowProvider
  config={{
    persister: createPersister({ store: createLocalStorageStore() }),
    onPersistenceError: (error, { flowId, operation, instanceId, variantId }) => {
      errorTracker.capture(error, { tags: { flowId, operation } });
    },
  }}
>
  • onPersistenceError(error, info): info is { flowId, operation: "save" | "restore" | "remove", instanceId?, variantId? }. Handlers that only take error keep working.
  • Per-call onError on the persister: save(), restore() and remove() accept onError, which replaces the persister's onError for that call (the same rule onDiscard already follows). <Flow> passes one whenever onPersistenceError is set, so failures caught inside the persister reach it and the persister's onError doesn't also fire. Without a Flow/provider handler, the persister's onError runs as before. Custom persisters should call the per-call onError when an operation fails.
  • incompatible_state reported once: to onDiscard when one is set, otherwise to onPersistenceError.
  • kvStorageAdapter.get throws when the storage read fails or stored data can't be deserialized. The persister reports it and restores nothing, so the flow still starts fresh. This covers the localStorage, sessionStorage and AsyncStorage stores. list() still skips unreadable entries.
  • Error handlers that throw no longer reject the persister's promise; they log a development-only warning.

New exported types: FlowPersistenceErrorInfo, FlowPersistenceOperation, FlowPersistenceErrorHandler.

Type of Change

  • 🐛 Bug fix
  • ✨ New feature
  • 💥 Breaking change
  • 📝 Documentation
  • ♻️ Refactoring
  • ✅ Tests

Breaking for apps that set both onPersistenceError and a persister onError (the persister's no longer fires for those flows), apps that relied on incompatible_state reaching both callbacks, and custom stores built on kvStorageAdapter that expected get never to throw.

Checklist

  • Tests pass (bun run test)
  • Types are valid (bun run typecheck)
  • Code is formatted (bun run check)
  • Added/updated tests
  • Updated docs (if needed)
  • Added changeset (if needed - run bun changeset)

Testing

  • bun run test: 405 tests pass. Of the 14 new tests, 9 fail on main and 5 pass on both (fallback and compatibility cases).
  • Core: per-call onError replaces the persister's for save, restore and remove; the persister's onError is still used when no per-call handler is given; the handler isn't forwarded to the store; a throwing handler doesn't reject; corrupted stored JSON reaches onError and restore returns null.
  • React: a store failure caught inside createPersister reaches the provider's onPersistenceError with { flowId, operation: "restore", instanceId, variantId }, and the persister's onError doesn't fire; save failures report operation: "save"; without a Flow handler the persister's onError still runs; incompatible_state without onDiscard reaches onPersistenceError exactly once, and with onDiscard it doesn't reach onPersistenceError; a one-argument handler still type-checks.
  • Docs build passes.

@bcheung
bcheung merged commit 778299f into main Nov 6, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant