@openstage/monadyssey-fetch 3.0.0-rc.2 → 3.0.0-rc.3
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/dist/monadyssey-fetch.d.ts +148 -9
- package/dist/monadyssey-fetch.mjs +1115 -283
- package/dist/monadyssey-fetch.mjs.map +1 -1
- package/package.json +2 -2
|
@@ -16,10 +16,25 @@ export declare type Credentials = "omit" | "same-origin" | "include";
|
|
|
16
16
|
* A stream transformation that decodes raw response bytes into {@link ServerSentEvent}s, buffering
|
|
17
17
|
* partial input across chunks. Single-use: each application maintains its own decoding state.
|
|
18
18
|
*
|
|
19
|
+
* A block that passes `maxBlockChars` without ending fails the stream with a `RangeError` defect:
|
|
20
|
+
* the input is not an event stream this decoder can read, and the surrounding error type `E` has no
|
|
21
|
+
* case for it.
|
|
22
|
+
*
|
|
19
23
|
* @typeParam E - The error type carried by the surrounding stream.
|
|
24
|
+
* @param options - `maxBlockChars`: the longest block buffered (default 1,048,576).
|
|
20
25
|
* @returns A pipe from a byte stream to a stream of parsed events.
|
|
26
|
+
* @throws {RangeError} If `maxBlockChars` is not a positive integer or `Infinity`.
|
|
21
27
|
*/
|
|
22
|
-
export declare const decodeEvents: <E>() => Pipe<E, Uint8Array, ServerSentEvent>;
|
|
28
|
+
export declare const decodeEvents: <E>(options?: DecodeEventsOptions) => Pipe<E, Uint8Array, ServerSentEvent>;
|
|
29
|
+
|
|
30
|
+
/** Options for {@link decodeEvents}. */
|
|
31
|
+
export declare interface DecodeEventsOptions {
|
|
32
|
+
/**
|
|
33
|
+
* The longest event block, in characters, buffered while waiting for its end. A positive
|
|
34
|
+
* integer or `Infinity`; defaults to 1,048,576, the limit `sse()` uses.
|
|
35
|
+
*/
|
|
36
|
+
readonly maxBlockChars?: number;
|
|
37
|
+
}
|
|
23
38
|
|
|
24
39
|
/**
|
|
25
40
|
* `T` restricted to the keys of `Shape`: every other key is typed `never`, so an object with an extra
|
|
@@ -75,6 +90,10 @@ export declare class HttpClient {
|
|
|
75
90
|
private readonly defaultHeaders;
|
|
76
91
|
private readonly defaultTimeout;
|
|
77
92
|
private readonly defaultCredentials;
|
|
93
|
+
private readonly defaultRedirect;
|
|
94
|
+
private readonly defaultMaxBodyBytes;
|
|
95
|
+
private readonly allowedOrigins;
|
|
96
|
+
private readonly transport;
|
|
78
97
|
/**
|
|
79
98
|
* Creates a new HttpClient with the given configuration.
|
|
80
99
|
*
|
|
@@ -204,6 +223,16 @@ export declare class HttpClient {
|
|
|
204
223
|
* await events.runForEach((event) => IO.sync(() => handle(event))).unsafeRun();
|
|
205
224
|
*/
|
|
206
225
|
sse(uri: string, options?: SseOptions): Stream<HttpError, ServerSentEvent>;
|
|
226
|
+
/** A `maxBodyBytes` setting, or a `RangeError` when it is not a positive integer or `Infinity`. */
|
|
227
|
+
private static checkMaxBodyBytes;
|
|
228
|
+
/**
|
|
229
|
+
* The `redirect` setting a request runs under: `"error"` under `allowedOrigins`, where `"follow"`
|
|
230
|
+
* throws `RangeError`, since `fetch` would send the request, its headers and its body to every
|
|
231
|
+
* origin on the way before the client could see where it ended.
|
|
232
|
+
*/
|
|
233
|
+
private redirectOf;
|
|
234
|
+
/** The request's limit, else the client's; checked where the request is built. */
|
|
235
|
+
private maxBodyBytes;
|
|
207
236
|
private resolveUrl;
|
|
208
237
|
/** Prepares the request, runs it through the interceptors and `fetch`, and yields the `Response`. */
|
|
209
238
|
private exchange;
|
|
@@ -230,6 +259,40 @@ export declare type HttpClientConfig = {
|
|
|
230
259
|
timeout?: number;
|
|
231
260
|
/** Default credentials policy. Defaults to `"same-origin"` (matches the platform `fetch` default). */
|
|
232
261
|
credentials?: Credentials;
|
|
262
|
+
/**
|
|
263
|
+
* Whether requests follow a redirect: `"follow"`, as `fetch` does, or `"error"`, which fails the
|
|
264
|
+
* request with `kind: "redirect"` instead. Can be overridden per request. When neither the client
|
|
265
|
+
* nor the request sets it, the `fetch` default (follow) applies and nothing is set on the request.
|
|
266
|
+
* With `allowedOrigins`, it is `"error"`, and `"follow"` throws `RangeError` in the constructor.
|
|
267
|
+
*/
|
|
268
|
+
redirect?: Redirect;
|
|
269
|
+
/**
|
|
270
|
+
* The largest response body, in bytes, a request reads; none by default. Reading stops at the
|
|
271
|
+
* limit: a 2xx body past it fails with `kind: "tooLarge"`, and a non-2xx body past it is dropped
|
|
272
|
+
* (`body: null`). A `Content-Length` above the limit fails before reading. `raw()` hands the body
|
|
273
|
+
* to you unread, and server-sent events are not limited, except for an error response's body.
|
|
274
|
+
* A positive integer or `Infinity`; anything else throws `RangeError` in the constructor. Can be
|
|
275
|
+
* overridden per request.
|
|
276
|
+
*/
|
|
277
|
+
maxBodyBytes?: number;
|
|
278
|
+
/**
|
|
279
|
+
* The only origins requests may go to, such as `["https://api.example.com"]`; any origin by
|
|
280
|
+
* default. A request to another origin — an absolute URL, a `data:` or `blob:` URL, or a URL an
|
|
281
|
+
* interceptor rewrote — fails with `kind: "request"` before anything is sent, so the client's
|
|
282
|
+
* default headers and interceptors' credentials never leave for it. In a browser, a URL is read
|
|
283
|
+
* against the page's base URL (a `<base href>` included), as `fetch` reads it, and `fetch` gets
|
|
284
|
+
* the absolute URL that was checked. With this set, redirects are refused (`kind: "redirect"`):
|
|
285
|
+
* `redirect: "follow"`, on the client or on a request, throws `RangeError`, since `fetch` would
|
|
286
|
+
* send the request to every origin on the way. Each entry must be exactly an origin, and the
|
|
287
|
+
* `baseUrl`'s origin must be listed; otherwise the constructor throws `RangeError`.
|
|
288
|
+
*/
|
|
289
|
+
allowedOrigins?: readonly string[];
|
|
290
|
+
/**
|
|
291
|
+
* The `fetch` that sends every request: the end of the interceptor chain, for HTTP requests and
|
|
292
|
+
* server-sent events alike. Defaults to the global `fetch`, looked up when each request is sent.
|
|
293
|
+
* It is called without a receiver, so the platform `fetch` can be passed as is.
|
|
294
|
+
*/
|
|
295
|
+
fetch?: typeof globalThis.fetch;
|
|
233
296
|
};
|
|
234
297
|
|
|
235
298
|
/**
|
|
@@ -241,12 +304,13 @@ export declare type HttpClientConfig = {
|
|
|
241
304
|
*
|
|
242
305
|
* `kind` tells the two facts apart that `status` alone cannot: "the server said 500" is
|
|
243
306
|
* `kind: "response", status: 500`, while "nothing answered" is `kind: "network", status: 0`.
|
|
244
|
-
* For every kind other than `"response"
|
|
245
|
-
* for `"response"`.
|
|
307
|
+
* For every kind other than `"response"`, `"decode"`, `"redirect"` and `"tooLarge"`, `status` is `0`;
|
|
308
|
+
* `body` is `null` except for `"response"`.
|
|
246
309
|
*
|
|
247
|
-
* `body`, `headers` and `
|
|
248
|
-
* (a token in a query string, an error page echoing input
|
|
249
|
-
*
|
|
310
|
+
* `message`, `rawMessage`, `body`, `headers`, `url` and `cause` hold what the server and the request
|
|
311
|
+
* contained, which may be sensitive (a token in a query string, an error page echoing input, part of
|
|
312
|
+
* a body in a parse error, a request header value the platform rejected); log {@link HttpError.summary} instead outside a trusted sink.
|
|
313
|
+
* `Set-Cookie` is never carried.
|
|
250
314
|
*
|
|
251
315
|
* @example
|
|
252
316
|
* client.post("/payments", payment).mapErr((error) =>
|
|
@@ -264,6 +328,8 @@ export declare class HttpError extends Error {
|
|
|
264
328
|
/** The parsed response body, or `null` when none was parsed. */
|
|
265
329
|
readonly body: unknown;
|
|
266
330
|
readonly url: string;
|
|
331
|
+
/** The request method. Set by `HttpClient` on every error it returns. */
|
|
332
|
+
readonly method?: Method;
|
|
267
333
|
readonly headers?: Record<string, string>;
|
|
268
334
|
/** The underlying exception, when there was one (a `TypeError` from `fetch`, a parse error, an abort reason). */
|
|
269
335
|
readonly cause?: unknown;
|
|
@@ -312,6 +378,24 @@ export declare class HttpError extends Error {
|
|
|
312
378
|
* @param {unknown} [cause] The abort reason, if any.
|
|
313
379
|
*/
|
|
314
380
|
static aborted(url: string, cause?: unknown): HttpError;
|
|
381
|
+
/**
|
|
382
|
+
* An error for a redirect that the request's `redirect: "error"` setting refused. The redirect
|
|
383
|
+
* was not followed. `status` is the redirect status (`0` in a browser, which hides it), `body` is
|
|
384
|
+
* `null`, and `headers` are the redirect's own (its `Location`, where the platform exposes it).
|
|
385
|
+
*
|
|
386
|
+
* @param {string} url The request URL.
|
|
387
|
+
* @param {Response} response The redirect response.
|
|
388
|
+
*/
|
|
389
|
+
static redirect(url: string, response: Response): HttpError;
|
|
390
|
+
/**
|
|
391
|
+
* An error for a 2xx response whose body is larger than the request's `maxBodyBytes`. Reading
|
|
392
|
+
* stopped at the limit. `status` is the real status and `body` is `null`.
|
|
393
|
+
*
|
|
394
|
+
* @param {string} url The request URL.
|
|
395
|
+
* @param {Response} response The response whose body was too large.
|
|
396
|
+
* @param {number} maxBodyBytes The limit, in bytes.
|
|
397
|
+
*/
|
|
398
|
+
static tooLarge(url: string, response: Response, maxBodyBytes: number): HttpError;
|
|
315
399
|
/**
|
|
316
400
|
* Narrows the `unknown` error body to a concrete type using a runtime type guard.
|
|
317
401
|
* Returns `Some(body)` if the guard passes, `None` otherwise — so the narrow is *checked*,
|
|
@@ -333,6 +417,18 @@ export declare class HttpError extends Error {
|
|
|
333
417
|
* );
|
|
334
418
|
*/
|
|
335
419
|
bodyAs<T>(guard: (x: unknown) => x is T): Option_2<NonNullable<T>>;
|
|
420
|
+
/**
|
|
421
|
+
* The parts of this error that are safe to log: the kind, the status, the method, the host (with
|
|
422
|
+
* its port, without credentials) and, for a timeout, `timeoutMs`. It never holds the URL's path or
|
|
423
|
+
* query, the body, the headers, the message or the cause.
|
|
424
|
+
*
|
|
425
|
+
* @returns {HttpErrorSummary} The summary.
|
|
426
|
+
*
|
|
427
|
+
* @example
|
|
428
|
+
* client.get("/users/42?token=…").tapErr((error) => logger.warn("user lookup failed", error.summary()));
|
|
429
|
+
* // { kind: "response", status: 404, method: "GET", host: "api.example.com" }
|
|
430
|
+
*/
|
|
431
|
+
summary(): HttpErrorSummary;
|
|
336
432
|
}
|
|
337
433
|
|
|
338
434
|
/**
|
|
@@ -349,10 +445,30 @@ export declare class HttpError extends Error {
|
|
|
349
445
|
* - `"aborted"`: the request was aborted by something other than IO cancellation, such as an
|
|
350
446
|
* interceptor's own signal (an IO cancelled via `fiber.cancel()` or `IO.timeout` ends as
|
|
351
447
|
* `Cancelled`, not as an `HttpError`).
|
|
448
|
+
* - `"redirect"`: the server answered with a redirect and the request's `redirect` setting is
|
|
449
|
+
* `"error"`. The redirect was not followed. `status` is the redirect status, or `0` in a browser,
|
|
450
|
+
* which hides it.
|
|
451
|
+
* - `"tooLarge"`: the server answered 2xx with a body larger than the request's `maxBodyBytes`.
|
|
452
|
+
* Reading stopped at the limit. `status` is the real status and `body` is `null`.
|
|
352
453
|
*
|
|
353
454
|
* New kinds may be added in a minor release, so give an exhaustive `switch` a `default` branch.
|
|
354
455
|
*/
|
|
355
|
-
export declare type HttpErrorKind = "request" | "response" | "decode" | "network" | "timeout" | "aborted";
|
|
456
|
+
export declare type HttpErrorKind = "request" | "response" | "decode" | "network" | "timeout" | "aborted" | "redirect" | "tooLarge";
|
|
457
|
+
|
|
458
|
+
/**
|
|
459
|
+
* What {@link HttpError.summary} returns: the parts of an error that are safe to log. It never holds
|
|
460
|
+
* the URL's path or query, the body, the headers, the message or the cause.
|
|
461
|
+
*/
|
|
462
|
+
export declare type HttpErrorSummary = {
|
|
463
|
+
readonly kind: HttpErrorKind;
|
|
464
|
+
readonly status: number;
|
|
465
|
+
/** The request method, when the error came from an `HttpClient`. */
|
|
466
|
+
readonly method?: Method;
|
|
467
|
+
/** The host and port of the URL, without credentials. Absent for a relative URL. */
|
|
468
|
+
readonly host?: string;
|
|
469
|
+
/** The timeout that fired. Present only for `kind: "timeout"`. */
|
|
470
|
+
readonly timeoutMs?: number;
|
|
471
|
+
};
|
|
356
472
|
|
|
357
473
|
/**
|
|
358
474
|
* An HTTP interceptor that can modify or handle a request before, and its response after, the
|
|
@@ -427,6 +543,13 @@ export declare type Options<A = unknown> = RequestOptions & {
|
|
|
427
543
|
empty?: "error" | "option";
|
|
428
544
|
};
|
|
429
545
|
|
|
546
|
+
/**
|
|
547
|
+
* What to do when the server answers with a redirect (`301`, `302`, `303`, `307` or `308`):
|
|
548
|
+
* - `"follow"`: follow it, as `fetch` does by default;
|
|
549
|
+
* - `"error"`: do not follow it, and fail the request with `kind: "redirect"`.
|
|
550
|
+
*/
|
|
551
|
+
export declare type Redirect = "follow" | "error";
|
|
552
|
+
|
|
430
553
|
/**
|
|
431
554
|
* Options shared by every request: headers, credentials and timeout.
|
|
432
555
|
*/
|
|
@@ -441,6 +564,16 @@ export declare type RequestOptions = {
|
|
|
441
564
|
* or `NaN` value throws `RangeError` where the request is built.
|
|
442
565
|
*/
|
|
443
566
|
timeout?: number;
|
|
567
|
+
/**
|
|
568
|
+
* Whether the request follows a redirect. Overrides the client-level setting. `"follow"` on a
|
|
569
|
+
* client with `allowedOrigins` throws `RangeError` where the request is built.
|
|
570
|
+
*/
|
|
571
|
+
redirect?: Redirect;
|
|
572
|
+
/**
|
|
573
|
+
* The largest response body, in bytes, this request reads. Overrides the client-level setting.
|
|
574
|
+
* A positive integer or `Infinity`; anything else throws `RangeError` where the request is built.
|
|
575
|
+
*/
|
|
576
|
+
maxBodyBytes?: number;
|
|
444
577
|
};
|
|
445
578
|
|
|
446
579
|
/** Options for a request whose body is required (the default). */
|
|
@@ -495,6 +628,12 @@ export declare type SseOptions = {
|
|
|
495
628
|
headers?: Record<string, string>;
|
|
496
629
|
/** The credential policy — set `"include"` to send cookies. Defaults to the client-level setting. */
|
|
497
630
|
credentials?: Credentials;
|
|
631
|
+
/**
|
|
632
|
+
* Whether the connection follows a redirect. Defaults to the client-level setting. A refused
|
|
633
|
+
* redirect ends the stream with `kind: "redirect"`, which is not retried. `"follow"` on a client
|
|
634
|
+
* with `allowedOrigins` throws `RangeError` where the stream is built.
|
|
635
|
+
*/
|
|
636
|
+
redirect?: Redirect;
|
|
498
637
|
/**
|
|
499
638
|
* Whether to automatically reconnect when the connection ends or fails with a retryable error
|
|
500
639
|
* (network error or a `5xx` status). Terminal `4xx` responses (including auth failures) are not
|
|
@@ -503,8 +642,8 @@ export declare type SseOptions = {
|
|
|
503
642
|
*
|
|
504
643
|
* `true` waits `retry` ms (or the server's `retry:` value) before each reconnect, forever. Pass a
|
|
505
644
|
* `Schedule` for backoff, jitter or a limit on consecutive failed reconnects, e.g.
|
|
506
|
-
* `Schedule.exponential(1000).maxDelay(30_000).jittered()`; a server `retry:` value
|
|
507
|
-
*
|
|
645
|
+
* `Schedule.exponential(1000).maxDelay(30_000).jittered()`; a server `retry:` value, once
|
|
646
|
+
* received, can lengthen the schedule's delay but not shorten it. `maxAttempts` counts connection attempts since the
|
|
508
647
|
* last delivered event, the connection that delivered it included — `maxAttempts(3)` allows two
|
|
509
648
|
* reconnects in a row that deliver nothing — and the count resets with every delivered event.
|
|
510
649
|
*/
|