Skip to content

README.md

Latest commit

 

History

History
172 lines (121 loc) · 4.54 KB

README.md

File metadata and controls

172 lines (121 loc) · 4.54 KB

regelrecht-engine

WebAssembly-based execution engine for machine-readable Dutch law (RegelRecht).

Installation

npm install regelrecht-engine

Usage

Browser

import init, { WasmEngine } from 'regelrecht-engine';

// Initialize WASM module (browser automatically fetches .wasm file)
await init();

// Create engine instance
const engine = new WasmEngine();

// Load a law from YAML
const response = await fetch('/laws/zorgtoeslagwet.yaml');
const yaml = await response.text();
const lawId = engine.loadLaw(yaml);  // Returns "zorgtoeslagwet"

// Execute an article output
// NOTE: External dependencies (source.regulation) must be pre-resolved
// and passed as parameters - see Limitations section
const result = engine.execute(
    'zorgtoeslagwet',
    'heeft_recht_op_zorgtoeslag',
    {
        BSN: '123456789',
        // Pre-resolved external values (workaround for WASM limitation)
        vermogen: 50000,
        heeft_toeslagpartner: false
    },
    '2025-01-01'  // calculation date
);

console.log(result.outputs.heeft_recht_op_zorgtoeslag);  // true or false

Node.js

import { initSync, WasmEngine } from 'regelrecht-engine';
import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';

// Node.js requires manual WASM loading
const wasmPath = fileURLToPath(new URL(
    './node_modules/regelrecht-engine/regelrecht_engine_bg.wasm',
    import.meta.url
));
const wasmBuffer = readFileSync(wasmPath);
initSync({ module: wasmBuffer });

// Create engine instance
const engine = new WasmEngine();

// Load and execute as shown above

API

new WasmEngine()

Creates a new engine instance.

engine.loadLaw(yaml: string): string

Load a law from a YAML string. Returns the law ID.

  • Limits: Max 1 MB YAML, max 100 laws per engine instance
  • Throws: If YAML parsing fails, limits exceeded, or law with same ID already loaded (call unloadLaw() first to replace)

engine.execute(lawId, outputName, parameters, calculationDate): ExecuteResult

Execute an article's output with the given parameters.

  • lawId - ID of the loaded law
  • outputName - Name of the output to calculate
  • parameters - Object with input parameters
  • calculationDate - Date string (YYYY-MM-DD)

Returns an object with:

  • outputs - Calculated output values (plain JavaScript object)
  • resolved_inputs - Input values used in calculation
  • article_number - Article that was executed
  • law_id - Law ID
  • law_uuid - Optional law UUID

engine.listLaws(): string[]

List all loaded law IDs (sorted alphabetically).

engine.getLawInfo(lawId: string): LawInfo

Get metadata about a loaded law.

Returns:

  • id - Law ID
  • regulatory_layer - Type of regulation (WET, MINISTERIELE_REGELING, etc.)
  • publication_date - Publication date
  • bwb_id - BWB identifier (optional)
  • url - Official government URL (optional)
  • outputs - Available output names (sorted alphabetically)
  • article_count - Number of articles

engine.hasLaw(lawId: string): boolean

Check if a law is loaded.

engine.unloadLaw(lawId: string): boolean

Remove a loaded law. Returns true if removed.

engine.lawCount(): number

Get the number of loaded laws.

engine.version(): string

Get the engine version.

Limitations

This WASM interface has some limitations compared to the full Rust engine:

  • No cross-law resolution: External references (source.regulation) require a ServiceProvider which is not available in WASM. Workaround: pre-resolve external values and pass them as parameters.
  • No open term resolution: Open terms (open_terms/implements IoC) require a ServiceProvider which is not available in WASM. Workaround: pre-resolve open term values and pass them as parameters.

TypeScript

Full TypeScript definitions are auto-generated by wasm-pack. The package exports:

import init, { WasmEngine } from 'regelrecht-engine';
import type { InitInput, InitOutput } from 'regelrecht-engine';

// Types for results
interface ExecuteResult {
    outputs: Record<string, any>;
    resolved_inputs: Record<string, any>;
    article_number: string;
    law_id: string;
    law_uuid?: string;
}

interface LawInfo {
    id: string;
    regulatory_layer: string;
    publication_date: string;
    bwb_id?: string;
    url?: string;
    outputs: string[];
    article_count: number;
}

License

EUPL-1.2 - See LICENSE for details.

Links