StateHoldr
General localStorage saving for collections of state.
Usage
StateHoldr is targeted for use in games where discrete areas within the game map may contain separate changes.
A house, for example, could contain a pot1
with { broken: boolean }
that should be retrieved when the area loads and saved when left.
This is referred to in StateHoldr as a "collection" of state.
Collections are serialized to JSON when switched into storage.
Constructor
const stateHolder = new StateHoldr();
collection
Starting collection to change within, if not ""
.
const stateHolder = new StateHoldr(
collection: "house",
});
The collection can later be changed with
.setCollection(collectionKey)
.
itemsHolder
Stores persistent changes locally.
If not provided, a new ItemsHoldr()
is used.
const itemsHolder = new ItemsHoldr();
const stateHolder = new StateHoldr({ itemsHolder });
prefix
Prefix to prepend to keys in storage.
Collections are stored under the prefix concatenated with their name.
A string[]
of collection keys (excluding the prefix) is stored under the prefix concatenated with "collectionKeys"
(exported from "stateholdr"
as collectionKeysItemName
).
const itemsHolder = new ItemsHoldr();
const stateHolder = new StateHoldr({
collection: "house",
itemsHolder,
prefix: "MyStateHoldr::",
});
itemsHolder.getItem("MyStateHoldr::collectionKeys"); // ["house"]
addChange
Parameters:
-
itemKey: string
: Key of the item to add a change under. -
attribute: string
: Attribute of the item being changed. -
value: any
: Value under the attribute to change.
Adds a change to an object under the current collection.
stateHolder.addChange("pot1", "broken", true);
stateHolder.getChanges("pot1"); // { broken: true }
addChangeToCollection
Parameters:
-
otherCollectionKey: string
: Key of the collection to change within. -
itemKey: string
: Key of the item to add a change under. -
attribute: string
: Attribute of the item being changed. -
value: any
: Value under the attribute to change.
Adds a change to an object under a named collection.
stateHolder.setCollection("outdoors");
stateHolder.getChanges("pot1"); // {}
stateHolder.addChangeToCollection("house", "pot1", "broken", true);
stateHolder.setCollection("house");
stateHolder.getChanges("pot1"); // { broken: true }
applyChanges
Parameters:
-
itemKey: string
: Key of a contained item. -
output: Object
: Recipient for all the changes.
Copies all changes from a contained item into an output item. Useful when creating objects whose state is reflected by a collection's storage.
const pot = {};
stateHolder.addChange("pot1", "broken", true);
stateHolder.applyChanges("pot1", pot);
pot; // { broken: true }
getChanges
Parameters:
-
itemKey: string
: Key of a contained item.
Returns: Any changes under the itemKey, or {}
if there were none.
stateHolder.addChange("pot1", "broken", true);
stateHolder.getChanges("pot1"); // { broken: true }
setCollection
Parameters:
-
collectionKey: string
: Key of a new collection to switch to. -
value: Object
(optional): Container to override any existing state with.
Sets the currently tracked collection.
stateHolder.addChangeToCollection("house", "pot1", "broken", true);
stateHolder.setCollection("house");
stateHolder.getChanges("pot1"); // { broken: true }
The previous collection is saved to storage.
saveCollection
Saves the currently tracked collection into storage.
stateHolder.setCollection("house");
stateHolder.addChange("pot1", "broken", true);
itemsHolder.getItem("MyStateHoldr::house"); // {}
stateHolder.saveCollection();
itemsHolder.getItem("MyStateHoldr::house"); // { broken: true }
Development
This repository is a portion of the EightBittr monorepo.
See its docs/Development.md for details on how to get started.
Running Tests
yarn run test
Tests are written in Mocha and Chai.
Their files are written using alongside source files under src/
and named *.test.ts?
.
Whenever you add, remove, or rename a *.test.t*
file under src/
, watch
will re-run yarn run test:setup
to regenerate the list of static test files in test/index.html
.
You can open that file in a browser to debug through the tests, or run yarn test:run
to run them in headless Chrome.