@dammers/use-signalr-vue 0.4.0 → 1.0.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/LICENSE +21 -21
- package/README.md +59 -284
- package/dist/create-signalr-client.d.ts +53 -4
- package/dist/create-signalr-client.js +62 -2
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1 -1
- package/dist/internal/create-composables.d.ts +4 -3
- package/dist/internal/create-composables.js +50 -33
- package/dist/internal/create-plugin.d.ts +1 -1
- package/dist/internal/create-plugin.js +26 -13
- package/dist/status-store.d.ts +4 -1
- package/dist/status-store.js +1 -1
- package/dist/types.d.ts +8 -4
- package/package.json +63 -61
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 DammersCode
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 DammersCode
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,284 +1,59 @@
|
|
|
1
|
-
# @dammers/use-signalr-vue
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/@dammers/use-signalr-vue)
|
|
6
|
-
[ also uses a Vue plugin and composable.
|
|
238
|
-
|
|
239
|
-
That package requires users to build and supply one `HubConnection`. It types commands and events through module augmentation.
|
|
240
|
-
|
|
241
|
-
This adapter infers its contract from `config.hubs`. The shared core also manages these behaviors:
|
|
242
|
-
|
|
243
|
-
- multiple hubs and shared connections,
|
|
244
|
-
- one status ref per hub,
|
|
245
|
-
- lazy reference counting and grace periods,
|
|
246
|
-
- initial retry and automatic reconnect,
|
|
247
|
-
- invoke retry, send, and teardown semantics,
|
|
248
|
-
- token rotation without connection recreation.
|
|
249
|
-
|
|
250
|
-
## API
|
|
251
|
-
|
|
252
|
-
| Export | Description |
|
|
253
|
-
| --- | --- |
|
|
254
|
-
| `createSignalRClient(config)` | Returns the configured plugin and composables, typed against the inferred contract. |
|
|
255
|
-
| `app.use(signalR, options)` | Builds, starts, retries, and reconnects configured hubs for one Vue application. |
|
|
256
|
-
| `useSignalR()` | Returns the raw context, including connection access and point status reads. |
|
|
257
|
-
| `useHubStatus(hub)` | Returns a readonly status ref for one hub. It also keeps the hub alive. |
|
|
258
|
-
| `useSignalREvent(hub, event, handler)` | Subscribes to a typed server event for the active effect scope. |
|
|
259
|
-
| `useSignalRInvoke(hub, method, options?)` | Waits for the connection and returns the typed method result. Retry is optional. |
|
|
260
|
-
| `useSignalRSend(hub, method)` | Sends without waiting. It returns `false` when the hub is not connected. |
|
|
261
|
-
| `useSignalRTeardown(hub, method, options?)` | Survives disposal, waits while connecting, and holds a lazy hub until dispatch. |
|
|
262
|
-
| `useOnReconnected(hub, callback)` | Runs a callback after each reconnect, but not after the first connection. |
|
|
263
|
-
| `useHubConsumer(hub)` | Keeps a lazy hub connected for the active effect scope without another subscription. |
|
|
264
|
-
| `event<Args>()` | Declares the handler argument tuple for a server event. |
|
|
265
|
-
| `method<Args, Return>()` | Declares the argument tuple and return type for a server method. |
|
|
266
|
-
| `InvokeError` | Wraps the last invoke failure after configured retries are exhausted. |
|
|
267
|
-
|
|
268
|
-
### Plugin options
|
|
269
|
-
|
|
270
|
-
Required: `baseUrl`, `accessTokenFactory`.
|
|
271
|
-
|
|
272
|
-
Optional: `enabled` (default `true`), `connectionKey`, `onStatusChange`, `onError`.
|
|
273
|
-
|
|
274
|
-
Connection behavior belongs in the configuration passed to `createSignalRClient`.
|
|
275
|
-
|
|
276
|
-
## More
|
|
277
|
-
|
|
278
|
-
The [root README](https://github.com/DammersCode/use-signalr#readme) documents per-hub configuration and call semantics.
|
|
279
|
-
|
|
280
|
-
[CONTRIBUTING.md](https://github.com/DammersCode/use-signalr/blob/main/CONTRIBUTING.md) documents the development workflow.
|
|
281
|
-
|
|
282
|
-
## License
|
|
283
|
-
|
|
284
|
-
MIT © [DammersCode](https://github.com/DammersCode)
|
|
1
|
+
# @dammers/use-signalr-vue
|
|
2
|
+
|
|
3
|
+
Plugin and composables for typed [SignalR](https://learn.microsoft.com/aspnet/core/signalr) in Vue. Part of [use-signalr](https://use-signalr.vercel.app).
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@dammers/use-signalr-vue)
|
|
6
|
+
[](https://github.com/DammersCode/use-signalr/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
npm install @dammers/use-signalr-vue @microsoft/signalr
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
It needs Vue ^3.3, `@microsoft/signalr` ^8 || ^9 || ^10, and Node 20.19 or later.
|
|
15
|
+
|
|
16
|
+
## Example
|
|
17
|
+
|
|
18
|
+
This file declares a hub, connects it, and reads a typed method result:
|
|
19
|
+
|
|
20
|
+
<!-- hero:vue:start -->
|
|
21
|
+
```ts
|
|
22
|
+
import { createApp, ref } from "vue";
|
|
23
|
+
import { createSignalRClient, method } from "@dammers/use-signalr-vue";
|
|
24
|
+
import App from "./App.vue";
|
|
25
|
+
|
|
26
|
+
export const signalR = createSignalRClient({
|
|
27
|
+
hubs: {
|
|
28
|
+
"/hubs/rooms": {
|
|
29
|
+
methods: { GetHistory: method<[roomId: string], { text: string }[]>() },
|
|
30
|
+
},
|
|
31
|
+
},
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
createApp(App)
|
|
35
|
+
.use(signalR, { baseUrl: "https://api.example.com", accessTokenFactory: () => "token" })
|
|
36
|
+
.mount("#app");
|
|
37
|
+
|
|
38
|
+
// Call this composable in a component's setup().
|
|
39
|
+
export function useHistoryCount(roomId: string) {
|
|
40
|
+
const getHistory = signalR.useSignalRInvoke("/hubs/rooms", "GetHistory");
|
|
41
|
+
const count = ref(0);
|
|
42
|
+
const load = () => getHistory(roomId).then((m) => (count.value = m.length)).catch(console.error);
|
|
43
|
+
return { count, load };
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
<!-- hero:vue:end -->
|
|
47
|
+
|
|
48
|
+
## Documentation
|
|
49
|
+
|
|
50
|
+
- [Quick start](https://use-signalr.vercel.app/docs/vue/quick-start)
|
|
51
|
+
- [Provider setup](https://use-signalr.vercel.app/docs/vue/concepts/provider)
|
|
52
|
+
- [Events](https://use-signalr.vercel.app/docs/vue/concepts/events) and [calls](https://use-signalr.vercel.app/docs/vue/concepts/calls)
|
|
53
|
+
- [Connection status](https://use-signalr.vercel.app/docs/vue/concepts/connection-status) and [recovery](https://use-signalr.vercel.app/docs/vue/concepts/recovery)
|
|
54
|
+
- [API reference](https://use-signalr.vercel.app/docs/vue/reference/api)
|
|
55
|
+
- [Troubleshooting](https://use-signalr.vercel.app/docs/vue/reference/troubleshooting)
|
|
56
|
+
|
|
57
|
+
## License
|
|
58
|
+
|
|
59
|
+
[MIT](https://github.com/DammersCode/use-signalr/blob/main/LICENSE) © [DammersCode](https://github.com/DammersCode)
|
|
@@ -1,13 +1,62 @@
|
|
|
1
1
|
import type { HubDef, HubString, InferContract, SignalRClientConfig } from "@dammers/use-signalr-core";
|
|
2
|
-
import type { SignalRContextValue } from "./types.js";
|
|
3
2
|
/** Creates a typed Vue plugin and the composables bound to its app context. */
|
|
4
|
-
export declare function createSignalRClient<const H extends Record<HubString, HubDef>>(config: SignalRClientConfig<H>): import("vue").Plugin<[import("./types.js").SignalROptions<
|
|
5
|
-
|
|
3
|
+
export declare function createSignalRClient<const H extends Record<HubString, HubDef>>(config: SignalRClientConfig<H>): import("vue").Plugin<[import("./types.js").SignalROptions<keyof H & `/${string}`>]> & {
|
|
4
|
+
/**
|
|
5
|
+
* Gives the SignalR context (`getConnection`, `getStatus`, and
|
|
6
|
+
* `waitForConnection`). Use it for the underlying `HubConnection` or a
|
|
7
|
+
* point read. Prefer the typed composables. Call it in `setup()` or inside
|
|
8
|
+
* `app.runWithContext()`.
|
|
9
|
+
*/
|
|
10
|
+
useSignalR: () => import("@dammers/use-signalr-core").SignalRPublicContext<InferContract<H>>;
|
|
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.
|
|
14
|
+
*/
|
|
6
15
|
useHubConsumer: <H_1 extends keyof H & `/${string}`>(hub: H_1) => void;
|
|
7
|
-
|
|
16
|
+
/**
|
|
17
|
+
* Gives the live connection status of a hub as a read-only `Ref`. It
|
|
18
|
+
* updates only when this hub's status changes. It also keeps a lazy hub
|
|
19
|
+
* 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
|
+
*/
|
|
22
|
+
useHubStatus: <H_1 extends keyof H & `/${string}`>(hub: H_1) => import("./status-store.js").HubStatusRef;
|
|
23
|
+
/**
|
|
24
|
+
* 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
|
+
*/
|
|
8
28
|
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
|
+
/**
|
|
30
|
+
* Gives a typed invoker that waits for the connection and resolves with
|
|
31
|
+
* the method's return value. It fails fast by default. Opt in to retry for
|
|
32
|
+
* 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.
|
|
35
|
+
*/
|
|
9
36
|
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
|
+
/**
|
|
38
|
+
* 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.
|
|
44
|
+
*/
|
|
10
45
|
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
|
+
/**
|
|
47
|
+
* Gives a typed teardown sender for a method that a cleanup invokes. It
|
|
48
|
+
* 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.
|
|
53
|
+
*/
|
|
11
54
|
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
|
+
/**
|
|
56
|
+
* 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.
|
|
60
|
+
*/
|
|
12
61
|
useOnReconnected: <H_1 extends keyof H & `/${string}`>(hub: H_1, callback: () => void) => void;
|
|
13
62
|
};
|
|
@@ -4,8 +4,68 @@ import { createPlugin } from "./internal/create-plugin.js";
|
|
|
4
4
|
/** Creates a typed Vue plugin and the composables bound to its app context. */
|
|
5
5
|
export function createSignalRClient(config) {
|
|
6
6
|
const hubs = hubKeys(config);
|
|
7
|
-
const resolved = new Map(hubs.map((hub) => [hub, resolveHubConfig(config,
|
|
7
|
+
const resolved = new Map(hubs.map((hub) => [hub, resolveHubConfig(config, hub)]));
|
|
8
8
|
const key = Symbol("use-signalr");
|
|
9
9
|
const plugin = createPlugin(key, hubs, (hub) => resolved.get(hub));
|
|
10
|
-
|
|
10
|
+
const composables = createComposables(key);
|
|
11
|
+
return Object.assign(plugin, {
|
|
12
|
+
/**
|
|
13
|
+
* Gives the SignalR context (`getConnection`, `getStatus`, and
|
|
14
|
+
* `waitForConnection`). Use it for the underlying `HubConnection` or a
|
|
15
|
+
* point read. Prefer the typed composables. Call it in `setup()` or inside
|
|
16
|
+
* `app.runWithContext()`.
|
|
17
|
+
*/
|
|
18
|
+
useSignalR: composables.useSignalR,
|
|
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.
|
|
22
|
+
*/
|
|
23
|
+
useHubConsumer: composables.useHubConsumer,
|
|
24
|
+
/**
|
|
25
|
+
* Gives the live connection status of a hub as a read-only `Ref`. It
|
|
26
|
+
* updates only when this hub's status changes. It also keeps a lazy hub
|
|
27
|
+
* 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
|
+
*/
|
|
30
|
+
useHubStatus: composables.useHubStatus,
|
|
31
|
+
/**
|
|
32
|
+
* 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
|
+
*/
|
|
36
|
+
useSignalREvent: composables.useSignalREvent,
|
|
37
|
+
/**
|
|
38
|
+
* Gives a typed invoker that waits for the connection and resolves with
|
|
39
|
+
* the method's return value. It fails fast by default. Opt in to retry for
|
|
40
|
+
* 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.
|
|
43
|
+
*/
|
|
44
|
+
useSignalRInvoke: composables.useSignalRInvoke,
|
|
45
|
+
/**
|
|
46
|
+
* 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.
|
|
52
|
+
*/
|
|
53
|
+
useSignalRSend: composables.useSignalRSend,
|
|
54
|
+
/**
|
|
55
|
+
* Gives a typed teardown sender for a method that a cleanup invokes. It
|
|
56
|
+
* 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.
|
|
61
|
+
*/
|
|
62
|
+
useSignalRTeardown: composables.useSignalRTeardown,
|
|
63
|
+
/**
|
|
64
|
+
* 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.
|
|
68
|
+
*/
|
|
69
|
+
useOnReconnected: composables.useOnReconnected,
|
|
70
|
+
});
|
|
11
71
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export { createSignalRClient } from "./create-signalr-client.js";
|
|
2
|
-
export {
|
|
3
|
-
export type {
|
|
4
|
-
export type { MaybeRefOrGetter, SignalROptions,
|
|
5
|
-
export type { HubString, HubContract, SignalRContract, SignalRClientConfig, PerHubConfig, HubDef, EventDef, MethodDef, InferContract,
|
|
2
|
+
export { event, method } from "@dammers/use-signalr-core";
|
|
3
|
+
export type { HubStatusRef } from "./status-store.js";
|
|
4
|
+
export type { MaybeRefOrGetter, SignalROptions, } from "./types.js";
|
|
5
|
+
export type { HubString, HubContract, SignalRContract, SignalRClientConfig, PerHubConfig, HubProtocolConfig, ConfigureBuilder, BuilderContext, HttpOptions, HubDef, EventDef, MethodDef, InferContract, ReconnectConfig, InvokeOptions, TeardownOptions, HubConnectionStatus, SignalRErrorInfo, SignalRPublicContext, EventName, MethodName, EventArgs, MethodArgs, MethodReturn, } from "@dammers/use-signalr-core";
|
package/dist/index.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
export { createSignalRClient } from "./create-signalr-client.js";
|
|
2
|
-
export {
|
|
2
|
+
export { event, method } from "@dammers/use-signalr-core";
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
import type { InjectionKey } from "vue";
|
|
2
|
-
import type { EventArgs, EventName, InvokeOptions, MethodName, SignalRContract, TeardownOptions } from "@dammers/use-signalr-core";
|
|
2
|
+
import type { EventArgs, EventName, InvokeOptions, MethodName, SignalRContract, SignalRPublicContext, TeardownOptions } from "@dammers/use-signalr-core";
|
|
3
|
+
import type { HubStatusRef } from "../status-store.js";
|
|
3
4
|
import type { SignalRContextValue } from "../types.js";
|
|
4
5
|
export declare function createComposables<T extends SignalRContract>(key: InjectionKey<SignalRContextValue<T>>): {
|
|
5
|
-
useSignalR: () =>
|
|
6
|
+
useSignalR: () => SignalRPublicContext<T>;
|
|
6
7
|
useHubConsumer: <H extends keyof T & `/${string}`>(hub: H) => void;
|
|
7
|
-
useHubStatus: <H extends keyof T & `/${string}`>(hub: H) =>
|
|
8
|
+
useHubStatus: <H extends keyof T & `/${string}`>(hub: H) => HubStatusRef;
|
|
8
9
|
useSignalREvent: <H extends keyof T & `/${string}`, E extends EventName<T, H>>(hub: H, event: E, handler: (...args: EventArgs<T, H, E>) => void) => void;
|
|
9
10
|
useSignalRInvoke: <H extends keyof T & `/${string}`, M extends MethodName<T, H>>(hub: H, method: M, options?: InvokeOptions) => (...args: import("@dammers/use-signalr-core").MethodArgs<T, H, M>) => Promise<import("@dammers/use-signalr-core").MethodReturn<T, H, M>>;
|
|
10
11
|
useSignalRSend: <H extends keyof T & `/${string}`, M extends MethodName<T, H>>(hub: H, method: M) => (...args: import("@dammers/use-signalr-core").MethodArgs<T, H, M>) => Promise<boolean>;
|
|
@@ -1,62 +1,79 @@
|
|
|
1
|
-
import { inject, onScopeDispose,
|
|
1
|
+
import { computed, getCurrentInstance, getCurrentScope, hasInjectionContext, inject, onMounted, onScopeDispose, shallowRef, } from "vue";
|
|
2
2
|
import { createAbortScope, createInvoker, createSender, createTeardownSender, } from "@dammers/use-signalr-core";
|
|
3
3
|
export function createComposables(key) {
|
|
4
|
-
function
|
|
4
|
+
function useInternalContext(name) {
|
|
5
|
+
if (!hasInjectionContext())
|
|
6
|
+
throw new Error(`${name} must be called inside setup() or app.runWithContext()`);
|
|
5
7
|
const context = inject(key, null);
|
|
6
8
|
if (!context)
|
|
7
9
|
throw new Error("useSignalR must be used after app.use(signalR, options)");
|
|
8
10
|
return context;
|
|
9
11
|
}
|
|
10
|
-
function
|
|
11
|
-
|
|
12
|
+
function useScopedContext(name) {
|
|
13
|
+
if (!getCurrentScope())
|
|
14
|
+
throw new Error(`${name} must be called inside setup() or an effectScope`);
|
|
15
|
+
return useInternalContext(name);
|
|
16
|
+
}
|
|
17
|
+
function useSignalR() {
|
|
18
|
+
return useInternalContext("useSignalR").publicContext;
|
|
19
|
+
}
|
|
20
|
+
function consume(context, hub) {
|
|
12
21
|
context.acquire(hub);
|
|
13
22
|
onScopeDispose(() => context.release(hub));
|
|
14
23
|
}
|
|
24
|
+
function useHubConsumer(hub) {
|
|
25
|
+
consume(useScopedContext("useHubConsumer"), hub);
|
|
26
|
+
}
|
|
15
27
|
function useHubStatus(hub) {
|
|
16
|
-
const context =
|
|
17
|
-
|
|
18
|
-
|
|
28
|
+
const context = useScopedContext("useHubStatus");
|
|
29
|
+
consume(context, hub);
|
|
30
|
+
const status = context.statusStore.ref(hub);
|
|
31
|
+
if (!getCurrentInstance()?.vnode.el)
|
|
32
|
+
return status;
|
|
33
|
+
// Async components hydrate after the session started; idle until mount matches the server HTML.
|
|
34
|
+
const mounted = shallowRef(false);
|
|
35
|
+
onMounted(() => {
|
|
36
|
+
mounted.value = true;
|
|
37
|
+
});
|
|
38
|
+
return computed(() => (mounted.value ? status.value : "idle"));
|
|
19
39
|
}
|
|
20
40
|
function useSignalREvent(hub, event, handler) {
|
|
21
|
-
const context =
|
|
22
|
-
|
|
23
|
-
const
|
|
24
|
-
|
|
25
|
-
return;
|
|
26
|
-
const connection = context.getConnection(hub);
|
|
27
|
-
if (!connection)
|
|
28
|
-
return;
|
|
29
|
-
const listener = (...args) => handler(...args);
|
|
30
|
-
connection.on(event, listener);
|
|
31
|
-
cleanup(() => connection.off(event, listener));
|
|
32
|
-
}, { immediate: true, flush: "sync" });
|
|
33
|
-
onScopeDispose(stop);
|
|
41
|
+
const context = useScopedContext("useSignalREvent");
|
|
42
|
+
consume(context, hub);
|
|
43
|
+
const unsubscribe = context.subscribe(hub, event, (...args) => handler(...args));
|
|
44
|
+
onScopeDispose(unsubscribe);
|
|
34
45
|
}
|
|
35
46
|
function useOnReconnected(hub, callback) {
|
|
36
|
-
const context =
|
|
37
|
-
|
|
38
|
-
const unregister = context.registerReconnect(hub, callback);
|
|
47
|
+
const context = useScopedContext("useOnReconnected");
|
|
48
|
+
consume(context, hub);
|
|
49
|
+
const unregister = context.registerReconnect(hub, () => callback());
|
|
39
50
|
onScopeDispose(unregister);
|
|
40
51
|
}
|
|
41
52
|
function useSignalRInvoke(hub, method, options) {
|
|
42
|
-
const context =
|
|
43
|
-
|
|
53
|
+
const context = useScopedContext("useSignalRInvoke");
|
|
54
|
+
consume(context, hub);
|
|
44
55
|
const scope = createAbortScope();
|
|
45
56
|
onScopeDispose(() => {
|
|
46
57
|
if (!options?.keepAliveOnUnmount)
|
|
47
|
-
scope.
|
|
58
|
+
scope.abort();
|
|
59
|
+
});
|
|
60
|
+
return createInvoker({
|
|
61
|
+
target: context,
|
|
62
|
+
hub,
|
|
63
|
+
method,
|
|
64
|
+
getOptions: () => options,
|
|
65
|
+
getSignal: scope.signal,
|
|
48
66
|
});
|
|
49
|
-
return createInvoker(context, hub, method, () => options, scope.track, scope.untrack);
|
|
50
67
|
}
|
|
51
68
|
function useSignalRSend(hub, method) {
|
|
52
|
-
const context =
|
|
53
|
-
|
|
54
|
-
return createSender(context.getConnection, hub, method);
|
|
69
|
+
const context = useScopedContext("useSignalRSend");
|
|
70
|
+
consume(context, hub);
|
|
71
|
+
return createSender({ getConnection: context.getConnection, hub, method });
|
|
55
72
|
}
|
|
56
73
|
function useSignalRTeardown(hub, method, options) {
|
|
57
|
-
const context =
|
|
58
|
-
|
|
59
|
-
return createTeardownSender(context, hub, method, () => options);
|
|
74
|
+
const context = useScopedContext("useSignalRTeardown");
|
|
75
|
+
consume(context, hub);
|
|
76
|
+
return createTeardownSender({ target: context, hub, method, getOptions: () => options });
|
|
60
77
|
}
|
|
61
78
|
return {
|
|
62
79
|
useSignalR,
|
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
import type { InjectionKey, Plugin } from "vue";
|
|
2
2
|
import type { HubString, ResolvedHubConfig, SignalRContract } from "@dammers/use-signalr-core";
|
|
3
3
|
import type { SignalRContextValue, SignalROptions } from "../types.js";
|
|
4
|
-
export declare function createPlugin<T extends SignalRContract>(key: InjectionKey<SignalRContextValue<T>>, hubs: Array<keyof T & HubString>, resolve: (hub: keyof T & HubString) => ResolvedHubConfig): Plugin<[SignalROptions<T>]>;
|
|
4
|
+
export declare function createPlugin<T extends SignalRContract>(key: InjectionKey<SignalRContextValue<T>>, hubs: Array<keyof T & HubString>, resolve: (hub: keyof T & HubString) => ResolvedHubConfig): Plugin<[SignalROptions<keyof T & HubString>]>;
|
|
@@ -11,7 +11,7 @@ export function createPlugin(key, hubs, resolve) {
|
|
|
11
11
|
statusStore,
|
|
12
12
|
getAccessToken: () => options.accessTokenFactory(),
|
|
13
13
|
onStatusChange: (hub, status) => options.onStatusChange?.(hub, status),
|
|
14
|
-
onError: (hub, error) => options.onError?.(hub, error),
|
|
14
|
+
onError: (hub, error, info) => options.onError?.(hub, error, info),
|
|
15
15
|
});
|
|
16
16
|
app.provide(key, session.context);
|
|
17
17
|
let disposed = false;
|
|
@@ -22,20 +22,29 @@ export function createPlugin(key, hubs, resolve) {
|
|
|
22
22
|
scope?.stop();
|
|
23
23
|
session.stop();
|
|
24
24
|
};
|
|
25
|
-
const scope = typeof window === "undefined" ? undefined : effectScope();
|
|
26
|
-
scope?.run(() => {
|
|
27
|
-
watch(() =>
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
}, { immediate: true });
|
|
25
|
+
const scope = typeof window === "undefined" ? undefined : effectScope(true);
|
|
26
|
+
const startWatching = () => scope?.run(() => {
|
|
27
|
+
watch(() => ({
|
|
28
|
+
baseUrl: toValue(options.baseUrl),
|
|
29
|
+
enabled: toValue(options.enabled ?? true),
|
|
30
|
+
connectionKey: toValue(options.connectionKey),
|
|
31
|
+
}), (values) => session.update(values), { immediate: true });
|
|
32
32
|
});
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
33
|
+
// Starting after mount keeps the first client render equal to the server HTML.
|
|
34
|
+
const mount = app.mount.bind(app);
|
|
35
|
+
app.mount = (...args) => {
|
|
36
|
+
const instance = mount(...args);
|
|
37
|
+
if (instance)
|
|
38
|
+
startWatching();
|
|
39
|
+
return instance;
|
|
40
|
+
};
|
|
41
|
+
const unmount = app.unmount.bind(app);
|
|
42
|
+
// On Vue 3.5 types the else branch narrows `app` to never, so it writes through a plain `App`.
|
|
43
|
+
const fallbackTarget = app;
|
|
44
|
+
if (hasOnUnmount(app))
|
|
45
|
+
app.onUnmount(dispose);
|
|
36
46
|
else {
|
|
37
|
-
|
|
38
|
-
app.unmount = () => {
|
|
47
|
+
fallbackTarget.unmount = () => {
|
|
39
48
|
dispose();
|
|
40
49
|
unmount();
|
|
41
50
|
};
|
|
@@ -43,3 +52,7 @@ export function createPlugin(key, hubs, resolve) {
|
|
|
43
52
|
},
|
|
44
53
|
};
|
|
45
54
|
}
|
|
55
|
+
// Vue before 3.5 has no app.onUnmount, and its App type does not declare it.
|
|
56
|
+
function hasOnUnmount(app) {
|
|
57
|
+
return "onUnmount" in app;
|
|
58
|
+
}
|
package/dist/status-store.d.ts
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
import type { Ref } from "vue";
|
|
2
2
|
import type { HubConnectionStatus, StatusStore as StatusStoreBase } from "@dammers/use-signalr-core";
|
|
3
|
+
/** Read-only ref with the status of one hub. */
|
|
4
|
+
export interface HubStatusRef extends Readonly<Ref<HubConnectionStatus>> {
|
|
5
|
+
}
|
|
3
6
|
export interface StatusStore<H extends string> extends StatusStoreBase<H> {
|
|
4
|
-
ref: (hub: H) =>
|
|
7
|
+
ref: (hub: H) => HubStatusRef;
|
|
5
8
|
}
|
|
6
9
|
/** One shallow ref per hub prevents unrelated status writes from invalidating it. */
|
|
7
10
|
export declare function createStatusStore<H extends string>(): StatusStore<H>;
|
package/dist/status-store.js
CHANGED
package/dist/types.d.ts
CHANGED
|
@@ -1,12 +1,16 @@
|
|
|
1
1
|
import type { MaybeRefOrGetter } from "vue";
|
|
2
|
-
import type {
|
|
2
|
+
import type { HubString, SignalRContract, SignalRContextValueBase, SignalRProviderPropsBase } from "@dammers/use-signalr-core";
|
|
3
3
|
import type { StatusStore } from "./status-store.js";
|
|
4
4
|
export type { MaybeRefOrGetter } from "vue";
|
|
5
|
-
export type SignalROptions<
|
|
5
|
+
export type SignalROptions<THub extends HubString = HubString> = Omit<SignalRProviderPropsBase<THub>, "baseUrl" | "enabled" | "connectionKey"> & {
|
|
6
|
+
/** Base URL of the SignalR server. The library adds the hub paths from the contract and removes a trailing slash. A new value rebuilds all connections. `undefined` or `""` disables the session. Use `"/"` for the same origin. */
|
|
6
7
|
baseUrl: MaybeRefOrGetter<string | undefined>;
|
|
8
|
+
/**
|
|
9
|
+
* When `false`, all hubs stop and the status is `idle`. An invoke that waits for the connection rejects at once with an error named `SignalRDisabledError`.
|
|
10
|
+
* @default true
|
|
11
|
+
*/
|
|
7
12
|
enabled?: MaybeRefOrGetter<boolean>;
|
|
13
|
+
/** A new value rebuilds all connections. Use it to recover from `disconnected`. Pass a user ID or a login counter, not the token. */
|
|
8
14
|
connectionKey?: MaybeRefOrGetter<string | number | undefined>;
|
|
9
|
-
onStatusChange?: (hub: keyof T & HubString, status: HubConnectionStatus) => void;
|
|
10
|
-
onError?: (hub: keyof T & HubString, error: unknown) => void;
|
|
11
15
|
};
|
|
12
16
|
export type SignalRContextValue<T extends SignalRContract> = SignalRContextValueBase<T, StatusStore<keyof T & HubString>>;
|
package/package.json
CHANGED
|
@@ -1,61 +1,63 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@dammers/use-signalr-vue",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Fully-typed multi-hub SignalR plugin + composables for Vue.",
|
|
5
|
-
"author": "Dammers",
|
|
6
|
-
"license": "MIT",
|
|
7
|
-
"repository": {
|
|
8
|
-
"type": "git",
|
|
9
|
-
"url": "git+https://github.com/DammersCode/use-signalr.git",
|
|
10
|
-
"directory": "packages/vue"
|
|
11
|
-
},
|
|
12
|
-
"homepage": "https://
|
|
13
|
-
"bugs": {
|
|
14
|
-
"url": "https://github.com/DammersCode/use-signalr/issues"
|
|
15
|
-
},
|
|
16
|
-
"keywords": [
|
|
17
|
-
"signalr",
|
|
18
|
-
"typescript",
|
|
19
|
-
"realtime",
|
|
20
|
-
"websocket",
|
|
21
|
-
"vue",
|
|
22
|
-
"composables"
|
|
23
|
-
],
|
|
24
|
-
"engines": {
|
|
25
|
-
"node": ">=
|
|
26
|
-
},
|
|
27
|
-
"type": "module",
|
|
28
|
-
"sideEffects": false,
|
|
29
|
-
"main": "./dist/index.js",
|
|
30
|
-
"types": "./dist/index.d.ts",
|
|
31
|
-
"exports": {
|
|
32
|
-
".": {
|
|
33
|
-
"types": "./dist/index.d.ts",
|
|
34
|
-
"import": "./dist/index.js"
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
"
|
|
47
|
-
"
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
"
|
|
60
|
-
|
|
61
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@dammers/use-signalr-vue",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Fully-typed multi-hub SignalR plugin + composables for Vue.",
|
|
5
|
+
"author": "Dammers",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/DammersCode/use-signalr.git",
|
|
10
|
+
"directory": "packages/vue"
|
|
11
|
+
},
|
|
12
|
+
"homepage": "https://use-signalr.vercel.app/docs/vue",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/DammersCode/use-signalr/issues"
|
|
15
|
+
},
|
|
16
|
+
"keywords": [
|
|
17
|
+
"signalr",
|
|
18
|
+
"typescript",
|
|
19
|
+
"realtime",
|
|
20
|
+
"websocket",
|
|
21
|
+
"vue",
|
|
22
|
+
"composables"
|
|
23
|
+
],
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=20.19"
|
|
26
|
+
},
|
|
27
|
+
"type": "module",
|
|
28
|
+
"sideEffects": false,
|
|
29
|
+
"main": "./dist/index.js",
|
|
30
|
+
"types": "./dist/index.d.ts",
|
|
31
|
+
"exports": {
|
|
32
|
+
".": {
|
|
33
|
+
"types": "./dist/index.d.ts",
|
|
34
|
+
"import": "./dist/index.js",
|
|
35
|
+
"default": "./dist/index.js"
|
|
36
|
+
},
|
|
37
|
+
"./package.json": "./package.json"
|
|
38
|
+
},
|
|
39
|
+
"files": [
|
|
40
|
+
"dist"
|
|
41
|
+
],
|
|
42
|
+
"publishConfig": {
|
|
43
|
+
"access": "public"
|
|
44
|
+
},
|
|
45
|
+
"scripts": {
|
|
46
|
+
"prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
|
|
47
|
+
"build": "tsc -p tsconfig.build.json",
|
|
48
|
+
"typecheck": "tsc --noEmit",
|
|
49
|
+
"test": "vitest run"
|
|
50
|
+
},
|
|
51
|
+
"dependencies": {
|
|
52
|
+
"@dammers/use-signalr-core": "1.0.0"
|
|
53
|
+
},
|
|
54
|
+
"peerDependencies": {
|
|
55
|
+
"@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0",
|
|
56
|
+
"vue": "^3.3.0"
|
|
57
|
+
},
|
|
58
|
+
"devDependencies": {
|
|
59
|
+
"@microsoft/signalr": "^8.0.0 || ^9.0.0 || ^10.0.0",
|
|
60
|
+
"@vue/test-utils": "^2.4.11",
|
|
61
|
+
"vue": "^3.3.0"
|
|
62
|
+
}
|
|
63
|
+
}
|