Demeter follows the monorepo's shared TypeScript style, enforced by ESLint +
Prettier (run via lint-staged on commit). This guide captures the conventions
that matter most.
Language & types#
- TypeScript everywhere by default; reach for Rust/WASM only for performance-critical kernels (not applicable to most Demeter code).
- Prefer explicit, descriptive types on public APIs. Avoid
any; useunknown- narrowing at boundaries.
- Validate external input with Zod at the route boundary; let inferred types flow inward.
Formatting#
- Prettier is the source of truth — don't hand-format. It runs on staged files automatically.
- Note: Prettier relocates trailing comments after
{; when a comment must stay put (e.g. an annotation on anif (...) {line), add// prettier-ignoreabove it.
Naming & structure#
- Files:
kebab-case.ts; one cohesive module per file. - DB layer:
<resource>-store.tsexposing a<Resource>Storeclass; routes inroutes/<resource>.tskeep Zod + Fastify schemas and delegate persistence. - Domain objects use camelCase with ISO-string timestamps; DB rows use
snake_case(see data models). - Match the surrounding code's idiom and comment density; write comments that explain why, not what.
The stub linter#
A custom ESLint plugin + a pre-commit scan reject stub indicators in logic:
TODO/FIXME, "in production this would…", Math.random() standing in for a
computed result, hardcoded returns with excuse comments, and "simulated"
backends. Genuine false positives are suppressed inline with
// stub:legitimate <reason> (same line) — see contributing.
Fastify plugins#
Wrap plugins with fastify-plugin, pin fastify: '5.x', and register
cross-cutting concerns in buildServer() before routes (see
ADR-0002).
Imports & dependencies#
- Use workspace path aliases (
@demeter/*,@oshun/*); no deep relative reaches across packages. - Add dependencies via the pnpm catalog (
catalog:refs) and runpnpm install. - No duplicate imports / unused imports — ESLint blocks the commit.