Skip to main content

Case study: retire tsc

You'll leave with: a forwardable migration playbook — before/after diagnostics, the command sequence status → strip → verify → retire, and honest friction notes — backed by runnable samples in this monorepo.

End state is always the same: nudo check is the only gate; typescript is gone. Coexistence is a migration tactic, not the destination. Command walkthrough: Migrate from TypeScript.

Honesty label. Every package below is an example-scale sample from docs/examples/ (two real npm consumers, one public demo package). Timings and friction counts are example-scale, not production-size — not a production migration audit. Do not invent external company names; the evidence is the committed before/ / after/ trees and pnpm run verify:examples.

The one-way door​

audit (migrate status) → strip → verify (nudo check) → retire (drop tsc)

Copy-ready sequence (paths swap for your package):

# 0. audit — what still carries tsc
npx nudojs migrate status ./my-pkg

# 1. strip — .ts → .js (annotations out, runtime stays). --write to emit.
npx nudojs migrate strip ./my-pkg/src --write

# 2. optional — reverse old annotations into a reviewable contract draft
npx nudojs contract --from-dts ./my-pkg/src/index.ts
# → @nudo:draft (NOT enforced until you copy it into *.nudo.js)

# 3. verify — nudo check must pass on the stripped JS
npx nudojs migrate verify ./my-pkg/src

# 4. retire — drop typescript, rewrite tsc scripts / GHA lines, write marker
npx nudojs migrate retire ./my-pkg --dry-run # then drop --dry-run

Step recap: status audits the surface (.ts count, tsc scripts, blockers) → strip emits plain JS (--write, optional sidecar draft) → verify gates the stripped JS with nudo check (--with-tsc dual-run during the move only) → retire drops typescript, rewrites tsc scripts and workflow lines, writes .nudo/migrate-retired.json. Full per-step table (what it does / exit when): Migrate from TypeScript.

migrate retire --all batches a monorepo. Dual-run exists only as migrate verify --with-tsc during the move — never as the endgame.

1. checkout-demo (public sample)​

beforeafter
WhatTypeScript checkout helpersPlain JS
Gatetsc --noEmitnudo check src
StorySynthetic but completeCommitted after/ is the gold end state

Source: docs/examples/migrate/

Before → after (code)​

// before/src/math.ts
export function lineTotal(price: number, qty: number): number {
return price * qty;
}
// after/src/math.js — runtime unchanged
export function lineTotal(price, qty) {
return price * qty;
}

Cross-file: type Item = { … } in cart.ts is deleted (TS-only; it never existed at runtime). Imports stay.

Before → after (diagnostics)​

Before is a tsc --noEmit type name. After is a Nudo signature (printed even on success) plus optional L1/L2 faces:

nudo check docs/examples/migrate/after/src/math.js
OK
0 error · 1 warning · 0 info · 3 fn

signatures
lineTotal(price: any, qty: any) => number
applyCoupon(total: any, percent: any) => number throws RangeError
formatMoney(cents: any) => string

issues
[WARNING L9 applyCoupon] applyCoupon (export): may throw RangeError (nudo:entry-may-throw)
→ throw RangeError → @nudo:throws RangeError / sidecar fn({ … }) contract / refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)

Read that as: signatures still print; unconstrained params are any (not unknown); the intentional throw surfaces as L2 with a next step. The after package flips it to warning via package.json#nudo.check.entryThrows if you want a softer first week.

Tighten later and the face becomes value + predicate (not a type name) — see Error faces:

actual: -1 #exact
expected: x > 0
→ use a value satisfying x > 0
fix: nudo contract --draft

2. Real package: ms (vercel/ms)​

A consumer of the real ms formatter (pure JS, very common) moves from TS + @types/ms to JS + nudo check. The dependency does not change.

beforeafter
Languageage.ts + ms.d.tsage.js
Gatetsc --noEmitnudo check
typescript depyesno
Real depms@^2.1.3same

Source: docs/examples/retire-real/

Command sequence (actual)​

# status — audit face (real output)
npx nudojs migrate status docs/examples/retire-real/before
# ts files: 2 tsx: 0 tsconfig: yes typescript dep: yes
# tsc scripts: typecheck
# blockers: tsc still in scripts; no nudo check/test script yet; typescript still in dependencies

# strip — dry-run in this repo; --write emits
npx nudojs migrate strip docs/examples/retire-real/before/src/age.ts

# reverse annotations into a draft you must review
npx nudojs contract --from-dts docs/examples/retire-real/before/src/age.ts
# export const formatAge = fn({ durationMs: number() }, string());
# export const parseAge = fn({ text: string() }, number());
# → copy into age.nudo.js only after review (that is when L1 goes live)

# verify / gate on the committed after/
npx nudojs check docs/examples/retire-real/after/src/age.js

# retire — dry-run first
npx nudojs migrate retire docs/examples/retire-real/after --dry-run

Before → after (code + gate)​

// before/src/age.ts
export function formatAge(durationMs: number): string {
return ms(durationMs, { long: true });
}
// after/src/age.js
export function formatAge(durationMs) {
return ms(durationMs, { long: true });
}

Accepted sidecar (after/src/age.nudo.js) — the draft above, reviewed:

import { fn, number, string } from "@nudojs/core";

export const formatAge = fn({ durationMs: number() }, string());
export const parseAge = fn({ text: string() }, number());

Post-retire check face (example-scale; native ms() internals are not fully harvested — parseAge folds to precise undefined, which is value evidence, not engine debt (Bug 22); the live obligations are the two L2 may-throw warnings):

signatures
formatAge(durationMs: number) => string throws Error
parseAge(text: string) => undefined throws Error

issues
[WARNING L10 formatAge] formatAge (export): may throw Error (nudo:entry-may-throw)
→ ToString coercion of abstract operand (Symbol) → @nudo:throws TypeError | sidecar: fn({ … }): shape({ <body-read fields> }) | refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)
[WARNING L19 parseAge] parseAge (export): may throw Error (nudo:entry-may-throw)
→ computed member on nullish (union arm) → @nudo:throws TypeError | sidecar: fn({ … }): shape({ <body-read fields> }) | refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)

Marker after a real retire: .nudo/migrate-retired.json (rewritten typecheck: tsc --noEmit → nudo check src, typescript removed).

3. Real package: debug (visionmedia/debug)​

Same door on debug — the log facade behind half of npm.

beforeafter
Languagelogger.ts + debug.d.tslogger.js
Gatetsc --noEmitnudo check src
Real depdebug@^4.3.4same

Source: docs/examples/retire-debug/

npx nudojs migrate status docs/examples/retire-debug/before
npx nudojs migrate strip docs/examples/retire-debug/before/src/logger.ts
npx nudojs contract --from-dts docs/examples/retire-debug/before/src/logger.ts
# → export const createLogger = fn({ namespace: string() }, any());
npx nudojs check docs/examples/retire-debug/after/src/logger.js
npx nudojs migrate retire docs/examples/retire-debug/after --dry-run

Honest edge: debug() is a native entry. With the real debug package resolvable, the engine evaluates the module for real and reports a precise return face (a function-shaped probe, () => ?, still open inside); if it cannot be resolved, the return honestly degrades to unknown + nudo:opaque-result. Neither is a contract failure — the gate stays 0 error:

signatures
createLogger(namespace: any) => (() => ?)
logHello(name: any) => undefined

(no issues)

In an environment where debug cannot be resolved, the same two lines read => unknown, plus an INFO ... conf=opaque (nudo:opaque-result) line; the gate is still 0 error.

With @types/debug present, harvest fills signatures; or pin with @nudo:mock / a declared return contract (@nudo:contract or a sidecar return slot). That is the same story as ms().

Friction and time (example-scale)​

FrictionWhere it showed upWhat fixed itCost (example-scale)
tsc scripts + typescript dep still presentmigrate status blockers listmigrate retire rewrites scripts; drops depOne command (--dry-run first)
Old annotations become obligations only if you accept themcontract --from-dts emits @nudo:draftReview → copy into *.nudo.jsMinutes per file; never silent
Native / unharvested deps (ms(), debug())unknown / conf=opaque / nudo:unknown-inference@types/* harvest, @nudo:mock, or a declared return contractBounded; stays a warning until you pin
L2 entry-may-throw on intentional throwcheckout-demo applyCoupon@nudo:throws RangeError / guard, or nudo.check.entryThrows: "warning"One line in package.json or a throws directive
Dual-run temptationmid-migration CIKeep verify --with-tsc only during the move; retire is the exitPolicy, not tooling

Wall-clock (example-scale, not production-size): these samples are small (2–3 modules, ~1–2 files stripped per package). The committed trees are the evidence — run pnpm run verify:examples yourself. We do not publish production-scale hour/days numbers; a “7-day retire path” in release notes is a product target narrative, not a measured median. For a real package, budget by .ts file count from migrate status, not by blog post.

What these prove​

ClaimEvidence
JS stays JSafter/ sources are plain .js
Contracts are optional obligationscontract --from-dts → review → *.nudo.js
Exit is retire, not dual-run.nudo/migrate-retired.json + no typescript dep
Real packages movems and debug are not synthetic fixtures
Honest engine debtunknown / opaque stays visible; never faked as success

Run the matrix​

pnpm run verify:examples

Every command above is CI-pinned in docs/examples/README.md.

Share this story​

Copy-ready blog / HN / release-notes text: docs/reports/retire-tsc-announcement.md.

Next​