@statewalker/webrun-streams-peerjs 0.1.1 → 0.2.2

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.
package/README.md CHANGED
@@ -1,16 +1,150 @@
1
1
  # @statewalker/webrun-streams-peerjs
2
2
 
3
- PeerJS DataConnection-backed `Connect` / `Serve` adapter. Wraps a `DataConnection` (which itself wraps a WebRTC DataChannel) into a byte channel; `emulateMux` provides multi-stream. Requires `serialization: "raw"` on the connection.
3
+ PeerJS `DataConnection`-backed `Connect` / `Serve` adapter in the
4
+ `webrun-streams-*` family.
5
+
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`.
16
+
17
+ ## Why it exists
18
+
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.
29
+
30
+ ## Install
31
+
32
+ ```sh
33
+ npm install @statewalker/webrun-streams-peerjs peerjs
34
+ ```
35
+
36
+ `peerjs` is a **peer dependency** (`^1.5.5`) — you own the `Peer` instance and
37
+ its broker configuration.
38
+
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.
42
+
43
+ ## Getting started
44
+
45
+ Responder — listen for inbound connections on a connected `Peer`:
46
+
47
+ ```ts
48
+ import Peer from "peerjs";
49
+ import { serve } from "@statewalker/webrun-streams-peerjs";
50
+
51
+ const peer = new Peer("my-server-id");
52
+ await new Promise((r) => peer.on("open", r));
53
+
54
+ const stop = await serve({ peer }, async function* echo(input) {
55
+ for await (const chunk of input) yield chunk;
56
+ });
57
+ ```
58
+
59
+ Caller — connect, then hand the open `DataConnection` to the adapter:
60
+
61
+ ```ts
62
+ import Peer from "peerjs";
63
+ import { connect } from "@statewalker/webrun-streams-peerjs";
64
+
65
+ const peer = new Peer();
66
+ const conn = peer.connect("my-server-id", { serialization: "raw" });
67
+ await new Promise((r) => conn.on("open", r));
68
+
69
+ const { call, close } = await connect({ conn });
70
+
71
+ for await (const chunk of call([new TextEncoder().encode("ping")])) {
72
+ console.log(new TextDecoder().decode(chunk)); // "ping"
73
+ }
74
+
75
+ await close();
76
+ ```
77
+
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
4
82
 
5
83
  ```ts
6
- import { connect, serve } from "@statewalker/webrun-streams-peerjs";
84
+ import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
85
+
86
+ const response = await fetchOverDuplex(call, new Request("http://peer/api/todo"));
87
+ ```
88
+
89
+ ## API
90
+
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>>`
7
104
 
8
- const { call } = await connect({ conn }); // open DataConnection
9
- const stop = await serve({ peer }, handler); // listens for inbound conns
105
+ Type: `Serve<ServePeerJsParams>`.
106
+
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`. |
111
+
112
+ Returns an idempotent teardown.
113
+
114
+ ### `byteChannelFromPeerJs(conn): ByteChannel`
115
+
116
+ Wraps one `DataConnection` as a `ByteChannel` (`send` / `recv` / `closed` /
117
+ `close`) for driving `emulateMux` yourself.
118
+
119
+ ### `ConnectPeerJsParams` / `ServePeerJsParams`
120
+
121
+ The two parameter types above.
122
+
123
+ ## Conformance
124
+
125
+ Runs [`@statewalker/webrun-streams-conformance`](../webrun-streams-conformance)
126
+ against a local broker (the [`peer`](https://www.npmjs.com/package/peer) server).
127
+
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.
132
+
133
+ ```sh
134
+ pnpm --filter @statewalker/webrun-streams-peerjs test:browser # runs the suite
135
+ pnpm --filter @statewalker/webrun-streams-peerjs test # reports it skipped
10
136
  ```
11
137
 
12
- Conformance is browser-gated; PeerJS's WebRTC handshake hangs under Node's wrtc polyfill. Run with `pnpm test:browser`.
138
+ ## Dependencies
139
+
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. |
145
+
146
+ ESM only (`"type": "module"`).
13
147
 
14
148
  ## License
15
149
 
16
- MIT
150
+ MIT © statewalker — see [LICENSE](../../LICENSE).
@@ -1,12 +1,28 @@
1
- import { type Connect, type Serve } from "@statewalker/webrun-streams";
1
+ import { type Connect, type EmulateMuxOptions, type Serve } from "@statewalker/webrun-streams";
2
2
  import type { DataConnection, Peer } from "peerjs";
3
3
  export interface ConnectPeerJsParams {
4
4
  /** Already-open `DataConnection` with `serialization: "raw"`. */
5
5
  conn: DataConnection;
6
+ /**
7
+ * Flow-control tuning forwarded to `emulateMux` — `mtu` and
8
+ * `maxStreamBuffer`, which is the credit this side advertises. `side` here
9
+ * wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
10
+ * suite's L6 uses this to run at a window small enough that a sender
11
+ * genuinely stalls.
12
+ */
13
+ mux?: EmulateMuxOptions;
6
14
  }
7
15
  export interface ServePeerJsParams {
8
16
  /** Connected `Peer`. The adapter listens for inbound `DataConnection`s. */
9
17
  peer: Peer;
18
+ /**
19
+ * Flow-control tuning forwarded to `emulateMux` — `mtu` and
20
+ * `maxStreamBuffer`, which is the credit this side advertises. `side` here
21
+ * wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
22
+ * suite's L6 uses this to run at a window small enough that a sender
23
+ * genuinely stalls.
24
+ */
25
+ mux?: EmulateMuxOptions;
10
26
  }
11
27
  export declare const connect: Connect<ConnectPeerJsParams>;
12
28
  export declare const serve: Serve<ServePeerJsParams>;
@@ -1 +1 @@
1
- {"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAA2B,KAAK,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAGnD,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,mBAAmB,CAShD,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,iBAAiB,CAuB1C,CAAC"}
1
+ {"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,iBAAiB,EAEtB,KAAK,KAAK,EACX,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAGnD,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,IAAI,EAAE,cAAc,CAAC;IACrB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,IAAI,EAAE,IAAI,CAAC;IACX;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,mBAAmB,CAShD,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,iBAAiB,CAuB1C,CAAC"}
package/dist/index.js CHANGED
@@ -91,9 +91,12 @@ function byteChannelFromPeerJs(conn) {
91
91
  }
92
92
  //#endregion
93
93
  //#region src/connect-serve.ts
94
- const connect = async ({ conn }) => {
94
+ const connect = async ({ conn, mux: muxOpts }) => {
95
95
  const channel = byteChannelFromPeerJs(conn);
96
- const mux = emulateMux(channel, { side: "initiator" });
96
+ const mux = emulateMux(channel, {
97
+ ...muxOpts,
98
+ side: "initiator"
99
+ });
97
100
  return {
98
101
  call: mux.call,
99
102
  async close() {
@@ -101,12 +104,15 @@ const connect = async ({ conn }) => {
101
104
  }
102
105
  };
103
106
  };
104
- const serve = async ({ peer }, handler) => {
107
+ const serve = async ({ peer, mux: muxOpts }, handler) => {
105
108
  const muxes = [];
106
109
  const onConnection = (conn) => {
107
110
  const ready = () => {
108
111
  const channel = byteChannelFromPeerJs(conn);
109
- const mux = emulateMux(channel, { side: "responder" });
112
+ const mux = emulateMux(channel, {
113
+ ...muxOpts,
114
+ side: "responder"
115
+ });
110
116
  mux.serve(handler);
111
117
  muxes.push(mux);
112
118
  channel.closed.then(() => mux.close());
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-peerjs",
3
- "version": "0.1.1",
3
+ "version": "0.2.2",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "PeerJS DataConnection-backed Connect/Serve adapter in the webrun-streams-* family",
@@ -15,33 +15,41 @@
15
15
  "url": "git@github.com:statewalker/webrun-wire.git"
16
16
  },
17
17
  "exports": {
18
- ".": "./src/index.ts"
18
+ ".": {
19
+ "source": "./src/index.ts",
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ }
19
23
  },
20
24
  "files": [
21
25
  "dist",
22
26
  "src"
23
27
  ],
24
28
  "dependencies": {
25
- "@statewalker/webrun-streams": "0.1.1"
29
+ "@statewalker/webrun-streams": "^0.2.1"
26
30
  },
27
31
  "peerDependencies": {
28
32
  "peerjs": "^1.5.5"
29
33
  },
30
34
  "devDependencies": {
31
- "@roamhq/wrtc": "^0.8.0",
32
- "@types/node": "^26.2.0",
35
+ "@biomejs/biome": "^2.5.15",
36
+ "@roamhq/wrtc": "^0.10.0",
37
+ "@types/node": "^26.6.4",
38
+ "@vitest/browser-playwright": "^5.0.3",
33
39
  "peer": "^1.0.2",
34
40
  "peerjs": "^1.5.5",
41
+ "playwright": "^1.63.0",
35
42
  "rimraf": "^6.1.3",
36
- "rolldown": "^1.2.4",
43
+ "rolldown": "^1.2.12",
37
44
  "typescript": "^7.0.2",
38
- "vitest": "^4.1.10",
39
- "@statewalker/webrun-streams-conformance": "0.1.1"
45
+ "vitest": "^5.0.3",
46
+ "@statewalker/webrun-streams-conformance": "^0.3.1"
40
47
  },
41
48
  "sideEffects": false,
42
49
  "publishConfig": {
43
50
  "access": "public"
44
51
  },
52
+ "types": "./dist/index.d.ts",
45
53
  "scripts": {
46
54
  "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
47
55
  "test": "vitest run",
@@ -1,20 +1,42 @@
1
- import { type Connect, type Duplex, emulateMux, type Serve } from "@statewalker/webrun-streams";
1
+ import {
2
+ type Connect,
3
+ type Duplex,
4
+ type EmulateMuxOptions,
5
+ emulateMux,
6
+ type Serve,
7
+ } from "@statewalker/webrun-streams";
2
8
  import type { DataConnection, Peer } from "peerjs";
3
9
  import { byteChannelFromPeerJs } from "./byte-channel.js";
4
10
 
5
11
  export interface ConnectPeerJsParams {
6
12
  /** Already-open `DataConnection` with `serialization: "raw"`. */
7
13
  conn: DataConnection;
14
+ /**
15
+ * Flow-control tuning forwarded to `emulateMux` — `mtu` and
16
+ * `maxStreamBuffer`, which is the credit this side advertises. `side` here
17
+ * wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
18
+ * suite's L6 uses this to run at a window small enough that a sender
19
+ * genuinely stalls.
20
+ */
21
+ mux?: EmulateMuxOptions;
8
22
  }
9
23
 
10
24
  export interface ServePeerJsParams {
11
25
  /** Connected `Peer`. The adapter listens for inbound `DataConnection`s. */
12
26
  peer: Peer;
27
+ /**
28
+ * Flow-control tuning forwarded to `emulateMux` — `mtu` and
29
+ * `maxStreamBuffer`, which is the credit this side advertises. `side` here
30
+ * wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
31
+ * suite's L6 uses this to run at a window small enough that a sender
32
+ * genuinely stalls.
33
+ */
34
+ mux?: EmulateMuxOptions;
13
35
  }
14
36
 
15
- export const connect: Connect<ConnectPeerJsParams> = async ({ conn }) => {
37
+ export const connect: Connect<ConnectPeerJsParams> = async ({ conn, mux: muxOpts }) => {
16
38
  const channel = byteChannelFromPeerJs(conn);
17
- const mux = emulateMux(channel, { side: "initiator" });
39
+ const mux = emulateMux(channel, { ...muxOpts, side: "initiator" });
18
40
  return {
19
41
  call: mux.call,
20
42
  async close() {
@@ -23,13 +45,13 @@ export const connect: Connect<ConnectPeerJsParams> = async ({ conn }) => {
23
45
  };
24
46
  };
25
47
 
26
- export const serve: Serve<ServePeerJsParams> = async ({ peer }, handler: Duplex) => {
48
+ export const serve: Serve<ServePeerJsParams> = async ({ peer, mux: muxOpts }, handler: Duplex) => {
27
49
  const muxes: Array<{ close: () => Promise<void> }> = [];
28
50
 
29
51
  const onConnection = (conn: DataConnection): void => {
30
52
  const ready = (): void => {
31
53
  const channel = byteChannelFromPeerJs(conn);
32
- const mux = emulateMux(channel, { side: "responder" });
54
+ const mux = emulateMux(channel, { ...muxOpts, side: "responder" });
33
55
  mux.serve(handler);
34
56
  muxes.push(mux);
35
57
  void channel.closed.then(() => mux.close());