PotentialStorage/CLAUDE.md

PotentialStorage

Layered TypeScript storage library: KV → Events → Documents. The full design, milestones and implementation decisions are in DESIGN.md — read it before changing anything. Record new decisions in DESIGN.md section 12.

Commands

• npm test — tsc --noEmit then all Vitest tests (including *.test-d.ts type tests)
• npm run test:only -- <file> — Vitest only, e.g. a single file
• npm run typecheck — tsc --noEmit over src, test and bench
• npm run bench — vitest bench
• npm run build — emit dist/
• npm run format / npm run format:check — Prettier

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

Rules

• No runtime dependencies in src/. Dev dependencies only.
• Drivers stay flat and string-keyed; all path/index/escaping logic lives in the node classes.
• Self vs child dispatch is by arguments.length; a passed-but-undefined/null key throws.
• Multi-result reads are AsyncIterable; don't build large arrays internally.
• Keep tests green and commit per milestone. Ask the owner before pushing.