{"id":15297010,"url":"https://github.com/samthor/gumnut","last_synced_at":"2025-04-07T10:24:20.721Z","repository":{"id":42668103,"uuid":"90504749","full_name":"samthor/gumnut","owner":"samthor","description":"JS parser in Web Assembly / C","archived":false,"fork":false,"pushed_at":"2023-03-05T20:13:18.000Z","size":1277,"stargazers_count":167,"open_issues_count":4,"forks_count":7,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-31T01:32:15.159Z","etag":null,"topics":["c","javascript-parser","parser","wasm"],"latest_commit_sha":null,"homepage":"https://samthor.github.io/gumnut/src/harness/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samthor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-07T02:51:54.000Z","updated_at":"2025-03-29T03:36:59.000Z","dependencies_parsed_at":"2024-06-18T22:54:16.679Z","dependency_job_id":"5e2bdf2f-fc77-4f41-b29a-78d8039eb539","html_url":"https://github.com/samthor/gumnut","commit_stats":{"total_commits":148,"total_committers":2,"mean_commits":74.0,"dds":"0.027027027027026973","last_synced_commit":"fde93fcaa2b115e7bf67a2e92b4103711eff2e49"},"previous_names":["samthor/prsr"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fgumnut","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fgumnut/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fgumnut/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fgumnut/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samthor","download_url":"https://codeload.github.com/samthor/gumnut/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247632927,"owners_count":20970245,"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":["c","javascript-parser","parser","wasm"],"created_at":"2024-09-30T19:14:15.185Z","updated_at":"2025-04-07T10:24:20.699Z","avatar_url":"https://github.com/samthor.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Tests](https://github.com/samthor/gumnut/workflows/Tests/badge.svg)](https://github.com/samthor/gumnut/actions)\n\nA permissive JavaScript tokenizer and parser in C.\nSee a [demo syntax highlighter](https://samthor.github.io/gumnut/src/harness/).\n\nSupports ESM code only (i.e., `type=\"module\"`, which is implicitly strict).\nSupports all language features in the [draft specification](https://github.com/tc39/proposals/blob/master/finished-proposals.md) (as of January 2021).\n\nThis is compiled via Web Assembly to run on the web or inside Node without native bindings.\nIt's not reentrant, so you can't parse another file from within its callbacks.\nIt does not generate an AST (although does emit enough data to do so in JS), does not modify the input, and does not use `malloc` or `free`.\n\n## Usage\n\nImport and install via your favourite package manager.\nThis requires Node [v13.10.0](https://twitter.com/guybedford/status/1235306690901422080?lang=en) or higher.\n\nThe parser works by invoking callbacks on every token as well as open/close announcements for a 'stack', which roughly maps to something you might make an AST node out of.\n\n```js\nimport {buildHarness} from 'gumnut';\n\nconst harness = await buildHarness();  // WebAssembly instantiation is async\n\nconst buffer = new TextEncoder().encode('console.info(\"hello\");');\nconst memory = harness.prepare(buffer.length);\nmemory.set(buffer);\n\nharness.handle({\n  callback() {\n    const type = harness.token.type();\n    console.info('token', harness.token.type(), harness.token.string());\n  },\n  open(stackType) { /* open stack type, return false to skip contents */ },\n  close(stackType) { /* close stack type */ },\n});\n\nharness.run();\n```\n\nThis is fairly low-level and designed to be used by other tools.\n\n### Module Imports Rewriter\n\nThis provides a rewriter for unresolved ESM imports (i.e., those pointing to \"node_modules\"), which could be used as part of an [ESM dev server](https://npmjs.com/package/dhost).\nUsage:\n\n```js\nimport buildImportsRewriter from 'gumnut/imports';\nimport buildResolver from 'esm-resolve';\n\n// WebAssembly instantiation is async\nconst run = await buildImportsRewriter(buildResolver);\nrun('./source.js', (part) =\u003e process.stdout.write(part));\n```\n\nThis example uses [esm-resolve](https://npmjs.com/package/esm-resolve), which implements an ESM resolver in pure JS.\n\n## Coverage\n\nThis correctly parses all 'pass-explicit' tests from [test262-parser-tests](https://github.com/tc39/test262-parser-tests), _except_ those which rely on non-strict mode behavior (e.g., use variable names like `static` and `let`).\n\n## Note\n\nJavaScript has a single open-ended 'after-the-fact' ambiguity for keywords, as `async` is not always a keyword—even in strict mode.\nHere's an example:\n\n```js\n// this is a function call of a method named \"async\"\nasync(/* anything can go here */) {}\n\n// this is an async arrow function\nasync(/* anything can go here */) =\u003e {}\n\n// this calls the async method on foo, and is _not_ ambiguous\nfoo.async() {}\n```\n\nThis parser has to walk over code like this at most twice to resolve whether `async` is a keyword _before_ continuing.\nSee [arrow functions break JavaScript parsers](https://dev.to/samthor/arrow-functions-break-javascript-parsers-1ldp) for more details.\n\nIt also needs to walk over non-async functions at most twice—like `(a, b) =\u003e`—to correctly label the argument as either _creating_ new variables in scope, or just using them (like a function call or simple parens).\n\n## History\n\nSince engineers like to rewrite everything all the time, see [the 2020 branch](https://github.com/samthor/gumnut/tree/legacy-2020) of this code.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamthor%2Fgumnut","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamthor%2Fgumnut","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamthor%2Fgumnut/lists"}