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

package/dist/Errors.js

@@ -0,0 +1,151 @@
+import * as Headers from "effect/http/Headers";
+import * as Schema from "effect/Schema";
+
+//#region src/Errors.ts
+/**
+* The request never produced a response: DNS failure, connection refused,
+* CORS rejection, the device is offline, and so on.
+*
+* `cause` is the underlying error from the platform's HTTP client.
+*
+* @example
+* ```ts
+* import * as Effect from "effect/Effect";
+* import * as Fetch from "@monarcode/effetch";
+*
+* declare const call: Effect.Effect<string, Fetch.FetchError>;
+*
+* const program = call.pipe(
+*   Effect.catchTag("NetworkError", (error) =>
+*     Effect.succeed(`Offline? ${error.method} ${error.url}`),
+*   ),
+* );
+* ```
+*
+* @since 0.1.0
+*/
+var NetworkError = class extends Schema.TaggedError()("NetworkError", {
+	method: Schema.String,
+	url: Schema.String,
+	cause: Schema.Unknown
+}) {
+	/** `"<method> <url>: network error"`. */
+	get message() {
+		return `${this.method} ${this.url}: network error`;
+	}
+};
+/**
+* The server answered with a non-2xx status.
+*
+* Only 2xx counts as success, as in `fetch`'s `response.ok`. 3xx is an
+* error too: `fetch` follows redirects itself, so a 3xx only reaches you
+* with `redirect: "manual"` or a conditional request answered with
+* `304 Not Modified`. Catch it by `status` if you expect one.
+*
+* - `url` is the request URL without its query string, so secrets in query
+*   parameters stay out of logs.
+* - `headers` are the response headers. They're Effect `Headers`, so
+*   sensitive ones (`set-cookie`, `authorization`, …) print as
+*   `<redacted>` when the error is logged or serialised.
+* - `text` is always the raw response body (`""` if it couldn't be read).
+* - `body` is the body decoded with the call's (or client's) `error` schema,
+*   or `undefined` if it didn't match. Without an `error` schema, `body` is
+*   the parsed JSON when `text` is valid JSON, else `undefined`. An empty
+*   body is always `undefined`. Reading `body` never fails the call.
+*
+* Use {@link HttpError.With} for the type of an `HttpError` whose `body` was
+* decoded with a known schema.
+*
+* @example
+* ```ts
+* import * as Effect from "effect/Effect";
+* import * as Fetch from "@monarcode/effetch";
+*
+* declare const call: Effect.Effect<
+*   string,
+*   Fetch.HttpError.With<{ readonly code: string }>
+* >;
+*
+* const program = call.pipe(
+*   Effect.catchTag("HttpError", (error) =>
+*     error.status === 404
+*       ? Effect.succeed("not found")
+*       : Effect.fail(error.body?.code ?? `HTTP ${error.status}`),
+*   ),
+* );
+* ```
+*
+* @since 0.1.0
+*/
+var HttpError = class extends Schema.TaggedError()("HttpError", {
+	method: Schema.String,
+	url: Schema.String,
+	status: Schema.Number,
+	headers: Schema.declare(Headers.isHeaders),
+	text: Schema.String,
+	body: Schema.Unknown
+}) {
+	/** `"<method> <url>: HTTP <status>"`. */
+	get message() {
+		return `${this.method} ${this.url}: HTTP ${this.status}`;
+	}
+};
+/**
+* A 2xx response body didn't match the call's `output` schema, wasn't valid
+* JSON, or couldn't be read.
+*
+* `issue` is what went wrong and `message` is a readable summary of it:
+*
+* - the schema issue when the body doesn't match `output`,
+* - the `SyntaxError` when the body isn't valid JSON,
+* - the `HttpClientError` when the body couldn't be read.
+*
+* An empty body (204, HEAD, …) is decoded as JSON `null`, so it only
+* passes schemas that accept nothing, such as `Schema.Void`.
+*
+* `url` is the request URL without its query string.
+*
+* @example
+* ```ts
+* import * as Effect from "effect/Effect";
+* import * as Fetch from "@monarcode/effetch";
+*
+* declare const call: Effect.Effect<string, Fetch.FetchError>;
+*
+* const program = call.pipe(
+*   Effect.catchTag("DecodeError", (error) =>
+*     Effect.succeed(`Unexpected response from ${error.url}: ${error.message}`),
+*   ),
+* );
+* ```
+*
+* @since 0.1.0
+*/
+var DecodeError = class extends Schema.TaggedError()("DecodeError", {
+	method: Schema.String,
+	url: Schema.String,
+	status: Schema.Number,
+	issue: Schema.Unknown,
+	message: Schema.String
+}) {};
+/**
+* Returns `true` if `u` is a {@link NetworkError}, {@link HttpError} or
+* {@link DecodeError}.
+*
+* @example
+* ```ts
+* import * as Fetch from "@monarcode/effetch";
+*
+* const report = (error: unknown) => {
+*   if (Fetch.isFetchError(error)) {
+*     console.error(error._tag, error.url);
+*   }
+* };
+* ```
+*
+* @since 0.1.0
+*/
+const isFetchError = (u) => u instanceof NetworkError || u instanceof HttpError || u instanceof DecodeError;
+
+//#endregion
+export { DecodeError, HttpError, NetworkError, isFetchError };

package/dist/Options.d.ts

@@ -0,0 +1,462 @@
+import * as Effect from "effect/Effect";
+import * as Headers from "effect/http/Headers";
+import * as HttpClientResponse from "effect/http/HttpClientResponse";
+import * as HttpMethod from "effect/http/HttpMethod";
+import * as UrlParams from "effect/http/UrlParams";
+import * as Schema from "effect/Schema";
+
+import { DecodeError, HttpError, NetworkError } from "./Errors.js";
+import { PathParamNames, PathParamValue, PathParams } from "./Path.js";
+import { Plugin } from "./Plugin.js";
+//#region src/Options.d.ts
+/**
+ * A single query value. effetch drops `null` and `undefined` (Effect's own
+ * `UrlParams` would send `null` as the string `"null"`); other values are
+ * converted with `String()`.
+ *
+ * @example
+ * ```ts
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const page: Fetch.QueryValue = 2;
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type QueryValue = UrlParams.Coercible;
+/**
+ * The `query` option: an object whose entries become URL query parameters.
+ * Arrays repeat the key (`tags=a&tags=b`); `null` and `undefined` entries
+ * and array items are dropped.
+ *
+ * @example
+ * ```ts
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const query: Fetch.QueryInput = {
+ *   page: 1,
+ *   tags: ["a", "b"],
+ *   search: undefined, // dropped
+ * };
+ * // → ?page=1&tags=a&tags=b
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type QueryInput = {
+	readonly [key: string]: QueryValue | ReadonlyArray<QueryValue>;
+};
+/**
+ * Any Effect schema accepted by the `output`, `error` and `input` options.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const Todo: Fetch.AnySchema = Schema.Struct({ id: Schema.Number });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type AnySchema = Schema.Constraint;
+/**
+ * The `params` option for path `P`: required (with exactly the path's
+ * parameter names) when the path has `:params`, forbidden otherwise.
+ *
+ * When `P` is plain `string` the names can't be known, so `params` is an
+ * optional record.
+ *
+ * @example
+ * ```ts
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const withParams: Fetch.ParamsOption<"/todos/:id"> = { params: { id: 1 } };
+ * const without: Fetch.ParamsOption<"/todos"> = {};
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type ParamsOption<P extends string> = string extends P
+	? {
+			readonly params?:
+				| {
+						readonly [name: string]: PathParamValue;
+				  }
+				| undefined;
+		}
+	: [PathParamNames<P>] extends [never]
+		? {
+				readonly params?: undefined;
+			}
+		: {
+				readonly params: PathParams<P>;
+			};
+/**
+ * Options shared by every method.
+ *
+ * - `O`: the `output` schema, or `undefined` for the raw response.
+ * - `EB`: the `error` schema for non-2xx bodies.
+ * - `Ps`: the client's plugins, for the `plugins` override map.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const Todo = Schema.Struct({ id: Schema.Number });
+ *
+ * const options: Fetch.BaseOptions<typeof Todo, Schema.Unknown, []> = {
+ *   query: { expand: "owner" },
+ *   headers: { "x-trace": "1" },
+ *   output: Todo,
+ * };
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface BaseOptions<
+	O extends AnySchema | undefined,
+	EB extends AnySchema,
+	Ps extends ReadonlyArray<Plugin.Any>,
+> {
+	/** Query parameters. Arrays repeat the key; `null`/`undefined` are dropped. */
+	readonly query?: QueryInput | undefined;
+	/** Headers for this call, merged over the client's headers. */
+	readonly headers?: Headers.Input | undefined;
+	/**
+	 * Decodes the 2xx JSON body with this schema. Without it, the call
+	 * succeeds with the raw `HttpClientResponse`.
+	 *
+	 * With an `output`, the request carries `Accept: application/json`,
+	 * unless an `accept` header is set on the call or the client.
+	 *
+	 * An empty body (204, HEAD, …) is decoded as JSON `null`: use
+	 * `Schema.Void` for endpoints that return nothing. Non-2xx responses,
+	 * 3xx included, fail with an `HttpError` before this runs.
+	 */
+	readonly output?: O;
+	/** Decodes non-2xx bodies into `HttpError.body`. Overrides the client's. */
+	readonly error?: EB | undefined;
+	/**
+	 * Per-request plugin overrides, by plugin name: `false` skips the
+	 * plugin's hooks and `wrap` for this call, and a partial of its options
+	 * is merged over its `defaults`.
+	 */
+	readonly plugins?: Plugin.Overrides<Ps> | undefined;
+}
+/**
+ * The `body` and `input` options of methods that send a body.
+ *
+ * With an `input` schema, `body` is typed as the schema's type and encoded
+ * with it before being sent as JSON. Without one (`I` is `Schema.Unknown`),
+ * `body` is sent according to its runtime type: `HttpBody`, strings,
+ * `ArrayBuffer` and typed arrays, `Blob`/`File`, `FormData` and
+ * `URLSearchParams` as-is, anything else as JSON.
+ *
+ * A body that doesn't match `input`, or can't be serialised as JSON, is a
+ * defect (the call dies), not a typed failure.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const NewTodo = Schema.Struct({ title: Schema.String });
+ *
+ * const options: Fetch.BodyOptions<typeof NewTodo> = {
+ *   input: NewTodo,
+ *   body: { title: "Write docs" },
+ * };
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface BodyOptions<I extends AnySchema> {
+	/** Encodes `body` with this schema, then sends it as JSON. */
+	readonly input?: I | undefined;
+	/** The request body. Typed by `input` when given. */
+	readonly body?: I["Type"] | undefined;
+}
+/**
+ * Options of methods that don't send a body: `get`, `head`, `options`.
+ *
+ * @example
+ * ```ts
+ * import type * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const options: Fetch.NoBodyRequestOptions<
+ *   "/todos/:id", undefined, Schema.Unknown, []
+ * > = { params: { id: 1 } };
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type NoBodyRequestOptions<
+	P extends string,
+	O extends AnySchema | undefined,
+	EB extends AnySchema,
+	Ps extends ReadonlyArray<Plugin.Any>,
+> = ParamsOption<P> &
+	BaseOptions<O, EB, Ps> & {
+		readonly body?: undefined;
+		readonly input?: undefined;
+	};
+/**
+ * Options of methods that send a body: `post`, `put`, `patch`, `del` and
+ * `request`.
+ *
+ * @example
+ * ```ts
+ * import type * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const options: Fetch.RequestOptions<
+ *   "/todos/:id", undefined, Schema.Unknown, Schema.Unknown, []
+ * > = { params: { id: 1 }, body: { done: true } };
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type RequestOptions<
+	P extends string,
+	O extends AnySchema | undefined,
+	EB extends AnySchema,
+	I extends AnySchema,
+	Ps extends ReadonlyArray<Plugin.Any>,
+> = ParamsOption<P> & BaseOptions<O, EB, Ps> & BodyOptions<I>;
+/**
+ * The rest arguments after the path: the options object `T` is required
+ * when path `P` has parameters, optional otherwise.
+ *
+ * @example
+ * ```ts
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * type WithParams = Fetch.Args<"/todos/:id", { params: { id: number } }>;
+ * //   ^? [options: { params: { id: number } }]
+ * type WithoutParams = Fetch.Args<"/todos", {}>;
+ * //   ^? [options?: {}]
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type Args<P extends string, T> = [PathParamNames<P>] extends [never]
+	? [options?: T]
+	: [options: T];
+/**
+ * What a call succeeds with: the `output` schema's type, or the raw
+ * `HttpClientResponse` without one. A conditional `output` gives the union.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * type Todo = Fetch.Success<Schema.Struct<{ id: Schema.Number }>>;
+ * //   ^? { readonly id: number }
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type Success<O extends AnySchema | undefined> = O extends AnySchema
+	? O["Type"]
+	: HttpClientResponse.HttpClientResponse;
+/**
+ * What a call can fail with: `NetworkError`, `HttpError` (with `body`
+ * typed by the `error` schema), `DecodeError` when there's an `output`
+ * schema, and the plugins' errors.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * type E = Fetch.CallError<
+ *   Schema.Struct<{ id: Schema.Number }>,
+ *   Schema.Struct<{ code: Schema.String }>,
+ *   []
+ * >;
+ * //   ^? NetworkError | HttpError.With<{ readonly code: string }> | DecodeError
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type CallError<
+	O extends AnySchema | undefined,
+	EB extends AnySchema,
+	Ps extends ReadonlyArray<Plugin.Any>,
+> =
+	| NetworkError
+	| HttpError.With<EB["Type"]>
+	| (O extends AnySchema ? DecodeError : never)
+	| Plugin.Errors<Ps>;
+/**
+ * The services a call requires: those needed to decode `output` and
+ * `error` and to encode `input`.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * type R = Fetch.CallServices<
+ *   Schema.Struct<{ id: Schema.Number }>,
+ *   Schema.Unknown,
+ *   Schema.Unknown
+ * >;
+ * //   ^? never
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type CallServices<
+	O extends AnySchema | undefined,
+	EB extends AnySchema,
+	I extends AnySchema,
+> =
+	| (O extends AnySchema ? O["DecodingServices"] : never)
+	| EB["DecodingServices"]
+	| I["EncodingServices"];
+/**
+ * The Effect a call returns: it succeeds with {@link Success}, fails with
+ * {@link CallError} and requires {@link CallServices}.
+ *
+ * - `O`: the `output` schema, or `undefined` for the raw response.
+ * - `EB`: the `error` schema for non-2xx bodies.
+ * - `I`: the `input` schema (`Schema.Unknown` when the call has none).
+ * - `Ps`: the client's plugins.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * type Call = Fetch.CallEffect<
+ *   Schema.Struct<{ id: Schema.Number }>,
+ *   Schema.Unknown,
+ *   Schema.Unknown,
+ *   []
+ * >;
+ * //   ^? Effect<{ readonly id: number }, NetworkError | HttpError.With<unknown> | DecodeError, never>
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type CallEffect<
+	O extends AnySchema | undefined,
+	EB extends AnySchema,
+	I extends AnySchema,
+	Ps extends ReadonlyArray<Plugin.Any>,
+> = Effect.Effect<Success<O>, CallError<O, EB, Ps>, CallServices<O, EB, I>>;
+/**
+ * The signature of `get`, `head` and `options`: no `body` or `input`.
+ *
+ * - `Ps`: the client's plugins.
+ * - `DefaultEB`: the client's `error` schema, used when a call has none.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * declare const get: Fetch.NoBodyMethod<[], Schema.Unknown>;
+ *
+ * const Todo = Schema.Struct({ id: Schema.Number });
+ * const todo = get("/todos/:id", { params: { id: 1 }, output: Todo });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface NoBodyMethod<
+	Ps extends ReadonlyArray<Plugin.Any>,
+	DefaultEB extends AnySchema,
+> {
+	<
+		P extends string,
+		O extends AnySchema | undefined = undefined,
+		EB extends AnySchema = DefaultEB,
+	>(
+		path: P,
+		...args: Args<P, NoBodyRequestOptions<P, O, EB, Ps>>
+	): CallEffect<O, EB, Schema.Unknown, Ps>;
+}
+/**
+ * The signature of `post`, `put`, `patch` and `del`: `body` allowed,
+ * typed by `input` when given.
+ *
+ * - `Ps`: the client's plugins.
+ * - `DefaultEB`: the client's `error` schema, used when a call has none.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * declare const patch: Fetch.BodyMethod<[], Schema.Unknown>;
+ *
+ * const Todo = Schema.Struct({ id: Schema.Number, done: Schema.Boolean });
+ * const updated = patch("/todos/:id", {
+ *   params: { id: 1 },
+ *   body: { done: true },
+ *   output: Todo,
+ * });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface BodyMethod<
+	Ps extends ReadonlyArray<Plugin.Any>,
+	DefaultEB extends AnySchema,
+> {
+	<
+		P extends string,
+		O extends AnySchema | undefined = undefined,
+		EB extends AnySchema = DefaultEB,
+		I extends AnySchema = Schema.Unknown,
+	>(
+		path: P,
+		...args: Args<P, RequestOptions<P, O, EB, I, Ps>>
+	): CallEffect<O, EB, I, Ps>;
+}
+/**
+ * The signature of `request`: any HTTP method, `body` allowed, typed by
+ * `input` when given.
+ *
+ * - `Ps`: the client's plugins.
+ * - `DefaultEB`: the client's `error` schema, used when a call has none.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * declare const request: Fetch.RequestMethod<[], Schema.Unknown>;
+ *
+ * const Todo = Schema.Struct({ id: Schema.Number, done: Schema.Boolean });
+ * const updated = request("PATCH", "/todos/:id", {
+ *   params: { id: 1 },
+ *   body: { done: true },
+ *   output: Todo,
+ * });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export interface RequestMethod<
+	Ps extends ReadonlyArray<Plugin.Any>,
+	DefaultEB extends AnySchema,
+> {
+	<
+		P extends string,
+		O extends AnySchema | undefined = undefined,
+		EB extends AnySchema = DefaultEB,
+		I extends AnySchema = Schema.Unknown,
+	>(
+		method: HttpMethod.HttpMethod,
+		path: P,
+		...args: Args<P, RequestOptions<P, O, EB, I, Ps>>
+	): CallEffect<O, EB, I, Ps>;
+}
+//#endregion

package/dist/Path.d.ts

@@ -0,0 +1,72 @@
+//#region src/Path.d.ts
+/**
+ * The parameter name in one path segment `S` (`":id"` gives `"id"`), or
+ * `never`.
+ */
+type SegmentParam<S extends string> = S extends `:${infer N}`
+	? N extends ""
+		? never
+		: N
+	: never;
+/**
+ * The names of the path parameters in `P`, as a union of string literals.
+ *
+ * A parameter is a **whole path segment** that starts with `:`. Segments are
+ * split on `/`, so `/files/:name.json` has one parameter called `name.json`,
+ * and `https://host:3000/users/:id` has one parameter called `id` (`host:3000`
+ * doesn't start with `:`). A lone `:` is not a parameter.
+ *
+ * Each segment is checked on its own, so template literal paths keep their
+ * parameters: in `` `/orgs/${string}/users/:id` `` the parameter is `id`.
+ *
+ * @example
+ * ```ts
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * type Names = Fetch.PathParamNames<"/users/:id/posts/:postId">;
+ * //   ^? "id" | "postId"
+ *
+ * type None = Fetch.PathParamNames<"/users">;
+ * //   ^? never
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type PathParamNames<P extends string> =
+	P extends `${infer Head}/${infer Tail}`
+		? SegmentParam<Head> | PathParamNames<Tail>
+		: SegmentParam<P>;
+/**
+ * A value accepted for a path parameter. It's converted with `String()` and
+ * then `encodeURIComponent`.
+ *
+ * @example
+ * ```ts
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const id: Fetch.PathParamValue = 42;
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type PathParamValue = string | number;
+/**
+ * The `params` object for path `P`: one required key per parameter name.
+ *
+ * @example
+ * ```ts
+ * import type * as Fetch from "@monarcode/effetch";
+ *
+ * const params: Fetch.PathParams<"/users/:id/posts/:postId"> = {
+ *   id: 1,
+ *   postId: "intro",
+ * };
+ * ```
+ *
+ * @since 0.1.0
+ */
+export type PathParams<P extends string> = {
+	readonly [K in PathParamNames<P>]: PathParamValue;
+};
+//#endregion
+export {};