magi-codex

magi-codex

magi-codex provides type-indexed, thread-safe storage primitives that make it easy to organise state by the types it is associated with. The crate exposes two primary data structures:

• CodexMap: a multi-value store keyed by (K, V) type pairs, backed by DashMap, allowing you to keep independent maps for different value types while sharing a single handle.
• CodexSet: a per-type singleton store that keeps at most one value for each type, ideal for configuration, global resources, or any data that should exist once.

Both collections are cheap to clone—they share the same underlying storage via Arc—and they provide closure-based access APIs so you can work with data while holding the lock only as long as needed.

CodexMap

CodexMap behaves like many distinct hash maps indexed by their (K, V) type pairs. You can insert, check for existence, iterate, remove entries, and clone values by key. A key feature is composition queries: methods such as contains2, with3, with4_mut, and get3_cloned let you read or mutate multiple component types that share the same key in a single call—perfect for Entity Component System (ECS) style workloads.

use magi_codex::CodexMap;

#[derive(Clone)]
struct Position { x: f32, y: f32 }

#[derive(Clone)]
struct Velocity { dx: f32, dy: f32 }

let map = CodexMap::new();
map.insert("player", Position { x: 0.0, y: 0.0 });
map.insert("player", Velocity { dx: 1.0, dy: 0.5 });

// Mutate multiple components together
map.with2_mut::<&str, Position, Velocity, _, _>(&"player", |pos, vel| {
    pos.x += vel.dx;
    pos.y += vel.dy;
});

See examples/composition_queries.rs for a longer ECS-inspired walkthrough that demonstrates querying and mutating two, three, or four component types at once.

CodexSet

CodexSet stores a single value for each concrete type. Insertions replace any existing value of that type, and you can access data immutably or mutably via closures, clone it out, or take ownership and remove it.

use magi_codex::CodexSet;

#[derive(Clone)]
struct Config { debug: bool }

let set = CodexSet::new();
set.insert(Config { debug: true });

let debug_enabled = set.with::<Config, _, _>(|cfg| cfg.debug).unwrap();
assert!(debug_enabled);

Testing

The crate ships with comprehensive unit tests covering insertion, removal, mutation, cloning, iteration, and the composition-query APIs for both CodexMap and CodexSet.