Skip to content

Latest commit

 

History

History
164 lines (112 loc) · 5.27 KB

README.md

File metadata and controls

164 lines (112 loc) · 5.27 KB
Raw

arangodb-scala-driver

Maven Central Build Status Known Vulnerabilities Codacy Badge MIT License

Idiomatic ArangoDB driver for Scala as Tagless-Final DSL.

This library is under heavy development until v1.0.0 and therefore not ready for production!

Example

Example app using cats.effect.IO as effect type:

import cats.effect._
import cats.implicits._
import ch.acmesoftware.arangodbscaladriver._

import scala.concurrent.ExecutionContext.Implicits.global

case class Test(_key: String, name: String)

object Test {
  // Use DocumentCodec.derive[T] from one of the supported json libs 
  // or implement a codec using DocumentCodec.of[T]
  implicit val codec: DocumentCodec[Test] = ???
}

object Main extends IOApp {

  def run(args: List[String]): IO[ExitCode] = for {
    // connect to server
    arango <- ArangoDBBuilder.interpreter[IO].build("http://localhost", 8529)
    
    // get or create database instance
    db <- arango.db("myDb")
    
    // get or create collection
    collection <- db.collection("myCollection")
    
    // add document to collection
    _ <- collection.insertDocument(Test("key-1234", "Frank"))
    
    // delete document
    deleted <- collection.deleteDocument[Test]("key-1234")
    
    // output name of deleted document
    _ <- IO{ println(deleted.getOld.name) }
    
    res <- IO.pure(ExitCode.Success)
  } yield res
  
}

Features

  • Tagless final DSL. Choose your own effect type.
  • Scala 2.11, 2.12 and 2.13 (planned)
  • Wraps the official arangodb-java-driver-async and therefore supports a wide range of ArangoDB versions
  • Fully async & non-blocking (just provide custom ExecutionContext to do so)
  • Supports Scala types like Option[T], Iterable[T], etc.
  • Simple case class mapping by using third-party JSON library of choice

Usage

Installation

Add dependency to SBT build:

libraryDependencies ++= Seq(
  "ch.acmesoftware" %% "arangodb-scala-driver" % version
)

Scaladoc

The full scaladoc can be found here

Keep reading for examples & explanations

Document Codecs

A document codec is needed to serialize/deserialize JSON, which is in turn used by ArangoDB. You can provide an implicit DocumentCodec in two different ways:

By using one of the supported JSON libs

Add the appropriate dependency for the json lib you like:

libraryDependencies ++= Seq(
  // ...
  "ch.acmesoftware" %% "arangodb-scala-driver-circe" % version
)

Add the imports:

import ch.acmesoftware.arangodbscaladriver._

// circe support
import ch.acmesoftware.arangodbscaladriver.circe._

// derive codec by using an implicit circe `Encoder[Test]` and `Decoder[Test]`
implicit val codec = DocumentCodec.derive[Test]

By implementing it (not recommended)

import ch.acmesoftware.arangodbscaladriver._

case class Test(name: String)

DocumentCodec.of[Test](
  e => s"""{ name: "${e.name}" }""", 
  str => Left(new RuntimeException("Not deserializable"))
)

About

Design

The complete library is designed as a tagless final DSL. Therefore, the Effect type (F[_]) can be virtually everything which satisfies cats.effect.Sync[F]. In the examples, cats.effect.IO is used.

Beside that, one key point during API design was to keep is as similar as possible to arangodb-driver-java. This simplifies documentation, usability and the upgrade path for future ArangoDB versions.

In the examples, the global Scala ExecutionContext is used. For production purposes, please create your own and pass it either implicitly or explicit.

Versioning

The lib follows semantic versioning while majors can be mapped to the underlying ArangoDB driver version:

Library Version ArangoDB Driver Version
0.x.x 5.x.x
1.x.x 5.x.x

Disclaimer

This library is released under the terms of the MIT License by ACME Software Solutions GmbH. There is no legal relationship to ArangoDB Inc., ArangoDB GmbH, nor any of their employees. Please visit arangodb.com for more information.