@hydranium/glsp-server 1.0.0-next.31 → 1.0.0-next.313

package/lib/command/hydranium-glsp-command-stack.js

@@ -0,0 +1,63 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { DefaultCommandStack, ModelState } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
+/**
+ * GLSP's command stack with the diagram's dirty state read from the text store:
+ * dirty while any document the diagram's client session has open differs from
+ * its file, as the store last knew the file. Undo and redo are GLSP's.
+ *
+ * GLSP's own answer counts the diagram's commands since its last save, so it
+ * misses every change the diagram did not make: another client's unsaved edit
+ * leaves it clean, and a save it did not make of a document other than the
+ * diagram's own leaves it dirty. Every `SetDirtyStateAction` GLSP sends reads
+ * this answer.
+ */
+let HydraniumGlspCommandStack = class HydraniumGlspCommandStack extends DefaultCommandStack {
+    modelState;
+    sharedServices;
+    get isDirty() {
+        const textDocuments = this.sharedServices.workspace.TextDocuments;
+        const clientId = this.modelState.clientId;
+        return textDocuments.openDocuments().some(open => open.clients.includes(clientId) && textDocuments.isDirty(open.uri));
+    }
+    /**
+     * Lifted from `@eclipse-glsp/server` 2.7.0's `DefaultCommandStack.handleError`
+     * without its `error` line: the failure is rethrown, and whoever ends it
+     * logs it. The accompanying test pins upstream's source.
+     */
+    handleError(error) {
+        this.flush();
+        this.logger.debug('A command failed; the command stack was flushed');
+        throw error;
+    }
+};
+__decorate([
+    inject(ModelState),
+    __metadata("design:type", Object)
+], HydraniumGlspCommandStack.prototype, "modelState", void 0);
+__decorate([
+    inject(HydraniumTypes.SharedCoreServices),
+    __metadata("design:type", Object)
+], HydraniumGlspCommandStack.prototype, "sharedServices", void 0);
+HydraniumGlspCommandStack = __decorate([
+    injectable()
+], HydraniumGlspCommandStack);
+export { HydraniumGlspCommandStack };
+//# sourceMappingURL=hydranium-glsp-command-stack.js.map

package/lib/command/hydranium-glsp-command-stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-glsp-command-stack.js","sourceRoot":"","sources":["../../src/command/hydranium-glsp-command-stack.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;;;;;;;;;;AAElF,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAC;AAE5E;;;;;;;;;;GAUG;AAEI,IAAM,yBAAyB,GAA/B,MAAM,yBAA0B,SAAQ,mBAAmB;IACxB,UAAU,CAAc;IACD,cAAc,CAAwB;IAEpG,IAAa,OAAO;QACjB,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,aAAa,CAAC;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAC1C,OAAO,aAAa,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACzH,CAAC;IAED;;;;OAIG;IACgB,WAAW,CAAC,KAAc;QAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,MAAM,KAAK,CAAC;IACf,CAAC;CACH,CAAA;AAnByC;IAAtC,MAAM,CAAC,UAAU,CAAC;;6DAA4C;AACD;IAA7D,MAAM,CAAC,cAAc,CAAC,kBAAkB,CAAC;;iEAA0D;AAF1F,yBAAyB;IADrC,UAAU,EAAE;GACA,yBAAyB,CAoBrC"}

package/lib/command/hydranium-glsp-operation-action-handler.d.ts

@@ -0,0 +1,64 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type Action, ActionDispatcher, type AnyObject, GLSPClientProxy, Logger, type Operation, OperationActionHandler, type OperationHandler } from '@eclipse-glsp/server';
+import { type HydraniumGlspRecordingState } from './hydranium-glsp-recording-command.js';
+/**
+ * GLSP's operation action handler, running each operation as a
+ * {@link HydraniumGlspOperationCommand} inside the state's `runExclusive`,
+ * which covers the operation, its write, the command-stack push and the
+ * submit, so neither another operation, an undo nor the storage's capture
+ * lands between them.
+ *
+ * An operation dispatched while another is open, as a handler's plain
+ * `dispatch` does, is queued behind it and its dispatch resolves at once;
+ * awaited inside the open operation, it would wait for the operation awaiting
+ * it. It writes, pushes and submits on its own, and a failure is reported to
+ * the client as GLSP reports a failed client action.
+ *
+ * Only operations are queued that way, and only while one is open, its undo's
+ * side effects included. Code running inside the boundary otherwise must not
+ * dispatch an operation and await it: a GModel factory or a submit after an
+ * operation, an undo's write and submit, the storage's render. Nor may any code
+ * inside the boundary await a dispatched undo, redo or model request, which
+ * take the boundary themselves. Each waits for the section awaiting it.
+ */
+export declare class HydraniumGlspOperationActionHandler extends OperationActionHandler {
+    protected modelState: HydraniumGlspRecordingState<AnyObject>;
+    protected readonly actionDispatcher: ActionDispatcher;
+    protected readonly logger: Logger;
+    protected readonly clientProxy: GLSPClientProxy;
+    protected executeHandler(operation: Operation, handler: OperationHandler): Promise<Action[]>;
+    /**
+     * Run `operation`; push it when its command was written, and submit the
+     * model when it executed one, written or dropped.
+     */
+    protected runOperation(operation: Operation, handler: OperationHandler): Promise<Action[]>;
+    /**
+     * Deliver what a queued operation answered: a message straight to the
+     * client, as {@link reportFailure} sends one, the rest through the
+     * dispatcher. A failure to deliver is logged, not reported as the
+     * operation's.
+     */
+    protected deliverQueued(actions: Action[]): void;
+    /**
+     * Log `error` with {@link logActionFailure}, as the server logs a failed
+     * action, and send the client the error message GLSP sends for one. A
+     * queued operation that fails once its diagram has closed, which the
+     * storage's dispose marks by clearing the state's session, is logged at
+     * `debug` and told to no client, as the server treats an ended session.
+     */
+    protected reportFailure(operation: Operation, error: unknown): void;
+    /**
+     * Send `action` straight to the client, as GLSP's server sends a failed
+     * action's message. Sent through the dispatcher instead, an action of a
+     * kind the client registered no handler for is rejected.
+     */
+    protected sendToClient(action: Action): void;
+}
+//# sourceMappingURL=hydranium-glsp-operation-action-handler.d.ts.map

package/lib/command/hydranium-glsp-operation-action-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-glsp-operation-action-handler.d.ts","sourceRoot":"","sources":["../../src/command/hydranium-glsp-operation-action-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,KAAK,MAAM,EACX,gBAAgB,EAChB,KAAK,SAAS,EACd,eAAe,EAEf,MAAM,EAEN,KAAK,SAAS,EACd,sBAAsB,EACtB,KAAK,gBAAgB,EACvB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uCAAuC,CAAC;AAEzF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBACa,mCAAoC,SAAQ,sBAAsB;IAC5E,UAAkB,UAAU,EAAE,2BAA2B,CAAC,SAAS,CAAC,CAAC;IAC3C,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAG,gBAAgB,CAAC;IACjE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAC;IAC1B,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAG,eAAe,CAAC;IAE1E,UAAmB,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWpG;IAED;;;OAGG;IACH,UAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAgB/F;IAED;;;;;OAKG;IACH,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAQ/C;IAED;;;;;;OAMG;IACH,SAAS,CAAC,aAAa,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAclE;IAED;;;;OAIG;IACH,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAM3C;CACH"}

package/lib/command/hydranium-glsp-operation-action-handler.js

@@ -0,0 +1,142 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { ActionDispatcher, GLSPClientProxy, GLSPServerError, Logger, MessageAction, OperationActionHandler } from '@eclipse-glsp/server';
+import { describeErrorWithStack } from '@hydranium/protocol';
+import { inject, injectable } from 'inversify';
+import { logActionFailure } from './diagram-edit-dropped-error.js';
+import { HydraniumGlspOperationCommand, openOperationOf, runOperation } from './hydranium-glsp-operation-command.js';
+/**
+ * GLSP's operation action handler, running each operation as a
+ * {@link HydraniumGlspOperationCommand} inside the state's `runExclusive`,
+ * which covers the operation, its write, the command-stack push and the
+ * submit, so neither another operation, an undo nor the storage's capture
+ * lands between them.
+ *
+ * An operation dispatched while another is open, as a handler's plain
+ * `dispatch` does, is queued behind it and its dispatch resolves at once;
+ * awaited inside the open operation, it would wait for the operation awaiting
+ * it. It writes, pushes and submits on its own, and a failure is reported to
+ * the client as GLSP reports a failed client action.
+ *
+ * Only operations are queued that way, and only while one is open, its undo's
+ * side effects included. Code running inside the boundary otherwise must not
+ * dispatch an operation and await it: a GModel factory or a submit after an
+ * operation, an undo's write and submit, the storage's render. Nor may any code
+ * inside the boundary await a dispatched undo, redo or model request, which
+ * take the boundary themselves. Each waits for the section awaiting it.
+ */
+let HydraniumGlspOperationActionHandler = class HydraniumGlspOperationActionHandler extends OperationActionHandler {
+    actionDispatcher;
+    logger;
+    clientProxy;
+    executeHandler(operation, handler) {
+        const queued = openOperationOf(this.modelState) !== undefined;
+        const run = this.modelState.runExclusive(() => this.runOperation(operation, handler));
+        if (!queued) {
+            return run;
+        }
+        run.then(actions => this.deliverQueued(actions), (error) => this.reportFailure(operation, error));
+        return Promise.resolve([]);
+    }
+    /**
+     * Run `operation`; push it when its command was written, and submit the
+     * model when it executed one, written or dropped.
+     */
+    async runOperation(operation, handler) {
+        // A queued operation can find the diagram read-only by the time it runs.
+        if (this.modelState.isReadonly) {
+            return [
+                MessageAction.create(`Server is in readonly-mode! Could not execute operation: ${operation.kind}`, { severity: 'WARNING' })
+            ];
+        }
+        const command = new HydraniumGlspOperationCommand(this.modelState);
+        const outcome = await runOperation(command, () => handler.execute(operation));
+        if (outcome === 'none') {
+            return [];
+        }
+        if (outcome === 'executed') {
+            await this.executeCommand(command);
+        }
+        return this.submitModel();
+    }
+    /**
+     * Deliver what a queued operation answered: a message straight to the
+     * client, as {@link reportFailure} sends one, the rest through the
+     * dispatcher. A failure to deliver is logged, not reported as the
+     * operation's.
+     */
+    deliverQueued(actions) {
+        const messages = actions.filter(action => MessageAction.is(action));
+        messages.forEach(message => this.sendToClient(message));
+        this.actionDispatcher
+            .dispatchAll(actions.filter(action => !MessageAction.is(action)))
+            .catch((error) => this.logger.warn(`Could not deliver the result of a queued operation: ${describeErrorWithStack(error)}`));
+    }
+    /**
+     * Log `error` with {@link logActionFailure}, as the server logs a failed
+     * action, and send the client the error message GLSP sends for one. A
+     * queued operation that fails once its diagram has closed, which the
+     * storage's dispose marks by clearing the state's session, is logged at
+     * `debug` and told to no client, as the server treats an ended session.
+     */
+    reportFailure(operation, error) {
+        // Queued only after a load registered the session, so none now means the diagram has closed.
+        if (this.modelState.modelSession === undefined) {
+            this.logger.debug(`Operation '${operation.kind}' ended with its diagram: ${describeErrorWithStack(error)}`);
+            return;
+        }
+        logActionFailure(this.logger, operation, error);
+        let message = `Could not process action: '${operation.kind}`;
+        let details = error instanceof Error ? error.toString() : String(error);
+        if (error instanceof GLSPServerError) {
+            details = String(error.cause);
+            message = error.message;
+        }
+        this.sendToClient(MessageAction.create(message, { severity: 'ERROR', details }));
+    }
+    /**
+     * Send `action` straight to the client, as GLSP's server sends a failed
+     * action's message. Sent through the dispatcher instead, an action of a
+     * kind the client registered no handler for is rejected.
+     */
+    sendToClient(action) {
+        try {
+            this.clientProxy.process({ clientId: this.modelState.clientId, action });
+        }
+        catch (error) {
+            this.logger.warn(`Could not send '${action.kind}' to the client: ${describeErrorWithStack(error)}`);
+        }
+    }
+};
+__decorate([
+    inject(ActionDispatcher),
+    __metadata("design:type", Object)
+], HydraniumGlspOperationActionHandler.prototype, "actionDispatcher", void 0);
+__decorate([
+    inject(Logger),
+    __metadata("design:type", Logger)
+], HydraniumGlspOperationActionHandler.prototype, "logger", void 0);
+__decorate([
+    inject(GLSPClientProxy),
+    __metadata("design:type", Object)
+], HydraniumGlspOperationActionHandler.prototype, "clientProxy", void 0);
+HydraniumGlspOperationActionHandler = __decorate([
+    injectable()
+], HydraniumGlspOperationActionHandler);
+export { HydraniumGlspOperationActionHandler };
+//# sourceMappingURL=hydranium-glsp-operation-action-handler.js.map

package/lib/command/hydranium-glsp-operation-action-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-glsp-operation-action-handler.js","sourceRoot":"","sources":["../../src/command/hydranium-glsp-operation-action-handler.ts"],"names":[],"mappings":"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"}

package/lib/command/hydranium-glsp-operation-command.d.ts

@@ -0,0 +1,250 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type AnyObject, Command, type MaybePromise } from '@eclipse-glsp/server';
+import { type AstNode, type MultiReference, type Reference } from '@hydranium/langium';
+import { type ModelVersion } from '@hydranium/protocol';
+import { type HydraniumGlspRecordingState } from './hydranium-glsp-recording-command.js';
+/**
+ * What becomes of an operation {@link HydraniumGlspOperationCommand} ran: its
+ * command written, its write dropped, or no command.
+ */
+export type OperationOutcome = 'executed' | 'dropped' | 'none';
+/**
+ * One executed side effect the operation undoes and redoes: a recording
+ * command's bridge, or a command that does not record.
+ */
+export interface OperationSideEffect {
+    undo(): MaybePromise<void>;
+    redo(): MaybePromise<void>;
+}
+/** The source model an operation changed, before and after it; a redo applies `from → to`, an undo the reverse. */
+export interface OperationTransition<TSourceModel> {
+    readonly from: TSourceModel;
+    readonly to: TSourceModel;
+}
+/** Whether an undo or a redo of an operation runs. */
+export type UndoRedoDirection = 'undo' | 'redo';
+/**
+ * The members of an operation the framework's state, recording command and
+ * operation action handler call; reached through {@link openOperationOf} and
+ * {@link runOperation}, not through the operation itself.
+ */
+export interface OperationInternals {
+    run(create: () => MaybePromise<Command | undefined>): Promise<OperationOutcome>;
+    workingRootOf(key: string, built: AstNode): AstNode;
+    existingWorkingRootOf(key: string): AstNode | undefined;
+    workingUriOf(node: AstNode): string | undefined;
+    builtNodeOf<T extends AstNode>(node: T): T;
+    recordWrittenRoot(root: AstNode): void;
+    recordDropped(current: AstNode | undefined): void;
+    recordExecuted(step: OperationSideEffect): void;
+    assertNotDuringUndoRedo(label: string): void;
+    amendBefore(update: (before: AnyObject) => AnyObject): void;
+}
+/**
+ * The canonical URI of the document whose working copy `node` belongs to;
+ * `undefined` for a node of no copy. A copy has no `$document`, so a lookup
+ * that routes by a node's document routes a copy node through this instead.
+ */
+export declare function workingUriOfCopy(node: AstNode): string | undefined;
+/** The operation open on `state`, executing, undoing or redoing its side effects; `undefined` between operations. */
+export declare function openOperationOf(state: object): OperationInternals | undefined;
+/** Run `operation` as {@link HydraniumGlspOperationCommand} describes. */
+export declare function runOperation<TSourceModel extends AnyObject>(operation: HydraniumGlspOperationCommand<TSourceModel>, create: () => MaybePromise<Command | undefined>): Promise<OperationOutcome>;
+/**
+ * One GLSP operation as a transaction, and the command-stack entry that undoes
+ * and redoes it.
+ *
+ * {@link runOperation} executes the operation's command against copies of the
+ * built roots and writes their projection once; a reader of a built root never
+ * sees an edit its write has not committed, and an edit the write drops stays
+ * out of every built root. Call it inside `runExclusive`: the copies, the write
+ * and the capture that follows assume no other operation, undo or storage
+ * capture runs meanwhile.
+ *
+ * The entry holds one model transition, from the copies' projection before the
+ * command to their projection after it, both as the documents hold them after
+ * a write (see `normalizeTransition`), and the side effects that executed, in
+ * order: each command that does not record, a `CompoundCommand`'s children
+ * counted one by one, and the bridge of each recording command at any depth.
+ * Rollback and undo run them in reverse, redo in order. A recording command
+ * executed inside an open operation writes nothing, and its own undo and redo
+ * do nothing there.
+ */
+export declare class HydraniumGlspOperationCommand<TSourceModel extends AnyObject = AnyObject> implements Command {
+    protected readonly modelState: HydraniumGlspRecordingState<TSourceModel>;
+    /** Working copies by canonical URI. */
+    protected readonly workingRoots: Map<string, AstNode>;
+    /** Built node to copy and copy to built node, across every working root, as `AstUtils.copyAstNode` records it. */
+    protected readonly trace: Map<AstNode, AstNode>;
+    /** The source root captured when the operation opened. */
+    protected sourceRootAtOpen?: AstNode;
+    /** The version of {@link sourceRootAtOpen}, which the write is gated on. */
+    protected baseVersionAtOpen?: ModelVersion;
+    /**
+     * The primary root to capture when the operation closes: the one its write
+     * produced, or the document's built one after a dropped write or one the
+     * document already held.
+     */
+    protected writtenRoot?: AstNode;
+    /** Whether the write's reconcile dropped the edit. */
+    protected dropped: boolean;
+    /** The command the operation executed. */
+    protected command?: Command;
+    /** The side effects that executed, in execution order. */
+    protected readonly steps: OperationSideEffect[];
+    /**
+     * The copies' projection when the operation opened, amended as documents
+     * join or leave the write set during it.
+     */
+    protected before?: TSourceModel;
+    protected transition?: OperationTransition<TSourceModel>;
+    /** Whether an undo or redo is running the side effects, on copies it discards. */
+    protected undoingOrRedoing: boolean;
+    constructor(modelState: HydraniumGlspRecordingState<TSourceModel>);
+    /**
+     * Open the operation, execute the command `create` makes, write the result
+     * once, and close the operation.
+     *
+     * `create` runs inside the operation, because handlers resolve their
+     * targets there. On any failure, `create`, the command or the write, the
+     * executed commands' side effects are undone, nothing is written, and the
+     * error is rethrown; after a write whose reconcile dropped the edit, the
+     * side effects are undone the same way and this answers `'dropped'`. The
+     * operation closes either way: the copies are dropped and the source root
+     * is captured again, with the base version, every tracked version and the
+     * index.
+     */
+    protected run(create: () => MaybePromise<Command | undefined>): Promise<'executed' | 'dropped' | 'none'>;
+    /**
+     * Awaited where the operation, or an undo or redo of it, yields to code it
+     * does not control: before creating the command, before each side effect
+     * executes, is undone or redone, rolls back or is compensated, before
+     * projecting the copies, before resolving an undo or redo. Does nothing; a
+     * test overrides it to land a foreign edit or a failure there.
+     */
+    protected checkpoint(_point: 'create' | 'execute' | 'project' | 'resolve' | UndoRedoDirection | 'rollback' | 'compensate'): Promise<void>;
+    /**
+     * Does nothing: {@link runOperation} executed the command; the command stack
+     * calls this when it pushes the entry.
+     */
+    execute(): Promise<void>;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    canUndo(): boolean;
+    /** The working copy of `built`, the root of the document whose canonical URI is `key`, made on the first request. */
+    protected workingRootOf(key: string, built: AstNode): AstNode;
+    /** The canonical URI of the working root `node` belongs to; `undefined` for a node of no copy. */
+    protected workingUriOf(node: AstNode): string | undefined;
+    /**
+     * The built node `node` was copied from; `node` itself for a node of no copy
+     * and for a node the operation created.
+     */
+    protected builtNodeOf<T extends AstNode>(node: T): T;
+    /**
+     * Copy the source root, and point the index at the copy, so the nodes a
+     * handler resolves by id are the nodes it edits.
+     */
+    protected open(): void;
+    /**
+     * Drop the copies, move every id added through `indexSemanticElement` from
+     * a copy back to the built node it was copied from, and capture the source
+     * root again, whether or not the write changed it.
+     */
+    protected close(): void;
+    /**
+     * Undo the side effects of the executed commands, newest first, each step
+     * on its own: a step that fails is logged and the rest are still undone.
+     * The operation's own error is the one thrown.
+     */
+    protected rollback(): Promise<void>;
+    /**
+     * Run each of `actions`, each reverting a side effect of its own: a failure
+     * is logged as `what` failing and the rest still run, so one step that
+     * cannot be reverted leaves no other step applied. The caller reports its
+     * own failure, not these.
+     */
+    protected runEach(actions: ReadonlyArray<() => MaybePromise<void>>, what: string, point: 'rollback' | 'compensate'): Promise<void>;
+    /**
+     * `command` with every side effect it executes recorded as a step: the
+     * command itself, or for a `CompoundCommand` each child, at any depth. A
+     * tracked command's own undo and redo do nothing, so a `CompoundCommand`
+     * reverting its children when a later one throws leaves that to the steps.
+     *
+     * The children are read from GLSP's protected `CompoundCommand.commands`;
+     * should that field stop being readable, a compound becomes one step and
+     * its children's side effects no longer interleave with the bridges.
+     */
+    protected tracked(command: Command): Command;
+    /** The model projected from the working copies, cloned; `undefined` for a state that projects none. */
+    protected project(): Promise<TSourceModel | undefined>;
+    /**
+     * Resolve the transition onto the current model, run the commands' side
+     * effects, then write once, gated on the versions the model was read at. A
+     * collision does nothing but warn; a transition with nothing left to apply,
+     * or one the model already holds, still runs the side effects.
+     *
+     * The caller holds `runExclusive`, which nothing here takes again.
+     */
+    protected undoOrRedo(direction: UndoRedoDirection): Promise<void>;
+    /**
+     * Write `model` once through the state's write path, gated on the versions
+     * read when the operation opened, a conflict reconciled as for any write of
+     * the state; `false` when the reconcile dropped it.
+     */
+    protected write(model: TSourceModel): Promise<boolean>;
+    /**
+     * Run the recorded steps of an undo or redo against fresh copies of the
+     * built roots, made on demand as in an operation and discarded unwritten,
+     * then write `merged`, the resolved transition, through {@link write}: that
+     * write is what changes the model, and a step that edits `sourceRoot` must
+     * not reach the root every reader shares. A recording command executed here
+     * throws.
+     *
+     * When a step or the write throws, or the write's reconcile drops it, the
+     * steps already run are run the other way, newest first, and the error is
+     * rethrown with nothing written; GLSP's command stack then flushes, as it
+     * does for any undo or redo that fails.
+     */
+    protected undoOrRedoSideEffects(direction: UndoRedoDirection, merged?: TSourceModel): Promise<void>;
+    /**
+     * Run `steps`, which a failed undo or redo already ran, the other way, each
+     * on its own as {@link rollback} does; the undo or redo's own error is the
+     * one thrown.
+     */
+    protected compensate(steps: readonly OperationSideEffect[], direction: UndoRedoDirection): Promise<void>;
+    /**
+     * The transition and the recorded steps as `direction` runs them: an undo
+     * runs the transition backwards and each step's undo, newest first, and is
+     * reverted by each step's redo; a redo the other way round.
+     */
+    protected inDirection(direction: UndoRedoDirection): {
+        readonly transition?: OperationTransition<TSourceModel>;
+        readonly steps: readonly OperationSideEffect[];
+        run(step: OperationSideEffect): MaybePromise<void>;
+        revert(step: OperationSideEffect): MaybePromise<void>;
+    };
+    /**
+     * The copy's stand-in for `original`: its target is the copy of
+     * `original`'s target once one exists, read when asked so a copy made later
+     * in the operation is found, else that target itself. A handler compares a
+     * target by identity with nodes it resolved from a copy.
+     */
+    protected buildWorkingReference(original: Reference): Reference;
+    /** {@link buildWorkingReference} for a reference with several targets. */
+    protected buildWorkingMultiReference(original: MultiReference): MultiReference;
+    /**
+     * Replace every multi-reference under `working` with a working one.
+     * `AstUtils.copyAstNode` rebuilds single references only and leaves a
+     * multi-reference object shared with the built root, whose targets are
+     * built nodes.
+     */
+    protected rebuildWorkingMultiReferences(working: AstNode): void;
+}
+//# sourceMappingURL=hydranium-glsp-operation-command.d.ts.map

package/lib/command/hydranium-glsp-operation-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-glsp-operation-command.d.ts","sourceRoot":"","sources":["../../src/command/hydranium-glsp-operation-command.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,SAAS,EAAE,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACnG,OAAO,EACJ,KAAK,OAAO,EAMZ,KAAK,cAAc,EAEnB,KAAK,SAAS,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,YAAY,EAA0B,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uCAAuC,CAAC;AAEzF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACjC,IAAI,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,mHAAmH;AACnH,MAAM,WAAW,mBAAmB,CAAC,YAAY;IAC9C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;CAC5B;AAED,sDAAsD;AACtD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAChC,GAAG,CAAC,MAAM,EAAE,MAAM,YAAY,CAAC,OAAO,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAChF,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IACpD,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACxD,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAChD,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IAC3C,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;IAClD,cAAc,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAChD,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,WAAW,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,SAAS,GAAG,IAAI,CAAC;CAC9D;AAMD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAElE;AAGD,qHAAqH;AACrH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE7E;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,YAAY,SAAS,SAAS,EACxD,SAAS,EAAE,6BAA6B,CAAC,YAAY,CAAC,EACtD,MAAM,EAAE,MAAM,YAAY,CAAC,OAAO,GAAG,SAAS,CAAC,GAC/C,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,6BAA6B,CAAC,YAAY,SAAS,SAAS,GAAG,SAAS,CAAE,YAAW,OAAO;IA8B1F,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC,YAAY,CAAC;IA7BpF,uCAAuC;IACvC,SAAS,CAAC,QAAQ,CAAC,YAAY,uBAA8B;IAC7D,kHAAkH;IAClH,SAAS,CAAC,QAAQ,CAAC,KAAK,wBAA+B;IACvD,0DAA0D;IAC1D,SAAS,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACrC,4EAA4E;IAC5E,SAAS,CAAC,iBAAiB,CAAC,EAAE,YAAY,CAAC;IAC3C;;;;OAIG;IACH,SAAS,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAChC,sDAAsD;IACtD,SAAS,CAAC,OAAO,UAAS;IAC1B,0CAA0C;IAC1C,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC5B,0DAA0D;IAC1D,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,EAAE,CAAM;IACrD;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAChC,SAAS,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;IACzD,kFAAkF;IAClF,SAAS,CAAC,gBAAgB,UAAS;IAEnC,YAA+B,UAAU,EAAE,2BAA2B,CAAC,YAAY,CAAC,EAgCnF;IAED;;;;;;;;;;;;OAYG;IACH,UAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,YAAY,CAAC,OAAO,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC,CAoC7G;IAED;;;;;;OAMG;IACH,UAAgB,UAAU,CACvB,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,iBAAiB,GAAG,UAAU,GAAG,YAAY,GACpG,OAAO,CAAC,IAAI,CAAC,CAEf;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1B;IAED,OAAO,IAAI,OAAO,CAEjB;IAED,qHAAqH;IACrH,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAgB5D;IAED,kGAAkG;IAClG,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQxD;IAED;;;OAGG;IACH,SAAS,CAAC,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAMnD;IAED;;;OAGG;IACH,SAAS,CAAC,IAAI,IAAI,IAAI,CAOrB;IAED;;;;OAIG;IACH,SAAS,CAAC,KAAK,IAAI,IAAI,CAQtB;IAED;;;;OAIG;IACH,UAAgB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAMxC;IAED;;;;;OAKG;IACH,UAAgB,OAAO,CACpB,OAAO,EAAE,aAAa,CAAC,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC,EAChD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,UAAU,GAAG,YAAY,GAChC,OAAO,CAAC,IAAI,CAAC,CASf;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAkB3C;IAED,uGAAuG;IACvG,UAAgB,OAAO,IAAI,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAG3D;IAED;;;;;;;OAOG;IACH,UAAgB,UAAU,CAAC,SAAS,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BtE;IAED;;;;OAIG;IACH,UAAgB,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;IAED;;;;;;;;;;;;OAYG;IACH,UAAgB,qBAAqB,CAAC,SAAS,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BxG;IAED;;;;OAIG;IACH,UAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,EAAE,SAAS,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7G;IAED;;;;OAIG;IACH,SAAS,CAAC,WAAW,CAAC,SAAS,EAAE,iBAAiB,GAAG;QAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;QACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;QAC/C,GAAG,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACnD,MAAM,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;KACxD,CAUA;IAED;;;;;OAKG;IACH,SAAS,CAAC,qBAAqB,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS,CAgB9D;IAED,0EAA0E;IAC1E,SAAS,CAAC,0BAA0B,CAAC,QAAQ,EAAE,cAAc,GAAG,cAAc,CAY7E;IAED;;;;;OAKG;IACH,SAAS,CAAC,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgB9D;CACH"}