type-safe kotlin source file generation via hierarchical builder pattern
Generates complete .kt source files programmatically using a composition-based builder pattern where FileSpec acts as the root container, with nested builders for TypeSpec (classes/interfaces/objects), FunSpec (functions), PropertySpec (properties), and ParameterSpec (parameters). The API mirrors Kotlin's syntactic structure directly, allowing developers to construct code hierarchically without string concatenation or template engines. Each Spec class has a corresponding Builder that enforces type safety at compile time.
Unique: Uses a hierarchical Spec class composition pattern (FileSpec → TypeSpec → FunSpec → PropertySpec → ParameterSpec) that directly mirrors Kotlin's syntactic structure, enabling compile-time type safety without runtime reflection or string templates. This is distinct from template-based generators because the entire code structure is validated at build time through the type system.
vs alternatives: Provides stronger type safety than string-based template engines (like Velocity or FreeMarker) and more Kotlin-idiomatic API than JavaPoet, though with slightly more verbose construction for simple cases.
polymorphic type representation with generics, lambdas, and variance support
Represents all Kotlin type references through a TypeName class hierarchy (ClassName, ParameterizedTypeName, WildcardTypeName, TypeVariableName, LambdaTypeName) that captures generics, type parameters, variance modifiers (in/out), and lambda signatures. The type system allows composing complex types like Map<String, (Int) -> Boolean> by nesting TypeName instances, with built-in support for nullable types, platform types, and Kotlin-specific constructs. Type names are immutable and can be reused across multiple code generation contexts.
Unique: Implements a complete TypeName hierarchy that captures Kotlin's full type system including LambdaTypeName for function types with explicit parameter and return types, WildcardTypeName for bounded generics, and TypeVariableName for type parameters with bounds. This enables precise representation of complex generic signatures that would be ambiguous in string-based approaches.
vs alternatives: More expressive than JavaPoet's type system because it includes first-class lambda type representation and Kotlin-specific nullable type handling, making it suitable for modern functional Kotlin APIs.
import statement management and package-aware code generation
Automatically manages import statements and package declarations in generated .kt files, resolving type references to their fully qualified names and generating appropriate imports. The system tracks which types are used in the generated code and generates import statements only for types that are actually referenced, avoiding unused imports. It also handles package-local types and star imports intelligently.
Unique: Automatically tracks type usage and generates minimal import statements without manual intervention, using the TypeName system to resolve fully qualified names and determine which imports are necessary. This is distinct from template-based approaches because it analyzes the actual code structure to determine imports.
vs alternatives: More maintainable than manual import management; cleaner output than generators that produce star imports or unused imports.
modifier and annotation application to generated declarations
Applies Kotlin modifiers (public, private, internal, protected, abstract, final, open, sealed, data, inline, etc.) and annotations to generated types, functions, properties, and parameters. The API provides type-safe methods for adding modifiers and annotations, with validation to prevent invalid modifier combinations (e.g., abstract and final). Annotations can include parameters and are properly formatted in the generated code.
Unique: Provides type-safe modifier and annotation application through KModifier enums and AnnotationSpec builders, preventing invalid modifier combinations at generation time. This is more robust than string-based approaches because the API enforces Kotlin's modifier rules.
vs alternatives: More type-safe than string-based modifier application; prevents invalid modifier combinations that would cause compilation errors.
file i/o and code output with customizable destination handling
Writes generated .kt files to the filesystem or arbitrary Appendable destinations (StringBuilders, Writers, etc.) with support for directory creation and file overwriting. The FileSpec.writeTo() method handles path resolution, file creation, and encoding, while toString() provides in-memory code generation. The system supports writing to standard file paths or custom output directories, making it suitable for both build-time code generation and runtime code inspection.
Unique: Provides both filesystem-based (writeTo) and in-memory (toString) code output, with automatic handling of package-based directory structure and file creation. This dual approach enables both build-time code generation and runtime code inspection without separate implementations.
vs alternatives: More flexible than generators that only support filesystem output; supports custom Appendable destinations for integration with non-standard build systems.
code block formatting with placeholder interpolation and smart indentation
Generates code blocks using a CodeBlock class that accepts format strings with named placeholders (%L for literals, %S for strings, %T for types, %N for names) that are substituted with properly escaped and formatted values. The system automatically handles indentation levels, line breaks, and spacing rules specific to Kotlin syntax. Code blocks can be nested within other code blocks, and the formatter maintains consistent indentation across multi-line constructs like function bodies, class definitions, and control flow statements.
Unique: Uses a format-string-based placeholder system (%L, %S, %T, %N, %M) that prevents injection attacks and formatting errors by separating code structure from interpolated values. The formatter automatically handles Kotlin-specific spacing rules (e.g., space before opening braces, no space before colons in type annotations) without manual string manipulation.
vs alternatives: Safer than string concatenation or simple template engines because placeholders enforce type-aware escaping; more flexible than rigid AST-based approaches because it allows arbitrary code expressions through %L (literal) placeholders.
annotation processing integration with ksp (kotlin symbol processing)
Integrates with Kotlin Symbol Processing (KSP) to read type information, annotations, and metadata from source code during compilation, enabling code generators to inspect existing Kotlin declarations and generate corresponding code. The integration allows KSP processors to use KotlinPoet's builder API to generate new .kt files based on analyzed symbols, with automatic handling of package names, import statements, and type resolution. KSP provides symbol information (KSClassDeclaration, KSFunctionDeclaration, etc.) that can be converted to KotlinPoet TypeName and other Spec objects.
Unique: Provides direct integration with KSP's symbol model, allowing processors to convert KSClassDeclaration and other KS* types into KotlinPoet Spec objects without manual type name extraction. This integration is tighter than generic code generation because it preserves type resolution context and handles Kotlin-specific metadata (e.g., data class properties, extension functions).
vs alternatives: Faster and more maintainable than KAPT-based annotation processors because KSP is incremental and doesn't require Java reflection; more type-safe than manual string-based code generation from KSP symbols.
kotlin metadata reflection for runtime type inspection
Integrates with Kotlin's reflection API and kotlinx-metadata library to inspect runtime type information from compiled Kotlin classes, including data class properties, extension functions, and generic type parameters. This capability allows code generators to read metadata from already-compiled Kotlin libraries and generate corresponding code (e.g., serializers, builders, copy functions). The integration handles the impedance mismatch between Kotlin's compile-time type system and Java's runtime type information.
Unique: Bridges Kotlin's compile-time metadata (preserved in .class files) with runtime code generation by parsing kotlinx-metadata structures and converting them to KotlinPoet Spec objects. This enables code generators to work with already-compiled Kotlin libraries without requiring source code or KSP processors.
vs alternatives: More practical than compile-time-only approaches for library code that needs to generate code from external dependencies; more type-safe than Java reflection because it preserves Kotlin-specific information like data class properties and extension functions.
+5 more capabilities