CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-arrow-kt--arrow-annotations

Annotation definitions for the Arrow functional programming library's optics code generation and synthetic code marking

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Arrow Annotations

Arrow Annotations provides compile-time and runtime annotation definitions used by the Arrow functional programming ecosystem for Kotlin. It enables optics code generation and synthetic code marking, supporting functional programming patterns and type-safe data transformation.

Note: The @optics annotation requires the Arrow KSP plugin (arrow-optics-ksp-plugin) to generate the actual optics code.

Package Information

  • Package Name: arrow-annotations
  • Package Type: maven
  • Language: Kotlin Multiplatform
  • Installation: implementation("io.arrow-kt:arrow-annotations:2.1.2")

Core Imports

import arrow.optics.optics
import arrow.optics.OpticsTarget
import arrow.synthetic

Basic Usage

import arrow.optics.optics
import arrow.optics.OpticsTarget
import arrow.synthetic

// Use @optics to generate optics for data classes
@optics
data class User(val name: String, val age: Int)

// Specify which optics to generate
@optics([OpticsTarget.LENS, OpticsTarget.PRISM])
data class Account(val id: String, val balance: Double)

// Mark synthetic/generated code
@synthetic
class GeneratedHelper

Capabilities

Optics Code Generation

Annotation for generating functional optics code that provides immutable data manipulation capabilities.

/**
 * Annotation for generating optics code (ISO, LENS, PRISM, OPTIONAL, DSL).
 * Empty array means "Everything that matches annotated class"
 * 
 * @param targets Array of OpticsTarget specifying which optics to generate
 */
@Retention(AnnotationRetention.SOURCE)
@Target(AnnotationTarget.CLASS)
public annotation class optics(val targets: Array<OpticsTarget> = emptyArray())

Usage Examples:

// Generate all applicable optics
@optics
data class Person(val name: String, val address: Address)

// Generate only specific optics
@optics([OpticsTarget.LENS])
data class Config(val host: String, val port: Int)

// Generate lens and prism optics for sealed class hierarchy
@optics([OpticsTarget.LENS, OpticsTarget.PRISM])
sealed class Result<T> {
    data class Success<T>(val value: T) : Result<T>()
    data class Error<T>(val message: String) : Result<T>()
}

Optics Target Types

Enumeration defining the types of optics that can be generated for functional data manipulation.

/**
 * Defines the types of optics that can be generated
 */
public enum class OpticsTarget {
    /** Isomorphism optics - bidirectional transformations between equivalent types */
    ISO,
    /** Lens optics - focus on a specific field of a product type */
    LENS,
    /** Prism optics - focus on a specific case of a sum type */
    PRISM,
    /** Optional optics - lens that might fail to focus */
    OPTIONAL,
    /** Domain-specific language generation for optics composition */
    DSL
}

Synthetic Code Marking

Runtime annotation for marking synthetic/generated code elements across all Kotlin language constructs.

/**
 * Marks synthetic code elements generated by Arrow's code generation tools
 * or other automated processes. Retained at runtime for reflection and tooling.
 */
@Retention(AnnotationRetention.RUNTIME)
@Target(
    AnnotationTarget.CLASS,
    AnnotationTarget.ANNOTATION_CLASS,
    AnnotationTarget.TYPE_PARAMETER,
    AnnotationTarget.PROPERTY,
    AnnotationTarget.FIELD,
    AnnotationTarget.LOCAL_VARIABLE,
    AnnotationTarget.VALUE_PARAMETER,
    AnnotationTarget.CONSTRUCTOR,
    AnnotationTarget.FUNCTION,
    AnnotationTarget.PROPERTY_GETTER,
    AnnotationTarget.PROPERTY_SETTER,
    AnnotationTarget.TYPE,
    AnnotationTarget.FILE,
    AnnotationTarget.TYPEALIAS
)
@MustBeDocumented
public annotation class synthetic

Usage Examples:

// Mark generated classes
@synthetic
class UserOptics

// Mark generated functions
@synthetic
fun generatedHelper() { }

// Mark generated properties
@synthetic
val computedValue: String = ""

// Mark generated type aliases
@synthetic
typealias GeneratedType = String

Error Handling

The annotations themselves do not throw exceptions. However:

  • @optics annotation requires proper data class or sealed class structure for successful code generation
  • Code generation failures occur at compile-time, not runtime, when using the KSP plugin
  • @synthetic annotation is purely for marking and does not affect runtime behavior
  • Missing KSP plugin dependency will result in no optics code being generated

docs

index.md

tile.json