@powerduck/openapi-codegen 0.4.3 → 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,271 @@
+/**
+ * Shared type definitions for OpenAPI3.2 code-generation library
+ * Browser-compatible, compliant with OAS 3.2 specification
+ */
+type ParameterLocation = "path" | "query" | "querystring" | "header" | "cookie";
+interface FileValue {
+    __file: true;
+    path?: string;
+    name?: string;
+    contentType?: string;
+    data?: string | ArrayBuffer | Uint8Array | Blob;
+}
+interface Parameter {
+    name: string;
+    in: ParameterLocation;
+    value: unknown;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+interface Body {
+    mediaType: string;
+    value: unknown;
+    encoding?: Record<string, unknown>;
+}
+interface Security {
+    name: string;
+    type: string;
+    scheme?: string;
+    in?: string;
+    paramName?: string;
+    value: string;
+}
+interface RequestIR {
+    method: string;
+    baseUrl: string;
+    path: string;
+    parameters: Parameter[];
+    headers: Parameter[];
+    body?: Body;
+    security: Security[];
+}
+interface GenerateResult {
+    code: string;
+    files?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+interface Generator {
+    language: string;
+    client: string;
+    generate(request: RequestIR): string;
+}
+interface Plugin {
+    name: string;
+    register(api: {
+        register(generator: Generator): void;
+    }): void;
+}
+interface GenerateOptions {
+    language: string;
+    client: string;
+    request?: RequestIR;
+    document?: unknown;
+    path?: string;
+    method?: string;
+    serverUrl?: string;
+    securityValues?: Record<string, string>;
+    softRefMode?: boolean;
+}
+
+/**
+ * RefResolver for OpenAPI 3.2, browser-compatible, only supports in-document JSON-Pointer references starting with #/
+ * Compliant: https://spec.openapis.org/oas/3.2/schema/2025-11-23.html
+ */
+declare class RefResolver {
+    private readonly root;
+    private readonly cache;
+    private readonly stack;
+    /** When softMode=true: do NOT throw on broken/circular refs; return partial/original value instead */
+    softMode: boolean;
+    constructor(root: unknown, softMode?: boolean);
+    /**
+     * Dereference value, if it contains $ref, resolve it; otherwise return original value.
+     * Does NOT validate type of resolved result, only resolves pointer.
+     */
+    deref<T = unknown>(value: T): T;
+    /**
+     * Resolve JSON Pointer $ref starting with #/.
+     * Throws for external refs, circular refs, broken pointers unless softMode is enabled.
+     */
+    resolveRef<T = unknown>(ref: string): T;
+    /** Clear internal cache, for reuse with different documents. */
+    clearCache(): void;
+}
+
+/**
+ * Context for example generation, controls readOnly/writeOnly filtering.
+ * - isRequestBody: true → skip readOnly properties
+ * - isResponse: true → skip writeOnly properties
+ */
+type ExampleGenContext = {
+    isRequestBody: boolean;
+    isResponse: boolean;
+};
+declare const defaultExampleContext: ExampleGenContext;
+/**
+ * Generate example value from JSON-Schema / OpenAPI 3.2 Schema Object.
+ * Compliant with OAS3.2 schema 2025-11-23, browser-only.
+ * Handles boolean schemas (true / false), const, enum, composition keywords, type inference, formats.
+ * Respects minLength/maxLength, minItems/maxItems, minimum/maximum, multipleOf.
+ * Skips readOnly fields for request-body context; skips writeOnly fields for response context.
+ * Basic pattern regex-aware string example generation.
+ * @param schema raw schema value (may contain $ref)
+ * @param resolver reference resolver instance
+ * @param seen set for circular-reference detection
+ * @param depth current recursion depth
+ * @param ctx generation context for readOnly/writeOnly rules
+ * @returns example instance value, null for stop-circular, undefined for no-inference
+ */
+declare function example(schema: unknown, resolver: RefResolver, seen?: Set<unknown>, depth?: number, ctx?: ExampleGenContext): unknown;
+
+type Pair = [string, string];
+declare function parameter(parameter: {
+    name: string;
+    in: string;
+    value: unknown;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}): Pair[];
+declare function query(pairs: Pair[]): string;
+declare function cookie(pairs: Pair[]): string;
+declare function headerValue(value: string): string;
+
+type GeneratorEmitter = (request: RequestIR) => string;
+declare function createGenerator(language: string, client: string, emit: GeneratorEmitter): Generator;
+
+declare function registerGenerator(generator: Generator): void;
+declare function getGenerator(language: string, client: string): Generator | undefined;
+declare function listGenerators(): Array<{
+    language: string;
+    client: string;
+}>;
+
+interface PluginApi {
+    register(generator: Generator): void;
+}
+declare function applyPlugin(plugin: Plugin, api: PluginApi): void;
+
+interface CompiledRequest {
+    url: string;
+    headers: Array<[string, string]>;
+    body?: Body;
+    queryPairs: Array<[string, string]>;
+    cookiePairs: Array<[string, string]>;
+}
+declare function compile(request: RequestIR): CompiledRequest;
+declare function form(value: unknown): string;
+
+interface NormalizeOptions {
+    document: unknown;
+    path: string;
+    method: string;
+    serverUrl?: string;
+    securityValues?: Record<string, string>;
+    softRefMode?: boolean;
+}
+interface NormalizedParameter {
+    name: string;
+    in: string;
+    value: unknown;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+interface NormalizedSecurity {
+    name: string;
+    type: string;
+    scheme?: string;
+    in?: string;
+    paramName?: string;
+    value: string;
+}
+declare function normalize(options: NormalizeOptions): {
+    preWarnings: string[];
+    method: string;
+    baseUrl: string;
+    path: string;
+    parameters: NormalizedParameter[];
+    headers: NormalizedParameter[];
+    body: {
+        mediaType: string;
+        value: unknown;
+        encoding?: unknown;
+    } | undefined;
+    security: NormalizedSecurity[];
+};
+
+/**
+ * Unified emitter registry.
+ *
+ * This module replaces the redundant src/generators/ directory.
+ * Each emitter exports an `emit` function; we wrap it with createGenerator
+ * and register all built-in generators here.
+ */
+
+/**
+ * All built-in generators, defined as [language, client, emitter] tuples.
+ * This is the single source of truth for built-in generator registration.
+ */
+declare const builtinGenerators: Generator[];
+
+/**
+ * @powerduck/openapi-codegen
+ *
+ * Generate runnable HTTP request examples from OpenAPI documents.
+ * Supports 21 languages and 41 language/client combinations.
+ *
+ * Browser-compatible, zero runtime dependencies.
+ */
+
+/**
+ * Register all built-in generators.
+ * Called automatically on first use, but can be called explicitly.
+ */
+declare function registerBuiltins(): void;
+/**
+ * Register a custom generator.
+ */
+declare function register(generator: Generator): void;
+/**
+ * Get a generator by language and client.
+ */
+declare function get(language: string, client: string): Generator | undefined;
+/**
+ * List all available generators.
+ */
+declare function list(): Array<{
+    language: string;
+    client: string;
+}>;
+/**
+ * Apply a plugin that can register custom generators.
+ */
+declare function use(plugin: Plugin): void;
+/**
+ * Generate an HTTP request example for an OpenAPI operation.
+ *
+ * @param options - Generation options
+ * @returns Generated source code as a string
+ * @throws Error when the path/method is not found, the generator is unknown,
+ *         or the document is invalid.
+ *
+ * @example
+ * ```typescript
+ * import { generate } from "@powerduck/openapi-codegen";
+ *
+ * const code = generate({
+ *   document: openApiDocument,
+ *   path: "/users/{id}",
+ *   method: "get",
+ *   language: "javascript",
+ *   client: "fetch",
+ * });
+ *
+ * console.log(code);
+ * ```
+ */
+declare function generate(options: GenerateOptions): string;
+
+export { type Body, type CompiledRequest, type ExampleGenContext, type FileValue, type GenerateOptions, type GenerateResult, type Generator, type GeneratorEmitter, type Pair, type Parameter, type ParameterLocation, type Plugin, type PluginApi, RefResolver, type RequestIR, type Security, applyPlugin, builtinGenerators, compile, cookie, createGenerator, defaultExampleContext, example, form, generate, get, getGenerator, headerValue, list, listGenerators, normalize, parameter, query, register, registerBuiltins, registerGenerator, use };

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Shared type definitions for OpenAPI3.2 code-generation library
+ * Browser-compatible, compliant with OAS 3.2 specification
+ */
+type ParameterLocation = "path" | "query" | "querystring" | "header" | "cookie";
+interface FileValue {
+    __file: true;
+    path?: string;
+    name?: string;
+    contentType?: string;
+    data?: string | ArrayBuffer | Uint8Array | Blob;
+}
+interface Parameter {
+    name: string;
+    in: ParameterLocation;
+    value: unknown;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+interface Body {
+    mediaType: string;
+    value: unknown;
+    encoding?: Record<string, unknown>;
+}
+interface Security {
+    name: string;
+    type: string;
+    scheme?: string;
+    in?: string;
+    paramName?: string;
+    value: string;
+}
+interface RequestIR {
+    method: string;
+    baseUrl: string;
+    path: string;
+    parameters: Parameter[];
+    headers: Parameter[];
+    body?: Body;
+    security: Security[];
+}
+interface GenerateResult {
+    code: string;
+    files?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+interface Generator {
+    language: string;
+    client: string;
+    generate(request: RequestIR): string;
+}
+interface Plugin {
+    name: string;
+    register(api: {
+        register(generator: Generator): void;
+    }): void;
+}
+interface GenerateOptions {
+    language: string;
+    client: string;
+    request?: RequestIR;
+    document?: unknown;
+    path?: string;
+    method?: string;
+    serverUrl?: string;
+    securityValues?: Record<string, string>;
+    softRefMode?: boolean;
+}
+
+/**
+ * RefResolver for OpenAPI 3.2, browser-compatible, only supports in-document JSON-Pointer references starting with #/
+ * Compliant: https://spec.openapis.org/oas/3.2/schema/2025-11-23.html
+ */
+declare class RefResolver {
+    private readonly root;
+    private readonly cache;
+    private readonly stack;
+    /** When softMode=true: do NOT throw on broken/circular refs; return partial/original value instead */
+    softMode: boolean;
+    constructor(root: unknown, softMode?: boolean);
+    /**
+     * Dereference value, if it contains $ref, resolve it; otherwise return original value.
+     * Does NOT validate type of resolved result, only resolves pointer.
+     */
+    deref<T = unknown>(value: T): T;
+    /**
+     * Resolve JSON Pointer $ref starting with #/.
+     * Throws for external refs, circular refs, broken pointers unless softMode is enabled.
+     */
+    resolveRef<T = unknown>(ref: string): T;
+    /** Clear internal cache, for reuse with different documents. */
+    clearCache(): void;
+}
+
+/**
+ * Context for example generation, controls readOnly/writeOnly filtering.
+ * - isRequestBody: true → skip readOnly properties
+ * - isResponse: true → skip writeOnly properties
+ */
+type ExampleGenContext = {
+    isRequestBody: boolean;
+    isResponse: boolean;
+};
+declare const defaultExampleContext: ExampleGenContext;
+/**
+ * Generate example value from JSON-Schema / OpenAPI 3.2 Schema Object.
+ * Compliant with OAS3.2 schema 2025-11-23, browser-only.
+ * Handles boolean schemas (true / false), const, enum, composition keywords, type inference, formats.
+ * Respects minLength/maxLength, minItems/maxItems, minimum/maximum, multipleOf.
+ * Skips readOnly fields for request-body context; skips writeOnly fields for response context.
+ * Basic pattern regex-aware string example generation.
+ * @param schema raw schema value (may contain $ref)
+ * @param resolver reference resolver instance
+ * @param seen set for circular-reference detection
+ * @param depth current recursion depth
+ * @param ctx generation context for readOnly/writeOnly rules
+ * @returns example instance value, null for stop-circular, undefined for no-inference
+ */
+declare function example(schema: unknown, resolver: RefResolver, seen?: Set<unknown>, depth?: number, ctx?: ExampleGenContext): unknown;
+
+type Pair = [string, string];
+declare function parameter(parameter: {
+    name: string;
+    in: string;
+    value: unknown;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}): Pair[];
+declare function query(pairs: Pair[]): string;
+declare function cookie(pairs: Pair[]): string;
+declare function headerValue(value: string): string;
+
+type GeneratorEmitter = (request: RequestIR) => string;
+declare function createGenerator(language: string, client: string, emit: GeneratorEmitter): Generator;
+
+declare function registerGenerator(generator: Generator): void;
+declare function getGenerator(language: string, client: string): Generator | undefined;
+declare function listGenerators(): Array<{
+    language: string;
+    client: string;
+}>;
+
+interface PluginApi {
+    register(generator: Generator): void;
+}
+declare function applyPlugin(plugin: Plugin, api: PluginApi): void;
+
+interface CompiledRequest {
+    url: string;
+    headers: Array<[string, string]>;
+    body?: Body;
+    queryPairs: Array<[string, string]>;
+    cookiePairs: Array<[string, string]>;
+}
+declare function compile(request: RequestIR): CompiledRequest;
+declare function form(value: unknown): string;
+
+interface NormalizeOptions {
+    document: unknown;
+    path: string;
+    method: string;
+    serverUrl?: string;
+    securityValues?: Record<string, string>;
+    softRefMode?: boolean;
+}
+interface NormalizedParameter {
+    name: string;
+    in: string;
+    value: unknown;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+interface NormalizedSecurity {
+    name: string;
+    type: string;
+    scheme?: string;
+    in?: string;
+    paramName?: string;
+    value: string;
+}
+declare function normalize(options: NormalizeOptions): {
+    preWarnings: string[];
+    method: string;
+    baseUrl: string;
+    path: string;
+    parameters: NormalizedParameter[];
+    headers: NormalizedParameter[];
+    body: {
+        mediaType: string;
+        value: unknown;
+        encoding?: unknown;
+    } | undefined;
+    security: NormalizedSecurity[];
+};
+
+/**
+ * Unified emitter registry.
+ *
+ * This module replaces the redundant src/generators/ directory.
+ * Each emitter exports an `emit` function; we wrap it with createGenerator
+ * and register all built-in generators here.
+ */
+
+/**
+ * All built-in generators, defined as [language, client, emitter] tuples.
+ * This is the single source of truth for built-in generator registration.
+ */
+declare const builtinGenerators: Generator[];
+
+/**
+ * @powerduck/openapi-codegen
+ *
+ * Generate runnable HTTP request examples from OpenAPI documents.
+ * Supports 21 languages and 41 language/client combinations.
+ *
+ * Browser-compatible, zero runtime dependencies.
+ */
+
+/**
+ * Register all built-in generators.
+ * Called automatically on first use, but can be called explicitly.
+ */
+declare function registerBuiltins(): void;
+/**
+ * Register a custom generator.
+ */
+declare function register(generator: Generator): void;
+/**
+ * Get a generator by language and client.
+ */
+declare function get(language: string, client: string): Generator | undefined;
+/**
+ * List all available generators.
+ */
+declare function list(): Array<{
+    language: string;
+    client: string;
+}>;
+/**
+ * Apply a plugin that can register custom generators.
+ */
+declare function use(plugin: Plugin): void;
+/**
+ * Generate an HTTP request example for an OpenAPI operation.
+ *
+ * @param options - Generation options
+ * @returns Generated source code as a string
+ * @throws Error when the path/method is not found, the generator is unknown,
+ *         or the document is invalid.
+ *
+ * @example
+ * ```typescript
+ * import { generate } from "@powerduck/openapi-codegen";
+ *
+ * const code = generate({
+ *   document: openApiDocument,
+ *   path: "/users/{id}",
+ *   method: "get",
+ *   language: "javascript",
+ *   client: "fetch",
+ * });
+ *
+ * console.log(code);
+ * ```
+ */
+declare function generate(options: GenerateOptions): string;
+
+export { type Body, type CompiledRequest, type ExampleGenContext, type FileValue, type GenerateOptions, type GenerateResult, type Generator, type GeneratorEmitter, type Pair, type Parameter, type ParameterLocation, type Plugin, type PluginApi, RefResolver, type RequestIR, type Security, applyPlugin, builtinGenerators, compile, cookie, createGenerator, defaultExampleContext, example, form, generate, get, getGenerator, headerValue, list, listGenerators, normalize, parameter, query, register, registerBuiltins, registerGenerator, use };