State

State

Per-entity key-value store. All operations are keyed by (entity, key).

Constructor

import { State } from './src/state.js';

const state = new State();

---

Basic get / set

state.set('alice', 'score', 10);
state.get('alice', 'score');          // → 10
state.get('alice', 'missing', 0);    // → 0  (default value)
state.has('alice', 'score');          // → true
state.delete('alice', 'score');       // → true if existed
state.clearAll('alice');              // remove all keys for entity

---

Numeric helpers

state.increment('alice', 'score', 5);  // default by: 1
state.decrement('alice', 'score', 2);
state.addDefault('alice', 'score', 0); // set only if key doesn't exist
state.clamp('alice', 'score', 0, 100); // clamp current value in [0, 100]

---

Boolean flags

state.setFlag('alice', 'isReady');          // sets to true
state.setFlag('alice', 'isReady', false);   // explicit false
state.unsetFlag('alice', 'isReady');        // sets to false
state.toggleFlag('alice', 'isReady');       // flips
state.getFlag('alice', 'isReady');          // → boolean

---

Multi-value helpers

// Swap two keys
state.swap('alice', 'a', 'b');

// Copy value from one entity/key to another
state.copy('alice', 'score', 'bob', 'score');

// Compare
state.is('alice', 'rank', 'admin'); // → true if value === 'admin'

// Cycle through an array of values
state.toggle('alice', 'mode', ['walk', 'run', 'sprint']);
// each call advances to the next value, wraps around

---

Introspection

state.list('alice');   // → ['score', 'rank', ...]
state.listAll();       // → ['alice', 'bob', ...]