@hyper-fetch/sockets 8.1.1 → 8.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.
@@ -9,10 +9,77 @@ export type ListenerInstanceProperties = {
9
9
  socket?: SocketInstance;
10
10
  hasParams?: boolean;
11
11
  };
12
+ /**
13
+ * The **constraint** form of a Listener type. Mindset: "any Listener that matches this partial shape".
14
+ *
15
+ * Use `ListenerInstance` when you are writing a **reusable abstraction** that accepts listeners
16
+ * from the outside - generic helpers (`<T extends ListenerInstance>`), reusable UI components /
17
+ * hooks, `sdk.$configure({...})` callbacks, mocking utilities, return types, etc.
18
+ *
19
+ * Unspecified generic parameters default to `any` **on purpose**: an omitted field means
20
+ * "I do not care about that field, the caller picks anything". This is exactly what you want
21
+ * for a constraint - any concrete `Listener` satisfies it. Partial constraints work too:
22
+ * `ListenerInstance<{ response: { text: string } }>` accepts every listener whose response has a
23
+ * `text` field, regardless of topic, params, etc.
24
+ *
25
+ * For describing a **single topic** inside a socket SDK schema, use {@link ListenerModel} instead.
26
+ * `ListenerModel` uses safe non-`any` defaults (`unknown`, `string`, `false`) so omitted fields
27
+ * stay strict instead of silently collapsing to `any`.
28
+ *
29
+ * @see {@link ListenerModel} - definition counterpart for SDK schema modeling.
30
+ */
12
31
  export type ListenerInstance<ListenerProperties extends ListenerInstanceProperties = {}> = Listener<TypeWithDefaults<ListenerProperties, "response", any>, TypeWithDefaults<ListenerProperties, "topic", any>, TypeWithDefaults<ListenerProperties, "socket", SocketInstance>, TypeWithDefaults<ListenerProperties, "hasParams", any>>;
32
+ /**
33
+ * The **definition** form of a Listener type. Mindset: "**this** specific topic".
34
+ *
35
+ * Use `ListenerModel` when you are **defining** a listener inside a socket SDK schema. Unlike
36
+ * {@link ListenerInstance}, every unspecified field stays strict instead of falling back to
37
+ * `any` - because in a definition, an omitted field means "**this topic carries no params**",
38
+ * not "anything goes". The type system will reject mismatches at the call site instead of
39
+ * silently erasing them.
40
+ *
41
+ * The `socket` field is also injected automatically by `createSocketSdk(socket)` at the SDK
42
+ * boundary, so you never need to repeat it inside schema declarations.
43
+ *
44
+ * ### Defaults for omitted fields
45
+ *
46
+ * | Field | Default | Why |
47
+ * | ----------- | ---------------- | ------------------------------------------------------------------ |
48
+ * | `response` | `unknown` | Forces narrowing in consumer code; never silently widened. |
49
+ * | `topic` | `string` | Allows literal narrowing without erasure. Pass a string literal. |
50
+ * | `socket` | `SocketInstance` | Injected by `createSocketSdk(socket)`; do not set this manually. |
51
+ * | `hasParams` | `false` | "Caller must call `.setParams()`." Override only when bound. |
52
+ *
53
+ * @example
54
+ * ```ts
55
+ * // Schema describes shape only - socket is injected by createSocketSdk(socket).
56
+ * type ChatSchema = {
57
+ * chat: {
58
+ * messages: {
59
+ * $listener: ListenerModel<{
60
+ * response: { text: string; user: string };
61
+ * topic: "chat/messages";
62
+ * }>;
63
+ * };
64
+ * $roomId: {
65
+ * $listener: ListenerModel<{
66
+ * response: { text: string; user: string };
67
+ * topic: "chat/:roomId";
68
+ * }>;
69
+ * };
70
+ * };
71
+ * };
72
+ * ```
73
+ *
74
+ * @see {@link ListenerInstance} - constraint counterpart for accepting any Listener.
75
+ */
76
+ export type ListenerModel<ListenerProperties extends ListenerInstanceProperties = {}> = Listener<TypeWithDefaults<ListenerProperties, "response", unknown>, TypeWithDefaults<ListenerProperties, "topic", string>, TypeWithDefaults<ListenerProperties, "socket", SocketInstance>, TypeWithDefaults<ListenerProperties, "hasParams", false>>;
13
77
  export type ListenerOfAdapter<A extends SocketAdapterInstance> = Listener<any, any, Socket<A>, any>;
78
+ /** Configuration options for creating a Listener instance. */
14
79
  export type ListenerOptionsType<Topic extends string, AdapterType extends SocketAdapterInstance> = {
80
+ /** The topic/channel name to listen on */
15
81
  topic: Topic;
82
+ /** Adapter-specific listener options */
16
83
  options?: ExtractAdapterListenerOptionsType<AdapterType>;
17
84
  };
18
85
  export type ListenerConfigurationType<Params, Topic extends string, Socket extends SocketInstance> = {
@@ -1 +1 @@
1
- {"version":3,"file":"listener.types.d.ts","sourceRoot":"","sources":["../../src/listener/listener.types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"listener.types.d.ts","sourceRoot":"","sources":["../../src/listener/listener.types.ts"],"names":[],"mappings":"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"}
package/dist/sdk/sdk.d.ts CHANGED
@@ -1,8 +1,22 @@
1
1
  import { SocketInstance } from '../socket';
2
- import { ListenerInstance } from '../listener';
3
- import { EmitterInstance } from '../emitter';
2
+ import { Listener, ListenerInstance } from '../listener';
3
+ import { Emitter, EmitterInstance } from '../emitter';
4
+ import { ExtractListenerResponseType, ExtractListenerTopicType, ExtractListenerHasParamsType, ExtractEmitterPayloadType, ExtractEmitterTopicType, ExtractEmitterHasPayloadType, ExtractEmitterHasParamsType } from '../types';
4
5
  export type RecursiveSocketSchemaType = Record<string, any>;
5
6
  type SocketSdkLeaf = ListenerInstance | EmitterInstance;
7
+ /**
8
+ * Recursively walks a socket schema and rebuilds every `Listener` / `Emitter` leaf with the
9
+ * SDK's actual socket type injected into the `Socket` generic slot. Lets users omit `socket`
10
+ * from their `ListenerModel<{...}>` / `EmitterModel<{...}>` declarations - the SDK fills it
11
+ * in from the socket passed to `createSocketSdk(socket)`.
12
+ *
13
+ * Non-leaf values (primitive types, plain values) are passed through unchanged. Nested schema
14
+ * objects are recursed into. Depth is guarded at 10 levels to keep the type checker within
15
+ * reasonable bounds.
16
+ */
17
+ export type InjectSocket<T, S extends SocketInstance, Depth extends unknown[] = []> = Depth["length"] extends 10 ? T : T extends ListenerInstance ? Listener<ExtractListenerResponseType<T>, ExtractListenerTopicType<T> extends string ? ExtractListenerTopicType<T> : string, S, ExtractListenerHasParamsType<T> extends boolean ? ExtractListenerHasParamsType<T> : false> : T extends EmitterInstance ? Emitter<ExtractEmitterPayloadType<T>, ExtractEmitterTopicType<T> extends string ? ExtractEmitterTopicType<T> : string, S, ExtractEmitterHasPayloadType<T> extends boolean ? ExtractEmitterHasPayloadType<T> : false, ExtractEmitterHasParamsType<T> extends boolean ? ExtractEmitterHasParamsType<T> : false> : T extends Record<string, any> ? {
18
+ [K in keyof T]: InjectSocket<T[K], S, [...Depth, unknown]>;
19
+ } : T;
6
20
  type ExtractTopicFromLeaf<T> = T extends {
7
21
  topic: infer Topic extends string;
8
22
  } ? Topic : never;
@@ -52,10 +66,18 @@ export type CreateSocketSdkOptions<Schema extends RecursiveSocketSchemaType = Re
52
66
  /** Per-path defaults (plain objects or functions) */
53
67
  defaults?: SocketSdkConfigurationMap<Schema>;
54
68
  };
55
- export type SocketSdkInstance<Schema extends RecursiveSocketSchemaType> = Schema & {
56
- $configure: (defaults: SocketSdkConfigurationMap<Schema>) => SocketSdkInstance<Schema>;
69
+ /**
70
+ * The fully-resolved Socket SDK instance type returned by `createSocketSdk`.
71
+ *
72
+ * The schema is rewritten via {@link InjectSocket} so every `Listener` / `Emitter` leaf
73
+ * carries the actual socket type passed to `createSocketSdk(socket)` - users do not need
74
+ * to repeat `socket: AppSocket` in every `ListenerModel<{...}>` / `EmitterModel<{...}>`
75
+ * declaration.
76
+ */
77
+ export type SocketSdkInstance<Schema extends RecursiveSocketSchemaType, S extends SocketInstance = SocketInstance> = InjectSocket<Schema, S> & {
78
+ $configure: (defaults: SocketSdkConfigurationMap<Schema>) => SocketSdkInstance<Schema, S>;
57
79
  };
58
- export declare const createSocketSdk: <S extends SocketInstance, RecursiveSchema extends RecursiveSocketSchemaType>(socket: S, options?: CreateSocketSdkOptions<RecursiveSchema>) => SocketSdkInstance<RecursiveSchema>;
80
+ export declare const createSocketSdk: <S extends SocketInstance, RecursiveSchema extends RecursiveSocketSchemaType>(socket: S, options?: CreateSocketSdkOptions<RecursiveSchema>) => SocketSdkInstance<RecursiveSchema, S>;
59
81
  /**
60
82
  * Type-safe factory for creating socket SDK configuration maps.
61
83
  *
@@ -1 +1 @@
1
- {"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/sdk/sdk.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/sdk/sdk.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hyper-fetch/sockets",
3
- "version": "8.1.1",
3
+ "version": "8.2.0",
4
4
  "description": "Sockets connection for hyper-fetch",
5
5
  "author": "Maciej Pyrc <maciekpyrc@gmail.com>, Kacper Skawina <kacper.skawina@gmail.com>",
6
6
  "homepage": "https://hyperfetch.bettertyped.com/",
@@ -12,7 +12,7 @@ import { getSocketError } from "../utils/socket.errors";
12
12
 
13
13
  /**
14
14
  * -------------------------------------------
15
- * Websocket
15
+ * Server-Sent Events
16
16
  * -------------------------------------------
17
17
  */
18
18
 
@@ -25,6 +25,7 @@ export type ServerSentEventsAdapterType = SocketAdapter<
25
25
  typeof stringifyQueryParams
26
26
  >;
27
27
 
28
+ /** Create a preconfigured socket adapter for Server-Sent Events (EventSource) connections. */
28
29
  export const ServerSentEventsAdapter = (): ServerSentEventsAdapterType =>
29
30
  new SocketAdapter<
30
31
  MessageEvent<any>,
@@ -26,6 +26,7 @@ export type WebsocketAdapterType = SocketAdapter<
26
26
  typeof stringifyQueryParams
27
27
  >;
28
28
 
29
+ /** Create a preconfigured socket adapter for native WebSocket connections. */
29
30
  export const WebsocketAdapter = (): WebsocketAdapterType =>
30
31
  new SocketAdapter<
31
32
  MessageEvent<any>,
@@ -4,6 +4,10 @@ import type { SocketInstance } from "socket";
4
4
  import type { EmitMethodOptionsType, EmitterCloneOptionsType, EmitterOptionsType, EmitType } from "emitter";
5
5
  import type { ExtractAdapterEmitterOptionsType, ExtractSocketAdapterType } from "types";
6
6
 
7
+ /**
8
+ * Represents a socket message emitter bound to a specific topic. Use it to send typed payloads
9
+ * over WebSocket or Server-Sent Events connections via the socket adapter.
10
+ */
7
11
  export class Emitter<
8
12
  Payload,
9
13
  Topic extends string,
@@ -35,16 +39,19 @@ export class Emitter<
35
39
  this.params = snapshot?.params;
36
40
  }
37
41
 
42
+ /** Set adapter-specific emit options (e.g., acknowledgment, timeout). */
38
43
  setOptions(options: ExtractAdapterEmitterOptionsType<ExtractSocketAdapterType<Socket>> | undefined) {
39
44
  return this.clone({ options });
40
45
  }
41
46
 
47
+ /** Set the message payload to be emitted. */
42
48
  setPayload = <D extends Payload>(payload: D) => {
43
49
  return this.clone<D, D extends EmptyTypes ? false : true, HasParams>({
44
50
  payload,
45
51
  });
46
52
  };
47
53
 
54
+ /** Set a mapper function that transforms the payload before it is sent. */
48
55
  setPayloadMapper = <DataMapper extends (payload: Payload) => any | Promise<any>>(payloadMapper: DataMapper) => {
49
56
  const cloned = this.clone<Payload, HasPayload, HasParams>(undefined);
50
57
 
@@ -53,6 +60,7 @@ export class Emitter<
53
60
  return cloned;
54
61
  };
55
62
 
63
+ /** Set the URL path parameters for the topic (e.g., `:channelId`). */
56
64
  setParams(params: NonNullable<ExtractUrlParams<Topic>>) {
57
65
  return this.clone<Payload, HasPayload, true>({ params });
58
66
  }
@@ -68,6 +76,7 @@ export class Emitter<
68
76
  return topic as Topic;
69
77
  };
70
78
 
79
+ /** Create a new emitter instance with optional configuration overrides. */
71
80
  clone<
72
81
  NewPayload extends Payload = Payload,
73
82
  NewHasPayload extends boolean = HasPayload,
@@ -94,6 +103,7 @@ export class Emitter<
94
103
  return newInstance;
95
104
  }
96
105
 
106
+ /** Send the message through the socket adapter on the configured topic. */
97
107
  emit: EmitType<Emitter<Payload, Topic, Socket, HasPayload, HasParams>> = (options = {}) => {
98
108
  const typedOptions = options as EmitMethodOptionsType<Emitter<Payload, Topic, Socket, HasPayload, HasParams>>;
99
109
  const instance = this.clone<Payload, HasPayload, HasParams>(typedOptions);
@@ -22,6 +22,25 @@ export type EmitterInstanceProperties = {
22
22
  hasPayload?: boolean;
23
23
  };
24
24
 
25
+ /**
26
+ * The **constraint** form of an Emitter type. Mindset: "any Emitter that matches this partial shape".
27
+ *
28
+ * Use `EmitterInstance` when you are writing a **reusable abstraction** that accepts emitters
29
+ * from the outside - generic helpers (`<T extends EmitterInstance>`), reusable UI components /
30
+ * hooks, `sdk.$configure({...})` callbacks, mocking utilities, return types, etc.
31
+ *
32
+ * Unspecified generic parameters default to `any` **on purpose**: an omitted field means
33
+ * "I do not care about that field, the caller picks anything". This is exactly what you want
34
+ * for a constraint - any concrete `Emitter` satisfies it. Partial constraints work too:
35
+ * `EmitterInstance<{ payload: { text: string } }>` accepts every emitter whose payload has a
36
+ * `text` field, regardless of topic, params, etc.
37
+ *
38
+ * For describing a **single topic** inside a socket SDK schema, use {@link EmitterModel} instead.
39
+ * `EmitterModel` uses safe non-`any` defaults (`undefined`, `string`, `false`) so omitted fields
40
+ * stay strict instead of silently collapsing to `any`.
41
+ *
42
+ * @see {@link EmitterModel} - definition counterpart for SDK schema modeling.
43
+ */
25
44
  export type EmitterInstance<EmitterProperties extends EmitterInstanceProperties = {}> = Emitter<
26
45
  TypeWithDefaults<EmitterProperties, "payload", any>,
27
46
  TypeWithDefaults<EmitterProperties, "topic", any>,
@@ -30,13 +49,63 @@ export type EmitterInstance<EmitterProperties extends EmitterInstanceProperties
30
49
  TypeWithDefaults<EmitterProperties, "hasParams", any>
31
50
  >;
32
51
 
52
+ /**
53
+ * The **definition** form of an Emitter type. Mindset: "**this** specific topic".
54
+ *
55
+ * Use `EmitterModel` when you are **defining** an emitter inside a socket SDK schema. Unlike
56
+ * {@link EmitterInstance}, every unspecified field stays strict instead of falling back to
57
+ * `any` - because in a definition, an omitted field means "**this topic carries no payload**",
58
+ * not "anything goes". The type system will reject mismatches at the call site instead of
59
+ * silently erasing them.
60
+ *
61
+ * The `socket` field is also injected automatically by `createSocketSdk(socket)` at the SDK
62
+ * boundary, so you never need to repeat it inside schema declarations.
63
+ *
64
+ * ### Defaults for omitted fields
65
+ *
66
+ * | Field | Default | Why |
67
+ * | ------------ | ---------------- | ---------------------------------------------------------------- |
68
+ * | `payload` | `undefined` | "No payload declared." `.setData()` is required for typed bodies.|
69
+ * | `topic` | `string` | Allows literal narrowing without erasure. Pass a string literal. |
70
+ * | `socket` | `SocketInstance` | Injected by `createSocketSdk(socket)`; do not set this manually. |
71
+ * | `hasPayload` | `false` | "Caller must call `.setData()`." Override only when bound. |
72
+ * | `hasParams` | `false` | "Caller must call `.setParams()`." Override only when bound. |
73
+ *
74
+ * @example
75
+ * ```ts
76
+ * // Schema describes shape only - socket is injected by createSocketSdk(socket).
77
+ * type ChatSchema = {
78
+ * chat: {
79
+ * messages: {
80
+ * $emitter: EmitterModel<{
81
+ * payload: { text: string };
82
+ * topic: "chat/messages";
83
+ * }>;
84
+ * };
85
+ * };
86
+ * };
87
+ * ```
88
+ *
89
+ * @see {@link EmitterInstance} - constraint counterpart for accepting any Emitter.
90
+ */
91
+ export type EmitterModel<EmitterProperties extends EmitterInstanceProperties = {}> = Emitter<
92
+ TypeWithDefaults<EmitterProperties, "payload", undefined>,
93
+ TypeWithDefaults<EmitterProperties, "topic", string>,
94
+ TypeWithDefaults<EmitterProperties, "socket", SocketInstance>,
95
+ TypeWithDefaults<EmitterProperties, "hasPayload", false>,
96
+ TypeWithDefaults<EmitterProperties, "hasParams", false>
97
+ >;
98
+
33
99
  export type EmitterCloneOptionsType<Payload, Params, Topic extends string, Socket extends SocketInstance> = {
34
100
  payload?: Payload;
35
101
  params?: Params | null;
36
102
  } & Partial<EmitterOptionsType<Topic, ExtractSocketAdapterType<Socket>>>;
37
103
 
104
+ /** Configuration options for creating an Emitter instance. */
38
105
  export type EmitterOptionsType<Topic extends string, AdapterType extends SocketAdapterInstance> = {
106
+ /** The topic/channel name to emit messages on */
39
107
  topic: Topic;
108
+ /** Adapter-specific emit options */
40
109
  options?: ExtractAdapterEmitterOptionsType<AdapterType>;
41
110
  };
42
111
 
@@ -4,6 +4,10 @@ import type { SocketInstance } from "socket";
4
4
  import type { ListenType, ListenerConfigurationType, ListenerOptionsType } from "listener";
5
5
  import type { ExtractAdapterListenerOptionsType, ExtractSocketAdapterType } from "types";
6
6
 
7
+ /**
8
+ * Represents a socket message listener bound to a specific topic. Use it to subscribe to
9
+ * typed messages from WebSocket or Server-Sent Events connections via the socket adapter.
10
+ */
7
11
  export class Listener<
8
12
  Response,
9
13
  Topic extends string,
@@ -23,14 +27,17 @@ export class Listener<
23
27
  this.options = options;
24
28
  }
25
29
 
30
+ /** Set adapter-specific listener options. */
26
31
  setOptions(options: ExtractAdapterListenerOptionsType<ExtractSocketAdapterType<Socket>>) {
27
32
  return this.clone({ options });
28
33
  }
29
34
 
35
+ /** Set the URL path parameters for the topic (e.g., `:channelId`). */
30
36
  setParams(params: ExtractUrlParams<Topic>) {
31
37
  return this.clone<true>({ params });
32
38
  }
33
39
 
40
+ /** Create a new listener instance with optional configuration overrides. */
34
41
  clone<NewHasParams extends true | false = HasParams>(
35
42
  options?: ListenerConfigurationType<ExtractUrlParams<Topic>, Topic, Socket>,
36
43
  ) {
@@ -43,6 +50,7 @@ export class Listener<
43
50
  return newInstance;
44
51
  }
45
52
 
53
+ /** Start listening for messages on the configured topic. Returns a function to unsubscribe. */
46
54
  listen: ListenType<Listener<Response, Topic, Socket, HasParams>, Socket> = (
47
55
  callback: Parameters<ListenType<Listener<Response, Topic, Socket, HasParams>, Socket>>[0],
48
56
  ) => {
@@ -21,6 +21,25 @@ export type ListenerInstanceProperties = {
21
21
  hasParams?: boolean;
22
22
  };
23
23
 
24
+ /**
25
+ * The **constraint** form of a Listener type. Mindset: "any Listener that matches this partial shape".
26
+ *
27
+ * Use `ListenerInstance` when you are writing a **reusable abstraction** that accepts listeners
28
+ * from the outside - generic helpers (`<T extends ListenerInstance>`), reusable UI components /
29
+ * hooks, `sdk.$configure({...})` callbacks, mocking utilities, return types, etc.
30
+ *
31
+ * Unspecified generic parameters default to `any` **on purpose**: an omitted field means
32
+ * "I do not care about that field, the caller picks anything". This is exactly what you want
33
+ * for a constraint - any concrete `Listener` satisfies it. Partial constraints work too:
34
+ * `ListenerInstance<{ response: { text: string } }>` accepts every listener whose response has a
35
+ * `text` field, regardless of topic, params, etc.
36
+ *
37
+ * For describing a **single topic** inside a socket SDK schema, use {@link ListenerModel} instead.
38
+ * `ListenerModel` uses safe non-`any` defaults (`unknown`, `string`, `false`) so omitted fields
39
+ * stay strict instead of silently collapsing to `any`.
40
+ *
41
+ * @see {@link ListenerModel} - definition counterpart for SDK schema modeling.
42
+ */
24
43
  export type ListenerInstance<ListenerProperties extends ListenerInstanceProperties = {}> = Listener<
25
44
  TypeWithDefaults<ListenerProperties, "response", any>,
26
45
  TypeWithDefaults<ListenerProperties, "topic", any>,
@@ -28,10 +47,64 @@ export type ListenerInstance<ListenerProperties extends ListenerInstanceProperti
28
47
  TypeWithDefaults<ListenerProperties, "hasParams", any>
29
48
  >;
30
49
 
50
+ /**
51
+ * The **definition** form of a Listener type. Mindset: "**this** specific topic".
52
+ *
53
+ * Use `ListenerModel` when you are **defining** a listener inside a socket SDK schema. Unlike
54
+ * {@link ListenerInstance}, every unspecified field stays strict instead of falling back to
55
+ * `any` - because in a definition, an omitted field means "**this topic carries no params**",
56
+ * not "anything goes". The type system will reject mismatches at the call site instead of
57
+ * silently erasing them.
58
+ *
59
+ * The `socket` field is also injected automatically by `createSocketSdk(socket)` at the SDK
60
+ * boundary, so you never need to repeat it inside schema declarations.
61
+ *
62
+ * ### Defaults for omitted fields
63
+ *
64
+ * | Field | Default | Why |
65
+ * | ----------- | ---------------- | ------------------------------------------------------------------ |
66
+ * | `response` | `unknown` | Forces narrowing in consumer code; never silently widened. |
67
+ * | `topic` | `string` | Allows literal narrowing without erasure. Pass a string literal. |
68
+ * | `socket` | `SocketInstance` | Injected by `createSocketSdk(socket)`; do not set this manually. |
69
+ * | `hasParams` | `false` | "Caller must call `.setParams()`." Override only when bound. |
70
+ *
71
+ * @example
72
+ * ```ts
73
+ * // Schema describes shape only - socket is injected by createSocketSdk(socket).
74
+ * type ChatSchema = {
75
+ * chat: {
76
+ * messages: {
77
+ * $listener: ListenerModel<{
78
+ * response: { text: string; user: string };
79
+ * topic: "chat/messages";
80
+ * }>;
81
+ * };
82
+ * $roomId: {
83
+ * $listener: ListenerModel<{
84
+ * response: { text: string; user: string };
85
+ * topic: "chat/:roomId";
86
+ * }>;
87
+ * };
88
+ * };
89
+ * };
90
+ * ```
91
+ *
92
+ * @see {@link ListenerInstance} - constraint counterpart for accepting any Listener.
93
+ */
94
+ export type ListenerModel<ListenerProperties extends ListenerInstanceProperties = {}> = Listener<
95
+ TypeWithDefaults<ListenerProperties, "response", unknown>,
96
+ TypeWithDefaults<ListenerProperties, "topic", string>,
97
+ TypeWithDefaults<ListenerProperties, "socket", SocketInstance>,
98
+ TypeWithDefaults<ListenerProperties, "hasParams", false>
99
+ >;
100
+
31
101
  export type ListenerOfAdapter<A extends SocketAdapterInstance> = Listener<any, any, Socket<A>, any>;
32
102
 
103
+ /** Configuration options for creating a Listener instance. */
33
104
  export type ListenerOptionsType<Topic extends string, AdapterType extends SocketAdapterInstance> = {
105
+ /** The topic/channel name to listen on */
34
106
  topic: Topic;
107
+ /** Adapter-specific listener options */
35
108
  options?: ExtractAdapterListenerOptionsType<AdapterType>;
36
109
  };
37
110
 
package/src/sdk/sdk.ts CHANGED
@@ -1,11 +1,51 @@
1
1
  import type { SocketInstance } from "socket";
2
- import type { ListenerInstance } from "listener";
3
- import type { EmitterInstance } from "emitter";
2
+ import type { Listener, ListenerInstance } from "listener";
3
+ import type { Emitter, EmitterInstance } from "emitter";
4
+ import type {
5
+ ExtractListenerResponseType,
6
+ ExtractListenerTopicType,
7
+ ExtractListenerHasParamsType,
8
+ ExtractEmitterPayloadType,
9
+ ExtractEmitterTopicType,
10
+ ExtractEmitterHasPayloadType,
11
+ ExtractEmitterHasParamsType,
12
+ } from "types";
4
13
 
5
14
  export type RecursiveSocketSchemaType = Record<string, any>;
6
15
 
7
16
  type SocketSdkLeaf = ListenerInstance | EmitterInstance;
8
17
 
18
+ /**
19
+ * Recursively walks a socket schema and rebuilds every `Listener` / `Emitter` leaf with the
20
+ * SDK's actual socket type injected into the `Socket` generic slot. Lets users omit `socket`
21
+ * from their `ListenerModel<{...}>` / `EmitterModel<{...}>` declarations - the SDK fills it
22
+ * in from the socket passed to `createSocketSdk(socket)`.
23
+ *
24
+ * Non-leaf values (primitive types, plain values) are passed through unchanged. Nested schema
25
+ * objects are recursed into. Depth is guarded at 10 levels to keep the type checker within
26
+ * reasonable bounds.
27
+ */
28
+ export type InjectSocket<T, S extends SocketInstance, Depth extends unknown[] = []> = Depth["length"] extends 10
29
+ ? T
30
+ : T extends ListenerInstance
31
+ ? Listener<
32
+ ExtractListenerResponseType<T>,
33
+ ExtractListenerTopicType<T> extends string ? ExtractListenerTopicType<T> : string,
34
+ S,
35
+ ExtractListenerHasParamsType<T> extends boolean ? ExtractListenerHasParamsType<T> : false
36
+ >
37
+ : T extends EmitterInstance
38
+ ? Emitter<
39
+ ExtractEmitterPayloadType<T>,
40
+ ExtractEmitterTopicType<T> extends string ? ExtractEmitterTopicType<T> : string,
41
+ S,
42
+ ExtractEmitterHasPayloadType<T> extends boolean ? ExtractEmitterHasPayloadType<T> : false,
43
+ ExtractEmitterHasParamsType<T> extends boolean ? ExtractEmitterHasParamsType<T> : false
44
+ >
45
+ : T extends Record<string, any>
46
+ ? { [K in keyof T]: InjectSocket<T[K], S, [...Depth, unknown]> }
47
+ : T;
48
+
9
49
  type ExtractTopicFromLeaf<T> = T extends { topic: infer Topic extends string } ? Topic : never;
10
50
 
11
51
  /**
@@ -225,14 +265,25 @@ const createSocketRecursiveProxy = ({
225
265
  });
226
266
  };
227
267
 
228
- export type SocketSdkInstance<Schema extends RecursiveSocketSchemaType> = Schema & {
229
- $configure: (defaults: SocketSdkConfigurationMap<Schema>) => SocketSdkInstance<Schema>;
268
+ /**
269
+ * The fully-resolved Socket SDK instance type returned by `createSocketSdk`.
270
+ *
271
+ * The schema is rewritten via {@link InjectSocket} so every `Listener` / `Emitter` leaf
272
+ * carries the actual socket type passed to `createSocketSdk(socket)` - users do not need
273
+ * to repeat `socket: AppSocket` in every `ListenerModel<{...}>` / `EmitterModel<{...}>`
274
+ * declaration.
275
+ */
276
+ export type SocketSdkInstance<
277
+ Schema extends RecursiveSocketSchemaType,
278
+ S extends SocketInstance = SocketInstance,
279
+ > = InjectSocket<Schema, S> & {
280
+ $configure: (defaults: SocketSdkConfigurationMap<Schema>) => SocketSdkInstance<Schema, S>;
230
281
  };
231
282
 
232
283
  export const createSocketSdk = <S extends SocketInstance, RecursiveSchema extends RecursiveSocketSchemaType>(
233
284
  socket: S,
234
285
  options?: CreateSocketSdkOptions<RecursiveSchema>,
235
- ): SocketSdkInstance<RecursiveSchema> => {
286
+ ): SocketSdkInstance<RecursiveSchema, S> => {
236
287
  const { camelCaseToKebabCase = true, ...rest } = options ?? {};
237
288
 
238
289
  const mergedOptions: CreateSocketSdkOptions<RecursiveSchema> = { camelCaseToKebabCase, ...rest };
@@ -251,7 +302,7 @@ export const createSocketSdk = <S extends SocketInstance, RecursiveSchema extend
251
302
  }
252
303
  return target[key];
253
304
  },
254
- }) as SocketSdkInstance<RecursiveSchema>;
305
+ }) as SocketSdkInstance<RecursiveSchema, S>;
255
306
  };
256
307
 
257
308
  /**