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

After forking the repo from GitHub:

git clone https://github.com/<your-name-here>/StateHoldr
cd StateHoldr
npm install
npm run setup
npm run verify

npm run setup creates a few auto-generated setup files locally.
npm run verify builds, lints, and runs tests.

Building

npm run watch

Source files are written under src/ in TypeScript and compile in-place to JavaScript files. npm run watch will directly run the TypeScript compiler on source files in watch mode. Use it in the background while developing to keep the compiled files up-to-date.

Running Tests

npm 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 npm 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.