Mental model
This page answers only: how Nudo sees and computes your JavaScript. The command surface lives in the CLI guide; migrating off tsc is linked at the end.
The one-sentence model
Nudo executes your JavaScript on abstract values so variables carry runtime-adjacent values, shapes, and constraints — and reports what the code actually computes — then validates the contracts you accept. Sources stay plain .js.
| You write | Nudo does |
|---|---|
Plain .js + call sites | Executes and observes: signatures, intermediates, call-site truth |
Optional *.nudo.js / @nudo:contract | Validates obligations (actual ⊭ expected) |
| Nothing extra | Still diagnoses export may-throw (L2) |
There is no second type language. Contracts are ordinary JS modules with builders like number().gt(0).
Two layers: observation and contracts
| Layer | What you read | Source |
|---|---|---|
| Observation | runtime-adjacent values / shapes / constraints | execution facts (call sites, paths) |
| Contracts | conditions that must hold; violations give actual / expected | declarations you accept (sidecar / @nudo:contract) |
Observation is not commentary; contracts are not type annotations.
export function scale(x) {
return x + 1;
}
scale(5);
scale(0); // violates the sidecar precondition below
import { number, fn } from "@nudojs/core";
export const scale = fn({ x: number().gt(0) }, number());
signatures
scale(x: number) => number
issues
[ERROR L6 scale] scale[x]: argument ⊭ precondition (nudo:constraint-violated)
actual: 0 #exact
expected: x > 0
The evidence from scale(5) keeps the entry from staying bare any; the contract turns x > 0 into a checkable obligation. if is not a contract — obligations come only from declarations you accept.
Why variables look runtime-adjacent
Because they are computable Abs (shape × term × pred × conf), not type names:
| Component | What you see on the product face | Meaning |
|---|---|---|
| shape | shape in the signature | prim / obj / arr / fn / sum / … |
| term | value identity | lit (42), var (symbolic A1), app (x+1) |
| pred | the expected: line | constraints (x > 0); participate in algebra (x>0 ⇒ x+1>1) |
| conf | #exact / #path | abstraction precision |
Call sites are evidence: more real calls → signatures closer to runtime. nudo test shows per-call witnesses; @nudo:case is debug-only and never creates contract obligations.
Deeper: Abs · Abstract interpretation · nudo check --abs.
Four model rules
- Call sites are evidence. More real calls → signatures closer to runtime.
any≠unknown.any= unconstrained entry (you may refine it).unknown= inference failed (engine debt).- Contracts are obligations, not annotations. Constraints participate in algebra — they are not intent written in comments.
- Projections are not the source of truth.
.d.ts/ schemas are lossy views of Abs; Abs from execution is the truth.
What you can ignore for now
- Abs algebra details — Abs when you want
--abs - Harvest / env internals — Dependency types
- Export dialects — only when a consumer needs
.d.tsor validators - Migrating off
tsc— Nudo vs TypeScript · Migrate from TypeScript
Next
- Quick Start — run it
- Concept layers — Observation / Contracts / Advanced
- CLI — command surface
- Error faces
- Playground