This module adds different methods to the generic javascript Object
.
It does not extend the javascript Object
itself, but defines a subClass.
If you use NPM, you can install the module via npm install xassist-object
. Otherwise, you can download the latest minified file. Be aware any dependencies are not installed by default; you should consider downloading them yourself.
If you want, you can install the complete library from github xassist, this includes all dependencies you may need.
The module uses UMD and supports AMD, CommonJS and vanilla environments. Using vanilla: the xa
global is exported:
<script>
xa.object()
</script>
The base function object() creates a new Class instance which gives access to some helper Object-functions
object(/*baseObject::object*/)
note that the new- keyword should not be used to create the class-instance.
object()
takes 1 parameters:
- baseObject [
Object
]:an Object on which we will execute the underlying methods
object()
returns a new class instance of the Class XaObject
object(a).constructor.name===XaObject
XaObject
returns 8 method:
clone()
: very basic cloner for simple objectsonChange
: adds a listener to the current object for changes in valuesassign()
: a polyfill for Object.assignmergeUnique()
: changes keys for this.object with given values, kinda similar to assigntoArray()
: returns all values for all keys in this.objecttoMapArray()
: returns all key,value-pairs in this.objectforEach()
: similar to forEach for Arrays, but iterates over the keys of an objectmap()
: similar to map for Arrays, but iterates over the keys of an object
XaObject
has 2 own attributes:
object
[Object
]:the current baseObject, provided via the simple factory-function object()currentValues
[Object
]:an intermediate object with the current values of the base object, used for events
object({a:157})
object({hello:"world", ok:true})
sets a listener that will be executed if a value for a given key gets changed
object(baseObject).onChange(keyName, callBack::function [thisArg])
object().onChange()
returns nothing.
object().onChange()
takes 3 parameters:
- keyName [
String
]:is an existing key for which the listener should gets executed, if the key does not exists, an Error is thrown - callBack [
Function
]:a listenerfunction which takes 4 parameter (newValue,oldValue,keyName,object) - thisArg [any datatype,defaults to:
XaObject.object
]:the execution-context of the listener
Suppose following initialization:
var b={yes:true}, res=false;
fn=function(value,oldValue,key,Object){ res=(Array.prototype.slice.call(arguments))};
var bObj=object(b);
bObj.onChange("yes",fn)
b.yes=true //nothing get's changed so the listener is not fired
b.yes="finally" //onChange is fired
This will result in:
res===["finally",true,"yes",b]
clone() is a very basic cloner of objects it uses JSON.parse(JSON.stringify(baseObject)) for cloning. Even with the different limitations JSON parse/stringify entails, the cloner works fairly well and reasonable fast.
object(baseObject).clone()
object().clone()
requires no parameters.
clone() returns a clone of the current baseObject.
The method object().assign()
works the same as the function [Object.assign()
](https
object(obj).assign(/*list of source objects*/)
This method copiesall own property-values of all objects inside the arguments-list
to the baseObject.
object().assign()
returns nothing.
object().assign()
takes 1 parameters:
- obj_1,obj_2,?,obj_n [
one or more source objects
]:All enumerable properties of these source-objects will be copied to the baseObject
object(obj).assign(c,null,{e:4})===Object.assign(obj,c,null,{e:4})
object().mergeUnique()
does the same as assign it copies all own property values to a target object (ie this.object, the baseObject of object()
), with this restriction. it only copies the values for properties allready existant in the base (target object).
object(obj).mergeUnique(sourceObj)
MergeUnique takes into account the type of the propertyvalue. if the baseobject has Strings
,Boolean
or Numbers
as propertyvalue, the corresponding value in the sourceobject (passed on as argument to mergeUnique
) will be transformed to this type.
object().mergeUnique()
takes 1 parameters:
- sourceObject [
Object
]:another object from which the values of the properies existent in the targetObject will be copied.
the method returns the base object (ie this.object
). the object that is changed.
Suppose following initialization:
var testObject={
number1:1,
number2:2,
number3:3,
number4:4,
number5:5,
number6:6,
txt1:"1",
txt2:"2",
txt3:"3",
txt4:"4",
bool1:true,
bool2:true,
bool3:true,
bool4:false,
bool5:true,
array1:[1,2],
array2:[true]
},
sourceObj={
number1:1.57,
number2:"3",
number3:"r",
number4:false,
number5:true,
number7:-157,
txt1:"ok",
txt2:4,
txt3:true,
bool1:false,
bool2:0,
bool3:"",
bool4:"false",
array1:[1,3]
}
object(testObject).mergeUnique(sourceObj);
This will result in:
console.log(testObject)
/*{
number1:1.57,
number2:3,
number3:NaN,
number4:0,
number5:1,
number6:6,
txt1:"ok",
txt2:"4",
txt3:"true",
txt4:"4",
bool1:false,
bool2:false,
bool3:false,
bool4:true,
bool5:true,
array1:[1,3],
array2:[true]
};*/
toArray
returns an array of all values for the own properties of the object.
object(obj).toArray()
object().toArray()
requires no parameters.
toArray()
returns an array with all values for each own property of the baseobject.
Suppose following initialization:
var testObject={key1:157,key2:"txt",key3:false}
var result=object(testObject).toArray();
This will result in:
console.log(result)
// [157,"txt",false]
toMapArray
returns an array with [key,value]
arrays as its elements.
object(obj).toMapArray()
object().toMapArray()
requires no parameters.
the result of toMapArray()
is an Array with all key,value pairs.
Suppose following initialization:
var testObject={key1:157,key2:"txt",key3:false}
var result=object(testObject).toMapArray();
This will result in:
console.log(result)
// [[key1,157],[key2,"txt"],[key3,false]]
forEach
is similar to the native Array.prototype.forEach
, it executes a function for each own property of the function.
object(obj).forEach(fn::function [,thisArg])
object().forEach()
takes 2 parameters:
- fn [
Function
]:he function that should be executed on each property of the object. this function accepts 3 parameters (value of the current property, the name of the property and the object itself) - thisArg [any datatype,defaults to:
XaObject.object
]:the execution-context of the function
forEach returns nothing, it executes a function for each property. If you think it should return anything, look at map()
Suppose following initialization:
var count=0,
testObject={key1:true,key2:false:key3:true,key4:false},
fn=function(value,keyName,obj){count+= (value&&keyName!="key3")}
object(testObject).forEach(fn);
This will result in:
count===1
map()
is comparable to the native map on arrays, it returns a new object constructed from the mapped key, value pairs of the baseObject.
object(obj).forEach(fn::function [,thisArg])
object().map()
takes 2 parameters:
- fn [
Function
]:he function that should be executed on each property of the object. this function accepts 3 parameters (value of the current property, the name of the property and the object itself) - thisArg [any datatype,defaults to:
XaObject.object
]:the execution-context of the function
map()
returns a new object, it executes a function for each property and those return values are the values for the corresponding properties.
Suppose following initialization:
var testObject={key1:157,key2:"text":key3:true,key4:false},
fn=function(value,keyName,obj){return (typeof value!=='number' && keyName!="key3")}
var result=object(testObject).map(fn);
This will result in:
console.log(result)
/*{
key1:false,
key2:true,
key3:false,
key4:true
}*/
- @xassist/xassist-eventdispatcher: general eventdispatcher class
- csv2readme: read csv file with fixed format and parse a readme markdown file
- rimraf: A deep deletion module for node (like
rm -rf
) - rollup: Next-generation ES6 module bundler
- tape: tap-producing test harness for node and browsers
This module is licensed under the terms of GPL-3.0.