or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

builtin-types.mdcore-serialization.mdindex.mdjson-integration.mdmessagepack-integration.mdsealed-traits.mdstreaming.mdtype-classes.md
tile.json

tessl/maven-com-lihaoyi--upickle_3

A lightweight JSON and MessagePack serialization library for Scala

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.lihaoyi/upickle_3@4.1.x

To install, run

npx @tessl/cli install tessl/maven-com-lihaoyi--upickle_3@4.1.0

index.mddocs/

uPickle

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.

Package Information

  • Package Name: upickle_3
  • Package Type: maven
  • Language: Scala
  • Maven Coordinates: "com.lihaoyi" %% "upickle" % "4.1.0"
  • SBT Installation: libraryDependencies += "com.lihaoyi" %% "upickle" % "4.1.0"

Core Imports

import upickle.default._

For custom behavior:

import upickle.{Api, AttributeTagged, legacy}

For core types:

import upickle.core.{Reader, Writer, ReadWriter}

For direct ujson operations:

import ujson._

For direct upack operations:

import upack._

For Scala.js web APIs:

import upickle.web._  // Scala.js only

Basic Usage

import upickle.default._

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

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

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

// MessagePack binary serialization
val binary = writeBinary(person)
val parsedBinary = readBinary[Person](binary)

// Collection handling
val people = List(Person("Alice", 30), Person("Bob", 25))
val jsonArray = write(people)
val parsedArray = read[List[Person]](jsonArray)

Architecture

uPickle is built around several key components:

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

Capabilities

Core Serialization API

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

def read[T: Reader](s: ujson.Readable, trace: Boolean = false): T
def write[T: Writer](t: T, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): String
def readBinary[T: Reader](s: upack.Readable, trace: Boolean = false): T  
def writeBinary[T: Writer](t: T, sortKeys: Boolean = false): Array[Byte]

Core Serialization

Type Classes System

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

trait Reader[T] extends Visitor[Any, T]
trait Writer[T] extends Transformer[T]
trait ReadWriter[T] extends Reader[T] with Writer[T]

def reader[T: Reader]: Reader[T]
def writer[T: Writer]: Writer[T] 
def readwriter[T: ReadWriter]: ReadWriter[T]

Type Classes

Built-in Type Support

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

implicit val StringReader: Reader[String]
implicit val IntReader: Reader[Int]
implicit val BooleanReader: Reader[Boolean]
implicit def OptionReader[T: Reader]: Reader[Option[T]]
implicit def ArrayReader[T: Reader: ClassTag]: Reader[Array[T]]
implicit def MapReader[K: Reader, V: Reader]: Reader[Map[K, V]]

Built-in Types

JSON Integration

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

def writeJs[T: Writer](t: T): ujson.Value
implicit def JsValueR: Reader[ujson.Value]
implicit def JsValueW: Writer[ujson.Value]

JSON Integration

MessagePack Integration

Direct integration with upack for binary MessagePack serialization.

def writeMsg[T: Writer](t: T): upack.Msg
implicit val MsgValueR: Reader[upack.Msg]
implicit val MsgValueW: Writer[upack.Msg]

MessagePack Integration

Sealed Trait Support

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

trait TaggedReader[T] extends SimpleReader[T]
trait TaggedWriter[T] extends Writer[T]
trait TaggedReadWriter[T] extends ReadWriter[T] with TaggedReader[T] with TaggedWriter[T]

Sealed Traits

Streaming and Output

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

def writeTo[T: Writer](t: T, out: java.io.Writer, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): Unit
def stream[T: Writer](t: T, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): geny.Writable
def writeBinaryTo[T: Writer](t: T, out: java.io.OutputStream, sortKeys: Boolean = false): Unit

Streaming

Types

trait Api extends upickle.core.Types with implicits.Readers with implicits.Writers with implicits.CaseClassReadWriters

object default extends AttributeTagged

object legacy extends LegacyApi

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