@hyper-fetch/sockets 9.0.3 → 9.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 (46) hide show
  1. package/__tests__/e2e/e2e.delivery.spec.ts +81 -0
  2. package/__tests__/features/delivery/delivery.batch.spec.ts +203 -0
  3. package/__tests__/features/delivery/delivery.latest.spec.ts +254 -0
  4. package/__tests__/features/delivery/delivery.typescript.spec.ts +143 -0
  5. package/__tests__/features/delivery/delivery.utils.spec.ts +122 -0
  6. package/__tests__/features/listener/listener.delivery.spec.ts +385 -0
  7. package/__tests__/features/listener/listener.delivery.sse.spec.ts +55 -0
  8. package/__tests__/features/sdk/sdk.configuration.spec.ts +60 -0
  9. package/__tests__/features/sdk/sdk.types.spec.ts +41 -17
  10. package/dist/delivery/delivery.batch.d.ts +19 -0
  11. package/dist/delivery/delivery.batch.d.ts.map +1 -0
  12. package/dist/delivery/delivery.latest.d.ts +18 -0
  13. package/dist/delivery/delivery.latest.d.ts.map +1 -0
  14. package/dist/delivery/delivery.types.d.ts +113 -0
  15. package/dist/delivery/delivery.types.d.ts.map +1 -0
  16. package/dist/delivery/delivery.utils.d.ts +50 -0
  17. package/dist/delivery/delivery.utils.d.ts.map +1 -0
  18. package/dist/delivery/index.d.ts +5 -0
  19. package/dist/delivery/index.d.ts.map +1 -0
  20. package/dist/index.d.ts +1 -0
  21. package/dist/index.d.ts.map +1 -1
  22. package/dist/index.mjs +198 -4
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/listener/listener.d.ts +22 -7
  25. package/dist/listener/listener.d.ts.map +1 -1
  26. package/dist/listener/listener.types.d.ts +29 -9
  27. package/dist/listener/listener.types.d.ts.map +1 -1
  28. package/dist/sdk/sdk.d.ts +6 -2
  29. package/dist/sdk/sdk.d.ts.map +1 -1
  30. package/dist/socket/socket.d.ts +2 -1
  31. package/dist/socket/socket.d.ts.map +1 -1
  32. package/dist/types/extract.types.d.ts +10 -4
  33. package/dist/types/extract.types.d.ts.map +1 -1
  34. package/package.json +1 -1
  35. package/src/delivery/delivery.batch.ts +71 -0
  36. package/src/delivery/delivery.latest.ts +64 -0
  37. package/src/delivery/delivery.types.ts +129 -0
  38. package/src/delivery/delivery.utils.ts +96 -0
  39. package/src/delivery/index.ts +4 -0
  40. package/src/index.ts +1 -0
  41. package/src/listener/listener.ts +48 -9
  42. package/src/listener/listener.types.ts +45 -10
  43. package/src/sdk/sdk.ts +27 -7
  44. package/src/socket/socket.ts +8 -2
  45. package/src/types/extract.types.ts +10 -4
  46. package/tsconfig.json +2 -0
@@ -20,28 +20,28 @@ type ChatMessage = { text: string; user: string };
20
20
  describe("ListenerModel - defaults for omitted fields", () => {
21
21
  it("should default response to unknown", () => {
22
22
  type L = ListenerModel<{ topic: "chat/messages" }>;
23
- type Response = L extends Listener<infer R, any, any, any> ? R : never;
23
+ type Response = L extends Listener<infer R, any, any, any, any> ? R : never;
24
24
  expectTypeOf<Response>().toEqualTypeOf<unknown>();
25
25
  expect(true).toBe(true);
26
26
  });
27
27
 
28
28
  it("should default topic to string when not provided", () => {
29
29
  type L = ListenerModel<{ response: ChatMessage }>;
30
- type Topic = L extends Listener<any, infer T, any, any> ? T : never;
30
+ type Topic = L extends Listener<any, infer T, any, any, any> ? T : never;
31
31
  expectTypeOf<Topic>().toEqualTypeOf<string>();
32
32
  expect(true).toBe(true);
33
33
  });
34
34
 
35
35
  it("should default socket to SocketInstance when not provided", () => {
36
36
  type L = ListenerModel<{ response: ChatMessage; topic: "chat" }>;
37
- type Sock = L extends Listener<any, any, infer S, any> ? S : never;
37
+ type Sock = L extends Listener<any, any, infer S, any, any> ? S : never;
38
38
  expectTypeOf<Sock>().toEqualTypeOf<SocketInstance>();
39
39
  expect(true).toBe(true);
40
40
  });
41
41
 
42
42
  it("should default hasParams to false", () => {
43
43
  type L = ListenerModel<{ topic: "chat" }>;
44
- type HasParams = L extends Listener<any, any, any, infer Hp> ? Hp : never;
44
+ type HasParams = L extends Listener<any, any, any, infer Hp, any> ? Hp : never;
45
45
  expectTypeOf<HasParams>().toEqualTypeOf<false>();
46
46
  expect(true).toBe(true);
47
47
  });
@@ -82,8 +82,8 @@ describe("EmitterModel - defaults for omitted fields", () => {
82
82
  describe("ListenerModel / EmitterModel - user-provided fields override defaults", () => {
83
83
  it("should narrow response and topic on a Listener when provided", () => {
84
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;
85
+ type Response = L extends Listener<infer R, any, any, any, any> ? R : never;
86
+ type Topic = L extends Listener<any, infer T, any, any, any> ? T : never;
87
87
  expectTypeOf<Response>().toEqualTypeOf<ChatMessage>();
88
88
  expectTypeOf<Topic>().toEqualTypeOf<"chat/messages">();
89
89
  expect(true).toBe(true);
@@ -102,7 +102,7 @@ describe("ListenerModel / EmitterModel - user-provided fields override defaults"
102
102
  describe("ListenerInstance / EmitterInstance - keep `any` defaults (constraint use)", () => {
103
103
  it("should keep ListenerInstance wide so concrete listeners satisfy it", () => {
104
104
  type LI = ListenerInstance;
105
- type Response = LI extends Listener<infer R, any, any, any> ? R : never;
105
+ type Response = LI extends Listener<infer R, any, any, any, any> ? R : never;
106
106
  expectTypeOf<Response>().toEqualTypeOf<any>();
107
107
  expect(true).toBe(true);
108
108
  });
@@ -126,7 +126,7 @@ describe("InjectSocket - schema-level socket injection", () => {
126
126
  $listener: ListenerModel<{ response: ChatMessage; topic: "chat" }>;
127
127
  };
128
128
  type Injected = InjectSocket<Schema, TestSocket>;
129
- type ResolvedSocket = Injected["$listener"] extends Listener<any, any, infer S, any> ? S : never;
129
+ type ResolvedSocket = Injected["$listener"] extends Listener<any, any, infer S, any, any> ? S : never;
130
130
  expectTypeOf<ResolvedSocket>().toEqualTypeOf<TestSocket>();
131
131
  expect(true).toBe(true);
132
132
  });
@@ -155,9 +155,10 @@ describe("InjectSocket - schema-level socket injection", () => {
155
155
  };
156
156
  type Injected = InjectSocket<Schema, TestSocket>;
157
157
 
158
- type LSocket = Injected["chat"]["messages"]["$listener"] extends Listener<any, any, infer S, any> ? S : never;
158
+ type LSocket = Injected["chat"]["messages"]["$listener"] extends Listener<any, any, infer S, any, any> ? S : never;
159
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;
160
+ type NestedLSocket =
161
+ Injected["chat"]["$roomId"]["$listener"] extends Listener<any, any, infer S, any, any> ? S : never;
161
162
 
162
163
  expectTypeOf<LSocket>().toEqualTypeOf<TestSocket>();
163
164
  expectTypeOf<ESocket>().toEqualTypeOf<TestSocket>();
@@ -174,8 +175,8 @@ describe("InjectSocket - schema-level socket injection", () => {
174
175
  };
175
176
  type Injected = InjectSocket<Schema, TestSocket>;
176
177
 
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;
178
+ type LResp = Injected["chat"]["$listener"] extends Listener<infer R, any, any, any, any> ? R : never;
179
+ type LTopic = Injected["chat"]["$listener"] extends Listener<any, infer T, any, any, any> ? T : never;
179
180
  type EPayload = Injected["chat"]["$emitter"] extends Emitter<infer P, any, any, any, any> ? P : never;
180
181
  type ETopic = Injected["chat"]["$emitter"] extends Emitter<any, infer T, any, any, any> ? T : never;
181
182
 
@@ -205,9 +206,9 @@ describe("createSocketSdk - produces a fully resolved SDK type", () => {
205
206
  const sdk = createSocketSdk<typeof socket, Schema>(socket);
206
207
 
207
208
  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;
209
+ type ResolvedSocket = ChatListener extends Listener<any, any, infer S, any, any> ? S : never;
210
+ type ResolvedResponse = ChatListener extends Listener<infer R, any, any, any, any> ? R : never;
211
+ type ResolvedTopic = ChatListener extends Listener<any, infer T, any, any, any> ? T : never;
211
212
 
212
213
  expectTypeOf<ResolvedSocket>().toEqualTypeOf<typeof socket>();
213
214
  expectTypeOf<ResolvedResponse>().toEqualTypeOf<ChatMessage>();
@@ -233,8 +234,8 @@ describe("createSocketSdk - produces a fully resolved SDK type", () => {
233
234
  const sdk = createSocketSdk<typeof socket, Schema>(socket);
234
235
 
235
236
  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;
237
+ type ResolvedSocket = RoomListener extends Listener<any, any, infer S, any, any> ? S : never;
238
+ type ResolvedTopic = RoomListener extends Listener<any, infer T, any, any, any> ? T : never;
238
239
 
239
240
  expectTypeOf<ResolvedSocket>().toEqualTypeOf<typeof socket>();
240
241
  expectTypeOf<ResolvedTopic>().toEqualTypeOf<"chat/:roomId">();
@@ -301,3 +302,26 @@ describe("$configure - dot-path callback narrowing", () => {
301
302
  expect(true).toBe(true);
302
303
  });
303
304
  });
305
+
306
+ describe("ListenerModel - delivered type", () => {
307
+ it("should default delivered to response", () => {
308
+ type L = ListenerModel<{ response: ChatMessage; topic: "chat/messages" }>;
309
+ type Delivered = L extends Listener<any, any, any, any, infer D> ? D : never;
310
+ expectTypeOf<Delivered>().toEqualTypeOf<ChatMessage>();
311
+ expect(true).toBe(true);
312
+ });
313
+
314
+ it("should keep an explicit delivered type through InjectSocket", () => {
315
+ type Schema = {
316
+ trades: {
317
+ $listener: ListenerModel<{ response: ChatMessage; topic: "trades"; delivered: ChatMessage[] }>;
318
+ };
319
+ };
320
+ type Injected = InjectSocket<Schema, TestSocket>;
321
+ type Delivered = Injected["trades"]["$listener"] extends Listener<any, any, any, any, infer D> ? D : never;
322
+ type Response = Injected["trades"]["$listener"] extends Listener<infer R, any, any, any, any> ? R : never;
323
+ expectTypeOf<Delivered>().toEqualTypeOf<ChatMessage[]>();
324
+ expectTypeOf<Response>().toEqualTypeOf<ChatMessage>();
325
+ expect(true).toBe(true);
326
+ });
327
+ });
@@ -0,0 +1,19 @@
1
+ import { BatchDeliveryType, DeliveryStrategyType } from '.';
2
+ /**
3
+ * Creates the built-in `batch` strategy.
4
+ *
5
+ * Timeline for `interval: 100` with messages A, B, C at 0/20/40ms and D at 300ms:
6
+ * ```
7
+ * t=0 push(A) buffer=[A], open 100ms window
8
+ * t=20 push(B) buffer=[A, B]
9
+ * t=40 push(C) buffer=[A, B, C]
10
+ * t=100 window closes → deliver([A, B, C])
11
+ * t=300 push(D) buffer=[D], open window
12
+ * t=400 window closes → deliver([D])
13
+ * ```
14
+ *
15
+ * The delivered `extra` is the one of the last message in the batch.
16
+ * Exported so custom strategies can compose it.
17
+ */
18
+ export declare const createBatchDeliveryStrategy: <Data, Extra = any>({ interval, maxSize, }: Omit<BatchDeliveryType, "strategy">) => DeliveryStrategyType<Data, Data[], Extra>;
19
+ //# sourceMappingURL=delivery.batch.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"delivery.batch.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery.batch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,GAAI,IAAI,EAAE,KAAK,GAAG,GAAG,EAAE,wBAG5D,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,KAAG,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,CAiDhF,CAAC"}
@@ -0,0 +1,18 @@
1
+ import { DeliveryStrategyType, LatestDeliveryType } from '.';
2
+ /**
3
+ * Creates the built-in `latest` (sampling) strategy.
4
+ *
5
+ * Timeline for `interval: 100` with messages A, B, C at 0/20/40ms and D at 300ms:
6
+ * ```
7
+ * t=0 push(A) idle → deliver(A) immediately, open 100ms window
8
+ * t=20 push(B) pending = B
9
+ * t=40 push(C) pending = C (B is dropped)
10
+ * t=100 window closes → deliver(C), open next window
11
+ * t=200 window closes → nothing pending → idle
12
+ * t=300 push(D) idle → deliver(D) immediately
13
+ * ```
14
+ *
15
+ * Exported so custom strategies can compose it.
16
+ */
17
+ export declare const createLatestDeliveryStrategy: <Data, Extra = any>({ interval, leading, }: Omit<LatestDeliveryType, "strategy">) => DeliveryStrategyType<Data, Data, Extra>;
18
+ //# sourceMappingURL=delivery.latest.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"delivery.latest.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery.latest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9F;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,GAAI,IAAI,EAAE,KAAK,GAAG,GAAG,EAAE,wBAG7D,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,KAAG,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CA2C/E,CAAC"}
@@ -0,0 +1,113 @@
1
+ import { SocketAdapterInstance } from '../adapter';
2
+ import { ExtractAdapterExtraType } from '../types';
3
+ /**
4
+ * A single message flowing through a delivery strategy.
5
+ *
6
+ * `data` is the payload, `extra` is adapter-specific metadata (for the WebSocket adapter it is the raw `MessageEvent`).
7
+ */
8
+ export type DeliveryMessageType<Data, Extra = any> = {
9
+ data: Data;
10
+ extra: Extra;
11
+ };
12
+ /**
13
+ * The object a delivery strategy returns for a single `listen()` subscription.
14
+ *
15
+ * Think of it as a tiny pipe: `push` is the input (every raw message lands here), `deliver` from the
16
+ * {@link DeliveryStrategyContextType} is the output, and `dispose` is the cleanup.
17
+ */
18
+ export type DeliveryControllerType<Input, Extra = any> = {
19
+ /**
20
+ * Receives every raw message of the subscription. The strategy decides if and when to call `deliver`.
21
+ */
22
+ push: (message: DeliveryMessageType<Input, Extra>) => void;
23
+ /**
24
+ * Called when the subscription ends (`unlisten()` / component unmount). Clear timers and drop pending
25
+ * state here. Nothing may be delivered after `dispose` was called. Must be safe to call more than once.
26
+ */
27
+ dispose: () => void;
28
+ };
29
+ /**
30
+ * Context handed to a delivery strategy when a subscription starts.
31
+ */
32
+ export type DeliveryStrategyContextType<Output, Extra = any> = {
33
+ /**
34
+ * Hands a (possibly aggregated) message to the user's `listen` callback.
35
+ */
36
+ deliver: (message: DeliveryMessageType<Output, Extra>) => void;
37
+ };
38
+ /**
39
+ * A custom delivery strategy. It is a factory invoked once per `listen()` call, so every subscription
40
+ * owns its own timers and buffers.
41
+ *
42
+ * `Input` is the raw message type (the listener's response type), `Output` is what `listen` callbacks
43
+ * receive. Use {@link createDeliveryStrategy} to author one with full type inference.
44
+ *
45
+ * @example
46
+ * ```ts
47
+ * // Deliver after 50ms of silence (debounce)
48
+ * const settle = createDeliveryStrategy<Tick>(({ deliver }) => {
49
+ * let timer: ReturnType<typeof setTimeout> | undefined;
50
+ * let last: DeliveryMessageType<Tick> | undefined;
51
+ * return {
52
+ * push: (message) => {
53
+ * last = message;
54
+ * clearTimeout(timer);
55
+ * timer = setTimeout(() => {
56
+ * if (last) deliver(last);
57
+ * last = undefined;
58
+ * }, 50);
59
+ * },
60
+ * dispose: () => {
61
+ * clearTimeout(timer);
62
+ * last = undefined;
63
+ * },
64
+ * };
65
+ * });
66
+ * ```
67
+ */
68
+ export type DeliveryStrategyType<Input, Output = Input, Extra = any> = (context: DeliveryStrategyContextType<Output, Extra>) => DeliveryControllerType<Input, Extra>;
69
+ /**
70
+ * Sampling delivery. The first message of an idle period is delivered immediately (when `leading` is `true`),
71
+ * then at most one message per `interval` is delivered - always the most recent one. Intermediate messages
72
+ * are dropped. Best for state-like data (prices, positions, cursors) where only the newest value matters.
73
+ */
74
+ export type LatestDeliveryType = {
75
+ strategy: "latest";
76
+ /** Minimum time in milliseconds between two deliveries. */
77
+ interval: number;
78
+ /**
79
+ * Deliver the first message of an idle period immediately instead of waiting for the interval to pass.
80
+ * @default true
81
+ */
82
+ leading?: boolean;
83
+ };
84
+ /**
85
+ * Batching delivery. The first message opens a window of `interval` milliseconds; when it closes, every
86
+ * message collected in it is delivered at once as an array, in arrival order. Nothing is dropped.
87
+ * Best for event-like data (trades, chat messages, logs) where every message must be processed.
88
+ */
89
+ export type BatchDeliveryType = {
90
+ strategy: "batch";
91
+ /** Window length in milliseconds, measured from the first message of a batch. */
92
+ interval: number;
93
+ /** Deliver early as soon as this many messages were collected. Defaults to no limit. */
94
+ maxSize?: number;
95
+ };
96
+ /** Built-in, serializable delivery presets. */
97
+ export type DeliveryPresetType = LatestDeliveryType | BatchDeliveryType;
98
+ /**
99
+ * Everything accepted by the listener `delivery` option: a built-in preset or a custom strategy.
100
+ */
101
+ export type ListenerDeliveryType<Response = any, Adapter extends SocketAdapterInstance = SocketAdapterInstance> = DeliveryPresetType | DeliveryStrategyType<Response, any, ExtractAdapterExtraType<Adapter>>;
102
+ /**
103
+ * Resolves what `listen` callbacks receive for a given `delivery` configuration.
104
+ *
105
+ * - no delivery → `Response`
106
+ * - `{ strategy: "latest" }` → `Response`
107
+ * - `{ strategy: "batch" }` → `Response[]`
108
+ * - custom strategy → its `Output` type
109
+ */
110
+ export type ResolveDeliveredType<Response, Delivery> = [Delivery] extends [undefined] ? Response : Delivery extends DeliveryStrategyType<any, infer Output, any> ? Output : Delivery extends {
111
+ strategy: "batch";
112
+ } ? Response[] : Response;
113
+ //# sourceMappingURL=delivery.types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"delivery.types.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,OAAO,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,IAAI,EAAE,KAAK,GAAG,GAAG,IAAI;IACnD,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,GAAG,IAAI;IACvD;;OAEG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;IAC3D;;;OAGG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,2BAA2B,CAAC,MAAM,EAAE,KAAK,GAAG,GAAG,IAAI;IAC7D;;OAEG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;CAChE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,KAAK,GAAG,GAAG,IAAI,CACrE,OAAO,EAAE,2BAA2B,CAAC,MAAM,EAAE,KAAK,CAAC,KAChD,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,+CAA+C;AAC/C,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,QAAQ,GAAG,GAAG,EAAE,OAAO,SAAS,qBAAqB,GAAG,qBAAqB,IAC1G,kBAAkB,GAClB,oBAAoB,CAAC,QAAQ,EAAE,GAAG,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,GACjF,QAAQ,GACR,QAAQ,SAAS,oBAAoB,CAAC,GAAG,EAAE,MAAM,MAAM,EAAE,GAAG,CAAC,GAC3D,MAAM,GACN,QAAQ,SAAS;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,GACpC,QAAQ,EAAE,GACV,QAAQ,CAAC"}
@@ -0,0 +1,50 @@
1
+ import { DeliveryControllerType, DeliveryPresetType, DeliveryStrategyContextType, DeliveryStrategyType, ListenerDeliveryType } from '.';
2
+ /**
3
+ * Typed identity helper for authoring custom delivery strategies.
4
+ *
5
+ * `Input` is the listener's response type, `Output` is what `listen` callbacks will receive. TypeScript cannot
6
+ * infer `Output` from how you call `deliver`, so declare it here - the same way `createListener<Response>()`
7
+ * declares the wire type.
8
+ *
9
+ * @example
10
+ * ```ts
11
+ * const summarize = createDeliveryStrategy<Tick, { count: number; last: Tick }>(({ deliver }) => {
12
+ * let count = 0;
13
+ * let last: Tick | undefined;
14
+ * let timer: ReturnType<typeof setTimeout> | undefined;
15
+ * return {
16
+ * push: ({ data, extra }) => {
17
+ * count += 1;
18
+ * last = data;
19
+ * timer ??= setTimeout(() => {
20
+ * timer = undefined;
21
+ * deliver({ data: { count, last: last! }, extra });
22
+ * count = 0;
23
+ * }, 1000);
24
+ * },
25
+ * dispose: () => clearTimeout(timer),
26
+ * };
27
+ * });
28
+ *
29
+ * const onTick = socket.createListener<Tick>()({ topic: "ticks", delivery: summarize });
30
+ * onTick.listen(({ data }) => data.count); // data: { count: number; last: Tick }
31
+ * ```
32
+ */
33
+ export declare const createDeliveryStrategy: <Input, Output = Input, Extra = any>(strategy: DeliveryStrategyType<Input, Output, Extra>) => DeliveryStrategyType<Input, Output, Extra>;
34
+ /** Narrows a `delivery` value to a custom strategy function. */
35
+ export declare const isDeliveryStrategy: (delivery: ListenerDeliveryType) => delivery is DeliveryStrategyType<any, any, any>;
36
+ /**
37
+ * Validates a `delivery` value. Throws for unknown presets so misconfiguration fails at listener creation,
38
+ * not on the first message.
39
+ */
40
+ export declare const assertDelivery: (delivery: ListenerDeliveryType) => void;
41
+ /**
42
+ * Instantiates a delivery controller for one `listen()` subscription.
43
+ */
44
+ export declare const createDeliveryController: <Input, Output, Extra>(delivery: DeliveryPresetType | DeliveryStrategyType<Input, any, Extra>, context: DeliveryStrategyContextType<Output, Extra>) => DeliveryControllerType<Input, Extra>;
45
+ /**
46
+ * Stable key describing a `delivery` value - presets by value, custom strategies by identity.
47
+ * Useful for memoization (e.g. React dependency arrays).
48
+ */
49
+ export declare const getDeliveryKey: (delivery?: ListenerDeliveryType) => string | DeliveryStrategyType<any>;
50
+ //# sourceMappingURL=delivery.utils.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"delivery.utils.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,sBAAsB,EACtB,kBAAkB,EAClB,2BAA2B,EAC3B,oBAAoB,EAEpB,oBAAoB,EACrB,MAAM,UAAU,CAAC;AAGlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,sBAAsB,GAAI,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,KAAK,GAAG,GAAG,EACvE,UAAU,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,KACnD,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAa,CAAC;AAE1D,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,GAAI,UAAU,oBAAoB,KAAG,QAAQ,IAAI,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAClF,CAAC;AAEjC;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,oBAAoB,KAAG,IAS/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,EAAE,MAAM,EAAE,KAAK,EAC3D,UAAU,kBAAkB,GAAG,oBAAoB,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,EACtE,SAAS,2BAA2B,CAAC,MAAM,EAAE,KAAK,CAAC,KAClD,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAUrC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,WAAW,oBAAoB,KAAG,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAQjG,CAAC"}
@@ -0,0 +1,5 @@
1
+ export * from './delivery.types';
2
+ export * from './delivery.latest';
3
+ export * from './delivery.batch';
4
+ export * from './delivery.utils';
5
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/delivery/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}
package/dist/index.d.ts CHANGED
@@ -2,6 +2,7 @@ export * from './socket';
2
2
  export * from './adapter';
3
3
  export * from './emitter';
4
4
  export * from './listener';
5
+ export * from './delivery';
5
6
  export * from './types';
6
7
  export * from './utils';
7
8
  export * from './adapter-websockets';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,OAAO,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,OAAO,CAAC"}
package/dist/index.mjs CHANGED
@@ -973,21 +973,204 @@ var require_events = /* @__PURE__ */ __commonJSMin(((exports, module) => {
973
973
  }
974
974
  }));
975
975
  //#endregion
976
+ //#region src/delivery/delivery.latest.ts
977
+ /**
978
+ * Creates the built-in `latest` (sampling) strategy.
979
+ *
980
+ * Timeline for `interval: 100` with messages A, B, C at 0/20/40ms and D at 300ms:
981
+ * ```
982
+ * t=0 push(A) idle → deliver(A) immediately, open 100ms window
983
+ * t=20 push(B) pending = B
984
+ * t=40 push(C) pending = C (B is dropped)
985
+ * t=100 window closes → deliver(C), open next window
986
+ * t=200 window closes → nothing pending → idle
987
+ * t=300 push(D) idle → deliver(D) immediately
988
+ * ```
989
+ *
990
+ * Exported so custom strategies can compose it.
991
+ */
992
+ var createLatestDeliveryStrategy = ({ interval, leading = true }) => {
993
+ return ({ deliver }) => {
994
+ let timer;
995
+ let pending;
996
+ let disposed = false;
997
+ const closeWindow = () => {
998
+ timer = void 0;
999
+ if (!pending) return;
1000
+ const message = pending;
1001
+ pending = void 0;
1002
+ timer = setTimeout(closeWindow, interval);
1003
+ deliver(message);
1004
+ };
1005
+ return {
1006
+ push: (message) => {
1007
+ if (disposed) return;
1008
+ if (timer === void 0) {
1009
+ timer = setTimeout(closeWindow, interval);
1010
+ if (leading) {
1011
+ deliver(message);
1012
+ return;
1013
+ }
1014
+ }
1015
+ pending = message;
1016
+ },
1017
+ dispose: () => {
1018
+ disposed = true;
1019
+ pending = void 0;
1020
+ if (timer !== void 0) clearTimeout(timer);
1021
+ timer = void 0;
1022
+ }
1023
+ };
1024
+ };
1025
+ };
1026
+ //#endregion
1027
+ //#region src/delivery/delivery.batch.ts
1028
+ /**
1029
+ * Creates the built-in `batch` strategy.
1030
+ *
1031
+ * Timeline for `interval: 100` with messages A, B, C at 0/20/40ms and D at 300ms:
1032
+ * ```
1033
+ * t=0 push(A) buffer=[A], open 100ms window
1034
+ * t=20 push(B) buffer=[A, B]
1035
+ * t=40 push(C) buffer=[A, B, C]
1036
+ * t=100 window closes → deliver([A, B, C])
1037
+ * t=300 push(D) buffer=[D], open window
1038
+ * t=400 window closes → deliver([D])
1039
+ * ```
1040
+ *
1041
+ * The delivered `extra` is the one of the last message in the batch.
1042
+ * Exported so custom strategies can compose it.
1043
+ */
1044
+ var createBatchDeliveryStrategy = ({ interval, maxSize = Infinity }) => {
1045
+ return ({ deliver }) => {
1046
+ let timer;
1047
+ let buffer = [];
1048
+ let lastExtra;
1049
+ let disposed = false;
1050
+ const flush = () => {
1051
+ if (timer !== void 0) clearTimeout(timer);
1052
+ timer = void 0;
1053
+ if (buffer.length === 0) return;
1054
+ const data = buffer;
1055
+ const extra = lastExtra;
1056
+ buffer = [];
1057
+ lastExtra = void 0;
1058
+ deliver({
1059
+ data,
1060
+ extra
1061
+ });
1062
+ };
1063
+ return {
1064
+ push: ({ data, extra }) => {
1065
+ if (disposed) return;
1066
+ buffer.push(data);
1067
+ lastExtra = extra;
1068
+ if (buffer.length >= maxSize) {
1069
+ flush();
1070
+ return;
1071
+ }
1072
+ if (timer === void 0) timer = setTimeout(flush, interval);
1073
+ },
1074
+ dispose: () => {
1075
+ disposed = true;
1076
+ buffer = [];
1077
+ lastExtra = void 0;
1078
+ if (timer !== void 0) clearTimeout(timer);
1079
+ timer = void 0;
1080
+ }
1081
+ };
1082
+ };
1083
+ };
1084
+ //#endregion
1085
+ //#region src/delivery/delivery.utils.ts
1086
+ /**
1087
+ * Typed identity helper for authoring custom delivery strategies.
1088
+ *
1089
+ * `Input` is the listener's response type, `Output` is what `listen` callbacks will receive. TypeScript cannot
1090
+ * infer `Output` from how you call `deliver`, so declare it here - the same way `createListener<Response>()`
1091
+ * declares the wire type.
1092
+ *
1093
+ * @example
1094
+ * ```ts
1095
+ * const summarize = createDeliveryStrategy<Tick, { count: number; last: Tick }>(({ deliver }) => {
1096
+ * let count = 0;
1097
+ * let last: Tick | undefined;
1098
+ * let timer: ReturnType<typeof setTimeout> | undefined;
1099
+ * return {
1100
+ * push: ({ data, extra }) => {
1101
+ * count += 1;
1102
+ * last = data;
1103
+ * timer ??= setTimeout(() => {
1104
+ * timer = undefined;
1105
+ * deliver({ data: { count, last: last! }, extra });
1106
+ * count = 0;
1107
+ * }, 1000);
1108
+ * },
1109
+ * dispose: () => clearTimeout(timer),
1110
+ * };
1111
+ * });
1112
+ *
1113
+ * const onTick = socket.createListener<Tick>()({ topic: "ticks", delivery: summarize });
1114
+ * onTick.listen(({ data }) => data.count); // data: { count: number; last: Tick }
1115
+ * ```
1116
+ */
1117
+ var createDeliveryStrategy = (strategy) => strategy;
1118
+ /** Narrows a `delivery` value to a custom strategy function. */
1119
+ var isDeliveryStrategy = (delivery) => typeof delivery === "function";
1120
+ /**
1121
+ * Validates a `delivery` value. Throws for unknown presets so misconfiguration fails at listener creation,
1122
+ * not on the first message.
1123
+ */
1124
+ var assertDelivery = (delivery) => {
1125
+ if (isDeliveryStrategy(delivery)) return;
1126
+ if (delivery.strategy !== "latest" && delivery.strategy !== "batch") throw new Error(`Unknown delivery strategy: ${String(delivery.strategy)}. Use "latest", "batch" or a custom strategy created with createDeliveryStrategy().`);
1127
+ };
1128
+ /**
1129
+ * Instantiates a delivery controller for one `listen()` subscription.
1130
+ */
1131
+ var createDeliveryController = (delivery, context) => {
1132
+ if (isDeliveryStrategy(delivery)) return delivery(context);
1133
+ const { strategy, ...options } = delivery;
1134
+ return (strategy === "latest" ? createLatestDeliveryStrategy(options) : createBatchDeliveryStrategy(options))(context);
1135
+ };
1136
+ /**
1137
+ * Stable key describing a `delivery` value - presets by value, custom strategies by identity.
1138
+ * Useful for memoization (e.g. React dependency arrays).
1139
+ */
1140
+ var getDeliveryKey = (delivery) => {
1141
+ if (!delivery) return "";
1142
+ if (isDeliveryStrategy(delivery)) return delivery;
1143
+ return JSON.stringify(delivery);
1144
+ };
1145
+ //#endregion
976
1146
  //#region src/listener/listener.ts
977
1147
  /**
978
1148
  * Represents a socket message listener bound to a specific topic. Use it to subscribe to
979
1149
  * typed messages from WebSocket or Server-Sent Events connections via the socket adapter.
1150
+ *
1151
+ * `Response` is the raw message type, `Delivered` is what `listen` callbacks receive. They differ only
1152
+ * when a `delivery` strategy changes the shape (e.g. `batch` delivers `Response[]`).
980
1153
  */
981
1154
  var Listener = class Listener {
982
1155
  topic;
983
1156
  params = void 0;
984
1157
  options = void 0;
1158
+ /**
1159
+ * How messages reach `listen` callbacks. Typed with `any` input on purpose - it keeps `Response`
1160
+ * covariant so partial `ListenerInstance<{ response: ... }>` constraints keep matching wider listeners.
1161
+ */
1162
+ delivery = void 0;
1163
+ /** Stored with an `any` response for the same covariance reason as `delivery`. */
1164
+ listenerOptions;
985
1165
  constructor(socket, listenerOptions) {
986
1166
  this.socket = socket;
987
1167
  this.listenerOptions = listenerOptions;
988
- const { topic, options } = listenerOptions;
1168
+ const { topic, options, delivery, params } = listenerOptions;
989
1169
  this.topic = topic;
990
1170
  this.options = options;
1171
+ this.params = params;
1172
+ this.delivery = delivery;
1173
+ if (delivery) assertDelivery(delivery);
991
1174
  }
992
1175
  /** Set adapter-specific listener options. */
993
1176
  setOptions(options) {
@@ -997,6 +1180,13 @@ var Listener = class Listener {
997
1180
  setParams(params) {
998
1181
  return this.clone({ params });
999
1182
  }
1183
+ /**
1184
+ * Set how messages are delivered to `listen` callbacks - a `latest` / `batch` preset or a custom strategy.
1185
+ * Pass `undefined` to restore immediate delivery. Returns a clone; the callback data type follows the strategy.
1186
+ */
1187
+ setDelivery(delivery) {
1188
+ return this.clone({ delivery });
1189
+ }
1000
1190
  /** Create a new listener instance with optional configuration overrides. */
1001
1191
  clone(options) {
1002
1192
  return new Listener(this.socket, {
@@ -1007,11 +1197,14 @@ var Listener = class Listener {
1007
1197
  }
1008
1198
  /** Start listening for messages on the configured topic. Returns a function to unsubscribe. */
1009
1199
  listen = (callback) => {
1010
- this.socket.adapter.listen(this, callback);
1200
+ const controller = this.delivery ? createDeliveryController(this.delivery, { deliver: callback }) : null;
1201
+ const adapterCallback = controller ? controller.push : callback;
1202
+ this.socket.adapter.listen(this, adapterCallback);
1011
1203
  const removeListener = () => {
1204
+ controller?.dispose();
1012
1205
  this.socket.adapter.removeListener({
1013
1206
  topic: this.topic,
1014
- callback
1207
+ callback: adapterCallback
1015
1208
  });
1016
1209
  };
1017
1210
  return removeListener;
@@ -1553,6 +1746,7 @@ var topicMatchesPattern = (topic, pattern) => {
1553
1746
  var applySocketObjectDefaults = (instance, config) => {
1554
1747
  let result = instance;
1555
1748
  if (config.options !== void 0) result = result.setOptions(config.options);
1749
+ if (config.delivery !== void 0 && result instanceof Listener) result = result.setDelivery(config.delivery);
1556
1750
  return result;
1557
1751
  };
1558
1752
  var applySocketDefaults = ({ instance, topic, sdkPath, defaults }) => {
@@ -1653,6 +1847,6 @@ var createSocketConfiguration = () => {
1653
1847
  return (defaults) => defaults;
1654
1848
  };
1655
1849
  //#endregion
1656
- export { Emitter, Listener, ServerSentEventsAdapter, Socket, SocketAdapter, WebsocketAdapter, createSocketClient, createSocketConfiguration, createSocketSdk, getAdapterBindings, getCloseKey, getConnectingKey, getEmitterErrorByTopicKey, getEmitterErrorKey, getEmitterStartEventByTopicKey, getEmitterStartEventKey, getErrorKey, getListenerEventByTopicKey, getListenerEventKey, getListenerRemoveByTopicKey, getListenerRemoveKey, getOpenKey, getReconnectingFailedKey, getReconnectingKey, getServerSentEventsAdapter, getSocketError, getSocketEvents, getSocketUrl, getWebsocketAdapter, interceptConnection, interceptEmitter, interceptListener, parseMessageEvent };
1850
+ export { Emitter, Listener, ServerSentEventsAdapter, Socket, SocketAdapter, WebsocketAdapter, assertDelivery, createBatchDeliveryStrategy, createDeliveryController, createDeliveryStrategy, createLatestDeliveryStrategy, createSocketClient, createSocketConfiguration, createSocketSdk, getAdapterBindings, getCloseKey, getConnectingKey, getDeliveryKey, getEmitterErrorByTopicKey, getEmitterErrorKey, getEmitterStartEventByTopicKey, getEmitterStartEventKey, getErrorKey, getListenerEventByTopicKey, getListenerEventKey, getListenerRemoveByTopicKey, getListenerRemoveKey, getOpenKey, getReconnectingFailedKey, getReconnectingKey, getServerSentEventsAdapter, getSocketError, getSocketEvents, getSocketUrl, getWebsocketAdapter, interceptConnection, interceptEmitter, interceptListener, isDeliveryStrategy, parseMessageEvent };
1657
1851
 
1658
1852
  //# sourceMappingURL=index.mjs.map