@hyper-fetch/sockets 8.1.1 → 8.2.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
@@ -1,6 +1,10 @@
1
1
  # 🛰️ Hyper Fetch Sockets
2
2
 
3
- <p>
3
+ <p align="center">
4
+ <b>Real-time data exchange for WebSockets, SSE, and Firebase. Type-safe listeners with automatic reconnection.</b>
5
+ </p>
6
+
7
+ <p align="center">
4
8
  <a href="https://bettertyped.com/">
5
9
  <img src="https://custom-icon-badges.demolab.com/static/v1?label=&message=BetterTyped&color=333&logo=BT" />
6
10
  </a>
@@ -13,56 +17,103 @@
13
17
  <a href="https://www.npmjs.com/package/@hyper-fetch/sockets">
14
18
  <img src="https://custom-icon-badges.demolab.com/npm/v/@hyper-fetch/sockets.svg?logo=npm&color=e76f51" />
15
19
  </a>
20
+ <a href="https://www.npmjs.com/package/@hyper-fetch/sockets">
21
+ <img src="https://custom-icon-badges.demolab.com/npm/dm/@hyper-fetch/sockets?logoColor=fff&logo=trending-up" />
22
+ </a>
16
23
  <a href="https://github.com/BetterTyped/hyper-fetch">
17
24
  <img src="https://custom-icon-badges.demolab.com/badge/typescript-%23007ACC.svg?logo=typescript&logoColor=white" />
18
25
  </a>
19
- <a href="https://www.npmjs.com/package/@hyper-fetch/sockets">
26
+ <a href="https://bundlephobia.com/package/@hyper-fetch/sockets">
20
27
  <img src="https://custom-icon-badges.demolab.com/bundlephobia/minzip/@hyper-fetch/sockets?color=64BC4B&logo=package" />
21
28
  </a>
22
29
  </p>
23
30
 
24
- ## About
31
+ ## 📖 About
32
+
33
+ `@hyper-fetch/sockets` provides a typed abstraction for real-time communication. It wraps WebSockets and Server-Sent Events behind a consistent API with typed listeners and emitters, automatic reconnection, offline queuing, and authentication support.
34
+
35
+ ## 🎯 Key Capabilities
36
+
37
+ - 🔮 **Type-safe events** — Every listener and emitter is typed end-to-end, no more `JSON.parse` guessing
38
+ - 📡 **WebSocket + SSE, one API** — Switch between protocols without rewriting your event handlers
39
+ - 🔁 **Never lose connection** — Auto-reconnect with exponential backoff handles flaky networks for you
40
+ - 📴 **Offline event queuing** — Events you emit offline are saved and sent when connection returns
41
+ - 🔐 **Auth built in** — Token and session-based authentication flows for socket connections
42
+ - ⚛️ **React hooks included** — `useListener` and `useEmitter` plug real-time data straight into components
43
+ - 🖥️ **SSR safe** — Import in server-rendered apps without breaking hydration
44
+
45
+ ## 🚀 Quick Start
46
+
47
+ ```bash
48
+ npm install @hyper-fetch/sockets
49
+ ```
50
+
51
+ ```ts
52
+ import { Socket } from "@hyper-fetch/sockets";
25
53
 
26
- **`Hyper Fetch Sockets`** is a library for handling `web sockets` and `server sent events`. Thanks to it, we get a
27
- **neutral layer of control** to which we can easily integrate any available solution for dynamic two-way communication.
54
+ const socket = new Socket({ url: "ws://localhost:3000" });
28
55
 
29
- ## Features
56
+ const onMessage = socket.createListener<{ response: { text: string; author: string } }>()({
57
+ endpoint: "chat-message",
58
+ });
30
59
 
31
- 🔮 **Simple setup** - [Read more](https://hyperfetch.bettertyped.com/docs/guides/sockets/setup)
60
+ onMessage.listen({ callback: ({ data }) => console.log(`${data.author}: ${data.text}`) });
61
+ ```
32
62
 
33
- 🎯 **Web Sockets** - [Read more](https://hyperfetch.bettertyped.com/docs/sockets/overview#Websockets)
63
+ ## 📚 Documentation
34
64
 
35
- ✨ **Server sent events** - [Read more](https://hyperfetch.bettertyped.com/docs/sockets/overview#Sockets)
65
+ - [Getting Started](https://hyperfetch.bettertyped.com/docs/getting-started/quick-start)
66
+ - [Sockets Overview](https://hyperfetch.bettertyped.com/docs/sockets/overview)
67
+ - [API Reference](https://hyperfetch.bettertyped.com/api/)
36
68
 
37
- 🚀 **Type safe** - [Read more](https://hyperfetch.bettertyped.com/docs/guides/sockets/typescript)
69
+ ## 💡 Examples
38
70
 
39
- 🎊 **SSR Support** - [Read more](https://hyperfetch.bettertyped.com/docs/getting-started/environment)
71
+ ### Emitting typed events
40
72
 
41
- 🔋 **Offline First** - [Read more](https://hyperfetch.bettertyped.com/docs/guides/sockets/offline)
73
+ ```ts
74
+ const sendMessage = socket.createEmitter<{ payload: { text: string; room: string } }>()({
75
+ endpoint: "send-message",
76
+ });
42
77
 
43
- 📡 **Built-in adapter** - [Read more](https://hyperfetch.bettertyped.com/docs/sockets/adapter)
78
+ sendMessage.emit({ data: { text: "Hello!", room: "general" } });
79
+ ```
44
80
 
45
- 🎟 **Authentication** - [Read more](https://hyperfetch.bettertyped.com/docs/guides/sockets/authentication)
81
+ ### Listening with React hooks
46
82
 
47
- ## Help me keep working on this project ❤️
83
+ ```tsx
84
+ import { useListener } from "@hyper-fetch/react";
48
85
 
49
- - [Become a Sponsor on GitHub](https://github.com/sponsors/prc5)
86
+ const ChatMessages = ({ room }: { room: string }) => {
87
+ const { data, connected, timestamp } = useListener(onMessage);
50
88
 
51
- ## React
89
+ return (
90
+ <div>
91
+ <p>Status: {connected ? "Connected" : "Disconnected"}</p>
92
+ {data && (
93
+ <div>
94
+ <strong>{data.author}</strong>: {data.text}
95
+ <small>{new Date(timestamp).toLocaleTimeString()}</small>
96
+ </div>
97
+ )}
98
+ </div>
99
+ );
100
+ };
101
+ ```
52
102
 
53
- We have specially created hooks to support sockets.
103
+ ### Server-Sent Events
54
104
 
55
- [Check it out](https://hyperfetch.bettertyped.com/react/websockets)
105
+ ```ts
106
+ const sseSocket = new Socket({ url: "https://api.example.com/events" });
56
107
 
57
- ## Sources
108
+ const onUpdate = sseSocket.createListener<{ response: { type: string; payload: unknown } }>()({
109
+ endpoint: "data-update",
110
+ });
58
111
 
59
- - #### [Installation](https://hyperfetch.bettertyped.com/docs/getting-started/installation)
60
- - #### [Docs](https://hyperfetch.bettertyped.com/docs/sockets/overview)
61
- - #### [API](https://hyperfetch.bettertyped.com/api/)
62
- - #### [NPM](https://www.npmjs.com/package/@hyper-fetch/sockets)
63
- - #### [Guides](https://hyperfetch.bettertyped.com/docs/guides/sockets/setup)
112
+ onUpdate.listen({
113
+ callback: ({ data }) => console.log(`Event: ${data.type}`, data.payload),
114
+ });
115
+ ```
64
116
 
65
- ## Other Packages
117
+ ## License
66
118
 
67
- - #### [Hyper Fetch](https://github.com/BetterTyped/hyper-fetch/tree/main/packages/core)
68
- - #### [React Hyper Fetch](https://github.com/BetterTyped/hyper-fetch/tree/main/packages/react)
119
+ [MIT](https://github.com/BetterTyped/hyper-fetch/blob/main/License.md)
@@ -1,40 +1,37 @@
1
1
  import type { SocketInstance } from "socket";
2
2
  import { Listener } from "listener";
3
- import type { ListenerInstance } from "listener";
3
+ import type { ListenerModel } from "listener";
4
4
  import { Emitter } from "emitter";
5
- import type { EmitterInstance } from "emitter";
5
+ import type { EmitterModel } from "emitter";
6
6
  import { createSocketSdk } from "sdk";
7
7
  import { createSocket } from "../../utils/socket.utils";
8
8
 
9
9
  type TestSocket = SocketInstance;
10
10
 
11
+ // Schema does not need to declare `socket` per leaf - the SDK injects it from createSocketSdk(socket).
11
12
  type TestSchema = {
12
13
  chat: {
13
14
  messages: {
14
- $listener: ListenerInstance<{
15
+ $listener: ListenerModel<{
15
16
  response: { text: string; user: string };
16
17
  topic: "chat/messages";
17
- socket: TestSocket;
18
18
  }>;
19
- $emitter: EmitterInstance<{
19
+ $emitter: EmitterModel<{
20
20
  payload: { text: string };
21
21
  topic: "chat/messages";
22
- socket: TestSocket;
23
22
  }>;
24
23
  };
25
24
  $roomId: {
26
- $listener: ListenerInstance<{
25
+ $listener: ListenerModel<{
27
26
  response: { text: string; user: string };
28
27
  topic: "chat/:roomId";
29
- socket: TestSocket;
30
28
  }>;
31
29
  };
32
30
  };
33
31
  notifications: {
34
- $listener: ListenerInstance<{
32
+ $listener: ListenerModel<{
35
33
  response: { message: string };
36
34
  topic: "notifications";
37
- socket: TestSocket;
38
35
  }>;
39
36
  };
40
37
  };
@@ -107,10 +104,9 @@ describe("Socket SDK [ Base ]", () => {
107
104
  it("should handle camelCase to kebab-case conversion", () => {
108
105
  type KebabSchema = {
109
106
  someChannel: {
110
- $listener: ListenerInstance<{
107
+ $listener: ListenerModel<{
111
108
  response: any;
112
109
  topic: "some-channel";
113
- socket: TestSocket;
114
110
  }>;
115
111
  };
116
112
  };
@@ -1,39 +1,36 @@
1
1
  import type { SocketInstance } from "socket";
2
- import type { ListenerInstance } from "listener";
3
- import type { EmitterInstance } from "emitter";
2
+ import type { ListenerModel } from "listener";
3
+ import type { EmitterModel } from "emitter";
4
4
  import type { SocketSdkConfigurationValue } from "sdk";
5
5
  import { createSocketSdk, createSocketConfiguration } from "sdk";
6
6
  import { createSocket } from "../../utils/socket.utils";
7
7
 
8
8
  type TestSocket = SocketInstance;
9
9
 
10
+ // Schema does not need to declare `socket` per leaf - the SDK injects it from createSocketSdk(socket).
10
11
  type TestSchema = {
11
12
  chat: {
12
13
  messages: {
13
- $listener: ListenerInstance<{
14
+ $listener: ListenerModel<{
14
15
  response: { text: string; user: string };
15
16
  topic: "chat/messages";
16
- socket: TestSocket;
17
17
  }>;
18
- $emitter: EmitterInstance<{
18
+ $emitter: EmitterModel<{
19
19
  payload: { text: string };
20
20
  topic: "chat/messages";
21
- socket: TestSocket;
22
21
  }>;
23
22
  };
24
23
  rooms: {
25
- $listener: ListenerInstance<{
24
+ $listener: ListenerModel<{
26
25
  response: { name: string };
27
26
  topic: "chat/rooms";
28
- socket: TestSocket;
29
27
  }>;
30
28
  };
31
29
  };
32
30
  notifications: {
33
- $listener: ListenerInstance<{
31
+ $listener: ListenerModel<{
34
32
  response: { message: string };
35
33
  topic: "notifications";
36
- socket: TestSocket;
37
34
  }>;
38
35
  };
39
36
  };
@@ -0,0 +1,303 @@
1
+ import { describe, it, expect, expectTypeOf } from "vitest";
2
+
3
+ import type { SocketInstance } from "socket";
4
+ import type { Listener, ListenerInstance, ListenerModel } from "listener";
5
+ import type { Emitter, EmitterInstance, EmitterModel } from "emitter";
6
+ import { createSocketSdk } from "sdk";
7
+ import type { InjectSocket } from "sdk";
8
+ import { createSocket } from "../../utils/socket.utils";
9
+
10
+ /**
11
+ * Type-only tests for the Socket SDK type surface.
12
+ *
13
+ * Each `it` block runs a static `expectTypeOf` assertion plus a trivial runtime placeholder
14
+ * so the tests show up in the Vitest report.
15
+ */
16
+
17
+ type TestSocket = SocketInstance;
18
+ type ChatMessage = { text: string; user: string };
19
+
20
+ describe("ListenerModel - defaults for omitted fields", () => {
21
+ it("should default response to unknown", () => {
22
+ type L = ListenerModel<{ topic: "chat/messages" }>;
23
+ type Response = L extends Listener<infer R, any, any, any> ? R : never;
24
+ expectTypeOf<Response>().toEqualTypeOf<unknown>();
25
+ expect(true).toBe(true);
26
+ });
27
+
28
+ it("should default topic to string when not provided", () => {
29
+ type L = ListenerModel<{ response: ChatMessage }>;
30
+ type Topic = L extends Listener<any, infer T, any, any> ? T : never;
31
+ expectTypeOf<Topic>().toEqualTypeOf<string>();
32
+ expect(true).toBe(true);
33
+ });
34
+
35
+ it("should default socket to SocketInstance when not provided", () => {
36
+ type L = ListenerModel<{ response: ChatMessage; topic: "chat" }>;
37
+ type Sock = L extends Listener<any, any, infer S, any> ? S : never;
38
+ expectTypeOf<Sock>().toEqualTypeOf<SocketInstance>();
39
+ expect(true).toBe(true);
40
+ });
41
+
42
+ it("should default hasParams to false", () => {
43
+ type L = ListenerModel<{ topic: "chat" }>;
44
+ type HasParams = L extends Listener<any, any, any, infer Hp> ? Hp : never;
45
+ expectTypeOf<HasParams>().toEqualTypeOf<false>();
46
+ expect(true).toBe(true);
47
+ });
48
+ });
49
+
50
+ describe("EmitterModel - defaults for omitted fields", () => {
51
+ it("should default payload to undefined", () => {
52
+ type E = EmitterModel<{ topic: "chat" }>;
53
+ type Payload = E extends Emitter<infer P, any, any, any, any> ? P : never;
54
+ expectTypeOf<Payload>().toEqualTypeOf<undefined>();
55
+ expect(true).toBe(true);
56
+ });
57
+
58
+ it("should default topic to string when not provided", () => {
59
+ type E = EmitterModel<{ payload: { text: string } }>;
60
+ type Topic = E extends Emitter<any, infer T, any, any, any> ? T : never;
61
+ expectTypeOf<Topic>().toEqualTypeOf<string>();
62
+ expect(true).toBe(true);
63
+ });
64
+
65
+ it("should default socket to SocketInstance when not provided", () => {
66
+ type E = EmitterModel<{ topic: "chat" }>;
67
+ type Sock = E extends Emitter<any, any, infer S, any, any> ? S : never;
68
+ expectTypeOf<Sock>().toEqualTypeOf<SocketInstance>();
69
+ expect(true).toBe(true);
70
+ });
71
+
72
+ it("should default hasPayload and hasParams to false", () => {
73
+ type E = EmitterModel<{ topic: "chat" }>;
74
+ type HasPayload = E extends Emitter<any, any, any, infer Hp, any> ? Hp : never;
75
+ type HasParams = E extends Emitter<any, any, any, any, infer Hpa> ? Hpa : never;
76
+ expectTypeOf<HasPayload>().toEqualTypeOf<false>();
77
+ expectTypeOf<HasParams>().toEqualTypeOf<false>();
78
+ expect(true).toBe(true);
79
+ });
80
+ });
81
+
82
+ describe("ListenerModel / EmitterModel - user-provided fields override defaults", () => {
83
+ it("should narrow response and topic on a Listener when provided", () => {
84
+ type L = ListenerModel<{ response: ChatMessage; topic: "chat/messages" }>;
85
+ type Response = L extends Listener<infer R, any, any, any> ? R : never;
86
+ type Topic = L extends Listener<any, infer T, any, any> ? T : never;
87
+ expectTypeOf<Response>().toEqualTypeOf<ChatMessage>();
88
+ expectTypeOf<Topic>().toEqualTypeOf<"chat/messages">();
89
+ expect(true).toBe(true);
90
+ });
91
+
92
+ it("should narrow payload and topic on an Emitter when provided", () => {
93
+ type E = EmitterModel<{ payload: { text: string }; topic: "chat/send" }>;
94
+ type Payload = E extends Emitter<infer P, any, any, any, any> ? P : never;
95
+ type Topic = E extends Emitter<any, infer T, any, any, any> ? T : never;
96
+ expectTypeOf<Payload>().toEqualTypeOf<{ text: string }>();
97
+ expectTypeOf<Topic>().toEqualTypeOf<"chat/send">();
98
+ expect(true).toBe(true);
99
+ });
100
+ });
101
+
102
+ describe("ListenerInstance / EmitterInstance - keep `any` defaults (constraint use)", () => {
103
+ it("should keep ListenerInstance wide so concrete listeners satisfy it", () => {
104
+ type LI = ListenerInstance;
105
+ type Response = LI extends Listener<infer R, any, any, any> ? R : never;
106
+ expectTypeOf<Response>().toEqualTypeOf<any>();
107
+ expect(true).toBe(true);
108
+ });
109
+
110
+ it("should accept a concrete ListenerModel as a ListenerInstance", () => {
111
+ type Concrete = ListenerModel<{ response: ChatMessage; topic: "chat" }>;
112
+ expectTypeOf<Concrete>().toMatchTypeOf<ListenerInstance>();
113
+ expect(true).toBe(true);
114
+ });
115
+
116
+ it("should accept a concrete EmitterModel as an EmitterInstance", () => {
117
+ type Concrete = EmitterModel<{ payload: { text: string }; topic: "chat" }>;
118
+ expectTypeOf<Concrete>().toMatchTypeOf<EmitterInstance>();
119
+ expect(true).toBe(true);
120
+ });
121
+ });
122
+
123
+ describe("InjectSocket - schema-level socket injection", () => {
124
+ it("should replace the Socket slot on a Listener leaf", () => {
125
+ type Schema = {
126
+ $listener: ListenerModel<{ response: ChatMessage; topic: "chat" }>;
127
+ };
128
+ type Injected = InjectSocket<Schema, TestSocket>;
129
+ type ResolvedSocket = Injected["$listener"] extends Listener<any, any, infer S, any> ? S : never;
130
+ expectTypeOf<ResolvedSocket>().toEqualTypeOf<TestSocket>();
131
+ expect(true).toBe(true);
132
+ });
133
+
134
+ it("should replace the Socket slot on an Emitter leaf", () => {
135
+ type Schema = {
136
+ $emitter: EmitterModel<{ payload: { text: string }; topic: "chat" }>;
137
+ };
138
+ type Injected = InjectSocket<Schema, TestSocket>;
139
+ type ResolvedSocket = Injected["$emitter"] extends Emitter<any, any, infer S, any, any> ? S : never;
140
+ expectTypeOf<ResolvedSocket>().toEqualTypeOf<TestSocket>();
141
+ expect(true).toBe(true);
142
+ });
143
+
144
+ it("should walk nested schema objects and inject into every leaf", () => {
145
+ type Schema = {
146
+ chat: {
147
+ messages: {
148
+ $listener: ListenerModel<{ response: ChatMessage; topic: "chat/messages" }>;
149
+ $emitter: EmitterModel<{ payload: { text: string }; topic: "chat/messages" }>;
150
+ };
151
+ $roomId: {
152
+ $listener: ListenerModel<{ response: ChatMessage; topic: "chat/:roomId" }>;
153
+ };
154
+ };
155
+ };
156
+ type Injected = InjectSocket<Schema, TestSocket>;
157
+
158
+ type LSocket = Injected["chat"]["messages"]["$listener"] extends Listener<any, any, infer S, any> ? S : never;
159
+ type ESocket = Injected["chat"]["messages"]["$emitter"] extends Emitter<any, any, infer S, any, any> ? S : never;
160
+ type NestedLSocket = Injected["chat"]["$roomId"]["$listener"] extends Listener<any, any, infer S, any> ? S : never;
161
+
162
+ expectTypeOf<LSocket>().toEqualTypeOf<TestSocket>();
163
+ expectTypeOf<ESocket>().toEqualTypeOf<TestSocket>();
164
+ expectTypeOf<NestedLSocket>().toEqualTypeOf<TestSocket>();
165
+ expect(true).toBe(true);
166
+ });
167
+
168
+ it("should preserve response, payload, topic on injected leaves", () => {
169
+ type Schema = {
170
+ chat: {
171
+ $listener: ListenerModel<{ response: ChatMessage; topic: "chat/messages" }>;
172
+ $emitter: EmitterModel<{ payload: { text: string }; topic: "chat/messages" }>;
173
+ };
174
+ };
175
+ type Injected = InjectSocket<Schema, TestSocket>;
176
+
177
+ type LResp = Injected["chat"]["$listener"] extends Listener<infer R, any, any, any> ? R : never;
178
+ type LTopic = Injected["chat"]["$listener"] extends Listener<any, infer T, any, any> ? T : never;
179
+ type EPayload = Injected["chat"]["$emitter"] extends Emitter<infer P, any, any, any, any> ? P : never;
180
+ type ETopic = Injected["chat"]["$emitter"] extends Emitter<any, infer T, any, any, any> ? T : never;
181
+
182
+ expectTypeOf<LResp>().toEqualTypeOf<ChatMessage>();
183
+ expectTypeOf<LTopic>().toEqualTypeOf<"chat/messages">();
184
+ expectTypeOf<EPayload>().toEqualTypeOf<{ text: string }>();
185
+ expectTypeOf<ETopic>().toEqualTypeOf<"chat/messages">();
186
+ expect(true).toBe(true);
187
+ });
188
+ });
189
+
190
+ describe("createSocketSdk - produces a fully resolved SDK type", () => {
191
+ type Schema = {
192
+ chat: {
193
+ messages: {
194
+ $listener: ListenerModel<{ response: ChatMessage; topic: "chat/messages" }>;
195
+ $emitter: EmitterModel<{ payload: { text: string }; topic: "chat/messages" }>;
196
+ };
197
+ $roomId: {
198
+ $listener: ListenerModel<{ response: ChatMessage; topic: "chat/:roomId" }>;
199
+ };
200
+ };
201
+ };
202
+
203
+ it("should type sdk.chat.messages.$listener with the SDK socket injected", () => {
204
+ const socket = createSocket();
205
+ const sdk = createSocketSdk<typeof socket, Schema>(socket);
206
+
207
+ type ChatListener = typeof sdk.chat.messages.$listener;
208
+ type ResolvedSocket = ChatListener extends Listener<any, any, infer S, any> ? S : never;
209
+ type ResolvedResponse = ChatListener extends Listener<infer R, any, any, any> ? R : never;
210
+ type ResolvedTopic = ChatListener extends Listener<any, infer T, any, any> ? T : never;
211
+
212
+ expectTypeOf<ResolvedSocket>().toEqualTypeOf<typeof socket>();
213
+ expectTypeOf<ResolvedResponse>().toEqualTypeOf<ChatMessage>();
214
+ expectTypeOf<ResolvedTopic>().toEqualTypeOf<"chat/messages">();
215
+ expect(true).toBe(true);
216
+ });
217
+
218
+ it("should type sdk.chat.messages.$emitter with the SDK socket injected", () => {
219
+ const socket = createSocket();
220
+ const sdk = createSocketSdk<typeof socket, Schema>(socket);
221
+
222
+ type ChatEmitter = typeof sdk.chat.messages.$emitter;
223
+ type ResolvedSocket = ChatEmitter extends Emitter<any, any, infer S, any, any> ? S : never;
224
+ type ResolvedPayload = ChatEmitter extends Emitter<infer P, any, any, any, any> ? P : never;
225
+
226
+ expectTypeOf<ResolvedSocket>().toEqualTypeOf<typeof socket>();
227
+ expectTypeOf<ResolvedPayload>().toEqualTypeOf<{ text: string }>();
228
+ expect(true).toBe(true);
229
+ });
230
+
231
+ it("should type nested sdk.chat.$roomId.$listener with the SDK socket injected", () => {
232
+ const socket = createSocket();
233
+ const sdk = createSocketSdk<typeof socket, Schema>(socket);
234
+
235
+ type RoomListener = typeof sdk.chat.$roomId.$listener;
236
+ type ResolvedSocket = RoomListener extends Listener<any, any, infer S, any> ? S : never;
237
+ type ResolvedTopic = RoomListener extends Listener<any, infer T, any, any> ? T : never;
238
+
239
+ expectTypeOf<ResolvedSocket>().toEqualTypeOf<typeof socket>();
240
+ expectTypeOf<ResolvedTopic>().toEqualTypeOf<"chat/:roomId">();
241
+ expect(true).toBe(true);
242
+ });
243
+
244
+ it("should expose $configure on the Socket SDK type", () => {
245
+ const socket = createSocket();
246
+ const sdk = createSocketSdk<typeof socket, Schema>(socket);
247
+
248
+ expectTypeOf(sdk.$configure).toBeFunction();
249
+ expect(true).toBe(true);
250
+ });
251
+ });
252
+
253
+ describe("$configure - dot-path callback narrowing", () => {
254
+ type Schema = {
255
+ chat: {
256
+ messages: {
257
+ $listener: ListenerModel<{ response: ChatMessage; topic: "chat/messages" }>;
258
+ $emitter: EmitterModel<{ payload: { text: string }; topic: "chat/messages" }>;
259
+ };
260
+ };
261
+ };
262
+
263
+ it("should accept a function value for a dot-path listener key", () => {
264
+ const socket = createSocket();
265
+ const sdk = createSocketSdk<typeof socket, Schema>(socket);
266
+
267
+ sdk.$configure({
268
+ "chat.messages.$listener": (instance) => {
269
+ expectTypeOf(instance).toMatchTypeOf<ListenerInstance>();
270
+ return instance;
271
+ },
272
+ });
273
+
274
+ expect(true).toBe(true);
275
+ });
276
+
277
+ it("should accept a function value for a dot-path emitter key", () => {
278
+ const socket = createSocket();
279
+ const sdk = createSocketSdk<typeof socket, Schema>(socket);
280
+
281
+ sdk.$configure({
282
+ "chat.messages.$emitter": (instance) => {
283
+ expectTypeOf(instance).toMatchTypeOf<EmitterInstance>();
284
+ return instance;
285
+ },
286
+ });
287
+
288
+ expect(true).toBe(true);
289
+ });
290
+
291
+ it("should accept a plain-object value for global wildcard and topic-group keys", () => {
292
+ const socket = createSocket();
293
+ const sdk = createSocketSdk<typeof socket, Schema>(socket);
294
+
295
+ sdk.$configure({
296
+ "*": { options: { reconnect: true } },
297
+ "chat/*": { options: { priority: "high" } },
298
+ "chat/messages": { options: { buffered: true } },
299
+ });
300
+
301
+ expect(true).toBe(true);
302
+ });
303
+ });
@@ -3,9 +3,10 @@ import { SocketAdapter } from '../adapter/adapter';
3
3
  import { SSEAdapterOptionsType } from './sse-adapter.types';
4
4
  /**
5
5
  * -------------------------------------------
6
- * Websocket
6
+ * Server-Sent Events
7
7
  * -------------------------------------------
8
8
  */
9
9
  export type ServerSentEventsAdapterType = SocketAdapter<MessageEvent<any>, SSEAdapterOptionsType, undefined, undefined, QueryParamsType | string, typeof stringifyQueryParams>;
10
+ /** Create a preconfigured socket adapter for Server-Sent Events (EventSource) connections. */
10
11
  export declare const ServerSentEventsAdapter: () => ServerSentEventsAdapterType;
11
12
  //# sourceMappingURL=sse-adapter.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"sse-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter-sse/sse-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAIzD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAIjE;;;;GAIG;AAEH,MAAM,MAAM,2BAA2B,GAAG,aAAa,CACrD,YAAY,CAAC,GAAG,CAAC,EACjB,qBAAqB,EACrB,SAAS,EACT,SAAS,EACT,eAAe,GAAG,MAAM,EACxB,OAAO,oBAAoB,CAC5B,CAAC;AAEF,eAAO,MAAM,uBAAuB,QAAO,2BA4JtC,CAAC"}
1
+ {"version":3,"file":"sse-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter-sse/sse-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAIzD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAIjE;;;;GAIG;AAEH,MAAM,MAAM,2BAA2B,GAAG,aAAa,CACrD,YAAY,CAAC,GAAG,CAAC,EACjB,qBAAqB,EACrB,SAAS,EACT,SAAS,EACT,eAAe,GAAG,MAAM,EACxB,OAAO,oBAAoB,CAC5B,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB,QAAO,2BA4JtC,CAAC"}
@@ -7,5 +7,6 @@ import { WebsocketAdapterOptionsType } from './websocket-adapter.types';
7
7
  * -------------------------------------------
8
8
  */
9
9
  export type WebsocketAdapterType = SocketAdapter<MessageEvent<any>, WebsocketAdapterOptionsType, undefined, undefined, QueryParamsType | string, typeof stringifyQueryParams>;
10
+ /** Create a preconfigured socket adapter for native WebSocket connections. */
10
11
  export declare const WebsocketAdapter: () => WebsocketAdapterType;
11
12
  //# sourceMappingURL=websocket-adapter.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"websocket-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter-websockets/websocket-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAQ,MAAM,mBAAmB,CAAC;AAK/D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAK7E;;;;GAIG;AAEH,MAAM,MAAM,oBAAoB,GAAG,aAAa,CAC9C,YAAY,CAAC,GAAG,CAAC,EACjB,2BAA2B,EAC3B,SAAS,EACT,SAAS,EACT,eAAe,GAAG,MAAM,EACxB,OAAO,oBAAoB,CAC5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAO,oBAsO/B,CAAC"}
1
+ {"version":3,"file":"websocket-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter-websockets/websocket-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAQ,MAAM,mBAAmB,CAAC;AAK/D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAK7E;;;;GAIG;AAEH,MAAM,MAAM,oBAAoB,GAAG,aAAa,CAC9C,YAAY,CAAC,GAAG,CAAC,EACjB,2BAA2B,EAC3B,SAAS,EACT,SAAS,EACT,eAAe,GAAG,MAAM,EACxB,OAAO,oBAAoB,CAC5B,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,QAAO,oBAsO/B,CAAC"}
@@ -2,6 +2,10 @@ import { ExtractUrlParams, ParamsType, PayloadMapperType, EmptyTypes } from '@hy
2
2
  import { SocketInstance } from '../socket';
3
3
  import { EmitterCloneOptionsType, EmitterOptionsType, EmitType } from '.';
4
4
  import { ExtractAdapterEmitterOptionsType, ExtractSocketAdapterType } from '../types';
5
+ /**
6
+ * Represents a socket message emitter bound to a specific topic. Use it to send typed payloads
7
+ * over WebSocket or Server-Sent Events connections via the socket adapter.
8
+ */
5
9
  export declare class Emitter<Payload, Topic extends string, Socket extends SocketInstance, HasPayload extends boolean = false, HasParams extends boolean = false> {
6
10
  readonly socket: Socket;
7
11
  readonly emitterOptions: EmitterOptionsType<Topic, ExtractSocketAdapterType<Socket>>;
@@ -17,12 +21,18 @@ export declare class Emitter<Payload, Topic extends string, Socket extends Socke
17
21
  * @internal
18
22
  */
19
23
  snapshot?: Partial<Emitter<Payload, Topic, Socket, any, any>>);
24
+ /** Set adapter-specific emit options (e.g., acknowledgment, timeout). */
20
25
  setOptions(options: ExtractAdapterEmitterOptionsType<ExtractSocketAdapterType<Socket>> | undefined): Emitter<Payload, Topic, Socket, HasPayload, HasParams>;
26
+ /** Set the message payload to be emitted. */
21
27
  setPayload: <D extends Payload>(payload: D) => Emitter<D, Topic, Socket, D extends EmptyTypes ? false : true, HasParams>;
28
+ /** Set a mapper function that transforms the payload before it is sent. */
22
29
  setPayloadMapper: <DataMapper extends (payload: Payload) => any | Promise<any>>(payloadMapper: DataMapper) => Emitter<Payload, Topic, Socket, HasPayload, HasParams>;
30
+ /** Set the URL path parameters for the topic (e.g., `:channelId`). */
23
31
  setParams(params: NonNullable<ExtractUrlParams<Topic>>): Emitter<Payload, Topic, Socket, HasPayload, true>;
24
32
  private paramsMapper;
33
+ /** Create a new emitter instance with optional configuration overrides. */
25
34
  clone<NewPayload extends Payload = Payload, NewHasPayload extends boolean = HasPayload, NewHasParams extends boolean = HasParams>(config?: EmitterCloneOptionsType<NewPayload, ParamsType, Topic, Socket>): Emitter<NewPayload, Topic, Socket, NewHasPayload, NewHasParams>;
35
+ /** Send the message through the socket adapter on the configured topic. */
26
36
  emit: EmitType<Emitter<Payload, Topic, Socket, HasPayload, HasParams>>;
27
37
  }
28
38
  //# sourceMappingURL=emitter.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/emitter/emitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAErG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAyB,uBAAuB,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5G,OAAO,KAAK,EAAE,gCAAgC,EAAE,wBAAwB,EAAE,MAAM,OAAO,CAAC;AAExF,qBAAa,OAAO,CAClB,OAAO,EACP,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,cAAc,EAC7B,UAAU,SAAS,OAAO,GAAG,KAAK,EAClC,SAAS,SAAS,OAAO,GAAG,KAAK;IAU/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC,KAAK,EAAE,wBAAwB,CAAC,MAAM,CAAC,CAAC;IATtF,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,gCAAgC,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IACxF,gBAAgB;IAChB,sBAAsB,CAAC,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;gBAGrC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,kBAAkB,CAAC,KAAK,EAAE,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACpF;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAU/D,UAAU,CAAC,OAAO,EAAE,gCAAgC,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS;IAIlG,UAAU,GAAI,CAAC,SAAS,OAAO,EAAE,SAAS,CAAC,+EAIzC;IAEF,gBAAgB,GAAI,UAAU,SAAS,CAAC,OAAO,EAAE,OAAO,KAAK,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,eAAe,UAAU,4DAMxG;IAEF,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAItD,OAAO,CAAC,YAAY,CASlB;IAEF,KAAK,CACH,UAAU,SAAS,OAAO,GAAG,OAAO,EACpC,aAAa,SAAS,OAAO,GAAG,UAAU,EAC1C,YAAY,SAAS,OAAO,GAAG,SAAS,EAExC,MAAM,CAAC,EAAE,uBAAuB,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,GACtE,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,CAAC;IAoBlE,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAKpE;CACH"}
1
+ {"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/emitter/emitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAErG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAyB,uBAAuB,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5G,OAAO,KAAK,EAAE,gCAAgC,EAAE,wBAAwB,EAAE,MAAM,OAAO,CAAC;AAExF;;;GAGG;AACH,qBAAa,OAAO,CAClB,OAAO,EACP,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,cAAc,EAC7B,UAAU,SAAS,OAAO,GAAG,KAAK,EAClC,SAAS,SAAS,OAAO,GAAG,KAAK;IAU/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC,KAAK,EAAE,wBAAwB,CAAC,MAAM,CAAC,CAAC;IATtF,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,gCAAgC,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IACxF,gBAAgB;IAChB,sBAAsB,CAAC,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;gBAGrC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,kBAAkB,CAAC,KAAK,EAAE,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACpF;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAU/D,yEAAyE;IACzE,UAAU,CAAC,OAAO,EAAE,gCAAgC,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS;IAIlG,6CAA6C;IAC7C,UAAU,GAAI,CAAC,SAAS,OAAO,EAAE,SAAS,CAAC,+EAIzC;IAEF,2EAA2E;IAC3E,gBAAgB,GAAI,UAAU,SAAS,CAAC,OAAO,EAAE,OAAO,KAAK,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,eAAe,UAAU,4DAMxG;IAEF,sEAAsE;IACtE,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAItD,OAAO,CAAC,YAAY,CASlB;IAEF,2EAA2E;IAC3E,KAAK,CACH,UAAU,SAAS,OAAO,GAAG,OAAO,EACpC,aAAa,SAAS,OAAO,GAAG,UAAU,EAC1C,YAAY,SAAS,OAAO,GAAG,SAAS,EAExC,MAAM,CAAC,EAAE,uBAAuB,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,GACtE,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,CAAC;IAoBlE,2EAA2E;IAC3E,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAKpE;CACH"}