#JOBJ

A collection of utilities to work with objects. Lighter than most, and does what I want Particularly useful to work with immutables, as all functions return new objects.

I was mainly tired of always re-writting the same little functions in every project.

Methods

Functions

addProperty(Object, String, any) ⇒

addProperty - adds a hidden property to an object addProperty(obj,name) adds the property addProperty(obj) returns a function f(name[,value]) bound to the object

Kind: global function
Returns: undefined

| Param | Description | | --- | --- | | Object | obj The object to add a property to | | String | name The name of the property | | any | [value] An optional value for the property |

pop(Array) ⇒

pop - removes the last element from an array

Kind: global function
Returns: Array a transformed array

| Param | Description | | --- | --- | | Array | arr the array |

splice(Array, start, deleteCount) ⇒

splice - removes/inserts one or more elements from/into an array

Kind: global function
Returns: Array a transformed array

| Param | Type | Description | | --- | --- | --- | | Array | | arr the array | | start | type | index to begin splicing at | | deleteCount | type | number of items to remove | | ...items | type | items to add |

push(Array) ⇒

push - adds elements to an array's tail

Kind: global function
Returns: Array a transformed array

| Param | Type | Description | | --- | --- | --- | | Array | | arr the array | | ...objs | type | objects to add |

sort(Array, predicate) ⇒

sort - sorts an array according to a given predicate

Kind: global function
Returns: Array a transformed array

| Param | Type | Description | | --- | --- | --- | | Array | | arr the array | | predicate | type | a function to filter with |

reverse(Array) ⇒

reverse - reverses an array sorting order

Kind: global function
Returns: Array a transformed array

| Param | Description | | --- | --- | | Array | arr the array |

shift(Array) ⇒

shift removes the first element of an array

Kind: global function
Returns: Array a transformed array

| Param | Description | | --- | --- | | Array | arr the array |

unshift(Array) ⇒

unshift - adds elements to the beginning of an array

Kind: global function
Returns: Array a transformed array

| Param | Type | Description | | --- | --- | --- | | Array | | arr the array | | ...elements | type | elements to add |

arrayToObj(Array, Function) ⇒

arrayToObj - transforms an array into an object, applying the given functor on each element. The functor has the following signature function(value,index) And should return an array of two elements: [key,value], that will be used to create the final object

Kind: global function
Returns: Object the object, as returned from the functor

| Param | Description | | --- | --- | | Array | arr the original array | | Function | fn description |

assign(any) ⇒

assign - shallow extending of an object properties The operation always returns a new object. This is comparable to Object.assign({},...objects).

Kind: global function
Returns: Object a new object

| Param | Description | | --- | --- | | any | ...objects the objects to merge |

debounce(Function, Number, any) ⇒

debounce - debounces a function to run only a certain number of times per second The debounced returned function has a delay property that can be changed to obtain dynamic delays.

Kind: global function
Returns: Function the debounced function

| Param | Description | | --- | --- | | Function | fn a function | | Number | [delay] the delay (defaults to 300ms) | | any | [thisArg] an optional context for the function |

EventEmitter(opts) ⇒

EventEmitter - Creates a new EventEmitter. This EventEmitter implementation is designed to handle one single event type. You are free to use new or just call the function. Takes an option object. The options are:

• onInit() runs when the EventEmitter instance is created
• onFirst() runs when the EventEmitter instance has its first listener
• onLast() runs when the EventEmitter instance removes its last listener

Use them to do some initialization and clean up

Kind: global function
Returns: EventEmitter an instance of EventEmitter

| Param | Description | | --- | --- | | opts | an options object |

• EventEmitter(opts) ⇒
  • .getListenerIndex(Function) ⇒
  • .addListener(Function) ⇒
  • .once(Function) ⇒
  • .removeListener(Function) ⇒
  • .removeListenerByIndex(Int) ⇒
  • .emit(any) ⇒
  • .clean() ⇒

eventEmitter.getListenerIndex(Function) ⇒

getListenerIndex - returns an index for a given listener

Kind: instance method of EventEmitter
Returns: Int the index, or -1 if not found;

| Param | Description | | --- | --- | | Function | listener the listener to find the index of |

eventEmitter.addListener(Function) ⇒

addListener - Adds a listener to the pool

Kind: instance method of EventEmitter
Returns: Int the index of the listener (useful for removeListenerByIndex)

| Param | Description | | --- | --- | | Function | listener |

eventEmitter.once(Function) ⇒

once - Adds a listener that will only fire once

Kind: instance method of EventEmitter
Returns: undefined

| Param | Description | | --- | --- | | Function | listener |

eventEmitter.removeListener(Function) ⇒

removeListener - removes a listener from the pool

Kind: instance method of EventEmitter
Returns: undefined

| Param | Description | | --- | --- | | Function | listener |

eventEmitter.removeListenerByIndex(Int) ⇒

removeListenerByIndex - Removes a listener from the pool

Kind: instance method of EventEmitter
Returns: undefined

| Param | Description | | --- | --- | | Int | index the index of the listener to remove |

eventEmitter.emit(any) ⇒

emit - Calls all the listeners with the given props

Kind: instance method of EventEmitter
Returns: undefined

| Param | Description | | --- | --- | | any | props something to pass to the listeners |

eventEmitter.clean() ⇒

clean - removes all listeners

Kind: instance method of EventEmitter
Returns: undefined

getNestedProperty(Object, Array|String) ⇒

getNestedProperty - Finds a property in an object with a provided path

Kind: global function
Returns: any The value, if found, or undefined

| Param | Description | | --- | --- | | Object | obj The object to look into | | Array|String | path The path, either as an array, or a dot separated string |

mapObj(Object, Function, Any) ⇒

mapObj - returns an array for a given object by applying a given functor The functor has the signature: function(value,key,object,index) The functor should return a value;

Kind: global function
Returns: Array the returned array, made of the values returned by the functor.

| Param | Description | | --- | --- | | Object | obj the object to operate on | | Function | fn the functor to apply | | Any | [thisArg] context for the functor |

merge(Function, Object) ⇒

merge - runs a functor on every passed objects, merging values from left to right This functor has the following signature: function(value,previousValue,key,object,currentObject) Where:

• value is the current value (you probably want to return that)
• previousValue is the value that was previously assigned
• key is the name of the current key
• object is the final object in construction
• currentObject is the object being currently operated on not returning a value (that is, returning undefined) will NOT add the value to the object.

Kind: global function
Returns: Object The final object

| Param | Description | | --- | --- | | Function | fn The functor to use | | Object | ...objects Objects to operate on |

objFilter(Object, Function|Array, Int, any) ⇒

objFilter - Filters an object's properties given a predicate. This predicate can either be:

• an array of strings: keys that are not in the array will be removed
• a function of signature function(value,key,object,index): should return true or false

Options:

• REVERSE: reverses the results. In this case, values that are NOT in the provided array will be included (or values for which the functor returns false).

Kind: global function
Returns: Object A new object

| Param | Description | | --- | --- | | Object | obj The object to filter | | Function|Array | predicate Either a function, or an array of keys | | Int | [opts] flags for the function | | any | [thisArg] A context for the function |

objForEach(Object, Function, any) ⇒

objForEach - iterates over an object's properties, applying a functor on each element. The functor has the following signature: function(value,key,object,index)

Kind: global function
Returns: undefined

| Param | Description | | --- | --- | | Object | obj The object to iterate on | | Function | fn The functor to apply | | any | [thisArg] A context for the functor |

onResize(Function) ⇒

onResize - listens to browser resize events. The function is debounced and runs only if there has been a change in value. It also automatically cleans the window event listener when the last callback function has been removed.

The listener receives an object:

{win:{width,height},doc:{width,height}}

Calling the function without arguments returns the current value. Calling it with a listener returns:

{dispose,win:{width,height},doc:{width,height}}

dispose() can be called to remove the listener.

Kind: global function
Returns: Object An object representing the current browser size

| Param | Description | | --- | --- | | Function | listener A function to run when the browser size changes |

throttle(Function, Number, Any) ⇒

throttle - throttles a function to emit only every nth second

Kind: global function
Returns: Function The throttled function

| Param | Description | | --- | --- | | Function | fn The function to throttle | | Number | [threshhold] A number of ms (defaults to 250) | | Any | [thisArg] An optional context for the function |

transform(Object, Function, Int, any) ⇒

transform - returns a new object from a given object, applying a functor on every element. The functor has the following signature: function(value,key,object,index) and is expected to return a value.

Options:

• SKIP_UNDEFINED: if set, undefined values will be stripped from the object, making the functor act as a filter of sorts.

Kind: global function
Returns: Object A new object made of the values returned from the functor

| Param | Description | | --- | --- | | Object | obj The object to operate on | | Function | fn The functor to apply | | Int | [opts] Flags | | any | [thisArg] A context for the functor |

traverse(any, Function, Int, Int) ⇒

traverse traverses an object, applying a functor to each element This method operates in a depth-first order, that is, and object's elements will be operated on before the object iself.

Functor signature: function(value,key,path){} value: the current value key: the current key path: an array representing the current path. The last element should == key

If the functor returns false (not a falsy value) at any moment, operation is stopped.

There are three binary flags (exposed on the function itself):

• REVERSE: reverses the order; the function is first applied to the parent object
• SKIP_ARRAYS: array elements won't be used
• SKIP_OBJECTS: object elements won't be used

Kind: global function
Returns: undefined

| Param | Description | | --- | --- | | any | obj The object to traverse | | Function | fn The function to apply | | Int | [opts] A mix of REVERSE, | | Int | [maxDepth] maximum recursion. Defaults to Infinity |

Additionally, it provides the following immutable replacements for mutative array functions: push,pop,splice,sort,reverse,shift, and unshift. All functions work like their native counterparts, but take an array argument first (they also return an array instead of, say, the length property for push).

Install

npm install jobj

License

MIT