bonsai-js 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,51 @@ 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).
 
+## [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
+
+- Native method support for commonly expected string methods: `trim`, `toLowerCase`, `toUpperCase`, `split`, `padStart`, `padEnd`, `concat`, `lastIndexOf`
+- Native method support for additional array methods: `join`, `flat`, `concat`, `lastIndexOf`, `findIndex`, `flatMap`
+- ES2023 non-mutating array methods: `toReversed`, `toSorted`, `toSpliced`, `with`
+- Mutating array methods (`reverse`, `sort`, `push`, `pop`, `splice`) are explicitly blocked to prevent context mutation
+
 ## [0.2.0] - 2026-03-15
 
 ### Added

package/README.md

@@ -27,6 +27,8 @@ bun add bonsai-js
 npm install bonsai-js
 ```
 
+[npm](https://www.npmjs.com/package/bonsai-js) · [Playground](https://danfry1.github.io/bonsai-js/playground.html) · [Docs](https://danfry1.github.io/bonsai-js/docs.html)
+
 ## When to use it
 
 - Evaluate expressions from config, database records, or admin tools.
@@ -183,6 +185,47 @@ expr.evaluateSync('[1, 2, 3].every(. > 0)') // true
 
 Both styles support async evaluation via `evaluate()`.
 
+### Built-in safe methods
+
+These methods work via native `.method()` syntax without any imports. Mutating methods (`reverse`, `sort`, `push`, `pop`, `splice`, etc.) are blocked to prevent context mutation.
+
+**String methods:**
+
+| Method | Example |
+| --- | --- |
+| `trim`, `trimStart`, `trimEnd` | `"  hi  ".trim()` → `"hi"` |
+| `toLowerCase`, `toUpperCase` | `"Hello".toLowerCase()` → `"hello"` |
+| `startsWith`, `endsWith` | `"hello".startsWith("hel")` → `true` |
+| `includes`, `indexOf`, `lastIndexOf` | `"hello".includes("ell")` → `true` |
+| `slice`, `substring`, `at` | `"hello".slice(1, 3)` → `"el"` |
+| `replace`, `replaceAll` | `"abc".replace("a", "x")` → `"xbc"` |
+| `split` | `"a,b,c".split(",")` → `["a", "b", "c"]` |
+| `padStart`, `padEnd` | `"5".padStart(3, "0")` → `"005"` |
+| `charAt`, `charCodeAt`, `repeat`, `concat` | `"ab".repeat(2)` → `"abab"` |
+
+**Array methods (with lambda support):**
+
+| Method | Example |
+| --- | --- |
+| `filter` | `[1,2,3].filter(. > 1)` → `[2, 3]` |
+| `map` | `[1,2,3].map(. * 10)` → `[10, 20, 30]` |
+| `find`, `findIndex` | `[1,2,3].find(. > 1)` → `2` |
+| `some`, `every` | `[1,2,3].some(. > 2)` → `true` |
+| `flatMap` | `[[1],[2,3]].flatMap(.)` |
+
+**Array methods (non-callback):**
+
+| Method | Example |
+| --- | --- |
+| `join` | `[1,2,3].join(", ")` → `"1, 2, 3"` |
+| `includes`, `indexOf`, `lastIndexOf` | `[1,2,3].includes(2)` → `true` |
+| `slice`, `at`, `concat`, `flat` | `[1,2,3].concat([4])` → `[1, 2, 3, 4]` |
+| `toReversed`, `toSorted`, `toSpliced`, `with` | `[3,1,2].toSorted()` → `[1, 2, 3]` |
+
+**Number methods:** `toFixed`, `toString`
+
+**Pipe-only transforms** (require stdlib import): `count`, `first`, `last`, `reverse`, `flatten`, `unique`, `sort`, `upper`, `lower`, `trim`, `sum`, `avg`, `clamp`, and more. See [Standard Library](#standard-library) for the full list.
+
 ## API Reference
 
 ### `bonsai(options?)`
@@ -535,9 +578,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 { c as InferredTypeName, n as BonsaiInstance } from "../types-BhsZZsLY.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"}