@hyper-fetch/sockets 8.0.0 → 8.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.
Files changed (41) hide show
  1. package/__tests__/e2e/e2e.callbacks.spec.ts +224 -0
  2. package/__tests__/e2e/e2e.connection.spec.ts +162 -0
  3. package/__tests__/e2e/e2e.edge-cases.spec.ts +232 -0
  4. package/__tests__/e2e/e2e.emitters.spec.ts +160 -0
  5. package/__tests__/e2e/e2e.heartbeat.spec.ts +162 -0
  6. package/__tests__/e2e/e2e.listeners.spec.ts +215 -0
  7. package/__tests__/e2e/e2e.reconnection.spec.ts +240 -0
  8. package/__tests__/e2e/e2e.sse.spec.ts +191 -0
  9. package/__tests__/features/adapter/adapter.sse.connection.spec.ts +1 -1
  10. package/__tests__/features/sdk/sdk.base.spec.ts +125 -0
  11. package/__tests__/features/sdk/sdk.configuration.spec.ts +341 -0
  12. package/__tests__/vitest.setup.ts +19 -6
  13. package/dist/adapter/adapter.bindings.d.ts.map +1 -1
  14. package/dist/adapter-sse/sse-adapter.d.ts.map +1 -1
  15. package/dist/adapter-sse/sse-adapter.utils.d.ts +1 -1
  16. package/dist/adapter-sse/sse-adapter.utils.d.ts.map +1 -1
  17. package/dist/adapter-websockets/websocket-adapter.utils.d.ts +1 -1
  18. package/dist/adapter-websockets/websocket-adapter.utils.d.ts.map +1 -1
  19. package/dist/index.d.ts +1 -0
  20. package/dist/index.d.ts.map +1 -1
  21. package/dist/index.mjs +153 -32
  22. package/dist/index.mjs.map +1 -1
  23. package/dist/sdk/index.d.ts +2 -0
  24. package/dist/sdk/index.d.ts.map +1 -0
  25. package/dist/sdk/sdk.d.ts +70 -0
  26. package/dist/sdk/sdk.d.ts.map +1 -0
  27. package/dist/socket/index.d.ts +1 -0
  28. package/dist/socket/index.d.ts.map +1 -1
  29. package/dist/socket/socket.create.d.ts +5 -0
  30. package/dist/socket/socket.create.d.ts.map +1 -0
  31. package/package.json +1 -1
  32. package/src/adapter/adapter.bindings.ts +15 -6
  33. package/src/adapter-sse/sse-adapter.ts +6 -14
  34. package/src/adapter-sse/sse-adapter.utils.ts +8 -7
  35. package/src/adapter-websockets/websocket-adapter.utils.ts +5 -4
  36. package/src/index.ts +1 -0
  37. package/src/sdk/index.ts +1 -0
  38. package/src/sdk/sdk.ts +268 -0
  39. package/src/socket/index.ts +1 -0
  40. package/src/socket/socket.create.ts +10 -0
  41. package/vite.config.ts +1 -0
@@ -0,0 +1,240 @@
1
+ /**
2
+ * @vitest-environment node
3
+ */
4
+ import { Socket } from "@hyper-fetch/sockets";
5
+ import { createWebsocketE2EServer, sleep, waitForConnection } from "@hyper-fetch/testing";
6
+
7
+ describe("E2E [ WebSocket Reconnection ]", () => {
8
+ it("should reconnect after server abnormal close", async () => {
9
+ const { startServer, stopServer, terminateAllClients } = createWebsocketE2EServer();
10
+ const url = await startServer();
11
+
12
+ const socket = new Socket({ url, reconnectTime: 200 });
13
+ await waitForConnection(socket);
14
+
15
+ let reconnectCount = 0;
16
+ socket.onReconnect(() => {
17
+ reconnectCount += 1;
18
+ });
19
+
20
+ terminateAllClients();
21
+ await sleep(500);
22
+
23
+ await waitForConnection(socket, 3000);
24
+
25
+ expect(reconnectCount).toBeGreaterThanOrEqual(1);
26
+ expect(socket.adapter.connected).toBe(true);
27
+
28
+ await socket.disconnect();
29
+ await stopServer();
30
+ });
31
+
32
+ it("should respect reconnectTime delay", async () => {
33
+ const { startServer, stopServer, terminateAllClients } = createWebsocketE2EServer();
34
+ const url = await startServer();
35
+
36
+ const reconnectTime = 500;
37
+ const socket = new Socket({ url, reconnectTime });
38
+ await waitForConnection(socket);
39
+
40
+ const timestamps: number[] = [];
41
+ socket.events.onReconnecting(() => {
42
+ timestamps.push(Date.now());
43
+ });
44
+
45
+ terminateAllClients();
46
+ await sleep(reconnectTime + 300);
47
+
48
+ expect(timestamps.length).toBeGreaterThanOrEqual(1);
49
+
50
+ await socket.disconnect();
51
+ await stopServer();
52
+ });
53
+
54
+ it("should stop reconnecting after reconnectAttempts limit", async () => {
55
+ const wsServer = createWebsocketE2EServer();
56
+ const url = await wsServer.startServer();
57
+
58
+ const socket = new Socket({ url, reconnect: 2, reconnectTime: 200 });
59
+ await waitForConnection(socket);
60
+
61
+ let reconnectFailedFired = false;
62
+ let reconnectCount = 0;
63
+ socket.onReconnect(() => {
64
+ reconnectCount += 1;
65
+ });
66
+ socket.onReconnectFailed(() => {
67
+ reconnectFailedFired = true;
68
+ });
69
+
70
+ // Stop server completely so reconnect attempts fail
71
+ await wsServer.stopServer();
72
+ // Wait enough for: close detection + (reconnectTime * attempts) + overhead
73
+ await sleep(3000);
74
+
75
+ expect(reconnectFailedFired).toBe(true);
76
+ expect(reconnectCount).toBeGreaterThanOrEqual(1);
77
+ });
78
+
79
+ it("should reset attempt counter after successful reconnection", async () => {
80
+ const { startServer, stopServer, terminateAllClients } = createWebsocketE2EServer();
81
+ const url = await startServer();
82
+
83
+ const socket = new Socket({ url, reconnectTime: 200, reconnect: 5 });
84
+ await waitForConnection(socket);
85
+
86
+ let reconnectCount = 0;
87
+ socket.onReconnect(() => {
88
+ reconnectCount += 1;
89
+ });
90
+
91
+ // First disruption
92
+ terminateAllClients();
93
+ await sleep(600);
94
+ await waitForConnection(socket, 3000);
95
+ const firstRoundReconnects = reconnectCount;
96
+
97
+ expect(socket.adapter.connected).toBe(true);
98
+ expect(socket.adapter.reconnectionAttempts).toBe(0);
99
+
100
+ // Second disruption - counter should have been reset
101
+ terminateAllClients();
102
+ await sleep(600);
103
+ await waitForConnection(socket, 3000);
104
+
105
+ expect(reconnectCount).toBeGreaterThan(firstRoundReconnects);
106
+ expect(socket.adapter.reconnectionAttempts).toBe(0);
107
+
108
+ await socket.disconnect();
109
+ await stopServer();
110
+ });
111
+
112
+ it("should recover after server restart", async () => {
113
+ const wsServer = createWebsocketE2EServer();
114
+ let url = await wsServer.startServer();
115
+
116
+ const socket = new Socket({ url, reconnectTime: 200, reconnect: 10 });
117
+ await waitForConnection(socket);
118
+
119
+ expect(socket.adapter.connected).toBe(true);
120
+
121
+ // Kill server
122
+ await wsServer.stopServer();
123
+ await sleep(300);
124
+
125
+ expect(socket.adapter.connected).toBe(false);
126
+
127
+ // Restart on same port is not guaranteed, so we update the URL
128
+ url = await wsServer.startServer();
129
+ // The socket will keep trying the old URL. If ports differ, it will fail.
130
+ // But since the server binds to port 0, we need a different approach.
131
+ // We'll just verify it reconnects when server comes back on same instance.
132
+
133
+ // Wait for reconnection
134
+ await sleep(1500);
135
+
136
+ // Connection may or may not succeed depending on port assignment
137
+ // The key behavior: socket attempted reconnection
138
+ expect(socket.adapter.reconnectionAttempts).toBeGreaterThanOrEqual(0);
139
+
140
+ await socket.disconnect();
141
+ await wsServer.stopServer();
142
+ });
143
+
144
+ it("should not reconnect when reconnect is set to 0", async () => {
145
+ const wsServer = createWebsocketE2EServer();
146
+ const url = await wsServer.startServer();
147
+
148
+ const socket = new Socket({ url, reconnect: 0, reconnectTime: 300 });
149
+ await waitForConnection(socket);
150
+
151
+ let reconnectFailedFired = false;
152
+ socket.onReconnectFailed(() => {
153
+ reconnectFailedFired = true;
154
+ });
155
+
156
+ // Stop server so reconnection attempt fails immediately
157
+ await wsServer.stopServer();
158
+ // Wait for: close detection + reconnectTime (300ms) + reconnect attempt + overhead
159
+ await sleep(2000);
160
+
161
+ // With reconnect: 0, the first reconnect attempt should immediately hit the limit
162
+ expect(reconnectFailedFired).toBe(true);
163
+ });
164
+
165
+ it("should handle manual reconnect() call", async () => {
166
+ const { startServer, stopServer } = createWebsocketE2EServer();
167
+ const url = await startServer();
168
+
169
+ const socket = new Socket({ url, adapterOptions: { autoConnect: false } });
170
+
171
+ await socket.connect();
172
+ await waitForConnection(socket);
173
+ expect(socket.adapter.connected).toBe(true);
174
+
175
+ let reconnectingFired = false;
176
+ socket.events.onReconnecting(() => {
177
+ reconnectingFired = true;
178
+ });
179
+
180
+ await socket.reconnect();
181
+ await sleep(300);
182
+ await waitForConnection(socket, 3000);
183
+
184
+ expect(reconnectingFired).toBe(true);
185
+ expect(socket.adapter.connected).toBe(true);
186
+
187
+ await socket.disconnect();
188
+ await stopServer();
189
+ });
190
+
191
+ it("should keep trying with reconnect: Infinity until server comes back", async () => {
192
+ const { startServer, stopServer, terminateAllClients } = createWebsocketE2EServer();
193
+ const url = await startServer();
194
+
195
+ const socket = new Socket({ url, reconnectTime: 100 }); // default reconnect: Infinity
196
+ await waitForConnection(socket);
197
+
198
+ let reconnectCount = 0;
199
+ socket.onReconnect(() => {
200
+ reconnectCount += 1;
201
+ });
202
+
203
+ terminateAllClients();
204
+ await sleep(1000);
205
+
206
+ // Should have attempted multiple reconnects
207
+ expect(reconnectCount).toBeGreaterThanOrEqual(1);
208
+
209
+ // Should eventually reconnect since server is still running
210
+ await waitForConnection(socket, 5000);
211
+ expect(socket.adapter.connected).toBe(true);
212
+
213
+ await socket.disconnect();
214
+ await stopServer();
215
+ });
216
+
217
+ it("should handle rapid server disruptions without crashing", async () => {
218
+ const { startServer, stopServer, terminateAllClients } = createWebsocketE2EServer();
219
+ const url = await startServer();
220
+
221
+ const socket = new Socket({ url, reconnectTime: 100 });
222
+ await waitForConnection(socket);
223
+
224
+ // Rapid disruptions
225
+ for (let i = 0; i < 3; i += 1) {
226
+ terminateAllClients();
227
+ // eslint-disable-next-line no-await-in-loop
228
+ await sleep(250);
229
+ }
230
+
231
+ // Wait for things to settle
232
+ await sleep(1000);
233
+
234
+ // Socket should either be connected or attempting to connect - no crash
235
+ expect(() => socket.adapter.connected).not.toThrow();
236
+
237
+ await socket.disconnect();
238
+ await stopServer();
239
+ });
240
+ });
@@ -0,0 +1,191 @@
1
+ /**
2
+ * @vitest-environment node
3
+ */
4
+ import { Socket, ServerSentEventsAdapter } from "@hyper-fetch/sockets";
5
+ import { createSseE2EServer, sleep, waitForConnection } from "@hyper-fetch/testing";
6
+
7
+ describe("E2E [ SSE Adapter ]", () => {
8
+ it("should connect to an SSE endpoint", async () => {
9
+ const { startServer, stopServer, waitForClient } = createSseE2EServer();
10
+ const url = await startServer();
11
+
12
+ const socket = new Socket({
13
+ url,
14
+ adapter: ServerSentEventsAdapter,
15
+ });
16
+
17
+ await waitForClient();
18
+ await waitForConnection(socket, 5000);
19
+
20
+ expect(socket.adapter.connected).toBe(true);
21
+
22
+ await socket.disconnect();
23
+ await stopServer();
24
+ });
25
+
26
+ it("should receive SSE events by topic", async () => {
27
+ const { startServer, stopServer, sendEvent, waitForClient } = createSseE2EServer();
28
+ const url = await startServer();
29
+
30
+ const socket = new Socket({
31
+ url,
32
+ adapter: ServerSentEventsAdapter,
33
+ });
34
+
35
+ await waitForClient();
36
+ await waitForConnection(socket, 5000);
37
+
38
+ const listener = socket.createListener<{ name: string }>()({ topic: "user-update" });
39
+ const received: any[] = [];
40
+ listener.listen(({ data }) => received.push(data));
41
+
42
+ await sleep(50);
43
+ sendEvent("user-update", { name: "Alice" });
44
+ await sleep(300);
45
+
46
+ expect(received).toHaveLength(1);
47
+ expect(received[0]).toStrictEqual({ name: "Alice" });
48
+
49
+ await socket.disconnect();
50
+ await stopServer();
51
+ });
52
+
53
+ it("should throw when trying to emit on SSE", async () => {
54
+ const { startServer, stopServer, waitForClient } = createSseE2EServer();
55
+ const url = await startServer();
56
+
57
+ const socket = new Socket({
58
+ url,
59
+ adapter: ServerSentEventsAdapter,
60
+ });
61
+
62
+ await waitForClient();
63
+ await waitForConnection(socket, 5000);
64
+
65
+ const emitter = socket.createEmitter<{ v: number }>()({ topic: "test" });
66
+
67
+ // Emitter.emit() calls adapter.emit() without awaiting, so the error
68
+ // surfaces as an unhandled rejection. Catch it explicitly.
69
+ let errorCaught = false;
70
+ try {
71
+ await (socket.adapter as any).emit(emitter.setPayload({ v: 1 }));
72
+ } catch (error: any) {
73
+ errorCaught = true;
74
+ expect(error.message).toBe("Cannot emit events in SSE adapter");
75
+ }
76
+ expect(errorCaught).toBe(true);
77
+
78
+ await socket.disconnect();
79
+ await stopServer();
80
+ });
81
+
82
+ it("should disconnect cleanly", async () => {
83
+ const { startServer, stopServer, waitForClient } = createSseE2EServer();
84
+ const url = await startServer();
85
+
86
+ const socket = new Socket({
87
+ url,
88
+ adapter: ServerSentEventsAdapter,
89
+ });
90
+
91
+ await waitForClient();
92
+ await waitForConnection(socket, 5000);
93
+
94
+ expect(socket.adapter.connected).toBe(true);
95
+
96
+ let disconnectedFired = false;
97
+ socket.events.onDisconnected(() => {
98
+ disconnectedFired = true;
99
+ });
100
+
101
+ await socket.disconnect();
102
+ await sleep(100);
103
+
104
+ expect(socket.adapter.connected).toBe(false);
105
+ expect(disconnectedFired).toBe(true);
106
+
107
+ await stopServer();
108
+ });
109
+
110
+ it("should reconnect via reconnectTime when initial connection fails", async () => {
111
+ // Start server, get URL, then stop it so initial connect fails
112
+ const sseServer = createSseE2EServer();
113
+ const url = await sseServer.startServer();
114
+ await sseServer.stopServer();
115
+
116
+ let reconnectFired = false;
117
+ const socket = new Socket({
118
+ url,
119
+ adapter: ServerSentEventsAdapter,
120
+ reconnectTime: 300,
121
+ reconnect: 2,
122
+ adapterOptions: { autoConnect: false },
123
+ });
124
+
125
+ socket.onReconnect(() => {
126
+ reconnectFired = true;
127
+ });
128
+
129
+ // Connect to a dead server - should trigger reconnectTime timeout
130
+ socket.connect();
131
+ await sleep(1000);
132
+
133
+ expect(reconnectFired).toBe(true);
134
+
135
+ await socket.disconnect();
136
+ });
137
+
138
+ it("should support multiple listeners on different topics", async () => {
139
+ const { startServer, stopServer, sendEvent, waitForClient } = createSseE2EServer();
140
+ const url = await startServer();
141
+
142
+ const socket = new Socket({
143
+ url,
144
+ adapter: ServerSentEventsAdapter,
145
+ });
146
+
147
+ await waitForClient();
148
+ await waitForConnection(socket, 5000);
149
+
150
+ const usersData: any[] = [];
151
+ const ordersData: any[] = [];
152
+
153
+ socket
154
+ .createListener<{ id: number }>()({ topic: "users" })
155
+ .listen(({ data }) => usersData.push(data));
156
+ socket
157
+ .createListener<{ orderId: string }>()({ topic: "orders" })
158
+ .listen(({ data }) => ordersData.push(data));
159
+
160
+ await sleep(50);
161
+ sendEvent("users", { id: 1 });
162
+ sendEvent("orders", { orderId: "o1" });
163
+ sendEvent("users", { id: 2 });
164
+ await sleep(300);
165
+
166
+ expect(usersData).toStrictEqual([{ id: 1 }, { id: 2 }]);
167
+ expect(ordersData).toStrictEqual([{ orderId: "o1" }]);
168
+
169
+ await socket.disconnect();
170
+ await stopServer();
171
+ });
172
+
173
+ it("should pass query params in the SSE URL", async () => {
174
+ const { startServer, stopServer, waitForClient } = createSseE2EServer();
175
+ const url = await startServer();
176
+
177
+ const socket = new Socket({
178
+ url,
179
+ adapter: ServerSentEventsAdapter,
180
+ queryParams: { token: "xyz", channel: "main" },
181
+ });
182
+
183
+ await waitForClient();
184
+ await waitForConnection(socket, 5000);
185
+
186
+ expect(socket.adapter.connected).toBe(true);
187
+
188
+ await socket.disconnect();
189
+ await stopServer();
190
+ });
191
+ });
@@ -59,7 +59,7 @@ describe("Socket SSE [ Connection ]", () => {
59
59
  startNewServer();
60
60
 
61
61
  await waitFor(() => {
62
- expect(spy3).toHaveBeenCalledTimes(3);
62
+ expect(spy3).toHaveBeenCalledTimes(4);
63
63
  expect(spy).toHaveBeenCalledTimes(1);
64
64
  expect(spy2).toHaveBeenCalledTimes(1);
65
65
  });
@@ -0,0 +1,125 @@
1
+ import type { SocketInstance } from "socket";
2
+ import { Listener } from "listener";
3
+ import type { ListenerInstance } from "listener";
4
+ import { Emitter } from "emitter";
5
+ import type { EmitterInstance } from "emitter";
6
+ import { createSocketSdk } from "sdk";
7
+ import { createSocket } from "../../utils/socket.utils";
8
+
9
+ type TestSocket = SocketInstance;
10
+
11
+ type TestSchema = {
12
+ chat: {
13
+ messages: {
14
+ $listener: ListenerInstance<{
15
+ response: { text: string; user: string };
16
+ topic: "chat/messages";
17
+ socket: TestSocket;
18
+ }>;
19
+ $emitter: EmitterInstance<{
20
+ payload: { text: string };
21
+ topic: "chat/messages";
22
+ socket: TestSocket;
23
+ }>;
24
+ };
25
+ $roomId: {
26
+ $listener: ListenerInstance<{
27
+ response: { text: string; user: string };
28
+ topic: "chat/:roomId";
29
+ socket: TestSocket;
30
+ }>;
31
+ };
32
+ };
33
+ notifications: {
34
+ $listener: ListenerInstance<{
35
+ response: { message: string };
36
+ topic: "notifications";
37
+ socket: TestSocket;
38
+ }>;
39
+ };
40
+ };
41
+
42
+ describe("Socket SDK [ Base ]", () => {
43
+ let socket: TestSocket;
44
+
45
+ beforeEach(() => {
46
+ socket = createSocket();
47
+ });
48
+
49
+ it("should create a socket SDK", () => {
50
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
51
+ expect(sdk).toBeDefined();
52
+ });
53
+
54
+ it("should create a listener from the SDK", () => {
55
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
56
+ const listener = sdk.chat.messages.$listener;
57
+ expect(listener).toBeInstanceOf(Listener);
58
+ });
59
+
60
+ it("should create an emitter from the SDK", () => {
61
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
62
+ const emitter = sdk.chat.messages.$emitter;
63
+ expect(emitter).toBeInstanceOf(Emitter);
64
+ });
65
+
66
+ it("should build correct topic for flat paths", () => {
67
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
68
+ const listener = sdk.notifications.$listener;
69
+ expect(listener.topic).toBe("notifications");
70
+ });
71
+
72
+ it("should build correct topic for nested paths", () => {
73
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
74
+ const listener = sdk.chat.messages.$listener;
75
+ expect(listener.topic).toBe("chat/messages");
76
+ });
77
+
78
+ it("should build correct topic with parameter segments", () => {
79
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
80
+ const listener = sdk.chat.$roomId.$listener;
81
+ expect(listener.topic).toBe("chat/:roomId");
82
+ });
83
+
84
+ it("should allow setParams on a listener with params", () => {
85
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
86
+ const listener = sdk.chat.$roomId.$listener.setParams({ roomId: "abc" });
87
+ expect(listener.topic).toBe("chat/abc");
88
+ });
89
+
90
+ it("should allow setPayload on an emitter", () => {
91
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
92
+ const emitter = sdk.chat.messages.$emitter.setPayload({ text: "hello" });
93
+ expect(emitter.payload).toStrictEqual({ text: "hello" });
94
+ });
95
+
96
+ it("should return undefined for symbol keys", () => {
97
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
98
+ const sym = Symbol("test");
99
+ expect((sdk as any)[sym]).toBeUndefined();
100
+ });
101
+
102
+ it("should return undefined for inspect key", () => {
103
+ const sdk = createSocketSdk<TestSocket, TestSchema>(socket);
104
+ expect((sdk as any).inspect).toBeUndefined();
105
+ });
106
+
107
+ it("should handle camelCase to kebab-case conversion", () => {
108
+ type KebabSchema = {
109
+ someChannel: {
110
+ $listener: ListenerInstance<{
111
+ response: any;
112
+ topic: "some-channel";
113
+ socket: TestSocket;
114
+ }>;
115
+ };
116
+ };
117
+
118
+ const sdk = createSocketSdk<TestSocket, KebabSchema>(socket, {
119
+ camelCaseToKebabCase: true,
120
+ });
121
+
122
+ const listener = sdk.someChannel.$listener;
123
+ expect(listener.topic).toBe("some-channel");
124
+ });
125
+ });