Eve library

Code Style Guide

Guide

Revision 1

On this page

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; use unknown
    • 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 an if (...) { line), add // prettier-ignore above it.

Naming & structure#

  • Files: kebab-case.ts; one cohesive module per file.
  • DB layer: <resource>-store.ts exposing a <Resource>Store class; routes in routes/<resource>.ts keep 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 run pnpm install.
  • No duplicate imports / unused imports — ESLint blocks the commit.