KStore

https://github.com/xxfast/kstore
Admin
KStore is a tiny Kotlin Multiplatform library that assists in saving and restoring objects to and...
Tokens:6,434
Snippets:70
Trust Score:9.9
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get values from list store

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage-list-store.md

Retrieves the full list or a specific element by index from the store.

```kotlin
val pets: List<Pet> = listStore.getOrEmpty()
val pet: Pet? = listStore.get(0)
```

--------------------------------

### Get a value from the store

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Retrieves the current value from the store once.

```kotlin
val mylo: Pet? = store.get()
```

--------------------------------

### Implement and use a binary codec

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Shows how to implement a custom BinaryCodec for formats like Protobuf or Cbor and use it to initialize a KStore.

```kotlin
// Boilerplate implementation for a BinaryCodec
public class BinaryCodec<T : @Serializable Any>(
  private val key: String,
  private val format: BinaryFormat,
  private val serializer: KSerializer<T>,
  private val storage: Storage,
) : Codec<T> {
  override suspend fun encode(value: T?) {
    if (value != null) storage[key] = format.encodeToByteArray(serializer, value)
    else storage.remove(key)
  }

  override suspend fun decode(): T? = storage[key]
    ?.let { format.decodeFromByteArray(serializer, it) }
}

// Protobuf implementation
public inline fun <reified T : @Serializable Any> ProtobufCodec(
  key: String,
  // Other formats can be found here: https://kotlinlang.org/api/kotlinx.serialization/
  format: BinaryFormat = Protobuf,
  storage: Storage = localStorage,
): BinaryCodec<T> = BinaryCodec(
  key = key,
  format = format,
  serializer = format.serializersModule.serializer(),
  storage = storage,
)

// Use the `Codec` to create a store
val store = KStore<Pet> = storeOf(
    codec = ProtobufCodec<Pet>,
    default = Pet(),
    enableCache = true
)
```

--------------------------------

### Initialize and use KStore

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/overview.md

Define a serializable model, create a store instance, and perform CRUD operations or observe updates.

```kotlin
import kotlin.io.path.Path
import kotlinx.serialization.Serializable

// Take any serializable model 
@Serializable data class Pet(val name: String, val age: Int) 

// Create a store
val store: KStore<Pet> = storeOf(file = Path("path/to/my_cats.json"))

// Get, set, update or delete values 
val mylo: Pet? = store.get()
store.set(mylo)
store.update { pet: Pet? ->
  pet?.copy(age = pet.age + 1)
}
store.delete()

// Observe for updates
val pets: Flow<Pet?> = store.updates
```

--------------------------------

### Initialize KStore with a file path

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Initializes a KStore instance using a file path. Ensure the appDir is configured correctly as per platform-specific documentation.

```kotlin
val store: KStore<Pet> = storeOf(file = Path("$appDir/my_cats.json"))
```

--------------------------------

### Configure KStore with factory options

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Demonstrates various configuration options including custom codecs, caching, versioning, migrations, and JSON serialization settings.

```kotlin
val store: KStore<Pet> = storeOf(
  // For kstore-file with json
  file = Path("$appDir/$fileName.json"),

  // Or for kstore-storage
  key = "$keyName",
  storage = localStorage, // optional
  
  // Or your own custom codec 
  codec = YourCustomCodec<Pet>(), // optional

  // Returns this value if the file is not found. Defaults to null
  default = null, // optional

  // Maintain a cache. If set to false, it always reads from disk
  enableCache = true, // optional

  // For versioning
  version = 0, // optional
  migration = { version, jsonElement -> default }, // optional

  // For kstore-file, the json serializer to use. 
  json = Json {
    ignoreUnknownKeys = true
    encodeDefaults = true
  }, // optional
)
```

--------------------------------

### Create Directories on Desktop

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/using-platform-paths.md

Ensure the target directories exist using SystemFileSystem before assigning them to path variables.

```kotlin
import kotlinx.io.files.Path
import kotlinx.io.files.SystemFileSystem

with(SystemFileSystem) { if(!exists(files)) createDirectories(files) }

files = Path(filesDir)
cache = Path(cacheDir)
```

--------------------------------

### Initialize KStore with Paths

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/using-platform-paths.md

Initialize KStore instances using the defined path variables.

```kotlin
val files: KStore<Pet> = storeOf(file = Path("$files/my_cats.json"))
val caches: KStore<Pet> = storeOf(file = Path("$cache/my_cats.json"))
```

--------------------------------

### Create a list store with listStoreOf

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage-list-store.md

Initializes a KStore for a list of pets, defaulting to an empty list instead of null.

```kotlin
val listStore: KStore<List<Pet>> = listStoreOf(file = Path("path/to/file"))
```

--------------------------------

### Initialize KStore with a storage key

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Initializes a KStore instance using a simple storage key.

```kotlin
val store: KStore<Pet> = storeOf(key = "my_cats")
```

--------------------------------

### Define KStore Dependencies in Version Catalog

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/installation.md

Define the KStore version and library modules in your version catalog TOML file.

```toml
[versions]
kstore = "x.x.x" 

[libraries]
kstore = { module = "io.github.xxfast:kstore", version.ref = "kstore" }
kstore-file = { module = "io.github.xxfast:kstore-file", version.ref = "kstore" }
kstore-storage = { module = "io.github.xxfast:kstore-storage", version.ref = "kstore" }
```

--------------------------------

### Resolve Paths on Desktop (JVM) using AppDirs

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/using-platform-paths.md

Use AppDirsFactory to determine user data and cache directories on JVM platforms.

```kotlin
import java.nio.file.FileSystem

const val PACKAGE_NAME = "io.github.xxfast.kstore"
const val VERSION = "1.0"
const val ORGANISATION = "xxfast"

val filesDir = AppDirsFactory.getInstance().getUserDataDir(PACKAGE_NAME, VERSION, ORGANISATION)
val cacheDir = AppDirsFactory.getInstance().getUserCacheDir(PACKAGE_NAME, VERSION, ORGANISATION)
```

--------------------------------

### Gradle Commands for Testing and API Management

Source: https://github.com/xxfast/kstore/blob/master/CLAUDE.md

Commands to run platform-specific test suites, execute single tests, check public API surface, and regenerate API dump files.

```bash
# Per-platform test suites (mirror the CI matrix)
./gradlew desktopTest                              # JVM
./gradlew testAndroidHostTest                      # Android (com.android.kotlin.multiplatform.library host tests)
./gradlew jsTest / wasmJsTest / linuxX64Test
./gradlew macosArm64Test iosSimulatorArm64Test     # Apple (on macOS)

# Single test
./gradlew :kstore:desktopTest --tests "io.github.xxfast.kstore.KStoreTests"

# Public API surface
./gradlew apiCheck      # CI runs this first; fails if public API drifts from checked-in *.api files
./gradlew apiDump       # regenerate *.api after an INTENTIONAL public API change, then commit it
```

--------------------------------

### Split Dependencies for Multiplatform Projects

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/installation.md

Configure platform-specific dependencies to accommodate browser limitations regarding file system access.

```kotlin
sourceSets {
  val commonMain by getting {
    dependencies {
      implementation(libs.kstore)
    }
  }
  
  val androidMain by getting { 
    dependencies { 
      implementation(libs.kstore.file) 
    } 
  }
  
  val iosMain by getting { 
    dependencies { 
      implementation(libs.kstore.file) 
    } 
  }
  
  val jvmMain by getting { 
    dependencies { 
      implementation(libs.kstore.file) 
    } 
  }

  val jsMain by getting {
    dependencies {
      implementation(libs.kstore.storage)
    }
  }

  val wasmJsMain by getting {
    dependencies {
      implementation(libs.kstore.storage)
    }
}
```

--------------------------------

### Configure Maven Central Repository

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/installation.md

Add the Maven Central repository to your project configuration to access KStore artifacts.

```kotlin
repositories { 
  mavenCentral()
  // or for snapshot builds
  maven("https://central.sonatype.com/repository/maven-snapshots/")
}
```

--------------------------------

### Include kstore-file in commonMain

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/installation.md

Add the kstore-file dependency to the commonMain source set for projects targeting Android, iOS, or Desktop.

```kotlin
sourceSets {
  val commonMain by getting {
    dependencies {
      implementation(libs.kstore.file)
    }
  }
}
```

--------------------------------

### Resolve Paths on Android

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/using-platform-paths.md

Retrieve filesDir and cacheDir from a Context within an Android Activity.

```kotlin
import kotlin.io.path.Path

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    files = Path(context.filesDir)
    cache = Path(context.cacheDir)
  }
}
```

--------------------------------

### Define Path Variables

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/using-platform-paths.md

Declare the path variables used for file and cache storage.

```kotlin
var files: Path
var cache: Path
```

--------------------------------

### Observe list store updates

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage-list-store.md

Observes the list store for updates as a Flow, defaulting to an empty list.

```kotlin
val pets: Flow<List<Pet>> = listStore.updatesOrEmpty
```

--------------------------------

### Set a value in the store

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Updates the store with a new value.

```kotlin
store.set(mylo)
```

--------------------------------

### Observe store updates

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Uses a Flow to observe changes to the stored value.

```kotlin
val pets: Flow<Pet?> = store.updates
```

--------------------------------

### Deriving fields for versioning

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/using-versioning.md

Use default values to derive new fields from existing ones without requiring explicit migration logic.

```kotlin
@Serializable data class CatV1(val name: String, val lives: Int = 9)
@Serializable data class CatV2(val name: String, val lives: Int = 9, val age: Int = 9 - lives)
```

--------------------------------

### Resolve Paths on iOS

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/using-platform-paths.md

Use NSFileManager to locate NSDocumentDirectory and NSCachesDirectory for iOS file storage.

```kotlin
val fileManager:NSFileManager = NSFileManager.defaultManager
val documentsUrl: NSURL = fileManager.URLForDirectory(
  directory = NSDocumentDirectory,
  appropriateForURL = null,
  create = false,
  inDomain = NSUserDomainMask,
  error = null
)!!

val cachesUrl:NSURL = fileManager.URLForDirectory(
  directory = NSCachesDirectory,
  appropriateForURL = null,
  create = false,
  inDomain = NSUserDomainMask,
  error = null
)!!

files = Path(documentsUrl.path)
caches = Path(cachesUrl.path)
```

--------------------------------

### Migrating binary incompatible changes

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/using-versioning.md

Define migration logic within the storeOf function to handle binary incompatible model changes by mapping older versions to the current model.

```kotlin
@Serializable
data class CatV1(
  val name: String,
  val lives: Int = 9,
  val cuteness: Int
)

@Serializable
data class CatV2(
  val name: String,
  val lives: Int = 9,
  val age: Int = 9 - lives, // derived field
  val kawaiiness: Long // new field
)

@Serializable
data class CatV3(
  val name: String,
  val lives: Int = 9, 
  val age: Int = 9 - lives, 
  val isCute: Boolean // renamed field 
)

val storeV3: KStore<CatV3> = storeOf(file = file, version = 3) { version, jsonElement ->
  when (version) {
    1 -> jsonElement?.jsonObject?.let {
      val name = it["name"]!!.jsonPrimitive.content
      val lives = it["lives"]!!.jsonPrimitive.int
      val age = it["age"]?.jsonPrimitive?.int ?: (9 - lives)
      val isCute = it["cuteness"]!!.jsonPrimitive.int.toLong() > 1
      CatV3(name, lives, age, isCute)
    }

    2 -> jsonElement?.jsonObject?.let {
      val name = it["name"]!!.jsonPrimitive.content
      val lives = it["lives"]!!.jsonPrimitive.int
      val age = it["age"]?.jsonPrimitive?.int ?: (9 - lives)
      val isCute = it["kawaiiness"]!!.jsonPrimitive.long > 1
      CatV3(name, lives, age, isCute)
    }

    else -> null
  }
}
```

--------------------------------

### Add or remove elements in list store

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage-list-store.md

Modifies the list store by adding or removing a specific pet element.

```kotlin
listStore.plus(pet)
listStore.minus(pet)
```

--------------------------------

### Delete or reset the store value

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Deletes the current value or resets it to the default value if one was configured.

```kotlin
store.delete()

store.reset()
```

--------------------------------

### Define a serializable model

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Defines a data class marked with @Serializable to be used with KStore.

```kotlin
@Serializable data class Pet(val name: String, val age: Int) // Any serializable
val mylo = Pet(name = "Mylo", age = 1)
```

--------------------------------

### Map elements in list store

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage-list-store.md

Transforms elements within the list store using map or mapIndexed operations.

```kotlin
listStore.map { pet -> pet.copy(age = pet.age + 1) }
listStore.mapIndexed { index, pet -> pet.copy(age = index) }
```

--------------------------------

### Update a value atomically

Source: https://github.com/xxfast/kstore/blob/master/docs/topics/usage.md

Updates the stored value using a mutex lock transaction to ensure consistency.

```kotlin
store.update { pet: Pet? ->
  pet?.copy(age = pet.age + 1)
}
```
Tokens:
Raw