make-service 0.0.1 → 0.0.3

package/README.md

@@ -34,93 +34,80 @@ Or you can use it with Deno:
 import { makeService } from "https://deno.land/x/make_service/mod.ts";
 ```
 
-# Public API
+# API
 
-This library exports the `makeService` function and all primitives used to build it. You can use the primitives as you wish but the `makeService` will have all the features combined.
+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.
 
-## addQueryToInput
+# makeService
 
-Adds an object of query parameters to a string or URL.
+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.
 
-```ts
-import { addQueryToInput } from 'make-service'
+This service object can be called with every HTTP method and it will return a [`typedResponse`](#typedresponse) object as it uses the [`enhancedFetch`](#enhancedfetch) internally.
 
-const input = addQueryToInput("https://example.com", { page: "1" })
-// input = "https://example.com?page=1"
+```ts
+import { makeService } from 'make-service'
 
-const input = addQueryToInput("https://example.com?page=1", { admin: "true" })
-// input = "https://example.com?page=1&admin=true"
+const api = makeService("https://example.com/api", {
+  authorization: "Bearer 123"
+})
 
-const input = addQueryToInput(new URL("https://example.com"), { page: "1" })
-// input.toString() = "https://example.com?page=1"
+const response = await api.get("/users")
+const json = await response.json()
+//    ^? unknown
 ```
 
-## makeGetApiUrl
-
-Creates a function that will add an endpoint and a query to the base URL.
-It uses the `addQueryToInput` function internally.
+On the example above, the `api.get` will call the [`enhancedFetch`](#enhancedfetch) with the following arguments:
 
 ```ts
-import { makeGetApiUrl } from 'make-service'
-
-const getApiUrl = makeGetApiUrl("https://example.com/api")
-
-const url = getApiUrl("/users", { page: "1" })
-// url = "https://example.com/api/users?page=1"
+// "https://example.com/api/users"
+// {
+//   method: 'GET',
+//   headers: {
+//    'content-type': 'application/json',
+//    'authorization': 'Bearer 123',
+//   }
+// }
 ```
 
-## ensureStringBody
+The `api` object can be called with the same arguments as the [`enhancedFetch`](#enhancedfetch), such as `query`, object-like `body`, and `trace`.
 
-Ensures that the body is a string. If it's not, it will be stringified.
+Its [`typedResponse`](#typedresponse) can also be parsed with a zod schema. Here follows a little more complex example:
 
 ```ts
-import { ensureStringBody } from 'make-service'
-
-const body1 = ensureStringBody({ foo: "bar" })
-// body1 = '{"foo":"bar"}'
-await fetch("https://example.com/api/users", {
-  method: 'POST',
-  body: body1
-})
-
-const body2 = ensureStringBody('{"foo":"bar"}')
-// body2 = '{"foo":"bar"}'
-await fetch("https://example.com/api/users", {
-  method: 'POST',
-  body: body2
+const response = await api.get("/users", {
+  query: { search: "John" },
+  trace: (input, requestInit) => console.log(input, requestInit),
 })
+const json = await response.json(
+  z.object({
+    data: z.object({
+      users: z.array(z.object({
+        name: z.string()
+      }))
+    })
+  })
+  // transformed and caught
+  .transform(({ data: { users } }) => users)
+  .catch([])
+)
+// type of json will be { name: string }[]
+// the URL called will be "https://example.com/api/users?search=John"
 ```
 
-## typedResponse
-
-A type-safe wrapper around the `Response` object. It adds a `json` and `text` method that will parse the response with a given zod schema. If you don't provide a schema, it will return `unknown` instead of `any`, then you can also give it a generic to type cast the result.
-
+It accepts more HTTP verbs:
 ```ts
-import { typedResponse } from 'make-service'
-
-// With JSON
-const response = new Response(JSON.stringify({ foo: "bar" }))
-const json = await typedResponse(response).json()
-//    ^? unknown
-const json = await typedResponse(response).json<{ foo: string }>()
-//    ^? { foo: string }
-const json = await typedResponse(response).json(z.object({ foo: z.string() }))
-//    ^? { foo: string }
-
-// With text
-const response = new Response("foo")
-const text = await typedResponse(response).text()
-//    ^? string
-const text = await typedResponse(response).text<`foo${string}`>()
-//    ^? `foo${string}`
-const text = await typedResponse(response).text(z.string().email())
-//    ^? string
+await api.post("/users", { body: { name: "John" } })
+await api.put("/users/1", { body: { name: "John" } })
+await api.patch("/users/1", { body: { name: "John" } })
+await api.delete("/users/1")
+await api.head("/users")
+await api.options("/users")
 ```
 
 ## enhancedFetch
 
 A wrapper around the `fetch` API.
-It uses the `addQueryToInput`, `ensureStringBody` function internally and returns a `typedResponse` instead of a `Response`.
+It returns a [`TypedResponse`](#typedresponse) instead of a `Response`.
 
 ```ts
 import { enhancedFetch } from 'make-service'
@@ -134,7 +121,9 @@ const json = await response.json()
 // You can pass it a generic or schema to type the result
 ```
 
-This function accepts the same arguments as the `fetch` API - with exception of JSON-like body -, and it also accepts an object-like `query` and a `trace` function that will be called with the `input` and `requestInit` arguments.
+This function accepts the same arguments as the `fetch` API - with exception of [JSON-like body](/src/make-service.ts) -, and it also accepts an object-like [`query`](/src/make-service.ts) and a `trace` function that will be called with the `input` and `requestInit` arguments.
+
+This slightly different `RequestInit` is typed as `EnhancedRequestInit`.
 
 ```ts
 import { enhancedFetch } from 'make-service'
@@ -157,70 +146,31 @@ await enhancedFetch("https://example.com/api/users", {
 
 Notice: the `enhancedFetch` adds a `'content-type': 'application/json'` header by default.
 
-# makeService
-
-The main function of this lib is built on top of the previous primitives and it allows you to create an "API" object with a `baseURL` and common `headers` for every request.
+## typedResponse
 
-This "api" object can be called with every HTTP method and it will return a `typedResponse` object as it uses the `enhancedFetch` internally.
+A type-safe wrapper around the `Response` object. It adds a `json` and `text` method that will parse the response with a given zod schema. If you don't provide a schema, it will return `unknown` instead of `any`, then you can also give it a generic to type cast the result.
 
 ```ts
-import { makeService } from 'make-service'
-
-const api = makeService("https://example.com/api", {
-  authorization: "Bearer 123"
-})
+import { typedResponse } from 'make-service'
+import type { TypedResponse } from 'make-service'
 
-const response = await api.get("/users")
-const json = await response.json()
+// With JSON
+const response: TypedResponse = new Response(JSON.stringify({ foo: "bar" }))
+const json = await typedResponse(response).json()
 //    ^? unknown
-```
-
-On the example above, the `api.get` will call the `enhancedFetch` with the following arguments:
-
-```ts
-// "https://example.com/api/users"
-// {
-//   method: 'GET',
-//   headers: {
-//    'content-type': 'application/json',
-//    'authorization': 'Bearer 123',
-//   }
-// }
-```
-
-The `api` object can be called with the same arguments as the `enhancedFetch`, such as `query`, object-like `body`, and `trace`.
-
-Its `typedResponse` can also be parsed with a zod schema. Here follows a little more complex example:
-
-```ts
-const response = await api.get("/users", {
-  query: { search: "John" },
-  trace: (...args: any[]) => console.log(...args)
-})
-const json = await response.json(
-  z.object({
-    data: z.object({
-      users: z.array(z.object({
-        name: z.string()
-      }))
-    })
-  })
-  // transformed and catched
-  .transform(({ data: { users } }) => users)
-  .catch([])
-)
-// type of json will be { name: string }[]
-// the URL called will be "https://example.com/api/users?search=John"
-```
+const json = await typedResponse(response).json<{ foo: string }>()
+//    ^? { foo: string }
+const json = await typedResponse(response).json(z.object({ foo: z.string() }))
+//    ^? { foo: string }
 
-It accepts more HTTP verbs:
-```ts
-await api.post("/users", { body: { name: "John" } })
-await api.put("/users/1", { body: { name: "John" } })
-await api.patch("/users/1", { body: { name: "John" } })
-await api.delete("/users/1")
-await api.head("/users")
-await api.options("/users")
+// With text
+const response: TypedResponse = new Response("foo")
+const text = await typedResponse(response).text()
+//    ^? string
+const text = await typedResponse(response).text<`foo${string}`>()
+//    ^? `foo${string}`
+const text = await typedResponse(response).text(z.string().email())
+//    ^? string
 ```
 
 ## Thank you

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+declare const HTTP_METHODS: readonly ["get", "post", "put", "delete", "patch", "options", "head"];
+
+/**
+ * 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;
+};
+type JSONValue = string | number | boolean | {
+    [x: string]: JSONValue;
+} | Array<JSONValue>;
+type SearchParams = ConstructorParameters<typeof URLSearchParams>[0];
+type TypedResponse = Omit<Response, 'json' | 'text'> & {
+    json: TypedResponseJson;
+    text: TypedResponseText;
+};
+type EnhancedRequestInit = Omit<RequestInit, 'body'> & {
+    body?: JSONValue;
+    query?: SearchParams;
+    trace?: (...args: Parameters<typeof fetch>) => void;
+};
+type ServiceRequestInit = Omit<EnhancedRequestInit, 'method'>;
+type HTTPMethod = (typeof HTTP_METHODS)[number];
+type TypedResponseJson = ReturnType<typeof getJson>;
+type TypedResponseText = ReturnType<typeof getText>;
+
+/**
+ * @param input a string or URL to which the query parameters will be added
+ * @param searchParams the query parameters
+ * @returns the input with the query parameters added with the same type as the input
+ */
+declare function addQueryToInput(input: string | URL, searchParams?: SearchParams): string | URL;
+/**
+ * @param baseURL the base path to the API
+ * @returns a function that receives a path and an object of query parameters and returns a URL
+ */
+declare function makeGetApiUrl(baseURL: string): (path: string, searchParams?: SearchParams) => string | URL;
+/**
+ * It hacks the Response object to add typed json and text methods
+ * @param response the Response to be proxied
+ * @returns a Response with typed json and text methods
+ * @example const response = await fetch("https://example.com/api/users");
+ * const users = await response.json(userSchema);
+ * //    ^? User[]
+ * const untyped = await response.json();
+ * //    ^? unknown
+ * const text = await response.text();
+ * //    ^? string
+ * const typedJson = await response.json<User[]>();
+ * //    ^? User[]
+ */
+declare function typedResponse(response: Response): TypedResponse;
+/**
+ * @param body the JSON-like body of the request
+ * @returns the body stringified if it is not a string
+ */
+declare function ensureStringBody(body?: JSONValue): string | undefined;
+/**
+ *
+ * @param input a string or URL to be fetched
+ * @param requestInit the requestInit to be passed to the fetch request. It is the same as the `RequestInit` type, but it also accepts a JSON-like `body` and an object-like `query` parameter.
+ * @param requestInit.body the body of the request. It will be automatically stringified so you can send a JSON-like object
+ * @param requestInit.query the query parameters to be added to the URL
+ * @param requestInit.trace a function that receives the URL and the requestInit and can be used to log the request
+ * @returns a Response with typed json and text methods
+ * @example const response = await fetch("https://example.com/api/users");
+ * const users = await response.json(userSchema);
+ * //    ^? User[]
+ * const untyped = await response.json();
+ * //    ^? unknown
+ */
+declare function enhancedFetch(input: string | URL, requestInit?: EnhancedRequestInit): Promise<TypedResponse>;
+/**
+ *
+ * @param baseURL the base URL to the API
+ * @param baseHeaders any headers that should be sent with 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);
+ * const response = await api.get("/users")
+ * const users = await response.json(userSchema);
+ * //    ^? User[]
+ */
+declare function makeService(baseURL: string, baseHeaders?: HeadersInit): {
+    get: (path: string, requestInit?: ServiceRequestInit) => Promise<TypedResponse>;
+    post: (path: string, requestInit?: ServiceRequestInit) => Promise<TypedResponse>;
+    put: (path: string, requestInit?: ServiceRequestInit) => Promise<TypedResponse>;
+    delete: (path: string, requestInit?: ServiceRequestInit) => Promise<TypedResponse>;
+    patch: (path: string, requestInit?: ServiceRequestInit) => Promise<TypedResponse>;
+    options: (path: string, requestInit?: ServiceRequestInit) => Promise<TypedResponse>;
+    head: (path: string, requestInit?: ServiceRequestInit) => Promise<TypedResponse>;
+};
+
+export { EnhancedRequestInit, HTTPMethod, JSONValue, Schema, SearchParams, ServiceRequestInit, TypedResponse, TypedResponseJson, TypedResponseText, addQueryToInput, enhancedFetch, ensureStringBody, makeGetApiUrl, makeService, typedResponse };

package/dist/index.js

@@ -0,0 +1,135 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  addQueryToInput: () => addQueryToInput,
+  enhancedFetch: () => enhancedFetch,
+  ensureStringBody: () => ensureStringBody,
+  makeGetApiUrl: () => makeGetApiUrl,
+  makeService: () => makeService,
+  typedResponse: () => typedResponse
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/constants.ts
+var HTTP_METHODS = [
+  "get",
+  "post",
+  "put",
+  "delete",
+  "patch",
+  "options",
+  "head"
+];
+
+// src/internals.ts
+function getJson(response) {
+  return async (schema) => {
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    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;
+  };
+}
+function isHTTPMethod(method) {
+  return HTTP_METHODS.includes(method);
+}
+
+// src/make-service.ts
+function addQueryToInput(input, searchParams) {
+  if (!searchParams)
+    return input;
+  if (searchParams && typeof input === "string") {
+    const separator = input.includes("?") ? "&" : "?";
+    return `${input}${separator}${new URLSearchParams(searchParams)}`;
+  }
+  if (searchParams && input instanceof URL) {
+    input.search = new URLSearchParams(searchParams).toString();
+  }
+  return input;
+}
+function makeGetApiUrl(baseURL) {
+  return (path, searchParams) => addQueryToInput(`${baseURL}${path}`, searchParams);
+}
+function typedResponse(response) {
+  return new Proxy(response, {
+    get(target, prop) {
+      if (prop === "json")
+        return getJson(target);
+      if (prop === "text")
+        return getText(target);
+      return target[prop];
+    }
+  });
+}
+function ensureStringBody(body) {
+  if (typeof body === "undefined")
+    return;
+  if (typeof body === "string")
+    return body;
+  return JSON.stringify(body);
+}
+async function enhancedFetch(input, requestInit) {
+  const { query, trace, ...reqInit } = requestInit != null ? requestInit : {};
+  const headers = { "content-type": "application/json", ...reqInit.headers };
+  const url = addQueryToInput(input, query);
+  const body = ensureStringBody(reqInit.body);
+  const enhancedReqInit = { ...reqInit, headers, body };
+  trace == null ? void 0 : trace(url, enhancedReqInit);
+  const request = new Request(url, enhancedReqInit);
+  const response = await fetch(request);
+  return typedResponse(response);
+}
+function makeService(baseURL, baseHeaders) {
+  const service = (method) => {
+    return async (path, requestInit = {}) => {
+      const response = await enhancedFetch(`${baseURL}${path}`, {
+        ...requestInit,
+        method,
+        headers: { ...baseHeaders, ...requestInit == null ? void 0 : requestInit.headers }
+      });
+      return response;
+    };
+  };
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (isHTTPMethod(prop))
+        return service(prop);
+      throw new Error(`Invalid HTTP method: ${prop.toString()}`);
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  addQueryToInput,
+  enhancedFetch,
+  ensureStringBody,
+  makeGetApiUrl,
+  makeService,
+  typedResponse
+});

package/dist/index.mjs

@@ -0,0 +1,103 @@
+// src/constants.ts
+var HTTP_METHODS = [
+  "get",
+  "post",
+  "put",
+  "delete",
+  "patch",
+  "options",
+  "head"
+];
+
+// src/internals.ts
+function getJson(response) {
+  return async (schema) => {
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    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;
+  };
+}
+function isHTTPMethod(method) {
+  return HTTP_METHODS.includes(method);
+}
+
+// src/make-service.ts
+function addQueryToInput(input, searchParams) {
+  if (!searchParams)
+    return input;
+  if (searchParams && typeof input === "string") {
+    const separator = input.includes("?") ? "&" : "?";
+    return `${input}${separator}${new URLSearchParams(searchParams)}`;
+  }
+  if (searchParams && input instanceof URL) {
+    input.search = new URLSearchParams(searchParams).toString();
+  }
+  return input;
+}
+function makeGetApiUrl(baseURL) {
+  return (path, searchParams) => addQueryToInput(`${baseURL}${path}`, searchParams);
+}
+function typedResponse(response) {
+  return new Proxy(response, {
+    get(target, prop) {
+      if (prop === "json")
+        return getJson(target);
+      if (prop === "text")
+        return getText(target);
+      return target[prop];
+    }
+  });
+}
+function ensureStringBody(body) {
+  if (typeof body === "undefined")
+    return;
+  if (typeof body === "string")
+    return body;
+  return JSON.stringify(body);
+}
+async function enhancedFetch(input, requestInit) {
+  const { query, trace, ...reqInit } = requestInit != null ? requestInit : {};
+  const headers = { "content-type": "application/json", ...reqInit.headers };
+  const url = addQueryToInput(input, query);
+  const body = ensureStringBody(reqInit.body);
+  const enhancedReqInit = { ...reqInit, headers, body };
+  trace == null ? void 0 : trace(url, enhancedReqInit);
+  const request = new Request(url, enhancedReqInit);
+  const response = await fetch(request);
+  return typedResponse(response);
+}
+function makeService(baseURL, baseHeaders) {
+  const service = (method) => {
+    return async (path, requestInit = {}) => {
+      const response = await enhancedFetch(`${baseURL}${path}`, {
+        ...requestInit,
+        method,
+        headers: { ...baseHeaders, ...requestInit == null ? void 0 : requestInit.headers }
+      });
+      return response;
+    };
+  };
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (isHTTPMethod(prop))
+        return service(prop);
+      throw new Error(`Invalid HTTP method: ${prop.toString()}`);
+    }
+  });
+}
+export {
+  addQueryToInput,
+  enhancedFetch,
+  ensureStringBody,
+  makeGetApiUrl,
+  makeService,
+  typedResponse
+};

package/package.json

@@ -1,33 +1,37 @@
 {
-  "module": "./esm/index.js",
-  "main": "./script/index.js",
-  "types": "./types/index.d.ts",
   "name": "make-service",
-  "version": "0.0.1",
-  "description": "Some utilities to extend the \"fetch\" API to better interact with external APIs.",
+  "version": "0.0.3",
+  "description": "Some utilities to extend the 'fetch' API to better interact with external APIs.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "author": "Gustavo Guichard <@gugaguichard>",
   "license": "MIT",
-  "author": "Gustavo Guichard",
-  "bugs": {
-    "url": "https://github.com/gustavoguichard/make-service/issues"
+  "scripts": {
+    "build": "tsup ./src/index.ts --format esm,cjs --dts",
+    "dev": "tsup ./src/index.ts --format esm,cjs --watch --dts",
+    "lint": "eslint *.ts*",
+    "tsc": "tsc",
+    "test": "vitest run"
   },
-  "homepage": "https://github.com/gustavoguichard/make-service",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./types/index.d.ts",
-        "default": "./esm/index.js"
-      },
-      "require": {
-        "types": "./types/index.d.ts",
-        "default": "./script/index.js"
-      }
-    }
+  "devDependencies": {
+    "eslint": "latest",
+    "jsdom": "^21.1.1",
+    "prettier": "latest",
+    "tsup": "^6.7.0",
+    "typescript": "^5.0.4",
+    "vitest": "latest",
+    "zod": "latest"
   },
-  "dependencies": {
-    "@deno/shim-deno": "~0.12.0",
-    "undici": "^5.14.0"
+  "files": [
+    "README.md",
+    "./dist/*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gugaguichard/make-service.git"
   },
-  "devDependencies": {
-    "@types/node": "^18.11.9"
+  "bugs": {
+    "url": "https://github.com/gugaguichard/make-service/issues"
   }
-}
+}