pxg-collection

WARNING

This module has been deprecated. Please use the latest release of dictionaryjs which now supports all es6 features.

See:

• https://www.npmjs.com/package/dictionaryjs
• https://github.com/phanxgames/dictionaryjs

PXG Collection

A Collection (Associative Array like) Class for ES6. Now supporting dot and bracket without a proxy, and generator/yield control flows.

Features

• Stores key/value pairs within a Associative Array like collections.
• Use dot operator and brackets to access keys.
• Remove key using the DELETE operator.
• Iterator to support for..of looping.
• Generator/yield async control flow (via suspend module) support.
• Set and Get methods for accessing keys.
• GetDefault method with default value if value is not found.
• Remove method to remove key from collection.
• Size method to get total key count within collection.
• Built-in forEach and asyncForEach methods for looping.
• Empty and asyncEmpty to remove all entries from collection.
• Has method checking if key is within collection.

Install

npm install pxg-collection

Requirements

• ECMAScript 2015 (ES6)
• Node.JS 6.2.2 or later (tested on 6.2.2)

You may find the older version (with less features) but will work with older version of Node.js: dictionaryjs

Proxy Version

A version made with Proxy is also available which will automatically invalidate keys: dictionaryjs-es6

However, do note: node.js (v8/chromium) has a known bug when debugging around Proxy, which is the reason why this new Collection class was made.

Basic Example

let Collection = require("pxg-collection");
let collection = new Collection();

collection.set("bob.smith","[e-mail]");
collection.["john.doe"] = "[e-mail]";

console.log(collection["bob.smith"]);

collection.empty();

Constructor

let collection = new Collection(resume, cacheKeys);

Where:

• resume - the reference to the suspend library's resume factory
• cacheKeys - (default false) - if keys should be cached

Caching keys should only be enabled if you plan to strictly use the set(key,value) method, or if you plan to invalidate() yourself manually.

Accessing and Setting Keys

You may access keys using the get/set methods, but also using the dot operator and brackets.

Standard get/set methods:

collection.set("key","value");
let out = collection.get("key);

Dot operator:

collection.key = "value";
let out = collection.key;

Bracket operators:

collection["key"] = "value";
let out = collection["key"];

You may also use the getDefault(key,defaultValue) method if the key was not found (or is null):

let out = collection.getDefault("test","not found");

Checking if Key exists

if (collection.has("key")) {
    //..
}
if (collection.hasOwnProperty("key")) {
    //..
}

Deleting Keys

To remove a key, you may use the remove(key) method, or the delete operator:

collection.remove("key");
//or...
delete collection["key"];

To empty the collection:

//blocking
collecton.empty();

//non-blocking:
collection.asyncEmpty(function() {
    //on completion
});

Looping through keys

ForEach (Blocking)

collection.forEach(function(key,value) {
    console.log(key,value);
});

AsyncForEach (Non-Blocking)

collection.asyncForEach(function(key,value,cbNext) {
    console.log(key,value);
    cbNext();
});

Using the (for...of) loop:

Each value within the collection can be accessed in a for...of loop. This is blocking.

for (let value of collection) {
    console.log(value);
}

To loop through each key within the collection you may use the for...in loop. This is blocking.

for (let key in collection) {
    console.log(key + "=" + collection[key]);
}

Getting the Collection Size:

//using the size method:
console.log("Collection size:", collection.size());

//using the length property:
console.log("Collection size:", collection.length);

Generator/yield Async control flow using Suspend (recommended)

Using the suspend module you may write async code using the new yield command. Here is an example that will show how you can write async code in a very clean manner:

var Collection = require("pxg-collection");

var suspend = require("suspend"),
	resume = suspend.resume;

var collection = new Collection(resume);

//setup collection with some test values:
collection["foo"] = "bar";
collection["its a me"] = "mario";
collection["hello"] = "bye";

suspend(function*() {

	console.log("Collection contains:");

	//looping (non blocking)
	yield collection.asyncForEach(function(index,item,cbNext) {
		console.log("   ",index,item);
		cbNext();
	});

	console.log("Looping complete...");


	console.log("Emptying collection:");

	//emptying (non blocking)
	yield collection.asyncEmpty();

	console.log("Empty complete...");


})();

Other methods

These methods you may not find useful, but are documented in case you do:

• getKeys() - Returns an array of keys
• invalidate() - Invalidates the keys, used if you enable caching
• setResume(resume) - used to set the suspend.resume reference, usually set in the constructor.