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 committedbefore//after/trees andpnpm 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)
| before | after | |
|---|---|---|
| What | TypeScript checkout helpers | Plain JS |
| Gate | tsc --noEmit | nudo check src |
| Story | Synthetic but complete | Committed 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.
| before | after | |
|---|---|---|
| Language | age.ts + ms.d.ts | age.js |
| Gate | tsc --noEmit | nudo check |
typescript dep | yes | no |
| Real dep | ms@^2.1.3 | same |
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.
| before | after | |
|---|---|---|
| Language | logger.ts + debug.d.ts | logger.js |
| Gate | tsc --noEmit | nudo check src |
| Real dep | debug@^4.3.4 | same |
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)
| Friction | Where it showed up | What fixed it | Cost (example-scale) |
|---|---|---|---|
tsc scripts + typescript dep still present | migrate status blockers list | migrate retire rewrites scripts; drops dep | One command (--dry-run first) |
| Old annotations become obligations only if you accept them | contract --from-dts emits @nudo:draft | Review → copy into *.nudo.js | Minutes per file; never silent |
Native / unharvested deps (ms(), debug()) | unknown / conf=opaque / nudo:unknown-inference | @types/* harvest, @nudo:mock, or a declared return contract | Bounded; stays a warning until you pin |
L2 entry-may-throw on intentional throw | checkout-demo applyCoupon | @nudo:throws RangeError / guard, or nudo.check.entryThrows: "warning" | One line in package.json or a throws directive |
| Dual-run temptation | mid-migration CI | Keep verify --with-tsc only during the move; retire is the exit | Policy, 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
| Claim | Evidence |
|---|---|
| JS stays JS | after/ sources are plain .js |
| Contracts are optional obligations | contract --from-dts → review → *.nudo.js |
| Exit is retire, not dual-run | .nudo/migrate-retired.json + no typescript dep |
| Real packages move | ms and debug are not synthetic fixtures |
| Honest engine debt | unknown / 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
- Migrate from TypeScript — the door itself
- Error faces — what you read after the gate
- Mental model