genoc 0.1.3 → 0.3.0

package/dist/runtime/defined-errors.js

@@ -0,0 +1,27 @@
+import { ApiError, UnspecifiedApiError } from './errors.js';
+/**
+ * Attaches the `__definedErrors` metadata property to a client method.
+ * The property carries the method's error codes and is used by
+ * `isDefinedError` for type narrowing.
+ */
+export function decorateWithErrors(item, runtimeErrors) {
+    Object.defineProperty(item, '__definedErrors', {
+        value: runtimeErrors,
+        enumerable: false,
+        configurable: true,
+        writable: false,
+    });
+    return item;
+}
+/**
+ * Type guard that narrows a caught error to a method's defined error union.
+ * Returns false for `UnspecifiedApiError` (status not declared in the spec)
+ * and for anything that is not an `ApiError`.
+ */
+export function isDefinedError(err, _fn) {
+    if (err instanceof UnspecifiedApiError)
+        return false;
+    if (!(err instanceof ApiError))
+        return false;
+    return true;
+}

package/dist/runtime/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared error classes for generated clients.
+ *
+ * This module is the single source of truth for error class identity:
+ * both generated client code and user-provided `Requester` implementations
+ * import these classes, so `instanceof` checks work across module boundaries.
+ */
+/** Error thrown for a specific status code declared in the spec. */
+export declare class ApiError<TStatus extends number, TData> extends Error {
+    readonly status: TStatus;
+    readonly data: TData;
+    constructor(status: TStatus, data: TData, message: string);
+}
+/** Error thrown for a status code not declared in the spec. */
+export declare class UnspecifiedApiError extends ApiError<number, unknown> {
+    constructor(status: number, data: unknown, message: string);
+}
+/** Error thrown for operations that declare a `default` response. */
+export declare class DefaultApiError<TData> extends Error {
+    readonly status: number;
+    readonly data: TData;
+    constructor(status: number, data: TData, message: string);
+}
+/** Wraps unexpected failures inside a `Requester` implementation. */
+export declare class RequesterFailError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}

package/dist/runtime/errors.js

@@ -0,0 +1,45 @@
+/**
+ * Shared error classes for generated clients.
+ *
+ * This module is the single source of truth for error class identity:
+ * both generated client code and user-provided `Requester` implementations
+ * import these classes, so `instanceof` checks work across module boundaries.
+ */
+/** Error thrown for a specific status code declared in the spec. */
+export class ApiError extends Error {
+    status;
+    data;
+    constructor(status, data, message) {
+        super(message);
+        this.status = status;
+        this.data = data;
+        this.name = 'ApiError';
+    }
+}
+/** Error thrown for a status code not declared in the spec. */
+export class UnspecifiedApiError extends ApiError {
+    constructor(status, data, message) {
+        super(status, data, message);
+        this.name = 'UnspecifiedApiError';
+    }
+}
+/** Error thrown for operations that declare a `default` response. */
+export class DefaultApiError extends Error {
+    status;
+    data;
+    constructor(status, data, message) {
+        super(message);
+        this.status = status;
+        this.data = data;
+        this.name = 'DefaultApiError';
+    }
+}
+/** Wraps unexpected failures inside a `Requester` implementation. */
+export class RequesterFailError extends Error {
+    cause;
+    constructor(cause) {
+        super(`Request failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.cause = cause;
+        this.name = 'RequesterFailError';
+    }
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public runtime contract shared by generated clients and user-provided
+ * `Requester` implementations.
+ *
+ * Import from `genoc/runtime` — the main `genoc` entry point is the
+ * generator API (dev-time only); this subpath is the tiny runtime surface.
+ */
+export { ApiError, UnspecifiedApiError, DefaultApiError, RequesterFailError } from './errors.js';
+export { StreamResponse, ErrorResponse } from './responses.js';
+export { decorateWithErrors, isDefinedError } from './defined-errors.js';
+export type { Requester } from './requester.js';

package/dist/runtime/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public runtime contract shared by generated clients and user-provided
+ * `Requester` implementations.
+ *
+ * Import from `genoc/runtime` — the main `genoc` entry point is the
+ * generator API (dev-time only); this subpath is the tiny runtime surface.
+ */
+export { ApiError, UnspecifiedApiError, DefaultApiError, RequesterFailError } from './errors.js';
+export { StreamResponse, ErrorResponse } from './responses.js';
+export { decorateWithErrors, isDefinedError } from './defined-errors.js';

package/dist/runtime/requester.d.ts

@@ -0,0 +1,14 @@
+import type { ErrorResponse, StreamResponse } from './responses.js';
+/**
+ * Performs an HTTP request and returns the response.
+ *
+ * When `expectStream` is true, the implementation should return
+ * a `StreamResponse` containing the stream data, filename (from
+ * Content-Disposition header), and response headers.
+ */
+export type Requester = <TResponse>(method: string, path: string, options: {
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    expectStream?: true;
+}) => Promise<TResponse | StreamResponse | ErrorResponse>;

package/dist/runtime/requester.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/responses.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared response containers exchanged between generated clients and
+ * `Requester` implementations.
+ */
+/** Container for binary/stream responses returned by a `Requester`. */
+export declare class StreamResponse {
+    readonly data: ReadableStream<Uint8Array>;
+    readonly filename?: string;
+    readonly headers: Record<string, string>;
+    constructor(data: ReadableStream<Uint8Array>, filename?: string, headers?: Record<string, string>);
+}
+/** Container for non-2xx responses returned by a `Requester`. */
+export declare class ErrorResponse {
+    readonly status: number;
+    readonly data: unknown;
+    readonly headers: Record<string, string>;
+    readonly message?: string;
+    constructor(status: number, data: unknown, headers?: Record<string, string>, message?: string);
+}

package/dist/runtime/responses.js

@@ -0,0 +1,28 @@
+/**
+ * Shared response containers exchanged between generated clients and
+ * `Requester` implementations.
+ */
+/** Container for binary/stream responses returned by a `Requester`. */
+export class StreamResponse {
+    data;
+    filename;
+    headers;
+    constructor(data, filename, headers = {}) {
+        this.data = data;
+        this.filename = filename;
+        this.headers = headers;
+    }
+}
+/** Container for non-2xx responses returned by a `Requester`. */
+export class ErrorResponse {
+    status;
+    data;
+    headers;
+    message;
+    constructor(status, data, headers = {}, message) {
+        this.status = status;
+        this.data = data;
+        this.headers = headers;
+        this.message = message;
+    }
+}

package/dist/types/client.d.ts

@@ -6,6 +6,8 @@ export type GeneratorConfig = {
     requesterModuleName?: string;
     specVersion?: string;
     strictVersion?: boolean;
+    runtimeImportPath?: string;
+    proxy?: string;
 };
 export type RequesterFunction = <TResponse>(method: string, path: string, options: {
     query?: Record<string, unknown>;

package/dist/types/openapi.d.ts

@@ -16,6 +16,10 @@ export type SchemaObject = {
     const?: unknown;
     default?: unknown;
     description?: string;
+    title?: string;
+    deprecated?: boolean;
+    example?: unknown;
+    examples?: unknown[];
     nullable?: boolean;
     readOnly?: boolean;
     writeOnly?: boolean;

package/dist/utils/generator-helpers.d.ts

@@ -1,20 +1,40 @@
 import type { AnalyzedOperation } from '../analyzer/path-analyzer.js';
+import type { SchemaObject } from '../types/openapi.js';
 /**
  * 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 declare const RESERVED_TYPE_NAMES: ReadonlySet<string>;
+/** Default module specifier generated code imports shared runtime classes from. */
+export declare const DEFAULT_RUNTIME_IMPORT_PATH = "genoc/runtime";
 /**
- * Sanitize a schema type name by converting dot-separated segments into
- * PascalCase. Names without dots pass through unchanged.
+ * Sanitize a schema type name into a valid TypeScript identifier.
  *
- * "Api.Error" → "ApiError", "Simple" → "Simple"
+ * Any run of non-identifier characters (dots, brackets, backticks, hyphens,
+ * spaces, slashes, ...) splits the name into segments that are re-joined in
+ * PascalCase:
+ *
+ *   "Api.Error"  → "ApiError"
+ *   "User[Dto]"  → "UserDto"
+ *   "my-schema"  → "MySchema"
+ *   "payment id" → "PaymentId"
+ *
+ * Names that are already valid identifiers pass through unchanged
+ * ("User", "my_schema", "mySchema", "$Foo", "Данные"). Results that would
+ * start with a digit ("2FA") get an "_" prefix, as do exact reserved words
+ * ("class" → "_class"). Names with no usable characters collapse to "_".
  */
 export declare function sanitizeTypeName(name: string): string;
 /**
- * Build a mapping of sanitized schema names → renamed names for any that
- * collide with reserved type names.
+ * Build a mapping of raw schema names → renamed names for any whose
+ * sanitized name collides with a reserved type name or with another
+ * schema's sanitized name (e.g. "User-Dto" and "User[Dto]" both → "UserDto").
+ *
+ * The map is keyed by the raw schema name (component keys are unique by
+ * construction), so callers resolve raw $ref segments / schema keys first
+ * and fall back to sanitizeTypeName for the common no-collision case.
+ * Numbered suffixes are used when the first renamed candidate also collides.
  */
 export declare function buildSchemaRenameMap(schemaNames: Iterable<string>, reserved: ReadonlySet<string>, suffix?: string): Map<string, string>;
 /**
@@ -25,6 +45,10 @@ export declare function toPascalCase(str: string): 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;
 /**
@@ -39,3 +63,34 @@ export declare function getErrorType(op: AnalyzedOperation): string;
  * Generate the auto-generated header comment.
  */
 export declare function makeHeader(version: string): string;
+/**
+ * Sanitize free-form text for safe inclusion inside a JSDoc comment.
+ *
+ * Normalizes CRLF to LF, flattens remaining newlines into single spaces,
+ * escapes the comment-closing sequence (asterisk + slash) as `*\/`, and
+ * trims leading/trailing whitespace. No other transformation is applied —
+ * no HTML stripping, no markdown processing, no wrapping.
+ */
+export declare function sanitizeJsDocText(text: string): string;
+/**
+ * Format an arbitrary metadata value for a JSDoc tag using JSON.stringify
+ * (no indent). Returns `null` when stringify yields `undefined` (e.g. for
+ * `undefined` or function values) — callers should skip the tag entirely.
+ */
+export declare function formatJsDocValue(value: unknown): string | null;
+/**
+ * Build the ordered JSDoc content segments for a schema-backed property.
+ *
+ * Order (frozen): description → `@deprecated` → `@default` → `@example`(s)
+ * → `@title`. Segments are skipped when their value is absent, empty, or
+ * whitespace-only. Sanitization is applied AFTER stringification for
+ * `@default` / `@example` values.
+ */
+export declare function buildFieldJsDocLines(schema: SchemaObject): string[];
+/**
+ * Render a schema's JSDoc metadata as a complete comment block.
+ *
+ * 0 segments → `''`; exactly 1 segment → single-line `/** text *\/`;
+ * ≥2 segments → multiline block with a blank ` *` line between segments.
+ */
+export declare function buildTypeJsDoc(schema: SchemaObject): string;

package/dist/utils/generator-helpers.js

@@ -1,3 +1,87 @@
+/**
+ * TypeScript/JavaScript reserved words, matched case-sensitively: a type
+ * named "Null" or "Class" is legal, only the exact lowercase keywords are.
+ */
+const RESERVED_WORDS = new Set([
+    'abstract',
+    'any',
+    'as',
+    'asserts',
+    'assert',
+    'async',
+    'await',
+    'boolean',
+    'break',
+    'case',
+    'catch',
+    'class',
+    'continue',
+    'const',
+    'constructor',
+    'debugger',
+    'declare',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'enum',
+    'export',
+    'extends',
+    'false',
+    'finally',
+    'for',
+    'from',
+    'function',
+    'get',
+    'if',
+    'implements',
+    'import',
+    'in',
+    'infer',
+    'instanceof',
+    'interface',
+    'is',
+    'keyof',
+    'let',
+    'module',
+    'namespace',
+    'never',
+    'new',
+    'null',
+    'number',
+    'object',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'readonly',
+    'require',
+    'return',
+    'satisfies',
+    'set',
+    'static',
+    'string',
+    'super',
+    'switch',
+    'symbol',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'type',
+    'typeof',
+    'undefined',
+    'unique',
+    'unknown',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+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
@@ -11,9 +95,6 @@ export const RESERVED_TYPE_NAMES = new Set([
     'UnspecifiedApiError',
     'DefaultApiError',
     'RequesterFailError',
-    // Functions in contracts.ts
-    'streamResponse',
-    'errorResponse',
     // Types / functions in client.ts
     'Requester',
     'isDefinedError',
@@ -22,31 +103,75 @@ export const RESERVED_TYPE_NAMES = new Set([
     // 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';
 /**
- * Sanitize a schema type name by converting dot-separated segments into
- * PascalCase. Names without dots pass through unchanged.
+ * Sanitize a schema type name into a valid TypeScript identifier.
+ *
+ * Any run of non-identifier characters (dots, brackets, backticks, hyphens,
+ * spaces, slashes, ...) splits the name into segments that are re-joined in
+ * PascalCase:
  *
- * "Api.Error" → "ApiError", "Simple" → "Simple"
+ *   "Api.Error"  → "ApiError"
+ *   "User[Dto]"  → "UserDto"
+ *   "my-schema"  → "MySchema"
+ *   "payment id" → "PaymentId"
+ *
+ * Names that are already valid identifiers pass through unchanged
+ * ("User", "my_schema", "mySchema", "$Foo", "Данные"). Results that would
+ * start with a digit ("2FA") get an "_" prefix, as do exact reserved words
+ * ("class" → "_class"). Names with no usable characters collapse to "_".
  */
 export function sanitizeTypeName(name) {
-    if (!name.includes('.'))
+    if (!name)
+        return '_';
+    // Exact reserved words keep their casing and get an "_" prefix
+    // ("class" → "_class"), while "Null" / "Class" are legal and pass through.
+    if (isReservedTypeName(name))
+        return `_${name}`;
+    const isValidIdentifier = /^[\p{ID_Start}$_][\p{ID_Continue}$]*$/u.test(name);
+    if (isValidIdentifier)
         return name;
-    return name
-        .split('.')
+    const segments = name.match(/[\p{ID_Continue}$]+/gu) ?? [];
+    const result = segments
         .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
         .join('');
+    // Covers empty results, ASCII digits, and non-ASCII digits (Nd but not
+    // ID_Start, e.g. Arabic-Indic) alike: anything not starting with a valid
+    // identifier start character gets the "_" prefix.
+    if (!/^[\p{ID_Start}$_]/u.test(result))
+        return `_${result}`;
+    if (isReservedTypeName(result))
+        return `_${result}`;
+    return result;
 }
 /**
- * Build a mapping of sanitized schema names → renamed names for any that
- * collide with reserved type names.
+ * Build a mapping of raw schema names → renamed names for any whose
+ * sanitized name collides with a reserved type name or with another
+ * schema's sanitized name (e.g. "User-Dto" and "User[Dto]" both → "UserDto").
+ *
+ * The map is keyed by the raw schema name (component keys are unique by
+ * construction), so callers resolve raw $ref segments / schema keys first
+ * and fall back to sanitizeTypeName for the common no-collision case.
+ * Numbered suffixes are used when the first renamed candidate also collides.
  */
 export function buildSchemaRenameMap(schemaNames, reserved, suffix = 'Model') {
     const renameMap = new Map();
+    const used = new Set(reserved);
     for (const name of schemaNames) {
         const sanitized = sanitizeTypeName(name);
-        if (reserved.has(sanitized)) {
-            renameMap.set(sanitized, `${sanitized}${suffix}`);
+        if (!used.has(sanitized)) {
+            used.add(sanitized);
+            continue;
         }
+        let candidate = `${sanitized}${suffix}`;
+        let counter = 2;
+        while (used.has(candidate)) {
+            candidate = `${sanitized}${suffix}${counter}`;
+            counter += 1;
+        }
+        used.add(candidate);
+        renameMap.set(name, candidate);
     }
     return renameMap;
 }
@@ -65,15 +190,24 @@ export function toPascalCase(str) {
 /**
  * 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 toPascalCase(cleaned);
+        return sanitizeTypeName(toPascalCase(cleaned));
     });
     return methodPascal + segments.join('');
 }
@@ -116,3 +250,78 @@ export function getErrorType(op) {
 export function makeHeader(version) {
     return `// Auto-generated by genoc from OpenAPI ${version} spec. DO NOT EDIT.`;
 }
+/**
+ * Sanitize free-form text for safe inclusion inside a JSDoc comment.
+ *
+ * Normalizes CRLF to LF, flattens remaining newlines into single spaces,
+ * escapes the comment-closing sequence (asterisk + slash) as `*\/`, and
+ * trims leading/trailing whitespace. No other transformation is applied —
+ * no HTML stripping, no markdown processing, no wrapping.
+ */
+export function sanitizeJsDocText(text) {
+    return text.replace(/\r\n/g, '\n').replace(/\n/g, ' ').replace(/\*\//g, '*\\/').trim();
+}
+/**
+ * Format an arbitrary metadata value for a JSDoc tag using JSON.stringify
+ * (no indent). Returns `null` when stringify yields `undefined` (e.g. for
+ * `undefined` or function values) — callers should skip the tag entirely.
+ */
+export function formatJsDocValue(value) {
+    const json = JSON.stringify(value);
+    return json === undefined ? null : json;
+}
+/**
+ * Build the ordered JSDoc content segments for a schema-backed property.
+ *
+ * Order (frozen): description → `@deprecated` → `@default` → `@example`(s)
+ * → `@title`. Segments are skipped when their value is absent, empty, or
+ * whitespace-only. Sanitization is applied AFTER stringification for
+ * `@default` / `@example` values.
+ */
+export function buildFieldJsDocLines(schema) {
+    const lines = [];
+    if (schema.description !== undefined && schema.description.trim() !== '') {
+        lines.push(sanitizeJsDocText(schema.description));
+    }
+    if (schema.deprecated === true) {
+        lines.push('@deprecated');
+    }
+    if (schema.default !== undefined) {
+        const formatted = formatJsDocValue(schema.default);
+        if (formatted !== null) {
+            lines.push(`@default ${sanitizeJsDocText(formatted)}`);
+        }
+    }
+    if (schema.example !== undefined) {
+        const formatted = formatJsDocValue(schema.example);
+        if (formatted !== null) {
+            lines.push(`@example ${sanitizeJsDocText(formatted)}`);
+        }
+    }
+    if (schema.examples !== undefined) {
+        for (const value of schema.examples) {
+            const formatted = formatJsDocValue(value);
+            if (formatted !== null) {
+                lines.push(`@example ${sanitizeJsDocText(formatted)}`);
+            }
+        }
+    }
+    if (schema.title) {
+        lines.push(`@title ${sanitizeJsDocText(schema.title)}`);
+    }
+    return lines;
+}
+/**
+ * Render a schema's JSDoc metadata as a complete comment block.
+ *
+ * 0 segments → `''`; exactly 1 segment → single-line `/** text *\/`;
+ * ≥2 segments → multiline block with a blank ` *` line between segments.
+ */
+export function buildTypeJsDoc(schema) {
+    const lines = buildFieldJsDocLines(schema);
+    if (lines.length === 0)
+        return '';
+    if (lines.length === 1)
+        return `/** ${lines[0]} */`;
+    return `/**\n${lines.map((line) => ` * ${line}`).join('\n *\n')}\n */`;
+}

package/dist/utils/proxy.d.ts

@@ -0,0 +1,6 @@
+export type LoadOptions = {
+    proxy?: string;
+};
+export declare function assertValidProxyUrl(url: string): void;
+export declare function hasProxyEnv(): boolean;
+export declare function fetchSpec(url: string, opts?: LoadOptions): Promise<Response>;