yuku-codegen 0.5.15 → 0.5.17

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,8 +150,8 @@ 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;"
 ```
 
@@ -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

@@ -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;
   }

package/index.d.ts

@@ -1,4 +1,4 @@
-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";
@@ -21,6 +21,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`. */
@@ -43,12 +49,13 @@ export interface CodegenOptions {
   /** @default "double" */
   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 +95,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.15",
+  "version": "0.5.17",
   "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.15",
-    "@yuku-codegen/binding-linux-arm64-gnu": "0.5.15",
-    "@yuku-codegen/binding-linux-arm-gnu": "0.5.15",
-    "@yuku-codegen/binding-linux-x64-musl": "0.5.15",
-    "@yuku-codegen/binding-linux-arm64-musl": "0.5.15",
-    "@yuku-codegen/binding-linux-arm-musl": "0.5.15",
-    "@yuku-codegen/binding-darwin-x64": "0.5.15",
-    "@yuku-codegen/binding-darwin-arm64": "0.5.15",
-    "@yuku-codegen/binding-win32-x64": "0.5.15",
-    "@yuku-codegen/binding-win32-arm64": "0.5.15",
-    "@yuku-codegen/binding-freebsd-x64": "0.5.15"
+    "@yuku-codegen/binding-linux-x64-gnu": "0.5.17",
+    "@yuku-codegen/binding-linux-arm64-gnu": "0.5.17",
+    "@yuku-codegen/binding-linux-arm-gnu": "0.5.17",
+    "@yuku-codegen/binding-linux-x64-musl": "0.5.17",
+    "@yuku-codegen/binding-linux-arm64-musl": "0.5.17",
+    "@yuku-codegen/binding-linux-arm-musl": "0.5.17",
+    "@yuku-codegen/binding-darwin-x64": "0.5.17",
+    "@yuku-codegen/binding-darwin-arm64": "0.5.17",
+    "@yuku-codegen/binding-win32-x64": "0.5.17",
+    "@yuku-codegen/binding-win32-arm64": "0.5.17",
+    "@yuku-codegen/binding-freebsd-x64": "0.5.17"
   },
   "keywords": [
     "ast",
@@ -39,7 +39,7 @@
     "printer",
     "typescript"
   ],
-  "dependencies": {
+  "peerDependencies": {
     "yuku-parser": "0.5.14"
   }
 }