Code TS

code-ts

Vanilla TS conventions (PascalCase types, kebab-case files, use-* hooks) are table stakes — assume them. This is the taste on top. Where naming decides the boundary of a module, code-ts decides what the code inside that boundary looks like so it stays testable and the boundary keeps doing its job.

One class or one namespace per file

The exported unit should be a single thing a test can target: one class with cohesive methods, or one export namespace (or const-as-namespace) wrapping related functions. Avoid the alternative — a file that exports ten free functions and a handful of types side-by-side.

Why:

• import { css } from "./css" then asserting against css.toReactCSSProperties(...) mirrors the file's structure 1:1. Tests, callers, and grep all read the same shape.
• Scattering free exports loses the gate naming worked to establish. The file becomes a bag — anything can drift in alongside.
• The unit becomes mockable and replaceable as a contract, not a pile of helpers.

The repo lives this. editor/grida-canvas/data-transfer.ts is a 24-line export namespace datatransfer carrying a type, a key, and an encode/decode pair, and nothing else. editor/grida-canvas-utils/css.ts is a single export namespace css with ~20 CSS-conversion functions inside, paired one-to-one with editor/grida-canvas-utils/css.test.ts. editor/grida-canvas/editor.ts is the Editor class — the engine's front door, one contract surface for everything downstream.

Not class or namespace everywhere

This is not "always use a class" or "always use a namespace." It is that the code most worth grouping in this repo — engine logic, library modules, contract-bearing utilities — is overwhelmingly stateful or spec-bearing, and reads better that way. UI glue, route handlers, one-shot scripts, and small page-local helpers can be plain exports.

Heuristic: if the filename is a noun that naming would approve (one concept, strict, honest), the contents probably want to live under that noun as a class or namespace. If the file is named for its location in a feature flow (page.tsx, loader.ts, route.ts), free exports are fine.

Consolidate, don't fragment

Prefer one coherent file with a namespace of five methods over five files each exporting one function. Five files force callers to remember five paths and force you to invent five names that didn't need to exist; one namespace exposes one path with five methods, and shared private helpers stay private without ceremony.

This is the inside-the-file consequence of the same discipline naming applies at the directory level — flatten with siblings, don't nest to hide drift. Siblings (the painter.rs / painter_geometry.rs pattern) are for things that earned their own gate, not for shaving a namespace into chunks.

The negative tell: a directory whose index.ts is a wall of re-exports from one-function files. That is a namespace pretending to be a folder.