Chariot.js

# Vial extends Map

An advanced data store extending a Map with additional, highly versatile utility methods. Similar in use to Collections, with the added benefit of being able to store any data structure imagineable, not limited to objects having preset Snowflake IDs. In addition data stored inside a Vial persists indefinitely and can coexist with duplicate entries, automatically managing key IDs.

# Constructor

Instantiation: new Vial();

Parameter Type Optional Default Description
No constructor parameters

# Properties

# first Read Only

The first item inside the Vial. This will return null if the Vial is empty or an array containing the first Key-Value pair.

Type: Array<Any>

# last Read Only

The last item inside the Vial. This will return null if the Vial is empty or an array containing the last Key-Value pair.

Type: Array<Any>

# size Read Only

How many items the Vial currently holds in total.

Type: Number

# Methods

# pourIn(...anything)

Store anything inside the Vial. If the data structure has no ID property, the Vial will generate a v4 UUID automatically. If an object gets provided of which the Snowflake is already present in the Vial, the object will be stored nevertheless.

Parameter Type Optional Default Description
...anything Any N/A Anything that needs to be stored inside of the Vial.
This may be as many arguments as needed.
Returns: Array<String>? A Snowflake or v4 UUID if only a single item was provided. An array of IDs otherwise.
Example:
const one = vial.pourIn({ username: 'Bob', age: 24 });   /* ⇨ 679bdf91-0833-45af-a43e-19eb3f7eee95 */
const two = vial.pourIn('Hi', { id: '1', name: 'Jim' }); /* ⇨ ['d7874876-a947-4cb1-9a59-793adb3a1e7a', '1'] */

# pourOut(identifier)

Pour out any item previously added by their identifier. Pouring an item from the Vial will remove the item irreversibly!

Parameter Type Optional Default Description
identifier String N/A An item's identifier (Snowflake or v4 UUID).
Returns: Any? The originally stored item inside the Vial or null if none was found.
Example:
const bobID   = vial.pourIn('Bob');  /* ⇨ 0dbe7f04-72fa-4957-a695-6da4e617569b */
const bob     = vial.pourOut(bobID); /* ⇨ Bob */
const unknown = vial.pourOut(bobID); /* ⇨ Null */

console.log(vial.size); /* ⇨ 0 */

# pourAll()

Pour out every item the Vial holds. This method will delete every item the Vial once held irreversibly!

Returns: Array<Any> An array containing every item the Vial once held.
Example:
const itemIds = vial.pourIn('John', 'Jess', { species: 'Cat', occupation: 'Pet' });
const items   = vial.pourAll(); /* ⇨ ['John', 'Jess', { species: 'Cat', occupation: 'Pet' }] */

console.log(vial.size); /* ⇨ 0 */

# incorporates(probe)

Test whether the Vial has at least one element satisfying the probe's condition

Parameter Type Optional Default Description
probe Function N/A A testing function that returns true or false
Returns: Boolean True if the Vial includes at least one element satisfying the probe's condition, otherwise false
Example:
const numberId = vial.pourIn(6);

console.log(vial.incorporates((item) => item === 6)); /* ⇨ True */

# incorporatesAll(probe)

Test whether ALL of the stored items within the Vial satisfy the probe's condition

Parameter Type Optional Default Description
probe Function N/A A testing function that returns true or false
Returns: Boolean True if the Vial includes ONLY elements satisfying the probe's condition, otherwise false
Example:
const one = vial.pourIn(1);
const two = vial.pourIn(2);

console.log(vial.incorporatesAll((item) => item >= 1)); /* ⇨ True */
console.log(vial.incorporatesAll((item) => item > 1));  /* ⇨ False */

# merge(operator [,initialDrip])

Runs an operator on each item of the Vial and returns a merged resulting value

Parameter Type Optional Default Description
operator Function N/A A function that takes the previous and next item
and returns a new resulting value
initialDrip Any First element An initial value passed to the operator function
Returns: Any A merged item resulting from running the operator on all items in the Vial
Example:
const numbers  = vial.pourIn(1, 2, 3);
const addUp    = (accumulator, currentValue) => accumulator + currentValue;
const multiply = (accumulator, currentValue) => accumulator * currentValue;

console.log(vial.merge(addUp));    /* ⇨ 6 */      // Because: (1 + 2 + 3)
console.log(vial.merge(multiply)); /* ⇨ 6 */      // Because: (1 * 2 * 3)
console.log(vial.merge(addUp), 3); /* ⇨ 9 */      // Because: (3 + 1 + 2 + 3)

# apply(operator)

Apply an operator on every item of the Vial and return the resulting items in an array

Parameter Type Optional Default Description
operator Function N/A A function taking an item from the Vial
and returning a new one in their place
Returns: Array<Any> An array containing all new applied items of the Vial
Example:
const items    = vial.pourIn(1, 2, 3);
const newItems = vial.apply((item) => item * 2);

console.log(newItems); /* ⇨ [2, 4, 6] */

# filter(operator)

Filter the entire Vial for items making the provided operator function evalute true

Parameter Type Optional Default Description
operator Function N/A A function taking an item and returning true if it matches
Returns: Array<Any>? An array containing all filtered items or null if none were found
Example:
const items = vial.pourIn(1, 2, 3);

console.log(vial.filter((item) => item >= 2));                 /* ⇨ [2, 3] */
console.log(vial.filter((item) => typeof item === 'string'));  /* ⇨ null */

# obtain(operator)

Get the first element from the Vial making the provided operator function evaluate true

Parameter Type Optional Default Description
operator Function N/A A function taking an item and returning true if it matches
Returns: Any? A found element from the Vial or null if none was found
Example:
const items = vial.pourIn(1, 2, 3);

console.log(vial.obtain((item) => item > 2));           /* ⇨ 3 */
console.log(vial.obtain((item) => item === 1));         /* ⇨ 1 */
console.log(vial.obtain((item) => item.id !== void 0)); /* ⇨ null */

# obtainRandom()

Get a random element from the Vial

Returns: Any? A random element or null if the Vial is empty
Example:
const items = vial.pourIn(1, 2, 3);

console.log(vial.obtainRandom()); /* ⇨ 1 or 2 or 3 */

← Colors →