@edgerules/node 0.0.0-alpha.202607061032 → 0.0.0-alpha.202607061957

package/README.md

@@ -0,0 +1,199 @@
+# @edgerules/node
+
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=rimvydasb_edgerules&metric=alert_status&token=98a392e505393c255f7de845e8b74a32911f2435)](https://sonarcloud.io/summary/new_code?id=rimvydasb_edgerules)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=rimvydasb_edgerules&metric=bugs&token=98a392e505393c255f7de845e8b74a32911f2435)](https://sonarcloud.io/summary/new_code?id=rimvydasb_edgerules)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=rimvydasb_edgerules&metric=code_smells&token=98a392e505393c255f7de845e8b74a32911f2435)](https://sonarcloud.io/summary/new_code?id=rimvydasb_edgerules)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=rimvydasb_edgerules&metric=coverage&token=98a392e505393c255f7de845e8b74a32911f2435)](https://sonarcloud.io/summary/new_code?id=rimvydasb_edgerules)
+[![Duplicated Lines](https://sonarcloud.io/api/project_badges/measure?project=rimvydasb_edgerules&metric=duplicated_lines_density&token=98a392e505393c255f7de845e8b74a32911f2435)](https://sonarcloud.io/summary/new_code?id=rimvydasb_edgerules)
+
+EdgeRules decision service for **Node.js**. Ships two builds:
+
+| Export | Description |
+|---|---|
+| `@edgerules/node` | Production build — execution only (`DecisionService`) |
+| `@edgerules/node/mutable` | Development build — execution + CRUD (`MutableDecisionService`) |
+
+---
+
+## Installation
+
+```sh
+npm install @edgerules/node @edgerules/portable
+```
+
+> Requires Node.js 18 or later (ESM only).
+
+---
+
+## Production Usage
+
+### Load from an EdgeRules DSL string
+
+```typescript
+import { DecisionService } from '@edgerules/node';
+
+const service = new DecisionService(`{
+    applicant: {
+        age:    <number, required: true>
+        income: <number, default: 0>
+    }
+    isEligible: applicant.age >= 18 and applicant.income >= 1000
+}`);
+
+// Execute the whole model — inputs are bound via a model-shaped request object
+const result = service.execute('*', { applicant: { age: 25, income: 2500 } });
+// { applicant: { age: 25, income: 2500 }, isEligible: true }
+```
+
+### Load from a Portable JSON model
+
+```typescript
+import { DecisionService } from '@edgerules/node';
+import type { PortableRootContext } from '@edgerules/portable';
+
+const model: PortableRootContext = {
+  '@version': '1.0',
+  '@model-name': 'Tax Calculator',
+  taxRate: 0.21,
+  calculateTax: {
+    '@kind': 'function',
+    '@parameters': { amount: 'number' },
+    '@body': {
+      '@kind': 'context',
+      result: 'amount * taxRate',
+    },
+  },
+};
+
+const service = new DecisionService(model);
+
+// Execute a specific function — pass its arguments as request bindings
+const tax = service.execute('calculateTax', { amount: 100 });
+// { result: 21 }
+```
+
+### Executing a ruleset
+
+```typescript
+const service = new DecisionService(`{
+    ruleset risk(age: number, income: number): {
+        hitPolicy: "first-match"
+        rules: [
+            { when: { age: 18..25, income: < 30000 }, then: { level: "high",   limit: 1000  } }
+            { when: { age: 18..25, income: >= 30000 }, then: { level: "medium", limit: 5000  } }
+            { when: { age: > 25 },                     then: { level: "low",    limit: 20000 } }
+        ]
+        default: { level: "none", limit: 0 }
+    }
+    decision: risk(age: applicant.age, income: applicant.income)
+}`);
+
+const result = service.execute('decision', { applicant: { age: 23, income: 25000 } });
+// { level: "high", limit: 1000 }
+```
+
+### Error handling
+
+Every execution or model error is a structured `PortableError` — never a plain string.
+
+```typescript
+import { DecisionService } from '@edgerules/node';
+import type { PortableError } from '@edgerules/portable';
+
+try {
+  service.execute('unknownField');
+} catch (err) {
+  const error = err as PortableError;
+  console.error(error.type);     // "EntryNotFound"
+  console.error(error.message);  // human-readable, safe to surface
+  console.error(error.path);     // "unknownField"
+}
+```
+
+| `error.type` | Meaning |
+|---|---|
+| `EntryNotFound` | Path does not exist in the model |
+| `WrongFieldPath` | Invalid path, out-of-bounds array index |
+| `Parse` | Expression string failed to parse |
+| `Linking` | Type mismatch or broken reference |
+| `Execution` | Runtime error during evaluation |
+
+---
+
+## Mutable / Development Usage
+
+Use the `./mutable` subpath import to access `MutableDecisionService`, which adds CRUD operations on top of execution.
+This build is intended for IDEs, rule editors, and test tooling — **not** for production traffic.
+
+```typescript
+import { MutableDecisionService } from '@edgerules/node/mutable';
+
+const service = new MutableDecisionService(`{
+    taxRate: 0.21
+    tax: amount * taxRate
+}`);
+
+// Read a node enriched with linked type information
+const node = service.get('taxRate');
+// { "@kind": "expression", "expression": 0.21, "type": "number", "readOnly": true }
+
+// Update a field at runtime — the engine relinks lazily on the next execute
+service.set('taxRate', 0.25);
+
+// Read the entire model snapshot
+const model = service.get('*');
+
+// Add a new typed input
+service.set('amount', { '@kind': 'type', type: 'number', required: true });
+
+// Remove a field
+service.remove('taxRate');
+
+// Rename a field
+service.rename('tax', 'vat');
+```
+
+### `get` filters
+
+```typescript
+// Default FIELDS view — returns expressions, typed holes, and function schemas
+service.get('isEligible');
+
+// Full function definition (body included)
+service.get('isEligible', 'FUNCTION_DEFINITIONS');
+
+// Type definition
+service.get('Customer', 'TYPE_DEFINITIONS');
+
+// Everything at once
+service.get('*', 'ALL');
+```
+
+---
+
+## API Reference
+
+### `DecisionService`
+
+| Method | Description |
+|---|---|
+| `new DecisionService(model)` | Create from DSL string or `PortableRootContext` |
+| `execute(method, args?)` | Evaluate `method` (field path, function, or `"*"`) against optional request bindings |
+
+### `MutableDecisionService` (dev build)
+
+Inherits `execute` and adds:
+
+| Method | Description |
+|---|---|
+| `get(path, filter?)` | Read a node enriched with inferred types |
+| `set(path, node)` | Write an expression, typed hole, function, type, or context |
+| `remove(path)` | Delete an entry |
+| `rename(oldPath, newPath)` | Rename an entry within its context |
+
+---
+
+## Related packages
+
+- [`@edgerules/web`](https://www.npmjs.com/package/@edgerules/web) — same API for the browser
+- [`@edgerules/portable`](https://www.npmjs.com/package/@edgerules/portable) — Portable JSON type definitions

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@edgerules/node",
-  "version": "0.0.0-alpha.202607061032",
+  "version": "0.0.0-alpha.202607061957",
   "type": "module",
   "description": "EdgeRules decision service for Node.js.",
   "dependencies": {
-    "@edgerules/portable": "0.0.0-alpha.202607061032"
+    "@edgerules/portable": "0.0.0-alpha.202607061957"
   },
   "devDependencies": {
     "@edgerules/core": "*",