ak-tools

AK's (nearly typesafe) collections of useful things...cobbled together from various projects over the years...

install:

$ npm i ak-tools

use:

const utils = require('ak-tools') 	//cjs
import {* as utils} from 'ak-tools' 	//esm

verify

$ npm run test

if using an IDE with jsdoc support you should have a good experience.

demo

/**
 * make a folder, and a file
 * measure it... remove it
 * time the whole thing
**/
const u = require('ak-tools');
const timer = u.time('myProcess')
timer.start()

const newFolder = u.mkdir('./tmp')
const myData = [{foo: "bar"}, {baz: "qux"}]
const file = await u.touch('./tmp/data.json', u.dupeVals(myData, 1000), true);
const contents = await u.load(file)

const size = u.calcSize(u.json(contents))
const del = u.rm('./tmp/data.json')
timer.end(false)

const diag = { size: u.bytesHuman(size),...timer.report(false) }
u.log(diag)

APIs

files

file management utilities

validate

data validation utilities

display

display, formatting, and other make it look right utilities

maths

functions for maths, crypto, and maths

objects

object utilities

arrays

array utilities

functions

function utilities

logging

logging, timers and other diagnostic utilities

Typedefs

generalObject : Object.<string, any>

generic for {} w/string keys

arrayOfObjects : Array.<generalObject>

generic for [{},{},{}]

GCSUri

filterCallback : function

files

file management utilities

• files
  • .ls([dir], [objectMode]) ⇒ Promise.<(Array.<string>|generalObject)>
  • .rm(fileNameOrPath) ⇒ Promise.<(string|boolean|void)>
  • .touch(fileNameOrPath, [data], [isJson]) ⇒ Promise.<(string|false)>
  • .load(fileNameOrPath, [isJson], [encoding]) ⇒ Promise.<(string|generalObject|arrayOfObjects)>
  • .mkdir([dirPath]) ⇒ string

files.ls([dir], [objectMode]) ⇒ Promise.<(Array.<string>|generalObject)>

list directory contents

Kind: static method of files
Returns: Promise.<(Array.<string>|generalObject)> - [] or {} of files in folder

Param	Type	Default	Description
[dir]	string	'./'	directory to enumerate; default ./
[objectMode]	boolean	false	return {name: path} instead of [path]; default false

Example

await ls('./tmp') // => []
await ls('./tmp', true) // => {}

files.rm(fileNameOrPath) ⇒ Promise.<(string|boolean|void)>

remove a file or directory

Kind: static method of files
Returns: Promise.<(string|boolean|void)> - path or false if fail

Param	Type	Description
fileNameOrPath	string	file or path to be removed

Example

await rm('./myfile.txt') // => '/path/to/myfile.txt' || false

files.touch(fileNameOrPath, [data], [isJson]) ⇒ Promise.<(string|false)>

create a file

Kind: static method of files
Returns: Promise.<(string|false)> - the name of the file

Param	Type	Default	Description
fileNameOrPath	string		file to create
[data]	string | generalObject | arrayOfObjects	\	data to write; default ""
[isJson]	boolean	false	is data JSON; default false

Example

await touch('newfile.txt', data)  // => '/path/to/newfile.txt' || false
await touch('newfile.json', data, true)  // => '/path/to/newfile.json' || false

files.load(fileNameOrPath, [isJson], [encoding]) ⇒ Promise.<(string|generalObject|arrayOfObjects)>

load a file into memory

Kind: static method of files
Returns: Promise.<(string|generalObject|arrayOfObjects)> - the file in memory

Param	Type	Default	Description
fileNameOrPath	string		file to create
[isJson]	boolean	false	is data JSON; default false
[encoding]	string	utf-8	file encoring; default utf-8

Example

await load('myfile.txt')  // => 'my file contents' || false
await load('myfile.json', true)  // => {my: "data"} || false

files.mkdir([dirPath]) ⇒ string

make a directory

Kind: static method of files
Returns: string - the absolute path of the directory

Param	Type	Default	Description
[dirPath]	string	./tmp</code>	path to create; default ./tmp

Example

const myTmpDir = mkdir('./tmp')

validate

data validation utilities

• validate
  • .isJSONStr(string) ⇒ boolean
  • .isJSON(data) ⇒ boolean
  • .is(type, val) ⇒ boolean
  • .isNil(val) ⇒ boolean
  • .similar(o1, o2) ⇒ boolean
  • .parseGCSUri(uri) ⇒ GCSUri

validate.isJSONStr(string) ⇒ boolean

test if string has JSON structure

Kind: static method of validate

Param	Type
string	string

Example

isJSONStr('{"foo": "bar"}') // => true

validate.isJSON(data) ⇒ boolean

test if data can be stringified as JSON

Kind: static method of validate

Param	Type
data	string | JSON

Example

isJSON({foo: "bar"}) // => true

validate.is(type, val) ⇒ boolean

check if a type matches a value

Kind: static method of validate

Param	Type	Description
type	'string' | any	a native type like Number or Boolean
val	any	any value to check

Example

is(Number, 42) // => true

validate.isNil(val) ⇒ boolean

check if a val is null or undefined

Kind: static method of validate

Param	Type	Description
val	any	value to check

Example

isNil(null) // => true

validate.similar(o1, o2) ⇒ boolean

check if a and b have similar shape (keys), recursively

Kind: static method of validate
Returns: boolean - do they have the same shape?

Param	Type	Description
o1	generalObject	first obj
o2	generalObject	second obj

Example

similar({a: "foo"}, {a: "bar"}) // => true

validate.parseGCSUri(uri) ⇒ GCSUri

turn a gcs uri into a bucket and file

Kind: static method of validate

Param	Type
uri	string

Example

parseGCSUri(`gcs://foo/bar.txt`) // => {uri: "gcs://foo/bar.txt", bucket: "foo", file: "bar.txt"}

display

display, formatting, and other "make it look right" utilities

• display
  • .comma(num) ⇒ string
  • .truncate(text, [chars], [useWordBoundary]) ⇒ string
  • .bytesHuman(bytes, [dp], [si]) ⇒ string
  • .json(data, [padding]) ⇒ string | false
  • .stripHTML(str) ⇒ string
  • .multiReplace(str, [replacePairs]) ⇒ string
  • .replaceAll(oldVal, newVal) ⇒ string
  • .toCSV(arr, [headers], [delimiter]) ⇒ string
  • .unBase64(b64Str) ⇒

display.comma(num) ⇒ string

turn a number into a comma separated (human readable) string

Kind: static method of display
Returns: string - formatted number

Param	Type
num	string | number

Example

comma(1000) // => "1,000"

display.truncate(text, [chars], [useWordBoundary]) ⇒ string

truncate a string w/ellipses

Kind: static method of display
Returns: string - truncated string

Param	Type	Default	Description
text	string		text to truncate
[chars]	number	500	# of max characters
[useWordBoundary]	boolean	true	don't break words; default true

Example

truncate('foo bar baz', 3) // => 'foo...'

display.bytesHuman(bytes, [dp], [si]) ⇒ string

turn a number (of bytes) into a human readable string

Kind: static method of display
Returns: string - # of bytes

Param	Type	Default	Description
bytes	number		number of bytes to convert
[dp]	number	2	decimal points; default 2
[si]	boolean	false	threshold of 1000 or 1024; default false

Example

bytesHuman(10000000) // => '9.54 MiB'

display.json(data, [padding]) ⇒ string | false

stringify object to json

Kind: static method of display
Returns: string | false - valid json

Param	Type	Default	Description
data	object		any serializable object
[padding]	number	2	padding to use

Example

json({foo: "bar"}) => '{"foo": "bar"}'

display.stripHTML(str) ⇒ string

strip all <html> tags from a string

Kind: static method of display
Returns: string - sanitized string
Note: note: <br> tags are replace with \n

Param	Type	Description
str	string	string with html tags

Example

stripHTML(`<div>i am <br/>text`) // => "i am \n text"

display.multiReplace(str, [replacePairs]) ⇒ string

find and replace many values in string

Kind: static method of display
Returns: string - multi-replaced string

Param	Type	Default	Description
str	string		string to replace
[replacePairs]	Array.<Array.<string, string>>	[[	],[<],[>]]

Example

multiReplace('red fish said', [["red", "blue"],["said"]]) // => "blue fish"

display.replaceAll(oldVal, newVal) ⇒ string

replace all occurrence of old with new

Kind: static method of display
Returns: string - replaced result
Note: this CAN be called on any string directly

Param	Type	Description
oldVal	string | RegExp	old value
newVal	string	new value

Example

'foo bar'.replaceAll('foo', 'qux') // => 'qux bar'

display.toCSV(arr, [headers], [delimiter]) ⇒ string

convert array of arrays to CSV like string

Kind: static method of display
Returns: string - a valid CSV

Param	Type	Default	Description
arr	Array.<(Array.<String>|Array.<Number>)>		data of the form [ [], [], [] ]
[headers]	Array.<String>	[]	header column
[delimiter]	string	,</code>	delimiter for cells; default ,

Example

toCSV([[1,2],[3,4]], ["foo", "bar"]) // => '"foo","bar"\n"1","2"\n"3","4"'

display.unBase64(b64Str) ⇒

serialize a base64 string

Kind: static method of display
Returns: dict or array of data

Param	Type	Description
b64Str	string	base64 encoded JSON data

Example

unBase64(`eyJmb28iOiAiYmFyIn0=`) => {"foo": "bar"}

maths

functions for maths, crypto, and maths

• maths
  • .rand(min, max) ⇒ number
  • .avg(...nums) ⇒ number
  • .calcSize(data) ⇒ number
  • .round(number, [decimalPlaces]) ⇒ number
  • .uid([length]) ⇒ string
  • .uuid() ⇒ string
  • .md5(data) ⇒ string

maths.rand(min, max) ⇒ number

random integer between min and max (inclusive)

Kind: static method of maths
Returns: number - random number
Note: this is not cryptographically safe

Param	Type	Default	Description
min	number	1	minimum
max	number	100	maximum

Example

rand(1,10) // 1 or 2 or 3 ... or 10

maths.avg(...nums) ⇒ number

calculate average of ...nums

Kind: static method of maths
Returns: number - average

Param	Type	Description
...nums	number	numbers to average

Example

avg(1,2,3) // => 2

maths.calcSize(data) ⇒ number

calculate the size (on disk)

Kind: static method of maths
Returns: number - estimated size in bytes

Param	Type	Description
data	string | generalObject	JSON to estimate

Example

calcSize({foo: "bar"}) // => 13

maths.round(number, [decimalPlaces]) ⇒ number

round a number to a number of decimal places

Kind: static method of maths
Returns: number - rounded number

Param	Type	Default	Description
number	number		number to round
[decimalPlaces]	number	0	decimal places; default 0

Example

round(3.14159, 3) // => 3.142

maths.uid([length]) ⇒ string

generate a random uid:

Kind: static method of maths
Returns: string - a uid of specified length
Note: not cryptographically safe

Param	Type	Default	Description
[length]	number	64	length of id; default 64

Example

uid(4) // => 'AwD9rbntSj'

maths.uuid() ⇒ string

generated a uuid in v4 format:

Kind: static method of maths
Returns: string - a uuid
Note: not cryptographically safe
Example

uuid() // => "f47e2fdf-e387-4a39-9bb9-80b0ed950b48"

maths.md5(data) ⇒ string

calculate the md5 hash of any data

Kind: static method of maths
Returns: string - md5 hash of `data

Param	Type	Description
data	any	data to hash

Example

md5({foo: "bar"}) // => "d41d8cd98f00b204e9800998ecf8427e"

objects

object utilities

• objects
  • .rnKeys(obj, newKeys) ⇒ generalObject
  • .rnVals(obj, pairs) ⇒ generalObject
  • .objFilter(hash, test_function, [keysOrValues]) ⇒ generalObject
  • .objClean(obj, [clone]) ⇒ generalObject
  • .objDefault(obj, defs) ⇒ generalObject
  • .objMatch(obj, source) ⇒ boolean
  • .objClone(thing, [opts]) ⇒ Object
  • .objTypecast(obj, [isClone]) ⇒ Object
  • .objAwait(obj) ⇒ Promise.<generalObject>
  • .removeNulls(objWithNullOrUndef) ⇒ Object
  • .flatten(obj, roots, sep)
  • .objMap(object, mapFn)
  • .getKey(object, value)

objects.rnKeys(obj, newKeys) ⇒ generalObject

rename object keys with a mapping object

Kind: static method of objects
Returns: generalObject - new object with renamed keys

Param	Type	Description
obj	generalObject	object to rename
newKeys	generalObject	map of form {oldKey: newKey}

Example

rnKeys({foo: 'bar'}, {foo: 'baz'}) // => {baz: "bar"}

objects.rnVals(obj, pairs) ⇒ generalObject

rename object values using a mapping array

Kind: static method of objects
Returns: generalObject - object with renamed values

Param	Type	Description
obj	generalObject
pairs	Array.<Array.<string, string>>	[['old', 'new']]

Example

rnVals({foo: "bar"}, [["bar","baz"]) // => {foo: "baz"}

objects.objFilter(hash, test_function, [keysOrValues]) ⇒ generalObject

filter objects by values or objects by keys; like map() for objects

Kind: static method of objects
Returns: generalObject - filtered object

Param	Type	Default	Description
hash	generalObject		object or array to filter
test_function	filterCallback		a function which is called on keys/values
[keysOrValues]	key | value	value	test keys or values; default value

Example

const d = {foo: "bar", baz: "qux"}
objFilter(d, x => x.startsWith('b')) // => {foo: "bar"}
objFilter(d, x => x.startsWith('f'), 'key') // => {foo: "bar"}

objects.objClean(obj, [clone]) ⇒ generalObject

removes the following from deeply nested objects:

• null | undefined | {} | [] | ""

Kind: static method of objects
Returns: generalObject - cleaned object

Param	Type	Default	Description
obj	generalObject		object to clean
[clone]	boolean	true	should produce a new object? default true

Example

objClean({foo: null, bar: undefined, baz: ""}) // => {}

objects.objDefault(obj, defs) ⇒ generalObject

apply default props to an object; don't override values from source

Kind: static method of objects
Returns: generalObject - an object which has defs props

Param	Type	Description
obj	generalObject	original object
defs	Object	props to add without overriding

Example

objDefault({foo: "bar"}, {foo: "qux", b: "m"}) // => {foo: 'bar', b: 'm'}

objects.objMatch(obj, source) ⇒ boolean

deep equality match for any two objects

Kind: static method of objects
Returns: boolean - do objects A & B (deeply) match?

Param	Type	Description
obj	Object	object A
source	Object	object B

Example

objMatch({f: {g: {h: 42}}}, {f: {g: {x: 42}}}) // => false

objects.objClone(thing, [opts]) ⇒ Object

efficient object cloning; outperforms parse(stringify()) by 100x

Kind: static method of objects
Returns: Object - deep copy of object

Param	Type	Description
thing	Object	object to clone
[opts]	Object

Example

objClone({f: {g: {h : 42}}}) // => { f: { g: { h: 42 } } }

objects.objTypecast(obj, [isClone]) ⇒ Object

visit every property of an object; turn "number" values into numbers

Kind: static method of objects
Returns: Object - object with all "numbers" as proper numbers

Param	Type	Default	Description
obj	object		object to traverse
[isClone]	boolean	false	default false; if true will mutate the passed in object

Example

objTypecast({foo: {bar: '42'}}) // => {foo: {bar: 42}}

objects.objAwait(obj) ⇒ Promise.<generalObject>

utility to await object values

Kind: static method of objects
Returns: Promise.<generalObject> - the resolved values of the object's keys

Param	Type	Description
obj	Object.<string, Promise>	object

Example

//bar is a promise
await objAwait({foo: bar()}) // => {foo: "resolved_bar"}

objects.removeNulls(objWithNullOrUndef) ⇒ Object

explicitly remove keys with null or undefined values

Kind: static method of objects
Returns: Object - an object without null or undefined values
Note: WARNING mutates object

Param	Type	Description
objWithNullOrUndef	Object	an object with null or undefined values

Example

removeNulls({foo: "bar", baz: null}) // => {foo: "bar"}

objects.flatten(obj, roots, sep)

deeply flatten as nested object; use . notation for nested keys

Kind: static method of objects

Param	Type	Default	Description
obj	Object		object to flatten
roots	Array	[	lineage for recursion
sep	string	'.'	separator to use

Example

flatten({foo: {bar: "baz"}}) => {"foo.bar": "baz"}

objects.objMap(object, mapFn)

map over an object's values and return a new object

Kind: static method of objects

Param	Type	Description
object	Object	object iterate
mapFn	function	function with signature (val) => {}

Example

objMap({foo: 2, bar: 4}, val => val * 2) => {foo: 4, bar: 8}

objects.getKey(object, value)

find a key in an object that has a particular value

Kind: static method of objects

Param	Type	Description
object	Object	object to search for
value	Object	value withing that object to search for

Example

getKey({foo: "bar"}, "bar") => "foo"

arrays

array utilities

• arrays
  • .dupeVals(array, [times]) ⇒ Array.<any>
  • .dedupe(arrayOfThings) ⇒ Array.<any>
  • .dedupeVal(arr, keyNames) ⇒ Array.<any>
  • .chunk(sourceArray, chunkSize) ⇒ Array.<any>
  • .shuffle(array, [mutate]) ⇒ Array.<any>
  • .range(min, max, [step]) ⇒ Array.<number>
  • .deepFlat(arr) ⇒ Array.<any>
  • .strToArr(str) ⇒ Array.<string>

arrays.dupeVals(array, [times]) ⇒ Array.<any>

duplicate values within an array N times

Kind: static method of arrays
Returns: Array.<any> - duplicated array

Param	Type	Default	Description
array	Array.<any>		array to duplicate
[times]	number	1	number of dupes per item; default 1

Example

dupeVals(["a","b","c"]) // => [ 'a', 'b', 'c', 'a', 'b', 'c' ]

arrays.dedupe(arrayOfThings) ⇒ Array.<any>

de-dupe array of objects w/Set, stringify, parse

Kind: static method of arrays
Returns: Array.<any> - deduped array

Param	Type	Description
arrayOfThings	any	array to dedupe

arrays.dedupeVal(arr, keyNames) ⇒ Array.<any>

de-dupe array of objects by value of specific keys

Kind: static method of arrays
Returns: Array.<any> - deduped array of objected

Param	Type	Description
arr	Array.<any>	array to dedupe
keyNames	Array.<string>	key names to dedupe values on

arrays.chunk(sourceArray, chunkSize) ⇒ Array.<any>

chunk array of objects into array of arrays with each less than or equal to chunkSize

• [{},{},{},{}] => [[{},{}],[{},{}]]

Kind: static method of arrays
Returns: Array.<any> - chunked array

Param	Type	Description
sourceArray	Array.<any>	array to batch
chunkSize	number	max length of each batch

arrays.shuffle(array, [mutate]) ⇒ Array.<any>

fisher-yates shuffle of array elements

Kind: static method of arrays
Returns: Array.<any> - shuffled array

Param	Type	Default	Description
array	Array.<any>		array to shuffle
[mutate]	boolean	false	mutate array in place? default: false

arrays.range(min, max, [step]) ⇒ Array.<number>

the classic python built-in for generating arrays of integers

Kind: static method of arrays
Returns: Array.<number> - a range of integers

Param	Type	Default	Description
min	number		starting number
max	number		ending number
[step]	number	1	step for each interval; default 1

arrays.deepFlat(arr) ⇒ Array.<any>

recursively and deeply flatten a nested array of objects

• ex: [ [ [{},{}], {}], {} ] => [{},{},{},{}]

Kind: static method of arrays
Returns: Array.<any> - flat array

Param	Type	Description
arr	Array.<any>	array to flatten

arrays.strToArr(str) ⇒ Array.<string>

extract words from a string as an array

• ex "foo bar baz" => ['foo','bar','baz']

Kind: static method of arrays
Returns: Array.<string> - extracted words

Param	Type	Description
str	string	string to extract from

functions

function utilities

• functions
  • .attempt(fn, ...args)
  • .times(n, iteratee)
  • .throttle(func, wait, [options])
  • .compose() ⇒ function
  • .id(any) ⇒ any

functions.attempt(fn, ...args)

try{} catch{} a function; return results

Kind: static method of functions

Param	Type
fn	function
...args	any

functions.times(n, iteratee)

do a function N times

Kind: static method of functions

Param	Type	Description
n	number	number of times
iteratee	function	function to run

functions.throttle(func, wait, [options])

throttle a functions's execution every N ms

Kind: static method of functions

Param	Type	Default	Description
func	function		function to throttle
wait	number		ms to wait between executions
[options]	object	{leading: true, trailing: false}

functions.compose() ⇒ function

compose functions, left-to-right

• ex: c(a,b,c) => a(b(c()))

Kind: static method of functions
Returns: function - a composed chain of functions

functions.id(any) ⇒ any

a function which returns it's value

Kind: static method of functions
Returns: any - the same thing

Param	Type	Description
any	any	anything

logging

logging, timers and other diagnostic utilities

• logging
  • .cLog(data, [message], [severity], [isCloud])
  • .log(item, [depth], [maxDepth]) ⇒ void
  • .progress(thing, p, message) ⇒ void
  • .time(label) ⇒ Timer
  • .quickTime(callback)
  • .tracker([app], [token], [distinct_id]) ⇒ function
  • .sleep(ms)
  • .clip(data) ⇒ void

logging.cLog(data, [message], [severity], [isCloud])

a cloud function compatible console.log()

Kind: static method of logging

Param	Type	Default	Description
data	string | JSON | object		data to log; preferably structured
[message]	string		accompanying message
[severity]	string	`INFO`	google sev label; default INFO
[isCloud]	boolean	true	force cloud logging

logging.log(item, [depth], [maxDepth]) ⇒ void

a comprehensive logging utility in all terminal environments

Kind: static method of logging

Param	Type	Default	Description
item	any		an item to log
[depth]	number	0	depth to log
[maxDepth]	number	100	maximum nested depth

logging.progress(thing, p, message) ⇒ void

dumb progress bar; incrementing console message

• ex: thing message #

Kind: static method of logging

Param	Type	Description
thing	string	what is being
p	number	the number to show
message	string	-

logging.time(label) ⇒ Timer

returns a timer with the following API

• timer.start()
• timer.end()
• timer.report()
• timer.prettyTime()

Kind: static method of logging
Returns: Timer - a time

Param	Type	Description
label	string	name for timer

logging.quickTime(callback)

a very quick way to check the length of a function; uses console.time

• ex: timeTaken(main)

Kind: static method of logging

Param	Type
callback	function

logging.tracker([app], [token], [distinct_id]) ⇒ function

track stuff to mixpanel

• ex: var t = track(); t('foo', {bar: "baz"})

Kind: static method of logging
Returns: function - func with signature: (event, props = {}, cb = (res)=>{})

Param	Type	Default	Description
[app]	string	'akTools'	value of $source prop
[token]	string	\99a1209a992b3f9fba55a293e211186a</code>	mixpanel token
[distinct_id]	string	os.userInfo().username	distinct_id

logging.sleep(ms)

arbitrary sleep for N ms

Kind: static method of logging

Param	Type	Description
ms	number	amount of time to sleep

logging.clip(data) ⇒ void

copy arbitrary data to your clipboard

Kind: static method of logging
Returns: void - but there's data on your clipboard!

Param	Type	Description
data	any	data to put on your clipboard

generalObject : Object.<string, any>

generic for {} w/string keys

Kind: global typedef

arrayOfObjects : Array.<generalObject>

generic for [{},{},{}]

Kind: global typedef

GCSUri

Kind: global typedef
Properties

Name	Type
uri	string
bucket	string
file	string

filterCallback : function

Kind: global typedef

Param	Type	Description
keyOrValue	string	object's value or key to test