@gamestdio/state-listener
v3.1.0
Published
Deeply compare JavaScript objects and listen to changes.
Downloads
495
Readme
@gamestdio/state-listener
Deeply compare JavaScript objects and listen to changes. Used in colyseus.js
Usage
This library is meant for listening to changes in a JavaScript object.
import { StateContainer } from "@gamestdio/state-listener"
// Create the container instance.
let container = new StateContainer({
entities: {
one: { x: 10, y: 10 }
}
});
Listening to changes
container.listen("entities/:id/:attribute", (change: DataChange) => {
console.log(change.path.id, change.path.attribute, change.operation, change.value);
});
// Setting new data into the container will trigger the matching listeners
container.set({ entities: { one: { x: 20 } } });
// Console output
// => "one", "x", "replace", 20
// => "one", "y", "remove", undefined
On this example, two properties has been changed ("entities/one/x"
, and
"entities/one/y"
). Thus, the callback will be triggered twice.
Fallback listener
You can use a fallback listener when you're not sure how exactly the change will come. Useful during development process.
Please note that change.path
in the fallback listener will be an array
containing the full path to the property that has changed.
container.listen((change: DataChange) => {
console.log(change.path, change.operation, change.value);
})
// Setting new data into the container will trigger the matching listeners
container.set({ entities: { one: { x: 20 } } });
// Console output
// => ["entities", "one", "x"], "replace", 20
// => ["entities", "one", "y"], "remove", undefined
See tests for more usage examples.
Registering custom placeholders
Registering the placeholder:
container.registerPlaceholder(":xyz", /([xyz])/);
Using the matcher:
container.listen("entity/:id/:xyz", (change: DataChange) => {
myEntities[ change.path.id ][ change.path.xyz ] = change.value;
});
Built-in placeholders
:id
:/([a-zA-Z0-9\-_]+)/
:number
:/([0-9]+)/
:string
:/(\w+)/
:axis
:/^([xyz])$/
:*
:/(.*)/
When any other name is used starting with :
(e.g. :example
), *
will be
used by default.
Inspiration
The compare
method is highly based on
fast-json-patch
implementation.
License
MIT