Theory

Theory is an abstraction layer for server side and client side JavaScript.

Motivation

1. Deep existence. It all started because a program would crash via if(obj.x.y.z) rather than if(obj && obj.x && obj.x.y && obj.x.y.z), so I wanted an elegant way to check and access deeply nested objects in a safe yet concise manner.

2. Dependency management. You should not have to declare dependencies in another language (HTML) to import required code or rely on globals. Other tools that solve this foolishly break Node's style in order to make it work asynchronously.

3. Universal normalization. Write once, run everywhere. This dream gets broken when you discover different implementations of JavaScript behave in unique ways, whether browsers or phones and tablets, or IE6 versus server side. I needed a reliable yet tiny library (at 7KB gzipped) that would normalize everything so any code written would literally work everywhere.

Require

As simple as npm install theory on Node and a single <script src='./theory.js'></script> client side. The brilliant thing is that you do not have to declare anything else after that, you can handle the rest within your module.

module.exports=require('theory')
('hello', function(a){
	
	var say = "Hello World!";
	console.log(say);
	return say;
	
}, ['./needed', './dependency']);

This is the beautiful fix that works everywhere. You get your own closure which executes only after all your dependencies (and all of their sub-dependencies) have loaded - then whatever you return from your closure gets exported out!

Say you name this file as 'world.js', all you have to do is run node world.js on the server or put require('world') on the client inside the 'theory.js' script tag (or have a normal 'world.js' script tag below theory.js). All dependencies are relative to your file, not the HTML page or the parent module!

If the dependency you require uses some global variable, you can access it from there (such as jQuery) as usual. You can access theory as a global, but you should not use it globally - theory copies itself into the scope of each module (the a argument, henceforth used for the rest of this documentation).

All dependencies that use exports (normal Node modules and theory specific modules) get attached to your module's local scope with their base filename (a.needed and a.dependency in the example above). If you have conflicting names or just want a different name then use an object to declare dependencies instead of an array ({'./needed': 'foo', './dependency': 'bar'} become a.foo and a.bar). Theory modules also attach to their own namespace, such as theory.hello in above.

You can also specify sub dependencies, such as {'./jquery':['./jquery-ui', './jquery-ext']}. Define environment specific dependencies by checking for root.page or root.node. Finally, imports.js is an unmaintained version of just the require feature, without anything below.

Now let's dive into the API.

Binary

• is a.bi.is(what)

  • determines to see if what is a boolean or not.

  • Examples

    • a.bi.is(false) → true

    • a.bi.is(true) → true

    • a.bi.is(0) → false

    • a.bi.is('yes') → false

Numbers

• is a.num.is(what)

  • determines to see if what is a number or not.

  • Examples

    • a.num.is(0) → true

    • a.num.is(NaN) → false

    • a.num.is(1.1) → true

    • a.num.is(Infinity) → true

• ify a.num.ify(what, opt)

  • what is the number, text, whatever that needs to be converted into a number.

  • opt is options parameter.

    • [] indicates you want a list of numbers returned.

  • Examples

    • a.num.ify("A37") → 37

    • a.num("It is -22.7 degrees").ify() → -22.7

    • a.num("My values are 33, -2.2, and 6.").ify([]) → [33, -2.2, 6]

• random a.num.random(what) or a.num.r(what)

  • if what is a number, it represents how many digits long you want your random number.

  • if what is a list, it represents the inclusive range you want your random number to be in.

  • Note: Maximum length is 14, what defaults to 6.

  • Examples

    • a.num.random() → 583587

    • a.num(2).r() → 64

    • a.num([-10,10]).random() → -7

    • a.num.r([1,99]) → 99

Text

• is a.text.is(what)

  • determines to see if what is text or not.

  • Examples

    • a.text.is("") → true

    • a.text.is([]) → false

    • a.text.is("Hello World!") → true

• ify a.text.ify(what)

  • what is the number, text, list, object, whatever you want to turn into text.

  • Note: Essentially just a wrapper for JSON.stringify() for now.

  • Examples

    • a.text.ify({a:0,b:'1',c:[0,'1'],d:{e:'f'}}) → "{a:0,b:'1',c:[0,'1'],d:{e:'f'}}"

• random a.text.random(what, length) or a.text.r(what, length)

  • what is a text of allowed characters to be used. Defaults to alpha-numeric characters.

  • length is how many characters long you want your random text. Defaults to 16.

  • Note: Does not matter what order you call the parameters in.

  • Examples

    • a.text.random() → "uTkphuTCmzQ7Pl3e"

    • a.text.r("AaSsDdFf",4) → "fDds"

    • a.text(4).random("j$k4") → "kj$k"

    • a.text("randomize").r() → "oadomneradnimarz"

• clip a.text(what).clip(split, start, end)

  • what is the text to clip.

  • split is the text or regex to split and rejoin upon.

  • start is the start position of the slice.

  • end is the end position of the slice.

  • Examples

    • a.text('A B C D').clip(' ',0,-1) → "A B C"

    • a.text.clip("path/to/awesome.js",'.',-1) → "js"

• caps a.text.caps(what)

  • what is the text you want to capitalize.

  • Examples

    • a.text.caps("shout1") → "SHOUT1"

• low a.text.low(what)

  • what is the text you want to make lower case.

  • Examples

    • a.text.low("HUSH!") → "hush!"

• find a collection of Regular Expressions.

  • Note: No guarantee of these working or being available in future versions.

Lists

• is a.list.is(what)

  • determines to see if what is a list or not.

  • Examples

    • a.list.is([]) → true

    • a.list.is("list") → false

    • a.list.is([0,false]) → true

• ify a.list.ify(what, opt)

  • what is the text or object that you want to convert into a list.

  • opt is the options parameter.

    • split: what to divide upon for text, whitespace auto handled. ',' is default.

    • wedge: what token to use as the divider between an object’s key and value. ':' default.

  • Examples

    • a.list.ify("Bob, Joe,Isaac , Fred") → ["Bob","Joe","Isaac","Fred"]

    • a.list({a:1,b:'c',d:[1,2,3]}).ify() → ['a:1','b:c','d:0,1,2']

    • a.list({session:'AK41795'}).ify({wedge:'='}) → ['session=AK41795']

    • a.list.ify("1,2,3 ; 4,5,6",{split:';'}) → ["1,2,3", "4,5,6"]

• at a.list.at(what, index, opt)

  • what is the list you want to access.

  • index is the where in the list you want to retrieve the value.

  • opt is the options parameter.

    • ebb: causes an over reaching index to cascade till it finds the closest item.

  • Examples

    • a.list.at([5,6,7,8,9],-2) → 8

    • a.list([5,6,7,8,9]).at(2) → 6

    • a.list.at([2,3,4],9,{ebb:true}) → 4

    • a.list([0,1,2]).at(-9,{ebb:true}) → 0

    • a.list.at([5,6,7],-2,{ebb:true}) → 6

• fuse a.list.fuse(what, ...)

  • what is the list that other lists will fuse into.

  • … any number of extra list parameters.

  • Examples

    • a.list.fuse([2,3],[4,5],[6,7]) → [2,3,4,5,6,7]

    • a.list([2,3]).fuse([3,4],[4,5]) → [2,3,3,4,4,5]

• less a.list.less(what, ...)

  • what is the list you want to subtract items from.

  • … the items you want to remove from the list,

  • Examples

    • a.list.less([0,1,false,'a',false],false) → [0,1,'a']

    • a.list([2,2,7,['a'],1,9,0,31]).less(0,['a'],2) → [7, 1, 9, 31]

  • Note: An option to pass a list of items to be removed exists by indicating you only want 2 parameters, such that a.list(2).less([0,1,2,2,3,4],[0,2]) → [1,3,4].

• find a.list.find(list, what)

  • list is the list you want to search.

  • what is the item you are looking for.

  • Examples

    • a.list([4,5]).find(9) → 0

    • a.list([4,5]).find(5) → 2

    • a.list.find([4,5],4) → 1

• each a.list.each(list, function, this)

  • list is the list you want to iterate through each of its items.

  • function is your callback which gets executed sequentially, on each item.

    • the first parameter is the current item’s value.

    • the second parameter is the current index of that value in the list.

    • the third parameter is a map function, which when called pushes its argument into a list that is returned by default by each.

    • return; or return undefined; immediately proceeds to the next item.

    • return anything else and the loop breaks, then each returns the value you returned instead.

  • this is an optional argument th