genoc 0.3.0 → 0.4.1

package/dist/utils/generator-helpers.js

@@ -82,27 +82,6 @@ const RESERVED_WORDS = new Set([
 function isReservedTypeName(name) {
     return RESERVED_WORDS.has(name);
 }
-/**
- * Reserved type names used by the generated output's built-in classes,
- * functions, and types. User-defined schema names that collide with these
- * are automatically renamed with a suffix to prevent duplicate identifiers.
- */
-export const RESERVED_TYPE_NAMES = new Set([
-    // Classes in contracts.ts
-    'StreamResponse',
-    'ErrorResponse',
-    'ApiError',
-    'UnspecifiedApiError',
-    'DefaultApiError',
-    'RequesterFailError',
-    // Types / functions in client.ts
-    'Requester',
-    'isDefinedError',
-    'decorateWithErrors',
-    'ApiClient',
-    // Interface in contracts.ts (when file uploads present)
-    'FileInput',
-]);
 /** Default module specifier generated code imports shared runtime classes from. */
 export const DEFAULT_RUNTIME_IMPORT_PATH = 'genoc/runtime';
 /**
@@ -187,63 +166,6 @@ export function toPascalCase(str) {
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
         .join('');
 }
-/**
- * Build a PascalCase type-name prefix from an operation's method + path.
- * get + /api/v1/products → "GetApiV1Products"
- *
- * Returns the deduped prefix assigned by analyzePaths when available
- * (distinct routes folding to the same identifier get numbered suffixes),
- * otherwise computes it from the operation directly.
- */
-export function getOperationTypePrefix(op) {
-    if (op.typePrefix)
-        return op.typePrefix;
-    return computeOperationTypePrefix(op);
-}
-function computeOperationTypePrefix(op) {
-    const methodPascal = op.method.charAt(0).toUpperCase() + op.method.slice(1).toLowerCase();
-    const segments = op.path
-        .split('/')
-        .filter((s) => s.length > 0)
-        .map((s) => {
-        const cleaned = s.replace(/[{}]/g, '');
-        return sanitizeTypeName(toPascalCase(cleaned));
-    });
-    return methodPascal + segments.join('');
-}
-/**
- * Determine the success return type for an operation.
- */
-export function getSuccessType(op) {
-    const successResponses = op.responses.filter((r) => r.isSuccess);
-    if (successResponses.length === 0) {
-        return 'unknown';
-    }
-    const noContent = successResponses.find((r) => r.tsType === 'void');
-    const hasOnlyNoContent = noContent && successResponses.every((r) => r.tsType === 'void');
-    if (hasOnlyNoContent) {
-        return 'void';
-    }
-    const withSchema = successResponses.filter((r) => r.tsType !== 'void');
-    if (withSchema.length === 0) {
-        return 'void';
-    }
-    const prefix = getOperationTypePrefix(op);
-    const types = withSchema.map(() => `${prefix}Response`);
-    const unique = [...new Set(types)];
-    return unique.join(' | ');
-}
-/**
- * Determine the error type name for an operation.
- */
-export function getErrorType(op) {
-    const prefix = getOperationTypePrefix(op);
-    const errorResponses = op.responses.filter((r) => !r.isSuccess && r.statusCode !== 'default');
-    if (errorResponses.length === 0) {
-        return 'never';
-    }
-    return `${prefix}Errors`;
-}
 /**
  * Generate the auto-generated header comment.
  */
@@ -325,3 +247,14 @@ export function buildTypeJsDoc(schema) {
         return `/** ${lines[0]} */`;
     return `/**\n${lines.map((line) => ` * ${line}`).join('\n *\n')}\n */`;
 }
+export 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;
+}

package/dist/utils/operation-naming.d.ts

@@ -0,0 +1,84 @@
+import type { AnalyzedOperation } from '../analyzer/path-analyzer.js';
+/**
+ * Canonical runtime class list in the contracts re-export order. Membership
+ * source of truth for every runtime class name the generators emit.
+ */
+export declare const RUNTIME_CLASS_NAMES: readonly ["ApiError", "UnspecifiedApiError", "DefaultApiError", "RequesterFailError", "StreamResponse", "ErrorResponse"];
+/**
+ * client.ts value imports from contracts.js in site emission order.
+ * `DefaultApiError` is conditional (only when an operation has a default
+ * error response), so it is appended by the client generator, not listed here.
+ */
+export declare const CLIENT_BASE_VALUE_IMPORTS: readonly ["ApiError", "UnspecifiedApiError", "ErrorResponse", "StreamResponse", "RequesterFailError"];
+/** Fixed client-file surface names (values and types client.ts declares). */
+export declare const CLIENT_SURFACE_NAMES: readonly ["Requester", "isDefinedError", "decorateWithErrors", "ApiClient", "createClient"];
+/**
+ * Reserved type names used by the generated output's built-in classes,
+ * functions, and types. User-defined schema names that collide with these
+ * are automatically renamed with a suffix to prevent duplicate identifiers.
+ *
+ * Derived — never hand-edited: add new fixed names to the owning constant
+ * (`RUNTIME_CLASS_NAMES` / `CLIENT_SURFACE_NAMES`) or, for contracts-only
+ * interfaces like `FileInput`, extend the derivation below.
+ */
+export declare const RESERVED_TYPE_NAMES: ReadonlySet<string>;
+/**
+ * Build a PascalCase type-name prefix from an operation's method + path.
+ * get + /api/v1/products → "GetApiV1Products"
+ *
+ * Returns the deduped prefix assigned by analyzePaths when available
+ * (distinct routes folding to the same identifier get numbered suffixes),
+ * otherwise computes it from the operation directly.
+ */
+export declare function getOperationTypePrefix(op: AnalyzedOperation): string;
+/**
+ * Determine the success return type for an operation.
+ */
+export declare function getSuccessType(op: AnalyzedOperation): string;
+/**
+ * Determine the error type name for an operation.
+ */
+export declare function getErrorType(op: AnalyzedOperation): string;
+/** Name of one per-status error type (`{prefix}Error{status}`). */
+export interface StatusErrorName {
+    status: string;
+    name: string;
+}
+/**
+ * Inventory of every operation-derived type name the contracts file emits
+ * for one operation. A field is present exactly when the contracts loop
+ * emits that type — presence and naming are decided here and nowhere else.
+ *
+ * The client file imports a subset of this inventory (`clientImportedNames`);
+ * the asymmetry is deliberate: e.g. 204-only operations emit
+ * `{prefix}Response = void` which the client does not import.
+ */
+export interface OperationEmissions {
+    query?: string;
+    headers?: string;
+    body?: string;
+    response?: string;
+    statusErrors: StatusErrorName[];
+    defaultError?: string;
+    errorsUnion?: string;
+}
+/**
+ * Derive the emission inventory for an operation. Pure function of the
+ * AnalyzedOperation — no mapper or resolver state participates in naming
+ * or presence decisions.
+ */
+export declare function operationEmissions(op: AnalyzedOperation): OperationEmissions;
+/**
+ * Type names the client file imports from contracts for one operation.
+ *
+ * Deliberately a subset of the emission inventory: the client names the
+ * response type only when the success type is a named type — 204-only
+ * operations emit `{prefix}Response = void` in contracts, but the client
+ * method returns `void` without ever naming the type.
+ */
+export declare function clientImportedNames(op: AnalyzedOperation): string[];
+/**
+ * Value imports for the client file: the fixed base list plus
+ * `DefaultApiError` when any operation has a default error response.
+ */
+export declare function clientValueImports(operations: AnalyzedOperation[]): string[];

package/dist/utils/operation-naming.js

@@ -0,0 +1,178 @@
+import { sanitizeTypeName, toPascalCase } from './generator-helpers.js';
+/**
+ * Canonical runtime class list in the contracts re-export order. Membership
+ * source of truth for every runtime class name the generators emit.
+ */
+export const RUNTIME_CLASS_NAMES = [
+    'ApiError',
+    'UnspecifiedApiError',
+    'DefaultApiError',
+    'RequesterFailError',
+    'StreamResponse',
+    'ErrorResponse',
+];
+/**
+ * client.ts value imports from contracts.js in site emission order.
+ * `DefaultApiError` is conditional (only when an operation has a default
+ * error response), so it is appended by the client generator, not listed here.
+ */
+export const CLIENT_BASE_VALUE_IMPORTS = [
+    'ApiError',
+    'UnspecifiedApiError',
+    'ErrorResponse',
+    'StreamResponse',
+    'RequesterFailError',
+];
+/** Fixed client-file surface names (values and types client.ts declares). */
+export const CLIENT_SURFACE_NAMES = [
+    'Requester',
+    'isDefinedError',
+    'decorateWithErrors',
+    'ApiClient',
+    'createClient',
+];
+/**
+ * Reserved type names used by the generated output's built-in classes,
+ * functions, and types. User-defined schema names that collide with these
+ * are automatically renamed with a suffix to prevent duplicate identifiers.
+ *
+ * Derived — never hand-edited: add new fixed names to the owning constant
+ * (`RUNTIME_CLASS_NAMES` / `CLIENT_SURFACE_NAMES`) or, for contracts-only
+ * interfaces like `FileInput`, extend the derivation below.
+ */
+export const RESERVED_TYPE_NAMES = new Set([
+    ...RUNTIME_CLASS_NAMES,
+    ...CLIENT_SURFACE_NAMES,
+    'FileInput',
+]);
+/**
+ * Build a PascalCase type-name prefix from an operation's method + path.
+ * get + /api/v1/products → "GetApiV1Products"
+ *
+ * Returns the deduped prefix assigned by analyzePaths when available
+ * (distinct routes folding to the same identifier get numbered suffixes),
+ * otherwise computes it from the operation directly.
+ */
+export function getOperationTypePrefix(op) {
+    if (op.typePrefix)
+        return op.typePrefix;
+    return computeOperationTypePrefix(op);
+}
+function computeOperationTypePrefix(op) {
+    const methodPascal = op.method.charAt(0).toUpperCase() + op.method.slice(1).toLowerCase();
+    const segments = op.path
+        .split('/')
+        .filter((s) => s.length > 0)
+        .map((s) => {
+        const cleaned = s.replace(/[{}]/g, '');
+        return sanitizeTypeName(toPascalCase(cleaned));
+    });
+    return methodPascal + segments.join('');
+}
+/**
+ * Classify a response as void by its finished type text. The finished type
+ * is `'void'` exactly for schema-less, non-binary 2xx responses — the same
+ * condition the analyzer records as `isVoid`.
+ */
+function isVoidResponse(r) {
+    return r.finishedType === 'void';
+}
+/**
+ * Determine the success return type for an operation.
+ */
+export function getSuccessType(op) {
+    const successResponses = op.responses.filter((r) => r.isSuccess);
+    if (successResponses.length === 0) {
+        return 'unknown';
+    }
+    const noContent = successResponses.find((r) => isVoidResponse(r));
+    const hasOnlyNoContent = noContent && successResponses.every((r) => isVoidResponse(r));
+    if (hasOnlyNoContent) {
+        return 'void';
+    }
+    const withSchema = successResponses.filter((r) => !isVoidResponse(r));
+    if (withSchema.length === 0) {
+        return 'void';
+    }
+    const prefix = getOperationTypePrefix(op);
+    const types = withSchema.map(() => `${prefix}Response`);
+    const unique = [...new Set(types)];
+    return unique.join(' | ');
+}
+/**
+ * Determine the error type name for an operation.
+ */
+export function getErrorType(op) {
+    const prefix = getOperationTypePrefix(op);
+    const errorResponses = op.responses.filter((r) => !r.isSuccess && r.statusCode !== 'default');
+    if (errorResponses.length === 0) {
+        return 'never';
+    }
+    return `${prefix}Errors`;
+}
+/**
+ * Derive the emission inventory for an operation. Pure function of the
+ * AnalyzedOperation — no mapper or resolver state participates in naming
+ * or presence decisions.
+ */
+export function operationEmissions(op) {
+    const prefix = getOperationTypePrefix(op);
+    const errorResponses = op.responses.filter((r) => !r.isSuccess && r.statusCode !== 'default');
+    const statusErrors = errorResponses.map((r) => ({
+        status: r.statusCode,
+        name: `${prefix}Error${r.statusCode}`,
+    }));
+    return {
+        query: op.queryParams.length > 0 ? `${prefix}Query` : undefined,
+        headers: op.headerParams.length > 0 ? `${prefix}Headers` : undefined,
+        body: op.requestBody?.hasSchema ? `${prefix}Body` : undefined,
+        response: op.responses.some((r) => r.isSuccess) ? `${prefix}Response` : undefined,
+        statusErrors,
+        defaultError: op.responses.some((r) => !r.isSuccess && r.statusCode === 'default')
+            ? `${prefix}DefaultError`
+            : undefined,
+        errorsUnion: statusErrors.length > 0 ? `${prefix}Errors` : undefined,
+    };
+}
+/**
+ * Type names the client file imports from contracts for one operation.
+ *
+ * Deliberately a subset of the emission inventory: the client names the
+ * response type only when the success type is a named type — 204-only
+ * operations emit `{prefix}Response = void` in contracts, but the client
+ * method returns `void` without ever naming the type.
+ */
+export function clientImportedNames(op) {
+    const emissions = operationEmissions(op);
+    const names = [];
+    if (emissions.query !== undefined)
+        names.push(emissions.query);
+    if (emissions.headers !== undefined)
+        names.push(emissions.headers);
+    if (emissions.body !== undefined)
+        names.push(emissions.body);
+    if (emissions.response !== undefined) {
+        const successType = getSuccessType(op);
+        if (successType !== 'void' && successType !== 'unknown' && /^[A-Z]/.test(successType)) {
+            names.push(successType);
+        }
+    }
+    for (const statusError of emissions.statusErrors) {
+        names.push(statusError.name);
+    }
+    if (emissions.errorsUnion !== undefined)
+        names.push(emissions.errorsUnion);
+    if (emissions.defaultError !== undefined)
+        names.push(emissions.defaultError);
+    return names;
+}
+/**
+ * Value imports for the client file: the fixed base list plus
+ * `DefaultApiError` when any operation has a default error response.
+ */
+export function clientValueImports(operations) {
+    const needsDefaultApiError = operations.some((op) => operationEmissions(op).defaultError !== undefined);
+    return needsDefaultApiError
+        ? [...CLIENT_BASE_VALUE_IMPORTS, 'DefaultApiError']
+        : [...CLIENT_BASE_VALUE_IMPORTS];
+}

package/dist/utils/proxy.d.ts

@@ -3,4 +3,6 @@ export type LoadOptions = {
 };
 export declare function assertValidProxyUrl(url: string): void;
 export declare function hasProxyEnv(): boolean;
+/** True when the dynamic `import('undici')` failed because undici is not installed (Node: ERR_MODULE_NOT_FOUND; Bun: "Cannot find package" message). */
+export declare function isMissingUndiciError(err: unknown): boolean;
 export declare function fetchSpec(url: string, opts?: LoadOptions): Promise<Response>;

package/dist/utils/proxy.js

@@ -48,6 +48,16 @@ export function hasProxyEnv() {
         process.env.HTTPS_PROXY ||
         process.env.https_proxy);
 }
+/** True when the dynamic `import('undici')` failed because undici is not installed (Node: ERR_MODULE_NOT_FOUND; Bun: "Cannot find package" message). */
+export function isMissingUndiciError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const code = err.code;
+    if (code === 'ERR_MODULE_NOT_FOUND')
+        return true;
+    return /Cannot find (?:module|package) ['"]?undici/.test(err.message);
+}
+const MISSING_UNDICI_MESSAGE = "Proxy support requires the 'undici' package. Install it: npm install undici";
 export async function fetchSpec(url, opts) {
     if (opts?.proxy) {
         assertValidProxyUrl(opts.proxy);
@@ -59,6 +69,9 @@ export async function fetchSpec(url, opts) {
             }));
         }
         catch (err) {
+            if (isMissingUndiciError(err)) {
+                throw new Error(MISSING_UNDICI_MESSAGE);
+            }
             throw new Error(`Failed to fetch spec from URL via proxy ${redacted}: ${describeFetchError(err)}`, {
                 cause: err,
             });
@@ -72,6 +85,9 @@ export async function fetchSpec(url, opts) {
             }));
         }
         catch (err) {
+            if (isMissingUndiciError(err)) {
+                throw new Error(MISSING_UNDICI_MESSAGE);
+            }
             throw new Error(`Failed to fetch spec from URL via proxy env: ${describeFetchError(err)}`, {
                 cause: err,
             });

package/dist/utils/string.d.ts

@@ -26,6 +26,13 @@ export declare function isReservedWord(str: string): boolean;
  * @returns Safe TypeScript identifier
  */
 export declare function sanitizeIdentifier(str: string): string;
+/**
+ * Escape a value for interpolation inside a TypeScript single-quoted string
+ * literal (backslash first, then the quote itself)
+ * @param value The raw string value
+ * @returns The value with `\` and `'` escaped
+ */
+export declare function escapeStringLiteral(value: string): string;
 /**
  * Quote a key if needed for TypeScript object literals
  * @param key The key to potentially quote

package/dist/utils/string.js

@@ -163,6 +163,15 @@ export function sanitizeIdentifier(str) {
     }
     return final;
 }
+/**
+ * Escape a value for interpolation inside a TypeScript single-quoted string
+ * literal (backslash first, then the quote itself)
+ * @param value The raw string value
+ * @returns The value with `\` and `'` escaped
+ */
+export function escapeStringLiteral(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
 /**
  * Quote a key if needed for TypeScript object literals
  * @param key The key to potentially quote

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genoc",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Generate typed HTTP clients from OpenAPI 3.0 / 3.1 specifications",
   "keywords": [
     "client",
@@ -22,13 +22,7 @@
     "dist"
   ],
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
     "./runtime": {
       "import": "./dist/runtime/index.js",
       "types": "./dist/runtime/index.d.ts"
@@ -48,18 +42,28 @@
   },
   "dependencies": {
     "@stricli/core": "^1.2.6",
-    "undici": "^6.13.0",
-    "yaml": "^2.8.4"
+    "lilconfig": "^3.1.3",
+    "yaml": "^2.2.2",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.31.0",
-    "@types/node": "^25.6.0",
-    "oxfmt": "^0.48.0",
-    "oxlint": "^1.63.0",
+    "@changesets/cli": "^3.0.3",
+    "@types/node": "^26.6.2",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "undici": "^8",
+    "vitest": "^5.0.1"
+  },
+  "peerDependencies": {
+    "undici": "^6.13.0 || ^7 || ^8"
+  },
+  "peerDependenciesMeta": {
+    "undici": {
+      "optional": true
+    }
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.18.1"
   }
 }

package/dist/index.d.ts

@@ -1,9 +0,0 @@
-import { type ApiClient } from './generator/client-generator.js';
-import type { GeneratorConfig } from './types/client.js';
-import { type LoadOptions } from './utils/proxy.js';
-export declare function generateClient(config: GeneratorConfig): Promise<void>;
-export { ApiError, UnspecifiedApiError, DefaultApiError, RequesterFailError, StreamResponse, ErrorResponse, decorateWithErrors, isDefinedError, } from './runtime/index.js';
-export type { Requester } from './runtime/index.js';
-export type { GeneratorConfig, ApiClient, LoadOptions };
-export type { GenerationOptions } from './generator/client-generator.js';
-export { load as loadSpec } from './parser/spec-reader.js';

package/dist/index.js

@@ -1,11 +0,0 @@
-import { generateFullOutput } from './generator/client-generator.js';
-import { load } from './parser/spec-reader.js';
-import { assertValidProxyUrl } from './utils/proxy.js';
-export async function generateClient(config) {
-    if (config.proxy)
-        assertValidProxyUrl(config.proxy);
-    const doc = await load(config.input, { proxy: config.proxy });
-    await generateFullOutput(doc, config);
-}
-export { ApiError, UnspecifiedApiError, DefaultApiError, RequesterFailError, StreamResponse, ErrorResponse, decorateWithErrors, isDefinedError, } from './runtime/index.js';
-export { load as loadSpec } from './parser/spec-reader.js';

package/dist/parser/validators.d.ts

@@ -1,7 +0,0 @@
-import type { VersionStrategy } from './version/version-strategy.js';
-export interface ValidationResult {
-    valid: boolean;
-    errors: string[];
-}
-export declare function validateOpenAPIVersion(version: string): boolean;
-export declare function validateSpec(doc: unknown, strategy?: VersionStrategy): ValidationResult;

package/dist/parser/validators.js

@@ -1,79 +0,0 @@
-export function validateOpenAPIVersion(version) {
-    return typeof version === 'string' && version.startsWith('3.1');
-}
-export function validateSpec(doc, strategy) {
-    if (strategy) {
-        try {
-            const normalized = strategy.normalizeSpec(doc);
-            return strategy.validateSpec(normalized);
-        }
-        catch (error) {
-            // normalizeSpec may throw for structurally invalid specs;
-            // but re-throw "not yet supported" errors
-            if (typeof error === 'object' && error !== null && 'message' in error) {
-                const errorMessage = error.message;
-                if (errorMessage.includes('not yet supported')) {
-                    throw error;
-                }
-            }
-            // fall through to default 3.1-only validation below
-        }
-    }
-    const errors = [];
-    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
-        errors.push('Document must be an object');
-        return { valid: false, errors };
-    }
-    const spec = doc;
-    // Check openapi field
-    if (!spec.openapi || typeof spec.openapi !== 'string') {
-        errors.push("OpenAPI specification must have an 'openapi' field with string value");
-    }
-    else if (!validateOpenAPIVersion(spec.openapi)) {
-        errors.push(`OpenAPI version must start with '3.1', got: ${spec.openapi}`);
-    }
-    // Check info field
-    if (!spec.info || typeof spec.info !== 'object' || Array.isArray(spec.info)) {
-        errors.push("OpenAPI specification must have an 'info' field with object value");
-    }
-    else {
-        const info = spec.info;
-        if (!info.title || typeof info.title !== 'string') {
-            errors.push("Info object must have a 'title' field with string value");
-        }
-        if (!info.version || typeof info.version !== 'string') {
-            errors.push("Info object must have a 'version' field with string value");
-        }
-    }
-    // Check at least one of paths, components, webhooks exists
-    if (!spec.paths && !spec.components && !spec.webhooks) {
-        errors.push("OpenAPI specification must have at least one of 'paths', 'components', or 'webhooks'");
-    }
-    // Validate paths if it exists
-    if (spec.paths) {
-        if (Array.isArray(spec.paths) || typeof spec.paths !== 'object') {
-            errors.push("'paths' field must be an object");
-        }
-    }
-    // Validate components.schemas if it exists
-    if (spec.components && typeof spec.components === 'object' && !Array.isArray(spec.components)) {
-        const components = spec.components;
-        if (components.schemas) {
-            if (Array.isArray(components.schemas) || typeof components.schemas !== 'object') {
-                errors.push("'components.schemas' must be an object");
-            }
-            else {
-                const schemas = components.schemas;
-                for (const [key, schema] of Object.entries(schemas)) {
-                    if (typeof schema !== 'object' || Array.isArray(schema)) {
-                        errors.push(`Schema '${key}' must be an object`);
-                    }
-                }
-            }
-        }
-    }
-    return {
-        valid: errors.length === 0,
-        errors,
-    };
-}