@statewalker/webrun-streams-peerjs 0.2.0 → 0.2.3

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 (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +95 -81
  3. package/package.json +17 -11
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2022-2026 statewalker
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,70 +1,80 @@
1
1
  # @statewalker/webrun-streams-peerjs
2
2
 
3
- PeerJS `DataConnection`-backed `Connect` / `Serve` adapter in the
4
- `webrun-streams-*` family.
3
+ ## What it is
5
4
 
6
- ## What this is
7
-
8
- A binding between a PeerJS [`DataConnection`](https://peerjs.com/docs/#dataconnection)
9
- and the [`webrun-streams`](../webrun-streams) `Duplex` seam. One
10
- `DataConnection` becomes one `ByteChannel`; `emulateMux` layers many concurrent
11
- logical calls on top of it.
12
-
13
- Your handler is an ordinary `Duplex` —
14
- `(input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>` — identical
15
- to the one you would run over a WebSocket or a `MessagePort`.
5
+ A `Connect` / `Serve` adapter that runs `@statewalker/webrun-streams` `Duplex` calls over a PeerJS
6
+ [`DataConnection`](https://peerjs.com/docs/#dataconnection). One connection becomes one
7
+ `ByteChannel`, and `webrun-streams`' `emulateMux` runs many concurrent calls over it. Your handler
8
+ is an ordinary `Duplex`, `(input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>`, the
9
+ same function you would run over a WebSocket or a `MessagePort`.
16
10
 
17
11
  ## Why it exists
18
12
 
19
- PeerJS is the least-effort route to a browser-to-browser connection: it ships a
20
- public broker, so you get a working peer link without standing up signalling
21
- infrastructure. What it hands you afterwards is a single message pipe with no
22
- request framing, no concurrency, no half-close, and no error propagation.
23
-
24
- This adapter supplies those once, so the transport becomes an implementation
25
- detail — prototype over PeerJS's public broker, then move the same handler to
26
- [`webrun-streams-webrtc`](../webrun-streams-webrtc) or
27
- [`webrun-streams-libp2p`](../webrun-streams-libp2p) for production without
28
- touching it.
13
+ PeerJS is the least-effort route to a browser-to-browser connection: it ships a public broker, so
14
+ you get a working peer link without running signalling infrastructure. What it hands you is one
15
+ message pipe with no request framing, no concurrency, no half-close and no error propagation. This
16
+ adapter supplies those, so the transport becomes a detail: a handler prototyped over PeerJS runs
17
+ unchanged over any other `webrun-streams` adapter.
29
18
 
30
- ## Install
19
+ ## How to use
31
20
 
32
21
  ```sh
33
- npm install @statewalker/webrun-streams-peerjs peerjs
22
+ pnpm add @statewalker/webrun-streams-peerjs peerjs
34
23
  ```
35
24
 
36
- `peerjs` is a **peer dependency** (`^1.5.5`) — you own the `Peer` instance and
37
- its broker configuration.
25
+ `peerjs` is a required peer dependency (`^1.5.5`). You create and own the `Peer`, its broker
26
+ configuration and its connections. Browser only in practice: PeerJS needs WebRTC. One entry point,
27
+ `.`, ESM only.
28
+
29
+ **Connections must use `serialization: "raw"`.** Otherwise PeerJS encodes the bytes itself and the
30
+ mux framing does not survive. The adapter checks and throws
31
+ `TypeError: byteChannelFromPeerJs: DataConnection serialization is '<value>', expected 'raw'`.
32
+
33
+ | Export | Purpose |
34
+ | --- | --- |
35
+ | `connect(params: ConnectPeerJsParams)` | `Connect`. Takes one open `DataConnection`. Resolves `{ call, close }`; each `call(input)` opens a new logical stream. `close()` ends the mux and closes the connection. |
36
+ | `serve(params: ServePeerJsParams, handler)` | `Serve`. Takes a `Peer`, serves `handler` on every inbound connection. Resolves an idempotent teardown. |
37
+ | `ConnectPeerJsParams` | `{ conn: DataConnection; mux?: EmulateMuxOptions }`. |
38
+ | `ServePeerJsParams` | `{ peer: Peer; mux?: EmulateMuxOptions }`. |
39
+ | `byteChannelFromPeerJs(conn)` | The `ByteChannel` both use, for driving `emulateMux` yourself. |
38
40
 
39
- > [!IMPORTANT]
40
- > Connections must be opened with `serialization: "raw"`. PeerJS otherwise
41
- > applies its own encoding to your bytes and the framing will not survive.
41
+ `mux` is forwarded to `emulateMux` (`mtu`, `maxStreamBuffer`, `maxStreams`, with `webrun-streams`'
42
+ defaults: 64 KiB, 8 MiB, 256). `side` is fixed by the function you call — `"initiator"` for
43
+ `connect`, `"responder"` for `serve` — and overrides `mux.side`.
42
44
 
43
- ## Getting started
45
+ `serve` takes the `Peer` because it accepts many inbound connections; `connect` takes one
46
+ connection you already opened.
44
47
 
45
- Responder — listen for inbound connections on a connected `Peer`:
48
+ ## Examples
49
+
50
+ ### Serving
46
51
 
47
52
  ```ts
48
- import Peer from "peerjs";
53
+ import { Peer } from "peerjs";
49
54
  import { serve } from "@statewalker/webrun-streams-peerjs";
50
55
 
51
56
  const peer = new Peer("my-server-id");
52
- await new Promise((r) => peer.on("open", r));
57
+ await new Promise((resolve) => peer.on("open", resolve));
53
58
 
54
59
  const stop = await serve({ peer }, async function* echo(input) {
55
60
  for await (const chunk of input) yield chunk;
56
61
  });
62
+
63
+ // later: stop accepting, close every served connection's mux
64
+ await stop();
57
65
  ```
58
66
 
59
- Caller — connect, then hand the open `DataConnection` to the adapter:
67
+ ### Calling
60
68
 
61
69
  ```ts
62
- import Peer from "peerjs";
70
+ import { Peer } from "peerjs";
63
71
  import { connect } from "@statewalker/webrun-streams-peerjs";
64
72
 
65
73
  const peer = new Peer();
74
+ await new Promise((resolve) => peer.on("open", resolve));
75
+
66
76
  const conn = peer.connect("my-server-id", { serialization: "raw" });
67
- await new Promise((r) => conn.on("open", r));
77
+ await new Promise((resolve) => conn.on("open", resolve));
68
78
 
69
79
  const { call, close } = await connect({ conn });
70
80
 
@@ -75,10 +85,7 @@ for await (const chunk of call([new TextEncoder().encode("ping")])) {
75
85
  await close();
76
86
  ```
77
87
 
78
- Note the asymmetry: `serve` takes the `Peer` (it accepts many inbound
79
- connections), `connect` takes one already-open `DataConnection`.
80
-
81
- ### Carrying HTTP over it
88
+ ### HTTP over the connection
82
89
 
83
90
  ```ts
84
91
  import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
@@ -86,65 +93,72 @@ import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
86
93
  const response = await fetchOverDuplex(call, new Request("http://peer/api/todo"));
87
94
  ```
88
95
 
89
- ## API
96
+ ### Driving the mux yourself
90
97
 
91
- ### `connect(params): Promise<{ call, close }>`
92
-
93
- Type: `Connect<ConnectPeerJsParams>`.
94
-
95
- | Field | Type | Meaning |
96
- | --- | --- | --- |
97
- | `conn` | `DataConnection` | An already-open connection with `serialization: "raw"`. |
98
- | `mux` | `EmulateMuxOptions` | Flow-control tuning (`mtu`, `maxStreamBuffer`) forwarded to `emulateMux`. `side` is always `"initiator"` regardless of `mux.side`. |
99
-
100
- Each `call(input)` opens a new logical stream over that connection. `close()`
101
- tears down the streams and the channel.
102
-
103
- ### `serve(params, handler): Promise<() => Promise<void>>`
104
-
105
- Type: `Serve<ServePeerJsParams>`.
98
+ ```ts
99
+ import { emulateMux } from "@statewalker/webrun-streams";
100
+ import { byteChannelFromPeerJs } from "@statewalker/webrun-streams-peerjs";
106
101
 
107
- | Field | Type | Meaning |
108
- | --- | --- | --- |
109
- | `peer` | `Peer` | A connected peer; the adapter listens for inbound `DataConnection`s. |
110
- | `mux` | `EmulateMuxOptions` | Flow-control tuning (`mtu`, `maxStreamBuffer`) forwarded to `emulateMux`. `side` is always `"responder"` regardless of `mux.side`. |
102
+ const channel = byteChannelFromPeerJs(conn); // conn opened with serialization: "raw"
103
+ const mux = emulateMux(channel, { side: "initiator" });
104
+ // mux.call(input), mux.serve(handler), mux.close()
105
+ ```
111
106
 
112
- Returns an idempotent teardown.
107
+ ## Internals
113
108
 
114
- ### `byteChannelFromPeerJs(conn): ByteChannel`
109
+ ```
110
+ handler / caller (Duplex)
111
+ │
112
+ emulateMux (webrun-streams): framed streams, credit flow control
113
+ │
114
+ byteChannelFromPeerJs: one ByteChannel per DataConnection
115
+ │ out: conn.send(bytes) in: "data" events
116
+ ▼
117
+ PeerJS DataConnection (serialization: "raw") ── WebRTC data channel
118
+ ```
115
119
 
116
- Wraps one `DataConnection` as a `ByteChannel` (`send` / `recv` / `closed` /
117
- `close`) for driving `emulateMux` yourself.
120
+ ### What the channel accepts, and what it drops
118
121
 
119
- ### `ConnectPeerJsParams` / `ServePeerJsParams`
122
+ Inbound `data` may be a `Uint8Array`, an `ArrayBuffer`, any `ArrayBufferView` or a `Blob` (read
123
+ asynchronously); each is copied into a fresh `Uint8Array`. Anything else is ignored. Outbound
124
+ `send` is a silent no-op while `conn.open` is false, so **wait for the connection's `open` event
125
+ before `connect`**; bytes sent earlier are lost without an error.
120
126
 
121
- The two parameter types above.
127
+ ### What closes the channel, and what you see
122
128
 
123
- ## Conformance
129
+ The channel closes on the connection's `close` event or when its `close()` is called. In-flight
130
+ and later calls then fail with `webrun-streams`' `TransportClosedError`. On the serving side each
131
+ inbound connection gets its own mux, created when the connection opens and closed when the
132
+ connection closes. A connection that arrives without `serialization: "raw"` makes the adapter
133
+ throw the `TypeError` above inside the connection's `open` handler, and that connection is not
134
+ served.
124
135
 
125
- Runs [`@statewalker/webrun-streams-conformance`](../webrun-streams-conformance)
126
- against a local broker (the [`peer`](https://www.npmjs.com/package/peer) server).
136
+ The serve teardown removes the `connection` listener and closes every mux it created. Muxes are
137
+ kept in a list until then, including those whose connection already closed.
127
138
 
128
- The suite is **browser-gated**. `@roamhq/wrtc` covers the WebRTC primitives in
129
- Node, but the full PeerJS handshake hangs there, so
130
- `tests/conformance.test.ts` registers the suite only when a `window` global is
131
- present; the plain Node run reports it as skipped.
139
+ ### Conformance runs in a browser against a local broker
132
140
 
133
141
  ```sh
134
142
  pnpm --filter @statewalker/webrun-streams-peerjs test:browser # runs the suite
135
143
  pnpm --filter @statewalker/webrun-streams-peerjs test # reports it skipped
136
144
  ```
137
145
 
138
- ## Dependencies
146
+ The `@statewalker/webrun-streams-conformance` suite runs in headless Chromium through Playwright.
147
+ A Vitest global setup starts the reference broker (the [`peer`](https://www.npmjs.com/package/peer)
148
+ package's `PeerServer`) on a loopback port in a child process, so runs need no internet access.
149
+ The broker runs out of process because, hosted in-process, it keeps the test run alive after the
150
+ last test: its `close()` waits on the browser's WebSockets and it holds client-expiry timers with
151
+ no public way to clear them. Under plain `pnpm test` (Node) the suite is skipped: the full PeerJS
152
+ handshake hangs there.
139
153
 
140
- | Dependency | Kind | Why |
141
- | --- | --- | --- |
142
- | [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` / `ByteChannel` seam and `emulateMux`. |
143
- | `peerjs` | **peer** (`^1.5.5`) | You supply and own the `Peer`. |
144
- | `peer`, `@roamhq/wrtc` | dev | Local broker and WebRTC for the conformance run. |
154
+ ### Dependencies
145
155
 
146
- ESM only (`"type": "module"`).
156
+ - `@statewalker/webrun-streams` (runtime): the `Duplex` / `Connect` / `Serve` / `ByteChannel`
157
+ types and `emulateMux`.
158
+ - `peerjs` (peer): you supply and own the `Peer`.
159
+ - Dev only: `peer` (the local broker), `@vitest/browser-playwright` and `playwright` (the browser
160
+ run), `@statewalker/webrun-streams-conformance` (the suite).
147
161
 
148
162
  ## License
149
163
 
150
- MIT © statewalker — see [LICENSE](../../LICENSE).
164
+ MIT
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-peerjs",
3
- "version": "0.2.0",
3
+ "version": "0.2.3",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "PeerJS DataConnection-backed Connect/Serve adapter in the webrun-streams-* family",
7
- "homepage": "https://github.com/statewalker/webrun-wire",
7
+ "bugs": {
8
+ "url": "https://github.com/statewalker/webrun-wire/issues"
9
+ },
10
+ "homepage": "https://github.com/statewalker/webrun-wire/tree/main/packages/webrun-streams-peerjs#readme",
8
11
  "author": {
9
12
  "name": "Mikhail Kotelnikov",
10
13
  "email": "mikhail.kotelnikov@gmail.com"
@@ -12,10 +15,12 @@
12
15
  "license": "MIT",
13
16
  "repository": {
14
17
  "type": "git",
15
- "url": "git@github.com:statewalker/webrun-wire.git"
18
+ "url": "git+https://github.com/statewalker/webrun-wire.git",
19
+ "directory": "packages/webrun-streams-peerjs"
16
20
  },
17
21
  "exports": {
18
22
  ".": {
23
+ "source": "./src/index.ts",
19
24
  "types": "./dist/index.d.ts",
20
25
  "import": "./dist/index.js"
21
26
  }
@@ -25,23 +30,24 @@
25
30
  "src"
26
31
  ],
27
32
  "dependencies": {
28
- "@statewalker/webrun-streams": "0.2.0"
33
+ "@statewalker/webrun-streams": "^0.2.2"
29
34
  },
30
35
  "peerDependencies": {
31
36
  "peerjs": "^1.5.5"
32
37
  },
33
38
  "devDependencies": {
34
- "@roamhq/wrtc": "^0.8.0",
35
- "@types/node": "^26.2.0",
36
- "@vitest/browser-playwright": "^4.1.10",
39
+ "@biomejs/biome": "^2.5.15",
40
+ "@roamhq/wrtc": "^0.10.0",
41
+ "@types/node": "^26.6.4",
42
+ "@vitest/browser-playwright": "^5.0.3",
37
43
  "peer": "^1.0.2",
38
44
  "peerjs": "^1.5.5",
39
- "playwright": "^1.62.1",
45
+ "playwright": "^1.63.0",
40
46
  "rimraf": "^6.1.3",
41
- "rolldown": "^1.2.4",
47
+ "rolldown": "^1.2.12",
42
48
  "typescript": "^7.0.2",
43
- "vitest": "^4.1.10",
44
- "@statewalker/webrun-streams-conformance": "0.2.0"
49
+ "vitest": "^5.0.3",
50
+ "@statewalker/webrun-streams-conformance": "^0.3.2"
45
51
  },
46
52
  "sideEffects": false,
47
53
  "publishConfig": {