@constructive-io/sdk 0.20.7 → 0.20.8

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 (41) hide show
  1. package/admin/orm/client.d.ts +30 -0
  2. package/admin/orm/client.js +41 -1
  3. package/admin/orm/realtime.d.ts +142 -0
  4. package/admin/orm/realtime.js +104 -0
  5. package/auth/orm/client.d.ts +30 -0
  6. package/auth/orm/client.js +41 -1
  7. package/auth/orm/realtime.d.ts +142 -0
  8. package/auth/orm/realtime.js +104 -0
  9. package/esm/admin/orm/client.d.ts +30 -0
  10. package/esm/admin/orm/client.js +39 -0
  11. package/esm/admin/orm/realtime.d.ts +142 -0
  12. package/esm/admin/orm/realtime.js +100 -0
  13. package/esm/auth/orm/client.d.ts +30 -0
  14. package/esm/auth/orm/client.js +39 -0
  15. package/esm/auth/orm/realtime.d.ts +142 -0
  16. package/esm/auth/orm/realtime.js +100 -0
  17. package/esm/objects/orm/client.d.ts +30 -0
  18. package/esm/objects/orm/client.js +39 -0
  19. package/esm/objects/orm/realtime.d.ts +142 -0
  20. package/esm/objects/orm/realtime.js +100 -0
  21. package/esm/public/orm/client.d.ts +30 -0
  22. package/esm/public/orm/client.js +39 -0
  23. package/esm/public/orm/index.d.ts +8 -3
  24. package/esm/public/orm/input-types.d.ts +14 -3
  25. package/esm/public/orm/mutation/index.d.ts +14 -6
  26. package/esm/public/orm/mutation/index.js +18 -6
  27. package/esm/public/orm/realtime.d.ts +142 -0
  28. package/esm/public/orm/realtime.js +100 -0
  29. package/objects/orm/client.d.ts +30 -0
  30. package/objects/orm/client.js +41 -1
  31. package/objects/orm/realtime.d.ts +142 -0
  32. package/objects/orm/realtime.js +104 -0
  33. package/package.json +2 -2
  34. package/public/orm/client.d.ts +30 -0
  35. package/public/orm/client.js +41 -1
  36. package/public/orm/index.d.ts +8 -3
  37. package/public/orm/input-types.d.ts +14 -3
  38. package/public/orm/mutation/index.d.ts +14 -6
  39. package/public/orm/mutation/index.js +18 -6
  40. package/public/orm/realtime.d.ts +142 -0
  41. package/public/orm/realtime.js +104 -0
@@ -4,7 +4,10 @@
4
4
  * DO NOT EDIT - changes will be overwritten
5
5
  */
6
6
  import type { GraphQLAdapter, GraphQLError, QueryResult } from '@constructive-io/graphql-query/runtime';
7
+ import type { ConnectionState, ConnectionStateListener, RealtimeConfig, SubscriptionEvent, SubscriptionFieldMeta, Unsubscribe } from './realtime';
7
8
  export type { GraphQLAdapter, GraphQLError, QueryResult, } from '@constructive-io/graphql-query/runtime';
9
+ export type { ConnectionState, ConnectionStateListener, RealtimeConfig, SubscribeOptions, SubscriptionEvent, SubscriptionFieldMeta, SubscriptionOperation, Unsubscribe, WsClient, } from './realtime';
10
+ export { RealtimeManager } from './realtime';
8
11
  /**
9
12
  * Default adapter that uses fetch for HTTP requests.
10
13
  *
@@ -41,6 +44,12 @@ export interface OrmClientConfig {
41
44
  fetch?: typeof globalThis.fetch;
42
45
  /** Custom adapter for GraphQL execution (overrides endpoint/headers/fetch) */
43
46
  adapter?: GraphQLAdapter;
47
+ /**
48
+ * Optional realtime (WebSocket) configuration.
49
+ * When provided, enables subscription methods on models.
50
+ * The WebSocket connection is created lazily on first subscribe().
51
+ */
52
+ realtime?: RealtimeConfig;
44
53
  }
45
54
  /**
46
55
  * Error thrown when GraphQL request fails
@@ -52,8 +61,19 @@ export declare class GraphQLRequestError extends Error {
52
61
  }
53
62
  export declare class OrmClient {
54
63
  private adapter;
64
+ private realtimeManager?;
55
65
  constructor(config: OrmClientConfig);
56
66
  execute<T>(document: string, variables?: Record<string, unknown>): Promise<QueryResult<T>>;
67
+ /**
68
+ * Subscribe to a GraphQL subscription operation.
69
+ * Used by generated model subscribe() methods.
70
+ * @throws Error if realtime is not configured
71
+ */
72
+ subscribe<T>(meta: SubscriptionFieldMeta, document: string, variables: Record<string, unknown>, options: {
73
+ onEvent: (event: SubscriptionEvent<T>) => void;
74
+ onError?: (error: Error) => void;
75
+ onComplete?: () => void;
76
+ }): Unsubscribe;
57
77
  /**
58
78
  * Set headers for requests.
59
79
  * Only works if the adapter supports headers.
@@ -64,4 +84,14 @@ export declare class OrmClient {
64
84
  * Returns empty string if the adapter doesn't have an endpoint.
65
85
  */
66
86
  getEndpoint(): string;
87
+ /** Get current WebSocket connection state */
88
+ getConnectionState(): ConnectionState;
89
+ /** Register a listener for WebSocket connection state changes */
90
+ onConnectionStateChange(listener: ConnectionStateListener): Unsubscribe;
91
+ /** Number of active subscriptions */
92
+ getActiveSubscriptionCount(): number;
93
+ /** Whether realtime is configured */
94
+ get isRealtimeEnabled(): boolean;
95
+ /** Dispose the realtime manager (close WebSocket) */
96
+ dispose(): void;
67
97
  }
@@ -1,7 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.OrmClient = exports.GraphQLRequestError = exports.FetchAdapter = void 0;
3
+ exports.OrmClient = exports.GraphQLRequestError = exports.FetchAdapter = exports.RealtimeManager = void 0;
4
4
  const runtime_1 = require("@constructive-io/graphql-query/runtime");
5
+ const realtime_1 = require("./realtime");
6
+ var realtime_2 = require("./realtime");
7
+ Object.defineProperty(exports, "RealtimeManager", { enumerable: true, get: function () { return realtime_2.RealtimeManager; } });
5
8
  /**
6
9
  * Default adapter that uses fetch for HTTP requests.
7
10
  *
@@ -78,6 +81,7 @@ class GraphQLRequestError extends Error {
78
81
  exports.GraphQLRequestError = GraphQLRequestError;
79
82
  class OrmClient {
80
83
  adapter;
84
+ realtimeManager;
81
85
  constructor(config) {
82
86
  if (config.adapter) {
83
87
  this.adapter = config.adapter;
@@ -88,10 +92,24 @@ class OrmClient {
88
92
  else {
89
93
  throw new Error('OrmClientConfig requires either an endpoint or a custom adapter');
90
94
  }
95
+ if (config.realtime) {
96
+ this.realtimeManager = new realtime_1.RealtimeManager(config.realtime);
97
+ }
91
98
  }
92
99
  async execute(document, variables) {
93
100
  return this.adapter.execute(document, variables);
94
101
  }
102
+ /**
103
+ * Subscribe to a GraphQL subscription operation.
104
+ * Used by generated model subscribe() methods.
105
+ * @throws Error if realtime is not configured
106
+ */
107
+ subscribe(meta, document, variables, options) {
108
+ if (!this.realtimeManager) {
109
+ throw new Error('Realtime not configured. Pass a `realtime` option to createClient() to enable subscriptions.');
110
+ }
111
+ return this.realtimeManager.subscribe(meta, document, variables, options);
112
+ }
95
113
  /**
96
114
  * Set headers for requests.
97
115
  * Only works if the adapter supports headers.
@@ -108,5 +126,27 @@ class OrmClient {
108
126
  getEndpoint() {
109
127
  return this.adapter.getEndpoint?.() ?? '';
110
128
  }
129
+ /** Get current WebSocket connection state */
130
+ getConnectionState() {
131
+ return this.realtimeManager?.getConnectionState() ?? 'disconnected';
132
+ }
133
+ /** Register a listener for WebSocket connection state changes */
134
+ onConnectionStateChange(listener) {
135
+ if (!this.realtimeManager)
136
+ return () => { };
137
+ return this.realtimeManager.onConnectionStateChange(listener);
138
+ }
139
+ /** Number of active subscriptions */
140
+ getActiveSubscriptionCount() {
141
+ return this.realtimeManager?.getActiveSubscriptionCount() ?? 0;
142
+ }
143
+ /** Whether realtime is configured */
144
+ get isRealtimeEnabled() {
145
+ return this.realtimeManager !== undefined;
146
+ }
147
+ /** Dispose the realtime manager (close WebSocket) */
148
+ dispose() {
149
+ this.realtimeManager?.dispose();
150
+ }
111
151
  }
112
152
  exports.OrmClient = OrmClient;
@@ -0,0 +1,142 @@
1
+ /**
2
+ * Realtime Manager - WebSocket subscription support
3
+ * @generated by @constructive-io/graphql-codegen
4
+ * DO NOT EDIT - changes will be overwritten
5
+ */
6
+ interface WsGraphQLError {
7
+ readonly message: string;
8
+ readonly [key: string]: unknown;
9
+ }
10
+ interface WsExecutionResult<TData = Record<string, unknown>> {
11
+ data?: TData | null;
12
+ errors?: readonly WsGraphQLError[];
13
+ extensions?: Record<string, unknown>;
14
+ }
15
+ interface WsSink<T> {
16
+ next(value: T): void;
17
+ error(error: unknown): void;
18
+ complete(): void;
19
+ }
20
+ /**
21
+ * Minimal interface matching the graphql-ws Client.
22
+ * Consumers pass a concrete instance via RealtimeConfig.client.
23
+ */
24
+ export interface WsClient {
25
+ subscribe<TData = Record<string, unknown>>(payload: {
26
+ query: string;
27
+ variables?: Record<string, unknown>;
28
+ }, sink: WsSink<WsExecutionResult<TData>>): () => void;
29
+ dispose(): void;
30
+ }
31
+ /** The DML operation that triggered the subscription event */
32
+ export type SubscriptionOperation = 'INSERT' | 'UPDATE' | 'DELETE';
33
+ /** Connection state of the WebSocket */
34
+ export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
35
+ /** Listener for connection state changes */
36
+ export type ConnectionStateListener = (state: ConnectionState) => void;
37
+ /** Function returned by subscribe() to cancel the subscription */
38
+ export type Unsubscribe = () => void;
39
+ /**
40
+ * A realtime subscription event delivered to the client.
41
+ *
42
+ * @typeParam T - The row type of the subscribed table
43
+ */
44
+ export interface SubscriptionEvent<T> {
45
+ /** The DML operation that triggered this event */
46
+ operation: SubscriptionOperation;
47
+ /** The current row data (null for DELETE if row is no longer visible) */
48
+ data: T | null;
49
+ /** Previous field values (populated on UPDATE when available) */
50
+ previousValues?: Partial<T>;
51
+ /** Server-side timestamp of when the change occurred */
52
+ timestamp: string;
53
+ }
54
+ /**
55
+ * Options for creating a subscription.
56
+ *
57
+ * @typeParam T - The row type of the subscribed table
58
+ * @typeParam TFilter - The filter type for the table
59
+ */
60
+ export interface SubscribeOptions<T, TFilter = Record<string, unknown>> {
61
+ /** Server-side filter to limit which events are delivered */
62
+ filter?: TFilter;
63
+ /** Called when a subscription event is received */
64
+ onEvent: (event: SubscriptionEvent<T>) => void;
65
+ /** Called when the subscription encounters an error */
66
+ onError?: (error: Error) => void;
67
+ /** Called when the subscription completes (server-initiated close) */
68
+ onComplete?: () => void;
69
+ }
70
+ /**
71
+ * Metadata about a subscription field, used internally to map
72
+ * table names to GraphQL subscription field names and types.
73
+ */
74
+ export interface SubscriptionFieldMeta {
75
+ /** The GraphQL subscription field name (e.g., 'onContactChanged') */
76
+ fieldName: string;
77
+ /** The table name in the source schema (e.g., 'contact') */
78
+ tableName: string;
79
+ /** The data field name inside the subscription payload (e.g., 'contact') */
80
+ dataFieldName: string;
81
+ }
82
+ /**
83
+ * Configuration for the realtime (WebSocket) connection.
84
+ * Pass this as the `realtime` option in OrmClientConfig.
85
+ *
86
+ * @example
87
+ * ```ts
88
+ * import { createClient } from 'graphql-ws';
89
+ *
90
+ * const client = createOrmClient({
91
+ * endpoint: 'https://api.example.com/graphql',
92
+ * realtime: {
93
+ * client: createClient({ url: 'wss://api.example.com/graphql' }),
94
+ * },
95
+ * });
96
+ * ```
97
+ */
98
+ export interface RealtimeConfig {
99
+ /**
100
+ * A graphql-ws Client instance (or any object satisfying WsClient).
101
+ * The consumer creates this themselves, giving full control over
102
+ * connection options, auth, and transport.
103
+ *
104
+ * @example
105
+ * ```ts
106
+ * import { createClient } from 'graphql-ws';
107
+ * const wsClient = createClient({ url: 'wss://...' });
108
+ * ```
109
+ */
110
+ client: WsClient;
111
+ }
112
+ /**
113
+ * Manages a graphql-ws WebSocket client and multiplexes
114
+ * subscriptions over it. Created by OrmClient when `realtime`
115
+ * config is provided.
116
+ */
117
+ export declare class RealtimeManager {
118
+ private wsClient;
119
+ private connectionState;
120
+ private stateListeners;
121
+ private activeSubscriptions;
122
+ constructor(config: RealtimeConfig);
123
+ /**
124
+ * Subscribe to a GraphQL subscription operation.
125
+ * Models call this with typed metadata and documents.
126
+ */
127
+ subscribe<T>(meta: SubscriptionFieldMeta, document: string, variables: Record<string, unknown>, options: {
128
+ onEvent: (event: SubscriptionEvent<T>) => void;
129
+ onError?: (error: Error) => void;
130
+ onComplete?: () => void;
131
+ }): Unsubscribe;
132
+ /** Register a listener for connection state changes */
133
+ onConnectionStateChange(listener: ConnectionStateListener): Unsubscribe;
134
+ /** Get current connection state */
135
+ getConnectionState(): ConnectionState;
136
+ /** Number of active subscriptions */
137
+ getActiveSubscriptionCount(): number;
138
+ /** Dispose the manager and close the WebSocket connection */
139
+ dispose(): void;
140
+ private setConnectionState;
141
+ }
142
+ export {};
@@ -0,0 +1,104 @@
1
+ "use strict";
2
+ /**
3
+ * Realtime Manager - WebSocket subscription support
4
+ * @generated by @constructive-io/graphql-codegen
5
+ * DO NOT EDIT - changes will be overwritten
6
+ */
7
+ // Minimal type shims so this module compiles without graphql-ws
8
+ // installed. Consumers supply a WsClient via RealtimeConfig;
9
+ // the SDK itself never imports or requires graphql-ws.
10
+ Object.defineProperty(exports, "__esModule", { value: true });
11
+ exports.RealtimeManager = void 0;
12
+ // ============================================================================
13
+ // RealtimeManager
14
+ // ============================================================================
15
+ /**
16
+ * Manages a graphql-ws WebSocket client and multiplexes
17
+ * subscriptions over it. Created by OrmClient when `realtime`
18
+ * config is provided.
19
+ */
20
+ class RealtimeManager {
21
+ wsClient;
22
+ connectionState = 'disconnected';
23
+ stateListeners = new Set();
24
+ activeSubscriptions = 0;
25
+ constructor(config) {
26
+ this.wsClient = config.client;
27
+ }
28
+ /**
29
+ * Subscribe to a GraphQL subscription operation.
30
+ * Models call this with typed metadata and documents.
31
+ */
32
+ subscribe(meta, document, variables, options) {
33
+ this.activeSubscriptions++;
34
+ let disposed = false;
35
+ const cleanup = this.wsClient.subscribe({ query: document, variables }, {
36
+ next: (result) => {
37
+ if (disposed)
38
+ return;
39
+ if (result.errors) {
40
+ options.onError?.(new Error(result.errors.map((e) => e.message).join('; ')));
41
+ return;
42
+ }
43
+ const payload = result.data?.[meta.fieldName];
44
+ if (!payload)
45
+ return;
46
+ const event = {
47
+ operation: payload.event ?? 'UPDATE',
48
+ data: payload[meta.dataFieldName] ?? null,
49
+ previousValues: payload.previousValues,
50
+ timestamp: payload.timestamp ?? new Date().toISOString(),
51
+ };
52
+ options.onEvent(event);
53
+ },
54
+ error: (err) => {
55
+ if (disposed)
56
+ return;
57
+ options.onError?.(err instanceof Error ? err : new Error(String(err)));
58
+ },
59
+ complete: () => {
60
+ if (disposed)
61
+ return;
62
+ options.onComplete?.();
63
+ },
64
+ });
65
+ return () => {
66
+ if (disposed)
67
+ return;
68
+ disposed = true;
69
+ this.activeSubscriptions--;
70
+ cleanup();
71
+ };
72
+ }
73
+ /** Register a listener for connection state changes */
74
+ onConnectionStateChange(listener) {
75
+ this.stateListeners.add(listener);
76
+ return () => {
77
+ this.stateListeners.delete(listener);
78
+ };
79
+ }
80
+ /** Get current connection state */
81
+ getConnectionState() {
82
+ return this.connectionState;
83
+ }
84
+ /** Number of active subscriptions */
85
+ getActiveSubscriptionCount() {
86
+ return this.activeSubscriptions;
87
+ }
88
+ /** Dispose the manager and close the WebSocket connection */
89
+ dispose() {
90
+ this.wsClient.dispose();
91
+ this.stateListeners.clear();
92
+ this.activeSubscriptions = 0;
93
+ this.setConnectionState('disconnected');
94
+ }
95
+ setConnectionState(state) {
96
+ if (this.connectionState === state)
97
+ return;
98
+ this.connectionState = state;
99
+ for (const listener of this.stateListeners) {
100
+ listener(state);
101
+ }
102
+ }
103
+ }
104
+ exports.RealtimeManager = RealtimeManager;
@@ -4,7 +4,10 @@
4
4
  * DO NOT EDIT - changes will be overwritten
5
5
  */
6
6
  import type { GraphQLAdapter, GraphQLError, QueryResult } from '@constructive-io/graphql-query/runtime';
7
+ import type { ConnectionState, ConnectionStateListener, RealtimeConfig, SubscriptionEvent, SubscriptionFieldMeta, Unsubscribe } from './realtime';
7
8
  export type { GraphQLAdapter, GraphQLError, QueryResult, } from '@constructive-io/graphql-query/runtime';
9
+ export type { ConnectionState, ConnectionStateListener, RealtimeConfig, SubscribeOptions, SubscriptionEvent, SubscriptionFieldMeta, SubscriptionOperation, Unsubscribe, WsClient, } from './realtime';
10
+ export { RealtimeManager } from './realtime';
8
11
  /**
9
12
  * Default adapter that uses fetch for HTTP requests.
10
13
  *
@@ -41,6 +44,12 @@ export interface OrmClientConfig {
41
44
  fetch?: typeof globalThis.fetch;
42
45
  /** Custom adapter for GraphQL execution (overrides endpoint/headers/fetch) */
43
46
  adapter?: GraphQLAdapter;
47
+ /**
48
+ * Optional realtime (WebSocket) configuration.
49
+ * When provided, enables subscription methods on models.
50
+ * The WebSocket connection is created lazily on first subscribe().
51
+ */
52
+ realtime?: RealtimeConfig;
44
53
  }
45
54
  /**
46
55
  * Error thrown when GraphQL request fails
@@ -52,8 +61,19 @@ export declare class GraphQLRequestError extends Error {
52
61
  }
53
62
  export declare class OrmClient {
54
63
  private adapter;
64
+ private realtimeManager?;
55
65
  constructor(config: OrmClientConfig);
56
66
  execute<T>(document: string, variables?: Record<string, unknown>): Promise<QueryResult<T>>;
67
+ /**
68
+ * Subscribe to a GraphQL subscription operation.
69
+ * Used by generated model subscribe() methods.
70
+ * @throws Error if realtime is not configured
71
+ */
72
+ subscribe<T>(meta: SubscriptionFieldMeta, document: string, variables: Record<string, unknown>, options: {
73
+ onEvent: (event: SubscriptionEvent<T>) => void;
74
+ onError?: (error: Error) => void;
75
+ onComplete?: () => void;
76
+ }): Unsubscribe;
57
77
  /**
58
78
  * Set headers for requests.
59
79
  * Only works if the adapter supports headers.
@@ -64,4 +84,14 @@ export declare class OrmClient {
64
84
  * Returns empty string if the adapter doesn't have an endpoint.
65
85
  */
66
86
  getEndpoint(): string;
87
+ /** Get current WebSocket connection state */
88
+ getConnectionState(): ConnectionState;
89
+ /** Register a listener for WebSocket connection state changes */
90
+ onConnectionStateChange(listener: ConnectionStateListener): Unsubscribe;
91
+ /** Number of active subscriptions */
92
+ getActiveSubscriptionCount(): number;
93
+ /** Whether realtime is configured */
94
+ get isRealtimeEnabled(): boolean;
95
+ /** Dispose the realtime manager (close WebSocket) */
96
+ dispose(): void;
67
97
  }
@@ -1,7 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.OrmClient = exports.GraphQLRequestError = exports.FetchAdapter = void 0;
3
+ exports.OrmClient = exports.GraphQLRequestError = exports.FetchAdapter = exports.RealtimeManager = void 0;
4
4
  const runtime_1 = require("@constructive-io/graphql-query/runtime");
5
+ const realtime_1 = require("./realtime");
6
+ var realtime_2 = require("./realtime");
7
+ Object.defineProperty(exports, "RealtimeManager", { enumerable: true, get: function () { return realtime_2.RealtimeManager; } });
5
8
  /**
6
9
  * Default adapter that uses fetch for HTTP requests.
7
10
  *
@@ -78,6 +81,7 @@ class GraphQLRequestError extends Error {
78
81
  exports.GraphQLRequestError = GraphQLRequestError;
79
82
  class OrmClient {
80
83
  adapter;
84
+ realtimeManager;
81
85
  constructor(config) {
82
86
  if (config.adapter) {
83
87
  this.adapter = config.adapter;
@@ -88,10 +92,24 @@ class OrmClient {
88
92
  else {
89
93
  throw new Error('OrmClientConfig requires either an endpoint or a custom adapter');
90
94
  }
95
+ if (config.realtime) {
96
+ this.realtimeManager = new realtime_1.RealtimeManager(config.realtime);
97
+ }
91
98
  }
92
99
  async execute(document, variables) {
93
100
  return this.adapter.execute(document, variables);
94
101
  }
102
+ /**
103
+ * Subscribe to a GraphQL subscription operation.
104
+ * Used by generated model subscribe() methods.
105
+ * @throws Error if realtime is not configured
106
+ */
107
+ subscribe(meta, document, variables, options) {
108
+ if (!this.realtimeManager) {
109
+ throw new Error('Realtime not configured. Pass a `realtime` option to createClient() to enable subscriptions.');
110
+ }
111
+ return this.realtimeManager.subscribe(meta, document, variables, options);
112
+ }
95
113
  /**
96
114
  * Set headers for requests.
97
115
  * Only works if the adapter supports headers.
@@ -108,5 +126,27 @@ class OrmClient {
108
126
  getEndpoint() {
109
127
  return this.adapter.getEndpoint?.() ?? '';
110
128
  }
129
+ /** Get current WebSocket connection state */
130
+ getConnectionState() {
131
+ return this.realtimeManager?.getConnectionState() ?? 'disconnected';
132
+ }
133
+ /** Register a listener for WebSocket connection state changes */
134
+ onConnectionStateChange(listener) {
135
+ if (!this.realtimeManager)
136
+ return () => { };
137
+ return this.realtimeManager.onConnectionStateChange(listener);
138
+ }
139
+ /** Number of active subscriptions */
140
+ getActiveSubscriptionCount() {
141
+ return this.realtimeManager?.getActiveSubscriptionCount() ?? 0;
142
+ }
143
+ /** Whether realtime is configured */
144
+ get isRealtimeEnabled() {
145
+ return this.realtimeManager !== undefined;
146
+ }
147
+ /** Dispose the realtime manager (close WebSocket) */
148
+ dispose() {
149
+ this.realtimeManager?.dispose();
150
+ }
111
151
  }
112
152
  exports.OrmClient = OrmClient;
@@ -0,0 +1,142 @@
1
+ /**
2
+ * Realtime Manager - WebSocket subscription support
3
+ * @generated by @constructive-io/graphql-codegen
4
+ * DO NOT EDIT - changes will be overwritten
5
+ */
6
+ interface WsGraphQLError {
7
+ readonly message: string;
8
+ readonly [key: string]: unknown;
9
+ }
10
+ interface WsExecutionResult<TData = Record<string, unknown>> {
11
+ data?: TData | null;
12
+ errors?: readonly WsGraphQLError[];
13
+ extensions?: Record<string, unknown>;
14
+ }
15
+ interface WsSink<T> {
16
+ next(value: T): void;
17
+ error(error: unknown): void;
18
+ complete(): void;
19
+ }
20
+ /**
21
+ * Minimal interface matching the graphql-ws Client.
22
+ * Consumers pass a concrete instance via RealtimeConfig.client.
23
+ */
24
+ export interface WsClient {
25
+ subscribe<TData = Record<string, unknown>>(payload: {
26
+ query: string;
27
+ variables?: Record<string, unknown>;
28
+ }, sink: WsSink<WsExecutionResult<TData>>): () => void;
29
+ dispose(): void;
30
+ }
31
+ /** The DML operation that triggered the subscription event */
32
+ export type SubscriptionOperation = 'INSERT' | 'UPDATE' | 'DELETE';
33
+ /** Connection state of the WebSocket */
34
+ export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
35
+ /** Listener for connection state changes */
36
+ export type ConnectionStateListener = (state: ConnectionState) => void;
37
+ /** Function returned by subscribe() to cancel the subscription */
38
+ export type Unsubscribe = () => void;
39
+ /**
40
+ * A realtime subscription event delivered to the client.
41
+ *
42
+ * @typeParam T - The row type of the subscribed table
43
+ */
44
+ export interface SubscriptionEvent<T> {
45
+ /** The DML operation that triggered this event */
46
+ operation: SubscriptionOperation;
47
+ /** The current row data (null for DELETE if row is no longer visible) */
48
+ data: T | null;
49
+ /** Previous field values (populated on UPDATE when available) */
50
+ previousValues?: Partial<T>;
51
+ /** Server-side timestamp of when the change occurred */
52
+ timestamp: string;
53
+ }
54
+ /**
55
+ * Options for creating a subscription.
56
+ *
57
+ * @typeParam T - The row type of the subscribed table
58
+ * @typeParam TFilter - The filter type for the table
59
+ */
60
+ export interface SubscribeOptions<T, TFilter = Record<string, unknown>> {
61
+ /** Server-side filter to limit which events are delivered */
62
+ filter?: TFilter;
63
+ /** Called when a subscription event is received */
64
+ onEvent: (event: SubscriptionEvent<T>) => void;
65
+ /** Called when the subscription encounters an error */
66
+ onError?: (error: Error) => void;
67
+ /** Called when the subscription completes (server-initiated close) */
68
+ onComplete?: () => void;
69
+ }
70
+ /**
71
+ * Metadata about a subscription field, used internally to map
72
+ * table names to GraphQL subscription field names and types.
73
+ */
74
+ export interface SubscriptionFieldMeta {
75
+ /** The GraphQL subscription field name (e.g., 'onContactChanged') */
76
+ fieldName: string;
77
+ /** The table name in the source schema (e.g., 'contact') */
78
+ tableName: string;
79
+ /** The data field name inside the subscription payload (e.g., 'contact') */
80
+ dataFieldName: string;
81
+ }
82
+ /**
83
+ * Configuration for the realtime (WebSocket) connection.
84
+ * Pass this as the `realtime` option in OrmClientConfig.
85
+ *
86
+ * @example
87
+ * ```ts
88
+ * import { createClient } from 'graphql-ws';
89
+ *
90
+ * const client = createOrmClient({
91
+ * endpoint: 'https://api.example.com/graphql',
92
+ * realtime: {
93
+ * client: createClient({ url: 'wss://api.example.com/graphql' }),
94
+ * },
95
+ * });
96
+ * ```
97
+ */
98
+ export interface RealtimeConfig {
99
+ /**
100
+ * A graphql-ws Client instance (or any object satisfying WsClient).
101
+ * The consumer creates this themselves, giving full control over
102
+ * connection options, auth, and transport.
103
+ *
104
+ * @example
105
+ * ```ts
106
+ * import { createClient } from 'graphql-ws';
107
+ * const wsClient = createClient({ url: 'wss://...' });
108
+ * ```
109
+ */
110
+ client: WsClient;
111
+ }
112
+ /**
113
+ * Manages a graphql-ws WebSocket client and multiplexes
114
+ * subscriptions over it. Created by OrmClient when `realtime`
115
+ * config is provided.
116
+ */
117
+ export declare class RealtimeManager {
118
+ private wsClient;
119
+ private connectionState;
120
+ private stateListeners;
121
+ private activeSubscriptions;
122
+ constructor(config: RealtimeConfig);
123
+ /**
124
+ * Subscribe to a GraphQL subscription operation.
125
+ * Models call this with typed metadata and documents.
126
+ */
127
+ subscribe<T>(meta: SubscriptionFieldMeta, document: string, variables: Record<string, unknown>, options: {
128
+ onEvent: (event: SubscriptionEvent<T>) => void;
129
+ onError?: (error: Error) => void;
130
+ onComplete?: () => void;
131
+ }): Unsubscribe;
132
+ /** Register a listener for connection state changes */
133
+ onConnectionStateChange(listener: ConnectionStateListener): Unsubscribe;
134
+ /** Get current connection state */
135
+ getConnectionState(): ConnectionState;
136
+ /** Number of active subscriptions */
137
+ getActiveSubscriptionCount(): number;
138
+ /** Dispose the manager and close the WebSocket connection */
139
+ dispose(): void;
140
+ private setConnectionState;
141
+ }
142
+ export {};