yuku-codegen

yuku-codegen

A high-performance JavaScript and TypeScript code generator written in Zig, powered by Yuku.

Renders an ESTree / TypeScript-ESTree AST back to source code, with optional Source Map V3 output.

Install

npm install yuku-codegen

Usage

import { parse } from "yuku-parser";
import { generate } from "yuku-codegen";

const { program } = parse("const x = 1 + 2;");
const { code } = generate(program);

console.log(code); // "const x = 1 + 2;"

API

generate takes the Program node off the ParseResult returned by yuku-parser and returns a GenerateResult:

interface GenerateResult {
  code: string;
  errors: Diagnostic[];
  map: SourceMap | null;
}

errors is empty on a clean run. map is non-null only when sourceMap is enabled.

Options

Every transformation is an independent flag, so they compose freely:

const { code, map } = generate(program, {
  strip: true,
  minify: true,
  sourceMap: { source },
});

Option	Type	Default	Description
strip	boolean	false	Drop TypeScript-only syntax and emit plain JavaScript. See TypeScript stripping.
minify	boolean | MinifyOptions	false	true for maximum minification, an object for fine-grained control. See Minification.
format	"pretty" | "compact"	"pretty"	Whitespace mode. "compact" emits only the separators the grammar requires.
indent	number	2	Spaces per indentation level. Applies in pretty mode only.
quotes	"preserve" | "double" | "single" | "shortest"	"preserve"	Quote style for string literals. See Quotes.
comments	boolean | "some" | "none" | "line" | "block"	"some"	Comment passthrough filter. See Comments.
sourceMap	SourceMapOptions	undefined	Pass an object to emit a Source Map V3. See Source maps.

TypeScript stripping

strip: true rewrites the AST as plain JavaScript.

import { parse } from "yuku-parser";
import { generate } from "yuku-codegen";

const { program } = parse(`const x: number = 1;`, { lang: "ts" });
console.log(generate(program, { strip: true }).code); // "const x = 1;"

Type annotations, type aliases, interfaces, and other type-only constructs are dropped. Constructs that have no clean JavaScript equivalent (enum, namespace, import = require(), export =) are reported in errors and elided. The output is always syntactically valid JavaScript.

Minification

minify: true enables every switch for maximum minification:

const { code } = generate(program, { minify: true });

For fine-grained control, pass an object. Enabled switches override format and quotes.

Switch	Behavior
whitespace	Emit compact whitespace.
syntax	Apply size-reducing syntax rewrites (see below).
quotes	Use whichever quote needs fewer escapes per literal.

// rewrites only, keeping readable output
const { code } = generate(program, { minify: { syntax: true } });

The syntax rewrites:

• true and false rewrite to !0 and !1.
• undefined rewrites to void 0 (in expression position).
• Infinity rewrites to 1/0.
• Numeric literals shorten to their shortest form (1000000 becomes 1e6, 0.5 becomes .5).
• obj["foo"] rewrites to obj.foo when the key is a valid identifier.
• { "foo": x } rewrites to { foo: x } when safe.

Quotes

Value	Behavior
"preserve"	Keep each literal's source quote style, re-escaping the content. (default)
"double"	Force double quotes.
"single"	Force single quotes.
"shortest"	Pick whichever quote needs fewer escapes per literal; double on a tie.

Comments

Comments live on the AST nodes they were attached to during parsing. To preserve them, parse with attachComments: true:

const { program } = parse(source, { attachComments: true });
generate(program).code;

The comments option then selects which attached comments are emitted. The default is "some", which matches the bundler convention of keeping legal banners, JSDoc, and tree-shaking annotations while dropping plain noise.

Value	Behavior
"some"	Emit legal headers, JSDoc, and @/# annotations. (default)
true	Emit every comment.
false	Drop every comment.
"line"	Emit // ... only.
"block"	Emit /* ... */ only.

const { program } = parse(`// hello\nconst x = 1;`, { attachComments: true });
generate(program, { comments: true }).code;
// "// hello\nconst x = 1;"

Because comments are attached to nodes, they survive AST transforms: move or replace a node and its comments come with it. See the yuku-parser comments docs for the comment options.

Source maps

Pass a SourceMapOptions object to emit a Source Map V3. Its source field is required: feed it the original source text (this is what maps generated positions back to the source). Without it, no map is produced and map is null. The remaining fields (file, sources, sourcesContent, sourceRoot) are optional metadata.

import { parse } from "yuku-parser";
import { generate } from "yuku-codegen";

const source = `const greet = (name) => "Hello, " + name;`;
const { program } = parse(source);

const { code, map } = generate(program, {
  sourceMap: {
    source,
    file: "out.js",
    sourceFileName: "in.js",
    sourcesContent: source,
  },
});

await Bun.write("out.js", `${code}\n//# sourceMappingURL=out.js.map`);
await Bun.write("out.js.map", JSON.stringify(map));

SourceMapOptions

Field	Type	Description
source	string	Required. The original source text, used to map positions to the source.
file	string	Output filename, embedded as the map's file.
sourceFileName	string	Source filename, embedded as the single entry of sources.
sourceRoot	string	Prefix embedded as sourceRoot.
sourcesContent	string	When set, embedded as the single entry of the map's sourcesContent. Omit to skip.

Output shape

map is a Source Map V3 object, ready to serialize with JSON.stringify:

interface SourceMap {
  version: 3;
  file: string | null;
  sourceRoot: string | null;
  sources: string[];
  sourcesContent: (string | null)[] | null;
  names: string[];
  mappings: string;
}

Columns are 0-indexed UTF-16 code units, matching Chrome DevTools and consumer-side libraries like @jridgewell/trace-mapping and source-map.

License

MIT