viell-effect-schema-http 0.1.0 → 0.3.0
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/README.md +44 -29
- package/dist/concurrency/Interaction.d.ts +7 -1
- package/dist/concurrency/Interaction.d.ts.map +1 -1
- package/dist/concurrency/Interaction.js.map +1 -1
- package/dist/http/Body.d.ts +25 -13
- package/dist/http/Body.d.ts.map +1 -1
- package/dist/http/Body.js +18 -8
- package/dist/http/Body.js.map +1 -1
- package/dist/http/Operation.d.ts +276 -13
- package/dist/http/Operation.d.ts.map +1 -1
- package/dist/http/Operation.js +210 -11
- package/dist/http/Operation.js.map +1 -1
- package/dist/http/Policy.d.ts +28 -2
- package/dist/http/Policy.d.ts.map +1 -1
- package/dist/http/Policy.js +28 -2
- package/dist/http/Policy.js.map +1 -1
- package/dist/http/Request.d.ts +520 -85
- package/dist/http/Request.d.ts.map +1 -1
- package/dist/http/Request.js +658 -143
- package/dist/http/Request.js.map +1 -1
- package/dist/http/Response.d.ts +130 -6
- package/dist/http/Response.d.ts.map +1 -1
- package/dist/http/Response.js +88 -7
- package/dist/http/Response.js.map +1 -1
- package/dist/http/UrlEncoding.d.ts +24 -7
- package/dist/http/UrlEncoding.d.ts.map +1 -1
- package/dist/http/UrlEncoding.js +7 -3
- package/dist/http/UrlEncoding.js.map +1 -1
- package/dist/http/internal/excess.d.ts +44 -0
- package/dist/http/internal/excess.d.ts.map +1 -0
- package/dist/http/internal/excess.js +231 -0
- package/dist/http/internal/excess.js.map +1 -0
- package/dist/http/internal/fields.d.ts +17 -4
- package/dist/http/internal/fields.d.ts.map +1 -1
- package/dist/http/internal/fields.js +11 -6
- package/dist/http/internal/fields.js.map +1 -1
- package/dist/http/internal/input.d.ts +70 -0
- package/dist/http/internal/input.d.ts.map +1 -0
- package/dist/http/internal/input.js +93 -0
- package/dist/http/internal/input.js.map +1 -0
- package/dist/http/internal/shape.d.ts +63 -0
- package/dist/http/internal/shape.d.ts.map +1 -0
- package/dist/http/internal/shape.js +225 -0
- package/dist/http/internal/shape.js.map +1 -0
- package/package.json +13 -12
- package/src/concurrency/Interaction.ts +7 -1
- package/src/http/Body.ts +41 -18
- package/src/http/Operation.ts +474 -33
- package/src/http/Policy.ts +30 -2
- package/src/http/Request.ts +1176 -253
- package/src/http/Response.ts +246 -23
- package/src/http/UrlEncoding.ts +32 -8
- package/src/http/internal/excess.ts +333 -0
- package/src/http/internal/fields.ts +37 -9
- package/src/http/internal/input.ts +228 -0
- package/src/http/internal/shape.ts +359 -0
package/src/http/Operation.ts
CHANGED
|
@@ -28,20 +28,70 @@ import * as Transport from "./Transport.js";
|
|
|
28
28
|
* @remarks
|
|
29
29
|
* `execute(input)` returns a cold Effect: work starts when it is evaluated, and each evaluation
|
|
30
30
|
* runs again. `Operation.make` supplies HTTP execution; `fromEffect` adapts an existing function.
|
|
31
|
-
* With `make`, the request bindings determine `I`.
|
|
32
|
-
*
|
|
31
|
+
* With `make`, the request bindings determine `I`. {@link InputOf} extracts it.
|
|
32
|
+
*
|
|
33
|
+
* `make` also keeps what it was built from in `parts`, which `P` describes, so {@link mapRequest},
|
|
34
|
+
* {@link mapResponse} and {@link mapOptions} can derive a variant. Annotating a value as
|
|
35
|
+
* `Operation<I, A, E, R>` leaves `P` unknown, which stops those functions compiling on it.
|
|
33
36
|
*/
|
|
34
|
-
export interface Operation<
|
|
37
|
+
export interface Operation<
|
|
38
|
+
in I,
|
|
39
|
+
out A,
|
|
40
|
+
out E = never,
|
|
41
|
+
out R = never,
|
|
42
|
+
out P = unknown,
|
|
43
|
+
>
|
|
35
44
|
extends Pipeable.Pipeable {
|
|
45
|
+
/** Describe one evaluation for this input. Nothing runs until the Effect does. */
|
|
36
46
|
readonly execute: (input: I) => Effect.Effect<A, E, R>;
|
|
47
|
+
/** What the operation was built from. A value from {@link fromEffect} has no parts. */
|
|
48
|
+
readonly parts?: P;
|
|
37
49
|
}
|
|
38
50
|
|
|
51
|
+
/**
|
|
52
|
+
* The input an operation's `execute` takes.
|
|
53
|
+
*
|
|
54
|
+
* @example
|
|
55
|
+
* ```ts
|
|
56
|
+
* import { Schema } from "effect";
|
|
57
|
+
* import { Body, Operation, Request, Response } from "viell-effect-schema-http";
|
|
58
|
+
* const search = Operation.make(
|
|
59
|
+
* Request.get("https://api.example.test/things").pipe(
|
|
60
|
+
* Request.query(Schema.Struct({ sort: Schema.String })),
|
|
61
|
+
* ),
|
|
62
|
+
* Response.status(200, Body.json),
|
|
63
|
+
* );
|
|
64
|
+
* type SearchInput = Operation.InputOf<typeof search>;
|
|
65
|
+
* const searchAll = (input: SearchInput) => search.execute(input);
|
|
66
|
+
* ```
|
|
67
|
+
*
|
|
68
|
+
* @remarks
|
|
69
|
+
* `Request.InputOf` gives the same for a request.
|
|
70
|
+
*/
|
|
71
|
+
export type InputOf<O> =
|
|
72
|
+
O extends Operation<infer I, unknown, unknown, unknown, unknown> ? I : never;
|
|
73
|
+
|
|
39
74
|
/**
|
|
40
75
|
* Adapt an Effect-returning function to the operation interface.
|
|
41
76
|
*
|
|
77
|
+
* @example
|
|
78
|
+
* ```ts
|
|
79
|
+
* import { Body, Operation, Request, Response } from "viell-effect-schema-http";
|
|
80
|
+
* const health = Operation.make(
|
|
81
|
+
* Request.get("https://api.example.test/health"),
|
|
82
|
+
* Response.status(200, Body.text),
|
|
83
|
+
* );
|
|
84
|
+
* // Callers can run this and map its result, and cannot adjust what it sends.
|
|
85
|
+
* const sealed = Operation.fromEffect(health.execute);
|
|
86
|
+
* ```
|
|
87
|
+
*
|
|
42
88
|
* @remarks
|
|
43
89
|
* The function is suspended until evaluation. This adapter adds no HTTP dispatch, decoding,
|
|
44
90
|
* retry policy or scope management beyond what the supplied function already does.
|
|
91
|
+
*
|
|
92
|
+
* The result has no parts, at compile time or at run time. So
|
|
93
|
+
* `Operation.fromEffect(operation.execute)` seals a definition: it keeps the same types and offers
|
|
94
|
+
* no adjustment.
|
|
45
95
|
*/
|
|
46
96
|
export const fromEffect = <I, A, E, R>(
|
|
47
97
|
execute: (input: I) => Effect.Effect<A, E, R>,
|
|
@@ -68,11 +118,16 @@ export interface Options<
|
|
|
68
118
|
* Applied after request preparation, suitable for fresh credentials or URL-dependent signatures.
|
|
69
119
|
* Run a signer after other request edits it must cover. Native status filters can reject responses
|
|
70
120
|
* before the declared response contract sees them.
|
|
121
|
+
* `attempt` starts at `1` and matches the `http.attempt` log annotation. A function with an optional
|
|
122
|
+
* second parameter of its own receives the number there, so wrap one in an arrow function.
|
|
71
123
|
* Appending native URL parameters can reserialize the entire query as form data, changing bare keys and
|
|
72
124
|
* escapes. Prefer Request query combinators, or preserve the query text when editing the URL directly.
|
|
73
125
|
*/
|
|
74
126
|
readonly transformClient?:
|
|
75
|
-
| ((
|
|
127
|
+
| ((
|
|
128
|
+
client: HttpClient.HttpClient,
|
|
129
|
+
attempt: number,
|
|
130
|
+
) => HttpClient.HttpClient.With<E, R>)
|
|
76
131
|
| undefined;
|
|
77
132
|
}
|
|
78
133
|
|
|
@@ -109,14 +164,16 @@ const outcome = (exit: Exit.Exit<unknown, unknown>): string =>
|
|
|
109
164
|
* Each evaluation prepares input once. Each attempt then owns a scope covering client execution
|
|
110
165
|
* and body decoding; cleanup completes before classification or a retry delay. Decoder and
|
|
111
166
|
* client `Scope` requirements are supplied by the attempt. Interruption and defects never retry.
|
|
112
|
-
* An automatic `Accept` header is added only when the request has
|
|
167
|
+
* An automatic `Accept` header is added only when the request declares none and has not removed
|
|
168
|
+
* it with `Request.removeHeader`.
|
|
169
|
+
*
|
|
170
|
+
* The result keeps its parts, so a definition written once can be adjusted where it is used with
|
|
171
|
+
* {@link mapRequest}, {@link mapResponse} and {@link mapOptions}. The original never changes.
|
|
113
172
|
*/
|
|
114
173
|
export const make = <
|
|
115
174
|
I,
|
|
116
175
|
E,
|
|
117
176
|
R,
|
|
118
|
-
H extends boolean,
|
|
119
|
-
Q extends boolean,
|
|
120
177
|
A,
|
|
121
178
|
E2,
|
|
122
179
|
R2,
|
|
@@ -124,22 +181,15 @@ export const make = <
|
|
|
124
181
|
R3 = never,
|
|
125
182
|
EP = never,
|
|
126
183
|
RP = never,
|
|
184
|
+
C extends Response.AnyCase = Response.AnyCase,
|
|
127
185
|
>(
|
|
128
|
-
request: Request.Request<I, E, R
|
|
129
|
-
response: Response.Response<A, E2, R2>,
|
|
186
|
+
request: Request.Request<I, E, R>,
|
|
187
|
+
response: Response.Response<A, E2, R2, C>,
|
|
130
188
|
options?: Options<E3, R3, EP, RP>,
|
|
131
|
-
):
|
|
132
|
-
I,
|
|
133
|
-
A,
|
|
134
|
-
|
|
135
|
-
| E3
|
|
136
|
-
| EP
|
|
137
|
-
| Request.InvalidRequest
|
|
138
|
-
| HttpClientError.HttpClientError
|
|
139
|
-
| Response.UnexpectedResponse
|
|
140
|
-
| Response.DecodeError<E2 | HttpClientError.HttpClientError>
|
|
141
|
-
| Cause.TimeoutError,
|
|
142
|
-
R | RP | Exclude<R2 | R3, Scope.Scope> | HttpClient.HttpClient
|
|
189
|
+
): Http<
|
|
190
|
+
Request.Request<I, E, R>,
|
|
191
|
+
Response.Response<A, E2, R2, C>,
|
|
192
|
+
Options<E3, R3, EP, RP>
|
|
143
193
|
> => {
|
|
144
194
|
const policy: Policy.Policy<EP, RP> = options?.policy ?? Policy.none;
|
|
145
195
|
const accept = response.accepts.join(", ");
|
|
@@ -147,7 +197,9 @@ export const make = <
|
|
|
147
197
|
function* (input: I) {
|
|
148
198
|
const compiled = yield* Request.compile(request, input);
|
|
149
199
|
const prepared =
|
|
150
|
-
accept !== "" &&
|
|
200
|
+
accept !== "" &&
|
|
201
|
+
compiled.request.headers.accept === undefined &&
|
|
202
|
+
!compiled.removedHeaders.has("accept")
|
|
151
203
|
? HttpClientRequest.setHeader(compiled.request, "accept", accept)
|
|
152
204
|
: compiled.request;
|
|
153
205
|
const client = yield* HttpClient.HttpClient;
|
|
@@ -174,7 +226,8 @@ export const make = <
|
|
|
174
226
|
> =
|
|
175
227
|
options?.transformClient === undefined
|
|
176
228
|
? HttpClient.withScope(client).execute
|
|
177
|
-
: HttpClient.withScope(options.transformClient(client))
|
|
229
|
+
: HttpClient.withScope(options.transformClient(client, attempt))
|
|
230
|
+
.execute;
|
|
178
231
|
// A fresh request identity keeps the scoped abort controller of this attempt separate.
|
|
179
232
|
const received = yield* send(
|
|
180
233
|
HttpClientRequest.setHeaders(prepared, {}),
|
|
@@ -254,7 +307,11 @@ export const make = <
|
|
|
254
307
|
),
|
|
255
308
|
Effect.withLogSpan("schema-http.operation"),
|
|
256
309
|
);
|
|
257
|
-
return {
|
|
310
|
+
return {
|
|
311
|
+
...Pipeable.Prototype,
|
|
312
|
+
execute,
|
|
313
|
+
parts: { request, response, options, step: undefined },
|
|
314
|
+
};
|
|
258
315
|
};
|
|
259
316
|
|
|
260
317
|
/**
|
|
@@ -274,27 +331,411 @@ export const execute: {
|
|
|
274
331
|
self.execute(input),
|
|
275
332
|
);
|
|
276
333
|
|
|
334
|
+
/**
|
|
335
|
+
* The conversion {@link map} and {@link mapEffect} recorded, run once after the parts.
|
|
336
|
+
*
|
|
337
|
+
* @remarks
|
|
338
|
+
* Only its failures and services are in the type. Its result is the operation's own `A`, and what
|
|
339
|
+
* it was written for is what the response still produces, so neither is repeated here.
|
|
340
|
+
*/
|
|
341
|
+
export interface Step<out E = never, out R = never> {
|
|
342
|
+
/** Convert the operation's result. */
|
|
343
|
+
readonly run: (value: never) => Effect.Effect<unknown, E, R>;
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/**
|
|
347
|
+
* What {@link make} keeps: the three parts as given, and any recorded {@link Step}.
|
|
348
|
+
*
|
|
349
|
+
* @remarks
|
|
350
|
+
* Read a part with `operation.parts?.request`. Each whole part is one type parameter, which keeps
|
|
351
|
+
* the parameter count down as `Schema.decodeTo` does.
|
|
352
|
+
*
|
|
353
|
+
* `S` is invariant: widening it by annotation could otherwise make any response look as if it fits
|
|
354
|
+
* a recorded step.
|
|
355
|
+
*
|
|
356
|
+
* {@link mapRequest}, {@link mapResponse}, {@link mapOptions} and {@link unmap} build from these,
|
|
357
|
+
* so they drop an `execute` replaced on the value. {@link map} and {@link mapEffect} wrap
|
|
358
|
+
* `execute` itself, and keep it.
|
|
359
|
+
*/
|
|
360
|
+
export interface Parts<out Q, in out S, out O, out T = undefined> {
|
|
361
|
+
/** The request it was built from. */
|
|
362
|
+
readonly request: Q;
|
|
363
|
+
/** The response contract it was built from. */
|
|
364
|
+
readonly response: S;
|
|
365
|
+
/** The options it was built with, or `undefined` for none. */
|
|
366
|
+
readonly options: O | undefined;
|
|
367
|
+
/** The recorded {@link Step}, or `undefined` for none. */
|
|
368
|
+
readonly step: T;
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
type RequestFailure<Q> =
|
|
372
|
+
Q extends Request.Request<never, infer E, unknown> ? E : never;
|
|
373
|
+
type RequestServices<Q> =
|
|
374
|
+
Q extends Request.Request<never, unknown, infer R> ? R : never;
|
|
375
|
+
// The cases are inferred too, or the check would not resolve while `C` is still generic.
|
|
376
|
+
type ValueOf<S> =
|
|
377
|
+
S extends Response.Response<infer A, unknown, unknown, infer _C> ? A : never;
|
|
378
|
+
type ResponseFailure<S> =
|
|
379
|
+
S extends Response.Response<unknown, infer E, unknown, infer _C> ? E : never;
|
|
380
|
+
type ResponseServices<S> =
|
|
381
|
+
S extends Response.Response<unknown, unknown, infer R, infer _C> ? R : never;
|
|
382
|
+
// Every slot is inferred: `Options` is invariant, and a fixed slot silently gives `never`.
|
|
383
|
+
type ClientFailure<O> =
|
|
384
|
+
O extends Options<infer E, infer _R, infer _EP, infer _RP> ? E : never;
|
|
385
|
+
type ClientServices<O> =
|
|
386
|
+
O extends Options<infer _E, infer R, infer _EP, infer _RP> ? R : never;
|
|
387
|
+
type PolicyFailure<O> =
|
|
388
|
+
O extends Options<infer _E, infer _R, infer E, infer _RP> ? E : never;
|
|
389
|
+
type PolicyServices<O> =
|
|
390
|
+
O extends Options<infer _E, infer _R, infer _EP, infer R> ? R : never;
|
|
391
|
+
type StepFailure<T> = T extends Step<infer E, unknown> ? E : never;
|
|
392
|
+
type StepServices<T> = T extends Step<unknown, infer R> ? R : never;
|
|
393
|
+
|
|
394
|
+
/** An operation fresh from {@link make}: three parts, no step, and the response's own result. */
|
|
395
|
+
export type Http<Q, S, O> = Derived<ValueOf<S>, Q, S, O>;
|
|
396
|
+
|
|
397
|
+
/**
|
|
398
|
+
* An operation built from parts, returning `B`.
|
|
399
|
+
*
|
|
400
|
+
* @remarks
|
|
401
|
+
* `B` comes first so that an editor hover shows the result before the parts. The unions stay
|
|
402
|
+
* inline: a named alias would print with all of `Q`, `S` and `O` repeated inside it.
|
|
403
|
+
*/
|
|
404
|
+
export type Derived<B, Q, S, O, T = undefined> = Operation<
|
|
405
|
+
Request.InputOf<Q>,
|
|
406
|
+
B,
|
|
407
|
+
| RequestFailure<Q>
|
|
408
|
+
| ClientFailure<O>
|
|
409
|
+
| PolicyFailure<O>
|
|
410
|
+
| StepFailure<T>
|
|
411
|
+
| Request.InvalidRequest
|
|
412
|
+
| HttpClientError.HttpClientError
|
|
413
|
+
| Response.UnexpectedResponse
|
|
414
|
+
| Response.DecodeError<ResponseFailure<S> | HttpClientError.HttpClientError>
|
|
415
|
+
| Cause.TimeoutError,
|
|
416
|
+
| RequestServices<Q>
|
|
417
|
+
| PolicyServices<O>
|
|
418
|
+
| StepServices<T>
|
|
419
|
+
| Exclude<ResponseServices<S> | ClientServices<O>, Scope.Scope>
|
|
420
|
+
| HttpClient.HttpClient,
|
|
421
|
+
Parts<Q, S, O, T>
|
|
422
|
+
>;
|
|
423
|
+
|
|
424
|
+
/**
|
|
425
|
+
* Any operation carrying the parts `P` and returning `B`.
|
|
426
|
+
*
|
|
427
|
+
* @remarks
|
|
428
|
+
* What {@link mapRequest}, {@link mapResponse}, {@link mapOptions} and {@link unmap} accept. The
|
|
429
|
+
* input, failures and services are left open because a variant works them out again from `P`.
|
|
430
|
+
*/
|
|
431
|
+
export type Adjustable<B, P> = Operation<never, B, unknown, unknown, P>;
|
|
432
|
+
|
|
433
|
+
type Runner = (value: unknown) => Effect.Effect<unknown, unknown, unknown>;
|
|
434
|
+
|
|
435
|
+
/** Parts with their types erased, for the helpers below. Each caller's signature states them. */
|
|
436
|
+
type ErasedParts = Parts<
|
|
437
|
+
Request.Request<never, unknown, unknown>,
|
|
438
|
+
Response.Response<unknown, unknown, unknown>,
|
|
439
|
+
Options<unknown, unknown, unknown, unknown>,
|
|
440
|
+
{ readonly run: Runner } | undefined
|
|
441
|
+
>;
|
|
442
|
+
|
|
443
|
+
/** The types refuse an operation with no parts; a cast or plain JavaScript gets a clear failure. */
|
|
444
|
+
const partsOf = <P>(self: Adjustable<unknown, P>): P => {
|
|
445
|
+
if (self.parts === undefined)
|
|
446
|
+
throw new Error(
|
|
447
|
+
"This operation has no parts to adjust: it came from Operation.fromEffect",
|
|
448
|
+
);
|
|
449
|
+
return self.parts;
|
|
450
|
+
};
|
|
451
|
+
|
|
452
|
+
/** Rebuild through {@link make}, so the automatic `Accept` follows the response. */
|
|
453
|
+
const rebuild = <Q, S, O, T, Result>(parts: Parts<Q, S, O, T>): Result => {
|
|
454
|
+
const { request, response, options, step } = parts as unknown as ErasedParts;
|
|
455
|
+
const built = make(request, response, options);
|
|
456
|
+
const result: unknown =
|
|
457
|
+
step === undefined
|
|
458
|
+
? built
|
|
459
|
+
: {
|
|
460
|
+
...built,
|
|
461
|
+
execute: (input: never) =>
|
|
462
|
+
Effect.flatMap(built.execute(input), step.run),
|
|
463
|
+
parts: { request, response, options, step },
|
|
464
|
+
};
|
|
465
|
+
return result as Result;
|
|
466
|
+
};
|
|
467
|
+
|
|
468
|
+
/**
|
|
469
|
+
* Derive a variant with a changed request. A recorded result step stays.
|
|
470
|
+
*
|
|
471
|
+
* @example
|
|
472
|
+
* ```ts
|
|
473
|
+
* import { Body, Operation, Request, Response } from "viell-effect-schema-http";
|
|
474
|
+
* const getThings = Operation.make(
|
|
475
|
+
* Request.get("https://api.example.test/things?limit=25"),
|
|
476
|
+
* Response.status(200, Body.json),
|
|
477
|
+
* );
|
|
478
|
+
* const firstFive = Request.setQuery("limit", "5");
|
|
479
|
+
* const fewerThings = getThings.pipe(Operation.mapRequest(firstFive));
|
|
480
|
+
* // getThings still asks for 25.
|
|
481
|
+
* ```
|
|
482
|
+
*
|
|
483
|
+
* @remarks
|
|
484
|
+
* The function receives the current request, so every `Request` function works here, including a
|
|
485
|
+
* binding that changes the operation's input. The automatic `Accept` and the options carry over.
|
|
486
|
+
* The library cannot tell whether a change alters the shape of the answer: selecting fields or
|
|
487
|
+
* embedding relations usually does, and then needs {@link mapResponse} too.
|
|
488
|
+
*
|
|
489
|
+
* Works on any operation from {@link make}, mapped or not. A value from {@link fromEffect} has no
|
|
490
|
+
* parts, and one annotated as a plain `Operation<I, A, E, R>` hides them: both are compile errors.
|
|
491
|
+
*/
|
|
492
|
+
export const mapRequest =
|
|
493
|
+
<I, E, R, I2, E2, R2>(
|
|
494
|
+
f: (request: Request.Request<I, E, R>) => Request.Request<I2, E2, R2>,
|
|
495
|
+
) =>
|
|
496
|
+
<B, S, O, T>(
|
|
497
|
+
self: Adjustable<B, Parts<Request.Request<I, E, R>, S, O, T>>,
|
|
498
|
+
): Derived<B, Request.Request<I2, E2, R2>, S, O, T> => {
|
|
499
|
+
const parts = partsOf(self);
|
|
500
|
+
return rebuild({ ...parts, request: f(parts.request) });
|
|
501
|
+
};
|
|
502
|
+
|
|
503
|
+
interface NoLongerFits<A> {
|
|
504
|
+
readonly "Use Operation.unmap first, then map again: this response no longer fits the mapping.": A;
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
/**
|
|
508
|
+
* The rule {@link mapResponse} applies to a new result `A2`, given the current result `A`.
|
|
509
|
+
*
|
|
510
|
+
* @remarks
|
|
511
|
+
* With no step, `T` is `undefined` and anything fits. With a step, `A2` must be something the
|
|
512
|
+
* current response could produce. An `any` result proves nothing, so it does not fit either.
|
|
513
|
+
*
|
|
514
|
+
* `W` is everything the function returned, and stays `never` when nothing was inferred from it.
|
|
515
|
+
* That means the function itself does not compile, as with a key the contract lacks. `A2` then
|
|
516
|
+
* reads `unknown` for no reason of its own, so the rule stands aside and leaves the function's own
|
|
517
|
+
* error as the only one. A function that returns a response, or `any`, always gives `W` a value, so
|
|
518
|
+
* a result that really is `unknown` is still refused.
|
|
519
|
+
*/
|
|
520
|
+
export type Fits<A2, A, T, W = unknown> = [T] extends [undefined]
|
|
521
|
+
? unknown
|
|
522
|
+
: [W] extends [never]
|
|
523
|
+
? unknown
|
|
524
|
+
: 0 extends 1 & A2
|
|
525
|
+
? NoLongerFits<A2>
|
|
526
|
+
: [A2] extends [A]
|
|
527
|
+
? unknown
|
|
528
|
+
: NoLongerFits<A2>;
|
|
529
|
+
|
|
530
|
+
/**
|
|
531
|
+
* Derive a variant with a changed response. A recorded result step stays, and has to fit.
|
|
532
|
+
*
|
|
533
|
+
* @example
|
|
534
|
+
* ```ts
|
|
535
|
+
* import { Schema } from "effect";
|
|
536
|
+
* import { Body, Operation, Request, Response } from "viell-effect-schema-http";
|
|
537
|
+
* const Thing = Schema.Struct({ id: Schema.Number, name: Schema.String });
|
|
538
|
+
* const ThingOption = Schema.Struct({ id: Schema.Number });
|
|
539
|
+
* const getThing = Operation.make(
|
|
540
|
+
* Request.get("https://api.example.test/things/1"),
|
|
541
|
+
* Response.status(200, Body.jsonSchema(Thing)),
|
|
542
|
+
* );
|
|
543
|
+
* const asOption = Response.replace(200, Body.jsonSchema(ThingOption));
|
|
544
|
+
* const thingOption = getThing.pipe(Operation.mapResponse(asOption));
|
|
545
|
+
* ```
|
|
546
|
+
*
|
|
547
|
+
* @remarks
|
|
548
|
+
* The function receives the current response, so {@link Response.replace},
|
|
549
|
+
* {@link Response.remove} and {@link Response.orElse} all work here. The automatic `Accept` follows
|
|
550
|
+
* the new response.
|
|
551
|
+
*
|
|
552
|
+
* On a mapped operation the new result must fit: it has to be assignable to the current response's
|
|
553
|
+
* result, and not `any`, because the recorded step was written for that result. So a same-shape
|
|
554
|
+
* replace or a removal works, and anything else is a compile error that names {@link unmap}.
|
|
555
|
+
* A narrowed result is the new baseline, so widening it back needs {@link unmap} as well.
|
|
556
|
+
* This is a compile-time rule: a cast gets past it, and the step then receives the wrong shape.
|
|
557
|
+
*/
|
|
558
|
+
export const mapResponse =
|
|
559
|
+
<
|
|
560
|
+
A,
|
|
561
|
+
E,
|
|
562
|
+
R,
|
|
563
|
+
C extends Response.AnyCase,
|
|
564
|
+
A2,
|
|
565
|
+
E2,
|
|
566
|
+
R2,
|
|
567
|
+
C2 extends Response.AnyCase,
|
|
568
|
+
W = never,
|
|
569
|
+
>(
|
|
570
|
+
f: (
|
|
571
|
+
response: Response.Response<A, E, R, C>,
|
|
572
|
+
) => Response.Response<A2, E2, R2, C2> & W,
|
|
573
|
+
) =>
|
|
574
|
+
<B, Q, O, T>(
|
|
575
|
+
self: Adjustable<B, Parts<Q, Response.Response<A, E, R, C>, O, T>> &
|
|
576
|
+
Fits<A2, A, T, W>,
|
|
577
|
+
): Derived<
|
|
578
|
+
[T] extends [undefined] ? A2 : B,
|
|
579
|
+
Q,
|
|
580
|
+
Response.Response<A2, E2, R2, C2>,
|
|
581
|
+
O,
|
|
582
|
+
T
|
|
583
|
+
> => {
|
|
584
|
+
const parts = partsOf(self);
|
|
585
|
+
return rebuild({ ...parts, response: f(parts.response) });
|
|
586
|
+
};
|
|
587
|
+
|
|
588
|
+
/**
|
|
589
|
+
* Derive a variant with changed options. A recorded result step stays.
|
|
590
|
+
*
|
|
591
|
+
* @example
|
|
592
|
+
* ```ts
|
|
593
|
+
* import { Schedule } from "effect";
|
|
594
|
+
* import {
|
|
595
|
+
* Body,
|
|
596
|
+
* Operation,
|
|
597
|
+
* Policy,
|
|
598
|
+
* Request,
|
|
599
|
+
* Response,
|
|
600
|
+
* } from "viell-effect-schema-http";
|
|
601
|
+
* const getThings = Operation.make(
|
|
602
|
+
* Request.get("https://api.example.test/things"),
|
|
603
|
+
* Response.status(200, Body.json),
|
|
604
|
+
* );
|
|
605
|
+
* const retryTwice = Policy.make(Schedule.recurs(2));
|
|
606
|
+
* const patient = getThings.pipe(
|
|
607
|
+
* Operation.mapOptions((options) => ({ ...options, policy: retryTwice })),
|
|
608
|
+
* );
|
|
609
|
+
* ```
|
|
610
|
+
*
|
|
611
|
+
* @remarks
|
|
612
|
+
* The function receives the current options, or `undefined` if there are none, and its result
|
|
613
|
+
* replaces them. Spread them to keep what you do not change. A failure or service type that only
|
|
614
|
+
* a dropped option added leaves with it.
|
|
615
|
+
*/
|
|
616
|
+
export const mapOptions =
|
|
617
|
+
<O, E = HttpClientError.HttpClientError, R = never, EP = never, RP = never>(
|
|
618
|
+
f: (options: O | undefined) => Options<E, R, EP, RP>,
|
|
619
|
+
) =>
|
|
620
|
+
<B, Q, S, T>(
|
|
621
|
+
self: Adjustable<B, Parts<Q, S, O, T>>,
|
|
622
|
+
): Derived<B, Q, S, Options<E, R, EP, RP>, T> => {
|
|
623
|
+
const parts = partsOf(self);
|
|
624
|
+
return rebuild({ ...parts, options: f(parts.options) });
|
|
625
|
+
};
|
|
626
|
+
|
|
627
|
+
/**
|
|
628
|
+
* Remove every recorded result step, so the operation returns what its response decodes.
|
|
629
|
+
*
|
|
630
|
+
* @example
|
|
631
|
+
* ```ts
|
|
632
|
+
* import { Schema } from "effect";
|
|
633
|
+
* import { Body, Operation, Request, Response } from "viell-effect-schema-http";
|
|
634
|
+
* const Page = Schema.Struct({ data: Schema.Array(Schema.String) });
|
|
635
|
+
* const Names = Schema.Struct({ data: Schema.Array(Schema.Number) });
|
|
636
|
+
* const getThings = Operation.make(
|
|
637
|
+
* Request.get("https://api.example.test/things"),
|
|
638
|
+
* Response.status(200, Body.jsonSchema(Page)),
|
|
639
|
+
* ).pipe(Operation.map((page) => page.data));
|
|
640
|
+
*
|
|
641
|
+
* const asIds = Response.replace(200, Body.jsonSchema(Names));
|
|
642
|
+
* const thingIds = getThings.pipe(
|
|
643
|
+
* Operation.unmap,
|
|
644
|
+
* Operation.mapResponse(asIds),
|
|
645
|
+
* Operation.map((page) => page.data),
|
|
646
|
+
* );
|
|
647
|
+
* ```
|
|
648
|
+
*
|
|
649
|
+
* @remarks
|
|
650
|
+
* This is the route to a response {@link mapResponse} refuses: remove the mapping, change the
|
|
651
|
+
* response, then map again. The failures and services the steps added leave with them. On an
|
|
652
|
+
* operation with no step this changes nothing.
|
|
653
|
+
*/
|
|
654
|
+
export const unmap = <B, Q, S, O, T>(
|
|
655
|
+
self: Adjustable<B, Parts<Q, S, O, T>>,
|
|
656
|
+
): Http<Q, S, O> => rebuild({ ...partsOf(self), step: undefined });
|
|
657
|
+
|
|
658
|
+
/**
|
|
659
|
+
* The parts after {@link map} or {@link mapEffect} records a step adding failures `E` and services
|
|
660
|
+
* `R`. An operation with no parts stays that way.
|
|
661
|
+
*
|
|
662
|
+
* @remarks
|
|
663
|
+
* The conditional lives here, in the fifth argument, because a conditional return type would stop
|
|
664
|
+
* `flow` composing these functions.
|
|
665
|
+
*/
|
|
666
|
+
export type Next<P, E, R> = [P] extends [
|
|
667
|
+
Parts<infer Q, infer S, infer O, infer T>,
|
|
668
|
+
]
|
|
669
|
+
? Parts<Q, S, O, Step<StepFailure<T> | E, StepServices<T> | R>>
|
|
670
|
+
: P;
|
|
671
|
+
|
|
672
|
+
/**
|
|
673
|
+
* Wrap the operation's own `execute`, and record the step for a later {@link rebuild}. Two steps
|
|
674
|
+
* combine into one, so the type does not grow with each map.
|
|
675
|
+
*/
|
|
676
|
+
const addStep = <Result>(
|
|
677
|
+
self: Adjustable<unknown, unknown>,
|
|
678
|
+
f: Runner,
|
|
679
|
+
): Result => {
|
|
680
|
+
const wrapped = fromEffect((input: never) =>
|
|
681
|
+
Effect.flatMap(self.execute(input), f),
|
|
682
|
+
);
|
|
683
|
+
const parts = self.parts as ErasedParts | undefined;
|
|
684
|
+
const previous = parts?.step;
|
|
685
|
+
const result: unknown =
|
|
686
|
+
parts === undefined
|
|
687
|
+
? wrapped
|
|
688
|
+
: {
|
|
689
|
+
...wrapped,
|
|
690
|
+
parts: {
|
|
691
|
+
...parts,
|
|
692
|
+
step: {
|
|
693
|
+
run:
|
|
694
|
+
previous === undefined
|
|
695
|
+
? f
|
|
696
|
+
: (value: unknown) => Effect.flatMap(previous.run(value), f),
|
|
697
|
+
},
|
|
698
|
+
},
|
|
699
|
+
};
|
|
700
|
+
return result as Result;
|
|
701
|
+
};
|
|
702
|
+
|
|
277
703
|
/**
|
|
278
704
|
* Transform an operation's successful result with a pure function.
|
|
279
705
|
*
|
|
280
706
|
* @remarks
|
|
281
|
-
* Keeps the input, error and service types. Runs after the operation and its retry policy
|
|
282
|
-
* Use {@link mapEffect} to return a typed failure
|
|
707
|
+
* Keeps the input, error and service types. Runs once, after the operation and its retry policy
|
|
708
|
+
* finish, outside each attempt's scope and timeout. Use {@link mapEffect} to return a typed failure
|
|
709
|
+
* or perform further effectful work.
|
|
710
|
+
*
|
|
711
|
+
* The operation keeps its parts and records this as a step, so {@link mapRequest} and
|
|
712
|
+
* {@link mapOptions} still work on the result, and {@link mapResponse} works while the new result
|
|
713
|
+
* fits. Two maps combine into one step. The mapping applies to the whole result, whichever case
|
|
714
|
+
* produced it. For a conversion that belongs to one case, use `Body.map` on that case's decoder: a
|
|
715
|
+
* later `Response.replace` takes the conversion with the case.
|
|
283
716
|
*/
|
|
284
717
|
export const map =
|
|
285
718
|
<A, B>(f: (value: A) => B) =>
|
|
286
|
-
<I, E, R
|
|
287
|
-
|
|
719
|
+
<I, E, R, P = unknown>(
|
|
720
|
+
self: Operation<I, A, E, R, P>,
|
|
721
|
+
): Operation<I, B, E, R, Next<P, never, never>> =>
|
|
722
|
+
addStep(self, (value) => Effect.succeed(f(value as A)));
|
|
288
723
|
|
|
289
724
|
/**
|
|
290
725
|
* Transform an operation's successful result with an Effect.
|
|
291
726
|
*
|
|
292
727
|
* @remarks
|
|
293
|
-
* Adds the transformation's errors and required services. Runs after the operation's retry
|
|
294
|
-
* policy completes, so failures here do not trigger that
|
|
295
|
-
* response outcome into an application
|
|
728
|
+
* Adds the transformation's errors and required services. Runs once, after the operation's retry
|
|
729
|
+
* policy completes, outside each attempt's scope and timeout, so failures here do not trigger that
|
|
730
|
+
* policy and arrive as themselves. Use it to turn a recognized response outcome into an application
|
|
731
|
+
* error.
|
|
732
|
+
*
|
|
733
|
+
* The operation keeps its parts and records this as a step, as {@link map} describes. Its failures
|
|
734
|
+
* and services stay through a variant and leave with {@link unmap}.
|
|
296
735
|
*/
|
|
297
736
|
export const mapEffect =
|
|
298
737
|
<A, B, E2, R2>(f: (value: A) => Effect.Effect<B, E2, R2>) =>
|
|
299
|
-
<I, E, R
|
|
300
|
-
|
|
738
|
+
<I, E, R, P = unknown>(
|
|
739
|
+
self: Operation<I, A, E, R, P>,
|
|
740
|
+
): Operation<I, B, E | E2, R | R2, Next<P, E2, R2>> =>
|
|
741
|
+
addStep(self, (value) => f(value as A));
|
package/src/http/Policy.ts
CHANGED
|
@@ -59,6 +59,10 @@ const isTransientError = (error: unknown): boolean =>
|
|
|
59
59
|
* The statuses are 408, 429, 500, 502, 503 and 504, matching Effect's transient classification.
|
|
60
60
|
* A declared response with one of these statuses is eligible even when decoding succeeded.
|
|
61
61
|
* This does not check the method or whether repeating a remote action is safe.
|
|
62
|
+
*
|
|
63
|
+
* It reads what the client reports, and clients differ. A body cut off after its headers is a
|
|
64
|
+
* decoding failure through `fetch`, which is not eligible, and a transport failure through a client
|
|
65
|
+
* that reads the whole response first, which is.
|
|
62
66
|
*/
|
|
63
67
|
export const transient = (reason: Reason): boolean => {
|
|
64
68
|
if (
|
|
@@ -87,8 +91,9 @@ export const transient = (reason: Reason): boolean => {
|
|
|
87
91
|
* `Schedule.recurs(n)` permits up to `n` retries after the first attempt. Defaults to
|
|
88
92
|
* {@link transient}, honoring `Retry-After`, and no attempt timeout. Enable retries only when
|
|
89
93
|
* repeating the service action is acceptable; transport failure does not prove it was unapplied.
|
|
90
|
-
*
|
|
91
|
-
*
|
|
94
|
+
* `while` sees every completed outcome, so `while: () => true` also repeats a successful 200 until
|
|
95
|
+
* the schedule ends. The attempt timeout covers client execution and decoding, not initial request
|
|
96
|
+
* preparation or retry delays. Apply `Effect.timeout` around the operation for an overall limit.
|
|
92
97
|
*/
|
|
93
98
|
export const make = <Out, E = never, R = never>(
|
|
94
99
|
schedule: Schedule.Schedule<Out, Reason, E, R>,
|
|
@@ -106,9 +111,32 @@ export const make = <Out, E = never, R = never>(
|
|
|
106
111
|
|
|
107
112
|
/**
|
|
108
113
|
* One attempt, with no retry and no library-imposed timeout.
|
|
114
|
+
*
|
|
115
|
+
* @remarks
|
|
116
|
+
* This is one attempt by the library, not one send. A client can send a request again by itself, as
|
|
117
|
+
* Chromium does, a POST included, when a reused connection ends with no response.
|
|
109
118
|
*/
|
|
110
119
|
export const none: Policy = make(Schedule.recurs(0));
|
|
111
120
|
|
|
121
|
+
/**
|
|
122
|
+
* One attempt with a timeout, and no retry.
|
|
123
|
+
*
|
|
124
|
+
* @example
|
|
125
|
+
* ```ts
|
|
126
|
+
* import { Policy } from "viell-effect-schema-http";
|
|
127
|
+
* const oneQuickAttempt = Policy.timeout("2 seconds");
|
|
128
|
+
* // One attempt, given up after two seconds.
|
|
129
|
+
* ```
|
|
130
|
+
*
|
|
131
|
+
* @remarks
|
|
132
|
+
* This is {@link none} with the `attemptTimeout` of {@link make}, so a timed-out attempt ends the
|
|
133
|
+
* operation. The timeout covers client execution and decoding. It excludes request preparation and
|
|
134
|
+
* result mapping, so a slow base URL Effect or `Operation.mapEffect` step is outside it. Apply
|
|
135
|
+
* `Effect.timeout` around the operation for a limit on all of that.
|
|
136
|
+
*/
|
|
137
|
+
export const timeout = (duration: Duration.Input): Policy =>
|
|
138
|
+
make(Schedule.recurs(0), { attemptTimeout: duration });
|
|
139
|
+
|
|
112
140
|
/**
|
|
113
141
|
* Read the minimum retry delay requested by a response's `Retry-After` header.
|
|
114
142
|
*
|