@powerduck/openapi-codegen 0.5.1 → 0.5.3

package/README.md

@@ -1,179 +1,51 @@
 # @powerduck/openapi-codegen
 
-Generate runnable HTTP request examples from OpenAPI documents for **21 languages** and **41 language/client combinations**.
-
-`@powerduck/openapi-codegen` is a high-performance, browser-compatible TypeScript library for API documentation systems, developer portals, API explorers, command-line tools, and build-time code generation.
-
-## Features
-
-- **Zero runtime dependencies** — works in browser, Node.js, Electron, and edge environments
-- **Dual module support** — native ESM and CommonJS (`require()`)
-- **OpenAPI 3.0, 3.1, and 3.2** support
-- **41 built-in generators** across 21 languages
-- **Parameter serialization** — path, query, header, cookie with full OpenAPI style support
-- **Security schemes** — API key, HTTP bearer, HTTP basic
-- **Body types** — JSON, plain-text, URL-encoded form, multipart form-data
-- **$ref resolution** — in-document JSON Pointer references with circular detection
-- **Example generation** — automatic example values from JSON Schema
-- **TypeScript declarations** — full type safety
-- **Highly optimized** — no `JSON.parse`/`JSON.stringify` deep cloning, structured reference handling
-
-## Supported Languages and Clients
-
-Use the exact `language` and `client` identifiers shown below when calling `generate()`. Identifiers are case-sensitive.
-
-| Language          | `language`   | Supported `client` values                                         |
-| ----------------- | ------------ | ----------------------------------------------------------------- |
-| C                 | `c`          | `libcurl`                                                         |
-| C#                | `csharp`     | `httpclient`, `restsharp`                                         |
-| Clojure           | `clojure`    | `clj-http`                                                        |
-| Dart              | `dart`       | `http`                                                            |
-| F#                | `fsharp`     | `httpclient`                                                      |
-| Go                | `go`         | `new-request`                                                     |
-| HTTP request file | `http`       | `http1`                                                           |
-| Java              | `java`       | `asynchttp`, `java-net-http`, `okhttp`, `unirest`                 |
-| JavaScript        | `javascript` | `fetch`, `axios`, `ofetch`, `jquery`, `xhr`                       |
-| Kotlin            | `kotlin`     | `okhttp`                                                          |
-| Node.js           | `node`       | `fetch`, `axios`, `ofetch`, `undici`                              |
-| Objective-C       | `objc`       | `nsurlsession`                                                    |
-| OCaml             | `ocaml`      | `cohttp`                                                          |
-| PHP               | `php`        | `curl`, `guzzle`, `laravel-http`                                  |
-| PowerShell        | `powershell` | `invoke-webrequest`, `invoke-restmethod`                          |
-| Python            | `python`     | `http-client`, `requests`, `aiohttp`, `httpx-sync`, `httpx-async` |
-| R                 | `r`          | `httr2`                                                           |
-| Ruby              | `ruby`       | `net-http`                                                        |
-| Rust              | `rust`       | `reqwest`                                                         |
-| Shell             | `shell`      | `curl`, `wget`, `httpie`                                          |
-| Swift             | `swift`      | `nsurlsession`                                                    |
-
-> Generator availability does not imply that every client can represent every OpenAPI operation. For example, GNU Wget cannot safely construct arbitrary `multipart/form-data` requests. Use `shell/curl` or `shell/httpie` for multipart uploads.
-
-## Requirements
-
-- Node.js 18 or later (for Node.js usage)
-- A parsed OpenAPI document (JavaScript object)
-- Modern browser with Fetch API (for browser usage)
-
-## Installation
-
-Using npm:
+[![npm version](https://img.shields.io/npm/v/@powerduck/openapi-codegen)](https://www.npmjs.com/package/@powerduck/openapi-codegen)
+[![license](https://img.shields.io/npm/l/@powerduck/openapi-codegen)](https://github.com/PowerDuckie/openapi-codegen/blob/main/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/@powerduck/openapi-codegen)](https://www.npmjs.com/package/@powerduck/openapi-codegen)
 
-```bash
-npm install @powerduck/openapi-codegen
-```
+Generate runnable HTTP request examples from OpenAPI documents. Supports 21 languages and 41 language/client combinations. Browser-compatible, zero runtime dependencies.
 
-Using pnpm:
+---
 
-```bash
-pnpm add @powerduck/openapi-codegen
-```
+Powerduck is an open-source developer tooling platform for teams building modern API workflows.
 
-Using Yarn:
+- **21 Languages** — JavaScript, TypeScript, Python, Go, Rust, Java, PHP, Ruby, C#, Kotlin, Swift, Dart, and more
+- **41 Client Combinations** — fetch, axios, requests, httpx, http.client, Faraday, Guzzle, RestSharp, and more
+- **OpenAPI 3.0/3.1/3.2** — Full support for modern OpenAPI specifications
+- **Security Schemes** — Bearer tokens, API keys, Basic auth, OAuth2, and custom headers
+- **Parameter Handling** — Path, query, header, and cookie parameters with proper encoding
+- **Request Bodies** — JSON, form-data, x-www-form-urlencoded, and raw payloads
+- **Browser Compatible** — Pure TypeScript, no Node.js dependencies, works in any modern browser
+- **Dual ESM/CJS** — Works with `import` and `require`, with bundled TypeScript declarations
 
-```bash
-yarn add @powerduck/openapi-codegen
-```
+---
 
 ## Quick Start
 
-### ESM (import)
+### Install
 
-```typescript
-import { generate } from "@powerduck/openapi-codegen";
-import document from "./openapi.json" with { type: "json" };
-
-const code = generate({
-  document,
-  path: "/users/{id}",
-  method: "get",
-  language: "javascript",
-  client: "fetch",
-});
-
-console.log(code);
-```
-
-### CommonJS (require)
-
-```javascript
-const { generate } = require("@powerduck/openapi-codegen");
-const fs = require("node:fs");
-
-const document = JSON.parse(fs.readFileSync("./openapi.json", "utf8"));
-
-const code = generate({
-  document,
-  path: "/users/{id}",
-  method: "get",
-  language: "python",
-  client: "requests",
-});
-
-console.log(code);
+```bash
+npm install @powerduck/openapi-codegen
 ```
 
-`generate()` returns the generated source code as a string.
-
-## Authentication
-
-Provide credentials through `securityValues`:
+### Generate from a document
 
 ```typescript
 import { generate } from "@powerduck/openapi-codegen";
 
 const code = generate({
-  document,
-  path: "/users/{id}",
+  document: openApiDocument,
+  path: "/pets/{id}",
   method: "get",
   language: "javascript",
   client: "fetch",
-  securityValues: {
-    bearerAuth: "YOUR_ACCESS_TOKEN",
-    apiKey: "YOUR_API_KEY",
-  },
 });
 
 console.log(code);
 ```
 
-The keys in `securityValues` must match the security scheme names defined in the OpenAPI document.
-
-**Security note:** Do not commit real credentials to source control.
-
-## Multipart Uploads
-
-```typescript
-import { generate } from "@powerduck/openapi-codegen";
-
-const code = generate({
-  document,
-  path: "/upload/{id}",
-  method: "post",
-  language: "shell",
-  client: "curl",
-  securityValues: {
-    bearerAuth: "YOUR_ACCESS_TOKEN",
-  },
-});
-
-console.log(code);
-```
-
-Generated multipart examples may include placeholder file paths:
-
-```text
-/tmp/file.bin
-```
-
-Replace all placeholder paths before running the generated code.
-
-Some clients cannot safely represent every OpenAPI request. Generation may throw a descriptive error when the selected client is incompatible with an operation.
-
-For example, `shell/wget` does not support arbitrary multipart generation. Use `shell/curl` or `shell/httpie` instead.
-
-## Discover Available Generators
-
-Use `list()` to inspect every installed language/client combination:
+### List available generators
 
 ```typescript
 import { list } from "@powerduck/openapi-codegen";
@@ -183,402 +55,154 @@ for (const { language, client } of list()) {
 }
 ```
 
-You can also select a generator programmatically:
+### Provide credentials
 
 ```typescript
-import { generate, list } from "@powerduck/openapi-codegen";
-
-const generator = list().find(
-  ({ language, client }) => language === "javascript" && client === "fetch",
-);
-
-if (!generator) {
-  throw new Error("The requested generator is not available");
-}
-
 const code = generate({
   document,
-  path: "/users",
+  path: "/pets/{id}",
   method: "get",
-  language: generator.language,
-  client: generator.client,
+  language: "javascript",
+  client: "fetch",
+  securityValues: {
+    bearerAuth: "your-token-here",
+    apiKey: "your-api-key",
+  },
 });
-
-console.log(code);
 ```
 
-## Custom Server URL
-
-Override the server URL from the OpenAPI document:
-
-```typescript
-const code = generate({
-  document,
-  path: "/users",
-  method: "get",
-  language: "shell",
-  client: "curl",
-  serverUrl: "https://staging.example.com/v1",
-});
-```
+---
+
+## Links
+
+- [Official Website](https://www.powerduck.com/opensource/openapi-codegen.html)
+- [Documentation](https://www.powerduck.com/docs/openapi-codegen/introduction)
+- [Live Demo](https://www.powerduck.com/demo/openapi-codegen)
+- [GitHub](https://github.com/PowerDuckie/openapi-codegen)
+- [npm](https://www.npmjs.com/package/@powerduck/openapi-codegen)
+
+---
+
+## Supported Languages & Clients
+
+| Language   | Clients                                            |
+| ---------- | -------------------------------------------------- |
+| JavaScript | fetch, axios, XMLHttpRequest, jQuery, Node.js http |
+| TypeScript | fetch, axios                                       |
+| Python     | requests, httpx, http.client, aiohttp              |
+| Go         | net/http, resty, fasthttp                          |
+| Rust       | reqwest, hyper                                     |
+| Java       | OkHttp, HttpClient, Unirest, Retrofit              |
+| PHP        | cURL, Guzzle, HTTP_Request2                        |
+| Ruby       | Net::HTTP, Faraday, RestClient                     |
+| C#         | HttpClient, RestSharp, WebRequest                  |
+| Kotlin     | OkHttp, Fuel                                       |
+| Swift      | URLSession, Alamofire                              |
+| Dart       | http, Dio                                          |
+| Shell      | cURL, wget, HTTPie                                 |
+| PowerShell | Invoke-RestMethod, Invoke-WebRequest               |
+| R          | httr, RCurl                                        |
+| MATLAB     | webread, urlwrite                                  |
+| Elixir     | HTTPoison, Tesla                                   |
+| Haskell    | http-conduit, wreq                                 |
+| Clojure    | clj-http, http-kit                                 |
+| Scala      | sttp, akka-http                                    |
+
+---
 
 ## API Reference
 
 ### `generate(options)`
 
-Generates an HTTP request example for an OpenAPI operation.
+Generate HTTP request code from an OpenAPI document.
 
 ```typescript
+import { generate } from "@powerduck/openapi-codegen";
+
 const code = generate({
-  document,
-  path,
-  method,
-  language,
-  client,
-  securityValues,
-  serverUrl,
-  softRefMode,
+  document: openApiDocument,
+  path: "/pets",
+  method: "post",
+  language: "python",
+  client: "requests",
+  securityValues: { bearerAuth: "token" },
+  parameterValues: { limit: 10, offset: 0 },
 });
 ```
 
 #### Options
 
-| Option           | Type                          | Required | Description                                  |
-| ---------------- | ----------------------------- | -------: | -------------------------------------------- |
-| `document`       | `unknown` (OpenAPI object)    |      Yes* | Parsed OpenAPI document                      |
-| `path`           | `string`                      |      Yes* | Exact OpenAPI path template                  |
-| `method`         | `string`                      |      Yes* | HTTP operation method                        |
-| `language`       | `string`                      |      Yes | Target language identifier                   |
-| `client`         | `string`                      |      Yes | Target HTTP client identifier                |
-| `securityValues` | `Record<string, string>`      |       No | Credentials for named security schemes       |
-| `serverUrl`      | `string`                      |       No | Override server URL from document            |
-| `softRefMode`    | `boolean`                     |       No | Soft mode for $ref resolution (no throws)    |
-| `request`        | `RequestIR`                   |      Yes* | Pre-normalized request (alternative to doc)  |
-
-\* Either `document` + `path` + `method` OR `request` must be provided.
-
-#### Return Value
-
-Returns the generated source code as a `string`.
-
-#### Errors
-
-Generation can throw when:
-
-- The requested path or operation does not exist
-- The language/client combination is unknown
-- The OpenAPI document is invalid or unsupported
-- Required generation data cannot be resolved
-- The selected client cannot safely represent the request
-- A circular $ref is detected (unless `softRefMode` is enabled)
-
-Handle errors when processing untrusted documents or user-selected generators:
-
-```typescript
-try {
-  const code = generate({
-    document,
-    path: "/users/{id}",
-    method: "get",
-    language: "javascript",
-    client: "fetch",
-  });
-
-  console.log(code);
-} catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-
-  console.error(`Generation failed: ${message}`);
-  process.exitCode = 1;
-}
-```
+| Option            | Type                      | Required | Description                                                |
+| ----------------- | ------------------------- | -------- | ---------------------------------------------------------- |
+| `document`        | `OpenAPIDocument`         | Yes      | Parsed OpenAPI document object                             |
+| `path`            | `string`                  | Yes      | API path (e.g., `/pets/{id}`)                              |
+| `method`          | `string`                  | Yes      | HTTP method (get, post, put, delete, patch, head, options) |
+| `language`        | `string`                  | Yes      | Target language                                            |
+| `client`          | `string`                  | Yes      | HTTP client library                                        |
+| `securityValues`  | `Record<string, string>`  | No       | Security scheme values                                     |
+| `parameterValues` | `Record<string, unknown>` | No       | Parameter values                                           |
+| `requestBody`     | `unknown`                 | No       | Request body value                                         |
+| `headers`         | `Record<string, string>`  | No       | Additional headers                                         |
+| `timeout`         | `number`                  | No       | Request timeout in ms                                      |
+| `indent`          | `string`                  | No       | Indentation string (default: 2 spaces)                     |
+| `quote`           | `"single" \| "double"`    | No       | Quote style (default: language-specific)                   |
 
 ### `list()`
 
-Returns the available generator descriptors:
+List all available language/client combinations.
 
 ```typescript
-const generators = list();
-```
-
-Each descriptor contains:
+import { list } from "@powerduck/openapi-codegen";
 
-```typescript
-interface GeneratorDescriptor {
-  language: string;
-  client: string;
-}
+const generators = list();
+// [{ language: "javascript", client: "fetch" }, ...]
 ```
 
-### `get(language, client)`
+### `normalize(document)`
 
-Returns a specific generator by language and client, or `undefined` if not found:
+Normalize and validate an OpenAPI document.
 
 ```typescript
-const generator = get("javascript", "fetch");
-```
-
-### `register(generator)`
+import { normalize } from "@powerduck/openapi-codegen";
 
-Register a custom generator:
-
-```typescript
-import { register } from "@powerduck/openapi-codegen";
-
-register({
-  language: "custom",
-  client: "my-client",
-  generate: (request) => {
-    // Custom generation logic
-    return "// Custom generated code";
-  },
-});
+const normalized = normalize(rawDocument);
 ```
 
-## OpenAPI Document Input
+---
 
-Pass a parsed JavaScript object rather than a JSON or YAML source string.
-
-### JSON
+## TypeScript Types
 
 ```typescript
-import { readFile } from "node:fs/promises";
-import { generate } from "@powerduck/openapi-codegen";
-
-const source = await readFile("./openapi.json", "utf8");
-const document = JSON.parse(source);
-
-const code = generate({
-  document,
-  path: "/pets/{petId}",
-  method: "get",
-  language: "javascript",
-  client: "fetch",
-});
-
-console.log(code);
+import type {
+  GenerateOptions,
+  GeneratorInfo,
+  OpenAPIDocument,
+  SecurityScheme,
+  Parameter,
+  RequestBody,
+} from "@powerduck/openapi-codegen";
 ```
 
-### YAML
-
-Install a YAML parser separately:
-
-```bash
-npm install yaml
-```
-
-Parse the document before passing it to `generate()`:
-
-```typescript
-import { readFile } from "node:fs/promises";
-import YAML from "yaml";
-import { generate } from "@powerduck/openapi-codegen";
-
-const source = await readFile("./openapi.yaml", "utf8");
-const document = YAML.parse(source);
-
-const code = generate({
-  document,
-  path: "/pets/{petId}",
-  method: "get",
-  language: "javascript",
-  client: "fetch",
-});
-
-console.log(code);
-```
+---
 
 ## Browser Usage
 
-The library is fully browser-compatible with zero Node.js dependencies:
-
 ```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>API Code Generator</title>
-</head>
-<body>
-  <script type="module">
-    import { generate, list } from "https://esm.sh/@powerduck/openapi-codegen";
-
-    const document = {
-      openapi: "3.1.0",
-      info: { title: "Demo API", version: "1.0.0" },
-      paths: {
-        "/hello": {
-          get: {
-            responses: { "200": { description: "OK" } },
-          },
-        },
-      },
-    };
-
-    const code = generate({
-      document,
-      path: "/hello",
-      method: "get",
-      language: "javascript",
-      client: "fetch",
-    });
-
-    console.log(code);
-  </script>
-</body>
-</html>
-```
-
-## Generated Code
-
-Generated examples are intended to be readable, runnable starting points. Depending on the selected language and client, they may include:
-
-- A 30-second connection or request timeout
-- HTTP status validation
-- Response body output
-- Resource cleanup
-- Runtime and dependency notes
-- Placeholder multipart file paths
-- Environment-specific proxy or TLS behavior
-
-Review generated code before using it in production. You may need to:
-
-- Install dependencies for the selected client
-- Replace placeholder parameter values
-- Replace multipart file paths
-- Supply authentication credentials securely
-- Configure certificate trust
-- Configure proxies
-- Adjust timeout and redirect policies
-- Add application-specific response parsing
-
-## Performance
-
-The library is optimized for high performance:
-
-- **No deep cloning via `JSON.parse(JSON.stringify())`** — uses structured reference handling
-- **Efficient $ref resolution** with caching and circular detection
-- **Lazy example generation** — only generates examples when needed
-- **Zero runtime dependencies** — minimal bundle size (~130KB minified)
-- **Tree-shakeable** — ESM build supports tree-shaking
-
-## Development
+<script type="module">
+  import { generate, list } from "https://esm.sh/@powerduck/openapi-codegen";
 
-Clone the repository and install dependencies:
-
-```bash
-git clone https://github.com/PowerDuckie/openapi-codegen.git
-cd openapi-codegen
-npm install
-```
-
-Run the test suite:
-
-```bash
-npm test
-```
-
-Run tests with coverage:
-
-```bash
-npm run test:coverage
-```
-
-Build the package:
-
-```bash
-npm run build
-```
-
-Run type checking:
-
-```bash
-npm run typecheck
-```
-
-Run all release checks:
-
-```bash
-npm run check
-```
-
-Run the demo:
-
-```bash
-npm run demo
-```
-
-## Testing
-
-The project uses:
-
-- [Vitest](https://vitest.dev/) for unit and integration tests
-- 270+ tests covering all core modules
-- Full branch coverage for core logic
-
-Run all tests:
-
-```bash
-npm test
-```
-
-## Project Structure
-
-```
-src/
-├── index.ts              # Main entry point
-├── types.ts              # TypeScript type definitions
-├── core/
-│   ├── generator.ts      # Generator factory
-│   ├── helpers.ts        # Utility functions (escaping, indentation, etc.)
-│   ├── normalize.ts      # OpenAPI document → RequestIR normalization
-│   ├── refs.ts           # JSON Pointer $ref resolver
-│   ├── registry.ts       # Generator registry (Map-based)
-│   ├── request.ts        # RequestIR → compiled request
-│   ├── serialize.ts      # Parameter serialization (path/query/header/cookie)
-│   ├── example.ts        # JSON Schema → example value generation
-│   └── plugin.ts         # Plugin system
-└── emitters/
-    ├── index.ts          # Unified emitter registry (41 generators)
-    ├── c/                # C (libcurl)
-    ├── csharp/           # C# (httpclient, restsharp)
-    ├── javascript/       # JavaScript (fetch, axios, ofetch, jquery, xhr)
-    ├── python/           # Python (requests, aiohttp, httpx, http-client)
-    └── ...               # 17 more languages
+  const code = generate({
+    document: openApiDoc,
+    path: "/users",
+    method: "get",
+    language: "javascript",
+    client: "fetch",
+  });
+</script>
 ```
 
-## Security
-
-Generated source code can contain request URLs, headers, parameter values, and credentials supplied to the generator.
-
-Avoid:
-
-- Committing generated examples that contain real credentials
-- Logging secrets in CI output
-- Running unreviewed generated commands in production
-- Passing untrusted file paths directly to generated upload code
-
-Report security issues privately to the repository owner instead of opening a public issue.
-
-## Contributing
-
-Contributions are welcome.
-
-1. Fork the repository.
-2. Create a feature branch.
-3. Add or update tests.
-4. Run the full validation suite.
-5. Commit the changes.
-6. Open a pull request.
-
-```bash
-git checkout -b feature/my-change
-npm install
-npm run check
-git add .
-git commit -m "feat: describe the change"
-git push -u origin feature/my-change
-```
+---
 
 ## License
 
-[MIT](LICENSE)
+MIT © [POWERDUCK LIMITED](https://www.powerduck.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerduck/openapi-codegen",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Generate runnable HTTP request examples from OpenAPI documents. 21 languages, 41 clients, browser-compatible, zero runtime dependencies.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -63,13 +63,13 @@
   },
   "homepage": "https://github.com/PowerDuckie/openapi-codegen#readme",
   "devDependencies": {
-     "@types/node": "^20.19.43",
-    "@vitest/coverage-v8": "^3.2.7",
+    "@types/node": "^20.19.43",
     "fast-check": "^4.0.0",
     "terser": "^5.51.2",
     "tsup": "^8.5.0",
     "tsx": "^4.23.13",
     "typescript": "^5.9.3",
+    "@vitest/coverage-v8": "^3.2.7",
     "vitest": "^3.2.7"
   }
 }