0
# Arrow Annotations
1

2
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.
3

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

6
## Package Information
7

8
- **Package Name**: arrow-annotations
9
- **Package Type**: maven
10
- **Language**: Kotlin Multiplatform
11
- **Installation**: `implementation("io.arrow-kt:arrow-annotations:2.1.2")`
12

13
## Core Imports
14

15
```kotlin
16
import arrow.optics.optics
17
import arrow.optics.OpticsTarget
18
import arrow.synthetic
19
```
20

21
## Basic Usage
22

23
```kotlin
24
import arrow.optics.optics
25
import arrow.optics.OpticsTarget
26
import arrow.synthetic
27

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

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

36
// Mark synthetic/generated code
37
@synthetic
38
class GeneratedHelper
39
```
40

41
## Capabilities
42

43
### Optics Code Generation
44

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

47
```kotlin { .api }
48
/**
49
 * Annotation for generating optics code (ISO, LENS, PRISM, OPTIONAL, DSL).
50
 * Empty array means "Everything that matches annotated class"
51
 * 
52
 * @param targets Array of OpticsTarget specifying which optics to generate
53
 */
54
@Retention(AnnotationRetention.SOURCE)
55
@Target(AnnotationTarget.CLASS)
56
public annotation class optics(val targets: Array<OpticsTarget> = emptyArray())
57
```
58

59
**Usage Examples:**
60

61
```kotlin
62
// Generate all applicable optics
63
@optics
64
data class Person(val name: String, val address: Address)
65

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

70
// Generate lens and prism optics for sealed class hierarchy
71
@optics([OpticsTarget.LENS, OpticsTarget.PRISM])
72
sealed class Result<T> {
73
    data class Success<T>(val value: T) : Result<T>()
74
    data class Error<T>(val message: String) : Result<T>()
75
}
76
```
77

78
### Optics Target Types
79

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

82
```kotlin { .api }
83
/**
84
 * Defines the types of optics that can be generated
85
 */
86
public enum class OpticsTarget {
87
    /** Isomorphism optics - bidirectional transformations between equivalent types */
88
    ISO,
89
    /** Lens optics - focus on a specific field of a product type */
90
    LENS,
91
    /** Prism optics - focus on a specific case of a sum type */
92
    PRISM,
93
    /** Optional optics - lens that might fail to focus */
94
    OPTIONAL,
95
    /** Domain-specific language generation for optics composition */
96
    DSL
97
}
98
```
99

100
### Synthetic Code Marking
101

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

104
```kotlin { .api }
105
/**
106
 * Marks synthetic code elements generated by Arrow's code generation tools
107
 * or other automated processes. Retained at runtime for reflection and tooling.
108
 */
109
@Retention(AnnotationRetention.RUNTIME)
110
@Target(
111
    AnnotationTarget.CLASS,
112
    AnnotationTarget.ANNOTATION_CLASS,
113
    AnnotationTarget.TYPE_PARAMETER,
114
    AnnotationTarget.PROPERTY,
115
    AnnotationTarget.FIELD,
116
    AnnotationTarget.LOCAL_VARIABLE,
117
    AnnotationTarget.VALUE_PARAMETER,
118
    AnnotationTarget.CONSTRUCTOR,
119
    AnnotationTarget.FUNCTION,
120
    AnnotationTarget.PROPERTY_GETTER,
121
    AnnotationTarget.PROPERTY_SETTER,
122
    AnnotationTarget.TYPE,
123
    AnnotationTarget.FILE,
124
    AnnotationTarget.TYPEALIAS
125
)
126
@MustBeDocumented
127
public annotation class synthetic
128
```
129

130
**Usage Examples:**
131

132
```kotlin
133
// Mark generated classes
134
@synthetic
135
class UserOptics
136

137
// Mark generated functions
138
@synthetic
139
fun generatedHelper() { }
140

141
// Mark generated properties
142
@synthetic
143
val computedValue: String = ""
144

145
// Mark generated type aliases
146
@synthetic
147
typealias GeneratedType = String
148
```
149

150
## Error Handling
151

152
The annotations themselves do not throw exceptions. However:
153

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