@hydranium/data-server 1.0.0-next.245 → 1.0.0-next.247

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 (2) hide show
  1. package/README.md +53 -88
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,55 +1,21 @@
1
1
  # `@hydranium/data-server`
2
2
 
3
- The typed JSON-RPC data head of [hydranium](../../README.md): it exposes the live
4
- Langium AST to non-LSP clients — form editors, tree views, code generators — as
5
- an adopter-defined transfer model over a `vscode-jsonrpc` `MessageConnection`.
6
- Installed by the server process that already composes
7
- [`@hydranium/core`](../core); a client needs only
8
- [`@hydranium/protocol`](../protocol).
3
+ The data head of [Hydranium](https://github.com/eclipse-emfcloud/hydranium): it
4
+ serves your model over JSON-RPC to clients other than a text editor, such as
5
+ forms, tree views and code generators. Install it in the server that composes
6
+ `@hydranium/core`; a client talks to it through `@hydranium/protocol`.
9
7
 
10
8
  ## What it gives you
11
9
 
12
- - **One class, `DataServer`.** `new DataServer(connection, services, options)`
13
- self-wires: a single `createRpcProxy` call registers the inbound
14
- `DataServerProtocol` handlers and builds the outbound `DataClientProtocol`
15
- proxy on the same wire. It contributes no shared-tier DI bindings — it reads
16
- exclusively from `ServerSharedServices`, so there is no shared module to
17
- compose.
18
- - **A document lifecycle over the shared workspace:** `openModelDocument`,
19
- `getModelDocument`, `updateModelDocument`, `saveModelDocument`,
20
- `persistModelDocument`, `closeModelDocument`, `watchModelDocument` / `unwatchModelDocument`, and
21
- `waitForReady` for clients that must not race workspace initialisation.
22
- - **Client sessions per connection:** `createSession` registers a participant,
23
- whose requests then write only what it has open; `createModelDocument` and
24
- the all-or-none `updateModelDocuments` serve sessions only; `closeSession`, or
25
- the connection closing, ends a session and closes everything it has open. See
26
- [Connect a data client](../../docs/guides/connect-a-data-client.md).
27
- - **Push notifications instead of polling:** `onDocumentUpdated` when a
28
- subscribed document reaches the configured build phase
29
- (`DataServerOptions.subscriptionPhase`, `DocumentState.Validated` by default),
30
- `onDocumentSaved` on a separate channel, `onDocumentDirtyChanged` when a
31
- subscribed document starts or stops differing from its file (every document
32
- the head sends that it holds also carries its `text` block: version, hash
33
- and current `dirty`), `onDocumentDeleted` (a deleted document has no built
34
- state to carry, and the build-phase path never runs for one),
35
- `onDocumentsBuilt` once per build for the documents nobody watches — chiefly
36
- those rebuilt as a cascade, which no filesystem watcher can see because their
37
- own files did not change — and `onProjectsChanged` from the project registry.
38
- - **Projects as first-class:** `getProjects` and `getProjectForUri`, answered from
39
- the framework's `ProjectManager`.
40
- - **An opt-in reference/naming slice** — `findReferenceCandidates`,
41
- `resolveReference`, `findNextName` — implemented here but deliberately outside
42
- the `DataServerProtocol` composition, so a pure data consumer does not pay for
43
- it. Compose `ReferenceServerProtocol` onto the connection explicitly.
44
- - **A diagnostics seam,** `DataServerDiagnosticsProvider`, with the Node
45
- implementation `nodeDataServerDiagnostics()` behind `./node` so the portable
46
- entry keeps bundling for a browser.
47
-
48
- The projection itself is not this package's: it delegates to `TransferEncoder`
49
- and `ModelService` from `@hydranium/core`, so there is no second in-memory model
50
- to keep in sync.
51
-
52
- 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.
10
+ - Typed reads, updates and saves of documents in the shared workspace, as your
11
+ transfer model. An edit from a data client reaches the other heads.
12
+ - Notifications when a document is rebuilt, saved or deleted, so a client
13
+ never polls.
14
+ - Your own methods on the same connection, through a `DataServer` subclass and
15
+ its `additionalMethods` option.
16
+ - An optional reference and naming slice: pass
17
+ `REFERENCE_SERVER_PROTOCOL_METHODS` from `@hydranium/protocol/data` in
18
+ `additionalMethods`.
53
19
 
54
20
  ## Install
55
21
 
@@ -57,50 +23,49 @@ For the adopter extension path, see [Add a data-server method](../../docs/guides
57
23
  npm install @hydranium/data-server
58
24
  ```
59
25
 
60
- This package bundles no runtime dependencies. Its peers must be present:
61
- `@hydranium/core`, `@hydranium/protocol`, `@hydranium/langium`, `vscode-jsonrpc`
62
- and `vscode-languageserver-textdocument`. You must already have a composed
63
- hydranium shared services tree and a `MessageConnection` — the socket and stdio
64
- launchers live in `@hydranium/core/node`, not here.
65
-
66
- ## Exports
67
-
68
- | subpath | holds | platform |
69
- | ----------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------- |
70
- | `.` | `DataServer` and its option types, plus the `DataServerDiagnosticsProvider` seam — the whole production surface. | browser-neutral |
71
- | `./node` | `nodeDataServerDiagnostics()`, the runtime-backed half of the diagnostics seam. | Node-only |
72
- | `./messages`| Every user-facing message the package raises, by code — what a translation catalogue keys on. | browser-neutral |
73
- | `./testing` | `makeDataServerHarness` — a real server driven in-process over a duplex connection pair. | Node-only (`vscode-jsonrpc/node`) |
74
-
75
- `.` is gated as browser-neutral in CI (`scripts/check-neutral-bundles.mts`). It
76
- stays that way through a `browser` field in `package.json` that swaps the
77
- diagnostics default for a browser twin, so a bundler never follows the
78
- `@hydranium/core/node` import a Node host resolves — see [what "gated neutral" does and does not promise](../../docs/contributing/design/browser-hosting.md#what-gated-neutral-does-and-does-not-promise).
79
- Resolve the subpaths with [a resolver that reads
80
- `exports`](../../docs/adopting/requirements.md#a-resolver-that-reads-exports);
81
- `"Node"` (node10) reaches none of them.
82
-
83
- ## Getting oriented
84
-
85
- Construct the head after the shared services tree exists and keep the returned
86
- instance for `dispose`; it registers its handlers on the connection you pass and
87
- subscribes to the document builder, the text-document store and the project
88
- manager for its push notifications. The typed contract a client codes against —
89
- `DataServerProtocol`, `DataClientProtocol`, the drift-proof method-name lists and
90
- the port constants — lives in `@hydranium/protocol/data`, and the generic
91
- `createRpcProxy` / `bindRpcMethods` machinery in `@hydranium/protocol`. The four
92
- distinct meanings of "document" this head sits between are worth reading first:
93
- [`docs/concepts/document-layers.md`](../../docs/concepts/document-layers.md). See
94
- also [Adopting Hydranium](../../docs/ADOPTING.md).
26
+ | Peer | Range |
27
+ | ------------------------------------ | ------------- |
28
+ | `@hydranium/core` | `^1.0.0-next` |
29
+ | `@hydranium/langium` | `^1.0.0-next` |
30
+ | `@hydranium/protocol` | `^1.0.0-next` |
31
+ | `vscode-jsonrpc` | `^9.0.0` |
32
+ | `vscode-languageserver-textdocument` | `^1.0.12` |
33
+
34
+ ## Wiring
35
+
36
+ The head adds no services module: it reads the shared services you composed
37
+ with `@hydranium/core`.
38
+
39
+ 1. Start a launcher from `@hydranium/core/node`: `startSocketServer` beside the
40
+ LSP head, with `publishPortOnLspConnection` to tell the client its port, or
41
+ `startStdioServer` for a data head alone.
42
+ 2. In its connection callback, create `new DataServer(connection, shared)`. It
43
+ cleans up when the connection closes.
44
+
45
+ See *Add a data-server method* and *Connect a data client* in
46
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
47
+
48
+ ## Entry points
49
+
50
+ | Subpath | Use it for | Runs in |
51
+ | ------------ | ---------------------------------------------------------- | --------------- |
52
+ | `.` | `DataServer`, its options, and the diagnostics seam | browser-neutral |
53
+ | `./node` | The Node implementation of the diagnostics seam | Node-only |
54
+ | `./messages` | The codes of the messages this package raises | browser-neutral |
55
+ | `./testing` | A harness that drives a real data head in-process | Node-only |
56
+
57
+ The subpaths need a TypeScript `moduleResolution` that reads `exports`
58
+ (`NodeNext` or `Bundler`); see *Requirements* in
59
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
95
60
 
96
61
  ## Status
97
62
 
98
- Alpha — pre-v0, published as a `1.0.0-next` prerelease on every merge to `main`.
99
- The API is not stable and may change without a deprecation cycle. See the
100
- [repository README](../../README.md) for the current status and known
101
- limitations.
63
+ Alpha: every release is a prerelease that may break the API, so pin an exact
64
+ version. Guides and known limitations:
65
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
102
66
 
103
67
  ## License
104
68
 
105
- `MIT` — see this package's [`LICENSE`](./LICENSE). Third-party notices for the
106
- repository are recorded in [`NOTICE.md`](../../NOTICE.md).
69
+ `MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
70
+ [`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
71
+ for third-party notices.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hydranium/data-server",
3
- "version": "1.0.0-next.245",
3
+ "version": "1.0.0-next.247",
4
4
  "description": "Typed-RPC protocol head for the hydranium framework. Peer of @hydranium/core/lsp and @hydranium/glsp-server; built on @hydranium/core.",
5
5
  "keywords": [
6
6
  "data-server",
@@ -66,18 +66,18 @@
66
66
  "watch": "tsc -b -w --preserveWatchOutput"
67
67
  },
68
68
  "devDependencies": {
69
- "@hydranium/core": "1.0.0-next.245",
70
- "@hydranium/langium": "1.0.0-next.245",
71
- "@hydranium/protocol": "1.0.0-next.245",
69
+ "@hydranium/core": "1.0.0-next.247",
70
+ "@hydranium/langium": "1.0.0-next.247",
71
+ "@hydranium/protocol": "1.0.0-next.247",
72
72
  "rimraf": "^5.0.0",
73
73
  "typescript": "^7.0.2",
74
74
  "vscode-jsonrpc": "9.0.0",
75
75
  "vscode-languageserver-textdocument": "^1.0.12"
76
76
  },
77
77
  "peerDependencies": {
78
- "@hydranium/core": "1.0.0-next.245",
79
- "@hydranium/langium": "1.0.0-next.245",
80
- "@hydranium/protocol": "1.0.0-next.245",
78
+ "@hydranium/core": "1.0.0-next.247",
79
+ "@hydranium/langium": "1.0.0-next.247",
80
+ "@hydranium/protocol": "1.0.0-next.247",
81
81
  "vscode-jsonrpc": "^9.0.0",
82
82
  "vscode-languageserver-textdocument": "^1.0.12"
83
83
  },