openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/api/string-to-ast.ts

@@ -0,0 +1,27 @@
+import { deprecate } from "node:util";
+import { parseStatements } from "../adapters/type-ast-bridge/ir-declarations-to-typescript.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import { IR_CALLBACKS_GUIDE_URL } from "./legacy-callback-warning.js";
+
+const STRING_TO_AST_DEPRECATION =
+  "stringToAST() is deprecated and removed in 2.0. Return TypeScript type text from an IR " +
+  `callback (irCallbacks: true) instead: ${IR_CALLBACKS_GUIDE_URL}`;
+
+/** Node's deprecation code for `stringToAST`, so users can filter or trace the warning. */
+export const STRING_TO_AST_DEPRECATION_CODE = "OPENAPI_TYPESAFE_DEP_STRING_TO_AST";
+
+function parseSource(source: string): unknown[] {
+  return [...parseStatements(loadTypeScript(), source)];
+}
+
+/**
+ * Convert an arbitrary string to TS (assuming it’s valid). Parses with the TypeScript bridge, so
+ * it needs TypeScript 6 or earlier (or `@typescript/typescript6`). Node's `util.deprecate` warns
+ * on the first call only.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 7). Use type text in IR callbacks.
+ */
+export const stringToAST: (source: string) => unknown[] = deprecate(
+  parseSource,
+  STRING_TO_AST_DEPRECATION,
+  STRING_TO_AST_DEPRECATION_CODE,
+);

package/src/api/transform-context.ts

@@ -0,0 +1,87 @@
+import * as changeCase from "change-case";
+import { RunFooter } from "../application/transform/footer/document-footer.js";
+import type { SchemaLocation } from "../application/transform/schema/schema-context.js";
+import type {
+  DocumentFooter,
+  NameCasing,
+  TransformContext,
+  TransformDiagnostics,
+  TransformOptions,
+} from "../application/transform/transform-context.js";
+import type { GlobalContext, TransformNodeOptions } from "../types.js";
+import { defaultLogger, monotonicNow } from "./default-ports.js";
+import { ContextFooterSink } from "./footer-sink.js";
+import { schemaCallbacks } from "./schema-callbacks.js";
+
+/**
+ * Builds the ported transformers' context from the original `GlobalContext`: options, refs,
+ * discriminators, the run footer and the user callbacks (see `schema-callbacks.ts`).
+ */
+
+function transformOptions(ctx: GlobalContext): TransformOptions {
+  return {
+    additionalProperties: ctx.additionalProperties,
+    alphabetize: ctx.alphabetize,
+    arrayLength: ctx.arrayLength,
+    binaryAsBlob: ctx.binaryAsBlob,
+    conditionalEnums: ctx.conditionalEnums,
+    dedupeEnums: ctx.dedupeEnums,
+    defaultNonNullable: ctx.defaultNonNullable,
+    emptyObjectsUnknown: ctx.emptyObjectsUnknown,
+    enum: ctx.enum,
+    enumValues: ctx.enumValues,
+    excludeDeprecated: ctx.excludeDeprecated,
+    fixes: new Set(ctx.fix ?? []),
+    immutable: ctx.immutable,
+    propertiesRequiredByDefault: ctx.propertiesRequiredByDefault,
+    readWriteMarkers: ctx.readWriteMarkers,
+    generatePathParams: ctx.generatePathParams,
+    pathParamsAsTypes: ctx.pathParamsAsTypes,
+    rootTypes: ctx.rootTypes,
+    rootTypesNoSchemaPrefix: ctx.rootTypesNoSchemaPrefix,
+    rootTypesKeepCasing: ctx.rootTypesKeepCasing,
+    exportType: ctx.exportType,
+    inject: ctx.inject,
+    makePathsEnum: ctx.makePathsEnum,
+  };
+}
+
+/** One footer per run: it holds the enum registry, so it lives on the run's context. */
+function runFooter(ctx: GlobalContext): DocumentFooter {
+  ctx.runFooter ??= new RunFooter(new ContextFooterSink(ctx.injectFooter), ctx.dedupeEnums);
+  return ctx.runFooter;
+}
+
+const CASING: NameCasing = { pascalCase: (text) => changeCase.pascalCase(text) };
+
+/**
+ * A monotonic clock and the run's logger (the default one for a user's own context), "ts" group.
+ */
+function diagnostics(ctx: GlobalContext): TransformDiagnostics {
+  const logger = ctx.logger ?? defaultLogger(ctx.silent);
+  return {
+    now: monotonicNow,
+    debug: (message, durationMs) => logger.debug(message, "ts", durationMs),
+  };
+}
+
+/** The ported transformers' context for one call from a legacy transformer. */
+export function createTransformContext(ctx: GlobalContext): TransformContext {
+  return {
+    options: transformOptions(ctx),
+    refs: { resolve: (ref) => ctx.resolve(ref) },
+    discriminators: {
+      objectAt: (ref) => ctx.discriminators.objects[ref],
+      isHandled: (ref) => ctx.discriminators.refsHandled.includes(ref),
+    },
+    footer: runFooter(ctx),
+    callbacks: schemaCallbacks(ctx),
+    diagnostics: diagnostics(ctx),
+    casing: CASING,
+  };
+}
+
+/** The transformer's location for the original options object. */
+export function schemaLocation(options: TransformNodeOptions): SchemaLocation {
+  return { path: options.path, schema: options.schema };
+}

package/src/api/transform-schema.ts

@@ -0,0 +1,39 @@
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import { documentBody, documentClosing } from "../application/transform/document/document.js";
+import { renameAliasesTakenByFooter } from "../application/transform/document/root-type-aliases.js";
+import type { IrDeclaration } from "../domain/ir/nodes.js";
+import type { DocumentObject } from "../domain/openapi/document-object.js";
+import type { GlobalContext, OpenAPI3 } from "../types.js";
+import { documentDeclarations, type TransformedDocument } from "./document-declarations.js";
+import { type FooterEntry, isIrDeclaration } from "./footer-entry.js";
+import { createTransformContext } from "./transform-context.js";
+
+const OPERATIONS_NAME = "operations";
+
+/** Whether a footer entry is named `operations` (any declaration kind, as in the original). */
+function isOperations(entry: FooterEntry): boolean {
+  const name = isIrDeclaration(entry)
+    ? (entry as { name?: string }).name
+    : (entry as Partial<ts.InterfaceDeclaration>).name?.escapedText;
+  return name === OPERATIONS_NAME;
+}
+
+/** @internal Root types, the footer, then the closing declarations (Phase 5, step 6). */
+export function transformDocument(schema: OpenAPI3, ctx: GlobalContext): TransformedDocument {
+  const document = schema as DocumentObject;
+  const context = createTransformContext(ctx);
+  // documentBody registers the enums in the footer, so the footer is read after it.
+  const rawBody = documentBody(document, context);
+  const footer: FooterEntry[] = [...ctx.injectFooter];
+  const body = renameAliasesTakenByFooter(rawBody, footer.filter(isIrDeclaration));
+  const closing = documentClosing(document, context, footer.some(isOperations));
+  return { body, footer, closing };
+}
+
+/**
+ * The whole document as IR declarations (ENGINEERING_PLAN 6.1–6.2); `openapiTS` returns the same
+ * for a loaded document.
+ */
+export default function transformSchema(schema: OpenAPI3, ctx: GlobalContext): IrDeclaration[] {
+  return documentDeclarations(transformDocument(schema, ctx));
+}

package/src/api/type-helpers.ts

@@ -0,0 +1,130 @@
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import { fromTypeNode } from "../adapters/type-ast-bridge/typescript-to-ir.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import { HELPER_TYPES } from "../application/transform/helper-types.js";
+import { literalType } from "../application/transform/literal-type.js";
+import { refType } from "../application/transform/ref-type.js";
+import { UNKNOWN_TYPE } from "../application/transform/shared-types.js";
+import {
+  intersectionOf,
+  nullableOf,
+  omitKeys,
+  unionOf,
+  withRequiredKeys,
+} from "../application/transform/type-combinators.js";
+import { irBoolean, irKeyword, irRecord } from "../domain/ir/constructors.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ParameterObject, ReferenceObject } from "../types.js";
+import { declaresTypeAlias, type FooterEntry } from "./footer-entry.js";
+
+/**
+ * The public type helpers (ENGINEERING_PLAN 6.2, ADR-004 decision 2). Same names and call
+ * signatures as the original helpers; they return IR types. A `ts.TypeNode` argument (from user
+ * code built with `ts.factory`) is read into IR by the bridge.
+ */
+
+/** A helper argument: an IR type, or a TypeScript type node from user code. */
+export type TypeInput = IrType | ts.TypeNode;
+
+export const BOOLEAN: IrType = Object.freeze(irKeyword("boolean"));
+export const FALSE: IrType = Object.freeze(irBoolean(false));
+export const NEVER: IrType = Object.freeze(irKeyword("never"));
+export const NULL: IrType = Object.freeze(irKeyword("null"));
+export const NUMBER: IrType = Object.freeze(irKeyword("number"));
+export const STRING: IrType = Object.freeze(irKeyword("string"));
+export const TRUE: IrType = Object.freeze(irBoolean(true));
+export const UNDEFINED: IrType = Object.freeze(irKeyword("undefined"));
+/** The shared `unknown` type; the transformers compare with it by identity, as the original did. */
+export const UNKNOWN: IrType = UNKNOWN_TYPE;
+
+/** IR nodes have a string `kind`; TypeScript nodes have a numeric `SyntaxKind`. */
+function isIrType(type: TypeInput): type is IrType {
+  return typeof type.kind === "string";
+}
+
+/** @internal Read a helper argument into IR. */
+export function toIrType(type: TypeInput): IrType {
+  return isIrType(type) ? type : fromTypeNode(loadTypeScript(), type);
+}
+
+/** `A | B`: `never` for no types, the type itself for one; repeated primitives are removed. */
+export function tsUnion(types: readonly TypeInput[]): IrType {
+  return unionOf(types.map(toIrType));
+}
+
+/** `A & B`, with the same rules as `tsUnion`. */
+export function tsIntersection(types: readonly TypeInput[]): IrType {
+  return intersectionOf(types.map(toIrType));
+}
+
+/** `A | null`, without removing repeated types. */
+export function tsNullable(types: readonly TypeInput[]): IrType {
+  return nullableOf(types.map(toIrType));
+}
+
+/** `Omit<T, "a" | "b">`. */
+export function tsOmit(type: TypeInput, keys: readonly string[]): IrType {
+  return omitKeys(toIrType(type), keys);
+}
+
+/** `Record<K, V>`. */
+export function tsRecord(key: TypeInput, value: TypeInput): IrType {
+  return irRecord(toIrType(key), toIrType(value));
+}
+
+/**
+ * The literal type of a JSON value: strings, numbers, booleans and `null` as literals, arrays as
+ * tuples (an empty one as `never[]`), objects as object types; anything else is `unknown`.
+ */
+export function tsLiteral(value: unknown): IrType {
+  return literalType(value);
+}
+
+/**
+ * `WithRequired<T, "a" | "b">`, or the type itself for no keys. Adds the `WithRequired` helper
+ * type to the footer once.
+ */
+export function tsWithRequired(
+  type: TypeInput,
+  keys: readonly string[],
+  injectFooter: FooterEntry[],
+): IrType {
+  if (keys.length === 0) {
+    return toIrType(type);
+  }
+  const { name, text } = HELPER_TYPES.withRequired;
+  if (!injectFooter.some((entry) => declaresTypeAlias(entry, name))) {
+    injectFooter.push({ kind: "rawDeclaration", name, text });
+  }
+  return withRequiredKeys(toIrType(type), keys);
+}
+
+export interface OapiRefOptions {
+  /** Whether to wrap with FlattenedDeepRequired<> (default: false) */
+  deep?: boolean;
+  /** Array of property names to wrap with Extract<> when accessing */
+  extractProperties?: string[];
+}
+
+function isParameterObject(
+  value: ParameterObject | ReferenceObject | undefined,
+): value is ParameterObject {
+  return Boolean(value && !("$ref" in value && value.$ref) && (value as ParameterObject).in);
+}
+
+/**
+ * The generated type a JSON Pointer refers to, as an indexed access: `#/components/schemas/Foo`
+ * → `components["schemas"]["Foo"]`. Object `properties` are skipped, and a referenced parameter
+ * is indexed by its location (`resolved`).
+ */
+export function oapiRef(
+  path: string,
+  resolved?: ParameterObject | ReferenceObject,
+  options: OapiRefOptions = {},
+): IrType {
+  return refType(path, {
+    isDeep: options.deep ?? false,
+    extractProperties: options.extractProperties ?? [],
+    parameter: isParameterObject(resolved) ? { in: resolved.in, name: resolved.name } : null,
+  });
+}

package/src/api/unsupported-feature-warnings.ts

@@ -0,0 +1,26 @@
+import type { Logger } from "../application/ports/logger.js";
+import {
+  findUnsupportedFeatures,
+  UnsupportedFeature,
+} from "../domain/openapi/unsupported-features.js";
+
+const DOCS_BASE_URL = "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs";
+const SUPPORT_DOCS_URL = `${DOCS_BASE_URL}/introduction.md#openapi-3-2-support`;
+
+/** Why each feature is not in the generated types. */
+const REASONS: Readonly<Record<UnsupportedFeature, string>> = {
+  [UnsupportedFeature.QUERYSTRING_NEXT_TO_QUERY]:
+    'is an "in: querystring" parameter next to "in: query" parameters, which OpenAPI 3.2 does ' +
+    "not allow; the query parameters keep their types and this parameter is not in the " +
+    "generated types",
+};
+
+/**
+ * Warn once per use of an OpenAPI 3.2 feature that the generated types leave out, so a missing
+ * parameter is never silent (CODING_PRINCIPLES §8.7).
+ */
+export function warnUnsupportedFeatures(document: unknown, logger: Logger): void {
+  for (const { feature, pointer } of findUnsupportedFeatures(document)) {
+    logger.warn(`${pointer} ${REASONS[feature]}. See ${SUPPORT_DOCS_URL}`);
+  }
+}

package/src/application/ports/file-system.ts

@@ -0,0 +1,12 @@
+/** Read a generated file, for `--check` (ENGINEERING_PLAN 4.5). Fails with `OUTPUT_READ_FAILED`. */
+export interface FileReader {
+  readText(file: URL): string;
+}
+
+/**
+ * Write a generated file, creating its directory first (ENGINEERING_PLAN 4.5). Fails with
+ * `OUTPUT_WRITE_FAILED`.
+ */
+export interface FileWriter {
+  writeText(file: URL, contents: string): void;
+}

package/src/application/ports/logger.ts

@@ -0,0 +1,16 @@
+/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
+export type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
+
+/**
+ * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
+ * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
+ */
+export interface Logger {
+  /**
+   * A debug line, with how long the step took when it was measured. A line without a group is
+   * written whenever debug output is on.
+   */
+  debug(message: string, group?: DebugGroup, durationMs?: number): void;
+  warn(message: string): void;
+  error(message: string): void;
+}

package/src/application/ports/redocly-config-source.ts

@@ -0,0 +1,16 @@
+import type { GeneratorOptions } from "../../types.js";
+
+/** The loaded Redocly config, as the generator options take it. */
+export type RedoclyConfig = NonNullable<GeneratorOptions["redocly"]>;
+
+/** Where the CLI finds and loads `redocly.yaml` (ENGINEERING_PLAN 4.5). */
+export interface RedoclyConfigSource {
+  /**
+   * The config file to use: `explicitPath` (a file, or a directory to search), or the one found
+   * from the working directory. Undefined when there is none.
+   */
+  find(explicitPath: string | undefined): string | undefined;
+  load(configPath: string): Promise<RedoclyConfig>;
+  /** The config used when there is no file: the minimal rules. */
+  createDefault(): Promise<RedoclyConfig>;
+}

package/src/application/ports/schema-loader.ts

@@ -0,0 +1,32 @@
+import type { OpenAPI3, SchemaSource } from "../../types.js";
+
+/**
+ * Where `$ref` documents may be loaded from (threat model R1 and R2, ADR-017). An unset limit
+ * allows everything, as in openapi-typescript; the root document is never limited.
+ */
+export interface RefAccess {
+  /** Local `$ref` files must be in this directory or below it (a `file:` URL). */
+  readonly localRoot?: URL;
+  /** Remote `$ref` documents must come from these hosts (`name` or `name:port`); `[]`: none. */
+  readonly remoteHosts?: readonly string[];
+}
+
+export interface SchemaLoadRequest {
+  readonly source: SchemaSource;
+  /** The base for relative `$ref`s of a source that is not a URL (a directory URL). */
+  readonly cwd: URL;
+  /** Lint with the Redocly config before bundling; off with the `lint: false` option. */
+  readonly shouldLint: boolean;
+  readonly refAccess: RefAccess;
+}
+
+/**
+ * Read, validate and bundle an OpenAPI 3 document into one document (ENGINEERING_PLAN 4.5).
+ * Fails with a typed error (ADR-011): `SCHEMA_SOURCE_*`, `SCHEMA_LOAD_FAILED`,
+ * `SCHEMA_REF_FORBIDDEN`,
+ * `SCHEMA_PARSE_FAILED`, `SCHEMA_VERSION_UNSUPPORTED`, `SCHEMA_INVALID`, `SCHEMA_REF_INVALID`,
+ * `SCHEMA_TOO_DEEP` or `SCHEMA_KEY_UNSUPPORTED`.
+ */
+export interface SchemaLoader {
+  load(request: SchemaLoadRequest): Promise<OpenAPI3>;
+}

package/src/application/print/comment-writer.ts

@@ -0,0 +1,91 @@
+import { assertNever } from "../../domain/assert-never.js";
+import type { IrComment } from "../../domain/ir/nodes.js";
+import { isLineBreak, type TextWriter } from "./text-writer.js";
+
+const LINE_FEED = 0x0a;
+const CARRIAGE_RETURN = 0x0d;
+
+/** Single-line white space as the TypeScript scanner defines it (`isWhiteSpaceSingleLine`). */
+const SINGLE_LINE_WHITESPACE = new Set([
+  0x20, 0x09, 0x0b, 0x0c, 0xa0, 0x85, 0x1680, 0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005,
+  0x2006, 0x2007, 0x2008, 0x2009, 0x200a, 0x200b, 0x202f, 0x205f, 0x3000, 0xfeff,
+]);
+const TAB = 0x09;
+
+/** Start offsets of every line, splitting at CR LF, CR, LF, U+2028 and U+2029 like TypeScript. */
+function computeLineStarts(text: string): number[] {
+  const starts = [0];
+  for (let position = 0; position < text.length; position++) {
+    const code = text.charCodeAt(position);
+    if (code === CARRIAGE_RETURN && text.charCodeAt(position + 1) === LINE_FEED) {
+      position++;
+    }
+    if (isLineBreak(code)) {
+      starts.push(position + 1);
+    }
+  }
+  return starts;
+}
+
+/** Leading white space width of `text[start, end)`, counting a tab up to the next tab stop. */
+function measureIndent(text: string, start: number, end: number, tabSize: number): number {
+  let width = 0;
+  for (
+    let position = start;
+    position < end && SINGLE_LINE_WHITESPACE.has(text.charCodeAt(position));
+    position++
+  ) {
+    width += text.charCodeAt(position) === TAB ? tabSize - (width % tabSize) : 1;
+  }
+  return width;
+}
+
+/** Write the line `text[start, end)` trimmed; a blank line becomes a bare line break. */
+function writeTrimmedLine(writer: TextWriter, text: string, start: number, end: number): void {
+  const lineEnd = Math.min(text.length, end - 1);
+  const line = text.substring(start, lineEnd).trim();
+  if (line.length === 0) {
+    writer.rawWrite(writer.options.newLine);
+    return;
+  }
+  writer.write(line);
+  if (lineEnd !== text.length) {
+    writer.writeLine();
+  }
+}
+
+/**
+ * Write a `/*...*\/` comment the way the TypeScript printer writes a synthesized one: every line
+ * after the first is re-indented to the current level plus the line's own leading white space, and
+ * every line is trimmed. (TypeScript only does this for comments whose second character is `*`,
+ * which is always true for a synthesized block comment, so there is no other branch.)
+ */
+function writeBlockComment(writer: TextWriter, body: string): void {
+  const text = `/*${body}*/`;
+  const lineStarts = computeLineStarts(text);
+  const { indentSize } = writer.options;
+  lineStarts.forEach((start, line) => {
+    const end = line + 1 === lineStarts.length ? text.length + 1 : (lineStarts[line + 1] as number);
+    if (line > 0) {
+      const spaces = writer.indent * indentSize + measureIndent(text, start, end, indentSize);
+      writer.rawWrite(" ".repeat(spaces));
+    }
+    writeTrimmedLine(writer, text, start, end);
+  });
+}
+
+/** Write a comment on its own line before the node it belongs to. */
+export function writeLeadingComment(writer: TextWriter, comment: IrComment): void {
+  switch (comment.kind) {
+    case "block":
+      writeBlockComment(writer, comment.text);
+      break;
+    case "line":
+      writer.writeLine();
+      writer.write(`//${comment.text}`);
+      break;
+    default:
+      assertNever(comment);
+  }
+  writer.writeLine();
+}

package/src/application/print/declaration-printer.ts

@@ -0,0 +1,100 @@
+import { assertNever } from "../../domain/assert-never.js";
+import type {
+  IrComment,
+  IrConstArrayDeclaration,
+  IrDeclaration,
+  IrEnumDeclaration,
+  IrEnumMember,
+  IrInterfaceDeclaration,
+  IrTypeAliasDeclaration,
+} from "../../domain/ir/nodes.js";
+import { writeLeadingComment } from "./comment-writer.js";
+import { printEscapedString, printNumberLiteral } from "./literal-text.js";
+import type { TextWriter } from "./text-writer.js";
+import { writeMember, writeMultiLineList, writeType } from "./type-printer.js";
+
+/** Enum initializers and array elements are expressions: strings use printer escaping. */
+function printValue(value: string | number): string {
+  return typeof value === "number" ? printNumberLiteral(value) : printEscapedString(value);
+}
+
+function writeHead(
+  writer: TextWriter,
+  declaration: { comments: readonly IrComment[]; isExported: boolean },
+): void {
+  for (const comment of declaration.comments) {
+    writeLeadingComment(writer, comment);
+  }
+  if (declaration.isExported) {
+    writer.write("export ");
+  }
+}
+
+function writeInterface(writer: TextWriter, declaration: IrInterfaceDeclaration): void {
+  writeHead(writer, declaration);
+  writer.write(`interface ${declaration.name} {`);
+  writeMultiLineList(
+    writer,
+    declaration.members,
+    { delimiter: "", isLineBreakWhenEmpty: true },
+    (member) => writeMember(writer, member),
+  );
+  writer.write("}");
+}
+
+function writeTypeAlias(writer: TextWriter, declaration: IrTypeAliasDeclaration): void {
+  writeHead(writer, declaration);
+  writer.write(`type ${declaration.name} = `);
+  writeType(writer, declaration.type);
+  writer.write(";");
+}
+
+function writeEnumMember(writer: TextWriter, member: IrEnumMember): void {
+  for (const comment of member.comments) {
+    writeLeadingComment(writer, comment);
+  }
+  writer.write(`${member.name} = ${printValue(member.value)}`);
+}
+
+function writeEnum(writer: TextWriter, declaration: IrEnumDeclaration): void {
+  writeHead(writer, declaration);
+  writer.write(`enum ${declaration.name} {`);
+  writeMultiLineList(
+    writer,
+    declaration.members,
+    { delimiter: ",", isLineBreakWhenEmpty: true },
+    (member) => writeEnumMember(writer, member),
+  );
+  writer.write("}");
+}
+
+function writeConstArray(writer: TextWriter, declaration: IrConstArrayDeclaration): void {
+  writeHead(writer, declaration);
+  writer.write(`const ${declaration.name}: `);
+  writeType(writer, declaration.type);
+  writer.write(` = [${declaration.values.map(printValue).join(", ")}];`);
+}
+
+/** Write one top-level declaration, starting on a new line. */
+export function writeDeclaration(writer: TextWriter, declaration: IrDeclaration): void {
+  writer.writeLine();
+  switch (declaration.kind) {
+    case "interface":
+      writeInterface(writer, declaration);
+      break;
+    case "typeAlias":
+      writeTypeAlias(writer, declaration);
+      break;
+    case "enum":
+      writeEnum(writer, declaration);
+      break;
+    case "constArray":
+      writeConstArray(writer, declaration);
+      break;
+    case "rawDeclaration":
+      writer.write(declaration.text);
+      break;
+    default:
+      assertNever(declaration);
+  }
+}

package/src/application/print/literal-text.ts

@@ -0,0 +1,62 @@
+import type { IrStringEncoding } from "../../domain/ir/nodes.js";
+
+/**
+ * Escapes TypeScript's printer uses inside a double-quoted string literal (its `escapeString`).
+ * Other characters below U+0020 use `\uXXXX`; so does every non-ASCII code unit
+ * (`escapeNonAsciiString`).
+ */
+const NAMED_ESCAPES: ReadonlyMap<number, string> = new Map([
+  [0x09, "\\t"],
+  [0x0b, "\\v"],
+  [0x0c, "\\f"],
+  [0x08, "\\b"],
+  [0x0d, "\\r"],
+  [0x0a, "\\n"],
+  [0x5c, "\\\\"],
+  [0x22, '\\"'],
+]);
+const NULL_CODE = 0x00;
+const FIRST_PRINTABLE_ASCII = 0x20;
+const LAST_ASCII = 0x7f;
+const DIGIT_ZERO = 0x30;
+const DIGIT_NINE = 0x39;
+
+function toUtf16Escape(code: number): string {
+  return `\\u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+
+function isDigit(code: number): boolean {
+  return code >= DIGIT_ZERO && code <= DIGIT_NINE;
+}
+
+/** `\0` must not be followed by a digit, or it would read as an octal escape. */
+function escapeCodeUnit(code: number, nextCode: number): string {
+  if (code === NULL_CODE) {
+    return isDigit(nextCode) ? "\\x00" : "\\0";
+  }
+  const named = NAMED_ESCAPES.get(code);
+  if (named !== undefined) {
+    return named;
+  }
+  const isPlainAscii = code >= FIRST_PRINTABLE_ASCII && code <= LAST_ASCII;
+  return isPlainAscii ? String.fromCharCode(code) : toUtf16Escape(code);
+}
+
+/** A double-quoted string literal as the TypeScript printer writes a synthesized one. */
+export function printEscapedString(value: string): string {
+  let escaped = "";
+  for (let index = 0; index < value.length; index++) {
+    escaped += escapeCodeUnit(value.charCodeAt(index), value.charCodeAt(index + 1));
+  }
+  return `"${escaped}"`;
+}
+
+/** A string literal in the given encoding (see `IrStringEncoding`). */
+export function printStringLiteral(value: string, encoding: IrStringEncoding): string {
+  return encoding === "json" ? JSON.stringify(value) : printEscapedString(value);
+}
+
+/** A number as the original writes it: the absolute value's `String()` text, with a minus sign. */
+export function printNumberLiteral(value: number): string {
+  return value < 0 ? `-${String(Math.abs(value))}` : String(value);
+}