{"_id":"@cristianmartinez/yexp","name":"@cristianmartinez/yexp","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@cristianmartinez/yexp","version":"0.0.1","description":"Fast, portable JSON expression language with bytecode compilation","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"sideEffects":false,"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"scripts":{"build":"tsc --project tsconfig.build.json","prepublishOnly":"bun run build && bun test","test":"bun test","lint":"biome check src/ tests/","check":"tsc --noEmit --project tsconfig.build.json"},"keywords":["yexp","expression","json","query","bytecode","compiler","ast","safe","portable"],"author":{"name":"Cristian Martinez","email":"dev.cmartinez@gmail.com"},"license":"MIT","engines":{"node":">=18"},"repository":{"type":"git","url":"git+https://github.com/cristianmartinez/yexp.git","directory":"packages/core"},"homepage":"https://github.com/cristianmartinez/yexp#readme","bugs":{"url":"https://github.com/cristianmartinez/yexp/issues"},"devDependencies":{"bun-types":"^1.3.8"},"gitHead":"6a124be38002b463fb6bd6a4767255a0413978c0","_id":"@cristianmartinez/yexp@0.0.1","_nodeVersion":"24.17.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-r1YIWrQoWmq+Rh44tRQj/ItLL6fDtS1L8NvAJh0CcueghT//0zAwISce/GQDYmFiq2qHKzQap70O31Wq6IjKSg==","shasum":"a8a670a6cdaa087338d28377cb005fbb52e716a9","tarball":"https://registry.npmjs.org/@cristianmartinez/yexp/-/yexp-0.0.1.tgz","fileCount":26,"unpackedSize":296676,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAafgJcZ7gntoOunzzY+fjSAMOrNIxbQPLx+qhqgpabuAiEApNOARTIvfKOX8m1KOb8YMOs+RxDahof4YF6WmSzrqtQ="}]},"_npmUser":{"name":"cristianmartinez","email":"dev.cmartinez@gmail.com"},"directories":{},"maintainers":[{"name":"cristianmartinez","email":"dev.cmartinez@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/yexp_0.0.1_1783729616596_0.5007962366605228"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-11T00:26:56.355Z","0.0.1":"2026-07-11T00:26:56.732Z","modified":"2026-07-11T00:26:56.960Z"},"maintainers":[{"name":"cristianmartinez","email":"dev.cmartinez@gmail.com"}],"description":"Fast, portable JSON expression language with bytecode compilation","homepage":"https://github.com/cristianmartinez/yexp#readme","keywords":["yexp","expression","json","query","bytecode","compiler","ast","safe","portable"],"repository":{"type":"git","url":"git+https://github.com/cristianmartinez/yexp.git","directory":"packages/core"},"author":{"name":"Cristian Martinez","email":"dev.cmartinez@gmail.com"},"bugs":{"url":"https://github.com/cristianmartinez/yexp/issues"},"license":"MIT","readme":"# yexp\n\nA portable expression language that compiles JavaScript-like syntax to bytecode and evaluates it without `eval()` or generated JavaScript.\n\n## Install\n\n```bash\nnpm install @cristianmartinez/yexp\n```\n\n## Use\n\n```ts\nimport { compile, evaluate } from '@cristianmartinez/yexp';\n\nconst program = compile('$.price * $.quantity');\nconst result = evaluate(program, { price: 12, quantity: 3 });\n\nconsole.log(result); // 36\n```\n\nCompile once and reuse the program with different inputs:\n\n```ts\nconst isAdult = compile('$.age >= 18');\n\nevaluate(isAdult, { age: 21 }); // true\nevaluate(isAdult, { age: 16 }); // false\n```\n\nAuxiliary context and environment values are explicit:\n\n```ts\nconst program = compile('$.ownerId == $context.userId && $env.region == \"eu\"');\n\nevaluate(program, { ownerId: 'user_1' }, {\n  context: { userId: 'user_1' },\n  env: { region: 'eu' },\n}); // true\n```\n\n## Language\n\nYexp supports:\n\n- Arithmetic, comparisons, logical operators, null coalescing, and ternaries\n- Object, array, string, and template literals\n- Property access, optional chaining, wildcards, and recursive descent\n- Pipes and method-call syntax\n- Lambdas and collection operations such as `map`, `filter`, and `reduce`\n- A fixed registry of built-in operations\n- Host-provided functions through evaluation options\n\nEquality never coerces operand types: `1 == \"1\"` is `false`.\n\n## Compilation pipeline\n\n```ts\nimport { compile, compileAst, parse, tokenize } from '@cristianmartinez/yexp';\n\nconst tokens = tokenize('$.items |> length');\nconst ast = parse(tokens);\nconst program = compileAst(ast);\n\n// Equivalent convenience API:\nconst sameProgram = compile('$.items |> length');\n```\n\nCompiled programs contain a bytecode version, slots, constants, and instructions. They are JSON-serializable, but applications should treat them as derived artifacts and regenerate them when the bytecode version changes.\n\n## Debug execution\n\n```ts\nconst program = compile('$.price * 2');\n\nevaluate(program, { price: 10 }, {\n  onStep: ({ ip, stack }) => {\n    console.log(ip, stack);\n  },\n});\n```\n\n## Security boundary\n\nThe default runtime does not expose JavaScript globals, Node.js APIs, the filesystem, `eval()`, or `Function()`.\n\nYexp is not yet a complete untrusted-code resource sandbox. Some operations can consume significant CPU or memory, and time-dependent or random built-ins are not deterministic. Apply application-level input limits and execution isolation when evaluating expressions supplied by untrusted users. Host functions extend the runtime's authority and must be reviewed as part of the host application's security model.\n\nSee the repository's [security documentation](https://github.com/cristianmartinez/yexp/blob/main/docs/security.md) for the current threat model.\n\n## API\n\n- `compile(source)` parses and compiles source text.\n- `compileAst(ast)` compiles an existing AST.\n- `evaluate(program, input, options?)` evaluates bytecode.\n- `run(source, context)` provides the legacy state/data context entry point while the public context model is being consolidated.\n- `tokenize(source)` and `parse(tokens)` expose the lower-level frontend.\n\n## CLI\n\nInstall [`@cristianmartinez/yexp-cli`](https://www.npmjs.com/package/@cristianmartinez/yexp-cli) for the `yexp` command.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-9954a967ed749c82627dcb1e7972d258"}