@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 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 fully-typed SignalR client. Returns a provider and hooks, typed
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 auto-reconnects every
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
- * Escape hatch to the SignalR context (`getConnection`, `getStatus`,
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 point read.
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 (possibly lazy) hub connected for the component's lifetime,
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 args are inferred from your contract. The subscription survives
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 you set `keepAliveOnUnmount`.
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 never throws, so a cleanup can call
44
- * it. For a call that must land in a cleanup, use `useSignalRTeardown`.
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 flush completes. Resolves `true` if the call is sent.
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. Re-renders only when this hub's status
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 that a
65
- * `connectionKey`, `baseUrl`, or `enabled` change causes.
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 fully-typed SignalR client. Returns a provider and hooks, typed
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 auto-reconnects every
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
- * Escape hatch to the SignalR context (`getConnection`, `getStatus`,
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 point read.
28
+ * for the underlying `HubConnection` or a non-reactive one-time read.
29
29
  */
30
30
  useSignalR: hooks.useSignalR,
31
31
  /**
32
- * Keeps a (possibly lazy) hub connected for the component's lifetime,
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 args are inferred from your contract. The subscription survives
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 you set `keepAliveOnUnmount`.
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 never throws, so a cleanup can call
54
- * it. For a call that must land in a cleanup, use `useSignalRTeardown`.
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 flush completes. Resolves `true` if the call is sent.
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. Re-renders only when this hub's status
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 that a
75
- * `connectionKey`, `baseUrl`, or `enabled` change causes.
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.0.0",
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.0.0"
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",