@rsconcept/domain 1.0.0

package/src/library/rsengine.ts

@@ -0,0 +1,593 @@
+import { type AstNode } from '../parsing';
+import { type CalculatorEvaluateOptions, type CalculatorResult, RSCalculator, TypeID, type Value } from '../rslang';
+import { compare } from '../rslang/eval/value';
+import { normalizeType } from '../rslang/labels';
+
+import { CstType, type RSForm } from './rsform';
+import { getAnalysisFor, isBaseSet, isBasicConcept, isFunctional } from './rsform-api';
+import { type BasicBinding, type BasicsContext, type EvalStatus, type RSModel, TYPE_BASIC } from './rsmodel';
+import { inferEvalStatus, isInferrable, tryFixValue } from './rsmodel-api';
+
+const INVALID_TYPE_MARKER = 'INVALID';
+
+/** Services for {@link RSEngine}. */
+export interface RSEngineServices {
+  setCstValue: (args: {
+    itemID: number;
+    data: { target: number; type: string; data: Value | BasicBinding }[];
+  }) => Promise<unknown>;
+  clearValues: (args: { itemID: number; data: { items: number[] } }) => Promise<unknown>;
+}
+
+/** Notifications for {@link RSEngine}. */
+export interface RSEngineNotifications {
+  onInvalidSetValue: () => void;
+  onCalculationSuccess: (timeSpent: string) => void;
+  onEvaluationError: (message: string) => void;
+}
+
+/** Calculation engine for {@link RSModel}. */
+export class RSEngine {
+  public modelID: number;
+  public schema: RSForm | null = null;
+  public data: RSModel | null = null;
+  public calculator = new RSCalculator();
+  public basics: BasicsContext = new Map<number, BasicBinding>();
+
+  private services: RSEngineServices;
+  private notifications: RSEngineNotifications | null;
+  private invalidData = new Set<number>();
+  private calculatedSet = new Set<number>();
+  private valueSubscribers = new Map<number, Set<() => void>>();
+  private statusSubscribers = new Map<number, Set<() => void>>();
+  private changeSubscribers = new Set<() => void>();
+  private changeGeneration = 0;
+  private pendingChange = false;
+  private coalescedEmitTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(modelID: number, services: RSEngineServices, notifications: RSEngineNotifications | null = null) {
+    this.services = services;
+    this.notifications = notifications;
+    this.modelID = modelID;
+  }
+
+  /** Updates data for {@link RSEngine}. */
+  public loadData(schema: RSForm, model: RSModel): void {
+    const oldSchema = this.schema;
+    const newSchema = oldSchema !== schema;
+    this.schema = schema;
+    if (newSchema) {
+      const changedCst = this.collectChanged(oldSchema, schema);
+      this.prepareAst();
+      this.setupEmptySets();
+      this.onChangeDefinitions(changedCst);
+    }
+    if (this.data !== model) {
+      this.data = model;
+      this.prepareValues();
+    }
+    this.notifyAll();
+  }
+
+  /** Updates services for {@link RSEngine}. */
+  public updateServices(services: RSEngineServices): void {
+    this.services = services;
+  }
+
+  /** Updates notifications for {@link RSEngine}. */
+  public updateNotifications(notifications: RSEngineNotifications | null): void {
+    this.notifications = notifications;
+  }
+
+  /** Gets value of {@link Constituenta}. */
+  public getCstValue(cstID: number): Value | null {
+    const cst = this.schema?.cstByID.get(cstID);
+    if (!cst) {
+      return null;
+    }
+    return this.calculator.getValue(cst.alias);
+  }
+
+  /** Gets status of {@link Constituenta}. */
+  public getCstStatus(cstID: number): EvalStatus {
+    const cst = this.schema?.cstByID.get(cstID);
+    if (!cst) {
+      return inferEvalStatus(null, CstType.NOMINAL, false);
+    }
+    const value = this.calculator.getValue(cst.alias);
+    return inferEvalStatus(value, cst.cst_type, this.calculatedSet.has(cstID), this.invalidData.has(cstID));
+  }
+
+  /** Subscribe to value change of {@link Constituenta}. */
+  public subscribeValue(cstID: number, callbackFn: () => void): () => void {
+    let subs = this.valueSubscribers.get(cstID);
+    if (!subs) {
+      subs = new Set();
+      this.valueSubscribers.set(cstID, subs);
+    }
+    subs.add(callbackFn);
+    return () => {
+      const current = this.valueSubscribers.get(cstID);
+      if (!current) {
+        return;
+      }
+      current.delete(callbackFn);
+      if (current.size === 0) {
+        this.valueSubscribers.delete(cstID);
+      }
+    };
+  }
+
+  /** Subscribe to status change of {@link Constituenta}. */
+  public subscribeStatus(cstID: number, callbackFn: () => void): () => void {
+    let subs = this.statusSubscribers.get(cstID);
+    if (!subs) {
+      subs = new Set();
+      this.statusSubscribers.set(cstID, subs);
+    }
+    subs.add(callbackFn);
+    return () => {
+      const current = this.statusSubscribers.get(cstID);
+      if (!current) {
+        return;
+      }
+      current.delete(callbackFn);
+      if (current.size === 0) {
+        this.statusSubscribers.delete(cstID);
+      }
+    };
+  }
+
+  /**
+   * Subscribe to any engine change that can affect evaluation (values, status, or loaded data).
+   */
+  public subscribeChanges(callbackFn: () => void): () => void {
+    this.changeSubscribers.add(callbackFn);
+    return () => {
+      this.changeSubscribers.delete(callbackFn);
+    };
+  }
+
+  /** Monotonic counter bumped whenever the engine emits a change to {@link RSEngine.subscribeChanges} listeners. */
+  public getChangeGeneration(): number {
+    return this.changeGeneration;
+  }
+
+  /**
+   * Runs pending {@link RSEngine.subscribeChanges} notifications immediately and clears the coalescing queue.
+   * Use after a synchronous batch of engine updates when listeners must observe a bumped {@link getChangeGeneration}
+   * in the same turn.
+   */
+  public flushPendingChanges(): void {
+    if (this.coalescedEmitTimeout !== null) {
+      clearTimeout(this.coalescedEmitTimeout);
+      this.coalescedEmitTimeout = null;
+    }
+    if (!this.pendingChange) {
+      return;
+    }
+    this.pendingChange = false;
+    this.emitChange();
+  }
+
+  /** Sets value for {@link Constituenta} from {@link Value}. */
+  public async setStructureValue(cstID: number, data: Value): Promise<void> {
+    const cst = this.schema?.cstByID.get(cstID);
+    if (!this.schema || !cst || isInferrable(cst.cst_type)) {
+      this.notifications?.onInvalidSetValue();
+      return;
+    }
+
+    const typeStr = cst.effectiveType ? normalizeType(cst.effectiveType) : INVALID_TYPE_MARKER;
+    const payload = [{ target: cstID, type: typeStr, data }];
+    await this.services.setCstValue({ itemID: this.modelID, data: payload });
+
+    if (!cst.effectiveType || !this.calculator.validate(data, cst.effectiveType)) {
+      this.invalidData.add(cstID);
+    } else {
+      this.invalidData.delete(cstID);
+    }
+    this.calculator.setValue(cst.alias, data);
+    this.notifyCst(cstID);
+    this.cascadeReset([cstID]);
+  }
+
+  /** Sets value for {@link Constituenta} from {@link BasicBinding}. */
+  public async setBasicValue(cstID: number, data: BasicBinding): Promise<void> {
+    const cst = this.schema?.cstByID.get(cstID);
+    if (!this.schema || !cst || !isBaseSet(cst.cst_type)) {
+      this.notifications?.onInvalidSetValue();
+      return;
+    }
+    const oldValue = this.calculator.getValue(cst.alias);
+    const newValue = Object.keys(data).map(Number);
+
+    const updateList: Parameters<RSEngineServices['setCstValue']>[0]['data'] = [
+      { target: cstID, type: TYPE_BASIC, data }
+    ];
+    const resetList: number[] = [];
+
+    if (oldValue !== null && compare(newValue, oldValue) !== 0) {
+      const dependencies = this.schema.graph.expandAllOutputs([cstID]);
+      for (const childID of dependencies) {
+        const child = this.schema.cstByID.get(childID)!;
+        if (child.cst_type === CstType.STRUCTURED && !!child.effectiveType) {
+          const value = this.calculator.getValue(child.alias);
+          if (value !== null) {
+            const fix = tryFixValue(value, child.effectiveType, cst.alias, newValue);
+            if (fix === null) {
+              resetList.push(childID);
+            } else if (fix === true) {
+              const typeStr = normalizeType(child.effectiveType);
+              updateList.push({ target: childID, type: typeStr, data: [...(value as Value[])] });
+            }
+          }
+        }
+      }
+    }
+
+    if (resetList.length > 0) {
+      await Promise.all([
+        this.services.setCstValue({ itemID: this.modelID, data: updateList }),
+        this.services.clearValues({ itemID: this.modelID, data: { items: resetList } })
+      ]);
+    } else {
+      await this.services.setCstValue({ itemID: this.modelID, data: updateList });
+    }
+    const changed = [...resetList, ...updateList.map(item => item.target)];
+
+    this.basics.set(cstID, data);
+    this.calculator.setValue(cst.alias, Object.keys(data).map(Number));
+
+    for (const item of resetList) {
+      this.calculator.resetValue(this.schema.cstByID.get(item)!.alias);
+      this.notifyCst(item);
+    }
+    for (const updateData of updateList) {
+      if (updateData.target !== cstID) {
+        this.calculator.setValue(
+          this.schema.cstByID.get(updateData.target)!.alias,
+          updateData.data as unknown as Value
+        );
+        this.notifyCst(updateData.target);
+      }
+    }
+    for (const item of changed) {
+      this.notifyCst(item);
+    }
+    this.cascadeReset(changed);
+  }
+
+  /** Resets value for {@link Constituenta}. */
+  public async resetValue(cstID: number): Promise<void> {
+    const cst = this.schema?.cstByID.get(cstID);
+    if (!cst) {
+      return;
+    }
+    await this.services.clearValues({ itemID: this.modelID, data: { items: [cstID] } });
+    this.calculator.resetValue(cst.alias);
+    this.basics.delete(cstID);
+    this.calculatedSet.delete(cstID);
+    this.invalidData.delete(cstID);
+    this.notifyCst(cstID);
+  }
+
+  /** Evaluates expression for {@link RSEngine}. */
+  public evaluateExpression(expression: string, cstType: CstType): CalculatorResult {
+    return getEvaluationFor(expression, cstType, this.schema!, this.calculator, message =>
+      this.notifications?.onEvaluationError(message)
+    );
+  }
+
+  /** Evaluates AST for {@link RSEngine}. */
+  public evaluateAst(ast: AstNode, options?: CalculatorEvaluateOptions): CalculatorResult {
+    try {
+      const evaluation = this.calculator.evaluateFull(ast, options);
+      return evaluation;
+    } catch (error) {
+      this.notifications?.onEvaluationError((error as Error).message);
+      console.error(error);
+      return {
+        value: null,
+        iterations: 0,
+        cacheHits: 0,
+        errors: []
+      };
+    }
+  }
+
+  /** Calculates value for {@link Constituenta}. */
+  public calculateCst(cstID: number): CalculatorResult {
+    const cst = this.schema?.cstByID.get(cstID);
+    if (!cst || !this.schema) {
+      return { value: null, iterations: 0, errors: [], cacheHits: 0 };
+    }
+
+    if (!this.calculatedSet.has(cstID)) {
+      const predecessors = this.schema.graph.expandAllInputs([cstID]);
+      this.prepareEvaluation(predecessors);
+    }
+    const result = getEvaluationFor(cst.definition_formal, cst.cst_type, this.schema, this.calculator, message =>
+      this.notifications?.onEvaluationError(message)
+    );
+
+    if (result.value === null) {
+      this.calculator.resetValue(cst.alias);
+    } else {
+      this.calculator.setValue(cst.alias, result.value);
+    }
+
+    this.calculatedSet.add(cstID);
+    this.notifyCst(cstID);
+
+    return result;
+  }
+
+  /** Recalculate model for all inferrable expressions. */
+  recalculateAll(): void {
+    const start = performance.now();
+    this.calculatedSet.clear();
+    this.recalculateInternal();
+    const end = performance.now();
+    const timeSpent = ((end - start) / 1000).toFixed(2);
+    this.notifications?.onCalculationSuccess(timeSpent);
+  }
+
+  /** Notify subscribers about value and status change of {@link Constituenta}. */
+  private notifyCst(cstID: number) {
+    this.notifyStatus(cstID);
+    this.notifyValue(cstID);
+    this.scheduleCoalescedEmitChange();
+  }
+
+  /** Notify all subscribers about value change. */
+  private notifyValue(cstID: number) {
+    const subs = this.valueSubscribers.get(cstID);
+    if (subs) {
+      for (const cb of subs) cb();
+    }
+  }
+
+  /** Notify all subscribers about status change. */
+  private notifyStatus(cstID: number) {
+    const subs = this.statusSubscribers.get(cstID);
+    if (subs) {
+      for (const cb of subs) cb();
+    }
+  }
+
+  /** Notify all subscribers about value and status change. */
+  private notifyAll(): void {
+    for (const subs of this.valueSubscribers.values()) {
+      for (const cb of subs) cb();
+    }
+    for (const subs of this.statusSubscribers.values()) {
+      for (const cb of subs) cb();
+    }
+    this.scheduleCoalescedEmitChange();
+  }
+
+  private scheduleCoalescedEmitChange(): void {
+    this.pendingChange = true;
+    if (this.coalescedEmitTimeout !== null) {
+      return;
+    }
+    this.coalescedEmitTimeout = setTimeout(
+      function runCoalescedEmitChange(this: RSEngine) {
+        this.coalescedEmitTimeout = null;
+        if (!this.pendingChange) {
+          return;
+        }
+        this.pendingChange = false;
+        this.emitChange();
+      }.bind(this),
+      0
+    );
+  }
+
+  private emitChange(): void {
+    this.changeGeneration += 1;
+    for (const cb of this.changeSubscribers) {
+      cb();
+    }
+  }
+
+  private prepareAst(): void {
+    this.calculator.clearAllAst();
+    const functions = this.schema!.items.filter(cst => isFunctional(cst.cst_type) && cst.analysis?.success);
+    for (const cst of functions) {
+      const fullAnalysis = getAnalysisFor(cst.definition_formal, cst.cst_type, this.schema!);
+      if (fullAnalysis.ast) {
+        this.calculator.setAST(cst.alias, fullAnalysis.ast);
+      }
+    }
+  }
+
+  private prepareValues(): void {
+    this.basics.clear();
+    this.invalidData.clear();
+    this.calculatedSet.clear();
+
+    for (const item of this.data!.items) {
+      const cst = this.schema!.cstByID.get(item.id)!;
+      if (item.type === TYPE_BASIC) {
+        if (cst.cst_type !== CstType.BASE && cst.cst_type !== CstType.CONSTANT) {
+          throw new Error(`Invalid data for ${cst.alias}`);
+        }
+        const data = item.value as BasicBinding;
+        this.basics.set(cst.id, data);
+        this.calculator.setValue(cst.alias, Object.keys(data).map(Number));
+      }
+    }
+    for (const item of this.data!.items) {
+      const cst = this.schema!.cstByID.get(item.id)!;
+      if (item.type !== TYPE_BASIC) {
+        this.calculator.setValue(cst.alias, item.value as Value);
+        if (!cst.effectiveType || !this.calculator.validate(item.value as Value, cst.effectiveType)) {
+          this.invalidData.add(item.id);
+        }
+      }
+    }
+    this.setupEmptySets();
+  }
+
+  private setupEmptySets(): void {
+    for (const cst of this.schema!.items) {
+      if (isBasicConcept(cst.cst_type) && this.schema!.analyzer.getType(cst.alias)?.typeID === TypeID.collection) {
+        if (this.calculator.getValue(cst.alias) === null) {
+          this.calculator.setValue(cst.alias, []);
+        }
+      }
+    }
+  }
+
+  private collectChanged(previousSchema: RSForm | null, nextSchema: RSForm): number[] {
+    if (!previousSchema) {
+      return [];
+    }
+    const changedIDs: number[] = [];
+    for (const cst of nextSchema.items) {
+      const prev = previousSchema.cstByID.get(cst.id);
+      if (prev && (prev.definition_formal !== cst.definition_formal || prev.alias !== cst.alias)) {
+        changedIDs.push(cst.id);
+      }
+    }
+    return changedIDs;
+  }
+
+  private onChangeDefinitions(cstIDs: number[]): void {
+    if (!this.schema || cstIDs.length === 0) {
+      return;
+    }
+    for (const cstID of cstIDs) {
+      const cst = this.schema.cstByID.get(cstID);
+      if (!cst || !isInferrable(cst.cst_type)) {
+        continue;
+      }
+      this.calculatedSet.delete(cstID);
+      this.calculator.resetValue(cst.alias);
+      this.notifyCst(cstID);
+    }
+    this.cascadeReset(cstIDs);
+  }
+
+  private cascadeReset(cstIDs: number[]): void {
+    if (!this.schema) {
+      return;
+    }
+    const dependencies = this.schema.graph.expandAllOutputs(cstIDs);
+    for (const cstID of dependencies) {
+      const cst = this.schema.cstByID.get(cstID);
+      if (!cst || !isInferrable(cst.cst_type)) {
+        continue;
+      }
+      this.calculatedSet.delete(cstID);
+      this.calculator.resetValue(this.schema.cstByID.get(cstID)!.alias);
+      this.notifyCst(cstID);
+    }
+  }
+
+  private prepareEvaluation(dependencies: number[]): void {
+    for (const cstID of this.schema!.graph.topologicalOrder()) {
+      if (dependencies.includes(cstID)) {
+        const cst = this.schema!.cstByID.get(cstID)!;
+        if (isInferrable(cst.cst_type)) {
+          const value = fastEvaluation(cst.definition_formal, cst.cst_type, this.schema!, this.calculator, message =>
+            this.notifications?.onEvaluationError(message)
+          );
+          if (value !== null) {
+            this.calculator.setValue(cst.alias, value);
+          } else {
+            this.calculator.resetValue(cst.alias);
+          }
+          this.notifyCst(cstID);
+        }
+        this.calculatedSet.add(cstID);
+      }
+    }
+  }
+
+  private recalculateInternal(): void {
+    const processedIDs = [];
+    for (const cst of this.schema!.cstByID.values()) {
+      if (isInferrable(cst.cst_type)) {
+        this.calculator.resetValue(cst.alias);
+      }
+    }
+
+    for (const cstID of this.schema!.graph.topologicalOrder()) {
+      processedIDs.push(cstID);
+      const cst = this.schema!.cstByID.get(cstID)!;
+      if (isInferrable(cst.cst_type)) {
+        const value = fastEvaluation(cst.definition_formal, cst.cst_type, this.schema!, this.calculator);
+        this.calculatedSet.add(cstID);
+        if (value !== null) {
+          this.calculator.setValue(cst.alias, value);
+        }
+      }
+    }
+    this.notifyAll();
+  }
+}
+
+// ==== Internal functions ==== /
+
+/** Evaluates expression for {@link Constituenta}, including error handling. */
+function getEvaluationFor(
+  expression: string,
+  cstType: CstType,
+  schema: RSForm,
+  calculator: RSCalculator,
+  onEvaluationError?: (message: string) => void
+): CalculatorResult {
+  const parse = getAnalysisFor(expression, cstType, schema);
+  if (!parse.success || !parse.ast) {
+    return {
+      value: null,
+      iterations: 0,
+      cacheHits: 0,
+      errors: parse.errors
+    };
+  } else {
+    try {
+      const result = calculator.evaluateFull(parse.ast);
+      return {
+        value: result.value,
+        iterations: result.iterations,
+        cacheHits: result.cacheHits,
+        errors: [...parse.errors, ...result.errors]
+      };
+    } catch (error) {
+      onEvaluationError?.((error as Error).message);
+      console.error(expression, error);
+      return {
+        value: null,
+        iterations: 0,
+        cacheHits: 0,
+        errors: []
+      };
+    }
+  }
+}
+
+/** Evaluates expression for {@link RSModel}. */
+function fastEvaluation(
+  expression: string,
+  cstType: CstType,
+  schema: RSForm,
+  calculator: RSCalculator,
+  onEvaluationError?: (message: string) => void
+): Value | null {
+  const parse = getAnalysisFor(expression, cstType, schema);
+  if (!parse.success || !parse.ast) {
+    return null;
+  } else {
+    try {
+      return calculator.evaluateFast(parse.ast);
+    } catch (error) {
+      onEvaluationError?.((error as Error).message);
+      console.error(expression, error);
+      return null;
+    }
+  }
+}