@powerduck/openapi-codegen 0.4.2 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Powerduck limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,23 +1,22 @@
 # @powerduck/openapi-codegen
 
-Generate runnable HTTP request examples from parsed OpenAPI documents for **21 language targets** and **41 language/client combinations**.
+Generate runnable HTTP request examples from OpenAPI documents for **21 languages** and **41 language/client combinations**.
 
-`@powerduck/openapi-codegen` is an ESM-first TypeScript library for API documentation systems, developer portals, API explorers, command-line tools, and build-time code generation.
+`@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
 
-- No need for Node environment support
-- Supports parsed OpenAPI documents, including OpenAPI 3.2
-- Generates readable HTTP request examples across 41 generators
-- Resolves path, query, header, and cookie parameters
-- Supports API key, HTTP bearer, and other security schemes
-- Supports JSON, plain-text, URL-encoded form, and multipart bodies
-- Generates multipart file-upload examples with placeholder paths
-- Preserves request bodies that have already been serialized
-- Adds timeouts, HTTP status checks, and resource cleanup where supported
-- Exposes generator discovery through `list()`
-- Includes TypeScript declarations
-- Ships as an ECMAScript module
+- **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
 
@@ -51,9 +50,9 @@ Use the exact `language` and `client` identifiers shown below when calling `gene
 
 ## Requirements
 
-- Node.js 20 or later
-- A parsed OpenAPI document
-- The runtime and dependencies required by the selected generated client
+- Node.js 18 or later (for Node.js usage)
+- A parsed OpenAPI document (JavaScript object)
+- Modern browser with Fetch API (for browser usage)
 
 ## Installation
 
@@ -77,7 +76,9 @@ yarn add @powerduck/openapi-codegen
 
 ## Quick Start
 
-```ts
+### ESM (import)
+
+```typescript
 import { generate } from "@powerduck/openapi-codegen";
 import document from "./openapi.json" with { type: "json" };
 
@@ -92,15 +93,33 @@ const code = generate({
 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);
+```
+
 `generate()` returns the generated source code as a string.
 
 ## Authentication
 
 Provide credentials through `securityValues`:
 
-```ts
+```typescript
 import { generate } from "@powerduck/openapi-codegen";
-import document from "./openapi.json" with { type: "json" };
 
 const code = generate({
   document,
@@ -109,7 +128,7 @@ const code = generate({
   language: "javascript",
   client: "fetch",
   securityValues: {
-    bearer: "YOUR_ACCESS_TOKEN",
+    bearerAuth: "YOUR_ACCESS_TOKEN",
     apiKey: "YOUR_API_KEY",
   },
 });
@@ -119,13 +138,12 @@ console.log(code);
 
 The keys in `securityValues` must match the security scheme names defined in the OpenAPI document.
 
-Do not commit real credentials to source control.
+**Security note:** Do not commit real credentials to source control.
 
 ## Multipart Uploads
 
-```ts
+```typescript
 import { generate } from "@powerduck/openapi-codegen";
-import document from "./openapi.json" with { type: "json" };
 
 const code = generate({
   document,
@@ -134,7 +152,7 @@ const code = generate({
   language: "shell",
   client: "curl",
   securityValues: {
-    bearer: "YOUR_ACCESS_TOKEN",
+    bearerAuth: "YOUR_ACCESS_TOKEN",
   },
 });
 
@@ -157,7 +175,7 @@ For example, `shell/wget` does not support arbitrary multipart generation. Use `
 
 Use `list()` to inspect every installed language/client combination:
 
-```ts
+```typescript
 import { list } from "@powerduck/openapi-codegen";
 
 for (const { language, client } of list()) {
@@ -167,9 +185,8 @@ for (const { language, client } of list()) {
 
 You can also select a generator programmatically:
 
-```ts
+```typescript
 import { generate, list } from "@powerduck/openapi-codegen";
-import document from "./openapi.json" with { type: "json" };
 
 const generator = list().find(
   ({ language, client }) => language === "javascript" && client === "fetch",
@@ -190,13 +207,28 @@ const code = generate({
 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",
+});
+```
+
 ## API Reference
 
 ### `generate(options)`
 
 Generates an HTTP request example for an OpenAPI operation.
 
-```ts
+```typescript
 const code = generate({
   document,
   path,
@@ -204,19 +236,26 @@ const code = generate({
   language,
   client,
   securityValues,
+  serverUrl,
+  softRefMode,
 });
 ```
 
 #### Options
 
-| Option           | Type                     | Required | Description                            |
-| ---------------- | ------------------------ | -------: | -------------------------------------- |
-| `document`       | `unknown`                |      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 |
+| 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
 
@@ -231,10 +270,11 @@ Generation can throw when:
 - 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:
 
-```ts
+```typescript
 try {
   const code = generate({
     document,
@@ -257,25 +297,51 @@ try {
 
 Returns the available generator descriptors:
 
-```ts
+```typescript
 const generators = list();
 ```
 
-Each descriptor contains the identifiers required by `generate()`:
+Each descriptor contains:
 
-```ts
-for (const { language, client } of generators) {
-  console.log(language, client);
+```typescript
+interface GeneratorDescriptor {
+  language: string;
+  client: string;
 }
 ```
 
+### `get(language, client)`
+
+Returns a specific generator by language and client, or `undefined` if not found:
+
+```typescript
+const generator = get("javascript", "fetch");
+```
+
+### `register(generator)`
+
+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";
+  },
+});
+```
+
 ## OpenAPI Document Input
 
 Pass a parsed JavaScript object rather than a JSON or YAML source string.
 
 ### JSON
 
-```ts
+```typescript
 import { readFile } from "node:fs/promises";
 import { generate } from "@powerduck/openapi-codegen";
 
@@ -303,7 +369,7 @@ npm install yaml
 
 Parse the document before passing it to `generate()`:
 
-```ts
+```typescript
 import { readFile } from "node:fs/promises";
 import YAML from "yaml";
 import { generate } from "@powerduck/openapi-codegen";
@@ -322,6 +388,46 @@ const code = generate({
 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:
@@ -345,13 +451,23 @@ Review generated code before using it in production. You may need to:
 - 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
 
 Clone the repository and install dependencies:
 
 ```bash
-git clone https://github.com/PowerDuckie/-powerduck-openapi-codegen.git
-cd ./-powerduck-openapi-codegen
+git clone https://github.com/PowerDuckie/openapi-codegen.git
+cd openapi-codegen
 npm install
 ```
 
@@ -361,10 +477,10 @@ Run the test suite:
 npm test
 ```
 
-Run property-based fuzz tests:
+Run tests with coverage:
 
 ```bash
-npm run fuzz
+npm run test:coverage
 ```
 
 Build the package:
@@ -373,6 +489,12 @@ Build the package:
 npm run build
 ```
 
+Run type checking:
+
+```bash
+npm run typecheck
+```
+
 Run all release checks:
 
 ```bash
@@ -389,8 +511,9 @@ npm run demo
 
 The project uses:
 
-- [Vitest](https://vitest.dev/) for unit and snapshot tests
-- [fast-check](https://fast-check.dev/) for property-based fuzz testing
+- [Vitest](https://vitest.dev/) for unit and integration tests
+- 270+ tests covering all core modules
+- Full branch coverage for core logic
 
 Run all tests:
 
@@ -398,22 +521,29 @@ Run all tests:
 npm test
 ```
 
-Update snapshots after intentionally changing generated output:
+## Project Structure
 
-```bash
-npx vitest run -u
 ```
-
-Run only the fuzz test suite:
-
-```bash
-npm run fuzz
-```
-
-Before committing snapshot changes, inspect the diff:
-
-```bash
-git diff
+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
 ```
 
 ## Security
@@ -449,13 +579,6 @@ git commit -m "feat: describe the change"
 git push -u origin feature/my-change
 ```
 
-When changing generated output, update and review the affected snapshots:
-
-```bash
-npx vitest run -u
-git diff
-```
-
 ## License
 
 [MIT](LICENSE)