Merge pull request #5 from moznion/default_header_generics

[BREAKING CHANGE] Support the default HTTP header by generic type in the generated client instead of CLI option

Author: moznion

README.md

@@ -67,30 +67,29 @@ async function doSomething() {
 
 ### Default HTTP Headers
 
-This tool provides a `--default-headers` CLI option to configure the generated client to use default HTTP headers.
+Generated clients support a generic type for default HTTP headers.
 
-For example, when you specify:
+Example:
 
-```bash
-npx openapi-fetch-gen \
-  --input ./schema.d.ts \
-  --output ./client.ts \
-  --default-headers "Authorization, Application-Version"
+```typescript
+export class Client<HT extends Record<string, string>> {
+  constructor(clientOptions: ClientOptions, defaultHeaders?: HT) {
+    this.client = createClient<paths>(clientOptions);
+    this.defaultHeaders = defaultHeaders ?? ({} as HT);
+  }
+  ...
+}
 ```
 
-the `Client` constructor accepts those default values:
+You can create a client instance with default headers like this:
 
 ```typescript
-type DefaultHeaders = Record<'Authorization' | 'Application-Version', string>;
-
-export class Client {
-  constructor(clientOptions: ClientOptions, defaultHeaders: DefaultHeaders) { ... }
-}
+new Client({}, {"Authorization": "Bearer your-token", "Application-Version": "1.0.0"});
 ```
 
-Endpoint methods that require those headers no longer need the default values to be passed explicitly.
+With this setup, endpoint methods that require these headers no longer need them to be explicitly passed each time.
 
-For example, given this schema:
+For example, given the following schema:
 
 ```typescript
 "/users/bulk/{jobId}": {
@@ -113,35 +112,29 @@ For example, given this schema:
     };
 ```
 
-When `--default-headers` is not specified, the generated client method looks like this:
-
-```typescript
-async getUsersBulkJobid(params: {
-  header: {
-    Authorization: string;
-    "Application-Version": string;
-    "Something-Id": string;
-  };
-  path: { jobId: string };
-}) {
-  ...
-}
-```
-
-This requires you to pass all header values explicitly.
-
-When you do specify `--default-headers`, the signature becomes:
+This tool generates an endpoint method using a type-level trick like this:
 
 ```typescript
 async getUsersBulkJobid(
-  params: keyof Omit<
-    {
-      Authorization: string;
-      "Application-Version": string;
-      "Something-Id": string;
-    },
-    keyof DefaultHeaders
-  > extends never
+  params: [
+    Exclude<
+      // Missed Header Keys for default headers
+      keyof {
+        Authorization: string;
+        "Application-Version": string;
+        "Something-Id": string;
+      },
+      Extract<
+        // Provided header keys by default headers' keys
+        keyof HT,
+        keyof {
+          Authorization: string;
+          "Application-Version": string;
+          "Something-Id": string;
+        }
+      >
+    >,
+  ] extends [never]
     ? {
         header?: {
           Authorization: string;
@@ -152,14 +145,46 @@ async getUsersBulkJobid(
       }
     : {
         header:
-          | Omit<
+          | (Pick<
+              // Pick the header keys that are not in the default headers
               {
                 Authorization: string;
                 "Application-Version": string;
                 "Something-Id": string;
               },
-              keyof DefaultHeaders
-            >
+              Exclude<
+                // Missed Header Keys for default headers
+                keyof {
+                  Authorization: string;
+                  "Application-Version": string;
+                  "Something-Id": string;
+                },
+                Extract<
+                  // Provided header keys by default headers' keys
+                  keyof HT,
+                  keyof {
+                    Authorization: string;
+                    "Application-Version": string;
+                    "Something-Id": string;
+                  }
+                >
+              >
+            > &
+              Partial<
+                // Disallow default headers' keys to be in the header param
+                Record<
+                  Extract<
+                    // Provided header keys by default headers' keys
+                    keyof HT,
+                    keyof {
+                      Authorization: string;
+                      "Application-Version": string;
+                      "Something-Id": string;
+                    }
+                  >,
+                  never
+                >
+              >)
           | {
               Authorization: string;
               "Application-Version": string;
@@ -168,11 +193,20 @@ async getUsersBulkJobid(
         path: { jobId: string };
       },
 ) {
-  ...
+  return await this.client.GET("/users/bulk/{jobId}", {
+    params: {
+      ...params,
+      header: { ...this.defaultHeaders, ...params.header } as {
+        Authorization: string;
+        "Application-Version": string;
+        "Something-Id": string;
+      },
+    },
+  });
 }
 ```
 
-That signature means you can:
+This signature allows you to:
 
 - **Omit** the defaulted headers and only pass additional ones (here, `Something-Id`):
 
@@ -186,7 +220,7 @@ client.getUsersBulkJobid({header: {"Something-Id": "foobar"}, path: {jobId: "123
 client.getUsersBulkJobid({header: {"Authorization": "foo", "Application-Version": "bar", "Something-Id": "foobar"}, path: {jobId: "123"}});
 ```
 
-If your default headers cover **all** required headers for the endpoint (e.g. `--default-headers 'Authorization, Application-Version, Something-Id'`), you can omit the `header` parameter entirely:
+If your default headers already include **all** required headers for the endpoint (e.g. `{"Authorization": "Bearer your-token", "Application-Version": "1.0.0", "Something-Id": "123"}` as the second constructor argument), you can omit the `header` parameter entirely:
 
 ```typescript
 client.getUsersBulkJobid({path: {jobId: "123"}});

src/cli.ts

@@ -23,37 +23,26 @@ program
     "path to output generated client file",
     "./client.ts",
   )
-  .option(
-    "--default-headers <comma_separated_names_of_headers>",
-    "header names so that the generated client includes the default HTTP headers across all endpoints",
-    "",
-  )
   .parse(process.argv);
 
 const options = program.opts();
 
 try {
   const inputPath = path.resolve(options["input"]);
   const outputPath = path.resolve(options["output"]);
-  const defaultHeaderNamesString = options["defaultHeaders"] as string;
 
   if (!fs.existsSync(inputPath)) {
     console.error(`Error: Input file not found: ${inputPath}`);
     process.exit(1);
   }
 
-  const defaultHeaderNames = defaultHeaderNamesString
-    .split(",")
-    .map((h) => h.trim())
-    .filter((h) => h !== "");
-
-  const clientCode = generateClient(inputPath, defaultHeaderNames);
+  const clientCode = generateClient(inputPath);
 
   fs.writeFileSync(outputPath, clientCode);
-  console.log(`Successfully generated client at: ${outputPath}`);
+  console.log(`🏁 Successfully generated client at: ${outputPath}`);
 } catch (error) {
   console.error(
-    "Error:",
+    "😵 Error:",
     error instanceof Error ? error.message : String(error),
   );
   process.exit(1);

src/index.ts

@@ -15,10 +15,7 @@ import {
  * Generates a TypeScript API client using openapi-fetch based on TypeScript interface definitions
  * generated by openapi-typescript.
  */
-export function generateClient(
-  schemaFilePath: string,
-  defaultHeaderNames: string[],
-): string {
+export function generateClient(schemaFilePath: string): string {
   const project = new Project({
     compilerOptions: {
       target: ScriptTarget.Latest,
@@ -32,11 +29,7 @@ export function generateClient(
     throw new Error(`Interface "paths" not found in ${schemaFilePath}`);
   }
 
-  return generateClientCode(
-    pathsInterface,
-    path.basename(schemaFilePath),
-    defaultHeaderNames,
-  );
+  return generateClientCode(pathsInterface, path.basename(schemaFilePath));
 }
 
 function findInterface(
@@ -53,23 +46,16 @@ interface EndpointInfo {
   commentLines: string[];
   paramsType: string | null;
   bodyType: string | null;
-  headerExists: boolean;
+  headerType: string | null;
 }
 
 function generateClientCode(
   pathsInterface: InterfaceDeclaration,
   schemaFileName: string,
-  defaultHeaderNames: string[],
 ): string {
-  const defaultHeaderExists = defaultHeaderNames.length > 0;
-
-  const endpoints = extractEndpointsInfo(pathsInterface, defaultHeaderExists);
+  const endpoints = extractEndpointsInfo(pathsInterface);
 
-  const defaultHeaderType =
-    defaultHeaderNames.length > 0
-      ? `type DefaultHeaders = Record<${defaultHeaderNames.map((n) => `"${n}"`).join("|")}, string>\n`
-      : "";
-  const clientClass = generateClientClass(endpoints, defaultHeaderExists);
+  const clientClass = generateClientClass(endpoints);
 
   const code = [
     "// THIS FILE IS AUTO-GENERATED BY openapi-fetch-gen.",
@@ -78,7 +64,6 @@ function generateClientCode(
     `import createClient, { type ClientOptions } from "openapi-fetch";`,
     `import type { paths } from "./${schemaFileName}"; // generated by openapi-typescript`,
     "",
-    defaultHeaderType,
     clientClass,
   ].join("\n");
 
@@ -90,7 +75,6 @@ function generateClientCode(
 
 function extractEndpointsInfo(
   pathsInterface: InterfaceDeclaration,
-  defaultHeaderExists: boolean,
 ): EndpointInfo[] {
   const endpoints: EndpointInfo[] = [];
 
@@ -148,20 +132,49 @@ function extractEndpointsInfo(
         .filter((kv) => kv["text"] !== "");
 
       const headerType = paramTypes.find((kv) => kv.name === "header");
-      if (defaultHeaderExists && headerType) {
+      if (headerType) {
+        // header exists in params
         const nonHeaderParams = paramTypes
           .filter((kv) => kv.name !== "header")
           .map((kv) => `${kv.name}: ${kv.text}`)
           .join("\n");
 
-        paramsType = `keyof Omit<${headerType["text"]}, keyof DefaultHeaders> extends never ?
-  {
+        paramsType =
+          `[
+  Exclude< // Missed Header Keys for default headers
+    keyof ${headerType["text"]},
+    Extract< // Provided header keys by default headers' keys
+      keyof HT, keyof ${headerType["text"]}
+    >
+  >,
+] extends [never] ? ` +
+          // When the default headers cover all the headers (i.e. `Exclude<...>` derived as `never`),
+          // header parameter becomes optional (omitting or )overriding default headers.
+          `{
     header?: ${headerType["text"]},
     ${nonHeaderParams}
-  } :
-  {
+  } : ` + // Else, header parameter is required as either follows:
+          // 1. requires sorely missed header values
+          // 2. requires all the header values (overriding default headers)
+          `{
     header:
-      | Omit<${headerType["text"]}, keyof DefaultHeaders>
+      | (Pick< // Pick the header keys that are not in the default headers
+          ${headerType["text"]},
+          Exclude< // Missed Header Keys for default headers
+            keyof ${headerType["text"]},
+            Extract< // Provided header keys by default headers' keys
+              keyof HT, keyof ${headerType["text"]}
+            >
+          >
+        > &
+        Partial< // Disallow default headers' keys to be in the header param
+          Record<
+            Extract< // Provided header keys by default headers' keys
+              keyof HT, keyof ${headerType["text"]}
+            >,
+            never
+          >
+        >)
       | ${headerType["text"]},
     ${nonHeaderParams}
 }
@@ -227,26 +240,23 @@ function extractEndpointsInfo(
         commentLines,
         paramsType,
         bodyType: requestBodyType,
-        headerExists: headerType !== undefined,
+        headerType: headerType ? headerType["text"] : null,
       });
     }
   }
 
   return endpoints;
 }
 
-function generateClientClass(
-  endpoints: EndpointInfo[],
-  defaultHeaderExists: boolean,
-): string {
+function generateClientClass(endpoints: EndpointInfo[]): string {
   const classCode = [
-    `export class Client {
+    `export class Client<HT extends Record<string, string>> {
        private readonly client;
-       ${defaultHeaderExists ? "private readonly defaultHeaders: DefaultHeaders;" : ""}
+       private readonly defaultHeaders: HT;
 
-       constructor(clientOptions: ClientOptions${defaultHeaderExists ? ", defaultHeaders: DefaultHeaders" : ""}) {
+       constructor(clientOptions: ClientOptions, defaultHeaders?: HT) {
          this.client = createClient<paths>(clientOptions);
-         ${defaultHeaderExists ? "this.defaultHeaders = defaultHeaders;" : ""}
+         this.defaultHeaders = defaultHeaders ?? ({} as HT);
        }
     `,
   ];
@@ -297,10 +307,10 @@ function generateClientClass(
     );
 
     if (paramsType) {
-      if (defaultHeaderExists && endpoint.headerExists) {
+      if (endpoint.headerType) {
         classCode.push(`params: {
   ...params,
-  header: {...this.defaultHeaders, ...params.header},
+  header: {...this.defaultHeaders, ...params.header} as ${endpoint.headerType},
 },`);
       } else {
         classCode.push("params,");