schemantic 0.1.0

package/docs/API.md

@@ -0,0 +1,600 @@
+# API Reference
+
+## Core Classes
+
+### Schemantic
+
+The main class for generating TypeScript types and API clients from OpenAPI schemas.
+
+```typescript
+import { Schemantic, SchemanticConfig } from "schemantic";
+
+const config: SchemanticConfig = {
+  schemaUrl: "http://localhost:8000/openapi.json",
+  outputDir: "./src/generated",
+  generateTypes: true,
+  generateApiClient: true,
+};
+
+const Schemantic = new Schemantic(config);
+```
+
+#### Methods
+
+##### `generate(): Promise<GenerationResult>`
+
+Generates TypeScript types and API clients from the configured OpenAPI schema.
+
+**Returns:** `Promise<GenerationResult>`
+
+```typescript
+const result = await Schemantic.generate();
+
+if (result.success) {
+  console.log(`Generated ${result.generatedFiles.length} files`);
+  console.log(`Types: ${result.statistics.totalTypes}`);
+  console.log(`Endpoints: ${result.statistics.totalEndpoints}`);
+}
+```
+
+##### `validate(): Promise<ValidationResult>`
+
+Validates the OpenAPI schema without generating any files.
+
+**Returns:** `Promise<ValidationResult>`
+
+```typescript
+const validation = await Schemantic.validate();
+
+if (validation.isValid) {
+  console.log("Schema is valid");
+} else {
+  console.log("Validation errors:", validation.errors);
+}
+```
+
+##### `getPluginManager(): PluginManager`
+
+Returns the plugin manager instance for registering and managing plugins.
+
+**Returns:** `PluginManager`
+
+```typescript
+const pluginManager = Schemantic.getPluginManager();
+pluginManager.registerPlugin(customPlugin);
+```
+
+##### `getConfig(): SchemanticConfig`
+
+Returns the current configuration.
+
+**Returns:** `SchemanticConfig`
+
+### SchemanticConfig
+
+Configuration interface for the Schemantic class.
+
+```typescript
+interface SchemanticConfig {
+  // Input configuration
+  schemaUrl?: string;
+  schemaFile?: string;
+  schemaData?: OpenAPISchema;
+
+  // Output configuration
+  outputDir: string;
+  outputFileName?: string;
+
+  // Generation options
+  generateTypes: boolean;
+  generateApiClient: boolean;
+  generateHooks?: boolean;
+  generateQueries?: boolean;
+
+  // TypeScript configuration
+  useStrictTypes: boolean;
+  useOptionalChaining: boolean;
+  useNullishCoalescing: boolean;
+
+  // Naming conventions
+  namingConvention: "camelCase" | "snake_case" | "PascalCase";
+  typePrefix?: string;
+  typeSuffix?: string;
+
+  // Customization
+  customTypeMappings?: Record<string, string>;
+  excludePaths?: string[];
+  includePaths?: string[];
+  excludeSchemas?: string[];
+  includeSchemas?: string[];
+
+  // Plugin configuration
+  plugins?: PluginConfig[];
+
+  // Advanced options
+  preserveComments: boolean;
+  generateIndexFile: boolean;
+  generateBarrelExports: boolean;
+}
+```
+
+## Parser Classes
+
+### ParserFactory
+
+Factory class for creating schema parsers.
+
+```typescript
+import { ParserFactory } from "schemantic";
+
+// Create parser by type
+const parser = ParserFactory.createParser("openapi", config);
+
+// Auto-detect parser type
+const autoParser = ParserFactory.autoCreateParser(input, config);
+```
+
+#### Methods
+
+##### `createParser(type: ParserType, config: SchemanticConfig): SchemaParser`
+
+Creates a parser instance of the specified type.
+
+**Parameters:**
+
+- `type` - The parser type ('openapi', 'swagger', 'json-schema')
+- `config` - Schemantic configuration
+
+**Returns:** `SchemaParser`
+
+##### `autoCreateParser(input: SchemaInput, config: SchemanticConfig): SchemaParser`
+
+Automatically detects the parser type and creates an appropriate instance.
+
+**Parameters:**
+
+- `input` - Schema input source
+- `config` - Schemantic configuration
+
+**Returns:** `SchemaParser`
+
+##### `detectParserType(input: SchemaInput): ParserType`
+
+Detects the appropriate parser type from the input.
+
+**Parameters:**
+
+- `input` - Schema input source
+
+**Returns:** `ParserType`
+
+### OpenAPIParser
+
+Parser implementation for OpenAPI 3.0+ specifications.
+
+```typescript
+import { OpenAPIParser } from "schemantic";
+
+const parser = new OpenAPIParser(config);
+```
+
+#### Methods
+
+##### `parse(input: SchemaInput): Promise<OpenAPISchema>`
+
+Parses schema from various input sources.
+
+**Parameters:**
+
+- `input` - Schema input source
+
+**Returns:** `Promise<OpenAPISchema>`
+
+##### `validate(schema: OpenAPISchema): Promise<ValidationResult>`
+
+Validates the parsed schema.
+
+**Parameters:**
+
+- `schema` - OpenAPI schema to validate
+
+**Returns:** `Promise<ValidationResult>`
+
+##### `createResolver(schema: OpenAPISchema): SchemaResolver`
+
+Creates a schema resolver for the parsed schema.
+
+**Parameters:**
+
+- `schema` - OpenAPI schema
+
+**Returns:** `SchemaResolver`
+
+## Generator Classes
+
+### TypeGeneratorFactory
+
+Factory class for creating type generators.
+
+```typescript
+import { TypeGeneratorFactory } from "schemantic";
+
+// Create generators from config
+const generators = TypeGeneratorFactory.createFromConfig(config);
+
+// Generate type from schema
+const generatedType = TypeGeneratorFactory.generateType(
+  schema,
+  context,
+  generators
+);
+```
+
+#### Methods
+
+##### `createFromConfig(config: SchemanticConfig): TypeGenerator[]`
+
+Creates type generators based on configuration.
+
+**Parameters:**
+
+- `config` - Schemantic configuration
+
+**Returns:** `TypeGenerator[]`
+
+##### `generateType(schema: ResolvedSchema, context: GenerationContext, generators: TypeGenerator[]): GeneratedType | undefined`
+
+Generates a TypeScript type from a schema using available generators.
+
+**Parameters:**
+
+- `schema` - Resolved schema
+- `context` - Generation context
+- `generators` - Available generators
+
+**Returns:** `GeneratedType | undefined`
+
+##### `getBestGenerator(schema: ResolvedSchema, generators: TypeGenerator[]): TypeGenerator | undefined`
+
+Finds the best generator for a given schema.
+
+**Parameters:**
+
+- `schema` - Resolved schema
+- `generators` - Available generators
+
+**Returns:** `TypeGenerator | undefined`
+
+### ObjectTypeGenerator
+
+Generator for creating TypeScript interfaces from OpenAPI schema objects.
+
+```typescript
+import { ObjectTypeGenerator } from "schemantic";
+
+const generator = new ObjectTypeGenerator(options);
+```
+
+### EnumTypeGenerator
+
+Generator for creating TypeScript enums from OpenAPI schema enums.
+
+```typescript
+import { EnumTypeGenerator } from "schemantic";
+
+const generator = new EnumTypeGenerator(options);
+```
+
+### ApiClientGenerator
+
+Generator for creating TypeScript API client classes.
+
+```typescript
+import { ApiClientGenerator } from "schemantic";
+
+const generator = new ApiClientGenerator(context);
+const client = generator.generate(context);
+// The client is exported via the generated index file and can be imported from './generated'
+```
+
+## Plugin System
+
+### PluginManager
+
+Manages plugin registration and execution.
+
+```typescript
+import { PluginManager } from "schemantic";
+
+const pluginManager = new PluginManager();
+```
+
+#### Methods
+
+##### `registerPlugin(plugin: SchemanticPlugin): void`
+
+Registers a plugin with the manager.
+
+**Parameters:**
+
+- `plugin` - Plugin to register
+
+##### `enablePlugin(name: string): void`
+
+Enables a registered plugin.
+
+**Parameters:**
+
+- `name` - Plugin name
+
+##### `disablePlugin(name: string): void`
+
+Disables a registered plugin.
+
+**Parameters:**
+
+- `name` - Plugin name
+
+##### `executeBeforeGeneration(context: GenerationContext): Promise<void>`
+
+Executes before generation hooks for all enabled plugins.
+
+**Parameters:**
+
+- `context` - Generation context
+
+**Returns:** `Promise<void>`
+
+##### `executeAfterGeneration(context: GenerationContext, result: GenerationResult): Promise<void>`
+
+Executes after generation hooks for all enabled plugins.
+
+**Parameters:**
+
+- `context` - Generation context
+- `result` - Generation result
+
+**Returns:** `Promise<void>`
+
+### PluginLoader
+
+Loads plugins from various sources.
+
+```typescript
+import { PluginLoader } from "schemantic";
+
+const loader = new PluginLoader();
+```
+
+#### Methods
+
+##### `loadPluginFromFile(filePath: string): Promise<SchemanticPlugin>`
+
+Loads a plugin from a file.
+
+**Parameters:**
+
+- `filePath` - Path to plugin file
+
+**Returns:** `Promise<SchemanticPlugin>`
+
+##### `loadPluginFromPackage(packageName: string): Promise<SchemanticPlugin>`
+
+Loads a plugin from an npm package.
+
+**Parameters:**
+
+- `packageName` - Package name
+
+**Returns:** `Promise<SchemanticPlugin>`
+
+##### `loadPluginsFromDirectory(directoryPath: string): Promise<SchemanticPlugin[]>`
+
+Loads all plugins from a directory.
+
+**Parameters:**
+
+- `directoryPath` - Directory path
+
+**Returns:** `Promise<SchemanticPlugin[]>`
+
+### SchemanticPlugin
+
+Plugin interface for extending Schemantic functionality.
+
+```typescript
+interface SchemanticPlugin {
+  name: string;
+  version: string;
+  description: string;
+
+  // Lifecycle hooks
+  beforeGeneration?(context: GenerationContext): Promise<void> | void;
+  afterGeneration?(
+    context: GenerationContext,
+    result: GenerationResult
+  ): Promise<void> | void;
+
+  // Type generation hooks
+  beforeTypeGeneration?(
+    typeName: string,
+    schema: ResolvedSchema,
+    context: GenerationContext
+  ): Promise<void> | void;
+  afterTypeGeneration?(
+    typeName: string,
+    generatedType: GeneratedType,
+    context: GenerationContext
+  ): Promise<void> | void;
+
+  // Client generation hooks
+  beforeClientGeneration?(context: GenerationContext): Promise<void> | void;
+  afterClientGeneration?(
+    generatedClient: GeneratedApiClient,
+    context: GenerationContext
+  ): Promise<void> | void;
+
+  // Schema transformation hooks
+  transformSchema?(
+    schema: ResolvedSchema,
+    context: GenerationContext
+  ): ResolvedSchema;
+
+  // Custom generators
+  customTypeGenerators?: Record<
+    string,
+    (schema: ResolvedSchema, context: GenerationContext) => GeneratedType
+  >;
+  customClientGenerators?: Record<
+    string,
+    (context: GenerationContext) => GeneratedApiClient
+  >;
+}
+```
+
+## Type Definitions
+
+### GeneratedType
+
+Represents a generated TypeScript type.
+
+```typescript
+interface GeneratedType {
+  name: string;
+  content: string;
+  dependencies: string[];
+  exports: string[];
+  isInterface: boolean;
+  isEnum: boolean;
+  isUnion: boolean;
+  sourceSchema: ResolvedSchema;
+}
+```
+
+### GeneratedApiClient
+
+Represents a generated API client.
+
+```typescript
+interface GeneratedApiClient {
+  name: string;
+  content: string;
+  dependencies: string[];
+  exports: string[];
+  endpoints: GeneratedEndpoint[];
+}
+```
+
+### GeneratedEndpoint
+
+Represents a generated API endpoint.
+
+```typescript
+interface GeneratedEndpoint {
+  operationId: string;
+  method: string;
+  path: string;
+  parameters: GeneratedParameter[];
+  requestBody?: GeneratedRequestBody;
+  responses: GeneratedResponse[];
+  returnType: string;
+  functionName: string;
+}
+```
+
+### GenerationResult
+
+Result of the generation process.
+
+```typescript
+interface GenerationResult {
+  success: boolean;
+  generatedFiles: GeneratedFile[];
+  errors: GenerationError[];
+  warnings: GenerationWarning[];
+  statistics: GenerationStatistics;
+}
+```
+
+### GenerationContext
+
+Context passed to plugins and generators.
+
+```typescript
+interface GenerationContext {
+  config: SchemanticConfig;
+  schema: OpenAPISchema;
+  resolvedSchemas: Map<string, ResolvedSchema>;
+  generatedTypes: Map<string, GeneratedType>;
+  generatedClients: Map<string, GeneratedApiClient>;
+  typeRegistry: TypeRegistry;
+  schemaResolver: SchemaResolver;
+}
+```
+
+## Error Handling
+
+### GenerationError
+
+Represents an error during generation.
+
+```typescript
+interface GenerationError {
+  code: string;
+  message: string;
+  source?: string;
+  line?: number;
+  column?: number;
+  severity: "error" | "warning";
+}
+```
+
+### GenerationWarning
+
+Represents a warning during generation.
+
+```typescript
+interface GenerationWarning {
+  code: string;
+  message: string;
+  source?: string;
+  suggestion?: string;
+}
+```
+
+## Utility Functions
+
+### Built-in Plugins
+
+```typescript
+import { getBuiltinPlugins, getBuiltinPlugin } from "schemantic";
+
+// Get all built-in plugins
+const plugins = getBuiltinPlugins();
+
+// Get specific built-in plugin
+const jsdocPlugin = getBuiltinPlugin("jsdoc");
+```
+
+### Convenience Functions
+
+```typescript
+import {
+  createParser,
+  autoCreateParser,
+  createGenerators,
+  generateType,
+} from "schemantic";
+
+// Create parser
+const parser = createParser("openapi", config);
+
+// Auto-create parser
+const autoParser = autoCreateParser(input, config);
+
+// Create generators
+const generators = createGenerators(config);
+
+// Generate type
+const type = generateType(schema, context, generators);
+```