SuperAPI AI Directory

principle-type-system-discipline

Coding & development

View repository

Updated 10-16 08:14

About this skill

Type system discipline

Use the type checker as a proof tool that rules out impossible states, mixed-up primitives, and unhandled variants before the code runs. A case the types let a caller skip becomes a failure at runtime.

When: designing a type or a signature.

  • Define errors and special cases out of existence rather than adding a handler for each one. Shapes that cannot hold a bad state, functions total over their input, and a redesigned interface are the tools.
  • Make illegal states impossible to build. Model alternatives as a sum type, one tagged variant per case, never as a record of optional fields whose contradictory combinations still compile. A done flag next to an optional completion time admits "done, with no time"; derive the flag from the time alone, or give "open" and "done at a time" a variant each. A bug that raises the question "can this combination really happen?" means the type is too loose.
  • Construct a type from its legal values rather than restricting a wider type with runtime checks. A non-empty list is a first element plus the rest, not a list whose length someone checks; a well-formed interval is its opening moment plus how long it lasts, not two moments someone keeps in order by hand. No representation is the privileged one: pick the shape that cannot express the illegal value, then offer callers the interface they need on top of it.
  • Give primitives with different meanings different types. A user id and an order id are both strings underneath and never interchangeable: wrap each in its own named type, check it once where it is created, and trust it from there on.
  • Data from outside is untyped until parsed: network payloads, serialized text, messages between processes, command-line arguments, config files, environment variables, database rows. Every such edge has a parse function that turns raw input into the typed model; the principle-boundary-discipline skill places it.
  • Never tell the compiler something it cannot check. A cast, an unchecked coercion, or an assertion that silences the checker is a runtime crash waiting; prove the fact instead by validating, narrowing, or refining the model. This is the implement rule of no escape hatches, applied.
  • Make exhaustiveness the compiler's job: a match over a sum type fails to compile when a new variant arrives unhandled. Use whatever check the language offers for that.
  • When an authoritative schema already defines a shape (an interface definition file, an API schema, a database migration, a design-token file), derive the type from it rather than writing a parallel one by hand. The principle-encode-lessons-in-structure skill carries the same idea past types.
  • Strengthen a type only where partiality shows up. A runtime assertion, an absence check, or a "cannot happen" throw marks the spot where a type is too weak: move that check into the type, then stop. A type exists to record which cases every caller has to cover; describing the data with maximum precision is not its job. Favor total functions: summing no numbers gives zero, so the sum accepts any list; taking the first element of nothing has no answer, so that operation accepts only a non-empty list.
  • Checks to run on a type:
    • A comment explaining when a combination of fields is valid means the type admits too much; break it into variants.
    • Two arguments of one primitive type with different meanings get their own types.
    • Every cast, unchecked value, or forced non-absence traces back to an edge, and the validation moves there.
    • Adding a variant next month makes the compiler point at every place that needs a new case.
    • A type that copies a shape another file owns is derived from that file instead.
    • A type made stronger only for precision, where nothing would otherwise fail, goes back to the plain type.

Where it stops: this principle deepens "Type-safe with no escape hatches" in implement; where outside data gets checked belongs to the principle-boundary-discipline skill, and how domain rules become structures belongs to the principle-model-the-domain skill. In code no static checker reads, the same shapes still guide the design, and the parse at the edge carries the guarantees the compiler would.