Coding Standards¶
TypeScript¶
Module System¶
- ESM only (
"type": "module"in all package.json files) - Use
.jsextensions in import paths (required for NodeNext module resolution) - Prefer named exports over default exports
Naming¶
camelCasefor variables, functions, and object propertiesPascalCasefor types, interfaces, classes, and React componentsSCREAMING_SNAKE_CASEfor constants and enum values- File names:
kebab-case.tsfor modules,PascalCase.tsxfor React components
Error Handling¶
- Use explicit error returns or typed Result patterns over thrown exceptions
- Catch at system boundaries (HTTP handlers, event listeners), not in internal functions
- Log errors with structured context (tracing fields), not bare
console.error
Imports¶
Order imports in groups separated by blank lines:
- Node built-ins (
node:fs,node:path) - External packages (
fastify,react) - Internal packages (
@sardeenz/types,@sardeenz/utils) - Relative imports (
./routes,../config)
Type Safety¶
strict: trueis non-negotiable- Never use
any— useunknownand narrow - Use
@sardeenz/typesfor all contract-derived types — never duplicate definitions
Rust¶
General¶
- Follow standard Rust conventions and idioms
- Target Rust edition 2021, MSRV 1.86
- Run
cargo clippy -- -D warningsbefore committing
Error Handling¶
- Use
thiserrorfor library-style error types - Use
anyhowfor application-level error propagation - Always provide context with
.context()or custom error variants
Naming¶
snake_casefor variables, functions, and modulesPascalCasefor types, structs, enums, and traitsSCREAMING_SNAKE_CASEfor constants
Module Organization¶
- Keep
main.rsminimal — delegate to modules - One public type per module when the type is complex
- Use
mod.rs-free module style (module_name.rs+module_name/for submodules)
Cross-Language Alignment¶
OpenAPI contracts bridge the Rust and TypeScript sides. Naming conventions differ by language but map predictably:
| JSON (contract) | TypeScript | Rust |
|---|---|---|
modelId |
modelId |
model_id |
ModelState |
ModelState |
ModelState |
LOADING |
ModelState.LOADING |
ModelState::Loading |
serde rename attributes handle the Rust ↔ JSON mapping automatically. TypeScript types are generated and match JSON conventions directly.
Documentation¶
- Every directory under
docs/must have aREADME.mdthat serves as an index for that folder. - Every Markdown file must be linked from the
README.mdof its parent directory. No orphan docs — if it's not referenced, it's invisible. - Keep README index entries short: a link and a one-line description, not a full summary.