@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
package/dist/index.mjs CHANGED
@@ -493,13 +493,13 @@ var WebsocketAdapter = () => new SocketAdapter({ name: "websockets" }).setQueryP
493
493
  }, socket.reconnectTime);
494
494
  });
495
495
  newWebsocket.addEventListener("message", (newEvent) => {
496
- const { topic, data, event } = parseMessageEvent(newEvent);
497
- onEvent({
498
- topic,
499
- data,
500
- extra: event
501
- });
502
496
  onHeartbeat();
497
+ const message = decodeMessage(newEvent);
498
+ if (message) onEvent({
499
+ topic: message.topic,
500
+ data: message.data,
501
+ extra: newEvent
502
+ });
503
503
  });
504
504
  return new Promise((resolve) => {
505
505
  if (newWebsocket.readyState === WebSocket.OPEN) {
@@ -567,13 +567,36 @@ var WebsocketAdapter = () => new SocketAdapter({ name: "websockets" }).setQueryP
567
567
  clearTimeout(pingTimer);
568
568
  clearTimeout(pongTimer);
569
569
  };
570
+ /** Maps an incoming frame to the listener event, reporting decoder failures instead of throwing */
571
+ const decodeMessage = (event) => {
572
+ try {
573
+ if (options?.decode) return options.decode(event);
574
+ const { topic, data } = parseMessageEvent(event);
575
+ return {
576
+ topic,
577
+ data
578
+ };
579
+ } catch (error) {
580
+ onError({ error });
581
+ return null;
582
+ }
583
+ };
570
584
  const sendEventMessage = ({ topic, payload }) => {
571
585
  if (!websocket) return false;
572
- websocket.send(JSON.stringify({
573
- topic,
574
- data: payload
575
- }));
576
- return true;
586
+ try {
587
+ const frame = options?.encode ? options.encode({
588
+ topic,
589
+ payload
590
+ }) : JSON.stringify({
591
+ topic,
592
+ data: payload
593
+ });
594
+ websocket.send(frame);
595
+ return true;
596
+ } catch (error) {
597
+ onError({ error });
598
+ return false;
599
+ }
577
600
  };
578
601
  const onHeartbeat = () => {
579
602
  const { heartbeat = false, pingTimeout = Time.SEC * 5, pongTimeout = Time.SEC * 5, heartbeatMessage = "heartbeat" } = options || (
@@ -973,21 +996,204 @@ var require_events = /* @__PURE__ */ __commonJSMin(((exports, module) => {
973
996
  }
974
997
  }));
975
998
  //#endregion
999
+ //#region src/delivery/delivery.latest.ts
1000
+ /**
1001
+ * Creates the built-in `latest` (sampling) strategy.
1002
+ *
1003
+ * Timeline for `interval: 100` with messages A, B, C at 0/20/40ms and D at 300ms:
1004
+ * ```
1005
+ * t=0 push(A) idle → deliver(A) immediately, open 100ms window
1006
+ * t=20 push(B) pending = B
1007
+ * t=40 push(C) pending = C (B is dropped)
1008
+ * t=100 window closes → deliver(C), open next window
1009
+ * t=200 window closes → nothing pending → idle
1010
+ * t=300 push(D) idle → deliver(D) immediately
1011
+ * ```
1012
+ *
1013
+ * Exported so custom strategies can compose it.
1014
+ */
1015
+ var createLatestDeliveryStrategy = ({ interval, leading = true }) => {
1016
+ return ({ deliver }) => {
1017
+ let timer;
1018
+ let pending;
1019
+ let disposed = false;
1020
+ const closeWindow = () => {
1021
+ timer = void 0;
1022
+ if (!pending) return;
1023
+ const message = pending;
1024
+ pending = void 0;
1025
+ timer = setTimeout(closeWindow, interval);
1026
+ deliver(message);
1027
+ };
1028
+ return {
1029
+ push: (message) => {
1030
+ if (disposed) return;
1031
+ if (timer === void 0) {
1032
+ timer = setTimeout(closeWindow, interval);
1033
+ if (leading) {
1034
+ deliver(message);
1035
+ return;
1036
+ }
1037
+ }
1038
+ pending = message;
1039
+ },
1040
+ dispose: () => {
1041
+ disposed = true;
1042
+ pending = void 0;
1043
+ if (timer !== void 0) clearTimeout(timer);
1044
+ timer = void 0;
1045
+ }
1046
+ };
1047
+ };
1048
+ };
1049
+ //#endregion
1050
+ //#region src/delivery/delivery.batch.ts
1051
+ /**
1052
+ * Creates the built-in `batch` strategy.
1053
+ *
1054
+ * Timeline for `interval: 100` with messages A, B, C at 0/20/40ms and D at 300ms:
1055
+ * ```
1056
+ * t=0 push(A) buffer=[A], open 100ms window
1057
+ * t=20 push(B) buffer=[A, B]
1058
+ * t=40 push(C) buffer=[A, B, C]
1059
+ * t=100 window closes → deliver([A, B, C])
1060
+ * t=300 push(D) buffer=[D], open window
1061
+ * t=400 window closes → deliver([D])
1062
+ * ```
1063
+ *
1064
+ * The delivered `extra` is the one of the last message in the batch.
1065
+ * Exported so custom strategies can compose it.
1066
+ */
1067
+ var createBatchDeliveryStrategy = ({ interval, maxSize = Infinity }) => {
1068
+ return ({ deliver }) => {
1069
+ let timer;
1070
+ let buffer = [];
1071
+ let lastExtra;
1072
+ let disposed = false;
1073
+ const flush = () => {
1074
+ if (timer !== void 0) clearTimeout(timer);
1075
+ timer = void 0;
1076
+ if (buffer.length === 0) return;
1077
+ const data = buffer;
1078
+ const extra = lastExtra;
1079
+ buffer = [];
1080
+ lastExtra = void 0;
1081
+ deliver({
1082
+ data,
1083
+ extra
1084
+ });
1085
+ };
1086
+ return {
1087
+ push: ({ data, extra }) => {
1088
+ if (disposed) return;
1089
+ buffer.push(data);
1090
+ lastExtra = extra;
1091
+ if (buffer.length >= maxSize) {
1092
+ flush();
1093
+ return;
1094
+ }
1095
+ if (timer === void 0) timer = setTimeout(flush, interval);
1096
+ },
1097
+ dispose: () => {
1098
+ disposed = true;
1099
+ buffer = [];
1100
+ lastExtra = void 0;
1101
+ if (timer !== void 0) clearTimeout(timer);
1102
+ timer = void 0;
1103
+ }
1104
+ };
1105
+ };
1106
+ };
1107
+ //#endregion
1108
+ //#region src/delivery/delivery.utils.ts
1109
+ /**
1110
+ * Typed identity helper for authoring custom delivery strategies.
1111
+ *
1112
+ * `Input` is the listener's response type, `Output` is what `listen` callbacks will receive. TypeScript cannot
1113
+ * infer `Output` from how you call `deliver`, so declare it here - the same way `createListener<Response>()`
1114
+ * declares the wire type.
1115
+ *
1116
+ * @example
1117
+ * ```ts
1118
+ * const summarize = createDeliveryStrategy<Tick, { count: number; last: Tick }>(({ deliver }) => {
1119
+ * let count = 0;
1120
+ * let last: Tick | undefined;
1121
+ * let timer: ReturnType<typeof setTimeout> | undefined;
1122
+ * return {
1123
+ * push: ({ data, extra }) => {
1124
+ * count += 1;
1125
+ * last = data;
1126
+ * timer ??= setTimeout(() => {
1127
+ * timer = undefined;
1128
+ * deliver({ data: { count, last: last! }, extra });
1129
+ * count = 0;
1130
+ * }, 1000);
1131
+ * },
1132
+ * dispose: () => clearTimeout(timer),
1133
+ * };
1134
+ * });
1135
+ *
1136
+ * const onTick = socket.createListener<Tick>()({ topic: "ticks", delivery: summarize });
1137
+ * onTick.listen(({ data }) => data.count); // data: { count: number; last: Tick }
1138
+ * ```
1139
+ */
1140
+ var createDeliveryStrategy = (strategy) => strategy;
1141
+ /** Narrows a `delivery` value to a custom strategy function. */
1142
+ var isDeliveryStrategy = (delivery) => typeof delivery === "function";
1143
+ /**
1144
+ * Validates a `delivery` value. Throws for unknown presets so misconfiguration fails at listener creation,
1145
+ * not on the first message.
1146
+ */
1147
+ var assertDelivery = (delivery) => {
1148
+ if (isDeliveryStrategy(delivery)) return;
1149
+ 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().`);
1150
+ };
1151
+ /**
1152
+ * Instantiates a delivery controller for one `listen()` subscription.
1153
+ */
1154
+ var createDeliveryController = (delivery, context) => {
1155
+ if (isDeliveryStrategy(delivery)) return delivery(context);
1156
+ const { strategy, ...options } = delivery;
1157
+ return (strategy === "latest" ? createLatestDeliveryStrategy(options) : createBatchDeliveryStrategy(options))(context);
1158
+ };
1159
+ /**
1160
+ * Stable key describing a `delivery` value - presets by value, custom strategies by identity.
1161
+ * Useful for memoization (e.g. React dependency arrays).
1162
+ */
1163
+ var getDeliveryKey = (delivery) => {
1164
+ if (!delivery) return "";
1165
+ if (isDeliveryStrategy(delivery)) return delivery;
1166
+ return JSON.stringify(delivery);
1167
+ };
1168
+ //#endregion
976
1169
  //#region src/listener/listener.ts
977
1170
  /**
978
1171
  * Represents a socket message listener bound to a specific topic. Use it to subscribe to
979
1172
  * typed messages from WebSocket or Server-Sent Events connections via the socket adapter.
1173
+ *
1174
+ * `Response` is the raw message type, `Delivered` is what `listen` callbacks receive. They differ only
1175
+ * when a `delivery` strategy changes the shape (e.g. `batch` delivers `Response[]`).
980
1176
  */
981
1177
  var Listener = class Listener {
982
1178
  topic;
983
1179
  params = void 0;
984
1180
  options = void 0;
1181
+ /**
1182
+ * How messages reach `listen` callbacks. Typed with `any` input on purpose - it keeps `Response`
1183
+ * covariant so partial `ListenerInstance<{ response: ... }>` constraints keep matching wider listeners.
1184
+ */
1185
+ delivery = void 0;
1186
+ /** Stored with an `any` response for the same covariance reason as `delivery`. */
1187
+ listenerOptions;
985
1188
  constructor(socket, listenerOptions) {
986
1189
  this.socket = socket;
987
1190
  this.listenerOptions = listenerOptions;
988
- const { topic, options } = listenerOptions;
1191
+ const { topic, options, delivery, params } = listenerOptions;
989
1192
  this.topic = topic;
990
1193
  this.options = options;
1194
+ this.params = params;
1195
+ this.delivery = delivery;
1196
+ if (delivery) assertDelivery(delivery);
991
1197
  }
992
1198
  /** Set adapter-specific listener options. */
993
1199
  setOptions(options) {
@@ -997,6 +1203,13 @@ var Listener = class Listener {
997
1203
  setParams(params) {
998
1204
  return this.clone({ params });
999
1205
  }
1206
+ /**
1207
+ * Set how messages are delivered to `listen` callbacks - a `latest` / `batch` preset or a custom strategy.
1208
+ * Pass `undefined` to restore immediate delivery. Returns a clone; the callback data type follows the strategy.
1209
+ */
1210
+ setDelivery(delivery) {
1211
+ return this.clone({ delivery });
1212
+ }
1000
1213
  /** Create a new listener instance with optional configuration overrides. */
1001
1214
  clone(options) {
1002
1215
  return new Listener(this.socket, {
@@ -1007,11 +1220,14 @@ var Listener = class Listener {
1007
1220
  }
1008
1221
  /** Start listening for messages on the configured topic. Returns a function to unsubscribe. */
1009
1222
  listen = (callback) => {
1010
- this.socket.adapter.listen(this, callback);
1223
+ const controller = this.delivery ? createDeliveryController(this.delivery, { deliver: callback }) : null;
1224
+ const adapterCallback = controller ? controller.push : callback;
1225
+ this.socket.adapter.listen(this, adapterCallback);
1011
1226
  const removeListener = () => {
1227
+ controller?.dispose();
1012
1228
  this.socket.adapter.removeListener({
1013
1229
  topic: this.topic,
1014
- callback
1230
+ callback: adapterCallback
1015
1231
  });
1016
1232
  };
1017
1233
  return removeListener;
@@ -1079,6 +1295,15 @@ var Socket = class {
1079
1295
  await this.adapter.reconnect();
1080
1296
  };
1081
1297
  /**
1298
+ * Set the url used by the next connection attempts - e.g. when switching tenants, regions or environments at runtime.
1299
+ * Call `reconnect()` to apply it to a live connection, or use `onConnect` to resolve it per attempt.
1300
+ * Listeners stay registered, so they keep receiving events after reconnecting.
1301
+ */
1302
+ setUrl = (url) => {
1303
+ this.url = url;
1304
+ return this;
1305
+ };
1306
+ /**
1082
1307
  * Set the default query params used by the next connection attempts.
1083
1308
  * Call `reconnect()` to apply them to a live connection, or use `onConnect` to resolve them per attempt.
1084
1309
  */
@@ -1436,6 +1661,20 @@ var getServerSentEventsAdapter = (url, adapterOptions) => {
1436
1661
  var ServerSentEventsAdapter = () => new SocketAdapter({ name: "sse" }).setQueryParamsMapper(stringifyQueryParams).setConnector(({ socket, adapter, getQueryParams, onConnect, onConnectFailed, onReconnect, onDisconnect, onListen, onConnected, onDisconnected, onError, onEvent }) => {
1437
1662
  let sse;
1438
1663
  const autoConnect = typeof socket.adapter.adapterOptions?.autoConnect === "boolean" ? socket.adapter.adapterOptions?.autoConnect : true;
1664
+ /** Maps an incoming message to the listener event, reporting decoder failures instead of throwing */
1665
+ const decodeMessage = (event, decode) => {
1666
+ try {
1667
+ if (decode) return decode(event);
1668
+ const { topic, data } = parseMessageEvent(event);
1669
+ return {
1670
+ topic,
1671
+ data
1672
+ };
1673
+ } catch (error) {
1674
+ onError({ error });
1675
+ return null;
1676
+ }
1677
+ };
1439
1678
  const connect = async () => {
1440
1679
  const connection = await onConnect();
1441
1680
  if (!connection) return socket.adapter.connected;
@@ -1458,12 +1697,13 @@ var ServerSentEventsAdapter = () => new SocketAdapter({ name: "sse" }).setQueryP
1458
1697
  const error = getSocketError(event);
1459
1698
  onError({ error: new Error(error) });
1460
1699
  });
1700
+ const { decode } = connection.adapterOptions || {};
1461
1701
  eventSource.addEventListener("message", (newEvent) => {
1462
- const { topic, data, event } = parseMessageEvent(newEvent);
1463
- onEvent({
1464
- topic,
1465
- data,
1466
- extra: event
1702
+ const message = decodeMessage(newEvent, decode);
1703
+ if (message) onEvent({
1704
+ topic: message.topic,
1705
+ data: message.data,
1706
+ extra: newEvent
1467
1707
  });
1468
1708
  });
1469
1709
  return new Promise((resolve) => {
@@ -1553,6 +1793,7 @@ var topicMatchesPattern = (topic, pattern) => {
1553
1793
  var applySocketObjectDefaults = (instance, config) => {
1554
1794
  let result = instance;
1555
1795
  if (config.options !== void 0) result = result.setOptions(config.options);
1796
+ if (config.delivery !== void 0 && result instanceof Listener) result = result.setDelivery(config.delivery);
1556
1797
  return result;
1557
1798
  };
1558
1799
  var applySocketDefaults = ({ instance, topic, sdkPath, defaults }) => {
@@ -1653,6 +1894,6 @@ var createSocketConfiguration = () => {
1653
1894
  return (defaults) => defaults;
1654
1895
  };
1655
1896
  //#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 };
1897
+ 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
1898
 
1658
1899
  //# sourceMappingURL=index.mjs.map