modelling-types-for-nodejs
/modelling-types-for-nodejs
How to express a type in a Node.js/TypeScript backend so the compiler catches the bug instead of the runtime: discriminated unions that make illegal states unrepresentable, branded ids, const-object unions over enums, satisfies, unknown over any, and validating every boundary into a schema-derived type. Use when deciding how to model a DTO, entity, command or event payload, choosing union versus enum or interface versus type, or reviewing backend code for any, unsafe casts, or types that lie.
- Author
- thesoftwarehouse ↗
- Repository
- agentic-collections ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
How to express a type in a Node.js/TypeScript backend so the compiler catches the bug instead of the runtime: discriminated unions that make illegal states unrepresentable, branded ids, const-object unions over enums, satisfies, unknown over any, and validating every boundary into a schema-derived type. Use when deciding how to model a DTO, entity, command or event payload, choosing union versus enum or interface versus type, or reviewing backend code for any, unsafe casts, or types that lie.
Original author description
How to express a type in a Node.js/TypeScript backend so the compiler catches the bug instead of the runtime: discriminated unions that make illegal states unrepresentable, branded ids, const-object unions over enums, satisfies, unknown over any, and validating every boundary into a schema-derived type. Use when deciding how to model a DTO, entity, command or event payload, choosing union versus enum or interface versus type, or reviewing backend code for any, unsafe casts, or types that lie.
How it works
- When to Use
- Applicability and Precedence
- Non-negotiable Rules
- Reference Loading
- Procedure
SKILL.md preview
--- name: modelling-types-for-nodejs description: "How to express a type in a Node.js/TypeScript backend so the compiler catches the bug instead of the runtime: discriminated unions that make illegal states unrepresentable, branded ids, const-object unions over enums, satisfies, unknown over any, and validating every boundary into a schema-derived type. Use when deciding how to model a DTO, entity, command or event payload, choosing union versus enum or interface versus type, or reviewing backend code for any, unsafe casts, or types that lie." when_to_use: "Trigger on: deciding how to shape a type (union vs enum, interface vs type, optional fields vs a discriminated union), a review comment about `any`, `as`, non-null `!`, or an unchecked cast, branding ids that must not be swapped, typing an HTTP body/env/message boundary, choosing `satisfies` vs an annotation, or a generic that only appears in a return position. For *compiler configuration* — tsconfig, versions, decorators — use configuring-typescript-for-nodejs instead." --- # Modelling Types for Node.js How to model types in a Node/TypeScript backend so wrong states fail to compile rather than reaching production. The organising principle: **a type is a claim, and the compiler can only protect you from claims that are true.** Every `any`, every unchecked assertion, and every over-wide signature trades a compile-time guarantee for a runtime hope. This is the type-*modelling* layer. The `tsconfig.json`, version policy, and decorator settings it assumes belong to [`configuring-typescript-for-nodejs`](../configuring-typescript-for-nodejs/SKILL.md), and the NestJS/TypeORM feature patterns to [`implementing-nestjs-api`](../implementing-nestjs-api/SKILL.md). All three ship in this plugin, so those links always resolve. ## When to Use - Deciding how to express a type: union vs enum, `interface` vs `type`, optional fields vs a discriminated union, a branded id vs a bare `string`. - Modelling a DTO, entity, command or event payload so illegal combinations cannot be constructed. - Typing a boundary — an HTTP body, query string, env var, or message payload — where data arrives untyped. - Reviewing backend code for `any`, unsafe assertions, non-null `!`, or types that claim more than the code proves. ## Applicability and Precedence Read the repository's own code and `tsconfig.json` before applying anything here. **Local conventions outrank these defaults** — a codebase that uses `enum` consistently stays consistent; apply this guidance where the repo is silent, and record a deliberate deviation rather than silently mixing both. Framework requirements also outrank this skill. NestJS, TypeORM, and the validation library in use constrain how DTOs and entities are shaped; where a framework skill and this one disagree, the framework skill wins for the files it owns. ## Non-negotiable Rules | Severity | Rule | | --- | --- | | NEVER | Use `any` to silence an error. Use `unknown` at the boundary and narrow with a type guard or a schema parse; a surviving `any` carries a comment naming the reason and the condition for removal. | | NEVER | Use a type assertion to overrule the compiler — `as unknown as T`, or a non-null `!` on a value the code cannot prove is present — without a comment justifying the claim. `as const` is the exception; it narrows rather than widens. | | MUST | Validate every value entering the process (HTTP body, query string, env, messages, third-party responses) and derive its static type from the schema (`z.infer`), never cast a response body to a hand-written interface. | | PREFER | A discriminated union with a literal discriminant over an interface with mutually exclusive optional fields, and add an exhaustiveness check so a new variant fails to compile until every consumer handles it. | | PREFER | Branded types for ids and validated values that cross module boundaries, constructed through one validating function so the brand means "checked". | | PREFER | A `const` object plus a derived union over `enum`; NEVER a numeric `enum` for a persisted or serialized value, whose stored integers become an unversioned contract. | | PREFER | `satisfies` over an annotation when you want validation *and* the narrow inferred type (config objects, lookup tables). | | NEVER | Add a type parameter that appears only in the return position *to hand back an unproven value* — `parse<T>(raw): T` is an unchecked assertion in generic syntax; have the caller narrow an `unknown` instead. A factory that returns a container of a caller-chosen type (`createSet<T>(): Set<T>`) is the opposite and is fine — it asserts nothing. | | MUST | Comment every suppression and prefer `@ts-expect-error` over `@ts-ignore`; never a file-level `@ts-nocheck` in application code. A growing suppression count means a type is modelled wrongly. | ## Reference Loading | Reference | Load when | Covers | | --- | --- | --- | | [Type modelling patterns](./references/type-modelling-patterns.md) | Applying any rule above to real code, or you need the worked example and the full rationale | Each pattern with backend code: `unknown` over `any`, assertions, making illegal states unrepresentable, branded types, unions over enums, `interface` vs `type`, generic discipline, `satisfies`, boundaries, suppression | ## Procedure 1. **Read the ground truth.** Look at the surrounding code and the repo's existing conventions — which of `enum`/union, `interface`/`type`, and validation library it already uses — before proposing a shape. 2. **Model the state, not the validation.** Prefer a type that makes the illegal combination impossible to construct over one that permits it and checks later. 3. **Check the boundaries.** Anything crossing into the process is `unknown` until a schema parses it; anything crossing a module boundary as a bare primitive id is a swap waiting to happen. 4. **Load the reference** for the worked example and the exact rule when applying any of the above to real code.
Files in this package (2)
- SKILL.md 6 KB
- references/type-modelling-patterns.md 12 KB
Versions
The database has no other skills named modelling-types-for-nodejs.
Database snapshot: 13.11.2026 · package version a55833fb1150 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100typescript
Apply these opinionated TypeScript conventions whenever writing or reviewing TypeScript: branded types for domain modeling, discriminated unions for state, `satisfies` over `as`, const objects instead of enums, type-only imports, and the strict tsconfig baseline beyond `strict:… - 95ts-conventions
ACTIVATE when writing TypeScript types, generics, branded types, discriminated unions, or configuring tsconfig. ACTIVATE for 'type vs interface', 'enum alternative', 'branded type', 'satisfies', 'strict mode'. Covers: strict mode policy, no-any/no-enum rules, type over… - 100lang-ts-base
TypeScript rules that make the compiler reject bad states. Unions over optional-field bags, branded ids, exhaustive switches, no `as` casts, and types derived from the schema that owns the shape. Use when reading, writing, editing or reviewing any .ts or .tsx file. - 95typescript-types
Use TypeScript's stronger types where they prevent real bugs (unknown with narrowing, discriminated unions, exhaustive checks, satisfies, branded ids, constrained generics) and stop before they become a puzzle. Use it when typing API data or states, when tempted by any, or on a confusing type error. - 91typescript-best-practices
TypeScript idioms and type-safety patterns: discriminated unions, branded types, narrowing, boundary validation. Use when reading, writing, or reviewing any .ts or .tsx file. - 100typescript-narrowing-expert
Use when designing discriminated unions, debugging control-flow analysis, choosing satisfies vs as, building branded types, writing user-defined type guards, or composing conditional types and template literal types. Triggers: "Type X is not assignable to type Y" after a type…