@marianmeres/http-utils 2.1.0 → 2.2.0

package/API.md

@@ -84,61 +84,66 @@ HTTP API client class. Usually created via `createHttpApi()`.
 
 ### Methods
 
-#### `get(path, options?)`
+#### `get<T>(path, options?)`
 
 Performs a GET request.
 
 **New Options API (recommended):**
 ```ts
-async get(path: string, options?: GetOptions): Promise<unknown>
+async get<T = unknown>(path: string, options?: GetOptions): Promise<T>
 ```
 
 **Legacy API:**
 ```ts
-async get(
+async get<T = unknown>(
   path: string,
   params?: FetchParams,
   respHeaders?: ResponseHeaders | null,
   errorMessageExtractor?: ErrorMessageExtractor | null
-): Promise<unknown>
+): Promise<T>
 ```
 
 **Example:**
 ```ts
-// New API
-const data = await api.get("/users", {
+// New API with type parameter
+interface User { id: number; name: string; }
+const user = await api.get<User>("/users/1", {
   params: { headers: { "X-Custom": "value" } },
   respHeaders: {}
 });
 
+// Without type parameter (returns unknown)
+const data = await api.get("/users");
+
 // Legacy API
 const data = await api.get("/users", { headers: { "X-Custom": "value" } });
 ```
 
-#### `post(path, options?)`
+#### `post<T>(path, options?)`
 
 Performs a POST request.
 
 **New Options API (recommended):**
 ```ts
-async post(path: string, options?: DataOptions): Promise<unknown>
+async post<T = unknown>(path: string, options?: DataOptions): Promise<T>
 ```
 
 **Legacy API:**
 ```ts
-async post(
+async post<T = unknown>(
   path: string,
   data?: RequestData,
   params?: FetchParams,
   respHeaders?: ResponseHeaders | null,
   errorMessageExtractor?: ErrorMessageExtractor | null
-): Promise<unknown>
+): Promise<T>
 ```
 
 **Example:**
 ```ts
-// New API
-const result = await api.post("/users", {
+// New API with type parameter
+interface User { id: number; name: string; }
+const user = await api.post<User>("/users", {
   data: { name: "John" },
   params: { headers: { "X-Custom": "value" } }
 });
@@ -147,17 +152,17 @@ const result = await api.post("/users", {
 const result = await api.post("/users", { name: "John" });
 ```
 
-#### `put(path, options?)`
+#### `put<T>(path, options?)`
 
-Performs a PUT request. Same signature as `post()`.
+Performs a PUT request. Same signature as `post<T>()`.
 
-#### `patch(path, options?)`
+#### `patch<T>(path, options?)`
 
-Performs a PATCH request. Same signature as `post()`.
+Performs a PATCH request. Same signature as `post<T>()`.
 
-#### `del(path, options?)`
+#### `del<T>(path, options?)`
 
-Performs a DELETE request. Same signature as `post()`.
+Performs a DELETE request. Same signature as `post<T>()`.
 
 #### `url(path)`
 

package/README.md

@@ -13,6 +13,7 @@ Opinionated, lightweight HTTP client wrapper for `fetch` with type-safe errors a
 - 🪶 **Lightweight** - Zero dependencies, thin wrapper over native `fetch`
 - 🎨 **Flexible error handling** - Three-tier error message extraction (local → factory → global)
 - 📦 **Deno & Node.js** - Works in both runtimes
+- 🦾 **Generic return types** - Optional type parameters for typed responses
 
 ## Installation
 
@@ -53,6 +54,11 @@ const newUser = await api.post("/users", {
 const legacyUsers = await api.get("/users", { headers: { "X-Custom": "value" } });
 const legacyUser = await api.post("/users", { name: "John Doe" });
 
+// With type parameters for typed responses
+interface User { id: number; name: string; }
+const user = await api.get<User>("/users/1");
+const created = await api.post<User>("/users", { data: { name: "Jane" } });
+
 // Error handling
 try {
   await api.get("/not-found");
@@ -123,6 +129,7 @@ try {
 - **Raw response**: Use `raw: true` to get the raw Response object
 - **Non-throwing**: Use `assert: false` to prevent throwing on errors
 - **AbortController**: Pass `signal` for request cancellation
+- **Typed responses**: Use generics for type-safe responses: `api.get<User>("/users/1")`
 
 ## Full API Reference
 

package/dist/api.d.ts

@@ -93,7 +93,7 @@ export declare class HttpApi {
      * });
      * ```
      */
-    get(path: string, options: GetOptions): Promise<unknown>;
+    get<T = unknown>(path: string, options: GetOptions): Promise<T>;
     /**
      * Performs a GET request (legacy API).
      *
@@ -105,7 +105,7 @@ export declare class HttpApi {
      * @returns The response body (auto-parsed as JSON if possible), or Response if `raw: true`.
      * @throws {HttpError} When the response is not OK and `assert` is true (default).
      */
-    get(path: string, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
+    get<T = unknown>(path: string, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<T>;
     /**
      * Performs a POST request (new options API - recommended).
      *
@@ -123,7 +123,7 @@ export declare class HttpApi {
      * });
      * ```
      */
-    post(path: string, options: DataOptions): Promise<unknown>;
+    post<T = unknown>(path: string, options: DataOptions): Promise<T>;
     /**
      * Performs a POST request (legacy API).
      *
@@ -136,23 +136,23 @@ export declare class HttpApi {
      * @returns The response body (auto-parsed as JSON if possible), or Response if `raw: true`.
      * @throws {HttpError} When the response is not OK and `assert` is true (default).
      */
-    post(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
+    post<T = unknown>(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<T>;
     /** Performs a PUT request (new options API). @see post */
-    put(path: string, options: DataOptions): Promise<unknown>;
+    put<T = unknown>(path: string, options: DataOptions): Promise<T>;
     /** Performs a PUT request (legacy API). @see post */
-    put(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
+    put<T = unknown>(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<T>;
     /** Performs a PATCH request (new options API). @see post */
-    patch(path: string, options: DataOptions): Promise<unknown>;
+    patch<T = unknown>(path: string, options: DataOptions): Promise<T>;
     /** Performs a PATCH request (legacy API). @see post */
-    patch(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
+    patch<T = unknown>(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<T>;
     /**
      * Performs a DELETE request (new options API).
      * Note: Request body in DELETE is allowed per HTTP spec.
      * @see post
      */
-    del(path: string, options: DataOptions): Promise<unknown>;
+    del<T = unknown>(path: string, options: DataOptions): Promise<T>;
     /** Performs a DELETE request (legacy API). @see post */
-    del(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
+    del<T = unknown>(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<T>;
     /**
      * Helper method to build the full URL from a path.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/http-utils",
-	"version": "2.1.0",
+	"version": "2.2.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",