Release Notes

This release contains a few bug fixes, better ergonomics for cats-interop and adapters, as well as a support for Apollo schema reporting.

Server Core

• Made the parser support inputs and enums with empty bodies #1283 by @jyoo980
• Added support for passing interfaces to Types.makeObject #1294 by @Fluxx
• Ensured the subscription streams are interruptible #1308 by @ghostdogpr
• Added support for Long passed as String inputs #1304 by @mdulac
• Fixed custom directive parsing in Scala 3 #1313 by @sergeykolbasov

Interop

• Refactored the cats-effect interop to support passing context with Kleisli or MTL, see docs #1246 by @iRevive

Adapters

• Improved adapter ergonomics: accepting their respective server options, changed RequestInterceptor to return more than just a status code #1288 by @paulpdaniels
• Upgraded zio-http to 1.0.0.0-RC25 #1216 by @uryyyyyyy

Relay Support

• Ensured validation errors gets propagated to the user #1302 by @SvenW
• Fixed connection from list #1307 by @dojusa
• Added forward and backward pagination #1310 by @dojusa

New Goodies

• Added support for Apollo schema reporting #1280 by @paulpdaniels

Release Notes

This release is the first one to support ZIO 2.0. It is based on ZIO 2.0.0-RC1.
For simplicity, I decided to align the version number with ZIO, so you can immediately recognize which ZIO version it corresponds to.
Keep in mind that this is an early stage version, as ZIO and a bunch of other dependencies are still release candidates.

Note: caliban-monix is not published for Scala 3 (a bug in ZIO 2.0.0-RC1 prevented this from working). It should be enabled when a version using ZIO 2.0.0-RC2 or higher is published.

Release Notes

This release contains a few bug fixes and improvements, in particular support for Relay.

Server

• Added basic support for Relay #1196 by @frekw
• Fixed variable resolution in directives #1263 by @ghostdogpr
• Improved render to show directives at the top of the schema #1270 by @Fluxx
• Added missing directives from annotations when deriving Schemas for enums, unions, input objects and interfaces #1275 by @Fluxx

Client

• Added support for BigInt & BigDecimal encoded as Strings #1250 by @nicoburniske
• Added ArgEncoder for UUID #1266 by @smiklos

Tools

• Used fully-qualified name for Vector in generated code so that it doesn't conflict with user types #1254 by @cornerman
• Ensured code generated by the compile-time plugin does not trigger any warnings #1247 by @guizmaii

Release Notes

This release fixes a few bugs.

Server

• Fixed selection merging with conflicting fragments #1213 by @ghostdogpr
• Fixed rendering of empty field list #1220 by @Fluxx
• Removed useless Has constraint in ZHttpAdapter #1241 by @ghostdogpr

Tools

• Made compile time codegen plugin work with sbt 1.6.x #1236 by @ghostdogpr
• Fixed interface/union client code generation #1217 #1223 #1237 by @ghostdogpr @iRevive
• Escaped function name properly in interface client generation #1225 by @ghostdogpr

Release Notes

This release fixes a few bugs and brings some goodies.

Server

• Fixed fields merging logic and improve overall performance #1199 by @ghostdogpr
• Fixed tapir-based subscriptions (stop commands were not properly handled) #1205 by @ghostdogpr
• Fixed behavior when no value has been provided for a variable (keep it empty instead of making it null) #1195 by @guymers
• Added cost estimation wrappers #1180 by @paulpdaniels
• Added helpers and a full-fledged example for using Http4sAdapter with F[_] and cats-effect #1206 by @ghostdogpr
• Changed RequestInterceptor to be same as the old ContextWrapper, making it possible to wrap the effect and change the ZIO environment #1208 by @ghostdogpr

Tools

• Added a new option to schema generation for preserving input names #1186 by @LaurenceWarne

Release Notes

This release brings two important changes to Caliban:

• the server adapters have been completely rewritten using Tapir
• the Schema.gen function has been changed to make it easier to deal with ZIO environment, especially with Scala 3

New adapters based on Tapir

Adapters have been completely rewritten and are now sharing code thanks to Tapir, with the following benefits:

• features are now consistent between each of the adapters: upload support, request interceptors, websocket hooks...
• you can create your own adapter very easily for any library that Tapir supports
• you can use the Json library of your choice easily
• tapir endpoints can be used to generate an sttp client (our test suite takes advantage of that)

Notable changes:

• FinchAdapter has been removed
• PlayRouter has been removed, in favor of PlayAdapter which is consistent with the other adapters
• AkkaHttpAdapter json support is now done via tapir
• Http4sAdapter requires Clock with Blocking in the environment (this constraint comes from the tapir interpreter)
• ContextWrapper is now RequestInterceptor
• Callbacks is now WebSocketHooks

Look at the documentation for more info. Examples have been updated and migration shouldn't be difficult, but feel free to drop by Discord if you need any help.

Change done in #1125 by @ghostdogpr

New gen function

TL;DR
gen[A] becomes gen[R, A]

For Scala 2:
You no longer need to worry about calling the right gen (from Schema vs GenericSchema), you can simply use Schema.gen everywhere. It now takes 2 type parameters R and A but you can usually omit them if you explicitly define the return type of your schema.

object schema extends GenericSchema[MyEnv]
import schema._

implicit val queriesSchema: Schema[MyEnv, Queries] = Schema.gen
// or
implicit val queriesSchema = Schema.gen[MyEnv, Queries]

If you use genMacro, you still need to do it on GenericSchema.

For Scala 3:
It is no longer necessary to use GenericSchema[R]. You can simply use Schema.gen when you need to explicitly derive a schema. Caliban will be able to derive a Schema[R, A] directly from that.

If your R is not Any, you need to pass it to the graphQL function, unless you already have a Schema[R, Query] in scope:

val api = graphQL[MyEnv, Queries, Unit, Unit](RootResolver(queries))
// or
implicit val queriesSchema: Schema[MyEnv, Queries] = Schema.gen
val api = graphQL(RootResolver(queries))

If you want to see the code generated by the derivation, you can use Schema.genDebug instead. It will print the generated code to the console when compiling.

Change done in #1115 by @ghostdogpr

Other Changes

Server

• A new spec for GraphQL was released in October 2021. Support for some new features have been added:
  • custom scalar specification URLs #1171 by @ghostdogpr
  • __typename is not valid at subscription root #1163 by @ghostdogpr
• Fixed withAdditionalTypes behavior #1170 #1175 #1176 #1177 by @frekw @ghostdogpr
• Fixed upload support when dealing with nested fields #1167 by @frekw
• Fixed deprecated directive support on manually created fields #1168 by @frekw

Client

• Code generation for interfaces was modified #1103 #1169 by @AlixBa. For each interface, 3 functions will be generated:
  • one with no suffix that takes a SelectionBuilder for each member implementing the interface
  • one suffixed with Option that takes an optional SelectionBuilder for each member implementing the interface, with default to None. That allows you not specifying a selection for every possible member.
  • one suffixed with Interface that takes a SelectionBuilder of the interface itself. This is useful if you want to select the common fields without having to provide a selection for each member.

Tools

• Made the source generator plugin support server-side code generation #1137 #1155 by @nikodemin @kubukoz
• Added support for multiple setting sets per file in CalibanPlugin #1156 by @kubukoz
• Added calibanVersion setting to CalibanPlugin #1165 by @kubukoz
• Updated scalafmt and stopped using deprecated methods #1174 by @AlixBa

Release Notes

This is a minor release to fix small bugs and add minor things.

Server

• Fixed int values coercion into float values (it was making false positive validation errors) #1150 by @ghostdogpr
• Added support for a @GQLExcluded annotation that can hide fields #1141 by @frekw

Tools

• Fixed the code generation to support fields starting with capital letters #1140 by @several27
• Changed schema comparison to consider the addition of a mandatory argument breaking #1147 by @ghostdogpr
• Added Scala 3 reserved keywords support in code generation #1145 by @jgoday

Release Notes

This is a minor release to fix some small bugs introduced by the new validations.

Server

• Fixed validation of null inputs in variables #1133 by @darl
• Fixed GQL syntax strings incorrectly validated as enums #1134 by @frekw
• Fixed translation of input value strings to enums #1136 by @frekw
• Introduced GraphQLAspect to customize a GraphQL object. See the documentation. #1128 by @paulpdaniels

Release Notes

Since I started Caliban 2 years ago, there were 3 validation rules that I left aside because they were pretty tricky to implement. Motivated by @frekw who bravely tackled the hardest one, I've implemented the last 2 and Caliban is now 100% compliant with the GraphQL spec! 🎉

If you had invalid queries that were accepted in the past, they might be rejected now so make sure to test before you upgrade Caliban straight to production 😉

Server

• Implemented "Field Selection Merging" validation #1084 by @frekw
• Implemented "All Variable Usages are Allowed" validation #1092 by @ghostdogpr
• Implemented "Values of Correct Type" validation #1093 by @ghostdogpr
• Added a new parameter isScalar to the @GQLValueType annotation to generate a scalar #1127 by @ghostdogpr
• Fixed a few mistakes in validation #1090 #1101 #1112 by @frekw
• Fixed LocationInfo Play Json serializer #1096 by @ghostdogpr

Adapters

• Removed blaze dependency from the http4s module #1110 by @kubukoz
• Extended request wrapper support to websockets in the Play Adapter #1063 by @easel
• Fixed variable parsing from query params in the ZIO HTTP Adapter #1118 by @ghostdogpr
• Fixed UTF-8 handling for request bodies in the ZIO HTTP Adapter #1120 by @frekw
• Fixed application/graphql handling in the ZIO HTTP Adapter #1124 by @frekw

Client

• Added a new generated function for union types that allows to not specify a selection for every subtype of the union #1099 by @ghostdogpr based on earlier work from @anotherhale

Tools

• Fixed the package name extraction regex used during code generation #1116 by @pavlosgi

Release Notes

Adapters

• Made the signature of makeWebSocketService in the Http4s adapter more permissive, allowing you to use a different R between GraphQLInterpreter and WebSocketBuilder2 #1080 by @ghostdogpr

Client

• Improved error handling in the laminext module #1086 by @ghostdogpr

Tools

• Added an option ctCalibanClientsVersionedCode to the compile time codegen plugin, so that it generates code in the target folder #1087 by @guizmaii
• Made all the generated case classes final #1081 by @guizmaii

Release Notes

The highlight of this release is the addition of a new sbt plugin to generate your Caliban client code directly from your Caliban server code at compile time. This is useful if you use Caliban on both client and server side. Check the plugin documentation for more details.

Here's a little preview showing how you tell sbt where your GraphQL server API is defined:

lazy val api =
  project
    .enablePlugins(CompileTimeCalibanServerPlugin)
    .settings(
      Compile / ctCalibanServer / ctCalibanServerSettings :=
        Seq(
          "com.example.my.awesome.project.api.CalibanServer.graphqlApi" -> ClientGenerationSettings.default
        )
    )

It is still very new, so let us know if you encounter any bug. This sbt voodoo magic was brought in #1037 by @guizmaii 🙏

Server

• Added support for @GQLDefault annotation for defining the default value of a field #1043 by @frekw
• Added Schema and ArgBuilder instances for Short #1011 by @Fluxx
• Added helpers for creating Schema instances for non-Throwable errors, see customErrorEffectSchema, customErrorQuerySchema and customErrorStreamSchema #1059 by @ghostdogpr
• Fixed fragment spreads parsing in Scala 3 #1066 by @ghostdogpr
• Fixed field metadata for enums coming from JSON variables (they now return EnumValue instead of StringValue) #1064 by @frekw

Adapters

• Upgraded http4s to 0.23.5. This caused a change in the interface of makeWebSocketService, because WebSocketBuilder was deprecated by http4s. It now requires a WebSocketBuilder2. See the examples project for an updated usage. #1075 by @ghostdogpr
• Added WebSocket lifecycle hooks to the zio-http adapter #1013 by @frekw

Tools

• Added a new sbt plugin to generate client code from server code #1037 by @guizmaii (see above)
• Fixed deprecated behaviour in SchemaLoader.fromCaliban #1006 by @ghostdogpr
• Fixed LocationInfo json decoding #1015 by @frekw
• Fixed interface types resolution in RemoteSchema #1018 by @frekw
• Added GraphQL error extensions decoding #1038 by @frekw
• Added then to the list of reserved keywords #1032 by @RhnSharma
• Added SchemaLoader.fromDocument #1036 by @frekw

Release Notes

Server

• Allowed tagless final variants for Http4sAdapter using R instead of Any for the environment #972 by @ghostdogpr
• Upgraded cats-effect and http4s to 3.2.1 and 0.23 respectively (CE3-based). The Finch and Monix interop is still using CE2. The http4s adapter is also published for Scala 3 now. #891 by @iRevive
• Added a new annotation @GQLValueType that allows redirecting a union type member to a different type defined in another file (removing the "sealed" constraint for unions) #989 by @paulpdaniels
• Added Scala 3 support for the federation module #997 by @ghostdogpr

Tools

• Added an option to client code generation to generate code in multiple files instead of a single one. Also allowed disabling formatting during code generation. #964 by @alexdupre
• Added an option to client code generation to map unknown enum values to __Unknown instead of failing #976 by @rtimush
• Made the client code generation automatically regenerate code when configs change #959 by @blast-hardcheese
• Made the client code generation properly detect packages when using a Play Framework project #956 by @yonlugoh

Release Notes

The main change in this release is the ability to run caliban client code generation automatically when you compile, instead of the previous (but still supported) manual sbt command. CodegenPlugin was also renamed to CalibanPlugin (the old name still exists but is deprecated).

See the updated documentation for more information. This work was done in #933 by @blast-hardcheese.

Server

• Fixed backslash parsing in queries #943 by @mingyuchi
• Added support for upload in the Http4s Adapter (batching not supported yet, like with Play) #945 by @pomadchin
• Added support for GQLInterface and GQLUnion annotations on enum-like traits #941 by @rtimush
• Added the ability to distinguish between a field value of null and a missing field in ArgBuilders #929 by @stephendavidmarsh
• Added a new resolver type to support using Field metadata with federation #939 by @paulpdaniels

Client

• Fixed string escaping problem when encoding arguments #942 by @mingyuchi
• Added a value helper function for enumeration members in generated code #936 by @blast-hardcheese
• Added a values helper function on enumerations in generated code, to get the list of possible members #934 by @blast-hardcheese

Tools

• Fixed wrong behavior in server codegen when a type is used in multiple unions #948 by @AlixBa
• Allowed scalarMappings to be used with enumerations in client codegen #930 by @blast-hardcheese
• Allowed colons in header values in client codegen --headers option #938 by @ghostdogpr
• Added a new parameter --abstractEffectType to server codegen to generate code with F[_] #951 by @LaurenceWarne

Release Notes

• Fixed a regression in caliban-client causing a wrong error message to be returned ("Result is not an object" instead of the actual error message) by @ghostdogpr.

Release Notes

1.0.0 Release

A little less than 2 years after the creation of Caliban, I decided it was time for an official 1.0.0 release 🎉

Caliban has been reliable and stable for a long while now, and the few bugs that have been discovered in the recent past were about minor edge cases and immediately fixed. Caliban is currently used at various companies (including mine) and I even saw it mentioned in a few job offers! The public API is not changing much: even the recently added support for Scala 3 didn't cause much public changes (despite important changes under the hood: a new parser and a new derivation mechanism). Most of the changes are now about improving usability and adding support for libraries or GraphQL plug-ins. The documentation is pretty rich and there are a lot of examples available. I think we're in a good shape for a release!

I intend to keep the current process of incrementing the patch version for minor releases that are 100% binary compatible and the minor version for small breaking changes. The major version will be changed if there are changes that requires a non-trivial migration (this is not semantic versioning but I think it is not necessary for a library like Caliban that don't have many libraries depending on it).

Finally, I'd like to thank the 73 contributors who all took a part in making Caliban what it is today. I'm amazed there has been so many of you. If anyone is interested in contributing, reach out to me on Discord and I can guide you through it.

Server

• Added a helper function to manually construct lazy fields #921 by @ghostdogpr
• Fixed description of temporal schemas #925 by @ghostdogpr
• Added a zio-json backend for the Akka HTTP Adapter #819 by @jczuchnowski

Client

Important: There are several changes related to code generation, so it is recommended to re-run the code generation if you upgrade Caliban to this version.

• Added a new module caliban-client-laminext for easy usage of Caliban Client with the Laminar Scala.js library. This includes subscriptions support via WebSockets. More details in the docs. #897 by @ghostdogpr
• Added an option to drop null values from input objects when building requests #923 by @ghostdogpr
• Added a variant of toRequest named toRequestWith that gives access to partial errors and extensions. This replaces toRequestWithExtensions. Also, partial errors with a non-null response are now handled as a success. #926 by @ghostdogpr
• Fixed the generated code when there are arguments that are type aliases #906 by @ghostdogpr
• Prevented name clashes in generated code when an object is named Field #918 by @blast-hardcheese
• Prevented name clashes in generated code when an object is named RootQuery, RootMutation or RootSubscription #924 by @ghostdogpr

Tools

• Added support for basic stitching of local and remote schemas. More details in the docs. #896 by @frekw

Release Notes

Server

• Added support for Scala 3.0.0. Supported modules: caliban, caliban-client, caliban-zio-http, caliban-cats and caliban-monix #889 #892 by @ghostdogpr
• Fixed an incorrect error message when an input object contains a field named "value" #880 by @mszczygiel

Release Notes

Major changes

This release of Caliban is the first one to support Scala 3! 🎉

It required important efforts because 2 major pieces of Caliban were using Scala 2 macros heavily:

• The GraphQL parser is based on Fastparse, which doesn't support Scala 3 yet. For this release, a new parser based on cats-parse was written by @timzaak with some preliminary work by @lvitaly. Since performance is slower than Fastparse, it is currently used only for Scala 3 (Fastparse remains for Scala 2). This might change in the future depending on the availability of alternatives and their performance (ideally, the same parser should be used for both Scala 2 and Scala 3). This change doesn't affect the public API.
• The typeclass derivation is based on Magnolia, which doesn't support Scala 3 yet. It was decided to rely on the typeclass derivation features of Scala 3 without the help of any library. This turned out to work well, and the code is barely longer than it was when using Magnolia, except we have full control and understanding of it now. The public API is the same (you can still use explicit derivation with gen).

The following components are available for Scala 3 (more will be added in the future when dependencies support it):

• caliban (with support for circe)
• caliban-client (for JVM and JS)
• caliban-zio-http (new! see below)

There is one breaking change caused by Scala 3 support: the API for wrappers changed a little bit. Before, wrappers were case classes containing a function such as (Info => ZIO[R, E, A]) => Info => ZIO[R, E, A], now they are traits with a similar function to implement. See here how caliban wrappers were migrated. This change only affects you if you created your own wrappers (using caliban wrappers require no change).

Changes can be found in #847 by @ghostdogpr with contributions from @timzaak and @javimartinez.

Other changes

Server (Core)

• Prevented stack overflow when using recursive types in interfaces #863 by @ghostdogpr
• Fixed the optionality of one introspection field #808 by @guymers
• Fixed validation logic for interface fields with arguments #864 by @tjarvstrand
• Added rendering of description for argument fields #845 by @kpbochenek

Server (Adapters/Interop)

• Added a brand new adapter for ZIO HTTP, with support for WebSockets included. Since this is a ZIO-native library, the usage of caliban is the simplest of all the adapters (see example). This is also the first adapter to support Scala 3. Note that this using a Release Candidate as there is no stable release yet. #867 by @frekw
• Reduced Runtime requirement for interpreter creation in cats and monix interop #866 by @willtrnr

Client

• Fixed a bug when passing list arguments #782 by @ghostdogpr

Tools

• Added a new command line option to codegen --scalarMappings to map scalars to custom types and --imports to add your own imports to the generated code #810 by @nikodemin
• Added RemoteSchema for parsing and working with remote schemas via introspection #833 by @frekw
• Prevented generating functions with name ending with underscore as it doesn't compile #783 by @johanneshiry

Release Notes

Server (Core)

• Introduced a new parameter queryExecution which allows controlling the parallelism of effectful fields in queries #692 by @ghostdogpr with support from @adamgfraser in zio-query. Possible values are:
  • sequential: effects are executed sequentially
  • parallel (default, same behavior as previous versions): effects are executed in parallel
  • batched: arbitrary effects are executed sequentially but batched queries (queries optimized with ZQuery and a DataSource) are executed in parallel. This provides better performance if you use mostly batched queries.
• Added helpers to easily generate schemas manually #687 by @paulpdaniels
  • This is especially useful when having problems with auto-derivation (e.g. when magnolia has issues with recursive types). See documentation on how to do that. You can generate manual schemas only for parts of your API and keep using auto-derivation for the rest.
• Added zio-json interop in addition to circe and play-json #649 by @paulpdaniels
• Implemented federation tracing #701 by @paulpdaniels (see docs)
• Added a new wrapper type IntrospectionWrapper that is only applied to introspection, making it possible to control what introspection returns #753 by @macchiatow
• Improved render to display descriptions on fields and scalars #675 by @jamonkko and #759 by @kpbochenek
• Improved render to display deprecated fields and enum vals #685 by @heyrutvik
• Improved printErrors wrapper to print full stack trace (in red) #695 by @palanga
• Fixed partial error handling #699 by @ghostdogpr
• Fixed handling of queries with a root fragment #729 by @ghostdogpr
• Fixed schema for Either #730 by @ghostdogpr
• Fixed rename on a union type #728 by @ghostdogpr

Server (Adapters)

• Added support for chunked websocket messages in Akka Http Adapter #726 by @moonkev

Client

• Upgraded sttp to 3.x #748 by @javimartinez
• Added a new option to code generation to generate "view" case classes and selections containing all fields #734 by @iRevive

Tools

• Fixed input fields in SchemaLoader.fromCaliban #681 by @ghostdogpr
• Fixed schema comparison for descriptions #751 by @kpbochenek

Release Notes

Server (Core)

• Added support for field metadata optimizations #646 by @jweaver-personal
  • This allows you to know which fields were selected in your resolvers. To use it, just make your field Field => A or Field => (Args => A) with Field being caliban.execution.Field and containing information about the query. Caliban will "feed" it for you. More info in the docs.
• Improved laziness of typeclass derivation #658 by @ghostdogpr and @darl
  • This should improve cases where Magnolia tries to auto-derive schemas for types like List or Option instead of using the existing ones. This shouldn't affect existing code but in case of ambiguities, add explicit calls to gen[A] or genMacro[A].schema (the latter will provide more detailed error messages).
• Fixed a bug with interfaces when they're used both in Queries and Mutations #628 by @iRevive
• Added Schema#rename #639 by @ghostdogpr
• Fixed wrapPureValues behavior in field wrappers #666 😈 by @ghostdogpr
• Fixed response from fake field _ (used in union members without fields) #673 by @ghostdogpr

Server (Adapters)

• Added support for query query string parameter in POST endpoint of the Play Adapter #641 by @jessenr
• Added support for application/graphql content type in the Play Adapter #643 by @dgeyer-mdsol
• Added support for multipart requests to the Play Adapter. It now requires a runtime with Blocking with Random capabilities #500 by @igorfialko

Client

• Renamed classes to avoid conflicts in generated code #642 by @xirc
  • Breaking: you will need to re-generate your client if you upgrade to this version
• Made exceptions override getMessage for better printing #640 by @tdrozdowski
• Added guarantee of case-insensitive name uniqueness #644 by @javimartinez
• Added mapEither #651 by @ghostdogpr

Release Notes

Server

• Fixed a couple of bugs with interfaces #619 by @ghostdogpr
• Allowed custom directives to be added and used in wrappers #597 by @hwielenberg
• Changed the signature of provideSomeLayerFromRequest in the Http4s adapter to allow using any environment R #593 by @fokot
• Fixed the execution error pass through on die #606 by @paulpdaniels

Client

• Added a pure selection builder helper #595 by @paulpdaniels

Federation

• Handled nested orphans #607 by @paulpdaniels