@hydranium/protocol 1.0.0-next.39 → 1.0.0-next.391

package/src/data/events.ts

@@ -10,27 +10,29 @@
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
 import type { Project } from '../project';
-import type { TransferDocument } from '../transfer-document';
+import type { TextState, TransferDocument } from '../transfer-document';
 
 /**
  * Why an update event fired. Subscribers filter on reason for behaviour
  * decisions (e.g. dirty-flag handling, undo-history grouping, telemetry):
  *
- * - `'changed'` — the URI appeared in `DocumentBuilder.onUpdate`'s
- *   `changed` list. The framework's underlying primitive is "this URI was
- *   passed to `documentBuilder.update(changed, deleted)`", which spans
- *   `didChange` text-document events, `notifyDidChangeTextDocument` calls,
- *   and any programmatic `documentBuilder.update([uri], [])` invocation.
- *   The name matches Langium's own `changed` parameter — it's vague-on-
- *   purpose because the underlying primitive is.
- * - `'rebuilt'` — the URI was rebuilt as a cascade from another URI's
- *   build (dependency graph re-derivation), without itself being passed to
- *   `documentBuilder.update`. The complement of `'changed'`.
+ * - `'changed'` — the server's first update event for the document's current
+ *   version: its content changed since the last one. A write whose build a
+ *   later write cancelled is still `'changed'` in the build that takes over.
+ * - `'rebuilt'` — a later event for a version the server already delivered,
+ *   whether or not any client watched it then: something the document depends
+ *   on changed, or the document was built again with the same content. The
+ *   complement of `'changed'`.
  * - `'saved'` — emitted by adopters that synthesise a unified update stream
  *   from both `onDocumentUpdated` and `onDocumentSaved`. The framework's own
  *   `dispatchPhaseEvent` does NOT emit `'saved'` — saves take the dedicated
  *   `DataClientProtocol.onDocumentSaved` channel.
  *
+ * The version rule needs a version the server keeps and builds that validate.
+ * For a document no client has opened, or when rebuilds do not validate,
+ * `'changed'` means the URI was passed to `DocumentBuilder.update` for this
+ * build. A document that a validating build skips is `'changed'` every time.
+ *
  * Deletion is deliberately NOT a member. An update event carries a built
  * document, which a deleted one has none of, and the phase-driven path that
  * produces these events never runs for a deleted URI — the builder drops the
@@ -42,18 +44,29 @@ export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved';
 /**
  * Delivered on the data-server when a document's content (or existence)
  * changed. Subscribers receive this via `DocumentServerProtocol.watchModelDocument`.
- *
- * The `document` field carries the latest built state — diagnostics + root
- * are coherent with each other at the time the event fired.
  */
 export interface TransferDocumentUpdatedEvent<
    TTransfer extends TransferElement,
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
+   /** The latest built state: diagnostics and root are coherent with each other at the time the event fired. */
    document: TransferDocument<TTransfer, TDiagnostic>;
-   /** Stable identifier of the client that triggered the update. */
+   /**
+    * The client whose write this event echoes: the author of the version on a
+    * `'changed'`, and the unknown-client id on a `'rebuilt'`, which echoes no
+    * write. A recipient compares it against its own id to recognise its echo.
+    * The build that follows a document's release names the release id
+    * instead.
+    */
    sourceClientId: string;
+   /** See {@link TransferDocumentUpdateReason} for which reasons the framework sends. */
    reason: TransferDocumentUpdateReason;
+   /**
+    * The position of this event among the update and deletion events the
+    * server sent on this connection, which a watch's answer carries as of
+    * the moment it was taken: a greater one was sent later.
+    */
+   sequence: number;
 }
 
 /** Callback shape for `DataClientProtocol.onDocumentUpdated`. */
@@ -63,28 +76,25 @@ export type TransferDocumentUpdatedListener<
 > = (event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>) => void;
 
 /**
- * Delivered on the data-server when a document was persisted to disk via
- * `DataServerProtocol.saveModelDocument`. Distinct from
- * {@link TransferDocumentUpdatedEvent}: subscribers that only care about
- * persistence (external sync, editor "saved" indicators, dirty-flag
- * clear) listen for this event family instead of filtering an update
- * stream for `reason: 'saved'`.
- *
- * The `document` field carries the post-save built state — same shape
- * the synchronous `saveModelDocument` RPC response returns, delivered
- * to subscribers (`DataClientProtocol.onDocumentSaved`) so non-caller
- * clients see the persistence event too.
+ * Delivered on the data-server when a subscribed document was saved to disk,
+ * whichever client saved it, an editor's save through the LSP head included.
+ * Distinct from {@link TransferDocumentUpdatedEvent}: subscribers that only
+ * care about persistence (external sync, editor "saved" indicators,
+ * dirty-flag clear) listen for this event family instead of filtering an
+ * update stream for `reason: 'saved'`.
  */
 export interface TransferDocumentSavedEvent<
    TTransfer extends TransferElement,
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
+   /** The latest built state, taken after the save. */
    document: TransferDocument<TTransfer, TDiagnostic>;
    /**
-    * The client whose `saveModelDocument` call produced this. Every subscriber
-    * receives the event including the originator, which already had the same
-    * state as the RPC response — compare against your own id to drop the echo
-    * rather than re-rendering from it.
+    * The client whose save produced this, also when another client wrote the
+    * persisted text: the caller of `saveModelDocument` or
+    * `persistModelDocument`, or `LANGUAGE_CLIENT_ID` for an editor's save
+    * through the LSP head. Every subscriber receives the event, the saving
+    * client included, so compare against your own id to drop the echo.
     */
    sourceClientId: string;
 }
@@ -95,6 +105,28 @@ export type TransferDocumentSavedListener<
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > = (event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>) => void;
 
+/**
+ * Delivered on the data-server when a watched document's text starts or stops
+ * differing from its file, as the server last knew the file. The current
+ * answer rides on every transfer document the server sends as `text.dirty`;
+ * this carries only its changes, so a client that follows it needs no rebuild
+ * to learn of a save.
+ */
+export interface TransferDocumentDirtyChangedEvent {
+   /** Canonical URI, keyed as the subscription is. */
+   readonly uri: string;
+   /**
+    * The text the answer was decided on. It is sent before that text is
+    * built, so a `text.version` ahead of the model a client holds means an
+    * update at this version or a later one follows. Absent when the document
+    * no longer exists, or when the build that follows its release failed.
+    */
+   readonly text?: TextState;
+}
+
+/** Callback shape for `DataClientProtocol.onDocumentDirtyChanged`. */
+export type TransferDocumentDirtyChangedListener = (event: TransferDocumentDirtyChangedEvent) => void;
+
 /**
  * Delivered on the data-server when a document's backing file was removed.
  * Carries no document, and cannot: the state a
@@ -118,11 +150,25 @@ export type TransferDocumentSavedListener<
  * A watch survives the deletion, so a file that comes back resumes delivering
  * `onDocumentUpdated` to the same subscribers with no re-subscription. A
  * client that responds by closing its editor releases the watch through
- * `closeModelDocument` as usual.
+ * `closeModelDocument` as usual, and `deleteModelDocument` releases the
+ * deleting session's own.
  */
 export interface TransferDocumentDeletedEvent {
    /** Canonical URI of the removed document, keyed as the subscription is. */
    readonly uri: string;
+   /**
+    * The session whose `deleteModelDocument` removed the file, so it can tell
+    * its own deletion from another's; the unknown-client id for a file
+    * removed outside any session, as a file watcher reports one, and for one
+    * a `DataConnection` found gone after a reconnect, which no event named.
+    */
+   readonly sourceClientId: string;
+   /**
+    * The position of this event among the update and deletion events the
+    * server sent on this connection, as on an update; absent on a deletion a
+    * `DataConnection` found after a reconnect, which the server never sent.
+    */
+   readonly sequence?: number;
 }
 
 /** Callback shape for `DataClientProtocol.onDocumentDeleted`. */

package/src/data/requests.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { TransferSaveArgs, TransferUpdateArgs } from '../model-service/args';
+import type { BaseVersion } from '../model-service/base-version';
 
 /** Get the current state of a single document. The server returns the latest built version. */
 export interface GetModelDocumentArgs {
@@ -41,29 +41,108 @@ export interface GetProjectForUriArgs {
 }
 
 /**
- * Update a document's content. Wire-side projection of the facade's
- * {@link TransferUpdateArgs}; structurally identical so the data-server RPC
- * handler can forward straight to the in-process `ModelService.update`
- * without an args mapping.
+ * Update a document the session `clientId` has open. Generic over `TTransfer`
+ * so adopters parameterise the structured shape against their grammar's
+ * transfer-model overlay; passing a string is always allowed.
  */
-export type TransferUpdateDocumentArgs<TTransfer> = TransferUpdateArgs<TTransfer>;
+export interface TransferUpdateDocumentArgs<TTransfer> {
+   /** Document URI. */
+   uri: string;
+   /** The id of a live session registered on this connection. */
+   clientId: string;
+   /** The whole structured model root, or its serialised textual form. */
+   model: TTransfer | string;
+   /**
+    * What this write was authored against. A `ModelVersion` is compared
+    * against the server's current text-document version for `uri` and throws
+    * `ConflictError` on mismatch; `'any'` writes unconditionally.
+    *
+    * **Required so that an ungated write is a decision rather than an
+    * omission.** An optional gate is indistinguishable from a forgotten one at
+    * the call site, and a file of twenty writes hides the one that lost the
+    * field. Nothing else here can see that, since the defect is an absence.
+    */
+   baseVersion: BaseVersion;
+   /**
+    * Set by a session's restore after a reconnect, which sends its last write
+    * again. A model the server took was written over text that parsed, so it
+    * is written even over text that does not, as it was before the
+    * reconnect. Any other model write over such text is refused with
+    * `DocumentSyntaxError`, a save's even when it sets this.
+    */
+   restore?: boolean;
+}
+
+/** Update a document the session `clientId` has open, then persist it to disk. */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- save names its own args; it adds no field to update's
+export interface TransferSaveDocumentArgs<TTransfer> extends Omit<TransferUpdateDocumentArgs<TTransfer>, 'restore'> {}
+
+/** Persist the text the server holds for a document the session `clientId` has open, without writing a model. */
+export type TransferPersistDocumentArgs = Omit<TransferUpdateDocumentArgs<never>, 'model' | 'restore'>;
+
+/** Delete a document the session `clientId` has open: its file, then the document. */
+export type TransferDeleteDocumentArgs = Omit<TransferUpdateDocumentArgs<never>, 'model' | 'restore'>;
+
+/** Register a client session on the connection. */
+export interface CreateSessionArgs {
+   /** The session's id, minted by the client; unique in the server process while the session is live. */
+   clientId: string;
+   /** What the participant is; kept as the server session's `label`. */
+   label?: string;
+   /**
+    * A token the client keeps for the session's lifetime. It is no secret: the
+    * wire carries no authentication. A later `createSession` for the same id
+    * carrying the same token, from any connection, ends the session it names
+    * and registers the id afresh, so a client whose connection dropped before
+    * the server noticed can register again. Without it the id stays refused
+    * until the server notices.
+    */
+   resumeToken?: string;
+}
+
+/** End a client session registered on the connection. */
+export interface CloseSessionArgs {
+   clientId: string;
+}
 
-/** Persist a document to disk. Wire-side projection of {@link TransferSaveArgs}. */
-export type TransferSaveDocumentArgs<TTransfer> = TransferSaveArgs<TTransfer>;
+/** Create a document that exists nowhere yet, open for the session creating it. */
+export interface CreateModelDocumentArgs {
+   uri: string;
+   /** The id of a live session registered on this connection. */
+   clientId: string;
+   /** The document's initial content; it reaches disk with the first save. */
+   text: string;
+}
+
+/**
+ * Write several documents a session has open, all or none. `clientId` is on
+ * the set rather than on each update: an id per update would allow a set
+ * mixing clients, which the server would have to refuse.
+ */
+export interface TransferUpdateDocumentsArgs<TTransfer> {
+   /** The id of a live session registered on this connection. */
+   clientId: string;
+   /**
+    * One entry per document: a set naming one twice, by any spellings that
+    * share its canonical URI, is refused.
+    */
+   updates: Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>[];
+}
 
 /**
  * Identifies a per-document watch on the data server. Shared by both
  * `watchModelDocument` and `unwatchModelDocument` — the `(uri, clientId)`
  * pair is the watch key, so unwatching names the same watch that was
  * started. The `clientId` identifies the originator the same way it does
- * on facade-side mutations (`TransferUpdateArgs.clientId`,
- * `TransferSaveArgs.clientId`): it keys the per-`(uri, clientId)` watch
- * bucket so multiple watchers on the same wire stay distinct, AND it lets
+ * on the document writes (`TransferUpdateDocumentArgs.clientId`,
+ * `TransferSaveDocumentArgs.clientId`): it keys the per-`(uri, clientId)`
+ * watch bucket so multiple watchers on the same wire stay distinct, AND it lets
  * each watcher recognise its own echo on inbound `onDocumentUpdated` events
  * (the wire shape's `sourceClientId` carries the originating mutation's
  * `clientId`).
  */
 export interface WatchModelDocumentArgs {
+   /** Any spelling that the document URI policy maps to the document. */
    uri: string;
    /** Stable identifier for the watching client. */
    clientId: string;

package/src/debouncer.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Clock } from './clock';
+import { type Clock, type Stopwatch } from './clock';
 import { ObservableValue, type MaybeObservableValue } from './observable-value';
 import { type Disposable } from './util';
 
@@ -50,11 +50,13 @@ export interface DebouncerOptions {
  * than a breaking change.
  */
 export class Debouncer implements Disposable {
+   /** {@link DebouncerOptions.delayMs}, read at each {@link schedule}. An armed timer keeps the delay it was armed with. */
    protected readonly delay: ObservableValue<number>;
+   /** {@link DebouncerOptions.maxWaitMs}, fixed at construction unlike {@link delay}. */
    protected readonly maxWaitMs?: number;
    protected timer?: Disposable;
-   /** Virtual time of the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
-   protected firstScheduledAt?: number;
+   /** Running since the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
+   protected sinceFirstSchedule?: Stopwatch;
 
    constructor(
       protected readonly clock: Clock,
@@ -77,20 +79,17 @@ export class Debouncer implements Disposable {
     * elapses since the first pending call.
     */
    schedule(): void {
-      const now = this.clock.now();
-      if (this.firstScheduledAt === undefined) {
-         this.firstScheduledAt = now;
-      }
+      this.sinceFirstSchedule ??= this.clock.stopwatch();
       let wait = Math.max(0, this.delay.value);
       if (this.maxWaitMs !== undefined) {
-         const untilCeiling = this.firstScheduledAt + this.maxWaitMs - now;
+         const untilCeiling = this.maxWaitMs - this.sinceFirstSchedule.elapsedMs;
          wait = Math.min(wait, Math.max(0, untilCeiling));
       }
       this.timer?.dispose();
       this.timer = this.clock.setTimer(() => this.fire(), wait);
    }
 
-   /** If a fire is pending, run {@link fn} now and clear the window; otherwise a no-op. */
+   /** Run {@link fn} now if a fire is pending, clearing the window first, and do nothing otherwise. */
    flush(): void {
       if (this.timer !== undefined) {
          this.fire();
@@ -101,7 +100,7 @@ export class Debouncer implements Disposable {
    cancel(): void {
       this.timer?.dispose();
       this.timer = undefined;
-      this.firstScheduledAt = undefined;
+      this.sinceFirstSchedule = undefined;
    }
 
    /** Cancel any pending fire and release. */
@@ -109,10 +108,11 @@ export class Debouncer implements Disposable {
       this.cancel();
    }
 
+   /** Clears the window before it runs {@link fn}, so a {@link schedule} from inside `fn` opens a new one. */
    protected fire(): void {
       this.timer?.dispose();
       this.timer = undefined;
-      this.firstScheduledAt = undefined;
+      this.sinceFirstSchedule = undefined;
       this.fn();
    }
 }