bonsai-js 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-06-02
+
+### Added
+
+- **Context-aware functions** (`addContextFunction`): register functions that receive the evaluation context as their first parameter (typed `Readonly<TCtx>`, passed by reference), enabling auth/permission/personalization patterns without threading context through expression arguments. Pure and context-aware functions share a single namespace; `isContextFunction(name)` introspects the kind.
+- **Generic context typing** (`bonsai<TCtx>()`): the factory is now generic over context type, with end-to-end type safety through `evaluate`, `evaluateSync`, `compile`, and `addContextFunction`. Backward compatible: defaults to `Record<string, unknown>` when unspecified.
+- New exported types: `ContextFunctionFn`, generic `BonsaiPlugin<TCtx>`, generic `CompiledExpression<TCtx>`, generic `BonsaiInstance<TCtx>`.
+- Internal: pure and context-aware functions share one tagged registry, and the cached `Bindings` snapshot consolidates transforms and that registry into a single object passed to the evaluator.
+
+### Resolves
+
+- #33: context access from registered functions.
+
+### Credits
+
+- Thanks to @jaenyf for raising #33 and contributing PR #34.
+
+## [0.3.0] - 2026-03-21
+
+### Added
+
+- **Autocomplete API** (`bonsai-js/autocomplete`): cursor-aware expression completions with property, method, transform, function, and keyword suggestions
+- `getPolicy()` method on `BonsaiInstance` for reading security policy
+- `InferredTypeName`, `PolicySnapshot`, `ResolveResult` shared types
+- Tolerant tokenization for incomplete expressions with regex fallback
+- Type inference from sample context objects with array element type detection
+- Lambda-aware dot classification (lambda-start, lambda member-access, top-level member-access)
+- Security policy filtering in completions (respects allowedProperties/deniedProperties in all paths)
+- Optional chaining (`?.`) support in completions
+- Fuzzy matching with camelCase-aware scoring
+- `onError` callback for debugging autocomplete failures
+- `transformTypes` option to skip auto-probing for performance
+- Eval-based type inference for method chains (e.g., `user.name.trim().`)
+- Nested lambda element inference (e.g., `groups.map(.users.filter(.`)
+- Pre-computed method completion cache for fast method suggestions
+- Autocomplete benchmarks (`benchmarks/autocomplete.bench.ts`)
+
+### Changed
+
+- **Performance**: core `evaluateSync` 1.4–2.4x faster (LRU cache fast path, pooled ExecutionContext, leaf node fast path)
+- **Performance**: autocomplete method completions 3–4x faster via pre-computed completion objects
+- LRU cache uses `lastKey` tracking to skip reordering on repeated hits
+- `ExecutionContext` reusable via `reset()` — avoids per-call allocation in `evaluateSync`
+- Leaf AST nodes (literals, identifiers) skip depth tracking overhead in both sync and async evaluators
+
+### Security
+
+- Transform names validated as safe identifiers before `evaluateSync` interpolation
+- `resolvePropertyChain` enforces `allowedProperties`/`deniedProperties` policy at every chain step
+- `BLOCKED_NAMES` unified with `BLOCKED_PROPERTIES` from execution context (single source of truth)
+- Catch blocks use `isExpectedError()` checking all 4 Bonsai error types — unexpected errors surface via `onError`
+- Top-level `complete()` catches unexpected errors and returns `[]` (never crashes host)
+
 ## [0.2.1] - 2026-03-16
 
 ### Added
@@ -22,11 +77,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Bare dot identity lambda:** `. > 2` and `. * 10` now work as lambda shorthand for the current item itself, in both method calls and pipe transforms (e.g., `[1,2,3,4].filter(. > 2)`, `[1,2,3] |> map(. * 10)`)
 - Async-safe evaluation for all higher-order array methods — lambda predicates that return Promises are correctly resolved in both top-level and nested contexts via `evaluate()`
 - Documentation for array methods, lambda shorthand, and method chaining in README and website docs
-
-## [Unreleased]
-
-### Added
-
 - Deterministic property-based parser and evaluator invariant tests
 - Random fuzz coverage for malformed parser input
 - Adversarial regression tests for deep nesting, oversized arrays, nested blocked keys, and spread misuse

package/README.md

@@ -125,6 +125,58 @@ expr.addFunction('lookupTier', async (userId) => {
 await expr.evaluate('lookupTier(userId) == "pro"', { userId: 'u_123' })
 ```
 
+### Context-aware functions
+
+Register functions that read the evaluation context directly. The function
+receives the evaluation context as its first parameter (typed read-only), so
+you can keep expressions terse and let the function pull what it needs:
+
+```ts
+import { bonsai } from 'bonsai-js'
+
+interface AppContext {
+  currentUserId: string
+  perms: readonly string[]
+}
+
+const app = bonsai<AppContext>()
+
+app.addContextFunction('lookupCurrentUserTier', async (ctx) => {
+  const row = await db.users.findById(ctx.currentUserId)
+  return row?.tier ?? 'free'
+})
+
+app.addContextFunction('hasPermission', (ctx, action) =>
+  ctx.perms.includes(String(action)))
+
+await app.evaluate(
+  'lookupCurrentUserTier() == "pro" && hasPermission("admin")',
+  { currentUserId: 'u_123', perms: ['admin', 'write'] },
+)
+```
+
+The instance is generic over the context type (`bonsai<AppContext>()`), giving
+you end-to-end type safety: `ctx` is typed inside the function, and the call
+site is type-checked against the same shape. If your context type has required
+fields, TypeScript also requires you to pass the `context` argument to
+`evaluate`, `evaluateSync`, and compiled-expression evaluation.
+
+The context is passed to your function by reference, not copied or frozen. The
+`Readonly<TCtx>` parameter type signals that you should treat it as read-only:
+TypeScript flags reassigning its top-level fields. Bonsai does not deep-freeze
+it, so nested mutation and writes from untyped JavaScript reach the object you
+passed in. If you need isolation between evaluations, pass a fresh context
+object each time.
+
+Pure functions (`addFunction`) and context-aware functions (`addContextFunction`)
+share a single namespace. Registering the same name with either method
+overwrites the prior registration, so re-registering a context-aware name with
+`addFunction` turns it back into a pure function (check `isContextFunction(name)`
+if the kind matters). Functions registered with `addFunction` never receive the
+context; reach for `addContextFunction` when a function needs it. Plugins typed
+against a minimal context requirement can still be applied to instances with a
+wider context shape.
+
 ### Editor validation
 
 ```ts
@@ -361,20 +413,25 @@ evaluateExpression<number>('x * 2', { x: 21 }) // 42
 ## Instance Methods
 
 ```ts
-interface BonsaiInstance {
-  use(plugin: BonsaiPlugin): this
+type EvaluationContextArgs<TCtx extends object = Record<string, unknown>> =
+  {} extends TCtx ? [context?: TCtx] : [context: TCtx]
+
+interface BonsaiInstance<TCtx extends object = Record<string, unknown>> {
+  use(plugin: BonsaiPlugin<TCtx>): this
   addTransform(name: string, fn: TransformFn): this
   addFunction(name: string, fn: FunctionFn): this
+  addContextFunction(name: string, fn: ContextFunctionFn<TCtx>): this
   removeTransform(name: string): boolean
   removeFunction(name: string): boolean
   hasTransform(name: string): boolean
   hasFunction(name: string): boolean
+  isContextFunction(name: string): boolean
   listTransforms(): string[]
   listFunctions(): string[]
   clearCache(): void
-  compile(expression: string): CompiledExpression
-  evaluate<T = unknown>(expression: string, context?: Record<string, unknown>): Promise<T>
-  evaluateSync<T = unknown>(expression: string, context?: Record<string, unknown>): T
+  compile(expression: string): CompiledExpression<TCtx>
+  evaluate<T = unknown>(expression: string, ...args: EvaluationContextArgs<TCtx>): Promise<T>
+  evaluateSync<T = unknown>(expression: string, ...args: EvaluationContextArgs<TCtx>): T
   validate(expression: string): ValidationResult
 }
 ```
@@ -382,9 +439,12 @@ interface BonsaiInstance {
 Method notes:
 
 - `use()` runs a plugin immediately and returns the same instance.
-- `addTransform()` and `addFunction()` overwrite any existing registration with the same name.
-- `listTransforms()` and `listFunctions()` return the currently registered names.
+- `addTransform()`, `addFunction()`, and `addContextFunction()` overwrite any existing registration with the same name. Pure and context-aware functions share a single namespace.
+- `addContextFunction()` registers a function that receives the live evaluation context as its first argument (typed read-only; passed by reference, not copied or frozen). See [Context-aware functions](#context-aware-functions).
+- `isContextFunction()` returns `true` if the named function was registered via `addContextFunction()`.
+- `listTransforms()` and `listFunctions()` return the currently registered names. `listFunctions()` includes both pure and context-aware functions.
 - `clearCache()` clears the internal AST cache and compiled-expression cache. It does not remove registered transforms/functions.
+- Pass a context type generic to `bonsai<MyContext>()` for end-to-end type safety: `evaluate`, `evaluateSync`, `addContextFunction`, `compile`, and `use` all propagate the type. If `MyContext` has required fields, TypeScript requires a context argument when evaluating.
 
 ## Extending the Runtime
 
@@ -578,9 +638,152 @@ Bonsai is optimized for repeated evaluation.
 
 Benchmark guidance and current numbers live in the website docs and benchmark suite. Treat raw benchmark numbers as directional, not part of the API contract.
 
+## Autocomplete
+
+Bonsai ships a cursor-aware autocomplete engine at `bonsai-js/autocomplete`. It provides ranked, type-aware completion suggestions for any cursor position in an expression — designed for rule builders, expression editors, and admin tools. Tree-shakeable: if you don't import it, it's not in your bundle.
+
+```ts
+import { bonsai } from 'bonsai-js'
+import { strings, arrays } from 'bonsai-js/stdlib'
+import { createAutocomplete } from 'bonsai-js/autocomplete'
+
+const expr = bonsai().use(strings).use(arrays)
+
+const ac = createAutocomplete(expr, {
+  context: { user: { name: 'Alice', age: 25 }, items: [1, 2, 3] },
+})
+
+ac.complete('user.', 5)
+// [{ label: 'name', detail: 'string', kind: 'property' },
+//  { label: 'age',  detail: 'number', kind: 'property' }, ...]
+
+ac.complete('user.name.', 10)
+// [{ label: 'trim', detail: 'string → string', insertText: 'trim()', cursorOffset: 5 },
+//  { label: 'toUpperCase', detail: 'string → string' }, ...]
+
+ac.complete('items |> ', 9)
+// Only array-compatible transforms — string-only transforms automatically excluded.
+
+ac.complete('users.filter(.', 14)
+// [{ label: 'name', detail: 'string' }, { label: 'age', detail: 'number' }]
+```
+
+### What it provides
+
+| Context | What you get |
+|---|---|
+| `user.` | Object properties with value types |
+| `user?.name?.` | Optional chaining — same completions as dot access |
+| `user.name.` | Type-appropriate methods with return types |
+| `user.name.trim().` | Methods inferred through chained calls (eval-based) |
+| `user.name.to` | Fuzzy-filtered methods via static type inference |
+| `items \|> ` | Transforms filtered by inferred input type |
+| `users.filter(.` | Lambda element properties with types |
+| `users.filter(.name.` | Lambda member — methods for the element property type |
+| `groups.map(.users.filter(.` | Nested lambda element inference |
+| `us` | Context variables, functions, keywords |
+| `name.tLC` | Fuzzy matching (camelCase-aware) |
+
+### How to integrate
+
+The API returns pure data — no DOM, no framework dependency. Wire it into any UI:
+
+```ts
+// Custom dropdown
+textarea.addEventListener('input', () => {
+  ac.setContext(getCurrentContext())
+  const completions = ac.complete(textarea.value, textarea.selectionStart)
+  showDropdown(completions)
+})
+
+// Monaco editor
+const monacoKindMap = {
+  variable: monaco.languages.CompletionItemKind.Variable,
+  property: monaco.languages.CompletionItemKind.Property,
+  method: monaco.languages.CompletionItemKind.Method,
+  transform: monaco.languages.CompletionItemKind.Function,
+  function: monaco.languages.CompletionItemKind.Function,
+  keyword: monaco.languages.CompletionItemKind.Keyword,
+}
+
+monaco.languages.registerCompletionItemProvider('bonsai', {
+  triggerCharacters: ['.', '|', '('],
+  provideCompletionItems(model, position) {
+    ac.setContext(getCurrentContext())
+    const offset = model.getOffsetAt(position)
+    return {
+      suggestions: ac.complete(model.getValue(), offset).map(c => ({
+        label: c.label,
+        kind: monacoKindMap[c.kind],
+        insertText: c.insertText ?? c.label,
+        detail: c.detail,
+      })),
+    }
+  },
+})
+```
+
+Context can be updated dynamically — call `ac.setContext(newData)` whenever the user's data changes.
+
+### Options
+
+```ts
+createAutocomplete(instance, {
+  // Expression evaluation context — the data your users are writing expressions against
+  context: { user: { name: 'Alice' }, items: [1, 2, 3] },
+
+  // Explicit transform type map — skips auto-probing for better performance.
+  // Keys are transform names, values are arrays of accepted input types.
+  // When omitted, types are discovered automatically by probing each transform.
+  transformTypes: {
+    upper: ['string'],
+    trim: ['string'],
+    count: ['array'],
+    sort: ['array'],
+  },
+
+  // Error callback for debugging missing or incorrect completions.
+  // Only called for unexpected internal errors — not for expected parse/eval failures.
+  onError: (error, phase) => console.warn(`[autocomplete] ${phase}:`, error),
+})
+```
+
+### Security policy
+
+Autocomplete respects the same `allowedProperties` and `deniedProperties` policy configured on the Bonsai instance. Completions are filtered to match what the evaluator would actually allow:
+
+```ts
+const expr = bonsai({ allowedProperties: ['name', 'age'] })
+const ac = createAutocomplete(expr, {
+  context: { user: { name: 'Alice', secret: 'hidden' } },
+})
+
+ac.complete('user.', 5)
+// 'secret' is excluded — only 'name' and 'age' appear
+```
+
+This applies to all contexts: property access, lambda element properties, and nested chain resolution. Methods (`trim`, `filter`, etc.) are always shown for their applicable types — they are controlled by `deniedProperties`, not `allowedProperties`.
+
+### Completion type
+
+```ts
+interface Completion {
+  label: string        // Display text and default insert text
+  kind: 'variable' | 'property' | 'method' | 'transform' | 'function' | 'keyword'
+  detail?: string      // Type info: 'string', 'string → array', '"Alice"', 'array(3)'
+  insertText?: string  // Override insert: 'trim()', 'filter(.)', 'min()'
+  cursorOffset?: number // Cursor position in insertText (e.g., between parens)
+  sortPriority: number // Lower = higher rank
+}
+```
+
+### Error handling
+
+`complete()` never throws — it always returns `Completion[]`. If an unexpected internal error occurs, it returns `[]` and reports the error via the `onError` callback. Expected errors (syntax errors from incomplete expressions, security policy blocks, type mismatches) are silently handled as part of normal autocomplete operation.
+
 ## Stability
 
-Bonsai follows SemVer for the documented package entrypoints `bonsai-js` and `bonsai-js/stdlib`.
+Bonsai follows SemVer for the documented package entrypoints `bonsai-js`, `bonsai-js/stdlib`, and `bonsai-js/autocomplete`.
 
 - Supported runtimes are Node 20+ and current Bun releases.
 - The packed npm artifact is smoke-tested on Node 20 and 22.

package/dist/autocomplete/index.d.mts

@@ -0,0 +1,47 @@
+import { r as BonsaiInstance, u as InferredTypeName } from "../types-C58c6SlH.mjs";
+
+//#region src/autocomplete/tokenizer.d.ts
+/** Known phases where errors can occur during completion. */
+type CompletionPhase = 'tokenize' | 'tryEvalPrefix' | 'inferPipeInputType' | `probeTransform:${string}` | 'complete';
+type ErrorHandler = (error: unknown, phase: CompletionPhase) => void;
+//#endregion
+//#region src/autocomplete/completions.d.ts
+type CompletionInsert = {
+  insertText?: undefined;
+  cursorOffset?: undefined;
+} | {
+  insertText: string;
+  cursorOffset?: number;
+};
+interface CompletionBase {
+  label: string;
+  kind: 'variable' | 'property' | 'method' | 'transform' | 'function' | 'keyword';
+  detail?: string;
+  /** Lower values sort first. Can become negative after fuzzy-match boosting. */
+  sortPriority: number;
+}
+type Completion = CompletionBase & CompletionInsert;
+//#endregion
+//#region src/autocomplete/index.d.ts
+interface AutocompleteOptions {
+  context?: Record<string, unknown>;
+  /** Map of transform name → accepted input types (e.g., { upper: ['string'], filter: ['array'] }).
+   *  When set, pipe-transform completions are filtered by the inferred input type.
+   *  When omitted, auto-probing discovers type compatibility by calling each transform
+   *  with a sample value — this runs once per type and is cached per instance.
+   *  For performance-sensitive contexts (e.g., large transform registries), pass this
+   *  explicitly to avoid the cold-start probe cost. */
+  transformTypes?: Record<string, InferredTypeName[]>;
+  /** Called when an unexpected internal error occurs during completion.
+   *  Expected errors (e.g., syntax errors, security blocks, type mismatches) are not reported.
+   *  Useful for debugging missing or incorrect completions. */
+  onError?: ErrorHandler;
+}
+interface AutocompleteInstance {
+  complete(expression: string, cursor: number): Completion[];
+  setContext(context: Record<string, unknown>): void;
+}
+declare function createAutocomplete(instance: BonsaiInstance, options?: AutocompleteOptions): AutocompleteInstance;
+//#endregion
+export { AutocompleteInstance, AutocompleteOptions, type Completion, createAutocomplete };
+//# sourceMappingURL=index.d.mts.map

package/dist/autocomplete/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/autocomplete/tokenizer.ts","../../src/autocomplete/completions.ts","../../src/autocomplete/index.ts"],"mappings":";;;;KAcY,eAAA;AAAA,KAOA,YAAA,IAAgB,KAAA,WAAgB,KAAA,EAAO,eAAA;;;KCd9C,gBAAA;EACC,UAAA;EAAwB,YAAA;AAAA;EACxB,UAAA;EAAoB,YAAA;AAAA;AAAA,UAEhB,cAAA;EACR,KAAA;EACA,IAAA;EACA,MAAA;EDO0C;ECL1C,YAAA;AAAA;AAAA,KAGU,UAAA,GAAa,cAAA,GAAiB,gBAAA;;;UCTzB,mBAAA;EACf,OAAA,GAAU,MAAA;EFGe;;AAO3B;;;;EEHE,cAAA,GAAiB,MAAA,SAAe,gBAAA;EFGiB;;;EECjD,OAAA,GAAU,YAAA;AAAA;AAAA,UAGK,oBAAA;EACf,QAAA,CAAS,UAAA,UAAoB,MAAA,WAAiB,UAAA;EAC9C,UAAA,CAAW,OAAA,EAAS,MAAA;AAAA;AAAA,iBAcN,kBAAA,CACd,QAAA,EAAU,cAAA,EACV,OAAA,GAAS,mBAAA,GACR,oBAAA"}