0
# Streaming
1

2
Functions for writing to streams, OutputStreams, and creating streamable representations. These provide efficient serialization for large data sets and integration with I/O systems.
3

4
## Capabilities
5

6
### Writing to java.io.Writer
7

8
Writes JSON directly to a java.io.Writer for efficient string output.
9

10
```scala { .api }
11
/**
12
 * Write the given Scala value as a JSON string to the given Writer
13
 * @param t Value to serialize
14
 * @param out java.io.Writer to write to
15
 * @param indent Indentation level (-1 for compact, >=0 for pretty printing)
16
 * @param escapeUnicode Whether to escape unicode characters
17
 * @param sortKeys Whether to sort object keys alphabetically
18
 */
19
def writeTo[T: Writer](t: T, out: java.io.Writer, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): Unit
20
```
21

22
**Usage Examples:**
23

24
```scala
25
import upickle.default._
26
import java.io.StringWriter
27

28
val data = List(Person("Alice", 30), Person("Bob", 25))
29

30
// Write to StringWriter
31
val stringWriter = new StringWriter()
32
writeTo(data, stringWriter, indent = 2)
33
val result = stringWriter.toString
34

35
// Write to FileWriter
36
val fileWriter = new java.io.FileWriter("output.json")
37
try {
38
  writeTo(data, fileWriter, indent = 2, sortKeys = true)
39
} finally {
40
  fileWriter.close()
41
}
42
```
43

44
### Writing to OutputStream
45

46
Writes JSON directly to a java.io.OutputStream as UTF-8 bytes.
47

48
```scala { .api }
49
/**
50
 * Write JSON to OutputStream as UTF-8 bytes
51
 * @param t Value to serialize
52
 * @param out OutputStream to write to  
53
 * @param indent Indentation level (-1 for compact, >=0 for pretty printing)
54
 * @param escapeUnicode Whether to escape unicode characters
55
 * @param sortKeys Whether to sort object keys alphabetically
56
 */
57
def writeToOutputStream[T: Writer](t: T, out: java.io.OutputStream, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): Unit
58
```
59

60
**Usage Examples:**
61

62
```scala
63
import upickle.default._
64
import java.io.{FileOutputStream, ByteArrayOutputStream}
65

66
val data = Map("users" -> List("Alice", "Bob", "Charlie"))
67

68
// Write to ByteArrayOutputStream
69
val byteStream = new ByteArrayOutputStream()
70
writeToOutputStream(data, byteStream, indent = 2)
71
val bytes = byteStream.toByteArray
72

73
// Write to FileOutputStream  
74
val fileStream = new FileOutputStream("data.json")
75
try {
76
  writeToOutputStream(data, fileStream, sortKeys = true)
77
} finally {
78
  fileStream.close()
79
}
80
```
81

82
### Writing to Byte Array
83

84
Writes JSON to a byte array for in-memory handling.
85

86
```scala { .api }
87
/**
88
 * Write JSON to byte array
89
 * @param t Value to serialize
90
 * @param indent Indentation level (-1 for compact, >=0 for pretty printing)  
91
 * @param escapeUnicode Whether to escape unicode characters
92
 * @param sortKeys Whether to sort object keys alphabetically
93
 * @return UTF-8 encoded JSON as byte array
94
 */
95
def writeToByteArray[T: Writer](t: T, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): Array[Byte]
96
```
97

98
**Usage Examples:**
99

100
```scala
101
import upickle.default._
102

103
val person = Person("Alice", 30)
104

105
// Compact byte array
106
val compactBytes = writeToByteArray(person)
107

108
// Pretty-printed byte array
109
val prettyBytes = writeToByteArray(person, indent = 2)
110

111
// Convert back to string
112
val jsonString = new String(compactBytes, "UTF-8")
113
```
114

115
### JSON Streaming with geny.Writable
116

117
Creates a geny.Writable for efficient streaming JSON output.
118

119
```scala { .api }
120
/**
121
 * Write the given Scala value as a JSON string via a geny.Writable
122
 * @param t Value to serialize
123
 * @param indent Indentation level (-1 for compact, >=0 for pretty printing)
124
 * @param escapeUnicode Whether to escape unicode characters  
125
 * @param sortKeys Whether to sort object keys alphabetically
126
 * @return geny.Writable with application/json content type
127
 */
128
def stream[T: Writer](t: T, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): geny.Writable
129
```
130

131
**Usage Examples:**
132

133
```scala
134
import upickle.default._
135

136
val data = List(1, 2, 3, 4, 5)
137

138
// Create streamable representation
139
val writable = stream(data, indent = 2)
140

141
// Write to OutputStream
142
val outputStream = new java.io.FileOutputStream("numbers.json")
143
try {
144
  writable.writeBytesTo(outputStream)
145
} finally {
146
  outputStream.close()
147
}
148

149
// Use with HTTP libraries that accept geny.Writable
150
// val response = requests.post("http://api.example.com/data", data = writable)
151
```
152

153
### MessagePack Binary Streaming
154

155
Functions for streaming MessagePack binary data.
156

157
```scala { .api }
158
/**
159
 * Write MessagePack binary to the given OutputStream
160
 * @param t Value to serialize
161
 * @param out OutputStream to write to
162
 * @param sortKeys Whether to sort object keys alphabetically
163
 */
164
def writeBinaryTo[T: Writer](t: T, out: java.io.OutputStream, sortKeys: Boolean = false): Unit
165

166
/**
167
 * Write MessagePack binary to byte array
168
 * @param t Value to serialize  
169
 * @param sortKeys Whether to sort object keys alphabetically
170
 * @return MessagePack byte array
171
 */
172
def writeBinaryToByteArray[T: Writer](t: T, sortKeys: Boolean = false): Array[Byte]
173

174
/**
175
 * Write MessagePack binary via a geny.Writable
176
 * @param t Value to serialize
177
 * @param sortKeys Whether to sort object keys alphabetically  
178
 * @return geny.Writable with application/octet-stream content type
179
 */
180
def streamBinary[T: Writer](t: T, sortKeys: Boolean = false): geny.Writable
181
```
182

183
**Usage Examples:**
184

185
```scala
186
import upickle.default._
187
import java.io.{FileOutputStream, ByteArrayOutputStream}
188

189
val data = Map("metrics" -> List(1.2, 3.4, 5.6))
190

191
// Write MessagePack to OutputStream
192
val fileOut = new FileOutputStream("data.msgpack")
193
try {
194
  writeBinaryTo(data, fileOut, sortKeys = true)
195
} finally {
196
  fileOut.close()
197
}
198

199
// Write to byte array
200
val binaryBytes = writeBinaryToByteArray(data)
201

202
// Create streamable binary representation  
203
val binaryWritable = streamBinary(data, sortKeys = true)
204

205
// Write via geny.Writable
206
val binaryOut = new ByteArrayOutputStream()
207
binaryWritable.writeBytesTo(binaryOut)
208
val result = binaryOut.toByteArray
209
```
210

211
### Large Data Streaming
212

213
Efficient patterns for handling large datasets.
214

215
**Usage Examples:**
216

217
```scala
218
import upickle.default._
219
import java.io.{BufferedWriter, FileWriter}
220

221
// Streaming large collections
222
def writeChunkedData[T: Writer](data: Iterator[T], filename: String, chunkSize: Int = 1000): Unit = {
223
  val writer = new BufferedWriter(new FileWriter(filename))
224
  try {
225
    writer.write("[")
226
    var first = true
227
    
228
    data.grouped(chunkSize).foreach { chunk =>
229
      chunk.foreach { item =>
230
        if (!first) writer.write(",")
231
        writeTo(item, writer)
232
        first = false
233
      }
234
    }
235
    
236
    writer.write("]")
237
  } finally {
238
    writer.close()
239
  }
240
}
241

242
// Usage with large dataset
243
val largeDataset: Iterator[LogEntry] = getLargeDataset()
244
writeChunkedData(largeDataset, "logs.json", chunkSize = 500)
245
```
246

247
### Stream Integration Examples
248

249
Integration with common streaming libraries and frameworks.
250

251
**Usage Examples:**
252

253
```scala
254
import upickle.default._
255

256
// Akka Streams integration
257
// implicit val system = ActorSystem()
258
// implicit val materializer = ActorMaterializer()
259
// 
260
// val source = Source(List(Person("Alice", 30), Person("Bob", 25)))
261
// val sink = StreamConverters.fromOutputStream(() => new FileOutputStream("people.json"))
262
// 
263
// source
264
//   .map(person => ByteString(write(person) + "\n"))
265
//   .runWith(sink)
266

267
// FS2 integration  
268
// val stream = fs2.Stream.emits(List(1, 2, 3, 4, 5))
269
// val jsonStream = stream.map(n => write(n)).intersperse(",")
270
// val result = jsonStream.compile.toList
271

272
// Play Framework integration
273
// def streamJson = Action {
274
//   val data = getData()
275
//   val writable = stream(data, indent = 2)
276
//   Ok.chunked(Enumerator.fromStream(writable.getBytes)).as(JSON)
277
// }
278
```
279

280
## Types
281

282
```scala { .api }
283
/**
284
 * geny.Writable represents streamable content with optional HTTP content type
285
 */
286
trait geny.Writable {
287
  def httpContentType: Option[String]
288
  def writeBytesTo(out: java.io.OutputStream): Unit
289
}
290
```