@monarcode/effetch 0.0.0-stage → 0.1.0-alpha.0

package/dist/plugins/logger.js

@@ -0,0 +1,67 @@
+import { errorUrl } from "../internal/url.js";
+import { plugin } from "../Plugin.js";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
+import * as Exit from "effect/Exit";
+
+//#region src/plugins/logger.ts
+/**
+* Logs one entry per call with Effect's logger: the method, the URL, the
+* status and how long the response took, e.g.
+* `GET https://api.example.com/todos 200 (35ms)`, or `… failed (35ms)`
+* with the failure's cause.
+*
+* The same values are log annotations (`method`, `url`, `status`,
+* `durationMs`). The URL has no query string, and no headers are logged,
+* so tokens and cookies stay out of logs. The duration is measured with
+* Effect's `Clock` until the response headers arrive, in whole
+* milliseconds.
+*
+* Put it first in the plugin list, so it sees the whole call, retries
+* included.
+*
+* @example
+* ```ts
+* import * as Fetch from "@monarcode/effetch";
+* import { logger } from "@monarcode/effetch/plugins";
+*
+* const make = Fetch.make({
+*   baseUrl: "https://api.example.com",
+*   plugins: [logger({ level: "Info" })],
+* });
+* ```
+*
+* @since 0.1.0
+*/
+const logger = (options = {}) => {
+	const log = options.level === "Info" ? Effect.logInfo : Effect.logDebug;
+	return plugin({
+		name: "logger",
+		wrap: (client) => HttpClient.transform(client, (response, request) => Effect.gen(function* () {
+			const start = yield* Clock.currentTimeMillis;
+			const exit = yield* Effect.exit(response);
+			const durationMs = Math.round((yield* Clock.currentTimeMillis) - start);
+			const method = request.method;
+			const url = errorUrl(request.url);
+			if (Exit.isSuccess(exit)) {
+				const { status } = exit.value;
+				yield* Effect.annotateLogs(log(`${method} ${url} ${status} (${durationMs}ms)`), {
+					method,
+					url,
+					status,
+					durationMs
+				});
+			} else if (!Cause.hasInterruptsOnly(exit.cause)) yield* Effect.annotateLogs(log(`${method} ${url} failed (${durationMs}ms)`, exit.cause), {
+				method,
+				url,
+				durationMs
+			});
+			return yield* exit;
+		}))
+	});
+};
+
+//#endregion
+export { logger };

package/dist/plugins/retry.d.ts

@@ -0,0 +1,94 @@
+import * as HttpMethod from "effect/http/HttpMethod";
+import * as Schedule from "effect/Schedule";
+
+import { Plugin } from "../Plugin.js";
+//#region src/plugins/retry.d.ts
+/**
+ * Options for {@link retry}.
+ *
+ * - `times`: how many times to retry, after the first attempt. Defaults to
+ *   `2`. Calls can override it.
+ * - `schedule`: the delays between attempts. Defaults to an exponential
+ *   backoff from 200ms, with jitter. `times` still caps the retries.
+ * - `methods`: the methods that are retried. Defaults to the idempotent
+ *   ones: `GET`, `HEAD`, `OPTIONS`, `PUT` and `DELETE`.
+ * - `statuses`: the response statuses that are retried. Defaults to `408`,
+ *   `429`, `500`, `502`, `503` and `504`.
+ *
+ * @example
+ * ```ts
+ * import * as Schedule from "effect/Schedule";
+ * import type { RetryOptions } from "@monarcode/effetch/plugins";
+ *
+ * const options: RetryOptions = {
+ *   times: 3,
+ *   schedule: Schedule.spaced("1 second"),
+ *   methods: ["GET"],
+ *   statuses: [503],
+ * };
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface RetryOptions {
+	/** How many times to retry after the first attempt. Defaults to `2`. */
+	readonly times?: number | undefined;
+	/** The delays between attempts. Defaults to jittered exponential backoff. */
+	readonly schedule?: Schedule.Schedule<unknown, unknown> | undefined;
+	/** The methods that are retried. Defaults to the idempotent ones. */
+	readonly methods?: ReadonlyArray<HttpMethod.HttpMethod> | undefined;
+	/** The statuses that are retried. Defaults to 408, 429, 500, 502–504. */
+	readonly statuses?: ReadonlyArray<number> | undefined;
+}
+/**
+ * The plugin made by {@link retry}. It adds no errors; calls can override
+ * `times` or skip it.
+ *
+ * @example
+ * ```ts
+ * import { retry, type RetryPlugin } from "@monarcode/effetch/plugins";
+ *
+ * const retryTwice: RetryPlugin = retry();
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type RetryPlugin = Plugin<
+	"retry",
+	never,
+	never,
+	{
+		readonly times: number;
+	}
+>;
+/**
+ * Retries a call that failed with a `NetworkError` or got a retryable
+ * status, for the configured methods only (idempotent ones by default, so
+ * a `POST` is never sent twice).
+ *
+ * When the retries run out, the last response is returned unchanged, so a
+ * `503` still ends as an `HttpError` with that response's body, and the
+ * last `NetworkError` is the call's error. Other failures, a timeout from
+ * the `timeout` plugin included, aren't retried.
+ *
+ * It retries everything after it in the plugin list. Put it before
+ * `timeout` and `bearer`, so each attempt gets its own time limit and a
+ * fresh token.
+ *
+ * @example
+ * ```ts
+ * import * as Fetch from "@monarcode/effetch";
+ * import { retry } from "@monarcode/effetch/plugins";
+ *
+ * const make = Fetch.make({
+ *   baseUrl: "https://api.example.com",
+ *   plugins: [retry({ times: 3 })],
+ * });
+ *
+ * // Per call: api.get("/health", { plugins: { retry: { times: 0 } } })
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const retry: (options?: RetryOptions) => RetryPlugin;
+//#endregion

package/dist/plugins/retry.js

@@ -0,0 +1,74 @@
+import { NetworkError } from "../Errors.js";
+import { plugin } from "../Plugin.js";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as Data from "effect/Data";
+import * as Schedule from "effect/Schedule";
+
+//#region src/plugins/retry.ts
+const idempotentMethods = [
+	"GET",
+	"HEAD",
+	"OPTIONS",
+	"PUT",
+	"DELETE"
+];
+const transientStatuses = [
+	408,
+	429,
+	500,
+	502,
+	503,
+	504
+];
+var RetryableStatus = class extends Data.TaggedError("RetryableStatus") {};
+/**
+* Retries a call that failed with a `NetworkError` or got a retryable
+* status, for the configured methods only (idempotent ones by default, so
+* a `POST` is never sent twice).
+*
+* When the retries run out, the last response is returned unchanged, so a
+* `503` still ends as an `HttpError` with that response's body, and the
+* last `NetworkError` is the call's error. Other failures, a timeout from
+* the `timeout` plugin included, aren't retried.
+*
+* It retries everything after it in the plugin list. Put it before
+* `timeout` and `bearer`, so each attempt gets its own time limit and a
+* fresh token.
+*
+* @example
+* ```ts
+* import * as Fetch from "@monarcode/effetch";
+* import { retry } from "@monarcode/effetch/plugins";
+*
+* const make = Fetch.make({
+*   baseUrl: "https://api.example.com",
+*   plugins: [retry({ times: 3 })],
+* });
+*
+* // Per call: api.get("/health", { plugins: { retry: { times: 0 } } })
+* ```
+*
+* @since 0.1.0
+*/
+const retry = (options = {}) => {
+	const methods = new Set(options.methods ?? idempotentMethods);
+	const statuses = new Set(options.statuses ?? transientStatuses);
+	const schedule = options.schedule ?? Schedule.jittered(Schedule.exponential("200 millis"));
+	return plugin({
+		name: "retry",
+		defaults: { times: options.times ?? 2 },
+		wrap: (client, callOptions) => HttpClient.transform(client, (response, request) => Effect.gen(function* () {
+			const { times } = yield* callOptions;
+			if (!(times > 0) || !methods.has(request.method)) return yield* response;
+			return yield* Effect.flatMap(response, (received) => statuses.has(received.status) ? Effect.fail(new RetryableStatus({ response: received })) : Effect.succeed(received)).pipe(Effect.retry({
+				schedule,
+				times,
+				while: (error) => error instanceof RetryableStatus || error instanceof NetworkError
+			}), Effect.catchTag("RetryableStatus", (error) => Effect.succeed(error.response)));
+		}))
+	});
+};
+
+//#endregion
+export { retry };

package/dist/plugins/timeout.d.ts

@@ -0,0 +1,108 @@
+import * as Duration from "effect/Duration";
+import * as Schema from "effect/Schema";
+
+import { Plugin } from "../Plugin.js";
+//#region src/plugins/timeout.d.ts
+declare const TimeoutError_base: Schema.Class<
+	TimeoutError,
+	Schema.TaggedStruct<
+		"TimeoutError",
+		{
+			readonly method: Schema.String;
+			readonly url: Schema.String;
+			readonly duration: Schema.String;
+		}
+	>,
+	import("effect/Cause").YieldableError
+>;
+/**
+ * No response arrived within the {@link timeout} plugin's duration. The
+ * request was aborted.
+ *
+ * - `url` is the request URL without its query string.
+ * - `duration` is the limit that was exceeded, formatted (`"10s"`).
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import type { TimeoutError } from "@monarcode/effetch/plugins";
+ *
+ * declare const call: Effect.Effect<string, TimeoutError>;
+ *
+ * const program = call.pipe(
+ *   Effect.catchTag("TimeoutError", (error) =>
+ *     Effect.succeed(`Gave up on ${error.url} after ${error.duration}`),
+ *   ),
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class TimeoutError extends TimeoutError_base {
+	/** `"<method> <url>: timed out after <duration>"`. */
+	get message(): string;
+}
+/**
+ * Options for {@link timeout}, and what a call can override:
+ * `plugins: { timeout: { duration } }`.
+ *
+ * @example
+ * ```ts
+ * import type { TimeoutOptions } from "@monarcode/effetch/plugins";
+ *
+ * const options: TimeoutOptions = { duration: "10 seconds" };
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface TimeoutOptions {
+	/** How long to wait for the response headers. */
+	readonly duration: Duration.Input;
+}
+/**
+ * The plugin made by {@link timeout}: it adds {@link TimeoutError}, and
+ * calls can override its `duration` or skip it.
+ *
+ * @example
+ * ```ts
+ * import { timeout, type TimeoutPlugin } from "@monarcode/effetch/plugins";
+ *
+ * const tenSeconds: TimeoutPlugin = timeout({ duration: "10 seconds" });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type TimeoutPlugin = Plugin<
+	"timeout",
+	TimeoutError,
+	never,
+	TimeoutOptions
+>;
+/**
+ * Fails the call with a {@link TimeoutError}, and aborts the request, when
+ * the response headers don't arrive within `duration`.
+ *
+ * It covers the plugins after it in the list, but not reading the body: a
+ * large response that starts in time isn't cut off while it downloads.
+ * Put it after `retry` so each attempt gets the full duration. A timed-out
+ * attempt isn't retried.
+ *
+ * @example
+ * ```ts
+ * import * as Fetch from "@monarcode/effetch";
+ * import { timeout } from "@monarcode/effetch/plugins";
+ *
+ * const make = Fetch.make({
+ *   baseUrl: "https://api.example.com",
+ *   plugins: [timeout({ duration: "10 seconds" })],
+ * });
+ *
+ * // Per call:
+ * // api.get("/export", { plugins: { timeout: { duration: "2 minutes" } } })
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const timeout: (options: TimeoutOptions) => TimeoutPlugin;
+//#endregion
+export {};

package/dist/plugins/timeout.js

@@ -0,0 +1,84 @@
+import { errorUrl } from "../internal/url.js";
+import { plugin } from "../Plugin.js";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as Schema from "effect/Schema";
+import * as Duration from "effect/Duration";
+
+//#region src/plugins/timeout.ts
+/**
+* No response arrived within the {@link timeout} plugin's duration. The
+* request was aborted.
+*
+* - `url` is the request URL without its query string.
+* - `duration` is the limit that was exceeded, formatted (`"10s"`).
+*
+* @example
+* ```ts
+* import * as Effect from "effect/Effect";
+* import type { TimeoutError } from "@monarcode/effetch/plugins";
+*
+* declare const call: Effect.Effect<string, TimeoutError>;
+*
+* const program = call.pipe(
+*   Effect.catchTag("TimeoutError", (error) =>
+*     Effect.succeed(`Gave up on ${error.url} after ${error.duration}`),
+*   ),
+* );
+* ```
+*
+* @since 0.1.0
+*/
+var TimeoutError = class extends Schema.TaggedError()("TimeoutError", {
+	method: Schema.String,
+	url: Schema.String,
+	duration: Schema.String
+}) {
+	/** `"<method> <url>: timed out after <duration>"`. */
+	get message() {
+		return `${this.method} ${this.url}: timed out after ${this.duration}`;
+	}
+};
+/**
+* Fails the call with a {@link TimeoutError}, and aborts the request, when
+* the response headers don't arrive within `duration`.
+*
+* It covers the plugins after it in the list, but not reading the body: a
+* large response that starts in time isn't cut off while it downloads.
+* Put it after `retry` so each attempt gets the full duration. A timed-out
+* attempt isn't retried.
+*
+* @example
+* ```ts
+* import * as Fetch from "@monarcode/effetch";
+* import { timeout } from "@monarcode/effetch/plugins";
+*
+* const make = Fetch.make({
+*   baseUrl: "https://api.example.com",
+*   plugins: [timeout({ duration: "10 seconds" })],
+* });
+*
+* // Per call:
+* // api.get("/export", { plugins: { timeout: { duration: "2 minutes" } } })
+* ```
+*
+* @since 0.1.0
+*/
+const timeout = (options) => plugin({
+	name: "timeout",
+	defaults: { duration: options.duration },
+	wrap: (client, callOptions) => HttpClient.transform(client, (response, request) => Effect.gen(function* () {
+		const { duration } = yield* callOptions;
+		return yield* Effect.timeoutOrElse(response, {
+			duration,
+			orElse: () => Effect.fail(new TimeoutError({
+				method: request.method,
+				url: errorUrl(request.url),
+				duration: Duration.format(Duration.fromInputUnsafe(duration))
+			}))
+		});
+	}))
+});
+
+//#endregion
+export { TimeoutError, timeout };

package/package.json

@@ -1,6 +1,91 @@
 {
-  "name": "@monarcode/effetch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@monarcode/effetch",
+	"version": "0.1.0-alpha.0",
+	"description": "Typed, schema-driven HTTP calls on Effect v4's HttpClient: path params, object queries, decoded responses and plugins",
+	"keywords": [
+		"effect",
+		"effect-ts",
+		"fetch",
+		"http",
+		"http-client",
+		"react-native",
+		"schema"
+	],
+	"homepage": "https://github.com/monarcode/effetch#readme",
+	"bugs": {
+		"url": "https://github.com/monarcode/effetch/issues"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/monarcode/effetch.git"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./plugins": {
+			"types": "./dist/plugins/index.d.ts",
+			"default": "./dist/plugins/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"scripts": {
+		"prepare": "husky",
+		"lint": "oxlint .",
+		"lint:fix": "oxlint --fix .",
+		"lint:effect": "effect-language-service diagnostics --project tsconfig.json --format text",
+		"format": "oxfmt --write .",
+		"format:check": "oxfmt --check .",
+		"build": "tsdown",
+		"dev": "tsdown --watch",
+		"typecheck": "tsc --noEmit",
+		"check:docs": "node scripts/check-docs.mjs",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"check:package": "publint --strict && attw --pack . --profile esm-only",
+		"smoke": "bash scripts/smoke.sh",
+		"check": "pnpm run lint && pnpm run format:check && pnpm run typecheck && pnpm run check:docs && pnpm run lint:effect && pnpm test && pnpm run build && pnpm run check:package && pnpm run smoke",
+		"prepublishOnly": "pnpm run check"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "0.18.5",
+		"@effect/language-service": "0.87.4",
+		"@effect/vitest": "4.0.2",
+		"@types/node": "26.6.5",
+		"effect": "4.0.2",
+		"husky": "9.1.7",
+		"oxfmt": "0.72.0",
+		"oxlint": "1.87.0",
+		"publint": "0.3.25",
+		"tsdown": "0.23.1",
+		"typescript": "6.0.3",
+		"vitest": "5.0.3"
+	},
+	"peerDependencies": {
+		"effect": "^4.0.0"
+	},
+	"devEngines": {
+		"runtime": {
+			"name": "node",
+			"version": ">=24",
+			"onFail": "error"
+		}
+	},
+	"packageManager": "pnpm@10.12.1"
+}