Skip to content

Commit 553deb1

Browse files
vinceglbvinceglb
authored
🔀 Merge pull request #458 from vinceglb/documentation-cookbook
📝 Documentation Cookbooks
2 parents d2ba747 + 4bc8f07 commit 553deb1

File tree

3 files changed

+193
-0
lines changed

3 files changed

+193
-0
lines changed

‎docs/cookbook/datastore.mdx‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: 'DataStore'
3+
description: 'Simplify DataStore setup in Kotlin Multiplatform'
4+
---
5+
6+
Setting up [DataStore](https://developer.android.com/kotlin/multiplatform/datastore) in Kotlin Multiplatform typically requires platform-specific code for each target. FileKit simplifies this by providing a unified path API.
7+
8+
## The Problem
9+
10+
The [official DataStore setup](https://developer.android.com/kotlin/multiplatform/datastore) requires `expect`/`actual` declarations with platform-specific implementations:
11+
12+
- **Android** needs `Context.filesDir`
13+
- **iOS** needs `NSDocumentDirectory`
14+
- **JVM** needs `System.getProperty("java.io.tmpdir")` or a custom path
15+
16+
This means writing and maintaining code in `androidMain`, `iosMain`, and `jvmMain` source sets.
17+
18+
## The Solution
19+
20+
With FileKit, you can define everything in `commonMain`:
21+
22+
```kotlin
23+
import androidx.datastore.core.DataStore
24+
import androidx.datastore.preferences.core.Preferences
25+
import androidx.datastore.preferences.core.PreferenceDataStoreFactory
26+
import io.github.vinceglb.filekit.FileKit
27+
import io.github.vinceglb.filekit.databasesDir
28+
import kotlinx.io.files.Path
29+
30+
fun createDataStore(fileName: String = "settings.preferences_pb"): DataStore<Preferences> =
31+
PreferenceDataStoreFactory.createWithPath {
32+
FileKit.databasesDir.resolve(fileName).path.toPath()
33+
}
34+
```
35+
36+
That's it! No platform-specific code needed.
37+
38+
## Complete Example
39+
40+
Here's a complete setup for a preferences manager:
41+
42+
```kotlin
43+
import androidx.datastore.core.DataStore
44+
import androidx.datastore.preferences.core.Preferences
45+
import androidx.datastore.preferences.core.booleanPreferencesKey
46+
import androidx.datastore.preferences.core.edit
47+
import androidx.datastore.preferences.core.PreferenceDataStoreFactory
48+
import io.github.vinceglb.filekit.FileKit
49+
import io.github.vinceglb.filekit.databasesDir
50+
import kotlinx.coroutines.flow.Flow
51+
import kotlinx.coroutines.flow.map
52+
53+
object AppPreferences {
54+
private val dataStore: DataStore<Preferences> = PreferenceDataStoreFactory.createWithPath {
55+
FileKit.databasesDir.resolve("app.preferences_pb").path.toPath()
56+
}
57+
58+
private val DARK_MODE_KEY = booleanPreferencesKey("dark_mode")
59+
60+
val darkMode: Flow<Boolean> = dataStore.data.map { preferences ->
61+
preferences[DARK_MODE_KEY] ?: false
62+
}
63+
64+
suspend fun setDarkMode(enabled: Boolean) {
65+
dataStore.edit { preferences ->
66+
preferences[DARK_MODE_KEY] = enabled
67+
}
68+
}
69+
}
70+
```
71+
72+
## Why `databasesDir`?
73+
74+
`FileKit.databasesDir` returns a platform-appropriate location for persistent data:
75+
76+
| Platform | Location |
77+
|----------|----------|
78+
| Android | App's internal databases directory |
79+
| iOS | `NSDocumentDirectory` |
80+
| macOS | `~/Library/Application Support/{bundle-id}` |
81+
| JVM | User's app data directory |
82+
83+
This ensures your preferences are stored in a safe, persistent location on each platform.
84+
85+
## Dependencies
86+
87+
Add the DataStore dependencies alongside FileKit Core:
88+
89+
```kotlin
90+
commonMain.dependencies {
91+
// FileKit Core
92+
implementation("io.github.vinceglb:filekit-core:<version>")
93+
94+
// DataStore
95+
implementation("androidx.datastore:datastore-preferences:<version>")
96+
}
97+
```

‎docs/cookbook/test-resources.mdx‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
title: 'Test Resources'
3+
description: 'Access test resources easily in Kotlin Multiplatform'
4+
---
5+
6+
Accessing test resources in Kotlin Multiplatform can be tricky. FileKit provides a simple solution with `FileKit.projectDir`.
7+
8+
## The Problem
9+
10+
In KMP, there's no built-in way to access files in your test resources folder across all platforms. Traditional approaches like `ClassLoader.getResource()` don't work consistently.
11+
12+
## The Solution
13+
14+
FileKit provides `FileKit.projectDir` which returns the root directory of your project. From there, you can easily navigate to your test resources:
15+
16+
```kotlin
17+
val resourceDirectory = FileKit.projectDir / "src/commonTest/resources"
18+
val testFile = resourceDirectory / "test-data.txt"
19+
```
20+
21+
## Example
22+
23+
Here's a complete example of a multiplatform test that reads a file from test resources:
24+
25+
```kotlin
26+
import io.github.vinceglb.filekit.FileKit
27+
import io.github.vinceglb.filekit.div
28+
import io.github.vinceglb.filekit.readString
29+
import kotlinx.coroutines.test.runTest
30+
import kotlin.test.Test
31+
import kotlin.test.assertEquals
32+
33+
class MyTest {
34+
private val resourceDirectory = FileKit.projectDir / "src/commonTest/resources"
35+
private val textFile = resourceDirectory / "hello.txt"
36+
private val imageFile = resourceDirectory / "image.png"
37+
38+
@Test
39+
fun readTestFile() = runTest {
40+
val content = textFile.readString()
41+
assertEquals(expected = "Hello, World!", actual = content)
42+
}
43+
44+
@Test
45+
fun checkFileExists() {
46+
assertTrue { textFile.exists() }
47+
assertTrue { imageFile.exists() }
48+
}
49+
}
50+
```
51+
52+
## Project Structure
53+
54+
Your test resources should be placed in the appropriate source set:
55+
56+
```
57+
my-project/
58+
├── src/
59+
│ ├── commonMain/
60+
│ ├── commonTest/
61+
│ │ ├── kotlin/
62+
│ │ │ └── MyTest.kt
63+
│ │ └── resources/
64+
│ │ ├── hello.txt
65+
│ │ └── image.png
66+
│ └── ...
67+
```
68+
69+
<Tip>
70+
Use the `/` operator (via `div`) to build paths in a readable way:
71+
72+
```kotlin
73+
val file = FileKit.projectDir / "src" / "commonTest" / "resources" / "data.json"
74+
```
75+
</Tip>
76+
77+
## Supported Platforms
78+
79+
`FileKit.projectDir` is available on all non-web platforms:
80+
81+
| Platform | Supported |
82+
|----------|-----------|
83+
| Android | ✅ |
84+
| iOS | ✅ |
85+
| macOS | ✅ |
86+
| JVM | ✅ |
87+
| JS | ❌ |
88+
| WASM | ❌ |
89+

‎docs/docs.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,13 @@
5454
"integrations/krop",
5555
"integrations/compose-media-player"
5656
]
57+
},
58+
{
59+
"group": "Cookbook",
60+
"pages": [
61+
"cookbook/datastore",
62+
"cookbook/test-resources"
63+
]
5764
}
5865
]
5966
},

0 commit comments

Comments
 (0)