itc-foundation v0.3.0

itc-foundation

Namespaces

lang

Usage

import {lang} from 'itc-foundation';

Terminology

collection

an instance of Object, Array, Map or Set

entry

a two-element tuple that represents a key-value pair

entries

an Array of key-value pair tuples

Functions

.empty(value)

• Boolean false, null, and undefined are empty
• Integer zero is empty
• Number other than integer zero is not empty
• NaN is not empty
• Zero-length string is empty
• Zero-length array is empty
• Object that owns no properties is empty
• Map with no keys is empty
• Set with no values is empty

.assign(recipient, donor1, donor2, ... donorN)

Works like Object.assign().

Example

let recipient = {name: 'Scooby Doo', age: 5};
let donor1 = {age: 6, occupation: 'actor'};
let donor2 = {occupation: 'scaredy cat',

lang.assign(recipient, donor1, donor1);
>>> {name: 'Scooby Doo', age: 6, occupation: 'scaredy-cat'}

.keys(collection)

Return an array containing the supplied collection's keys.

Example

let collection = new Map();
collection.set('foo', 1);
collection.set('bar', 2);

lang.keys(collection);
>>> ['foo', 'bar']

.values(collection)

Example

let collection = new Map();
collection.set('foo', 1);
collection.set('bar', 2);

lang.values(collection);
>>> [1, 2]

Return an array containing the supplied collection's values.

.entries(collection)

Represent the collection as entries.

Example

let collection = new Map();
collection.set('foo', 1);
collection.set('bar', 2);

lang.entries(collection);
>>> [['foo', 1], ['bar', 2]]

.size(collection)

Return the number of entries in the collection.

.reduce(collection, reducer, initial)

Iteratively reduce a collection to a single value.

Example

let collection = new Map();
collection.set('foo', 1);
collection.set('bar', 2);

let sum = (result, value, key, collection) => result + value;

lang.reduce(collection, sum, 0);
>>> 3

.reduce.until(collection, reducer, initial, breakpoint)

Iteratively reduce a collection to a single value until a truth test passes.

The breakpoint argument is a function that breaks the iteration loop. It receives the same arguments as the reducer. Reduction will continue until the function returns a truthy value.

Example

let fibonacci = [1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let sum = (result, value, key, collection) => result + value;

// break out of the reduction sequence if the current value is 5 or greater
let breakpoint = (result, value, key, collection) => value >= 5;

lang.reduce.until(fibonacci, sum, 0, breakpoint);
>>> 7

.map(collection, fn)

Return an array containing the collection values mapped through the mapping function fn.

Example

let collection = new Set[0, 1, 2, 3, 4]);
let squared = (x) => x * x;

lang.map(collection, squared);
>>> [0, 1, 4, 9, 16]

.map.until(collection, fn, breakpoint)

Works like .map(), but accepts a breakpoint function that receives the same arguments as the mapping function fn.

Example

let collection = new Set([0, 1, 2, 3, 4]);
let squared = (x) => x * x;
let breakpoint = (x) => x > 2;

lang.map.until(collection, squared, breakpoint);
>>> [0, 1, 4]

.filter(collection, fn)

Return an array containing the values of the collection that pass a truth test fn.

Example

let collection = new Map([['a', 0], ['b', 1], ['c', 2], ['d', 3]]);
let even = (x) => x % 2 === 0;

lang.filter(collection, even);
>>> [0, 2]

.first(collection, fn)

Return the first value of the collection that passes a truth test fn. Return the very first enumerable value in the collection if the truth test is not supplied.

Example

let collection = {a: 2, b: "Scooby Doo", c: 3};
let nan = (v) => typeof v !== 'number';

lang.first(collection, nan);
>>> "Scooby Doo"

lang.first(collection);
>>> 1

tree

Usage

import {tree} from 'itc-foundation';

Tree

Tree wraps a data object with an interface that allows consumers to resolve values path expressions.

Options

data        the object to be wrapped with the Tree interface
delimiter   path expresssion token boundary
tokenize    a function that converts a path expression into tokens
normalize   a function that normalizes a path expression
cache       optional caching strategy that has an ES6 Map-like interface; defaults to a dummy cache

Methods

.path(expr)

Given a path expression expr, traverse the data object structure and return the matching value.

Example

let teams = new tree.Tree({
  data: {
    nfc: {
      west: [
        {
          home: 'San Francisco',
          name: '49ers',
        },
      ],
      east: []
    },
  },
});

teams.path('nfc/west/0/name');
>>> 49ers

teams.path('nfc/east');
>>> []

Example with custom path delimiter

let teams = new Tree({
  delimiter: '.'
  data: {
    nfc: {
      west: [
        {
          home: 'San Francisco',
          name: '49ers',
        },
      ],
    },
  },
});

teams.path('nfc.west.0.name');
>>> 49ers

Example with caching (ES6 Map strategy)

let teams = new Tree({
  cache: new Map(),
  data: {...}
});

translation

Usage

import {translation} from 'itc-foundation';

Translator

Translator is an object that converts translations to human-readable strings.

Options

tree          a Tree object
suppress      if truthy, the translate() method will return an empty string if a translation does not exist
substitute    placeholder substitution algorithm

Methods

.translate(translation, subs)

Given a translatable string translation, return a human-readable string matching that translation.

Example

let translations = new tree.Tree({
  data: {
    greetings: {
      hello: 'Hello!',
      yo: 'Yo :subject',
    },
  },
});

let translator = new translation.Translator({translations});

translator.translate('greetings.hello');
>>> Hello!

translator.translate('greetings.yo', {subject: 'Adrian'});
>>> Yo Adrian