@zap-studio/fetch 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @zap-studio/fetch
+
+## 0.1.0
+
+### Minor Changes
+
+- 1644006: Comprehensive description of the initial release features including:
+
+  - Type-safe HTTP requests with Zod validation
+  - Automatic content-type handling
+  - Multiple response type support
+  - Convenient API methods (GET, POST, PUT, PATCH, DELETE)
+  - Flexible error handling
+  - Custom FetchError class
+  - Full TypeScript support

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexandre Trotel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@zap-studio/fetch",
+  "version": "0.1.0",
+  "type": "module",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "jsdom": "latest",
+    "tsdown": "latest",
+    "typescript": "latest",
+    "vitest": "latest",
+    "@zap-studio/typescript-config": "0.0.0",
+    "@zap-studio/vitest-config": "0.0.0",
+    "@zap-studio/tsdown-config": "0.0.0"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./errors": "./dist/errors/index.js",
+    "./types": "./dist/types/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsdown --config tsdown.config.ts",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest --watch"
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,11 @@
+export class FetchError extends Error {
+	constructor(
+		message: string,
+		public status: number,
+		public statusText: string,
+		public response: Response,
+	) {
+		super(message);
+		this.name = "FetchError";
+	}
+}

package/src/index.ts

@@ -0,0 +1,126 @@
+import type { z } from "zod";
+import { FetchError } from "./errors";
+import type { FetchConfig, ResponseType } from "./types";
+import { parseResponse, prepareHeadersAndBody } from "./utils";
+
+/**
+ * Type-safe fetch wrapper with Zod validation
+ *
+ * @example
+ * import { z } from "zod";
+ * import { safeFetch } from "@zap-studio/fetch";
+ *
+ * const UserSchema = z.object({
+ *   id: z.number(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * async function getUser(userId: number) {
+ *   const user = await safeFetch(
+ *     `https://api.example.com/users/${userId}`,
+ *     UserSchema,
+ *     { method: "GET" }
+ *   );
+ *   return user; // user is typed as { id: number; name: string; email: string; }
+ * }
+ */
+export async function safeFetch<
+	TResponse,
+	TBody = unknown,
+	TResponseType extends ResponseType = "json",
+>(
+	resource: string,
+	responseSchema: z.ZodType<TResponse>,
+	config?: FetchConfig<TBody> & {
+		throwOnValidationError?: boolean;
+		responseType?: TResponseType;
+	},
+): Promise<
+	TResponse | z.ZodSafeParseSuccess<TResponse> | z.ZodSafeParseError<TResponse>
+> {
+	const {
+		body,
+		headers,
+		throwOnValidationError = true,
+		responseType = "json" as TResponseType,
+		...rest
+	} = config || {};
+
+	const { body: preparedBody, headers: preparedHeaders } =
+		prepareHeadersAndBody(body, headers);
+
+	const response = await fetch(resource, {
+		...rest,
+		body: preparedBody,
+		headers: preparedHeaders,
+	});
+
+	if (!response.ok) {
+		throw new FetchError(
+			`HTTP ${response.status}: ${response.statusText}`,
+			response.status,
+			response.statusText,
+			response,
+		);
+	}
+
+	const data = await parseResponse(response, responseType);
+
+	return throwOnValidationError
+		? responseSchema.parse(data)
+		: responseSchema.safeParse(data);
+}
+
+/**
+ * Convenience methods for common HTTP verbs
+ *
+ * @example
+ * import { z } from "zod";
+ * import { api } from "@zap-studio/fetch";
+ *
+ * const PostSchema = z.object({
+ *   id: z.number(),
+ *   title: z.string(),
+ *   content: z.string(),
+ * });
+ *
+ * async function fetchPost(postId: number) {
+ *  const post = await api.get(`https://api.example.com/posts/${postId}`, PostSchema);
+ *   return post; // post is typed as { id: number; title: string; content: string; }
+ * }
+ */
+export const api = {
+	get: <TResponse>(
+		resource: string,
+		schema: z.ZodType<TResponse>,
+		options?: Omit<RequestInit, "method" | "body">,
+	) => safeFetch(resource, schema, { ...options, method: "GET" }),
+
+	post: <TResponse, TBody = unknown>(
+		resource: string,
+		schema: z.ZodType<TResponse>,
+		body?: TBody,
+		options?: Omit<RequestInit, "method" | "body">,
+	) => safeFetch(resource, schema, { ...options, method: "POST", body }),
+
+	put: <TResponse, TBody = unknown>(
+		resource: string,
+		schema: z.ZodType<TResponse>,
+		body?: TBody,
+		options?: Omit<RequestInit, "method" | "body">,
+	) => safeFetch(resource, schema, { ...options, method: "PUT", body }),
+
+	patch: <TResponse, TBody = unknown>(
+		resource: string,
+		schema: z.ZodType<TResponse>,
+		body?: TBody,
+		options?: Omit<RequestInit, "method" | "body">,
+	) => safeFetch(resource, schema, { ...options, method: "PATCH", body }),
+
+	delete: <TResponse>(
+		resource: string,
+		schema: z.ZodType<TResponse>,
+		options?: Omit<RequestInit, "method" | "body">,
+	) => safeFetch(resource, schema, { ...options, method: "DELETE" }),
+};

package/src/types/index.ts

@@ -0,0 +1,23 @@
+export type FetchConfig<TBody> = Omit<RequestInit, "body"> & {
+	body?: TBody;
+	throwOnValidationError?: boolean;
+};
+
+export type ResponseType =
+	| "arrayBuffer"
+	| "blob"
+	| "bytes"
+	| "clone"
+	| "formData"
+	| "json"
+	| "text";
+
+export type ResponseTypeMap = {
+	arrayBuffer: ArrayBuffer;
+	blob: Blob;
+	bytes: Uint8Array;
+	clone: Response;
+	formData: FormData;
+	json: unknown;
+	text: string;
+};

package/src/utils/index.ts

@@ -0,0 +1,104 @@
+import { FetchError } from "../errors";
+import type { ResponseType, ResponseTypeMap } from "../types";
+
+export async function parseResponse<TResponseType extends ResponseType>(
+	response: Response,
+	responseType: TResponseType,
+): Promise<ResponseTypeMap[TResponseType]> {
+	const contentType = response.headers.get("content-type");
+
+	const parsers: Record<
+		ResponseType,
+		() => Promise<ResponseTypeMap[ResponseType]>
+	> = {
+		json: async () => {
+			if (!contentType?.includes("application/json")) {
+				throw new FetchError(
+					"Expected JSON response but received no content type",
+					response.status,
+					response.statusText,
+					response,
+				);
+			}
+			return response.json();
+		},
+		arrayBuffer: async () => response.arrayBuffer(),
+		blob: async () => response.blob(),
+		bytes: async () => {
+			const buffer = await response.arrayBuffer();
+			return new Uint8Array(buffer);
+		},
+		clone: async () => response.clone(),
+		formData: async () => {
+			if (!contentType?.includes("multipart/form-data")) {
+				throw new FetchError(
+					"Expected FormData response but received different content type",
+					response.status,
+					response.statusText,
+					response,
+				);
+			}
+			return response.formData();
+		},
+		text: async () => {
+			if (!contentType?.includes("text/")) {
+				throw new FetchError(
+					"Expected text response but received different content type",
+					response.status,
+					response.statusText,
+					response,
+				);
+			}
+			return response.text();
+		},
+	};
+
+	const parser = parsers[responseType];
+	if (!parser) {
+		throw new FetchError(
+			`Unsupported response type: ${responseType}`,
+			response.status,
+			response.statusText,
+			response,
+		);
+	}
+
+	return parser() as Promise<ResponseTypeMap[TResponseType]>;
+}
+
+export function prepareHeadersAndBody<TBody = unknown>(
+	body: TBody,
+	headers: HeadersInit | undefined,
+): { body: BodyInit | null; headers: HeadersInit | undefined } {
+	let preparedBody: BodyInit | null = null;
+	let preparedHeaders = headers;
+
+	// Handle null/undefined body
+	if (body === null || body === undefined) {
+		return { body: null, headers: preparedHeaders };
+	}
+
+	// Check if body is already a valid BodyInit type
+	if (
+		body instanceof FormData ||
+		body instanceof URLSearchParams ||
+		body instanceof Blob ||
+		body instanceof ArrayBuffer ||
+		body instanceof ReadableStream ||
+		typeof body === "string"
+	) {
+		preparedBody = body as BodyInit;
+	} else if (typeof body === "object") {
+		// If body is a plain object, stringify it and set Content-Type
+		preparedBody = JSON.stringify(body);
+		preparedHeaders = {
+			"Content-Type": "application/json",
+			...headers,
+		};
+	} else {
+		// Handle other primitive types by converting to string
+		preparedBody = String(body);
+	}
+
+	return { body: preparedBody, headers: preparedHeaders };
+}