sound-ts

What this is / isn’t

Soundness (project goal)

TypeScript’s contract is type safety with erased types — no runtime companions from the type layer. Sound-TS aims for F#-style soundness: opaque / branded (phantom) types plus runtime companions so values enter through checked paths.

Where we claim soundness today (0.x)

• brand type string-literal brands — member literals stay assignable; a phantom arm keeps two brands with the same members distinct. Outbound to string works; outbound to the bare literal union does not
• brand type refined brands — phantom unique symbol emit; bare base not assignable under stock tsc
• validate type — same phantom + .is / .from
• cast<Target>(expr) — checked entry path (primitive checks or companion .from)
• On .sts: reject as / any / ! / wide types, no bare structural aliases, methods emit as readonly function properties (#36–#38, #40–#42)

1.0 slice (delivered on .sts) — AST + symbols close more holes before emit. Ordinary .ts stays stock TypeScript. Matrix: SOUNDNESS_1_0.md.

• FFI: author x is Brand / asserts x is Brand rejected — entry via cast<> / .from
• Honest Mode B is shapes (empty / ignored param / always-true rejected)
• Mutation of companions / dialect-annotated bindings rejected
• Conservative generics: Partial / Required on brands rejected; Readonly allowed
• Still deferred (see design note): proving is correctness, unannotated mutation, full variance, ambient FFI
• Outbound widen from a validate type to the naked field structure remains a stock tsc hole until a later design closes it

Gate: new dialect surface should close a soundness hole, not paper over one. See also Non-goals.

Authoring — string literal brands

Prefer .sts files. Stock TypeScript language service will red-squiggle brand type inside ordinary .ts / .tsx. The VS Code TextMate grammar covers .sts; injection into .ts only helps highlighting, not the checker.

String literal brands emit as the member literals or a phantom arm, plus a runtime companion (.values / .is / .from / .toPrimitive). setRole("admin") stays OK. A second brand with the same members is not assignable. A value of the brand assigns to string, not back to the bare literal union.

Unknown input enters with .from. .from always runs the check and throws on failure. A known member is the literal itself (setRole("admin"), type: 0). The companion does not format and has no method that skips is. toFixed and slugify stay in a normal function that calls .from. A label stays a normal function over .toPrimitive.

// file: roles.sts
brand type Account = "admin" | "regular";

const admin: Account = "admin";

function greet(role: Account): string {
  return role === "admin" ? "hello, admin" : "hello";
}

greet(Account.from("admin"));
Account.from("guest"); // throws

brand type CurrencyNumber = string {
  is(value: string): value is CurrencyNumber {
    return /^\d+\.\d{2}$/.test(value);
  }
}

function currencyFromAmount(amount: number): CurrencyNumber {
  return CurrencyNumber.from(amount.toFixed(2));
}

For plain TS / JS after expand, use the playground.

Brand enum

A closed number set with a name for each value. Same checks as a number literal brand. The name is a property on the companion. from, is, values, name, and toPrimitive cannot be member names.

brand enum AccountCode {
  Zero = 0,
  One = 1,
  Two = 2,
  Three = 3,
}

const code: AccountCode = AccountCode.Zero;
AccountCode.from(1);
AccountCode.from(4); // throws

0 is the same member as AccountCode.Zero. Runnable copy: examples/tsc-app/src/account-code.sts.

Refined brands

Custom is body; CLI generates from that validates via is. Emit is plain .ts — a phantom unique-symbol brand plus companion — so stock tsc blocks bare number (or other base) from assigning. Enter via .from / cast<PositiveInt>(…); runtime checks still matter at boundaries.

// file: positive.sts
brand type PositiveInt = number {
  is(n: number): n is PositiveInt {
    return Number.isInteger(n) && n > 0;
  }
}

See the playground for the expanded TypeScript / JavaScript.

Brand-only unions / intersections

Members must be known brand names from the transform input — same file or another .sts on the CLI batch. Open types like string in a brand | / & are rejected; unknown brands and cycles error at transform time.

Two-file example (declare in a.sts, compose in b.sts):

// a.sts
brand type Admin = "admin";
brand type Regular = "regular";

export { Admin, Regular };

// b.sts
import { Admin, Regular } from "./a.js";

brand type Staff = Admin | Regular;

Run sts on the directory (or both files) so the project brand map sees every declaration, then point stock tsc at the expanded output.

Call-site usage of the runtime companions:

Staff.is("admin");     // true (Admin member)
Staff.from(raw);       // throws if neither brand matches

Expanded TS / JS lives in the playground.

Same-file intersections still work:

brand type User = "u";
brand type Session = "s";
brand type Authed = User & Session;
// Authed.is(value) → User.is(value) && Session.is(value)

validate type

Object types with primitive fields expand to a phantom unique-symbol brand plus the same .is / .from companion shape as refined brands. Stock tsc blocks bare object literals — enter via .from / cast<User>(…).

// file: user.sts
validate type User = { id: string; age: number };

User.is(data);   // boolean
User.from(data); // throws on mismatch; returns User

See the playground for the expanded TypeScript / JavaScript.

Supported field shapes:

• string | number | boolean | null
• optional ?
• arrays of primitives (string[]) — not null[]
• unions of those (e.g. string | null, string | number, string[] | number)
• nested objects whose leaves are those shapes
• Date
• a brand type or validate type name from the same file, an import, or the batch — enter a raw value with that companion's .from; an existing brand value may be stored as-is

Generics (Partial, Required, Array<…>), function types, and other shapes error at expand and name the gap. .from checks the value and does not format it. null[] stays rejected. Not a full schema library.

validate type Flags = {
  active?: boolean;
  tags: string[];
  id: string | number;
  note: string | null;
};

Checked casts — cast<Target>(expr)

Throw-on-mismatch cast. Targets are primitives or known companions (brand type / validate type) from the CLI batch.

const n = cast<number>(raw);
// → inline typeof check; throws if not a number

const u = cast<User>(raw);
// → User.from(raw) when User is in the project companion map

Unknown targets error at transform time. Pass the whole .sts batch so cross-file cast<User>(…) resolves.

CLI quickstart

Install from npm (scoped packages under @mishelashala):

npm i -g @mishelashala/sound-ts-cli
# or
pnpm add -g @mishelashala/sound-ts-cli

sts ./example.sts -o ./out/example.ts
# same binary: sound-ts

Library: @mishelashala/sound-ts-core. Bins: sts / sound-ts. Point bundlers at the transformed output.

From source (contributors):

git clone https://github.com/mishelashala/sound-ts.git
cd sound-ts
pnpm install && pnpm build && pnpm test
node packages/cli/dist/cli.js ./example.sts -o ./out/example.ts

Adoption / roadmap

Keep most of the app as normal .ts (stock tsc / Vite). Add .sts only where you want brand type, validate type, or cast. VS Code already highlights .sts, so “just add a file” isn’t red-squiggle hell.

Today — two-step compilation (expand, then stock build):

.sts  --sts -o …-->  plain .ts  --tsc/nest-->  .js in normal build out

• sts never emits .js
• Default output → <cwd>/.sound-ts/ (gitignored; input outside the cwd caches next to that input) or -o you choose
• Stock Nest / tsc still owns dist/
• Don’t point tsc at raw .sts
• Whole .sts batch on each sts run for cross-file | / & and cast companions
• Enter refined / validate type values via .from or cast<> — bare bases are not assignable under stock tsc

0.x (delivered) — tooling + surface soundness on .sts. Checkboxes stay checked as history. Ordinary .ts stays stock TypeScript.

Seamless integration — roadmap v1:

• Shadow emit — sts writes a gitignored cache, never a sibling .ts. CI fails if that output is committed.
• Bidirectional resolve — .ts and .sts import each other. Import paths stay as the author wrote them.
• Drop-in build script — one package.json script expands, then runs tsc. Expand failure stops the build.
• Loader — Vite expands .sts on dev and build, so you stop calling sts by hand.

Soundness on .sts — roadmap v2:

• Reject as — a type assertion in .sts fails expand. as const and cast<> stay. as is not rewritten into cast.
• Reject any — any in .sts fails expand. unknown stays. any is not rewritten to unknown.
• No structural aliases — a bare object alias in .sts fails expand. validate type stays nominal. Outbound widen to the naked structure stays a stock tsc hole.
• Method parameters — a method in .sts emits as a readonly function property, so stock strictFunctionTypes checks parameters contravariantly.
• Reject ! — value! and prop!: Type in .sts fail expand. !== stays. ! is not deleted.
• Reject Object, {}, Function — those types in .sts fail expand. An empty object literal stays. They are not rewritten to unknown.

1.0.0 — complete soundness — roadmap 1.0. AST frontend, dialect nodes, AST bans, symbols, and the initial 1.0 rule slice are delivered. Stock tsc stays the backend on expand output. Deferred holes live in SOUNDNESS_1_0.md.

• AST frontend with parity — TypeScript parser/AST replaces the regex frontend; fixtures expand equivalently.
• Dialect AST nodes — brand type / validate type / cast<> are explicit nodes (or a stable side-table).
• AST soundness visitors — move 0.x bans off masked-string scans onto AST visitors.
• Scopes and symbols — cross-file Sound-TS symbols for brands / companions / cast targets.
• Complete soundness rules — 1.0 reject/accept matrix (boundaries, predicates, mutation, generics subset) on the AST + symbol layer.
• .from is the only door — unknown input enters with .from (always checks). Known members are the literals ("admin", 0). No unchecked constructor. Formatting and labels stay normal functions.

Caveats

• Parser edges: regex literals; nested ${} in templates (whole template skipped).
• Editor: author in .sts to avoid stock tsc red squiggles on the dialect keywords.
• Cross-file companions: pass every .sts on the CLI batch (e.g. a directory) so | / & members and cast targets resolve against the project companion map. After expand, stock tsc sees normal imports of the emitted type + companion.

VS Code (thin, local-only)

packages/vscode registers .sts, highlights brand type (including in .ts), and can shell out to the CLI. No full custom checker.

Local (Cursor / VS Code):

1. Clone mishelashala/sound-ts
2. Extensions → … → Install from Location… → pick packages/vscode

Optional one-liner for VSIX:

cd packages/vscode && npx @vscode/vsce package --no-dependencies

then Install from VSIX…

Transform command needs pnpm build so CLI dist exists. Marketplace not listed yet (extension is local-only; CLI/core are on npm).

defineLiteralSet?

Internal emit / runtime helper — not the public API. Authors write brand type; the CLI expands. Do not treat import { defineLiteralSet } as the product.

Non-goals (this cut)

See also Soundness (where we claim soundness vs what stays open toward 1.0).

• No Microsoft / TypeScript fork to maintain
• No custom TypeScript language server in 0.x — stock tsc runs on expand output; 1.0 adds a Sound-TS semantic phase before emit, still not a Microsoft fork
• No open brands without is (use refined brands with a custom .is)
• Refined brands and validate type are nominally opaque under stock tsc (phantom unique-symbol brands) — not structural aliases of their bases. Enter via .from / cast<>.
• String literal brands are the member literals or a phantom arm (nominal under stock tsc; member literals still assign). They do not flow back to the bare literal union. Number/bigint literal brands not supported yet.
• 0.x delivered surface bans and tooling (roadmap v1 / v2). Outbound widen from a validate type to the naked structure remains a stock tsc hole until a later design closes it.
• 1.0 roadmap issues #50–#54 delivered (AST + symbols + initial rule slice). Deferred items: SOUNDNESS_1_0.md. Package version may still be 0.x until a 1.0.0 release cut.
• Not a full schema library — validate type accepts nested objects, Date, and brand / validate field names. Generics (Partial, Required), function fields, and formatting inside .from stay out.
• VS Code extension not on Marketplace yet (local install only)
• defineLiteralSet is not the authoring surface

FAQ: Why not TypeScript?

TypeScript’s design non-goal: don’t add RTTI or emit different JS from the type system — no runtime overhead from the type layer. Stock tsc therefore won’t grow companions from the type layer.

Gaps that non-goal leaves where this dialect claims a surface (not a wishlist of everything TS declined):

1. Runtime validation from types (auto .is / assert)
   This dialect covers it via validate type — see Validate type.

   validate type User = { id: string; age: number };
   User.is(data);   // ✅ companion
   User.from(data); // throws on mismatch

2. Nominal / opaque / brand types with runtime companions
   That’s what brand type + companions cover here — string-literal brands keep member-literal assignability and a phantom arm; refined / validate are phantom-opaque. Enter untrusted values via .from / cast<>. See Refined brands / String literal brands.
3. Contracts / checked casts
   This dialect covers it via cast<> — see Checked casts.

   const n = cast<number>(raw); // ✅ throws on mismatch
   const u = cast<User>(raw);   // ✅ User.from when companion is in the batch

Honest limits of the dialect live under Non-goals (no fork, no custom checker, brand does not flow back to the bare literal union, …) — not as a catalog of TypeScript declines we also don’t ship. TS already emits for some expression features (enum, namespace, parameter properties, downleveled class/async, decorators) — those aren’t “types that generate companions.”

Bottom line: for erase-the-type and emit a runtime artifact, stock TS usually says no — sts fills only the dialect surface above (brand type, validate type, cast<>, phantom emit).

Pages palette

UX lock for this site. Brand blue is large/UI only on dark (≈3.9:1) — body copy uses text tokens. Signal is focus / logo highlight only. Error is fail-closed examples only.