genoc 0.1.3 → 0.2.0

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

@@ -1,10 +1,13 @@
 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.
@@ -39,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

@@ -11,9 +11,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,6 +19,8 @@ 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.
@@ -116,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.3",
+  "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": {