@dammers/use-signalr-react 1.0.0 → 1.1.0
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 +1 -1
- package/dist/create-signalr-client.d.ts +17 -14
- package/dist/create-signalr-client.js +17 -14
- package/dist/internal/create-hooks.js +3 -3
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ Provider and hooks for typed [SignalR](https://learn.microsoft.com/aspnet/core/s
|
|
|
11
11
|
npm install @dammers/use-signalr-react @microsoft/signalr
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
-
It needs React ^19, `@microsoft/signalr` ^8 || ^9 || ^10, and Node 20.19 or later.
|
|
14
|
+
It needs React ^19, `@microsoft/signalr` ^8 || ^9 || ^10 || ^11, and Node 20.19 or later.
|
|
15
15
|
|
|
16
16
|
## Example
|
|
17
17
|
|
|
@@ -1,32 +1,32 @@
|
|
|
1
1
|
import type { HubDef, HubString, InferContract, SignalRClientConfig } from "@dammers/use-signalr-core";
|
|
2
2
|
/**
|
|
3
|
-
* Creates a
|
|
3
|
+
* Creates a typed SignalR client. Returns a provider and hooks, typed
|
|
4
4
|
* against the contract inferred from `config.hubs`: the keys declare the
|
|
5
5
|
* hubs, and each hub's `event()`/`method()` declarations declare its events
|
|
6
6
|
* and methods.
|
|
7
7
|
*/
|
|
8
8
|
export declare function createSignalRClient<const H extends Record<HubString, HubDef>>(config: SignalRClientConfig<H>): {
|
|
9
9
|
/**
|
|
10
|
-
* Provider that builds, starts, retries, and
|
|
10
|
+
* Provider that builds, starts, retries, and reconnects on its own every
|
|
11
11
|
* configured hub. Pass `baseUrl` and `accessTokenFactory`, and gate them
|
|
12
12
|
* with `enabled`. Mount it once, near the root.
|
|
13
13
|
*/
|
|
14
14
|
SignalRProvider: ({ children, baseUrl, accessTokenFactory, enabled, connectionKey, onStatusChange, onError, }: import("./types.js").SignalRProviderProps<keyof H & `/${string}`>) => import("react").JSX.Element;
|
|
15
15
|
/**
|
|
16
|
-
*
|
|
16
|
+
* Gives access to the SignalR context (`getConnection`, `getStatus`,
|
|
17
17
|
* and `waitForConnection`). Prefer the typed hooks below. Use this only
|
|
18
|
-
* for the underlying `HubConnection` or a non-reactive
|
|
18
|
+
* for the underlying `HubConnection` or a non-reactive one-time read.
|
|
19
19
|
*/
|
|
20
20
|
useSignalR: () => import("@dammers/use-signalr-core").SignalRPublicContext<InferContract<H>>;
|
|
21
21
|
/**
|
|
22
|
-
* Keeps a
|
|
22
|
+
* Keeps a hub, eager or lazy, connected for the component's lifetime,
|
|
23
23
|
* without subscribing to events or status. Acquires on mount, releases on
|
|
24
24
|
* unmount.
|
|
25
25
|
*/
|
|
26
26
|
useHubConsumer: (hub: keyof H & `/${string}`) => void;
|
|
27
27
|
/**
|
|
28
28
|
* Subscribes to a typed server event for the component's lifetime.
|
|
29
|
-
* Handler
|
|
29
|
+
* Handler arguments are inferred from your contract. The subscription survives
|
|
30
30
|
* reconnects and rebuilds.
|
|
31
31
|
*/
|
|
32
32
|
useSignalREffect: <H_1 extends keyof H & `/${string}`, E extends import("@dammers/use-signalr-core").EventName<InferContract<H>, H_1>>(hub: H_1, event: E, handler: (...args: import("@dammers/use-signalr-core").EventArgs<InferContract<H>, H_1, E>) => void) => void;
|
|
@@ -34,35 +34,38 @@ export declare function createSignalRClient<const H extends Record<HubString, Hu
|
|
|
34
34
|
* Typed invoker that waits for the connection and resolves with the
|
|
35
35
|
* method's return value. Fails fast by default. Opt in to retry for
|
|
36
36
|
* idempotent methods only. When the component unmounts, a call that still
|
|
37
|
-
* waits rejects with `AbortError`, unless
|
|
37
|
+
* waits rejects with `AbortError`, unless `keepAliveOnUnmount` is `true`.
|
|
38
|
+
* With `keepAliveOnUnmount`, the call also holds a lazy hub open until it settles.
|
|
38
39
|
*/
|
|
39
40
|
useSignalRInvoke: <H_1 extends keyof H & `/${string}`, M extends import("@dammers/use-signalr-core").MethodName<InferContract<H>, H_1>>(hub: H_1, method: M, options?: import("@dammers/use-signalr-core").InvokeOptions) => (...args: import("@dammers/use-signalr-core").MethodArgs<InferContract<H>, H_1, M>) => Promise<import("@dammers/use-signalr-core").MethodReturn<InferContract<H>, H_1, M>>;
|
|
40
41
|
/**
|
|
41
42
|
* Typed fire-and-forget sender. It does not wait for the connection. It
|
|
42
43
|
* resolves `true` when it sends the call, and `false` when the hub is not
|
|
43
|
-
* connected and it drops the call. It
|
|
44
|
-
*
|
|
44
|
+
* connected and it drops the call. It also resolves `false` when the send
|
|
45
|
+
* fails. It never throws, so a cleanup can call it. For a call that must
|
|
46
|
+
* land in a cleanup, use `useSignalRTeardown`.
|
|
45
47
|
*/
|
|
46
48
|
useSignalRSend: <H_1 extends keyof H & `/${string}`, M extends import("@dammers/use-signalr-core").MethodName<InferContract<H>, H_1>>(hub: H_1, method: M) => (...args: import("@dammers/use-signalr-core").MethodArgs<InferContract<H>, H_1, M>) => Promise<boolean>;
|
|
47
49
|
/**
|
|
48
50
|
* Typed teardown sender for a method invoked in an effect
|
|
49
51
|
* cleanup. Survives the calling component's unmount, queues while the hub
|
|
50
52
|
* is still connecting instead of dropping, and holds a lazy hub open
|
|
51
|
-
* until the
|
|
53
|
+
* until the send ends. Resolves `true` if the call is sent.
|
|
52
54
|
* Resolves `false` if the hub does not connect in time,
|
|
53
|
-
* the session is disabled, the hub failed, or the send fails. Never
|
|
55
|
+
* the session stops while the call waits for the hub, the session is disabled, the hub failed, or the send fails or does not end in time. Never
|
|
54
56
|
* throws.
|
|
57
|
+
* If the session stops while the call is pending on a connected hub, the call is sent before the connection closes.
|
|
55
58
|
*/
|
|
56
59
|
useSignalRTeardown: <H_1 extends keyof H & `/${string}`, M extends import("@dammers/use-signalr-core").MethodName<InferContract<H>, H_1>>(hub: H_1, method: M, options?: import("@dammers/use-signalr-core").TeardownOptions) => (...args: import("@dammers/use-signalr-core").MethodArgs<InferContract<H>, H_1, M>) => Promise<boolean>;
|
|
57
60
|
/**
|
|
58
|
-
* Live connection status of a hub.
|
|
61
|
+
* Live connection status of a hub. Renders again only when this hub's status
|
|
59
62
|
* changes. Also keeps a lazy hub connected while mounted.
|
|
60
63
|
*/
|
|
61
64
|
useHubStatus: <H_1 extends keyof H & `/${string}`>(hub: H_1) => import("@dammers/use-signalr-core").HubConnectionStatus;
|
|
62
65
|
/**
|
|
63
66
|
* Runs a callback after each reconnect, not the first connect, to refetch
|
|
64
|
-
* state that went stale while offline. It also runs after a rebuild
|
|
65
|
-
*
|
|
67
|
+
* state that went stale while offline. It also runs after a rebuild, but
|
|
68
|
+
* only for a hub that was connected before.
|
|
66
69
|
*/
|
|
67
70
|
useOnReconnected: <H_1 extends keyof H & `/${string}`>(hub: H_1, callback: () => void) => void;
|
|
68
71
|
};
|
|
@@ -3,7 +3,7 @@ import { hubKeys, resolveHubConfig } from "@dammers/use-signalr-core";
|
|
|
3
3
|
import { createSignalRProvider } from "./internal/create-provider.js";
|
|
4
4
|
import { createSignalRHooks } from "./internal/create-hooks.js";
|
|
5
5
|
/**
|
|
6
|
-
* Creates a
|
|
6
|
+
* Creates a typed SignalR client. Returns a provider and hooks, typed
|
|
7
7
|
* against the contract inferred from `config.hubs`: the keys declare the
|
|
8
8
|
* hubs, and each hub's `event()`/`method()` declarations declare its events
|
|
9
9
|
* and methods.
|
|
@@ -17,26 +17,26 @@ export function createSignalRClient(config) {
|
|
|
17
17
|
const hooks = createSignalRHooks(Context);
|
|
18
18
|
return {
|
|
19
19
|
/**
|
|
20
|
-
* Provider that builds, starts, retries, and
|
|
20
|
+
* Provider that builds, starts, retries, and reconnects on its own every
|
|
21
21
|
* configured hub. Pass `baseUrl` and `accessTokenFactory`, and gate them
|
|
22
22
|
* with `enabled`. Mount it once, near the root.
|
|
23
23
|
*/
|
|
24
24
|
SignalRProvider,
|
|
25
25
|
/**
|
|
26
|
-
*
|
|
26
|
+
* Gives access to the SignalR context (`getConnection`, `getStatus`,
|
|
27
27
|
* and `waitForConnection`). Prefer the typed hooks below. Use this only
|
|
28
|
-
* for the underlying `HubConnection` or a non-reactive
|
|
28
|
+
* for the underlying `HubConnection` or a non-reactive one-time read.
|
|
29
29
|
*/
|
|
30
30
|
useSignalR: hooks.useSignalR,
|
|
31
31
|
/**
|
|
32
|
-
* Keeps a
|
|
32
|
+
* Keeps a hub, eager or lazy, connected for the component's lifetime,
|
|
33
33
|
* without subscribing to events or status. Acquires on mount, releases on
|
|
34
34
|
* unmount.
|
|
35
35
|
*/
|
|
36
36
|
useHubConsumer: hooks.useHubConsumer,
|
|
37
37
|
/**
|
|
38
38
|
* Subscribes to a typed server event for the component's lifetime.
|
|
39
|
-
* Handler
|
|
39
|
+
* Handler arguments are inferred from your contract. The subscription survives
|
|
40
40
|
* reconnects and rebuilds.
|
|
41
41
|
*/
|
|
42
42
|
useSignalREffect: hooks.useSignalREffect,
|
|
@@ -44,35 +44,38 @@ export function createSignalRClient(config) {
|
|
|
44
44
|
* Typed invoker that waits for the connection and resolves with the
|
|
45
45
|
* method's return value. Fails fast by default. Opt in to retry for
|
|
46
46
|
* idempotent methods only. When the component unmounts, a call that still
|
|
47
|
-
* waits rejects with `AbortError`, unless
|
|
47
|
+
* waits rejects with `AbortError`, unless `keepAliveOnUnmount` is `true`.
|
|
48
|
+
* With `keepAliveOnUnmount`, the call also holds a lazy hub open until it settles.
|
|
48
49
|
*/
|
|
49
50
|
useSignalRInvoke: hooks.useSignalRInvoke,
|
|
50
51
|
/**
|
|
51
52
|
* Typed fire-and-forget sender. It does not wait for the connection. It
|
|
52
53
|
* resolves `true` when it sends the call, and `false` when the hub is not
|
|
53
|
-
* connected and it drops the call. It
|
|
54
|
-
*
|
|
54
|
+
* connected and it drops the call. It also resolves `false` when the send
|
|
55
|
+
* fails. It never throws, so a cleanup can call it. For a call that must
|
|
56
|
+
* land in a cleanup, use `useSignalRTeardown`.
|
|
55
57
|
*/
|
|
56
58
|
useSignalRSend: hooks.useSignalRSend,
|
|
57
59
|
/**
|
|
58
60
|
* Typed teardown sender for a method invoked in an effect
|
|
59
61
|
* cleanup. Survives the calling component's unmount, queues while the hub
|
|
60
62
|
* is still connecting instead of dropping, and holds a lazy hub open
|
|
61
|
-
* until the
|
|
63
|
+
* until the send ends. Resolves `true` if the call is sent.
|
|
62
64
|
* Resolves `false` if the hub does not connect in time,
|
|
63
|
-
* the session is disabled, the hub failed, or the send fails. Never
|
|
65
|
+
* the session stops while the call waits for the hub, the session is disabled, the hub failed, or the send fails or does not end in time. Never
|
|
64
66
|
* throws.
|
|
67
|
+
* If the session stops while the call is pending on a connected hub, the call is sent before the connection closes.
|
|
65
68
|
*/
|
|
66
69
|
useSignalRTeardown: hooks.useSignalRTeardown,
|
|
67
70
|
/**
|
|
68
|
-
* Live connection status of a hub.
|
|
71
|
+
* Live connection status of a hub. Renders again only when this hub's status
|
|
69
72
|
* changes. Also keeps a lazy hub connected while mounted.
|
|
70
73
|
*/
|
|
71
74
|
useHubStatus: hooks.useHubStatus,
|
|
72
75
|
/**
|
|
73
76
|
* Runs a callback after each reconnect, not the first connect, to refetch
|
|
74
|
-
* state that went stale while offline. It also runs after a rebuild
|
|
75
|
-
*
|
|
77
|
+
* state that went stale while offline. It also runs after a rebuild, but
|
|
78
|
+
* only for a hub that was connected before.
|
|
76
79
|
*/
|
|
77
80
|
useOnReconnected: hooks.useOnReconnected,
|
|
78
81
|
};
|
|
@@ -63,15 +63,15 @@ export function createSignalRHooks(ReactContext) {
|
|
|
63
63
|
return useMemo(() => createSender({ getConnection, hub, method }), [getConnection, hub, method]);
|
|
64
64
|
}
|
|
65
65
|
function useSignalRTeardown(hub, method, options) {
|
|
66
|
-
const { acquire, release, waitForConnection } = useInternalContext();
|
|
66
|
+
const { acquire, release, waitForConnection, beginSend } = useInternalContext();
|
|
67
67
|
useHubConsumer(hub);
|
|
68
68
|
const optsRef = useLatest(options);
|
|
69
69
|
return useMemo(() => createTeardownSender({
|
|
70
|
-
target: { acquire, release, waitForConnection },
|
|
70
|
+
target: { acquire, release, waitForConnection, beginSend },
|
|
71
71
|
hub,
|
|
72
72
|
method,
|
|
73
73
|
getOptions: () => optsRef.current,
|
|
74
|
-
}), [acquire, release, waitForConnection, hub, method, optsRef]);
|
|
74
|
+
}), [acquire, release, waitForConnection, beginSend, hub, method, optsRef]);
|
|
75
75
|
}
|
|
76
76
|
return {
|
|
77
77
|
useSignalR,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dammers/use-signalr-react",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Fully-typed multi-hub SignalR provider + hooks for React: auto-reconnect, invoke retry, lazy hubs, live status.",
|
|
5
5
|
"author": "Dammers",
|
|
6
6
|
"license": "MIT",
|
|
@@ -47,14 +47,14 @@
|
|
|
47
47
|
"test": "vitest run"
|
|
48
48
|
},
|
|
49
49
|
"dependencies": {
|
|
50
|
-
"@dammers/use-signalr-core": "1.
|
|
50
|
+
"@dammers/use-signalr-core": "1.1.0"
|
|
51
51
|
},
|
|
52
52
|
"peerDependencies": {
|
|
53
|
-
"@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0",
|
|
53
|
+
"@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
|
|
54
54
|
"react": "^19.0.0"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
|
-
"@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0",
|
|
57
|
+
"@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
|
|
58
58
|
"@testing-library/react": "^16.1.0",
|
|
59
59
|
"@types/react": "^19.0.0",
|
|
60
60
|
"react": "^19.0.0",
|