@milkio/stargate 1.3.71 → 1.3.73

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 +102 -19
  2. package/index.js +891 -724
  3. package/package.json +1 -1
package/index.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  export type MilkioStargateOptions = {
2
2
  baseUrl: string | (() => string) | (() => Promise<string>);
3
+ /** 默认请求超时(毫秒);可被单次 execute 的 options.timeout 覆盖。action / stream / ping 均生效,默认 6000。 */
3
4
  timeout?: number;
4
5
  fetch?: typeof fetch;
5
6
  abort?: typeof AbortController;
@@ -19,6 +20,7 @@ export interface CacheStorage {
19
20
  export type ExecuteOptions<T extends any> = {
20
21
  params?: Record<any, any>;
21
22
  headers?: Record<string, string>;
23
+ /** 单次请求超时(毫秒),优先于 MilkioStargateOptions.timeout;默认 6000。 */
22
24
  timeout?: number;
23
25
  baseUrl?: string | (() => string) | (() => Promise<string>);
24
26
  cacheStrategy?: CacheStrategy;
@@ -44,9 +46,54 @@ export type Ping = [
44
46
  serverTimestamp: number;
45
47
  }
46
48
  ];
49
+ export type MilkioFailureWire = {
50
+ kind: "fail";
51
+ code: string;
52
+ data: unknown;
53
+ } | {
54
+ kind: "fault";
55
+ code: "INTERNAL_SERVER_ERROR";
56
+ };
57
+ /** structural shape of a failure restored from the wire (fail keeps code/data; fault stays generic) */
58
+ export interface MilkioClientFailure {
59
+ readonly $milkioFailure: true;
60
+ readonly kind: "fail" | "fault";
61
+ readonly code: string;
62
+ readonly data?: unknown;
63
+ }
64
+ /** transport faults carry the root-cause details locally (never sent to the server) */
65
+ export interface MilkioTransportFailureData {
66
+ name?: string;
67
+ message?: string;
68
+ /** node/undici error code, e.g. ECONNREFUSED / ENOTFOUND */
69
+ code?: string;
70
+ }
71
+ /** faults synthesized by the client itself; they are not server fault-codes */
72
+ export type MilkioClientTransportFailure = (MilkioClientFailure & {
73
+ readonly kind: "fault";
74
+ readonly code: "NETWORK_ERROR";
75
+ readonly data?: MilkioTransportFailureData;
76
+ }) | (MilkioClientFailure & {
77
+ readonly kind: "fault";
78
+ readonly code: "REQUEST_TIMEOUT";
79
+ readonly data: {
80
+ timeout: number;
81
+ message: string;
82
+ };
83
+ });
84
+ /**
85
+ * Everything a stargate call can fail with: the generated client-visible failure union
86
+ * (all fail-codes with typed data + the generic server fault) plus the client transport faults.
87
+ * The transport members carry literal codes so `failure.code` narrowing still works for fail-codes.
88
+ */
89
+ export type MilkioPublicFailure<Generated extends {
90
+ failure: any;
91
+ } = {
92
+ failure: any;
93
+ }> = Generated["failure"] | MilkioClientTransportFailure;
47
94
  export declare function createStargate<Generated extends {
48
95
  routeSchema: any;
49
- rejectCode: any;
96
+ failure: MilkioClientFailure;
50
97
  events: any;
51
98
  }>(stargateOptions: MilkioStargateOptions): Promise<{
52
99
  on: <Key extends keyof {
@@ -71,8 +118,13 @@ export declare function createStargate<Generated extends {
71
118
  headers: Record<string, string>;
72
119
  baseUrl: string;
73
120
  }>;
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>;
121
+ failure: MilkioPublicFailure<Generated>;
122
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
123
+ kind: "fail";
124
+ code: Code;
125
+ }> extends {
126
+ data: infer Data;
127
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
76
128
  };
77
129
  }, Handler extends (event: {
78
130
  'milkio:executeBefore': {
@@ -96,8 +148,13 @@ export declare function createStargate<Generated extends {
96
148
  headers: Record<string, string>;
97
149
  baseUrl: string;
98
150
  }>;
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>;
151
+ failure: MilkioPublicFailure<Generated>;
152
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
153
+ kind: "fail";
154
+ code: Code;
155
+ }> extends {
156
+ data: infer Data;
157
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
101
158
  };
102
159
  }[Key]) => void>(key: Key, handler: Handler) => () => void;
103
160
  off: <Key extends keyof {
@@ -122,8 +179,13 @@ export declare function createStargate<Generated extends {
122
179
  headers: Record<string, string>;
123
180
  baseUrl: string;
124
181
  }>;
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>;
182
+ failure: MilkioPublicFailure<Generated>;
183
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
184
+ kind: "fail";
185
+ code: Code;
186
+ }> extends {
187
+ data: infer Data;
188
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
127
189
  };
128
190
  }, Handler extends (event: {
129
191
  'milkio:executeBefore': {
@@ -147,8 +209,13 @@ export declare function createStargate<Generated extends {
147
209
  headers: Record<string, string>;
148
210
  baseUrl: string;
149
211
  }>;
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>;
212
+ failure: MilkioPublicFailure<Generated>;
213
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
214
+ kind: "fail";
215
+ code: Code;
216
+ }> extends {
217
+ data: infer Data;
218
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
152
219
  };
153
220
  }[Key]) => void>(key: Key, handler: Handler) => void;
154
221
  emit: <Key extends keyof {
@@ -173,8 +240,13 @@ export declare function createStargate<Generated extends {
173
240
  headers: Record<string, string>;
174
241
  baseUrl: string;
175
242
  }>;
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>;
243
+ failure: MilkioPublicFailure<Generated>;
244
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
245
+ kind: "fail";
246
+ code: Code;
247
+ }> extends {
248
+ data: infer Data;
249
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
178
250
  };
179
251
  }, Value extends {
180
252
  'milkio:executeBefore': {
@@ -198,31 +270,36 @@ export declare function createStargate<Generated extends {
198
270
  headers: Record<string, string>;
199
271
  baseUrl: string;
200
272
  }>;
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>;
273
+ failure: MilkioPublicFailure<Generated>;
274
+ handleError: <Code extends string>(failure: MilkioPublicFailure<Generated>, code: Code, handler: (data: Extract<Generated["failure"], {
275
+ kind: "fail";
276
+ code: Code;
277
+ }> extends {
278
+ data: infer Data;
279
+ } ? Data : unknown) => boolean | Promise<boolean>) => Promise<boolean>;
203
280
  };
204
281
  }[Key]>(key: Key, value: Value) => Promise<void>;
205
282
  options: MilkioStargateOptions;
206
283
  execute<Path extends keyof Generated['routeSchema']>(path: Path, options: Mixin<ExecuteOptions<Generated['routeSchema'][Path]['types']['result']>, {
207
284
  params?: Generated['routeSchema'][Path]['types']['params'];
208
285
  }>): 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]>;
286
+ [MilkioPublicFailure<Generated>, null, ExecuteResultsOption] | [null, Generated['routeSchema'][Path]['types']['result'], ExecuteResultsOption] : // stream
287
+ [MilkioPublicFailure<Generated>, null, ExecuteResultsOption] | [null, AsyncGenerator<[MilkioPublicFailure<Generated>, null] | [null, Generated['routeSchema'][Path]['types']['result']], undefined>, ExecuteResultsOption]>;
211
288
  __cookbook: {
212
289
  subscribe: (baseUrl: string) => Promise<any>;
213
290
  };
214
291
  __astraEmitEvent: (key: any, options?: {
215
292
  params?: any;
216
293
  headers?: Record<string, string>;
217
- }) => Promise<any[]>;
294
+ }) => Promise<any>;
218
295
  ping(options?: {
219
296
  timeout?: number;
220
297
  }): Promise<Ping>;
221
298
  $types: {
222
299
  generated: Generated;
223
- error: Generated['rejectCode'];
300
+ failure: MilkioPublicFailure<Generated>;
224
301
  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>; };
302
+ 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
303
  };
227
304
  }>;
228
305
  export declare function reviveJSONParse<T>(json: T): T;
@@ -304,7 +381,13 @@ export declare function getLines(onLine: (line: Uint8Array, fieldLength: number)
304
381
  * @returns A function that should be called for each incoming line buffer.
305
382
  */
306
383
  export declare function getMessages(onMessage?: (msg: EventSourceMessage) => void): (line: Uint8Array, fieldLength: number) => void;
307
- export declare function withResolvers<T = any>(): PromiseWithResolvers<T>;
384
+ /** locally declared so the package does not require the `ESNext.Promise` lib (PromiseWithResolvers) */
385
+ export interface MilkioPromiseWithResolvers<T> {
386
+ promise: Promise<T>;
387
+ resolve: (value: T | PromiseLike<T>) => void;
388
+ reject: (reason?: any) => void;
389
+ }
390
+ export declare function withResolvers<T = any>(): MilkioPromiseWithResolvers<T>;
308
391
  export declare function createDefaultCacheStorage(options?: {
309
392
  encryption?: boolean;
310
393
  encryptionKey?: string;