@milkio/stargate 1.3.70 → 1.3.72

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 (3) hide show
  1. package/index.d.ts +92 -19
  2. package/index.js +859 -724
  3. package/package.json +1 -1
package/index.d.ts CHANGED
@@ -44,9 +44,46 @@ export type Ping = [
44
44
  serverTimestamp: number;
45
45
  }
46
46
  ];
47
+ export type MilkioFailureWire = {
48
+ kind: "fail";
49
+ code: string;
50
+ data: unknown;
51
+ } | {
52
+ kind: "fault";
53
+ code: "INTERNAL_SERVER_ERROR";
54
+ };
55
+ /** structural shape of a failure restored from the wire (fail keeps code/data; fault stays generic) */
56
+ export interface MilkioClientFailure {
57
+ readonly $milkioFailure: true;
58
+ readonly kind: "fail" | "fault";
59
+ readonly code: string;
60
+ readonly data?: unknown;
61
+ }
62
+ /** faults synthesized by the client itself; they are not server fault-codes */
63
+ export type MilkioClientTransportFailure = (MilkioClientFailure & {
64
+ readonly kind: "fault";
65
+ readonly code: "NETWORK_ERROR";
66
+ }) | (MilkioClientFailure & {
67
+ readonly kind: "fault";
68
+ readonly code: "REQUEST_TIMEOUT";
69
+ readonly data: {
70
+ timeout: number;
71
+ message: string;
72
+ };
73
+ });
74
+ /**
75
+ * Everything a stargate call can fail with: the generated client-visible failure union
76
+ * (all fail-codes with typed data + the generic server fault) plus the client transport faults.
77
+ * The transport members carry literal codes so `failure.code` narrowing still works for fail-codes.
78
+ */
79
+ export type MilkioPublicFailure<Generated extends {
80
+ failure: any;
81
+ } = {
82
+ failure: any;
83
+ }> = Generated["failure"] | MilkioClientTransportFailure;
47
84
  export declare function createStargate<Generated extends {
48
85
  routeSchema: any;
49
- rejectCode: any;
86
+ failure: MilkioClientFailure;
50
87
  events: any;
51
88
  }>(stargateOptions: MilkioStargateOptions): Promise<{
52
89
  on: <Key extends keyof {
@@ -71,8 +108,13 @@ export declare function createStargate<Generated extends {
71
108
  headers: Record<string, string>;
72
109
  baseUrl: string;
73
110
  }>;
74
- error: Partial<Generated['rejectCode']>;
75
- handleError: <K extends keyof Partial<Generated['rejectCode']>>(error: any, key: K, handler: (error: Partial<Generated['rejectCode'][K]>) => boolean | Promise<boolean>) => Promise<void>;
111
+ failure: MilkioPublicFailure<Generated>;
112
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
113
+ kind: "fail";
114
+ code: Code;
115
+ }> extends {
116
+ data: infer Data;
117
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
76
118
  };
77
119
  }, Handler extends (event: {
78
120
  'milkio:executeBefore': {
@@ -96,8 +138,13 @@ export declare function createStargate<Generated extends {
96
138
  headers: Record<string, string>;
97
139
  baseUrl: string;
98
140
  }>;
99
- error: Partial<Generated['rejectCode']>;
100
- handleError: <K extends keyof Partial<Generated['rejectCode']>>(error: any, key: K, handler: (error: Partial<Generated['rejectCode'][K]>) => boolean | Promise<boolean>) => Promise<void>;
141
+ failure: MilkioPublicFailure<Generated>;
142
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
143
+ kind: "fail";
144
+ code: Code;
145
+ }> extends {
146
+ data: infer Data;
147
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
101
148
  };
102
149
  }[Key]) => void>(key: Key, handler: Handler) => () => void;
103
150
  off: <Key extends keyof {
@@ -122,8 +169,13 @@ export declare function createStargate<Generated extends {
122
169
  headers: Record<string, string>;
123
170
  baseUrl: string;
124
171
  }>;
125
- error: Partial<Generated['rejectCode']>;
126
- handleError: <K extends keyof Partial<Generated['rejectCode']>>(error: any, key: K, handler: (error: Partial<Generated['rejectCode'][K]>) => boolean | Promise<boolean>) => Promise<void>;
172
+ failure: MilkioPublicFailure<Generated>;
173
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
174
+ kind: "fail";
175
+ code: Code;
176
+ }> extends {
177
+ data: infer Data;
178
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
127
179
  };
128
180
  }, Handler extends (event: {
129
181
  'milkio:executeBefore': {
@@ -147,8 +199,13 @@ export declare function createStargate<Generated extends {
147
199
  headers: Record<string, string>;
148
200
  baseUrl: string;
149
201
  }>;
150
- error: Partial<Generated['rejectCode']>;
151
- handleError: <K extends keyof Partial<Generated['rejectCode']>>(error: any, key: K, handler: (error: Partial<Generated['rejectCode'][K]>) => boolean | Promise<boolean>) => Promise<void>;
202
+ failure: MilkioPublicFailure<Generated>;
203
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
204
+ kind: "fail";
205
+ code: Code;
206
+ }> extends {
207
+ data: infer Data;
208
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
152
209
  };
153
210
  }[Key]) => void>(key: Key, handler: Handler) => void;
154
211
  emit: <Key extends keyof {
@@ -173,8 +230,13 @@ export declare function createStargate<Generated extends {
173
230
  headers: Record<string, string>;
174
231
  baseUrl: string;
175
232
  }>;
176
- error: Partial<Generated['rejectCode']>;
177
- handleError: <K extends keyof Partial<Generated['rejectCode']>>(error: any, key: K, handler: (error: Partial<Generated['rejectCode'][K]>) => boolean | Promise<boolean>) => Promise<void>;
233
+ failure: MilkioPublicFailure<Generated>;
234
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
235
+ kind: "fail";
236
+ code: Code;
237
+ }> extends {
238
+ data: infer Data;
239
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
178
240
  };
179
241
  }, Value extends {
180
242
  'milkio:executeBefore': {
@@ -198,31 +260,36 @@ export declare function createStargate<Generated extends {
198
260
  headers: Record<string, string>;
199
261
  baseUrl: string;
200
262
  }>;
201
- error: Partial<Generated['rejectCode']>;
202
- handleError: <K extends keyof Partial<Generated['rejectCode']>>(error: any, key: K, handler: (error: Partial<Generated['rejectCode'][K]>) => boolean | Promise<boolean>) => Promise<void>;
263
+ failure: MilkioPublicFailure<Generated>;
264
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
265
+ kind: "fail";
266
+ code: Code;
267
+ }> extends {
268
+ data: infer Data;
269
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
203
270
  };
204
271
  }[Key]>(key: Key, value: Value) => Promise<void>;
205
272
  options: MilkioStargateOptions;
206
273
  execute<Path extends keyof Generated['routeSchema']>(path: Path, options: Mixin<ExecuteOptions<Generated['routeSchema'][Path]['types']['result']>, {
207
274
  params?: Generated['routeSchema'][Path]['types']['params'];
208
275
  }>): Promise<Generated['routeSchema'][Path]['types']['🥛'] extends boolean ? // action
209
- [Partial<Generated['rejectCode']>, null, ExecuteResultsOption] | [null, Generated['routeSchema'][Path]['types']['result'], ExecuteResultsOption] : // stream
210
- [Partial<Generated['rejectCode']>, null, ExecuteResultsOption] | [null, AsyncGenerator<[Partial<Generated['rejectCode']>, null] | [null, Generated['routeSchema'][Path]['types']['result']], undefined>, ExecuteResultsOption]>;
276
+ [MilkioPublicFailure<Generated>, null, ExecuteResultsOption] | [null, Generated['routeSchema'][Path]['types']['result'], ExecuteResultsOption] : // stream
277
+ [MilkioPublicFailure<Generated>, null, ExecuteResultsOption] | [null, AsyncGenerator<[MilkioPublicFailure<Generated>, null] | [null, Generated['routeSchema'][Path]['types']['result']], undefined>, ExecuteResultsOption]>;
211
278
  __cookbook: {
212
279
  subscribe: (baseUrl: string) => Promise<any>;
213
280
  };
214
281
  __astraEmitEvent: (key: any, options?: {
215
282
  params?: any;
216
283
  headers?: Record<string, string>;
217
- }) => Promise<any[]>;
284
+ }) => Promise<any>;
218
285
  ping(options?: {
219
286
  timeout?: number;
220
287
  }): Promise<Ping>;
221
288
  $types: {
222
289
  generated: Generated;
223
- error: Generated['rejectCode'];
290
+ failure: MilkioPublicFailure<Generated>;
224
291
  params: { [Path in keyof Generated['routeSchema']]: Generated['routeSchema'][Path]['types']['params']; };
225
- results: { [Path in keyof Generated['routeSchema']]: Generated['routeSchema'][Path]['types']['🥛'] extends boolean ? Generated['routeSchema'][Path]['types']['result'] : AsyncGenerator<[Partial<Generated['rejectCode']>, null] | [null, Generated['routeSchema'][Path]['types']['result']], undefined>; };
292
+ results: { [Path in keyof Generated['routeSchema']]: Generated['routeSchema'][Path]['types']['🥛'] extends boolean ? Generated['routeSchema'][Path]['types']['result'] : AsyncGenerator<[MilkioPublicFailure<Generated>, null] | [null, Generated['routeSchema'][Path]['types']['result']], undefined>; };
226
293
  };
227
294
  }>;
228
295
  export declare function reviveJSONParse<T>(json: T): T;
@@ -304,7 +371,13 @@ export declare function getLines(onLine: (line: Uint8Array, fieldLength: number)
304
371
  * @returns A function that should be called for each incoming line buffer.
305
372
  */
306
373
  export declare function getMessages(onMessage?: (msg: EventSourceMessage) => void): (line: Uint8Array, fieldLength: number) => void;
307
- export declare function withResolvers<T = any>(): PromiseWithResolvers<T>;
374
+ /** locally declared so the package does not require the `ESNext.Promise` lib (PromiseWithResolvers) */
375
+ export interface MilkioPromiseWithResolvers<T> {
376
+ promise: Promise<T>;
377
+ resolve: (value: T | PromiseLike<T>) => void;
378
+ reject: (reason?: any) => void;
379
+ }
380
+ export declare function withResolvers<T = any>(): MilkioPromiseWithResolvers<T>;
308
381
  export declare function createDefaultCacheStorage(options?: {
309
382
  encryption?: boolean;
310
383
  encryptionKey?: string;