@dorval/core/dist/index.d.ts

Core Dart/Flutter code generation library for OpenAPI specifications

import { OpenAPIV3 } from 'openapi-types';

type OpenAPIObject = OpenAPIV3.Document;
type DartClientType = 'dio' | 'http' | 'chopper' | 'retrofit';
type DartOutputMode = 'single' | 'split' | 'tags';
interface DartGeneratorOptions {
    input: string | OpenAPIObject;
    output: {
        target: string;
        mode?: DartOutputMode;
        client?: DartClientType;
        override?: {
            generator?: {
                freezed?: boolean;
                jsonSerializable?: boolean;
                nullSafety?: boolean;
                partFiles?: boolean;
                equatable?: boolean;
            };
            dio?: {
                baseUrl?: string;
                interceptors?: string[];
            };
            methodNaming?: 'operationId' | 'methodPath';
            sharedHeaders?: Record<string, string[]>;
        };
    };
    hooks?: {
        afterAllFilesWrite?: string | string[];
    };
}
interface GeneratedFile {
    path: string;
    content: string;
    overwrite?: boolean;
}
interface DartModel {
    name: string;
    properties: DartProperty[];
    imports: string[];
    isEnum?: boolean;
    enumValues?: string[];
    description?: string;
}
interface DartProperty {
    name: string;
    type: string;
    required: boolean;
    nullable: boolean;
    description?: string;
    defaultValue?: any;
    jsonKey?: string;
}
interface DartEndpoint {
    name: string;
    method: string;
    path: string;
    parameters: DartParameter[];
    requestBody?: DartRequestBody;
    responses: DartResponse[];
    description?: string;
    deprecated?: boolean;
    tags?: string[];
}
interface DartParameter {
    name: string;
    type: string;
    in: 'path' | 'query' | 'header' | 'cookie';
    required: boolean;
    description?: string;
}
interface DartRequestBody {
    type: string;
    required: boolean;
    contentType?: string;
}
interface DartResponse {
    status: string;
    type?: string;
    description?: string;
}
type DartConfig = {
    [project: string]: DartGeneratorOptions;
};
type DartConfigExport = DartConfig | Promise<DartConfig> | (() => DartConfig | Promise<DartConfig>);

/**
 * OpenAPI specification parser with enhanced functionality
 */

declare class OpenAPIParser {
    private spec;
    private resolved;
    /**
     * Parse and validate OpenAPI specification
     */
    parse(input: string | OpenAPIObject): Promise<this>;
    /**
     * Parse without dereferencing to preserve $refs
     */
    parseWithoutDereference(input: string | OpenAPIObject): Promise<this>;
    /**
     * Get the parsed specification
     */
    getSpec(): OpenAPIObject;
    /**
     * Get API info
     */
    getInfo(): OpenAPIV3.InfoObject;
    /**
     * Get servers
     */
    getServers(): OpenAPIV3.ServerObject[];
    /**
     * Get base URL from first server
     */
    getBaseUrl(): string;
    /**
     * Get all paths
     */
    getPaths(): OpenAPIV3.PathsObject;
    /**
     * Get components
     */
    getComponents(): OpenAPIV3.ComponentsObject | undefined;
    /**
     * Get all schemas
     */
    getSchemas(): Record<string, OpenAPIV3.SchemaObject>;
    /**
     * Get all tags
     */
    getTags(): OpenAPIV3.TagObject[];
    /**
     * Extract Dart models from the spec
     */
    extractModels(): DartModel[];
    /**
     * Extract Dart endpoints from the spec
     */
    extractEndpoints(): DartEndpoint[];
    /**
     * Get endpoints grouped by tag
     */
    getEndpointsByTag(): Map<string, DartEndpoint[]>;
    /**
     * Check if spec has been parsed
     */
    private ensureParsed;
    /**
     * Get operation by operationId
     */
    getOperationById(operationId: string): OpenAPIV3.OperationObject | null;
    /**
     * Get all security schemes
     */
    getSecuritySchemes(): Record<string, OpenAPIV3.SecuritySchemeObject>;
    /**
     * Check if API requires authentication
     */
    hasAuthentication(): boolean;
    /**
     * Get global parameters
     */
    getGlobalParameters(): OpenAPIV3.ParameterObject[];
}

/**
 * Extract and parse model definitions from OpenAPI spec
 */

declare function extractModels(spec: OpenAPIObject): DartModel[];

/**
 * Extract endpoint definitions from OpenAPI spec
 */

declare function extractEndpoints(spec: OpenAPIObject): DartEndpoint[];

/**
 * Resolve $ref references in OpenAPI spec
 */

declare function resolveReferences(spec: OpenAPIObject): OpenAPIObject;

/**
 * OpenAPI specification parser
 * Converts OpenAPI/Swagger specs to internal representation
 */

declare function parseOpenAPISpec(input: string | OpenAPIObject): Promise<OpenAPIObject>;

/**
 * Generate Dart model files using Freezed
 */

declare function generateModels(spec: OpenAPIObject, options: DartGeneratorOptions): Promise<GeneratedFile[]>;

/**
 * Generate Dio API client
 */

declare function generateClient(spec: OpenAPIObject, options: DartGeneratorOptions): Promise<GeneratedFile[]>;

/**
 * Generate API service classes
 */

declare function generateServices(spec: OpenAPIObject, options: DartGeneratorOptions): Promise<GeneratedFile[]>;

/**
 * Utility for resolving OpenAPI $ref references
 */

declare class RefResolver {
    private schemas;
    private schemaNames;
    private processedSchemas;
    constructor(schemas: Record<string, OpenAPIV3.SchemaObject>);
    /**
     * Build a map of schema objects to their names
     */
    private buildSchemaNameMap;
    /**
     * Get a unique key for a schema object
     */
    private getSchemaKey;
    /**
     * Resolve a schema to get its Dart type
     */
    resolveSchemaType(schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject): string;
    /**
     * Resolve property type with proper model references
     */
    resolvePropertyType(propSchema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, required?: boolean): {
        type: string;
        imports: string[];
        isModel: boolean;
    };
    /**
     * Check if a schema represents an enum
     */
    isEnumSchema(schema: OpenAPIV3.SchemaObject): boolean;
    /**
     * Extract enum values from schema
     */
    getEnumValues(schema: OpenAPIV3.SchemaObject): string[];
    /**
     * Check for circular dependencies
     */
    hasCircularDependency(schemaName: string, visited?: Set<string>): boolean;
}

/**
 * Dart model generator using Freezed
 */

declare class ModelGenerator {
    private templateManager;
    private refResolver?;
    constructor();
    /**
     * Set the reference resolver for this generator
     */
    setRefResolver(refResolver: RefResolver): void;
    /**
     * Generate a Freezed model from OpenAPI schema
     */
    generateModel(name: string, schema: OpenAPIV3.SchemaObject): GeneratedFile;
    /**
     * Convert OpenAPI schema to DartModel
     */
    private schemaToModel;
    /**
     * Render a DartModel to Dart code
     */
    private renderModel;
    /**
     * Format default value for template
     */
    private formatDefaultValue;
    /**
     * Generate enum from schema
     */
    generateEnum(name: string, values: string[], description?: string): GeneratedFile;
}

/**
 * Generate Dart API endpoint methods
 */

interface EndpointMethod {
    methodName: string;
    httpMethod: string;
    path: string;
    description?: string;
    summary?: string;
    deprecated?: boolean;
    deprecationMessage?: string;
    hasParameters: boolean;
    parameters: MethodParameter[];
    pathParams: PathParameter[];
    queryParams: QueryParameter[];
    headers: HeaderParameter[];
    hasPathParams: boolean;
    hasQueryParams: boolean;
    hasHeaders: boolean;
    hasBody: boolean;
    bodyParam?: string;
    bodyType?: string;
    returnType: string;
    responseDataType?: string;
    returnsVoid: boolean;
    returnsList: boolean;
    returnsModel: boolean;
    returnsPrimitive: boolean;
    isGenericResponse: boolean;
    itemType?: string;
    hasErrorHandling: boolean;
    errorResponses: ErrorResponse[];
    contentType?: string;
    responseType?: string;
    hasCancelToken: boolean;
    hasProgressCallback: boolean;
    hasSpecialOptions: boolean;
    queryParamsModelName?: string;
    headersModelName?: string;
    needsParamsModel: boolean;
    needsHeadersModel: boolean;
}
interface MethodParameter {
    name: string;
    type: string;
    required: boolean;
    description?: string;
}
interface PathParameter {
    name: string;
    dartName: string;
    originalName: string;
}
interface QueryParameter {
    dartName: string;
    originalName: string;
    required: boolean;
    type?: string;
    description?: string;
}
interface HeaderParameter {
    dartName: string;
    originalName: string;
    required: boolean;
    type?: string;
    description?: string;
}
interface ErrorResponse {
    statusCode: number;
    description: string;
    hasErrorModel: boolean;
    errorModel?: string;
}
declare class EndpointGenerator {
    private schemas;
    private originalSpec;
    private referenceResolver;
    private methodNaming;
    /**
     * Set schemas for reference resolution
     */
    setSchemas(schemas: Record<string, any>): void;
    /**
     * Set original spec for reference resolution
     */
    setOriginalSpec(spec: OpenAPIV3.Document): void;
    /**
     * Set method naming strategy
     */
    setMethodNaming(naming: 'operationId' | 'methodPath'): void;
    /**
     * Generate method data for a GET endpoint
     */
    generateGetMethod(operationId: string, path: string, operation: OpenAPIV3.OperationObject, pathItem?: OpenAPIV3.PathItemObject): EndpointMethod;
    /**
     * Generate method data for POST/PUT/PATCH endpoint
     */
    generateMutationMethod(method: string, operationId: string, path: string, operation: OpenAPIV3.OperationObject, pathItem?: OpenAPIV3.PathItemObject): EndpointMethod;
    /**
     * Generate method data for DELETE endpoint
     */
    generateDeleteMethod(operationId: string, path: string, operation: OpenAPIV3.OperationObject, pathItem?: OpenAPIV3.PathItemObject): EndpointMethod;
    /**
     * Extract parameters from operation
     */
    private extractParameters;
    /**
     * Extract request body information
     */
    private extractRequestBody;
    /**
     * Get successful response schema
     */
    private getSuccessResponse;
    /**
     * Determine return type from response
     */
    private getReturnType;
    /**
     * Extract model name from $ref
     */
    private getModelNameFromRef;
    /**
     * Get original response from spec to preserve $ref
     */
    private getOriginalResponse;
    /**
     * Get parameter type
     */
    private getParameterType;
    /**
     * Generate method name from operation
     */
    private getMethodName;
    /**
     * Normalize path for Dart string
     */
    private normalizePath;
    /**
     * Resolve a parameter reference
     */
    private resolveParameterRef;
}

/**
 * Generate Dart service classes
 */

declare class ServiceGenerator {
    private endpointGenerator;
    private templateManager;
    private paramsGenerator;
    private configurableHeaderGenerator;
    private schemas;
    private originalSpec;
    private options;
    constructor();
    /**
     * Generate service classes from OpenAPI spec
     */
    generateServices(spec: OpenAPIObject, options: DartGeneratorOptions): Promise<GeneratedFile[]>;
    /**
     * Get endpoints grouped by tag
     */
    private getEndpointsByTag;
    /**
     * Create a service class from endpoints
     */
    private createServiceClass;
    /**
     * Render a service class
     */
    private renderService;
    /**
     * Generate index file for services
     */
    private generateServicesIndex;
    /**
     * Check if a type is primitive
     */
    private isPrimitiveType;
    /**
     * Generate ApiException file
     */
    private generateApiException;
    /**
     * Generate index file for parameter models
     */
    private generateParamsIndex;
    /**
     * Generate index file for header models
     */
    private generateHeadersIndex;
}

/**
 * Main generator orchestrator
 */

declare function generateDartCode(options: DartGeneratorOptions): Promise<GeneratedFile[]>;

/**
 * File system utilities
 */

declare function writeToDisk(files: GeneratedFile[], targetDir: string): Promise<void>;
declare function readFile(filePath: string): Promise<string>;
declare function fileExists(filePath: string): Promise<boolean>;

/**
 * OpenAPI to Dart type mapping utilities
 */

type SchemaObject = OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
/**
 * Basic type mapping from OpenAPI to Dart
 */
declare const TYPE_MAP: Record<string, string>;
declare class TypeMapper {
    /**
     * Map OpenAPI type to Dart type
     */
    static mapType(schema: SchemaObject): string;
    /**
     * Map OpenAPI type to Dart type with null safety
     */
    static mapTypeWithNullability(schema: SchemaObject, required?: boolean): string;
    /**
     * Extract type name from $ref
     */
    static extractTypeFromRef(ref: string): string;
    /**
     * Convert OpenAPI property name to Dart property name
     */
    static toDartPropertyName(name: string): string;
    /**
     * List of Dart reserved keywords
     */
    private static readonly DART_RESERVED_KEYWORDS;
    /**
     * Check if a name is a Dart reserved keyword
     */
    static isDartReservedKeyword(name: string): boolean;
    /**
     * Convert to camelCase (specifically for parameter names)
     */
    static toCamelCase(name: string): string;
    /**
     * Convert to Dart class name (PascalCase)
     */
    static toDartClassName(name: string): string;
    /**
     * Convert to snake_case for file names
     */
    static toSnakeCase(str: string): string;
    /**
     * Get Dart imports needed for a type
     */
    static getImportsForType(type: string): string[];
    /**
     * Check if type needs JSON serialization annotation
     */
    static needsJsonAnnotation(schema: SchemaObject, propertyName: string): boolean;
    /**
     * Generate JsonKey annotation
     */
    static generateJsonKeyAnnotation(schema: SchemaObject, propertyName: string): string | null;
    /**
     * Generate default value for a type
     */
    static getDefaultValue(schema: SchemaObject): string | null;
}

/**
 * Utility for resolving $ref references in OpenAPI specifications
 */

declare class ReferenceResolver {
    private spec;
    constructor(spec: OpenAPIV3.Document);
    /**
     * Extract model name from a $ref string
     * Example: "#/components/schemas/LocationSettingsResponseDto" -> "LocationSettingsResponseDto"
     */
    static extractModelNameFromRef(ref: string): string;
    /**
     * Check if a schema is a reference
     */
    static isReference(schema: any): schema is OpenAPIV3.ReferenceObject;
    /**
     * Resolve a reference to its actual schema
     */
    resolveReference(ref: string): OpenAPIV3.SchemaObject | null;
    /**
     * Get the Dart type for a schema (handles both direct schemas and references)
     */
    getDartType(schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject): string;
    /**
     * Get response type from an operation
     */
    getResponseType(operation: OpenAPIV3.OperationObject): string;
    /**
     * Get request body type from an operation
     */
    getRequestBodyType(operation: OpenAPIV3.OperationObject): string | null;
}

/**
 * @dorval/core
 * Core library for generating Dart code from OpenAPI specifications
 */

declare function defineConfig(config: DartConfig): DartConfig;

export { type DartClientType, type DartConfig, type DartConfigExport, type DartGeneratorOptions, type DartOutputMode, EndpointGenerator, type GeneratedFile, ModelGenerator, OpenAPIParser, ReferenceResolver, ServiceGenerator, TYPE_MAP, TypeMapper, defineConfig, extractEndpoints, extractModels, fileExists, generateClient, generateDartCode, generateModels, generateServices, parseOpenAPISpec, readFile, resolveReferences, writeToDisk };