make-service 1.1.0 → 2.0.0-next.0

package/README.md

@@ -6,7 +6,7 @@ It adds a set of little features and allows you to parse responses with [zod](ht
 
 ## Features
 - 🤩 Type-safe return of `response.json()` and `response.text()`. Defaults to `unknown` instead of `any`.
-- 🚦 Easily setup an API with a `baseURL` and common `headers` for every request.
+- 🚦 Easily setup an API with a `baseURL` and common options like `headers` for every request.
 - 🏗️ Compose URL from the base by just calling the endpoints and an object-like `query`.
 - 🐾 Replaces URL wildcards with a **strongly-typed** object of `params`.
 - 🧙‍♀️ Automatically stringifies the `body` of a request so you can give it a JSON-like structure.
@@ -17,7 +17,9 @@ It adds a set of little features and allows you to parse responses with [zod](ht
 
 ```ts
 const service = makeService("https://example.com/api", {
-  Authorization: "Bearer 123",
+  headers: {
+    Authorization: "Bearer 123",
+  },
 });
 
 const response = await service.get("/users")
@@ -33,9 +35,12 @@ const users = await response.json(usersSchema);
     - [Runtime type-checking and parsing the response body](#runtime-type-checking-and-parsing-the-response-body)
     - [Supported HTTP Verbs](#supported-http-verbs)
     - [Headers](#headers)
-      - [Passing a function as `baseHeaders`](#passing-a-function-as-baseheaders)
+      - [Passing a function as `headers`](#passing-a-function-as-headers)
       - [Deleting a previously set header](#deleting-a-previously-set-header)
     - [Base URL](#base-url)
+    - [Transformers](#transformers)
+      - [Request transformers](#request-transformers)
+      - [Response transformers](#response-transformers)
     - [Body](#body)
     - [Query](#query)
     - [Params](#params)
@@ -68,7 +73,7 @@ import { makeService } from "https://deno.land/x/make_service/mod.ts";
 This library exports the `makeService` function and some primitives used to build it. You can use the primitives as you wish but the `makeService` will have all the features combined.
 
 ## makeService
-The main function of this lib is built on top of the primitives described in the following sections. It allows you to create a service object with a `baseURL` and common `headers` for every request.
+The main function of this lib is built on top of the primitives described in the following sections. It allows you to create a service object with a `baseURL` and common options like `headers` for every request.
 
 This service object can be called with every HTTP method and it will return a [`typedResponse`](#typedresponse).
 
@@ -76,7 +81,9 @@ This service object can be called with every HTTP method and it will return a [`
 import { makeService } from 'make-service'
 
 const service = makeService("https://example.com/api", {
-  authorization: "Bearer 123"
+  headers :{
+    authorization: "Bearer 123",
+  },
 })
 
 const response = await service.get("/users")
@@ -146,15 +153,17 @@ await service.options("/users")
 
 ### Headers
 The `headers` argument can be a `Headers` object, a `Record<string, string>`, or an array of `[key, value]` tuples (entries).
-The `baseHeaders` and the `headers` will be merged together, with the `headers` taking precedence.
+The `headers` option on `baseOptions` and the `headers` argument will be merged together, with the `headers` argument taking precedence.
 
 ```ts
 import { makeService } from 'make-service'
 
-const service = makeService("https://example.com/api", new Headers({
-  authorization: "Bearer 123",
-  accept: "*/*",
-}))
+const service = makeService("https://example.com/api", {
+  headers: new Headers({
+    authorization: "Bearer 123",
+    accept: "*/*",
+  }),
+})
 
 const response = await service.get("/users", {
   headers: [['accept', 'application/json']],
@@ -164,8 +173,8 @@ const response = await service.get("/users", {
 // with headers: { authorization: "Bearer 123", accept: "application/json" }
 ```
 
-#### Passing a function as `baseHeaders`
-The given `baseHeaders` can be a sync or async function that will run in every request before it gets merged with the other headers.
+#### Passing a function as `headers`
+The `headers` option on `baseOptions` can be a sync or async function that will run in every request before it gets merged with the other headers.
 This is particularly useful when you need to send a refreshed token or add a timestamp to the request.
 
 ```ts
@@ -173,16 +182,21 @@ import { makeService } from 'make-service'
 
 declare getAuthorizationToken: () => Promise<HeadersInit>
 
-const service = makeService("https://example.com/api", async () => ({
-  authorization: await getAuthorizationToken(),
-}))
+const service = makeService("https://example.com/api", {
+  headers: async () => ({
+    authorization: await getAuthorizationToken(),
+  }),
+})
 
 ```
 
 #### Deleting a previously set header
 In case you want to delete a header previously set you can pass `undefined` or `'undefined'` as its value:
 ```ts
-const service = makeService("https://example.com/api", { authorization: "Bearer 123" })
+const service = makeService("https://example.com/api", {
+  headers: { authorization: "Bearer 123" },
+})
+
 const response = await service.get("/users", {
   headers: new Headers({ authorization: 'undefined', "Content-Type": undefined }),
 })
@@ -210,6 +224,37 @@ const response = await service.get("/users?admin=true")
 ```
 You can use the [`makeGetApiUrl`](#makegetapiurl) method to do that kind of URL composition.
 
+### Transformers
+`makeService` can also receive `requestTransformer` and `responseTransformer` as options that will be applied to all requests.
+
+#### Request transformers
+You can transform the request in any way you want, like:
+
+```ts
+const service = makeService('https://example.com/api', {
+  requestTransformer: (request) => ({ ...request, query: { admin: 'true' } }),
+})
+
+const response = await service.get("/users")
+
+// It will call "https://example.com/api/users?admin=true"
+```
+
+Please note that the `headers` option will be applied _after_ the request transformer runs. If you're using a request transformer, we recommend adding custom headers inside your transformer instead of using both options.
+
+#### Response transformers
+You can also transform the response in any way you want, like:
+
+```ts
+const service = makeService('https://example.com/api', {
+  responseTransformer: (response) => ({ ...response, statusText: 'It worked!' }),
+})
+
+const response = await service.get("/users")
+
+// response.statusText will be 'It worked!'
+```
+
 ### Body
 The function can also receive a `body` object that will be stringified and sent as the request body:
 

package/dist/index.d.ts

@@ -1,17 +1,5 @@
 declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD", "CONNECT"];
 
-/**
- * It returns the JSON object or throws an error if the response is not ok.
- * @param response the Response to be parsed
- * @returns the response.json method that accepts a type or Zod schema for a typed json response
- */
-declare function getJson(response: Response): <T = unknown>(schema?: Schema<T> | undefined) => Promise<T>;
-/**
- * @param response the Response to be parsed
- * @returns the response.text method that accepts a type or Zod schema for a typed response
- */
-declare function getText(response: Response): <T extends string = string>(schema?: Schema<T> | undefined) => Promise<T>;
-
 type Schema<T> = {
     parse: (d: unknown) => T;
 };
@@ -32,9 +20,18 @@ type EnhancedRequestInit<T = string> = Omit<RequestInit, 'body' | 'method'> & {
     trace?: (...args: Parameters<typeof fetch>) => void;
 };
 type ServiceRequestInit<T = string> = Omit<EnhancedRequestInit<T>, 'method'>;
+type RequestTransformer = (request: EnhancedRequestInit) => EnhancedRequestInit | Promise<EnhancedRequestInit>;
+type ResponseTransformer = (response: TypedResponse) => TypedResponse | Promise<TypedResponse>;
+type BaseOptions = {
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    requestTransformer?: RequestTransformer;
+    responseTransformer?: ResponseTransformer;
+};
 type HTTPMethod = (typeof HTTP_METHODS)[number];
-type TypedResponseJson = ReturnType<typeof getJson>;
-type TypedResponseText = ReturnType<typeof getText>;
+type TypedResponseJson = <T = unknown>(schema?: Schema<T>) => Promise<T>;
+type TypedResponseText = <T extends string = string>(schema?: Schema<T>) => Promise<T>;
+type GetJson = (response: Response) => TypedResponseJson;
+type GetText = (response: Response) => TypedResponseText;
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
@@ -58,7 +55,10 @@ type ExtractPathParams<T extends string> = T extends `${infer _}:${infer Param}/
  * const typedJson = await response.json<User[]>();
  * //    ^? User[]
  */
-declare function typedResponse(response: Response): TypedResponse;
+declare function typedResponse(response: Response, options?: {
+    getJson?: GetJson;
+    getText?: GetText;
+}): TypedResponse;
 /**
  *
  * @param url a string or URL to be fetched
@@ -77,7 +77,10 @@ declare function enhancedFetch<T extends string | URL>(url: T, requestInit?: Enh
 /**
  *
  * @param baseURL the base URL to be fetched in every request
- * @param baseHeaders any headers that should be sent with every request
+ * @param baseOptions options that will be applied to all requests
+ * @param baseOptions.headers any headers that should be sent with every request
+ * @param baseOptions.requestTransformer a function that will transform the enhanced request init of every request
+ * @param baseOptions.responseTransformer a function that will transform the typed response of every request
  * @returns a function that receive a path and requestInit and return a serialized json response that can be typed or not.
  * @example const headers = { Authorization: "Bearer 123" }
  * const fetcher = makeFetcher("https://example.com/api", headers);
@@ -85,11 +88,14 @@ declare function enhancedFetch<T extends string | URL>(url: T, requestInit?: Enh
  * const users = await response.json(userSchema);
  * //    ^? User[]
  */
-declare function makeFetcher(baseURL: string | URL, baseHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>)): <T extends string>(path: T, requestInit?: EnhancedRequestInit<T>) => Promise<TypedResponse>;
+declare function makeFetcher(baseURL: string | URL, baseOptions?: BaseOptions): <T extends string>(path: T, requestInit?: EnhancedRequestInit<T>) => Promise<TypedResponse>;
 /**
  *
  * @param baseURL the base URL to the API
- * @param baseHeaders any headers that should be sent with every request
+ * @param baseOptions options that will be applied to all requests
+ * @param baseOptions.headers any headers that should be sent with every request
+ * @param baseOptions.requestTransformer a function that will transform the enhanced request init of every request
+ * @param baseOptions.responseTransformer a function that will transform the typed response of every request
  * @returns a service object with HTTP methods that are functions that receive a path and requestInit and return a serialized json response that can be typed or not.
  * @example const headers = { Authorization: "Bearer 123" }
  * const api = makeService("https://example.com/api", headers);
@@ -97,7 +103,7 @@ declare function makeFetcher(baseURL: string | URL, baseHeaders?: HeadersInit |
  * const users = await response.json(userSchema);
  * //    ^? User[]
  */
-declare function makeService(baseURL: string | URL, baseHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>)): Record<"get" | "post" | "put" | "delete" | "patch" | "options" | "head" | "connect", <T extends string>(path: T, requestInit?: ServiceRequestInit<T>) => Promise<TypedResponse>>;
+declare function makeService(baseURL: string | URL, baseOptions?: BaseOptions): Record<"get" | "post" | "put" | "delete" | "patch" | "options" | "head" | "connect", <T extends string>(path: T, requestInit?: ServiceRequestInit<T>) => Promise<TypedResponse>>;
 
 /**
  * @param url a string or URL to which the query parameters will be added
@@ -175,4 +181,4 @@ type DeepKebabToSnake<T> = T extends [any, ...any] ? {
 };
 declare function kebabToSnake<T>(obj: T): DeepKebabToSnake<T>;
 
-export { CamelToKebab, CamelToSnake, DeepCamelToKebab, DeepCamelToSnake, DeepKebabToCamel, DeepKebabToSnake, DeepSnakeToCamel, DeepSnakeToKebab, EnhancedRequestInit, HTTPMethod, JSONValue, KebabToCamel, KebabToSnake, PathParams, Schema, SearchParams, ServiceRequestInit, SnakeToCamel, SnakeToKebab, TypedResponse, TypedResponseJson, TypedResponseText, addQueryToURL, camelToKebab, camelToSnake, enhancedFetch, ensureStringBody, kebabToCamel, kebabToSnake, makeFetcher, makeGetApiURL, makeService, mergeHeaders, replaceURLParams, snakeToCamel, snakeToKebab, typedResponse };
+export { BaseOptions, CamelToKebab, CamelToSnake, DeepCamelToKebab, DeepCamelToSnake, DeepKebabToCamel, DeepKebabToSnake, DeepSnakeToCamel, DeepSnakeToKebab, EnhancedRequestInit, GetJson, GetText, HTTPMethod, JSONValue, KebabToCamel, KebabToSnake, PathParams, RequestTransformer, ResponseTransformer, Schema, SearchParams, ServiceRequestInit, SnakeToCamel, SnakeToKebab, TypedResponse, TypedResponseJson, TypedResponseText, addQueryToURL, camelToKebab, camelToSnake, enhancedFetch, ensureStringBody, kebabToCamel, kebabToSnake, makeFetcher, makeGetApiURL, makeService, mergeHeaders, replaceURLParams, snakeToCamel, snakeToKebab, typedResponse };

package/dist/index.js

@@ -52,18 +52,14 @@ var HTTP_METHODS = [
 ];
 
 // src/internals.ts
-function getJson(response) {
-  return async (schema) => {
-    const json = await response.json();
-    return schema ? schema.parse(json) : json;
-  };
-}
-function getText(response) {
-  return async (schema) => {
-    const text = await response.text();
-    return schema ? schema.parse(text) : text;
-  };
-}
+var getJson = (response) => async (schema) => {
+  const json = await response.json();
+  return schema ? schema.parse(json) : json;
+};
+var getText = (response) => async (schema) => {
+  const text = await response.text();
+  return schema ? schema.parse(text) : text;
+};
 function typeOf(t) {
   return Object.prototype.toString.call(t).replace(/^\[object (.+)\]$/, "$1").toLowerCase();
 }
@@ -124,13 +120,17 @@ function replaceURLParams(url, params) {
 }
 
 // src/api.ts
-function typedResponse(response) {
+var identity = (value) => value;
+function typedResponse(response, options) {
+  var _a, _b;
+  const getJsonFn = (_a = options == null ? void 0 : options.getJson) != null ? _a : getJson;
+  const getTextFn = (_b = options == null ? void 0 : options.getText) != null ? _b : getText;
   return new Proxy(response, {
     get(target, prop) {
       if (prop === "json")
-        return getJson(target);
+        return getJsonFn(target);
       if (prop === "text")
-        return getText(target);
+        return getTextFn(target);
       return target[prop];
     }
   });
@@ -152,22 +152,32 @@ async function enhancedFetch(url, requestInit) {
   const response = await fetch(fullURL, enhancedReqInit);
   return typedResponse(response);
 }
-function makeFetcher(baseURL, baseHeaders) {
+function makeFetcher(baseURL, baseOptions = {}) {
   return async (path, requestInit = {}) => {
-    var _a;
+    var _a, _b;
+    const { headers } = baseOptions;
+    const requestTransformer = (_a = baseOptions.requestTransformer) != null ? _a : identity;
+    const responseTransformer = (_b = baseOptions.responseTransformer) != null ? _b : identity;
+    const headerTransformer = async (ri) => {
+      var _a2;
+      return {
+        ...ri,
+        headers: mergeHeaders(
+          typeof headers === "function" ? await headers() : headers != null ? headers : {},
+          (_a2 = requestInit == null ? void 0 : requestInit.headers) != null ? _a2 : {}
+        )
+      };
+    };
     const url = makeGetApiURL(baseURL)(path);
-    const response = await enhancedFetch(url, {
-      ...requestInit,
-      headers: mergeHeaders(
-        typeof baseHeaders === "function" ? await baseHeaders() : baseHeaders != null ? baseHeaders : {},
-        (_a = requestInit == null ? void 0 : requestInit.headers) != null ? _a : {}
-      )
-    });
-    return response;
+    const response = await enhancedFetch(
+      url,
+      await headerTransformer(await requestTransformer(requestInit))
+    );
+    return responseTransformer(response);
   };
 }
-function makeService(baseURL, baseHeaders) {
-  const fetcher = makeFetcher(baseURL, baseHeaders);
+function makeService(baseURL, baseOptions) {
+  const fetcher = makeFetcher(baseURL, baseOptions);
   function appliedService(method) {
     return async (path, requestInit = {}) => fetcher(path, { ...requestInit, method });
   }

package/dist/index.mjs

@@ -12,18 +12,14 @@ var HTTP_METHODS = [
 ];
 
 // src/internals.ts
-function getJson(response) {
-  return async (schema) => {
-    const json = await response.json();
-    return schema ? schema.parse(json) : json;
-  };
-}
-function getText(response) {
-  return async (schema) => {
-    const text = await response.text();
-    return schema ? schema.parse(text) : text;
-  };
-}
+var getJson = (response) => async (schema) => {
+  const json = await response.json();
+  return schema ? schema.parse(json) : json;
+};
+var getText = (response) => async (schema) => {
+  const text = await response.text();
+  return schema ? schema.parse(text) : text;
+};
 function typeOf(t) {
   return Object.prototype.toString.call(t).replace(/^\[object (.+)\]$/, "$1").toLowerCase();
 }
@@ -84,13 +80,17 @@ function replaceURLParams(url, params) {
 }
 
 // src/api.ts
-function typedResponse(response) {
+var identity = (value) => value;
+function typedResponse(response, options) {
+  var _a, _b;
+  const getJsonFn = (_a = options == null ? void 0 : options.getJson) != null ? _a : getJson;
+  const getTextFn = (_b = options == null ? void 0 : options.getText) != null ? _b : getText;
   return new Proxy(response, {
     get(target, prop) {
       if (prop === "json")
-        return getJson(target);
+        return getJsonFn(target);
       if (prop === "text")
-        return getText(target);
+        return getTextFn(target);
       return target[prop];
     }
   });
@@ -112,22 +112,32 @@ async function enhancedFetch(url, requestInit) {
   const response = await fetch(fullURL, enhancedReqInit);
   return typedResponse(response);
 }
-function makeFetcher(baseURL, baseHeaders) {
+function makeFetcher(baseURL, baseOptions = {}) {
   return async (path, requestInit = {}) => {
-    var _a;
+    var _a, _b;
+    const { headers } = baseOptions;
+    const requestTransformer = (_a = baseOptions.requestTransformer) != null ? _a : identity;
+    const responseTransformer = (_b = baseOptions.responseTransformer) != null ? _b : identity;
+    const headerTransformer = async (ri) => {
+      var _a2;
+      return {
+        ...ri,
+        headers: mergeHeaders(
+          typeof headers === "function" ? await headers() : headers != null ? headers : {},
+          (_a2 = requestInit == null ? void 0 : requestInit.headers) != null ? _a2 : {}
+        )
+      };
+    };
     const url = makeGetApiURL(baseURL)(path);
-    const response = await enhancedFetch(url, {
-      ...requestInit,
-      headers: mergeHeaders(
-        typeof baseHeaders === "function" ? await baseHeaders() : baseHeaders != null ? baseHeaders : {},
-        (_a = requestInit == null ? void 0 : requestInit.headers) != null ? _a : {}
-      )
-    });
-    return response;
+    const response = await enhancedFetch(
+      url,
+      await headerTransformer(await requestTransformer(requestInit))
+    );
+    return responseTransformer(response);
   };
 }
-function makeService(baseURL, baseHeaders) {
-  const fetcher = makeFetcher(baseURL, baseHeaders);
+function makeService(baseURL, baseOptions) {
+  const fetcher = makeFetcher(baseURL, baseOptions);
   function appliedService(method) {
     return async (path, requestInit = {}) => fetcher(path, { ...requestInit, method });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "make-service",
-  "version": "1.1.0",
+  "version": "2.0.0-next.0",
   "description": "Some utilities to extend the 'fetch' API to better interact with external APIs.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -16,10 +16,10 @@
   },
   "devDependencies": {
     "eslint": "latest",
-    "jsdom": "^21.1.1",
+    "jsdom": "^22.1.0",
     "prettier": "latest",
     "tsup": "^6.7.0",
-    "typescript": "^5.0.4",
+    "typescript": "^5.1.3",
     "vitest": "latest",
     "zod": "latest"
   },