@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.
- package/__tests__/e2e/e2e.delivery.spec.ts +81 -0
- package/__tests__/features/adapter/adapter.sse.codec.spec.ts +101 -0
- package/__tests__/features/adapter/adapter.websocket.codec.spec.ts +208 -0
- package/__tests__/features/delivery/delivery.batch.spec.ts +203 -0
- package/__tests__/features/delivery/delivery.latest.spec.ts +254 -0
- package/__tests__/features/delivery/delivery.typescript.spec.ts +143 -0
- package/__tests__/features/delivery/delivery.utils.spec.ts +122 -0
- package/__tests__/features/listener/listener.delivery.spec.ts +385 -0
- package/__tests__/features/listener/listener.delivery.sse.spec.ts +55 -0
- package/__tests__/features/sdk/sdk.configuration.spec.ts +60 -0
- package/__tests__/features/sdk/sdk.types.spec.ts +41 -17
- package/__tests__/features/socket/socket.methods.spec.ts +40 -0
- package/dist/adapter-sse/sse-adapter.d.ts.map +1 -1
- package/dist/adapter-sse/sse-adapter.types.d.ts +11 -0
- package/dist/adapter-sse/sse-adapter.types.d.ts.map +1 -1
- package/dist/adapter-websockets/websocket-adapter.d.ts.map +1 -1
- package/dist/adapter-websockets/websocket-adapter.types.d.ts +23 -0
- package/dist/adapter-websockets/websocket-adapter.types.d.ts.map +1 -1
- package/dist/delivery/delivery.batch.d.ts +19 -0
- package/dist/delivery/delivery.batch.d.ts.map +1 -0
- package/dist/delivery/delivery.latest.d.ts +18 -0
- package/dist/delivery/delivery.latest.d.ts.map +1 -0
- package/dist/delivery/delivery.types.d.ts +113 -0
- package/dist/delivery/delivery.types.d.ts.map +1 -0
- package/dist/delivery/delivery.utils.d.ts +50 -0
- package/dist/delivery/delivery.utils.d.ts.map +1 -0
- package/dist/delivery/index.d.ts +5 -0
- package/dist/delivery/index.d.ts.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.mjs +261 -20
- package/dist/index.mjs.map +1 -1
- package/dist/listener/listener.d.ts +22 -7
- package/dist/listener/listener.d.ts.map +1 -1
- package/dist/listener/listener.types.d.ts +29 -9
- package/dist/listener/listener.types.d.ts.map +1 -1
- package/dist/sdk/sdk.d.ts +6 -2
- package/dist/sdk/sdk.d.ts.map +1 -1
- package/dist/socket/socket.d.ts +8 -1
- package/dist/socket/socket.d.ts.map +1 -1
- package/dist/types/extract.types.d.ts +10 -4
- package/dist/types/extract.types.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/adapter-sse/sse-adapter.ts +23 -4
- package/src/adapter-sse/sse-adapter.types.ts +9 -0
- package/src/adapter-websockets/websocket-adapter.ts +31 -6
- package/src/adapter-websockets/websocket-adapter.types.ts +20 -0
- package/src/delivery/delivery.batch.ts +71 -0
- package/src/delivery/delivery.latest.ts +64 -0
- package/src/delivery/delivery.types.ts +129 -0
- package/src/delivery/delivery.utils.ts +96 -0
- package/src/delivery/index.ts +4 -0
- package/src/index.ts +1 -0
- package/src/listener/listener.ts +48 -9
- package/src/listener/listener.types.ts +45 -10
- package/src/sdk/sdk.ts +27 -7
- package/src/socket/socket.ts +18 -2
- package/src/types/extract.types.ts +10 -4
- 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
|
+
};
|
package/src/index.ts
CHANGED
package/src/listener/listener.ts
CHANGED
|
@@ -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
|
-
|
|
35
|
+
listenerOptions: ListenerOptionsType<Topic, ExtractSocketAdapterType<Socket>, Response>,
|
|
23
36
|
) {
|
|
24
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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<
|
|
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>,
|
|
155
|
+
callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>, ExtractListenerDeliveredType<Listener>>,
|
|
127
156
|
) => () => void
|
|
128
157
|
: ExtractListenerHasParamsType<Listener> extends true
|
|
129
158
|
? (
|
|
130
|
-
callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>,
|
|
159
|
+
callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>, ExtractListenerDeliveredType<Listener>>,
|
|
131
160
|
) => () => void
|
|
132
161
|
: (
|
|
133
|
-
callback: ListenerCallbackType<ExtractSocketAdapterType<Socket>,
|
|
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
|
|
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 === "*") {
|
|
146
|
-
|
|
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) {
|
|
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) {
|
|
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) {
|
|
200
|
+
if (!value) {
|
|
201
|
+
continue;
|
|
202
|
+
}
|
|
183
203
|
const entry: [string, SocketSdkConfigurationValue] = [key, value];
|
|
184
204
|
if (entry[0] === "*") {
|
|
185
205
|
globalEntries.push(entry);
|
package/src/socket/socket.ts
CHANGED
|
@@ -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 <
|
|
242
|
-
|
|
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
|
-
|
|
23
|
-
export type
|
|
24
|
-
export type
|
|
25
|
-
export type
|
|
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"],
|