@gik/tools 0.2.5

A tools suite for Node / Javascript development.

Contributors

• Héctor Menéndez

Supported platforms

• darwin
• linux

Table of contents

• thrower Errors with pretty stack and customizable name.
• streamer An utility belt for our most common operations with RXJS's Observables.
  • fromAccess member Determine if given path is accessible.
  • fromStat member Determine statistics about a file system node.
  • fromSpawn member Spawn a shell command.
  • fromDirMake member Creates a directory.
  • fromDirRequire member Requires a directory path, if the directory does not exists, it's created.
  • fromDirRead member Get path of nodes in given directory (non recursively).
  • fromDirReadRecursive member Get path of nodes in given directory (recursively).
  • fromFileRead member Reads a file from the disk.
  • fromFileWrite member Writes a file on the disk.
• server A minimal webserver using RxJS Observables.
• populator Allows properties in an object to inherit values from sibling properties.
• mapper Generates a flattened object containing a map for all the properties
• logger A wrapper around pino.
• checker A minimal type-checker for JavaScript purists.
  • is Determine if given value really belongs to the corresponding type.
    • objectEmpty member Determine if an element is an object and has no keys
    • string member Determines if value is really a string.
    • number member Determines if value is really a number.
    • array member Determines if value is really an array.
    • function member Determines if value is really a function.
    • regexp member Determines if value is really a regexp.
    • boolean member Determines if value is really a boolean.
    • object member Determines if value is really an object.
  • props function Validates properties of given object.

thrower

Errors with pretty stack and customizable name.

• Standalone version.
• Report a Bug.

Parameters

Returns

Error - A custom error instance with a pretty stack.

Example

Thrower('test'); // A standard Error with prettified stack
Thrower(new TypeError('test2')); // Standard TypeError with prettified stack
Thrower('test3', 'TestError'); // Custom TestError with 'test3' as message
Thrower(['hola %s', 'mundo'], 'HelloError'); // HelloError with 'hola mundo' as message
const Err = Thrower('bad boy', 'CanineError', false); // Returns CanineError instance.

▲ Top

streamer

An utility belt for our most common operations with RXJS's Observables.

• Standalone version.
• Report a Bug.

To do

• [ ] Add unit tests for all operators.

Members

• fromAccess
• fromStat
• fromSpawn
• fromDirMake
• fromDirRequire
• fromDirRead
• fromDirReadRecursive
• fromFileRead
• fromFileWrite

▲ Top

fromAccess

static property of streamer

Determine if given path is accessible.

Parameters

Returns

StreamBoolean - Wether the file is accessible or not.

▲ Top

fromStat

static property of streamer

Determine statistics about a file system node.

Parameters

Returns

StreamStat - stat object for the node.

Throws

• Error - When given an invalid node.

▲ Top

fromSpawn

static property of streamer

Spawn a shell command.

Parameters

Returns

StreamOutput - Each chunk of either stdout or stderr data.

▲ Top

fromDirMake

static property of streamer

Creates a directory.

Parameters

Returns

StreamString - The path of the directory that was just created.

Throws

• Error - When directory cannot be created.

▲ Top

fromDirRequire

static property of streamer

Requires a directory path, if the directory does not exists, it's created.

Parameters

Returns

Array.<StreamString> - The path of the directory.

Throws

• Error - When requested path exists and is not a directory.

▲ Top

fromDirRead

static property of streamer

Get path of nodes in given directory (non recursively).

Parameters

Returns

Array.<StreamDirNode> - The path of the directory.

Throws

• Error - When requested path exists and is not a directory.

▲ Top

fromDirReadRecursive

static property of streamer

Get path of nodes in given directory (recursively).

Parameters

Returns

StreamPath - The path of the directory.

Throws

• Error - When requested path exists and is not a directory.

▲ Top

fromFileRead

static property of streamer

Reads a file from the disk.

Parameters

Returns

Observable.<string> - The contents of the file.

▲ Top

fromFileWrite

static property of streamer

Writes a file on the disk.

Parameters

Returns

Observable.<string> - The future value true if write was succesful.

Throws

• Error - When the file cannot be written.

▲ Top

server

A minimal webserver using RxJS Observables.

• Standalone version.
• Report a Bug.

Parameters

Returns

Subscription Observable - if subscription mode was enabled a subscription would be returned, otherwise an observable is returned.

▲ Top

populator

Allows properties in an object to inherit values from sibling properties. This specially useful when creating JSON configuration files.

• Standalone version.
• Report a Bug.

Parameters

Returns

Object - An object copy with references replaced.

Example

const subject = {
    a: { b: { c: 'world' } },
    d: "hello ${a.b.c}${e}",
    e: "!!!",
    f: ["${e}", "${a.b.c}"]
};
const result = Populator(subject);
// result:
// { a: { b: { c: 'world' } }, d: "hello world!!!", e: "!!!", f: ["!!!", "world"] };

▲ Top

mapper

Generates a flattened object containing a map for all the properties available on subject.

• Standalone version.
• Report a Bug.

Parameters

Returns

mapperResult - A flattened object.

Throws

• mapperTypeError

Example

const subject = {
    a: {
        b: {
           d: true,
           e:  {
               g: 'foo'
           }
        },
        f: undefined,
    }
};
const result = Mapper(subject);
// result:
// { 'a.b.d': true, 'a.b.e.g': 'foo', 'a.f': undefined }

▲ Top

logger

A wrapper around pino.

• Standalone version.
• Report a Bug.

Behaviour

• When the environment is non-production it will output prettier logs.

• All calls to error will use @gik/tools-thrower halting the execution when the environment is non-production (ie: development) however, when in production, it will fallback to Pino's default logger.

• When the environment is set as production it will load extreme-mode adding an even faster approach to logging. (make sure to read the documentation about the caveats)

Parameters

Returns

Types.Instance - A function that you can use for logging.

Throws

• Types.ParamTypeError - When parameters are not valid.

▲ Top

checker

A minimal type-checker for JavaScript purists.

• Standalone version.
• Report a Bug.

Members

• is
• props

▲ Top

is

Determine if given value really belongs to the corresponding type.

Members

• objectEmpty
• string
• number
• array
• function
• regexp
• boolean
• object

▲ Top

objectEmpty

static property of checker.is

Determine if an element is an object and has no keys

Parameters

Returns

boolean - Whether the object is empty or not.

▲ Top

string

static property of checker.is

Determines if value is really a string.

Parameters

Returns

boolean - Wheter value is string or not.

▲ Top

number

static property of checker.is

Determines if value is really a number.

Parameters

Returns

boolean - Wheter value is number or not.

▲ Top

array

static property of checker.is

Determines if value is really an array.

Parameters

Returns

boolean - Wheter value is array or not.

▲ Top

function

static property of checker.is

Determines if value is really a function.

Parameters

Returns

boolean - Wheter value is function or not.

▲ Top

regexp

static property of checker.is

Determines if value is really a regexp.

Parameters

Returns

boolean - Wheter value is regexp or not.

▲ Top

boolean

static property of checker.is

Determines if value is really a boolean.

Parameters

Returns

boolean - Wheter value is boolean or not.

▲ Top

object

static property of checker.is

Determines if value is really an object.

Parameters

Returns

boolean - Wheter value is object or not.

▲ Top

props

static method of checker

Validates properties of given object.

Parameters

Returns

Object - The validated subject extended with default values (when applies).

Throws

• CheckerPropParamError when invalid parameters are passed.
• CheckerPropDefError when a type definition is invalid.
• CheckerPropDefTypeError when a type defintiion is not supported.
• CheckerPropReqError when a required property is not found.
• CheckerPropTypeError when a property does not match the defintion.

Example

const subject = { a: 1, b: 'hello' z: undefined };
const result = props(subject, {
    a: { type:'number', required:true },
    b: 'string',
    c: { default: new Date() },
    d: { required: false, default: null, map: value => [value, true] },
})
// result:
// { a: 1, b: 'hello', c: '1981-06-23 10:06:08', d: [null, true], z: undefined }

▲ Top