@eclipse-glsp/protocol/lib/action-protocol/base-protocol.d.ts

The protocol definition for client-server communication in GLSP

/********************************************************************************
 * Copyright (c) 2021-2026 STMicroelectronics and others.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the Eclipse
 * Public License v. 2.0 are satisfied: GNU General Public License, version 2
 * with the GNU Classpath Exception which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 ********************************************************************************/
import * as sprotty from 'sprotty-protocol/lib/actions';
import { TypeGuard } from '../utils/type-util';
import { Args } from './types';
/**
 * An action is a declarative description of a behavior that shall be invoked by the receiver upon receipt of the action.
 * It is a plain data structure, and as such transferable between server and client. An action must never contain actual
 * SModelElement instances, but either refer to them via their ids or contain serializable schema for model elements.
 * Additional typeguard functions are provided via the corresponding namespace.
 */
export interface Action extends sprotty.Action {
    /**
     * Unique identifier specifying the kind of action to process.
     */
    kind: string;
}
export declare namespace Action {
    function is(object: any): object is Action;
    /**
     * Typeguard function to check wether the given object is an {@link Action} with the given `kind`.
     * @param object The object to check.
     * @param kind  The expected action kind.
     * @returns A type literal indicating wether the given object is an action with the given kind.
     */
    function hasKind(object: any, kind: string): object is Action;
}
/**
 * A general message serves as an envelope carrying an action to be transmitted between the client and the server via a DiagramServer.
 * @typeParam A the {@link Action} type that is contained by this message.
 * A typeguard function is provided via the corresponding namespace.
 */
export interface ActionMessage<A extends Action = Action> extends sprotty.ActionMessage {
    /**
     * The unique client id
     *  */
    clientId: string;
    /**
     * The action to execute.
     */
    action: A;
}
export declare namespace ActionMessage {
    function is<A extends Action>(object: any, typeguard?: TypeGuard<A>): object is ActionMessage<A>;
}
/**
 * A request action is tied to the expectation of receiving a corresponding response action. The requestId property is used to match the
 * received response with the original request. Typically its not necessary to create an explicit requestId. The requestId can be set
 * to an empty string. The action dispatcher than auto generates an request id if needed (i.e. the action was dispatched as request).
 *

 * A typeguard function, and a generic helper function to generate a request id are provided via the corresponding namespace.
 */
export interface RequestAction<Res extends ResponseAction> extends Action, sprotty.RequestAction<Res> {
    /**
     * Unique id for this request. In order to match a response to this request, the response needs to have the same id.
     */
    requestId: string;
    /**
     * Optional timeout in milliseconds. When set, `requestUntil()` uses this value instead of its
     * default timeout. This allows the sender to control how long the receiver waits for a response.
     * Precedence: explicit `timeoutMs` parameter > `action.timeout` > default (2000ms).
     */
    timeout?: number;
    /**
     * Used to ensure correct typing. Clients must not use this property
     */
    readonly _?: Res;
}
export declare namespace RequestAction {
    function is(object: any): object is RequestAction<ResponseAction>;
    /**
     * Typeguard function to check wether the given object is an {@link RequestAction} with the given `kind`.
     * @param object The object to check.
     * @param kind  The expected action kind.
     * @returns A type literal indicating wether the given object is a request action with the given kind.
     */
    function hasKind(object: any, kind: string): object is Action;
    function generateRequestId(): string;
}
/**
 * A response action is sent to respond to a request action. The responseId must match the requestId of the preceding request.
 * In case the responseId is empty, the action is handled as standalone, i.e. it was fired without a preceding request.
 * The action dispatcher of the GLSP server has a special handling for {@link RequestAction} handlers
 * and automatically sets the `responseId` of the corresponding responseAction. So on the server side its typically enough
 * to set the `responseId` to an empty string and rely on the `ActionDispatcher` for assigning the correct `responseId.
 * Additional typeguard functions are provided via the corresponding namespace.
 */
export interface ResponseAction extends Action, sprotty.ResponseAction {
    /**
     * Id corresponding to the request this action responds to.
     */
    responseId: string;
}
export declare namespace ResponseAction {
    function is(object: any): object is ResponseAction;
    /**
     * Typeguard function to check wether the given object is an {@link ResponseAction} with a non-empty response id.
     * @param object The object to check.
     * @returns A type literal indicating wether the given object is a response action with a non-empty response id.
     */
    function hasValidResponseId(object: any): object is ResponseAction;
}
/**
 * A reject action is a {@link ResponseAction} fired to indicate that a certain {@link ResponseAction}
 * has been rejected.
 * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
 * and creating new `RejectActions`.
 */
export interface RejectAction extends ResponseAction, sprotty.RejectAction {
    kind: typeof RejectAction.KIND;
    /**
     * A human-readable description of the reject reason. Typically this is an error message
     * that has been thrown when handling the corresponding {@link RequestAction}.
     */
    message: string;
    /**
     * Optional additional details.
     */
    detail?: string;
}
export declare namespace RejectAction {
    const KIND = "rejectRequest";
    function is(object: unknown): object is RejectAction;
    function create(message: string, options?: {
        detail?: string;
        responseId?: string;
    }): RejectAction;
}
/**
 * Operations are actions that denote requests from the client to _modify_ the model. Model modifications are always performed by the
 * server. After a successful modification, the server sends the updated model back to the client using the `UpdateModelAction`.
 * An operation contains a dedicated `isOperation` property that is used as a discriminator. This is necessary so that the server
 * can distinguish between plain actions and operations.
 * The corresponding namespace offers a helper function for type guard checks.
 */
export interface Operation extends Action {
    /**
     * Discriminator property to make operations distinguishable from plain {@link Action}s.
     */
    isOperation: true;
    /**
     * Optional custom arguments.
     */
    args?: Args;
}
export declare namespace Operation {
    function is(object: unknown): object is Operation;
    /**
     * Typeguard function to check wether the given object is an {@link Operation} with the given `kind`.
     * @param object The object to check.
     * @param kind  The expected operation kind.
     * @returns A type literal indicating wether the given object is an operation with the given kind.
     */
    function hasKind(object: unknown, kind: string): object is Operation;
}
/**
 * An operation that executes a list of sub-operations.
 * The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
 * and creating new `CompoundOperations`.
 */
export interface CompoundOperation extends Operation {
    kind: typeof CompoundOperation.KIND;
    /**
     * List of operations that should be executed.
     */
    operationList: Operation[];
}
export declare namespace CompoundOperation {
    const KIND = "compound";
    function is(object: unknown): object is CompoundOperation;
    function create(operationList: Operation[], options?: {
        args?: Args;
    }): CompoundOperation;
}
//# sourceMappingURL=base-protocol.d.ts.map