@hydranium/protocol 1.0.0-next.12 → 1.0.0-next.123

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/README.md +35 -1
  2. package/lib/client/data-connection.d.ts +114 -0
  3. package/lib/client/data-connection.d.ts.map +1 -0
  4. package/lib/client/data-connection.js +143 -0
  5. package/lib/client/data-connection.js.map +1 -0
  6. package/lib/client/data-events.d.ts +9 -1
  7. package/lib/client/data-events.d.ts.map +1 -1
  8. package/lib/client/data-events.js +14 -0
  9. package/lib/client/data-events.js.map +1 -1
  10. package/lib/client/data-port.d.ts +17 -22
  11. package/lib/client/data-port.d.ts.map +1 -1
  12. package/lib/client/data-session.d.ts +235 -82
  13. package/lib/client/data-session.d.ts.map +1 -1
  14. package/lib/client/data-session.js +337 -108
  15. package/lib/client/data-session.js.map +1 -1
  16. package/lib/client/index.d.ts +10 -7
  17. package/lib/client/index.d.ts.map +1 -1
  18. package/lib/client/index.js +10 -7
  19. package/lib/client/index.js.map +1 -1
  20. package/lib/client/message-relay.d.ts +8 -2
  21. package/lib/client/message-relay.d.ts.map +1 -1
  22. package/lib/client/message-relay.js +10 -4
  23. package/lib/client/message-relay.js.map +1 -1
  24. package/lib/client/rpc-connection.d.ts +143 -0
  25. package/lib/client/rpc-connection.d.ts.map +1 -0
  26. package/lib/client/rpc-connection.js +171 -0
  27. package/lib/client/rpc-connection.js.map +1 -0
  28. package/lib/client-ids.d.ts +41 -0
  29. package/lib/client-ids.d.ts.map +1 -0
  30. package/lib/client-ids.js +44 -0
  31. package/lib/client-ids.js.map +1 -0
  32. package/lib/data/data-protocol-methods.d.ts +4 -4
  33. package/lib/data/data-protocol-methods.d.ts.map +1 -1
  34. package/lib/data/data-protocol-methods.js +10 -1
  35. package/lib/data/data-protocol-methods.js.map +1 -1
  36. package/lib/data/data-server-protocol.d.ts +100 -31
  37. package/lib/data/data-server-protocol.d.ts.map +1 -1
  38. package/lib/data/events.d.ts +70 -3
  39. package/lib/data/events.d.ts.map +1 -1
  40. package/lib/data/requests.d.ts +67 -11
  41. package/lib/data/requests.d.ts.map +1 -1
  42. package/lib/errors.d.ts +91 -12
  43. package/lib/errors.d.ts.map +1 -1
  44. package/lib/errors.js +127 -18
  45. package/lib/errors.js.map +1 -1
  46. package/lib/index.d.ts +2 -0
  47. package/lib/index.d.ts.map +1 -1
  48. package/lib/index.js +5 -0
  49. package/lib/index.js.map +1 -1
  50. package/lib/latency-collector.d.ts +8 -4
  51. package/lib/latency-collector.d.ts.map +1 -1
  52. package/lib/latency-collector.js.map +1 -1
  53. package/lib/messages/index.d.ts +29 -0
  54. package/lib/messages/index.d.ts.map +1 -0
  55. package/lib/messages/index.js +55 -0
  56. package/lib/messages/index.js.map +1 -0
  57. package/lib/messages/primitives.d.ts +188 -0
  58. package/lib/messages/primitives.d.ts.map +1 -0
  59. package/lib/messages/primitives.js +161 -0
  60. package/lib/messages/primitives.js.map +1 -0
  61. package/lib/model-server.d.ts +44 -13
  62. package/lib/model-server.d.ts.map +1 -1
  63. package/lib/model-server.js +4 -2
  64. package/lib/model-server.js.map +1 -1
  65. package/lib/model-service/based-on.d.ts +57 -0
  66. package/lib/model-service/based-on.d.ts.map +1 -0
  67. package/lib/model-service/based-on.js +37 -0
  68. package/lib/model-service/based-on.js.map +1 -0
  69. package/lib/model-service/index.d.ts +1 -1
  70. package/lib/model-service/index.d.ts.map +1 -1
  71. package/lib/model-service/index.js +4 -5
  72. package/lib/model-service/index.js.map +1 -1
  73. package/lib/patch-merge.d.ts +28 -27
  74. package/lib/patch-merge.d.ts.map +1 -1
  75. package/lib/patch-merge.js +66 -22
  76. package/lib/patch-merge.js.map +1 -1
  77. package/lib/profile-session.d.ts +8 -4
  78. package/lib/profile-session.d.ts.map +1 -1
  79. package/lib/profile-session.js.map +1 -1
  80. package/lib/rpc/bind-rpc-methods.d.ts +29 -3
  81. package/lib/rpc/bind-rpc-methods.d.ts.map +1 -1
  82. package/lib/rpc/bind-rpc-methods.js +22 -3
  83. package/lib/rpc/bind-rpc-methods.js.map +1 -1
  84. package/lib/rpc/create-rpc-proxy.d.ts +7 -0
  85. package/lib/rpc/create-rpc-proxy.d.ts.map +1 -1
  86. package/lib/rpc/create-rpc-proxy.js +6 -1
  87. package/lib/rpc/create-rpc-proxy.js.map +1 -1
  88. package/lib/testing/catalogue-audit.d.ts +80 -0
  89. package/lib/testing/catalogue-audit.d.ts.map +1 -0
  90. package/lib/testing/catalogue-audit.js +94 -0
  91. package/lib/testing/catalogue-audit.js.map +1 -0
  92. package/lib/testing/data-doubles.d.ts +11 -12
  93. package/lib/testing/data-doubles.d.ts.map +1 -1
  94. package/lib/testing/data-doubles.js +14 -5
  95. package/lib/testing/data-doubles.js.map +1 -1
  96. package/lib/testing/index.d.ts +1 -0
  97. package/lib/testing/index.d.ts.map +1 -1
  98. package/lib/testing/index.js +4 -1
  99. package/lib/testing/index.js.map +1 -1
  100. package/lib/transfer-diagnostic.d.ts +33 -0
  101. package/lib/transfer-diagnostic.d.ts.map +1 -1
  102. package/lib/transfer-diagnostic.js +23 -0
  103. package/lib/transfer-diagnostic.js.map +1 -1
  104. package/lib/transfer-document.d.ts +14 -5
  105. package/lib/transfer-document.d.ts.map +1 -1
  106. package/lib/transfer-document.js +14 -1
  107. package/lib/transfer-document.js.map +1 -1
  108. package/package.json +11 -2
  109. package/src/client/data-connection.ts +216 -0
  110. package/src/client/data-events.ts +24 -1
  111. package/src/client/data-port.ts +17 -23
  112. package/src/client/data-session.ts +447 -128
  113. package/src/client/index.ts +10 -7
  114. package/src/client/message-relay.ts +28 -6
  115. package/src/client/rpc-connection.ts +235 -0
  116. package/src/client-ids.ts +45 -0
  117. package/src/data/data-protocol-methods.ts +10 -3
  118. package/src/data/data-server-protocol.ts +119 -31
  119. package/src/data/events.ts +74 -3
  120. package/src/data/requests.ts +71 -11
  121. package/src/errors.ts +139 -20
  122. package/src/index.ts +5 -0
  123. package/src/latency-collector.ts +8 -3
  124. package/src/messages/index.ts +36 -0
  125. package/src/messages/primitives.ts +271 -0
  126. package/src/model-server.ts +47 -18
  127. package/src/model-service/based-on.ts +63 -0
  128. package/src/model-service/index.ts +4 -5
  129. package/src/patch-merge.ts +90 -37
  130. package/src/profile-session.ts +9 -4
  131. package/src/rpc/bind-rpc-methods.ts +49 -4
  132. package/src/rpc/create-rpc-proxy.ts +14 -1
  133. package/src/testing/catalogue-audit.ts +111 -0
  134. package/src/testing/data-doubles.ts +33 -17
  135. package/src/testing/index.ts +4 -1
  136. package/src/transfer-diagnostic.ts +40 -0
  137. package/src/transfer-document.ts +21 -6
  138. package/lib/model-service/args.d.ts +0 -64
  139. package/lib/model-service/args.d.ts.map +0 -1
  140. package/lib/model-service/args.js +0 -11
  141. package/lib/model-service/args.js.map +0 -1
  142. package/src/model-service/args.ts +0 -67
@@ -6,84 +6,162 @@
6
6
  *
7
7
  * SPDX-License-Identifier: MIT
8
8
  ********************************************************************************/
9
- import type { MessageConnection } from 'vscode-jsonrpc';
10
- import { type DataClientProtocol, type DataServerProtocol } from '../data';
11
- import { type RpcProxy } from '../rpc';
9
+ import type { DataServerProtocol, DiagnosticOf } from '../data';
10
+ import type { SnapshotVersion } from '../model-service/based-on';
11
+ import { type ResolvedMessage } from '../messages/primitives';
12
+ import type { OpenModelArgs } from '../model-server';
13
+ import type { MaybePromise } from '../util';
14
+ import type { RpcProxy } from '../rpc';
12
15
  import type { TransferDocument } from '../transfer-document';
13
16
  import type { TransferElement } from '../transfer-element';
14
- import type { DataPort } from './data-port';
15
- /** Options for {@link DataSession}. */
16
- export interface DataSessionOptions {
17
- /**
18
- * Wire namespace the server is addressed under. Defaults to the
19
- * framework's {@link DATA_SERVER_WIRE_PREFIX}, which is what an unmodified
20
- * `DataServer` binds. Override only alongside the server's own
21
- * `methodNamespace` option — a mismatch turns every request into
22
- * "Unhandled method" rather than failing at wire-up.
23
- */
24
- readonly methodNamespace?: string;
25
- }
26
- /** One connection generation: its connection, its proxy, and its readiness. */
27
- interface Generation<TTransfer extends TransferElement> {
28
- readonly connection: Promise<MessageConnection>;
29
- readonly server: RpcProxy<DataServerProtocol<TTransfer>>;
30
- /** Set on first use; the shared readiness gate for this generation. */
31
- ready?: Promise<void>;
17
+ /**
18
+ * A session could not re-open a document it had open after its connection
19
+ * dropped.
20
+ */
21
+ export declare const DATA_SESSION_RESTORE_FAILED: import("../messages/primitives").MessageDefinition<"Could not restore {uri} after reconnecting to the data server: {detail}">;
22
+ /**
23
+ * A session re-opened documents after its connection dropped whose version had
24
+ * moved on since the session's last unsaved write to them: another client
25
+ * edited them, even while the session was still connected, the server reverted
26
+ * them to what is on disk, or the server restarted. The session's unsaved edits
27
+ * may be gone.
28
+ */
29
+ export declare const DATA_SESSION_UNSAVED_LOST: import("../messages/primitives").MessageDefinition<"Unsaved changes to {uris} may have been lost when the connection to the data server dropped.">;
30
+ /**
31
+ * What one of `TServer`'s document methods takes, minus the `clientId` a
32
+ * {@link DataSession} stamps itself.
33
+ *
34
+ * Read off the SERVER's signature, not off the framework's own arg type: an
35
+ * adopter server widens these, and a wrapper declared against the narrow
36
+ * shape rejects the extra field on a fresh object literal, so that call
37
+ * cannot go through a session at all.
38
+ */
39
+ export type DataSessionArgs<TMethod extends (args: never) => unknown> = Omit<Parameters<TMethod>[0], 'clientId'>;
40
+ /**
41
+ * Open a document through a session; the session supplies `clientId`. Only the
42
+ * URI and the open's options: a session's open reads the file, and the server
43
+ * ignores the `languageId`, `version` and `text` seeds of `OpenModelArgs`, so
44
+ * accepting them here would let a caller believe they took effect.
45
+ */
46
+ export type DataSessionOpenArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = Pick<OpenModelArgs, 'uri' | 'options'>;
47
+ /** Create a document through a session; the session supplies `clientId`. */
48
+ export type DataSessionCreateArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['createModelDocument']>;
49
+ /** Close a document through a session; the session supplies `clientId`. */
50
+ export type DataSessionCloseArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['closeModelDocument']>;
51
+ /** Update a document through a session; the session supplies `clientId`. */
52
+ export type DataSessionUpdateArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['updateModelDocument']>;
53
+ /** Update several documents at once through a session; the session supplies `clientId`. */
54
+ export type DataSessionUpdatesArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['updateModelDocuments']>;
55
+ /** Persist a document through a session; the session supplies `clientId`. */
56
+ export type DataSessionSaveArgs<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = DataSessionArgs<TServer['saveModelDocument']>;
57
+ /** The document a session hands back, carrying its server's diagnostic shape. */
58
+ export type DataSessionDocument<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> = TransferDocument<TTransfer, DiagnosticOf<TServer>>;
59
+ /**
60
+ * What a {@link DataSession} needs from the connection that minted it.
61
+ *
62
+ * Narrower than the connection itself so the dependency points one way:
63
+ * `DataConnection` constructs sessions, and nothing here imports it back.
64
+ */
65
+ export interface DataSessionHost<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>>> {
66
+ /** The connected, READY proxy of the current connection; a new object after each reconnect. */
67
+ connected(): Promise<RpcProxy<TServer>>;
68
+ releaseSession(session: DataSession<TTransfer, TServer>): void;
69
+ /** Surface a failure no caller is waiting on, such as restoring a document after a reconnect. */
70
+ reportError?(error: unknown, reported: ResolvedMessage): void;
32
71
  }
33
72
  /**
34
- * The host-invariant half of talking to the data head: everything above
35
- * {@link DataPort} that would otherwise be re-derived by every host
36
- * adapter.
73
+ * Builds the session `DataConnection.createSession` hands out, for an adopter
74
+ * that extends {@link DataSession}. The connection has minted `clientId` and
75
+ * checked it by then.
76
+ */
77
+ export type DataSessionFactory<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>>> = (clientId: string, host: DataSessionHost<TTransfer, TServer>, label: string) => DataSession<TTransfer, TServer>;
78
+ /**
79
+ * One participant on a data connection: a properties panel, a tree, a form
80
+ * editor. The client side of a server client session, registered over the
81
+ * wire under {@link clientId}.
37
82
  *
38
- * Three jobs, and deliberately no fourth:
83
+ * The session writes only what it has open: the server refuses its update or
84
+ * save of a document it has not opened with a `DocumentNotOpenError` code.
85
+ * Every call waits for the registration, so the first can be issued at once.
39
86
  *
40
- * 1. **Build the typed proxy** over the port's connection, with the framework's
41
- * wire prefix and its drift-proof client-method allowlist.
42
- * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
43
- * across concurrent callers. A socket client can connect before the
44
- * workspace walk finishes, and an early request is then answered correctly
45
- * from an empty registry, which reads as a broken project tier rather than
46
- * as a race.
47
- * 3. **Own the reconnect policy**, by dropping its connection generation when
48
- * the port disposes and building a fresh one on the next request.
87
+ * Every document operation stamps {@link clientId} itself. A caller that
88
+ * passed its own could pass another participant's, and the server would
89
+ * attribute the write and close the document accordingly.
49
90
  *
50
- * It does **not** wrap the protocol methods; callers reach them through
51
- * {@link connected}. The one exception is {@link openDocument}, which exists
52
- * because the open/watch *order* is silently wrong the other way round — see
53
- * its own doc.
91
+ * {@link closeDocument} and {@link dispose} first wait, up to
92
+ * {@link settleBeforeCloseMs}, for this session's calls still in flight on the
93
+ * URI, or on any URI for `dispose`: a save sent just before its close would
94
+ * otherwise reach the server after it, and fail as not open.
54
95
  *
55
- * Generic over the transfer root so this file names no grammar. An adopter
56
- * binds the concrete root (or the union of them, for a multi-grammar head) at
57
- * its own edge.
96
+ * After the connection drops, the session registers again under the same id,
97
+ * re-opens and re-watches what it had open, and reports the documents whose
98
+ * unsaved edits did not survive; see {@link restore}. The connection does this at
99
+ * once for a session with documents open, and any session's next call does it
100
+ * too.
101
+ *
102
+ * Generic over the transfer root so this file names no grammar.
103
+ *
104
+ * `TServer` is bound to a server answering with ITS OWN diagnostic shape, read
105
+ * back off the parameter being bound. Simplifying that to
106
+ * `DataServerProtocol<TTransfer>` compiles and costs the wrappers their
107
+ * return type: every call through `TServer` would resolve against that looser
108
+ * bound, so an adopter's diagnostics would come back as the framework's and
109
+ * the document would have to be cast on the way out.
58
110
  */
59
- export declare class DataSession<TTransfer extends TransferElement> {
60
- protected readonly port: DataPort;
61
- protected readonly client: DataClientProtocol<TTransfer>;
62
- protected readonly methodNamespace: string;
63
- /** The current generation, or `undefined` before the first request / after a teardown. */
64
- protected generation?: Generation<TTransfer>;
111
+ export declare class DataSession<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>> {
112
+ readonly clientId: string;
113
+ protected readonly host: DataSessionHost<TTransfer, TServer>;
114
+ readonly label: string;
115
+ /**
116
+ * How long {@link closeDocument} and {@link dispose} wait for this session's
117
+ * calls in flight before closing anyway. Long, because the wait only runs
118
+ * out when a call hangs, and a close sent while a save is still running
119
+ * fails that save.
120
+ */
121
+ protected readonly settleBeforeCloseMs: number;
122
+ /** URIs this session has open, re-opened after a reconnect. */
123
+ protected readonly openUris: Set<string>;
124
+ /**
125
+ * Per URI, how many opens of it this session has under way. Such a URI
126
+ * counts as open for {@link withOpenDocument}, which would otherwise close
127
+ * it under the open that is still being made.
128
+ */
129
+ protected readonly openingUris: Map<string, number>;
130
+ /**
131
+ * Per URI written since its last save, the version the server answered this
132
+ * session's last write with; see {@link restore}.
133
+ */
134
+ protected readonly unsavedWrites: Map<string, SnapshotVersion>;
135
+ /** Per URI, this session's calls still in flight on it, which a close waits for. */
136
+ protected readonly inFlight: Map<string, Set<Promise<unknown>>>;
137
+ /**
138
+ * Sent with every registration, so the server lets this session register
139
+ * its id again while the dropped connection's session is still live there:
140
+ * a server that has not yet noticed the drop would otherwise refuse the id
141
+ * as a duplicate until it does.
142
+ */
143
+ protected readonly resumeToken: string;
144
+ /** The proxy the session is registered on; another one means the connection was replaced. */
145
+ protected registeredOn?: RpcProxy<TServer>;
146
+ protected registration?: Promise<void>;
65
147
  protected disposed: boolean;
66
- protected readonly portDisposeListener: {
67
- dispose(): void;
68
- };
69
- constructor(port: DataPort, client: DataClientProtocol<TTransfer>, options?: DataSessionOptions);
70
- /** The identity every request is made under — the port's, not a second one. */
71
- get clientId(): string;
72
- /**
73
- * The connected, READY server proxy.
74
- *
75
- * Returns the proxy rather than `void` on purpose. A reconnect replaces the
76
- * proxy, so a caller that cached one from an earlier call would go on
77
- * addressing a dead connection with no error — handing it back per call
78
- * makes the stale reference unrepresentable.
79
- *
80
- * Concurrent callers share one readiness promise, so `waitForReady` is
81
- * awaited once per generation and not once per caller.
148
+ /**
149
+ * Disposed through {@link detach} rather than {@link dispose}, so nothing may
150
+ * be sent. Folding it into {@link disposed} would send the session's close
151
+ * over a connection that is going away.
82
152
  */
83
- connected(): Promise<RpcProxy<DataServerProtocol<TTransfer>>>;
153
+ protected detached: boolean;
154
+ constructor(clientId: string, host: DataSessionHost<TTransfer, TServer>, label: string);
84
155
  /**
85
- * Open `uri` for editing and start watching it, in that order, returning
86
- * the opened snapshot.
156
+ * The connected, READY server proxy once this session is registered on it,
157
+ * for protocol methods this session does not wrap. The proxy stamps
158
+ * nothing: pass this session's {@link clientId} to any method that carries
159
+ * one.
160
+ */
161
+ connected(): Promise<RpcProxy<TServer>>;
162
+ /**
163
+ * Open `args.uri` for editing and start watching it, in that order,
164
+ * returning the opened snapshot.
87
165
  *
88
166
  * **The order is the whole reason this method exists.**
89
167
  * `watchModelDocument` baselines its dedup fingerprint from the *current*
@@ -91,39 +169,114 @@ export declare class DataSession<TTransfer extends TransferElement> {
91
169
  * baseline, and the first phase event after the open arrives as a spurious
92
170
  * `'changed'` — which a widget that resets its in-memory root to the server
93
171
  * view misreads as a concurrent third-party write, losing whatever the user
94
- * had typed. Nothing about the wrong order fails loudly, so it is encoded
95
- * here rather than documented and re-derived.
172
+ * had typed.
96
173
  *
97
174
  * Note that the returned snapshot's empty `diagnostics` does not mean
98
175
  * valid: `open` settles at the integrity landmark, not at validation.
99
176
  * Validity arrives asynchronously on `onDocumentUpdated`, or synchronously
100
177
  * from `getModelDocument({ includeDiagnostics: true })`.
101
178
  */
102
- openDocument(uri: string): Promise<TransferDocument<TTransfer>>;
179
+ openDocument(args: DataSessionOpenArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>>;
180
+ /**
181
+ * Create a document that exists nowhere yet, open and watched for this
182
+ * session; it reaches disk with the first {@link saveDocument}. The server
183
+ * refuses a URI that exists on disk or that any client has open.
184
+ */
185
+ createDocument(args: DataSessionCreateArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>>;
186
+ /**
187
+ * Watch a document this session just opened, and record it as open. A
188
+ * failed watch closes it again: the caller sees a failed open and so would
189
+ * never close it.
190
+ */
191
+ protected watchOpened(server: RpcProxy<TServer>, uri: string, document: DataSessionDocument<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>>;
192
+ /**
193
+ * Close `args.uri`, once this session's calls on it have settled or
194
+ * {@link settleBeforeCloseMs} has passed. The server unwatches implicitly,
195
+ * so this is the dual of {@link openDocument} and needs no separate unwatch.
196
+ */
197
+ closeDocument(args: DataSessionCloseArgs<TTransfer, TServer>): Promise<void>;
198
+ /**
199
+ * Open `args.uri`, run `fn` with the opened snapshot, and close it once
200
+ * `fn` settles, whether it returned or threw. A URI this session already
201
+ * had open, or is still opening through another call, stays open: the close
202
+ * undoes only the open this call made.
203
+ */
204
+ withOpenDocument<T>(args: DataSessionOpenArgs<TTransfer, TServer>, fn: (document: DataSessionDocument<TTransfer, TServer>) => MaybePromise<T>): Promise<T>;
205
+ /** Write `args.model` back as this session. The session must have `args.uri` open. */
206
+ updateDocument(args: DataSessionUpdateArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>>;
103
207
  /**
104
- * Close `uri`. The server unwatches implicitly, so this is the dual of
105
- * {@link openDocument} and needs no separate unwatch.
208
+ * Write several documents this session has open, all or none: the server
209
+ * refuses the whole set, before any text applies, when one is stale or not
210
+ * open. Resolves to the documents in the order given.
106
211
  */
107
- closeDocument(uri: string): Promise<void>;
212
+ updateDocuments(args: DataSessionUpdatesArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>[]>;
213
+ /** Persist `args.model` to disk as this session. The session must have `args.uri` open. */
214
+ saveDocument(args: DataSessionSaveArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>>;
108
215
  /**
109
- * Whether `event.sourceClientId` identifies this session's own write.
216
+ * Whether `sourceClientId` identifies this session's own write.
110
217
  *
111
218
  * Every watcher needs this and the check is one comparison, so getting it
112
219
  * wrong is cheap to do and expensive to find: an unfiltered echo looks
113
220
  * exactly like a concurrent third-party edit.
114
221
  */
115
222
  isOwnEcho(sourceClientId: string): boolean;
116
- /** Tear down the current connection and stop tracking the port. Idempotent. */
223
+ /**
224
+ * End the session: detach it from the connection at once, and once its
225
+ * calls in flight have settled or {@link settleBeforeCloseMs} has passed,
226
+ * end it on the server, which closes everything it has open. Idempotent,
227
+ * and leaves the connection usable by its other sessions.
228
+ *
229
+ * Every later call rejects. The server close is not awaited, because a
230
+ * `Disposable` cannot be; a close that fails leaves the session to the
231
+ * server's connection-close cleanup.
232
+ */
117
233
  dispose(): void;
118
- /** The live generation, building one if there is none. */
119
- protected currentGeneration(): Generation<TTransfer>;
120
- /** Await the connection and the server's startup gate for one generation. */
121
- protected awaitReady(generation: Generation<TTransfer>): Promise<void>;
122
234
  /**
123
- * Discard the current generation, disposing its connection if it opened.
124
- * The next {@link connected} builds a fresh one.
235
+ * Come off the connection because it is going away.
236
+ *
237
+ * Sends nothing, unlike {@link dispose}: the server ends every session on a
238
+ * connection it sees close, and the close would travel over the very
239
+ * connection being disposed.
240
+ */
241
+ detach(): void;
242
+ /**
243
+ * Register again and restore now, after the connection dropped, instead of
244
+ * on the next call. A no-op for a session with nothing open, which the next
245
+ * call restores anyway. A failure is left to that next call, which meets it
246
+ * again.
247
+ */
248
+ reconnect(): void;
249
+ /**
250
+ * Register on `server`, and after a reconnect restore what the ended session
251
+ * had. Calls issued meanwhile wait for this.
252
+ */
253
+ protected register(server: RpcProxy<TServer>, reconnected: boolean): Promise<void>;
254
+ /**
255
+ * Re-open and re-watch every document the session had open, and tell the
256
+ * host which of them lost what the session wrote since their last save.
257
+ *
258
+ * The unsaved text is not sent again. A document whose re-opened version is
259
+ * the one the session's last write was answered with still holds that
260
+ * write. Any other version means the text changed after that write:
261
+ * another client edited it, even while the session was still connected;
262
+ * the server reverted it to disk when the session's open closed as the
263
+ * document's last; or the server restarted and numbers versions afresh.
264
+ * Re-sending based on the write's own version then always conflicts, and
265
+ * based on the re-opened version it would overwrite whatever changed, so
266
+ * neither is done.
267
+ *
268
+ * No caller is waiting, so both outcomes go through the host: one report
269
+ * naming every document whose unsaved text is gone, whose record is then
270
+ * dropped, and one per document that could not be re-opened, which is
271
+ * forgotten.
125
272
  */
126
- protected dropGeneration(): void;
273
+ protected restore(server: RpcProxy<TServer>): Promise<void>;
274
+ /** Run `call`, counted as in flight on each of `uris` until it settles. */
275
+ protected track<T>(uris: readonly string[], call: () => Promise<T>): Promise<T>;
276
+ /** {@link track} an open of `uri`, counted in {@link openingUris} until it settles. */
277
+ protected trackOpen<T>(uri: string, call: () => Promise<T>): Promise<T>;
278
+ /** Wait until `calls` have settled, or {@link settleBeforeCloseMs} has passed. */
279
+ protected settle(calls: Iterable<Promise<unknown>> | undefined): Promise<void>;
280
+ protected assertLive(): void;
127
281
  }
128
- export {};
129
282
  //# sourceMappingURL=data-session.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"data-session.d.ts","sourceRoot":"","sources":["../../src/client/data-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAyD,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClI,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,QAAQ,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,+EAA+E;AAC/E,UAAU,UAAU,CAAC,SAAS,SAAS,eAAe;IACnD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;IACzD,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,WAAW,CAAC,SAAS,SAAS,eAAe;IAQpD,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ;IACjC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,SAAS,CAAC;IAR3D,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAC3C,0FAA0F;IAC1F,SAAS,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC7C,SAAS,CAAC,QAAQ,UAAS;IAC3B,SAAS,CAAC,QAAQ,CAAC,mBAAmB,EAAE;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,CAAC;gBAGtC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,kBAAkB,CAAC,SAAS,CAAC,EACxD,OAAO,GAAE,kBAAuB;IAMnC,+EAA+E;IAC/E,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;;;;;;OAUG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;IAYnE;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAOrE;;;OAGG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/C;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI1C,+EAA+E;IAC/E,OAAO,IAAI,IAAI;IASf,0DAA0D;IAC1D,SAAS,CAAC,iBAAiB,IAAI,UAAU,CAAC,SAAS,CAAC;IAkBpD,6EAA6E;cAC7D,UAAU,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAe5E;;;OAGG;IACH,SAAS,CAAC,cAAc,IAAI,IAAI;CAQlC"}
1
+ {"version":3,"file":"data-session.d.ts","sourceRoot":"","sources":["../../src/client/data-session.ts"],"names":[],"mappings":"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"}