viell-effect-schema-http 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +88 -2
- package/dist/concurrency/Interaction.d.ts +65 -0
- package/dist/concurrency/Interaction.d.ts.map +1 -0
- package/dist/concurrency/Interaction.js +99 -0
- package/dist/concurrency/Interaction.js.map +1 -0
- package/dist/http/Body.d.ts +162 -0
- package/dist/http/Body.d.ts.map +1 -0
- package/dist/http/Body.js +184 -0
- package/dist/http/Body.js.map +1 -0
- package/dist/http/Operation.d.ts +97 -0
- package/dist/http/Operation.d.ts.map +1 -0
- package/dist/http/Operation.js +146 -0
- package/dist/http/Operation.js.map +1 -0
- package/dist/http/Policy.d.ts +82 -0
- package/dist/http/Policy.d.ts.map +1 -0
- package/dist/http/Policy.js +76 -0
- package/dist/http/Policy.js.map +1 -0
- package/dist/http/Request.d.ts +324 -0
- package/dist/http/Request.d.ts.map +1 -0
- package/dist/http/Request.js +391 -0
- package/dist/http/Request.js.map +1 -0
- package/dist/http/Response.d.ts +126 -0
- package/dist/http/Response.d.ts.map +1 -0
- package/dist/http/Response.js +100 -0
- package/dist/http/Response.js.map +1 -0
- package/dist/http/Transport.d.ts +75 -0
- package/dist/http/Transport.d.ts.map +1 -0
- package/dist/http/Transport.js +91 -0
- package/dist/http/Transport.js.map +1 -0
- package/dist/http/UrlEncoding.d.ts +78 -0
- package/dist/http/UrlEncoding.d.ts.map +1 -0
- package/dist/http/UrlEncoding.js +64 -0
- package/dist/http/UrlEncoding.js.map +1 -0
- package/dist/http/internal/fields.d.ts +12 -0
- package/dist/http/internal/fields.d.ts.map +1 -0
- package/dist/http/internal/fields.js +21 -0
- package/dist/http/internal/fields.js.map +1 -0
- package/dist/main.d.ts +33 -0
- package/dist/main.d.ts.map +1 -0
- package/dist/main.js +33 -0
- package/dist/main.js.map +1 -0
- package/package.json +125 -4
- package/src/concurrency/Interaction.ts +192 -0
- package/src/http/Body.ts +318 -0
- package/src/http/Operation.ts +300 -0
- package/src/http/Policy.ts +130 -0
- package/src/http/Request.ts +700 -0
- package/src/http/Response.ts +201 -0
- package/src/http/Transport.ts +143 -0
- package/src/http/UrlEncoding.ts +119 -0
- package/src/http/internal/fields.ts +46 -0
- package/src/main.ts +32 -0
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
import { Data, Effect, Option, Pipeable } from "effect";
|
|
2
|
+
import type {
|
|
3
|
+
Cookies,
|
|
4
|
+
Headers,
|
|
5
|
+
HttpClientError,
|
|
6
|
+
HttpClientResponse,
|
|
7
|
+
} from "effect/http";
|
|
8
|
+
import * as Body from "./Body.js";
|
|
9
|
+
import * as Transport from "./Transport.js";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* The status, headers and cookies available for selecting a response decoder.
|
|
13
|
+
*
|
|
14
|
+
* @remarks
|
|
15
|
+
* Contains no body. Header and cookie visibility depends on the HTTP provider and browser.
|
|
16
|
+
* `headerLines` is present only when a provider attached its observed lines.
|
|
17
|
+
*/
|
|
18
|
+
export interface Metadata {
|
|
19
|
+
readonly status: number;
|
|
20
|
+
readonly headers: Headers.Headers;
|
|
21
|
+
readonly cookies: Cookies.Cookies;
|
|
22
|
+
/** Provider-observed lines, when the provider supplied them. Normalized headers are always available. */
|
|
23
|
+
readonly headerLines: Option.Option<Transport.Lines>;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* No response case matched, and the unmatched body was successfully drained.
|
|
28
|
+
*
|
|
29
|
+
* @remarks
|
|
30
|
+
* Contains metadata only. A failed drain produces {@link DecodeError} instead.
|
|
31
|
+
*/
|
|
32
|
+
export class UnexpectedResponse extends Data.TaggedError("UnexpectedResponse")<{
|
|
33
|
+
readonly metadata: Metadata;
|
|
34
|
+
}> {}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* A selected body decoder failed, or draining an unmatched body failed.
|
|
38
|
+
*
|
|
39
|
+
* @remarks
|
|
40
|
+
* `cause` retains the underlying typed error; it may contain schema input or response content.
|
|
41
|
+
* Selection does not fall through to a different case after this failure.
|
|
42
|
+
*/
|
|
43
|
+
export class DecodeError<out E> extends Data.TaggedError("DecodeError")<{
|
|
44
|
+
readonly metadata: Metadata;
|
|
45
|
+
readonly cause: E;
|
|
46
|
+
}> {}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* An ordered contract that chooses a body decoder from response metadata.
|
|
50
|
+
*
|
|
51
|
+
* @remarks
|
|
52
|
+
* Build cases with {@link status} or {@link when}, then combine them with {@link orElse}.
|
|
53
|
+
* A declared status, including 4xx or 5xx, returns the decoder's value if decoding succeeds.
|
|
54
|
+
*/
|
|
55
|
+
export interface Response<out A, out E = never, out R = never>
|
|
56
|
+
extends Pipeable.Pipeable {
|
|
57
|
+
readonly select: (metadata: Metadata) => Option.Option<Body.Decoder<A, E, R>>;
|
|
58
|
+
/** Media types contributed to the automatic `Accept` header, in declaration order. */
|
|
59
|
+
readonly accepts: ReadonlyArray<string>;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Read metadata from an Effect HTTP response without consuming its body.
|
|
64
|
+
*/
|
|
65
|
+
export const metadata = (
|
|
66
|
+
response: HttpClientResponse.HttpClientResponse,
|
|
67
|
+
): Metadata => ({
|
|
68
|
+
status: response.status,
|
|
69
|
+
headers: response.headers,
|
|
70
|
+
cookies: response.cookies,
|
|
71
|
+
headerLines: Transport.responseHeaderLines(response),
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
const make = <A, E, R>(
|
|
75
|
+
select: Response<A, E, R>["select"],
|
|
76
|
+
accepts: ReadonlyArray<string>,
|
|
77
|
+
): Response<A, E, R> => ({
|
|
78
|
+
...Pipeable.Prototype,
|
|
79
|
+
select,
|
|
80
|
+
accepts,
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Select a body decoder when a predicate accepts the response metadata.
|
|
85
|
+
*
|
|
86
|
+
* @remarks
|
|
87
|
+
* The predicate runs before body decoding. It cannot select by payload contents; use one schema
|
|
88
|
+
* with alternatives for payloads sharing the same metadata.
|
|
89
|
+
*/
|
|
90
|
+
export const when = <A, E, R>(
|
|
91
|
+
predicate: (metadata: Metadata) => boolean,
|
|
92
|
+
body: Body.Decoder<A, E, R>,
|
|
93
|
+
): Response<A, E, R> =>
|
|
94
|
+
make(
|
|
95
|
+
(info) => (predicate(info) ? Option.some(body) : Option.none()),
|
|
96
|
+
body.mediaType === undefined ? [] : [body.mediaType],
|
|
97
|
+
);
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Select a body decoder for one exact HTTP status.
|
|
101
|
+
*
|
|
102
|
+
* @example
|
|
103
|
+
* ```ts
|
|
104
|
+
* import { Body, Response } from "viell-effect-schema-http";
|
|
105
|
+
* const health = Response.status(200, Body.text);
|
|
106
|
+
* ```
|
|
107
|
+
*/
|
|
108
|
+
export const status = <A, E, R>(
|
|
109
|
+
code: number,
|
|
110
|
+
body: Body.Decoder<A, E, R>,
|
|
111
|
+
): Response<A, E, R> => when((info) => info.status === code, body);
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Use another response contract when this one has no matching case.
|
|
115
|
+
*
|
|
116
|
+
* @remarks
|
|
117
|
+
* Declaration order is priority. This is selection fallback, not decoding-error recovery.
|
|
118
|
+
* A selected decoder's failure never tries the fallback.
|
|
119
|
+
*/
|
|
120
|
+
export const orElse =
|
|
121
|
+
<B, E2, R2>(that: Response<B, E2, R2>) =>
|
|
122
|
+
<A, E, R>(self: Response<A, E, R>): Response<A | B, E | E2, R | R2> =>
|
|
123
|
+
make<A | B, E | E2, R | R2>(
|
|
124
|
+
(info) => Option.orElse(self.select(info), () => that.select(info)),
|
|
125
|
+
Array.from(new Set([...self.accepts, ...that.accepts])),
|
|
126
|
+
);
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* A decoded value labelled with its case name and response metadata.
|
|
130
|
+
*
|
|
131
|
+
* @remarks
|
|
132
|
+
* Checking `_tag` narrows the value type when several tagged outcomes form a union.
|
|
133
|
+
*/
|
|
134
|
+
export interface Tagged<Tag extends string, A> {
|
|
135
|
+
readonly _tag: Tag;
|
|
136
|
+
readonly value: A;
|
|
137
|
+
readonly metadata: Metadata;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* Wrap a body decoder's result with a case name, value and response metadata.
|
|
142
|
+
*
|
|
143
|
+
* @example
|
|
144
|
+
* ```ts
|
|
145
|
+
* import { Body, Response } from "viell-effect-schema-http";
|
|
146
|
+
* const response = Response.status(200, Response.tag("Found", Body.text)).pipe(
|
|
147
|
+
* Response.orElse(Response.status(404, Response.tag("Missing", Body.empty))),
|
|
148
|
+
* );
|
|
149
|
+
* ```
|
|
150
|
+
*
|
|
151
|
+
* @remarks
|
|
152
|
+
* This returns a body decoder, ready to use inside {@link status} or {@link when}.
|
|
153
|
+
* Tagging a response does not turn it into an Effect failure.
|
|
154
|
+
*/
|
|
155
|
+
export const tag = <const Tag extends string, A, E, R>(
|
|
156
|
+
name: Tag,
|
|
157
|
+
body: Body.Decoder<A, E, R>,
|
|
158
|
+
): Body.Decoder<Tagged<Tag, A>, E, R> =>
|
|
159
|
+
Body.decoder(
|
|
160
|
+
(response) =>
|
|
161
|
+
Effect.map(body.decode(response), (value) => ({
|
|
162
|
+
_tag: name,
|
|
163
|
+
value,
|
|
164
|
+
metadata: metadata(response),
|
|
165
|
+
})),
|
|
166
|
+
body.mediaType,
|
|
167
|
+
);
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Choose a response case and decode the native response's body.
|
|
171
|
+
*
|
|
172
|
+
* @remarks
|
|
173
|
+
* An unmatched body is drained before `UnexpectedResponse`; a failed drain or decoder becomes
|
|
174
|
+
* `DecodeError`. Direct callers own the response's resource lifetime. `Operation.make` manages
|
|
175
|
+
* that lifetime and any configured attempt timeout for ordinary execution.
|
|
176
|
+
*/
|
|
177
|
+
export const decode = <A, E, R>(
|
|
178
|
+
self: Response<A, E, R>,
|
|
179
|
+
response: HttpClientResponse.HttpClientResponse,
|
|
180
|
+
): Effect.Effect<
|
|
181
|
+
A,
|
|
182
|
+
UnexpectedResponse | DecodeError<E | HttpClientError.HttpClientError>,
|
|
183
|
+
R
|
|
184
|
+
> =>
|
|
185
|
+
Effect.suspend(() => {
|
|
186
|
+
const info = metadata(response);
|
|
187
|
+
const selected = self.select(info);
|
|
188
|
+
const decodeError = (cause: E | HttpClientError.HttpClientError) =>
|
|
189
|
+
new DecodeError({ metadata: info, cause });
|
|
190
|
+
if (Option.isNone(selected)) {
|
|
191
|
+
return Body.empty
|
|
192
|
+
.decode(response)
|
|
193
|
+
.pipe(
|
|
194
|
+
Effect.mapError(decodeError),
|
|
195
|
+
Effect.andThen(
|
|
196
|
+
Effect.fail(new UnexpectedResponse({ metadata: info })),
|
|
197
|
+
),
|
|
198
|
+
);
|
|
199
|
+
}
|
|
200
|
+
return Effect.mapError(selected.value.decode(response), decodeError);
|
|
201
|
+
});
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
import { Context, Effect, Option } from "effect";
|
|
2
|
+
import {
|
|
3
|
+
Headers,
|
|
4
|
+
type HttpClientRequest,
|
|
5
|
+
type HttpClientResponse,
|
|
6
|
+
} from "effect/http";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Ordered header name/value pairs, preserving supplied spelling and repeated lines.
|
|
10
|
+
*
|
|
11
|
+
* @remarks
|
|
12
|
+
* These are declarations or provider observations. Sending separate lines requires provider
|
|
13
|
+
* support; normalized headers cannot reveal their original line boundaries.
|
|
14
|
+
*/
|
|
15
|
+
export type Lines = ReadonlyArray<readonly [string, string]>;
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* The header collection shapes accepted by Effect's `Headers.Input`.
|
|
19
|
+
*
|
|
20
|
+
* @remarks
|
|
21
|
+
* Use {@link entries} to expand them without combining repeated values.
|
|
22
|
+
*/
|
|
23
|
+
export type HeaderInput = Headers.Input;
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Expand a supported header collection into ordered name/value lines.
|
|
27
|
+
*
|
|
28
|
+
* @remarks
|
|
29
|
+
* Record array values become repeated lines; `undefined` fields are omitted.
|
|
30
|
+
*/
|
|
31
|
+
export const entries = (input: HeaderInput): Lines =>
|
|
32
|
+
Symbol.iterator in input
|
|
33
|
+
? Array.from(input, ([name, value]) => [name, value] as const)
|
|
34
|
+
: Object.entries(input).flatMap(
|
|
35
|
+
([name, value]): Array<readonly [string, string]> =>
|
|
36
|
+
value === undefined
|
|
37
|
+
? []
|
|
38
|
+
: typeof value === "string"
|
|
39
|
+
? [[name, value]]
|
|
40
|
+
: value.map((line) => [name, line]),
|
|
41
|
+
);
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Produce Effect's normalized header view from ordered lines.
|
|
45
|
+
*
|
|
46
|
+
* @remarks
|
|
47
|
+
* Names become lowercase and repeated values are joined with `, `. This loses line boundaries;
|
|
48
|
+
* keep the original lines when a provider can send them.
|
|
49
|
+
*/
|
|
50
|
+
export const toHeaders = (lines: Lines): Headers.Headers => {
|
|
51
|
+
const grouped = new Map<string, Array<string>>();
|
|
52
|
+
for (const [name, value] of lines) {
|
|
53
|
+
const key = name.toLowerCase();
|
|
54
|
+
const values = grouped.get(key);
|
|
55
|
+
if (values === undefined) grouped.set(key, [value]);
|
|
56
|
+
else values.push(value);
|
|
57
|
+
}
|
|
58
|
+
return Headers.fromInput(
|
|
59
|
+
Array.from(grouped, ([key, values]) => [key, values.join(", ")] as const),
|
|
60
|
+
);
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Preserve original header lines where native middleware left the normalized value unchanged.
|
|
65
|
+
*
|
|
66
|
+
* @remarks
|
|
67
|
+
* Changed or added native fields replace those fields' original lines. Removed fields disappear.
|
|
68
|
+
* For a provider handling an operation, prefer {@link headerLines} to obtain the original lines
|
|
69
|
+
* from the current Effect context.
|
|
70
|
+
*/
|
|
71
|
+
export const reconcile = (lines: Lines, headers: Headers.Headers): Lines => {
|
|
72
|
+
const original = toHeaders(lines);
|
|
73
|
+
const preserved = new Set(
|
|
74
|
+
Object.keys(original).filter((name) => original[name] === headers[name]),
|
|
75
|
+
);
|
|
76
|
+
return [
|
|
77
|
+
...lines.filter(([name]) => preserved.has(name.toLowerCase())),
|
|
78
|
+
...Object.entries(headers).filter(([name]) => !preserved.has(name)),
|
|
79
|
+
];
|
|
80
|
+
};
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The original request header lines available during an operation's attempt.
|
|
84
|
+
*
|
|
85
|
+
* @remarks
|
|
86
|
+
* Operations supply this context reference to the client. It defaults to an empty array outside
|
|
87
|
+
* that context. Providers should read it through {@link headerLines}.
|
|
88
|
+
*/
|
|
89
|
+
export const HeaderLines: Context.Reference<Lines> = Context.Reference<Lines>(
|
|
90
|
+
"viell-effect-schema-http/Transport/HeaderLines",
|
|
91
|
+
{ defaultValue: () => [] },
|
|
92
|
+
);
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Get the header lines a custom provider should send after native middleware edits.
|
|
96
|
+
*
|
|
97
|
+
* @remarks
|
|
98
|
+
* Reads {@link HeaderLines} and reconciles it with the native request. Fetch does not gain
|
|
99
|
+
* separate-line support from this helper.
|
|
100
|
+
*/
|
|
101
|
+
export const headerLines = (
|
|
102
|
+
request: HttpClientRequest.HttpClientRequest,
|
|
103
|
+
): Effect.Effect<Lines> =>
|
|
104
|
+
Effect.map(HeaderLines, (lines) => reconcile(lines, request.headers));
|
|
105
|
+
|
|
106
|
+
const ResponseHeaderLines = Symbol.for(
|
|
107
|
+
"viell-effect-schema-http/Transport/ResponseHeaderLines",
|
|
108
|
+
);
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Attach the header lines a custom provider observed to its native response.
|
|
112
|
+
*
|
|
113
|
+
* @remarks
|
|
114
|
+
* Copies the supplied lines, mutates the response with that snapshot, and returns the same
|
|
115
|
+
* response object. Normalized headers and received bytes are unchanged. Attach only information
|
|
116
|
+
* the provider actually observed; do not split normalized values to guess original lines.
|
|
117
|
+
*/
|
|
118
|
+
export const withResponseHeaders = (
|
|
119
|
+
response: HttpClientResponse.HttpClientResponse,
|
|
120
|
+
lines: Lines,
|
|
121
|
+
): HttpClientResponse.HttpClientResponse => {
|
|
122
|
+
Object.defineProperty(response, ResponseHeaderLines, {
|
|
123
|
+
value: lines.map(([name, value]) => [name, value] as const),
|
|
124
|
+
configurable: true,
|
|
125
|
+
});
|
|
126
|
+
return response;
|
|
127
|
+
};
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Read the original response lines attached by a supporting provider.
|
|
131
|
+
*
|
|
132
|
+
* @remarks
|
|
133
|
+
* Returns `None` when none were supplied, not when the response necessarily has no headers.
|
|
134
|
+
* Normalized header values are never split to reconstruct lines.
|
|
135
|
+
*/
|
|
136
|
+
export const responseHeaderLines = (
|
|
137
|
+
response: HttpClientResponse.HttpClientResponse,
|
|
138
|
+
): Option.Option<Lines> =>
|
|
139
|
+
Option.fromUndefinedOr(
|
|
140
|
+
(response as { readonly [ResponseHeaderLines]?: Lines })[
|
|
141
|
+
ResponseHeaderLines
|
|
142
|
+
],
|
|
143
|
+
);
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import { Context, Layer } from "effect";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Ordered decoded query entries, including repeated names.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* `null` is a bare key (`?preview`); `""` is an empty value (`?preview=`).
|
|
8
|
+
*/
|
|
9
|
+
export type Query = ReadonlyArray<readonly [string, string | null]>;
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* A scalar query value before conversion to URL text.
|
|
13
|
+
*
|
|
14
|
+
* @remarks
|
|
15
|
+
* `null` keeps a bare key and `undefined` omits an entry. Other values are converted to strings.
|
|
16
|
+
*/
|
|
17
|
+
export type QueryValue = string | number | bigint | boolean | null | undefined;
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* A record or iterable of query pairs accepted as a schema's encoded output.
|
|
21
|
+
*
|
|
22
|
+
* @remarks
|
|
23
|
+
* Array values expand to repeated entries. Use ordered pairs to control order across names.
|
|
24
|
+
*/
|
|
25
|
+
export type QueryInput =
|
|
26
|
+
| Readonly<Record<string, QueryValue | ReadonlyArray<QueryValue>>>
|
|
27
|
+
| Iterable<readonly [string, QueryValue | ReadonlyArray<QueryValue>]>;
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Expand query input into ordered decoded entries, preserving repetitions.
|
|
31
|
+
*
|
|
32
|
+
* @example
|
|
33
|
+
* ```ts
|
|
34
|
+
* import { UrlEncoding } from "viell-effect-schema-http";
|
|
35
|
+
* const entries = UrlEncoding.queryEntries({ tag: ["one", "two"], preview: null });
|
|
36
|
+
* // [["tag", "one"], ["tag", "two"], ["preview", null]]
|
|
37
|
+
* ```
|
|
38
|
+
*
|
|
39
|
+
* @remarks
|
|
40
|
+
* Omits `undefined`, keeps `null`, and converts other scalar values to strings. URL escaping
|
|
41
|
+
* happens later through the query renderer.
|
|
42
|
+
*/
|
|
43
|
+
export const queryEntries = (input: QueryInput): Query => {
|
|
44
|
+
const entries =
|
|
45
|
+
Symbol.iterator in input ? Array.from(input) : Object.entries(input);
|
|
46
|
+
return entries.flatMap(
|
|
47
|
+
([key, value]): Array<readonly [string, string | null]> =>
|
|
48
|
+
(Array.isArray(value) ? value : [value]).flatMap((entry: QueryValue) =>
|
|
49
|
+
entry === undefined
|
|
50
|
+
? []
|
|
51
|
+
: [[key, entry === null ? null : String(entry)] as const],
|
|
52
|
+
),
|
|
53
|
+
);
|
|
54
|
+
};
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Functions that render path values, query entries and the final request URL.
|
|
58
|
+
*
|
|
59
|
+
* @remarks
|
|
60
|
+
* The default policy is available without setup. Provide {@link layer} to replace it for a
|
|
61
|
+
* service that needs another URL representation.
|
|
62
|
+
*/
|
|
63
|
+
export interface Service {
|
|
64
|
+
/** Escape one dynamic path value; the renderer supplies separators between values. */
|
|
65
|
+
readonly path: (value: string) => string;
|
|
66
|
+
/** Render ordered query entries without a leading `?`. */
|
|
67
|
+
readonly query: (entries: Query) => string;
|
|
68
|
+
/** Combine the base origin/prefix and the request's rendered path or absolute URL. */
|
|
69
|
+
readonly join: (base: string, path: string) => string;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const absolute = /^[a-z][a-z\d+.-]*:\/\//i;
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Percent-encode path values and query fields, and join a base URL with a request path.
|
|
76
|
+
*
|
|
77
|
+
* @remarks
|
|
78
|
+
* Uses `encodeURIComponent`, preserving bare keys, empty values, repetition and order.
|
|
79
|
+
* An absolute request URL bypasses the base. Otherwise joining removes one boundary slash from
|
|
80
|
+
* each side before inserting `/`. Dot segments and empty path values are not normalized here;
|
|
81
|
+
* the HTTP provider's later URL processing may normalize them.
|
|
82
|
+
*/
|
|
83
|
+
export const defaults: Service = {
|
|
84
|
+
path: encodeURIComponent,
|
|
85
|
+
query: (entries) =>
|
|
86
|
+
entries
|
|
87
|
+
.map(([key, value]) =>
|
|
88
|
+
value === null
|
|
89
|
+
? encodeURIComponent(key)
|
|
90
|
+
: `${encodeURIComponent(key)}=${encodeURIComponent(value)}`,
|
|
91
|
+
)
|
|
92
|
+
.join("&"),
|
|
93
|
+
join: (base, path) => {
|
|
94
|
+
if (base === "" || absolute.test(path)) return path;
|
|
95
|
+
if (path === "") return base;
|
|
96
|
+
return `${base.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
|
|
97
|
+
},
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The Effect context reference used to render request URLs.
|
|
102
|
+
*
|
|
103
|
+
* @remarks
|
|
104
|
+
* Uses {@link defaults} unless replaced. The value is read during request preparation.
|
|
105
|
+
*/
|
|
106
|
+
export const UrlEncoding: Context.Reference<Service> =
|
|
107
|
+
Context.Reference<Service>("viell-effect-schema-http/UrlEncoding", {
|
|
108
|
+
defaultValue: () => defaults,
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Supply an alternative URL-rendering policy through an Effect layer.
|
|
113
|
+
*
|
|
114
|
+
* @remarks
|
|
115
|
+
* Provide it around request compilation or operation execution. Renderer exceptions become
|
|
116
|
+
* `Request.InvalidRequest`. Provider URL processing still applies after library rendering.
|
|
117
|
+
*/
|
|
118
|
+
export const layer = (service: Service): Layer.Layer<never> =>
|
|
119
|
+
Layer.succeed(UrlEncoding, service);
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/** A field value, or a computation that stays data until materialization. `undefined` omits the field. */
|
|
2
|
+
export type Value<A = string> = A | (() => A | undefined);
|
|
3
|
+
|
|
4
|
+
/** Ordered declarations. Entries preserve repetition and their order across names. */
|
|
5
|
+
export type Fields<A = string> = ReadonlyArray<readonly [string, Value<A>]>;
|
|
6
|
+
|
|
7
|
+
/** Replace a name at its first position and drop its later entries, or append a new entry. */
|
|
8
|
+
export const set = <A>(
|
|
9
|
+
fields: Fields<A>,
|
|
10
|
+
name: string,
|
|
11
|
+
value: Value<A>,
|
|
12
|
+
): Fields<A> => {
|
|
13
|
+
const position = fields.findIndex(([key]) => key === name);
|
|
14
|
+
if (position < 0) return [...fields, [name, value]];
|
|
15
|
+
return fields.flatMap((entry, index): Array<readonly [string, Value<A>]> =>
|
|
16
|
+
index === position ? [[name, value]] : entry[0] === name ? [] : [entry],
|
|
17
|
+
);
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
export const append = <A>(
|
|
21
|
+
fields: Fields<A>,
|
|
22
|
+
name: string,
|
|
23
|
+
value: Value<A>,
|
|
24
|
+
): Fields<A> => [...fields, [name, value]];
|
|
25
|
+
|
|
26
|
+
/** Without a value, remove the whole name. With one, remove matching static entries without evaluating computations. */
|
|
27
|
+
export const remove = <A>(
|
|
28
|
+
fields: Fields<A>,
|
|
29
|
+
name: string,
|
|
30
|
+
value?: A,
|
|
31
|
+
): Fields<A> =>
|
|
32
|
+
fields.filter(
|
|
33
|
+
([key, entry]) => key !== name || (value !== undefined && entry !== value),
|
|
34
|
+
);
|
|
35
|
+
|
|
36
|
+
/** Evaluate every surviving computation once, omitting `undefined` results. */
|
|
37
|
+
export const resolve = <A extends string | null>(
|
|
38
|
+
fields: Fields<A>,
|
|
39
|
+
): Array<readonly [string, A]> => {
|
|
40
|
+
const output: Array<readonly [string, A]> = [];
|
|
41
|
+
for (const [name, value] of fields) {
|
|
42
|
+
const resolved = typeof value === "function" ? value() : value;
|
|
43
|
+
if (resolved !== undefined) output.push([name, resolved]);
|
|
44
|
+
}
|
|
45
|
+
return output;
|
|
46
|
+
};
|
package/src/main.ts
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Encode and decode finite HTTP bodies, with optional schema validation.
|
|
3
|
+
*/
|
|
4
|
+
export * as Body from "./http/Body.js";
|
|
5
|
+
/**
|
|
6
|
+
* Share or replace work for one scoped user interaction.
|
|
7
|
+
*/
|
|
8
|
+
export * as Interaction from "./concurrency/Interaction.js";
|
|
9
|
+
/**
|
|
10
|
+
* Pair request and response contracts and execute them through an Effect HTTP client.
|
|
11
|
+
*/
|
|
12
|
+
export * as Operation from "./http/Operation.js";
|
|
13
|
+
/**
|
|
14
|
+
* Configure operation retries, delays and attempt timeouts.
|
|
15
|
+
*/
|
|
16
|
+
export * as Policy from "./http/Policy.js";
|
|
17
|
+
/**
|
|
18
|
+
* Describe outgoing requests and bind typed application input.
|
|
19
|
+
*/
|
|
20
|
+
export * as Request from "./http/Request.js";
|
|
21
|
+
/**
|
|
22
|
+
* Select and decode accepted responses using status and metadata.
|
|
23
|
+
*/
|
|
24
|
+
export * as Response from "./http/Response.js";
|
|
25
|
+
/**
|
|
26
|
+
* Preserve individual header lines through a supporting HTTP provider.
|
|
27
|
+
*/
|
|
28
|
+
export * as Transport from "./http/Transport.js";
|
|
29
|
+
/**
|
|
30
|
+
* Customize path escaping, query rendering and base-URL joining.
|
|
31
|
+
*/
|
|
32
|
+
export * as UrlEncoding from "./http/UrlEncoding.js";
|