@marianmeres/http-utils 2.2.0 → 2.3.0

package/AGENTS.md

@@ -103,6 +103,13 @@ HTTP_ERROR.BadGateway       // 502
 HTTP_ERROR.ServiceUnavailable // 503
 ```
 
+### Helper Functions
+
+```typescript
+// Marks options object for options-based API (vs legacy positional API)
+function opts<T extends GetOptions | DataOptions>(options: T): T
+```
+
 ### Utility Functions
 
 ```typescript
@@ -168,12 +175,18 @@ deno task publish     # Publish to JSR and NPM
 ### Basic Usage
 
 ```typescript
+import { createHttpApi, opts } from "@marianmeres/http-utils";
+
 const api = createHttpApi("https://api.example.com", {
   headers: { "Authorization": "Bearer token" }
 });
 
+// Legacy API (default - object is request body)
 const data = await api.get("/users");
-await api.post("/users", { data: { name: "John" } });
+await api.post("/users", { name: "John" });
+
+// Options API (requires opts() wrapper)
+await api.post("/users", opts({ data: { name: "John" }, params: { token: "abc" } }));
 ```
 
 ### Error Handling

package/API.md

@@ -5,6 +5,7 @@ Complete API reference for `@marianmeres/http-utils`.
 ## Table of Contents
 
 - [createHttpApi](#createhttpapi)
+- [opts](#opts)
 - [HttpApi Class](#httpapi-class)
 - [Types](#types)
 - [HTTP Errors](#http-errors)
@@ -78,6 +79,47 @@ Priority order: per-request > per-instance > global > built-in fallback.
 
 ---
 
+## opts
+
+Marks an options object for the options-based API. Without this wrapper, arguments are treated as legacy positional parameters.
+
+```ts
+function opts<T extends GetOptions | DataOptions>(options: T): T
+```
+
+### Why `opts()`?
+
+The library supports two API styles:
+- **Legacy API**: Positional parameters (backward compatible)
+- **Options API**: Single options object with named properties
+
+The `opts()` wrapper explicitly indicates which style you're using, preventing ambiguity when your request data might look like an options object.
+
+### Example
+
+```ts
+import { createHttpApi, opts } from "@marianmeres/http-utils";
+
+const api = createHttpApi("https://api.example.com");
+
+// Without opts() - legacy behavior: entire object is sent as request body
+await api.post("/users", { data: { name: "John" } });
+// Sends: { "data": { "name": "John" } }
+
+// With opts() - options API: data is extracted and sent as body
+await api.post("/users", opts({ data: { name: "John" } }));
+// Sends: { "name": "John" }
+
+// GET with options
+const respHeaders = {};
+await api.get("/users", opts({
+  params: { headers: { "X-Custom": "value" } },
+  respHeaders
+}));
+```
+
+---
+
 ## HttpApi Class
 
 HTTP API client class. Usually created via `createHttpApi()`.
@@ -88,12 +130,12 @@ HTTP API client class. Usually created via `createHttpApi()`.
 
 Performs a GET request.
 
-**New Options API (recommended):**
+**Options API (with `opts()` wrapper):**
 ```ts
 async get<T = unknown>(path: string, options?: GetOptions): Promise<T>
 ```
 
-**Legacy API:**
+**Legacy API (default behavior):**
 ```ts
 async get<T = unknown>(
   path: string,
@@ -105,17 +147,17 @@ async get<T = unknown>(
 
 **Example:**
 ```ts
-// New API with type parameter
+// Options API with type parameter (requires opts() wrapper)
 interface User { id: number; name: string; }
-const user = await api.get<User>("/users/1", {
+const user = await api.get<User>("/users/1", opts({
   params: { headers: { "X-Custom": "value" } },
   respHeaders: {}
-});
+}));
 
 // Without type parameter (returns unknown)
 const data = await api.get("/users");
 
-// Legacy API
+// Legacy API (no opts() needed)
 const data = await api.get("/users", { headers: { "X-Custom": "value" } });
 ```
 
@@ -123,12 +165,12 @@ const data = await api.get("/users", { headers: { "X-Custom": "value" } });
 
 Performs a POST request.
 
-**New Options API (recommended):**
+**Options API (with `opts()` wrapper):**
 ```ts
 async post<T = unknown>(path: string, options?: DataOptions): Promise<T>
 ```
 
-**Legacy API:**
+**Legacy API (default behavior):**
 ```ts
 async post<T = unknown>(
   path: string,
@@ -141,14 +183,14 @@ async post<T = unknown>(
 
 **Example:**
 ```ts
-// New API with type parameter
+// Options API with type parameter (requires opts() wrapper)
 interface User { id: number; name: string; }
-const user = await api.post<User>("/users", {
+const user = await api.post<User>("/users", opts({
   data: { name: "John" },
   params: { headers: { "X-Custom": "value" } }
-});
+}));
 
-// Legacy API
+// Legacy API (no opts() needed)
 const result = await api.post("/users", { name: "John" });
 ```
 

package/README.md

@@ -26,38 +26,38 @@ npm install @marianmeres/http-utils
 ```
 
 ```ts
-import { createHttpApi, HTTP_ERROR } from "@marianmeres/http-utils";
+import { createHttpApi, opts, HTTP_ERROR } from "@marianmeres/http-utils";
 ```
 
 ## Quick Start
 
 ```ts
-import { createHttpApi, HTTP_ERROR, NotFound } from "@marianmeres/http-utils";
+import { createHttpApi, opts, HTTP_ERROR, NotFound } from "@marianmeres/http-utils";
 
 // Create an API client with base URL
 const api = createHttpApi("https://api.example.com", {
   headers: { "Authorization": "Bearer your-token" }
 });
 
-// GET request (new options API - recommended)
-const users = await api.get("/users", {
+// GET request (options API with opts() wrapper)
+const users = await api.get("/users", opts({
   params: { headers: { "X-Custom": "value" } }
-});
+}));
 
-// POST request (new options API - recommended)
-const newUser = await api.post("/users", {
+// POST request (options API with opts() wrapper)
+const newUser = await api.post("/users", opts({
   data: { name: "John Doe" },
   params: { headers: { "X-Custom": "value" } }
-});
+}));
 
-// Legacy API still works
+// Legacy API (default behavior without opts())
 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" } });
+const created = await api.post<User>("/users", opts({ data: { name: "Jane" } }));
 
 // Error handling
 try {
@@ -89,23 +89,37 @@ const api = createHttpApi("https://api.example.com", {
 ### HTTP Methods
 
 ```ts
-// GET (new options API)
-const data = await api.get("/users", {
+// GET (options API with opts() wrapper)
+const data = await api.get("/users", opts({
   params: { headers: { "X-Custom": "value" } },
   respHeaders: {}
-});
+}));
 
-// POST/PUT/PATCH/DELETE (new options API)
-await api.post("/users", {
+// POST/PUT/PATCH/DELETE (options API with opts() wrapper)
+await api.post("/users", opts({
   data: { name: "John" },
   params: { token: "bearer-token" }
-});
+}));
 
-// Legacy API still supported
+// Legacy API (default behavior without opts())
 const data = await api.get("/users", { headers: { "X-Custom": "value" } });
 await api.post("/users", { name: "John" });
 ```
 
+### The `opts()` Helper
+
+The `opts()` function explicitly marks an options object for the options-based API. Without it, arguments are treated as legacy positional parameters.
+
+```ts
+// Without opts() - legacy behavior: object is sent as request body
+await api.post("/users", { data: { name: "John" } });  // Sends: { data: { name: "John" } }
+
+// With opts() - options API: data is extracted and sent as body
+await api.post("/users", opts({ data: { name: "John" } }));  // Sends: { name: "John" }
+```
+
+This makes the API unambiguous and prevents accidental misinterpretation of request data.
+
 ### Error Handling
 
 ```ts

package/dist/api.d.ts

@@ -71,6 +71,20 @@ export interface DataOptions {
     /** Custom error message extractor for this request. */
     errorExtractor?: ErrorMessageExtractor | null;
 }
+/**
+ * Marks an options object for the new options API.
+ * Use this to explicitly indicate you're using the options-based API.
+ *
+ * @example
+ * ```ts
+ * // GET with options
+ * await api.get('/users', opts({ params: { token: 'abc' } }));
+ *
+ * // POST with options
+ * await api.post('/users', opts({ data: { name: 'John' }, params: { token: 'abc' } }));
+ * ```
+ */
+export declare function opts<T extends GetOptions | DataOptions>(options: T): T;
 /**
  * HTTP API client with convenient defaults and error handling.
  */

package/dist/api.js

@@ -32,6 +32,68 @@ function deepMerge(target, source) {
 function isObject(item) {
     return item !== null && typeof item === 'object' && !Array.isArray(item);
 }
+/** Symbol marker for explicit options API detection. */
+const OPTIONS_MARKER = Symbol('options');
+/**
+ * Marks an options object for the new options API.
+ * Use this to explicitly indicate you're using the options-based API.
+ *
+ * @example
+ * ```ts
+ * // GET with options
+ * await api.get('/users', opts({ params: { token: 'abc' } }));
+ *
+ * // POST with options
+ * await api.post('/users', opts({ data: { name: 'John' }, params: { token: 'abc' } }));
+ * ```
+ */
+export function opts(options) {
+    return Object.assign(options, { [OPTIONS_MARKER]: true });
+}
+/**
+ * Parses GET method arguments, detecting new options API via OPTIONS_MARKER.
+ */
+function parseGetOptions(paramsOrOptions, legacyRespHeaders, legacyErrorExtractor) {
+    if (paramsOrOptions && OPTIONS_MARKER in paramsOrOptions) {
+        // New options API (explicit via opts() wrapper)
+        const o = paramsOrOptions;
+        return {
+            params: o.params,
+            respHeaders: o.respHeaders ?? null,
+            errorExtractor: o.errorExtractor ?? null,
+        };
+    }
+    // Legacy positional API
+    return {
+        params: paramsOrOptions,
+        respHeaders: legacyRespHeaders ?? null,
+        errorExtractor: legacyErrorExtractor ?? null,
+    };
+}
+/**
+ * Parses body method arguments (POST/PUT/PATCH/DELETE), detecting new options API via OPTIONS_MARKER.
+ */
+function parseDataOptions(dataOrOptions, legacyParams, legacyRespHeaders, legacyErrorExtractor) {
+    if (dataOrOptions &&
+        typeof dataOrOptions === 'object' &&
+        OPTIONS_MARKER in dataOrOptions) {
+        // New options API (explicit via opts() wrapper)
+        const o = dataOrOptions;
+        return {
+            data: o.data ?? null,
+            params: o.params,
+            respHeaders: o.respHeaders ?? null,
+            errorExtractor: o.errorExtractor ?? null,
+        };
+    }
+    // Legacy positional API
+    return {
+        data: dataOrOptions ?? null,
+        params: legacyParams,
+        respHeaders: legacyRespHeaders ?? null,
+        errorExtractor: legacyErrorExtractor ?? null,
+    };
+}
 const _fetchRaw = async ({ method, path, data = null, token = null, headers = null, signal, credentials, }) => {
     const normalizedHeaders = Object.entries(headers || {}).reduce((m, [k, v]) => ({ ...m, [k.toLowerCase()]: v }), {});
     const opts = {
@@ -142,136 +204,29 @@ export class HttpApi {
         return /^https?:/.test(path) ? path : base + path;
     }
     async get(path, paramsOrOptions, respHeaders, errorMessageExtractor, _dumpParams = false) {
-        // Detect which API is being used
-        let params;
-        let headers = null;
-        let extractor = null;
-        if (paramsOrOptions && ('respHeaders' in paramsOrOptions || 'errorExtractor' in paramsOrOptions)) {
-            // New options API
-            const opts = paramsOrOptions;
-            params = opts.params;
-            headers = opts.respHeaders ?? null;
-            extractor = opts.errorExtractor ?? null;
-        }
-        else {
-            // Legacy positional API
-            params = paramsOrOptions;
-            headers = respHeaders ?? null;
-            extractor = errorMessageExtractor ?? null;
-        }
+        const { params, respHeaders: headers, errorExtractor } = parseGetOptions(paramsOrOptions, respHeaders, errorMessageExtractor);
         path = this.#buildPath(path, this.#base);
-        return _fetch(this.#merge(await this.#getDefs(), { ...params, method: 'GET', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        return _fetch(this.#merge(await this.#getDefs(), { ...params, method: 'GET', path }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
     }
     async post(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
-        // Detect which API is being used
-        let data = null;
-        let fetchParams;
-        let headers = null;
-        let extractor = null;
-        if (dataOrOptions &&
-            typeof dataOrOptions === 'object' &&
-            !(dataOrOptions instanceof FormData) &&
-            ('data' in dataOrOptions ||
-                'params' in dataOrOptions ||
-                'respHeaders' in dataOrOptions ||
-                'errorExtractor' in dataOrOptions)) {
-            // New options API
-            const opts = dataOrOptions;
-            data = opts.data ?? null;
-            fetchParams = opts.params;
-            headers = opts.respHeaders ?? null;
-            extractor = opts.errorExtractor ?? null;
-        }
-        else {
-            // Legacy positional API
-            data = dataOrOptions ?? null;
-            fetchParams = params;
-            headers = respHeaders ?? null;
-            extractor = errorMessageExtractor ?? null;
-        }
+        const { data, params: fetchParams, respHeaders: headers, errorExtractor } = parseDataOptions(dataOrOptions, params, respHeaders, errorMessageExtractor);
         path = this.#buildPath(path, this.#base);
-        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'POST', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'POST', path }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
     }
     async put(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
-        let data = null;
-        let fetchParams;
-        let headers = null;
-        let extractor = null;
-        if (dataOrOptions &&
-            typeof dataOrOptions === 'object' &&
-            !(dataOrOptions instanceof FormData) &&
-            ('data' in dataOrOptions ||
-                'params' in dataOrOptions ||
-                'respHeaders' in dataOrOptions ||
-                'errorExtractor' in dataOrOptions)) {
-            const opts = dataOrOptions;
-            data = opts.data ?? null;
-            fetchParams = opts.params;
-            headers = opts.respHeaders ?? null;
-            extractor = opts.errorExtractor ?? null;
-        }
-        else {
-            data = dataOrOptions ?? null;
-            fetchParams = params;
-            headers = respHeaders ?? null;
-            extractor = errorMessageExtractor ?? null;
-        }
+        const { data, params: fetchParams, respHeaders: headers, errorExtractor } = parseDataOptions(dataOrOptions, params, respHeaders, errorMessageExtractor);
         path = this.#buildPath(path, this.#base);
-        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'PUT', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'PUT', path }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
     }
     async patch(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
-        let data = null;
-        let fetchParams;
-        let headers = null;
-        let extractor = null;
-        if (dataOrOptions &&
-            typeof dataOrOptions === 'object' &&
-            !(dataOrOptions instanceof FormData) &&
-            ('data' in dataOrOptions ||
-                'params' in dataOrOptions ||
-                'respHeaders' in dataOrOptions ||
-                'errorExtractor' in dataOrOptions)) {
-            const opts = dataOrOptions;
-            data = opts.data ?? null;
-            fetchParams = opts.params;
-            headers = opts.respHeaders ?? null;
-            extractor = opts.errorExtractor ?? null;
-        }
-        else {
-            data = dataOrOptions ?? null;
-            fetchParams = params;
-            headers = respHeaders ?? null;
-            extractor = errorMessageExtractor ?? null;
-        }
+        const { data, params: fetchParams, respHeaders: headers, errorExtractor } = parseDataOptions(dataOrOptions, params, respHeaders, errorMessageExtractor);
         path = this.#buildPath(path, this.#base);
-        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'PATCH', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'PATCH', path }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
     }
     async del(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
-        let data = null;
-        let fetchParams;
-        let headers = null;
-        let extractor = null;
-        if (dataOrOptions &&
-            typeof dataOrOptions === 'object' &&
-            !(dataOrOptions instanceof FormData) &&
-            ('data' in dataOrOptions ||
-                'params' in dataOrOptions ||
-                'respHeaders' in dataOrOptions ||
-                'errorExtractor' in dataOrOptions)) {
-            const opts = dataOrOptions;
-            data = opts.data ?? null;
-            fetchParams = opts.params;
-            headers = opts.respHeaders ?? null;
-            extractor = opts.errorExtractor ?? null;
-        }
-        else {
-            data = dataOrOptions ?? null;
-            fetchParams = params;
-            headers = respHeaders ?? null;
-            extractor = errorMessageExtractor ?? null;
-        }
+        const { data, params: fetchParams, respHeaders: headers, errorExtractor } = parseDataOptions(dataOrOptions, params, respHeaders, errorMessageExtractor);
         path = this.#buildPath(path, this.#base);
-        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'DELETE', path }), headers, extractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        return _fetch(this.#merge(await this.#getDefs(), { ...(fetchParams || {}), data, method: 'DELETE', path }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
     }
     /**
      * Helper method to build the full URL from a path.

package/dist/mod.d.ts

@@ -21,6 +21,6 @@
  * }
  * ```
  */
-export { HttpApi, createHttpApi, type DataOptions, type GetOptions, type FetchParams, type ErrorMessageExtractor, type ResponseHeaders, type RequestData, } from "./api.js";
+export { HttpApi, createHttpApi, opts, type DataOptions, type GetOptions, type FetchParams, type ErrorMessageExtractor, type ResponseHeaders, type RequestData, } from "./api.js";
 export { HTTP_ERROR, createHttpError, getErrorMessage } from "./error.js";
 export { HTTP_STATUS } from "./status.js";

package/dist/mod.js

@@ -21,6 +21,6 @@
  * }
  * ```
  */
-export { HttpApi, createHttpApi, } from "./api.js";
+export { HttpApi, createHttpApi, opts, } from "./api.js";
 export { HTTP_ERROR, createHttpError, getErrorMessage } from "./error.js";
 export { HTTP_STATUS } from "./status.js";

package/package.json

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