KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #cli #claude-code #mcp #rust #deepseek-harness #ai-agent

shoebox

★ 49 Open GitHub ↗

ShoeBox is a Kotlin library for persistent data storage that supports views and the observer pattern. While often used with Kweb, it doesn't need to be.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ShoeBox

[![](https://jitpack.io/v/kwebio/shoebox.svg)](https://jitpack.io/#kwebio/shoebox)

ShoeBox is a [Kotlin](http://kotlinlang.org/) library for object persistence that supports the 
[observer pattern](https://en.wikipedia.org/wiki/Observer_pattern) so your code can be notified immediately when 
stored data is changed.

### Motivation

While it is a standalone library, ShoeBox was created as a persistence layer for [Kweb](http://kweb.io/) applications, 
motivated by the lack of a simple persistence mechanism that supports the observer pattern.  The idea is to create a 
"bridge" library between Shoebox and Kweb that will allow "binding" of UI components to persistent state, also known as 
the [data mapper pattern](https://en.m.wikipedia.org/wiki/Data_mapper_pattern).
[Here is a video](https://www.youtube.com/watch?v=0Q-BUldFZjA) illustrating this idea for TornadoFX on Android.

To emphasize, however, Shoebox doesn't depend on Kweb and should be useful for many other things.

### Features
* Functionality similar to MutableMap
* Add listeners for object addition, deletion, and modification
* Fairly comprehensive [unit tests](https://github.com/sanity/shoebox/tree/master/src/test/kotlin/com/github/sanity/shoebox)
* Lightweight, pulls in very few dependencies
* Materialized views
  * Efficiently retrieve objects by any specified key derived from the object
  * Similar to database indexes, but also supporting the observer pattern
* Currently data is stored as uncompressed files, serialized to JSON

### Limitations
* Not very space efficient for small objects as files take up at least 4K on many filesystems
* Data isn't currently compressed
* Directories can't be shared between different Shoebox instances, although this is planned
  * Once this is supported we can use [shared filesystems](https://aws.amazon.com/blogs/aws/amazon-elastic-file-system-shared-file-storage-for-amazon-ec2/)
    to scale horizontally, limited only by the filesystem
* Doesn't implement the [MutableMap](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-mutable-map/) interface
  * Even though the semantics are very similar to MutableMap, it isn't currently implemented because we wanted to avoid
    loading all data into memory.  
  * This is probably solvable through custom implementations of MutableSet, MutableEntry and other interfaces, and
    will probably be done before 1.0 is released.

### Adding to your project
Shoebox can be added easily to your Maven or Gradle project through Jitpack:

[![Release](https://jitpack.io/v/kwebio/shoebox.svg)](https://jitpack.io/#kwebio/shoebox)

As of release 0.4.0 Shoebox uses Kotlin Serialization, so you will also need to add [the serialization plugin](https://github.com/Kotlin/kotlinx.serialization#gradle) to your project.

### Simple Usage Example
```kotlin
fun main() {
    val dir = Files.createTempDirectory("sb-")
    val userStore = shoebox(dir.resolve("users"), User.serializer())
    val usersByEmail = userStore.view("usersByEmail", User::email)
    val usersByGender = userStore.view("usersByGender", User::gender)

userStore["ian"] = User("Ian Clarke", "male", "ian@blah.com")
    userStore["fred"] = User("Fred Smith", "male", "fred@blah.com")
    userStore["sue"] = User("Sue Smith", "female", "sue@blah.com")

println(usersByEmail["ian@blah.com"])   // [User(name=Ian Clarke, gender=male, email=ian@blah.com)]
    println(usersByGender["male"])          // [User(name=Ian Clarke, gender=male, email=ian@blah.com),
                                            // User(name=Fred Smith, gender=male, email=fred@blah.com)]
    // note: view["xx]" returns a set of values
    usersByGender.onAdd("male") { kv ->
        println("${kv.key} became male")
    }
    usersByGender.onRemove("male") { kv ->
        println("${kv.key} ceased to be male")
    }

userStore["fred"] = userStore["fred"]!!.copy(gender = "female") // Prints "fred ceased to be male"
}

@Serializable data class User(val name : String, val gender : String, val email : String)

```

### Documentation
* API
  * [0.4.12](https://jitpack.io/com/github/sanity/shoebox/0.4.12/javadoc/)
  * [SNAPSHOT](https://jitpack.io/com/github/sanity/shoebox/-SNAPSHOT/javadoc/) (might be slow to load)

shoebox

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README