README.md

Crux Key-Value Store capability

This crate contains the KeyValue capability, which can be used to ask the Shell to read from, and write to, a key-value store.

Currently it provides an interface for getting, setting, and deleting keys, checking if keys exists in the store, and listing keys that start with a prefix.

Getting Started

Add crux_kv as a dependency in your app's Cargo.toml.

Typegen

This crate has a feature called typegen which supports generation of code (e.g. in TypeScript, Swift, Kotlin etc.) for the types that the Capability passes over the bridge.

Crux apps usually contain a shared crate for the behavioural "core" and a shared_types crate that is responsible for generating the types that are shared between the core and the shell.

The shared crate can re-export the capability with a typegen feature that depends on the typegen feature of the Capability crate. This way, the shared crate can ask the Capability to register its types for type generation.

e.g. in the shared crate's Cargo.toml:

[features]
typegen = ["crux_core/typegen", "crux_kv/typegen"]

and in the shared_types crate's Cargo.toml:

[build-dependencies]
crux_core = { workspace = true, features = ["typegen"] }
shared = { path = "../shared", features = ["typegen"] }

About Crux Capabilities

Crux capabilities teach Crux how to interact with the shell when performing side effects. They do the following:

1. define a Request struct to instruct the Shell how to perform the side effect on behalf of the Core
2. define a Response struct to hold the data returned by the Shell after the side effect has completed
3. declare one or more convenience methods for invoking the Shell's capability, each of which creates a Command (describing the effect and its continuation) that Crux can "execute"

Note that because Swift has no namespacing, there is currently a requirement to ensure that Request and Response are unambiguously named (e.g. HttpRequest and HttpResponse).