{"id":20664509,"url":"https://github.com/outr/giant-scala","last_synced_at":"2026-01-11T17:36:26.411Z","repository":{"id":57728206,"uuid":"119737568","full_name":"outr/giant-scala","owner":"outr","description":"Advanced functionality for working with MongoDB in Scala","archived":false,"fork":false,"pushed_at":"2025-03-30T00:11:51.000Z","size":221,"stargazers_count":6,"open_issues_count":19,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-19T18:58:59.282Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/outr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-01-31T20:09:32.000Z","updated_at":"2023-01-31T16:56:39.000Z","dependencies_parsed_at":"2024-04-21T01:44:04.419Z","dependency_job_id":"039b331c-313a-4a35-9279-e0a73de7943e","html_url":"https://github.com/outr/giant-scala","commit_stats":null,"previous_names":["outr/giantscala"],"tags_count":49,"template":false,"template_full_name":null,"purl":"pkg:github/outr/giant-scala","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outr%2Fgiant-scala","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outr%2Fgiant-scala/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outr%2Fgiant-scala/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outr%2Fgiant-scala/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/outr","download_url":"https://codeload.github.com/outr/giant-scala/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outr%2Fgiant-scala/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260857428,"owners_count":23073439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T19:24:42.715Z","updated_at":"2026-01-11T17:36:26.384Z","avatar_url":"https://github.com/outr.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# giant-scala\n\n[![CI](https://github.com/outr/giant-scala/actions/workflows/ci.yml/badge.svg)](https://github.com/outr/giant-scala/actions/workflows/ci.yml)\n[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/outr/giantscala)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.outr/giant-scala_2.12/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.outr/giant-scala_2.12)\n[![Scala version support](https://index.scala-lang.org/outr/giant-scala/giant-scala/latest.svg)](https://index.scala-lang.org/outr/giant-scala/giant-scala)\n[![javadoc](https://javadoc.io/badge2/com.outr/giant-scala_2.13/javadoc.svg)](https://javadoc.io/doc/com.outr/giant-scala_2.13)\n\nGiantScala is wrapper on top of the Scala MongoDB driver to provide higher level functionality and better type-safety.\n\n## Quick Start\n\nFor people that want to skip the explanations and see it action, this is the place to start!\n\n### Dependency Configuration\n\n```scala\nlibraryDependencies += \"com.outr\" %% \"giant-scala\" % \"1.5.0\"\n```\n\nIf you are developing a cross-project with Scala.js support:\n\n```scala\nlibraryDependencies += \"com.outr\" %%% \"giant-scala\" % \"1.5.0\"\n```\n\nNote: while MongoDB obviously doesn't work in the browser, the purpose of the Scala.js functionality is to allow shared\nmodel objects that extend from the base `ModelObject`.\n\n### Case Classes\n\nMost of the functionality in GiantScala is accessible via the import:\n\n```scala\nimport com.outr.giantscala._\n```\n\nIn order to represent our object, we begin with a case class:\n\n```scala\ncase class Person(_id: String,\n                  name: String,\n                  age: Int,\n                  created: Long = System.currentTimeMillis(),\n                  modified: Long = System.currentTimeMillis()) extends ModelObject\n```\n\nNotice that this case class extends from `ModelObject`. This is a simple trait that defines three required fields for all\nmodel objects:\n* `_id: String`: A unique identifier in the database\n* `created: Long`: The creation date of this document\n* `modified: Long`: The last modified date of this document\n\n### Database\n\nIn order to represent the tie-in to an actual MongoDB instance, we must create a database object:\n\n```scala\nobject Database extends MongoDatabase(name = \"giant-scala-tutorial\") {\n    ... collections listed here ...\n}\n```\n\n### DBCollection\n\nNow that we have a `Person` case class, we need to tie it to a database collection. To do this, we use the `DBCollection`\nobject:\n\n```scala\nclass PersonCollection extends DBCollection[Person](\"person\", Database) {\n  override val converter: Converter[Person] = Converter.auto[Person]\n\n  val name: Field[String] = Field(\"name\")\n  val age: Field[Int] = Field(\"age\")\n  val created: Field[Long] = Field(\"created\")\n  val modified: Field[Long] = Field(\"modified\")\n  val _id: Field[String] = Field(\"_id\")\n\n  override def indexes: List[Index] = List(\n    name.index.ascending.unique\n  )\n}\n```\n\nThere's a lot of boilerplate code in this class, but we can simplify this setup if we use the GiantScala SBT plugin. Add\nthe following line to your `project/plugins.sbt` file in your project:\n\n```scala\naddSbtPlugin(\"com.outr\" % \"giant-scala-plugin\" % \"1.2.0\")\n```\n\nNow you can run `sbt generateDBModels` and a `PersonModel` class will be generated in your source directory. This simplifies\nset up by changing the signature of the `PersonCollection` to:\n\n```scala\nclass PersonCollection extends PersonModel(\"person\", Database) {\n  override def indexes: List[Index] = List(\n    name.index.ascending.unique\n  )\n}\n```\n\nThe fields and converter are all defined in the `PersonModel` class. The only things left to define are indexes.\n\nNow, we need to update our `Database` to include the collection:\n\n```scala\nobject Database extends MongoDatabase(name = \"giant-scala-tutorial\") {\n    val person: PersonCollection = new PersonCollection\n}\n```\n\n### Initialize the Database\n\nGiantScala supports advanced features like database upgrades that are handled during the initialization phase:\n\n```scala\nDatabase.init()\n```\n\nNote that `init()` returns a `IO[Unit]` that must complete before the database is fully usable. We'll talk about\ndatabase upgrades later in this tutorial.\n\n### Inserting a Person\n\nNow that our database is fully defined we can easily insert a person:\n\n```scala\nDatabase.person.insert(Person(_id = \"john.doe\", name = \"John Doe\", age = 30))\n```\n\nNote that this returns a `IO[Either[DBFailure, Person]]` representing the success or failure of the operation.\n\n### Querying a Person\n\nNow that there's a person in our database, we can query them back with:\n\n```scala\nDatabase.person.all()\n```\n\nThis will return a `IO[List[Person]]`\n\nFor a more advanced query, GiantScala offers a type-safe implementation of aggregation:\n\n```scala\nimport Database.person._\n\naggregate\n  .`match`(name === \"John Doe\")\n  .toList\n```\n\nNote that this will return a `IO[List[Person]]`.\n\nIf we wanted a more simplistic, limited type to result from aggregation we could do:\n\n```scala\nimport Database.person._\n\ncase class SimplePerson(_id: String, name: String)\n\naggregate\n  .project(name.include)\n  .`match`(name === \"John Doe\")\n  .as[SimplePerson]\n  .toList\n```\n\nThis will return a `IO[List[SimplePerson]]`. This can be extremely useful for complex queries to avoid being bound to\nthe original type. It is also worth noting that instead of calling `toList` you can call `toQuery()` and it will generate\na `String` representation of the query that can be directly pasted into the `mongo` REPL. This allows for much easier testing\nof complex queries.\n\n### Advanced Features (TODO: Give examples for each of these)\n* Database Upgrades: Extend from `DatabaseUpgrade` and call `Database.register(upgrade)` before calling `Database.init()`\n* Batch Operations: GiantScala provides several features for batch operations. The typical path is to simply call `collection.batch` to get started\n* Key/Value Store: `Database.store` provides lots of functionality for storing key/value data into the database\n* Realtime Monitoring: GiantScala provides advanced functionality to monitor changes happening in real-time to the database (see `collection.monitor`)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutr%2Fgiant-scala","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foutr%2Fgiant-scala","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutr%2Fgiant-scala/lists"}