Rebasely Beta: data may be purged

justintypescript-ultra-strict Public

Markdown · 9.3 KiB · at eb4a6ea

Writing TypeScript-Ultra-Strict (.tsus)

This project uses .tsus files: TypeScript with the escape hatches removed. Plain .ts files keep working and are not checked. Everything below applies to .tsus only. Read it once before writing code; tsus explain <CODE> covers any single rule in depth.

The loop

  1. Write or edit .tsus files under src/.
  2. Run tsus check --json. Each diagnostic has a stable code, a position, a hint, and usually a fix with exact text edits.
  3. Run tsus fix to apply every safe fix (--unsafe adds fixes that can change behavior; review those). Or apply a diagnostic's fix.edits yourself: each edit replaces [start, end) (UTF-16 offsets into the original file) with newText.
  4. For anything left, run tsus explain <CODE> and change the code. Do not work around a rule: there is no suppression comment, and as, any and ! are themselves errors.
  5. Repeat until tsus check passes, then tsus build emits plain ESM, source maps and .d.ts declarations into dist/. tsus check also type-checks the project in strict mode; a TypeScript error comes back as TSUS200 with the original code in tsCode.

To port a .ts file, run tsus migrate src/file.ts. It writes src/file.tsus next to it and lists what it could not convert.

What is not allowed

No null, no undefined, no class, no var, no throw, no any, no as casts (except as const), no ! non-null assertions, no enum, no == or !=, no default exports, no @ts-ignore/@ts-expect-error/@ts-nocheck. Do not reassign or mutate function parameters. Use const unless the binding really is reassigned. Every promise is awaited or returned. Every Result is matched, propagated or returned. Result error types are string literal unions or tagged unions.

Types

TypeScript
import { Some, None, Ok, Err, tag, type Option, type Result, type Tagged } from "@tsus/runtime";

type User = { readonly name: string; readonly email: Option<string> }; // data is plain objects

const ada: User = { name: "ada", email: Some("ada@example.com") };
const nobody: Option<string> = None;

// Errors are a closed set the caller can match on: all string literals,
// or all tagged variants. Never string, Error or a mix of the two kinds.
type ParseError = "empty" | "not a number";
type LoadError = Tagged<"EmptyId", string> | Tagged<"NotFound", string> | { tag: "Timeout"; ms: number };

const load = (id: string): Result<User, LoadError> =>
  id === "" ? Err(tag("EmptyId", id)) : Err(tag("NotFound", id));
  • Option<T>: Some(value) or None. Methods: map, andThen, unwrapOr(fallback), okOr(error), isSome(), isNone().
  • Result<T, E>: Ok(value) or Err(error). Methods: map, mapErr, andThen, unwrapOr(fallback), ok(), isOk(), isErr().
  • Tagged<"Name", V> and tag("Name", value) build tagged variants; any object type with a literal tag field works too.
  • Behavior lives in functions that take data and return new data: const rename = (u: User, name: string): User => ({ ...u, name });.
  • A void operation that can fail returns Result<true, E> and ends with return Ok(true);.
  • A string literal passed to a generic widens to string (okOr("empty") is Result<T, string>). Give the type argument (okOr<ParseError>("empty")) or return through a function whose return type names the error.

match

match is a macro and an expression. Each arm is Pattern => expression, separated by commas.

TypeScript
const greet = (u: User): string =>
  match (u.email) {
    Some(address) => `mail ${address}`,
    None => `no email for ${u.name}`,
  };

const explain = (e: LoadError): string =>
  match (e) {
    NotFound(id) => `no user ${id}`,    // Tagged variant: binds its value
    Timeout(t) => `timed out after ${t.ms}ms`, // plain tagged object: binds the object
    _ => "no id given",                  // wildcard
  };

const describe = (e: ParseError): string =>
  match (e) {
    "empty" => "nothing to parse",       // literal patterns
    "not a number" => "digits only",     // a finite union needs no _
  };
  • Variant patterns: Some(x), None, Ok(x), Err(e), and any tag Variant(x) of a union with a literal tag field (binds .value for Tagged, the whole object otherwise). Literal patterns: string, number or boolean literals. One match uses one kind, not both; either kind may end with _.
  • Matches are checked at compile time: a missing variant is TSUS201, an arm the subject cannot hold is TSUS202. A literal match over a plain string needs _.
  • Arms are expressions, not blocks. Put multi-step logic in a named function and call it from the arm. Build tagged values in arms with tag(...), not raw object literals (the tag field would widen to string).
  • Matches nest. An arm may await; then write await match (...) { ... }.

The ? operator

? after a Result or Option expression returns early with its Err or None, and otherwise yields the inner value. It only works inside a function whose declared return type is a Result or Option (or a Promise of one), never at top level or inside a match arm (TSUS300). Error types must line up: convert with mapErr, or turn an Option into a Result with okOr (TSUS302). In async code ? applies to the awaited value: const user = await load(id)?;. ? binds loosely, so wrap it in parentheses inside larger expressions ((a?) + (b?)), and keep it out of ?: branches, the right side of && || ??, and loop conditions (TSUS303).

TypeScript
const total = (rawA: string, rawB: string): Result<number, ParseError> => {
  const a = parse(rawA)?;
  const b = parse(rawB)?;
  return Ok(a + b);
};

const portOf = (env: Map<string, string>): Result<number, ParseError> => {
  const raw = fromNullable(env.get("PORT")).okOr<ParseError>("empty")?;
  return parse(raw);
};

The boundary

The outside world (npm, DOM, Node, .ts files) returns undefined, throws, and hands you classes. Convert it at the edge:

TypeScript
import { tag, type Tagged } from "@tsus/runtime";
import { fromNullable, wrapSync, wrapAsync, isRecord, asRecord, field } from "@tsus/runtime/boundary";
import { readFile } from "node:fs/promises";

const first = fromNullable([1, 2].find((n) => n > 1)); // T | null | undefined -> Option<T>
const parseJson = wrapSync(JSON.parse);                 // throws -> Result<T, Error>
const read = wrapAsync(readFile);                       // rejects -> Promise<Result<T, Error>>

type ReadError = Tagged<"ReadFailed", string>;
const text = (await read("a.txt", "utf8")).mapErr((e): ReadError => tag("ReadFailed", e.message));

For unknown data use isRecord(v) (a type guard: plain object, not null, not an array), asRecord(v) (Option<Record<string, unknown>>) and field(v, "key") (an own property as Option<unknown>) instead of casts. Map Error into your own tagged error type right away with mapErr. A file named *.boundary.tsus may use as casts (after a runtime check) and default exports (for hosts such as Cloudflare Workers that require export default). All other rules still apply there. Keep boundary files small; validate untrusted data with a schema library such as zod and return a Result.

Diagnostic codes

Code Rule Fix
TSUS000 Syntax error none
TSUS001 Classes are banned none
TSUS002 null is banned none
TSUS003 undefined is banned none
TSUS004 var is banned safe
TSUS005 throw is banned none
TSUS006 Malformed match expression none
TSUS100 Non-exhaustive match (runtime) none
TSUS200 Type error none
TSUS201 Non-exhaustive match none
TSUS202 Match arm does not fit the subject none
TSUS203 Match subject is not matchable none
TSUS300 ? outside a function returning Result or Option none
TSUS301 ? applied to something that is not a Result or Option none
TSUS302 ? propagates a value the function cannot return none
TSUS303 ? in a position that may not run none
TSUS401 any is banned safe
TSUS402 as casts are banned outside boundary files none
TSUS403 Non-null assertions are banned none
TSUS404 enum is banned unsafe
TSUS405 == and != are banned safe
TSUS406 Default exports are banned outside boundary files unsafe
TSUS407 Reassigning a parameter is banned none
TSUS408 let that is never reassigned safe
TSUS409 Mutating a parameter is banned unsafe
TSUS410 Result error types must be tagged none
TSUS411 Floating promises are banned unsafe
TSUS412 Unused Result none
TSUS413 Type-check suppressions are banned safe

tsus explain <CODE> prints the rule, why it exists, a rejected and an accepted example. tsus check --json diagnostics look like:

JSON
{ "code": "TSUS405", "message": "loose equality (== / !=) is banned in .tsus files", "hint": "Use === or !==.",
  "file": "src/main.tsus", "line": 3, "col": 48, "endLine": 3, "endCol": 50, "start": 97, "end": 99,
  "explain": "tsus explain TSUS405",
  "fix": { "description": "Replace == with ===", "safe": true,
           "edits": [{ "start": 97, "end": 99, "line": 3, "col": 48, "endLine": 3, "endCol": 50, "newText": "===" }] } }

fix is null when no automatic fix exists. Safe fixes keep runtime behavior (they can surface type errors that any was hiding); unsafe ones ("safe": false) can change it.