{"id":19379073,"url":"https://github.com/lamba92/kotlin.document.store","last_synced_at":"2025-08-20T18:27:17.154Z","repository":{"id":246418686,"uuid":"820628346","full_name":"lamba92/kotlin.document.store","owner":"lamba92","description":"A Kotlin Multiplatform embedded nosql document database","archived":false,"fork":false,"pushed_at":"2025-06-02T22:20:15.000Z","size":534,"stargazers_count":36,"open_issues_count":13,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-03T04:13:20.779Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lamba92.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2024-06-26T21:24:05.000Z","updated_at":"2025-06-02T14:48:23.000Z","dependencies_parsed_at":"2024-06-27T22:10:31.771Z","dependency_job_id":"b573144a-1582-4584-97d0-07494872bdd4","html_url":"https://github.com/lamba92/kotlin.document.store","commit_stats":null,"previous_names":["lamba92/kotlin-db","lamba92/kotlin.document.store"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/lamba92/kotlin.document.store","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamba92%2Fkotlin.document.store","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamba92%2Fkotlin.document.store/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamba92%2Fkotlin.document.store/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamba92%2Fkotlin.document.store/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lamba92","download_url":"https://codeload.github.com/lamba92/kotlin.document.store/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamba92%2Fkotlin.document.store/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271362670,"owners_count":24746531,"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","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-10T09:08:29.835Z","updated_at":"2025-08-20T18:27:17.115Z","avatar_url":"https://github.com/lamba92.png","language":"Kotlin","funding_links":[],"categories":["数据库"],"sub_categories":["Spring Cloud框架"],"readme":"# kotlin.document.store\n\nFast NoSql document store for Kotlin Multiplatform, inspired by [Nitrite-java](https://github.com/nitrite/nitrite-java) and [MongoDB](https://github.com/mongodb/mongo).\n\nWith support for typed and schemaless data, lets you work with JSON objects easily, leveraging `kotlin.serialization` for fast and simple object serialization/deserialization.\n\nOriginally created for [JetBrains/package-search-intellij-plugin](https://github.com/JetBrains/package-search-intellij-plugin) for a fast and reliable offline cache, evolved for all KMP developers 🚀\n\nSome key highlights:\n- **Multiplatform**: Works on Kotlin/JVM, Kotlin/JS, and ALL Kotlin/Native platforms (excepts wasm).\n- **Typed and Schemaless Storage**: Use strongly-typed data models using [kotlin.serialization](https://github.com/kotlin/kotlin.serialization) or raw JSON depending on your needs.\n- **Simple APIs**: Built with a developer-friendly, coroutine-based API.\n- **Indexing Support**: Create and manage indexes for efficient querying of data.\n- **Thread-Safe and Asynchronous**: Built to handle concurrent read/write operations safely, with coroutine-based APIs for non-blocking interactions.\n- **Extensible**: Easily extend functionality by plugging in custom serializers or storage backends.\n\nWhether you're building desktop, web, or backend applications, `kotlin.document.store` provides a unified, intuitive way to manage structured or unstructured data across platforms.\n\n1. [Overview](#kotlindocumentstore)\n2. [Supported Platforms](#supported-platforms)\n3. [Quickstart](#quickstart)\n    - [Android and JVM](#android-and-jvm)\n        - [Dependency Setup](#dependency-setup)\n            - [Gradle Setup](#gradle-setup)\n            - [Using Version Catalog](#using-version-catalog)\n            - [In your Activity](#in-your-android-activity)\n            - [For JVM](#for-jvm)\n    - [JS Browser](#js-browser)\n        - [Dependency Setup](#dependency-setup-1)\n            - [Gradle Setup](#gradle-setup-1)\n            - [Using Version Catalog](#using-version-catalog-1)\n            - [Anywhere in your code](#anywhere-in-your-code)\n    - [Typed collections](#typed-collections)\n    - [JSON collections](#json-collections)\n4. [Advanced usage](#advanced-usage)\n    - [Indexes](#indexes)\n        - [Index Selector](#index-selector)\n        - [Array Indexing](#array-indexing)\n    - [ID Field](#id-field)\n5. [Testing](#testing)\n    - [DataStore Test Setup](#datastore-test-setup)\n    - [Available Test Implementations](#available-test-implementations)\n\n# Supported Platforms\nThere are three main implementations of the `DataStore` interface:\n- **LevelDB**: For all Kotlin platforms (excluding JS and Wasm), using [kotlin-leveldb](https://github.com/lamba92/kotlin-leveldb) key-value store.\n  - JVM:\n    - Windows: arm64, x64\n    - Linux: arm64, x64\n    - macOs: arm64, x64\n  - JS\n  - Native (Linux, macOS, Windows, iOS, Android, Android native, watchOS, tvOS)\n- **Browser**: For browser-based applications, using the browser's [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) storage.\n  - JS\n- **MVStore**: For JVM-based applications, using the [H2 Database Engine](https://www.h2database.com/html/main.html) MVStore. Recommended only for IntelliJ Plugin development.\n  - JVM\n\ngoogle/leveldb is licensed under [BSD-3-Clause license](https://github.com/google/leveldb/blob/main/LICENSE), all rights reserved to the original authors.\n\nThe modules `core` and `test` are common to all platforms and contain the main interfaces and tests for the library and they support also `wasmWasi`.\n\n# Quickstart\n\n## Android and JVM\n\n### Dependency Setup\nImport the library to your project, see the latest version in the [Releases](https://github.com/lamba92/kotlin.document.store/releases) page:\n\n#### Gradle Setup\n```kotlin\ndependencies {\n    implementation(\"com.github.lamba92:kotlin-document-store-leveldb:{latest_version}\")\n}\n```\n#### Using Version Catalog\nAlternatively with the provided version catalog:\n```kotlin\n// settings.gradle.kts\ndependencyResolutionManagement {\n    repositories {\n        mavenCentral()\n    }\n    versionCatalogs {\n        create(\"kotlinDocumentStore\") {\n            from(\"com.github.lamba92:kotlin-document-store-version-catalog:{latest_version}\")\n        }\n    }\n}\n\n// build.gradle.kts\ndependencies {\n  implementation(kotlinDocumentStore.leveldb)\n}\n```\n\n#### In your Android Activity\n\n```kotlin\nclass MyActivity : CompactActivity() {\n    \n    override fun onCreate(): String {\n        val store = context.openLevelDBStore()\n        val db = KotlinDocumentStore(store)\n        // your stuff...\n    }\n    \n}\n```\n\n#### For JVM\n\n```kotlin\nfun main() {\n    val store = LevelDBStore.open(\"path/to/db\")\n    val db = KotlinDocumentStore(store)\n    // your stuff...\n}\n```\n\n## JS Browser\n\n### Dependency Setup\nImport the library to your project, see the latest version in the [Releases](https://github.com/lamba92/kotlin.document.store/releases) page:\n\n#### Gradle Setup\n```kotlin\ndependencies {\n    implementation(\"com.github.lamba92:kotlin-document-store-browser:{latest_version}\")\n}\n```\n#### Using Version Catalog\nAlternatively with the provided version catalog:\n```kotlin\n// settings.gradle.kts\ndependencyResolutionManagement {\n    repositories {\n        mavenCentral()\n    }\n    versionCatalogs {\n        create(\"kotlinDocumentStore\") {\n            from(\"com.github.lamba92:kotlin-document-store-version-catalog:{latest_version}\")\n        }\n    }\n}\n\n// build.gradle.kts\ndependencies {\n  implementation(kotlinDocumentStore.browser)\n}\n```\n\n#### Anywhere in your code\n\n```kotlin\nval db = KotlinDocumentStore(BrowserStore)\n```\n\n---\n\n### Typed collections\n\nUse `ObjectCollection` to store and manipulate strongly typed objects:\n\n```kotlin\n@Serializable\ndata class User(\n    // id declaration is optional, but if declared make sure\n    // to make it `Long? = null` to handle insertions where id is not provided\n    @SerialName(\"_id\") val id: Long? = null, \n    val name: String, \n    val age: Int\n)\n\n// ...\n\nval documentStore = KotlinDocumentStore(aDataStore)\n\n// Retrieve a typed collection\nval userCollection = documentStore.getObjectCollection\u003cUser\u003e(\"users\")\n\n// Insert a user\nval user = userCollection.insert(User(name = \"John Smith\", age = 30))\nprintln(\"Inserted User: $user\") // will also print the generated id\n\nval id = requireNotNull(user.id) { \"IMPOSSIBAH!\" }\nprintln(\"User ID: $id\")\n\n// Query by name\nval queriedUser = userCollection.find(\"name\", \"John Smith\").firstOrNull()\nprintln(\"Queried User: $queriedUser\")\n\n// Close the store\ndocumentStore.close()\n```\n\n---\n\n### JSON collections\n\nUse `JsonCollection` to store and manipulate raw JSON objects:\n\n```kotlin\nval documentStore = KotlinDocumentStore(aDataStore)\n\n// Create or fetch a collection\nval collection = documentStore.getJsonCollection(\"users\")\n\n// Insert a document\nval json = buildJsonObject { // kotlinx.serialization json APIs\n    put(\"name\", \"Jane Doe\")\n    put(\"age\", 25)\n}\ncollection.insert(json)\n\n// Retrieve the inserted document\nval allUsers = collection.iterateAll().toList()\nprintln(\"Users: $allUsers\")\n\n// Clean up\ndocumentStore.close()\n```\n---\n\n# Advanced usage\n\n## Indexes\n\nAny collection, JSON or typed, can have indexes created on them for faster querying:\n\n```kotlin\nval documentStore = kotlinDocumentStore(aDataStore)\n\nval collection = documentStore.getJsonCollection(\"users\")\n\n// Create an index\ncollection.createIndex(\"name\")\n\n// Insert documents\nval json1 = buildJsonObject {\n    put(\"name\", \"Alice\")\n    put(\"age\", 28)\n}\nval json2 = buildJsonObject {\n    put(\"name\", \"Bob\")\n    put(\"age\", 34)\n}\ncollection.insert(json1)\ncollection.insert(json2)\n\n// Use the index to query\nval results = collection.find(\"name\", \"Alice\").toList()\n\nprintln(\"Search Results: $results\")\n```\n\nIn the example above, we create an index on the `name` field of the `users` collection. We then insert two documents into the collection and query for documents where the `name` field is `Alice`. The query uses the index to find the documents faster.\n\n### Index Selector\n\nIndexes can be created using JSON selectors to index nested fields. For example, consider the following JSON document:\n\n```json\n{\n  \"name\": \"Alice\",\n  \"address\": {\n    \"city\": \"New York\",\n    \"zip\": 10001\n  }\n}\n```\n\nTo create an index on the `city` field in the `address` object, we can use a JSON selector:\n\n```kotlin\nval documentStore = kotlinDocumentStore(aDataStore)\nval collection = documentStore.getJsonCollection(\"users\")\ncollection.createIndex(\"address.city\")\n```\n\nNow, an index is created on the `city` field in the `address` object. We can query for documents where the `city` field is, for example, `New York`:\n\n```kotlin\nval results = collection.find(\"address.city\", \"New York\").toList()\n```\n\n##### Array Indexing\n\nIndexes can also be created on array fields. For example, consider the following JSON document:\n\n```json\n{\n  \"name\": \"Alice\",\n  \"tags\": [\"tag1\", \"tag2\", \"tag3\"]\n}\n```\n\nTo create an index on the `tags` array field, we can use a JSON selector:\n\n```kotlin\nval documentStore = kotlinDocumentStore(aDataStore)\nval collection = documentStore.getJsonCollection(\"users\")\ncollection.createIndex(\"tags.$3\")\n```\n\nNow, an index is created on the third element of the `tags` array field. We can query for documents where the third element of the `tags` array is, for example, `tag3`:\n\n```kotlin\nval results = collection.find(\"tags.$3\", \"tag3\").toList()\n```\n\n## ID field\n\nThe ID field name is `_id` and cannot be changed in the representation inside the database. The ID has to be of type `Long` and is autogenerated if not provided when inserting a document.\n\nWhen using typed collections, the ID field is optional in the data class, but it has to be of type `Long?` and nullable. Dor example:\n\n```kotlin\n@Serializable\ndata class User(\n    val _id: Long? = null,\n    val name: String,\n    val age: Int\n)\n```\n\nIt is possible to change the name of the ID field in the data class using the `@SerialName` annotation, but the actual field name in the database will always be `_id`:\n    \n```kotlin\n@Serializable\ndata class User(\n    @SerialName(\"_id\") val id: Long? = null,\n    val name: String,\n    val age: Int\n)\n```\n\n# Testing\n\n## DataStore Test Setup\nTo test your own implementation of [DataStore](core/src/commonMain/kotlin/com/github/lamba92/kotlin/document/store/core/DataStore.kt), \nyou can use the provided module `kotlin-document-store-test`:\n\n```kotlin\n// build.gradle.kts\n\n// Kotlin/JVM\ndependencies {\n    testImplementation(\"com.github.lamba92:kotlin-document-store-test:{latest_version}\")\n}\n\n// Kotlin/JS or Kotlin/Multiplatform\nkotlin {\n    sourceSets {\n        commonTest {\n            dependencies {\n                implementation(\"com.github.lamba92:kotlin-document-store-test:{latest_version}\")\n            }\n        }\n    }\n}\n```\n## Available Test Implementations\nClasses of tests are provided and only the implementation of `DataStore` is needed to run them. See test implementation for:\n- [MVDataStore](stores/mvstore/src/test/kotlin/com/github/lamba92/kotlin/document/store/tests/stores/mvstore/MVStoreTests.kt)\n- [LevelDBStore](stores/leveldb/src/commonTest/kotlin/com/github/lamba92/kotlin/document/store/tests/stores/leveldb/LeveldbTests.kt)\n- [BrowserStore](stores/browser/src/jsTest/kotlin/com/github/lamba92/kotlin/document/store/tests/stores/browser/BrowserTests.kt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flamba92%2Fkotlin.document.store","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flamba92%2Fkotlin.document.store","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flamba92%2Fkotlin.document.store/lists"}