code-ts

name

code-ts

description

TypeScript code shape inside a well-named module — taste, not lint. Prefer one class or namespace per file (the unit a test targets) over scattered free exports; consolidate related code, don't fragment. The unit of code should be the unit of spec. Use when authoring TS in `editor/grida-canvas*`, `editor/lib/`, or `packages/*`. Sibling to the `naming` skill; React-specific shape lives in `code-react`.

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.

The spec is the shape

The unit of test should be the unit of code. A namespace css paired with css.test.ts, where each describe block targets one css.<fn>, is the shape this repo expects.

Why:

• The test file becomes a readable spec of the module's public contract. A reader can enumerate the module's surface without opening the source.
• It keeps the public surface honest. Anything not in the test is suspect — either dead, or doing work behind the contract that should be exposed.

editor/grida-canvas-utils/css.ts and its css.test.ts are the canonical example: namespace methods map directly to test suites. editor/lib/templating/template.ts and template.test.ts show the same shape for a single-function module.

Co-locate tests as *.test.ts siblings to the source, unless the module already uses a __tests__/ directory — then follow local convention.

The short version

• One class or one namespace per file. The exported unit is what a test targets.
• Not everywhere — engine and library code want this shape; UI glue and route handlers don't.
• Consolidate over fragment. Five one-function files want to be one namespace.
• The test file should read like the spec of the module. If it doesn't, the export surface is wrong, not the test.

See also naming for the boundary discipline this builds on, and code-react for React-specific shape.