@shivaedev/http 0.6.1 → 0.7.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/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.0 - 2026-11-05
4
+
5
+ ### Added
6
+
7
+ - Add `makeReadClient` for outside JSON APIs with a request/body timeout, bounded response decoding, a capacity-bounded success-only TTL cache, source-labelled typed failures, and query-redacted request logs and tracing.
8
+ - Add `optionalField` to decode malformed outside fields as absent keys while preserving valid values.
9
+
3
10
  ## 0.6.1 - 2026-11-04
4
11
 
5
12
  ### Changed
package/README.md CHANGED
@@ -33,6 +33,32 @@ Everything here wraps a native `HttpClient`, `HttpClientResponse` or `HttpServer
33
33
 
34
34
  ### Calling outside APIs
35
35
 
36
+ For repeated JSON reads from an outside API, create one `makeReadClient` from `readClient.ts` per source and payload schema. It reads the native `HttpClient` from the Effect environment. Keep the returned client in the source's service so its cache survives between calls:
37
+
38
+ ```ts
39
+ import { Effect, Schema } from "effect";
40
+ import { makeReadClient } from "@shivaedev/http/readClient.ts";
41
+ import { optionalField } from "@shivaedev/http/optionalField.ts";
42
+
43
+ const makeFoodSource = Effect.gen(function* () {
44
+ const client = yield* makeReadClient({
45
+ source: "foods",
46
+ schema: Schema.Struct({ name: Schema.String, energy: optionalField(Schema.Number) }),
47
+ timeout: "5 seconds",
48
+ bodyLimit: 256 * 1024,
49
+ capacity: 100,
50
+ timeToLive: "5 minutes",
51
+ });
52
+ return { search: (query: string) => client.get(`https://api.example/foods?q=${encodeURIComponent(query)}`) };
53
+ });
54
+ ```
55
+
56
+ `get(url)` checks the status with `filterStatus` and decodes through `readBoundedJson`. The timeout covers the request and body read, including decoding. The cache is bounded by `capacity` entries, keys by the complete URL, evicts the least recently read entry, and keeps only successful decoded values for `timeToLive`. A failed read is fetched again on the next call.
57
+
58
+ Failures are `ReadClientError` from `readClient.ts`, with the configured `source` and a `reason`: `timeout`, `body-too-large`, `status`, `decode`, `transport` or `invalid-limit`. A status failure also carries `status`. They retain no raw request, response body or decoding cause. Each cache miss emits an Effect debug log with the source, GET method and URL origin/path, dropping userinfo, query and fragment. Native HTTP spans redact query values too.
59
+
60
+ `optionalField(schema)` from `optionalField.ts` makes a Struct field optional and treats a field's decoding failure as an absent key. Valid values still decode normally. Use it for unreliable outside fields; required fields elsewhere in the payload still fail decoding.
61
+
36
62
  `filterStatus(client)` passes 2xx responses through and fails other statuses with Schema tagged errors from `errors.ts`: `RemoteUnauthorized` (401), `RemoteNotFound` (404), `RemoteGone` (410), `RemoteRateLimited` (429, or 503 carrying `Retry-After`) and `RemoteHttpError` for other statuses. Errors carry the method, the URL without userinfo, query string or fragment and the status, without headers or body. `RemoteRateLimited.retryAfter` is an optional UTC `DateTime`: delay-seconds use Effect's clock, and HTTP dates name the instant directly. Missing or invalid values leave it undefined; `parseRetryAfter(header, now)` exposes the same parsing.
37
63
 
38
64
  `checkStatus(response)` from `checkStatus.ts` applies the same status mapping to an existing native response. `filterStatus` delegates to it. Use `isRemoteStatusError(error)` from `errors.ts` to recognize any of these typed status failures.
@@ -0,0 +1,3 @@
1
+ import { Schema } from "effect";
2
+ export declare function optionalField<TSchema extends Schema.Constraint>(schema: TSchema): Schema.middlewareDecoding<Schema.optionalKey<TSchema>, TSchema["DecodingServices"]>;
3
+ //# sourceMappingURL=optionalField.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"optionalField.d.ts","sourceRoot":"","sources":["../src/optionalField.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhD,wBAAgB,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,uFAE/E"}
@@ -0,0 +1,5 @@
1
+ import { Effect, Option, Schema } from "effect";
2
+ export function optionalField(schema) {
3
+ return Schema.catchDecoding(() => Effect.succeed(Option.none()))(Schema.optionalKey(schema));
4
+ }
5
+ //# sourceMappingURL=optionalField.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"optionalField.js","sourceRoot":"","sources":["../src/optionalField.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhD,MAAM,UAAU,aAAa,CAAoC,MAAe;IAC/E,OAAO,MAAM,CAAC,aAAa,CAA8B,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;AAC3H,CAAC"}
@@ -0,0 +1,22 @@
1
+ import { type Duration, Effect, Schema } from "effect";
2
+ import { HttpClient } from "effect/http";
3
+ declare const ReadClientError_base: Schema.Class<ReadClientError, Schema.TaggedStruct<"ReadClientError", {
4
+ readonly reason: Schema.Literals<readonly ["timeout", "body-too-large", "status", "decode", "transport", "invalid-limit"]>;
5
+ readonly source: Schema.String;
6
+ readonly status: Schema.optionalKey<Schema.Number>;
7
+ }>, import("effect/Cause").YieldableError>;
8
+ export declare class ReadClientError extends ReadClientError_base {
9
+ }
10
+ export interface ReadClientOptions<TSchema extends Schema.Constraint> {
11
+ readonly bodyLimit: number;
12
+ readonly capacity: number;
13
+ readonly schema: TSchema;
14
+ readonly source: string;
15
+ readonly timeout: Duration.Input;
16
+ readonly timeToLive: Duration.Input;
17
+ }
18
+ export declare const makeReadClient: <TSchema extends Schema.Constraint>(options: ReadClientOptions<TSchema>) => Effect.Effect<{
19
+ get: (url: string) => Effect.Effect<TSchema["Type"], ReadClientError, never>;
20
+ }, never, HttpClient.HttpClient | Exclude<TSchema["DecodingServices"], never>>;
21
+ export {};
22
+ //# sourceMappingURL=readClient.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"readClient.d.ts","sourceRoot":"","sources":["../src/readClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,QAAQ,EAAE,MAAM,EAAQ,MAAM,EAAE,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAE,UAAU,EAAa,MAAM,aAAa,CAAC;;;;;;AAKpD,qBAAa,eAAgB,SAAQ,oBAInC;CAAG;AAEL,MAAM,WAAW,iBAAiB,CAAC,OAAO,SAAS,MAAM,CAAC,UAAU;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC;CACpC;AAED,eAAO,MAAM,cAAc,GAAgC,OAAO,SAAS,MAAM,CAAC,UAAU;eAoCvE,MAAM;8EACzB,CAAC"}
@@ -0,0 +1,46 @@
1
+ import { Cache, Effect, Exit, Schema } from "effect";
2
+ import { HttpClient, UrlParams } from "effect/http";
3
+ import { readBoundedJson } from "./body.js";
4
+ import { InvalidBodyLimit, isRemoteStatusError, ResponseBodyTooLarge } from "./errors.js";
5
+ import { filterStatus } from "./filterStatus.js";
6
+ export class ReadClientError extends Schema.TaggedError()("ReadClientError", {
7
+ reason: Schema.Literals(["timeout", "body-too-large", "status", "decode", "transport", "invalid-limit"]),
8
+ source: Schema.String,
9
+ status: Schema.optionalKey(Schema.Number),
10
+ }) {
11
+ }
12
+ export const makeReadClient = Effect.fnUntraced(function* (options) {
13
+ const client = filterStatus(yield* HttpClient.HttpClient);
14
+ function lookup(url) {
15
+ return Effect.gen(function* () {
16
+ const parsed = URL.parse(url);
17
+ yield* Effect.logDebug("Outside API request").pipe(Effect.annotateLogs({ method: "GET", source: options.source, url: parsed === null ? "<invalid>" : `${parsed.origin}${parsed.pathname}` }));
18
+ const response = yield* client.get(url);
19
+ return yield* readBoundedJson(response, options.bodyLimit, options.schema);
20
+ }).pipe(Effect.mapError((error) => {
21
+ if (isRemoteStatusError(error)) {
22
+ return new ReadClientError({ reason: "status", source: options.source, status: error.status });
23
+ }
24
+ let reason = "transport";
25
+ if (error instanceof ResponseBodyTooLarge) {
26
+ reason = "body-too-large";
27
+ }
28
+ else if (error instanceof InvalidBodyLimit) {
29
+ reason = "invalid-limit";
30
+ }
31
+ else if (error instanceof Schema.SchemaError) {
32
+ reason = "decode";
33
+ }
34
+ return new ReadClientError({ reason, source: options.source });
35
+ }), Effect.timeoutOrElse({
36
+ duration: options.timeout,
37
+ orElse: () => Effect.fail(new ReadClientError({ reason: "timeout", source: options.source })),
38
+ }), Effect.provideService(UrlParams.CurrentRedactedNames, [/.*/u]));
39
+ }
40
+ const cache = yield* Cache.makeWith(lookup, {
41
+ capacity: options.capacity,
42
+ timeToLive: (exit) => (Exit.isSuccess(exit) ? options.timeToLive : 0),
43
+ });
44
+ return { get: (url) => Cache.get(cache, url) };
45
+ });
46
+ //# sourceMappingURL=readClient.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"readClient.js","sourceRoot":"","sources":["../src/readClient.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shivaedev/http",
3
- "version": "0.6.1",
3
+ "version": "0.7.0",
4
4
  "description": "Bounded HTTP bodies, status failures and paginated clients over Effect HTTP",
5
5
  "keywords": [
6
6
  "effect"
@@ -46,8 +46,8 @@
46
46
  ],
47
47
  "devDependencies": {
48
48
  "@effect/platform-node": "4.0.7",
49
- "@shivaedev/quality": "0.61.1",
50
- "@shivaedev/test-story": "0.39.1",
49
+ "@shivaedev/quality": "0.63.0",
50
+ "@shivaedev/test-story": "0.40.0",
51
51
  "@types/node": "24.19.2",
52
52
  "effect": "4.0.7",
53
53
  "typescript": "7.0.2",
@@ -0,0 +1,5 @@
1
+ import { Effect, Option, Schema } from "effect";
2
+
3
+ export function optionalField<TSchema extends Schema.Constraint>(schema: TSchema) {
4
+ return Schema.catchDecoding<Schema.optionalKey<TSchema>>(() => Effect.succeed(Option.none()))(Schema.optionalKey(schema));
5
+ }
@@ -0,0 +1,59 @@
1
+ import { Cache, type Duration, Effect, Exit, Schema } from "effect";
2
+ import { HttpClient, UrlParams } from "effect/http";
3
+ import { readBoundedJson } from "./body.ts";
4
+ import { InvalidBodyLimit, isRemoteStatusError, ResponseBodyTooLarge } from "./errors.ts";
5
+ import { filterStatus } from "./filterStatus.ts";
6
+
7
+ export class ReadClientError extends Schema.TaggedError<ReadClientError>()("ReadClientError", {
8
+ reason: Schema.Literals(["timeout", "body-too-large", "status", "decode", "transport", "invalid-limit"]),
9
+ source: Schema.String,
10
+ status: Schema.optionalKey(Schema.Number),
11
+ }) {}
12
+
13
+ export interface ReadClientOptions<TSchema extends Schema.Constraint> {
14
+ readonly bodyLimit: number;
15
+ readonly capacity: number;
16
+ readonly schema: TSchema;
17
+ readonly source: string;
18
+ readonly timeout: Duration.Input;
19
+ readonly timeToLive: Duration.Input;
20
+ }
21
+
22
+ export const makeReadClient = Effect.fnUntraced(function* <TSchema extends Schema.Constraint>(options: ReadClientOptions<TSchema>) {
23
+ const client = filterStatus(yield* HttpClient.HttpClient);
24
+ function lookup(url: string) {
25
+ return Effect.gen(function* () {
26
+ const parsed = URL.parse(url);
27
+ yield* Effect.logDebug("Outside API request").pipe(
28
+ Effect.annotateLogs({ method: "GET", source: options.source, url: parsed === null ? "<invalid>" : `${parsed.origin}${parsed.pathname}` }),
29
+ );
30
+ const response = yield* client.get(url);
31
+ return yield* readBoundedJson(response, options.bodyLimit, options.schema);
32
+ }).pipe(
33
+ Effect.mapError((error) => {
34
+ if (isRemoteStatusError(error)) {
35
+ return new ReadClientError({ reason: "status", source: options.source, status: error.status });
36
+ }
37
+ let reason: ReadClientError["reason"] = "transport";
38
+ if (error instanceof ResponseBodyTooLarge) {
39
+ reason = "body-too-large";
40
+ } else if (error instanceof InvalidBodyLimit) {
41
+ reason = "invalid-limit";
42
+ } else if (error instanceof Schema.SchemaError) {
43
+ reason = "decode";
44
+ }
45
+ return new ReadClientError({ reason, source: options.source });
46
+ }),
47
+ Effect.timeoutOrElse({
48
+ duration: options.timeout,
49
+ orElse: () => Effect.fail(new ReadClientError({ reason: "timeout", source: options.source })),
50
+ }),
51
+ Effect.provideService(UrlParams.CurrentRedactedNames, [/.*/u]),
52
+ );
53
+ }
54
+ const cache = yield* Cache.makeWith(lookup, {
55
+ capacity: options.capacity,
56
+ timeToLive: (exit) => (Exit.isSuccess(exit) ? options.timeToLive : 0),
57
+ });
58
+ return { get: (url: string) => Cache.get(cache, url) };
59
+ });