@metarhia/common

Metarhia Common Library

Namespace: api.common in Impress Application Server

Installation

$ npm install @metarhia/common

API

splitAt(index, array)

• index: <number> index defining end of first part and start of second
• array: <Array> to be split

Returns: <Array> tuple with two parts of the array

Split array into two parts

shuffle(arr)

• arr: <Array>

Returns: <Array>

Shuffle an array

range(from, to)

• from: <number> range start
• to: <number> range end

Returns: <Array>

Generate int array from given range

Example:

range(1, 5);

Result:

[1, 2, 3, 4, 5];

sequence(seq[, max])

• seq: <Array>
• max: <number> (optional), max

Returns: <Array>

Generate int array from sequence syntax

Example:

list: sequence([81, 82, 83]);

Result:

[81, 82, 83];

Example:

range from..to: sequence([81,,83]) = [81, 82, 83];

Result:

[81, 82, 83];

Example:

range from..count: sequence([81, [3]]) = [81, 82, 83];

Result:

[81, 82, 83];

Example:

range from..max-to: sequence([81, [-2]], 5) = [81, 82, 83];

Result:

[81, 82, 83];

last(arr)

• arr: <Array>

Returns: <any> element

Get last element of array

pushSame(arr, n, value)

• arr: <Array>
• n: <number>
• value: <any>

Returns: <number> new value of arr.length

Push single value multiple times

checkLogin(login, required[, optional])

• login: <string> login to test
• required: <Array> required tests configs
• optional: <Array> optional tests configs, defalult: []

Returns: <AuthenticationStrength>

Function that tests the login

checkPassword(password, required[, optional])

• password: <string> password to test
• required: <Array> required tests configs
• optional: <Array> optional tests configs, default: []

Returns: <AuthenticationStrength>

Function that tests the password

checkLoginPassword(login, password, required[, optional])

• login: <string> login to test
• password: <string> password to test
• required: <Array> required tests configs
• optional: <Array> optional tests configs, default: []

Returns: <AuthenticationStrength>

Function that tests the login with password

class BTree

BTree.prototype.constructor(degree = DEFAULT_DEGREE)

BTree.prototype.get(key)

BTree.prototype.iterator(start, finish)

BTree.prototype.remove(key)

BTree.prototype.set(key, data)

cache()

Returns: <Cache>

Create Cache, enhanced Map

class Cache extends Map

Cache.prototype.constructor()

Cache.prototype.add(key, val)

• key: <string> key
• val: <any> associated value

Add key-value pair to cache

Cache.prototype.clr(prefix[, fn])

• prefix: <string> to compare with beginning of the key
• fn: <Function> (optional)
  • key: <string> key
  • val: <any> associative value to be called on each key

Clear cache elements that start with prefix

Cache.prototype.del(key)

• key: <string> key

Delete cache element

falseness()

Returns: <boolean> always false

Empty function

trueness()

Returns: <boolean> always true

Empty function

emptiness()

Empty function

nop(callback)

• callback: <Function> callback to be called with (null)

Empty asynchronous callback-last single-argument function

noop(empty, callback)

• empty: <any> incoming value to be ignored
• callback: <Function> callback to be called with (null, null)

Empty asynchronous callback-last double-argument function

once([fn])

• fn: <Function> (optional)

Returns: <Function> function(...args) wrapped callback

• args: <Array>

Wrap function: call once, not null

unsafeCallback(args)

• args: <Array> arguments

Returns: <Function>|<null> callback if any

Extract callback function

It's unsafe: may return null, allows multiple calls

safeCallback(args)

• args: <Array> arguments

Returns: <Function> callback or common.emptiness if there is no callback

Extract callback

requiredCallback(args)

• args: <Array> arguments

Returns: <Function> extracted callback

Extract callback

Throws: <TypeError> if there is no callback

onceCallback(args)

• args: <Array> arguments

Returns: <Function> callback or common.emptiness if there is no callback

Extract callback and make it safe

Wrap callback with once()

safeFunction(fn)

• fn: <Function>

Returns: <Function> function or common.emptiness if fn is not a function

Check function and make it safe

unsafeFunction(fn)

• fn: <Function>

Returns: <Function>|<null> function or null if fn is not a function

Check function

id(x)

• x: <any> incoming value which will be returned

Returns: <any> incoming value

Identity function

asyncId(x, callback)

• x: <any> incoming value which will be returned into the callback
• callback: <Function> callback to be called with first argument
  • err: <null>
  • data: <any>

Async identity function

isScalar(value)

• value: <any>

Returns: <boolean>

Check if value is scalar

copy(ds)

• ds: <Object[]> source dataset to be copied

Returns: <Object[]>

Copy dataset (copy objects to new array)

clone(obj)

• obj: <Object>|<Array>

Returns: <Object>|<Array>

Clone object or array

duplicate(obj)

• obj: <Object>|<Array>

Returns: <Object>|<Array>

Duplicate object or array (properly handles prototype and circular links)

getByPath(data, dataPath)

• data: <Object>
• dataPath: <string> dot-separated path

Returns: <any> value

Read property by dot-separated path

setByPath(data, dataPath, value)

• data: <Object>
• dataPath: <string> dot-separated path
• value: <any> new value

Set property by dot-separated path

deleteByPath(data, dataPath)

• data: <Object>
• dataPath: <string> dot-separated path

Returns: <boolean>

Delete property by dot-separated path

merge(...args)

• args: <Array[]> arrays with elements to be merged

Returns: <Array>

Distinctly merge multiple arrays

mergeObjects(merger, ...objs)

• merger: <Function>
  • key: <string> current merging key
  • ...values: <any[]> values under key
• objs: <Object[]> objects to be merged

Returns: <Object>

Merge multiple objects with merger

class Enum

Enum.NaE

• <Symbol> Not an Enum

Enum.from(...args)

Enum.prototype.constructor()

forwardEvents(from, to[, events])

• from: <EventEmitter> to listen for event
• to: <EventEmitter> to emit event on
• events: <string>|<Object>|<string[]> (optional), events names

Forward events from one EventEmitter to another

Example:

forwardEvents(from, to);

Example:

forwardEvents(from, to, 'eventName');

Example:

forwardEvents(from, to, { eventName: 'newEventName' });

Example:

forwardEvents(from, to, ['eventName1', 'eventName2']);

emitter()

Returns: <EventEmitter>

Create EnhancedEmitter, enhanced EventEmitter

with wildcard and forward method

class EnhancedEmitter extends EventEmitter

EnhancedEmitter.prototype.constructor()

EnhancedEmitter.prototype.emit(...args)

• args: <Array> arguments to be passed

Call listener with provided arguments

EnhancedEmitter.prototype.forward(to, events)

• to: <EventEmitter> to emit event on
• events: <string>|<Object>|<string[]> events names

Forward events from one EventEmitter to another

class Flags

Flags.from(...args)

Flags.prototype.constructor(...args)

partial(fn, ...args)

• fn: <Function>
• args: <Array> arguments to be applied

Returns: <Function> function(...rest)

• rest: <Array> arguments

Partially apply arguments to function

omap(mapFn, obj)

• mapFn: <Function> to apply to every field value
• obj: <Object> which fields used for mapping

Returns: <Object> with same reference but with transformed fields

Map object fields with provided function

compose(...fns)

• fns: <Array> functions to be composed

Returns: <Function> function(...args), composed

• args: <Array> arguments to be passed to the first function

Compose multiple functions into one

maybe(fn, defVal[, value])

• fn: <Function>
• defVal: <any> default value
• value: <any> (optional), value

Returns: <any> result of fn or defVal

Apply given function to value or default value

zip(...arrays)

• arrays: <Array[]> arrays to be zipped

Returns: <Array> length is minimal of input arrays length, element with index i of resulting array is array with elements with index i from input array

Zip several arrays into one

replicate(count, elem)

• count: <number> new array length
• elem: <any> value to replicate

Returns: <Array> replicated

Create array of replicated values

zipWith(fn, ...arrays)

• fn: <Function> for zipping elements with index i
• arrays: <Array[]> arrays to be zipped

Returns: <Array> zipped, element with index i of resulting array is result of fn called with arguments from arrays

Zip arrays using specific function

curryUntil(condition, fn, ...args)

• condition: <Function> returns: <boolean>
  • argsI: <Array> arguments for i-th currying
  • argsParts: <Array> of args given for currying from first to i-th currying
• fn: <Function> to be curried
• args: <Array> arguments for fn

Returns: <Function> function(...args), curried

• args: <Array> arguments

Curry function until the condition is met

curryN(fn, count, ...args)

• fn: <Function> to be curried
• count: <number> of times function should be curried
• args: <Array> arguments for first currying

Returns: <Function> curried given times count

Curry fn count times, first curry uses args for first currying

curryTwice(fn)

• fn: <Function> to be curried

Returns: <Function> to pass arguments that returns curried fn

Curry function curry with fn

curry(fn, ...param)

• fn: <Function> to be curried
• param: <Array> arguments to the function

Returns: <Function> function(...args), curried

Curry function with given arguments

applyArgs(...args)

• args: <Array> arguments to save in closure

Returns: <Function> returns: <any>, result of fn(...args)

• fn: <Function> to be applied saved arguments

Apply arguments

either(fn)

• fn: <Function> to be called

Returns: <Function> function(...args), returns: <any>, result of fn(arg), where arg - first valid element of args

• args: <Array> arguments to iterate

Get first not errored result of fn

Throws: <Error> if fn throws it

restLeft(fn)

• fn: <Function> function(args, ...namedArgs, callback)
  • args: <Array> rest of spreadArgs created by excluding namedArgs
  • namedArgs: <Array> first values of spreadArgs, length is based upon interface of fn
  • callback: <Function> callback, last argument of spreadArgs

Returns: <Function> function(...spreadArgs)

• spreadArgs: <Array> arguments to be added

Rest left, transform function

mkdirp(dir, mode, cb)

rmdirp(dir, cb)

rmRecursive(path, callback)

• path: <string> path to a file or directory to be removed
• callback: <Function> callback

Recursively remove directory

async rmRecursivePromise(path)

• path: <string> path to a file or directory to be removed

Returns: <Promise>

Recursively remove directory

generateKey(length, possible)

• length: <number> key length
• possible: <string> with possible characters

Returns: <string> key

Generate random key

generateGUID()

Returns: <string> GUID

Generate an RFC4122-compliant GUID (UUID v4)

generateToken(secret, characters, length)

• secret: <string>
• characters: <string>
• length: <number>

Returns: <string> token

Generate random Token

crcToken(secret, key)

• secret: <string>
• key: <string>

Returns: <string> crc

Calculate Token crc

validateToken(secret, token)

• secret: <string>
• token: <string>

Returns: <boolean>

Validate Token

hash(password, salt)

• password: <string>
• salt: <string>

Returns: <string> hash

Calculate hash with salt

validateHash(hashValue, password, salt)

• hashValue: <string>
• password: <string>
• salt: <string>

Returns: <boolean>

Validate hash

generateStorageKey()

Returns: <string[]> [folder1, folder2, code]

Generate file storage key

idToChunks(id)

• id: <number>

Returns: <Array> minimal length is 2 which contains hex strings with length of 4

Convert id to array of hex strings

idToPath(id)

• id: <number>

Returns: <string>

Convert id to file path

pathToId(path)

• path: <string>

Returns: <number>

Convert file path to id

class Int64

Int64.add(a, b)

Int64.and(a, b)

Int64.cmp(a, b)

Int64.div(a, b)

Int64.mod(a, b)

Int64.mult(a, b)

Int64.not(a)

Int64.one()

Int64.or(a, b)

Int64.shiftLeft(a, b)

Int64.shiftRight(a, b)

Int64.sub(a, b)

Int64.xor(a, b)

Int64.zero()

Int64.prototype.constructor(value)

Int64.prototype.add(b)

Int64.prototype.and(b)

Int64.prototype.dec()

Int64.prototype.inc()

Int64.prototype.not()

Int64.prototype.or(b)

Int64.prototype.shiftLeft(b)

Int64.prototype.shiftRight(b)

Int64.prototype.shiftRightArithmetic(b)

Int64.prototype.shiftRightLogical(b)

Int64.prototype.sub(b)

Int64.prototype.toInt32()

Int64.prototype.toJSON()

Int64.prototype.toPostgres()

Int64.prototype.toString(radix = 10)

Int64.prototype.toUint32()

Int64.prototype.xor(b)

class Iterator

Iterator.range(start, stop[, step])

• start: <number>
• stop: <number>
• step: <number> (optional), default: 1

Returns: <Iterator>

Create iterator iterating over the range

Iterator.prototype.constructor(base)

Iterator.prototype.chain(...iterators)

Iterator.prototype.collectTo(CollectionClass)

Iterator.prototype.collectWith(obj, collector)

Iterator.prototype.count()

Iterator.prototype.each(fn, thisArg)

Iterator.prototype.enumerate()

Iterator.prototype.every(predicate, thisArg)

Iterator.prototype.filter(predicate, thisArg)

Iterator.prototype.filterMap(mapper[, thisArg[, filterValue]])

• mapper: <Function> function that maps values and returns either new value that will be the next value of the new iterator or filterValue that will be ignored.
  • value: <any> iterator element
• thisArg: <any> value to be used as this when calling mapper
• filterValue: <any> value to filter out mapper results.

Creates an iterator that both filters and maps with the passed mapper.

This iterator will call mapper on each element and if mapper returns NOT filterValue it will be returned, otherwise it is ignored.

Iterator.prototype.find(predicate, thisArg)

Iterator.prototype.flat(depth = 1)

Iterator.prototype.flatMap(mapper, thisArg)

Iterator.prototype.forEach(fn, thisArg)

Iterator.prototype.includes(element)

Iterator.prototype.join(sep = ', ', prefix = '', suffix = '')

Iterator.prototype.map(mapper, thisArg)

Iterator.prototype.next()

Iterator.prototype.reduce(reducer, initialValue)

Iterator.prototype.skip(amount)

Iterator.prototype.skipWhile(predicate, thisArg)

Iterator.prototype.some(predicate, thisArg)

Iterator.prototype.someCount(predicate, count, thisArg)

Iterator.prototype.take(amount)

Iterator.prototype.takeWhile(predicate, thisArg)

Iterator.prototype.toArray()

Iterator.prototype.toObject()

Transforms an iterator of key-value pairs into an object.

This is similar to what Object.fromEntries() would offer.

Iterator.prototype.zip(...iterators)

iter(base)

iterEntries(obj)

iterKeys(obj)

iterValues(obj)

cryptoPrefetcher(bufSize, valueSize)

• bufSize: <number> size in bytes of the buffer to preallocate
• valueSize: <number> size in bytes of the produced chunks

Create prefetcher to use when crypto.randomBytes is required to generate

multiple same-size values. bufSize must be a multiple of valueSize for this to work.

random(min, max)

• min: <number> range start
• max: <number> range end

Returns: <number>

Generate random integer value in given range

cryptoRandom()

Returns: <number>

Generate random number in the range from 0 inclusive up to

but not including 1 (same as Math.random), using crypto-secure number generator.

methods(iface)

• iface: <Object> to be introspected

Returns: <string[]> method names

List method names

properties(iface)

• iface: <Object> to be introspected

Returns: <string[]> property names

List property names

ipToInt([ip])

• ip: <string> (optional), default: '127.0.0.1', IP address

Returns: <number>

Convert IP string to number

localIPs()

Returns: <string[]>

Get local network interfaces

parseHost(host)

• host: <string> host or empty string, may contain :port

Returns: <string> host without port but not empty

Parse host string

override(obj, fn)

• obj: <Object> containing method to override
• fn: <Function> name will be used to find method

Override method: save old to fn.inherited

Previous function will be accessible by obj.fnName.inherited

mixin(target, source)

• target: <Object> mixin to target
• source: <Object> source methods

Mixin for ES6 classes without overriding existing methods

class Pool

Pool.prototype.constructor(factory = null)

Pool.prototype.get()

Pool.prototype.put(value)

sortComparePriority(priority, s1, s2)

• priority: <string[]> with priority
• s1: <string> to compare
• s2: <string> to compare

Returns: <number>

Compare for array.sort with priority

Example:

files.sort(common.sortComparePriority);

sortCompareDirectories(a, b)

• a: <string> to compare
• b: <string> to compare

Returns: <number>

Compare for array.sort, directories first

Example:

files.sort(sortCompareDirectories);

sortCompareByName(a, b)

• a: <Object> { name } to compare
• b: <Object> { name } to compare

Returns: <number>

Compare for array.sort

Example:

files.sort(sortCompareByName);

class MemoryWritable extends Writable

MemoryWritable.prototype.constructor()

async MemoryWritable.prototype.getData([encoding])

• encoding: <string> encoding to convert the resulting data to, must be a valid <Buffer> encoding

Returns: <Promise>

Return a Promise that will be resolved with all the written data once it

becomes available.

subst(tpl, data, dataPath, escapeHtml)

• tpl: <string> template body
• data: <Object> hash, data structure to visualize
• dataPath: <string> current position in data structure
• escapeHtml: <boolean> escape html special characters if true

Returns: <string>

Substitute variables

htmlEscape(content)

• content: <string> to escape

Returns: <string>

Escape html characters

Example:

htmlEscape('5>=5') = '5<=5';

fileExt(fileName)

• fileName: <string> file name

Returns: <string>

Extract file extension in lower case without dot

Example:

fileExt('/dir/file.txt');

Result:

'txt';

removeExt(fileName)

• fileName: <string> file name

Returns: <string>

Remove file extension from file name

Example:

fileExt('file.txt');

Result:

'file';

spinalToCamel(name)

• name: <string>

Returns: <string>

Convert spinal case to camel case

escapeRegExp(s)

• s: <string>

Returns: <string>

Escape regular expression control characters

Example:

escapeRegExp('/path/to/res?search=this.that');

newEscapedRegExp(s)

• s: <string>

Returns: <RegExp>

Generate escaped regular expression

addTrailingSlash(s)

• s: <string>

Returns: <string>

Add trailing slash at the end if there isn't one

stripTrailingSlash(s)

• s: <string>

Returns: <string>

Remove trailing slash from string

dirname(filePath)

• filePath: <string>

Returns: <string>

Get directory name with trailing slash from path

capitalize(s)

• s: <string>

Returns: <string>

Capitalize string

between(s, prefix, suffix)

• s: <string> source
• prefix: <string> before needed fragment
• suffix: <string> after needed fragment

Returns: <string>

Extract substring between prefix and suffix

removeBOM(s)

• s: <string> possibly starts with BOM

Returns: <string>

Remove UTF-8 BOM

arrayRegExp(items)

• items: <string[]>

Returns: <RegExp>

Generate RegExp from array with '*' wildcards

Example:

['/css/*', '/index.html'];

section(s, separator)

• s: <string>
• separator: <string> or char

Returns: <string[]>

Split string by the first occurrence of separator

Example:

rsection('All you need is JavaScript', 'is');

Result:

['All you need ', ' JavaScript'];

rsection(s, separator)

• s: <string>
• separator: <string> or char

Returns: <string[]>

Split string by the last occurrence of separator

Example:

rsection('All you need is JavaScript', 'a');

Result:

['All you need is Jav', 'Script'];

split(s[, separator[, limit]])

• s: <string>
• separator: <string> (optional), default: ','
• limit: <number> (optional), default: -1, max length of result array

Returns: <string[]>

Split string by multiple occurrence of separator

Example:

split('a,b,c,d');

Result:

['a', 'b', 'c', 'd'];

Example:

split('a,b,c,d', ',', 2);

Result:

['a', 'b'];

rsplit(s[, separator[, limit]])

• s: <string>
• separator: <string> (optional), default: ','
• limit: <number> (optional), default: -1, max length of result array

Returns: <string[]>

Split string by multiple occurrences of separator

Example:

split('a,b,c,d', ',', 2);

Result:

['c', 'd'];

normalizeEmail(email)

• email: <string> email address to normalize

Returns: <string> normalized email address

Normalize email address according to OWASP recommendations

isTimeEqual(time1, time2)

• time1: <string> time or milliseconds
• time2: <string> time or milliseconds

Returns: <boolean>

Compare time1 and time2

Example:

isTimeEqual(sinceTime, buffer.stats.mtime);

nowDate([date])

• date: <Date> (optional), default: new Date()

Returns: <string>

Get current date in YYYY-MM-DD format

nowDateTime([date])

• date: <Date> (optional), default: new Date()

Returns: <string>

Get current date in YYYY-MM-DD hh:mm format

class Uint64

Uint64.add(a, b)

Uint64.and(a, b)

Uint64.cmp(a, b)

Uint64.div(a, b)

Uint64.mod(a, b)

Uint64.mult(a, b)

Uint64.not(a)

Uint64.or(a, b)

Uint64.shiftLeft(a, b)

Uint64.shiftRight(a, b)

Uint64.sub(a, b)

Uint64.xor(a, b)

Uint64.prototype.constructor(value)

Uint64.prototype.add(b)

Uint64.prototype.and(b)

Uint64.prototype.dec()

Uint64.prototype.inc()

Uint64.prototype.not()

Uint64.prototype.or(b)

Uint64.prototype.shiftLeft(b)

Uint64.prototype.shiftRight(b)

Uint64.prototype.sub(b)

Uint64.prototype.toJSON()

Uint64.prototype.toPostgres()

Uint64.prototype.toString(radix = 10)

Uint64.prototype.toUint32()

Uint64.prototype.xor(b)

duration(s)

• s: <string> duration syntax

Returns: <number> milliseconds

Parse duration to seconds

Example:

duration('1d 10h 7m 13s');

durationToString(n)

• n: <number> duration

Returns: <string>

Convert integer duration to string

bytesToSize(bytes)

• bytes: <number> size

Returns: <string>

Convert integer to string, representing data size in Kb, Mb, Gb, and Tb

sizeToBytes(size)

• size: <string> size

Returns: <number>

Convert string with data size to integer

safe(fn)

• fn: <Function>

Returns: <Function> function(...args), wrapped with try/catch interception

• args: <Array> arguments to be passed to wrapped function

Make function raise-safe

callerFilename(depth = 0, stack = null)

callerFilepath(depth = 0, stack = null)

Contributors

See github for full contributors list

Changelog

[2.1.0][] - 2019-06-18

Added

• rmRecursive() and rmRecursivePromise() functions.
• Iterator#filterMap() to enable more efficient filter+map. It will only return values from mapper function that do not match the passed filterValue (undefined by default).
• Iterator#skipWhile() to enable skipping elements while predicate holds.
• MemoryWritable stream implementation.

Fixed

• Documentation by marking some methods as private and regenerating with a newer version of @metarhia/doc (changelog).