@hydranium/data-client-theia 1.0.0-next.245 → 1.0.0-next.246

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 +57 -113
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,61 +1,20 @@
1
1
  # `@hydranium/data-client-theia`
2
2
 
3
- Theia client primitives for the hydranium **data head** — the companion of
4
- `@hydranium/data-server` in the
5
- [Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework.
6
-
7
- The data head's frontend speaks the data server's own `vscode-jsonrpc` protocol
8
- over a channel that the Theia backend relays byte-for-byte onto the server's
9
- socket. This package is the Theia-specific half of that arrangement: the browser-side
10
- transport and the backend-side connection handler and forwarder. Everything above
11
- the transport — the connection, its sessions, the event fan-out — is host-neutral
12
- and lives in `@hydranium/protocol/client`. Install it if a Theia application needs
13
- form editors, trees, or code-gen driven from the live AST rather than from LSP
14
- text edits.
3
+ The Theia connection for the
4
+ [Hydranium](https://github.com/eclipse-emfcloud/hydranium) data head, the
5
+ companion of `@hydranium/data-server`. Install it when forms, trees or views in
6
+ a Theia application work on the live model rather than on text. It builds on
7
+ `@hydranium/client-theia`.
15
8
 
16
9
  ## What it gives you
17
10
 
18
- - **`openChannelConnection`** with `createChannelConnection` and
19
- `ChannelConnectionHandle` — wraps a Theia `Channel` as a `vscode-jsonrpc`
20
- `MessageConnection`, gated on a `whenReady` promise, and by default
21
- re-establishes it by **re-opening the channel** when the connection is lost.
22
- Re-opening rather than rebuilding is what recovers a restarted language server:
23
- a server restart closes only the multiplexed sub-channel, so no replacement
24
- channel ever arrives on its own. Retries follow `DEFAULT_RECONNECT_DELAYS`,
25
- escalating per consecutive loss and resetting after
26
- `RECONNECT_ESCALATION_RESET_MS`.
27
- - **`ChannelDataPort`** — the `DataPort` implementation over a Theia frontend
28
- channel, and the only class a Theia adopter has to write against. Subclass it
29
- with a `servicePath`; it supplies the channel, the workspace gate, the
30
- reconnect signal and the `MessageService` error sink. Bind one per service path
31
- in singleton scope. Hand it to `DataConnectionWithEvents` (from
32
- `@hydranium/protocol`) and each connection reports through the
33
- `ConnectionReporter`, a data server not ready after 30 s included; the
34
- connection, its sessions and its event fan-out are the host-neutral ones every
35
- other shell uses.
36
- - **`EmitterDataClient`** (on `./common`, not `./browser`) — the default
37
- client-side implementation of the data protocol's inbound notifications,
38
- fanning each one out to a Theia `Event` of the matching name
39
- (`onDidUpdateDocument`, `onDidSaveDocument`, …). Bind an instance as the
40
- `localTarget` of the frontend's RPC proxy. It sits on the common tier because
41
- its only runtime dependency is `@theia/core`'s root entry, which is Theia's own
42
- common tier, so a backend or a plain-Node consumer can bind it too.
43
- - **`whenWorkspaceOpen`** — resolves once Theia reports a workspace root. The data
44
- server only starts once the LSP launches for a workspace, so connecting earlier
45
- would hang in port discovery; pass this as `whenReady`.
46
- - **`DataSessionStopContribution`** — ends a frontend's data sessions with its
47
- page, so the server ends them as closed rather than waiting for the connection
48
- to go, and holds the page while one of them is saving.
49
- `bindDataConnection(bind, isBound, ConnectionClass)` binds a connection with
50
- its sessions tracked, and binds this contribution and the
51
- `ConnectionReporter` the connection's port injects unless they are bound.
52
- - **Backend (`./node`)** — `DataServerConnectionHandler` (the socket bridge,
53
- over `@hydranium/client-theia`'s `SocketChannelForwarder`),
54
- `createDataServerConnectionContainerModule(...handlers)` for the
55
- frontend-scoped module boilerplate, and `HostDiagnosticsServer` with
56
- `createHostDiagnosticsBackendModule()` — which, paired with the browser-side
57
- `bindHostDiagnostics`, lights up the "Backend" diagnostics commands in
58
- `@hydranium/client-theia`'s contribution.
11
+ - A data connection in the Theia frontend: you subclass `ChannelDataPort`, and
12
+ the connection and sessions from `@hydranium/protocol` run over it.
13
+ - A connection that waits for a workspace, and reconnects on its own when the
14
+ channel is lost, a restarted server included.
15
+ - Sessions that end with the page, and a page held while one of them saves.
16
+ - The backend handler that relays the channel to the data server's socket.
17
+ - Diagnostics commands for the Theia backend process, beside the server's.
59
18
 
60
19
  ## Install
61
20
 
@@ -63,76 +22,61 @@ text edits.
63
22
  npm install @hydranium/data-client-theia
64
23
  ```
65
24
 
66
- You must already have a Theia application with `@theia/workspace` available, and a
67
- running hydranium data server to connect to. The declared peer dependencies are:
68
-
69
- | Peer | Range |
70
- | ------------------------- | -------------------- |
71
- | `@hydranium/client-theia` | `^1.0.0-next` |
72
- | `@hydranium/protocol` | `^1.0.0-next` |
73
- | `@theia/core` | `^1.70.0` |
74
- | `@theia/workspace` | `^1.70.0` |
75
- | `inversify` | `^6.0.0` |
76
- | `vscode-jsonrpc` | `^9.0.0` |
25
+ | Peer | Range |
26
+ | ------------------------- | ------------- |
27
+ | `@hydranium/client-theia` | `^1.0.0-next` |
28
+ | `@hydranium/protocol` | `^1.0.0-next` |
29
+ | `@theia/core` | `^1.70.0` |
30
+ | `@theia/workspace` | `^1.70.0` |
31
+ | `inversify` | `^6.0.0` |
32
+ | `vscode-jsonrpc` | `^9.0.0` |
77
33
 
78
34
  ## Wiring
79
35
 
80
- This package declares no `theiaExtensions` — it is a library your own Theia
81
- extension builds on. That extension's `package.json` declares the entries, and
82
- each entry names one frontend/backend module pair:
83
-
84
- - the **frontend** module:
85
- - binds your `ChannelDataPort` subclass in singleton scope;
86
- - calls `bindDataConnection(bind, isBound, MyConnection)` for the connection
87
- over it;
88
- - calls `bindChannelLogger` from `@hydranium/client-theia`, where the port
89
- logs the connection failures it leaves to the reporter, and the connection
90
- over it logs at debug level what it does on its own;
91
- - calls `bindEditorDiskSync` from `@hydranium/client-theia`, since a data
92
- server save writes a file an editor can have open;
93
- - calls `bindHostDiagnostics` for the diagnostics commands;
94
- - the **backend** module is typically a one-liner:
95
- `export default createDataServerConnectionContainerModule(MyHandler)`, where
96
- `MyHandler` extends `DataServerConnectionHandler`.
97
-
98
- More than one handler is the normal case, not an exotic one. Theia keys a
99
- frontend channel by its service path and refuses a second channel on a path
100
- already open, so every frontend abstraction reaching the data head on its own
101
- channel needs its own `servicePath` — while the shared `portCommand` still names
102
- the one server process behind them all. Several participants over ONE channel
103
- need no second handler: that is what `DataConnection`'s sessions are for, and it
104
- is the cheaper arrangement.
105
-
106
- The refusal is silent, which is what makes it expensive: the loser's promise is
107
- left unsettled rather than rejected, so a frontend that shared a path hangs on
108
- its loading state indefinitely with nothing in the server log to say why.
36
+ This package declares no `theiaExtensions`; your own Theia extension declares
37
+ them and binds from here.
38
+
39
+ - In a frontend module, subclass `ChannelDataPort` with a `servicePath` and
40
+ bind it in singleton scope. Call `bindDataConnection` for the connection
41
+ over it.
42
+ - In the same frontend, call `bindChannelLogger` from
43
+ `@hydranium/client-theia`, and its `bindEditorDiskSync`, since a data server
44
+ save writes a file an editor can have open.
45
+ - For the backend diagnostics commands, call `bindHostDiagnostics` in the
46
+ frontend and export `createHostDiagnosticsBackendModule()` from a backend
47
+ module.
48
+ - In the backend, export
49
+ `createDataServerConnectionContainerModule(MyHandler)`, where `MyHandler`
50
+ extends `DataServerConnectionHandler` and names your server's port command.
51
+
52
+ Give each frontend channel its own `servicePath`. Theia refuses a second
53
+ channel on a path already open, silently: the frontend hangs with nothing in
54
+ the log. For several participants on one channel, use sessions instead.
55
+
56
+ For the whole setup, see *Host in Theia* in
57
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
109
58
 
110
59
  ## Entry points
111
60
 
112
- | Subpath | Holds | Environment |
113
- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
114
- | `.` | Nothing — the surface is split by environment, so the root barrel stays empty. | browser-neutral (gated) |
115
- | `./common` | `EmitterDataClient` — a module lands here only when values, types and relative imports are all neutral or Theia COMMON tier. No error-reconstruction bridge, and that is a property of the transport: the direct `vscode-jsonrpc` connection carries a typed error across the relay natively. | browser-neutral (gated) |
116
- | `./browser` | `openChannelConnection`, `createChannelConnection`, `ChannelDataPort`, `bindHostDiagnostics`, `whenWorkspaceOpen`, `DataSessionStopContribution`, `bindDataConnection` | browser / Theia frontend (gated) |
117
- | `./node` | `DataServerConnectionHandler`, `createDataServerConnectionContainerModule`, `HostDiagnosticsServer`, `createHostDiagnosticsBackendModule` | Node / Theia backend |
61
+ | Subpath | Use it for | Runs in |
62
+ | ----------- | ------------------------------------------------------------- | --------------- |
63
+ | `.` | Nothing; import a subpath | browser-neutral |
64
+ | `./common` | The data server's notifications as Theia events, on any side | browser-neutral |
65
+ | `./browser` | The port, the connection binding and the diagnostics proxy | Theia frontend |
66
+ | `./node` | The connection handler and the backend modules | Theia backend |
118
67
 
119
- Resolve the subpaths with [a resolver that reads
120
- `exports`](../../docs/adopting/requirements.md#a-resolver-that-reads-exports);
121
- `"Node"` (node10) reaches none of them. "Gated" means the
122
- repository's neutral-bundle check enforces that the entry bundles for the
123
- browser with no `node:*` import, transitive ones included; `./node` is
124
- deliberately outside that gate. Also worth reading: [what "gated neutral" does and does not promise](../../docs/contributing/design/browser-hosting.md#what-gated-neutral-does-and-does-not-promise).
68
+ The subpaths need a TypeScript `moduleResolution` that reads `exports`
69
+ (`NodeNext` or `Bundler`); see *Requirements* in
70
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
125
71
 
126
72
  ## Status
127
73
 
128
- Alpha — pre-v0, published as a `1.0.0-next` prerelease on every merge to `main`.
129
- The API is not stable and may change without a deprecation cycle. See
130
- [Adopting Hydranium](../../docs/ADOPTING.md) for the data head's place among
131
- the heads, and the [repository README](../../README.md)
132
- for current status and known limitations.
74
+ Alpha: every release is a prerelease that may break the API, so pin an exact
75
+ version. Guides and known limitations:
76
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
133
77
 
134
78
  ## License
135
79
 
136
- `MIT` — see this package's [`LICENSE`](./LICENSE). Third-party notices for the
137
- runtime dependency closure are collected in the repository
138
- [`NOTICE.md`](../../NOTICE.md).
80
+ `MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
81
+ [`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
82
+ for third-party notices.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hydranium/data-client-theia",
3
- "version": "1.0.0-next.245",
3
+ "version": "1.0.0-next.246",
4
4
  "description": "Theia-coupled client primitives for the hydranium data-server protocol head; companion of @hydranium/data-server. Bridges framework typed errors (e.g. ConflictError) across Theia's RPC boundary so their code + data survive the wire.",
5
5
  "keywords": [
6
6
  "hydranium",
@@ -61,8 +61,8 @@
61
61
  "watch": "tsc -b -w --preserveWatchOutput"
62
62
  },
63
63
  "devDependencies": {
64
- "@hydranium/client-theia": "1.0.0-next.245",
65
- "@hydranium/protocol": "1.0.0-next.245",
64
+ "@hydranium/client-theia": "1.0.0-next.246",
65
+ "@hydranium/protocol": "1.0.0-next.246",
66
66
  "@theia/core": "^1.70.0",
67
67
  "@theia/workspace": "^1.70.0",
68
68
  "@types/node": "^22.0.0",
@@ -73,8 +73,8 @@
73
73
  "vscode-jsonrpc": "9.0.0"
74
74
  },
75
75
  "peerDependencies": {
76
- "@hydranium/client-theia": "1.0.0-next.245",
77
- "@hydranium/protocol": "1.0.0-next.245",
76
+ "@hydranium/client-theia": "1.0.0-next.246",
77
+ "@hydranium/protocol": "1.0.0-next.246",
78
78
  "@theia/core": "^1.70.0",
79
79
  "@theia/workspace": "^1.70.0",
80
80
  "inversify": "^6.0.0",