0
# uPickle
1

2
uPickle is a lightweight JSON and MessagePack serialization library for Scala that provides simple, human-readable serialization with extensive customization options. It supports Scala 2.12, 2.13, and 3.x with cross-compilation for JVM, JavaScript (ScalaJS), and Native platforms, offering automatic derivation for case classes and sealed traits while maintaining superior performance.
3

4
## Package Information
5

6
- **Package Name**: upickle_3
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Maven Coordinates**: `"com.lihaoyi" %% "upickle" % "4.1.0"`
10
- **SBT Installation**: `libraryDependencies += "com.lihaoyi" %% "upickle" % "4.1.0"`
11

12
## Core Imports
13

14
```scala
15
import upickle.default._
16
```
17

18
For custom behavior:
19

20
```scala
21
import upickle.{Api, AttributeTagged, legacy}
22
```
23

24
For core types:
25

26
```scala
27
import upickle.core.{Reader, Writer, ReadWriter}
28
```
29

30
For direct ujson operations:
31

32
```scala
33
import ujson._
34
```
35

36
For direct upack operations:
37

38
```scala
39
import upack._
40
```
41

42
For Scala.js web APIs:
43

44
```scala
45
import upickle.web._  // Scala.js only
46
```
47

48
## Basic Usage
49

50
```scala
51
import upickle.default._
52

53
// Case class serialization
54
case class Person(name: String, age: Int)
55
val person = Person("Alice", 30)
56

57
// JSON serialization
58
val json = write(person)
59
// Result: {"name":"Alice","age":30}
60

61
// JSON deserialization
62
val parsed = read[Person](json)
63
// Result: Person("Alice", 30)
64

65
// MessagePack binary serialization
66
val binary = writeBinary(person)
67
val parsedBinary = readBinary[Person](binary)
68

69
// Collection handling
70
val people = List(Person("Alice", 30), Person("Bob", 25))
71
val jsonArray = write(people)
72
val parsedArray = read[List[Person]](jsonArray)
73
```
74

75
## Architecture
76

77
uPickle is built around several key components:
78

79
- **Type Classes**: `Reader[T]`, `Writer[T]`, and `ReadWriter[T]` for serialization behavior definition
80
- **Visitor Pattern**: Core abstraction for traversing structured data (JSON, MessagePack, Scala objects)
81
- **Default API**: `upickle.default` provides automatic derivation for most types
82
- **Custom APIs**: `upickle.legacy` and trait extensions for specialized behavior
83
- **Format Support**: Unified interface for JSON and MessagePack with format-specific optimizations
84
- **Macro Derivation**: Automatic Reader/Writer generation for case classes and sealed traits
85
- **Direct Module APIs**: `ujson` and `upack` modules provide direct JSON/MessagePack processing utilities
86
- **Platform Support**: Cross-platform compatibility with specialized APIs for Scala.js, JVM, and Native
87

88
## Capabilities
89

90
### Core Serialization API
91

92
Primary read/write functions for JSON and binary formats, with streaming and configuration options.
93

94
```scala { .api }
95
def read[T: Reader](s: ujson.Readable, trace: Boolean = false): T
96
def write[T: Writer](t: T, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): String
97
def readBinary[T: Reader](s: upack.Readable, trace: Boolean = false): T  
98
def writeBinary[T: Writer](t: T, sortKeys: Boolean = false): Array[Byte]
99
```
100

101
[Core Serialization](./core-serialization.md)
102

103
### Type Classes System
104

105
Reader, Writer, and ReadWriter type classes that define serialization behavior for types.
106

107
```scala { .api }
108
trait Reader[T] extends Visitor[Any, T]
109
trait Writer[T] extends Transformer[T]
110
trait ReadWriter[T] extends Reader[T] with Writer[T]
111

112
def reader[T: Reader]: Reader[T]
113
def writer[T: Writer]: Writer[T] 
114
def readwriter[T: ReadWriter]: ReadWriter[T]
115
```
116

117
[Type Classes](./type-classes.md)
118

119
### Built-in Type Support
120

121
Comprehensive built-in readers and writers for primitive and collection types.
122

123
```scala { .api }
124
implicit val StringReader: Reader[String]
125
implicit val IntReader: Reader[Int]
126
implicit val BooleanReader: Reader[Boolean]
127
implicit def OptionReader[T: Reader]: Reader[Option[T]]
128
implicit def ArrayReader[T: Reader: ClassTag]: Reader[Array[T]]
129
implicit def MapReader[K: Reader, V: Reader]: Reader[Map[K, V]]
130
```
131

132
[Built-in Types](./builtin-types.md)
133

134
### JSON Integration
135

136
Direct integration with ujson for working with JSON AST and value types.
137

138
```scala { .api }
139
def writeJs[T: Writer](t: T): ujson.Value
140
implicit def JsValueR: Reader[ujson.Value]
141
implicit def JsValueW: Writer[ujson.Value]
142
```
143

144
[JSON Integration](./json-integration.md)
145

146
### MessagePack Integration  
147

148
Direct integration with upack for binary MessagePack serialization.
149

150
```scala { .api }
151
def writeMsg[T: Writer](t: T): upack.Msg
152
implicit val MsgValueR: Reader[upack.Msg]
153
implicit val MsgValueW: Writer[upack.Msg]
154
```
155

156
[MessagePack Integration](./messagepack-integration.md)
157

158
### Sealed Trait Support
159

160
Automatic tagging and discrimination for sealed trait hierarchies with customizable behavior.
161

162
```scala { .api }
163
trait TaggedReader[T] extends SimpleReader[T]
164
trait TaggedWriter[T] extends Writer[T]
165
trait TaggedReadWriter[T] extends ReadWriter[T] with TaggedReader[T] with TaggedWriter[T]
166
```
167

168
[Sealed Traits](./sealed-traits.md)
169

170
### Streaming and Output
171

172
Functions for writing to streams, OutputStreams, and creating streamable representations.
173

174
```scala { .api }
175
def writeTo[T: Writer](t: T, out: java.io.Writer, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): Unit
176
def stream[T: Writer](t: T, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): geny.Writable
177
def writeBinaryTo[T: Writer](t: T, out: java.io.OutputStream, sortKeys: Boolean = false): Unit
178
```
179

180
[Streaming](./streaming.md)
181

182
## Types
183

184
```scala { .api }
185
trait Api extends upickle.core.Types with implicits.Readers with implicits.Writers with implicits.CaseClassReadWriters
186

187
object default extends AttributeTagged
188

189
object legacy extends LegacyApi
190

191
case class transform[T: Writer](t: T) extends upack.Readable with ujson.Readable
192
```