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

package/README.md

@@ -1,42 +1,21 @@
 # `@hydranium/data-server`
 
-The typed JSON-RPC data head of [hydranium](../../README.md): it exposes the live
-Langium AST to non-LSP clients — form editors, tree views, code generators — as
-an adopter-defined transfer model over a `vscode-jsonrpc` `MessageConnection`.
-Installed by the server process that already composes
-[`@hydranium/core`](../core); a client needs only
-[`@hydranium/protocol`](../protocol).
+The data head of [Hydranium](https://github.com/eclipse-emfcloud/hydranium): it
+serves your model over JSON-RPC to clients other than a text editor, such as
+forms, tree views and code generators. Install it in the server that composes
+`@hydranium/core`; a client talks to it through `@hydranium/protocol`.
 
 ## What it gives you
 
-- **One class, `DataServer`.** `new DataServer(connection, services, options)`
-  self-wires: a single `createRpcProxy` call registers the inbound
-  `DataServerProtocol` handlers and builds the outbound `DataClientProtocol`
-  proxy on the same wire. It contributes no shared-tier DI bindings — it reads
-  exclusively from `ServerSharedServices`, so there is no shared module to
-  compose.
-- **A document lifecycle over the shared workspace:** `openModelDocument`,
-  `getModelDocument`, `updateModelDocument`, `saveModelDocument`,
-  `closeModelDocument`, `watchModelDocument` / `unwatchModelDocument`, and
-  `waitForReady` for clients that must not race workspace initialisation.
-- **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.
-- **Projects as first-class:** `getProjects` and `getProjectForUri`, answered from
-  the framework's `ProjectManager`.
-- **An opt-in reference/naming slice** — `findReferenceCandidates`,
-  `resolveReference`, `findNextName` — implemented here but deliberately outside
-  the `DataServerProtocol` composition, so a pure data consumer does not pay for
-  it. Compose `ReferenceServerProtocol` onto the connection explicitly.
-- **A diagnostics seam,** `DataServerDiagnosticsProvider`, with the Node
-  implementation `nodeDataServerDiagnostics()` behind `./node` so the portable
-  entry keeps bundling for a browser.
-
-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.
+- Typed reads, updates and saves of documents in the shared workspace, as your
+  transfer model. An edit from a data client reaches the other heads.
+- Notifications when a document is rebuilt, saved or deleted, so a client
+  never polls.
+- Your own methods on the same connection, through a `DataServer` subclass and
+  its `additionalMethods` option.
+- An optional reference and naming slice: pass
+  `REFERENCE_SERVER_PROTOCOL_METHODS` from `@hydranium/protocol/data` in
+  `additionalMethods`.
 
 ## Install
 
@@ -44,48 +23,53 @@ to keep in sync.
 npm install @hydranium/data-server
 ```
 
-This package bundles no runtime dependencies. Its peers must be present:
-`@hydranium/core`, `@hydranium/protocol`, `@hydranium/langium`, `vscode-jsonrpc`
-and `vscode-languageserver-textdocument`. You must already have a composed
-hydranium shared services tree and a `MessageConnection` — the socket and stdio
-launchers live in `@hydranium/core/node`, not here.
-
-## Exports
-
-| subpath     | holds                                                                                                          | platform                          |
-| ----------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| `.`         | `DataServer` and its option types, plus the `DataServerDiagnosticsProvider` seam — the whole production surface. | browser-neutral                   |
-| `./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
-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"`.
-
-## Getting oriented
-
-Construct the head after the shared services tree exists and keep the returned
-instance for `dispose`; it registers its handlers on the connection you pass and
-subscribes to the document builder, the text-document store and the project
-manager for its push notifications. The typed contract a client codes against —
-`DataServerProtocol`, `DataClientProtocol`, the drift-proof method-name lists and
-the port constants — lives in `@hydranium/protocol/data`, and the generic
-`createRpcProxy` / `bindRpcMethods` machinery in `@hydranium/protocol`. The four
-distinct meanings of "document" this head sits between are worth reading first:
-[`docs/concepts/document-layers.md`](../../docs/concepts/document-layers.md). See
-also [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md) and
-[`docs/concepts/head-module-maps.md`](../../docs/concepts/head-module-maps.md).
+| Peer                                 | Range         |
+| ------------------------------------ | ------------- |
+| `@hydranium/core`                    | `^1.0.0-next` |
+| `@hydranium/langium`                 | `^1.0.0-next` |
+| `@hydranium/protocol`                | `^1.0.0-next` |
+| `vscode-jsonrpc`                     | `^9.0.0`      |
+| `vscode-languageserver-textdocument` | `^1.0.12`     |
+
+## Wiring
+
+The head adds no services module: it reads the shared services you composed
+with `@hydranium/core`.
+
+1. Start a launcher from `@hydranium/core/node`: `startSocketServer` beside the
+   LSP head, with `publishPortOnLspConnection` to tell the client its port, or
+   `startStdioServer` for a data head alone. Without an LSP head, give it the
+   workspace root as `workspace`.
+2. In its connection callback, create `new DataServer(connection, shared)`. It
+   cleans up when the connection closes.
+3. In a web worker, start it with `startDataServerInWorker` from `./browser`
+   on the port the page transferred for it; its callback creates the server.
+
+See *Add a data-server method* and *Connect a data client* in
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
+
+## Entry points
+
+| Subpath      | Use it for                                                 | Runs in         |
+| ------------ | ---------------------------------------------------------- | --------------- |
+| `.`          | `DataServer`, its options, and the diagnostics seam        | browser-neutral |
+| `./node`     | The Node implementation of the diagnostics seam            | Node-only       |
+| `./browser`  | Starting the head in a web worker                          | browser-only    |
+| `./messages` | The codes of the messages this package raises              | browser-neutral |
+| `./testing`  | A harness that drives a real data head in-process          | Node-only       |
+
+The subpaths need a TypeScript `moduleResolution` that reads `exports`
+(`NodeNext` or `Bundler`); see *Requirements* in
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
 
 ## Status
 
-Alpha — pre-v0, not yet published. The API is not stable and may change without a
-deprecation cycle. See the [repository README](../../README.md) for the current
-status and known limitations.
+Alpha: every release is a prerelease that may break the API, so pin an exact
+version. Guides and known limitations:
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
 
 ## License
 
-`MIT` — see this package's [`LICENSE`](./LICENSE). Third-party notices for the
-repository are recorded in [`NOTICE.md`](../../NOTICE.md).
+`MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
+[`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
+for third-party notices.

package/lib/browser/index.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export * from './start-data-server-in-worker.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAOlF,cAAc,kCAAkC,CAAC"}

package/lib/browser/index.js

@@ -0,0 +1,15 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+// Browser-only entry (`@hydranium/data-server/browser`). Holds the worker
+// starter, whose connection comes from `vscode-jsonrpc/browser`. The portable
+// `.` entry stays free of that import for the same reason it stays free of the
+// node one: it must resolve under both platforms, and a build that names one
+// has picked.
+export * from './start-data-server-in-worker.js';
+//# sourceMappingURL=index.js.map

package/lib/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,6EAA6E;AAC7E,cAAc;AACd,cAAc,kCAAkC,CAAC"}

package/lib/browser/start-data-server-in-worker.d.ts

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * 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 TransferredMessagePort } from '@hydranium/protocol';
+import type { ServerSharedServicesMinimal } from '@hydranium/core';
+import { type MessageConnection } from 'vscode-jsonrpc/browser';
+/**
+ * Start the data head on the port the page transferred for it, on the same
+ * shared tier the LSP head runs on, and return the server `create` built.
+ *
+ * `create` constructs the adopter's `DataServer`, or a subclass of it, around
+ * the connection, as a Node host's socket callback does, and the connection
+ * listens once it has returned, in the order the Node launcher uses. The
+ * page's end of the port closing disposes the server, which ends every
+ * session this connection registered.
+ */
+export declare function startDataServerInWorker<TServer>(port: TransferredMessagePort, shared: Pick<ServerSharedServicesMinimal, 'Logger'>, create: (connection: MessageConnection) => TServer): TServer;
+//# sourceMappingURL=start-data-server-in-worker.d.ts.map

package/lib/browser/start-data-server-in-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-data-server-in-worker.d.ts","sourceRoot":"","sources":["../../src/browser/start-data-server-in-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAA8B,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEzF;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAC5C,IAAI,EAAE,sBAAsB,EAC5B,MAAM,EAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAC,EACnD,MAAM,EAAE,CAAC,UAAU,EAAE,iBAAiB,KAAK,OAAO,GAClD,OAAO,CAOT"}

package/lib/browser/start-data-server-in-worker.js

@@ -0,0 +1,29 @@
+/********************************************************************************
+ * 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 { createMessagePortTransport } from '@hydranium/protocol';
+import { createMessageConnection } from 'vscode-jsonrpc/browser';
+/**
+ * Start the data head on the port the page transferred for it, on the same
+ * shared tier the LSP head runs on, and return the server `create` built.
+ *
+ * `create` constructs the adopter's `DataServer`, or a subclass of it, around
+ * the connection, as a Node host's socket callback does, and the connection
+ * listens once it has returned, in the order the Node launcher uses. The
+ * page's end of the port closing disposes the server, which ends every
+ * session this connection registered.
+ */
+export function startDataServerInWorker(port, shared, create) {
+    // Both ends use `createMessagePortTransport`; see it for why.
+    const transport = createMessagePortTransport(port);
+    const connection = createMessageConnection(transport.reader, transport.writer, shared.Logger.with('ModelServer'));
+    const server = create(connection);
+    connection.listen();
+    return server;
+}
+//# sourceMappingURL=start-data-server-in-worker.js.map

package/lib/browser/start-data-server-in-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-data-server-in-worker.js","sourceRoot":"","sources":["../../src/browser/start-data-server-in-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,0BAA0B,EAA+B,MAAM,qBAAqB,CAAC;AAE9F,OAAO,EAAE,uBAAuB,EAA0B,MAAM,wBAAwB,CAAC;AAEzF;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACpC,IAA4B,EAC5B,MAAmD,EACnD,MAAkD;IAElD,8DAA8D;IAC9D,MAAM,SAAS,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,uBAAuB,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;IAClH,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAClC,UAAU,CAAC,MAAM,EAAE,CAAC;IACpB,OAAO,MAAM,CAAC;AACjB,CAAC"}