@hyper-fetch/sockets 9.0.3 → 9.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.
Files changed (59) hide show
  1. package/__tests__/e2e/e2e.delivery.spec.ts +81 -0
  2. package/__tests__/features/adapter/adapter.sse.codec.spec.ts +101 -0
  3. package/__tests__/features/adapter/adapter.websocket.codec.spec.ts +208 -0
  4. package/__tests__/features/delivery/delivery.batch.spec.ts +203 -0
  5. package/__tests__/features/delivery/delivery.latest.spec.ts +254 -0
  6. package/__tests__/features/delivery/delivery.typescript.spec.ts +143 -0
  7. package/__tests__/features/delivery/delivery.utils.spec.ts +122 -0
  8. package/__tests__/features/listener/listener.delivery.spec.ts +385 -0
  9. package/__tests__/features/listener/listener.delivery.sse.spec.ts +55 -0
  10. package/__tests__/features/sdk/sdk.configuration.spec.ts +60 -0
  11. package/__tests__/features/sdk/sdk.types.spec.ts +41 -17
  12. package/__tests__/features/socket/socket.methods.spec.ts +40 -0
  13. package/dist/adapter-sse/sse-adapter.d.ts.map +1 -1
  14. package/dist/adapter-sse/sse-adapter.types.d.ts +11 -0
  15. package/dist/adapter-sse/sse-adapter.types.d.ts.map +1 -1
  16. package/dist/adapter-websockets/websocket-adapter.d.ts.map +1 -1
  17. package/dist/adapter-websockets/websocket-adapter.types.d.ts +23 -0
  18. package/dist/adapter-websockets/websocket-adapter.types.d.ts.map +1 -1
  19. package/dist/delivery/delivery.batch.d.ts +19 -0
  20. package/dist/delivery/delivery.batch.d.ts.map +1 -0
  21. package/dist/delivery/delivery.latest.d.ts +18 -0
  22. package/dist/delivery/delivery.latest.d.ts.map +1 -0
  23. package/dist/delivery/delivery.types.d.ts +113 -0
  24. package/dist/delivery/delivery.types.d.ts.map +1 -0
  25. package/dist/delivery/delivery.utils.d.ts +50 -0
  26. package/dist/delivery/delivery.utils.d.ts.map +1 -0
  27. package/dist/delivery/index.d.ts +5 -0
  28. package/dist/delivery/index.d.ts.map +1 -0
  29. package/dist/index.d.ts +1 -0
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.mjs +261 -20
  32. package/dist/index.mjs.map +1 -1
  33. package/dist/listener/listener.d.ts +22 -7
  34. package/dist/listener/listener.d.ts.map +1 -1
  35. package/dist/listener/listener.types.d.ts +29 -9
  36. package/dist/listener/listener.types.d.ts.map +1 -1
  37. package/dist/sdk/sdk.d.ts +6 -2
  38. package/dist/sdk/sdk.d.ts.map +1 -1
  39. package/dist/socket/socket.d.ts +8 -1
  40. package/dist/socket/socket.d.ts.map +1 -1
  41. package/dist/types/extract.types.d.ts +10 -4
  42. package/dist/types/extract.types.d.ts.map +1 -1
  43. package/package.json +1 -1
  44. package/src/adapter-sse/sse-adapter.ts +23 -4
  45. package/src/adapter-sse/sse-adapter.types.ts +9 -0
  46. package/src/adapter-websockets/websocket-adapter.ts +31 -6
  47. package/src/adapter-websockets/websocket-adapter.types.ts +20 -0
  48. package/src/delivery/delivery.batch.ts +71 -0
  49. package/src/delivery/delivery.latest.ts +64 -0
  50. package/src/delivery/delivery.types.ts +129 -0
  51. package/src/delivery/delivery.utils.ts +96 -0
  52. package/src/delivery/index.ts +4 -0
  53. package/src/index.ts +1 -0
  54. package/src/listener/listener.ts +48 -9
  55. package/src/listener/listener.types.ts +45 -10
  56. package/src/sdk/sdk.ts +27 -7
  57. package/src/socket/socket.ts +18 -2
  58. package/src/types/extract.types.ts +10 -4
  59. package/tsconfig.json +2 -0
@@ -0,0 +1,129 @@
1
+ import type { SocketAdapterInstance } from "adapter";
2
+ import type { ExtractAdapterExtraType } from "types";
3
+
4
+ /**
5
+ * A single message flowing through a delivery strategy.
6
+ *
7
+ * `data` is the payload, `extra` is adapter-specific metadata (for the WebSocket adapter it is the raw `MessageEvent`).
8
+ */
9
+ export type DeliveryMessageType<Data, Extra = any> = {
10
+ data: Data;
11
+ extra: Extra;
12
+ };
13
+
14
+ /**
15
+ * The object a delivery strategy returns for a single `listen()` subscription.
16
+ *
17
+ * Think of it as a tiny pipe: `push` is the input (every raw message lands here), `deliver` from the
18
+ * {@link DeliveryStrategyContextType} is the output, and `dispose` is the cleanup.
19
+ */
20
+ export type DeliveryControllerType<Input, Extra = any> = {
21
+ /**
22
+ * Receives every raw message of the subscription. The strategy decides if and when to call `deliver`.
23
+ */
24
+ push: (message: DeliveryMessageType<Input, Extra>) => void;
25
+ /**
26
+ * Called when the subscription ends (`unlisten()` / component unmount). Clear timers and drop pending
27
+ * state here. Nothing may be delivered after `dispose` was called. Must be safe to call more than once.
28
+ */
29
+ dispose: () => void;
30
+ };
31
+
32
+ /**
33
+ * Context handed to a delivery strategy when a subscription starts.
34
+ */
35
+ export type DeliveryStrategyContextType<Output, Extra = any> = {
36
+ /**
37
+ * Hands a (possibly aggregated) message to the user's `listen` callback.
38
+ */
39
+ deliver: (message: DeliveryMessageType<Output, Extra>) => void;
40
+ };
41
+
42
+ /**
43
+ * A custom delivery strategy. It is a factory invoked once per `listen()` call, so every subscription
44
+ * owns its own timers and buffers.
45
+ *
46
+ * `Input` is the raw message type (the listener's response type), `Output` is what `listen` callbacks
47
+ * receive. Use {@link createDeliveryStrategy} to author one with full type inference.
48
+ *
49
+ * @example
50
+ * ```ts
51
+ * // Deliver after 50ms of silence (debounce)
52
+ * const settle = createDeliveryStrategy<Tick>(({ deliver }) => {
53
+ * let timer: ReturnType<typeof setTimeout> | undefined;
54
+ * let last: DeliveryMessageType<Tick> | undefined;
55
+ * return {
56
+ * push: (message) => {
57
+ * last = message;
58
+ * clearTimeout(timer);
59
+ * timer = setTimeout(() => {
60
+ * if (last) deliver(last);
61
+ * last = undefined;
62
+ * }, 50);
63
+ * },
64
+ * dispose: () => {
65
+ * clearTimeout(timer);
66
+ * last = undefined;
67
+ * },
68
+ * };
69
+ * });
70
+ * ```
71
+ */
72
+ export type DeliveryStrategyType<Input, Output = Input, Extra = any> = (
73
+ context: DeliveryStrategyContextType<Output, Extra>,
74
+ ) => DeliveryControllerType<Input, Extra>;
75
+
76
+ /**
77
+ * Sampling delivery. The first message of an idle period is delivered immediately (when `leading` is `true`),
78
+ * then at most one message per `interval` is delivered - always the most recent one. Intermediate messages
79
+ * are dropped. Best for state-like data (prices, positions, cursors) where only the newest value matters.
80
+ */
81
+ export type LatestDeliveryType = {
82
+ strategy: "latest";
83
+ /** Minimum time in milliseconds between two deliveries. */
84
+ interval: number;
85
+ /**
86
+ * Deliver the first message of an idle period immediately instead of waiting for the interval to pass.
87
+ * @default true
88
+ */
89
+ leading?: boolean;
90
+ };
91
+
92
+ /**
93
+ * Batching delivery. The first message opens a window of `interval` milliseconds; when it closes, every
94
+ * message collected in it is delivered at once as an array, in arrival order. Nothing is dropped.
95
+ * Best for event-like data (trades, chat messages, logs) where every message must be processed.
96
+ */
97
+ export type BatchDeliveryType = {
98
+ strategy: "batch";
99
+ /** Window length in milliseconds, measured from the first message of a batch. */
100
+ interval: number;
101
+ /** Deliver early as soon as this many messages were collected. Defaults to no limit. */
102
+ maxSize?: number;
103
+ };
104
+
105
+ /** Built-in, serializable delivery presets. */
106
+ export type DeliveryPresetType = LatestDeliveryType | BatchDeliveryType;
107
+
108
+ /**
109
+ * Everything accepted by the listener `delivery` option: a built-in preset or a custom strategy.
110
+ */
111
+ export type ListenerDeliveryType<Response = any, Adapter extends SocketAdapterInstance = SocketAdapterInstance> =
112
+ | DeliveryPresetType
113
+ | DeliveryStrategyType<Response, any, ExtractAdapterExtraType<Adapter>>;
114
+
115
+ /**
116
+ * Resolves what `listen` callbacks receive for a given `delivery` configuration.
117
+ *
118
+ * - no delivery → `Response`
119
+ * - `{ strategy: "latest" }` → `Response`
120
+ * - `{ strategy: "batch" }` → `Response[]`
121
+ * - custom strategy → its `Output` type
122
+ */
123
+ export type ResolveDeliveredType<Response, Delivery> = [Delivery] extends [undefined]
124
+ ? Response
125
+ : Delivery extends DeliveryStrategyType<any, infer Output, any>
126
+ ? Output
127
+ : Delivery extends { strategy: "batch" }
128
+ ? Response[]
129
+ : Response;
@@ -0,0 +1,96 @@
1
+ import type {
2
+ BatchDeliveryType,
3
+ DeliveryControllerType,
4
+ DeliveryPresetType,
5
+ DeliveryStrategyContextType,
6
+ DeliveryStrategyType,
7
+ LatestDeliveryType,
8
+ ListenerDeliveryType,
9
+ } from "delivery";
10
+ import { createBatchDeliveryStrategy, createLatestDeliveryStrategy } from "delivery";
11
+
12
+ /**
13
+ * Typed identity helper for authoring custom delivery strategies.
14
+ *
15
+ * `Input` is the listener's response type, `Output` is what `listen` callbacks will receive. TypeScript cannot
16
+ * infer `Output` from how you call `deliver`, so declare it here - the same way `createListener<Response>()`
17
+ * declares the wire type.
18
+ *
19
+ * @example
20
+ * ```ts
21
+ * const summarize = createDeliveryStrategy<Tick, { count: number; last: Tick }>(({ deliver }) => {
22
+ * let count = 0;
23
+ * let last: Tick | undefined;
24
+ * let timer: ReturnType<typeof setTimeout> | undefined;
25
+ * return {
26
+ * push: ({ data, extra }) => {
27
+ * count += 1;
28
+ * last = data;
29
+ * timer ??= setTimeout(() => {
30
+ * timer = undefined;
31
+ * deliver({ data: { count, last: last! }, extra });
32
+ * count = 0;
33
+ * }, 1000);
34
+ * },
35
+ * dispose: () => clearTimeout(timer),
36
+ * };
37
+ * });
38
+ *
39
+ * const onTick = socket.createListener<Tick>()({ topic: "ticks", delivery: summarize });
40
+ * onTick.listen(({ data }) => data.count); // data: { count: number; last: Tick }
41
+ * ```
42
+ */
43
+ export const createDeliveryStrategy = <Input, Output = Input, Extra = any>(
44
+ strategy: DeliveryStrategyType<Input, Output, Extra>,
45
+ ): DeliveryStrategyType<Input, Output, Extra> => strategy;
46
+
47
+ /** Narrows a `delivery` value to a custom strategy function. */
48
+ export const isDeliveryStrategy = (delivery: ListenerDeliveryType): delivery is DeliveryStrategyType<any, any, any> =>
49
+ typeof delivery === "function";
50
+
51
+ /**
52
+ * Validates a `delivery` value. Throws for unknown presets so misconfiguration fails at listener creation,
53
+ * not on the first message.
54
+ */
55
+ export const assertDelivery = (delivery: ListenerDeliveryType): void => {
56
+ if (isDeliveryStrategy(delivery)) {
57
+ return;
58
+ }
59
+ if (delivery.strategy !== "latest" && delivery.strategy !== "batch") {
60
+ throw new Error(
61
+ `Unknown delivery strategy: ${String((delivery as { strategy: unknown }).strategy)}. Use "latest", "batch" or a custom strategy created with createDeliveryStrategy().`,
62
+ );
63
+ }
64
+ };
65
+
66
+ /**
67
+ * Instantiates a delivery controller for one `listen()` subscription.
68
+ */
69
+ export const createDeliveryController = <Input, Output, Extra>(
70
+ delivery: DeliveryPresetType | DeliveryStrategyType<Input, any, Extra>,
71
+ context: DeliveryStrategyContextType<Output, Extra>,
72
+ ): DeliveryControllerType<Input, Extra> => {
73
+ if (isDeliveryStrategy(delivery)) {
74
+ return delivery(context);
75
+ }
76
+ const { strategy, ...options } = delivery as DeliveryPresetType;
77
+ const factory =
78
+ strategy === "latest"
79
+ ? createLatestDeliveryStrategy<Input, Extra>(options as Omit<LatestDeliveryType, "strategy">)
80
+ : createBatchDeliveryStrategy<Input, Extra>(options as Omit<BatchDeliveryType, "strategy">);
81
+ return (factory as DeliveryStrategyType<Input, any, Extra>)(context);
82
+ };
83
+
84
+ /**
85
+ * Stable key describing a `delivery` value - presets by value, custom strategies by identity.
86
+ * Useful for memoization (e.g. React dependency arrays).
87
+ */
88
+ export const getDeliveryKey = (delivery?: ListenerDeliveryType): string | DeliveryStrategyType<any> => {
89
+ if (!delivery) {
90
+ return "";
91
+ }
92
+ if (isDeliveryStrategy(delivery)) {
93
+ return delivery;
94
+ }
95
+ return JSON.stringify(delivery);
96
+ };
@@ -0,0 +1,4 @@
1
+ export * from "./delivery.types";
2
+ export * from "./delivery.latest";
3
+ export * from "./delivery.batch";
4
+ export * from "./delivery.utils";
package/src/index.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,4 +1,6 @@
1
1
  import type { ExtractUrlParams, ParamsType } from "@hyper-fetch/core";
2
+ import type { DeliveryStrategyContextType, ListenerDeliveryType, ResolveDeliveredType } from "delivery";
3
+ import { assertDelivery, createDeliveryController } from "delivery";
2
4
  import type { ListenType, ListenerConfigurationType, ListenerOptionsType } from "listener";
3
5
  import type { SocketInstance } from "socket";
4
6
  import type { ExtractAdapterListenerOptionsType, ExtractSocketAdapterType } from "types";
@@ -6,24 +8,41 @@ import type { ExtractAdapterListenerOptionsType, ExtractSocketAdapterType } from
6
8
  /**
7
9
  * Represents a socket message listener bound to a specific topic. Use it to subscribe to
8
10
  * typed messages from WebSocket or Server-Sent Events connections via the socket adapter.
11
+ *
12
+ * `Response` is the raw message type, `Delivered` is what `listen` callbacks receive. They differ only
13
+ * when a `delivery` strategy changes the shape (e.g. `batch` delivers `Response[]`).
9
14
  */
10
15
  export class Listener<
11
16
  Response,
12
17
  Topic extends string,
13
18
  Socket extends SocketInstance,
14
19
  HasParams extends boolean = false,
20
+ Delivered = Response,
15
21
  > {
16
22
  readonly topic: Topic;
17
23
  params?: ParamsType = undefined;
18
24
  options?: ExtractAdapterListenerOptionsType<ExtractSocketAdapterType<Socket>> = undefined;
25
+ /**
26
+ * How messages reach `listen` callbacks. Typed with `any` input on purpose - it keeps `Response`
27
+ * covariant so partial `ListenerInstance<{ response: ... }>` constraints keep matching wider listeners.
28
+ */
29
+ delivery?: ListenerDeliveryType<any, ExtractSocketAdapterType<Socket>> = undefined;
30
+ /** Stored with an `any` response for the same covariance reason as `delivery`. */
31
+ readonly listenerOptions: ListenerOptionsType<Topic, ExtractSocketAdapterType<Socket>>;
19
32
 
20
33
  constructor(
21
34
  readonly socket: Socket,
22
- readonly listenerOptions: ListenerOptionsType<Topic, ExtractSocketAdapterType<Socket>>,
35
+ listenerOptions: ListenerOptionsType<Topic, ExtractSocketAdapterType<Socket>, Response>,
23
36
  ) {
24
- const { topic, options } = listenerOptions;
37
+ this.listenerOptions = listenerOptions;
38
+ const { topic, options, delivery, params } = listenerOptions as typeof listenerOptions & { params?: ParamsType };
25
39
  this.topic = topic;
26
40
  this.options = options;
41
+ this.params = params;
42
+ this.delivery = delivery;
43
+ if (delivery) {
44
+ assertDelivery(delivery);
45
+ }
27
46
  }
28
47
 
29
48
  /** Set adapter-specific listener options. */
@@ -36,11 +55,21 @@ export class Listener<
36
55
  return this.clone<true>({ params });
37
56
  }
38
57
 
58
+ /**
59
+ * Set how messages are delivered to `listen` callbacks - a `latest` / `batch` preset or a custom strategy.
60
+ * Pass `undefined` to restore immediate delivery. Returns a clone; the callback data type follows the strategy.
61
+ */
62
+ setDelivery<NewDelivery extends ListenerDeliveryType<Response, ExtractSocketAdapterType<Socket>> | undefined>(
63
+ delivery: NewDelivery,
64
+ ) {
65
+ return this.clone<HasParams, ResolveDeliveredType<Response, NewDelivery>>({ delivery });
66
+ }
67
+
39
68
  /** Create a new listener instance with optional configuration overrides. */
40
- clone<NewHasParams extends true | false = HasParams>(
41
- options?: ListenerConfigurationType<ExtractUrlParams<Topic>, Topic, Socket>,
69
+ clone<NewHasParams extends true | false = HasParams, NewDelivered = Delivered>(
70
+ options?: ListenerConfigurationType<ExtractUrlParams<Topic>, Topic, Socket, Response>,
42
71
  ) {
43
- const newInstance = new Listener<Response, Topic, Socket, NewHasParams>(this.socket, {
72
+ const newInstance = new Listener<Response, Topic, Socket, NewHasParams, NewDelivered>(this.socket, {
44
73
  ...this.listenerOptions,
45
74
  ...options,
46
75
  topic: this.paramsMapper(options?.params || this.params),
@@ -50,13 +79,23 @@ export class Listener<
50
79
  }
51
80
 
52
81
  /** Start listening for messages on the configured topic. Returns a function to unsubscribe. */
53
- listen: ListenType<Listener<Response, Topic, Socket, HasParams>, Socket> = (
54
- callback: Parameters<ListenType<Listener<Response, Topic, Socket, HasParams>, Socket>>[0],
82
+ listen: ListenType<Listener<Response, Topic, Socket, HasParams, Delivered>, Socket> = (
83
+ callback: Parameters<ListenType<Listener<Response, Topic, Socket, HasParams, Delivered>, Socket>>[0],
55
84
  ) => {
56
- this.socket.adapter.listen(this, callback);
85
+ // With a delivery strategy the adapter receives the controller's `push` instead of the user callback.
86
+ // Each listen() call gets its own controller, so subscriptions never share timers or buffers.
87
+ const controller = this.delivery
88
+ ? createDeliveryController(this.delivery, {
89
+ deliver: callback as DeliveryStrategyContextType<any, any>["deliver"],
90
+ })
91
+ : null;
92
+ const adapterCallback = controller ? controller.push : callback;
93
+
94
+ this.socket.adapter.listen(this, adapterCallback);
57
95
 
58
96
  const removeListener = () => {
59
- this.socket.adapter.removeListener({ topic: this.topic, callback });
97
+ controller?.dispose();
98
+ this.socket.adapter.removeListener({ topic: this.topic, callback: adapterCallback });
60
99
  };
61
100
 
62
101
  return removeListener;
@@ -1,6 +1,7 @@
1
1
  /* eslint-disable @typescript-eslint/no-shadow */
2
2
  import type { ExtractUrlParams, EmptyTypes, TypeWithDefaults } from "@hyper-fetch/core";
3
3
  import type { SocketAdapterInstance } from "adapter";
4
+ import type { ListenerDeliveryType } from "delivery";
4
5
  import type { Listener } from "listener";
5
6
  import type { Socket, SocketInstance } from "socket";
6
7
  import type {
@@ -11,6 +12,7 @@ import type {
11
12
  ExtractAdapterExtraType,
12
13
  ExtractListenerSocketType,
13
14
  ExtractSocketAdapterType,
15
+ ExtractListenerDeliveredType,
14
16
  } from "types";
15
17
 
16
18
  export type ListenerInstanceProperties = {
@@ -18,6 +20,11 @@ export type ListenerInstanceProperties = {
18
20
  topic?: string;
19
21
  socket?: SocketInstance;
20
22
  hasParams?: boolean;
23
+ /**
24
+ * Type received by `listen` callbacks. Differs from `response` only when a `delivery` strategy
25
+ * changes the shape (e.g. `batch` delivers `response[]`).
26
+ */
27
+ delivered?: any;
21
28
  };
22
29
 
23
30
  /**
@@ -43,7 +50,8 @@ export type ListenerInstance<ListenerProperties extends ListenerInstanceProperti
43
50
  TypeWithDefaults<ListenerProperties, "response", any>,
44
51
  TypeWithDefaults<ListenerProperties, "topic", any>,
45
52
  TypeWithDefaults<ListenerProperties, "socket", SocketInstance>,
46
- TypeWithDefaults<ListenerProperties, "hasParams", any>
53
+ TypeWithDefaults<ListenerProperties, "hasParams", any>,
54
+ TypeWithDefaults<ListenerProperties, "delivered", any>
47
55
  >;
48
56
 
49
57
  /**
@@ -66,6 +74,7 @@ export type ListenerInstance<ListenerProperties extends ListenerInstanceProperti
66
74
  * | `topic` | `string` | Allows literal narrowing without erasure. Pass a string literal. |
67
75
  * | `socket` | `SocketInstance` | Injected by `createSocketSdk(socket)`; do not set this manually. |
68
76
  * | `hasParams` | `false` | "Caller must call `.setParams()`." Override only when bound. |
77
+ * | `delivered` | same as `response` | Set only when a `delivery` strategy changes the callback shape. |
69
78
  *
70
79
  * @example
71
80
  * ```ts
@@ -94,22 +103,42 @@ export type ListenerModel<ListenerProperties extends ListenerInstanceProperties
94
103
  TypeWithDefaults<ListenerProperties, "response", unknown>,
95
104
  TypeWithDefaults<ListenerProperties, "topic", string>,
96
105
  TypeWithDefaults<ListenerProperties, "socket", SocketInstance>,
97
- TypeWithDefaults<ListenerProperties, "hasParams", false>
106
+ TypeWithDefaults<ListenerProperties, "hasParams", false>,
107
+ TypeWithDefaults<ListenerProperties, "delivered", TypeWithDefaults<ListenerProperties, "response", unknown>>
98
108
  >;
99
109
 
100
- export type ListenerOfAdapter<A extends SocketAdapterInstance> = Listener<any, any, Socket<A>, any>;
110
+ export type ListenerOfAdapter<A extends SocketAdapterInstance> = Listener<any, any, Socket<A>, any, any>;
101
111
 
102
112
  /** Configuration options for creating a Listener instance. */
103
- export type ListenerOptionsType<Topic extends string, AdapterType extends SocketAdapterInstance> = {
113
+ export type ListenerOptionsType<
114
+ Topic extends string,
115
+ AdapterType extends SocketAdapterInstance,
116
+ Response = any,
117
+ Delivery extends ListenerDeliveryType<Response, AdapterType> | undefined =
118
+ | ListenerDeliveryType<Response, AdapterType>
119
+ | undefined,
120
+ > = {
104
121
  /** The topic/channel name to listen on */
105
122
  topic: Topic;
106
123
  /** Adapter-specific listener options */
107
124
  options?: ExtractAdapterListenerOptionsType<AdapterType>;
125
+ /**
126
+ * Controls how incoming messages reach `listen` callbacks. Omit it for immediate delivery of every message.
127
+ *
128
+ * - `{ strategy: "latest", interval }` - sampling: deliver the first message immediately, then at most one
129
+ * (the newest) per `interval` ms. Intermediate messages are dropped. For state-like data such as prices.
130
+ * - `{ strategy: "batch", interval, maxSize? }` - deliver every message collected during `interval` ms as one
131
+ * array. Nothing is dropped and callbacks receive `Response[]`. For event-like data such as trades.
132
+ * - a function created with `createDeliveryStrategy()` - full control over buffering and timing.
133
+ *
134
+ * Pending messages are dropped on unsubscribe. See the "Throttling & Batching" guide for details.
135
+ */
136
+ delivery?: Delivery;
108
137
  };
109
138
 
110
- export type ListenerConfigurationType<Params, Topic extends string, Socket extends SocketInstance> = {
139
+ export type ListenerConfigurationType<Params, Topic extends string, Socket extends SocketInstance, Response = any> = {
111
140
  params?: Params;
112
- } & Partial<ListenerOptionsType<Topic, ExtractSocketAdapterType<Socket>>>;
141
+ } & Partial<ListenerOptionsType<Topic, ExtractSocketAdapterType<Socket>, Response>>;
113
142
 
114
143
  export type ListenerParamsOptionsType<Listener extends ListenerInstance> =
115
144
  ExtractListenerHasParamsType<Listener> extends false
@@ -123,14 +152,14 @@ export type ListenerParamsOptionsType<Listener extends ListenerInstance> =
123
152
  export type ListenType<Listener extends ListenerInstance, Socket extends SocketInstance> =
124
153
  ExtractUrlParams<ExtractListenerTopicType<Listener>> extends EmptyTypes
125
154
  ? (
126
- callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>, ExtractListenerResponseType<Listener>>,
155
+ callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>, ExtractListenerDeliveredType<Listener>>,
127
156
  ) => () => void
128
157
  : ExtractListenerHasParamsType<Listener> extends true
129
158
  ? (
130
- callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>, ExtractListenerResponseType<Listener>>,
159
+ callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>, ExtractListenerDeliveredType<Listener>>,
131
160
  ) => () => void
132
161
  : (
133
- callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>, ExtractListenerResponseType<Listener>>,
162
+ callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>, ExtractListenerDeliveredType<Listener>>,
134
163
  ) => () => void;
135
164
 
136
165
  export type ListenerCallbackType<AdapterType extends SocketAdapterInstance, D> = (response: {
@@ -145,10 +174,16 @@ export type ExtendListener<
145
174
  topic?: string;
146
175
  socket?: SocketInstance;
147
176
  hasParams?: true | false;
177
+ delivered?: any;
148
178
  },
149
179
  > = Listener<
150
180
  TypeWithDefaults<Properties, "response", ExtractListenerResponseType<T>>,
151
181
  Properties["topic"] extends string ? Properties["topic"] : ExtractListenerTopicType<T>,
152
182
  Properties["socket"] extends SocketInstance ? Properties["socket"] : ExtractListenerSocketType<T>,
153
- Properties["hasParams"] extends true ? true : ExtractListenerHasParamsType<T>
183
+ Properties["hasParams"] extends true ? true : ExtractListenerHasParamsType<T>,
184
+ TypeWithDefaults<
185
+ Properties,
186
+ "delivered",
187
+ "response" extends keyof Properties ? Properties["response"] : ExtractListenerDeliveredType<T>
188
+ >
154
189
  >;
package/src/sdk/sdk.ts CHANGED
@@ -1,10 +1,13 @@
1
+ import type { ListenerDeliveryType } from "delivery";
1
2
  import type { Emitter, EmitterInstance } from "emitter";
2
- import type { Listener, ListenerInstance } from "listener";
3
+ import { Listener } from "listener";
4
+ import type { ListenerInstance } from "listener";
3
5
  import type { SocketInstance } from "socket";
4
6
  import type {
5
7
  ExtractListenerResponseType,
6
8
  ExtractListenerTopicType,
7
9
  ExtractListenerHasParamsType,
10
+ ExtractListenerDeliveredType,
8
11
  ExtractEmitterPayloadType,
9
12
  ExtractEmitterTopicType,
10
13
  ExtractEmitterHasPayloadType,
@@ -32,7 +35,8 @@ export type InjectSocket<T, S extends SocketInstance, Depth extends unknown[] =
32
35
  ExtractListenerResponseType<T>,
33
36
  ExtractListenerTopicType<T> extends string ? ExtractListenerTopicType<T> : string,
34
37
  S,
35
- ExtractListenerHasParamsType<T> extends boolean ? ExtractListenerHasParamsType<T> : false
38
+ ExtractListenerHasParamsType<T> extends boolean ? ExtractListenerHasParamsType<T> : false,
39
+ ExtractListenerDeliveredType<T>
36
40
  >
37
41
  : T extends EmitterInstance
38
42
  ? Emitter<
@@ -99,7 +103,10 @@ type SocketSdkConfigurationKeys<Schema extends RecursiveSocketSchemaType> =
99
103
  | ExtractSocketSdkPaths<Schema>;
100
104
 
101
105
  export type SocketSdkDefaults = {
106
+ /** Adapter-specific options applied with `setOptions` to listeners and emitters. */
102
107
  options?: Record<string, unknown>;
108
+ /** Delivery strategy applied with `setDelivery` to listeners. Ignored for emitters. */
109
+ delivery?: ListenerDeliveryType;
103
110
  };
104
111
 
105
112
  export type SocketSdkConfigurationValue = SocketSdkDefaults | ((instance: SocketSdkLeaf) => SocketSdkLeaf);
@@ -142,8 +149,12 @@ const isTopicGroup = (key: string): boolean => {
142
149
  };
143
150
 
144
151
  const topicMatchesPattern = (topic: string, pattern: string): boolean => {
145
- if (pattern === "*") {return true;}
146
- if (pattern === topic) {return true;}
152
+ if (pattern === "*") {
153
+ return true;
154
+ }
155
+ if (pattern === topic) {
156
+ return true;
157
+ }
147
158
  if (pattern.endsWith("/*")) {
148
159
  const prefix = pattern.slice(0, -1);
149
160
  return topic.startsWith(prefix) || topic === prefix.slice(0, -1);
@@ -153,7 +164,12 @@ const topicMatchesPattern = (topic: string, pattern: string): boolean => {
153
164
 
154
165
  const applySocketObjectDefaults = (instance: SocketSdkLeaf, config: SocketSdkDefaults): SocketSdkLeaf => {
155
166
  let result = instance;
156
- if (config.options !== undefined) {result = result.setOptions(config.options);}
167
+ if (config.options !== undefined) {
168
+ result = result.setOptions(config.options);
169
+ }
170
+ if (config.delivery !== undefined && result instanceof Listener) {
171
+ result = result.setDelivery(config.delivery);
172
+ }
157
173
  return result;
158
174
  };
159
175
 
@@ -168,7 +184,9 @@ const applySocketDefaults = ({
168
184
  sdkPath: string;
169
185
  defaults?: Partial<Record<string, SocketSdkConfigurationValue>>;
170
186
  }): SocketSdkLeaf => {
171
- if (!defaults) {return instance;}
187
+ if (!defaults) {
188
+ return instance;
189
+ }
172
190
 
173
191
  let result = instance;
174
192
  const entries = Object.entries(defaults);
@@ -179,7 +197,9 @@ const applySocketDefaults = ({
179
197
 
180
198
  for (let i = 0; i < entries.length; i += 1) {
181
199
  const [key, value] = entries[i];
182
- if (!value) {continue;}
200
+ if (!value) {
201
+ continue;
202
+ }
183
203
  const entry: [string, SocketSdkConfigurationValue] = [key, value];
184
204
  if (entry[0] === "*") {
185
205
  globalEntries.push(entry);
@@ -3,6 +3,7 @@ import { LoggerManager, AppManager, Time } from "@hyper-fetch/core";
3
3
  import type { SocketAdapterInstance } from "adapter";
4
4
  import type { WebsocketAdapterType } from "adapter-websockets/websocket-adapter";
5
5
  import { WebsocketAdapter } from "adapter-websockets/websocket-adapter";
6
+ import type { ListenerDeliveryType, ResolveDeliveredType } from "delivery";
6
7
  import type { EmitterInstance, EmitterOptionsType } from "emitter";
7
8
  import { Emitter } from "emitter";
8
9
  import EventEmitter from "events";
@@ -90,6 +91,16 @@ export class Socket<Adapter extends SocketAdapterInstance = WebsocketAdapterType
90
91
  await this.adapter.reconnect();
91
92
  };
92
93
 
94
+ /**
95
+ * Set the url used by the next connection attempts - e.g. when switching tenants, regions or environments at runtime.
96
+ * Call `reconnect()` to apply it to a live connection, or use `onConnect` to resolve it per attempt.
97
+ * Listeners stay registered, so they keep receiving events after reconnecting.
98
+ */
99
+ setUrl = (url: string) => {
100
+ this.url = url;
101
+ return this;
102
+ };
103
+
93
104
  /**
94
105
  * Set the default query params used by the next connection attempts.
95
106
  * Call `reconnect()` to apply them to a live connection, or use `onConnect` to resolve them per attempt.
@@ -238,8 +249,13 @@ export class Socket<Adapter extends SocketAdapterInstance = WebsocketAdapterType
238
249
  * @returns
239
250
  */
240
251
  createListener = <Response>() => {
241
- return <Endpoint extends string>(options: ListenerOptionsType<Endpoint, Adapter>) => {
242
- return new Listener<Response, Endpoint, Socket<Adapter>>(this, options);
252
+ return <Topic extends string, Delivery extends ListenerDeliveryType<Response, Adapter> | undefined = undefined>(
253
+ options: ListenerOptionsType<Topic, Adapter, Response, Delivery>,
254
+ ) => {
255
+ return new Listener<Response, Topic, Socket<Adapter>, false, ResolveDeliveredType<Response, Delivery>>(
256
+ this,
257
+ options,
258
+ );
243
259
  };
244
260
  };
245
261
 
@@ -19,10 +19,16 @@ export type ExtractEmitterHasParamsType<E> = E extends Emitter<any, any, any, an
19
19
 
20
20
  // Listener
21
21
 
22
- export type ExtractListenerResponseType<T> = T extends Listener<infer R, any, any, any> ? R : never;
23
- export type ExtractListenerTopicType<E> = E extends Listener<any, infer T, any, any> ? T : never;
24
- export type ExtractListenerSocketType<E> = E extends Listener<any, any, infer A, any> ? A : never;
25
- export type ExtractListenerHasParamsType<E> = E extends Listener<any, any, any, infer P> ? P : never;
22
+ /** Raw message type of a listener - what arrives on the wire, before any `delivery` strategy. */
23
+ export type ExtractListenerResponseType<T> = T extends Listener<infer R, any, any, any, any> ? R : never;
24
+ export type ExtractListenerTopicType<E> = E extends Listener<any, infer T, any, any, any> ? T : never;
25
+ export type ExtractListenerSocketType<E> = E extends Listener<any, any, infer A, any, any> ? A : never;
26
+ export type ExtractListenerHasParamsType<E> = E extends Listener<any, any, any, infer P, any> ? P : never;
27
+ /**
28
+ * What `listen` callbacks receive. Equals {@link ExtractListenerResponseType} unless the listener has a
29
+ * `delivery` strategy (e.g. `batch` delivers `Response[]`).
30
+ */
31
+ export type ExtractListenerDeliveredType<T> = T extends Listener<any, any, any, any, infer D> ? D : never;
26
32
 
27
33
  // Socket
28
34
 
package/tsconfig.json CHANGED
@@ -10,6 +10,8 @@
10
10
  "adapter-sse/*": ["./src/adapter-sse/*"],
11
11
  "adapter-websockets": ["./src/adapter-websockets"],
12
12
  "adapter-websockets/*": ["./src/adapter-websockets/*"],
13
+ "delivery": ["./src/delivery"],
14
+ "delivery/*": ["./src/delivery/*"],
13
15
  "emitter": ["./src/emitter"],
14
16
  "emitter/*": ["./src/emitter/*"],
15
17
  "listener": ["./src/listener"],