genoc 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # genoc
 
-Generate TypeScript HTTP clients from OpenAPI 3.0 / 3.1 specifications.
+Generate TypeScript HTTP clients from OpenAPI 3.0 or 3.1 specifications.
 Generated code depends only on the tiny `genoc/runtime` module. Full type safety. Bring your own HTTP client.
 
 [![npm version](https://img.shields.io/npm/v/genoc)](https://www.npmjs.com/package/genoc)
@@ -11,13 +11,12 @@ Generated code depends only on the tiny `genoc/runtime` module. Full type safety
 ## 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
-- Shared runtime contract — `genoc/runtime` exports the `Requester` type and response/error classes, so one requester implementation works with every generated client
+- End-to-end type safety: requests, responses, and errors are fully typed
+- Works with any HTTP client: plug in fetch, axios, or anything else
+- Shared runtime contract: `genoc/runtime` exports the `Requester` type and response and error classes, so one requester implementation works with every generated client
 - Error types with per-status-code narrowing and type guards
-- File and binary upload/download with stream handling
+- File and binary uploads and downloads with stream handling
 - Flexible method naming strategies (path-based, operationId, operationId-with-fallback)
-- CLI and programmatic API
 
 ## Quick Start
 
@@ -36,15 +35,18 @@ Generate:
 genoc ./path/to/spec.yaml --output-dir ./src/api
 ```
 
-This creates two files in `./src/api`:
+This creates three files in `./src/api`:
 
-- `contracts.ts` — Type definitions, error classes, and helper types
-- `client.ts` — Typed client with `createClient(requester)` factory
+- `contracts.ts`: type definitions, error classes, and helper types
+- `client.ts`: typed client with the `createClient(requester)` factory
+- `index.ts`: barrel that re-exports both files, so you can import directly from the output directory
+
+The barrel means `import { createClient } from './index.js'` works too.
 
 ## Usage
 
-The generated client requires a `Requester` implementation — a function that
-performs the actual HTTP call and returns the result. The type lives in
+The generated client requires a `Requester` implementation: a function that
+performs the HTTP call and returns the result. The type lives in
 `genoc/runtime`, so you can write and compile a requester before generating
 anything:
 
@@ -52,20 +54,7 @@ anything:
 import type { Requester } from 'genoc/runtime';
 ```
 
-```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`
+For the full `Requester` type signature and binary and stream handling, see [Usage](./docs/usage.md).
 
 ```typescript
 import { createClient } from './client.js';
@@ -105,159 +94,37 @@ const requester: Requester = async (method, path, options) => {
 
 const client = createClient(requester);
 
-// Typed call — response type is inferred from the spec
+// 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`.
-
-## Shared Runtime (`genoc/runtime`)
-
-Generated clients import their response and error classes from `genoc/runtime`
-instead of declaring inline copies (the generated `contracts.ts` re-exports
-them, so existing imports keep working). This gives every generated client the
-same class identity — `instanceof` checks work across clients, and you can
-implement **one shared requester** typed against the package:
-
-```typescript
-// common-requester.ts — reusable across all generated clients,
-// no generated imports needed
-import type { Requester } from 'genoc/runtime';
-
-export const requester: Requester = async (method, path, options) => {
-  // ...your fetch/axios/etc. implementation
-};
-```
-
-To pin a specific version or point at a mirror, override the import specifier
-via `--runtime-import-path` (CLI) or `runtimeImportPath` (programmatic config).
-
-## 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 'genoc/runtime';
-
-// Inside your Requester implementation:
-if (options.expectStream === true) {
-  return new StreamResponse(
-    response.body as ReadableStream<Uint8Array>,
-    getFilename(response.headers), // extract from Content-Disposition
-    Object.fromEntries(response.headers.entries())
-  );
-}
-```
-
-`StreamResponse` is a simple container:
-
-```typescript
-class StreamResponse {
-  data: ReadableStream<Uint8Array>;
-  filename?: string;
-  headers: Record<string, string>;
-}
-```
+For handling `expectStream: true`, see [Binary and file responses](./docs/usage.md#binary-and-file-responses).
 
-## 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         |
-| `--runtime-import-path`  | `genoc/runtime` | Module specifier generated code imports runtime classes from |
-
-## 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.
-
-## JSDoc Documentation Output
-
-`description`, `deprecated`, `default`, `example`/`examples`, and `title`
-fields from your spec become JSDoc comments in the generated code — on object
-type properties, named schemas, and client methods. Object types are always
-emitted multi-line, so per-property JSDoc stays aligned at each nesting depth.
-`@deprecated` tags give you editor strikethrough on deprecated fields and
-methods for free.
-
-## 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
+## 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 'genoc/runtime';
-
-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);
-  }
-}
-```
+- **`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
 
-## Feature Support
+For the full example of catching and narrowing errors, see [Error handling](./docs/error-handling.md).
 
-Check the detailed feature support tables to see if your OpenAPI spec features are covered:
+## Documentation
 
-- **[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).
+- [Configuration](./docs/configuration.md): CLI flags, `.genocrc` config files, method naming strategies, and proxy support
+- [Usage](./docs/usage.md): the `Requester` contract, shared runtime, binary and file responses, and JSDoc output
+- [Error handling](./docs/error-handling.md): typed errors, `isDefinedError`, and the catching example
+- [OpenAPI 3.0 support](./docs/openapi-3.0-support.md): data types, schema keywords, parameters, bodies, uploads, responses, errors, `$ref`, components, security, servers, and operations
+- [OpenAPI 3.1 support](./docs/openapi-3.1-support.md): all 3.0 features plus webhooks and JSON Schema 2020-12 alignment, with a diff against 3.0
 
 ## Requirements
 
-- Node.js >= 18
+- Node.js 18 or later
 - OpenAPI 3.0.x or 3.1.x specification (JSON or YAML, file path or URL)
 
 ## License
 
-[MIT](./LICENSE) — Copyright © Andrey Kiselev
+[MIT](./LICENSE). Copyright © Andrey Kiselev

package/dist/analyzer/analyze.d.ts

@@ -0,0 +1,18 @@
+import type { OpenAPIDocument } from '../types/openapi.js';
+import type { AnalyzedSpec, AnalyzeOptions } from './types.js';
+/**
+ * Build a description-only type-level JSDoc comment for operation-derived
+ * types (body / response). Returns '' when the description is absent or
+ * whitespace-only so callers can skip emission entirely.
+ */
+export declare function buildDescriptionJsDoc(description: string | undefined): string;
+/**
+ * Analyze an OpenAPI document into the finished model every renderer consumes:
+ * schema→TS-type translation (rename machinery, discriminator discovery, the
+ * schema mapper) runs here exactly once, producing render-ready type text.
+ *
+ * @param doc - The parsed and validated OpenAPI document
+ * @param opts - Optional resolver override and method naming strategy
+ * @returns The AnalyzedSpec model consumed by all generators
+ */
+export declare function analyze(doc: OpenAPIDocument, opts?: AnalyzeOptions): AnalyzedSpec;