@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.
- package/index.d.ts +102 -19
- package/index.js +891 -724
- 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
|
-
|
|
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
|
-
|
|
75
|
-
handleError: <
|
|
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
|
-
|
|
100
|
-
handleError: <
|
|
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
|
-
|
|
126
|
-
handleError: <
|
|
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
|
-
|
|
151
|
-
handleError: <
|
|
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
|
-
|
|
177
|
-
handleError: <
|
|
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
|
-
|
|
202
|
-
handleError: <
|
|
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
|
-
[
|
|
210
|
-
[
|
|
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
|
-
|
|
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<[
|
|
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
|
-
|
|
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;
|