@hydranium/protocol 1.0.0-next.244 → 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 +44 -86
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,41 +1,40 @@
1
1
  # `@hydranium/protocol`
2
2
 
3
- Generic, language-agnostic types, constants, and pure utilities for the
4
- [Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework.
5
-
6
- This package is the contract surface shared between hydranium servers and
7
- their clients. It contains:
8
-
9
- - Cross-reference and reference-resolution types.
10
- - The `TransferDocument<TTransfer, TDiagnostic>` transfer-document wrapper.
11
- - The generic `DataServerProtocol` and `DataClientProtocol` RPC interfaces.
12
- - Pure utility functions and version constants.
13
-
14
- **Dependency budget:** one runtime dependency, `fast-json-patch`. Anything
15
- heavier (transport, Inversify, Theia, Langium runtime) lives in consuming
16
- packages.
3
+ The contract shared between
4
+ [Hydranium](https://github.com/eclipse-emfcloud/hydranium) servers and their
5
+ clients. With `vscode-jsonrpc`, it is the only Hydranium package a pure client
6
+ needs: a form editor, a tree view or a code generator talking to the data head
7
+ never depends on `@hydranium/core`, which carries the Langium runtime.
8
+
9
+ ## What it gives you
10
+
11
+ - Type your client against `DataServerProtocol` and `DataClientProtocol`.
12
+ - Connect, reconnect and open documents through one client tier, in a Theia
13
+ frontend, a VS Code extension or webview, or a plain browser page.
14
+ - Declare your own RPC contract as a TypeScript interface and use it on both
15
+ ends of a connection.
16
+ - Test your client, and audit your translation catalogues (see *Translate your
17
+ language* in
18
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md)).
17
19
 
18
20
  ## Install
19
21
 
20
22
  ```bash
21
- npm install @hydranium/protocol
23
+ npm install @hydranium/protocol vscode-jsonrpc
22
24
  ```
23
25
 
24
- This is the only hydranium package a pure client needs. A form editor, a tree
25
- view or a code generator talking to the data head depends on this and on
26
- `vscode-jsonrpc` for the transport — never on `@hydranium/core`, which carries
27
- the Langium runtime and does not bundle for a client.
26
+ | Peer | Range |
27
+ | ---------------- | -------- |
28
+ | `vscode-jsonrpc` | `^9.0.0` |
28
29
 
29
30
  ## The RPC pattern
30
31
 
31
- The data head is not a bespoke wire format — it is a TypeScript interface, bound
32
- on one side and proxied on the other. An adopter declares a contract `T`, binds
33
- it with `bindRpcMethods`, and consumes it with `createRpcProxy<T>`; nothing
34
- between the two is hand-written, and the compiler is what keeps the ends
35
- agreeing.
32
+ You declare a contract `T`, bind it on the server with `bindRpcMethods`, and
33
+ call it with `createRpcProxy<T>`. Nothing between the two is hand-written, so
34
+ the compiler keeps the ends agreeing.
36
35
 
37
36
  ```
38
- adopter contract T adopter contract T
37
+ your contract T your contract T
39
38
  │ │
40
39
  ▼ ▼
41
40
  bindRpcMethods createRpcProxy<T>
@@ -45,74 +44,33 @@ agreeing.
45
44
  (vscode-jsonrpc)
46
45
  ```
47
46
 
48
- The two helpers are deliberately symmetric — the same wire-name composition
49
- rule, the same notification heuristic, the same deferred-connection support — so
50
- a contract written once works on both ends with no per-method configuration.
51
- Both are exported from the package root; there is no `/rpc` subpath.
52
-
53
- Full reference — the options both ends must agree on, the reserved property
54
- names, a worked example — is in
55
- [`src/rpc/README.md`](./src/rpc/README.md), which ships in the tarball.
56
-
57
- ## Subpaths
58
-
59
- ```bash
60
- @hydranium/protocol # transfer documents, references, RPC machinery
61
- @hydranium/protocol/data # DataServerProtocol / DataClientProtocol
62
- @hydranium/protocol/client # the host-neutral client tier
63
- @hydranium/protocol/messages # every message it raises, by code
64
- @hydranium/protocol/node # process memory and heap-snapshot helpers
65
- @hydranium/protocol/testing # test doubles, waiters, catalogue audit
66
- @hydranium/protocol/testing/node # the Node-only doubles
67
- ```
68
-
69
- The root barrel re-exports `data` and `client`, so those two subpaths buy a
70
- narrower surface rather than reach; `node` and `testing` are only reachable by
71
- their own specifiers, which keeps `node:*` imports out of a browser bundle and
72
- the doubles out of a production bundle. The RPC
73
- machinery documents itself in [`src/rpc/README.md`](./src/rpc/README.md).
74
-
75
- ### Auditing a translation catalogue
76
-
77
- An adopter with i18n has one failure mode nothing else catches: a catalogue key
78
- naming no declared code falls back to the English, which is byte-identical to
79
- the deliberately-partial behaviour every adopter relies on. So a typo is
80
- invisible at runtime, and `theia nls-extract` reports what the source declares
81
- rather than whether a catalogue matches it.
47
+ The options both ends must agree on, and a worked example, are in
48
+ [`src/rpc/README.md`](./src/rpc/README.md).
82
49
 
83
- `@hydranium/protocol/testing` ships the audit for it — call it from your own
84
- test, over your own barrels:
50
+ ## Entry points
85
51
 
86
- <!-- snippet-preamble
87
- import { flattenCatalogue, findUndeclaredCodes, findSharedCodes } from '@hydranium/protocol/testing';
88
- import * as protocolMessages from '@hydranium/protocol';
89
- declare const readFileSync: (path: string, encoding: string) => string;
90
- declare const expect: (actual: unknown) => { toEqual(expected: unknown): void };
91
- -->
92
-
93
- ```ts
94
- const keys = Object.keys(flattenCatalogue(JSON.parse(readFileSync('nls/de.json', 'utf-8'))));
95
-
96
- // Every key names a code some barrel declares. `exemptPrefixes` is for keys no
97
- // barrel CAN declare — a host mechanism taking its key as an inline literal.
98
- expect(findUndeclaredCodes(keys, [protocolMessages])).toEqual([]);
99
- ```
52
+ | Subpath | Use it for | Runs in |
53
+ | ---------------- | ----------------------------------------------------------- | --------------- |
54
+ | `.` | The production surface, `./data` and `./client` included | browser-neutral |
55
+ | `./data` | The data-head protocol types alone | browser-neutral |
56
+ | `./client` | The client tier alone | browser-neutral |
57
+ | `./messages` | The message codes this package raises | browser-neutral |
58
+ | `./node` | Process-memory and heap-snapshot diagnostics | Node-only |
59
+ | `./testing` | Test doubles, waiters and the translation-catalogue audit | browser-neutral |
60
+ | `./testing/node` | In-memory stream and port pairs for tests | Node-only |
100
61
 
101
- `flattenCatalogue` joins nested keys with `/` (the separator a code already
102
- uses, and what Theia does to a nested catalogue) and drops `_`-prefixed note
103
- keys, so a flat server-side catalogue and a nested host-side one both go through
104
- it. `findSharedCodes` covers the other half: exactly one side renders a given
105
- message, so two catalogues holding one code are two authorities over one
106
- sentence — assert both key sets non-empty first, since an empty one satisfies
107
- disjointness while proving nothing.
62
+ The subpaths need a TypeScript `moduleResolution` that reads `exports`
63
+ (`NodeNext` or `Bundler`); see *Requirements* in
64
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
108
65
 
109
66
  ## Status
110
67
 
111
- Alpha — pre-v0. The package is being populated incrementally, and its API is
112
- not yet stable. See the [repository README](../../README.md) for the current
113
- status and known limitations.
68
+ Alpha: every release is a prerelease that may break the API, so pin an exact
69
+ version. Guides and known limitations:
70
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
114
71
 
115
72
  ## License
116
73
 
117
74
  `MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
118
- [`NOTICE.md`](../../NOTICE.md) for third-party notices.
75
+ [`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
76
+ for third-party notices.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hydranium/protocol",
3
- "version": "1.0.0-next.244",
3
+ "version": "1.0.0-next.246",
4
4
  "description": "Generic, language-agnostic types, constants, and pure utilities for the hydranium framework.",
5
5
  "keywords": [
6
6
  "hydranium",