ak-tools v1.0.54

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

Functions

Typedefs

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

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

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)

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)

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)

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

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!

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