bonsai-js 0.1.0

package/dist/types-Cbouo-QC.d.mts

@@ -0,0 +1,244 @@
+//#region src/types.d.ts
+type BinaryOperator = '||' | '&&' | '==' | '!=' | '<' | '>' | '<=' | '>=' | '+' | '-' | '*' | '/' | '%' | '**' | 'in' | 'not';
+type UnaryOperator = '!' | '-' | '+';
+type BinaryExpressionOperator = Exclude<BinaryOperator, 'not'> | 'not in' | '??';
+type OperatorValue = BinaryOperator | UnaryOperator;
+type PunctuationValue = '(' | ')' | '[' | ']' | '{' | '}' | ',' | '.' | ':' | '?';
+interface BaseToken {
+  start: number;
+  end: number;
+}
+type Token = {
+  type: 'Number';
+  value: string;
+} & BaseToken | {
+  type: 'String';
+  value: string;
+} & BaseToken | {
+  type: 'TemplateLiteral';
+  value: string;
+} & BaseToken | {
+  type: 'Boolean';
+  value: 'true' | 'false';
+} & BaseToken | {
+  type: 'Null';
+  value: 'null';
+} & BaseToken | {
+  type: 'Undefined';
+  value: 'undefined';
+} & BaseToken | {
+  type: 'Identifier';
+  value: string;
+} & BaseToken | {
+  type: 'Operator';
+  value: OperatorValue;
+} & BaseToken | {
+  type: 'Punctuation';
+  value: PunctuationValue;
+} & BaseToken | {
+  type: 'Pipe';
+  value: '|>';
+} & BaseToken | {
+  type: 'OptionalChain';
+  value: '?.';
+} & BaseToken | {
+  type: 'NullishCoalescing';
+  value: '??';
+} & BaseToken | {
+  type: 'Spread';
+  value: '...';
+} & BaseToken | {
+  type: 'EOF';
+  value: '';
+} & BaseToken;
+type TokenType = Token['type'];
+interface BaseNode {
+  start: number;
+  end: number;
+}
+interface NumberLiteral extends BaseNode {
+  type: 'NumberLiteral';
+  value: number;
+}
+interface StringLiteral extends BaseNode {
+  type: 'StringLiteral';
+  value: string;
+}
+interface BooleanLiteral extends BaseNode {
+  type: 'BooleanLiteral';
+  value: boolean;
+}
+interface NullLiteral extends BaseNode {
+  type: 'NullLiteral';
+  value: null;
+}
+interface UndefinedLiteral extends BaseNode {
+  type: 'UndefinedLiteral';
+  value: undefined;
+}
+interface Identifier extends BaseNode {
+  type: 'Identifier';
+  name: string;
+}
+interface BinaryExpression extends BaseNode {
+  type: 'BinaryExpression';
+  operator: BinaryExpressionOperator;
+  left: ASTNode;
+  right: ASTNode;
+}
+interface UnaryExpression extends BaseNode {
+  type: 'UnaryExpression';
+  operator: UnaryOperator;
+  operand: ASTNode;
+}
+interface ConditionalExpression extends BaseNode {
+  type: 'ConditionalExpression';
+  test: ASTNode;
+  consequent: ASTNode;
+  alternate: ASTNode;
+}
+interface MemberExpression extends BaseNode {
+  type: 'MemberExpression';
+  object: ASTNode;
+  property: ASTNode;
+  computed: boolean;
+}
+interface OptionalMemberExpression extends BaseNode {
+  type: 'OptionalMemberExpression';
+  object: ASTNode;
+  property: ASTNode;
+  computed: boolean;
+}
+interface ArrayLiteral extends BaseNode {
+  type: 'ArrayLiteral';
+  readonly elements: readonly (ASTNode | SpreadElement)[];
+}
+interface ObjectLiteral extends BaseNode {
+  type: 'ObjectLiteral';
+  readonly properties: readonly ObjectProperty[];
+}
+interface ObjectProperty extends BaseNode {
+  type: 'ObjectProperty';
+  key: ASTNode;
+  value: ASTNode;
+  computed: boolean;
+}
+interface CallExpression extends BaseNode {
+  type: 'CallExpression';
+  callee: ASTNode;
+  readonly args: readonly ASTNode[];
+}
+interface PipeExpression extends BaseNode {
+  type: 'PipeExpression';
+  input: ASTNode;
+  transform: ASTNode;
+}
+interface TemplateLiteral extends BaseNode {
+  type: 'TemplateLiteral';
+  readonly parts: readonly (StringLiteral | ASTNode)[];
+}
+interface SpreadElement extends BaseNode {
+  type: 'SpreadElement';
+  argument: ASTNode;
+}
+interface LambdaAccessor extends BaseNode {
+  type: 'LambdaAccessor';
+  property: string;
+}
+interface LambdaExpression extends BaseNode {
+  type: 'LambdaExpression';
+  body: ASTNode;
+}
+type ASTNode = NumberLiteral | StringLiteral | BooleanLiteral | NullLiteral | UndefinedLiteral | Identifier | BinaryExpression | UnaryExpression | ConditionalExpression | MemberExpression | OptionalMemberExpression | ArrayLiteral | ObjectLiteral | CallExpression | PipeExpression | TemplateLiteral | SpreadElement | LambdaAccessor | LambdaExpression;
+/** Options for creating a Bonsai instance via {@link BonsaiInstance}. */
+interface BonsaiOptions {
+  /** Cooperative timeout in milliseconds. 0 (default) disables timeout checks. */
+  timeout?: number;
+  /** Maximum expression nesting depth. Default: 100. */
+  maxDepth?: number;
+  /** Maximum array literal or spread size. Default: 100,000. */
+  maxArrayLength?: number;
+  /** Allowlist of property/method names expressions can access. */
+  allowedProperties?: string[];
+  /** Denylist of property/method names expressions cannot access. */
+  deniedProperties?: string[];
+  /** LRU cache size for compiled expressions and parsed ASTs. Default: 256. */
+  cacheSize?: number;
+}
+/** A transform receives the piped value as its first argument: `value |> myTransform(arg)`. */
+type TransformFn = (value: unknown, ...args: unknown[]) => unknown | Promise<unknown>;
+/** A function is called directly by name: `myFunction(arg1, arg2)`. */
+type FunctionFn = (...args: unknown[]) => unknown | Promise<unknown>;
+/** A plugin receives the Bonsai instance and extends it with transforms or functions. */
+type BonsaiPlugin = (instance: BonsaiInstance) => void;
+/** Core Bonsai instance returned by `bonsai()`. */
+interface BonsaiInstance {
+  /** Register a plugin that extends this instance with transforms/functions. */
+  use(plugin: BonsaiPlugin): this;
+  /** Register a named transform for use with the pipe operator (`|>`). */
+  addTransform(name: string, fn: TransformFn): this;
+  /** Register a named function callable as `name(args)` in expressions. */
+  addFunction(name: string, fn: FunctionFn): this;
+  /** Remove a previously registered transform. Returns true if it existed. */
+  removeTransform(name: string): boolean;
+  /** Remove a previously registered function. Returns true if it existed. */
+  removeFunction(name: string): boolean;
+  /** Check whether a transform with the given name is registered. */
+  hasTransform(name: string): boolean;
+  /** Check whether a function with the given name is registered. */
+  hasFunction(name: string): boolean;
+  /** List all registered transform names. */
+  listTransforms(): string[];
+  /** List all registered function names. */
+  listFunctions(): string[];
+  /** Clear the compiled expression and AST caches. */
+  clearCache(): void;
+  /** Pre-compile an expression for repeated evaluation. */
+  compile(expression: string): CompiledExpression;
+  /** Evaluate an expression asynchronously. Required when transforms/functions are async. */
+  evaluate<T = unknown>(expression: string, context?: Record<string, unknown>): Promise<T>;
+  /** Evaluate an expression synchronously. Throws if a transform/function returns a Promise. */
+  evaluateSync<T = unknown>(expression: string, context?: Record<string, unknown>): T;
+  /** Check if an expression is syntactically valid without evaluating it. */
+  validate(expression: string): ValidationResult;
+}
+/** A pre-compiled expression that can be evaluated repeatedly with different contexts. */
+interface CompiledExpression {
+  /** Evaluate asynchronously. Required when transforms/functions are async. */
+  evaluate<T = unknown>(context?: Record<string, unknown>): Promise<T>;
+  /** Evaluate synchronously. Throws if a transform/function returns a Promise. */
+  evaluateSync<T = unknown>(context?: Record<string, unknown>): T;
+  /** The optimized AST after constant folding and dead branch elimination. */
+  readonly ast: ASTNode;
+  /** The original expression string. */
+  readonly source: string;
+}
+/** Identifiers, transforms, and functions referenced by a parsed expression. */
+interface ExpressionReferences {
+  identifiers: string[];
+  transforms: string[];
+  functions: string[];
+}
+/** Result of {@link BonsaiInstance.validate}. Discriminated on the `valid` field. */
+type ValidationResult = {
+  valid: true;
+  errors: [];
+  ast: ASTNode;
+  references: ExpressionReferences;
+} | {
+  valid: false;
+  errors: ValidationError[];
+};
+/** A syntax error with position information from {@link BonsaiInstance.validate}. */
+interface ValidationError {
+  message: string;
+  position: {
+    line: number;
+    column: number;
+  };
+  suggestion?: string;
+  formatted?: string;
+}
+//#endregion
+export { CompiledExpression as a, Token as c, ValidationResult as d, BonsaiPlugin as i, TokenType as l, BonsaiInstance as n, ExpressionReferences as o, BonsaiOptions as r, FunctionFn as s, ASTNode as t, TransformFn as u };
+//# sourceMappingURL=types-Cbouo-QC.d.mts.map

package/dist/types-Cbouo-QC.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-Cbouo-QC.d.mts","names":[],"sources":["../src/types.ts"],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "bonsai-js",
+  "version": "0.1.0",
+  "description": "A modern, high-performance expression evaluator for JavaScript",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./stdlib": {
+      "types": "./dist/stdlib/index.d.mts",
+      "import": "./dist/stdlib/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danfry1/bonsai-js"
+  },
+  "homepage": "https://github.com/danfry1/bonsai-js#readme",
+  "bugs": "https://github.com/danfry1/bonsai-js/issues",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bench": "vitest bench",
+    "bench:gate": "bun run scripts/perf-gate.ts",
+    "check:package": "bun run build && bun run scripts/check-package.ts",
+    "lint": "oxlint --deny-warnings src tests scripts",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "build:website": "bun website/build.ts",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run bench:gate && bun run check:package"
+  },
+  "keywords": ["expression", "evaluator", "parser", "safe", "sandbox", "template", "pipe", "transform", "formula", "dsl", "ast", "jexl", "compiler"],
+  "author": "Daniel Fry",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "jexl": "^2.3.0",
+    "oxlint": "^1.51.0",
+    "tsdown": "^0.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}