CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-lihaoyi--upickle-3

A lightweight JSON and MessagePack serialization library for Scala

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.lihaoyi/upickle_3@4.1.x
Publish Source
CLI
Badge
tessl/maven-com-lihaoyi--upickle-3 badge