mol-proto

proto

Prototypes aware object manipulation library for node and modern browsers

Why not use underscore or lo-dash

1. They do NOT use properties that are non-enumerable when they extend/clone/etc.
2. They DO use enumerable properties from prototypes when they extend/clone/etc.
3. When they clone, they create instances of Object rather than of the same class as cloned object.
4. They implement many methods that are already implemented natively.
5. They don't implement methods for inheritance and extention of prototypes.
6. They create confusion when you read code as you can't clearly differentiate between arrays and objects (maps), e.g. when each function is used.

Install

npm install mol-proto --save

To use and develop:

git clone [e-mail]:MailOnline/proto.git
cd proto
npm link
cd ../<your project>
npm link mol-proto

Use

Node/browserify:

var _ = require('mol-proto');

Browser: All functions are exported as properties of a global _ object.

Functions

• Prototype functions

  • extendProto
  • createSubclass
  • makeSubclass

• Object functions

  • extend
  • clone
  • deepExtend
  • allKeys
  • keyOf
  • allKeysOf
  • eachKey
  • mapKeys

• Array functions

  • appendArray
  • prependArray
  • toArray

• String functions

  • firstUpperCase
  • firstLowerCase

Prototype functions

extendProto (Constructor, properties)

Adds non-enumerable, non-configurable and non-writable properties to the prototype of constructor function

function MyClass() {}
_.extendProto(MyClass, {
    method1: function() {},
    method2: function() {}
});

To extend class via object:

_.extendProto(obj.constructor, { /* ... */ } );

createSubclass (Constructor [, name [, applyConstructor]])

Makes a subclass of class Constructor. The returned function will have specified name if supplied. The constructor of superclass will be called in subclass constructor by default unless applyConstructor === false (not just falsy).

makeSubclass (thisClass, Superclass)

Sets up prototype chain to change thisClass (a constructor function) so that it becomes a subclass of Superclass.

Object functions

extend (self, obj [, onlyEnumerable])

Extends object self with an object obj copying all own properties (not those inherited via prototype chain), including non-enumerable properties (unless onlyEnumerable is truthy)

clone (self)

Makes a shallow clone of object self creating an instance of the same class.

Although it can be used to clone an Array and the returned object will look and behave like a real array (it will be an instance of Array), depending on JavaScript implementation it may store items inefficiently (not sequentially) and it may affect performance.

If you need to clone array, use

var clonedArray = [].concat(arr);

deepExtend (self, obj [, onlyEnumerable)

Extends object on all levels without overwriting existing properties that are objects:

var obj = {
    inner: {
        a: 1
    }
};

_.deepExtend(obj, {
    inner: {
        b: 2
    }
});

assert.deepEqual(obj, {
    inner: {
        a: 1,
        b: 2
    }
}); // assert passes

allKeys (self)

Returns array of property names of an object self. This function is defined in this way:

_.allKeys = Object.getOwnPropertyNames.bind(Object)

keyOf (self, searchElement [, onlyEnumerable])

An analogue of indexOf method of Array prototype.

Returns the key of searchElement in the object self.

As object keys are unsorted, if there are several keys that hold searchElement any of them can be returned. Use allKeysOf to return all keys.

All own properties are searched (not those inherited via prototype chain), including non-enumerable properties (unless onlyEnumerable is truthy).

allKeysOf (self, searchElement [, onlyEnumerable])

Works similarly to the previous function, but returns the array of keys holding searchElement as their value.

eachKey (self, callback [, thisArg [, onlyEnumerable]])

An analogue of forEach method of Array prototype.

Iterates all own properties of self (or only enumerable own properties if onlyEnumerable is truthy) calling callback for each key.

Callback is passed value, key and self, its return value is not used.

If thisArg is set it will be the context (the value of this) in callback.

This method should not be used with arrays, it will include length property in iteration.

To iterate array-like objects (e.g., arguments pseudo-array) use:

Array.prototype.forEach.call(arguments, callback, thisArg);

mapKeys (self, callback [, thisArg [, onlyEnumerable]])

An analogue of map method of Array prototype.

Returns the map that is the result of the application of callback to values in all own properties of self (or only enumerable own properties if onlyEnumerable is truthy).

Callback is passed value, key and self and should return value that will be included in the map. Property descriptors of the returned map will have the same values of properties enumerable, configurable and writable as the original map.

If thisArg is set it will be the context (the value of this) in callback.

This method should not be used with arrays, it will include length property in iteration.

To map array-like objects use:

var result = Array.prototype.map.call(arguments, callback, thisArg);

Array functions

Functions that Array implements natively are not included.

appendArray (self, arrayToAppend)

Appends arrayToAppend to the end of array self in place (can be an instance of Array or array-like object).

Changes the value of self (it uses Array.prototype.splice) and returns the new value of self.

TODO: test

prependArray (self, arrayToPrepend)

Appends arrayToPrepend to the beginning of array self in place (can be an instance of Array or array-like object).

Changes the value of self (it uses Array.prototype.splice) and returns the new value of self.

TODO: test

toArray (arrayLike)

Returns new array created from array like object (e.g., arguments pseudo-array).

String functions

firstUpperCase (str)

Returns string with the first character changed to upper case.

firstLowerCase (str)

Returns string with the first character changed to lower case.