SimpleTypeScript 1.1.0

SimpleTypeScript 📘

An emitter for generated TypeScript. Build a module out of declarations, types and values; the library decides how each of them is spelled, once, so every generator writing through it produces the same shape.

var module = new TsModule()
    .Const("LOCALES", TsValue.AsConst(TsValue.Array(["en-US", "sv-SE"])))
    .Const(
        "MESSAGES",
        TsValue.Object(new Dictionary<string, string> { ["greeting"] = "Hej värld" }),
        TsType.Record(TsType.String, TsType.String),
        doc: "Every key, authored in the neutral culture.");

File.WriteAllText(path, module.Render());

// GENERATED — do not edit.

export const LOCALES = ["en-US","sv-SE"] as const;

/** Every key, authored in the neutral culture. */
export const MESSAGES: Record<string, string> = {
  "greeting": "Hej värld",
};

Shapes as well as values:

string[] statuses = ["Queued", "Running"];

var module = new TsModule()
    .TypeAlias("ScanStatus", TsType.Union(statuses.Select(TsType.StringLiteral)))
    .Interface(
        "ScanSummary",
        [
            new TsMember("id", TsType.String) { IsReadOnly = true },
            new TsMember("status", TsType.Of("ScanStatus")),
            new TsMember("finishedAt", TsType.Union([TsType.String, TsType.Null])) { Doc = "Null while running." },
        ],
        doc: "One scan, as the API returns it.");

export type ScanStatus = "Queued" | "Running";

/** One scan, as the API returns it. */
export interface ScanSummary {
  id: string;
  status: ScanStatus;
  /** Null while running. */
  finishedAt: string | null;
}

Generating those declarations from C# types is SimpleTypeScript.TypeGeneration, a companion package. This one has no dependencies and reflects over nothing.

What it is for

Generated code is compiled before anyone reads it, so a rule that is merely probably right produces a file that is broken where nobody is looking. The rules that are easy to get wrong are the ones this owns:

• String literals are escaped for ECMAScript source, not for JSON. The two differ where it matters: JSON leaves U+2028 and U+2029 raw inside a string, ECMAScript ends a line on them. A lone surrogate is escaped for the same reason — it cannot be encoded as well-formed UTF-8. Everything else printable is written as itself, because a generated vocabulary is read by whoever checks a translation and å is no use to them.
• A comment cannot be ended from inside it. Text carrying a line terminator would put the rest of itself into the module as code, so every terminator re-opens the comment — including the two only ECMAScript treats as one — and a doc comment's */ is neutralised.
• Numbers are invariant and round-trippable, and NaN and the infinities are refused rather than emitted as something that parses and means another thing.
• Output is byte-stable. Line endings are \n whatever the platform spells a newline as, and order is the caller's, so regenerating on another machine does not rewrite every line of a file that did not change.

Nothing here reflects: a value is built explicitly, so what is emitted is what the generator said to emit, and no trimming or AOT caveat is carried into a consumer.

The model

Three types here do not close with their own syntax, so TsType carries how tightly each binds and a container brackets anything looser than the position allows — ("a" | "b")[] rather than "a" | "b"[], which is a different type that compiles just as well. A rank rather than a flag, because the three disagree with each other: an array brackets a union and an intersection, an intersection brackets only the union, and B & readonly A[] needs nothing while (readonly A[])[] does.

readonly T[] is there because readonly on a member is only half the promise — readonly lines: Line[] refuses order.lines = [] and permits order.lines.push(x). Saying it properly needs the modifier on both.

An intersection is there for the open set. A generator describing a producer's vocabulary that may grow wants the known members to stay the editor's suggestions while a value nobody has seen is still assignable, and Known | string does not do that — TypeScript reduces it to string. Known | (string & Record<never, never>) does.

Still deliberately not the whole type system. Conditionals, mapped types and generics beyond Record and the two arrays have no shape here, because every level of a grammar that is modelled has to be kept correct. A composed type written as a name is refused by TsType.Of rather than half-supported: a type is something to build, not something to spell.

Installing

dotnet add package SimpleTypeScript

net8.0 and net10.0.

License

MIT. See LICENSE.txt.