0
# Core Serialization
1

2
Primary read/write functions for JSON and binary formats, providing the main entry points for uPickle serialization with configuration options for formatting and behavior.
3

4
## Capabilities
5

6
### JSON Reading
7

8
Reads JSON input into Scala values with optional trace support for debugging.
9

10
```scala { .api }
11
/**
12
 * Reads the given JSON input into a Scala value
13
 * @param s JSON input (string, InputStream, etc.)
14
 * @param trace Enable tracing for debugging serialization issues
15
 * @return Deserialized Scala value of type T
16
 */
17
def read[T: Reader](s: ujson.Readable, trace: Boolean = false): T
18
```
19

20
**Usage Examples:**
21

22
```scala
23
import upickle.default._
24

25
// From string
26
val person = read[Person]("""{"name":"Alice","age":30}""")
27

28
// From file
29
val data = read[List[Int]](os.read(os.pwd / "data.json"))
30

31
// With tracing
32
val traced = read[Person](json, trace = true)
33
```
34

35
### JSON Writing
36

37
Writes Scala values as JSON strings with formatting options.
38

39
```scala { .api }
40
/**
41
 * Write the given Scala value as a JSON string
42
 * @param t Value to serialize
43
 * @param indent Indentation level (-1 for compact, >=0 for pretty printing)
44
 * @param escapeUnicode Whether to escape unicode characters
45
 * @param sortKeys Whether to sort object keys alphabetically
46
 * @return JSON string representation
47
 */
48
def write[T: Writer](t: T, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): String
49
```
50

51
**Usage Examples:**
52

53
```scala
54
import upickle.default._
55

56
val person = Person("Alice", 30)
57

58
// Compact JSON
59
val compact = write(person)
60
// Result: {"name":"Alice","age":30}
61

62
// Pretty-printed JSON
63
val pretty = write(person, indent = 2)
64
// Result:
65
// {
66
//   "name": "Alice",
67
//   "age": 30
68
// }
69

70
// Sorted keys
71
val sorted = write(person, sortKeys = true)
72
```
73

74
### MessagePack Reading
75

76
Reads MessagePack binary input into Scala values.
77

78
```scala { .api }
79
/**
80
 * Reads the given MessagePack input into a Scala value
81
 * @param s MessagePack binary input
82
 * @param trace Enable tracing for debugging
83
 * @return Deserialized Scala value of type T
84
 */
85
def readBinary[T: Reader](s: upack.Readable, trace: Boolean = false): T
86
```
87

88
**Usage Examples:**
89

90
```scala
91
import upickle.default._
92

93
// From byte array
94
val binary: Array[Byte] = getBinaryData()
95
val person = readBinary[Person](binary)
96

97
// From InputStream
98
val stream: InputStream = getInputStream()
99
val data = readBinary[List[Int]](stream)
100
```
101

102
### MessagePack Writing
103

104
Writes Scala values as MessagePack binary data.
105

106
```scala { .api }
107
/**
108
 * Write the given Scala value as a MessagePack binary
109
 * @param t Value to serialize
110
 * @param sortKeys Whether to sort object keys alphabetically
111
 * @return MessagePack byte array
112
 */
113
def writeBinary[T: Writer](t: T, sortKeys: Boolean = false): Array[Byte]
114
```
115

116
**Usage Examples:**
117

118
```scala
119
import upickle.default._
120

121
val person = Person("Alice", 30)
122

123
// Binary serialization
124
val binary = writeBinary(person)
125

126
// With sorted keys
127
val sortedBinary = writeBinary(person, sortKeys = true)
128

129
// Write to file
130
os.write(os.pwd / "data.msgpack", binary)
131
```
132

133
### AST Writing
134

135
Writes Scala values directly to JSON and MessagePack AST types.
136

137
```scala { .api }
138
/**
139
 * Write the given Scala value as a JSON struct
140
 * @param t Value to serialize
141
 * @return ujson.Value representation
142
 */
143
def writeJs[T: Writer](t: T): ujson.Value
144

145
/**
146
 * Write the given Scala value as a MessagePack struct  
147
 * @param t Value to serialize
148
 * @return upack.Msg representation
149
 */
150
def writeMsg[T: Writer](t: T): upack.Msg
151
```
152

153
**Usage Examples:**
154

155
```scala
156
import upickle.default._
157

158
val person = Person("Alice", 30)
159

160
// JSON AST
161
val jsonAst = writeJs(person)
162
// Result: ujson.Obj("name" -> ujson.Str("Alice"), "age" -> ujson.Num(30))
163

164
// MessagePack AST  
165
val msgAst = writeMsg(person)
166
// Result: upack.Obj("name" -> upack.Str("Alice"), "age" -> upack.Int32(30))
167
```
168

169
### Type Class Access
170

171
Direct access to Reader, Writer, and ReadWriter instances.
172

173
```scala { .api }
174
/**
175
 * Gets the Reader typeclass instance for type T
176
 */
177
def reader[T: Reader]: Reader[T]
178

179
/**
180
 * Gets the Writer typeclass instance for type T
181
 */
182
def writer[T: Writer]: Writer[T]
183

184
/**
185
 * Gets the ReadWriter typeclass instance for type T
186
 */
187
def readwriter[T: ReadWriter]: ReadWriter[T]
188
```
189

190
**Usage Examples:**
191

192
```scala
193
import upickle.default._
194

195
// Get type class instances
196
val personReader = reader[Person]
197
val personWriter = writer[Person]
198
val personRW = readwriter[Person]
199

200
// Use directly
201
val person = personReader.transform(ujson.parse(json))
202
val json = personWriter.transform(person, ujson.StringRenderer()).toString
203
```
204

205
### Transform Wrapper
206

207
Wraps values for flexible transformation between formats.
208

209
```scala { .api }
210
/**
211
 * Wraps a value for transformation operations
212
 * @param t Value to wrap
213
 */
214
case class transform[T: Writer](t: T) extends upack.Readable with ujson.Readable {
215
  def transform[V](f: Visitor[_, V]): V
216
  def to[V](f: Visitor[_, V]): V  
217
  def to[V](implicit f: Reader[V]): V
218
}
219
```
220

221
**Usage Examples:**
222

223
```scala
224
import upickle.default._
225

226
val person = Person("Alice", 30)
227

228
// Transform to different formats
229
val jsonValue = transform(person).to[ujson.Value]
230
val msgValue = transform(person).to[upack.Msg]
231
val backToPerson = transform(person).to[Person]
232

233
// Transform with custom visitor
234
val customResult = transform(person).transform(myCustomVisitor)
235
```
236

237
### Platform-Specific APIs
238

239
Web-optimized APIs for Scala.js environments.
240

241
```scala { .api }
242
/**
243
 * Web-optimized JSON reading for Scala.js (import upickle.web._)
244
 * @param s JSON string input
245
 * @return Deserialized Scala value of type T
246
 */
247
def web.read[T: Reader](s: String): T
248

249
/**
250
 * Web-optimized JSON writing for Scala.js (import upickle.web._)
251
 * @param t Value to serialize
252
 * @param indent Indentation level for pretty printing
253
 * @return JSON string representation
254
 */
255
def web.write[T: Writer](t: T, indent: Int = -1): String
256
```
257

258
**Usage Examples:**
259

260
```scala
261
// Scala.js only - optimized for browser environments
262
import upickle.web._
263

264
case class WebData(id: String, timestamp: Double, userAgent: String)
265

266
// Fast JSON operations in browser
267
val webData = WebData("user123", js.Date.now(), window.navigator.userAgent)
268

269
// Optimized serialization for web APIs
270
val json = web.write(webData)
271

272
// Send to server or store in browser
273
localStorage.setItem("userData", json)
274

275
// Read back from browser storage
276
val stored = localStorage.getItem("userData")
277
val parsed = web.read[WebData](stored)
278

279
// Integration with browser APIs
280
def sendToServer(data: WebData): Unit = {
281
  val json = web.write(data)
282
  
283
  // XMLHttpRequest integration
284
  val xhr = new XMLHttpRequest()
285
  xhr.open("POST", "/api/data")
286
  xhr.setRequestHeader("Content-Type", "application/json")
287
  xhr.send(json)
288
}
289
```