/**
* @file worldFacts.js
* CORE-03: Authoritative key-value fact store, typed prioritized event bus,
* and ordered condition/effect rule engine.
*/
/**
* Normalizes provenance metadata.
* @param {string|object|null} provenance
* @returns {{ source: string, timestamp: number }}
*/
function normalizeProvenance(provenance) {
if (typeof provenance === 'string' && provenance.trim()) {
return { source: provenance.trim(), timestamp: Date.now() };
}
if (provenance && typeof provenance === 'object') {
const source = (typeof provenance.source === 'string' && provenance.source.trim())
? provenance.source.trim()
: 'system';
const timestamp = (typeof provenance.timestamp === 'number' && Number.isFinite(provenance.timestamp))
? provenance.timestamp
: Date.now();
return { source, timestamp };
}
return { source: 'system', timestamp: Date.now() };
}
/**
* Safely traverses an object along path segments.
* @param {object} obj
* @param {string[]} parts
* @returns {any}
*/
function getNested(obj, parts) {
let curr = obj;
for (let i = 0; i < parts.length; i++) {
if (curr === null || typeof curr !== 'object') {
return undefined;
}
const prop = parts[i];
if (!(prop in curr)) {
return undefined;
}
curr = curr[prop];
}
return curr;
}
/**
* Sets a nested property on an object, creating intermediate objects as needed.
* @param {object} obj
* @param {string[]} parts
* @param {any} value
*/
function setNested(obj, parts, value) {
let curr = obj;
for (let i = 0; i < parts.length - 1; i++) {
const prop = parts[i];
if (!(prop in curr) || typeof curr[prop] !== 'object' || curr[prop] === null) {
curr[prop] = {};
}
curr = curr[prop];
}
curr[parts[parts.length - 1]] = value;
}
/**
* Matches a key against a pattern with wildcard support.
* @param {string|null} pattern
* @param {string} key
* @returns {boolean}
*/
function matchesPattern(pattern, key) {
if (!pattern || pattern === '*') return true;
if (pattern === key) return true;
if (pattern.endsWith('*')) {
const prefix = pattern.slice(0, -1);
return key.startsWith(prefix);
}
if (pattern.includes('*')) {
const regexStr = '^' + pattern.split('*').map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$';
return new RegExp(regexStr).test(key);
}
return false;
}
/**
* Authoritative key-value fact store with dot-notated/string keys,
* provenance tracking ({ source, timestamp }), snapshot/restore for save games,
* and onChange listeners with unbind.
*/
export class WorldFacts {
#facts = new Map();
#listeners = new Set();
/**
* @param {Record<string, any>} [initialFacts]
*/
constructor(initialFacts = null) {
if (initialFacts && typeof initialFacts === 'object') {
for (const [key, value] of Object.entries(initialFacts)) {
this.set(key, value, { source: 'initial', timestamp: Date.now() });
}
}
}
/**
* Number of stored authoritative facts.
* @returns {number}
*/
get size() {
return this.#facts.size;
}
/**
* Sets a fact with provenance tracking.
* @param {string} key
* @param {any} value
* @param {string|object} [provenance]
* @returns {this}
*/
set(key, value, provenance = null) {
if (typeof key !== 'string' || !key.trim()) {
throw new TypeError('Fact key must be a non-empty string');
}
const prov = normalizeProvenance(provenance);
const oldRecord = this.#facts.get(key);
const oldValue = oldRecord ? oldRecord.value : undefined;
const storedValue = (value !== null && typeof value === 'object')
? structuredClone(value)
: value;
this.#facts.set(key, {
value: storedValue,
source: prov.source,
timestamp: prov.timestamp
});
this._notifyChange(key, storedValue, oldValue, prov);
return this;
}
/**
* Gets a fact value. Supports exact key, dot-notated sub-path traversal,
* and namespace aggregation.
* @param {string} key
* @param {any} [defaultValue=undefined]
* @returns {any}
*/
get(key, defaultValue = undefined) {
if (typeof key !== 'string') return defaultValue;
// 1. Direct match
if (this.#facts.has(key)) {
const val = this.#facts.get(key).value;
return (val !== null && typeof val === 'object') ? structuredClone(val) : val;
}
// 2. Dot-notated subpath lookup into a stored object fact
if (key.includes('.')) {
const parts = key.split('.');
for (let i = parts.length - 1; i >= 1; i--) {
const prefix = parts.slice(0, i).join('.');
if (this.#facts.has(prefix)) {
const rootVal = this.#facts.get(prefix).value;
const subVal = getNested(rootVal, parts.slice(i));
if (subVal !== undefined) {
return (subVal !== null && typeof subVal === 'object')
? structuredClone(subVal)
: subVal;
}
}
}
}
// 3. Namespace aggregation: if keys like `${key}.*` exist, assemble a composite object
const prefix = key + '.';
let matched = false;
const composite = {};
for (const [k, rec] of this.#facts.entries()) {
if (k.startsWith(prefix)) {
matched = true;
const subParts = k.slice(prefix.length).split('.');
const val = (rec.value !== null && typeof rec.value === 'object')
? structuredClone(rec.value)
: rec.value;
setNested(composite, subParts, val);
}
}
if (matched) {
return composite;
}
return defaultValue;
}
/**
* Checks whether a fact exists (exact key, nested property, or namespace).
* @param {string} key
* @returns {boolean}
*/
has(key) {
if (typeof key !== 'string') return false;
if (this.#facts.has(key)) return true;
return this.get(key) !== undefined;
}
/**
* Returns full fact record including value and provenance metadata.
* @param {string} key
* @returns {{ value: any, source: string, timestamp: number }|null}
*/
getFact(key) {
if (typeof key !== 'string') return null;
if (this.#facts.has(key)) {
const rec = this.#facts.get(key);
return {
value: (rec.value !== null && typeof rec.value === 'object') ? structuredClone(rec.value) : rec.value,
source: rec.source,
timestamp: rec.timestamp
};
}
if (key.includes('.')) {
const parts = key.split('.');
for (let i = parts.length - 1; i >= 1; i--) {
const prefix = parts.slice(0, i).join('.');
if (this.#facts.has(prefix)) {
const rootRec = this.#facts.get(prefix);
const subVal = getNested(rootRec.value, parts.slice(i));
if (subVal !== undefined) {
return {
value: (subVal !== null && typeof subVal === 'object') ? structuredClone(subVal) : subVal,
source: rootRec.source,
timestamp: rootRec.timestamp
};
}
}
}
}
return null;
}
/**
* Returns provenance metadata for a fact.
* @param {string} key
* @returns {{ source: string, timestamp: number }|null}
*/
getProvenance(key) {
const fact = this.getFact(key);
return fact ? { source: fact.source, timestamp: fact.timestamp } : null;
}
/**
* Deletes a fact and notifies listeners.
* @param {string} key
* @param {string|object} [provenance]
* @returns {boolean}
*/
delete(key, provenance = null) {
if (typeof key !== 'string' || !this.#facts.has(key)) return false;
const oldRec = this.#facts.get(key);
const prov = normalizeProvenance(provenance);
this.#facts.delete(key);
this._notifyChange(key, undefined, oldRec.value, prov);
return true;
}
/**
* Clears all facts.
*/
clear() {
this.#facts.clear();
}
/**
* Returns an array of stored fact keys.
* @returns {string[]}
*/
keys() {
return Array.from(this.#facts.keys());
}
/**
* Returns an array of `[key, value]` entries.
* @returns {Array<Array>}
*/
entries() {
return Array.from(this.#facts.entries()).map(([k, rec]) => [
k,
(rec.value !== null && typeof rec.value === 'object') ? structuredClone(rec.value) : rec.value
]);
}
/**
* Returns a plain object representation of all stored facts.
* @returns {Record<string, any>}
*/
toObject() {
const obj = {};
for (const [k, rec] of this.#facts.entries()) {
obj[k] = (rec.value !== null && typeof rec.value === 'object') ? structuredClone(rec.value) : rec.value;
}
return obj;
}
/**
* Returns all authoritative records with provenance.
* @returns {Record<string, { value: any, source: string, timestamp: number }>}
*/
allFacts() {
const result = {};
for (const [k, rec] of this.#facts.entries()) {
result[k] = {
value: (rec.value !== null && typeof rec.value === 'object') ? structuredClone(rec.value) : rec.value,
source: rec.source,
timestamp: rec.timestamp
};
}
return result;
}
/**
* Registers a change listener with pattern filtering and clean unbind.
* - `onChange(callback)`: global listener (key, newValue, oldValue, provenance)
* - `onChange(pattern, callback)`: filtered listener (newValue, oldValue, provenance, key)
* @param {string|Function} patternOrCallback
* @param {Function} [maybeCallback]
* @returns {Function} Unbind function
*/
onChange(patternOrCallback, maybeCallback) {
let pattern = null;
let callback = null;
if (typeof patternOrCallback === 'function') {
callback = patternOrCallback;
} else if (typeof patternOrCallback === 'string' && typeof maybeCallback === 'function') {
pattern = patternOrCallback;
callback = maybeCallback;
} else {
throw new TypeError('Invalid arguments for onChange: expected (callback) or (pattern, callback)');
}
const listenerRecord = {
pattern,
callback,
isRemoved: false
};
this.#listeners.add(listenerRecord);
const unbind = () => {
if (listenerRecord.isRemoved) return;
listenerRecord.isRemoved = true;
this.#listeners.delete(listenerRecord);
};
listenerRecord.unbind = unbind;
return unbind;
}
/**
* Explicit unbind for a listener or unbind function.
* @param {Function} unbindOrCallback
*/
offChange(unbindOrCallback) {
if (typeof unbindOrCallback !== 'function') return false;
for (const record of this.#listeners) {
if (record.unbind === unbindOrCallback || record.callback === unbindOrCallback) {
record.unbind();
return true;
}
}
return false;
}
/**
* Internal change notification.
* @private
*/
_notifyChange(key, newValue, oldValue, provenance) {
if (this.#listeners.size === 0) return;
const snapshot = Array.from(this.#listeners);
for (const listener of snapshot) {
if (listener.isRemoved) continue;
if (!listener.pattern) {
// Global listener: (key, newValue, oldValue, provenance)
listener.callback(key, newValue, oldValue, provenance);
} else if (matchesPattern(listener.pattern, key)) {
// Pattern listener: (newValue, oldValue, provenance, key)
listener.callback(newValue, oldValue, provenance, key);
}
}
}
/**
* Creates a deep-cloned, serializable snapshot for save games.
* @returns {{ version: number, timestamp: number, facts: Record<string, { value: any, source: string, timestamp: number }> }}
*/
snapshot() {
const factsObj = {};
for (const [key, record] of this.#facts.entries()) {
factsObj[key] = {
value: (record.value !== null && typeof record.value === 'object')
? structuredClone(record.value)
: record.value,
source: record.source,
timestamp: record.timestamp
};
}
return {
version: 1,
timestamp: Date.now(),
facts: factsObj
};
}
/**
* Restores state from a snapshot.
* @param {object} snapshot
* @param {object} [options]
* @returns {this}
*/
restore(snapshot, { clearExisting = true, notify = false } = {}) {
if (!snapshot || typeof snapshot !== 'object') {
throw new TypeError('Snapshot must be an object');
}
if (clearExisting) {
this.#facts.clear();
}
const rawFacts = (snapshot.facts && typeof snapshot.facts === 'object' && !Array.isArray(snapshot.facts))
? snapshot.facts
: snapshot;
for (const [key, entry] of Object.entries(rawFacts)) {
if (snapshot.facts && (key === 'version' || key === 'timestamp')) {
continue;
}
let value;
let provenance;
if (entry && typeof entry === 'object' && 'value' in entry && 'source' in entry) {
value = (entry.value !== null && typeof entry.value === 'object')
? structuredClone(entry.value)
: entry.value;
provenance = {
source: entry.source,
timestamp: typeof entry.timestamp === 'number' ? entry.timestamp : Date.now()
};
} else {
value = (entry !== null && typeof entry === 'object')
? structuredClone(entry)
: entry;
provenance = { source: 'restore', timestamp: Date.now() };
}
this.#facts.set(key, {
value,
source: provenance.source,
timestamp: provenance.timestamp
});
if (notify) {
this._notifyChange(key, value, undefined, provenance);
}
}
return this;
}
}
/**
* Prioritized event dispatcher handling self-removing listeners,
* bounded recursive events, duplicate guards, once-only subscriptions,
* and clean unbind.
*/
export class TypedEventBus {
#listeners = new Map(); // eventType -> Array<ListenerRecord>
#depth = 0;
#eventDepths = new Map();
#orderSeq = 0;
/**
* @param {object} [options]
*/
constructor({ maxRecursionDepth = 32, guardDuplicates = true } = {}) {
this.maxRecursionDepth = maxRecursionDepth;
this.guardDuplicates = guardDuplicates;
}
/**
* Subscribes a prioritized listener to an event type.
* @param {string|symbol} eventType
* @param {Function} listener
* @param {number|object} [options]
* @returns {Function} Idempotent unbind function
*/
on(eventType, listener, options = {}) {
if (typeof eventType !== 'string' && typeof eventType !== 'symbol') {
throw new TypeError('Event type must be a string or symbol');
}
if (typeof listener !== 'function') {
throw new TypeError('Listener must be a function');
}
const opts = typeof options === 'number' ? { priority: options } : (options || {});
const priority = Number.isFinite(opts.priority) ? Number(opts.priority) : 0;
const once = Boolean(opts.once);
const id = opts.id || null;
const shouldGuardDuplicates = opts.guardDuplicates !== undefined
? Boolean(opts.guardDuplicates)
: this.guardDuplicates;
if (!this.#listeners.has(eventType)) {
this.#listeners.set(eventType, []);
}
const list = this.#listeners.get(eventType);
if (shouldGuardDuplicates) {
const existing = list.find(r => !r.isRemoved && (r.fn === listener || (id !== null && r.id === id)));
if (existing) {
return existing.unbind;
}
}
let record;
const unbind = () => {
if (record.isRemoved) return;
record.isRemoved = true;
const currentList = this.#listeners.get(eventType);
if (currentList) {
const idx = currentList.indexOf(record);
if (idx !== -1) {
currentList.splice(idx, 1);
}
if (currentList.length === 0) {
this.#listeners.delete(eventType);
}
}
};
record = {
fn: listener,
priority,
once,
id,
isRemoved: false,
order: ++this.#orderSeq,
unbind
};
list.push(record);
list.sort((a, b) => b.priority - a.priority || a.order - b.order);
return unbind;
}
/**
* Subscribes a listener that runs at most once.
* @param {string|symbol} eventType
* @param {Function} listener
* @param {number|object} [options]
* @returns {Function}
*/
once(eventType, listener, options = {}) {
const opts = typeof options === 'number' ? { priority: options } : { ...(options || {}) };
opts.once = true;
return this.on(eventType, listener, opts);
}
/**
* Unsubscribes a listener by function reference or registration ID.
* @param {string|symbol} eventType
* @param {Function|string} listenerOrId
* @returns {boolean}
*/
off(eventType, listenerOrId) {
const list = this.#listeners.get(eventType);
if (!list || list.length === 0) return false;
let removed = false;
for (let i = list.length - 1; i >= 0; i--) {
const r = list[i];
if (r.fn === listenerOrId || (typeof listenerOrId === 'string' && r.id === listenerOrId)) {
r.unbind();
removed = true;
}
}
return removed;
}
/**
* Emits an event with prioritized dispatch, recursion bounding,
* self-removal safety, and stopPropagation support.
* @param {string|symbol} eventType
* @param {any} [data={}]
* @returns {{ stopped: boolean, count: number, defaultPrevented: boolean }}
*/
emit(eventType, data = {}) {
const currentEvent = this.#eventDepths.get(eventType) || 0;
if (currentEvent >= this.maxRecursionDepth) {
throw new RangeError(
`Event recursion depth exceeded maximum limit of ${this.maxRecursionDepth} for event "${String(eventType)}"`
);
}
this.#depth++;
this.#eventDepths.set(eventType, currentEvent + 1);
try {
const list = this.#listeners.get(eventType);
if (!list || list.length === 0) {
return { stopped: false, count: 0, defaultPrevented: false };
}
// Snapshot listeners array for safe traversal with self-removing listeners
const snapshot = list.slice();
let stopped = false;
let prevented = false;
const originalStopPropagation = (data && typeof data === 'object' && typeof data.stopPropagation === 'function')
? data.stopPropagation.bind(data)
: null;
const originalPreventDefault = (data && typeof data === 'object' && typeof data.preventDefault === 'function')
? data.preventDefault.bind(data)
: null;
const stopPropagation = () => {
stopped = true;
if (originalStopPropagation) {
originalStopPropagation();
}
};
const preventDefault = () => {
prevented = true;
if (originalPreventDefault) {
originalPreventDefault();
}
};
const eventContext = {
type: eventType,
data,
stopPropagation,
preventDefault,
get isPropagationStopped() {
return stopped || Boolean(data?.isPropagationStopped?.());
},
get defaultPrevented() {
return prevented || Boolean(data?.defaultPrevented);
}
};
if (data && typeof data === 'object') {
if (typeof data.stopPropagation !== 'function') {
try {
Object.defineProperty(data, 'stopPropagation', {
value: stopPropagation,
writable: true,
configurable: true
});
} catch (_) {}
}
if (typeof data.isPropagationStopped !== 'function') {
try {
Object.defineProperty(data, 'isPropagationStopped', {
value: () => stopped,
writable: true,
configurable: true
});
} catch (_) {}
}
}
let invokedCount = 0;
for (let i = 0; i < snapshot.length; i++) {
const record = snapshot[i];
if (record.isRemoved) {
continue;
}
if (stopped || data?.isPropagationStopped?.()) {
break;
}
if (record.once) {
record.unbind();
}
invokedCount++;
const result = record.fn(data, eventContext);
if (result && typeof result === 'object' && result.stopPropagation) {
stopPropagation();
}
}
return {
stopped: stopped || Boolean(data?.isPropagationStopped?.()),
count: invokedCount,
defaultPrevented: prevented
};
} finally {
this.#depth--;
const count = (this.#eventDepths.get(eventType) || 1) - 1;
if (count <= 0) {
this.#eventDepths.delete(eventType);
} else {
this.#eventDepths.set(eventType, count);
}
}
}
/**
* Returns the count of active listeners for an event type (or all events).
* @param {string|symbol} [eventType]
* @returns {number}
*/
listenerCount(eventType) {
if (eventType !== undefined) {
const list = this.#listeners.get(eventType);
return list ? list.filter(r => !r.isRemoved).length : 0;
}
let total = 0;
for (const list of this.#listeners.values()) {
total += list.filter(r => !r.isRemoved).length;
}
return total;
}
/**
* Checks if there are any active listeners for an event type.
* @param {string|symbol} eventType
* @returns {boolean}
*/
hasListeners(eventType) {
return this.listenerCount(eventType) > 0;
}
/**
* Clears listeners for a given event type or all listeners if omitted.
* @param {string|symbol} [eventType]
*/
clear(eventType) {
if (eventType !== undefined) {
const list = this.#listeners.get(eventType);
if (list) {
for (const r of list) {
r.isRemoved = true;
}
this.#listeners.delete(eventType);
}
} else {
for (const list of this.#listeners.values()) {
for (const r of list) {
r.isRemoved = true;
}
}
this.#listeners.clear();
}
}
}
/**
* Ordered condition/effect rule evaluator connecting WorldFacts and TypedEventBus
* with priority order, condition checks, action execution, stopPropagation support,
* and decision trace logging.
*/
export class RuleEngine {
#rules = new Map();
#eventSubscriptions = new Map();
#traces = [];
#traceSeq = 0;
#ruleSeq = 0;
/**
* @param {WorldFacts|object} [optionsOrFacts]
* @param {TypedEventBus} [maybeBus]
* @param {object} [maybeOptions]
*/
constructor(optionsOrFacts = {}, maybeBus = null, maybeOptions = {}) {
let facts;
let bus;
let options;
if (optionsOrFacts instanceof WorldFacts) {
facts = optionsOrFacts;
bus = maybeBus instanceof TypedEventBus ? maybeBus : new TypedEventBus();
options = maybeOptions || {};
} else if (optionsOrFacts && typeof optionsOrFacts === 'object') {
facts = optionsOrFacts.facts instanceof WorldFacts ? optionsOrFacts.facts : new WorldFacts();
bus = optionsOrFacts.bus instanceof TypedEventBus ? optionsOrFacts.bus : new TypedEventBus();
options = optionsOrFacts;
} else {
facts = new WorldFacts();
bus = new TypedEventBus();
options = {};
}
this.facts = facts;
this.bus = bus;
this.maxTraces = typeof options.maxTraces === 'number' ? options.maxTraces : 1000;
this.enableTracing = options.enableTracing !== false;
}
/**
* Total number of registered rules.
* @returns {number}
*/
get ruleCount() {
return this.#rules.size;
}
/**
* Adds an ordered condition/effect rule.
* @param {object} ruleDef
* @param {string} [ruleDef.id] Unique rule identifier
* @param {string} [ruleDef.name] Human readable name
* @param {number} [ruleDef.priority=0] Higher executes first
* @param {string|string[]} [ruleDef.event] Event(s) to bind on TypedEventBus
* @param {Function|boolean} [ruleDef.condition] Condition check
* @param {Function} [ruleDef.action] Action effect
* @param {boolean} [ruleDef.stopPropagation=false] If true, halts further rules/listeners on execution
* @param {boolean} [ruleDef.enabled=true]
* @returns {Function} Unbind function
*/
addRule(ruleDef) {
if (!ruleDef || typeof ruleDef !== 'object') {
throw new TypeError('Rule definition must be an object');
}
const id = (typeof ruleDef.id === 'string' && ruleDef.id.trim())
? ruleDef.id.trim()
: `rule_${++this.#ruleSeq}`;
if (this.#rules.has(id)) {
this.removeRule(id);
}
const priority = Number.isFinite(ruleDef.priority) ? Number(ruleDef.priority) : 0;
const condition = typeof ruleDef.condition === 'function'
? ruleDef.condition
: (typeof ruleDef.when === 'function'
? ruleDef.when
: (ruleDef.condition !== undefined ? () => Boolean(ruleDef.condition) : () => true));
const action = typeof ruleDef.action === 'function'
? ruleDef.action
: (typeof ruleDef.effect === 'function'
? ruleDef.effect
: (typeof ruleDef.then === 'function' ? ruleDef.then : null));
const ruleRecord = {
id,
name: ruleDef.name || ruleDef.description || id,
priority,
event: ruleDef.event || ruleDef.on || null,
condition,
action,
stopPropagation: Boolean(ruleDef.stopPropagation),
enabled: ruleDef.enabled !== false,
order: ++this.#ruleSeq
};
this.#rules.set(id, ruleRecord);
// Bind event listeners if event(s) specified
const unbindSubscriptions = [];
if (ruleRecord.event) {
const events = Array.isArray(ruleRecord.event) ? ruleRecord.event : [ruleRecord.event];
for (const evt of events) {
if (typeof evt === 'string' && evt.trim()) {
const unbindBus = this.bus.on(evt, (data, eventContext) => {
if (!ruleRecord.enabled) return;
let stopped = false;
const stop = () => {
stopped = true;
eventContext.stopPropagation();
};
const executionContext = {
facts: this.facts,
bus: this.bus,
event: data,
data,
eventType: evt,
rule: ruleRecord,
stopPropagation: stop,
trace: (details) => this._logTrace({
ruleId: id,
priority,
eventType: evt,
conditionMatched: true,
actionExecuted: true,
stoppedPropagation: stopped,
details
})
};
let matched = false;
let executed = false;
let error = null;
try {
matched = Boolean(condition(executionContext));
} catch (err) {
error = err;
this._logTrace({
ruleId: id,
priority,
eventType: evt,
conditionMatched: false,
actionExecuted: false,
stoppedPropagation: false,
error
});
throw err;
}
if (matched) {
if (action) {
try {
const result = action(executionContext);
executed = true;
if (result && typeof result === 'object' && result.stopPropagation) {
stop();
}
} catch (err) {
error = err;
this._logTrace({
ruleId: id,
priority,
eventType: evt,
conditionMatched: true,
actionExecuted: false,
stoppedPropagation: stopped || ruleRecord.stopPropagation,
error
});
throw err;
}
} else {
executed = true;
}
if (ruleRecord.stopPropagation) {
stop();
}
}
this._logTrace({
ruleId: id,
priority,
eventType: evt,
conditionMatched: matched,
actionExecuted: executed,
stoppedPropagation: stopped || (matched && ruleRecord.stopPropagation),
error: null
});
}, { priority, id: `rule:${id}:${evt}` });
unbindSubscriptions.push(unbindBus);
}
}
}
this.#eventSubscriptions.set(id, unbindSubscriptions);
const unbind = () => {
this.removeRule(id);
};
ruleRecord.unbind = unbind;
return unbind;
}
/**
* Removes a rule and cleans up all its event bus subscriptions.
* @param {string} ruleId
* @returns {boolean}
*/
removeRule(ruleId) {
const rule = this.#rules.get(ruleId);
if (!rule) return false;
const subs = this.#eventSubscriptions.get(ruleId);
if (subs) {
for (const unbind of subs) {
try { unbind(); } catch (_) {}
}
this.#eventSubscriptions.delete(ruleId);
}
this.#rules.delete(ruleId);
return true;
}
/**
* Returns a rule definition by ID.
* @param {string} ruleId
* @returns {object|null}
*/
getRule(ruleId) {
return this.#rules.get(ruleId) || null;
}
/**
* Checks if a rule is registered.
* @param {string} ruleId
* @returns {boolean}
*/
hasRule(ruleId) {
return this.#rules.has(ruleId);
}
/**
* Enables a rule.
* @param {string} ruleId
*/
enableRule(ruleId) {
const rule = this.#rules.get(ruleId);
if (rule) rule.enabled = true;
}
/**
* Disables a rule.
* @param {string} ruleId
*/
disableRule(ruleId) {
const rule = this.#rules.get(ruleId);
if (rule) rule.enabled = false;
}
/**
* Evaluates matching rules in priority order against facts and event data.
* @param {string|null} [eventType=null]
* @param {any} [eventData={}]
* @param {object} [options]
* @returns {{ matchedCount: number, executedCount: number, stoppedPropagation: boolean }}
*/
evaluate(eventType = null, eventData = {}, options = {}) {
const matching = [];
for (const rule of this.#rules.values()) {
if (!rule.enabled) continue;
if (eventType !== null && rule.event !== null) {
const events = Array.isArray(rule.event) ? rule.event : [rule.event];
if (!events.includes(eventType)) continue;
}
matching.push(rule);
}
matching.sort((a, b) => b.priority - a.priority || a.order - b.order);
let stopped = false;
let matchedCount = 0;
let executedCount = 0;
const stop = () => {
stopped = true;
};
for (const rule of matching) {
if (stopped) break;
const executionContext = {
facts: this.facts,
bus: this.bus,
event: eventData,
data: eventData,
eventType,
rule,
stopPropagation: stop,
trace: (details) => this._logTrace({
ruleId: rule.id,
priority: rule.priority,
eventType,
conditionMatched: true,
actionExecuted: true,
stoppedPropagation: stopped,
details
})
};
let matched = false;
let executed = false;
let error = null;
try {
matched = Boolean(rule.condition(executionContext));
} catch (err) {
error = err;
this._logTrace({
ruleId: rule.id,
priority: rule.priority,
eventType,
conditionMatched: false,
actionExecuted: false,
stoppedPropagation: false,
error
});
if (options.rethrow !== false) throw err;
continue;
}
if (matched) {
matchedCount++;
if (rule.action) {
try {
const result = rule.action(executionContext);
executed = true;
executedCount++;
if (result && typeof result === 'object' && result.stopPropagation) {
stop();
}
} catch (err) {
error = err;
this._logTrace({
ruleId: rule.id,
priority: rule.priority,
eventType,
conditionMatched: true,
actionExecuted: false,
stoppedPropagation: stopped || rule.stopPropagation,
error
});
if (options.rethrow !== false) throw err;
continue;
}
} else {
executed = true;
executedCount++;
}
if (rule.stopPropagation) {
stop();
}
}
this._logTrace({
ruleId: rule.id,
priority: rule.priority,
eventType,
conditionMatched: matched,
actionExecuted: executed,
stoppedPropagation: stopped || (matched && rule.stopPropagation),
error: null
});
}
return {
matchedCount,
executedCount,
stoppedPropagation: stopped
};
}
/**
* Internal decision trace logger.
* @private
*/
_logTrace(entry) {
if (!this.enableTracing) return null;
const trace = {
id: ++this.#traceSeq,
timestamp: Date.now(),
ruleId: entry.ruleId,
priority: entry.priority,
eventType: entry.eventType || null,
conditionMatched: Boolean(entry.conditionMatched),
actionExecuted: Boolean(entry.actionExecuted),
stoppedPropagation: Boolean(entry.stoppedPropagation),
error: entry.error || null,
details: entry.details || null
};
this.#traces.push(trace);
if (this.#traces.length > this.maxTraces) {
this.#traces.shift();
}
return trace;
}
/**
* Retrieves recorded decision traces with optional filtering.
* @param {object} [filter]
* @returns {Array<object>}
*/
getDecisionTraces(filter = {}) {
let list = this.#traces.slice();
if (filter.ruleId) {
list = list.filter(t => t.ruleId === filter.ruleId);
}
if (filter.eventType) {
list = list.filter(t => t.eventType === filter.eventType);
}
if (filter.matched !== undefined) {
list = list.filter(t => t.conditionMatched === filter.matched);
}
if (filter.executed !== undefined) {
list = list.filter(t => t.actionExecuted === filter.executed);
}
if (typeof filter.limit === 'number' && filter.limit > 0) {
list = list.slice(-filter.limit);
}
return list;
}
/**
* Returns the most recent decision trace.
* @returns {object|null}
*/
getLastDecisionTrace() {
return this.#traces.length > 0 ? { ...this.#traces[this.#traces.length - 1] } : null;
}
/**
* Clears all recorded decision traces.
*/
clearDecisionTraces() {
this.#traces = [];
}
/**
* Unbinds and clears all registered rules.
*/
clearRules() {
for (const ruleId of Array.from(this.#rules.keys())) {
this.removeRule(ruleId);
}
}
/**
* Cleans up all rules and decision traces.
*/
dispose() {
this.clearRules();
this.clearDecisionTraces();
}
}