{"id":13672845,"url":"https://github.com/kataw/kataw","last_synced_at":"2025-04-28T04:30:29.256Z","repository":{"id":42670009,"uuid":"330411805","full_name":"kataw/kataw","owner":"kataw","description":"An 100% spec compliant ES2022 JavaScript toolchain","archived":false,"fork":false,"pushed_at":"2023-03-05T19:31:00.000Z","size":234403,"stargazers_count":334,"open_issues_count":15,"forks_count":6,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-22T08:25:39.644Z","etag":null,"topics":["acorn","ast","ast-nodes","babel","cst","cst-parser","diagnostics","ecma","ecmascript","error-recovery","estree","parsing","performance","recovery-mode","typescript","walker"],"latest_commit_sha":null,"homepage":"https://kataw.github.io/kataw/kataw_ast/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kataw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null},"funding":{"open_collective":"kataw"}},"created_at":"2021-01-17T14:38:34.000Z","updated_at":"2025-04-15T11:30:51.000Z","dependencies_parsed_at":"2023-02-01T01:31:21.044Z","dependency_job_id":null,"html_url":"https://github.com/kataw/kataw","commit_stats":{"total_commits":778,"total_committers":3,"mean_commits":259.3333333333333,"dds":"0.10925449871465298","last_synced_commit":"d01f961ef84a9a2a1bdb176aed3062f3649edcde"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataw%2Fkataw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataw%2Fkataw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataw%2Fkataw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kataw%2Fkataw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kataw","download_url":"https://codeload.github.com/kataw/kataw/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251031512,"owners_count":21525666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acorn","ast","ast-nodes","babel","cst","cst-parser","diagnostics","ecma","ecmascript","error-recovery","estree","parsing","performance","recovery-mode","typescript","walker"],"created_at":"2024-08-02T09:01:51.531Z","updated_at":"2025-04-28T04:30:29.230Z","avatar_url":"https://github.com/kataw.png","language":"TypeScript","funding_links":["https://opencollective.com/kataw"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eKataw\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e An insane fast Javascript toolchain.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://www.npmjs.com/package/kataw\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/kataw.svg?style=flat-square\" alt=\"Kataw NPM\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://lgtm.com/projects/g/kataw/kataw/context:javascript\"\u003e\u003cimg src=\"https://img.shields.io/lgtm/grade/javascript/g/kataw/kataw.svg?logo=lgtm\u0026logoWidth=18\" alt=\"GitHub license\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/kataw/kataw\"\u003e\u003cimg src=\"https://img.shields.io/badge/code_style-kataw-ff69b4.svg?style=flat-square\" alt=\"Meriyah NPM\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\n**WIP**\n\nKataw is a JavaScript toolchain that aim to unify functionality that has previously been separate tools. It features everything from low-level CST manipulation\nto tools like linting, code analyzes, transform, and minification.\n\n\u003c!-- vscode-markdown-toc --\u003e\n* [CST nodes](#CSTnodes)\n* [CST keywords](#CSTkeywords)\n* [ESNext](#ESNext)\n* [Diagnostics](#Diagnostics)\n \t* [Diagnostic arguments](#DiagnosticArgs)\n* [Printing](#CSTprinting)\n \t* [Ignore comment](#Ignorecomment)\n* [Linting](#Linting)\n* [Transformation](#Transformation)\n* [Types](#Types)\n* [Comments](#Comments)\n* [CST parser features](#CSTparserfeatures)\n* [Current state](#Currentstate)\n* [Roadmap](#Roadmap)\n\t* [📌v0.1](#v0.1)\n\t* [v0.2](#v0.2)\n\t* [v0.3](#v0.3)\n\t* [v1.0](#v1.0)\n* [Future](#Future)\n\n\u003c!-- vscode-markdown-toc-config\n\tnumbering=false\n\tautoSave=true\n\t/vscode-markdown-toc-config --\u003e\n\u003c!-- /vscode-markdown-toc --\u003e\n\nThe toolchain's core is based upon a ECMAScript friendly CST that allows you to parse `ECMAScript® 2022 (ECMA-262 12th Edition) language specification`.\n\nIf the only goal is to perform syntactic analysis (parsing) of a Javascript program, you can do this with either `kataw.parseModule` or `kataw.parseScript`.\n\n\u003e Noted that with `ES2015` and later a Javascript program can be either a [script or a module](https://tc39.es/ecma262/index.html#sec-ecmascript-language-scripts-and-modules).\n\nHere is an example on how to set up `Kataw` to act like for example `Acorn`:\n\n```ts\n // Parse with module goal\n kataw.parseModule('x = y', { next: true }, function(source, kind, msg, line, column) {\n    throw msg + '(' + line + ', ' + column + ')';\n });\n\n // Parse in script mode\n kataw.parseScript('x = y', { next: true }, function(source, kind, msg, line, column) {\n    throw msg + '(' + line + ', ' + column + ')';\n });\n```\n\nThe returned CST tree can now be used as an AST.\n\n\u003e Note that the CST contains more information that can be extracted from the CST node's through\n[public API methods](https://github.com/kataw/kataw/tree/main/src/parser#public-api-methods-to-extract-info-from-cst-nodes).\n\nMany of these APIs have the advantage that they allow you to \"retrieve\" info that is not otherwise available with a standard AST parser.\n\nOne example is that you only need to use `kataw.isStatementNode` to find out if the current CST node is a statement node. With an AST parser you must use\na `switch statement` with 60 `switch cases`.\n\n\n```ts\n // With Babel you are forced to do\n switch(node.type) {\n   case 'SwitchStatement': ...\n   case 'ReturnStatement': ...\n }\n\n // With Kataw\n kataw.isStatementNode(node); // return 'true'\n```\n\nA second benefit with this CST parser is that it is running in `recovery mode` by `default` and can be used in any editor. A build-in diagnostic system reports diagnostics if an `error handler` have been used. The diagnostics are dynamic. It means all the diagnostics are informative, and they will change based on the context you\nare parsing in.\n\nThese features used together gives you more options to adjust, modify and customize the CST tree compared to a regular AST parser and you can also write fewer\ncode lines and at the same time experience insane performance.\n\n## \u003ca name='CSTnodes'\u003e\u003c/a\u003eCST nodes\n\nAll CST nodes has a `kind` which is a number that represents the node type. It's identical to `ESTree` type with the exception that Kataw doesn't do any\nstring comparisons - everything in Kataw is a number.\n\nHere is an example:\n\n```ts\nif (node.kind === Kataw.SyntaxKind.Identifier) {}\n```\n\nYou need to use `kataw.visitEachChild` to traverse the CST tree to get access to each CST node. After that you do any kind of transformation.\n\nBe aware that also the  `kind` contain some additional information that you can extract through the public API - not only the `NodeFlags`.\n\nFor example `Kataw.isKeyword`, `Kataw.isIdentifier`, and `Kataw.isFutureReserved`.\n\nThis is made possible because there are no `token` in Kataw. Everything is\na `SyntaxKind` - `token` and `kind` merged into one.\n\nKataw also exports all CST nodes so you can create your own nodes. This is handy if you want to try out new `ECMA` features that isn't part of the language yet, or make your own transformers as in `Babel`.\n\nHere is an example on how to create an CST node:\n\n```ts\n // creates an identifier\n kataw.createIdentifier(/* text */ 'hello', /* rawText */ 'hello', /* start */ 1,  /* end */ 5)\n```\n\nSome CST nodes needes additional info. This can be set using the `Kataw.NodeFlags` andt this bitwise mask can be set on every CST node and CST keyword node.\n\n```ts\n // creates an string literal\n const str = kataw.createStringLiteral(\n    /* text */ 'hello', /* rawText */ 'hello', /* start */ 1,  /* end */ 5\n);\n\n // set the flag and mark it as a single quote. E.g. 'string'\n str.flag |= Kataw.NodeFlags.SingleQuote.\n\n // Check if the flag is set\n kataw.isSingleQuote(str); // true\n```\n\n## \u003ca name='CSTkeywords'\u003e\u003c/a\u003eCST keywords\n\nAll keywords in Kataw is it's own CST node, and you create them in almost the same way as any other CST nodes.\n\n```ts\nkataw.createToken(kataw.SyntaxKind.ForKeyword, Kataw.NodeFlags.NoChildren, /* start */ 1,  /* end */ 5);\n```\n\n## \u003ca name='Diagnostics'\u003e\u003c/a\u003eDiagnostics\n\nDiagnostics in Kataw can either be `error`, `warning` or `lint failure`.\n\nThe diagnostics have been designed like this so you can quickly understand what the problem is and correct it.\n\nAdding a error handler as the 3rd argument will enable diagnostics. The diagnostics are flexible and let you\nuse them together with Kataw's own reporters or you can create your own reporter or whatever is your use case.\n\nHere is how it works:\n\n```ts\nimport { parseScript } from 'kataw';\n\nparseScript('[x', { next: true }, function(diagnosticSource, kind, message, start, end) {\n});\n```\n\n### \u003ca name='DiagnosticArgs'\u003e\u003c/a\u003eDiagnostic arguments\n\n| Param        |   Description |\n| ----------- |------------------------------------------------- |\n| `diagnosticSource`  | Is either `Lexer` or `Printer`. |\n| `kind`    | Is either `lint`, `error`, `warning` |\n| `message`    | The diagnostic message |\n| `start`    | The start position of the diagnostics |\n| `end`    | The end position of the diagnostics |\n\n\n## \u003ca name='ESNext'\u003e\u003c/a\u003eESNext\n\n`Stage 3` proposals can be parsed if the `next` options are enabled.\n\n`Stage 1` and `stage 2` proposals are not supported because the specs drafts are changing all the time.\n\n\n## \u003ca name='Types'\u003e\u003c/a\u003eTypes\n\nKataw has it's own type system that is an improvement over `Typescript` and `Flow`, and it\nconform to the `ECMAScript® 2022 (ECMA-262 12th Edition) language specification`.\n\nAs everything else - it's developed for high performance and it consumes less memory.\n\nIt allows you to parse syntax like `function x(y: string, z: number): string | number {}` and other\nsimiliar syntax.\n\nThe type system is still `WIP` and will be enabled by default in the `CLI` together with\nKataw's own type checker.\n\nYou can manually enable this if you enable the `allowTypes` option. It will then parse the types but it\nwill not do any type checking.\n\nYou can use `kataw.removeKatawTypes` to remove Kataw's types from the CST tree\n\n\n```ts\nconst source = kataw.parseModule('let: string', { allowTypes: true});\n// Remove the types\nkataw.removeKatawTypes(source);\n```\n\n## \u003ca name='Comments'\u003e\u003c/a\u003eComments\n\nLeading and trailing comments can be extracted at correct position with `kataw.getLeadingComments` and `kataw.getTrailingComments`.\n\n```ts\nHello\n/* I'm a comment */\n  there!\n```\n\nGetting the trailing comment of `Hello` can be done like this `kataw.getTrailingComments(5, 24).` It get the comments from the end value of\n`hello` until the start value of `there!`.\n\nIf you want a `1:1` copy of the actual source code, you can do a \"*slice*\" from the start value of `Hello` to the end value of `there!`.\n\n## \u003ca name='Linting'\u003e\u003c/a\u003eLinting\n\nRules still being added, but Kataw can go linting either through public API methods or options. Most of ESLint common or recommended rules\nalso works for Kataw and you can either enable or disable them.\n\n### Linting with public API\n\nIt can be done like this\n\n```ts\nimport { lintScript } from 'kataw';\n\nlintScript('eval()', { reporter: aladdin }, { noEval: true});\n```\n\n### Linting with parser options\n\n```ts\nimport { parseScript } from 'kataw';\n\nparseScript('eval()', { noEval: true});\n```\nThe `DiagnosticKind` will be set to `DiagnosticKind.Lint` and you can chose to ignore this and treat the diagnostic as any other error, or\nfor example create your own reporter.\n\n\n## \u003ca name='Transformation'\u003e\u003c/a\u003eTransformation\n\n`Kataw` can act the same way as`Babel` and be a tool that helps you write code in the latest version of Javascript. This can be done with\ndeveloping transformers to handle situations where your supported environments don't support certain features natively.\n\nThe compiler transform those features down to a supported version.\n\nYou have to use `kataw.visitEachChild` to traverse the CST tree. `kataw.visitNode`can be used to traverse a single node, and\n`kataw.visitNodes` to visit an array of CST nodes. This API method should only be used on *lists*. CST nodes that is *known*\nto contain an array. There are no need to use for example `Array.Array` to verify if it's an array.\nPerformance is maintained that way.\n\nAll CST nodes will be updated automatically if any changes has been detected.\n\nKeywords can also be swapped around and the same with `AssignmentExpression`, `BinaryExpression`, `UnaryExpression` and\n`UpdateExpression` operands. For example `!==` can be changed to `===`.\n\nA `WithStatement` can be transformed into a `WhileStatement` simply by changing the value of the `TokenNode`.\n\nThe location of the CST node in the CST tree can also be changed if you change the values of `start` and `end` on the CST node.\n\nChanging the `NodeFlags` allow you to change how the CST node should behave.\n\nAll this things gives a you better control over transformation of each CST node compared to `Babel` and `Rome`.\n\nHere is an example on an simple transformer that will replace all identifiers with an `NumericLiteral`.\n\n```ts\nexport function swapIdentifierWithNumeric(transform) {\n  return transformSourceFile;\n\n  function transformSourceFile(root) {\n    switch (node.kind) {\n      case kataw.NodeKind.Identifier:\n        return kataw.createNumericLiteral(\n          123,\n          \"123\",\n          kataw.NodeFlags.ExpressionNode | kataw.NodeFlags.NoChildren,\n          /* start */ 1,\n          /* end */ 3\n        );\n      default:\n        return kataw.visitEachChild(transform, root, visitor);\n    }\n  }\n\n  function visitor() {\n    switch (node.kind) {\n      default:\n        return kataw.visitEachChild(transform, node, visitor);\n    }\n  }\n}\n\n```\n\n## \u003ca name='CSTprinting'\u003e\u003c/a\u003ePrinting\n\nKataw is adjustable and allows three different ways to print your source code.\n\nThe returned source does not include any extra parenthesis or unnecessary code.\n\nThe comments are 100% correct and they will be printed in the places you expect.\n\n\n| API        |   Description |\n| ----------- |------------------------------------------------- |\n| `print`  |   Prints *a given* CST tree and let you adjust the diagnostics and set your own parser options |\n| `printModule`    | Prints the source in module goal |\n| `printScript`    | Prints the source in script mode |\n\nHere is an example:\n\n```ts\n\n// Print\n kataw.print(kataw.parseModule('x = y', { next: true }, function(source, kind, msg, line, column) {\n    throw msg + '(' + line + ', ' + column + ')';\n }));\n\n // Print with module goal\n kataw.printModule('x = y');\n\n // Print in script mode\n kataw.printScript('x = y');\n```\n\n### \u003ca name='Ignorecomment'\u003e\u003c/a\u003eIgnore comment\n\nStatements, blocks and other code lines can be ignored in Kataw with a `// kataw-ignore` comment.\n\nIf set on a `WhileStatement` it will ignore the entire statement and the `BlockStatement`.\n\n```ts\n// kataw-ignore\nwhile (true) {}\n```\n\nYou can use `kataw.shouldIgnoreNextNode(node);` to verify if the node should be ignored.\n\n\n## CST parser features\n\n- Error recovery by default (_like Acorn loose_), but it reconstruct the CST tree correctly\n\n- Optional error reporting (_require a callback as the parsers 3rd argument_)\n\n- Dynamic error, hint and warning diagnostics (_depends on the context you are parsing in_)\n\n- Public API methods to extract info from the CST nodes\n\n- 100% correct comment extraction and attachment algorithm\n\n- Can parse types and type annotations (_Kataw has it's own type system_)\n\n- Can be used in any editors\n\n- Scalable\n\n- Performance\n\n## \u003ca name='Currentstate'\u003e\u003c/a\u003eCurrent state\n\n- The CST parser can be used in production\n\n## \u003ca name='Roadmap'\u003e\u003c/a\u003eRoadmap\n\n### \u003ca name='v0.1'\u003e\u003c/a\u003e📌v0.1\n- [x] Parsing ECMA 262(aka JavaScript), and the cst spec be stable\n- [x] Test 262 passes\n- [x] Printing API (like prettier API)\n- [ ] //kataw-ignore(like //prettier-ignore)\n- [ ] Command line interface (like prettier cli)\n- [ ] Documentation \u0026 website\n\n### \u003ca name='v0.2'\u003e\u003c/a\u003ev0.2\n- [ ] plugin system, to make it possible to support jsx/ts/flow...\n- [ ] jsx plugin\n- [ ] ts plugin\n\n### \u003ca name='v0.3'\u003e\u003c/a\u003ev0.3\n- [ ] transformers: like babel\n- [ ] minify: like uglify-js\n- [ ] linter: like eslint\n\n### \u003ca name='v1.0'\u003e\u003c/a\u003ev1.0\n\n\n## \u003ca name='Future'\u003e\u003c/a\u003eFuture\n\n- A \"hook system\" for adding additional rules for the linter and the grammar checker will be published.\n\n- Hooks to support experimental syntax and ECMA proposals in an sandboxed envirnonment\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkataw%2Fkataw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkataw%2Fkataw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkataw%2Fkataw/lists"}