@dammers/use-signalr-vue 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 @@ Plugin and composables for typed [SignalR](https://learn.microsoft.com/aspnet/co
11
11
  npm install @dammers/use-signalr-vue @microsoft/signalr
12
12
  ```
13
13
 
14
- It needs Vue ^3.3, `@microsoft/signalr` ^8 || ^9 || ^10, and Node 20.19 or later.
14
+ It needs Vue ^3.3, `@microsoft/signalr` ^8 || ^9 || ^10 || ^11, and Node 20.19 or later.
15
15
 
16
16
  ## Example
17
17
 
@@ -4,59 +4,66 @@ export declare function createSignalRClient<const H extends Record<HubString, Hu
4
4
  /**
5
5
  * Gives the SignalR context (`getConnection`, `getStatus`, and
6
6
  * `waitForConnection`). Use it for the underlying `HubConnection` or a
7
- * point read. Prefer the typed composables. Call it in `setup()` or inside
7
+ * one-time read. Prefer the typed composables. Call it in `setup()` or inside
8
8
  * `app.runWithContext()`.
9
9
  */
10
10
  useSignalR: () => import("@dammers/use-signalr-core").SignalRPublicContext<InferContract<H>>;
11
11
  /**
12
- * Keeps a (possibly lazy) hub connected while the scope is alive, without
13
- * subscribing to events or status. Call it in `setup()` or an effect scope.
12
+ * Keeps a hub, eager or lazy, connected while the scope is alive, without
13
+ * subscribing to events or status. Call it in `setup()`, or inside an
14
+ * effect scope that runs in `app.runWithContext()`.
14
15
  */
15
16
  useHubConsumer: <H_1 extends keyof H & `/${string}`>(hub: H_1) => void;
16
17
  /**
17
18
  * Gives the live connection status of a hub as a read-only `Ref`. It
18
19
  * updates only when this hub's status changes. It also keeps a lazy hub
19
20
  * connected while the scope is alive. A component that hydrates shows
20
- * `"idle"` until it mounts. Call it in `setup()` or an effect scope.
21
+ * `"idle"` until it mounts. Call it in `setup()`, or inside an effect scope
22
+ * that runs in `app.runWithContext()`.
21
23
  */
22
24
  useHubStatus: <H_1 extends keyof H & `/${string}`>(hub: H_1) => import("./status-store.js").HubStatusRef;
23
25
  /**
24
26
  * Subscribes to a typed server event while the scope is alive. Handler
25
- * args come from your contract. The subscription survives reconnects and
26
- * rebuilds. Call it in `setup()` or an effect scope.
27
+ * arguments come from your contract. The subscription survives reconnects
28
+ * and rebuilds. Call it in `setup()`, or inside an effect scope that runs
29
+ * in `app.runWithContext()`.
27
30
  */
28
31
  useSignalREvent: <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;
29
32
  /**
30
33
  * Gives a typed invoker that waits for the connection and resolves with
31
34
  * the method's return value. It fails fast by default. Opt in to retry for
32
35
  * idempotent methods only. When the scope ends, a waiting call rejects
33
- * with `AbortError`, unless you set `keepAliveOnUnmount`. Call it in
34
- * `setup()` or an effect scope.
36
+ * with `AbortError`, unless `keepAliveOnUnmount` is `true`. With it, the call
37
+ * also holds a lazy hub open until it settles. Call it in `setup()`, or
38
+ * inside an effect scope that runs in `app.runWithContext()`.
35
39
  */
36
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>>;
37
41
  /**
38
42
  * Gives a typed fire-and-forget sender. It does not wait for the
39
- * connection. It resolves `true` when it sends the call. It resolves
40
- * `false` when the hub is not connected and it drops the call, or when
41
- * the send fails. It never throws, so a cleanup can call it. For a call
42
- * that must land in a cleanup, use `useSignalRTeardown`. Call it in
43
- * `setup()` or an effect scope.
43
+ * connection. It resolves `true` when it sends the call, and `false` when
44
+ * the hub is not connected and it drops the call. It also resolves `false`
45
+ * when the send fails. It never throws, so a cleanup can call it. For a
46
+ * call that must land in a cleanup, use `useSignalRTeardown`. Call it in
47
+ * `setup()`, or inside an effect scope that runs in
48
+ * `app.runWithContext()`.
44
49
  */
45
50
  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>;
46
51
  /**
47
52
  * Gives a typed teardown sender for a method that a cleanup invokes. It
48
53
  * survives the end of the calling scope, queues while the hub connects,
49
- * and holds a lazy hub open until the flush completes. It resolves `true`
50
- * when it dispatches the call. It resolves `false` when the hub does not
51
- * connect in time, the session is disabled, the hub failed, or the send
52
- * fails. It never throws. Call it in `setup()` or an effect scope.
54
+ * and holds a lazy hub open until the send ends. It resolves `true`
55
+ * if the call is sent. It resolves `false` if the hub does not connect in
56
+ * time, 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. It
57
+ * never throws. Call it in `setup()`, or inside an effect scope that runs
58
+ * in `app.runWithContext()`.
59
+ * If the session stops while the call is pending on a connected hub, the call is sent before the connection closes.
53
60
  */
54
61
  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>;
55
62
  /**
56
63
  * Runs a callback after each reconnect, not the first connect, to refetch
57
- * state that went stale while offline. It also runs after a rebuild from
58
- * a `baseUrl`, `enabled`, or `connectionKey` change. Call it in `setup()`
59
- * or an effect scope.
64
+ * state that went stale while offline. It also runs after a rebuild, but
65
+ * only for a hub that was connected before. Call it in `setup()`, or inside
66
+ * an effect scope that runs in `app.runWithContext()`.
60
67
  */
61
68
  useOnReconnected: <H_1 extends keyof H & `/${string}`>(hub: H_1, callback: () => void) => void;
62
69
  };
@@ -12,59 +12,66 @@ export function createSignalRClient(config) {
12
12
  /**
13
13
  * Gives the SignalR context (`getConnection`, `getStatus`, and
14
14
  * `waitForConnection`). Use it for the underlying `HubConnection` or a
15
- * point read. Prefer the typed composables. Call it in `setup()` or inside
15
+ * one-time read. Prefer the typed composables. Call it in `setup()` or inside
16
16
  * `app.runWithContext()`.
17
17
  */
18
18
  useSignalR: composables.useSignalR,
19
19
  /**
20
- * Keeps a (possibly lazy) hub connected while the scope is alive, without
21
- * subscribing to events or status. Call it in `setup()` or an effect scope.
20
+ * Keeps a hub, eager or lazy, connected while the scope is alive, without
21
+ * subscribing to events or status. Call it in `setup()`, or inside an
22
+ * effect scope that runs in `app.runWithContext()`.
22
23
  */
23
24
  useHubConsumer: composables.useHubConsumer,
24
25
  /**
25
26
  * Gives the live connection status of a hub as a read-only `Ref`. It
26
27
  * updates only when this hub's status changes. It also keeps a lazy hub
27
28
  * connected while the scope is alive. A component that hydrates shows
28
- * `"idle"` until it mounts. Call it in `setup()` or an effect scope.
29
+ * `"idle"` until it mounts. Call it in `setup()`, or inside an effect scope
30
+ * that runs in `app.runWithContext()`.
29
31
  */
30
32
  useHubStatus: composables.useHubStatus,
31
33
  /**
32
34
  * Subscribes to a typed server event while the scope is alive. Handler
33
- * args come from your contract. The subscription survives reconnects and
34
- * rebuilds. Call it in `setup()` or an effect scope.
35
+ * arguments come from your contract. The subscription survives reconnects
36
+ * and rebuilds. Call it in `setup()`, or inside an effect scope that runs
37
+ * in `app.runWithContext()`.
35
38
  */
36
39
  useSignalREvent: composables.useSignalREvent,
37
40
  /**
38
41
  * Gives a typed invoker that waits for the connection and resolves with
39
42
  * the method's return value. It fails fast by default. Opt in to retry for
40
43
  * idempotent methods only. When the scope ends, a waiting call rejects
41
- * with `AbortError`, unless you set `keepAliveOnUnmount`. Call it in
42
- * `setup()` or an effect scope.
44
+ * with `AbortError`, unless `keepAliveOnUnmount` is `true`. With it, the call
45
+ * also holds a lazy hub open until it settles. Call it in `setup()`, or
46
+ * inside an effect scope that runs in `app.runWithContext()`.
43
47
  */
44
48
  useSignalRInvoke: composables.useSignalRInvoke,
45
49
  /**
46
50
  * Gives a typed fire-and-forget sender. It does not wait for the
47
- * connection. It resolves `true` when it sends the call. It resolves
48
- * `false` when the hub is not connected and it drops the call, or when
49
- * the send fails. It never throws, so a cleanup can call it. For a call
50
- * that must land in a cleanup, use `useSignalRTeardown`. Call it in
51
- * `setup()` or an effect scope.
51
+ * connection. It resolves `true` when it sends the call, and `false` when
52
+ * the hub is not connected and it drops the call. It also resolves `false`
53
+ * when the send fails. It never throws, so a cleanup can call it. For a
54
+ * call that must land in a cleanup, use `useSignalRTeardown`. Call it in
55
+ * `setup()`, or inside an effect scope that runs in
56
+ * `app.runWithContext()`.
52
57
  */
53
58
  useSignalRSend: composables.useSignalRSend,
54
59
  /**
55
60
  * Gives a typed teardown sender for a method that a cleanup invokes. It
56
61
  * survives the end of the calling scope, queues while the hub connects,
57
- * and holds a lazy hub open until the flush completes. It resolves `true`
58
- * when it dispatches the call. It resolves `false` when the hub does not
59
- * connect in time, the session is disabled, the hub failed, or the send
60
- * fails. It never throws. Call it in `setup()` or an effect scope.
62
+ * and holds a lazy hub open until the send ends. It resolves `true`
63
+ * if the call is sent. It resolves `false` if the hub does not connect in
64
+ * time, 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. It
65
+ * never throws. Call it in `setup()`, or inside an effect scope that runs
66
+ * in `app.runWithContext()`.
67
+ * If the session stops while the call is pending on a connected hub, the call is sent before the connection closes.
61
68
  */
62
69
  useSignalRTeardown: composables.useSignalRTeardown,
63
70
  /**
64
71
  * Runs a callback after each reconnect, not the first connect, to refetch
65
- * state that went stale while offline. It also runs after a rebuild from
66
- * a `baseUrl`, `enabled`, or `connectionKey` change. Call it in `setup()`
67
- * or an effect scope.
72
+ * state that went stale while offline. It also runs after a rebuild, but
73
+ * only for a hub that was connected before. Call it in `setup()`, or inside
74
+ * an effect scope that runs in `app.runWithContext()`.
68
75
  */
69
76
  useOnReconnected: composables.useOnReconnected,
70
77
  });
@@ -20,7 +20,8 @@ export function createPlugin(key, hubs, resolve) {
20
20
  return;
21
21
  disposed = true;
22
22
  scope?.stop();
23
- session.stop();
23
+ // Vue runs this before the `unmounted` hooks, so a teardown call in a hook registers first.
24
+ queueMicrotask(() => session.stop());
24
25
  };
25
26
  const scope = typeof window === "undefined" ? undefined : effectScope(true);
26
27
  const startWatching = () => scope?.run(() => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dammers/use-signalr-vue",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Fully-typed multi-hub SignalR plugin + composables for Vue.",
5
5
  "author": "Dammers",
6
6
  "license": "MIT",
@@ -49,14 +49,14 @@
49
49
  "test": "vitest run"
50
50
  },
51
51
  "dependencies": {
52
- "@dammers/use-signalr-core": "1.0.0"
52
+ "@dammers/use-signalr-core": "1.1.0"
53
53
  },
54
54
  "peerDependencies": {
55
- "@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0",
55
+ "@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
56
56
  "vue": "^3.3.0"
57
57
  },
58
58
  "devDependencies": {
59
- "@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0",
59
+ "@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
60
60
  "@vue/test-utils": "^2.4.11",
61
61
  "vue": "^3.3.0"
62
62
  }