@open-rap/runtime 0.0.0-stage → 0.1.0

package/dist/rap/transaction.d.ts

@@ -0,0 +1,227 @@
+/**
+ * The managed RAP transaction (LUW): transactional buffer over the persistent tables, the
+ * operations of the business objects with their checks (authorization, feature control, locks,
+ * numbering, administrative fields), the determinations on modify (decision D21) and the save
+ * sequence (determinations on save, validations, write).
+ */
+import { type Kysely } from "kysely";
+import { type ActionModel, type EntityModel } from "@open-rap/model";
+import type { AbapBridge } from "../abap/bridge.js";
+import type { User } from "../auth/user.js";
+import { type CanonicalValue } from "../values.js";
+import { type BoAssociation, type BoEntity, type BoModel } from "./bo.js";
+import { Responses, type AccessMode, type FailedOperation, type Row } from "./types.js";
+export interface CreateRequest {
+    cid?: string;
+    values: Row;
+    /** Fields given by the consumer (`%control`). */
+    fields: Set<string>;
+}
+export interface UpdateRequest {
+    key: Row;
+    cidRef?: string;
+    values: Row;
+    fields: Set<string>;
+}
+export interface DeleteRequest {
+    key: Row;
+    cidRef?: string;
+}
+export interface CreateByAssociationRequest {
+    key: Row;
+    cidRef?: string;
+    targets: CreateRequest[];
+}
+export interface ActionRequest {
+    /** Instance actions: the instance. */
+    key?: Row;
+    cidRef?: string;
+    /** Static and factory actions: the content ID of the call. */
+    cid?: string;
+    param: Row;
+}
+export interface ActionResult {
+    key?: Row;
+    cidRef?: string;
+    cid?: string;
+    /** The result: a row of the result entity (or of the abstract entity), when the action has one. */
+    value?: Row;
+}
+export interface TransactionServices {
+    bo: BoModel;
+    bridge: AbapBridge;
+    /** Reads the instances of a custom entity through its query class (D43): rows by element. */
+    customRead?: (entity: EntityModel, equalities: Array<{
+        name: string;
+        value: CanonicalValue;
+    }>) => Promise<Row[]>;
+    /** Time stamps of the administrative fields: ISO UTC with microseconds, strictly increasing. */
+    now(): string;
+}
+export declare class Transaction {
+    private readonly services;
+    readonly db: Kysely<unknown>;
+    readonly user: User;
+    private readonly instances;
+    private readonly cids;
+    private readonly events;
+    private seq;
+    private readonly seen;
+    private readonly locked;
+    private source;
+    private saved;
+    /** ETag masters whose ETag field changes with their `etag dependent` instances (D32). */
+    private readonly etagTouched;
+    /** The saver runs (save_modified, cleanup): the only place where ABAP SQL may write. */
+    inSaver: boolean;
+    constructor(services: TransactionServices, db: Kysely<unknown>, user: User);
+    private get bo();
+    private get bridge();
+    private id;
+    /** The instances of a custom entity meeting equalities, read by its query class (D43). */
+    private readCustom;
+    private load;
+    /**
+     * The calculated elements (D67) of instances read from the persistent table, read from the CDS
+     * view: their values as of the last save.
+     */
+    private withCalculated;
+    private fromRecord;
+    /** The instance with this key, from the buffer or the database; undefined if it does not exist. */
+    private instance;
+    /** Key of a request row: its key, or the instance created with its `%cid_ref`. */
+    private resolveKey;
+    private record;
+    /** Instances of the buffer and the database reached by an association. */
+    private associated;
+    private failure;
+    /** Locks the lock master of an existing instance (`SELECT … FOR UPDATE NOWAIT`). */
+    private lock;
+    /** Global authorization of operations: the result of the authorization master's handler. */
+    private globalAuthorization;
+    /** Instance authorization: denied operations per instance key (of `bo`). */
+    private instanceAuthorization;
+    /** Key of the instance of `master` (an ancestor) that `key` of `bo` belongs to. */
+    private masterKey;
+    /** Instance feature control: operations disabled per instance, and read-only fields. */
+    private instanceFeatures;
+    /** Global feature control: disabled operations. */
+    private globalFeatures;
+    private operationFlag;
+    /** Calls a handler with the parameter names of its definition. */
+    private call;
+    private precheck;
+    private setAdminFields;
+    /** Fields a consumer may not write: read-only, managed numbering, admin fields (outside local mode). */
+    private writable;
+    create(bo: BoEntity, requests: CreateRequest[], mode: AccessMode, parent?: {
+        association: BoAssociation;
+        key: Row;
+        numbered?: Map<string, Row>;
+    }): Promise<Responses>;
+    private createTable;
+    /** Early numbering by the FOR NUMBERING handler: %cid → key. */
+    private number;
+    /**
+     * Early numbering of a creation by association (`FOR NUMBERING … FOR CREATE Travel\_Booking`):
+     * the handler gets the parent instances with their %target, and maps the %cid of the children.
+     */
+    private numberByAssociation;
+    update(bo: BoEntity, requests: UpdateRequest[], mode: AccessMode): Promise<Responses>;
+    delete(bo: BoEntity, requests: DeleteRequest[], mode: AccessMode): Promise<Responses>;
+    /** Deletes an instance and its composition children. */
+    private cascade;
+    createByAssociation(bo: BoEntity, association: BoAssociation, requests: CreateByAssociationRequest[], mode: AccessMode): Promise<Responses>;
+    read(bo: BoEntity, keys: Array<{
+        key: Row;
+        cidRef?: string;
+    }>): Promise<{
+        rows: Array<Row | undefined>;
+        responses: Responses;
+    }>;
+    readByAssociation(bo: BoEntity, association: BoAssociation, keys: Row[]): Promise<{
+        results: Array<{
+            source: Row;
+            target: Row;
+        }>;
+        responses: Responses;
+    }>;
+    execute(bo: BoEntity, action: ActionModel, requests: ActionRequest[], mode: AccessMode): Promise<{
+        results: ActionResult[];
+        responses: Responses;
+    }>;
+    private matches;
+    /** Keys of the instances whose triggers were touched since `since`, not by `id` itself. */
+    private triggered;
+    /** Keys of the instances changed in the LUW in a way that matches the triggers. */
+    private triggeredInLuw;
+    private runDetermination;
+    /** Determinations on modify, by rounds (D21). Called at the end of each modify request. */
+    determineOnModify(): Promise<Responses>;
+    private determine;
+    /** The save sequence: determinations on save, validations; the write when nothing failed. */
+    save(): Promise<Responses>;
+    /**
+     * Enhanced mode (D45): `field ( mandatory )` is checked when saving, as a validation on save
+     * would (on SAP, the mandatory characteristic is only a hint for the consumer, D20): each
+     * created or changed instance with an initial mandatory field fails, with a message per field.
+     */
+    private checkMandatory;
+    /** The changes of the LUW for save_modified: created, updated and deleted instances. */
+    private changes;
+    /**
+     * `INSERT|UPDATE|MODIFY|DELETE dbtab FROM [TABLE] @source [INDICATORS SET STRUCTURE %control]
+     * MAPPING FROM ENTITY` in save_modified: the rows of the entity are written to the table of its
+     * BDEF mapping. sy-subrc 4 when a row is not found (UPDATE, DELETE) or already there (INSERT of
+     * a work area); an INSERT FROM TABLE with a duplicate key is a runtime error, as in ABAP.
+     */
+    writeMapped(bo: BoEntity, operation: string, rows: Array<{
+        values: Row;
+        control: Set<string> | undefined;
+    }>, single: boolean, indicators: boolean): Promise<{
+        subrc: number;
+        dbcnt: number;
+    }>;
+    /** save_modified (and cleanup) of the BDEFs with additional or unmanaged save. */
+    private saveModified;
+    private write;
+    /** Keys of the instances created in the LUW, by content ID. */
+    createdByCid(cid: string): {
+        bo: BoEntity;
+        key: Row;
+    } | undefined;
+    /**
+     * The instance whose ETag field covers an instance (of `bo`, with the values `row`): itself
+     * for an `etag master`, the master reached by the `etag dependent by` associations otherwise.
+     */
+    private etagMasterInstance;
+    /**
+     * The ETag value an If-Match is compared with: the ETag field of the instance or of its ETag
+     * master, as it was when the LUW began (the state the client has read: the requests of a change
+     * set carry the ETags read before it, and the changes of the LUW, a determination that updates
+     * the master for example, do not make them stale); undefined when the instance is not found.
+     */
+    etagValue(bo: BoEntity, key: Row): Promise<{
+        value: unknown;
+    } | undefined>;
+    /**
+     * `etag dependent by` (D32): the ETag field of a master changes with its dependent instances.
+     * The runtime sets it when it is an administrative time stamp it manages
+     * (`localInstanceLastChangedAt`, `lastChangedAt`) and writes the master; at save time, so that
+     * the requests of a change set check the ETag the client has read.
+     */
+    private refreshEtagMasters;
+    /**
+     * Instance and global feature control of rows about to be read (GET): __EntityControl… The
+     * global and instance authorizations of the user disable the operations they refuse, as RAP
+     * presents both to its consumers (D36).
+     */
+    features(bo: BoEntity, keys: Row[], operations: FailedOperation[], fields: string[]): Promise<{
+        disabled: Set<string>;
+        readonly: Map<string, Set<string>>;
+        global: Set<string>;
+    }>;
+    /** The operations of an entity the user may perform: global authorization and global features (D36). */
+    allowed(bo: BoEntity, operations: FailedOperation[]): Promise<Set<string>>;
+}
+export declare function operationId(op: FailedOperation): string;