create-swagger-client 0.1.5 → 0.1.7

package/README.md

@@ -1,4 +1,4 @@
-# create-swagger-client
+# Create Swagger Client
 
 A TypeScript tool that generates a fully type-safe REST API client from OpenAPI/Swagger specifications. Built with `openapi-typescript` and `ts-morph`, it creates a strongly-typed client class with autocomplete and compile-time type checking for all API endpoints.
 
@@ -10,6 +10,7 @@ A TypeScript tool that generates a fully type-safe REST API client from OpenAPI/
 - 📝 **OpenAPI Spec Support**: Works with OpenAPI 3.x specifications (JSON or YAML)
 - 🌐 **URL or File Input**: Generate from remote URLs or local files
 - 🎯 **Type Inference**: Automatic extraction of path params, query params, headers, and request/response types
+- ⏱️ **Built-in Timeout**: Default 30s timeout per request (configurable)
 
 ## Installation
 
@@ -38,7 +39,7 @@ npx create-swagger-client https://api.example.com/openapi.json my-api-client.ts
 
 **Arguments:**
 - `source` (required): URL or file path to your OpenAPI/Swagger specification
-- `output` (optional): Output file name (default: `client-api.ts`)
+- `output` (optional): Output file name (default: `swagger-client.ts`)
 
 This will generate a file with:
 - All TypeScript types from your OpenAPI spec
@@ -50,7 +51,7 @@ This will generate a file with:
 After generation, import and use the client:
 
 ```typescript
-import { RestApiClient } from './client-api';
+import { RestApiClient } from './swagger-client';
 
 // Initialize the client
 const api = new RestApiClient('https://api.example.com', {
@@ -129,23 +130,30 @@ const result = await api.post('/projects/{projectId}/tasks', {
 
 #### Custom Fetch Options
 
+Each method accepts an optional `RequestInit` as the third argument:
+
 ```typescript
-const api = new RestApiClient('https://api.example.com', {
-  headers: {
-    'Authorization': 'Bearer TOKEN'
-  },
-  mode: 'cors',
+const users = await api.get('/users', { query: { page: 1 } }, {
   credentials: 'include',
-  // Any other RequestInit options
+  mode: 'cors'
 });
 ```
 
+#### Timeout
+
+The client uses a default timeout of 30 seconds. You can override it in the constructor:
+
+```typescript
+const api = new RestApiClient('https://api.example.com', {}, 10_000);
+```
+
 ## Generated Types
 
 The generator creates several useful type utilities:
 
 - `RestMethod`: Union of HTTP methods (`"get" | "post" | "put" | "delete" | "patch"`)
 - `KeyPaths`: All available API paths
+- `PathsForMethod<M>`: Paths that support method `M`
 - `ExtractPathParams<Path, Method>`: Extract path parameters for an endpoint
 - `ExtractQueryParams<Path, Method>`: Extract query parameters for an endpoint
 - `ExtractHeaderParams<Path, Method>`: Extract header parameters for an endpoint
@@ -161,7 +169,7 @@ import {
   RestApiClient, 
   ExtractBody, 
   APIResponse 
-} from './client-api';
+} from './swagger-client';
 
 // Use types in your code
 type CreateUserBody = ExtractBody<'/users', 'post'>;
@@ -174,7 +182,7 @@ const createUser = (data: CreateUserBody): Promise<UserResponse> => {
 
 ## Error Handling
 
-The client throws errors for failed requests:
+The client throws an `ApiError` for failed requests. The error includes `status`, `statusText`, and a parsed JSON `body` when available:
 
 ```typescript
 try {
@@ -183,7 +191,7 @@ try {
   });
 } catch (error) {
   console.error('API request failed:', error.message);
-  // Error message includes status code, status text, and response body
+  // error.status, error.statusText, error.body
 }
 ```
 
@@ -198,4 +206,4 @@ MIT
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please feel free to submit a Pull Request.

package/index.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { existsSync, readFileSync } from "fs";
 import openapiTS, { astToString } from "openapi-typescript";
 import ora from "ora";
 import { resolve } from "path";
@@ -24,6 +25,11 @@ async function generate() {
   if (isUrl(source) === false) {
     source = resolve(process.cwd(), source);
   }
+
+  if (existsSync(source)) {
+    source = readFileSync(source, "utf-8");
+  }
+
   const spinner = ora(`Generating API client from ${source}...`).start();
   const ast = await openapiTS(source);
   const contents = astToString(ast);
@@ -78,45 +84,31 @@ async function generate() {
     isExported: true,
     typeParameters: ["K extends KeyPaths", "M extends RestMethod"],
     type: `paths[K][M] extends { responses: infer R }
-  ? R extends {
-      content: { "application/json": infer C };
-    }
+  ? R extends { "200"?: { content: { "application/json": infer C } } }
     ? C
-    : R extends {
-          [status: number]: infer S;
-        }
-      ? S extends { content: { "application/json": infer C } }
-        ? C
-        : never
-      : never
-  : never;`,
+    : R extends { content: { "application/json": infer C } }
+    ? C
+    : R extends Record<number | string, { content: { "application/json": infer C } }>
+    ? C
+    : never
+  : never`,
   });
   sourceFile.addTypeAlias({
     name: "ApiPayload",
     isExported: true,
-    typeParameters: ["T extends KeyPaths", "K extends RestMethod"],
+    typeParameters: ["T extends KeyPaths", "M extends RestMethod"],
     type: `{
-  path?: ExtractPathParams<T, K>;
-  query?: ExtractQueryParams<T, K>;
-  body?: K extends "post" | "put" | "patch" ? ExtractBody<T, K> : never;
-  headers?: ExtractHeaderParams<T, K>;
+  path?: ExtractPathParams<T, M>;
+  query?: ExtractQueryParams<T, M>;
+  body?: M extends "post" | "put" | "patch" ? ExtractBody<T, M> : never;
+  headers?: ExtractHeaderParams<T, M> & Record<string, string>;
 }`,
   });
   sourceFile.addTypeAlias({
-    name: "ApiClientType",
-    isExported: true,
-    type: `{
-  [K in RestMethod]: <T extends KeyPaths>(
-    path: T,
-    payload?: ApiPayload<T, K>,
-  ) => Promise<APIResponse<T, K>>;
-}`,
-  });
-  sourceFile.addTypeAlias({
-    name: "TypePaths",
-    typeParameters: ["T extends RestMethod"],
+    name: "PathsForMethod",
+    typeParameters: ["M extends RestMethod"],
     type: `{
-  [K in KeyPaths]: paths[K] extends { [M in T]: unknown } ? K : never;
+  [K in KeyPaths]: paths[K] extends Record<M, unknown> ? K : never;
 }[KeyPaths]`,
   });
   sourceFile.addClass({
@@ -125,195 +117,250 @@ async function generate() {
     ctors: [
       {
         parameters: [
-          { name: "basePath", type: "string", scope: tsMorph.Scope.Private },
+          { name: "baseUrl", type: "string", scope: tsMorph.Scope.Private },
           {
-            name: "option",
+            name: "defaultOptions",
             type: "RequestInit",
-            hasQuestionToken: true,
+            initializer: "{}",
+            scope: tsMorph.Scope.Private,
+          },
+          {
+            name: "defaultTimeoutMs",
+            type: "number",
+            initializer: "30000",
             scope: tsMorph.Scope.Private,
           },
         ],
+        statements: `this.baseUrl = baseUrl.replace(/\\/+$/, "");`,
       },
     ],
     methods: [
       {
-        name: "fetcher",
-        scope: tsMorph.Scope.Public,
+        name: "buildUrl",
+        scope: tsMorph.Scope.Private,
+        typeParameters: ["P extends KeyPaths", "M extends RestMethod"],
+        parameters: [
+          { name: "pathTemplate", type: "P" },
+          { name: "pathParams", type: "ExtractPathParams<P, M>", hasQuestionToken: true },
+        ],
+        returnType: "URL",
+        statements: `let pathname = pathTemplate as string;
+
+    if (pathParams) {
+      pathname = pathname.replace(/\\{([^}]+)\\}/g, (_, paramName) => {
+        const value = (pathParams as Record<string, unknown>)[paramName];
+        if (value === undefined || value === null) {
+          throw new Error(\`Missing required path parameter: \${paramName}\`);
+        }
+        return encodeURIComponent(String(value));
+      });
+    }
+
+    return new URL(this.baseUrl + pathname);`,
+      },
+      {
+        name: "appendQueryParams",
+        scope: tsMorph.Scope.Private,
+        parameters: [
+          { name: "url", type: "URL" },
+          { name: "query", type: "Record<string, unknown>", hasQuestionToken: true },
+        ],
+        returnType: "void",
+        statements: `if (!query) return;
+
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null) continue;
+
+      if (Array.isArray(value)) {
+        value.forEach((v) => {
+          if (v !== undefined && v !== null) {
+            url.searchParams.append(key, String(v));
+          }
+        });
+      } else {
+        url.searchParams.append(key, String(value));
+      }
+    }`,
+      },
+      {
+        name: "prepareBody",
+        scope: tsMorph.Scope.Private,
+        typeParameters: ["M extends RestMethod"],
+        parameters: [
+          { name: "method", type: "M" },
+          { name: "body", type: "unknown", hasQuestionToken: true },
+        ],
+        returnType: "BodyInit | null",
+        statements: `if (!body || !["post", "put", "patch"].includes(method)) return null;
+    return JSON.stringify(body);`,
+      },
+      {
+        name: "fetchWithTimeout",
+        scope: tsMorph.Scope.Private,
         isAsync: true,
         parameters: [
           { name: "input", type: "RequestInfo" },
-          { name: "init", type: "RequestInit", hasQuestionToken: true },
+          { name: "init", type: "RequestInit" },
+          { name: "timeoutMs", type: "number" },
         ],
-        statements: `const headers = {
-      "Content-Type": "application/json",
-      ...init?.headers,
-    };
+        returnType: "Promise<Response>",
+        statements: `const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
 
-    const response = await fetch(input, { ...init, headers });
-    if (!response.ok) {
-      const errorBody = await response.text();
-      throw new Error(
-        \`API request failed: \${response.status} \${response.statusText} - \${errorBody}\`,
-      );
-    }
-    return response.json();`,
+    try {
+      const response = await fetch(input, {
+        ...init,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      return response;
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof DOMException && err.name === "AbortError") {
+        throw new Error(\`Request timed out after \${timeoutMs}ms\`);
+      }
+      throw err;
+    }`,
+      },
+      {
+        name: "createError",
+        scope: tsMorph.Scope.Private,
+        parameters: [
+          { name: "response", type: "Response" },
+          { name: "body", type: "string | null" },
+        ],
+        statements: `return Object.assign(new Error(), {
+      name: "ApiError",
+      message: \`API request failed: \${response.status} \${response.statusText}\`,
+      status: response.status,
+      statusText: response.statusText,
+      body: body ? JSON.parse(body) : null,
+    });`,
       },
       {
         name: "request",
-        typeParameters: ["M extends RestMethod", "P extends TypePaths<M>"],
+        isAsync: true,
+        typeParameters: ["M extends RestMethod", "P extends PathsForMethod<M>"],
         parameters: [
           { name: "method", type: "M" },
           { name: "path", type: "P" },
           {
-            name: "init",
+            name: "payload",
             type: "ApiPayload<P, M>",
             initializer: "{} as ApiPayload<P, M>",
           },
+          {
+            name: "options",
+            type: "RequestInit",
+            initializer: "{}",
+          },
         ],
         returnType: "Promise<APIResponse<P, M>>",
-        statements: `const url = new URL(this.basePath + String(path));
+        statements: `const url = this.buildUrl(path, payload.path);
+    this.appendQueryParams(url, payload.query ?? {});
 
-    url.pathname = this.buildPathUrl(url.pathname, init.path);
-    this.appendQueryParams(url, init.query);
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.defaultOptions.headers,
+      ...payload.headers,
+      ...options.headers,
+    };
 
     const requestInit: RequestInit = {
       method: method.toUpperCase(),
-      ...this.option,
-      headers: {
-        ...(this.option?.headers ?? {}),
-        ...(init.headers ?? {}),
-      },
-      body: this.prepareBody(method, init.body),
+      ...this.defaultOptions,
+      ...options,
+      headers,
+      body: this.prepareBody(method, payload.body),
     };
 
-    return this.fetcher(url.toString(), requestInit) as Promise<
-      APIResponse<P, M>
-    >;`,
+    const response = await this.fetchWithTimeout(
+      url.toString(),
+      requestInit,
+      this.defaultTimeoutMs,
+    );
+
+    let responseBody: unknown;
+
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+      responseBody = await response.json();
+    } else {
+      responseBody = await response.text();
+    }
+
+    if (!response.ok) {
+      throw this.createError(
+        response,
+        typeof responseBody === "string" ? responseBody : null,
+      );
+    }
+
+    return responseBody as APIResponse<P, M>;`,
       },
       {
         name: "get",
         scope: tsMorph.Scope.Public,
-        typeParameters: ['T extends TypePaths<"get">'],
+        typeParameters: ['P extends PathsForMethod<"get">'],
         parameters: [
-          { name: "path", type: "T" },
-          {
-            name: "payload",
-            type: 'ApiPayload<T, "get">',
-            hasQuestionToken: true,
-          },
+          { name: "path", type: "P" },
+          { name: "payload", type: 'ApiPayload<P, "get">', hasQuestionToken: true },
+          { name: "options", type: "RequestInit", hasQuestionToken: true },
         ],
-        returnType: 'Promise<APIResponse<T, "get">>',
-        statements: 'return this.request("get", path, payload);',
+        returnType: 'Promise<APIResponse<P, "get">>',
+        statements: 'return this.request("get", path, payload, options);',
       },
       {
         name: "post",
         scope: tsMorph.Scope.Public,
-        typeParameters: ['T extends TypePaths<"post">'],
+        typeParameters: ['P extends PathsForMethod<"post">'],
         parameters: [
-          { name: "path", type: "T" },
-          {
-            name: "payload",
-            type: 'ApiPayload<T, "post">',
-            hasQuestionToken: true,
-          },
+          { name: "path", type: "P" },
+          { name: "payload", type: 'ApiPayload<P, "post">', hasQuestionToken: true },
+          { name: "options", type: "RequestInit", hasQuestionToken: true },
         ],
-        returnType: 'Promise<APIResponse<T, "post">>',
-        statements: 'return this.request("post", path, payload);',
+        returnType: 'Promise<APIResponse<P, "post">>',
+        statements: 'return this.request("post", path, payload, options);',
       },
       {
         name: "put",
         scope: tsMorph.Scope.Public,
-        typeParameters: ['T extends TypePaths<"put">'],
-        parameters: [
-          { name: "path", type: "T" },
-          {
-            name: "payload",
-            type: 'ApiPayload<T, "put">',
-            hasQuestionToken: true,
-          },
-        ],
-        returnType: 'Promise<APIResponse<T, "put">>',
-        statements: 'return this.request("put", path, payload);',
-      },
-      {
-        name: "delete",
-        scope: tsMorph.Scope.Public,
-        typeParameters: ['T extends TypePaths<"delete">'],
+        typeParameters: ['P extends PathsForMethod<"put">'],
         parameters: [
-          { name: "path", type: "T" },
-          {
-            name: "payload",
-            type: 'ApiPayload<T, "delete">',
-            hasQuestionToken: true,
-          },
+          { name: "path", type: "P" },
+          { name: "payload", type: 'ApiPayload<P, "put">', hasQuestionToken: true },
+          { name: "options", type: "RequestInit", hasQuestionToken: true },
         ],
-        returnType: 'Promise<APIResponse<T, "delete">>',
-        statements: 'return this.request("delete", path, payload);',
+        returnType: 'Promise<APIResponse<P, "put">>',
+        statements: 'return this.request("put", path, payload, options);',
       },
       {
         name: "patch",
         scope: tsMorph.Scope.Public,
-        typeParameters: ['T extends TypePaths<"patch">'],
-        parameters: [
-          { name: "path", type: "T" },
-          {
-            name: "payload",
-            type: 'ApiPayload<T, "patch">',
-            hasQuestionToken: true,
-          },
-        ],
-        returnType: 'Promise<APIResponse<T, "patch">>',
-        statements: 'return this.request("patch", path, payload);',
-      },
-      {
-        name: "buildPathUrl",
-        scope: tsMorph.Scope.Private,
+        typeParameters: ['P extends PathsForMethod<"patch">'],
         parameters: [
-          { name: "basePath", type: "string" },
-          { name: "pathParams", type: "unknown", hasQuestionToken: true },
-        ],
-        returnType: "string",
-        statements: `let pathname = basePath;
-    if (pathParams != null) {
-      const params = pathParams as Record<string, unknown>;
-      pathname = decodeURIComponent(pathname).replace(/{(w+)}/g, (_, key) =>
-        encodeURIComponent(String(params[key])),
-      );
-    }
-    return pathname;`,
-      },
-      {
-        name: "prepareBody",
-        scope: tsMorph.Scope.Private,
-        parameters: [
-          { name: "method", type: "RestMethod" },
-          { name: "body", type: "unknown", hasQuestionToken: true },
+          { name: "path", type: "P" },
+          { name: "payload", type: 'ApiPayload<P, "patch">', hasQuestionToken: true },
+          { name: "options", type: "RequestInit", hasQuestionToken: true },
         ],
-        returnType: "string | undefined",
-        statements: `if (body && ["post", "put", "patch"].includes(method)) {
-      return JSON.stringify(body);
-    }
-    return undefined;`,
+        returnType: 'Promise<APIResponse<P, "patch">>',
+        statements: 'return this.request("patch", path, payload, options);',
       },
       {
-        name: "appendQueryParams",
-        scope: tsMorph.Scope.Private,
+        name: "delete",
+        scope: tsMorph.Scope.Public,
+        typeParameters: ['P extends PathsForMethod<"delete">'],
         parameters: [
-          { name: "url", type: "URL" },
-          { name: "queryParams", type: "unknown", hasQuestionToken: true },
+          { name: "path", type: "P" },
+          { name: "payload", type: 'ApiPayload<P, "delete">', hasQuestionToken: true },
+          { name: "options", type: "RequestInit", hasQuestionToken: true },
         ],
-        returnType: "void",
-        statements: `if (queryParams != null) {
-      const params = queryParams as Record<string, unknown>;
-      for (const [key, value] of Object.entries(params)) {
-        if (value !== undefined && value !== null) {
-          url.searchParams.append(key, String(value));
-        }
-      }
-    }`,
+        returnType: 'Promise<APIResponse<P, "delete">>',
+        statements: 'return this.request("delete", path, payload, options);',
       },
     ],
   });
+
   await sourceFile.formatText();
   await project.save();
   spinner.stopAndPersist({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-swagger-client",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Generate fully type-safe REST API clients from OpenAPI/Swagger specifications",
   "main": "./index.mjs",
   "module": "./index.mjs",