make-service 1.0.0 → 1.1.0

package/README.md

@@ -8,9 +8,10 @@ It adds a set of little features and allows you to parse responses with [zod](ht
 - 🤩 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.
 - 🏗️ Compose URL from the base by just calling the endpoints and an object-like `query`.
-- 🐾 Replaces URL wildcards with an object of `params`.
+- 🐾 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.
 - 🐛 Accepts a `trace` function for debugging.
+- 🔥 Transforms responses and payloads back and forth to support interchangeability of casing styles (kebab-case -> camelCase -> snake_case -> kebab-case).
 
 ## Example
 
@@ -42,13 +43,14 @@ const users = await response.json(usersSchema);
   - [makeFetcher](#makefetcher)
   - [enhancedFetch](#enhancedfetch)
   - [typedResponse](#typedresponse)
+- [Payload transformers](#payload-transformers)
 - [Other available primitives](#other-available-primitives)
   - [addQueryToURL](#addquerytourl)
   - [ensureStringBody](#ensurestringbody)
   - [makeGetApiURL](#makegetapiurl)
   - [mergeHeaders](#mergeheaders)
   - [replaceURLParams](#replaceurlparams)
-  - [Thank you](#thank-you)
+- [Acknowledgements](#acknowledgements)
 
 # Installation
 
@@ -274,6 +276,12 @@ const response = await service.get("/users/:id/article/:articleId", {
 
 // It will call "https://example.com/api/users/2/article/3"
 ```
+The `params` object will not type-check if the given object doesn't follow the path structure.
+```ts
+// @ts-expect-error
+service.get("/users/:id", { params: { id: "2", foobar: "foo" } })
+```
+
 This is achieved by using the [`replaceURLParams`](#replaceurlparams) function internally.
 
 ### Trace
@@ -384,6 +392,34 @@ const text = await response.text(z.string().email())
 //    ^? string
 ```
 
+# Payload transformers
+The `make-service` library has a few payload transformers that you can use to transform the request body before sending it or the response body after returning from the server.
+The resulting type will be **properly typed** 🤩.
+```ts
+import { makeService, kebabToCamel, camelToKebab } from 'make-service'
+
+const service = makeService("https://example.com/api")
+const response = service.get("/users")
+const users = await response.json(
+  z
+    .array(z.object({ "first-name": z.string(), contact: z.object({ "home-address": z.string() }) }))
+    .transform(kebabToCamel)
+)
+console.log(users)
+//          ^? { firstName: string, contact: { homeAddress: string } }[]
+
+const body = camelToKebab({ firstName: "John", contact: { homeAddress: "123 Main St" } })
+//    ^? { "first-name": string, contact: { "home-address": string } }
+service.patch("/users/:id", { body, params: { id: "1" } })
+```
+The available transformations are:
+- `camelToKebab`: `"someProp" -> "some-prop"`
+- `camelToSnake`: `"someProp" -> "some_prop"`
+- `kebabToCamel`: `"some-prop" -> "someProp"`
+- `kebabToSnake`: `"some-prop" -> "some_prop"`
+- `snakeToCamel`: `"some_prop" -> "someProp"`
+- `snakeToKebab`: `"some_prop" -> "some-prop"`
+
 # Other available primitives
 This little library has plenty of other useful functions that you can use to build your own services and interactions with external APIs.
 
@@ -503,5 +539,13 @@ const url = replaceURLParams(
 // It will return: "https://example.com/users/2/posts/3"
 ```
 
-## Thank you
+The params will be **strongly-typed** which means they will be validated against the URL structure and will not type-check if the given object does not match that structure.
+
+# Acknowledgements
+This library is part of a code I've been carrying around for a while through many projects.
+
+- [croods](https://github.com/seasonedcc/croods) by [@danielweinmann](https://github.com/danielweinmann) - a react data-layer library from pre-ReactQuery/pre-SWR era - gave me ideas and experience dealing with APIs after spending a lot of time in that codebase.
+- [zod](https://zod.dev/) by [@colinhacks](https://github.com/colinhacks) changed my mindset about how to deal with external data.
+- [zod-fetch](https://github.com/mattpocock/zod-fetch) by [@mattpocock](https://github.com/mattpocock) for the inspiration, when I realized I had a similar solution that could be extracted and be available for everyone to use.
+
 I really appreciate your feedback and contributions. If you have any questions, feel free to open an issue or contact me on [Twitter](https://twitter.com/gugaguichard).

package/dist/index.d.ts

@@ -23,26 +23,26 @@ type TypedResponse = Omit<Response, 'json' | 'text'> & {
     json: TypedResponseJson;
     text: TypedResponseText;
 };
-type EnhancedRequestInit = Omit<RequestInit, 'body' | 'method'> & {
+type PathParams<T> = T extends string ? ExtractPathParams<T> extends Record<string, unknown> ? ExtractPathParams<T> : Record<string, string> : Record<string, string>;
+type EnhancedRequestInit<T = string> = Omit<RequestInit, 'body' | 'method'> & {
     method?: HTTPMethod | Lowercase<HTTPMethod>;
     body?: JSONValue | BodyInit | null;
     query?: SearchParams;
-    params?: Record<string, string>;
+    params?: PathParams<T>;
     trace?: (...args: Parameters<typeof fetch>) => void;
 };
-type ServiceRequestInit = Omit<EnhancedRequestInit, 'method'>;
+type ServiceRequestInit<T = string> = Omit<EnhancedRequestInit<T>, 'method'>;
 type HTTPMethod = (typeof HTTP_METHODS)[number];
 type TypedResponseJson = ReturnType<typeof getJson>;
 type TypedResponseText = ReturnType<typeof getText>;
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
-type NoEmpty<T> = keyof T extends never ? never : T;
-type PathParams<T extends string> = NoEmpty<T extends `${infer _}:${infer Param}/${infer Rest}` ? Prettify<{
+type ExtractPathParams<T extends string> = T extends `${infer _}:${infer Param}/${infer Rest}` ? Prettify<Omit<{
     [K in Param]: string;
-} & PathParams<Rest>> : T extends `${infer _}:${infer Param}` ? {
+} & ExtractPathParams<Rest>, ''>> : T extends `${infer _}:${infer Param}` ? {
     [K in Param]: string;
-} : {}>;
+} : {};
 
 /**
  * It hacks the Response object to add typed json and text methods
@@ -73,7 +73,7 @@ declare function typedResponse(response: Response): TypedResponse;
  * const untyped = await response.json();
  * //    ^? unknown
  */
-declare function enhancedFetch(url: string | URL, requestInit?: EnhancedRequestInit): Promise<TypedResponse>;
+declare function enhancedFetch<T extends string | URL>(url: T, requestInit?: EnhancedRequestInit<T>): Promise<TypedResponse>;
 /**
  *
  * @param baseURL the base URL to be fetched in every request
@@ -85,7 +85,7 @@ declare function enhancedFetch(url: string | URL, requestInit?: EnhancedRequestI
  * const users = await response.json(userSchema);
  * //    ^? User[]
  */
-declare function makeFetcher(baseURL: string | URL, baseHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>)): (path: string, requestInit?: EnhancedRequestInit) => Promise<TypedResponse>;
+declare function makeFetcher(baseURL: string | URL, baseHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>)): <T extends string>(path: T, requestInit?: EnhancedRequestInit<T>) => Promise<TypedResponse>;
 /**
  *
  * @param baseURL the base URL to the API
@@ -97,7 +97,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", (path: string, requestInit?: ServiceRequestInit) => Promise<TypedResponse>>;
+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>>;
 
 /**
  * @param url a string or URL to which the query parameters will be added
@@ -127,6 +127,52 @@ declare function mergeHeaders(...entries: (HeadersInit | [string, undefined][] |
  * @param params the params map to be replaced in the url
  * @returns the url with the params replaced and with the same type as the given url
  */
-declare function replaceURLParams<T extends string | URL>(url: string | URL, params: EnhancedRequestInit['params']): T;
+declare function replaceURLParams<T extends string | URL>(url: T, params: PathParams<T>): T;
 
-export { EnhancedRequestInit, HTTPMethod, JSONValue, PathParams, Schema, SearchParams, ServiceRequestInit, TypedResponse, TypedResponseJson, TypedResponseText, addQueryToURL, enhancedFetch, ensureStringBody, makeFetcher, makeGetApiURL, makeService, mergeHeaders, replaceURLParams, typedResponse };
+type KebabToCamel<Str> = Str extends `${infer First}-${infer Rest}` ? `${First}${Capitalize<KebabToCamel<Rest>>}` : Str;
+type SnakeToCamel<Str> = Str extends `${infer First}_${infer Rest}` ? `${First}${Capitalize<SnakeToCamel<Rest>>}` : Str;
+type KebabToSnake<Str> = Str extends `${infer First}-${infer Rest}` ? `${First}_${KebabToSnake<Rest>}` : Str;
+type SnakeToKebab<Str> = Str extends `${infer First}_${infer Rest}` ? `${First}-${SnakeToKebab<Rest>}` : Str;
+type HandleFirstChar<Str> = Str extends `${infer First}${infer Rest}` ? `${Lowercase<First>}${Rest}` : Str;
+type CamelToSnakeFn<Str> = Str extends `${infer First}${infer Rest}` ? `${First extends Capitalize<First> ? '_' : ''}${Lowercase<First>}${CamelToSnakeFn<Rest>}` : Str;
+type CamelToSnake<Str> = CamelToSnakeFn<HandleFirstChar<Str>>;
+type CamelToKebabFn<Str> = Str extends `${infer First}${infer Rest}` ? `${First extends Capitalize<First> ? '-' : ''}${Lowercase<First>}${CamelToKebabFn<Rest>}` : Str;
+type CamelToKebab<Str> = CamelToKebabFn<HandleFirstChar<Str>>;
+type DeepKebabToCamel<T> = T extends [any, ...any] ? {
+    [I in keyof T]: DeepKebabToCamel<T[I]>;
+} : T extends (infer V)[] ? DeepKebabToCamel<V>[] : {
+    [K in keyof T as KebabToCamel<K>]: DeepKebabToCamel<T[K]>;
+};
+declare function kebabToCamel<T>(obj: T): DeepKebabToCamel<T>;
+type DeepSnakeToCamel<T> = T extends [any, ...any] ? {
+    [I in keyof T]: DeepSnakeToCamel<T[I]>;
+} : T extends (infer V)[] ? DeepSnakeToCamel<V>[] : {
+    [K in keyof T as SnakeToCamel<K>]: DeepSnakeToCamel<T[K]>;
+};
+declare function snakeToCamel<T>(obj: T): DeepSnakeToCamel<T>;
+type DeepCamelToSnake<T> = T extends [any, ...any] ? {
+    [I in keyof T]: DeepCamelToSnake<T[I]>;
+} : T extends (infer V)[] ? DeepCamelToSnake<V>[] : {
+    [K in keyof T as CamelToSnake<K>]: DeepCamelToSnake<T[K]>;
+};
+declare function camelToSnake<T>(obj: T): DeepCamelToSnake<T>;
+type DeepCamelToKebab<T> = T extends [any, ...any] ? {
+    [I in keyof T]: DeepCamelToKebab<T[I]>;
+} : T extends (infer V)[] ? DeepCamelToKebab<V>[] : {
+    [K in keyof T as CamelToKebab<K>]: DeepCamelToKebab<T[K]>;
+};
+declare function camelToKebab<T>(obj: T): DeepCamelToKebab<T>;
+type DeepSnakeToKebab<T> = T extends [any, ...any] ? {
+    [I in keyof T]: DeepSnakeToKebab<T[I]>;
+} : T extends (infer V)[] ? DeepSnakeToKebab<V>[] : {
+    [K in keyof T as SnakeToKebab<K>]: DeepSnakeToKebab<T[K]>;
+};
+declare function snakeToKebab<T>(obj: T): DeepSnakeToKebab<T>;
+type DeepKebabToSnake<T> = T extends [any, ...any] ? {
+    [I in keyof T]: DeepKebabToSnake<T[I]>;
+} : T extends (infer V)[] ? DeepKebabToSnake<V>[] : {
+    [K in keyof T as KebabToSnake<K>]: DeepKebabToSnake<T[K]>;
+};
+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 };

package/dist/index.js

@@ -21,13 +21,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   addQueryToURL: () => addQueryToURL,
+  camelToKebab: () => camelToKebab,
+  camelToSnake: () => camelToSnake,
   enhancedFetch: () => enhancedFetch,
   ensureStringBody: () => ensureStringBody,
+  kebabToCamel: () => kebabToCamel,
+  kebabToSnake: () => kebabToSnake,
   makeFetcher: () => makeFetcher,
   makeGetApiURL: () => makeGetApiURL,
   makeService: () => makeService,
   mergeHeaders: () => mergeHeaders,
   replaceURLParams: () => replaceURLParams,
+  snakeToCamel: () => snakeToCamel,
+  snakeToKebab: () => snakeToKebab,
   typedResponse: () => typedResponse
 });
 module.exports = __toCommonJS(src_exports);
@@ -172,15 +178,69 @@ function makeService(baseURL, baseHeaders) {
   }
   return service;
 }
+
+// src/transforms.ts
+function words(str) {
+  const matches = str.match(
+    /[A-Z]{2,}(?=[A-Z][a-z]+[0-9]*|\b)|[A-Z]?[a-z]+[0-9]*|[A-Z]|[0-9]+/g
+  );
+  return matches ? Array.from(matches) : [str];
+}
+function toCamelCase(str) {
+  const result = words(str).map((x) => x.slice(0, 1).toUpperCase() + x.slice(1).toLowerCase()).join("");
+  return result.slice(0, 1).toLowerCase() + result.slice(1);
+}
+function toKebabCase(str) {
+  return words(str).map((x) => x.toLowerCase()).join("-");
+}
+function toSnakeCase(str) {
+  return words(str).map((x) => x.toLowerCase()).join("_");
+}
+function deepTransformKeys(obj, transform) {
+  if (!["object", "array"].includes(typeOf(obj)))
+    return obj;
+  if (Array.isArray(obj)) {
+    return obj.map((x) => deepTransformKeys(x, transform));
+  }
+  const res = {};
+  for (const key in obj) {
+    res[transform(key)] = deepTransformKeys(obj[key], transform);
+  }
+  return res;
+}
+function kebabToCamel(obj) {
+  return deepTransformKeys(obj, toCamelCase);
+}
+function snakeToCamel(obj) {
+  return deepTransformKeys(obj, toCamelCase);
+}
+function camelToSnake(obj) {
+  return deepTransformKeys(obj, toSnakeCase);
+}
+function camelToKebab(obj) {
+  return deepTransformKeys(obj, toKebabCase);
+}
+function snakeToKebab(obj) {
+  return deepTransformKeys(obj, toKebabCase);
+}
+function kebabToSnake(obj) {
+  return deepTransformKeys(obj, toSnakeCase);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   addQueryToURL,
+  camelToKebab,
+  camelToSnake,
   enhancedFetch,
   ensureStringBody,
+  kebabToCamel,
+  kebabToSnake,
   makeFetcher,
   makeGetApiURL,
   makeService,
   mergeHeaders,
   replaceURLParams,
+  snakeToCamel,
+  snakeToKebab,
   typedResponse
 });

package/dist/index.mjs

@@ -138,14 +138,68 @@ function makeService(baseURL, baseHeaders) {
   }
   return service;
 }
+
+// src/transforms.ts
+function words(str) {
+  const matches = str.match(
+    /[A-Z]{2,}(?=[A-Z][a-z]+[0-9]*|\b)|[A-Z]?[a-z]+[0-9]*|[A-Z]|[0-9]+/g
+  );
+  return matches ? Array.from(matches) : [str];
+}
+function toCamelCase(str) {
+  const result = words(str).map((x) => x.slice(0, 1).toUpperCase() + x.slice(1).toLowerCase()).join("");
+  return result.slice(0, 1).toLowerCase() + result.slice(1);
+}
+function toKebabCase(str) {
+  return words(str).map((x) => x.toLowerCase()).join("-");
+}
+function toSnakeCase(str) {
+  return words(str).map((x) => x.toLowerCase()).join("_");
+}
+function deepTransformKeys(obj, transform) {
+  if (!["object", "array"].includes(typeOf(obj)))
+    return obj;
+  if (Array.isArray(obj)) {
+    return obj.map((x) => deepTransformKeys(x, transform));
+  }
+  const res = {};
+  for (const key in obj) {
+    res[transform(key)] = deepTransformKeys(obj[key], transform);
+  }
+  return res;
+}
+function kebabToCamel(obj) {
+  return deepTransformKeys(obj, toCamelCase);
+}
+function snakeToCamel(obj) {
+  return deepTransformKeys(obj, toCamelCase);
+}
+function camelToSnake(obj) {
+  return deepTransformKeys(obj, toSnakeCase);
+}
+function camelToKebab(obj) {
+  return deepTransformKeys(obj, toKebabCase);
+}
+function snakeToKebab(obj) {
+  return deepTransformKeys(obj, toKebabCase);
+}
+function kebabToSnake(obj) {
+  return deepTransformKeys(obj, toSnakeCase);
+}
 export {
   addQueryToURL,
+  camelToKebab,
+  camelToSnake,
   enhancedFetch,
   ensureStringBody,
+  kebabToCamel,
+  kebabToSnake,
   makeFetcher,
   makeGetApiURL,
   makeService,
   mergeHeaders,
   replaceURLParams,
+  snakeToCamel,
+  snakeToKebab,
   typedResponse
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "make-service",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Some utilities to extend the 'fetch' API to better interact with external APIs.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",