# PotentialStorage

Layered TypeScript storage library: KV → Events → Documents. The design is in
[DESIGN.md](./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 20 and 22.

## 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.
- No runtime dependencies. 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.