@autochitect/engine 1.1.3 → 1.1.4

package/README.md

@@ -8,86 +8,13 @@ A 245KB WebAssembly cost estimation engine. Define cost models in a purpose-buil
 npm install @autochitect/engine
 ```
 
-## Quick start
+## Node.js
 
 ```javascript
 import { createEngine } from '@autochitect/engine';
 
-const engine = await createEngine(
-  new URL('@autochitect/engine/engine.wasm', import.meta.url)
-);
-
-const result = engine.estimate(`
-  revenue: Input
-  cost_ratio: Input
-  costs = revenue * cost_ratio
-  profit = revenue - costs
-`, {
-  revenue: 500000,
-  cost_ratio: 0.6
-});
-
-console.log(result.results);
-// { revenue: 500000, cost_ratio: 0.6, costs: 300000, profit: 200000 }
-```
-
-## What you get
-
-**`result.results`** — computed values for every variable.
-
-**`result.graph`** — the full dependency DAG showing how each value was derived. Nodes have `kind` (input, formula, map, scan) and edges show data flow. Build audit trails, trace calculations back to source inputs, or render interactive cost breakdowns.
-
-**`result.errors`** / **`result.warnings`** — with line and column numbers.
-
-## Why use this
-
-| Instead of... | You get... |
-|---|---|
-| Building a calculation backend | 245KB client-side engine, zero infrastructure |
-| Exporting Excel/Google Sheets | Version-controlled DSL, real-time interactivity |
-| Spreadsheet-in-browser libraries | Just the engine — no grid UI overhead |
-| Python/R models behind an API | Embeddable in any web app, no server round-trips |
-
-The engine compiles your model into a directed acyclic graph, topologically sorts it, and estimates in one pass. Switching scenarios just swaps the input context — sub-millisecond.
-
-## The DSL
-
-The language is deliberately small. It's designed for cost estimation and financial modeling specifically.
-
-```
-# Inputs — bind to external data (your JSON)
-revenue: Input("annual_revenue")
-headcount: Input
-
-# Constants — use formula assignment
-tax_rate = 0.21
-avg_salary = 85000
-
-# Params — tunable scenario knobs (passed via inputs)
-growth: Param
-
-# Formulas — define cost relationships
-labor_cost = headcount * avg_salary
-gross_profit = revenue * (1 - tax_rate)
-net_income = gross_profit * (1 - tax_rate)
-
-# Array operations — project over time
-periods = SEQUENCE(12, 1, 1)
-monthly = MAP(periods, LAMBDA(p, revenue / 12 * POWER(1 + growth, p)))
-
-# Accumulation — running totals
-cumulative = SCAN(monthly, 0, LAMBDA(acc, m, acc + m))
-```
-
-**Inputs** bind to external data (your JSON). **Constants** are defined with formula assignment (`name = value`). **Params** are tunable scenario knobs passed via the inputs object.
-
-**MAP** transforms arrays element-wise. **SCAN** accumulates (like reduce, but returns intermediate results). **LAMBDA** defines inline functions with named parameters.
-
-## Real-world examples
+const engine = await createEngine();
 
-### SaaS pricing calculator
-
-```javascript
 const result = engine.estimate(`
   seats: Input
   base_price_per_seat = 12
@@ -98,7 +25,6 @@ const result = engine.estimate(`
   storage_cost = storage_gb * storage_price_per_gb
   subtotal = seat_cost + storage_cost
 
-  # Volume discount
   discount_rate = IF(seats > 50, 0.20, IF(seats > 20, 0.10, 0))
   discount = subtotal * discount_rate
   monthly_total = subtotal - discount
@@ -108,130 +34,55 @@ const result = engine.estimate(`
   storage_gb: 200,
 });
 
-console.log(result.results.monthly_total);  // 455
-console.log(result.results.discount_rate);  // 0.1 (10% for 35 seats)
-```
-
-### Construction cost estimation
-
-```javascript
-const result = engine.estimate(`
-  square_footage: Input
-  base_cost_per_sqft: Input
-  num_floors: Input
-
-  material_cost = square_footage * base_cost_per_sqft
-  labor_cost = material_cost * 0.60
-  floor_premium = (material_cost + labor_cost) * ((num_floors - 1) * 0.08)
-
-  permits = (material_cost + labor_cost) * 0.03
-  insurance = (material_cost + labor_cost) * 0.02
-
-  total = material_cost + labor_cost + floor_premium + permits + insurance
-  cost_per_sqft = total / square_footage
-`, {
-  square_footage: 5000,
-  base_cost_per_sqft: 150,
-  num_floors: 3,
-});
-
-console.log(result.results.total);         // 1,452,000
-console.log(result.results.cost_per_sqft); // 290.40
-```
-
-### Loan amortization projection
-
-```javascript
-const result = engine.estimate(`
-  principal: Input
-  annual_rate: Input
-  months: Input
-
-  monthly_rate = annual_rate / 12
-  payment = principal * (monthly_rate * POWER(1 + monthly_rate, months))
-            / (POWER(1 + monthly_rate, months) - 1)
-
-  periods = SEQUENCE(months, 1, 1)
-  balances = SCAN(periods, principal, LAMBDA(bal, p,
-    bal * (1 + monthly_rate) - payment
-  ))
-
-  total_paid = payment * months
-  total_interest = total_paid - principal
-`, {
-  principal: 400000,
-  annual_rate: 0.065,
-  months: 360,
-});
-
-console.log(result.results.payment);        // ~2,528.27/month
-console.log(result.results.total_interest);  // ~510,177
-```
-
-## Node.js usage
-
-```javascript
-import { createEngine } from '@autochitect/engine';
-import { createRequire } from 'module';
-
-const require = createRequire(import.meta.url);
-const wasmPath = require.resolve('@autochitect/engine/engine.wasm');
-const engine = await createEngine(wasmPath);
-
-const result = engine.estimate(`
-  headcount: Input
-  avg_salary = 85000
-  benefits_rate = 0.3
-
-  labor_cost = headcount * avg_salary
-  benefits = labor_cost * benefits_rate
-  total_people_cost = labor_cost + benefits
-`, {
-  headcount: 12,
-});
-
 console.log(result.results);
 // {
-//   headcount: 12,
-//   avg_salary: 85000,
-//   benefits_rate: 0.3,
-//   labor_cost: 1020000,
-//   benefits: 306000,
-//   total_people_cost: 1326000
+//   seats: 35, base_price_per_seat: 12, storage_gb: 200, storage_price_per_gb: 0.5,
+//   seat_cost: 420, storage_cost: 100, subtotal: 520,
+//   discount_rate: 0.1, discount: 52, monthly_total: 468, annual_total: 5616
 // }
 ```
 
-## Browser usage
+## Browser
+
+No install needed — paste this into an HTML file and open it.
 
 ```html
 <script type="module">
-  import { createEngine } from './node_modules/@autochitect/engine/index.mjs';
+  import { createEngine } from 'https://esm.sh/@autochitect/engine';
 
   const engine = await createEngine(
-    new URL('./node_modules/@autochitect/engine/engine.wasm', import.meta.url)
+    'https://unpkg.com/@autochitect/engine/engine.wasm'
   );
 
   const result = engine.estimate(`
-    units: Input
-    price_per_unit: Input
-    discount_rate: Input
+    seats: Input
+    base_price_per_seat = 12
+    storage_gb: Input
+    storage_price_per_gb = 0.50
+
+    seat_cost = seats * base_price_per_seat
+    storage_cost = storage_gb * storage_price_per_gb
+    subtotal = seat_cost + storage_cost
 
-    subtotal = units * price_per_unit
+    discount_rate = IF(seats > 50, 0.20, IF(seats > 20, 0.10, 0))
     discount = subtotal * discount_rate
-    total = subtotal - discount
+    monthly_total = subtotal - discount
+    annual_total = monthly_total * 12
   `, {
-    units: 1000,
-    price_per_unit: 49.99,
-    discount_rate: 0.15,
+    seats: 35,
+    storage_gb: 200,
   });
 
   console.log(result.results);
-  // { units: 1000, price_per_unit: 49.99, discount_rate: 0.15,
-  //   subtotal: 49990, discount: 7498.5, total: 42491.5 }
+  // {
+  //   seats: 35, base_price_per_seat: 12, storage_gb: 200, storage_price_per_gb: 0.5,
+  //   seat_cost: 420, storage_cost: 100, subtotal: 520,
+  //   discount_rate: 0.1, discount: 52, monthly_total: 468, annual_total: 5616
+  // }
 </script>
 ```
 
-When using a bundler (Vite, webpack, etc.), import the WASM file directly:
+If you use a bundler (Vite, webpack, etc.), import normally:
 
 ```javascript
 import { createEngine } from '@autochitect/engine';
@@ -241,16 +92,44 @@ const engine = await createEngine(
 );
 ```
 
-## Framework examples
+## What you get
+
+**`result.results`** — computed values for every variable.
+
+**`result.graph`** — the full dependency DAG showing how each value was derived. Nodes have `kind` (input, formula, map, scan) and edges show data flow. Build audit trails, trace calculations back to source inputs, or render interactive cost breakdowns.
+
+**`result.errors`** / **`result.warnings`** — with line and column numbers.
+
+## The DSL
+
+```
+# Inputs — bind to external data (your JSON)
+revenue: Input("annual_revenue")
+headcount: Input
+
+# Constants — use formula assignment
+tax_rate = 0.21
+avg_salary = 85000
+
+# Params — tunable scenario knobs (passed via inputs)
+growth: Param
+
+# Formulas — define cost relationships
+labor_cost = headcount * avg_salary
+gross_profit = revenue * (1 - tax_rate)
+net_income = gross_profit * (1 - tax_rate)
+
+# Array operations — project over time
+periods = SEQUENCE(12, 1, 1)
+monthly = MAP(periods, LAMBDA(p, revenue / 12 * POWER(1 + growth, p)))
+
+# Accumulation — running totals
+cumulative = SCAN(monthly, 0, LAMBDA(acc, m, acc + m))
+```
 
-Working integration examples are available in the [`examples/`](https://github.com/autochitect/engine/tree/main/examples) directory:
+**Inputs** bind to external data (your JSON). **Constants** are defined with formula assignment (`name = value`). **Params** are tunable scenario knobs passed via the inputs object.
 
-| Example | Description |
-|---------|-------------|
-| [Next.js pricing calculator](https://github.com/autochitect/engine/tree/main/examples/nextjs-pricing-calculator) | SaaS pricing page with real-time sliders and volume discounts |
-| [Vue.js cost estimator](https://github.com/autochitect/engine/tree/main/examples/vue-cost-estimator) | Construction cost estimator with dependency graph visualization |
-| [Strapi pricing page](https://github.com/autochitect/engine/tree/main/examples/strapi-pricing-page) | CMS-driven pricing — content in Strapi, calculations in engine |
-| [Vanilla JS](https://github.com/autochitect/engine/tree/main/examples/vanilla-js) | Single HTML file, no build tools, plain DOM |
+**MAP** transforms arrays element-wise. **SCAN** accumulates (like reduce, but returns intermediate results). **LAMBDA** defines inline functions with named parameters.
 
 ## Options
 

package/index.d.ts

@@ -24,4 +24,4 @@ export interface Engine {
   estimate(source: string, inputs?: Record<string, unknown> | object, options?: EstimateOptions): EstimateResult;
 }
 
-export function createEngine(wasmSource: string | URL | Response | ArrayBuffer): Promise<Engine>;
+export function createEngine(wasmSource?: string | URL | Response | ArrayBuffer): Promise<Engine>;

package/index.mjs

@@ -82,6 +82,13 @@ export async function createEngine(wasmSource) {
   const memoryRef = { current: null };
   const imports = { wasi_snapshot_preview1: buildWasiImports(memoryRef) };
 
+  if (wasmSource == null && typeof globalThis.process !== 'undefined') {
+    const { fileURLToPath } = await import('url');
+    const { dirname, join } = await import('path');
+    const fs = await import('fs');
+    wasmSource = join(dirname(fileURLToPath(import.meta.url)), 'engine.wasm');
+  }
+
   let bytes;
   if (wasmSource instanceof ArrayBuffer || ArrayBuffer.isView(wasmSource)) {
     bytes = wasmSource;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autochitect/engine",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "A 245KB WebAssembly financial modeling engine. Define cost models in a purpose-built DSL, get instant estimates with full dependency tracing. No server required.",
   "license": "MIT",
   "type": "module",