ack-x

Extra functional library to objectify & compartmentalize variables into wrappers that make invokation & injection processes, lighter & easier to implement.


Table of Contents

- Install
- Import
- NodeJs
- Web Browser
- TypeScript
- Usage Documentation
- getBoolean
- isBooleanLike
- nullsToEmptyString
- getBit
- stringify
- get
- byName
- ack.date
- ack.array
- ack.method
- ack.error
- ack.number
- ack.object
- ack.string
- More Examples

Install

``
npm install ack-x
`

Import

$3

`javascript
require("ack-x").ack
`

$3

`javascript
require("ack-x/browser").ack
`

$3

`javascript
import { ack } from "ack-x/browser"
`

Usage Documentation

$3

reduces variable to a true/false
`javascript
ack('y').getBoolean() == true
`

$3

`javascript
ack('y').isBooleanLike == true
`

$3

`javascript
ack({x:null, y:null}).nullsToEmptyString == {x:'', y:''}
`

$3

returns only 0 or 1. Negative numbers will be 0
`javascript
ack(-2).getBit() == 0
`

$3

JSON.stringify with default spacing=2
`javascript
ack({x:22, y:33}).stringify() == {
"x":22,
"y":33
}
`

$3

case insensative object key search
`javascript
ack({XxX:22}).get('xXx') == 22
`

$3

Returns another ack class object based on case insensative object key search
`javascript
ack({XxX:{YyY:33}}).byName('xXx').get('yYy') == 33
`

Back to Top

ack.date

- ack.date.addDays
- ack.date.dayOfYear
- ack.date.daysFromNow
- ack.date.from
- ack.date.fromNow
- ack.date.fromToday
- ack.date.now
- ack.date.format
- ack.date.storageFormat
- ack.date.addYears
- ack.date.yearsFromNow
- ack.date.greater
- ack.date.lesser
- ack.date.getUtcDate
- ack.date.utc
- ack.date.toUtc
- ack.date.gotoFirstDayOfMonth
- ack.date.gotoFirstDayOfWeek
- ack.date.gotoLastDayOfMonth
- ack.date.gotoLastDayOfWeek
- ack.date.dateWeekDiff

$3

`javascript
ack.date().now().addYears(5).yearsFromNow() == 5
ack.date().now().addMonths(5).monthsFromNow() == 5
ack.date().now().addDays(5).daysFromNow() == 5

ack.date().now().addYears(-1).fromNow(true) == 'a year'
ack.date().now().addYears(-1).fromNow() == 'a year ago'

ack.date().now().from( new Date()-31536000000 ) == 'a year ago'
`

$3


`javascript
ack.date('2016-12-28').addDays(-2).getDate() == 26
`

$3

`javascript
ack.date('2016-12-28').dayOfYear() == 362
`

$3

`javascript
ack.date().now().addDays(-2).daysFromNow() == 2
`

$3

`javascript
var d = ack.date().now().addMinutes(-15).date

ack.date().now().from(d) == '15 minutes ago'
ack.date().now().from(d, true) == '15 minutes'
`

$3


`javascript
ack.date().now().addMinutes(-15).fromNow() == '15 minutes ago'
ack.date().now().addMinutes(-15).fromNow(true) == '15 minutes'
`

$3

`javascript
ack.date().now().gotoSod().addDays(-2).fromToday() == '2 days ago'
ack.date().now().gotoSod().addDays(-2).fromToday(true) == '2 days'
`

$3

Goto End of Day
`javascript
ack.date().now().gotoEod().hhmmsstt() == '11:59:59 PM'
`

$3

Goto Start of Day
`javascript
ack.date().now().gotoSod().hhmmsstt() == '00:00:00 AM'
`

$3

Example of getting at raw Date variable
`javascript
const d = new Date()
ack.date(d).date == d
`

$3

`javascript
ack.date().now().date.getMinutes() == new Date().getMinutes()
`

$3

See moment.js format function
`javascript
ack.date().now().format('YYYY-MM-DD hh:mm:A') == '2017-08-08 01:40:PM'
`

$3

`javascript
ack.date().now().hhmmsstt() == '01:40:00 PM'
`

$3

`javascript
ack.date().now().hhmmsstt() == '01:40:00.0'
`

$3

yyyy-mm-dd hh:nn:ss:l
`javascript
ack.date().now().storageFormat() == '2017-04-20 01:35:05.845'
`

$3

`javascript
ack.date().now().addYears(5).date.getFullYear() == new Date().getFullYear()+5

$3

`javascript
ack.date().now().yearsFromNow() - new Date().getFullYear() == 0
`

$3

Check if argument date is greater than defined date
`javascript
ack.date().now().greater( Date.now()+200 ) == true
`

$3

Check if argument date is lesser than defined date
`javascript
ack.date().now().lesser( Date.now()-200 ) == true
`

$3

Takes current Date and returns casted utc set Date object

$3

Takes current Date and returns casted utc set Date number

$3

Takes current Date and casts to utc set Date number. Returns this

$3

`
var date = ack.date('4/2/2018').gotoFirstDayOfMonth()
assert.equal(date.mmddyyyy(),'04/01/2018')
`

$3

`
var date = ack.date('4/1/2018').gotoFirstDayOfWeek()
assert.equal(date.mmddyyyy(),'04/01/2018')
`

$3

`
var date = ack.date('4/1/2018').gotoLastDayOfMonth().gotoLastDayOfWeek()
assert.equal(date.mmddyyyy(),'05/05/2018')
`

$3

`
var date = ack.date('4/1/2018').gotoLastDayOfWeek()
assert.equal(date.mmddyyyy(),'04/07/2018')
`

$3

`
ack.date().addDays(7).dateWeekDiff( Date.now() ) === 1
ack.date().addDays(14).dateWeekDiff( Date.now() ) === 2
ack.date().addDays(15).dateWeekDiff( Date.now() ) === 2
`

Back to Top

ack.array

- distinct
- objectify
- appendArray
- prependArray
- reduce
- map
- sum
- average
- group

`javascript
var a = []

/**
Intended for high performance by looping an array only once but performing multiple actions.
Run multiple functions for each iteration of an array.

Example: array.each(countTeacher, countChild) instead of two loops array.each(countTeacher) + array.each(countChild)
*/
ack.array(a).each(method0, method1, method2, method3)
`

$3

reduce array down to only distinct items
- @method - optional, returned value is used to determine distinctness

`javascript
ack.array(a).distinct(method)
`

$3


pivets array of objects to object of arrays
`javascript
ack.array(a).objectify()
`

$3

append an array's items onto the end of this array
`javascript
ack.array(a).appendArray(array)
`

$3

prepend an array's items onto the front of this array
`javascript
ack.array(a).prependArray(array)
`

$3

reduces an array to a single value
- @method : (accumlatedValue:any,value:any,index:number,array:any[]) => any
- @initValue? : any

`javascript
ack.array(a).reduce(method)
`

$3

produce a new array
- @method : (value:any,index:number,array:any[]) => any

`javascript
ack.array(a).map(method)
`

$3

ads an array all up
- @method? : (value:any)=>any

`javascript
ack.array(a).sum(method)
`

$3

ads an array all up
- @method? : (value:any)=>any

`javascript
ack.array(a).average(method)
`

$3

break an array into buckets of arrays
- @isIndexValue=false - when true, buckets of arrays will be corresponding index values back to original array
- @grouptype='sequence' - ('sequence'||'struct') . 'sequence', array of arrays = [ [],[],[] ] . 'struct' = {value0:[buckets...], value1:[buckets...]}

`javascript
ack.array(a).group(method, isIndexValue, grouptype)
`

Back to Top

ack.method

Holds a function in memory and offers convenient methods to invoke set method

$3

sets a timeout and then runs set method in milsecs
`javascript
var f = function(){}

ack.method(f).runInMs(ms)
`

$3


gets name of defined function
`javascript
ack.method(f).getName()
`

$3

returns array of argument names defined within set function
`javascript
ack.method(f).getArgNameArray()
`

$3

get set functions inner definition
`javascript
ack.method(f).getDefinition()
`

$3

This is an option enhanced version of expectOne
`javascript
ack.method(f).expect(nameOrMap, value, requiredOrType, type)
`

$3

Build argument validation for when set function is invoked.
- @name - argument-name
- @value - runtime value argument-value
- @required
- @type - requiredOrType - true/false or constructor validation. When constructor validatation, required is true. When undefined, required is true

`javascript
ack.method(f).expectOne(name, value, requiredOrType, type)
`

Back to Top

ack.error

great for standardizing error control

$3

returns all object keys of an error which is takes extra steps
`javascript
var e = new Error()

ack.error(e).getKeys()
`

$3


converts error.stack into array via stack.split(' at ')
`javascript
ack.error(e).getStackArray(amount)
`

$3

dig out just the stack trace from error
`javascript
ack.error(e).getTraceArray(amount)
`

$3

dig out only just the first trace of errors stack trace
`javascript
ack.error(e).getFirstTrace(amount)
`

$3

`javascript
ack.error(e).setStackArray(stackArray)
`

$3

analyzes stack to remove 1st trace (leaves error message in stack). Essentially calls .splice(1,1) on stack array
`javascript
ack.error(e).cutFirstTrace()
`

$3

attempt to extract a line number from the error
`javascript
ack.error(e).getLineNum()
`

$3

attempt to extract a file path from the error
`javascript
ack.error(e).getFilePath()
`

$3

attempt to extract the error's name
`javascript
ack.error(e).getName()
`

$3

attempt to extract the named function or code that is running
`javascript
ack.error(e).getFailingObjectName()
`

$3

get a message from the error even if it has no message
`javascript
ack.error(e).getMessage()
`

$3

attempt to extract the error's type
`javascript
ack.error(e).getType()
`

$3

attempt to compare error with another error or another type of an error
`javascript
ack.error(e).isType(type)
`

$3

Use these errors to standardized error flow
`javascript
ack.error().types.notFound( message )
ack.error().types.localNetworkRequired( message )
ack.error().types.unauthorized( message )
ack.error().types.badRequest( message )
ack.error().types.methodNotAllowed( message )
`

TYPES OF ERRORS, Object Details
`javascript
ack.error().types.NotFound(message){
this.status = 404;
this.code = "not_found";
this.message = message || "Could Not Find Requested Resource";
}

ack.error().types.LocalNetworkRequired(message){
this.status = 403;
this.code = "local_network_required";
this.message = message || "Local Network Connection Required";
}

ack.error().types.Unauthorized = function(message){
this.status = 401;
this.code = "credentials_required";
this.message = message || "No authorization token was found";
}

ack.error().types.BadRequest = function(message){
this.status = 400;
this.code = "bad_request";
this.message = message || "Bad Request";
}

ack.error().types.MethodNotAllowed = function(message){
this.status = 405;
this.code = "method_not_allowed";
this.message = message || "Method Not Allowed";
}
`

Back to Top

ack.number

Convenient methods to handle numbers

- decimalFormat
- asMinutesToDateTime
- asMinutesToTime

$3

- @p - decimal places
`javascript
var n = 10

ack.number(n).decimalFormat(p)
`

$3

convert set number into how many minutes into a date. Ex: 60 = new Date('2016-01-16 1:00:00.0')
- @options - {}
- @options.date - default=new Date()

`javascript
ack.number(n).asMinutesToDateTime(options)
`

$3

convert set number into how many minutes into a string date. Ex: 60 = 1:00 AM')
- @options = {}
- @options.timeDelim - default=':'
- @optiosn.dayPeriodDelim - default=' '

`javascript
ack.number(n).asMinutesToTime(options)
`

Back to Top

ack.object

- assign
- deepAssign
- forEach
- map
- getTypeMap
- isCyclic

$3

Works exactly like Javascript built-in function Object.assign(, {})

- Returns ack.object
- @method(item0, item1, item2)

`javascript
var from = {b:2,c:{ca:0}}
var copy = {a:1,b:1}
ack.object( copy ).assign( from )

copy.c.ca = 1

from == {b:2,c:{ca:1}}
copy == {a:1,b:2,c:{ca:1}}
`

$3

Works exactly like Javascript built-in function Object.assign(, {}) with the addition of recursive cloning

- Returns ack.object
- @method(item0, item1, item2)

`javascript
var from = {b:2,c:{ca:0}}
var copy = {a:1,b:1}
ack.object( copy ).deepAssign( from )

copy.c.ca = 1

from == {a:1,b:2,c:{ca:0}}
copy == {a:1,b:2,c:{ca:1}}
`

$3

- @method(item, index, object)

`javascript
var o = {}

ack.object(o).forEach(method)
`

$3

this.object will be the map result
- @method(item, index, object)

`javascript
ack.object(o).map(method)
`

$3


Crawls any variable type to generate a map of types
`javascript
var v = {
a:1,b:2,
c:{
c0:0,
c1:'a string here'
},
agency:[{
name:'My Agency'
},{
name:'Toast',
email:'fake@aol.com',
active:0
}]
}

//Example A
ack.object(v).getTypeMap() == {
a: 'number',
b: 'number',
c: { c0: 'number', c1: 'string' },
agency: [{ name: 'string', email: 'string', active: 'number' }]
}

//Example B
ack.object(v).getTypeMap(function(type, subs, key){
return {type:type, subs:subs, key}
}) == {
"a": {
"type": "number",
"subs": null
},
"b": {
"type": "number",
"subs": null
},
"c": {
"type": "object",
"subs": {
"c0": {
"type": "number",
"subs": null
},
"c1": {
"type": "string",
"subs": null
}
}
},
"agency": {
"type": "array",
"subs": {
"type": "object",
"subs": {
"name": {
"type": "string",
"subs": null
},
"email": {
"type": "string",
"subs": null
},
"active": {
"type": "number",
"subs": null
}
}
}
}
}
`

$3


tests Object for circular references
`javascript
ack.object(o).isCyclic()
`

like JSON.stringify but converts all to cookie definition
`javascript
ack.object(o).toCookieString()
`

Back to Top

ack.string

- isEmail
- repeat
- htmlFormat
- toBase64
- _utf8_encode

$3


test string against email regX
`javascript
var s = 'String'
ack.string(s).isEmail()
`

$3

Node.js doesnt have .repeat as of 2/11/15
`javascript
ack.string(s).repeat(num)
`

$3

escapes html brackets
`javascript
ack.string(s).htmlFormat()
`

$3

string becomes really long
`javascript
ack.string(s).toBase64()
`

$3

convert string to something more safely portable

`javascript
ack.string(s)._utf8_encode()
`

Back to Top

More Examples

Simple Example of Variable Exposing


`javascript
//get date object for the first hour, minute and second of the first day of month
var aDate = require('ack-x').ack.date().now()
var startOfDate = aDate.gotoFirstDayOfMonth().gotoStartOfDate()
var monthStartsExactlyAt = startOfDate.date

console.log( monthStartsExactlyAt )
`




$3


In the following example, many modules are used to manipulate variables
`javascript
var ack = require('ack-x').ack
var xDate = ack.date().now()//expose date as now

ack.promise(
xDate.getNextYear(),//promise val0 is next year as number
xDate.nextYear(2).year(),//promise val1 is the year as number, in two years
xDate.getNextYear(3)//promise val2 is the year as number, in two years
)
.then(function(y0, y1, y2){
return y0 < y1 && y1 < y2
})
.if(false, function(){
return 'Time is going in reverse'
})
.if(true, function(){
return 'Time is going in correct direction'
})
.then( ack.string )//The promise string value, is injected into the string variable exposer
.call('toBase64')//The exposed string variable is casted to base64
.then( console.log )//log results of base64
.catch(function(e){
console.log(e)
})
``