Harvmaster/PotentialStorage

Fork 0

Files

T

Claude 4ffbc7e78d

CI / Node 24 (pull_request) Failing after 12s

Details

CI / Node 22 (pull_request) Successful in 14s

Details

CI / Node 26 (pull_request) Failing after 21s

Details

Add KVStorageComposite, IndexedDB storage and SSE change streams

- Every KV storage emits change events (base class owns writeMany/removeMany/
  writeIfAbsent; implementations provide protected apply* methods)
- KVStorageHttpServer streams changes over SSE (GET /events) with a resumable
  history; KVStorageHttp.watch() subscribes and resumes via Last-Event-ID
- KVStorageIndexedDB for local persistence
- KVStorageComposite keeps replicas of a source in sync: local reads, resume
  instead of full sync, offline outbox replayed in order, echo tracking
- Values may contain bigint/Uint8Array (Extended JSON over the network)
- Vendor sse-session, event-emitter and extended-json (no runtime deps)
- Freeze child nodes so shadowed state on children fails loudly
- CI on Node 22, 24 and 26

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Qxbkp4tA7G5SCWjzWuxmE

2026-10-23 08:41:42 +00:00

1.5 KiB

Raw Blame History

PotentialStorage

Layered TypeScript storage library: KV → Events → Documents. The design is in DESIGN.md; read it before changing anything and keep it up to date.

Commands

npm test: tsc --noEmit, then all Vitest tests (including test/types.test-d.ts)
npm run test:only -- <file>: Vitest only
npm run typecheck, npm run build, npm run bench
npm run format / npm run format:check: Prettier

CI (.gitea/workflows/ci.yml, Gitea Actions) runs the format check, typecheck, tests and build on Node 22, 24 and 26.

Conventions

One abstract base class per layer (src/<layer>/base-*.ts); implementations only provide the raw primitives, and the user-facing API lives in the base class.
Classes over loose functions; TS private, not #; no overloads (use param? or tuple-union rest params); don't override base methods in subclasses.
Never reassign a field after construction. child() nodes are frozen Object.create(root) views, so this.x = ... on a child throws. Keep mutable state in a private readonly state object or in Maps (see KVStorageComposite, KVStorageHttp).
No runtime dependencies; third-party code is vendored (src/utils/sse-session/, event-emitter.ts, extended-json.ts, with a header naming the source). Tests live only in test/, mirroring src/.
New KV/document implementations must pass test/kv-storage/kv-storage.conformance.ts / test/document-storage/document-storage.suite.ts.
Ask the owner before pushing.

1.5 KiB Raw Blame History

PotentialStorage

Commands

Conventions

1.5 KiB

Raw Blame History