event-sourced-collection 0.0.7 → 0.0.9

package/ARCHITECTURE.md

@@ -98,13 +98,13 @@ bundles free of browser APIs.
 
 ### Reserved collections
 
-| Id | Role |
-| -- | ---- |
-| `outbox` | Local mutations; push due set |
-| `inbox` | Pulled events; replay / skip markers |
-| `deadletter` | Terminal push failures and unapplicable pulled events |
-| `syncmeta` | Singleton: cursor, backendId, clientId, lastSyncAt, lastError |
-| `rowversions` | Last applied event id per row (conflict detection only) |
+| Id            | Role                                                          |
+| ------------- | ------------------------------------------------------------- |
+| `outbox`      | Local mutations; push due set                                 |
+| `inbox`       | Pulled events; replay / skip markers                          |
+| `deadletter`  | Terminal push failures and unapplicable pulled events         |
+| `syncmeta`    | Singleton: cursor, backendId, clientId, lastSyncAt, lastError |
+| `rowversions` | Last applied event id per row (conflict detection only)       |
 
 User collection ids must not collide with these.
 
@@ -158,13 +158,13 @@ path). Deferred lock acquisition returns `{ deferred: true }` without firing
 
 **Why:**
 
-| Factor               | One Mixed Table                                          | Outbox + Inbox                                              |
-| -------------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
-| Mental model         | A single row could be "ours, pending" or "theirs, synced" | Direction is explicit: outbox = ours, inbox = theirs        |
-| Per-row `sync` flag  | Overloaded — means "pushed" or "applied" depending on row | Unambiguous — outbox `sync` = pushed, inbox `sync` = replayed |
-| Visualization        | Needs raw SQL access to inspect                          | Just `useLiveQuery(db.collections.outbox)`                  |
-| Cursor               | Dedicated `esdb_cursor` row to keep in step              | A single `syncmeta` row, seeded from inbox state on upgrade |
-| Storage layer        | Hand-rolled SQLite table + indexes                       | Reuses TanStack DB persistence (reactive, multi-tab aware)  |
+| Factor              | One Mixed Table                                           | Outbox + Inbox                                                |
+| ------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
+| Mental model        | A single row could be "ours, pending" or "theirs, synced" | Direction is explicit: outbox = ours, inbox = theirs          |
+| Per-row `sync` flag | Overloaded — means "pushed" or "applied" depending on row | Unambiguous — outbox `sync` = pushed, inbox `sync` = replayed |
+| Visualization       | Needs raw SQL access to inspect                           | Just `useLiveQuery(db.collections.outbox)`                    |
+| Cursor              | Dedicated `esdb_cursor` row to keep in step               | A single `syncmeta` row, seeded from inbox state on upgrade   |
+| Storage layer       | Hand-rolled SQLite table + indexes                        | Reuses TanStack DB persistence (reactive, multi-tab aware)    |
 
 Three more reserved collections support the sync loop: `deadletter` (events that
 will never be retried, in either direction), `syncmeta` (one row holding the pull
@@ -174,7 +174,7 @@ cursor, the backend identity, and this device's own identity), and `rowversions`
 **Per-row sync semantics:**
 
 - **outbox** — `sync: false` means the mutation has not been pushed yet. `sync: true` means the server accepted it (no errors) and assigned a `globalSeq`.
-- **outbox `syncStatus`** — `pending` means eligible to send, `synced` means confirmed, and `failed` means the server rejected it but marked it retryable; `nextAttemptAt` records when the backoff window opens. A rejection that is *not* retryable never lingers as `failed` — it moves straight to `deadletter`.
+- **outbox `syncStatus`** — `pending` means eligible to send, `synced` means confirmed, and `failed` means the server rejected it but marked it retryable; `nextAttemptAt` records when the backoff window opens. A rejection that is _not_ retryable never lingers as `failed` — it moves straight to `deadletter`.
 - **inbox** — `sync: false` means the event was pulled but not yet resolved. `sync: true` means resolved: applied on top of the local data, originated locally and already applied before push, or deliberately skipped. Skipped rows carry `skipped: true` and a `skipReason`, and still allow the cursor to advance.
 - **deadletter** — terminal. Rows carry a `direction` (`outbound` / `inbound`) and a `reason` (`rejected`, `maxAttemptsExceeded`, `conflict`, `replayFailed`, `manual`), and only move via `retryDeadLetter()` or `discardDeadLetter()`. `retryDeadLetter()` returns each event to the queue it came from: the outbox for outbound, the inbox for inbound.
 
@@ -332,12 +332,12 @@ const { ensureDb, db } = createBrowserEventSourcedDB({
 
 **Why:**
 
-| Factor | BIGSERIAL (`global_seq`) | UUIDv7 |
-| ------ | ------------------------ | ------ |
-| Storage per event | 8 bytes | 16 bytes |
-| Index / cursor | Dense integer compare | Lexicographic string |
-| Who assigns order | One server (authority) | Whoever mints the UUID |
-| Multi-device → one API → one DB | Correct | Unnecessary for order |
+| Factor                               | BIGSERIAL (`global_seq`)      | UUIDv7                                                      |
+| ------------------------------------ | ----------------------------- | ----------------------------------------------------------- |
+| Storage per event                    | 8 bytes                       | 16 bytes                                                    |
+| Index / cursor                       | Dense integer compare         | Lexicographic string                                        |
+| Who assigns order                    | One server (authority)        | Whoever mints the UUID                                      |
+| Multi-device → one API → one DB      | Correct                       | Unnecessary for order                                       |
 | Multiple independent write primaries | Needs a distributed sequencer | Helps generate unique sortable IDs without a central SERIAL |
 
 **“Distributed writers” means multiple databases minting order, not multiple
@@ -351,11 +351,11 @@ require switching to UUIDv7. Server-minted UUIDv7 before commit has the same gap
 
 How to handle it (pick at least one server-side approach):
 
-| Approach | Where | Notes |
-| -------- | ----- | ----- |
-| `pg_advisory_xact_lock` around insert | Server push | One writer assigns+commits at a time; simplest correct fix |
-| Serve only `global_seq < pg_snapshot_xmin(...)` | Server pull | Never returns in-flight sequences |
-| `pullOverlap` | Client | Fallback; narrows the window, does not close it |
+| Approach                                        | Where       | Notes                                                      |
+| ----------------------------------------------- | ----------- | ---------------------------------------------------------- |
+| `pg_advisory_xact_lock` around insert           | Server push | One writer assigns+commits at a time; simplest correct fix |
+| Serve only `global_seq < pg_snapshot_xmin(...)` | Server pull | Never returns in-flight sequences                          |
+| `pullOverlap`                                   | Client      | Fallback; narrows the window, does not close it            |
 
 Annotated handlers (plain comments, not a checklist):
 [`examples/postgres-sync-server/`](./examples/postgres-sync-server/).
@@ -439,7 +439,7 @@ event applied to that row) and sends it with the event. The server rejects the
 push with code `CONFLICT` when the row has moved on. Off by default.
 
 **Why not always on:** it costs a write to the `rowversions` index on every
-mutation *and* every replay. Single-device apps get nothing for that.
+mutation _and_ every replay. Single-device apps get nothing for that.
 
 **What it does not do:** there is no rebase. A losing event goes to the
 dead-letter queue with `reason: "conflict"` and stops there. Resolution is your
@@ -447,7 +447,7 @@ application's job — show the user both versions, re-apply on top of the new
 state, or discard.
 
 **Without it,** the semantics are not "last writer wins" but **"stale writer
-wins"**: a pending local write pushed *after* a conflicting server event was
+wins"**: a pending local write pushed _after_ a conflicting server event was
 pulled lands at a higher `global_seq` and overwrites it, with neither side able
 to detect that it happened. For single-user single-device this never comes up;
 for multi-device it is real, silent data loss on concurrently edited rows.
@@ -499,7 +499,7 @@ row is resolved as skipped, and the cursor advances past it.
 **Why:** replay used to rethrow. Because the cursor only advances past resolved
 events, one event the local schema could not accept — a constraint violation, a
 row referencing something this build does not have — stopped that client pulling
-*anything* ever again. Every later event queued behind it silently, and the only
+_anything_ ever again. Every later event queued behind it silently, and the only
 symptom was a repeating error in `lastError`. Outbound events had a full
 retry-then-park pipeline; inbound events had none, despite being the direction
 the client has no control over.
@@ -529,7 +529,7 @@ by checking `outbox.has(eventId) || event.clientId === clientId`. The `clientId`
 half exists precisely so that origin detection keeps working after the outbox has
 been pruned — but a per-process id makes that half useless the moment the page
 reloads. A client that had pruned its outbox and then rewound its cursor (via
-`pullOverlap`, or via a `resetCursor` backend mismatch) would re-apply its *own*
+`pullOverlap`, or via a `resetCursor` backend mismatch) would re-apply its _own_
 history as if it were remote. Replaying an old insert is harmless; replaying an
 old delete silently destroys whatever now lives at that key.
 
@@ -547,7 +547,7 @@ each batch's confirmations are persisted before the next request goes out.
 
 **Why:** a device offline for a week comes back with thousands of pending
 events. One unbounded POST either times out or exceeds a body limit, and on
-failure *nothing* is durable — the next attempt does exactly the same thing and
+failure _nothing_ is durable — the next attempt does exactly the same thing and
 fails the same way. Batching makes the work resumable.
 
 A transport-level failure stops the loop and is reported alongside the counts
@@ -566,7 +566,7 @@ and lets a batch exceed `pushBatchSize` rather than split one.
 
 **Decision:** The pull response may carry a `backendId`. The client stores the
 first one it sees and compares on every subsequent sync. On mismatch the default
-policy `resetCursor` clears the inbox, re-pulls from zero, *and* marks every
+policy `resetCursor` clears the inbox, re-pulls from zero, _and_ marks every
 retained outbox event pending again so local history is re-uploaded.
 
 **Why:** the cursor is just an integer. Wiping or swapping the server restarts
@@ -581,7 +581,7 @@ client already flipped to `sync: true` describe data the replacement backend has
 never seen; without the requeue the client keeps them locally, believes they are
 safely synced, and never uploads them again — so a restored-from-backup server
 quietly loses every write made since the backup. Push is idempotent by `eventId`,
-so re-uploading to a *restored* backend is a no-op rather than a duplicate.
+so re-uploading to a _restored_ backend is a no-op rather than a duplicate.
 
 The reset is only discovered during pull, after this sync's push has run, so the
 requeued events would otherwise sit unsent until the next sync. `pushPull` runs a
@@ -607,8 +607,8 @@ replays events written by the old shape into code expecting the new one. Without
 a version there is nothing to branch on and the mismatch surfaces as corrupt
 data rather than an error.
 
-**Asymmetric default:** with no upcaster, *older* events are applied as-is with
-a warning (usually additive changes, usually fine), but *newer* events are
+**Asymmetric default:** with no upcaster, _older_ events are applied as-is with
+a warning (usually additive changes, usually fine), but _newer_ events are
 refused via `unknownEventHandling`. This build cannot know what a future field
 means, and guessing is worse than skipping.
 
@@ -802,10 +802,10 @@ const offlineSync = createOfflineTransaction({
 
 **How they help us:**
 
-| Problem                                 | Solution with Virtual Props                              |
-| --------------------------------------- | -------------------------------------------------------- |
-| "Which todos haven't synced yet?"       | `where(({ todo }) => eq(todo.$synced, false))`           |
-| "Show a spinner on unsynced items"      | Render based on `todo.$synced` in the UI                 |
+| Problem                                 | Solution with Virtual Props                                  |
+| --------------------------------------- | ------------------------------------------------------------ |
+| "Which todos haven't synced yet?"       | `where(({ todo }) => eq(todo.$synced, false))`               |
+| "Show a spinner on unsynced items"      | Render based on `todo.$synced` in the UI                     |
 | "Skip re-logging server-applied events" | Already handled — `acceptMutations` bypasses the write hooks |
 
 **Note:** This library no longer needs a re-logging guard. Server replay goes through `acceptMutations`, which never invokes the outbox-logging hooks (see Design Decision #4). Virtual props remain useful for surfacing optimistic vs confirmed state in the UI.
@@ -888,7 +888,7 @@ Two devices that edit the same row between syncs end up disagreeing, and neither
 notices. Say `a` and `b` both edit row `t1`; `a`'s event lands at `globalSeq` 2
 and `b`'s at 3, so the server's answer is unambiguously `b`. `a` pulls both,
 skips its own event 2, applies 3, and is correct. `b` pulls both, applies `a`'s
-event 2, then reaches its *own* event 3 and skips it as local origin — so `b`
+event 2, then reaches its _own_ event 3 and skips it as local origin — so `b`
 finishes holding `a`'s value while everyone else holds `b`'s.
 
 The origin skip is not incidental: it is what stops a client re-applying its own
@@ -920,7 +920,7 @@ increment `attemptCount` and schedule backoff. A long offline window can exhaust
 ### 2. Outbox durability vs state durability
 
 `persistedCollectionOptions` wraps our mutation hook: it awaits the hook (the
-outbox append) and *then* calls `persistAndConfirmCollectionMutations` to write
+outbox append) and _then_ calls `persistAndConfirmCollectionMutations` to write
 collection state. So the previously documented hazard — state persisting with no
 event — does not occur: if the outbox append rejects, state is never written and
 TanStack rolls the optimistic mutation back. That direction is pinned by the
@@ -929,7 +929,7 @@ TanStack rolls the optimistic mutation back. That direction is pinned by the
 The remaining exposure is the mirror image. The outbox append has already
 committed by the time the state write runs, so a state write that fails leaves an
 event with no local row. The mutation rejects and the optimistic value is rolled
-back, but the event survives, gets pushed, and materialises on every *other*
+back, but the event survives, gets pushed, and materialises on every _other_
 device. The authoring client then skips it on pull as its own echo and never
 materialises it — the one device that originated the row is the only one without
 it.

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+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.7] - 2026-08-09
+
+Reliability-focused release: dead-lettering, backend identity, retries, conflict detection, multi-tab locking, React helpers, and published examples.
+
+### Added
+
+- Dead-letter collection for permanently rejected or exhausted outbound/inbound events
+- `backendId` / `backendMismatch` handling (`resetCursor` | `fail` | `ignore`) and `BackendMismatchError`
+- Retry config with exponential backoff; batched push that preserves earlier batch progress on failure
+- `getSyncStatus()` / `subscribeSyncStatus()` for pending/failed/synced observability
+- `pruneSyncedEvents()` to compact confirmed outbox and resolved inbox rows
+- Optional conflict detection via `rowversions` + `baseVersion`
+- Lifecycle `hooks` (`onMutation`, `onSyncStart`, `onEventPushed`, `onBackendMismatch`, `onDeadLetter`, …)
+- Event schema evolution: `eventSchemaVersion`, `upcastEvent`, `unknownEventHandling`
+- Multi-tab sync lock via Web Locks (`createWebLocksSyncLock`, `supportsWebLocks`); `lock: null` to opt out
+- `createMockSyncBackend()` for in-memory push/pull tests (pagination, rejections, backend reset)
+- `event-sourced-collection/react` entry: `useManualSync`, `useSyncEnabled`, `formatManualSyncMessage`
+- Published examples: `examples/web-worker-sync/` (Dedicated Worker transport) and `examples/postgres-sync-server/`
+- Repository and bugs metadata on the package
+
+### Changed
+
+- Sync transport surface expanded (`SyncLock`, `SyncStatus`, `RetryConfig`, prune/hook types, …)
+- Package `files` now includes `examples/`
+
+## [0.0.6] - 2026-06-24
+
+### Changed
+
+- Documentation and project-structure guidance for browser apps (`collections.ts`, settings, sync wrappers)
+
+## [0.0.5] - 2026-06-24
+
+### Added
+
+- `CollectionIndexDef` and typed collection index registration on defs
+
+## [0.0.2] - 2026-06-24
+
+### Added
+
+- `createLazySingleton()` for deferred DB init (`ensure` / `proxy` / `reset`)
+- `ARCHITECTURE.md` shipped with the package
+
+## [0.0.1] - 2026-06-23
+
+### Added
+
+- Initial release: `createEventSourcedDB`, browser and React Native helpers
+- Outbox / inbox sync over `SyncTransport` or `createHttpTransport`
+- `createEventSourcedLogger`, `generateEventId` (UUIDv7)
+- Platform entry points: `event-sourced-collection/browser`, `event-sourced-collection/react-native`
+
+[0.0.7]: https://www.npmjs.com/package/event-sourced-collection/v/0.0.7
+[0.0.6]: https://www.npmjs.com/package/event-sourced-collection/v/0.0.6
+[0.0.5]: https://www.npmjs.com/package/event-sourced-collection/v/0.0.5
+[0.0.2]: https://www.npmjs.com/package/event-sourced-collection/v/0.0.2
+[0.0.1]: https://www.npmjs.com/package/event-sourced-collection/v/0.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 my-tanstack-db-collections contributors
+Copyright (c) 2026 locally-first contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal