How xxfast/kstore works
Project type and purpose
• Type: A Kotlin Multiplatform library (not an end-user application).
• Purpose: Provide a simple, coroutine-based, serialization-backed API for persisting and observing objects on disk or in JS storage, with caching, locking, migrations, and defaults.
File structure
Top-level modules:
– kstore (core API & common implementation)
– kstore-file (file-system backing for JVM/Native/Android/iOS)
– kstore-storage (JS/wasm browser & Node storage)
Each module uses the standard Kotlin MPP layout:
• commonMain – shared code (interfaces, codecs, caching, flows, locks)
• commonTest – shared tests
• platform-specific source sets (androidMain, desktopMain, jsMain, etc.)
Extract additional insights from the README
• Core features: read-write locks, in-memory cache, default values, migration support, multiplatform targets.
• Dependencies: kotlinx.coroutines, kotlinx.serialization, kotlinx.io (for file I/O in JS), Kotlin stdlib.
• Usage: client calls factory functions like storeOf(file=Path(...)) or platform storeOf(...) to get a KStore<T> instance, then invokes get(), set(), update(), delete(), or observes updates via Flow<T?>.
Main components and their relationships
A. KStore Core Module (kstore)
– Public API: interface KStore<T> with methods get(), set(), update(), delete(), and Flow<T?> updates.
– In-memory cache & read-write lock manager (FIFO mutex).
– Migration and default-value logic.
– Serialization glue (uses kotlinx.serialization).
B. File-backed Module (kstore-file)
– Implements KStore<T> for JVM/Native platforms using FileCodec + Kotlin I/O Path.
– Extensions: KListStore, KVersionedStore.
C. JS/Browser/Node Storage Module (kstore-storage)
– Implements KStore<T> using Storage and StorageCodec for web localStorage, Node fs or in-memory emulation.
D. External Dependencies
– kotlinx.coroutines (Flow, suspend functions)
– kotlinx.serialization (Serializable models)
– kotlin.io.path (JVM/Native file access)
– Platform storage APIs (localStorage, Node fs, etc.)
[Consumer Code]
↓ calls
[KStore Core API Module]
↙ ↘
[kstore-file] [kstore-storage]
↘ ↙
[File System] [Browser / Node Storage]
Architectural patterns & design principles
– Multiplexing by platform: single API surface (commonMain) + multiple implementations (PL-specific source sets).
– Layered design:
1. API layer (KStore interface)
2. Caching & locking layer (in-memory + mutex)
3. Serialization layer (Serializable ↔ JSON/Binary via codecs)
4. Transport layer (file I/O or JS storage)
– Extensibility points: custom codecs, custom storage backends, versioned migrations.