@benrogmans/lemma-engine 0.8.1 → 0.8.3

package/README.md

@@ -1,299 +1,84 @@
 # @benrogmans/lemma-engine
 
-Lemma is a declarative programming language for expressing business rules. This WebAssembly build for JavaScript and TypeScript provides an embeddable runtime, so that Lemma code can be evaluated anywhere.
+Embeddable Lemma engine (WebAssembly).
 
-**New to Lemma?** Check out the [language introduction](https://github.com/benrogmans/lemma#quick-start) and [examples](https://github.com/benrogmans/lemma/tree/main/documentation/examples).
+npm `description` / `keywords` / `homepage`: edit **`NPM_BRANDING`** in `build.js` (not Cargo).
 
-## Installation
+## Install
 
 ```bash
 npm install @benrogmans/lemma-engine
 ```
 
-## JavaScript API Reference
+## Browser / bundler
 
-### Initialization
-
-#### Browser
 ```javascript
-import init, { WasmEngine } from '@benrogmans/lemma-engine';
+import { Lemma } from '@benrogmans/lemma-engine';
 
-// Async initialization (recommended for browsers)
-await init();
-const engine = new WasmEngine();
+const engine = await Lemma();
 ```
 
-#### Node.js
-```javascript
-import { readFileSync } from 'fs';
-import { WasmEngine, initSync } from '@benrogmans/lemma-engine';
+`Lemma()` initializes WASM once and returns an `Engine`. Serve over **http(s)** (not `file://`). For manual init: `init()` then `new Engine()`.
 
-// Synchronous initialization for Node.js
-const wasmBytes = readFileSync('node_modules/@benrogmans/lemma-engine/lemma_bg.wasm');
-initSync(wasmBytes);
-const engine = new WasmEngine();
-```
+If your bundler outputs IIFE (or otherwise breaks `import.meta.url`), use:
 
-#### Bundlers (Webpack, Vite, etc.)
 ```javascript
-import init, { WasmEngine } from '@benrogmans/lemma-engine';
-import wasmUrl from '@benrogmans/lemma-engine/lemma_bg.wasm?url';
+import { Lemma } from '@benrogmans/lemma-engine/iife';
 
-// Initialize with URL
-await init(wasmUrl);
-const engine = new WasmEngine();
+const engine = await Lemma();
 ```
 
-### Core Methods
+This entry embeds WASM bytes and avoids external wasm URL handling.
 
-#### `addLemmaFile(code: string, filename: string): string`
+## esbuild auto-handler
 
-Adds a Lemma spec to the engine.
+If you use esbuild JS API, plugin rewrites root import to `/iife` automatically:
 
 ```javascript
-const result = engine.addLemmaFile(`
-  spec employee_contract
-
-  fact salary: 5000 eur
-  fact start_date: 2024-01-15
-  fact vacation_days: 25
-
-  rule annual_salary: salary * 12
-  rule daily_rate: salary / 21
-`, 'employee.lemma');
-
-const response = JSON.parse(result);
-if (response.success) {
-  console.log('Spec loaded:', response.data);
-} else {
-  console.error('Error:', response.error);
-}
+import { lemmaEngineEsbuildPlugin } from '@benrogmans/lemma-engine/esbuild';
 ```
 
-#### `evaluate(docName: string, facts: string): string`
-
-Evaluates a spec with optional runtime facts.
+## Node
 
 ```javascript
-// Evaluate with default facts
-const result1 = engine.evaluate('employee_contract', '{}');
-
-// Evaluate with runtime fact values (as JSON object)
-const result2 = engine.evaluate('employee_contract', JSON.stringify({
-  salary: 6000,
-  vacation_days: 30
-}));
-
-const response = JSON.parse(result2);
-if (response.success) {
-  console.log('Spec:', response.data.spec);
-  console.log('Rules:', response.data.rules);
-  // Access specific rule results directly:
-  // response.data.rules.annual_salary.value
-}
-```
-
-#### `listSpecs(): string`
-
-Lists all loaded specs in the engine.
-
-```javascript
-const result = engine.listSpecs();
-const response = JSON.parse(result);
-
-if (response.success) {
-  console.log('Loaded specs:', response.data);
-  // response.data is an array of spec names
-}
-```
-
-### Response Format
-
-All methods return a JSON string with this structure:
-
-```typescript
-interface WasmResponse {
-  success: boolean;
-  data?: any;        // Success data (varies by method)
-  error?: string;    // Error message if success is false
-  warnings?: string[]; // Optional warnings
-}
-```
-
-### Complete Example
-
-```javascript
-import init, { WasmEngine } from '@benrogmans/lemma-engine';
-
-async function calculatePricing() {
-  // Initialize WASM
-  await init();
-  const engine = new WasmEngine();
+import { Lemma } from '@benrogmans/lemma-engine';
 
-  // Define pricing rules
-  const pricingDoc = `
-    spec product_pricing
-
-    fact base_price: 100 usd
-    fact quantity: 1
-    fact is_member: false
-    fact promo_code: ""
-
-    rule bulk_discount: 0%
-      unless quantity >= 10 then 5%
-      unless quantity >= 50 then 10%
-      unless quantity >= 100 then 15%
-
-    rule member_discount: 0%
-      unless is_member then 10%
-
-    rule promo_discount: 0%
-      unless promo_code == "SAVE10" then 10%
-      unless promo_code == "SAVE20" then 20%
-
-    rule best_discount: bulk_discount
-      unless member_discount >= bulk_discount  then member_discount
-      unless promo_discount >= bulk_discount   then promo_discount
-      unless member_discount >= promo_discount then member_discount
-      unless promo_discount >= member_discount then promo_discount
-
-    rule final_price: base_price * quantity * (1 - best_discount)
-  `;
-
-  // Load the spec
-  const loadResult = JSON.parse(
-    engine.addLemmaFile(pricingDoc, 'pricing.lemma')
-  );
-
-  if (!loadResult.success) {
-    throw new Error(loadResult.error);
-  }
-
-    // Calculate for different scenarios
-    const scenarios = [
-      { quantity: 25, is_member: false, promo_code: "" },
-      { quantity: 10, is_member: true, promo_code: "" },
-      { quantity: 5, is_member: false, promo_code: "SAVE20" }
-    ];
-
-    for (const scenario of scenarios) {
-      const result = JSON.parse(
-        engine.evaluate('product_pricing', JSON.stringify(scenario))
-      );
-
-    if (result.success) {
-      console.log(`Scenario:`, scenario);
-      // Access rule results directly by name
-      const finalPrice = result.data.rules.final_price.value;
-      const bestDiscount = result.data.rules.best_discount.value;
-      console.log(`Final price:`, finalPrice);
-      console.log(`Discount applied:`, bestDiscount);
-      console.log('---');
-    }
-  }
-}
-
-calculatePricing().catch(console.error);
+const engine = await Lemma();
 ```
 
-### TypeScript Support
-
-The package includes TypeScript definitions. For better type safety:
+Or with a preloaded buffer (e.g. no async fetch): `initSync({ module })` then `new Engine()`.
 
-```typescript
-import init, { WasmEngine } from '@benrogmans/lemma-engine';
+## LSP (browser streams)
 
-interface PricingFacts {
-  quantity: number;
-  is_member: boolean;
-  promo_code: string;
-}
-
-interface PricingResults {
-  base_price: string;
-  final_price: string;
-  best_discount: string;
-  // ... other fields
-}
-
-interface EvaluationResponse {
-  success: boolean;
-  data?: {
-    spec: string;
-    rules: {
-      [ruleName: string]: {
-        value: any;  // The computed value (e.g., {Number: "100"})
-        veto?: string;  // Present if rule was vetoed
-        missing_facts?: string[];  // Present if rule couldn't be evaluated
-        operations?: Array<{  // Operation records (always present if rule was evaluated)
-          type: string;  // "fact_used", "operation_executed", "final_result", etc.
-          // Additional fields depend on type
-        }>;
-      };
-    };
-  };
-  error?: string;
-  warnings?: string[];  // Spec-level warnings
-}
-
-async function typedExample() {
-  await init();
-  const engine = new WasmEngine();
-
-  // ... load spec
-
-  const facts = {
-    quantity: 10,
-    is_member: true,
-    promo_code: "SAVE10"
-  };
-
-  const result: EvaluationResponse = JSON.parse(
-    engine.evaluate('product_pricing', JSON.stringify(facts))
-  );
-
-  if (result.success && result.data) {
-    const price = result.data.rules.final_price?.value;
-  }
-}
-```
-
-### Error Handling
+Call `init()` first. Use `LspClient`; `start()` uses the bundled LSP (no need to pass `serve`/`ServerConfig`). Optional: `start(serve, ServerConfig)` to override.
 
 ```javascript
-try {
-  const result = JSON.parse(
-    engine.addLemmaFile('invalid syntax', 'bad.lemma')
-  );
+import { init } from '@benrogmans/lemma-engine';
+import { LspClient } from '@benrogmans/lemma-engine/lsp-client';
 
-  if (!result.success) {
-    console.error('Lemma error:', result.error);
-    // Handle parse/semantic errors
-  }
-} catch (e) {
-  // Handle JSON parse errors or WASM exceptions
-  console.error('System error:', e);
-}
+await init();
+const client = new LspClient(monaco);
+await client.start();
+await client.initialize();
+client.onDiagnostics((uri, diagnostics) => { /* ... */ });
+client.didOpen(uri, 'lemma', 1, documentText);
 ```
 
-### Performance Tips
+## API (`Engine`)
 
-1. **Initialize once**: The WASM module should be initialized once per application
-2. **Reuse engines**: Create one `WasmEngine` and load multiple specs
-3. **Batch operations**: Load all specs before evaluating
-4. **Cache results**: Evaluation results can be cached if facts don't change
+| Method | |
+|--------|--|
+| `load(code, attribute)` | Promise; reject → `string[]` |
+| `list()` | Spec entries |
+| `schema(spec, effective?)` | `SpecSchema` |
+| `run(spec, rules, facts, effective?)` | `Response` |
+| `format(code, attribute?)` | string or throw |
+| `invert(...)` | throws (N/A) |
 
-### Compatibility
+## Build (maintainers)
 
-Works in modern browsers with WebAssembly support and Node.js with ES module support.
+`node build.js`: wasm-pack → `lemma.bindings.js` + `lemma_bg.wasm` → copy checked-in `lemma-entry.js` / `lsp-entry.js` / `*.d.ts` into `dist/`. Do not edit generated bindings by hand.
 
 ## License
 
 Apache-2.0
-
-## Links
-
-- [GitHub Repository](https://github.com/benrogmans/lemma)
-- [Lemma Language Guide](https://github.com/benrogmans/lemma/tree/main/documentation)
-- [Examples](https://github.com/benrogmans/lemma/tree/main/documentation/examples)
-- [Report Issues](https://github.com/benrogmans/lemma/issues)

package/esbuild.js

@@ -0,0 +1,21 @@
+/**
+ * esbuild plugin for @benrogmans/lemma-engine.
+ *
+ * Rewrites root imports to the IIFE-safe entry so users do not have
+ * to handle WASM asset paths manually in esbuild-based builds.
+ */
+import { createRequire } from "node:module";
+
+export function lemmaEngineEsbuildPlugin() {
+  const require = createRequire(import.meta.url);
+
+  return {
+    name: "lemma-engine",
+    setup(build) {
+      build.onResolve({ filter: /^@benrogmans\/lemma-engine$/ }, () => {
+        const iifePath = require.resolve("@benrogmans/lemma-engine/iife");
+        return { path: iifePath };
+      });
+    },
+  };
+}

package/lemma.bindings.d.ts

@@ -0,0 +1,138 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * The `ReadableStreamType` enum.
+ *
+ * *This API requires the following crate features to be activated: `ReadableStreamType`*
+ */
+
+type ReadableStreamType = "bytes";
+
+export class Engine {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Returns formatted source string on success; throws with error message on failure.
+     */
+    format(code: string, attribute?: string | null): any;
+    invert(_spec_name: string, _rule_name: string, _target_json: string, _provided_values_json: string): any;
+    /**
+     * Spec names from the engine (same order as [`Engine::list_specs`]).
+     */
+    list(): any;
+    /**
+     * Load Lemma source. Resolves with `undefined` on success; rejects with an array of error strings.
+     */
+    load(code: string, attribute: string): Promise<any>;
+    constructor();
+    /**
+     * Evaluate spec. Returns [`crate::evaluation::Response`] as a JS object. Throws on planning/runtime error.
+     */
+    run(spec: string, rule_names: any, fact_values: any, effective?: string | null): any;
+    /**
+     * Planning schema for the spec ([`crate::planning::execution_plan::SpecSchema`]). Throws on error.
+     */
+    schema(spec: string, effective?: string | null): any;
+}
+
+export class IntoUnderlyingByteSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableByteStreamController): Promise<any>;
+    start(controller: ReadableByteStreamController): void;
+    readonly autoAllocateChunkSize: number;
+    readonly type: ReadableStreamType;
+}
+
+export class IntoUnderlyingSink {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    abort(reason: any): Promise<any>;
+    close(): Promise<any>;
+    write(chunk: any): Promise<any>;
+}
+
+export class IntoUnderlyingSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableStreamDefaultController): Promise<any>;
+}
+
+export class ServerConfig {
+    free(): void;
+    [Symbol.dispose](): void;
+    constructor(into_server: AsyncIterator<any>, from_server: WritableStream);
+}
+
+/**
+ * Run the Lemma LSP over the given streams. Call from JS after creating
+ * an AsyncIterator (client → server messages) and a WritableStream (server → client).
+ */
+export function serve(config: ServerConfig): Promise<void>;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_serverconfig_free: (a: number, b: number) => void;
+    readonly serve: (a: number) => number;
+    readonly serverconfig_new: (a: number, b: number) => number;
+    readonly __wbg_intounderlyingbytesource_free: (a: number, b: number) => void;
+    readonly __wbg_intounderlyingsink_free: (a: number, b: number) => void;
+    readonly __wbg_intounderlyingsource_free: (a: number, b: number) => void;
+    readonly intounderlyingbytesource_autoAllocateChunkSize: (a: number) => number;
+    readonly intounderlyingbytesource_cancel: (a: number) => void;
+    readonly intounderlyingbytesource_pull: (a: number, b: number) => number;
+    readonly intounderlyingbytesource_start: (a: number, b: number) => void;
+    readonly intounderlyingbytesource_type: (a: number) => number;
+    readonly intounderlyingsink_abort: (a: number, b: number) => number;
+    readonly intounderlyingsink_close: (a: number) => number;
+    readonly intounderlyingsink_write: (a: number, b: number) => number;
+    readonly intounderlyingsource_cancel: (a: number) => void;
+    readonly intounderlyingsource_pull: (a: number, b: number) => number;
+    readonly __wbg_engine_free: (a: number, b: number) => void;
+    readonly wasmengine_format: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly wasmengine_invert: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
+    readonly wasmengine_list: (a: number, b: number) => void;
+    readonly wasmengine_load: (a: number, b: number, c: number, d: number, e: number) => number;
+    readonly wasmengine_new: () => number;
+    readonly wasmengine_run: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly wasmengine_schema: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly __wasm_bindgen_func_elem_9731: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_385: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_10982: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_2764: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_10985: (a: number, b: number, c: number, d: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;