Skip to main content

Nudo vs TypeScript

Code understanding, robustness, and language continuity — how those needs divide between Nudo and TypeScript is what this page answers.

Related: Migrate from TypeScript · Why Nudo · Error faces.

Nudo is built to replace TypeScript as the day-to-day type check gate — not to reimplement the TypeScript compiler. Dual gates are a migration tactic only; the exit is nudo migrate retire. Whether the tree is JS or TS today is not a selection criterion — Nudo analyzes TypeScript (annotations stripped, JS semantics) and ships a one-way migrate path. The sections below compare dimensions and state engine scope, not a permanent “keep tsc” checklist.

Positioning​

TypeScriptNudo
Primary surface.ts + type annotationsPlain .js (type syntax is stripped if .ts is passed)
Type modelDeclared structural typesAbs (shape × term × pred × conf) — computable types
Contractsinterface / type language*.nudo.js builders (fn, shape, number().gt(0)) + optional @nudo:contract
InferenceAnnotations + local inferenceExecuting code on symbolic Abs (evaluator)
Check / diagnosticstsc --noEmitnudo check (actual ⊭ expected on Abs; signatures even on success)
Ecosystem exit.d.ts is the model.d.ts is a lossy projection (absToTSType) — not the source of truth
Leaving the other tool—nudo migrate → retire tsc

The goal is not “TypeScript syntax on JavaScript.” The goal is: JavaScript remains JavaScript; obligations come from explicit contracts (L1) and the JS runtime export boundary (L2 entry throws); the engine reasons by evaluation, not by a second type language.

Relation to TypeScript design goals​

Microsoft’s TypeScript Design Goals list two non-goals that sit on Nudo’s main axes:

Apply a sound or "provably correct" type system. Instead, strike a balance between correctness and productivity.

Add or rely on run-time type information in programs, or emit different code based on the results of the type system. Instead, encourage programming patterns that do not require run-time metadata.

The throws axis (L2 entry may-throw) and the Pred axis (constraint implication on Abs) are therefore outside TypeScript’s roadmap by design. Nudo takes that complementary scope. Full map against Flow, Hegel, schema libraries, and refinement types: Competitive landscape.

GoalTypeScriptNudo
Code understandingSource annotations / IDE hover shows declared typescheck signatures and per-variable derivations; call-site evidence
Check / diagnosticstsc --noEmitnudo check (signatures even on success)
Entry safetyany.prop does not errorDangerous operations on entry any enter the throws domain; L2 can error
Violation shape“Not assignable to type …”actual / expected / fix:

Where the replacement happens​

The comparison is developer experience and fact quality, not file extensions:

DimensionTypeScriptNudo
Annotation burdenWrite logic and a type language in parallelLogic stays JS; contracts optional and draftable via contract --draft
Observation grainDeclared type namesPer-variable runtime-adjacent values / shapes / constraints
Constraint expressionStructural types (number)Computable Pred (ms > 0, returns > 0)
Semantic sourceAnnotations + local inferenceExecution on Abs; call sites are evidence
Error shape“Not assignable to type …”actual / expected / fix:
Source of truthSource annotationsAbs; .d.ts and similar are lossy projections
Edit-path costWhole-program structural residency (tsserver)Per-file / dirty-set Abs evaluation; bounded memory
Agent loop costProse diagnostics; full-project roundsStructured actions[]; cheaper gate payloads (see below)
Migration cost—migrate status → strip → verify → retire

Contracts can be declared first (sidecar / @nudo:contract) or drafted from code and then tightened by hand; the declaration surface is sharper than interface (numeric and shape constraints). “Types first vs logic first” is not the divide between TypeScript and Nudo.

Performance, tokens, and memory​

Full comparative suites are still incomplete. Direction is established by architecture and by the measurements already in-repo; treat numbers as baselines to be widened, not as a closed benchmark.

Why the cost structure favors Nudo​

FactorTypeScriptNudo
What is residentWhole-Program structural typing — any cross-file shape can change any decisionPer-file Abs results + small bookkeeping; close a file, drop its analysis
Edit pathLanguage-service / program refreshDirty-set re-analysis; single-file analyzeFile / checkSource
What agents must readType-name prose (“Not assignable to type …”)actual / expected / actions[] — fewer repair rounds
What authors must writeAnnotations + type-level workOptional contracts; no second language in source

Measurements already available​

ProbeNudoTypeScriptNotes
Single-file live editanalyzeFile 0.19 ms, checkSource 0.39 ms mediantsc.LS on the order of 10 ms+ per probe in benchmark/micro/bench-vs-tsc (≈ 150× in the micro harness)Synthetic monorepo / micro workload; see Performance · S1 baseline report
Agent repair (node-semver historical bugs, ~2.4k LOC)tokenTotal 569k · rounds 45 · repair loops 16 · gate peak RSS 226 MB993k (+75%) · 63 · 21 · 289 MBBoth finished 6/6; the gap is cost, not detect ceiling — OSS-SEMVER report
Constraint-shaped gate payloaddetects; pays tokens to reportoften silent green (no tokens, bug ships)pnpm run agent-dx — TS “cheap” tokens are silence

Boundaries of the claim​

  • Micro and S1 corpora are synthetic; OSS-SEMVER is one real package family. Absolute SLOs need broader suites.
  • Peak RSS is gate process RSS during agent loops, not steady-state IDE residency.
  • Memory advantage is structural (no whole-program forced residency) and shows up in LSP design (bounded session model); long-running multi-GB tsserver heaps vs Nudo LSP under the same editor load are not yet a published matrix.

The Nudo-side performance story — budgets, truncation diagnostics, and the analysis cache — is covered in Performance.

Capability bounds (engine non-goals)​

These are Nudo engine non-goals — not the same question as “should this package keep tsc as its gate forever”:

  1. Full TS type-language programming: conditional types, template-literal type programming, mapped types as programming devices — packages whose surface is that work keep handwritten declarations: Keeping handwritten .d.ts.
  2. Bit-for-bit tsc assignability: Nudo’s gate is Pred implication on Abs and some leqAbs shapes.
  3. Declaration merging / project references as product IR: the TypeScript project model is not reimplemented.
  4. Soundness proofs: no soundness claim, and no head-to-head contest on “a stricter type system.”

If the product is the type language itself (type-level libraries, DefinitelyTyped-style declaration surfaces), TypeScript is the tool for that work. For ordinary application and tooling packages, the check gate still ends at nudo check + migrate retire — not permanent dual gates.

What “replace TypeScript” means here​

For a package, the full replacement checklist is:

CapabilityNudo path
Open a normal .js file, get hover / inlayLSP + package.json#nudo.analysis.mode (default exports; all / directives available)
Observationnudo check signatures (no infer verb)
Check gatenudo check — exit 1 on error-level diagnostics (L1 + non-ignored L2); attachable to any local or automated workflow
Explicit contracts*.nudo.js + @nudo:contract; handwritten = L1 obligation
Generated factsnudo contract --emit → @generated segments (drift records, not silent rewrites of obligations)
npm / editor typesnudo export --format dts — one-way projection only
Retire tscnudo migrate status → strip → verify → retire
Performance baselineRepo benchmark + benchmark:gate — same case-set size; fail on exact regressions beyond 1-case jitter, rising unknown/error counts, per-case order worse than baseline, or average > 3.0× baseline

What is not claimed: one-click migration of a TS monorepo of any size; full structural typing as the primary model; a second IR; bit-for-bit tsc semantics.

Side-by-side example​

TypeScript (declared):

export function needsPositive(x: number): number {
return x > 0 ? x : 0;
}
needsPositive(-1); // allowed by tsc

Nudo (contract + diagnostics):

/// @nudo:import { positive } from "./shapes.nudo.js"

/**
* @nudo:contract x positive
*/
export function needsPositive(x) {
return x > 0 ? x : 0;
}

needsPositive(-1);
// nudo check → nudo:constraint-violated
// actual: -1 #exact
// expected: x > 0

TypeScript encodes intent in the signature. Nudo encodes the same obligation as a computable constraint and reports the violating call site. Both are valid; only the latter avoids a type language. More shapes: Error faces; ten runnable scenarios with pinned outputs: Error catalog.

Migration, not permanent dual gates​

In a monorepo, migrate package by package, then retire:

npx nudojs migrate status packages/tool
npx nudojs migrate strip packages/tool/src --write
npx nudojs migrate verify packages/tool/src
npx nudojs migrate retire packages/tool

Short-lived dual jobs during migration are a tactic, not an end state — see Coexistence. The product end state is one gate: nudo check.