yuku-parser 0.4.0 → 0.4.2

package/README.md

@@ -0,0 +1,137 @@
+# yuku-parser
+
+A high-performance, spec-compliant JavaScript/TypeScript parser written in Zig, powered by [Yuku](https://github.com/yuku-toolchain/yuku).
+
+## Install
+
+```bash
+npm install yuku-parser
+```
+
+## Usage
+
+```js
+import { parse } from "yuku-parser";
+
+const result = parse("const x = 1 + 2;");
+
+console.log(result.program);     // ESTree / TypeScript-ESTree Program node
+console.log(result.comments);    // all comments
+console.log(result.diagnostics); // errors and warnings
+```
+
+## ESTree / TypeScript-ESTree
+
+For JavaScript and JSX, the AST is fully conformant with the [ESTree](https://github.com/estree/estree) specification, identical to what [Acorn](https://www.npmjs.com/package/acorn) produces.
+
+For TypeScript, the AST conforms to the [TypeScript-ESTree](https://www.npmjs.com/package/@typescript-eslint/typescript-estree) format used by `@typescript-eslint`.
+
+The only differences from the base ESTree / TypeScript-ESTree specifications are:
+
+- Support for Stage 3 [decorators](https://github.com/tc39/proposal-decorators).
+- Support for Stage 3 [import defer](https://github.com/tc39/proposal-defer-import-eval) and [import source](https://github.com/tc39/proposal-source-phase-imports). Dynamic forms (`import.defer(...)`, `import.source(...)`) are represented as an `ImportExpression` with a `phase` field set to `"defer"` or `"source"`, following the ESTree convention.
+- A non-standard `hashbang` field on `Program` for `#!/usr/bin/env node` lines.
+
+Any other deviation from Acorn's ESTree or `@typescript-eslint`'s TypeScript-ESTree would be considered a bug.
+
+## AST Types
+
+All AST node types are exported directly from this package:
+
+```ts
+import type { Node, Statement, Expression, Identifier } from "yuku-parser";
+```
+
+The `Node` union type covers every possible AST node. Individual types like `Statement`, `Expression`, `Declaration`, etc. are also available. See the full list in the [type definitions](https://github.com/yuku-toolchain/yuku/blob/main/npm/yuku-parser/index.d.ts).
+
+## Walking the AST
+
+The AST is standard ESTree, so any ESTree-compatible walker works. For example, with [zimmerframe](https://github.com/sveltejs/zimmerframe):
+
+```ts
+import { parse, type Node } from "yuku-parser";
+import { walk } from "zimmerframe";
+
+const { program } = parse(`
+  const message = "hello";
+  console.log(message);
+`);
+
+walk(program as Node, null, {
+  Identifier(node) {
+    console.log(node.name);
+  },
+  VariableDeclaration(node) {
+    console.log(node.kind);
+  },
+});
+```
+
+## Options
+
+All options are optional.
+
+```js
+const result = parse(source, {
+  sourceType: "module",
+  lang: "jsx",
+  preserveParens: false,
+  semanticErrors: false,
+});
+```
+
+| Option | Values | Default | Description |
+|--------|--------|---------|-------------|
+| `sourceType` | `"module"`, `"script"` | `"module"` | Module mode enables `import`/`export`, `import.meta`, top-level `await`, and strict mode. |
+| `lang` | `"js"`, `"ts"`, `"jsx"`, `"tsx"`, `"dts"` | `"js"` | Language variant controls which syntax extensions are enabled. |
+| `preserveParens` | `true`, `false` | `false` | Keep `ParenthesizedExpression` nodes in the AST. When false, parentheses are stripped and only the inner expression is kept. |
+| `semanticErrors` | `true`, `false` | `false` | Run semantic analysis and report semantic errors alongside syntax errors. |
+
+## Result
+
+`parse` returns a `ParseResult`:
+
+```ts
+interface ParseResult {
+  program: Program;
+  comments: Comment[];
+  diagnostics: Diagnostic[];
+}
+```
+
+The parser is error-tolerant, an AST is always produced even when diagnostics are present.
+
+### Diagnostics
+
+Diagnostics cover both syntax errors found during parsing and, when `semanticErrors` is enabled, semantic errors that require scope and binding information (e.g. duplicate `let` declarations, `break` outside a loop, unresolved private fields).
+
+Each diagnostic includes:
+
+- `severity`: `"error"`, `"warning"`, `"hint"`, or `"info"`
+- `message`: description of the issue
+- `help`: fix suggestion, or `null`
+- `start` / `end`: byte offsets into the source
+- `labels`: additional source spans with messages for context
+
+### Semantic Errors
+
+By default, the parser only reports syntax errors. Semantic errors require resolving scopes and bindings, which is done in a separate AST pass. Enable this with the `semanticErrors` option:
+
+```js
+const result = parse(`let x = 1; let x = 2;`, { semanticErrors: true });
+// result.diagnostics will include "Identifier `x` has already been declared", etc.
+```
+
+This incurs a very small performance overhead. If your build pipeline already handles semantic validation (e.g. through a linter or type checker), you can leave this off for faster parsing.
+
+### Comments
+
+Each comment includes:
+
+- `type`: `"Line"` or `"Block"`
+- `value`: comment text without delimiters (`//`, `/*`, `*/`)
+- `start` / `end`: byte offsets
+
+## License
+
+MIT

package/index.d.ts

@@ -18,6 +18,13 @@ interface ParseOptions {
 	 * @default "js"
 	 */
 	lang?: SourceLang;
+	/**
+	 * When true, parenthesized expressions are represented as
+	 * `ParenthesizedExpression` nodes in the AST. When false,
+	 * parentheses are stripped and only the inner expression is kept.
+	 * @default false
+	 */
+	preserveParens?: boolean;
 	/**
 	 * Run semantic analysis after parsing and include semantic errors
 	 * (e.g. duplicate declarations, invalid `break`/`continue` targets)
@@ -76,14 +83,9 @@ interface ParseResult {
 }
 
 /**
- * Parse JS/TS source code synchronously on the current thread.
- */
-export function parseSync(source: string, options?: ParseOptions): ParseResult;
-
-/**
- * Parse JS/TS source code asynchronously on a background thread.
+ * Parse JS/TS source code and return an ESTree / TypeScript-ESTree compatible AST.
  */
-export function parse(source: string, options?: ParseOptions): Promise<ParseResult>;
+export function parse(source: string, options?: ParseOptions): ParseResult;
 
 // AST node types
 
@@ -612,10 +614,15 @@ interface Program extends BaseNode {
 	hashbang: string | null;
 	body: Array<Statement | ModuleDeclaration>;
 }
+
 type Declaration = FunctionDeclaration | ClassDeclaration | VariableDeclaration | TSDeclareFunction;
+
 type Expression = Identifier | Literal | ThisExpression | Super | ArrayExpression | ObjectExpression | FunctionExpression | ArrowFunctionExpression | ClassExpression | TaggedTemplateExpression | TemplateLiteral | MemberExpression | CallExpression | NewExpression | ChainExpression | SequenceExpression | ParenthesizedExpression | BinaryExpression | LogicalExpression | ConditionalExpression | UnaryExpression | UpdateExpression | AssignmentExpression | YieldExpression | AwaitExpression | ImportExpression | MetaProperty | SpreadElement | TSEmptyBodyFunctionExpression | JSXElement | JSXFragment;
+
 type Statement = ExpressionStatement | BlockStatement | EmptyStatement | DebuggerStatement | ReturnStatement | LabeledStatement | BreakStatement | ContinueStatement | IfStatement | SwitchStatement | ThrowStatement | TryStatement | WhileStatement | DoWhileStatement | ForStatement | ForInStatement | ForOfStatement | WithStatement | Declaration;
+
 type ModuleDeclaration = ImportDeclaration | ExportNamedDeclaration | ExportDefaultDeclaration | ExportAllDeclaration | TSExportAssignment | TSNamespaceExportDeclaration;
+
 type Node = Program | Statement | Expression | ModuleDeclaration | Property | PrivateIdentifier | TemplateElement | VariableDeclarator | CatchClause | SwitchCase | RestElement | ArrayPattern | ObjectPattern | AssignmentPattern | ClassBody | MethodDefinition | PropertyDefinition | AccessorProperty | StaticBlock | Decorator | ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier | ImportAttribute | ExportSpecifier | JSXOpeningElement | JSXClosingElement | JSXOpeningFragment | JSXClosingFragment | JSXIdentifier | JSXNamespacedName | JSXMemberExpression | JSXAttribute | JSXSpreadAttribute | JSXExpressionContainer | JSXEmptyExpression | JSXText | JSXSpreadChild;
 
 export type { ParseOptions, ParseResult, Comment, Diagnostic, DiagnosticLabel, SourceType, SourceLang, BaseNode, Program, Statement, Expression, Declaration, ModuleDeclaration, Node, Identifier, PrivateIdentifier, Literal, StringLiteral, NumericLiteral, BigIntLiteral, BooleanLiteral, NullLiteral, RegExpLiteral, BindingPattern, FunctionParameter, Property, ArrayPattern, ObjectPattern, AssignmentPattern, RestElement, SequenceExpression, ParenthesizedExpression, BinaryExpression, LogicalExpression, ConditionalExpression, UnaryExpression, UpdateExpression, AssignmentExpression, YieldExpression, AwaitExpression, ArrayExpression, ObjectExpression, SpreadElement, MemberExpression, CallExpression, ChainExpression, TaggedTemplateExpression, NewExpression, MetaProperty, ImportExpression, TemplateLiteral, TemplateElement, Super, ThisExpression, ExpressionStatement, BlockStatement, IfStatement, SwitchStatement, SwitchCase, ForStatement, ForInStatement, ForOfStatement, WhileStatement, DoWhileStatement, BreakStatement, ContinueStatement, LabeledStatement, WithStatement, ReturnStatement, ThrowStatement, TryStatement, CatchClause, DebuggerStatement, EmptyStatement, VariableDeclaration, VariableDeclarator, FunctionDeclaration, FunctionExpression, TSDeclareFunction, TSEmptyBodyFunctionExpression, ArrowFunctionExpression, ClassDeclaration, ClassExpression, ClassBody, MethodDefinition, PropertyDefinition, AccessorProperty, StaticBlock, Decorator, ClassElement, ImportDeclaration, ImportSpecifier, ImportDefaultSpecifier, ImportNamespaceSpecifier, ImportAttribute, ExportNamedDeclaration, ExportDefaultDeclaration, ExportAllDeclaration, ExportSpecifier, TSExportAssignment, TSNamespaceExportDeclaration, JSXElement, JSXOpeningElement, JSXClosingElement, JSXFragment, JSXOpeningFragment, JSXClosingFragment, JSXIdentifier, JSXNamespacedName, JSXMemberExpression, JSXAttribute, JSXSpreadAttribute, JSXExpressionContainer, JSXEmptyExpression, JSXText, JSXSpreadChild, JSXTagName, JSXChild, BinaryOperator, LogicalOperator, UnaryOperator, UpdateOperator, AssignmentOperator, FunctionNodeBase, ClassNodeBase };

package/index.js

@@ -1,12 +1,7 @@
 import binding from './binding.js';
 import { decode } from './decode.js';
 
-export function parseSync(source, options) {
+export function parse(source, options) {
   const buffer = binding.parseSync(source, options ?? {});
   return decode(buffer, source);
 }
-
-export async function parse(source, options) {
-  const buffer = await binding.parse(source, options ?? {});
-  return decode(buffer, source);
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuku-parser",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "High-performance JavaScript/TypeScript parser",
   "repository": {
     "type": "git",
@@ -17,16 +17,16 @@
     "decode.js"
   ],
   "optionalDependencies": {
-    "@yuku-parser/binding-linux-x64-gnu": "0.4.0",
-    "@yuku-parser/binding-linux-arm64-gnu": "0.4.0",
-    "@yuku-parser/binding-linux-arm-gnu": "0.4.0",
-    "@yuku-parser/binding-linux-x64-musl": "0.4.0",
-    "@yuku-parser/binding-linux-arm64-musl": "0.4.0",
-    "@yuku-parser/binding-linux-arm-musl": "0.4.0",
-    "@yuku-parser/binding-darwin-x64": "0.4.0",
-    "@yuku-parser/binding-darwin-arm64": "0.4.0",
-    "@yuku-parser/binding-win32-x64": "0.4.0",
-    "@yuku-parser/binding-win32-arm64": "0.4.0",
-    "@yuku-parser/binding-freebsd-x64": "0.4.0"
+    "@yuku-parser/binding-linux-x64-gnu": "0.4.2",
+    "@yuku-parser/binding-linux-arm64-gnu": "0.4.2",
+    "@yuku-parser/binding-linux-arm-gnu": "0.4.2",
+    "@yuku-parser/binding-linux-x64-musl": "0.4.2",
+    "@yuku-parser/binding-linux-arm64-musl": "0.4.2",
+    "@yuku-parser/binding-linux-arm-musl": "0.4.2",
+    "@yuku-parser/binding-darwin-x64": "0.4.2",
+    "@yuku-parser/binding-darwin-arm64": "0.4.2",
+    "@yuku-parser/binding-win32-x64": "0.4.2",
+    "@yuku-parser/binding-win32-arm64": "0.4.2",
+    "@yuku-parser/binding-freebsd-x64": "0.4.2"
   }
 }