Annotations

/**
 * Marks a class as serializable, instructing the compiler plugin to generate a KSerializer implementation.
 * @param with Optional custom serializer class to use instead of generated one
 */
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.TYPE)
annotation class Serializable(val with: KClass<out KSerializer<*>> = KSerializer::class)

/**
 * Overrides the name of a class or property in the SerialDescriptor.
 * Used to customize how fields appear in the serialized format.
 * @param value The custom name to use in serialization
 */
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY)  
annotation class SerialName(val value: String)

/**
 * Marks a property as invisible to the entire serialization process.
 * Transient properties are completely ignored during serialization and deserialization.
 */
@Target(AnnotationTarget.PROPERTY)
annotation class Transient

@Serializable
data class User(
    @SerialName("user_name")
    val name: String,
    val email: String,
    @Transient
    val password: String = ""
)

// Serializes as: {"user_name":"Alice","email":"alice@example.com"}
// password field is completely ignored

/**
 * Marks a property as required during deserialization, even if it has a default value.
 * Throws MissingFieldException if the field is not present in input.
 */
@Target(AnnotationTarget.PROPERTY)
annotation class Required

/**
 * Controls whether a property is serialized when its value equals the default value.
 * @param mode Strategy for encoding default values
 */
@Target(AnnotationTarget.PROPERTY)
annotation class EncodeDefault(val mode: Mode = Mode.ALWAYS) {
    enum class Mode {
        /**
         * Configures serializer to always encode the property, even if its value is equal to its default.
         * For annotated properties, format settings are not taken into account.
         */
        ALWAYS,
        
        /**
         * Configures serializer not to encode the property if its value is equal to its default.
         * For annotated properties, format settings are not taken into account.
         */
        NEVER
    }
}

@Serializable
data class Config(
    @Required
    val apiKey: String = "", // Always required, even with default
    
    @EncodeDefault(EncodeDefault.Mode.ALWAYS)
    val timeout: Int = 30,   // Always serialized, even if 30
    
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val debug: Boolean = false // Only serialized if true
)

/**
 * Instructs the plugin to turn the annotated class into a serializer for the specified target class.
 * @param forClass The class this serializer handles
 */
@Target(AnnotationTarget.CLASS)
annotation class Serializer(val forClass: KClass<*>)

/**
 * Instructs the plugin to use ContextualSerializer for the annotated property.
 * The actual serializer is resolved from SerializersModule at runtime.
 */
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.TYPE)
annotation class Contextual

/**
 * Keep the auto-generated KSerializer even when a custom serializer is specified.
 * The generated serializer is available via generatedSerializer() function.
 */
@Target(AnnotationTarget.CLASS)
annotation class KeepGeneratedSerializer

@Serializer(forClass = LocalDate::class)
object LocalDateSerializer : KSerializer<LocalDate> {
    override val descriptor = PrimitiveSerialDescriptor("LocalDate", PrimitiveKind.STRING)
    override fun serialize(encoder: Encoder, value: LocalDate) = encoder.encodeString(value.toString())
    override fun deserialize(decoder: Decoder): LocalDate = LocalDate.parse(decoder.decodeString())
}

@Serializable
data class Event(
    val name: String,
    @Contextual 
    val date: LocalDate  // Resolved from SerializersModule
)

/**
 * Use ContextualSerializer for every type listed in forClasses within the annotated file.
 * @param forClasses Array of classes to treat as contextual
 */
@Target(AnnotationTarget.FILE)
annotation class UseContextualSerialization(vararg val forClasses: KClass<*>)

/**
 * Adds the specified serializer classes to the serialization resolution process for the file.
 * @param serializerClasses Array of serializer classes to register
 */
@Target(AnnotationTarget.FILE)  
annotation class UseSerializers(vararg val serializerClasses: KClass<out KSerializer<*>>)

/**
 * Instructs the plugin to use PolymorphicSerializer for the annotated property or type.
 * Used for polymorphic serialization scenarios.
 */
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.CLASS, AnnotationTarget.TYPE)
annotation class Polymorphic

@file:UseContextualSerialization(LocalDate::class, UUID::class)
@file:UseSerializers(LocalDateSerializer::class, UUIDSerializer::class)

package com.example.models

@Serializable
data class Document(
    val id: UUID,        // Uses UUIDSerializer from file-level config
    val created: LocalDate  // Uses LocalDateSerializer from file-level config
)

/**
 * Meta-annotation for creating custom serialization-specific annotations.
 * Marks an annotation as containing serialization metadata.
 */
@Target(AnnotationTarget.ANNOTATION_CLASS)
annotation class SerialInfo

/**
 * Like SerialInfo but makes the annotation inheritable by subclasses.
 * Useful for creating annotation hierarchies.
 */
@Target(AnnotationTarget.ANNOTATION_CLASS)
annotation class InheritableSerialInfo

/**
 * Meta-annotation that adds Serializable behavior to user-defined annotations.
 * Classes annotated with meta-serializable annotations become serializable.
 */
@Target(AnnotationTarget.ANNOTATION_CLASS)
annotation class MetaSerializable

@SerialInfo
@Target(AnnotationTarget.PROPERTY)
annotation class Since(val version: String)

@InheritableSerialInfo  
@Target(AnnotationTarget.CLASS)
annotation class ApiVersion(val version: Int)

@MetaSerializable
@Target(AnnotationTarget.CLASS)
annotation class JsonSerializable

// Classes with JsonSerializable automatically become @Serializable
@JsonSerializable
data class User(
    @Since("1.0")
    val name: String,
    @Since("1.1") 
    val email: String
)