• Stars
    star
    735
  • Rank 58,099 (Top 2 %)
  • Language
    Scala
  • License
    Apache License 2.0
  • Created over 6 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Easy, fast, transparent generic derivation of typeclass instances

Magnolia

GitHub Workflow

Magnolia

Magnolia is a generic macro for automatic materialization of typeclasses for datatypes composed from product types (e.g. case classes) and coproduct types (e.g. enums). It supports recursively-defined datatypes out-of-the-box, and incurs no significant time-penalty during compilation.

Features

  • derives typeclasses for case classes, case objects and sealed traits
  • offers a lightweight syntax for writing derivations without needing to understand complex parts of Scala
  • builds upon Scala 3's built-in generic derivation
  • works with recursive and mutually-recursive definitions
  • supports parameterized ADTs (GADTs), including those in recursive types
  • supports typeclasses whose generic type parameter is used in either covariant and contravariant positions

Getting Started

Given an ADT such as,

enum Tree[+T] derives Print:
  case Branch(left: Tree[T], right: Tree[T])
  case Leaf(value: T)

and provided a given instance of Print[Int] is in scope, and a Magnolia derivation for the Print typeclass has been provided, we can automatically derive given typeclass instances of Print[Tree[Int]] on-demand, like so,

Tree.Branch(Tree.Branch(Tree.Leaf(1), Tree.Leaf(2)), Tree.Leaf(3)).print

Typeclass authors may provide Magnolia derivations in the typeclass's companion object, but it is easy to create your own.

Creating a generic derivation with Magnolia requires implementing two methods on magnolia1.Derivation:

  • join() : create typeclasses for case classes ('product types')
  • split() : create typeclasses for sealed-traits/enums ('sum types')

Example derivations

There are many examples in the src/examples folder.

The definition of a Print typeclass with generic derivation might look like this (note we're using the Lambda syntax for Single Abstract Method types to instantiate the Print instances in join & split - that's possible because Print has only a single abstract method, print):

import magnolia1.*

trait Print[T] {
  extension (x: T) def print: String
}

object Print extends AutoDerivation[Print]:
  def join[T](ctx: CaseClass[Print, T]): Print[T] = value =>
    ctx.params.map { param =>
      param.typeclass.print(param.deref(value))
    }.mkString(s"${ctx.typeInfo.short}(", ",", ")")

  override def split[T](ctx: SealedTrait[Print, T]): Print[T] = value =>
    ctx.choose(value) { sub => sub.typeclass.print(sub.cast(value)) }
  
  given Print[Int] = _.toString

The AutoDerivation trait provides a given autoDerived method which will attempt to construct a corresponding typeclass instance for the type passed to it. Importing Print.autoDerived as defined in the example above will make generic derivation for Print typeclasses available in the scope of the import.

While any object may be used to define a derivation, if you control the typeclass you are deriving for, the companion object of the typeclass is the obvious choice since it generic derivations for that typeclass will be automatically available for consideration during contextual search.

If you don't want to make the automatic derivation available in the given scope, consider using the Derivation trait which provides semi-auto derivation with derived method, but also brings some additional limitations.

Limitations

Accessing default values for case class parameters requires compilation with -Yretain-trees on.

For a recursive structures it is required to assign the derived value to an implicit variable e.g.

given instance: SemiPrint[Recursive] = SemiPrint.derived

Availability

For Scala 3:

val magnolia = "com.softwaremill.magnolia1_3" %% "magnolia" % "1.3.3"

For Scala 2, see the scala2 branch.

Package and artifact naming, versioning

The main magnolia package is magnolia1, so that magnolia 1.x can be used alongside magnolia 0.17 (which are binary-incompatible). Future major releases of magnolia can change the package name for the same reason.

The group id for magnolia follows the naming scheme: com.softwaremill.magnolia[major version]_[scala major version]. The scala major version suffix is necessary to allow evolving and publishing versions for Scala 2 & Scala 3 independently. The magnolia major version is included for consistency with the package name, and so that future major releases may be used alongside this release.

Contributing

Contributors to Magnolia are welcome and encouraged. New contributors may like to look for issues marked label: good first issue.

Credits

Magnolia was originally designed and developed by Jon Pretty, and is currently maintained by SoftwareMill.

License

Magnolia is made available under the Apache 2.0 License.

More Repositories

1

elasticmq

In-memory message queue with an Amazon SQS-compatible interface. Runs stand-alone or embedded.
Scala
2,331
star
2

sttp

The Scala HTTP client you always wanted!
Scala
1,404
star
3

tapir

Declarative, type-safe web endpoints library
Scala
1,263
star
4

macwire

Lightweight and Nonintrusive Scala Dependency Injection Library
Scala
1,249
star
5

quicklens

Modify deeply nested case class fields
Scala
803
star
6

bootzooka

Simple project to quickly start developing a Scala-based microservice or web application, without the need to write login, user registration etc.
Scala
695
star
7

codebrag

Your daily code review tool
Scala
651
star
8

akka-http-session

Web & mobile client-side akka-http sessions, with optional JWT support
Scala
440
star
9

it-cfp-list

List of Call For Papers for IT conferences
374
star
10

retry

because you should never give up, at least not on the first try
Scala
346
star
11

diffx

Pretty diffs for scala case classes
Scala
341
star
12

kmq

Kafka-based message queue
Scala
317
star
13

scala-clippy

Good advice for Scala compiler errors
Scala
315
star
14

supler

Rapid Form Development library. Use your favourite JS frontend & Scala backend frameworks.
Scala
286
star
15

ox

Safe direct-style concurrency and resiliency for Scala on the JVM
Scala
266
star
16

mqperf

Scala
142
star
17

scala-common

Tiny independent libraries with a single purpose, often a single class
Scala
120
star
18

slick-eventsourcing

Example for "Entry level event-sourcing" blog
Scala
118
star
19

lemon-dataset

Lemons quality control dataset
97
star
20

jox

Fast and Scalable Channels in Java
Java
87
star
21

maven-badges

A node.js implementation of https://github.com/jirutka/maven-badges, originally created in ruby.
TypeScript
84
star
22

sbt-softwaremill

A sane set of default build settings
Scala
72
star
23

akka-vs-scalaz

Scala
63
star
24

recursion-training

Recursion schemes training examples and exercises
HTML
59
star
25

scala-sql-compare

Scala
51
star
26

livestub

The HTTP server stub you always wanted!
Scala
50
star
27

stringmask

A micro-library for macro-based case class field masking in .toString
Scala
48
star
28

scala-id-generator

Scala
48
star
29

confluent-playground

Java
44
star
30

odelay

delayed reactions
Scala
43
star
31

sttp-model

Simple Scala HTTP model
Scala
42
star
32

saft

Scala
41
star
33

akka-simple-cluster-k8s

Scala
39
star
34

softwaremill-common

SoftwareMill Common library
Java
37
star
35

walk-that-type

A tool for evaluating TypeScript types step by step.
TypeScript
31
star
36

sttp-openai

Scala
30
star
37

neme-plugin

Scala compiler plugin for turning non exhaustive match warnings into errors
Scala
29
star
38

FoXAI

The open-source library for explainable AI. Generic and easy to integrate with PyTorch.
Python
27
star
39

scala-pre-commit-hooks

Pre-commit/Pre-push hooks for Scala
Python
27
star
40

zio2-structure

Scala
26
star
41

helisa

Scala API for jenetics
Scala
26
star
42

streams-tests

Scala
25
star
43

tapir-loom

Scala
24
star
44

reactive-event-sourcing-java

Java
24
star
45

node-typescript-starter

A basic boilerplate for node + TypeScript development with debugger source maps support.
TypeScript
22
star
46

free-tagless-compare

Free monads compared to tagless final
Scala
22
star
47

akka-http-session-faq

Java
21
star
48

activator-reactive-kafka-scala

Activator template for Reactive Kafka
Scala
20
star
49

sttp-apispec

OpenAPI, AsyncAPI and JSON Schema Scala models.
Scala
20
star
50

scala3-macro-debug

Scala
17
star
51

reactive-streams-for-java-developers

Java
17
star
52

resilience4s

Scala
16
star
53

react-use-promise-matcher

React hooks allowing you to handle promises in a stateful way
TypeScript
16
star
54

simple-http-server

Simple JVM based HTTP server with no dependencies
Scala
15
star
55

correlator

Scala
15
star
56

adopt-tapir

A quickstart generator for Tapir projects
Scala
14
star
57

detectnet-tests

Python scripts and other resources for tesing DetectNet on Nvidia DIGITS
Python
14
star
58

blockchain-schedule

An experimental collaborative planning app based on Ethereum ("Decentralized Doodle")
TypeScript
14
star
59

blog-scala-structure-lifecycle

Scala
12
star
60

akka-sandbox

Training ground for experiments with Akka framework.
Scala
12
star
61

undelay

Satisfy Scala Futures quickly
Scala
11
star
62

broadway-pipelines-blog

Constructing effective data processing workflows using Elixir and Broadway
Elixir
11
star
63

monix-correlation-id

Scala
10
star
64

cassandra-monitoring

Scripts for the Cassandra Monitoring blog miniseries
10
star
65

reason-companies-example

Reason example application
OCaml
10
star
66

jvmbot

Scala
9
star
67

asamal

POC for a CDI-based web lightweight framework
Java
8
star
68

botarium

A simple starter kit for building bots using Node + TypeScript + BotKit.
TypeScript
8
star
69

sbt-template

Scala
8
star
70

boot-scala-microservice

Bootstrap microservice template that uses micro-deps library https://github.com/4finance/micro-deps
Scala
8
star
71

sttp-shared

Scala
7
star
72

modem-connector

Modulator and Demodulator for HAM Radio AX.25 audio signals
Scala
7
star
73

gatling-zeromq

A Gatling stress test plugin for ZeroMQ protocol
Scala
5
star
74

trqbox-demo

Ruby
5
star
75

idea-pastie-plugin

Plugin to post pastie.org pasties from IntelliJ Idea
Java
5
star
76

scala-compiler-plugin-template

Scala
5
star
77

sentinel-cgan

Sentinel generative conditional adversarial network implementation
Python
5
star
78

tapir-serverless

Scala
5
star
79

scalar-conf-website

Scalar - Scala Conference in Central Europe
Python
4
star
80

try-them-off

Showcase service presenting possible usage of the Try monad from Vavr.
Java
4
star
81

sttp-openapi-example

Scala
4
star
82

slack-alphabet

Scala
4
star
83

cache-get-or-create

Java
4
star
84

bootzooka-react

Simple project to quickly start developing a web application using React and Akka HTTP, without the need to write login, user registration etc. https://softwaremill.com/open-source/
Scala
4
star
85

fabrica

Shell
3
star
86

akka-typed-workshop

Scala
3
star
87

scalatimes

Pug
3
star
88

kuberenetes-fundamentals

Training projects to explore k8s features
Scala
3
star
89

play-scala-slick-example-part2

Scala
3
star
90

ansible-bigbluebutton

Shell
3
star
91

kleisli-example

Scala
3
star
92

loom-protect

Java
3
star
93

vehicle-routing-problem-java

Java
3
star
94

supler-example

Example project for Supler http://supler.io
JavaScript
2
star
95

sttp-native-cli

Scala Native with scala-cli and sttp example
Scala
2
star
96

jekyll-softwaremill

SoftwareMill.com website written in Jekyll
PHP
2
star
97

terraform-gke-bootstrap

HCL
2
star
98

functional-pancakes

Scala
2
star
99

aws-demo

Java
2
star
100

gcp-goodies

Source code and other materials for the blog post series - GCP Goodies
Scala
2
star