oolong

Oolong.js API Documentation =========================== ### [Oolong](#Oolong) - [.assign](#Oolong.assign)(target, source...) - [.assignOwn](#Oolong.assignOwn)(target, source...) - [.clone](#Oolong.clone)(object) - [.cloneDeep](#Oolong.cloneDeep)(object) - [.create](#Oolong.create)(prototype, [source...]) - [.defaults](#Oolong.defaults)(target, source...) - [.defineGetter](#Oolong.defineGetter)(object, property, fn) - [.defineSetter](#Oolong.defineSetter)(object, property, fn) - [.each](#Oolong.each)(object, callback, [thisArg]) - [.eachOwn](#Oolong.eachOwn)(object, callback, [thisArg]) - [.filter](#Oolong.filter)(object, callback, [thisArg]) - [.forEach](#Oolong.forEach)(object, callback, [thisArg]) - [.forEachOwn](#Oolong.forEachOwn)(object, callback, [thisArg]) - [.has](#Oolong.has)(object, key) - [.hasOwn](#Oolong.hasOwn)(object, key) - [.isEmpty](#Oolong.isEmpty)(object) - [.isIn](#Oolong.isIn)(object, key) - [.isInOwn](#Oolong.isInOwn)(object, key) - [.isObject](#Oolong.isObject)(object) - [.isOwnEmpty](#Oolong.isOwnEmpty)(object) - [.isPlainObject](#Oolong.isPlainObject)(object) - [.keys](#Oolong.keys)(object) - [.lookupGetter](#Oolong.lookupGetter)(object, property) - [.lookupSetter](#Oolong.lookupSetter)(object, property) - [.map](#Oolong.map)(object, callback, [thisArg]) - [.mapKeys](#Oolong.mapKeys)(object, callback, [thisArg]) - [.merge](#Oolong.merge)(target, source...) - [.object](#Oolong.object)(keys, callback, [thisArg]) - [.ownKeys](#Oolong.ownKeys)(object) - [.pick](#Oolong.pick)(object, keys...) - [.pickDeep](#Oolong.pickDeep)(object, keys...) - [.pluck](#Oolong.pluck)(object, key) - [.property](#Oolong.property)(key) - [.reject](#Oolong.reject)(object, callback, [thisArg]) - [.setPrototypeOf](#Oolong.setPrototypeOf)(object, prototype) - [.values](#Oolong.values)(object) - [.wrap](#Oolong.wrap)(value, key) <a name="Oolong" /> Oolong ------ <a name="Oolong.assign" /> ### Oolong.assign(target, source...) Assigns all enumerable properties on `source` objects to `target`. Similar to `Object.assign`, but takes inherited properties into account. Does not modify anything in the source objects. Returns `target`. Think of it as _extending_ the first object step by step with others. **Examples**: ```javascript Oolong.assign({name: "John"}, {age: 32}, {shirt: "blue"}) // => {name: "John", age: 32, shirt: "blue"} ``` <a name="Oolong.assignOwn" /> ### Oolong.assignOwn(target, source...) Assigns all own enumerable properties on `source` objects to `target`. Like `Object.assign`. Does not modify anything in the source objects. Returns `target`. Think of it as _extending_ the first object step by step with others. **Examples**: ```javascript Oolong.assignOwn({name: "John"}, {age: 32}, Object.create({shirt: "blue"})) // => {name: "John", age: 32} ``` <a name="Oolong.clone" /> ### Oolong.clone(object) Creates a shallow clone of the given object, taking all enumerable properties into account. Shallow means if you've got nested objects, those will be shared. **Examples**: ```javascript Oolong.clone({name: "John", age: 32}) // => {name: "John", age: 32} ``` <a name="Oolong.cloneDeep" /> ### Oolong.cloneDeep(object) Creates a deep clone of the given object, taking all enumerable properties into account. **Examples**: ```javascript Oolong.cloneDeep({name: "John", attributes: {age: 42}}) // => {name: "John", attributes: {age: 42}} ``` <a name="Oolong.create" /> ### Oolong.create(prototype, [source...]) Creates and returns an object inheriting from `prototype` and, optionally, assigns enumerable properties from `source` objects to the new object. Uses `Object.create` and [`Oolong.assign`](#Oolong.assign) internally. Does not modify the given `prototype` nor source objects. **Examples**: ```javascript var PERSON = {name: "Unknown", age: 0} Oolong.create(PERSON, {name: "John"}, {shirt: "blue"}) // => {name: "John", age: 0, shirt: "blue"} ``` <a name="Oolong.defaults" /> ### Oolong.defaults(target, source...) Assigns all enumerable properties on `source` objects to `target` that the `target` already _doesn't_ have. Uses `key in obj` to check for existence. Does not modify anything in the source objects. Returns `target`. Note that because **inherited properties** on `target` are checked, any property that exists on `Object.prototype` (e.g. `toString`, `valueOf`) will be skipped. Usually that's not a problem, but if you want to use `Oolong.defaults` for hashmaps/dictionaries with unknown keys, ensure `target` inherits from `null` instead (use `Object.create(null)`). **Examples**: ```javascript var PERSON = {name: "Unknown", age: 0, shirt: "blue"} Oolong.defaults({name: "John", age: 42}, PERSON) // => {name: "John", age: 42, shirt: "blue"} ``` <a name="Oolong.defineGetter" /> ### Oolong.defineGetter(object, property, fn) Defines a getter on an object. Similar to [`Object.prototype.__defineGetter__`][__defineGetter__], but works in a standards compliant way. Returns `object`. The property is by default made *configurable* and *enumerable*. Should the property exist before, it's enumerability will be left as is. [__defineGetter__]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/__defineGetter__ **Examples**: ```javascript var person = {birthyear: 1987} Oolong.defineGetter(person, "age", function() { return new Date().getFullYear() - this.birthyear }) person.age // => 28 as of today in 2015. ``` <a name="Oolong.defineSetter" /> ### Oolong.defineSetter(object, property, fn) Defines a setter on an object. Similar to [`Object.prototype.__defineSetter__`][__defineSetter__], but works in a standards compliant way. Returns `object`. The property is by default made *configurable* and *enumerable*. Should the property exist before, it's enumerability will be left as is. [__defineSetter__]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/__defineSetter__ **Examples**: ```javascript var person = {} Oolong.defineSetter(person, "age", function(age) { this.birthyear = new Date().getFullYear() - age }) person.age = 28 person.birthyear // => 1987 as of today in 2015. ``` <a name="Oolong.each" /> ### Oolong.each(object, callback, [thisArg]) Calls the given function for all enumerable properties. Returns the given object. The function will be called with arguments `value`, `key` and `object` and bound to `thisArg`. **Examples**: ```javascript var obj = {name: "John", age: 42} Oolong.each(obj, function(val, key) { console.log(key + "=" + val) }) ``` <a name="Oolong.eachOwn" /> ### Oolong.eachOwn(object, callback, [thisArg]) Calls the given function for all _own_ enumerable properties. Returns the given object. The function will be called with arguments `value`, `key` and `object` and bound to `thisArg`. **Examples**: ```javascript var obj = {name: "John", age: 42} Oolong.eachOwn(obj, function(val, key) { console.log(key + "=" + val) }) ``` <a name="Oolong.filter" /> ### Oolong.filter(object, callback, [thisArg]) Filters all enumerable properties and returns a new object with only those properties for which the given function returned truthy for. The function will be called with arguments `value`, `key` and `object` and bound to `thisArg`. **Examples**: ```javascript var obj = {a: 1, b: 2, c: 3, d: 4} Oolong.filter(obj, function(value, key) { return value % 2 == 0 }) // => {b: 2, d: 4} ``` <a name="Oolong.forEach" /> ### Oolong.forEach(object, callback, [thisArg]) Alias of [`each`](#Oolong.each). <a name="Oolong.forEachOwn" /> ### Oolong.forEachOwn(object, callback, [thisArg]) Alias of [`eachOwn`](#Oolong.eachOwn). <a name="Oolong.has" /> ### Oolong.has(object, key) Checks whether the given object has the given property, inherited or not. Given a set, but `undefined` property will still return `true`. **Examples**: ```javascript Oolong.has({name: "John"}) // => true Oolong.has(Object.create({name: "John"}), "name") // => true Oolong.has({}, "name") // => false ``` <a name="Oolong.hasOwn" /> ### Oolong.hasOwn(object, key) Checks whether the given object has the given property as an own property. Given a set, but `undefined` property will still return `true`. **Examples**: ```javascript Oolong.hasOwn({name: "John"}) // => true Oolong.hasOwn(Object.create({name: "John"}), "name") // => false Oolong.hasOwn({}, "name") // => false ``` <a name="Oolong.isEmpty" /> ### Oolong.isEmpty(object) Checks whether the given object has any enumerable properties, inherited or not. **Examples**: ```javascript Oolong.isEmpty({name: "John"}) // => false Oolong.isEmpty(Object.create({name: "John"})) // => false Oolong.isEmpty({}) // => true ``` <a name="Oolong.isIn" /> ### Oolong.isIn(object, key) Alias of [`has`](#Oolong.has). <a name="Oolong.isInOwn" /> ### Oolong.isInOwn(object, key) Alias of [`hasOwn`](#Oolong.hasOwn). <a name="Oolong.isObject" /> ### Oolong.isObject(object) Checks whether the given object is of type object and is not null. **Examples**: ```javascript Oolong.isObject({name: "John"}) // => true Oolong.isObject(new Date) // => true Oolong.isObject(42) // => false Oolong.isObject(null) // => false ``` <a name="Oolong.isOwnEmpty" /> ### Oolong.isOwnEmpty(object) Checks whether the given object has any _own_ enumerable properties. **Examples**: ```javascript Oolong.isOwnEmpty({name: "John"}) // => false Oolong.isOwnEmpty(Object.create({name: "John"})) // => true Oolong.isOwnEmpty({}) // => true ``` <a name="Oolong.isPlainObject" /> ### Oolong.isPlainObject(object) Checks whether the given object is one constructed by `Object` or inheriting from `null`. A non-plain object has a `constructor` property set to anything but `Object`. That's the case when you do, for example, `new MyModel`, `new Date`. `Array.prototype` is not considered a plain object just like an array isn't a plain object. JavaScript is a prototypical language and the prototype of an array should be considered an array. **Examples**: ```javascript Oolong.isPlainObject({name: "John", age: 42}) // => true Oolong.isPlainObject(Object.create(null)) // => true Oolong.isPlainObject(Math) // => true Oolong.isPlainObject([]) // => false Oolong.isPlainObject(Array.prototype) // => false Oolong.isPlainObject(new Date) // => false Oolong.isPlainObject("John") // => false ``` <a name="Oolong.keys" /> ### Oolong.keys(object) Returns all enumerable keys of an object as an array. Similar to `Object.keys`, but takes inherited properties into account. **Examples**: ```javascript Oolong.keys({name: "John", age: 32}) // => ["name", "age"] ``` <a name="Oolong.lookupGetter" /> ### Oolong.lookupGetter(object, property) Looks up and returns a getter on an object. Similar to [`Object.prototype.__lookupGetter__`][__lookupGetter__], but works in a standards compliant way. Takes inherited getters into account, just like `__lookupGetter__`. [__lookupGetter__]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/__lookupGetter__ **Examples**: ```javascript var person = {birthyear: 1987} Oolong.defineGetter(person, "age", function() { return new Date().getFullYear() - this.birthyear }) Oolong.lookupGetter(person, "age") // Returns the function above. ``` <a name="Oolong.lookupSetter" /> ### Oolong.lookupSetter(object, property) Looks up and returns a setter on an object. Similar to [`Object.prototype.__lookupSetter__`][__lookupSetter__], but works in a standards compliant way. Takes inherited setters into account, just like `__lookupSetter__`. [__lookupSetter__]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/__lookupSetter__ **Examples**: ```javascript var person = {birthyear: 1987} Oolong.defineSetter(person, "age", function(age) { this.birthyear = new Date().getFullYear() - age }) Oolong.lookupSetter(person, "age") // Returns the function above. ``` <a name="Oolong.map" /> ### Oolong.map(object, callback, [thisArg]) Maps all enumerable property values and returns a new object. The function will be called with arguments `value`, `key` and `object` and bound to `thisArg`. **Examples**: ```javascript var obj = {a: 1, b: 2, c: 3} Oolong.map(obj, function(value, key) { return value * 2 }) // => {a: 2, b: 4, c: 6} ``` <a name="Oolong.mapKeys" /> ### Oolong.mapKeys(object, callback, [thisArg]) Transforms all enumerable keys and returns a new object. The function will be called with arguments `key`, `value` and `object` and bound to `thisArg`. **Examples**: ```javascript var person = {name: "John", age: 32} Oolong.mapKeys(person, function(key) { return key.toUpperCase() }) // => {NAME: "John", AGE: 32} ``` <a name="Oolong.merge" /> ### Oolong.merge(target, source...) Assigns all enumerable properties on `source` objects to `target` recursively. Only plain objects a merged. Refer to [`Oolong.isPlainObject`](#Oolong.isPlainObject) for the definition of a plain object. Does not modify anything in the source objects. Think of it as _extending_ the first object step by step with others. **Examples**: ```javascript var person = {name: "John", attributes: {age: 42}} Oolong.merge(person, {attributes: {height: 190}}) person // => {name: "John", attributes: {age: 42, height: 190}} ``` <a name="Oolong.object" /> ### Oolong.object(keys, callback, [thisArg]) Returns a new object with keys taken from the array `keys` and values from the result of calling the given function with `key`, `index` and `keys`. It's like the reverse of indexing an array. **Examples**: ```javascript var names = ["Alice", "Bob", "Charlie"] var lengths = Oolong.object(names, function(name) { return name.length }) lengths // => {Alice: 5, Bob: 3, Charlie: 7} ``` <a name="Oolong.ownKeys" /> ### Oolong.ownKeys(object) Returns all enumerable _own_ keys of an object as an array. Same as `Object.keys`, really. **Examples**: ```javascript var person = Object.create({name: "John"}) person.age = 42 Oolong.ownKeys(person) // => ["age"] ``` <a name="Oolong.pick" /> ### Oolong.pick(object, keys...) Filters the keys of an object to only those given as `keys...`. Only keys that exist in `object` are included. **Examples**: ```javascript var person = {name: "Alice", email: "alice@example.com", age: 42} Oolong.pick(person, "name", "age") // => {name: "Alice", age: 42} ``` <a name="Oolong.pickDeep" /> ### Oolong.pickDeep(object, keys...) Filters the keys of an object to only those given as `keys...` with support for nested keys in an array (`["a", "b", "c"]`). Only keys that exist in `object` are included. If you'd like to use some other path syntax, feel free to preprocess your keys before passing them to `pickDeep`. For example, for a period-separated syntax (`a.b.c`), use a helper: ```javascript function path(s) { return s.split(".") } Oolong.pickDeep(person, "name", path("address.country")) ``` **Examples**: ```javascript var person = {name: "Alice", address: {country: "UK", street: "Downing"}} var obj = Oolong.pickDeep(person, "name", ["address", "country"]) obj // => {name: "Alice", address: {country: "UK"}} ``` <a name="Oolong.pluck" /> ### Oolong.pluck(object, key) Returns a new object with the same keys, but with values being the value's property `key`. In other words, it's the same as `Oolong.map(obj, Oolong.property(key))`. **Examples**: ```javascript var people = { a: {name: "Alice"}, b: {name: "Bob"}, c: {name: "Charlie"} } Oolong.pluck(people, "name") // => {a: "Alice", b: "Bob", c: "Charlie"} ``` <a name="Oolong.property" /> ### Oolong.property(key) Returns a function that returns the given property of an object. **Examples**: ```javascript var getName = Oolong.property("name") getName({name: "John"}) // => "John ``` <a name="Oolong.reject" /> ### Oolong.reject(object, callback, [thisArg]) Rejects all enumerable properties and returns a new object without those properties for which the given function returned truthy for. Opposite of [`filter`](#Oolong.filter). The function will be called with arguments `value`, `key` and `object` and bound to `thisArg`. **Examples**: ```javascript var obj = {a: 1, b: 2, c: 3, d: 4} Oolong.reject(obj, function(value, key) { return value % 2 == 0 }) // => {a: 1, c: 3} ``` <a name="Oolong.setPrototypeOf" /> ### Oolong.setPrototypeOf(object, prototype) Set the prototype of the given object to the given prototype. Pass `null` or another object for the prototype. Returns `object`. Uses `Object.setPrototypeOf` if it exists. Otherwise uses a polyfill. **Examples**: ```javascript var person = {name: "Unnamed", age: 42} var mike = Oolong.setPrototypeOf({name: "Mike"}, person) mike.name // => "Mike mike.age // => 42 ``` <a name="Oolong.values" /> ### Oolong.values(object) Returns all enumerable property values as an array. **Examples**: ```javascript Oolong.values({name: "John", age: 32}) // => ["John", 32] ``` <a name="Oolong.wrap" /> ### Oolong.wrap(value, key) Wraps a given value in an object under the specified key. Works also with [ECMAScript 6 Symbol](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Symbol). **Examples**: ```javascript Oolong.wrap("John", "name") // => {name: "John"} ```