ak-tools
Advanced tools
Readme
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.
/**
* 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)
file management utilities
data validation utilities
display, formatting, and other make it look right utilities
functions for maths, crypto, and maths
object utilities
array utilities
function utilities
logging, timers and other diagnostic utilities
stringgenerate a random name (adjective + noun + verb + adverb)
Object.<string, any>generic for {} w/string keys
Array.<generalObject>generic for [{},{},{}]
functionfile management utilities
Promise.<(Array.<string>|generalObject)>Promise.<(string|boolean|void)>Promise.<(string|false)>Promise.<(string|generalObject|arrayOfObjects|any)>stringPromise.<(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) // => {}
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
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
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
| 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
stringmake a directory with error handling and confirmation.
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')
data validation utilities
booleanbooleanbooleanbooleanbooleanGCSUribooleantest if string has JSON structure
Kind: static method of validate
| Param | Type |
|---|---|
| string | string |
Example
isJSONStr('{"foo": "bar"}') // => true
booleantest if data can be stringified as JSON
Kind: static method of validate
| Param | Type |
|---|---|
| data | string | JSON |
Example
isJSON({foo: "bar"}) // => true
booleancheck 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
booleancheck if a val is null or undefined
Kind: static method of validate
| Param | Type | Description |
|---|---|---|
| val | any | value to check |
Example
isNil(null) // => true
booleancheck 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
GCSUriturn 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"}
turns a string into a boolean
Kind: static method of validate
| Param | Type |
|---|---|
| string | string |
display, formatting, and other "make it look right" utilities
stringstringstringstring | falsestringstringstringstringstringturn 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"
stringtruncate 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...'
stringturn 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'
string | falsestringify 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"}'
stringstrip 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"
stringfind 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"
stringreplace 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'
stringconvert 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"'
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"}
functions for maths, crypto, and maths
numbernumbernumbernumberstringstringstringnumberrandom 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
numbercalculate 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
numbercalculate 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
numberround 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
stringgenerate 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'
stringgenerated 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"
stringcalculate 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"
object utilities
generalObjectgeneralObjectgeneralObjectgeneralObjectgeneralObjectbooleanObjectObjectPromise.<generalObject>ObjectObjectObjectstringgeneralObjectrename 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"}
generalObjectrename 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"}
generalObjectfilter 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"}
generalObjectremoves 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: ""}) // => {}
generalObjectapply 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'}
booleandeep 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
Objectefficient 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 } } }
Objectvisit 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}}
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"}
Objectexplicitly 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"}
Objectdeeply 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"}
Objectmap 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}
stringfind 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"
array utilities
Array.<any>Array.<any>Array.<any>Array.<any>Array.<any>Array.<number>Array.<any>Array.<string>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' ]
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 |
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 |
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 |
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 |
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 |
Array.<any>recursively and deeply flatten a nested array of objects
[ [ [{},{}], {}], {} ] => [{},{},{},{}]Kind: static method of arrays
Returns: Array.<any> - flat array
| Param | Type | Description |
|---|---|---|
| arr | Array.<any> | array to flatten |
Array.<string>extract words from a string as an array
"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 |
function utilities
try{} catch{} a function; return results
Kind: static method of functions
| Param | Type |
|---|---|
| fn | function |
| ...args | any |
do a function N times
Kind: static method of functions
| Param | Type | Description |
|---|---|---|
| n | number | number of times |
| iteratee | function | function to run |
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} |
functioncompose functions, left-to-right
c(a,b,c) => a(b(c()))Kind: static method of functions
Returns: function - a composed chain of functions
anya function which returns it's value
Kind: static method of functions
Returns: any - the same thing
| Param | Type | Description |
|---|---|---|
| any | any | anything |
logging, timers and other diagnostic utilities
voidvoidTimerfunctionvoidstringa cloud function compatible console.log()
Kind: static method of logging
| Param | Type | Default | Description |
|---|---|---|---|
| [message] | string | accompanying message | |
| data | string | JSON | object | data to log; preferably structured | |
| [severity] | string | `INFO` | google sev label; default INFO |
create a structured logger with initial properties
Kind: static method of logging
| Param | Type |
|---|---|
| initialProps | any |
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");
Deprecated
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 |
voida 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 |
voiddumb progress bar; incrementing console message
thing message #pKind: static method of logging
| Param | Type | Description |
|---|---|---|
| thing | string | what is being |
| p | number | the number to show |
| message | string | - |
Timerreturns 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 |
a very quick way to check the length of a function; uses console.time
timeTaken(main)Kind: static method of logging
| Param | Type |
|---|---|
| callback | function |
functiontrack stuff to mixpanel
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 |
arbitrary sleep for N ms
Kind: static method of logging
| Param | Type | Description |
|---|---|---|
| ms | number | amount of time to sleep |
voidcopy 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 |
stringcreate human readable time from milliseconds
Kind: static method of logging
Returns: string - human readable time
| Param | Type | Description |
|---|---|---|
| milliseconds | number | time to format |
stringgenerate a random name (adjective + noun + verb + adverb)
Kind: global function
Returns: string - a random name
Object.<string, any>generic for {} w/string keys
Array.<generalObject>generic for [{},{},{}]
Kind: global typedef
Properties
| Name | Type |
|---|---|
| uri | string |
| bucket | string |
| file | string |
functionKind: global typedef
| Param | Type | Description |
|---|---|---|
| keyOrValue | string | object's value or key to test |
FAQs
AK's collections of useful things...
We found that ak-tools demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Application Security
New SEC disclosure rules aim to enforce timely cyber incident reporting, but fear of job loss and inadequate resources lead to significant underreporting.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).
Security News
LDAPjs, an LDAP Client and Server API for Node.js, was decommissioned after its maintainer received an abusive email from a user, raising concerns about this form of abuse as a potential attack vector.