@open-rap/runtime 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clément Ringot and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @open-rap/runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The generic runtime of the applications produced by
+[Open RAP Runtime](https://clementringot.github.io/RAP-Transpiler/): Fastify server, OData V4
+(`$batch`, draft, ETags), RAP managed runtime, execution of the transpiled behavior pool, OIDC
+authentication, launchpad and MCP server.
+
+An application generated by `rapt build` bundles it in `vendor/`; `rapt dev` uses it directly.
+Installed with the command line:
+
+```sh
+npm install -g open-rap-runtime
+```
+
+MIT license.

package/dist/abap/background.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Background processing (bgPF, decision D41): cl_bgmc_process_factory saves a process in the LUW
+ * of the request (table rapt_background_process, state NEW); once that LUW is committed, the
+ * operation runs in a LUW of its own, as the same user, after the request. A controlled operation
+ * (if_bgmc_op_single) writes the database after cl_abap_tx=>save( ) and its EML changes are saved
+ * at its end; an uncontrolled one (if_bgmc_op_single_tx_uncontr) writes when it wants and saves
+ * its EML changes with COMMIT ENTITIES. The process then ends SUCCESSFUL or ERRONEOUS.
+ *
+ * The operation object stays in memory: a process that has not run when the application stops
+ * is not run again (see KNOWN_GAPS.md).
+ */
+import type { RapRuntime } from "../rap/runtime.js";
+import { type AbapData } from "./convert.js";
+export declare function installBackground(kernel: AbapData, runtime: RapRuntime): void;

package/dist/abap/background.js

@@ -0,0 +1,130 @@
+/**
+ * Background processing (bgPF, decision D41): cl_bgmc_process_factory saves a process in the LUW
+ * of the request (table rapt_background_process, state NEW); once that LUW is committed, the
+ * operation runs in a LUW of its own, as the same user, after the request. A controlled operation
+ * (if_bgmc_op_single) writes the database after cl_abap_tx=>save( ) and its EML changes are saved
+ * at its end; an uncontrolled one (if_bgmc_op_single_tx_uncontr) writes when it wants and saves
+ * its EML changes with COMMIT ENTITIES. The process then ends SUCCESSFUL or ERRONEOUS.
+ *
+ * The operation object stays in memory: a process that has not run when the application stops
+ * is not run again (see KNOWN_GAPS.md).
+ */
+import { randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import { same } from "@open-rap/model";
+import { RapRuntimeError } from "../rap/types.js";
+import { setSubrc } from "./bridge.js";
+import { abapGlobal, abapString } from "./convert.js";
+class RolledBack extends Error {
+}
+const flag = (value) => value !== undefined && abapString(value) !== "";
+export function installBackground(kernel, runtime) {
+    const abap = abapGlobal();
+    const errorText = (error) => {
+        const name = error?.constructor?.INTERNAL_NAME;
+        if (name !== undefined) {
+            return `${name}: ${runtime.bridge.exceptionText(error)}`;
+        }
+        return error instanceof Error ? error.message : String(error);
+    };
+    const finish = async (luw, id, state, error) => {
+        await runtime.transaction(luw.db, luw.user, luw.language, async (tx) => {
+            await sql `UPDATE rapt_background_process SET state = ${state}, error_text = ${error}, finished_at = now() WHERE process_id = ${id}`.execute(tx.db);
+        });
+    };
+    kernel.bgmc_save = async (input) => {
+        const context = runtime.context();
+        const id = randomUUID().replace(/-/g, "").toUpperCase();
+        const name = abapString(input?.["name"]);
+        const controlled = flag(input?.["controlled"]);
+        // the reference of the operation, kept until the process runs
+        const operation = new abap.types.ABAPObject().set(input?.["operation"]);
+        if (operation.get() === undefined) {
+            throw new RapRuntimeError("save_for_execution: the process has no operation (set_operation or set_operation_tx_uncontrolled)");
+        }
+        await sql `INSERT INTO rapt_background_process (process_id, process_name, state, process_user, created_at)
+      VALUES (${id}, ${name}, 'NEW', ${context.user.abapName}, now())`.execute(context.tx.db);
+        context.afterCommit.push(async (luw) => {
+            const background = { controlled, committed: false, rolledBack: false };
+            let state = "SUCCESSFUL";
+            let error = "";
+            try {
+                await runtime.transaction(luw.db, luw.user, luw.language, async (tx) => {
+                    await abap.Classes["ZRAP_CL_BGMC_PROCESS"].zrap_run({ operation, controlled: new abap.types.Character(1).set(controlled ? "X" : "") });
+                    if (background.rolledBack) {
+                        throw new RolledBack();
+                    }
+                    if (!background.committed) {
+                        // the changes of the operation's EML are saved at its end, as by the RAP framework
+                        const responses = await tx.save();
+                        if (responses.hasFailed) {
+                            throw new Error(`the save sequence failed: ${responses.reported.map((r) => r.message.text).join("; ") || "failed instances"}`);
+                        }
+                    }
+                }, { background });
+            }
+            catch (e) {
+                if (!(e instanceof RolledBack)) {
+                    state = "ERRONEOUS";
+                    error = errorText(e);
+                    process.stderr.write(`open-rap-runtime: background process ${name || id} failed: ${error}\n`);
+                }
+            }
+            await finish(luw, id, state, error);
+        });
+        return new abap.types.String().set(id);
+    };
+    kernel.bgmc_state = async (input) => {
+        const { rows } = await sql `SELECT state FROM rapt_background_process WHERE process_id = ${abapString(input?.["id"])}`.execute(runtime.context().tx.db);
+        return new abap.types.String().set(rows[0]?.state ?? "");
+    };
+    // cl_abap_tx=>modify( ) / save( ): the transactional phase of a controlled operation
+    kernel.tx_phase = async (input) => {
+        const context = runtime.context();
+        if (context.background?.controlled === true) {
+            context.tx.inSaver = abapString(input?.["phase"]) === "save";
+        }
+    };
+    // COMMIT ENTITIES and ROLLBACK ENTITIES: only in a background operation
+    const forbidden = () => {
+        throw new RapRuntimeError("COMMIT ENTITIES and ROLLBACK ENTITIES are not allowed in a behavior implementation");
+    };
+    kernel.commit = async (input) => {
+        const context = runtime.context();
+        const background = context.background;
+        if (background === undefined) {
+            forbidden();
+            return;
+        }
+        if (background.committed) {
+            throw new RapRuntimeError("COMMIT ENTITIES: a background operation commits once");
+        }
+        const responses = await context.tx.save();
+        background.responses = responses;
+        if (!flag(input?.["simulation"]) && !responses.hasFailed) {
+            background.committed = true;
+        }
+        setSubrc(responses.hasFailed ? 4 : 0);
+    };
+    kernel.commit_response = async (input) => {
+        const background = runtime.context().background;
+        if (background === undefined) {
+            forbidden();
+            return;
+        }
+        const bdef = abapString(input?.["bdef"]);
+        const bo = runtime.bo.entities.find((e) => same(e.bdef.name, bdef));
+        if (bo !== undefined && background.responses !== undefined) {
+            await runtime.bridge.writeResponses(bo, background.responses, input?.["failed"], input?.["reported"]);
+        }
+    };
+    kernel.rollback = async () => {
+        const background = runtime.context().background;
+        if (background === undefined) {
+            forbidden();
+            return;
+        }
+        background.rolledBack = true;
+    };
+}
+//# sourceMappingURL=background.js.map

package/dist/abap/background.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background.js","sourceRoot":"","sources":["../../src/abap/background.ts"],"names":[],"mappings":"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"}

package/dist/abap/bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The bridge between the managed runtime (canonical rows, JavaScript responses) and the
+ * transpiled behavior pool (ABAP data objects of the derived types, handler methods).
+ */
+import { type HandlerRef, type FieldModel } from "@open-rap/model";
+import type { User } from "../auth/user.js";
+import type { BoEntity, BoModel } from "../rap/bo.js";
+import { Responses, type Message, type Row } from "../rap/types.js";
+import { type AbapData } from "./convert.js";
+/** Imports the transpiled modules (`abap/init.mjs` sets the global `abap` object). */
+export declare function loadAbap(abapDir: string, entry?: string): Promise<void>;
+/** Sets the system fields the ABAP code reads (sy-uname, sy-datum, sy-uzeit, sy-langu). */
+export declare function setSystemFields(user: User, language: string, now?: Date): void;
+export declare function setSubrc(value: number): void;
+export type MessageTexts = Record<string, Record<string, string>>;
+/** T100 text with its placeholders (`&1`…`&4`, `&`) replaced. */
+export declare function formatT100(texts: MessageTexts, id: string, number: string, vars: string[]): string;
+export declare class AbapBridge {
+    private readonly bo;
+    private readonly texts;
+    constructor(bo: BoModel, texts: MessageTexts);
+    iface(bo: BoEntity): AbapData;
+    /** A new data object of a derived type (`tt_e1_keys`…). */
+    data(bo: BoEntity, typeName: string): AbapData;
+    /** Sets the fields of `row` (all, or the given ones) in an ABAP structure that has them. */
+    fillRow(target: AbapData, bo: BoEntity, row: Row, fields?: Iterable<string>): void;
+    fillKey(target: AbapData, bo: BoEntity, key: Row): void;
+    readRow(source: AbapData, bo: BoEntity, fields?: Iterable<string>): Row;
+    readKey(source: AbapData, bo: BoEntity): Row;
+    /** Fields flagged in the `%control` component of a row; undefined when the row has none. */
+    readControl(source: AbapData, bo: BoEntity): Set<string> | undefined;
+    fillControl(target: AbapData, bo: BoEntity, fields: Iterable<string>): void;
+    readText(source: AbapData, name: string): string;
+    /** The fields of a parameter structure (`%param`) of an abstract entity. */
+    readParameter(source: AbapData, fields: FieldModel[]): Row;
+    fillParameter(target: AbapData, fields: FieldModel[], values: Row): void;
+    /** A table of keys (`tt_eN_keys` or another table with the key fields) from canonical keys. */
+    keysTable(bo: BoEntity, keys: Row[], typeName?: string): AbapData;
+    /** `ts_failed_early`, `ts_reported_late`… of the BDEF of `bo`. */
+    response(bo: BoEntity, kind: "failed" | "reported" | "mapped", late?: boolean): AbapData;
+    private entitiesOf;
+    /** Reads the ABAP responses of a handler or of an EML statement. */
+    readResponses(bo: BoEntity, failed?: AbapData, reported?: AbapData, mapped?: AbapData): Promise<Responses>;
+    private failedOperation;
+    /** Text and severity of a message object (`%msg`, an ABAP reference). */
+    message(ref: AbapData | undefined): Promise<Message | undefined>;
+    /** A message object for the ABAP code (`%msg` of the responses the kernel writes). */
+    messageObject(message: Message): Promise<AbapData>;
+    /** Writes responses into the ABAP response structures of an EML statement (cleared first). */
+    writeResponses(bo: BoEntity, responses: Responses, failed?: AbapData, reported?: AbapData, mapped?: AbapData): Promise<void>;
+    /** Calls a handler method of a local class of the behavior pool. */
+    call(ref: HandlerRef, params: Record<string, AbapData>): Promise<void>;
+    t100(id: string, number: string, vars: string[]): string;
+    /** The T100 message key of a message object (`if_t100_message~t100key`), if it has one. */
+    t100Key(object: AbapData): {
+        msgid: string;
+        msgno: string;
+        attributes: string[];
+    } | undefined;
+    /** Text of an exception: its T100 message with the attributes named by attr1…attr4. */
+    exceptionText(object: AbapData): string;
+}

package/dist/abap/bridge.js

@@ -0,0 +1,402 @@
+/**
+ * The bridge between the managed runtime (canonical rows, JavaScript responses) and the
+ * transpiled behavior pool (ABAP data objects of the derived types, handler methods).
+ */
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+import { abapName } from "@open-rap/model";
+import { FAIL_CAUSES, Responses } from "../rap/types.js";
+import { abapGlobal, abapString, appendRow, component, getAbapValue, isFlagOn, rowsOf, setAbapValue, setFlag } from "./convert.js";
+/** Imports the transpiled modules (`abap/init.mjs` sets the global `abap` object). */
+export async function loadAbap(abapDir, entry = "init.mjs") {
+    await import(pathToFileURL(path.resolve(abapDir, entry)).href);
+    abapGlobal();
+}
+const LANGUAGES = { en: "E", de: "D", fr: "F", es: "S", it: "I", pt: "P", nl: "N", ja: "J", zh: "1", ru: "R", pl: "L", cs: "C", da: "K", fi: "U", sv: "V", tr: "T", ko: "3" };
+/** Sets the system fields the ABAP code reads (sy-uname, sy-datum, sy-uzeit, sy-langu). */
+export function setSystemFields(user, language, now = new Date()) {
+    const sy = abapGlobal().builtin.sy.get();
+    sy.uname.set(user.abapName);
+    const iso = now.toISOString();
+    sy.datum.set(iso.slice(0, 10).replace(/-/g, ""));
+    sy.uzeit.set(iso.slice(11, 19).replace(/:/g, ""));
+    sy.langu.set(LANGUAGES[language.slice(0, 2).toLowerCase()] ?? "E");
+}
+export function setSubrc(value) {
+    abapGlobal().builtin.sy.get().subrc.set(value);
+}
+/** T100 text with its placeholders (`&1`…`&4`, `&`) replaced. */
+export function formatT100(texts, id, number, vars) {
+    const text = texts[id.toUpperCase()]?.[number.padStart(3, "0")];
+    if (text === undefined) {
+        return `${id} ${number}${vars.some((v) => v !== "") ? ` ${vars.join(" ")}`.trimEnd() : ""}`;
+    }
+    let next = 0;
+    return text.replace(/&(\d)|&/g, (_match, n) => {
+        const value = n === undefined ? vars[next++] : vars[Number(n) - 1];
+        return value ?? "";
+    });
+}
+export class AbapBridge {
+    bo;
+    texts;
+    constructor(bo, texts) {
+        this.bo = bo;
+        this.texts = texts;
+    }
+    iface(bo) {
+        const iface = abapGlobal().Classes[bo.iface];
+        if (iface === undefined) {
+            throw new Error(`derived types ${bo.iface} not loaded`);
+        }
+        return iface;
+    }
+    /** A new data object of a derived type (`tt_e1_keys`…). */
+    data(bo, typeName) {
+        const type = this.iface(bo)[typeName];
+        if (type === undefined) {
+            throw new Error(`derived type ${bo.iface}=>${typeName} not found`);
+        }
+        return type.clone();
+    }
+    // -------------------------------------------------------------------------------------------
+    // rows
+    /** Sets the fields of `row` (all, or the given ones) in an ABAP structure that has them. */
+    fillRow(target, bo, row, fields) {
+        const names = fields === undefined ? bo.fields.map((f) => f.name) : [...fields];
+        for (const name of names) {
+            const field = this.bo.field(bo, name);
+            const data = field === undefined ? undefined : component(target, field.name);
+            if (field !== undefined && data !== undefined && name in row) {
+                setAbapValue(data, field.type, row[field.name]);
+            }
+        }
+    }
+    fillKey(target, bo, key) {
+        this.fillRow(target, bo, key, bo.keys.map((k) => k.name));
+    }
+    readRow(source, bo, fields) {
+        const row = {};
+        const list = fields === undefined ? bo.fields : [...fields].map((n) => this.bo.field(bo, n)).filter((f) => f !== undefined);
+        for (const field of list) {
+            const data = component(source, field.name);
+            if (data !== undefined) {
+                row[field.name] = getAbapValue(data, field.type);
+            }
+        }
+        return row;
+    }
+    readKey(source, bo) {
+        return this.readRow(source, bo, bo.keys.map((k) => k.name));
+    }
+    /** Fields flagged in the `%control` component of a row; undefined when the row has none. */
+    readControl(source, bo) {
+        const control = component(source, "%control");
+        if (control === undefined) {
+            return undefined;
+        }
+        const fields = new Set();
+        for (const field of bo.fields) {
+            if (isFlagOn(component(control, field.name))) {
+                fields.add(field.name);
+            }
+        }
+        return fields;
+    }
+    fillControl(target, bo, fields) {
+        const control = component(target, "%control");
+        if (control === undefined) {
+            return;
+        }
+        for (const name of fields) {
+            setFlag(component(control, name), true);
+        }
+    }
+    readText(source, name) {
+        return abapString(component(source, name));
+    }
+    /** The fields of a parameter structure (`%param`) of an abstract entity. */
+    readParameter(source, fields) {
+        const param = component(source, "%param");
+        const row = {};
+        if (param === undefined) {
+            return row;
+        }
+        for (const field of fields) {
+            const data = component(param, field.name);
+            if (data !== undefined) {
+                row[field.name] = getAbapValue(data, field.type);
+            }
+        }
+        return row;
+    }
+    fillParameter(target, fields, values) {
+        const param = component(target, "%param");
+        if (param === undefined) {
+            return;
+        }
+        for (const field of fields) {
+            const data = component(param, field.name);
+            if (data !== undefined && field.name in values) {
+                setAbapValue(data, field.type, values[field.name]);
+            }
+        }
+    }
+    /** A table of keys (`tt_eN_keys` or another table with the key fields) from canonical keys. */
+    keysTable(bo, keys, typeName = `tt_e${bo.index}_keys`) {
+        const table = this.data(bo, typeName);
+        for (const key of keys) {
+            appendRow(table, (row) => this.fillKey(row, bo, key));
+        }
+        return table;
+    }
+    // -------------------------------------------------------------------------------------------
+    // responses
+    /** `ts_failed_early`, `ts_reported_late`… of the BDEF of `bo`. */
+    response(bo, kind, late = false) {
+        return this.data(bo, `ts_${kind}_${late ? "late" : "early"}`);
+    }
+    entitiesOf(bo) {
+        return this.bo.entities.filter((e) => e.bdef === bo.bdef);
+    }
+    /** Reads the ABAP responses of a handler or of an EML statement. */
+    async readResponses(bo, failed, reported, mapped) {
+        const responses = new Responses();
+        for (const entity of this.entitiesOf(bo)) {
+            const alias = abapName(entity.behavior.alias);
+            for (const row of rowsOf(failed === undefined ? undefined : component(failed, alias))) {
+                const fail = component(row, "%fail");
+                const cause = FAIL_CAUSES[parseInt(String(fail === undefined ? "0" : component(fail, "cause")?.get() ?? "0"), 16)] ?? "unspecific";
+                const entry = { entity: entity.entity.name, key: this.readKey(row, entity), cause };
+                const cid = this.readText(row, "%cid");
+                if (cid !== "") {
+                    entry.cid = cid;
+                }
+                const operation = this.failedOperation(row, entity);
+                if (operation !== undefined) {
+                    entry.operation = operation;
+                }
+                responses.failed.push(entry);
+            }
+            for (const row of rowsOf(reported === undefined ? undefined : component(reported, alias))) {
+                const message = await this.message(component(row, "%msg"));
+                if (message === undefined) {
+                    continue;
+                }
+                const elements = [];
+                const element = component(row, "%element");
+                if (element !== undefined) {
+                    for (const name of Object.keys(element.get())) {
+                        if (isFlagOn(component(element, name))) {
+                            elements.push(entity.fields.find((f) => abapName(f.name) === name)?.name ?? entity.associations.find((a) => abapName(a.name) === name)?.name ?? name);
+                        }
+                    }
+                }
+                const key = this.readKey(row, entity);
+                const hasKey = Object.values(key).some((v) => v !== null && v !== "" && v !== false && !/^0+$/.test(String(v)));
+                const entry = { entity: entity.entity.name, message, elements, global: isFlagOn(component(row, "%global")) };
+                if (hasKey) {
+                    entry.key = key;
+                }
+                const cid = this.readText(row, "%cid");
+                if (cid !== "") {
+                    entry.cid = cid;
+                }
+                const stateArea = this.readText(row, "%state_area");
+                if (stateArea !== "") {
+                    entry.stateArea = stateArea;
+                }
+                responses.reported.push(entry);
+            }
+            for (const row of rowsOf(mapped === undefined ? undefined : component(mapped, alias))) {
+                responses.mapped.push({ entity: entity.entity.name, cid: this.readText(row, "%cid"), key: this.readKey(row, entity) });
+            }
+        }
+        for (const ref of rowsOf(reported === undefined ? undefined : component(reported, "%other"))) {
+            const message = await this.message(ref);
+            if (message !== undefined) {
+                responses.reported.push({ message, elements: [], global: true });
+            }
+        }
+        return responses;
+    }
+    failedOperation(row, bo) {
+        for (const kind of ["create", "update", "delete"]) {
+            if (isFlagOn(component(row, `%${kind}`))) {
+                return { kind };
+            }
+        }
+        const action = component(row, "%action");
+        for (const a of bo.behavior.actions) {
+            if (action !== undefined && isFlagOn(component(action, a.name))) {
+                return { kind: "action", name: a.name };
+            }
+        }
+        const assoc = component(row, "%assoc");
+        for (const a of bo.associations) {
+            if (assoc !== undefined && isFlagOn(component(assoc, a.name))) {
+                return { kind: "association", name: a.name };
+            }
+        }
+        return undefined;
+    }
+    /** Text and severity of a message object (`%msg`, an ABAP reference). */
+    async message(ref) {
+        const object = ref?.get?.();
+        if (object === undefined || object === null) {
+            return undefined;
+        }
+        const severity = (abapString(object["if_abap_behv_message$m_severity"]) || "E");
+        let text = "";
+        for (const method of ["if_message$get_text", "if_abap_behv_message$get_text", "get_text"]) {
+            if (typeof object[method] === "function") {
+                text = abapString(await object[method]({}));
+                break;
+            }
+        }
+        const message = { severity, text };
+        const key = this.t100Key(object);
+        if (key !== undefined) {
+            message.msgid = key.msgid;
+            message.msgno = key.msgno;
+        }
+        return message;
+    }
+    /** A message object for the ABAP code (`%msg` of the responses the kernel writes). */
+    async messageObject(message) {
+        const abap = abapGlobal();
+        const MessageClass = abap.Classes["ZRAP_CL_MESSAGE"];
+        const object = await new MessageClass().constructor_({
+            severity: new abap.types.Character(1).set(message.severity),
+            text: new abap.types.String().set(message.text),
+        });
+        const ref = new abap.types.ABAPObject();
+        ref.set(object);
+        return ref;
+    }
+    /** Writes responses into the ABAP response structures of an EML statement (cleared first). */
+    async writeResponses(bo, responses, failed, reported, mapped) {
+        failed?.clear();
+        reported?.clear();
+        mapped?.clear();
+        const entities = this.entitiesOf(bo);
+        const entityOf = (name) => entities.find((e) => e.entity.name === name);
+        for (const entry of responses.failed) {
+            const entity = entityOf(entry.entity);
+            const table = entity === undefined || failed === undefined ? undefined : component(failed, abapName(entity.behavior.alias));
+            if (entity === undefined || table === undefined) {
+                continue;
+            }
+            appendRow(table, (row) => {
+                if (entry.key !== undefined) {
+                    this.fillKey(row, entity, entry.key);
+                }
+                component(row, "%cid")?.set(entry.cid ?? "");
+                const fail = component(row, "%fail");
+                component(fail, "cause")?.set(`0${FAIL_CAUSES.indexOf(entry.cause)}`);
+                const operation = entry.operation;
+                if (operation?.kind === "create" || operation?.kind === "update" || operation?.kind === "delete") {
+                    setFlag(component(row, `%${operation.kind}`), true);
+                }
+                else if (operation?.kind === "action") {
+                    const action = component(row, "%action");
+                    setFlag(action === undefined ? undefined : component(action, operation.name), true);
+                }
+                else if (operation?.kind === "association") {
+                    const assoc = component(row, "%assoc");
+                    setFlag(assoc === undefined ? undefined : component(assoc, operation.name), true);
+                }
+            });
+        }
+        for (const entry of responses.reported) {
+            const entity = entityOf(entry.entity);
+            const msg = await this.messageObject(entry.message);
+            if (entity === undefined) {
+                const other = reported === undefined ? undefined : component(reported, "%other");
+                if (other !== undefined) {
+                    other.append(msg);
+                }
+                continue;
+            }
+            const table = reported === undefined ? undefined : component(reported, abapName(entity.behavior.alias));
+            if (table === undefined) {
+                continue;
+            }
+            appendRow(table, (row) => {
+                if (entry.key !== undefined) {
+                    this.fillKey(row, entity, entry.key);
+                }
+                component(row, "%cid")?.set(entry.cid ?? "");
+                component(row, "%msg")?.set(msg);
+                const element = component(row, "%element");
+                for (const name of entry.elements) {
+                    setFlag(element === undefined ? undefined : component(element, name), true);
+                }
+                setFlag(component(row, "%global"), entry.global);
+            });
+        }
+        for (const entry of responses.mapped) {
+            const entity = entityOf(entry.entity);
+            const table = entity === undefined || mapped === undefined ? undefined : component(mapped, abapName(entity.behavior.alias));
+            if (entity === undefined || table === undefined) {
+                continue;
+            }
+            appendRow(table, (row) => {
+                this.fillKey(row, entity, entry.key);
+                component(row, "%cid")?.set(entry.cid);
+            });
+        }
+    }
+    // -------------------------------------------------------------------------------------------
+    // handlers
+    /** Calls a handler method of a local class of the behavior pool. */
+    async call(ref, params) {
+        const Class = abapGlobal().Classes[ref.classKey];
+        if (Class === undefined) {
+            throw new Error(`handler class ${ref.classKey} is not loaded`);
+        }
+        const instance = await new Class().constructor_();
+        const friends = instance.FRIENDS_ACCESS_INSTANCE;
+        const method = friends?.[ref.method] ?? (typeof instance[ref.method] === "function" ? instance[ref.method].bind(instance) : undefined);
+        if (method === undefined) {
+            throw new Error(`handler method ${ref.className}->${ref.method} not found`);
+        }
+        await method(params);
+    }
+    t100(id, number, vars) {
+        return formatT100(this.texts, id, number, vars);
+    }
+    /** The T100 message key of a message object (`if_t100_message~t100key`), if it has one. */
+    t100Key(object) {
+        const key = object?.["if_t100_message$t100key"];
+        if (key === undefined) {
+            return undefined;
+        }
+        const msgid = abapString(component(key, "msgid"));
+        if (msgid === "") {
+            return undefined;
+        }
+        return { msgid, msgno: abapString(component(key, "msgno")), attributes: [1, 2, 3, 4].map((n) => abapString(component(key, `attr${n}`))) };
+    }
+    /** Text of an exception: its T100 message with the attributes named by attr1…attr4. */
+    exceptionText(object) {
+        // the exceptions of the framework that carry a text of their own (HTTP, OData client proxy)
+        const own = object?.zrap_text === undefined ? "" : abapString(object.zrap_text);
+        if (own !== "") {
+            return own;
+        }
+        const key = this.t100Key(object);
+        if (key === undefined) {
+            return "An exception was raised";
+        }
+        const vars = key.attributes.map((name) => {
+            if (name === "") {
+                return "";
+            }
+            const attribute = object[name.toLowerCase().replace(/~/g, "$")];
+            return attribute === undefined ? name : abapString(attribute);
+        });
+        return this.t100(key.msgid, key.msgno, vars);
+    }
+}
+//# sourceMappingURL=bridge.js.map