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

Functions

makeName() ⇒ string

generate a random name (adjective + noun + verb + adverb)

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|any)>
  • .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

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

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

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

load a file into memory

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

Example

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

files.mkdir([dirPath]) ⇒ string

make a directory with error handling and confirmation.

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

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
  • .toBool(string)

validate.isJSONStr(string) ⇒ boolean

test if string has JSON structure

Kind: static method of validate

Example

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

validate.isJSON(data) ⇒ boolean

test if data can be stringified as JSON

Kind: static method of validate

Example

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

validate.is(type, val) ⇒ boolean

check if a type matches a value

Kind: static method of validate

Example

is(Number, 42) // => true

validate.isNil(val) ⇒ boolean

check if a val is null or undefined

Kind: static method of validate

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?

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

Example

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

validate.toBool(string)

turns a string into a boolean

Kind: static method of validate

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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) ⇒ Object
  • .objMap(object, mapFn) ⇒ Object
  • .getKey(object, value) ⇒ string

objects.rnKeys(obj, newKeys) ⇒ generalObject

rename object keys with a mapping object

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

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

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

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

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

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?

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

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

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

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

Example

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

objects.flatten(obj, roots, sep) ⇒ Object

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

Kind: static method of objects

Example

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

objects.objMap(object, mapFn) ⇒ Object

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

Kind: static method of objects

Example

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

objects.getKey(object, value) ⇒ string

find a key in an object that has a particular value

Kind: static method of objects

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

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

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

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

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

fisher-yates shuffle of array elements

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

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

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

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

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

functions.times(n, iteratee)

do a function N times

Kind: static method of functions

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

throttle a functions's execution every N ms

Kind: static method of functions

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

logging

logging, timers and other diagnostic utilities

• logging
  • .sLog([message], data, [severity])
  • .logger(initialProps)
  • .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
  • .prettyTime(milliseconds) ⇒ string

logging.sLog([message], data, [severity])

a cloud function compatible console.log()

Kind: static method of logging

logging.logger(initialProps)

create a structured logger with initial properties

Kind: static method of logging

Example

// Creating a new structured logger with initial properties
const logger = createStructuredLogger({ app: "MyApp", module: "Main" });

// Logging a message with the structured logger
logger.log("Application started", { user: "JohnDoe" });

// Creating a child logger inheriting initial properties and adding new ones
const childLogger = logger.createChild({ subModule: "Auth" });

// Logging a message with the child logger
childLogger.log("User logged in", { user: "JohnDoe" }, "INFO");

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

Deprecated

a cloud function compatible console.log()

Kind: static method of logging

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

a comprehensive logging utility in all terminal environments

Kind: static method of logging

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

dumb progress bar; incrementing console message

• ex: thing message #p

Kind: static method of logging

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

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

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)=>{})

logging.sleep(ms)

arbitrary sleep for N ms

Kind: static method of logging

logging.clip(data) ⇒ void

copy arbitrary data to your clipboard

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

logging.prettyTime(milliseconds) ⇒ string

create human readable time from milliseconds

Kind: static method of logging
Returns: string - human readable time

makeName() ⇒ string

generate a random name (adjective + noun + verb + adverb)

Kind: global function
Returns: string - a random name

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

filterCallback : function

Kind: global typedef