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

package/dist/internal/path.js

@@ -0,0 +1,23 @@
+import { hasOwn } from "./object.js";
+
+//#region src/internal/path.ts
+/**
+* Replaces each `:name` segment of `path` with the URI-encoded value of
+* `params[name]`. Splits on `/` exactly like `PathParamNames`, so the
+* runtime and the types agree.
+*
+* Only own properties of `params` count, so `:constructor` or `:toString`
+* never pick up inherited members.
+*
+* Throws if a parameter is missing. Callers run it inside an Effect, where
+* the throw becomes a defect.
+*/
+const interpolatePath = (path, params) => path.split("/").map((segment) => {
+	if (segment.length < 2 || !segment.startsWith(":")) return segment;
+	const name = segment.slice(1);
+	if (params === void 0 || !hasOwn(params, name)) throw new Error(`Missing path parameter "${name}" for path "${path}"`);
+	return encodeURIComponent(String(params[name]));
+}).join("/");
+
+//#endregion
+export { interpolatePath };

package/dist/internal/pipeline.js

@@ -0,0 +1,29 @@
+import { NetworkError } from "../Errors.js";
+import { errorUrl, joinUrl } from "./url.js";
+import * as Effect from "effect/Effect";
+import * as Headers from "effect/http/Headers";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+
+//#region src/internal/pipeline.ts
+const mapClientError = (error) => {
+	const { reason } = error;
+	switch (reason._tag) {
+		case "TransportError": return Effect.fail(new NetworkError({
+			method: reason.request.method,
+			url: errorUrl(reason.request.url),
+			cause: reason.cause
+		}));
+		case "StatusCodeError": return Effect.succeed(reason.response);
+		default: return Effect.die(error);
+	}
+};
+const mapClientErrors = (client) => HttpClient.transformResponse(client, Effect.catch(mapClientError));
+const bodyHeaders = ["content-type", "content-length"];
+const makeApplyDefaults = (baseUrl, headers) => {
+	const defaults = Headers.removeMany(headers, bodyHeaders);
+	return (request) => HttpClientRequest.setHeaders(HttpClientRequest.setUrl(request, joinUrl(baseUrl, request.url)), Headers.merge(defaults, request.headers));
+};
+
+//#endregion
+export { makeApplyDefaults, mapClientErrors };

package/dist/internal/plugins.js

@@ -0,0 +1,92 @@
+import { hasOwn } from "./object.js";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+
+//#region src/internal/plugins.ts
+const noOverrides = {};
+/**
+* The `plugins` option of the call being run. Provided around each call;
+* anything else (such as `client.httpClient`) sees no overrides.
+*/
+const CurrentOverrides = Context.Reference("@monarcode/effetch/CurrentOverrides", { defaultValue: () => noOverrides });
+const provideOverrides = (overrides) => Effect.provideService(CurrentOverrides, overrides ?? noOverrides);
+const overrideOf = (overrides, name) => hasOwn(overrides, name) ? overrides[name] : void 0;
+const isRecord = (u) => typeof u === "object" && u !== null && !Array.isArray(u);
+/**
+* `{ ...defaults, ...override }`, leaving out the override's `undefined`
+* values so they keep their default. Only object options can be
+* overridden; anything else keeps `defaults`.
+*/
+const mergeOptions = (defaults, override) => isRecord(defaults) && isRecord(override) ? {
+	...defaults,
+	...Object.fromEntries(Object.entries(override).filter(([, value]) => value !== void 0))
+} : defaults;
+const fromExecute = (execute) => HttpClient.makeWith(Effect.flatMap(execute), Effect.succeed);
+const executeOf = (client) => (request) => client.execute(request);
+/**
+* One plugin around `inner`: its `wrap` encloses its `onRequest` and
+* `onResponse`, and a call that sets the plugin to `false` goes straight to
+* `inner`.
+*
+* Each layer is a plain `execute` function rather than an `HttpClient`
+* split into Effect's `preprocess` and `postprocess`, so a `wrap` that
+* re-runs its client (a retry) re-runs only what is inside it.
+*/
+const layer = (plugin, inner) => {
+	const { onRequest, onResponse, wrap } = plugin;
+	if (onRequest === void 0 && onResponse === void 0 && wrap === void 0) return inner;
+	const options = Effect.map(Effect.service(CurrentOverrides), (overrides) => mergeOptions(plugin.defaults, overrideOf(overrides, plugin.name)));
+	const hooked = onRequest === void 0 && onResponse === void 0 ? inner : (request) => Effect.gen(function* () {
+		const current = yield* options;
+		const sent = onRequest === void 0 ? request : yield* onRequest(request, {
+			request,
+			options: current
+		});
+		const response = yield* inner(sent);
+		return onResponse === void 0 ? response : yield* onResponse(response, {
+			request: sent,
+			options: current
+		});
+	});
+	const wrapped = wrap === void 0 ? hooked : executeOf(wrap(fromExecute(hooked), options));
+	return (request) => Effect.flatMap(Effect.service(CurrentOverrides), (overrides) => overrideOf(overrides, plugin.name) === false ? inner(request) : wrapped(request));
+};
+/**
+* Runs `effect` with the services captured by `make` filling in whatever the
+* calling fiber doesn't have. The caller's own services and references win,
+* as with Effect's `HttpClient.layerMergedContext`.
+*/
+const withContext = (context) => (effect) => Effect.updateContext(effect, (input) => Context.merge(context, input));
+/**
+* The plugins around `client`, `plugins[0]` outermost, run with the captured
+* `context`.
+*/
+const applyPlugins = (client, plugins, context) => {
+	const execute = plugins.reduceRight((inner, plugin) => layer(plugin, inner), executeOf(client));
+	return fromExecute((request) => withContext(context)(execute(request)));
+};
+/**
+* Runs the `onError` hooks, in array order, for a call that failed or died
+* after `request` was built. Interruption isn't a failure, so it runs none.
+* Plugins skipped by the call are left out. A hook that dies is logged at
+* Debug level and never changes the call's outcome.
+*/
+const runErrorHooks = (plugins, context, request, cause) => {
+	if (!Cause.hasFails(cause) && !Cause.hasDies(cause)) return Effect.void;
+	const error = Cause.squash(cause);
+	const hooks = Effect.flatMap(Effect.service(CurrentOverrides), (overrides) => Effect.forEach(plugins, (plugin) => {
+		const override = overrideOf(overrides, plugin.name);
+		if (plugin.onError === void 0 || override === false) return Effect.void;
+		const options = mergeOptions(plugin.defaults, override);
+		return Effect.catchCause(plugin.onError(error, {
+			request,
+			options
+		}), (failure) => Effect.logDebug(`effetch: the onError hook of plugin "${plugin.name}" failed`, failure));
+	}, { discard: true }));
+	return withContext(context)(hooks);
+};
+
+//#endregion
+export { CurrentOverrides, applyPlugins, mergeOptions, provideOverrides, runErrorHooks, withContext };

package/dist/internal/query.js

@@ -0,0 +1,22 @@
+import * as UrlParams from "effect/http/UrlParams";
+
+//#region src/internal/query.ts
+/**
+* Converts the `query` option into `UrlParams`, in key order. Arrays repeat
+* the key; `null` and `undefined` values and array items are dropped.
+*
+* Deliberately not `UrlParams.fromInput(query)`: that sends a `null` value
+* as the string `"null"` and keeps `null` array items.
+*/
+const toUrlParams = (query) => {
+	const entries = [];
+	if (query !== void 0) {
+		for (const [key, value] of Object.entries(query)) if (Array.isArray(value)) {
+			for (const item of value) if (item !== null && item !== void 0) entries.push([key, String(item)]);
+		} else if (value !== null && value !== void 0) entries.push([key, String(value)]);
+	}
+	return UrlParams.make(entries);
+};
+
+//#endregion
+export { toUrlParams };

package/dist/internal/request.js

@@ -0,0 +1,33 @@
+import { provideOverrides, runErrorHooks } from "./plugins.js";
+import { encodeBody } from "./body.js";
+import { interpolatePath } from "./path.js";
+import { toUrlParams } from "./query.js";
+import { checkStatus, decodeOutput } from "./response.js";
+import * as Effect from "effect/Effect";
+import * as Headers from "effect/http/Headers";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+
+//#region src/internal/request.ts
+const buildRequest = (state, method, path, options) => Effect.gen(function* () {
+	if (options.body !== void 0 && (method === "GET" || method === "HEAD")) return yield* Effect.die(/* @__PURE__ */ new Error(`A ${method} request can't have a body`));
+	let request = HttpClientRequest.make(method)(interpolatePath(path, options.params), { urlParams: toUrlParams(options.query) });
+	const body = yield* encodeBody(options.body, options.input);
+	if (body !== void 0) request = HttpClientRequest.setBody(request, body);
+	if (options.headers !== void 0) request = HttpClientRequest.setHeaders(request, options.headers);
+	request = state.applyDefaults(request);
+	if (options.output !== void 0 && !Headers.has(request.headers, "accept")) request = HttpClientRequest.acceptJson(request);
+	return request;
+});
+const execute = (state, request, options) => Effect.gen(function* () {
+	const response = yield* state.chain.execute(request);
+	const checked = yield* checkStatus(response, options.error ?? state.errorSchema);
+	return options.output === void 0 ? checked : yield* decodeOutput(checked, options.output);
+});
+const send = (state, method, path, options) => Effect.gen(function* () {
+	const request = yield* buildRequest(state, method, path, options);
+	return yield* Effect.tapCause(execute(state, request, options), (cause) => runErrorHooks(state.plugins, state.context, request, cause));
+}).pipe(provideOverrides(options.plugins));
+const makeCall = (state) => (method) => (path, options = {}) => send(state, method, path, options);
+
+//#endregion
+export { makeCall };

package/dist/internal/resolve.js

@@ -0,0 +1,23 @@
+import * as Effect from "effect/Effect";
+
+//#region src/internal/resolve.ts
+const isThenable = (u) => typeof u === "object" && u !== null && typeof u.then === "function";
+/**
+* Resolves a bearer token source for `request`, in the calling fiber. The
+* forms are told apart in this order: a string, an Effect (which may also
+* be a function, like a `Context.Service` class), then a function.
+*
+* A function that throws or returns a rejected promise is a defect.
+* Interrupting the Effect stops waiting on a pending promise.
+*/
+const resolveTokenSource = (source, request) => {
+	if (typeof source === "string") return Effect.succeed(source);
+	if (Effect.isEffect(source)) return source;
+	return Effect.suspend(() => {
+		const value = source(request);
+		return isThenable(value) ? Effect.promise(() => value) : Effect.succeed(value);
+	});
+};
+
+//#endregion
+export { resolveTokenSource };

package/dist/internal/response.js

@@ -0,0 +1,73 @@
+import { DecodeError, HttpError } from "../Errors.js";
+import { errorUrl } from "./url.js";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+//#region src/internal/response.ts
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+/**
+* `undefined` for an empty or whitespace-only body, else the parsed JSON.
+* Throws on invalid JSON. `JSON.parse` never returns `undefined`, so an
+* empty body and a JSON `null` stay distinguishable here.
+*/
+const parseBody = (text) => text.trim() === "" ? void 0 : JSON.parse(text);
+const decodeJson = (schema) => Schema.decodeUnknownEffect(Schema.toCodecJson(schema));
+const readErrorBody = (text, schema) => {
+	let json;
+	try {
+		json = parseBody(text);
+	} catch {
+		return Effect.succeed(void 0);
+	}
+	if (json === void 0 || schema === void 0) return Effect.succeed(json);
+	return Effect.orElseSucceed(decodeJson(schema)(json), () => void 0);
+};
+function checkStatus(response, errorSchema) {
+	if (response.status >= 200 && response.status < 300) return Effect.succeed(response);
+	return Effect.gen(function* () {
+		const text = yield* Effect.orElseSucceed(response.text, () => "");
+		const body = yield* readErrorBody(text, errorSchema);
+		return yield* Effect.fail(new HttpError({
+			method: response.request.method,
+			url: errorUrl(response.request.url),
+			status: response.status,
+			headers: response.headers,
+			text,
+			body
+		}));
+	});
+}
+/**
+* Decodes a 2xx response body with `output`.
+*
+* An empty or whitespace-only body (204, 205, HEAD, …) is decoded as JSON
+* `null`, which `Schema.Void`, `Schema.Undefined` and `Schema.NullOr`
+* accept. A JSON `null` body is therefore indistinguishable from an empty
+* one.
+*
+* Fails with a `DecodeError` whose `issue` is:
+*
+* - the `HttpClientError` when the body can't be read,
+* - the `SyntaxError` when it isn't valid JSON,
+* - the schema issue when it doesn't match `output`.
+*/
+const decodeOutput = (response, output) => {
+	const failure = (issue, message) => new DecodeError({
+		method: response.request.method,
+		url: errorUrl(response.request.url),
+		status: response.status,
+		issue,
+		message
+	});
+	return Effect.gen(function* () {
+		const text = yield* Effect.mapError(response.text, (error) => failure(error, `Failed to read the response body: ${messageOf(error.cause ?? error)}`));
+		const json = yield* Effect.try({
+			try: () => parseBody(text),
+			catch: (cause) => failure(cause, `The response body isn't valid JSON: ${messageOf(cause)}`)
+		});
+		return yield* Effect.mapError(decodeJson(output)(json ?? null), (error) => failure(error.issue, json === void 0 ? `The response body is empty, but the output schema requires a value: ${error.message}` : error.message));
+	});
+};
+
+//#endregion
+export { checkStatus, decodeOutput };

package/dist/internal/url.js

@@ -0,0 +1,24 @@
+//#region src/internal/url.ts
+const absoluteUrl = /^https?:\/\//i;
+/**
+* True for `http://` and `https://` URLs only. Protocol-relative (`//host`)
+* and other schemes are treated as paths, so a request can't switch host or
+* protocol by accident.
+*/
+const isAbsoluteUrl = (path) => absoluteUrl.test(path);
+/**
+* Joins `base` and `path` with exactly one `/`. An absolute `path` (see
+* `isAbsoluteUrl`) is returned unchanged, as is any `path` when there's no
+* `base`. Uses string operations, not `new URL()`, for React Native.
+*/
+const joinUrl = (base, path) => base === void 0 || isAbsoluteUrl(path) ? path : base.replace(/\/+$/, "") + "/" + path.replace(/^\/+/, "");
+/**
+* `url` without its query string or fragment, so secrets such as
+* `?api_key=…` never reach error messages or logs.
+*/
+const errorUrl = (url) => url.split(/[?#]/, 1)[0] ?? "";
+/** True if `url` contains a query string or a fragment. */
+const hasQueryOrFragment = (url) => /[?#]/.test(url);
+
+//#endregion
+export { errorUrl, hasQueryOrFragment, isAbsoluteUrl, joinUrl };

package/dist/plugins/bearer.d.ts

@@ -0,0 +1,152 @@
+import * as Effect from "effect/Effect";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+
+import { Plugin } from "../Plugin.js";
+//#region src/plugins/bearer.d.ts
+/**
+ * `T` itself, once known. In {@link BearerPlugin} it stops TypeScript
+ * inferring the token's error and services from where the plugin goes: in
+ * a `plugins` list they would become `any`.
+ */
+type Settled<T> = [T] extends [infer U] ? U : never;
+/**
+ * What a token source gives: the token, or `null`, `undefined` or `""` to
+ * send the request without an `Authorization` header.
+ *
+ * @example
+ * ```ts
+ * import type { TokenValue } from "@monarcode/effetch/plugins";
+ *
+ * const signedOut: TokenValue = undefined;
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type TokenValue = string | null | undefined;
+/**
+ * Where {@link bearer} gets the token, for every request:
+ *
+ * - a string, for a token that never changes;
+ * - a function of the request, returning the token or a promise of it;
+ * - an Effect, whose error and services become the plugin's (and so the
+ *   client's).
+ *
+ * A function that throws, or whose promise rejects, makes the call die
+ * (a defect), so the error type stays clean. To fail with a typed error,
+ * pass an Effect.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import type { TokenSource } from "@monarcode/effetch/plugins";
+ *
+ * declare const store: { getState(): { accessToken?: string } };
+ * declare const readToken: () => Promise<string | null>;
+ *
+ * const fixed: TokenSource = "dev-token";
+ * const sync: TokenSource = () => store.getState().accessToken;
+ * const async: TokenSource = () => readToken();
+ * const fromEffect: TokenSource = Effect.succeed("token");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type TokenSource<E = never, R = never> =
+	| string
+	| ((
+			request: HttpClientRequest.HttpClientRequest,
+	  ) => TokenValue | PromiseLike<TokenValue>)
+	| Effect.Effect<TokenValue, E, R>;
+/**
+ * Options for {@link bearer}.
+ *
+ * - `token`: where the token comes from (see {@link TokenSource}). It's
+ *   resolved for every request, inside that request's fiber, and never
+ *   cached, so a refreshed or cleared token takes effect on the next
+ *   request.
+ * - `scheme`: the word before the token. Defaults to `"Bearer"`.
+ *
+ * @example
+ * ```ts
+ * import type { BearerOptions } from "@monarcode/effetch/plugins";
+ *
+ * const options: BearerOptions = { token: "dev-token", scheme: "Token" };
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface BearerOptions<E = never, R = never> {
+	/** Where the token comes from, resolved for every request. */
+	readonly token: TokenSource<E, R>;
+	/** The word before the token. Defaults to `"Bearer"`. */
+	readonly scheme?: string | undefined;
+}
+/**
+ * The plugin made by {@link bearer}: it fails with the token Effect's `E`
+ * and needs its `R`. Calls can only skip it (`plugins: { bearer: false }`).
+ *
+ * @example
+ * ```ts
+ * import { bearer, type BearerPlugin } from "@monarcode/effetch/plugins";
+ *
+ * const auth: BearerPlugin = bearer({ token: "dev-token" });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type BearerPlugin<E = never, R = never> = Plugin<
+	"bearer",
+	Settled<E>,
+	Settled<R>
+>;
+/**
+ * Sends `Authorization: <scheme> <token>` with every request.
+ *
+ * The header is left out when the token is `null`, `undefined` or `""`,
+ * and a request that already has an `Authorization` header keeps it (the
+ * token isn't resolved then).
+ *
+ * Put it last in the plugin list, so retries ask for the token again.
+ *
+ * @example
+ * ```ts
+ * import * as Context from "effect/Context";
+ * import * as Effect from "effect/Effect";
+ * import * as Fetch from "@monarcode/effetch";
+ * import { bearer } from "@monarcode/effetch/plugins";
+ *
+ * declare const SecureStore: {
+ *   getItemAsync(key: string): Promise<string | null>;
+ * };
+ *
+ * class Session extends Context.Service<
+ *   Session,
+ *   { readonly accessToken: Effect.Effect<string | undefined> }
+ * >()("Session") {}
+ *
+ * const fromStorage = bearer({
+ *   token: () => SecureStore.getItemAsync("access_token"),
+ * });
+ *
+ * const fromSession = bearer({
+ *   token: Effect.gen(function* () {
+ *     const session = yield* Session;
+ *     return yield* session.accessToken;
+ *   }),
+ * });
+ *
+ * const make = Fetch.make({
+ *   baseUrl: "https://api.example.com",
+ *   plugins: [fromSession],
+ * });
+ *
+ * // Per call: api.post("/auth/login", { body, plugins: { bearer: false } })
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const bearer: <E = never, R = never>(
+	options: BearerOptions<E, R>,
+) => BearerPlugin<E, R>;
+//#endregion
+export {};

package/dist/plugins/bearer.js

@@ -0,0 +1,63 @@
+import { plugin } from "../Plugin.js";
+import { resolveTokenSource } from "../internal/resolve.js";
+import * as Effect from "effect/Effect";
+import * as Headers from "effect/http/Headers";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+
+//#region src/plugins/bearer.ts
+/**
+* Sends `Authorization: <scheme> <token>` with every request.
+*
+* The header is left out when the token is `null`, `undefined` or `""`,
+* and a request that already has an `Authorization` header keeps it (the
+* token isn't resolved then).
+*
+* Put it last in the plugin list, so retries ask for the token again.
+*
+* @example
+* ```ts
+* import * as Context from "effect/Context";
+* import * as Effect from "effect/Effect";
+* import * as Fetch from "@monarcode/effetch";
+* import { bearer } from "@monarcode/effetch/plugins";
+*
+* declare const SecureStore: {
+*   getItemAsync(key: string): Promise<string | null>;
+* };
+*
+* class Session extends Context.Service<
+*   Session,
+*   { readonly accessToken: Effect.Effect<string | undefined> }
+* >()("Session") {}
+*
+* const fromStorage = bearer({
+*   token: () => SecureStore.getItemAsync("access_token"),
+* });
+*
+* const fromSession = bearer({
+*   token: Effect.gen(function* () {
+*     const session = yield* Session;
+*     return yield* session.accessToken;
+*   }),
+* });
+*
+* const make = Fetch.make({
+*   baseUrl: "https://api.example.com",
+*   plugins: [fromSession],
+* });
+*
+* // Per call: api.post("/auth/login", { body, plugins: { bearer: false } })
+* ```
+*
+* @since 0.1.0
+*/
+const bearer = (options) => {
+	const scheme = options.scheme ?? "Bearer";
+	return plugin({
+		name: "bearer",
+		onRequest: (request) => Headers.has(request.headers, "authorization") ? Effect.succeed(request) : Effect.map(resolveTokenSource(options.token, request), (token) => token === void 0 || token === null || token === "" ? request : HttpClientRequest.setHeader(request, "authorization", `${scheme} ${token}`))
+	});
+};
+
+//#endregion
+export { bearer };

package/dist/plugins/index.d.ts

@@ -0,0 +1,32 @@
+import {
+	BearerOptions,
+	BearerPlugin,
+	TokenSource,
+	TokenValue,
+	bearer,
+} from "./bearer.js";
+import { LoggerOptions, LoggerPlugin, logger } from "./logger.js";
+import { RetryOptions, RetryPlugin, retry } from "./retry.js";
+import {
+	TimeoutError,
+	TimeoutOptions,
+	TimeoutPlugin,
+	timeout,
+} from "./timeout.js";
+export {
+	type BearerOptions,
+	type BearerPlugin,
+	type LoggerOptions,
+	type LoggerPlugin,
+	type RetryOptions,
+	type RetryPlugin,
+	TimeoutError,
+	type TimeoutOptions,
+	type TimeoutPlugin,
+	type TokenSource,
+	type TokenValue,
+	bearer,
+	logger,
+	retry,
+	timeout,
+};

package/dist/plugins/index.js

@@ -0,0 +1,6 @@
+import { bearer } from "./bearer.js";
+import { logger } from "./logger.js";
+import { retry } from "./retry.js";
+import { TimeoutError, timeout } from "./timeout.js";
+
+export { TimeoutError, bearer, logger, retry, timeout };

package/dist/plugins/logger.d.ts

@@ -0,0 +1,66 @@
+import { Plugin } from "../Plugin.js";
+//#region src/plugins/logger.d.ts
+/**
+ * Options for {@link logger}.
+ *
+ * - `level`: the log level of every entry, `"Debug"` (the default) or
+ *   `"Info"`. Effect's default logger hides Debug entries unless the
+ *   minimum log level allows them.
+ *
+ * @example
+ * ```ts
+ * import type { LoggerOptions } from "@monarcode/effetch/plugins";
+ *
+ * const options: LoggerOptions = { level: "Info" };
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface LoggerOptions {
+	/** The level of every entry. Defaults to `"Debug"`. */
+	readonly level?: "Debug" | "Info" | undefined;
+}
+/**
+ * The plugin made by {@link logger}. Calls can only skip it
+ * (`plugins: { logger: false }`).
+ *
+ * @example
+ * ```ts
+ * import { logger, type LoggerPlugin } from "@monarcode/effetch/plugins";
+ *
+ * const log: LoggerPlugin = logger();
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type LoggerPlugin = Plugin<"logger">;
+/**
+ * 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
+ */
+export declare const logger: (options?: LoggerOptions) => LoggerPlugin;
+//#endregion