@transport-io/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 #V0ID <hey@v0id.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @transport-io/react
+
+React bindings for [transport-io](https://www.npmjs.com/package/transport-io).
+
+```bash
+npm install @transport-io/react
+```
+
+React and react-dom are peer dependencies and the floor is **React 19.2**, because `useEvent`
+is built on `useEffectEvent`. There is no other runtime dependency, and core neither depends
+on this package nor mentions it.
+
+## What it gives you
+
+| | |
+|---|---|
+| `<TransportProvider client>` | Holds the client and connects while mounted. Takes a client rather than making one. |
+| `useClient()` | The client itself, for `emit` and anything else. |
+| `useConnection()` | Status, session id, rooms, last error, and the connect and disconnect calls. |
+| `useEvent(name, handler)` | Subscribe for as long as the component is mounted. No memoising required. |
+| `useCall(name)` | Request and response, as a discriminated union. |
+| `useStream(name)` | A streaming response, accumulated, cancelled on unmount. |
+
+There is deliberately no `useEmit` and no `useRooms`. `emit` is one synchronous method with
+no state and no cleanup, so `useClient().emit(…)` is already the right call. `useRooms` would
+read one field off a snapshot while re-rendering on every change to any of it, which looks
+like a narrow subscription and is not one; `useConnection().rooms` is the same thing without
+the false promise.
+
+## The parts that are easy to get wrong
+
+**All state comes through `useSyncExternalStore`.** `useConnection` returns a referentially
+stable object, so it is safe in a dependency array.
+
+**Handlers do not need memoising.** `useEvent` wraps yours in an Effect Event, so an inline
+arrow re-created every render subscribes exactly once.
+
+**Server rendering reports `idle`**, which is both true and what makes the server's HTML match
+the client's first render.
+
+**Unmounting cleans up.** Subscriptions unsubscribe, an in-flight call aborts unless you pass
+`{ abortOnUnmount: false }`, and a stream cancels, which resets the QUIC stream and runs the
+responder's `finally`.
+
+**Your `connect` function must return a new connection each call.** A reconnect is a new
+session and StrictMode calls it twice in development.
+
+The [React guide](https://transport-io.github.io/transport-io/guides/react/) has the whole
+thing with code.
+
+## Licence
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from 'react';
+/**
+ * The client, and how components reach it.
+ *
+ * The provider takes a client rather than making one. Construction needs a `connect`
+ * function, which is transport-specific, and hiding that choice in here would mean
+ * re-exporting transport concerns from a React package. It also matters for the server: a
+ * module-level singleton client is a cross-request state leak on anything rendering more
+ * than one user, so the documented pattern builds one per browser session inside a client
+ * component and the server never shares it.
+ */
+import type { Client } from 'transport-io';
+export interface TransportProviderProps {
+    readonly client: Client;
+    /**
+     * Connect while the provider is mounted. On by default: `connect` and `disconnect` are
+     * idempotent and refcounted in core, so mounting twice is safe, and every application
+     * writes this effect identically. Pass `false` to drive the connection yourself.
+     */
+    readonly autoConnect?: boolean;
+    readonly children?: ReactNode;
+}
+export declare function TransportProvider({ client, autoConnect, children, }: TransportProviderProps): ReactNode;
+/**
+ * The client from the nearest provider.
+ *
+ * Throws a plain `Error` rather than a `TransportError`: nothing has gone wrong on the
+ * wire, and core must never gain a React-shaped error code.
+ */
+export declare function useClient(): Client;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,SAAS,EAAyB,MAAM,OAAO,CAAA;AAC5E;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAI1C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAC9B;AAED,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,WAAkB,EAClB,QAAQ,GACT,EAAE,sBAAsB,GAAG,SAAS,CAapC;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAUlC"}

package/dist/context.js

@@ -0,0 +1,34 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect } from 'react';
+const ClientContext = createContext(null);
+export function TransportProvider({ client, autoConnect = true, children, }) {
+    useEffect(() => {
+        if (!autoConnect)
+            return;
+        // A failed connect is reported through `lastError` on the snapshot, which is what
+        // `useConnection` reads. Rethrowing here would be an unhandled rejection with nowhere
+        // to be caught, since an effect has no caller.
+        void client.connect().catch(() => undefined);
+        return () => {
+            client.disconnect();
+        };
+    }, [client, autoConnect]);
+    return _jsx(ClientContext.Provider, { value: client, children: children });
+}
+/**
+ * The client from the nearest provider.
+ *
+ * Throws a plain `Error` rather than a `TransportError`: nothing has gone wrong on the
+ * wire, and core must never gain a React-shaped error code.
+ */
+export function useClient() {
+    const client = useContext(ClientContext);
+    if (client === null) {
+        throw new Error('no transport-io client in context. Wrap this tree in <TransportProvider client={…}>, ' +
+            'and note that the provider is a client component: it needs "use client" at the top ' +
+            'of the file that renders it.');
+    }
+    return client;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;;AACZ,OAAO,EAAE,aAAa,EAAkB,UAAU,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAa5E,MAAM,aAAa,GAAG,aAAa,CAAgB,IAAI,CAAC,CAAA;AAaxD,MAAM,UAAU,iBAAiB,CAAC,EAChC,MAAM,EACN,WAAW,GAAG,IAAI,EAClB,QAAQ,GACe;IACvB,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,WAAW;YAAE,OAAM;QACxB,kFAAkF;QAClF,sFAAsF;QACtF,+CAA+C;QAC/C,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC5C,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,UAAU,EAAE,CAAA;QACrB,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAA;IAEzB,OAAO,KAAC,aAAa,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YAAG,QAAQ,GAA0B,CAAA;AACnF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,MAAM,GAAG,UAAU,CAAC,aAAa,CAAC,CAAA;IACxC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,uFAAuF;YACrF,qFAAqF;YACrF,8BAA8B,CACjC,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * React bindings for transport-io.
+ *
+ * Every hook reads state through `useSyncExternalStore`, every subscription unsubscribes on
+ * unmount, and nothing touches `window` or `WebTransport` at module scope, so importing this
+ * on a server is safe.
+ */
+export { TransportProvider, type TransportProviderProps, useClient } from './context.tsx';
+export { type CallState, type UseCallOptions, type UseCallResult, useCall } from './use-call.ts';
+export { type Connection, useConnection } from './use-connection.ts';
+export { useEvent } from './use-event.ts';
+export { type StreamState, type UseStreamOptions, type UseStreamResult, useStream, } from './use-stream.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzF,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAChG,OAAO,EAAE,KAAK,UAAU,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,SAAS,GACV,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * React bindings for transport-io.
+ *
+ * Every hook reads state through `useSyncExternalStore`, every subscription unsubscribes on
+ * unmount, and nothing touches `window` or `WebTransport` at module scope, so importing this
+ * on a server is safe.
+ */
+export { TransportProvider, useClient } from './context.js';
+export { useCall } from './use-call.js';
+export { useConnection } from './use-connection.js';
+export { useEvent } from './use-event.js';
+export { useStream, } from './use-stream.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,iBAAiB,EAA+B,SAAS,EAAE,MAAM,cAAe,CAAA;AACzF,OAAO,EAA2D,OAAO,EAAE,MAAM,eAAe,CAAA;AAChG,OAAO,EAAmB,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAIL,SAAS,GACV,MAAM,iBAAiB,CAAA"}

package/dist/use-call.d.ts

@@ -0,0 +1,37 @@
+import { type CallableOf, type Registered, TransportError } from 'transport-io';
+/**
+ * A union rather than independent flags.
+ *
+ * With flags, `data` is `R | undefined` and every consumer narrows it by hand, while
+ * `pending` and `error` can both be true at once. Checking `status` here narrows `data`
+ * automatically, and the impossible combinations cannot be written down.
+ */
+export type CallState<R> = {
+    readonly status: 'idle';
+} | {
+    readonly status: 'pending';
+} | {
+    readonly status: 'error';
+    readonly error: TransportError;
+} | {
+    readonly status: 'success';
+    readonly data: R;
+};
+export interface UseCallOptions {
+    /**
+     * Abort an in-flight call when the component unmounts. On by default: an unmounted
+     * component's answer goes nowhere, and aborting is a QUIC stream reset that costs no
+     * application message.
+     *
+     * Pass `false` when the call has a server-side effect that must complete regardless of
+     * whether anyone is still watching.
+     */
+    readonly abortOnUnmount?: boolean;
+}
+export type UseCallResult<K extends CallableOf<Registered> & string> = readonly [
+    (payload: Registered[K]['payload']) => Promise<void>,
+    CallState<Registered[K]['returns']>
+];
+/** Request and response, with the state a component actually renders. */
+export declare function useCall<K extends CallableOf<Registered> & string>(event: K, options?: UseCallOptions): UseCallResult<K>;
+//# sourceMappingURL=use-call.d.ts.map

package/dist/use-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-call.d.ts","sourceRoot":"","sources":["../src/use-call.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAG/E;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IACnB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAAA;AAEpD,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAClC;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,CAAC,GAAG,MAAM,IAAI,SAAS;IAC9E,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC;IACpD,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;CACpC,CAAA;AAWD,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,CAAC,GAAG,MAAM,EAC/D,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,cAAc,GACvB,aAAa,CAAC,CAAC,CAAC,CA0ClB"}

package/dist/use-call.js

@@ -0,0 +1,50 @@
+'use client';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { TransportError } from 'transport-io';
+import { useClient } from './context.js';
+function asTransportError(e) {
+    if (e instanceof TransportError)
+        return e;
+    return new TransportError('WT_HANDLER_ERROR', e instanceof Error ? e.message : String(e), 'The call rejected with something that was not a TransportError.');
+}
+/** Request and response, with the state a component actually renders. */
+export function useCall(event, options) {
+    const client = useClient();
+    const [state, setState] = useState({ status: 'idle' });
+    const abortOnUnmount = options?.abortOnUnmount ?? true;
+    const inFlight = useRef(null);
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            if (abortOnUnmount)
+                inFlight.current?.abort();
+        };
+    }, [abortOnUnmount]);
+    const invoke = useCallback(async (payload) => {
+        // A second call supersedes the first: rendering two answers at once is not a state
+        // this union can hold, and the newer one is the one the user asked for.
+        inFlight.current?.abort();
+        const controller = new AbortController();
+        inFlight.current = controller;
+        setState({ status: 'pending' });
+        try {
+            const data = await client.call(event, payload, { signal: controller.signal });
+            if (mounted.current && inFlight.current === controller) {
+                setState({ status: 'success', data });
+            }
+        }
+        catch (e) {
+            // An abort is this hook's own doing, on unmount or on being superseded. Reporting
+            // it as an error would put a failure on screen that nobody caused.
+            if (controller.signal.aborted)
+                return;
+            if (mounted.current && inFlight.current === controller) {
+                setState({ status: 'error', error: asTransportError(e) });
+            }
+        }
+    }, [client, event]);
+    return useMemo(() => [invoke, state], [invoke, state]);
+}
+//# sourceMappingURL=use-call.js.map

package/dist/use-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-call.js","sourceRoot":"","sources":["../src/use-call.ts"],"names":[],"mappings":"AAAA,YAAY,CAAA;AACZ,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACzE,OAAO,EAAoC,cAAc,EAAE,MAAM,cAAc,CAAA;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,cAAe,CAAA;AAgCzC,SAAS,gBAAgB,CAAC,CAAU;IAClC,IAAI,CAAC,YAAY,cAAc;QAAE,OAAO,CAAC,CAAA;IACzC,OAAO,IAAI,cAAc,CACvB,kBAAkB,EAClB,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAC1C,iEAAiE,CAClE,CAAA;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,OAAO,CACrB,KAAQ,EACR,OAAwB;IAExB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAC1B,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAsC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAC3F,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAA;IAEtD,MAAM,QAAQ,GAAG,MAAM,CAAyB,IAAI,CAAC,CAAA;IACrD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;IAE5B,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,OAAO,GAAG,IAAI,CAAA;QACtB,OAAO,GAAG,EAAE;YACV,OAAO,CAAC,OAAO,GAAG,KAAK,CAAA;YACvB,IAAI,cAAc;gBAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,CAAA;QAC/C,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAA;IAEpB,MAAM,MAAM,GAAG,WAAW,CACxB,KAAK,EAAE,OAAiC,EAAiB,EAAE;QACzD,mFAAmF;QACnF,wEAAwE;QACxE,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,CAAA;QACzB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,QAAQ,CAAC,OAAO,GAAG,UAAU,CAAA;QAC7B,QAAQ,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAA;YAC7E,IAAI,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;gBACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YACvC,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,kFAAkF;YAClF,mEAAmE;YACnE,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAM;YACrC,IAAI,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;gBACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YAC3D,CAAC;QACH,CAAC;IACH,CAAC,EACD,CAAC,MAAM,EAAE,KAAK,CAAC,CAChB,CAAA;IAED,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,CAAU,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;AACjE,CAAC"}

package/dist/use-connection.d.ts

@@ -0,0 +1,20 @@
+import type { ClientState } from 'transport-io';
+export interface Connection extends ClientState {
+    readonly connect: () => Promise<void>;
+    readonly disconnect: () => void;
+}
+/**
+ * Connection state, and the two calls that change it.
+ *
+ * All state comes through `useSyncExternalStore`, which is what `subscribe` and
+ * `getSnapshot` exist for. `getSnapshot` returns a referentially stable object, so this
+ * hook's return is memoised on it rather than rebuilt: a fresh object per render would
+ * re-render forever in anything that puts it in a dependency array.
+ *
+ * **During server rendering this reports `idle`**, because that is true - no connection
+ * exists on a server - and because it makes the server's HTML identical to the client's
+ * first render. The connect effect then drives the only transition, so there is no
+ * hydration mismatch. Any other server value would produce one.
+ */
+export declare function useConnection(): Connection;
+//# sourceMappingURL=use-connection.d.ts.map

package/dist/use-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-connection.d.ts","sourceRoot":"","sources":["../src/use-connection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAG/C,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAA;CAChC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAc1C"}

package/dist/use-connection.js

@@ -0,0 +1,28 @@
+'use client';
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { useClient } from './context.js';
+/**
+ * Connection state, and the two calls that change it.
+ *
+ * All state comes through `useSyncExternalStore`, which is what `subscribe` and
+ * `getSnapshot` exist for. `getSnapshot` returns a referentially stable object, so this
+ * hook's return is memoised on it rather than rebuilt: a fresh object per render would
+ * re-render forever in anything that puts it in a dependency array.
+ *
+ * **During server rendering this reports `idle`**, because that is true - no connection
+ * exists on a server - and because it makes the server's HTML identical to the client's
+ * first render. The connect effect then drives the only transition, so there is no
+ * hydration mismatch. Any other server value would produce one.
+ */
+export function useConnection() {
+    const client = useClient();
+    const subscribe = useCallback((onChange) => client.subscribe(onChange), [client]);
+    const snapshot = useCallback(() => client.getSnapshot(), [client]);
+    const state = useSyncExternalStore(subscribe, snapshot, snapshot);
+    const connect = useCallback(() => client.connect(), [client]);
+    const disconnect = useCallback(() => {
+        client.disconnect();
+    }, [client]);
+    return useMemo(() => ({ ...state, connect, disconnect }), [state, connect, disconnect]);
+}
+//# sourceMappingURL=use-connection.js.map

package/dist/use-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-connection.js","sourceRoot":"","sources":["../src/use-connection.ts"],"names":[],"mappings":"AAAA,YAAY,CAAA;AACZ,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAElE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAe,CAAA;AAOzC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAE1B,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,QAAoB,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IAC7F,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IAElE,MAAM,KAAK,GAAG,oBAAoB,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;IAEjE,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IAC7D,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;QAClC,MAAM,CAAC,UAAU,EAAE,CAAA;IACrB,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IAEZ,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAA;AACzF,CAAC"}

package/dist/use-event.d.ts

@@ -0,0 +1,16 @@
+import type { Registered } from 'transport-io';
+/**
+ * Subscribe to an event for as long as the component is mounted.
+ *
+ * The handler may be a fresh inline arrow on every render and the subscription still
+ * happens once. `useEffectEvent` is the mechanism: it always sees the latest render's
+ * handler, so the effect below does not need it as a dependency and therefore does not
+ * resubscribe when it changes.
+ *
+ * Passing the Effect Event to `client.on` is the sanctioned shape, and the same one React's
+ * own `useInterval` example uses with `setInterval`. The restriction is on passing Effect
+ * Events to *components and Hooks*, and on calling them during render; `client.on` is a
+ * plain subscription API called from inside an Effect.
+ */
+export declare function useEvent<K extends keyof Registered & string>(event: K, handler: (payload: Registered[K]['payload']) => void): void;
+//# sourceMappingURL=use-event.d.ts.map

package/dist/use-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-event.d.ts","sourceRoot":"","sources":["../src/use-event.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,UAAU,GAAG,MAAM,EAC1D,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,IAAI,GACnD,IAAI,CAaN"}

package/dist/use-event.js

@@ -0,0 +1,27 @@
+'use client';
+import { useEffect, useEffectEvent } from 'react';
+import { useClient } from './context.js';
+/**
+ * Subscribe to an event for as long as the component is mounted.
+ *
+ * The handler may be a fresh inline arrow on every render and the subscription still
+ * happens once. `useEffectEvent` is the mechanism: it always sees the latest render's
+ * handler, so the effect below does not need it as a dependency and therefore does not
+ * resubscribe when it changes.
+ *
+ * Passing the Effect Event to `client.on` is the sanctioned shape, and the same one React's
+ * own `useInterval` example uses with `setInterval`. The restriction is on passing Effect
+ * Events to *components and Hooks*, and on calling them during render; `client.on` is a
+ * plain subscription API called from inside an Effect.
+ */
+export function useEvent(event, handler) {
+    const client = useClient();
+    const onPayload = useEffectEvent(handler);
+    useEffect(() => client.on(event, onPayload), 
+    // `onPayload` is deliberately absent. An Effect Event's identity changes on every
+    // render by design, so listing it here would resubscribe on every render - which is
+    // precisely the bug this hook exists to avoid. It looks like a missing dependency and
+    // is the opposite of one.
+    [client, event]);
+}
+//# sourceMappingURL=use-event.js.map

package/dist/use-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-event.js","sourceRoot":"","sources":["../src/use-event.ts"],"names":[],"mappings":"AAAA,YAAY,CAAA;AACZ,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAEjD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAe,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAQ,EACR,OAAoD;IAEpD,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAE1B,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IAEzC,SAAS,CACP,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC;IACjC,kFAAkF;IAClF,oFAAoF;IACpF,sFAAsF;IACtF,0BAA0B;IAC1B,CAAC,MAAM,EAAE,KAAK,CAAC,CAChB,CAAA;AACH,CAAC"}

package/dist/use-stream.d.ts

@@ -0,0 +1,36 @@
+import { type Registered, type StreamableOf, TransportError } from 'transport-io';
+/** `elements` is present in every state after the first, so a render never loses what arrived. */
+export type StreamState<T> = {
+    readonly status: 'idle';
+} | {
+    readonly status: 'streaming';
+    readonly elements: readonly T[];
+} | {
+    readonly status: 'done';
+    readonly elements: readonly T[];
+} | {
+    readonly status: 'error';
+    readonly elements: readonly T[];
+    readonly error: TransportError;
+};
+export interface UseStreamOptions<T> {
+    /**
+     * Called for each element as it arrives. Use it to render without accumulating: the
+     * `elements` array grows for the life of the stream and a long generation is a long array.
+     */
+    readonly onElement?: (element: T) => void;
+}
+export type UseStreamResult<K extends StreamableOf<Registered> & string> = readonly [
+    (payload: Registered[K]['payload']) => void,
+    StreamState<Registered[K]['yields']>,
+    () => void
+];
+/**
+ * A streaming response, accumulated.
+ *
+ * Unmounting cancels. That resets the QUIC stream, which fires the responder's `ctx.signal`
+ * and runs any `finally` in its generator, so a component going away does not leave a
+ * generator producing into nothing.
+ */
+export declare function useStream<K extends StreamableOf<Registered> & string>(event: K, options?: UseStreamOptions<Registered[K]['yields']>): UseStreamResult<K>;
+//# sourceMappingURL=use-stream.d.ts.map

package/dist/use-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-stream.d.ts","sourceRoot":"","sources":["../src/use-stream.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGjF,kGAAkG;AAClG,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAA;CAAE,GAC5D;IACE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAC/B,CAAA;AAEL,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAA;CAC1C;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,YAAY,CAAC,UAAU,CAAC,GAAG,MAAM,IAAI,SAAS;IAClF,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,IAAI;IAC3C,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,IAAI;CACX,CAAA;AAWD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,YAAY,CAAC,UAAU,CAAC,GAAG,MAAM,EACnE,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAClD,eAAe,CAAC,CAAC,CAAC,CAiEpB"}

package/dist/use-stream.js

@@ -0,0 +1,74 @@
+'use client';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { TransportError } from 'transport-io';
+import { useClient } from './context.js';
+function asTransportError(e) {
+    if (e instanceof TransportError)
+        return e;
+    return new TransportError('WT_HANDLER_ERROR', e instanceof Error ? e.message : String(e), 'The stream rejected with something that was not a TransportError.');
+}
+/**
+ * A streaming response, accumulated.
+ *
+ * Unmounting cancels. That resets the QUIC stream, which fires the responder's `ctx.signal`
+ * and runs any `finally` in its generator, so a component going away does not leave a
+ * generator producing into nothing.
+ */
+export function useStream(event, options) {
+    const client = useClient();
+    const [state, setState] = useState({ status: 'idle' });
+    const active = useRef(null);
+    const mounted = useRef(true);
+    const onElement = useRef(options?.onElement);
+    onElement.current = options?.onElement;
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            active.current?.cancel();
+        };
+    }, []);
+    const stop = useCallback(() => {
+        active.current?.cancel();
+        active.current = null;
+    }, []);
+    const start = useCallback((payload) => {
+        active.current?.cancel();
+        const result = client.stream(event, payload);
+        active.current = result;
+        /**
+         * `elements` keeps its identity between renders because it is only ever replaced when
+         * something is appended. Rebuilding it per render would break every consumer
+         * memoising on it, which is the same defect class as `getSnapshot` handing back a new
+         * object each call.
+         */
+        let elements = [];
+        setState({ status: 'streaming', elements });
+        void (async () => {
+            try {
+                for await (const element of result) {
+                    if (!mounted.current || active.current !== result)
+                        return;
+                    onElement.current?.(element);
+                    elements = [...elements, element];
+                    setState({ status: 'streaming', elements });
+                }
+                if (mounted.current && active.current === result) {
+                    setState({ status: 'done', elements });
+                }
+            }
+            catch (e) {
+                if (!mounted.current || active.current !== result)
+                    return;
+                const error = asTransportError(e);
+                // A cancellation is this hook's own doing, so it ends the stream rather than
+                // failing it. Anything else is a real error the component should render.
+                setState(error.code === 'WT_ABORTED'
+                    ? { status: 'done', elements }
+                    : { status: 'error', elements, error });
+            }
+        })();
+    }, [client, event]);
+    return useMemo(() => [start, state, stop], [start, state, stop]);
+}
+//# sourceMappingURL=use-stream.js.map

package/dist/use-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-stream.js","sourceRoot":"","sources":["../src/use-stream.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@transport-io/react",
+  "version": "0.1.0",
+  "description": "React bindings for transport-io. Hooks over useSyncExternalStore, correct under StrictMode, SSR and RSC.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build"
+  },
+  "author": "#V0ID <hey@v0id.me>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/transport-io/transport-io.git",
+    "directory": "packages/react"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.11.15",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "react": ">=19.2",
+    "react-dom": ">=19.2",
+    "transport-io": "^0.6.1"
+  },
+  "peerDependencies": {
+    "react": ">=19.2",
+    "react-dom": ">=19.2",
+    "transport-io": "^0.6.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}