Skip to content

Latest commit

 

History

History
1873 lines (1182 loc) · 45.3 KB

README.md

File metadata and controls

1873 lines (1182 loc) · 45.3 KB
Raw

Metarhia Common Library

ci status snyk npm version npm downloads/month npm downloads license

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)

Returns: <Array>

Shuffle an array

sample(arr)

Returns: <any>

Random element from array

range(from, to)

Returns: <Array>

Generate int array from given range

Example:

range(1, 5);

Result:

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

sequence(seq[, 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)

Returns: <any> element

Get last element of array

pushSame(arr, n, value)

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)

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])

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

Wrap function: call once, not null

unsafeCallback(args)

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

Extract callback function

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

safeCallback(args)

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

Extract callback

requiredCallback(args)

Returns: <Function> extracted callback

Extract callback

Throws: <TypeError> if there is no callback

onceCallback(args)

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

Extract callback and make it safe

Wrap callback with once()

safeFunction(fn)

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

Check function and make it safe

unsafeFunction(fn)

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

Async identity function

isScalar(value)

  • value: <any>

Returns: <boolean>

Check if value is scalar

copy(ds)

Returns: <Object[]>

Copy dataset (copy objects to new array)

clone(obj)

Returns: <Object>|<Array>

Clone object or array

duplicate(obj)

Returns: <Object>|<Array>

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

getByPath(data, dataPath)

Returns: <any> value

Read property by dot-separated path

setByPath(data, dataPath, value)

Set property by dot-separated path

deleteByPath(data, dataPath)

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)

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])

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)

Forward events from one EventEmitter to another

class Flags

Flags.from(...args)

Flags.prototype.constructor(...args)

partial(fn, ...args)

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

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)

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)

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)

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

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)

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

Curry function curry with fn

curry(fn, ...param)

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)

Apply arguments

either(fn)

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)

mkdirpPromise(dir, mode = MKDIRP_DEFAULT_MODE)

rmdirp(dir, cb)

rmRecursive(path, 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)

Returns: <string> key

Generate random key

generateGUID()

Returns: <string> GUID

Generate an RFC4122-compliant GUID (UUID v4)

generateToken(secret, characters, length)

Returns: <string> token

Generate random Token

crcToken(secret, key)

Returns: <string> crc

Calculate Token crc

validateToken(secret, token)

Returns: <boolean>

Validate Token

hash(password, salt)

Returns: <string> hash

Calculate hash with salt

validateHash(hashValue, password, salt)

Returns: <boolean>

Validate hash

generateStorageKey()

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

Generate file storage key

idToChunks(id)

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

Convert id to array of hex strings

idToPath(id)

Returns: <string>

Convert id to file path

pathToId(path)

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.indices(arr)

  • arr: <Array> array-like object to create indices from

Returns: <Iterator>

Create iterator over indices of an array

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

Returns: <Iterator>

Create iterator iterating over the range

Iterator.zip(...iterators)

Returns: <Iterator>

Create iterator by zipping multiple provided iterators into one

Iterator.prototype.constructor(base)

Iterator.prototype.apply(fn)

Returns: the result of fn(this) call.

Call a function with this. Will be equivalent to calling fn(it).

Iterator.prototype.chain(...iterators)

Iterator.prototype.chainApply(fn)

Returns: <Iterator> result of fn(this) wrapped in an Iterator.

Call a function with this and wrap the result in an Iterator.

Example:

iter([1, 2])
  .chainApply(([a, b]) => [a   b, a - b])
  .join(', ');

Result:

'3, -1';

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.findCompare(comparator[, accessor[, thisArg]])

  • comparator: <Function> returns true if new value should be accepted
    • currValue: <any> current value, starts with undefined
    • nextValue: <any> next value
    • Returns: <boolean> true if next value should be accepted
  • accessor: <Function> gets value to compare by, current iterator value is used by default
    • value: <any> current iterator value
    • Returns: <any> value to compare by
  • thisArg: <any> value to be used as this when calling accessor and comparator

Returns: last iterator value where comparator returned true, <undefined> by default

Find value in this iterator by comparing every value with

the found one using comparator

Iterator.prototype.firstNonNullable([defaultValue])

  • defaultValue: <any> value to return if this iterator doesn't have non-nullable values
  • Returns: first non-nullable value or <defaultValue>

Finds first non-nullable value in this iterator

Iterator.prototype.flat(depth = 1)

Iterator.prototype.flatMap(mapper, thisArg)

Iterator.prototype.forEach(fn, thisArg)

Iterator.prototype.groupBy(classifier[, thisArg])

  • classifier: <Function> gets value to group by
    • value: <any> current iterator value
    • Returns: <any> value to group by
  • thisArg: <any> value to be used as this when calling classifier
  • Returns: <Map> map with arrays of iterator values grouped by keys returned by classifier

Consumes an iterator grouping values by keys

Iterator.prototype.includes(element)

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

Iterator.prototype.last([defaultValue])

  • defaultValue: <any> value to be used if iterator is empty

Returns: <any>|<undefined> last value of this iterator or <undefined>

Consumes an iterator returning last iterator value

Iterator.prototype.map(mapper, thisArg)

Iterator.prototype.max([accessor[, thisArg]])

  • accessor: <Function> gets value to compare by, current iterator value is used by default
    • value: <any> current iterator value
    • Returns: <any> value to compare by
  • thisArg: <any> value to be used as this when calling accessor

Returns: element with maximum value or <undefined> if iterator is empty

Find the maximum value in this iterator

Iterator.prototype.min([accessor[, thisArg]])

  • accessor: <Function> gets value to compare by, current iterator value is used by default
    • value: <any> current iterator value
    • Returns: <any> value to compare by
  • thisArg: <any> value to be used as this when calling accessor

Returns: element with minimum value or <undefined> if iterator is empty

Find the minimum value in this iterator

Iterator.prototype.next()

Iterator.prototype.partition(predicate[, thisArg])

  • predicate: <Function> function returns a value to partition this iterator
    • value: <any> current iterator element
    • Returns: <boolean>|<number> key denoting resulting partition this value will be assigned to. Number denotes index in the resulting array. Boolean will be cast to number
  • thisArg: <any> value to be used as this when calling predicate
  • Returns: <Array> array of partitions (arrays), will always have at least 2 arrays in it

Consumes an iterator, partitioning it into Arrays

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)

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)

Returns: <string[]> method names

List method names

properties(iface)

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)

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)

Returns: <number>

Compare for array.sort with priority

Example:

files.sort(common.sortComparePriority);

sortCompareDirectories(a, b)

Returns: <number>

Compare for array.sort, directories first

Example:

files.sort(sortCompareDirectories);

sortCompareByName(a, b)

Returns: <number>

Compare for array.sort

Example:

files.sort(sortCompareByName);

class MemoryWritable extends Writable

MemoryWritable.prototype.constructor([sizeLimit])

  • sizeLimit: <number>|<string> limit of the internal buffer size specified as number in bytes or as string in format supported by common.bytesToSize(). Defaults to 8 MB

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)

Returns: <string>

Escape html characters

Example:

htmlEscape('5>=5') = '5&lt;=5';

fileExt(fileName)

Returns: <string>

Extract file extension in lower case without dot

Example:

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

Result:

'txt';

removeExt(fileName)

Returns: <string>

Remove file extension from file name

Example:

fileExt('file.txt');

Result:

'file';

spinalToCamel(name)

Returns: <string>

Convert spinal case to camel case

escapeRegExp(s)

Returns: <string>

Escape regular expression control characters

Example:

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

newEscapedRegExp(s)

Returns: <RegExp>

Generate escaped regular expression

addTrailingSlash(s)

Returns: <string>

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

stripTrailingSlash(s)

Returns: <string>

Remove trailing slash from string

dirname(filePath)

Returns: <string>

Get directory name with trailing slash from path

capitalize(s)

Returns: <string>

Capitalize string

between(s, prefix, suffix)

Returns: <string>

Extract substring between prefix and suffix

removeBOM(s)

Returns: <string>

Remove UTF-8 BOM

arrayRegExp(items)

Returns: <RegExp>

Generate RegExp from array with '*' wildcards

Example:

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

section(s, separator)

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)

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)

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)

Returns: <number> milliseconds

Parse duration to seconds

Example:

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

durationToString(n)

Returns: <string>

Convert integer duration to string

bytesToSize(bytes)

Returns: <string>

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

sizeToBytes(size)

Returns: <number>

Convert string with data size to integer

safe(fn)

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

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

Make function raise-safe

captureMaxStack()

callerFilename(depth = 0, stack = null)

callerFilepath(depth = 0, stack = null)

  • depth: <number>|<RegExp> initial stack slice or filter regular expression, 0 by default.
  • stack: <string> stack string, optional

Try to detect the filepath of a caller of this function.

Contributors

See github for full contributors list