yuku-codegen 0.5.16 → 0.5.18

package/README.md

@@ -16,15 +16,15 @@ npm install yuku-codegen
 import { parse } from "yuku-parser";
 import { print } from "yuku-codegen";
 
-const result = parse("const x = 1 + 2;");
-const { code } = print(result);
+const { program } = parse("const x = 1 + 2;");
+const { code } = print(program);
 
 console.log(code); // "const x = 1 + 2;"
 ```
 
 ## API
 
-All three entry points take the `ParseResult` returned by [`yuku-parser`](https://www.npmjs.com/package/yuku-parser) and share the same options and result shape.
+All three entry points take the `Program` node off the `ParseResult` returned by [`yuku-parser`](https://www.npmjs.com/package/yuku-parser) and share the same options and result shape.
 
 | Function | Behavior                                                                                              |
 | -------- | ----------------------------------------------------------------------------------------------------- |
@@ -47,12 +47,12 @@ interface CodegenResult {
 ## Options
 
 ```js
-const out = print(result, {
+const out = print(program, {
   format: "pretty",
   indent: 2,
   quotes: "double",
   comments: "some",
-  sourceMaps: true,
+  sourceMaps: { lineStarts },
 });
 ```
 
@@ -62,21 +62,22 @@ const out = print(result, {
 | `indent`     | `number`                                 | `2`        | Spaces per indentation level. Applies in pretty mode only.                   |
 | `quotes`     | `"double" \| "single"`                   | `"double"` | Quote style for emitted string literals.                                     |
 | `comments`   | `boolean \| "some" \| "line" \| "block"` | `"some"`   | Comment passthrough filter. See [Comments](#comments).                       |
-| `sourceMaps` | `boolean \| SourceMapOptions`            | `false`    | `true` emits a Source Map V3 with default metadata; pass an object for fine-grained control. See [Source maps](#source-maps). |
+| `sourceMaps` | `SourceMapOptions`                       | `undefined` | Pass an object to emit a Source Map V3. Its `lineStarts` is required, the rest of the metadata is optional. See [Source maps](#source-maps). |
 
 ## Source maps
 
-Set `sourceMaps: true` for a Source Map V3 with default metadata, or pass a `SourceMapOptions` object to fill in `file`, `sources`, `sourcesContent`, and `sourceRoot`. Source maps are read off `result.lineStarts`, so the `ParseResult` must come from `yuku-parser`.
+Pass a `SourceMapOptions` object to emit a Source Map V3. Its `lineStarts` field is required: feed it the `lineStarts` array from the parser's `ParseResult` (this is what maps generated positions back to the source). The remaining fields (`file`, `sources`, `sourcesContent`, `sourceRoot`) are optional metadata.
 
 ```js
 import { parse } from "yuku-parser";
 import { print } from "yuku-codegen";
 
 const source = `const greet = (name) => "Hello, " + name;`;
-const result = parse(source);
+const { program, lineStarts } = parse(source);
 
-const { code, map } = print(result, {
+const { code, map } = print(program, {
   sourceMaps: {
+    lineStarts,
     file: "out.js",
     sourceFileName: "in.js",
     sourcesContent: source,
@@ -89,9 +90,10 @@ await Bun.write("out.js.map", JSON.stringify(map));
 
 ### `SourceMapOptions`
 
-| Field            | Type     | Description                                                                         |
-| ---------------- | -------- | ----------------------------------------------------------------------------------- |
-| `file`           | `string` | Output filename, embedded as the map's `file`.                                      |
+| Field            | Type       | Description                                                                       |
+| ---------------- | ---------- | --------------------------------------------------------------------------------- |
+| `lineStarts`     | `number[]` | **Required.** The parser's `ParseResult.lineStarts`, 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. |
@@ -122,8 +124,8 @@ Columns are 0-indexed UTF-16 code units, matching Chrome DevTools and consumer-s
 import { parse } from "yuku-parser";
 import { strip } from "yuku-codegen";
 
-const result = parse(`const x: number = 1;`, { lang: "ts" });
-console.log(strip(result).code); // "const x = 1;"
+const { program } = parse(`const x: number = 1;`, { lang: "ts" });
+console.log(strip(program).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.
@@ -133,8 +135,8 @@ Type annotations, type aliases, interfaces, and other type-only constructs are d
 Comments live on the AST nodes they were attached to during parsing. To preserve them, parse with `attachComments: true`:
 
 ```js
-const result = parse(source, { attachComments: true });
-print(result).code;
+const { program } = parse(source, { attachComments: true });
+print(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.
@@ -148,12 +150,12 @@ The `comments` option then selects which attached comments are emitted. The defa
 | `"block"` | Emit `/* ... */` only.                                          |
 
 ```js
-const result = parse(`// hello\nconst x = 1;`, { attachComments: true });
-print(result, { comments: true }).code;
+const { program } = parse(`// hello\nconst x = 1;`, { attachComments: true });
+print(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](https://www.npmjs.com/package/yuku-parser#comments) for the full design rationale.
+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](https://www.npmjs.com/package/yuku-parser#comments) for the comment options.
 
 ## Minification
 
@@ -171,7 +173,7 @@ Combine with `format: "compact"` for full minification:
 ```js
 import { minify } from "yuku-codegen";
 
-const { code } = minify(result, { format: "compact" });
+const { code } = minify(program, { format: "compact" });
 ```
 
 ## License

package/encode.js

@@ -4,17 +4,17 @@
 const NULL = 0xFFFFFFFF;
 const _enc = new TextEncoder();
 const NODE_SIZE = 48;
-const HEADER_SIZE = 40;
+const HEADER_SIZE = 44;
 const NODE_FLAGS_OFFSET = 2;
 const NODE_FIELD0_OFFSET = 4;
 const NODE_HEADER_U32S = 2;
 const NODE_SPAN_START_U32 = 10;
 const NODE_SPAN_END_U32 = 11;
-const COMMENT_SIZE = 12;
-const COMMENT_FLAGS_OFFSET = 0;
-const COMMENT_VALUE_START_OFFSET = 4;
-const COMMENT_VALUE_END_OFFSET = 8;
-const FLAG_ATTACH_COMMENTS = 2;
+const ATTACHED_COMMENT_SIZE = 12;
+const ATTACHED_COMMENT_FLAGS_OFFSET = 0;
+const ATTACHED_COMMENT_VALUE_START_OFFSET = 4;
+const ATTACHED_COMMENT_VALUE_END_OFFSET = 8;
+const FLAG_ATTACHED_COMMENTS = 2;
 const BINARY_OPS_INV = {"==": 0, "!=": 1, "===": 2, "!==": 3, "<": 4, "<=": 5, ">": 6, ">=": 7, "+": 8, "-": 9, "*": 10, "/": 11, "%": 12, "**": 13, "|": 14, "^": 15, "&": 16, "<<": 17, ">>": 18, ">>>": 19, "in": 20, "instanceof": 21};
 const LOGICAL_OPS_INV = {"&&": 0, "||": 1, "??": 2};
 const UNARY_OPS_INV = {"-": 0, "+": 1, "!": 2, "~": 3, "typeof": 4, "void": 5, "delete": 6};
@@ -35,18 +35,18 @@ const ACCESSIBILITY_INV = (v) =>
   : 3;
 const TS_MAPPED_OPTIONAL_INV = (v) => v === true ? 1 : v === "+" ? 2 : v === "-" ? 3 : 0;
 const TS_MAPPED_READONLY_INV = (v) => v === true ? 1 : v === "+" ? 2 : v === "-" ? 3 : 0;
-function encode(result) {
-  const root = result.program;
-  const lineStarts = result.lineStarts;
-  let nodeCap = 512;
+function encode(program, lineStarts) {
+  const root = program;
+  const sizeHint = root.end || 0;
+  let nodeCap = Math.max(512, (sizeHint / 7) | 0);
   let nodeAB = new ArrayBuffer(nodeCap * NODE_SIZE);
   let nU8 = new Uint8Array(nodeAB);
   let nU32 = new Uint32Array(nodeAB);
   let nodeCount = 0;
-  let extraCap = 512;
+  let extraCap = Math.max(512, (sizeHint / 20) | 0);
   let extras = new Uint32Array(extraCap);
   let extraCount = 0;
-  let poolCap = 4096;
+  let poolCap = Math.max(4096, (sizeHint / 8) | 0);
   let pool = new Uint8Array(poolCap);
   let poolLen = 0;
   const strMap = new Map();
@@ -119,15 +119,29 @@ function encode(result) {
     if (s == null || s === "") return { start: 0, end: 0 };
     const hit = strMap.get(s);
     if (hit !== undefined) return hit;
-    const bytes = _enc.encode(s);
-    while (poolLen + bytes.length > poolCap) {
-      poolCap *= 2;
+    const n = s.length;
+    if (poolLen + n * 3 > poolCap) {
+      do { poolCap *= 2; } while (poolLen + n * 3 > poolCap);
       const np = new Uint8Array(poolCap);
       np.set(pool); pool = np;
     }
-    pool.set(bytes, poolLen);
-    const r = { start: poolLen, end: poolLen + bytes.length };
-    poolLen += bytes.length;
+    const start = poolLen;
+    let p = start;
+    let ascii = true;
+    for (let i = 0; i < n; i++) {
+      const c = s.charCodeAt(i);
+      if (c < 0x80) { pool[p++] = c; } else { ascii = false; break; }
+    }
+    let r;
+    if (ascii) {
+      r = { start, end: p };
+      poolLen = p;
+    } else {
+      const bytes = _enc.encode(s);
+      pool.set(bytes, start);
+      r = { start, end: start + bytes.length };
+      poolLen = start + bytes.length;
+    }
     strMap.set(s, r);
     return r;
   }
@@ -577,9 +591,11 @@ function encode(result) {
   }
   function enc_string_literal(n) {
     const s = encStr(typeof n.value === "string" ? n.value : "");
+    const r = encStr(typeof n.raw === "string" ? n.raw : "");
     const idx = alloc();
     tagAt(idx, 33);
     slotAt(idx, 0, s.start); slotAt(idx, 1, s.end);
+    slotAt(idx, 2, r.start); slotAt(idx, 3, r.end);
     spanAt(idx, asStart(n), asEnd(n));
     recordComments(n, idx);
     return idx;
@@ -2278,14 +2294,14 @@ function encode(result) {
   }
   const progIdx = encNode(root);
   const POSITION_INV = { "before": 0, "after": 1, "inside": 2 };
-  // counting-sort comments by host into a prefix-sum offsets table,
-  // then write each comment at its slot in `commentBytes`.
-  const attachComments = commentsByIdx.size > 0;
-  let commentCount = 0;
+  // counting-sort attached comments by host into a prefix-sum offsets
+  // table, then write each at its slot in `attachedBytes`.
+  const attached = commentsByIdx.size > 0;
+  let attachedCount = 0;
   let offsetsBytes = null;
-  let commentBytes = null;
-  if (attachComments) {
-    for (const arr of commentsByIdx.values()) commentCount += arr.length;
+  let attachedBytes = null;
+  if (attached) {
+    for (const arr of commentsByIdx.values()) attachedCount += arr.length;
     const offsets = new Uint32Array(nodeCount + 1);
     for (const [idx, arr] of commentsByIdx) offsets[idx] = arr.length;
     let sum = 0;
@@ -2296,9 +2312,9 @@ function encode(result) {
     }
     offsets[nodeCount] = sum;
     offsetsBytes = offsets.buffer;
-    commentBytes = new ArrayBuffer(commentCount * COMMENT_SIZE);
-    const cU8 = new Uint8Array(commentBytes);
-    const cDV = new DataView(commentBytes);
+    attachedBytes = new ArrayBuffer(attachedCount * ATTACHED_COMMENT_SIZE);
+    const cU8 = new Uint8Array(attachedBytes);
+    const cDV = new DataView(attachedBytes);
     const cursor = new Uint32Array(nodeCount);
     for (const [idx, arr] of commentsByIdx) {
       for (let j = 0; j < arr.length; j++) {
@@ -2309,10 +2325,10 @@ function encode(result) {
         f |= ((POSITION_INV[c.position] ?? 0) & 3) << 1;
         if (c.sameLine) f |= 8;
         const v = encStr(typeof c.value === "string" ? c.value : "");
-        const o = slot * COMMENT_SIZE;
-        cU8[o + COMMENT_FLAGS_OFFSET] = f;
-        cDV.setUint32(o + COMMENT_VALUE_START_OFFSET, v.start, true);
-        cDV.setUint32(o + COMMENT_VALUE_END_OFFSET, v.end, true);
+        const o = slot * ATTACHED_COMMENT_SIZE;
+        cU8[o + ATTACHED_COMMENT_FLAGS_OFFSET] = f;
+        cDV.setUint32(o + ATTACHED_COMMENT_VALUE_START_OFFSET, v.start, true);
+        cDV.setUint32(o + ATTACHED_COMMENT_VALUE_END_OFFSET, v.end, true);
       }
     }
   }
@@ -2327,12 +2343,12 @@ function encode(result) {
   }
   const totalNodeBytes = nodeCount * NODE_SIZE;
   const totalExtraBytes = extraCount * 4;
-  const totalOffsetsBytes = attachComments ? (nodeCount + 1) * 4 : 0;
-  const totalCommentBytes = commentCount * COMMENT_SIZE;
+  const totalOffsetsBytes = attached ? (nodeCount + 1) * 4 : 0;
+  const totalAttachedBytes = attachedCount * ATTACHED_COMMENT_SIZE;
   const totalLineStartsBytes = lineStartsCount * 4;
   const finalSize =
     HEADER_SIZE + totalNodeBytes + totalExtraBytes + poolLen +
-    totalOffsetsBytes + totalCommentBytes + totalLineStartsBytes;
+    totalOffsetsBytes + totalAttachedBytes + totalLineStartsBytes;
   const out = new ArrayBuffer(finalSize);
   const outU8 = new Uint8Array(out);
   const outU32 = new Uint32Array(out, 0, (finalSize >>> 2));
@@ -2340,23 +2356,24 @@ function encode(result) {
   outU32[1] = extraCount;
   outU32[2] = poolLen;
   outU32[3] = 0;
-  outU32[4] = commentCount;
-  outU32[5] = lineStartsCount;
-  outU32[6] = 0;
-  outU32[7] = progIdx;
-  outU32[8] = attachComments ? FLAG_ATTACH_COMMENTS : 0;
-  outU32[9] = 0;
+  outU32[4] = 0;
+  outU32[5] = attachedCount;
+  outU32[6] = lineStartsCount;
+  outU32[7] = 0;
+  outU32[8] = progIdx;
+  outU32[9] = attached ? FLAG_ATTACHED_COMMENTS : 0;
+  outU32[10] = 0;
   const nodesOff = HEADER_SIZE;
   const extrasOff = nodesOff + totalNodeBytes;
   const poolOff = extrasOff + totalExtraBytes;
   const offsetsOff = poolOff + poolLen;
-  const commentsOff = offsetsOff + totalOffsetsBytes;
-  const lineStartsOff = commentsOff + totalCommentBytes;
+  const attachedOff = offsetsOff + totalOffsetsBytes;
+  const lineStartsOff = attachedOff + totalAttachedBytes;
   outU8.set(new Uint8Array(nodeAB, 0, totalNodeBytes), nodesOff);
   outU8.set(new Uint8Array(extras.buffer, 0, totalExtraBytes), extrasOff);
   outU8.set(pool.subarray(0, poolLen), poolOff);
   if (offsetsBytes !== null) outU8.set(new Uint8Array(offsetsBytes), offsetsOff);
-  if (commentBytes !== null) outU8.set(new Uint8Array(commentBytes), commentsOff);
+  if (attachedBytes !== null) outU8.set(new Uint8Array(attachedBytes), attachedOff);
   if (lineStartsBytes !== null) outU8.set(new Uint8Array(lineStartsBytes), lineStartsOff);
   return out;
 }

package/index.d.ts

@@ -1,10 +1,16 @@
-import type { Comment, ParseResult } from "yuku-parser";
+import type { Comment, Program } from "yuku-parser";
 
 /** Whitespace mode for the generated output. */
 export type Format = "pretty" | "compact";
 
-/** Quote style for emitted string literals. */
-export type Quotes = "double" | "single";
+/**
+ * Quote style for emitted string literals.
+ *
+ * - `"preserve"`: reuse each literal's raw source text verbatim (quotes and
+ *   escapes exactly as written).
+ * - `"double"` / `"single"`: re-escape from the decoded value using that quote.
+ */
+export type Quotes = "preserve" | "double" | "single";
 
 /**
  * Comment passthrough filter.
@@ -21,6 +27,12 @@ export type { Comment };
 
 /** Source-map configuration. Pass to `CodegenOptions.sourceMaps` to enable. */
 export interface SourceMapOptions {
+  /**
+   * UTF-16 line-start offsets, taken straight from the parser's
+   * `ParseResult.lineStarts`. Required: this is what maps generated positions
+   * back to the original source.
+   */
+  lineStarts: number[];
   /** Output filename, embedded as the map's `file`. */
   file?: string;
   /** Source filename, embedded as the single entry of `sources`. */
@@ -40,15 +52,16 @@ export interface CodegenOptions {
    * @default 2
    */
   indent?: number;
-  /** @default "double" */
+  /** @default "preserve" */
   quotes?: Quotes;
   /**
-   * Enable Source Map V3 output. `true` uses default metadata; pass a
-   * {@link SourceMapOptions} object to fill in `file`, `sources`,
-   * `sourcesContent`, and `sourceRoot`.
-   * @default false
+   * Enable Source Map V3 output. Pass a {@link SourceMapOptions} object. Its
+   * `lineStarts` (from the parser) is required. The rest of the metadata
+   * (`file`, `sources`, `sourcesContent`, `sourceRoot`) is optional. Omit to
+   * disable.
+   * @default undefined
    */
-  sourceMaps?: boolean | SourceMapOptions;
+  sourceMaps?: SourceMapOptions;
   /**
    * Comment passthrough filter. Defaults to `"some"`, which preserves
    * legal headers, JSDoc, and tree-shaking annotations.
@@ -88,13 +101,13 @@ export interface CodegenResult {
 }
 
 /** Renders the AST verbatim, preserving TypeScript syntax. */
-export function print(result: ParseResult, options?: CodegenOptions): CodegenResult;
+export function print(program: Program, options?: CodegenOptions): CodegenResult;
 
 /** Renders the AST as JavaScript, dropping TypeScript-specific syntax. */
-export function strip(result: ParseResult, options?: CodegenOptions): CodegenResult;
+export function strip(program: Program, options?: CodegenOptions): CodegenResult;
 
 /**
  * Renders the AST with size-reducing rewrites. Combine with
  * `format: "compact"` for full minification.
  */
-export function minify(result: ParseResult, options?: CodegenOptions): CodegenResult;
+export function minify(program: Program, options?: CodegenOptions): CodegenResult;

package/index.js

@@ -7,37 +7,44 @@ function normalizeOptions(options) {
   const c = next.comments;
   if (c === true) next.comments = "all";
   else if (c === false) next.comments = "none";
+  // `lineStarts` is consumed by the encoder, not the native binding, so strip
+  // it from the source-map options. Only V3 metadata reaches the binding.
   const s = next.sourceMaps;
-  if (s === true) next.sourceMaps = {};
-  else if (s === false) next.sourceMaps = undefined;
+  if (s) {
+    const { lineStarts, ...meta } = s;
+    next.sourceMaps = meta;
+  } else {
+    next.sourceMaps = undefined;
+  }
   return next;
 }
 
-function prepare(result, options) {
-  if (!result || !result.program || !result.program.type) {
+function run(method, program, options) {
+  if (!program || !program.type) {
     throw new TypeError(
-      "Expected a `ParseResult` from yuku-parser, got " +
-        (result === null ? "null" : typeof result),
+      "Expected a `Program` node from yuku-parser, got " +
+        (program === null ? "null" : typeof program),
     );
   }
-  if (options?.sourceMaps && !result.lineStarts) {
+  const sourceMaps = options?.sourceMaps;
+  const lineStarts = sourceMaps ? sourceMaps.lineStarts : null;
+  if (sourceMaps && !Array.isArray(lineStarts)) {
     throw new Error(
-      "Source maps require a `ParseResult` with `lineStarts`. " +
-        "If you built or transformed this result outside of yuku-parser, " +
-        "either drop `sourceMaps` or attach a `lineStarts` array.",
+      "`sourceMaps` requires a `lineStarts` array. Pass the parser's " +
+        "`ParseResult.lineStarts`, e.g. `{ sourceMaps: { lineStarts } }`.",
     );
   }
-  return encode(result);
+  return binding[method](encode(program, lineStarts), normalizeOptions(options));
 }
 
-export function print(result, options) {
-  return binding.print(prepare(result, options), normalizeOptions(options));
+export function print(program, options) {
+  return run("print", program, options);
 }
 
-export function strip(result, options) {
-  return binding.strip(prepare(result, options), normalizeOptions(options));
+export function strip(program, options) {
+  return run("strip", program, options);
 }
 
-export function minify(result, options) {
-  return binding.minify(prepare(result, options), normalizeOptions(options));
+export function minify(program, options) {
+  return run("minify", program, options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuku-codegen",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "description": "High-performance JavaScript/TypeScript code generator written in Zig",
   "license": "MIT",
   "repository": {
@@ -17,17 +17,17 @@
     "encode.js"
   ],
   "optionalDependencies": {
-    "@yuku-codegen/binding-linux-x64-gnu": "0.5.16",
-    "@yuku-codegen/binding-linux-arm64-gnu": "0.5.16",
-    "@yuku-codegen/binding-linux-arm-gnu": "0.5.16",
-    "@yuku-codegen/binding-linux-x64-musl": "0.5.16",
-    "@yuku-codegen/binding-linux-arm64-musl": "0.5.16",
-    "@yuku-codegen/binding-linux-arm-musl": "0.5.16",
-    "@yuku-codegen/binding-darwin-x64": "0.5.16",
-    "@yuku-codegen/binding-darwin-arm64": "0.5.16",
-    "@yuku-codegen/binding-win32-x64": "0.5.16",
-    "@yuku-codegen/binding-win32-arm64": "0.5.16",
-    "@yuku-codegen/binding-freebsd-x64": "0.5.16"
+    "@yuku-codegen/binding-linux-x64-gnu": "0.5.18",
+    "@yuku-codegen/binding-linux-arm64-gnu": "0.5.18",
+    "@yuku-codegen/binding-linux-arm-gnu": "0.5.18",
+    "@yuku-codegen/binding-linux-x64-musl": "0.5.18",
+    "@yuku-codegen/binding-linux-arm64-musl": "0.5.18",
+    "@yuku-codegen/binding-linux-arm-musl": "0.5.18",
+    "@yuku-codegen/binding-darwin-x64": "0.5.18",
+    "@yuku-codegen/binding-darwin-arm64": "0.5.18",
+    "@yuku-codegen/binding-win32-x64": "0.5.18",
+    "@yuku-codegen/binding-win32-arm64": "0.5.18",
+    "@yuku-codegen/binding-freebsd-x64": "0.5.18"
   },
   "keywords": [
     "ast",
@@ -39,7 +39,7 @@
     "printer",
     "typescript"
   ],
-  "dependencies": {
-    "yuku-parser": "0.5.14"
+  "peerDependencies": {
+    "yuku-parser": "0.5.17"
   }
 }