genoc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrey Kiselev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# genoc
+
+Generate TypeScript HTTP clients from OpenAPI 3.0 / 3.1 specifications.
+The generated code has zero runtime dependencies. Full type safety. Bring your own HTTP client.
+
+[![npm version](https://img.shields.io/npm/v/genoc)](https://www.npmjs.com/package/genoc)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/typescript-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+## Features
+
+- Full OpenAPI 3.0 and 3.1 specification support with automatic version detection
+- End-to-end type safety — requests, responses, and errors are fully typed
+- HTTP-client agnostic — adapter pattern lets you plug in fetch, axios, or anything else
+- Error types with per-status-code narrowing and type guards
+- File and binary upload/download with stream handling
+- Flexible method naming strategies (path-based, operationId, operationId-with-fallback)
+- CLI and programmatic API
+
+## Quick Start
+
+Install:
+
+```bash
+npm install -D genoc
+```
+
+Generate:
+
+```bash
+genoc ./path/to/spec.yaml --output-dir ./src/api
+```
+
+This creates two files in `./src/api`:
+
+- `contracts.ts` — Type definitions, error classes, and helper types
+- `client.ts` — Typed client with `createClient(requester)` factory
+
+## Usage
+
+The generated client requires a `Requester` implementation — a function that
+performs the actual HTTP call and returns the result. This is the type your
+implementation must satisfy:
+
+```typescript
+type Requester = <TResponse>(
+  method: string,
+  path: string,
+  options: {
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    expectStream?: true;
+  }
+) => Promise<TResponse | StreamResponse | ErrorResponse>;
+```
+
+### Basic Example with `fetch`
+
+```typescript
+import { createClient } from './client.js';
+import { ApiError, RequesterFailError, ErrorResponse } from './contracts.js';
+
+const baseUrl = 'https://api.example.com';
+
+const requester: Requester = async (method, path, options) => {
+  const url = new URL(path, baseUrl);
+  if (options.query) {
+    Object.entries(options.query).forEach(([key, value]) => {
+      url.searchParams.set(key, String(value));
+    });
+  }
+
+  const response = await fetch(url, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      ...options.headers,
+    },
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+
+  if (!response.ok) {
+    return new ErrorResponse(
+      response.status,
+      await response.json(),
+      response.headers,
+      response.statusText
+    );
+  }
+
+  return response.json();
+};
+
+const client = createClient(requester);
+
+// Typed call — response type is inferred from the spec
+const pets = await client.getPets({ limit: 10 });
+```
+
+See [Binary / File Responses](#binary--file-responses) for handling `expectStream: true`.
+
+## Binary / File Responses
+
+When your spec defines binary responses (e.g. `format: binary`,
+`application/octet-stream`, `image/*`), the generated client sends
+`expectStream: true` in options. Your `Requester` should return a
+`StreamResponse` in that case:
+
+```typescript
+import { StreamResponse } from './contracts.js';
+
+// Inside your Requester implementation:
+if (options.expectStream === true) {
+  return new StreamResponse(
+    response.body as ReadableStream<Uint8Array>,
+    getFilename(response.headers), // extract from Content-Disposition
+    response.headers
+  );
+}
+```
+
+`StreamResponse` is a simple container:
+
+```typescript
+class StreamResponse {
+  data: ReadableStream<Uint8Array>;
+  filename?: string;
+  headers: Headers;
+}
+```
+
+### Response Helpers
+
+The generated `contracts.ts` includes helper functions for constructing
+responses in your `Requester` implementation:
+
+- `streamResponse(data, filename?, headers?)` — Creates a `StreamResponse` instance
+- `errorResponse(status, data, headers?, message?)` — Creates an `ErrorResponse` instance
+
+These are convenience wrappers around the `StreamResponse` and `ErrorResponse`
+constructors.
+
+## CLI Reference
+
+```bash
+genoc <spec> [flags]
+```
+
+`<spec>` — Path or URL to an OpenAPI 3.0 / 3.1 spec (JSON or YAML).
+
+| Flag                     | Default      | Description                                          |
+| ------------------------ | ------------ | ---------------------------------------------------- |
+| `--output-dir`           | (required)   | Output directory for generated files                 |
+| `--method-name-strategy` | `path-based` | Method naming strategy                               |
+| `--spec-version`         | auto-detect  | Override version detection (`"3.0"` or `"3.1"`)      |
+| `--strict-version`       | `true`       | Warn if `--spec-version` mismatches detected version |
+
+## Method Naming Strategies
+
+- **`path-based`** (default) — HTTP method + path segments in PascalCase.
+  `GET /pets` → `getPets`, `GET /api/v1/products` → `getApiV1Products`
+
+- **`operationId`** — Use the `operationId` field from the spec.
+  `GET /pets` → `findPets` (if `operationId` is `"findPets"`)
+
+- **`operationId-with-fallback`** — Use `operationId` if present, otherwise
+  fall back to path-based naming.
+
+## Programmatic API
+
+```typescript
+import { generateClient } from 'genoc';
+
+await generateClient({
+  input: './openapi.yaml',
+  outputDir: './src/api',
+  methodNameStrategy: 'path-based',
+  specVersion: '3.1',
+  strictVersion: true,
+});
+```
+
+## Error Handling
+
+The generated client throws typed errors. Each method carries its own error
+union, and `isDefinedError` narrows a caught error to that union:
+
+- **`ApiError<TStatus, TData>`** — Error for a specific status code defined in the spec
+- **`UnspecifiedApiError`** — Error for a status code not defined in the spec
+- **`RequesterFailError`** — Wraps unexpected failures in your `Requester`
+- **`isDefinedError(err, client.method)`** — Type guard that narrows to the method's defined error union
+
+```typescript
+import { UnspecifiedApiError, RequesterFailError } from './contracts.js';
+import { isDefinedError } from './client.js';
+
+try {
+  const result = await client.getPets();
+} catch (error) {
+  if (isDefinedError(error, client.getPets)) {
+    // error is narrowed to GetPetsErrors (ApiError<400, ...> | ApiError<500, ...>)
+    if (error.status === 400) {
+      console.error('Bad request:', error.data);
+    }
+  }
+
+  if (error instanceof UnspecifiedApiError) {
+    console.error('Unexpected status:', error.status, error.data);
+  }
+
+  if (error instanceof RequesterFailError) {
+    console.error('Requester failed:', error.cause);
+  }
+}
+```
+
+## Feature Support
+
+Check the detailed feature support tables to see if your OpenAPI spec features are covered:
+
+- **[OpenAPI 3.0 Support](./docs/openapi-3.0-support.md)** — Data types, schema keywords, parameters, request bodies, file uploads, responses, error handling, `$ref` resolution, components, security schemes, servers, and path operations.
+- **[OpenAPI 3.1 Support](./docs/openapi-3.1-support.md)** — All 3.0 features plus type arrays, `$ref` siblings, webhooks, JSON Schema 2020-12 alignment, and a [3.0 → 3.1 diff](./docs/openapi-3.1-support.md#differences-from-openapi-30).
+
+## Requirements
+
+- Node.js >= 18
+- OpenAPI 3.0.x or 3.1.x specification (JSON or YAML, file path or URL)
+
+## License
+
+[MIT](./LICENSE) — Copyright © Andrey Kiselev

package/dist/analyzer/naming.d.ts

@@ -0,0 +1,24 @@
+import type { MethodNameStrategy } from '../types/client.js';
+/**
+ * Generate a TypeScript method name from HTTP method and path
+ * @param method HTTP method (get, post, put, patch, delete, options, head, trace)
+ * @param path URL path
+ * @returns Generated method name
+ */
+export declare function generateMethodName(method: string, path: string): string;
+/**
+ * Generate a method name from operation ID
+ * @param operationId Operation ID from OpenAPI spec
+ * @returns Generated method name in camelCase
+ */
+export declare function generateMethodNameFromOperationId(operationId: string): string;
+/**
+ * Get method name based on strategy
+ * @param method HTTP method
+ * @param path URL path
+ * @param operationId Operation ID (optional)
+ * @param strategy Method naming strategy
+ * @returns Generated method name
+ * @throws Error if operationId strategy is used but no operationId provided
+ */
+export declare function getMethodName(method: string, path: string, operationId: string | undefined, strategy: MethodNameStrategy): string;

package/dist/analyzer/naming.js

@@ -0,0 +1,122 @@
+import { toPascalCaseSegment } from '../utils/case.js';
+import { sanitizeIdentifier } from '../utils/string.js';
+import { isPathParam, extractParamName } from '../utils/url.js';
+/**
+ * Generate a TypeScript method name from HTTP method and path
+ * @param method HTTP method (get, post, put, patch, delete, options, head, trace)
+ * @param path URL path
+ * @returns Generated method name
+ */
+export function generateMethodName(method, path) {
+    const lowerMethod = method.toLowerCase();
+    // Get segments and identify parameters
+    const rawSegments = path.split('/').filter((segment) => segment.length > 0);
+    const segments = [];
+    const isParam = [];
+    for (const part of rawSegments) {
+        if (isPathParam(part)) {
+            // Extract parameter name and mark as parameter
+            const paramName = extractParamName(part);
+            isParam.push(true);
+            segments.push(paramName);
+        }
+        else if (part.startsWith(':')) {
+            // Handle standalone :param format
+            const paramName = part.substring(1);
+            isParam.push(true);
+            segments.push(paramName);
+        }
+        else if (part.includes(':')) {
+            // Handle embedded : separators (e.g., Products:change-quantity, {id}:recall)
+            const subParts = part.split(':');
+            for (let i = 0; i < subParts.length; i++) {
+                const subPart = subParts[i];
+                if (subPart === '')
+                    continue;
+                if (isPathParam(subPart)) {
+                    isParam.push(true);
+                    segments.push(extractParamName(subPart));
+                }
+                else {
+                    isParam.push(false);
+                    segments.push(subPart);
+                }
+            }
+        }
+        else {
+            // Regular segment
+            isParam.push(false);
+            segments.push(part);
+        }
+    }
+    const transformedSegments = segments.map((segment, index) => {
+        if (isParam[index]) {
+            return `By${toPascalCaseSegment(segment)}`;
+        }
+        return toPascalCaseSegment(segment);
+    });
+    return lowerMethod + transformedSegments.join('');
+}
+/**
+ * Generate a method name from operation ID
+ * @param operationId Operation ID from OpenAPI spec
+ * @returns Generated method name in camelCase
+ */
+export function generateMethodNameFromOperationId(operationId) {
+    if (!operationId) {
+        throw new Error('Operation ID cannot be empty');
+    }
+    const sanitized = sanitizeIdentifier(operationId);
+    const normalizedForCamelCase = sanitized.replace(/[$]/g, '').replace(/_/g, ' ');
+    // Split into words and convert to camelCase
+    const words = normalizedForCamelCase.split(/\s+/).filter((word) => word.length > 0);
+    if (words.length === 0) {
+        return '_';
+    }
+    // Check if the first word is a reserved word
+    const firstWord = words[0];
+    const isReservedWord = ['class', 'const', 'function', 'if', 'else', 'for', 'while', 'return', 'var', 'let'].includes(firstWord.toLowerCase()) || firstWord === 'getClass';
+    let camelCased;
+    if (isReservedWord) {
+        camelCased = '_' + firstWord.charAt(0).toLowerCase() + firstWord.slice(1);
+    }
+    else {
+        camelCased = firstWord.charAt(0).toLowerCase() + firstWord.slice(1);
+    }
+    // Add remaining words with proper capitalization
+    camelCased += words
+        .slice(1)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+    if (!camelCased || !/^[a-zA-Z_$]/.test(camelCased)) {
+        return '_' + camelCased;
+    }
+    return camelCased;
+}
+/**
+ * Get method name based on strategy
+ * @param method HTTP method
+ * @param path URL path
+ * @param operationId Operation ID (optional)
+ * @param strategy Method naming strategy
+ * @returns Generated method name
+ * @throws Error if operationId strategy is used but no operationId provided
+ */
+export function getMethodName(method, path, operationId, strategy) {
+    switch (strategy) {
+        case 'path-based':
+            return generateMethodName(method, path);
+        case 'operationId':
+            if (!operationId) {
+                throw new Error('Operation ID is required for operationId strategy but not provided');
+            }
+            return generateMethodNameFromOperationId(operationId);
+        case 'operationId-with-fallback':
+            if (operationId) {
+                return generateMethodNameFromOperationId(operationId);
+            }
+            return generateMethodName(method, path);
+        default:
+            throw new Error(`Unknown method name strategy: ${strategy}`);
+    }
+}

package/dist/analyzer/path-analyzer.d.ts

@@ -0,0 +1,53 @@
+import { RefResolver } from '../parser/ref-resolver.js';
+import type { MethodNameStrategy } from '../types/client.js';
+import type { OpenAPIDocument, ReferenceObject, SchemaObject } from '../types/openapi.js';
+export interface AnalyzedParameter {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required: boolean;
+    schema: SchemaObject | undefined;
+    tsType: string;
+    description?: string;
+    deprecated?: boolean;
+}
+export interface AnalyzedRequestBody {
+    required: boolean;
+    contentTypes: string[];
+    schema: SchemaObject | ReferenceObject | undefined;
+    tsType: string;
+    isMultipart: boolean;
+}
+export interface AnalyzedResponse {
+    statusCode: string;
+    description?: string;
+    schema: SchemaObject | ReferenceObject | undefined;
+    tsType: string;
+    isSuccess: boolean;
+    isBinary: boolean;
+}
+export interface AnalyzedOperation {
+    method: string;
+    path: string;
+    operationId: string | undefined;
+    methodName: string;
+    summary: string | undefined;
+    description: string | undefined;
+    deprecated: boolean;
+    tags: string[];
+    pathParams: AnalyzedParameter[];
+    queryParams: AnalyzedParameter[];
+    headerParams: AnalyzedParameter[];
+    cookieParams: AnalyzedParameter[];
+    requestBody: AnalyzedRequestBody | undefined;
+    responses: AnalyzedResponse[];
+}
+/**
+ * Analyze all paths and operations from an OpenAPI document into structured data
+ * for code generation.
+ *
+ * @param doc - The parsed and validated OpenAPI document
+ * @param resolver - A RefResolver for resolving $ref pointers
+ * @param strategy - Method naming strategy (defaults to 'path-based')
+ * @returns Array of AnalyzedOperation objects
+ */
+export declare function analyzePaths(doc: OpenAPIDocument, resolver: RefResolver, strategy?: MethodNameStrategy): AnalyzedOperation[];

package/dist/analyzer/path-analyzer.js

@@ -0,0 +1,222 @@
+import { RefResolver } from '../parser/ref-resolver.js';
+import { getMethodName } from './naming.js';
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
+function isRef(obj) {
+    return obj !== null && typeof obj === 'object' && '$ref' in obj;
+}
+function isBinaryContentType(ct) {
+    if (ct === 'application/octet-stream')
+        return true;
+    if (ct.startsWith('image/'))
+        return true;
+    if (ct.startsWith('video/'))
+        return true;
+    if (ct.startsWith('audio/'))
+        return true;
+    return false;
+}
+function schemaToTsType(schema, resolver) {
+    if (!schema)
+        return 'unknown';
+    if (isRef(schema)) {
+        const resolved = resolver.resolve(schema);
+        const refStr = schema.$ref;
+        const lastSegment = refStr.split('/').pop();
+        if (lastSegment && resolved.type) {
+            return lastSegment;
+        }
+        return lastSegment ?? 'unknown';
+    }
+    const s = schema;
+    if (s.type === undefined)
+        return 'unknown';
+    if (Array.isArray(s.type)) {
+        const nonNull = s.type.filter((t) => t !== 'null');
+        if (nonNull.length === 0)
+            return 'null';
+        return schemaToTsType({ ...s, type: nonNull[0] }, resolver);
+    }
+    switch (s.type) {
+        case 'string':
+            return 'string';
+        case 'integer':
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'array':
+            if (s.items) {
+                const itemType = schemaToTsType(s.items, resolver);
+                return `${itemType}[]`;
+            }
+            return 'unknown[]';
+        case 'object':
+            return 'object';
+        case 'null':
+            return 'null';
+        default:
+            return 'unknown';
+    }
+}
+function resolveParameter(param, resolver) {
+    return resolver.resolve(param);
+}
+function resolveRequestBody(body, resolver) {
+    return resolver.resolve(body);
+}
+function resolveResponse(response, resolver) {
+    return resolver.resolve(response);
+}
+function analyzeParameter(param, resolver) {
+    const schema = param.schema ? resolver.resolve(param.schema) : undefined;
+    return {
+        name: param.name,
+        in: param.in,
+        required: param.required ?? param.in === 'path',
+        schema,
+        tsType: schemaToTsType(param.schema, resolver),
+        description: param.description,
+        deprecated: param.deprecated,
+    };
+}
+function mergeParameters(pathItemParams, operationParams, resolver) {
+    const resolvedPathParams = (pathItemParams ?? []).map((p) => resolveParameter(p, resolver));
+    const resolvedOpParams = (operationParams ?? []).map((p) => resolveParameter(p, resolver));
+    const opParamMap = new Map();
+    for (const p of resolvedOpParams) {
+        opParamMap.set(`${p.name}::${p.in}`, p);
+    }
+    const merged = [];
+    for (const p of resolvedPathParams) {
+        const key = `${p.name}::${p.in}`;
+        if (!opParamMap.has(key)) {
+            merged.push(p);
+        }
+    }
+    for (const p of resolvedOpParams) {
+        merged.push(p);
+    }
+    return merged;
+}
+function analyzeRequestBody(body, resolver) {
+    if (!body)
+        return undefined;
+    const resolved = resolveRequestBody(body, resolver);
+    const contentTypes = Object.keys(resolved.content);
+    let schema;
+    let tsType = 'unknown';
+    if (contentTypes.length > 0) {
+        const firstContent = resolved.content[contentTypes[0]];
+        if (firstContent?.schema) {
+            schema = firstContent.schema;
+            tsType = schemaToTsType(schema, resolver);
+        }
+    }
+    const isMultipart = contentTypes.length > 0 && contentTypes[0] === 'multipart/form-data';
+    return {
+        required: resolved.required ?? false,
+        contentTypes,
+        schema,
+        tsType,
+        isMultipart,
+    };
+}
+function analyzeResponses(responses, resolver) {
+    const result = [];
+    for (const [statusCode, response] of Object.entries(responses)) {
+        const resolved = resolveResponse(response, resolver);
+        let schema;
+        let tsType = 'unknown';
+        let contentTypes = [];
+        if (resolved.content) {
+            contentTypes = Object.keys(resolved.content);
+            if (contentTypes.length > 0) {
+                const firstContent = resolved.content[contentTypes[0]];
+                if (firstContent?.schema) {
+                    schema = firstContent.schema;
+                    tsType = schemaToTsType(schema, resolver);
+                }
+            }
+        }
+        // Empty-body success responses → void
+        if (tsType === 'unknown' &&
+            statusCode.startsWith('2') &&
+            (!resolved.content || contentTypes.length === 0)) {
+            tsType = 'void';
+        }
+        const isBinary = contentTypes.length > 0 && isBinaryContentType(contentTypes[0]);
+        result.push({
+            statusCode,
+            description: resolved.description,
+            schema,
+            tsType,
+            isSuccess: statusCode.startsWith('2'),
+            isBinary,
+        });
+    }
+    return result;
+}
+function categorizeParameters(params) {
+    const pathParams = [];
+    const queryParams = [];
+    const headerParams = [];
+    const cookieParams = [];
+    for (const param of params) {
+        switch (param.in) {
+            case 'path':
+                pathParams.push(param);
+                break;
+            case 'query':
+                queryParams.push(param);
+                break;
+            case 'header':
+                headerParams.push(param);
+                break;
+            case 'cookie':
+                cookieParams.push(param);
+                break;
+        }
+    }
+    return { pathParams, queryParams, headerParams, cookieParams };
+}
+/**
+ * Analyze all paths and operations from an OpenAPI document into structured data
+ * for code generation.
+ *
+ * @param doc - The parsed and validated OpenAPI document
+ * @param resolver - A RefResolver for resolving $ref pointers
+ * @param strategy - Method naming strategy (defaults to 'path-based')
+ * @returns Array of AnalyzedOperation objects
+ */
+export function analyzePaths(doc, resolver, strategy = 'path-based') {
+    const operations = [];
+    if (!doc.paths)
+        return operations;
+    for (const [urlPath, pathItem] of Object.entries(doc.paths)) {
+        for (const method of HTTP_METHODS) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            const mergedParams = mergeParameters(pathItem.parameters, operation.parameters, resolver);
+            const analyzedParams = mergedParams.map((p) => analyzeParameter(p, resolver));
+            const categorized = categorizeParameters(analyzedParams);
+            const requestBody = analyzeRequestBody(operation.requestBody, resolver);
+            const responses = analyzeResponses(operation.responses, resolver);
+            const methodName = getMethodName(method, urlPath, operation.operationId, strategy);
+            operations.push({
+                method,
+                path: urlPath,
+                operationId: operation.operationId,
+                methodName,
+                summary: operation.summary,
+                description: operation.description,
+                deprecated: operation.deprecated ?? false,
+                tags: operation.tags ?? [],
+                ...categorized,
+                requestBody,
+                responses,
+            });
+        }
+    }
+    return operations;
+}