@openmbee/opensysml 0.9.1 → 0.10.0

package/dist/core/document.js

@@ -0,0 +1,457 @@
+// Native document queries: a calc def specializing `DocumentQueries::Query`,
+// answered as typed rows. Binding values are plain values, an ElementRef
+// naming a model element, or an ObjectRef naming an object the service holds.
+import { create } from "@bufbuild/protobuf";
+import { DocumentObjectSchema, DocumentQueryBindingSchema, DocumentValueSchema, QuantitySchema, UnitFactorSchema, UnitTermSchema, } from "../generated/sysml_pb.js";
+import { DocumentQueryError, UnsupportedValueError } from "./errors.js";
+import { decodeBigInteger, decodeRational, encodeQuantityMagnitude, encodeRational, fitsInt64, formatValue, quantityRationalAsReal, rationalAsDouble, } from "./values.js";
+/** Whether a wire binding sends an Integer beyond int64, which needs `big_int_values`. */
+export function bindingHoldsBigInt(binding) {
+    return binding.values.some((value) => value.kind.case === "bigIntValue" ||
+        (value.kind.case === "quantity" && value.kind.value.magnitude.case === "bigIntMagnitude"));
+}
+/** Whether a wire binding sends an exact Rational, which needs `rational_values`. */
+export function bindingHoldsRational(binding) {
+    return binding.values.some((value) => value.kind.case === "rationalValue" ||
+        (value.kind.case === "quantity" && value.kind.value.magnitude.case === "rationalMagnitude"));
+}
+/** Rewrites each Rational a binding sends that a double holds exactly as that double, for a service without `rational_values`. */
+export function bindingRationalsAsReals(binding) {
+    for (const value of binding.values) {
+        if (value.kind.case === "rationalValue") {
+            const { numerator, denominator } = value.kind.value;
+            const double = rationalAsDouble({ numerator: BigInt(numerator), denominator: BigInt(denominator) });
+            if (double !== undefined) {
+                value.kind = { case: "realValue", value: double };
+            }
+        }
+        else if (value.kind.case === "quantity") {
+            quantityRationalAsReal(value.kind.value);
+        }
+    }
+}
+/** A model element, named by qualified name. */
+export class ElementRef {
+    /** Qualified name of the element. */
+    id;
+    /** Metamodel type name; empty when bound by a caller, reported when answered. */
+    type;
+    constructor(id, type = "") {
+        this.id = id;
+        this.type = type;
+    }
+    toString() {
+        return this.type !== "" ? `${this.id} (${this.type})` : this.id;
+    }
+}
+/** An object the service holds for the model, created by `instantiate`. */
+export class ObjectRef {
+    /** The object's id, as `instantiate` answered it. */
+    id;
+    /** The object by the label a session reaches it under. */
+    path;
+    /** The usage the object is held under; reported when answered, ignored when bound. */
+    element;
+    constructor(options = {}) {
+        this.id = typeof options.id === "number" ? BigInt(options.id) : (options.id ?? 0n);
+        this.path = options.path ?? "";
+        this.element = options.element;
+    }
+    toString() {
+        return this.path !== "" ? this.path : `#${this.id.toString()}`;
+    }
+}
+/** A row a `Verdicts` query answered: an assertion checked on one object. Answered only. */
+export class DocumentVerdict {
+    assertion;
+    /** "constraint", "requirement", "satisfaction" or "verification". */
+    kind;
+    /** The assertion as written. */
+    text;
+    /** The object checked, named from the element the query was bound to. */
+    path;
+    /** "holds", "violated" or "undecided". */
+    status;
+    /** The condition that evaluated to false, as written; empty otherwise. */
+    condition;
+    /** Why the assertion is violated or undecided; empty when it holds. */
+    reason;
+    /** Verdict kinds of the verification cases verifying the row's requirement. */
+    verification;
+    constructor(init) {
+        this.assertion = init.assertion;
+        this.kind = init.kind;
+        this.text = init.text;
+        this.path = init.path;
+        this.status = init.status;
+        this.condition = init.condition ?? "";
+        this.reason = init.reason ?? "";
+        this.verification = init.verification ?? [];
+    }
+    toString() {
+        const where = this.path !== "" ? ` on ${this.path}` : "";
+        return `${this.text}${where}: ${this.status}`;
+    }
+}
+/** A row a `States` query answered: one active leaf state of one object. Answered only. */
+export class DocumentState {
+    /** The object whose state machine the row reads. */
+    object;
+    /** The exhibited state usage's name, or the state def's. */
+    machine;
+    /** The active leaf state's own name. */
+    name;
+    /** The leaf's path from the machine's top level. */
+    path;
+    /** The state usage's declaration. */
+    state;
+    /** The orthogonal region declaring the leaf; empty when not in one. */
+    region;
+    /** The active composite states around the leaf, outermost first. */
+    enclosing;
+    constructor(init) {
+        this.object = init.object;
+        this.machine = init.machine;
+        this.name = init.name;
+        this.path = init.path;
+        this.state = init.state;
+        this.region = init.region ?? "";
+        this.enclosing = init.enclosing ?? [];
+    }
+    toString() {
+        return `${this.object.toString()}.${this.machine} in ${this.path}`;
+    }
+}
+/** A row an `Events` query answered: one record of a session's trace. Answered only. */
+export class DocumentEvent {
+    /** "accept", "send", "transition", "entry", "exit", "do", "choice", "guard" or "terminate". */
+    kind;
+    /** The instant the record was written at: a quantity, an int or a real. */
+    time;
+    /** The object the record is about; undefined for a record of the run as a whole. */
+    object;
+    /** The state machine the record is about. */
+    machine;
+    /** The state entered, exited or run (entry, exit and do records). */
+    state;
+    /** The transition's source state. */
+    fromState;
+    /** The transition's target state. */
+    toState;
+    /** The object a send was delivered to. */
+    target;
+    /** The accepted or sent event's type name. */
+    event;
+    /** The accept's payload, one `name = value` text per attribute. */
+    payload;
+    /** What a choice drew from, in order. */
+    alternatives;
+    /** The alternative the choice took. */
+    taken;
+    /** The record as the trace prints it. */
+    text;
+    constructor(init) {
+        this.kind = init.kind;
+        this.time = init.time;
+        this.text = init.text;
+        this.object = init.object;
+        this.machine = init.machine ?? "";
+        this.state = init.state ?? "";
+        this.fromState = init.fromState ?? "";
+        this.toState = init.toState ?? "";
+        this.target = init.target;
+        this.event = init.event ?? "";
+        this.payload = init.payload ?? [];
+        this.alternatives = init.alternatives ?? [];
+        this.taken = init.taken ?? "";
+    }
+    toString() {
+        const time = this.time;
+        const rendered = time instanceof ElementRef ||
+            time instanceof ObjectRef ||
+            time instanceof DocumentVerdict ||
+            time instanceof DocumentState ||
+            time instanceof DocumentEvent
+            ? time.toString()
+            : renderPlainTime(time);
+        return `${rendered}: ${this.text}`;
+    }
+}
+/** What a binding value or an answered cell value may be. */
+/** A time that is a plain value: a SysML value formatted, anything else as JavaScript spells it. */
+function renderPlainTime(time) {
+    return typeof time === "object" ? formatValue(time) : String(time);
+}
+/** One selected element and its projected cells, one per column. */
+export class DocumentRow {
+    /** The selected element itself, or the usage the row's object is held under. */
+    element;
+    /** One value sequence per column, in column order. */
+    cells;
+    /** The verdict a `Verdicts` row carries; undefined for any other row. */
+    verdict;
+    /** The object a row over held objects is about; undefined for any other row. */
+    object;
+    /** The state a `States` row carries; undefined for any other row. */
+    state;
+    /** The event an `Events` row carries; undefined for any other row. */
+    event;
+    constructor(init) {
+        this.element = init.element;
+        this.cells = init.cells;
+        this.verdict = init.verdict;
+        this.object = init.object;
+        this.state = init.state;
+        this.event = init.event;
+    }
+    /** The values of the `index`-th column. */
+    cell(index) {
+        if (index < 0 || index >= this.cells.length) {
+            throw new RangeError(`the row has ${this.cells.length} cells, not ${index + 1}`);
+        }
+        return this.cells[index];
+    }
+}
+/** A document query's answer: projected columns and typed rows, in the engine's order. */
+export class DocumentQueryResult {
+    /** Projected property names, in projection order. */
+    columns;
+    /** The selected rows, in the engine's order. */
+    rows;
+    constructor(init) {
+        this.columns = init.columns;
+        this.rows = init.rows;
+    }
+    get length() {
+        return this.rows.length;
+    }
+    [Symbol.iterator]() {
+        return this.rows[Symbol.iterator]();
+    }
+}
+/** Translate a bindings mapping into the RPC's protobuf. */
+export function buildBindings(bindings) {
+    if (bindings === undefined) {
+        return [];
+    }
+    const out = [];
+    for (const [parameter, values] of Object.entries(bindings)) {
+        const list = Array.isArray(values) ? values : [values];
+        out.push(create(DocumentQueryBindingSchema, {
+            parameter,
+            values: list.map((value) => boundValue(parameter, value)),
+        }));
+    }
+    return out;
+}
+function boundValue(parameter, value) {
+    if (value instanceof ElementRef) {
+        return create(DocumentValueSchema, { kind: { case: "elementId", value: value.id } });
+    }
+    if (value instanceof ObjectRef) {
+        if (value.id === 0n && value.path === "") {
+            throw new DocumentQueryError(`binding ${JSON.stringify(parameter)} cannot carry ${value.toString()}: an object is ` +
+                `bound by id or by path; neither was given`);
+        }
+        return create(DocumentValueSchema, {
+            kind: {
+                case: "object",
+                value: create(DocumentObjectSchema, { instanceId: value.id, path: value.path }),
+            },
+        });
+    }
+    if (typeof value === "boolean") {
+        return create(DocumentValueSchema, { kind: { case: "boolValue", value } });
+    }
+    if (typeof value === "string") {
+        return create(DocumentValueSchema, { kind: { case: "stringValue", value } });
+    }
+    if (typeof value === "bigint") {
+        return fitsInt64(value)
+            ? create(DocumentValueSchema, { kind: { case: "intValue", value } })
+            : create(DocumentValueSchema, { kind: { case: "bigIntValue", value: value.toString() } });
+    }
+    if (typeof value === "number") {
+        return create(DocumentValueSchema, { kind: { case: "realValue", value } });
+    }
+    if (value instanceof DocumentVerdict) {
+        throw new DocumentQueryError(`binding ${JSON.stringify(parameter)} cannot carry ${value.toString()}: a verdict is ` +
+            `answered by queries, not bound to them`);
+    }
+    if (value instanceof DocumentState || value instanceof DocumentEvent) {
+        const what = value instanceof DocumentState ? "a state" : "an event";
+        throw new DocumentQueryError(`binding ${JSON.stringify(parameter)} cannot carry ${value.toString()}: ${what} row is ` +
+            `answered by queries, not bound to them`);
+    }
+    if (typeof value === "object" && "kind" in value && value.kind === "rational") {
+        return create(DocumentValueSchema, { kind: { case: "rationalValue", value: encodeRational(value) } });
+    }
+    if (typeof value === "object" && "kind" in value && value.kind === "quantity") {
+        return create(DocumentValueSchema, {
+            kind: { case: "quantity", value: boundQuantity(value) },
+        });
+    }
+    throw new DocumentQueryError(`binding ${JSON.stringify(parameter)} cannot carry ${JSON.stringify(value)}: a binding is a ` +
+        `str, int, float, bool, Quantity, ElementRef or ObjectRef`);
+}
+/** A wire quantity's magnitude as a value; one carrying none reads as a real zero. */
+function decodeMagnitude(magnitude) {
+    switch (magnitude.case) {
+        case "intMagnitude":
+            return { kind: "int", value: magnitude.value };
+        case "bigIntMagnitude":
+            return { kind: "int", value: decodeBigInteger(magnitude.value) };
+        case "realMagnitude":
+            return { kind: "real", value: magnitude.value };
+        case "rationalMagnitude":
+            return { kind: "rational", ...decodeRational(magnitude.value) };
+        default:
+            return { kind: "real", value: 0 };
+    }
+}
+function boundQuantity(value) {
+    const magnitude = value.magnitude;
+    return create(QuantitySchema, {
+        magnitude: encodeQuantityMagnitude(magnitude),
+        unit: value.unit,
+        ...(value.unitTerm === undefined
+            ? {}
+            : {
+                unitTerm: create(UnitTermSchema, {
+                    scaleNum: value.unitTerm.scaleNum,
+                    scaleDen: value.unitTerm.scaleDen,
+                    factors: value.unitTerm.factors.map((factor) => create(UnitFactorSchema, { unitId: factor.unitId, exponent: factor.exponent })),
+                }),
+            }),
+    });
+}
+/** Decode a `RunDocumentQueryResponse` into a `DocumentQueryResult`. */
+export function documentResult(response) {
+    return new DocumentQueryResult({
+        columns: response.columns.map((column) => column.name),
+        rows: response.rows.map(rowOf),
+    });
+}
+function rowOf(row) {
+    const cells = row.cells.map((cell) => cell.values.map(valueOf));
+    const kind = row.element?.kind;
+    if (kind?.case === "verdict") {
+        const verdict = valueOf(row.element);
+        return new DocumentRow({ element: verdict.assertion, cells, verdict });
+    }
+    if (kind?.case === "object") {
+        const obj = objectOf(kind.value);
+        return new DocumentRow({ element: obj.element ?? new ElementRef(""), cells, object: obj });
+    }
+    if (kind?.case === "state") {
+        const state = stateOf(kind.value);
+        return new DocumentRow({
+            element: state.object.element ?? new ElementRef(""),
+            cells,
+            object: state.object,
+            state,
+        });
+    }
+    if (kind?.case === "event") {
+        const event = eventOf(kind.value);
+        return new DocumentRow({
+            element: event.object?.element ?? new ElementRef(""),
+            cells,
+            ...(event.object === undefined ? {} : { object: event.object }),
+            event,
+        });
+    }
+    return new DocumentRow({ element: elementOf(row.element), cells });
+}
+function elementOf(value) {
+    if (value?.kind.case === "elementId") {
+        return new ElementRef(value.kind.value, value.elementType);
+    }
+    return new ElementRef("", value?.elementType ?? "");
+}
+function objectOf(obj) {
+    return new ObjectRef({ id: obj.instanceId, path: obj.path, element: elementOf(obj.element) });
+}
+function stateOf(state) {
+    return new DocumentState({
+        object: state.object === undefined ? new ObjectRef() : objectOf(state.object),
+        machine: state.machine,
+        name: state.name,
+        path: state.statePath,
+        ...(state.state === undefined ? {} : { state: elementOf(state.state) }),
+        region: state.region,
+        enclosing: [...state.enclosing],
+    });
+}
+function eventOf(event) {
+    return new DocumentEvent({
+        kind: event.kind,
+        time: valueOf(event.time),
+        text: event.text,
+        ...(event.object === undefined ? {} : { object: objectOf(event.object) }),
+        machine: event.machine,
+        state: event.state,
+        fromState: event.from,
+        toState: event.to,
+        ...(event.target === undefined ? {} : { target: objectOf(event.target) }),
+        event: event.event,
+        payload: [...event.payload],
+        alternatives: [...event.alternatives],
+        taken: event.taken,
+    });
+}
+/** Decode a run-trace event using the document query's event conversion. */
+export function documentEventOf(event) {
+    return eventOf(event);
+}
+function valueOf(value) {
+    const kind = value?.kind;
+    switch (kind?.case) {
+        case "elementId":
+            return new ElementRef(kind.value, value?.elementType ?? "");
+        case "stringValue":
+            return kind.value;
+        case "intValue":
+            return kind.value;
+        case "bigIntValue":
+            return decodeBigInteger(kind.value);
+        case "realValue":
+            return kind.value;
+        case "rationalValue":
+            return { kind: "rational", ...decodeRational(kind.value) };
+        case "boolValue":
+            return kind.value;
+        case "infinity":
+            return { kind: "infinity" };
+        case "quantity": {
+            const magnitude = kind.value.magnitude;
+            const decoded = {
+                kind: "quantity",
+                magnitude: decodeMagnitude(magnitude),
+                unit: kind.value.unit,
+            };
+            return decoded;
+        }
+        case "object":
+            return objectOf(kind.value);
+        case "verdict": {
+            const verdict = kind.value;
+            return new DocumentVerdict({
+                assertion: elementOf(verdict.assertion),
+                kind: verdict.kind,
+                text: verdict.text,
+                path: verdict.path,
+                status: verdict.verdict,
+                condition: verdict.condition,
+                reason: verdict.reason,
+                verification: [...verdict.verification],
+            });
+        }
+        case "state":
+            return stateOf(kind.value);
+        case "event":
+            return eventOf(kind.value);
+        default:
+            throw new UnsupportedValueError(`the service answered a document value this client cannot read: ${JSON.stringify(kind?.case)}`);
+    }
+}