StateHoldr/README.md

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

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.