@hydranium/data-server 1.0.0-next.22 → 1.0.0-next.221

package/README.md

@@ -17,13 +17,24 @@ Installed by the server process that already composes
   compose.
 - **A document lifecycle over the shared workspace:** `openModelDocument`,
   `getModelDocument`, `updateModelDocument`, `saveModelDocument`,
-  `closeModelDocument`, `watchModelDocument` / `unwatchModelDocument`, and
+  `persistModelDocument`, `closeModelDocument`, `watchModelDocument` / `unwatchModelDocument`, and
   `waitForReady` for clients that must not race workspace initialisation.
+- **Client sessions per connection:** `createSession` registers a participant,
+  whose requests then write only what it has open; `createModelDocument` and
+  the all-or-none `updateModelDocuments` serve sessions only; `closeSession`, or
+  the connection closing, ends a session and closes everything it has open. See
+  [Client sessions](../../docs/concepts/client-sessions.md).
 - **Push notifications instead of polling:** `onDocumentUpdated` when a
   subscribed document reaches the configured build phase
   (`DataServerOptions.subscriptionPhase`, `DocumentState.Validated` by default),
-  `onDocumentSaved` on a separate channel, and `onProjectsChanged` from the
-  project registry.
+  `onDocumentSaved` on a separate channel, `onDocumentDirtyChanged` when a
+  subscribed document starts or stops differing from its file (every document
+  the head sends that it holds also carries its `text` block: version, hash
+  and current `dirty`), `onDocumentDeleted` (a deleted document has no built
+  state to carry, and the build-phase path never runs for one),
+  `onDocumentsBuilt` once per build for the documents nobody watches — chiefly
+  those rebuilt as a cascade, which no filesystem watcher can see because their
+  own files did not change — and `onProjectsChanged` from the project registry.
 - **Projects as first-class:** `getProjects` and `getProjectForUri`, answered from
   the framework's `ProjectManager`.
 - **An opt-in reference/naming slice** — `findReferenceCandidates`,
@@ -38,6 +49,8 @@ The projection itself is not this package's: it delegates to `TransferEncoder`
 and `ModelService` from `@hydranium/core`, so there is no second in-memory model
 to keep in sync.
 
+For the adopter extension path, see [Add a data-server method](../../docs/guides/data-server-method.md). It covers the typed subclass, `additionalMethods`, shared namespace, and client proxy as one wire contract.
+
 ## Install
 
 ```bash
@@ -58,12 +71,13 @@ launchers live in `@hydranium/core/node`, not here.
 | `./node`    | `nodeDataServerDiagnostics()`, the runtime-backed half of the diagnostics seam.                                 | Node-only                         |
 | `./testing` | `makeDataServerHarness` — a real server driven in-process over a duplex connection pair.                        | Node-only (`vscode-jsonrpc/node`) |
 
-`.` is gated as browser-neutral in CI (`scripts/check-neutral-bundles.mjs`). It
+`.` is gated as browser-neutral in CI (`scripts/check-neutral-bundles.mts`). It
 stays that way through a `browser` field in `package.json` that swaps the
 diagnostics default for a browser twin, so a bundler never follows the
 `@hydranium/core/node` import a Node host resolves — see [what "gated neutral" does and does not promise](../../docs/concepts/browser-hosting.md#a-note-on-what-gated-neutral-does-and-does-not-promise).
-Each subpath also has a `./lib/…` twin for consumers on
-`moduleResolution: "Node"`.
+Resolve the subpaths with [a resolver that reads
+`exports`](../../docs/adopting/requirements.md#a-resolver-that-reads-exports);
+`"Node"` (node10) reaches none of them.
 
 ## Getting oriented