Skip to content

Latest commit

 

History

History
726 lines (478 loc) · 23.2 KB

API.md

File metadata and controls

726 lines (478 loc) · 23.2 KB
Raw

Classes

DateUtils

Utilities for working with dates.

ModuleUtils

Utilities for working with modules, or understanding the code itself.

ObjectUtils

Object utility functions.

PromiseUtils

Utilities for dealing with Promises.

VMUtils

Utilities for working with the underlying virtual machine.

DateUtils

Utilities for working with dates.

Kind: global class

dateUtils.SECOND

Returns the number of milliseconds in a single second.

Kind: instance property of DateUtils

dateUtils.MINUTE

Returns the number of milliseconds in a single minute.

Kind: instance property of DateUtils

dateUtils.HOUR

Returns the number of milliseconds in a single hour.

Kind: instance property of DateUtils

dateUtils.DAY

Returns the number of milliseconds in a single day.

Kind: instance property of DateUtils

dateUtils.WEEK

Returns the number of milliseconds in a single week.

Kind: instance property of DateUtils

dateUtils.DAYS_OF_WEEK

Returns an array of the days of the week, in english.

Kind: instance property of DateUtils

dateUtils.DAYS_OF_WEEK3

Returns an array of the shortened 3 character days of the week, in english.

Kind: instance property of DateUtils

dateUtils.DAYS_OF_WEEK2

Returns an array of the shortened 2 character days of the week, in english.

Kind: instance property of DateUtils

dateUtils.MONTHS

Returns an array of the months of the year, in english.

Kind: instance property of DateUtils

dateUtils.MONTHS3

Returns an array of the shortened 3 character months of the year, in english.

Kind: instance property of DateUtils

dateUtils.floor(date, to) ⇒ Date

Given some date, floor it to the nearest to argument, where to is some number of milliseconds. For example, to floor to the nearest minute you would do floor(date,60000) where 60000 is the number of milliseconds in a single date. You can use this in conjunction with SECOND, MINUTE, HOUR, and DAY. See also floorSecond(), floorMinute(), floorHour(), and floorDay() below.

Kind: instance method of DateUtils

Param Type Default
date Date | number | string
to Number 0

dateUtils.floorSeconds(date) ⇒ Date

Floor the given date to the nearest second.

Kind: instance method of DateUtils

Param Type
date Date | number | string

dateUtils.floorMinutes(date) ⇒ Date

Floor the given date to the nearest minute.

Kind: instance method of DateUtils

Param Type
date Date | number | string

dateUtils.floorHours(date) ⇒ Date

Floor the given date to the nearest hour.

Kind: instance method of DateUtils

Param Type
date Date | number | string

dateUtils.floorDays(date) ⇒ Date

Floor the given date to the nearest day.

Kind: instance method of DateUtils

Param Type
date Date | number | string

dateUtils.from(date) ⇒ Date

Given some date or date line object, return a Date object. This allows you to quickly move between different types of date like objects. It will parse numbers as a unix epoch, a string of numbers as a unix epoch, JS Date object as a Date Object, or a String as a Date.parse() call.

Basically, it does its best to return a Date Object or an exception.

Kind: instance method of DateUtils

Param Type
date Date | number | string

dateUtils.computeDayOfYear(date) ⇒ number

Given some date, compute what day of the year it is.

Kind: instance method of DateUtils

Param Type
date Date | number | string

dateUtils.format(date, pattern) ⇒ string

Format a given date using a given pattern. Patterns are built using the following chart similar to how momentjs, datejs, php strftime, Java SimpleDateFormat, etc.

You use one or more of the patterns from above to create a pattern. You may also use literals in your pattern like YYYYMMDD'T'HHMMSSSSS'ZULU' where both 'T' and 'ZULU' are literals and are inserted verbatim.

Pattern Substitution Example against July 20, 1969, 20:18:04.017 UTC
YY 2 digit year. 69
YYYY 4 digit year. 1969
M numeric month, not zero filled. 7
MM numeric month, zero filled. 07
MMM shortened 3 character month name. Jul
MMMM full month name July
D numeric day of month, not zero filled. 20
DD numeric day of month, zero filled. 20
DDD numeric day of year, not zero filled. 200
DDDD numeric day of year, zero filled. 200
d numeric day of the week (0=sunday). 0
dd shortened 2 character day of the week Su
ddd shortened 3 character day of the week Sun
dddd full textual day of the week Sunday
A AM or PM. PM
a am or pm. pm
H 24 0 based hour of day, not zero filled. 20
HH 24 0 based hour of day, zero filled. 20
h 12 hour of day, not zero filled. 8
hh 12 hour of day, zero filled. 8
k 24 1 based hour of day, not zero filled. 21
kk 24 1 based hour of day, zero filled. 21
m minute of hour, not zero filled. 18
mm minute of hour, zero filled. 18
s second of minute, not zero filled. 4
ss second of minute, zero filled. 04
S milliseconds of second, not zero filled. 17
SSS milliseconds of second, zero filled. 017
z textual time zone UTC
Z relative time zone with separator -00:00
ZZ relative time zone without separator -0000
X unix timestamp (seconds) -14182916
x unix timestamp (milliseconds) -14182916000

Kind: instance method of DateUtils

Param Type
date Date | number | string
pattern string

ModuleUtils

Utilities for working with modules, or understanding the code itself.

Kind: global class

moduleUtils.resolve(mod, filename) ⇒ string

Resolves a given filename relative to a given module.

Kind: instance method of ModuleUtils

Param Type
mod Module
filename string

moduleUtils.require(mod, filename) ⇒ string

Requires a filename, relative to a given module.

Kind: instance method of ModuleUtils

Param Type
mod Module
filename string

moduleUtils.unrequire(mod, [removeChildren]) ⇒ number

Removes a module from the require cache, thus making it reload again if required. Also, any children that were loaded by the given module are also removed.

Returns the total number of modules removed.

You may optional indicate if the unrequire should remove dependant children as well. This can have unwanted side-effects so use with caution.

Kind: instance method of ModuleUtils

Param Type Default Description
mod module | string
[removeChildren] boolean false removeChildren

moduleUtils.moduleSource(depth) ⇒ string

Returns the filename of the code that called this function. This works by throwing and catching an exception and then reading the stack trace of the exception and finding the info it needs.

depth specifies how far back into the stack we should go. So if you want the caller of this function, set it to 0 (or omit it). If you want the caller of the caller of this function, set it to 1. etc.

Kind: instance method of ModuleUtils

Param Type Default
depth number 0

moduleUtils.moduleStack(mod, [start], [end]) ⇒ Array.<String>

Returns the module require stack for the given module. That is, how was the given module imported (required) into the current execution.

This returns an array of strings, which are the module ancestor module.id values.

Kind: instance method of ModuleUtils

Param Type Default
mod module
[start] Number 0
[end] Number start+10

ObjectUtils

Object utility functions.

Kind: global class

objectUtils.isPlainObject(obj) ⇒ Boolean

Returns true oif the given object is a "plain" javascript object, meaning it doesn't inherit from some other type of js object like an array, date, error, etc.

Kind: instance method of ObjectUtils

Param Type
obj Object

objectUtils.extend(target, ...sources) ⇒ Object

deep clone of each given source into the target.

Kind: instance method of ObjectUtils

Param Type
target Object | null
...sources Object

objectUtils.deepFreeze(obj) ⇒ void

Call Object.freeze() on the object and each property of the object, essentially freezing the entire structure.

Kind: instance method of ObjectUtils

Param Type
obj Object

objectUtils.paths(obj, path, [leafsOnly], [delimiter]) ⇒ Array.<string>

Return an array of all possible paths for a given object.

Kind: instance method of ObjectUtils

Param Type Default
obj Object
path string
[leafsOnly] Boolean false
[delimiter] String "."

objectUtils.get(obj, path, [defaultValue], [delimiter]) ⇒ *

Get a value for a given path of a given object.

Kind: instance method of ObjectUtils

Param Type Default
obj Object
path string
[defaultValue] *
[delimiter] String "."

objectUtils.set(obj, path, value, [delimiter]) ⇒ Object

Set a value for a given path of a given object.

Kind: instance method of ObjectUtils

Param Type Default
obj Object
path string
value *
[delimiter] String "."

objectUtils.delete(obj, path, [prune], [delimiter]) ⇒ Object

Delete a value for a given path of a given object.

Kind: instance method of ObjectUtils

Param Type Default
obj Object
path string
[prune] Boolean true
[delimiter] String "."

PromiseUtils

Utilities for dealing with Promises.

Kind: global class

promiseUtils.sleep(duration) ⇒ Promise

Creates a promise that resolves after n milliseconds. Great for usage with await for delaying some period of time.

Kind: instance method of PromiseUtils

Param Type
duration number

promiseUtils.series(array, f) ⇒ Promise

Execute the given function for each cell of the array, in series order. If the given function returns a Promise, the promise will await resolution before the function is called next. This creates a series execution of an array of Promise executions. On a reject, all remaining executions are skipped.

The given function is called with the signature f(item,index,originalArray,resultsArray).

Kind: instance method of PromiseUtils

Param Type
array Array.<Promise>
f function

promiseUtils.timeout(promise, [ttl], [timeoutException]) ⇒ Promise

In essence this lets you wrap a promise in a timeout such that if the timeout occurs before the promise resolves or reject, this rejects.

Returns a promise that will resolve/reject if the passed in promise resolves or rejects before the passed in ttl time has elapsed. If the ttl time does elsapse, the returned promise will reject (with the optional exception) and the passed in promise resolve or reject will be swallowed.

Kind: instance method of PromiseUtils

Param Type Default
promise Promise
[ttl] number 30000
[timeoutException] Error new Error("Timed out.")

VMUtils

Utilities for working with the underlying virtual machine.

Kind: global class

vmUtils.executionLine(depth) ⇒ number

Returns the line number of the code of the line that called the line() function. This works by throwing and catching an exception and then reading the stack trace of the exception and finding the info it needs.

depth specifies how far back into the stack we should go. So if you want the caller of this function, set it to 0 (or omit it). If you want the caller of the caller of this function, set it to 1. etc.

Kind: instance method of VMUtils

Param Type Default
depth number 0

vmUtils.executionSource(depth) ⇒ string

Returns the filename of the code that called this function. This works by throwing and catching an exception and then reading the stack trace of the exception and finding the info it needs.

depth specifies how far back into the stack we should go. So if you want the caller of this function, set it to 0 (or omit it). If you want the caller of the caller of this function, set it to 1. etc.

Kind: instance method of VMUtils

Param Type Default
depth number 0

vmUtils.executionSourceAndLine(depth) ⇒ string

Returns the filename and line number of the code that called this function. This works by throwing and catching an exception and then reading the stack trace of the exception and finding the info it needs.

depth specifies how far back into the stack we should go. So if you want the caller of this function, set it to 0 (or omit it). If you want the caller of the caller of this function, set it to 1. etc.

Kind: instance method of VMUtils

Param Type Default
depth number 0

vmUtils.executionStack([start], [end]) ⇒ Array.<Object>

Returns the currently running stack trace, as an array of objects (see below) that describes where in the current execution stack the application currently is.

The returned array is comprised of stack entry objects which have the following shape:

entry = {
  entry: string - the full stack trace entry string
  method: the method name from the stack trace entry
  source: the filename the method is in
  line: the line number the execution is on
  position: the line position the execution is on
}

Kind: instance method of VMUtils

Param Type Default
[start] Number 0
[end] Number 10