auto-api-hooks 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,297 @@
+/**
+ * Intermediate Representation (IR) types.
+ *
+ * All parsers (OpenAPI, Swagger, GraphQL) produce this IR.
+ * All generators (fetch, axios, react-query, swr) consume it.
+ */
+/** The complete normalized API specification. */
+interface ApiSpec {
+    /** Human-readable title from the spec. */
+    title: string;
+    /** Base URL / server URL. */
+    baseUrl: string;
+    /** API version string. */
+    version: string;
+    /** All operations (endpoints / queries / mutations). */
+    operations: ApiOperation[];
+    /** All named types referenced by operations. */
+    types: Map<string, ApiType>;
+}
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+type OperationMethod = HttpMethod | 'QUERY' | 'MUTATION' | 'SUBSCRIPTION';
+/** A single API operation (REST endpoint or GraphQL field). */
+interface ApiOperation {
+    /** Unique operation ID (from spec or auto-generated). */
+    operationId: string;
+    /** Human-readable summary. */
+    summary?: string;
+    /** HTTP method or GraphQL operation type. */
+    method: OperationMethod;
+    /** URL path with parameter placeholders, e.g. `/users/{id}`. */
+    path: string;
+    /** Tags / groups for organizing generated files. */
+    tags: string[];
+    /** Path parameters. */
+    pathParams: ApiParam[];
+    /** Query string parameters. */
+    queryParams: ApiParam[];
+    /** Header parameters. */
+    headerParams: ApiParam[];
+    /** Request body schema (if any). */
+    requestBody?: ApiRequestBody;
+    /** Response schema (success case). */
+    response: ApiResponse;
+    /** Whether this is a paginated endpoint. */
+    pagination?: PaginationInfo;
+    /** Whether this operation is deprecated. */
+    deprecated: boolean;
+}
+interface ApiParam {
+    name: string;
+    required: boolean;
+    type: ApiType;
+    description?: string;
+    in: 'path' | 'query' | 'header';
+}
+interface ApiRequestBody {
+    required: boolean;
+    contentType: string;
+    type: ApiType;
+    description?: string;
+}
+interface ApiResponse {
+    statusCode: number | 'default';
+    contentType: string;
+    type: ApiType;
+    description?: string;
+}
+type PaginationStrategy = 'cursor' | 'offset-limit' | 'page-number';
+interface PaginationInfo {
+    /** Strategy detected. */
+    strategy: PaginationStrategy;
+    /** The query param name for the cursor / offset / page. */
+    pageParam: string;
+    /** Dot-path in the response to find the next page value. */
+    nextPagePath: string[];
+    /** Dot-path in the response to find the items array. */
+    itemsPath: string[];
+}
+/**
+ * Recursive type representation — a unified schema type system
+ * that covers JSON Schema and GraphQL types.
+ */
+type ApiType = ApiPrimitiveType | ApiObjectType | ApiArrayType | ApiEnumType | ApiUnionType | ApiRefType;
+interface ApiPrimitiveType {
+    kind: 'primitive';
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'null' | 'unknown';
+    /** e.g. 'date-time', 'email', 'uuid', 'int64', 'uri' */
+    format?: string;
+    description?: string;
+}
+interface ApiObjectType {
+    kind: 'object';
+    name?: string;
+    properties: ApiProperty[];
+    additionalProperties?: ApiType | boolean;
+    description?: string;
+}
+interface ApiProperty {
+    name: string;
+    type: ApiType;
+    required: boolean;
+    description?: string;
+}
+interface ApiArrayType {
+    kind: 'array';
+    items: ApiType;
+    description?: string;
+}
+interface ApiEnumType {
+    kind: 'enum';
+    name?: string;
+    values: (string | number)[];
+    description?: string;
+}
+interface ApiUnionType {
+    kind: 'union';
+    variants: ApiType[];
+    description?: string;
+}
+interface ApiRefType {
+    kind: 'ref';
+    /** Reference to a named type in ApiSpec.types. */
+    name: string;
+}
+
+interface GeneratedFile {
+    /** Relative path from output directory. */
+    path: string;
+    /** Generated source code. */
+    content: string;
+}
+
+/**
+ * Generator interfaces and types.
+ */
+
+type FetcherStrategy = 'fetch' | 'axios' | 'react-query' | 'swr';
+interface GeneratorOptions {
+    /** Which fetcher strategy to generate. */
+    fetcher: FetcherStrategy;
+    /** Generate Zod validation schemas for response validation. */
+    zod: boolean;
+    /** Generate MSW mock server handlers. */
+    mock: boolean;
+    /** Output directory path. */
+    outputDir: string;
+    /** Base URL override. */
+    baseUrl?: string;
+    /** Whether to generate infinite query hooks for paginated endpoints. */
+    infiniteQueries: boolean;
+}
+interface HookGenerator {
+    /** Generate all files for the given spec. */
+    generate(spec: ApiSpec, options: GeneratorOptions): GeneratedFile[];
+}
+
+interface ParseOptions {
+    baseUrl?: string;
+}
+
+/**
+ * Parses an API specification from a file path, URL, or in-memory object.
+ *
+ * Supports OpenAPI 3.x, Swagger 2.0, and GraphQL (introspection JSON or SDL).
+ * File formats: `.yaml`, `.yml`, `.json`, `.graphql`, `.gql`.
+ *
+ * After parsing, automatic pagination detection is applied to all GET/QUERY
+ * operations.
+ *
+ * @param input - A file path string, or an already-parsed object (JSON/YAML content or introspection result).
+ * @param options - Optional parse configuration (e.g. base URL override).
+ * @returns The parsed API specification in the IR format.
+ * @throws {ParseError} If the input format is not recognized or no parser can handle it.
+ *
+ * @example
+ * ```ts
+ * // From file
+ * const spec = await parseSpec('./openapi.yaml')
+ *
+ * // From object
+ * const spec = await parseSpec(openapiDocument, { baseUrl: 'https://api.example.com' })
+ *
+ * // From GraphQL SDL
+ * const spec = await parseSpec('./schema.graphql')
+ * ```
+ */
+declare function parseSpec(input: string | object, options?: ParseOptions): Promise<ApiSpec>;
+
+/**
+ * Generator factory and public API.
+ */
+
+/**
+ * Create a hook generator for the specified fetcher strategy.
+ */
+declare function createGenerator(strategy: FetcherStrategy): HookGenerator;
+/**
+ * Generate hooks from a parsed API spec.
+ */
+declare function generateHooks(spec: ApiSpec, options: GeneratorOptions): GeneratedFile[];
+
+/**
+ * Mock generation public API.
+ */
+
+/**
+ * Generate all mock-related files.
+ */
+declare function generateMockFiles(spec: ApiSpec): GeneratedFile[];
+
+/**
+ * TypeScript source code emitter.
+ *
+ * Converts IR types into plain TypeScript string output that can be
+ * written directly to a `.ts` file. No ts-morph dependency — just
+ * fast string concatenation.
+ */
+
+/**
+ * Generate a complete TypeScript `types.ts` file from the API specification.
+ *
+ * The output includes:
+ * - All named types from `spec.types` as interfaces / type aliases
+ * - Per-operation params, request body, and response types
+ * - JSDoc comments where descriptions are available
+ *
+ * Every exported symbol is prefixed with `export`.
+ */
+declare function emitTypeScriptTypes(spec: ApiSpec): string;
+/**
+ * Convert an {@link ApiType} into its TypeScript string representation.
+ *
+ * Handles all discriminated union kinds recursively:
+ * - `primitive` -> `string`, `number`, `boolean`, `null`, `unknown`
+ * - `object`    -> inline `{ ... }` literal
+ * - `array`     -> `Array<T>`
+ * - `enum`      -> string/number literal union
+ * - `union`     -> `A | B | C`
+ * - `ref`       -> PascalCase type name
+ */
+declare function emitTypeString(type: ApiType): string;
+
+/**
+ * Zod schema source code emitter.
+ *
+ * Converts IR types into Zod schema definitions as plain TypeScript
+ * strings. The output can be written directly to a `schemas.ts` file.
+ */
+
+/**
+ * Generate a complete Zod `schemas.ts` file from the API specification.
+ *
+ * The output includes:
+ * - `import { z } from 'zod'`
+ * - A `const …Schema = z.…` for every named type in `spec.types`
+ * - A response schema for every operation
+ * - Re-exports of all schemas
+ */
+declare function emitZodSchemas(spec: ApiSpec): string;
+/**
+ * Convert an {@link ApiType} into its Zod schema string representation.
+ *
+ * Handles every discriminated union kind recursively:
+ * - `primitive` -> `z.string()`, `z.number()`, etc. with format refinements
+ * - `object`    -> `z.object({ ... })`
+ * - `array`     -> `z.array(...)`
+ * - `enum`      -> `z.enum([...])` for strings, `z.union([z.literal(...), ...])` for mixed
+ * - `union`     -> `z.union([...])`
+ * - `ref`       -> camelCase schema variable name
+ */
+declare function emitZodType(type: ApiType): string;
+
+interface GenerateOptions {
+    /** Path to the API spec file, or a parsed object. */
+    spec: string | object;
+    /** Fetching strategy. */
+    fetcher: FetcherStrategy;
+    /** Output directory. If provided, files are written to disk. */
+    outputDir?: string;
+    /** Override base URL from the spec. */
+    baseUrl?: string;
+    /** Generate Zod validation schemas. */
+    zod?: boolean;
+    /** Generate MSW mock server handlers. */
+    mock?: boolean;
+    /** Generate infinite query hooks for paginated endpoints. */
+    infiniteQueries?: boolean;
+}
+/**
+ * Generate type-safe React hooks from an API specification.
+ *
+ * @param options - Generation options
+ * @returns Array of generated files (path + content)
+ */
+declare function generate(options: GenerateOptions): Promise<GeneratedFile[]>;
+
+export { type ApiArrayType, type ApiEnumType, type ApiObjectType, type ApiOperation, type ApiParam, type ApiPrimitiveType, type ApiProperty, type ApiRefType, type ApiRequestBody, type ApiResponse, type ApiSpec, type ApiType, type ApiUnionType, type FetcherStrategy, type GenerateOptions, type GeneratedFile, type GeneratorOptions, type HookGenerator, type HttpMethod, type OperationMethod, type PaginationInfo, type PaginationStrategy, type ParseOptions, createGenerator, emitTypeScriptTypes, emitTypeString, emitZodSchemas, emitZodType, generate, generateHooks, generateMockFiles, parseSpec };

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+/**
+ * Intermediate Representation (IR) types.
+ *
+ * All parsers (OpenAPI, Swagger, GraphQL) produce this IR.
+ * All generators (fetch, axios, react-query, swr) consume it.
+ */
+/** The complete normalized API specification. */
+interface ApiSpec {
+    /** Human-readable title from the spec. */
+    title: string;
+    /** Base URL / server URL. */
+    baseUrl: string;
+    /** API version string. */
+    version: string;
+    /** All operations (endpoints / queries / mutations). */
+    operations: ApiOperation[];
+    /** All named types referenced by operations. */
+    types: Map<string, ApiType>;
+}
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+type OperationMethod = HttpMethod | 'QUERY' | 'MUTATION' | 'SUBSCRIPTION';
+/** A single API operation (REST endpoint or GraphQL field). */
+interface ApiOperation {
+    /** Unique operation ID (from spec or auto-generated). */
+    operationId: string;
+    /** Human-readable summary. */
+    summary?: string;
+    /** HTTP method or GraphQL operation type. */
+    method: OperationMethod;
+    /** URL path with parameter placeholders, e.g. `/users/{id}`. */
+    path: string;
+    /** Tags / groups for organizing generated files. */
+    tags: string[];
+    /** Path parameters. */
+    pathParams: ApiParam[];
+    /** Query string parameters. */
+    queryParams: ApiParam[];
+    /** Header parameters. */
+    headerParams: ApiParam[];
+    /** Request body schema (if any). */
+    requestBody?: ApiRequestBody;
+    /** Response schema (success case). */
+    response: ApiResponse;
+    /** Whether this is a paginated endpoint. */
+    pagination?: PaginationInfo;
+    /** Whether this operation is deprecated. */
+    deprecated: boolean;
+}
+interface ApiParam {
+    name: string;
+    required: boolean;
+    type: ApiType;
+    description?: string;
+    in: 'path' | 'query' | 'header';
+}
+interface ApiRequestBody {
+    required: boolean;
+    contentType: string;
+    type: ApiType;
+    description?: string;
+}
+interface ApiResponse {
+    statusCode: number | 'default';
+    contentType: string;
+    type: ApiType;
+    description?: string;
+}
+type PaginationStrategy = 'cursor' | 'offset-limit' | 'page-number';
+interface PaginationInfo {
+    /** Strategy detected. */
+    strategy: PaginationStrategy;
+    /** The query param name for the cursor / offset / page. */
+    pageParam: string;
+    /** Dot-path in the response to find the next page value. */
+    nextPagePath: string[];
+    /** Dot-path in the response to find the items array. */
+    itemsPath: string[];
+}
+/**
+ * Recursive type representation — a unified schema type system
+ * that covers JSON Schema and GraphQL types.
+ */
+type ApiType = ApiPrimitiveType | ApiObjectType | ApiArrayType | ApiEnumType | ApiUnionType | ApiRefType;
+interface ApiPrimitiveType {
+    kind: 'primitive';
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'null' | 'unknown';
+    /** e.g. 'date-time', 'email', 'uuid', 'int64', 'uri' */
+    format?: string;
+    description?: string;
+}
+interface ApiObjectType {
+    kind: 'object';
+    name?: string;
+    properties: ApiProperty[];
+    additionalProperties?: ApiType | boolean;
+    description?: string;
+}
+interface ApiProperty {
+    name: string;
+    type: ApiType;
+    required: boolean;
+    description?: string;
+}
+interface ApiArrayType {
+    kind: 'array';
+    items: ApiType;
+    description?: string;
+}
+interface ApiEnumType {
+    kind: 'enum';
+    name?: string;
+    values: (string | number)[];
+    description?: string;
+}
+interface ApiUnionType {
+    kind: 'union';
+    variants: ApiType[];
+    description?: string;
+}
+interface ApiRefType {
+    kind: 'ref';
+    /** Reference to a named type in ApiSpec.types. */
+    name: string;
+}
+
+interface GeneratedFile {
+    /** Relative path from output directory. */
+    path: string;
+    /** Generated source code. */
+    content: string;
+}
+
+/**
+ * Generator interfaces and types.
+ */
+
+type FetcherStrategy = 'fetch' | 'axios' | 'react-query' | 'swr';
+interface GeneratorOptions {
+    /** Which fetcher strategy to generate. */
+    fetcher: FetcherStrategy;
+    /** Generate Zod validation schemas for response validation. */
+    zod: boolean;
+    /** Generate MSW mock server handlers. */
+    mock: boolean;
+    /** Output directory path. */
+    outputDir: string;
+    /** Base URL override. */
+    baseUrl?: string;
+    /** Whether to generate infinite query hooks for paginated endpoints. */
+    infiniteQueries: boolean;
+}
+interface HookGenerator {
+    /** Generate all files for the given spec. */
+    generate(spec: ApiSpec, options: GeneratorOptions): GeneratedFile[];
+}
+
+interface ParseOptions {
+    baseUrl?: string;
+}
+
+/**
+ * Parses an API specification from a file path, URL, or in-memory object.
+ *
+ * Supports OpenAPI 3.x, Swagger 2.0, and GraphQL (introspection JSON or SDL).
+ * File formats: `.yaml`, `.yml`, `.json`, `.graphql`, `.gql`.
+ *
+ * After parsing, automatic pagination detection is applied to all GET/QUERY
+ * operations.
+ *
+ * @param input - A file path string, or an already-parsed object (JSON/YAML content or introspection result).
+ * @param options - Optional parse configuration (e.g. base URL override).
+ * @returns The parsed API specification in the IR format.
+ * @throws {ParseError} If the input format is not recognized or no parser can handle it.
+ *
+ * @example
+ * ```ts
+ * // From file
+ * const spec = await parseSpec('./openapi.yaml')
+ *
+ * // From object
+ * const spec = await parseSpec(openapiDocument, { baseUrl: 'https://api.example.com' })
+ *
+ * // From GraphQL SDL
+ * const spec = await parseSpec('./schema.graphql')
+ * ```
+ */
+declare function parseSpec(input: string | object, options?: ParseOptions): Promise<ApiSpec>;
+
+/**
+ * Generator factory and public API.
+ */
+
+/**
+ * Create a hook generator for the specified fetcher strategy.
+ */
+declare function createGenerator(strategy: FetcherStrategy): HookGenerator;
+/**
+ * Generate hooks from a parsed API spec.
+ */
+declare function generateHooks(spec: ApiSpec, options: GeneratorOptions): GeneratedFile[];
+
+/**
+ * Mock generation public API.
+ */
+
+/**
+ * Generate all mock-related files.
+ */
+declare function generateMockFiles(spec: ApiSpec): GeneratedFile[];
+
+/**
+ * TypeScript source code emitter.
+ *
+ * Converts IR types into plain TypeScript string output that can be
+ * written directly to a `.ts` file. No ts-morph dependency — just
+ * fast string concatenation.
+ */
+
+/**
+ * Generate a complete TypeScript `types.ts` file from the API specification.
+ *
+ * The output includes:
+ * - All named types from `spec.types` as interfaces / type aliases
+ * - Per-operation params, request body, and response types
+ * - JSDoc comments where descriptions are available
+ *
+ * Every exported symbol is prefixed with `export`.
+ */
+declare function emitTypeScriptTypes(spec: ApiSpec): string;
+/**
+ * Convert an {@link ApiType} into its TypeScript string representation.
+ *
+ * Handles all discriminated union kinds recursively:
+ * - `primitive` -> `string`, `number`, `boolean`, `null`, `unknown`
+ * - `object`    -> inline `{ ... }` literal
+ * - `array`     -> `Array<T>`
+ * - `enum`      -> string/number literal union
+ * - `union`     -> `A | B | C`
+ * - `ref`       -> PascalCase type name
+ */
+declare function emitTypeString(type: ApiType): string;
+
+/**
+ * Zod schema source code emitter.
+ *
+ * Converts IR types into Zod schema definitions as plain TypeScript
+ * strings. The output can be written directly to a `schemas.ts` file.
+ */
+
+/**
+ * Generate a complete Zod `schemas.ts` file from the API specification.
+ *
+ * The output includes:
+ * - `import { z } from 'zod'`
+ * - A `const …Schema = z.…` for every named type in `spec.types`
+ * - A response schema for every operation
+ * - Re-exports of all schemas
+ */
+declare function emitZodSchemas(spec: ApiSpec): string;
+/**
+ * Convert an {@link ApiType} into its Zod schema string representation.
+ *
+ * Handles every discriminated union kind recursively:
+ * - `primitive` -> `z.string()`, `z.number()`, etc. with format refinements
+ * - `object`    -> `z.object({ ... })`
+ * - `array`     -> `z.array(...)`
+ * - `enum`      -> `z.enum([...])` for strings, `z.union([z.literal(...), ...])` for mixed
+ * - `union`     -> `z.union([...])`
+ * - `ref`       -> camelCase schema variable name
+ */
+declare function emitZodType(type: ApiType): string;
+
+interface GenerateOptions {
+    /** Path to the API spec file, or a parsed object. */
+    spec: string | object;
+    /** Fetching strategy. */
+    fetcher: FetcherStrategy;
+    /** Output directory. If provided, files are written to disk. */
+    outputDir?: string;
+    /** Override base URL from the spec. */
+    baseUrl?: string;
+    /** Generate Zod validation schemas. */
+    zod?: boolean;
+    /** Generate MSW mock server handlers. */
+    mock?: boolean;
+    /** Generate infinite query hooks for paginated endpoints. */
+    infiniteQueries?: boolean;
+}
+/**
+ * Generate type-safe React hooks from an API specification.
+ *
+ * @param options - Generation options
+ * @returns Array of generated files (path + content)
+ */
+declare function generate(options: GenerateOptions): Promise<GeneratedFile[]>;
+
+export { type ApiArrayType, type ApiEnumType, type ApiObjectType, type ApiOperation, type ApiParam, type ApiPrimitiveType, type ApiProperty, type ApiRefType, type ApiRequestBody, type ApiResponse, type ApiSpec, type ApiType, type ApiUnionType, type FetcherStrategy, type GenerateOptions, type GeneratedFile, type GeneratorOptions, type HookGenerator, type HttpMethod, type OperationMethod, type PaginationInfo, type PaginationStrategy, type ParseOptions, createGenerator, emitTypeScriptTypes, emitTypeString, emitZodSchemas, emitZodType, generate, generateHooks, generateMockFiles, parseSpec };