basic-collection

A generic collection class to contain array-like data.

Table of contents:

• Installation
• Usage
  • Example 1: Basic usage
  • Example 2: Creating custom collections
  • Example 3: Filtering values
• API
  • new BasicCollection( parameters )
  • .normalize( key )
  • .set( key, value )
  • .get( key[, default] )
  • .has( key )
  • .remove( key )
  • .clear()
  • .each( callback )
  • .filterByKey( pattern )
  • .filterByValue( pattern )
  • .size
  • .entries
  • .keys
  • .values
• Tests

Installation

$ npm install basic-collection

Usage

You can load basic-collection like a typical node module or using the global variable basicCollection:

let Collection = require( "basic-collection" );
// or...
let Collection = window.basicCollection;

Example 1: Basic usage

import BasicCollection from "basic-collection";
 
let Collection = new BasicCollection;
 
Collection.set( "key_1", "value_1" );
Collection.set( "key_2", "value_2" );
Collection.set( 1234567, true );
 
Collection.get( "key_1" ); // value_1
Collection.get( "key_2" ); // value_2
Collection.get( "key_3", "default" ); // default
 
Collection.has( "key_1" ); // true
Collection.has( "key_2" ); // true
Collection.has( "key_3" ); // false
 
Collection.remove( "key_2" );
console.log( Collection.size ); // 2
console.log( Collection.keys ); // [ 'key_1', 1234567 ]
console.log( Collection.values ); // [ 'value_1', true ]
console.log( Collection.entries ); // [ [ 'key_1', 'value_1' ], [ '1234567', 'true' ] ]
 
Collection.each( ( key, value, map ) => {
    console.log( `Collection[${key}] = ${value}` );
} );
 
Collection.clear();
console.log( Collection.size ); // 0

Example 2: Creating custom collections

import BasicCollection from "basic-collection";
 
class MyCollection {
    constructor( parameters ) {
        super( parameters );
    }
 
    normalize( key ) {
        return `transformed_${key}`;
    }
};
 
let Collection = new MyCollection;
 
Collection.set( "key_1", "value_1" );
Collection.set( "key_2", "value_2" );
 
console.log( Collection.keys );
// => [ 'transformed_key_1', 'transformed_key_2' ]

Example 3: Filtering values

You can filter data using patterns. A pattern can contain wildcards. There are predefined wildcards by a basic collection:

[digit]     // Match /([0-9]+)/
[alnum]     // Match /([0-9A-Za-z]+)/
[alpah]     // Match /([A-Za-z]+)/
[xdigit]    // Match /([0-9A-Fa-f]+)/
[punct]     // Match /([\p{P}\d]+)/
[print]     // Match /([\x20-\x7e]*)/
[upper]     // Match /([A-Z]+)/
[lower]     // Match /([a-z]+)/
[all]       // Match /(.*?)/

import BasicCollection from "basic-collection";
 
let Collection = new BasicCollection;
 
Collection.set( "key_1", "value_1" );
Collection.set( "key_2", "value_2" );
Collection.set( "test1", "1_abc" );
Collection.set( "test2", "2_def" );
 
Collection.filterByKey( "key_[digit]" );
// => [ 'key_1', 'key_2' ]
 
Collection.filterByValue( "[digit]_[lower]" );
// => [ '1_abc', '2_def' ]

API

new BasicCollection( parameters )

Creates a new BasicCollection instance with custom parameters in [ [ 'key1', 'value1' ], [ 'key2', 'value2' ] ] format.

.normalize( key )

Normalizes data key.

.set( key, value )

Sets an attribute for the current collection. If the attribute name already exists, its value will be overwritten.

.get( key[, default] )

Returns an attribute of the collection or a default value if the key does not exist.

.has( key )

Checks if an attribute exists in the current collection.

.remove( key )

Removes an attribute from the current collection.

.clear()

Clears all values.

.each( callback )

Executes a callback for each element of this Collection.

.filterByKey( pattern )

Returns keys that match a pattern.

.filterByValue( pattern )

Returns values that match a pattern.

.size

Counts parameters.

.entries

Returns a new Iterator object that contains an array of [key, value] for each element in the Collection in insertion order.

.keys

Returns a new Iterator object that contains the keys for each element in the Collection in insertion order.

.values

Returns a new Iterator object that contains the values for each element in the Collection in insertion order.

Tests

$ npm test