genoc 0.1.2 → 0.2.0

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,7 @@ export type GeneratorConfig = {
     requesterModuleName?: string;
     specVersion?: string;
     strictVersion?: boolean;
+    runtimeImportPath?: 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,4 +1,25 @@
 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.
+ *
+ * "Api.Error" → "ApiError", "Simple" → "Simple"
+ */
+export declare function sanitizeTypeName(name: string): string;
+/**
+ * Build a mapping of sanitized schema names → renamed names for any that
+ * collide with reserved type names.
+ */
+export declare function buildSchemaRenameMap(schemaNames: Iterable<string>, reserved: ReadonlySet<string>, suffix?: string): Map<string, string>;
 /**
  * Convert a string to PascalCase, handling camelCase, kebab-case, snake_case,
  * and colon-separated segments.
@@ -21,3 +42,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,54 @@
+/**
+ * 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';
+/**
+ * Sanitize a schema type name by converting dot-separated segments into
+ * PascalCase. Names without dots pass through unchanged.
+ *
+ * "Api.Error" → "ApiError", "Simple" → "Simple"
+ */
+export function sanitizeTypeName(name) {
+    if (!name.includes('.'))
+        return name;
+    return name
+        .split('.')
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join('');
+}
+/**
+ * Build a mapping of sanitized schema names → renamed names for any that
+ * collide with reserved type names.
+ */
+export function buildSchemaRenameMap(schemaNames, reserved, suffix = 'Model') {
+    const renameMap = new Map();
+    for (const name of schemaNames) {
+        const sanitized = sanitizeTypeName(name);
+        if (reserved.has(sanitized)) {
+            renameMap.set(sanitized, `${sanitized}${suffix}`);
+        }
+    }
+    return renameMap;
+}
 /**
  * Convert a string to PascalCase, handling camelCase, kebab-case, snake_case,
  * and colon-separated segments.
@@ -64,3 +115,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genoc",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Generate typed HTTP clients from OpenAPI 3.0 / 3.1 specifications",
   "keywords": [
     "client",
@@ -28,6 +28,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./runtime": {
+      "import": "./dist/runtime/index.js",
+      "types": "./dist/runtime/index.d.ts"
     }
   },
   "scripts": {
@@ -39,7 +43,7 @@
     "format": "oxfmt --write",
     "format:check": "oxfmt --check",
     "changeset": "changeset",
-    "version-packages": "changeset version",
+    "version-packages": "changeset version && oxfmt --write",
     "release": "bun run build && changeset publish"
   },
   "dependencies": {