key-count v1.2.2
key-count
key-count
is a simple JavaScript module for keeping collections of keyed integers that can be incremented/decremented and observed.
Install
npm install key-count --save
Usage
key-count
can easily be used to create a presence tracker:
import keyCount, { ADD, REMOVE } from 'key-count';
const presence = keyCount();
const unsubscribe = presence.subscribe(['users'], ({ type, payload }) => {
if (type === ADD) {
console.log(payload.key, 'came online');
} else if (type === REMOVE) {
console.log(payload.key, 'went offline');
}
});
presence.getCount(['users']); // 0
presence.increment('users', 'simon'); // 1 - "simon came online"
presence.increment(['users', 'simon']); // 2
presence.getCount(['users']); // 1
presence.getCount(['users', 'simon']); // 2
presence.decrement(['users', 'simon']); // 1
presence.decrement(['users', 'simon']); // 0 - "simon went offline"
unsubscribe();
API
The module exports a default function keyCount
which can be used to create a key-count
instance. An instance has the following shape:
{
decrement: (Path) => Number,
getCount: (Path) => Number,
increment: (Path) => Number,
remove: (Path) => Boolean,
subscribe: (Path, receiver:Function) => unsubscribe:Function,
subscribe: (receiver:Function) => unsubscribe:Function
}
A Path
can be a single value, an array of values or values spread across multiple arguments. For example, the following represent the same operation:
presence.increment('users', 'simon');
presence.increment(['users', 'simon']);
Events
The subscribe
function can either be called with a single argument or two or more arguments.
If a single argument is provided, it must be a receiver
function which will be called when any event is dispatched.
If two or more arguments are provided, arguments[0...arguments.length - 1]
will be flattened to create a Path
and the last argument will be treated as a receiver
function. Only events which affect the Path will cause the receiver to be called. For example, if you call subscribe('users', onChange)
then only mutations to direct children of the path will trigger the receiver (e.g. increment('users', 'simon')
).
The subscribe
function will return an unsubscribe
function which can be called to cancel the subscription.
The module exports four event type constants:
ADD
- A key has been added to a Path (key's value became1
).REMOVE
- A key has been removed from a Path (key's value became0
).INCREMENT
- A key's value has been increased.DECREMENT
- A key's value has decreased.
Each event dispatched has the following shape:
{ type: String, payload: { path: Array, key: String, count: Number } }
License
MIT