@hydranium/protocol 1.0.0-next.37 → 1.0.0-next.371

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,100 @@ 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;
+}
+
+/** 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 TransferUpdateDocumentArgs<TTransfer> {}
+
+/** 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'>;
+
+/** Delete a document the session `clientId` has open: its file, then the document. */
+export type TransferDeleteDocumentArgs = Omit<TransferUpdateDocumentArgs<never>, 'model'>;
+
+/** 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;
+}
+
+/** 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;
+}
 
-/** Persist a document to disk. Wire-side projection of {@link TransferSaveArgs}. */
-export type TransferSaveDocumentArgs<TTransfer> = TransferSaveArgs<TTransfer>;
+/**
+ * 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();
    }
 }