feat: api config object

Author: ddadaal

.changeset/little-trains-brush.md

@@ -0,0 +1,6 @@
+---
+"@ddadaal/next-typed-api-routes-runtime": minor
+"@ddadaal/next-typed-api-routes-cli": minor
+---
+
+Add api config object used to configure API client

README.md

@@ -70,13 +70,24 @@ export default route<TestApiSchema>("TestApiSchema", async (req) => {
 });
 ```
 
-3. Run `npx ntar schema && npx ntar client`
+3. Create `apiClient` object
+
+Create `src/apis/client.ts` with the following content
+
+```ts
+import { createApiClient } from "@ddadaal/next-typed-api-routes-runtime";
+
+// Pass custom client config here
+export const apiClient = createApiClient({});
+```
+
+4. Run `npx ntar schema && npx ntar client`
 
 `api-routes-schemas.json` will be generated at cwd. You should never edit it directly. The project cannot start without this file.
 
 `src/apis/api.ts` will be generated at `src/apis`.
 
-4. Import the `api` variable from `src/apis/api.ts` to use the client.
+5. Import the `api` variable from `src/apis/api.ts` to use the client.
 
 ```ts
 import { api } from "src/apis/api";
@@ -146,39 +157,6 @@ interface TestSchema {
 }
 ```
 
-# Custom basePath
-
-Custom basePath is now supported. The generated API client will use `NEXT_PUBLIC_BASE_PATH` env for the base path for all the api routes. If you are upgrading from an older version, you should run `npx ntar client` to regenerate the api file to leverage this feature. 
-
-To keep the basePath config consistent in both Next.js and this library, you can set `basePath: process.env.NEXT_PUBLIC_BASE_PATH` in the `next.config.js`, and use the `NEXT_PUBLIC_BASE_PATH` env. Check out [the Next.js doc](https://nextjs.org/docs/api-reference/next.config.js/basepath) to configure basePath for Next.js.
-
-```js
-// next.config.js
-module.exports = {
-  basePath: process.env.NEXT_PUBLIC_BASE_PATH,
-}
-```
-
-You can also use `--basePathVar` option of `ntar` cli to customize the value of base path. 
-
-For example, when running `npx ntar client --basePathVar publicConfig.BASE_PATH`, the client file will look like:
-
-```tsx
-import { fromApi } from "@ddadaal/next-typed-api-routes-runtime/lib/client";
-import { join } from "path";
-
-import type { LoginSchema } from "src/pages/api/login/[username]";
-
-// the value of basePath is the same as the basePathVar option
-const basePath = publicConfig.BASE_PATH; 
-
-export const api = {
-  login: fromApi<LoginSchema>("GET", join(basePath, "/api/login/[username]")),
-};
-```
-
-If your `basePath` declaration needs imports, you can also use `extraImports` cli option to add extra imports into the client file. Multiple `extraImports` options can be specified.
-
 # Tips
 
 - All schemas and used models must have globally unique name

example/src/apis/api.ts

@@ -1,21 +1,15 @@
 /* eslint-disable max-len */
 
-import { fromStaticRoute, fromTypeboxRoute, fromZodRoute } from "@ddadaal/next-typed-api-routes-runtime/lib/client";
-import { join } from "path";
+import { apiClient } from "src/apis/client";
 import type { LoginSchema } from "src/pages/api/login/[username]";
 import type { RegisterSchema } from "src/pages/api/register/index";
 import type { TypeboxRouteSchema } from "src/pages/api/typeboxRoute/[test]";
 import type { ZodRouteSchema } from "src/pages/api/zodRoute/[test]";
 
 
-
-const basePath = process.env.NEXT_PUBLIC_BASE_PATH || "";
-
-
 export const api = {
-  login: fromStaticRoute<LoginSchema>("GET", join(basePath, "/api/login/[username]")),
-  register: fromStaticRoute<RegisterSchema>("POST", join(basePath, "/api/register")),
-  typeboxRoute: fromTypeboxRoute<typeof TypeboxRouteSchema>("POST", join(basePath, "/api/typeboxRoute/[test]")),
-  zodRoute: fromZodRoute<typeof ZodRouteSchema>("POST", join(basePath, "/api/zodRoute/[test]")),
+  login: apiClient.fromStaticRoute<LoginSchema>("GET", "/api/login/[username]"),
+  register: apiClient.fromStaticRoute<RegisterSchema>("POST", "/api/register"),
+  typeboxRoute: apiClient.fromTypeboxRoute<typeof TypeboxRouteSchema>("POST", "/api/typeboxRoute/[test]"),
+  zodRoute: apiClient.fromZodRoute<typeof ZodRouteSchema>("POST", "/api/zodRoute/[test]"),
 };
-  

example/src/apis/client.ts

@@ -0,0 +1,5 @@
+import { createApiClient } from "@ddadaal/next-typed-api-routes-runtime";
+
+export const apiClient = createApiClient({
+  baseUrl: typeof window === "undefined" ? `http://localhost:${process.env.PORT || 3000}` : "",
+});

packages/cli/src/generateClients.ts

@@ -34,7 +34,7 @@ interface Endpoint {
   importName: string;
   type: ApiType;
   method: string;
-  url: string;
+  path: string;
 }
 
 async function getApiObject(
@@ -143,7 +143,7 @@ async function getApiObject(
           importName: found.typeName,
           functionName,
           type: found.apiType,
-          url: "/api/" + relativePath + (filename === "index" ? "" : ("/" + filename)),
+          path: "/api/" + relativePath + (filename === "index" ? "" : ("/" + filename)),
         });
       }
     } else {
@@ -155,19 +155,17 @@ async function getApiObject(
 export interface GenerateApiClientsArgs {
   apiFilePath?: string;
   apiRoutesPath?: string;
-  fetchImport?: string;
+  clientObjectName: string;
+  clientObjectImportPath: string;
   apiObjectName?: string;
-  basePathVar?: string;
-  extraImports?: string[],
 }
 
 export async function generateClients({
   apiFilePath = "src/apis/api.ts",
   apiRoutesPath = "src/pages/api",
-  fetchImport = "@ddadaal/next-typed-api-routes-runtime/lib/client",
+  clientObjectName,
+  clientObjectImportPath,
   apiObjectName = "api",
-  basePathVar = "process.env.NEXT_PUBLIC_BASE_PATH || \"\"",
-  extraImports = [],
 }: GenerateApiClientsArgs) {
 
   if (!apiRoutesPath.endsWith("/")) {
@@ -182,31 +180,23 @@ export async function generateClients({
 
   await getApiObject(apiRoutesPath, "", endpoints, imports);
 
-  const basePathVarDeclaration = `const basePath = ${basePathVar};`;
-
   // use string instead of ts factories to easily style the code and reduce complexity
   const apiObjDeclaration = `
 export const ${apiObjectName} = {
 ${endpoints.map((e) => {
 
     const { libImport, typeFormat } = ApiTypes[e.type];
     return (
-      ` ${e.functionName}: ${libImport}<${typeFormat(e.importName)}>("${e.method}", join(basePath, "${e.url}")),`
+      `  ${e.functionName}: ${clientObjectName}.${libImport}<${typeFormat(e.importName)}>` +
+      `("${e.method}", "${e.path}"),`
     );
   },
   ).join(EOL)}
 };
   `;
 
-  const importsFromRootPackage = new Set<string>();
-
-  for (const endpoint of endpoints) {
-    importsFromRootPackage.add(ApiTypes[endpoint.type].libImport);
-  }
-
   const fetchApiImportDeclaration = `
-import { ${Array.from(importsFromRootPackage.values()).join(", ")} } from "${fetchImport}";
-import { join } from "path";
+import { ${clientObjectName} } from "${clientObjectImportPath}";
 `;
 
   const importDeclarations = imports.map(({ relativePath, interfaceName }) => (
@@ -219,10 +209,6 @@ import { join } from "path";
     EOL + EOL +
     importDeclarations +
     EOL + EOL +
-    extraImports.join(EOL) +
-    EOL + EOL +
-    basePathVarDeclaration +
-    EOL + EOL +
     apiObjDeclaration;
 
   // create dir if not exists

packages/cli/src/index.ts

@@ -22,13 +22,9 @@ yargs(hideBin(process.argv))
         default: "src/apis/api.ts",
       },
       apiRoutesPath: { type: "string", default: "src/pages/api" },
-      fetchImport: {
-        type: "string",
-        default: "@ddadaal/next-typed-api-routes-runtime/lib/client",
-      },
+      clientObjectName: { type: "string", default: "apiClient" },
+      clientObjectImportPath: { type: "string", default: "src/apis/client" },
       apiObjectName: { type: "string", default: "api" },
-      basePathVar: { type: "string", default: "process.env.NEXT_PUBLIC_BASE_PATH || \"\"" },
-      extraImports: { type: "array", string: true, default: []},
     });
   }, (argv) => {
     generateClients(argv);

packages/runtime/src/fetch/client.ts

@@ -0,0 +1,65 @@
+import { TypeboxRouteSchema, TypeboxRouteSchemaToSchema } from "../route/typeboxRoute";
+import { ZodRouteSchema, ZodRouteSchemaToSchema } from "../route/zodRoute";
+import { AnySchema, RequestArgs } from "../types";
+import { HttpMethod, jsonFetch, JsonFetchResultPromiseLike } from "./fetch";
+import { replacePathArgs } from "./replacePathArgs";
+import { removeNullOrUndefinedKey } from "./utils";
+
+/**
+ * Config for api client
+ */
+interface ApiClientConfig {
+  /**
+   * The baseUrl for all requests
+   */
+  baseUrl?: string;
+
+  /**
+   * Extra headers passed in every requests
+   */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Create a apiObject that will be used in generated API file
+ * @param config Client config
+ * @returns Api client that will be used in generated API file
+ */
+export const createApiClient = (config: ApiClientConfig) => {
+
+  function fromStaticRoute<TSchema extends AnySchema>(method: HttpMethod, url: string) {
+    return function(
+      args: RequestArgs<TSchema>,
+      signal?: AbortSignal,
+    ): JsonFetchResultPromiseLike<TSchema> {
+
+      const anyArgs = args as any;
+      // replace path params using query
+      const replacedPath = anyArgs.query
+        ? replacePathArgs(url, anyArgs.query)
+        : url;
+
+      return jsonFetch({
+        url: (config.baseUrl ?? "") + replacedPath,
+        method: method,
+        query: removeNullOrUndefinedKey(anyArgs.query),
+        body: anyArgs.body,
+        headers: config.headers,
+      }, signal);
+    };
+  }
+
+  function fromZodRoute<TSchema extends ZodRouteSchema>(method: HttpMethod, url: string) {
+    return fromStaticRoute<ZodRouteSchemaToSchema<TSchema>>(method, url);
+  }
+
+  function fromTypeboxRoute<TSchema extends TypeboxRouteSchema>(method: HttpMethod, url: string) {
+    return fromStaticRoute<TypeboxRouteSchemaToSchema<TSchema>>(method, url);
+  }
+
+  return {
+    fromStaticRoute,
+    fromZodRoute,
+    fromTypeboxRoute,
+  };
+};

packages/runtime/src/fetch/fetch.ts

@@ -1,14 +1,8 @@
-import { TypeboxRouteSchema, TypeboxRouteSchemaToSchema } from "../route";
-import { ZodRouteSchema, ZodRouteSchemaToSchema } from "../route/zodRoute";
-import type {
-  Querystring, RequestArgs,
-} from "../types/request";
+import type { Querystring } from "../types/request";
 import type { AnySchema, SuccessResponse } from "../types/schema";
 import { failEvent, finallyEvent, prefetchEvent, successEvent } from "./events";
 import { FETCH_ERROR, HttpError, TYPE_ERROR } from "./HttpError";
 import { parseQueryToQuerystring } from "./parseQueryToQuerystring";
-import { replacePathArgs } from "./replacePathArgs";
-import { removeNullOrUndefinedKey } from "./utils";
 
 function isServer() {
   return typeof window === "undefined";
@@ -20,45 +14,29 @@ function isFormData(a: any): a is FormData {
 
 export type HttpMethod = "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
 
-let token = "";
-
-export function changeBearerToken(newToken: string): void {
-  token = newToken;
-}
-
 
 export function fullFetch(
-  path: string,
+  url: string,
   query?: Querystring,
   init?: RequestInit,
 ): Promise<Response> {
-  const headers = token
-    ? { ...init?.headers, "authorization": `Bearer ${token}` }
-    : init?.headers ?? {};
-
-  let url = path;
   if (query) {
     url += parseQueryToQuerystring(query);
   }
 
-  if (typeof window === "undefined") {
-    url = `http://127.0.0.1:${process.env.PORT || 3000}${url}`;
-  }
-
   return fetch(url,
     {
-      ...init,
-      headers,
       mode: "cors",
       // disable cache for IE11
       cache: "no-cache",
+      ...init,
     });
 }
 
 export type FullFetch = typeof fullFetch;
 
 export interface FetchInfo {
-  path: string;
+  url: string;
   method?: HttpMethod;
   query?: Querystring;
   body?: unknown;
@@ -206,7 +184,7 @@ export function jsonFetch<T extends AnySchema>(
 
   prefetchEvent.execute(undefined);
 
-  return new JsonFetchResultPromiseLike(fullFetch(info.path, info.query, {
+  return new JsonFetchResultPromiseLike(fullFetch(info.url, info.query, {
     method: info.method ?? "GET",
     headers: {
       ...isForm ? undefined : { "content-type": "application/json" },
@@ -219,32 +197,3 @@ export function jsonFetch<T extends AnySchema>(
 
 export type JsonFetch = typeof jsonFetch;
 
-export function fromStaticRoute<TSchema extends AnySchema>(method: HttpMethod, url: string) {
-  return function(
-    args: RequestArgs<TSchema>,
-    signal?: AbortSignal,
-  ): JsonFetchResultPromiseLike<TSchema> {
-
-    const anyArgs = args as any;
-    // replace path params using query
-    const replacedPath = anyArgs.query
-      ? replacePathArgs(url, anyArgs.query)
-      : url;
-
-    return jsonFetch({
-      path: replacedPath,
-      method: method,
-      query: removeNullOrUndefinedKey(anyArgs.query),
-      body: anyArgs.body,
-    }, signal);
-  };
-}
-
-export function fromZodRoute<TSchema extends ZodRouteSchema>(method: HttpMethod, url: string) {
-  return fromStaticRoute<ZodRouteSchemaToSchema<TSchema>>(method, url);
-}
-
-export function fromTypeboxRoute<TSchema extends TypeboxRouteSchema>(method: HttpMethod, url: string) {
-  return fromStaticRoute<TypeboxRouteSchemaToSchema<TSchema>>(method, url);
-}
-

packages/runtime/src/fetch/index.ts

@@ -1,3 +1,4 @@
+export * from "./client";
 export * from "./events";
 export * from "./fetch";
 export * from "./HttpError";