M2: replace shape-specific backend with generic KV doc store (firebase mirror)

Backend was endpoint-mapper (POST /api/campaigns ignores path id, etc). Adapter
translation layer brittle, untested, lost doc identity. Generic contract (Layer 2)
test caught 15 bugs immediately.

Rewrite to firebase-mirror KV model:
- server/db.js: docs table (path PK, parent, data JSON). getDoc/setDoc/updateDoc/
  deleteDoc/getCollection/batchWrite. parent = path prefix for collection queries.
- server/index.js: generic REST (GET/PUT/PATCH/DELETE /api/doc, GET /api/collection,
  POST /api/collection addDoc, POST /api/batch). WS subscribe by path (doc|collection),
  broadcast to doc subs at changed path + collection subs at parent path.
- src/storage/ws.js: thin passthrough adapter. norm() strips firebase prefix.
  initial value via REST (independent of WS connect), subsequent changes via WS.
- shared/turn.js kept (M4 use). server/handlers.js + server.test.js removed (logic
  now in App, backend is dumb KV).
- src/storage/contract.js: flush() bumped to 50ms (WS roundtrip > setTimeout(0)).

Layer 2 test (server/ws-contract.test.js): spins fresh backend per test, runs same
storage contract spec against createWsStorage. Catches adapter translation bugs
that firebase-mock Layer 1 tests cannot.

nanoid v5 ESM breaks jest CJS -> replaced with crypto.randomUUID (Node builtin).

Tests: 114 green (39 shared + 19 ws-contract + 56 frontend).
This commit is contained in:
david raistrick
2026-06-29 13:00:24 -04:00
parent 35cd1581e3
commit 52866784b2
9 changed files with 277 additions and 902 deletions
+5 -6
View File
@@ -14,11 +14,10 @@ TTRPG Initiative Tracker — fork with self-hosted backend. Monorepo via npm wor
package.json # workspaces root
src/ # React frontend (CRA, existing)
App.js # ~2935 lines, Firebase direct (M2 abstracts this)
server/ # Backend: Express + ws + better-sqlite3
index.js # REST + WS bootstrap
db.js # SQLite schema, row mappers
handlers.js # action -> shared turn fn -> tx persist -> broadcast
server.test.js # integration tests
server/ # Backend: generic KV doc store (firebase mirror)
index.js # REST (doc/coll/batch) + WS bootstrap
db.js # SQLite docs table, KV ops, broadcast
ws-contract.test.js # adapter vs live backend (Layer 2)
shared/ # Pure logic, no I/O (client + server + tests import)
turn.js # turn-order state machine
turn.characterization.test.js
@@ -67,7 +66,7 @@ Three commands:
```bash
npm run test:all # runs shared/ + server/ suites in sequence
npm run shared:test # turn logic only (shared/ folder)
npm run server:test # backend REST + combat flow (server/ folder)
npm run server:test # backend ws-contract (adapter vs live backend)
```
What each runs:
+3 -5
View File
@@ -96,11 +96,9 @@ Memory impl: in-memory Map + EventEmitter, for tests (M3).
memory.js # NEW — test only
types.js # interface contract (JSDoc)
server/ # NEW
index.js # Express + ws bootstrap
db.js # better-sqlite3, schema, migrations
turn.js # turn-order logic (pure, server-authoritative)
handlers/ # action handlers (call turn logic, persist, broadcast)
server.test.js # API + WS integration tests
index.js # Express + ws bootstrap, generic KV REST
db.js # better-sqlite3, docs table (KV), broadcast
ws-contract.test.js # adapter vs live backend (Layer 2 test)
shared/ # pure logic, no I/O, importable by client + server + tests
turn.js # turn logic (single source; server imports, tests import)
types.js