@eclipse-emfcloud/trigger-engine/lib/core/trigger-engine.d.ts

Generic model triggers computation engine.

import { Operation } from 'fast-json-patch';
import { Trigger } from './trigger';
/**
 * An engine for computation of further patches to a JSON document based
 * on ("triggered by") changes previously captured.
 */
export interface TriggerEngine {
    /**
     * Add a trigger that provides new patches to follow up triggering changes.
     *
     * @param trigger a trigger to add
     * @template T the JSON document type
     */
    addTrigger<T extends object = object>(trigger: Trigger<T>): void;
    /**
     * Compute the totality of additional changes to follow up the changes
     * previously applied to a `document` that are described by a given
     * `delta`.
     *
     * @param document a JSON document that has been updated. This document is in the _after_
     *   state with respect to the `delta`, which is to say that it has already been
     *   updated as described by the delta
     * @param delta a patch describing the changes that were applied to it. The `delta`
     *   may include `test` assertion operations. It is guaranteed to comprise at least
     *   one operation that is not a `test`
     * @param previousDocument the JSON `document` as it was before the changes described by
     *   the `delta` were performed on it. Thus, this is the _before_ state with respect to
     *   that `delta`
     * @returns a new patch, applicable to the current state of the `document`, describing
     *   additional changes that should be applied to it to follow up the triggering `delta`,
     *   or `undefined` if no follow-up is provided. The resulting patch, if any,
     *   is invertible according to `fast-json-patch` semantics of invertibility
     */
    applyTriggers(document: NonNullable<object>, delta: Operation[], previousDocument: NonNullable<object>): Promise<Operation[] | undefined>;
}
/**
 * Options for configuration of the default trigger engine implementation.
 */
export interface TriggerEngineOptions {
    /**
     * Whether to clone patches provided by triggers before applying them,
     * to avoid objects that they contain being modified in situ by
     * subsequent patches. This is only necessary if triggers will
     * reuse or otherwise retain the patches that they provide.
     *
     * Default is `false`.
     */
    safePatches?: boolean;
    /**
     * A limit to the number of iterations of triggers that the engine
     * will perform before assuming that some trigger(s) is/are inducing
     * an unbounded oscillation that needs to be aborted.
     *
     * Default is `1000`. Minimum is `50`.
     */
    iterationLimit?: number;
    /**
     * Run triggers effectively in parallel, meaning that, at each iteration
     *
     * - all triggers are executed on the same state of the model with the same delta
     * - the patches they return are all applied at once to the working state of the
     *   model to seed the next iteration
     * - within each iteration, triggers _do not see_ the effects of triggers that
     *   run before them
     *
     * This implies that, in parallel mode, it does not make sense to have
     * ordering dependencies between triggers and the order in which they
     * are run must not matter.
     *
     * Default is `false`, meaning strictly serial execution of triggers that each
     * see all results of previous triggers, with the concomitant cost of copying
     * and comparing model states to calculate inputs to each next trigger.
     */
    parallel?: boolean;
}
/**
 * A default implementation of the `TriggerEngine`.
 */
export declare class TriggerEngineImpl implements TriggerEngine {
    private readonly _triggers;
    private readonly _safePatches;
    private readonly _iterationLimit;
    readonly applyTriggers: TriggerEngine['applyTriggers'];
    constructor(options?: TriggerEngineOptions);
    addTrigger<T extends object = object>(trigger: Trigger<T>): void;
    protected applyTriggersInStrictSequence(document: NonNullable<object>, delta: Operation[], previousDocument: NonNullable<object>): Promise<Operation[] | undefined>;
    protected applyTriggersInParallel(document: NonNullable<object>, delta: Operation[], previousDocument: NonNullable<object>): Promise<Operation[] | undefined>;
    /**
     * Create a working copy of the given `document` that it is safe to
     * modify by patching, to compute further patches from triggers.
     *
     * @param document the document to be patched
     * @returns a safely patchable working copy of the `document`
     */
    protected createWorkingCopy(document: NonNullable<object>): NonNullable<object>;
    /**
     * Apply a patch to the working copy of the document under computation.
     *
     * @param workingCopy the working copy of the document on which triggers are being computed
     * @param patch  a patch to apply to the working copy
     */
    protected applyPatch(workingCopy: NonNullable<object>, patch: Operation[]): void;
    /**
     * Compare a `document` with the `workingCopy` evolved from it to produce a patch
     * describing the total changes to be applied to the `document` to effect the
     * totality of triggered follow-ups changes.
     *
     * @param document the original document for which triggers are computed
     * @param workingCopy the working copy resulting from iterative application of triggers
     * @returns the delta between the `document` as pre-image and the `workingCopy` as post-image
     */
    protected compare(document: NonNullable<object>, workingCopy: NonNullable<object>): Operation[];
}
//# sourceMappingURL=trigger-engine.d.ts.map