ts-class-to-openapi 1.0.0

package/dist/transformer.d.ts

@@ -0,0 +1,329 @@
+import { type SchemaType } from './types.js';
+/**
+ * Configuration options for SchemaTransformer memory management
+ */
+interface TransformerOptions {
+    /** Maximum number of schemas to cache before cleanup (default: 100) */
+    maxCacheSize?: number;
+    /** Whether to automatically clean up cache (default: true) */
+    autoCleanup?: boolean;
+}
+/**
+ * Transforms class-validator decorated classes into OpenAPI schema objects.
+ * Analyzes TypeScript source files directly using the TypeScript compiler API.
+ * Implemented as a singleton for performance optimization.
+ *
+ * @example
+ * ```typescript
+ * const transformer = SchemaTransformer.getInstance();
+ * const schema = transformer.transform(User);
+ * console.log(schema);
+ * ```
+ *
+ * @public
+ */
+declare class SchemaTransformer {
+    /**
+     * Singleton instance
+     * @private
+     */
+    private static instance;
+    /**
+     * TypeScript program instance for analyzing source files.
+     * @private
+     */
+    private program;
+    /**
+     * TypeScript type checker for resolving types.
+     * @private
+     */
+    private checker;
+    /**
+     * Cache for storing transformed class schemas to avoid reprocessing.
+     * Key format: "fileName:className" for uniqueness across different files.
+     * @private
+     */
+    private classCache;
+    /**
+     * Maximum number of entries to keep in cache before cleanup
+     * @private
+     */
+    private readonly maxCacheSize;
+    /**
+     * Whether to automatically clean up cache
+     * @private
+     */
+    private readonly autoCleanup;
+    /**
+     * Set of file paths that have been loaded to avoid redundant processing
+     * @private
+     */
+    private loadedFiles;
+    /**
+     * Private constructor for singleton pattern.
+     *
+     * @param tsConfigPath - Optional path to a specific TypeScript config file
+     * @param options - Configuration options for memory management
+     * @throws {Error} When TypeScript configuration cannot be loaded
+     * @private
+     */
+    private constructor();
+    /**
+     * Generates a unique cache key using file name and class name.
+     *
+     * @param fileName - The source file name
+     * @param className - The class name
+     * @returns Unique cache key in format "fileName:className"
+     * @private
+     */
+    private getCacheKey;
+    /**
+     * Cleans up cache when it exceeds maximum size to prevent memory leaks.
+     * Removes oldest entries using LRU strategy.
+     * @private
+     */
+    private cleanupCache;
+    /**
+     * Gets relevant source files for a class, filtering out unnecessary files to save memory.
+     *
+     * @param className - The name of the class to find files for
+     * @param filePath - Optional specific file path
+     * @returns Array of relevant source files
+     * @private
+     */
+    private getRelevantSourceFiles;
+    /**
+     * Transforms a class by its name into an OpenAPI schema object.
+     *
+     * @param className - The name of the class to transform
+     * @param filePath - Optional path to the file containing the class
+     * @returns Object containing the class name and its corresponding JSON schema
+     * @throws {Error} When the specified class cannot be found
+     * @private
+     */
+    private transformByName;
+    /**
+     * Gets the singleton instance of SchemaTransformer.
+     *
+     * @param tsConfigPath - Optional path to a specific TypeScript config file (only used on first call)
+     * @param options - Configuration options for memory management (only used on first call)
+     * @returns The singleton instance
+     *
+     * @example
+     * ```typescript
+     * const transformer = SchemaTransformer.getInstance();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With memory optimization options
+     * const transformer = SchemaTransformer.getInstance('./tsconfig.json', {
+     *   maxCacheSize: 50,
+     *   autoCleanup: true
+     * });
+     * ```
+     *
+     * @public
+     */
+    /**
+     * Clears the current singleton instance. Useful for testing or when you need
+     * to create a new instance with different configuration.
+     */
+    static clearInstance(): void;
+    static getInstance(tsConfigPath?: string, options?: TransformerOptions): SchemaTransformer;
+    /**
+     * Transforms a class constructor function into an OpenAPI schema object.
+     *
+     * @param cls - The class constructor function to transform
+     * @returns Object containing the class name and its corresponding JSON schema
+     *
+     * @example
+     * ```typescript
+     * import { User } from './entities/user.js';
+     * const transformer = SchemaTransformer.getInstance();
+     * const schema = transformer.transform(User);
+     * ```
+     *
+     * @public
+     */
+    transform(cls: Function): {
+        name: string;
+        schema: SchemaType;
+    };
+    /**
+     * Clears all cached schemas and loaded file references to free memory.
+     * Useful for long-running applications or when processing many different classes.
+     *
+     * @example
+     * ```typescript
+     * const transformer = SchemaTransformer.getInstance();
+     * // After processing many classes...
+     * transformer.clearCache();
+     * ```
+     *
+     * @public
+     */
+    clearCache(): void;
+    /**
+     * Gets memory usage statistics for monitoring and debugging.
+     *
+     * @returns Object containing cache size and loaded files count
+     *
+     * @example
+     * ```typescript
+     * const transformer = SchemaTransformer.getInstance();
+     * const stats = transformer.getMemoryStats();
+     * console.log(`Cache entries: ${stats.cacheSize}, Files loaded: ${stats.loadedFiles}`);
+     * ```
+     *
+     * @public
+     */
+    getMemoryStats(): {
+        cacheSize: number;
+        loadedFiles: number;
+    };
+    /**
+     * Finds a class declaration by name within a source file.
+     *
+     * @param sourceFile - The TypeScript source file to search in
+     * @param className - The name of the class to find
+     * @returns The class declaration node if found, undefined otherwise
+     * @private
+     */
+    private findClassByName;
+    /**
+     * Transforms a TypeScript class declaration into a schema object.
+     *
+     * @param classNode - The TypeScript class declaration node
+     * @returns Object containing class name and generated schema
+     * @private
+     */
+    private transformClass;
+    /**
+     * Extracts property information from a class declaration.
+     *
+     * @param classNode - The TypeScript class declaration node
+     * @returns Array of property information including names, types, decorators, and optional status
+     * @private
+     */
+    private extractProperties;
+    /**
+     * Gets the TypeScript type of a property as a string.
+     *
+     * @param property - The property declaration to analyze
+     * @returns String representation of the property's type
+     * @private
+     */
+    private getPropertyType;
+    /**
+     * Converts a TypeScript type node to its string representation.
+     *
+     * @param typeNode - The TypeScript type node to convert
+     * @returns String representation of the type
+     * @private
+     */
+    private getTypeNodeToString;
+    /**
+     * Extracts decorator information from a property declaration.
+     *
+     * @param member - The property declaration to analyze
+     * @returns Array of decorator information including names and arguments
+     * @private
+     */
+    private extractDecorators;
+    /**
+     * Gets the name of a decorator from a call expression.
+     *
+     * @param callExpression - The decorator call expression
+     * @returns The decorator name or "unknown" if not identifiable
+     * @private
+     */
+    private getDecoratorName;
+    /**
+     * Extracts arguments from a decorator call expression.
+     *
+     * @param callExpression - The decorator call expression
+     * @returns Array of parsed decorator arguments
+     * @private
+     */
+    private getDecoratorArguments;
+    /**
+     * Generates an OpenAPI schema from extracted property information.
+     *
+     * @param properties - Array of property information to process
+     * @returns Complete OpenAPI schema object with properties and validation rules
+     * @private
+     */
+    private generateSchema;
+    /**
+     * Maps TypeScript types to OpenAPI schema types and formats.
+     * Handles primitive types, arrays, and nested objects recursively.
+     *
+     * @param type - The TypeScript type string to map
+     * @returns Object containing OpenAPI type, optional format, and nested schema
+     * @private
+     */
+    private mapTypeToSchema;
+    /**
+     * Applies class-validator decorators to schema properties.
+     * Maps validation decorators to their corresponding OpenAPI schema constraints.
+     *
+     * @param decorators - Array of decorator information to apply
+     * @param schema - The schema object to modify
+     * @param propertyName - Name of the property being processed
+     * @private
+     */
+    private applyDecorators;
+    /**
+     * Applies sensible default behaviors for properties without class-validator decorators.
+     * This allows the schema generator to work with plain TypeScript classes.
+     *
+     * @param property - The property information
+     * @param schema - The schema object to modify
+     * @private
+     */
+    private applySensibleDefaults;
+    /**
+     * Determines if a property should be required based on decorators and optional status.
+     *
+     * Logic:
+     * - If property has IsNotEmpty or ArrayNotEmpty decorator, it's required (handled in applyDecorators)
+     * - Otherwise, the property is not required (preserving original behavior)
+     * - The isOptional information is stored for future use and documentation
+     *
+     * @param property - The property information
+     * @param schema - The schema object to modify
+     * @private
+     */
+    private determineRequiredStatus;
+}
+/**
+ * Convenience function to transform a class using the singleton instance.
+ *
+ * @param cls - The class constructor function to transform
+ * @param options - Optional configuration for memory management
+ * @returns Object containing the class name and its corresponding JSON schema
+ *
+ * @example
+ * ```typescript
+ * import { transform } from 'class-validator-to-open-api'
+ * import { User } from './entities/user.js'
+ *
+ * const schema = transform(User)
+ * console.log(schema)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With memory optimization
+ * const schema = transform(User, { maxCacheSize: 50, autoCleanup: true })
+ * ```
+ *
+ * @public
+ */
+export declare function transform<T>(cls: new (...args: any[]) => T, options?: TransformerOptions): {
+    name: string;
+    schema: SchemaType;
+};
+export type { TransformerOptions };
+export { SchemaTransformer };

package/dist/transformer.fixtures.d.ts

@@ -0,0 +1,143 @@
+declare const messages: {
+    errors: {
+        tsconfigNotFound: (path: string) => string;
+        classNotFound: (className: string) => string;
+        fileNotFound: (filePath: string) => string;
+    };
+};
+declare const constants: {
+    TS_CONFIG_DEFAULT_PATH: string;
+    jsPrimitives: {
+        String: {
+            type: string;
+            value: string;
+        };
+        Number: {
+            type: string;
+            value: string;
+        };
+        Boolean: {
+            type: string;
+            value: string;
+        };
+        Symbol: {
+            type: string;
+            value: string;
+        };
+        BigInt: {
+            type: string;
+            value: string;
+        };
+        null: {
+            type: string;
+            value: string;
+        };
+        Object: {
+            type: string;
+            value: string;
+        };
+        Array: {
+            type: string;
+            value: string;
+        };
+        Date: {
+            type: string;
+            value: string;
+            format: string;
+        };
+        Function: {
+            type: string;
+            value: string;
+        };
+        Buffer: {
+            type: string;
+            value: string;
+            format: string;
+        };
+        Uint8Array: {
+            type: string;
+            value: string;
+            format: string;
+        };
+        UploadFile: {
+            type: string;
+            value: string;
+            format: string;
+        };
+        File: {
+            type: string;
+            value: string;
+            format: string;
+        };
+    };
+    validatorDecorators: {
+        Length: {
+            name: string;
+            type: string;
+        };
+        MinLength: {
+            name: string;
+            type: string;
+        };
+        MaxLength: {
+            name: string;
+            type: string;
+        };
+        IsInt: {
+            name: string;
+            type: string;
+            format: string;
+        };
+        IsNumber: {
+            name: string;
+            type: string;
+            format: string;
+        };
+        IsString: {
+            name: string;
+            type: string;
+            format: string;
+        };
+        IsPositive: {
+            name: string;
+            type: string;
+        };
+        IsDate: {
+            name: string;
+            type: string;
+            format: string;
+        };
+        IsEmail: {
+            name: string;
+            type: string;
+            format: string;
+        };
+        IsNotEmpty: {
+            name: string;
+        };
+        IsBoolean: {
+            name: string;
+            type: string;
+        };
+        IsArray: {
+            name: string;
+            type: string;
+        };
+        Min: {
+            name: string;
+        };
+        Max: {
+            name: string;
+        };
+        ArrayNotEmpty: {
+            name: string;
+        };
+        ArrayMaxSize: {
+            name: string;
+        };
+        ArrayMinSize: {
+            name: string;
+        };
+    };
+};
+export { messages, constants };

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+type Property = {
+    [key: string]: any;
+} & {
+    type: string;
+};
+type SchemaType = {
+    [key: string]: any;
+} & {
+    properties: {
+        [key: string]: any;
+    };
+} & {
+    required: string[];
+} & {
+    type: string;
+};
+/**
+ * Information about a class-validator decorator found on a property.
+ * @interface DecoratorInfo
+ */
+interface DecoratorInfo {
+    /** The name of the decorator (e.g., "IsString", "MinLength") */
+    name: string;
+    /** Arguments passed to the decorator */
+    arguments: any[];
+}
+/**
+ * Information about a class property including its type and decorators.
+ * @interface PropertyInfo
+ */
+interface PropertyInfo {
+    /** The name of the property */
+    name: string;
+    /** The TypeScript type of the property as a string */
+    type: string;
+    /** Array of decorators applied to this property */
+    decorators: DecoratorInfo[];
+    /** Whether the property is optional (has ? operator) */
+    isOptional: boolean;
+}
+export { type SchemaType, type Property, type DecoratorInfo, type PropertyInfo };

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "ts-class-to-openapi",
+  "version": "1.0.0",
+  "description": "Transform TypeScript classes into OpenAPI 3.1.0 schema objects, which support class-validator decorators",
+  "main": "./dist/index.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "typings": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julioolivares/ts-class-to-openapi.git"
+  },
+  "keywords": [
+    "ts-class-to-openapi",
+    "typescript-to-openapi",
+    "class-validator",
+    "openapi",
+    "swagger",
+    "typescript",
+    "validation",
+    "schema",
+    "api",
+    "dto",
+    "nestjs",
+    "express",
+    "decorators",
+    "transform",
+    "json-schema",
+    "rest-api",
+    "documentation"
+  ],
+  "author": "Julio Olivares",
+  "homepage": "https://github.com/julioolivares/ts-class-to-openapi#readme",
+  "bugs": {
+    "url": "https://github.com/julioolivares/ts-class-to-openapi/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=8.0.0"
+  },
+  "engineStrict": true,
+  "peerDependencies": {
+    "class-validator": "0.14.0"
+  },
+  "peerDependenciesMeta": {
+    "class-validator": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "typescript": "5.0.2"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "12.1.4",
+    "@types/node": "24.2.1",
+    "class-validator": "0.14.2",
+    "glob": "10.3.10",
+    "prettier": "3.6.2",
+    "rollup": "4.46.2",
+    "tslib": "2.8.1"
+  },
+  "package": "./package-dist.json",
+  "scripts": {
+    "test": "npm run build:test && node --test dist/test.js",
+    "test:watch": "npm run build:test && node --test --watch dist/**/*.test.js",
+    "test:coverage": "npm run build:test && node --test --experimental-test-coverage dist/**/*.test.js",
+    "build": "rm -rf dist && rollup -c",
+    "build:test": "rm -rf dist && BUILD_TARGET=test rollup -c",
+    "build:watch": "rm -rf dist && rollup -c -w",
+    "dev": "node --trace-deprecation  --watch dist/run.js",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublish": "pnpm run build"
+  }
+}