@blimu/codegen 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# @blimu/codegen
+
+A powerful TypeScript library and CLI tool for generating type-safe SDKs from OpenAPI specifications. Built with NestJS Commander and following NestJS conventions.
+
+## Features
+
+- 🚀 **Multiple Language Support**: TypeScript, Go, Python (with more planned)
+- 📝 **OpenAPI 3.x Support**: Full support for modern OpenAPI specifications
+- 🎯 **Tag Filtering**: Include/exclude specific API endpoints by tags
+- 🔧 **Highly Configurable**: Flexible configuration via MJS config files with TypeScript hints
+- 📦 **Library & CLI**: Use as a TypeScript library or standalone CLI tool
+- 🎨 **Beautiful Generated Code**: Clean, idiomatic code with excellent TypeScript types
+- ⚡ **Function-Based Transforms**: Use JavaScript functions for operationId transformation with full type safety
+
+## Installation
+
+```bash
+yarn add @blimu/codegen
+# or
+npm install @blimu/codegen
+```
+
+## CLI Usage
+
+### Using Command Line Arguments
+
+```bash
+# Generate TypeScript SDK from OpenAPI spec
+codegen generate \
+  --input https://petstore3.swagger.io/api/v3/openapi.json \
+  --type typescript \
+  --out ./petstore-sdk \
+  --package-name petstore-client \
+  --client-name PetStoreClient
+```
+
+### Using Configuration File
+
+The CLI automatically looks for `chunkflow-codegen.config.mjs` in the current directory and parent directories. You can also specify a custom path:
+
+```bash
+# Auto-discover chunkflow-codegen.config.mjs
+codegen generate
+
+# Use explicit config file path
+codegen generate --config ./chunkflow-codegen.config.mjs
+
+# Generate only a specific client from config
+codegen generate --client MyClient
+```
+
+### Configuration File Example
+
+Create `chunkflow-codegen.config.mjs` in your project root:
+
+```javascript
+// @ts-check
+import { defineConfig } from "@blimu/codegen";
+
+export default defineConfig({
+  spec: "http://localhost:3020/docs/backend-api/json",
+  clients: [
+    {
+      type: "typescript",
+      outDir: "./my-sdk",
+      packageName: "my-sdk",
+      name: "MyClient",
+      operationIdParser: (operationId, method, path) => {
+        // Custom transform logic
+        return operationId.replace(/Controller/g, "");
+      },
+    },
+  ],
+});
+```
+
+The `// @ts-check` directive enables TypeScript type checking and autocomplete in your config file!
+
+See `examples/chunkflow-codegen.config.mjs.example` for a complete example with all available options.
+
+## Programmatic API
+
+Use the codegen library programmatically in your TypeScript code:
+
+```typescript
+import { generate, loadConfig, defineConfig } from "@blimu/codegen";
+
+// Generate from config object
+await generate({
+  spec: "http://localhost:3020/docs/backend-api/json",
+  clients: [
+    {
+      type: "typescript",
+      outDir: "./my-sdk",
+      packageName: "my-sdk",
+      name: "MyClient",
+      operationIdParser: (operationId, method, path) => {
+        return operationId.replace(/Controller/g, "");
+      },
+    },
+  ],
+});
+
+// Generate from config file path
+await generate("./chunkflow-codegen.config.mjs");
+
+// Generate only a specific client
+await generate("./chunkflow-codegen.config.mjs", { client: "MyClient" });
+
+// Load config programmatically
+const config = await loadConfig("./chunkflow-codegen.config.mjs");
+```
+
+## Configuration Options
+
+### Top-Level Config
+
+- `spec` (required): OpenAPI spec file path or URL
+- `name` (optional): Name for this configuration
+- `clients` (required): Array of client configurations
+
+### Client Configuration
+
+- `type` (required): Generator type (e.g., `'typescript'`)
+- `outDir` (required): Output directory for generated SDK
+- `packageName` (required): Package name for the generated SDK
+- `name` (required): Client class name
+- `moduleName` (optional): Module name for type augmentation generators
+- `includeTags` (optional): Array of regex patterns for tags to include
+- `excludeTags` (optional): Array of regex patterns for tags to exclude
+- `includeQueryKeys` (optional): Generate query key helper methods
+- `operationIdParser` (optional): Function to transform operationId to method name
+  - Signature: `(operationId: string, method: string, path: string) => string | Promise<string>`
+- `preCommand` (optional): Commands to run before SDK generation
+- `postCommand` (optional): Commands to run after SDK generation
+- `defaultBaseURL` (optional): Default base URL for the client
+- `exclude` (optional): Array of file paths to exclude from generation
+- `typeAugmentation` (optional): Options for type augmentation generators
+
+## License
+
+MIT

package/dist/generator/typescript/templates/README.md.hbs

@@ -0,0 +1,123 @@
+# {{Client.name}} TypeScript SDK
+
+This is an auto-generated TypeScript/JavaScript SDK for the {{Client.name}} API.
+
+## Installation
+
+```bash
+npm install {{Client.packageName}}
+# or
+yarn add {{Client.packageName}}
+```
+
+## Quick Start
+
+```typescript
+import { {{pascal Client.name}}Client } from '{{Client.packageName}}';
+
+// Create a new client
+const client = new {{pascal Client.name}}Client({
+  baseURL: '{{Client.defaultBaseURL}}',
+  timeoutMs: 10000,
+  retry: { retries: 2, backoffMs: 300, retryOn: [429, 500, 502, 503, 504] },
+  // Environment-based baseURL (optional)
+  env: 'sandbox',
+  envBaseURLs: { sandbox: 'https://api-sandbox.example.com', production: 'https://api.example.com' },
+  // Auth (generic API Key or Bearer header)
+  accessToken: process.env.API_TOKEN,
+  headerName: 'access_token', // or 'Authorization' (defaults to Authorization: Bearer <token>)
+});
+
+{{#each IR.services}}
+{{#if (gt (len this.operations) 0)}}
+{{#with (index this.operations 0) as |firstOp|}}
+// Example: {{firstOp.summary}}
+try {
+  const result = await client.{{serviceProp ../tag}}.{{methodName firstOp}}(
+    {{#each (pathParamsInOrder firstOp)}}{{#if @index}}, {{/if}}'{{this.name}}'{{/each}}
+    {{#if (gt (len firstOp.queryParams) 0)}}{{#if (gt (len (pathParamsInOrder firstOp)) 0)}}, {{/if}}{
+      {{#each firstOp.queryParams}}
+      {{#if this.required}}
+      {{this.name}}: {{#if (eq this.schema.kind "string")}}'example'{{else if (eq this.schema.kind "integer")}}123{{else if (eq this.schema.kind "boolean")}}true{{else}}undefined{{/if}},
+      {{/if}}
+      {{/each}}
+    }{{/if}}
+    {{#if firstOp.requestBody}}{{#if (or (gt (len (pathParamsInOrder firstOp)) 0) (gt (len firstOp.queryParams) 0))}}, {{/if}}{
+      // Request body data
+    }{{/if}}
+  );
+  console.log('Result:', result);
+} catch (error) {
+  // FetchError with structured data
+  console.error(error);
+}
+{{/with}}
+{{/if}}
+{{/each}}
+```
+
+## TypeScript Support
+
+This SDK is written in TypeScript and provides full type safety:
+
+```typescript
+import { {{pascal Client.name}}Client, Schema } from '{{Client.packageName}}';
+
+const client = new {{pascal Client.name}}Client({ /* config */ });
+
+// All methods are fully typed
+// Schema types are available
+{{#if IR.modelDefs}}
+{{#with (index IR.modelDefs 0) as |firstModel|}}
+const data: Schema.{{firstModel.name}} = {
+  // Fully typed object
+};
+{{/with}}
+{{/if}}
+```
+
+## Node.js Usage
+
+For Node.js environments, you may need to provide a fetch implementation:
+
+```bash
+npm install undici
+```
+
+```typescript
+import { fetch } from 'undici';
+import { {{pascal Client.name}}Client } from '{{Client.packageName}}';
+
+const client = new {{pascal Client.name}}Client({
+  baseURL: '{{Client.defaultBaseURL}}',
+  fetch,
+});
+```
+
+{{#if IR.modelDefs}}
+## Models and Types
+
+The SDK includes the following TypeScript interfaces:
+
+{{#each IR.modelDefs}}
+- **{{this.name}}**{{#if this.annotations.description}}: {{this.annotations.description}}{{/if}}
+{{/each}}
+
+All types are available under the `Schema` namespace:
+
+```typescript
+import { Schema } from '{{Client.packageName}}';
+
+// Use any model type
+const user: Schema.User = { /* ... */ };
+```
+{{/if}}
+
+## Contributing
+
+This SDK is auto-generated. Please do not edit the generated files directly. 
+If you find issues, please report them in the main project repository.
+
+## License
+
+This SDK is generated from the {{Client.name}} API specification.

package/dist/generator/typescript/templates/client.ts.hbs

@@ -0,0 +1,380 @@
+{{~#if IR.securitySchemes~}}
+export type ClientOption = {
+  baseURL?: string;
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+  retry?: { retries: number; backoffMs: number; retryOn?: number[] };
+  onRequest?: (ctx: { url: string; init: RequestInit & { path: string; method: string; query?: Record<string, any>; headers: Headers }; attempt: number }) => void | Promise<void>;
+  onResponse?: (ctx: { url: string; init: RequestInit & { path: string; method: string; query?: Record<string, any>; headers: Headers }; attempt: number; response: Response }) => void | Promise<void>;
+  onError?: (err: unknown, ctx: { url: string; init: RequestInit & { path: string; method: string; query?: Record<string, any> }; attempt: number }) => void | Promise<void>;
+  // Environment & Auth
+  env?: 'sandbox' | 'production';
+  envBaseURLs?: { sandbox: string; production: string };
+  accessToken?: string | undefined | (() => string | undefined | Promise<string | undefined>);
+  headerName?: string;
+  {{~#each IR.securitySchemes~}}
+  {{~#if (eq this.type "http")~}}
+    {{~#if (eq this.scheme "bearer")~}}
+  {{camel this.key}}?: string;
+    {{~else if (eq this.scheme "basic")~}}
+  {{camel this.key}}?: { username: string; password: string };
+    {{~/if~}}
+  {{~else if (eq this.type "apiKey")~}}
+  {{camel this.key}}?: string;
+  {{~/if~}}
+  {{~/each~}}
+  fetch?: typeof fetch;
+  credentials?: RequestCredentials;
+};
+
+export class FetchError<T = unknown> extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly data?: T,
+    readonly headers?: Headers,
+  ) {
+    super(message);
+    this.name = "FetchError";
+  }
+}
+
+export class CoreClient {
+  constructor(private cfg: ClientOption = {}) {
+    // Set default base URL if not provided
+    if (!this.cfg.baseURL) {
+      if (this.cfg.env && this.cfg.envBaseURLs) {
+        this.cfg.baseURL = this.cfg.env === 'production' ? this.cfg.envBaseURLs.production : this.cfg.envBaseURLs.sandbox;
+      } else {
+        this.cfg.baseURL = "{{Client.defaultBaseURL}}";
+      }
+    }
+  }
+  setAccessToken(token: string | undefined | (() => string | undefined | Promise<string | undefined>)) {
+    this.cfg.accessToken = token;
+  }
+  async request(
+    init: RequestInit & {
+      path: string;
+      method: string;
+      query?: Record<string, any>;
+    }
+  ) {
+    let normalizedPath = init.path || "";
+    if (normalizedPath.length > 1 && normalizedPath.endsWith('/')) {
+      normalizedPath = normalizedPath.slice(0, -1);
+    }
+    const url = new URL((this.cfg.baseURL || "") + normalizedPath);
+    if (init.query) {
+      Object.entries(init.query).forEach(([k, v]) => {
+        if (v === undefined || v === null) return;
+        if (Array.isArray(v))
+          v.forEach((vv) => url.searchParams.append(k, String(vv)));
+        else url.searchParams.set(k, String(v));
+      });
+    }
+    {{~#each IR.securitySchemes~}}
+    {{~#if (and (eq this.type "apiKey") (eq this.in "query"))~}}
+    if (this.cfg.{{camel this.key}}) {
+      url.searchParams.set("{{this.name}}", String(this.cfg.{{camel this.key}}));
+    }
+    {{~/if~}}
+    {{~/each~}}
+    const headers = new Headers({
+      ...(this.cfg.headers || {}),
+      ...(init.headers as any),
+    });
+    // Generic access token support (optional)
+    if (this.cfg.accessToken) {
+      const token = typeof this.cfg.accessToken === 'function' ? await this.cfg.accessToken() : this.cfg.accessToken;
+      // Only set header if token is not nullish
+      if (token != null) {
+        const name = this.cfg.headerName || 'Authorization';
+        if (name.toLowerCase() === 'authorization') headers.set(name, `Bearer ${String(token)}`);
+        else headers.set(name, String(token));
+      }
+    }
+    {{~#each IR.securitySchemes~}}
+    {{~#if (eq this.type "http")~}}
+      {{~#if (eq this.scheme "bearer")~}}
+    const {{camel this.key}}Key = "{{camel this.key}}";
+    if (this.cfg[{{camel this.key}}Key])
+      headers.set("Authorization", `Bearer ${this.cfg[{{camel this.key}}Key]}`);
+      {{~else if (eq this.scheme "basic")~}}
+    const {{camel this.key}}Key = "{{camel this.key}}";
+    if (this.cfg[{{camel this.key}}Key]) {
+      const u = this.cfg[{{camel this.key}}Key].username;
+      const p = this.cfg[{{camel this.key}}Key].password;
+      const encoded = typeof btoa !== 'undefined' ? btoa(`${u}:${p}`) : (typeof Buffer !== 'undefined' ? Buffer.from(`${u}:${p}`).toString('base64') : '' );
+      if (encoded) headers.set("Authorization", `Basic ${encoded}`);
+    }
+      {{~/if~}}
+    {{~else if (eq this.type "apiKey")~}}
+      {{~#if (eq this.in "header")~}}
+    if (this.cfg?.{{camel this.key}})
+      headers.set("{{this.name}}", String(this.cfg?.{{camel this.key}}));
+      {{~else if (eq this.in "cookie")~}}
+    if (this.cfg?.{{camel this.key}})
+      headers.set("Cookie", `${"{{this.name}}"}=${String(this.cfg?.{{camel this.key}})}`);
+      {{~/if~}}
+    {{~/if~}}
+    {{~/each~}}
+
+    const doFetch = async (attempt: number) => {
+      // Clone init to prevent mutations from affecting concurrent requests
+      // Create a new Headers object for each request to avoid sharing references
+      const requestHeaders = new Headers(headers);
+      const fetchInit: RequestInit & {
+        path: string;
+        method: string;
+        query?: Record<string, any>;
+        headers: Headers;
+      } = {
+        ...init,
+        headers: requestHeaders,
+      };
+      // Set credentials from config if provided (can be overridden by onRequest)
+      if (this.cfg.credentials !== undefined) {
+        fetchInit.credentials = this.cfg.credentials;
+      }
+      if (this.cfg.onRequest) await this.cfg.onRequest({ url: url.toString(), init: fetchInit, attempt });
+      let controller: AbortController | undefined;
+      let timeoutId: any;
+      const existingSignal = fetchInit.signal;
+
+      if (this.cfg.timeoutMs && typeof AbortController !== 'undefined') {
+        controller = new AbortController();
+
+        // If there's an existing signal, combine it with the timeout signal
+        // The combined controller will abort when either signal aborts
+        if (existingSignal) {
+          // If existing signal is already aborted, abort the new controller immediately
+          if (existingSignal.aborted) {
+            controller.abort();
+          } else {
+            // Listen to the existing signal and abort the combined controller when it aborts
+            existingSignal.addEventListener('abort', () => {
+              controller?.abort();
+            });
+          }
+        }
+
+        fetchInit.signal = controller.signal;
+        timeoutId = setTimeout(() => controller?.abort(), this.cfg.timeoutMs);
+      }
+      try {
+        const res = await (this.cfg.fetch || fetch)(url.toString(), fetchInit);
+        if (this.cfg.onResponse) await this.cfg.onResponse({ url: url.toString(), init: fetchInit, attempt, response: res });
+        const ct = res.headers.get("content-type") || "";
+        let parsed: any;
+        if (ct.includes("application/json")) {
+          parsed = await res.json();
+        } else if (ct.startsWith("text/")) {
+          parsed = await res.text();
+        } else {
+          // binary or unknown -> ArrayBuffer
+          parsed = await res.arrayBuffer();
+        }
+        if (!res.ok) {
+          throw new FetchError(
+            parsed?.message || `HTTP ${res.status}`,
+            res.status,
+            parsed,
+            res.headers,
+          );
+        }
+        return parsed as any;
+      } catch (err) {
+        if (this.cfg.onError) await this.cfg.onError(err, { url: url.toString(), init, attempt });
+        throw err;
+      } finally {
+        if (timeoutId) clearTimeout(timeoutId);
+      }
+    };
+
+    const retries = this.cfg.retry?.retries ?? 0;
+    const baseBackoff = this.cfg.retry?.backoffMs ?? 300;
+    const retryOn = this.cfg.retry?.retryOn ?? [429, 500, 502, 503, 504];
+
+    let lastError: unknown;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        return await doFetch(attempt);
+      } catch (err: any) {
+        // Retry on network errors or configured status errors
+        const status = err?.status as number | undefined;
+        const shouldRetry = status ? retryOn.includes(status) : true;
+        if (attempt < retries && shouldRetry) {
+          const delay = baseBackoff * Math.pow(2, attempt);
+          await new Promise((r) => setTimeout(r, delay));
+          lastError = err;
+          continue;
+        }
+        if (err instanceof DOMException) throw err;
+        if (err instanceof FetchError) throw err;
+        if (typeof err === 'string') throw new FetchError(err, status ?? 0);
+        throw new FetchError((err as Error)?.message || 'Network error', status ?? 0);
+      }
+    }
+    throw lastError as any;
+  }
+
+  async *requestStream<T = any>(
+    init: RequestInit & {
+      path: string;
+      method: string;
+      query?: Record<string, any>;
+      contentType: string;
+      streamingFormat?: "sse" | "ndjson" | "chunked";
+    }
+  ): AsyncGenerator<T, void, unknown> {
+    let normalizedPath = init.path || "";
+    if (normalizedPath.length > 1 && normalizedPath.endsWith('/')) {
+      normalizedPath = normalizedPath.slice(0, -1);
+    }
+    const url = new URL((this.cfg.baseURL || "") + normalizedPath);
+    if (init.query) {
+      Object.entries(init.query).forEach(([k, v]) => {
+        if (v === undefined || v === null) return;
+        if (Array.isArray(v))
+          v.forEach((vv) => url.searchParams.append(k, String(vv)));
+        else url.searchParams.set(k, String(v));
+      });
+    }
+    {{~#each IR.securitySchemes~}}
+    {{~#if (and (eq this.type "apiKey") (eq this.in "query"))~}}
+    if (this.cfg.{{camel this.key}}) {
+      url.searchParams.set("{{this.name}}", String(this.cfg.{{camel this.key}}));
+    }
+    {{~/if~}}
+    {{~/each~}}
+    const headers = new Headers({
+      ...(this.cfg.headers || {}),
+      ...(init.headers as any),
+    });
+    // Generic access token support (optional)
+    if (this.cfg.accessToken) {
+      const token = typeof this.cfg.accessToken === 'function' ? await this.cfg.accessToken() : this.cfg.accessToken;
+      // Only set header if token is not nullish
+      if (token != null) {
+        const name = this.cfg.headerName || 'Authorization';
+        if (name.toLowerCase() === 'authorization') headers.set(name, `Bearer ${String(token)}`);
+        else headers.set(name, String(token));
+      }
+    }
+    {{~#each IR.securitySchemes~}}
+    {{~#if (eq this.type "http")~}}
+      {{~#if (eq this.scheme "bearer")~}}
+    const {{camel this.key}}Key = "{{camel this.key}}";
+    if (this.cfg[{{camel this.key}}Key])
+      headers.set("Authorization", `Bearer ${this.cfg[{{camel this.key}}Key]}`);
+      {{~else if (eq this.scheme "basic")~}}
+    const {{camel this.key}}Key = "{{camel this.key}}";
+    if (this.cfg[{{camel this.key}}Key]) {
+      const u = this.cfg[{{camel this.key}}Key].username;
+      const p = this.cfg[{{camel this.key}}Key].password;
+      const encoded = typeof btoa !== 'undefined' ? btoa(`${u}:${p}`) : (typeof Buffer !== 'undefined' ? Buffer.from(`${u}:${p}`).toString('base64') : '' );
+      if (encoded) headers.set("Authorization", `Basic ${encoded}`);
+    }
+      {{~/if~}}
+    {{~else if (eq this.type "apiKey")~}}
+      {{~#if (eq this.in "header")~}}
+    if (this.cfg?.{{camel this.key}})
+      headers.set("{{this.name}}", String(this.cfg?.{{camel this.key}}));
+      {{~else if (eq this.in "cookie")~}}
+    if (this.cfg?.{{camel this.key}})
+      headers.set("Cookie", `${"{{this.name}}"}=${String(this.cfg?.{{camel this.key}})}`);
+      {{~/if~}}
+    {{~/if~}}
+    {{~/each~}}
+
+    const fetchInit: RequestInit & {
+      path: string;
+      method: string;
+      query?: Record<string, any>;
+      headers: Headers;
+    } = {
+      ...init,
+      headers,
+    };
+    // Set credentials from config if provided
+    if (this.cfg.credentials !== undefined) {
+      fetchInit.credentials = this.cfg.credentials;
+    }
+
+    if (this.cfg.onRequest) await this.cfg.onRequest({ url: url.toString(), init: fetchInit, attempt: 0 });
+
+    let controller: AbortController | undefined;
+    let timeoutId: any;
+    const existingSignal = fetchInit.signal;
+
+    if (this.cfg.timeoutMs && typeof AbortController !== 'undefined') {
+      controller = new AbortController();
+      if (existingSignal) {
+        if (existingSignal.aborted) {
+          controller.abort();
+        } else {
+          existingSignal.addEventListener('abort', () => {
+            controller?.abort();
+          });
+        }
+      }
+      fetchInit.signal = controller.signal;
+      timeoutId = setTimeout(() => controller?.abort(), this.cfg.timeoutMs);
+    }
+
+    try {
+      const res = await (this.cfg.fetch || fetch)(url.toString(), fetchInit);
+      if (this.cfg.onResponse) await this.cfg.onResponse({ url: url.toString(), init: fetchInit, attempt: 0, response: res });
+
+      if (!res.ok) {
+        const ct = res.headers.get("content-type") || "";
+        let parsed: any;
+        if (ct.includes("application/json")) {
+          parsed = await res.json();
+        } else if (ct.startsWith("text/")) {
+          parsed = await res.text();
+        } else {
+          parsed = await res.arrayBuffer();
+        }
+        throw new FetchError(
+          parsed?.message || `HTTP ${res.status}`,
+          res.status,
+          parsed,
+          res.headers,
+        );
+      }
+
+      // Import streaming parsers
+      const { parseSSEStream, parseNDJSONStream } = await import("./utils");
+
+      // Route to appropriate parser based on streaming format
+      if (init.streamingFormat === "sse") {
+        yield* parseSSEStream(res) as AsyncGenerator<T, void, unknown>;
+      } else if (init.streamingFormat === "ndjson") {
+        yield* parseNDJSONStream<T>(res);
+      } else {
+        // Generic chunked streaming - yield raw chunks as strings
+        if (!res.body) return;
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            const chunk = decoder.decode(value, { stream: true });
+            yield chunk as T;
+          }
+        } finally {
+          reader.releaseLock();
+        }
+      }
+    } catch (err) {
+      if (this.cfg.onError) await this.cfg.onError(err, { url: url.toString(), init, attempt: 0 });
+      throw err;
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+  }
+}
+{{~/if~}}