soak

Simple functions for extending JavaScript objects

npm install soak
24 downloads in the last day
106 downloads in the last week
660 downloads in the last month

Soak.js

Provides simple methods for working with inheritance and objects. This library is heavily influenced by the simplistic prototypal inheritance provided in both CoffeeScript and Backbone and simply exists so that it can be included in other libraries.

inherit(Parent, instance, object)

Creates a new constructor function that inherits from a parent constructor. Instance and static methods can also be provided as additional arguments, if the methods argument has a property called constructor this will be used as the constructor function.

Arguments

  • parent: A constructor Function to inherit from.
  • instance: An Object literal of instance methods that are added to the constructors prototype (optional).
  • object: An Object literal of static/class methods to add to the constructor itself (optional).

Examples

// Original function to inherit from.
function MyObject() {};

var SubClass = inherit(MyObject, {
  instanceMethod: function () {}
}, {
  staticProp: 'some-string',
  staticMethod: function () {}
});

var instance = new SubClass();
instance instanceof MyObject   //=> true
typeof instance.instanceMethod //=> "function"
typeof SubClass.staticMethod   //=> "function"

Calling parent methods is the same as pure prototypal inheritance, just call the parent method using .call() or .apply() passing in this as the first argument to set the appropriate context.

// Original function to inherit from.
function MyObject() {};
MyObject.prototype.say = function () { return 'Hello'; }

var SubClass = inherit(MyObject, {
  constructor: function SubClass() {
   // Call the parent constructor.
    MyObject.apply(this, arguments);

    // Set up other properties.
  },
  say: function () {
    // Call the parent method providing `this` to set the context.
    return MyObject.prototype.say.apply(this, arguments) + ' World';
  }
});

(new SubClass()).say(); //=> 'Hello World'

mixin(target [ , arguments... ])

Extends an object with the properties on successive arguments. Returns the first argument. Properties will be copied from right to left with the right overriding the left.

Arguments

  • target: The object that is to be extended.
  • arguments*: Properties from all successive arguments will be copied to the target.

Examples

mixin({type: 'person'}, {name: 'bill', age: 20}, {age: 21});
//=> {type: 'person', name: 'bill', age: 21}

create(parent)

Creates a new object instance and sets it's internal prototype to the parent argument provided. This is based on Crockford's Object.create() but will use the native Object.create() if present. Unlike Object.create() this function will always return a new object even if a non object is provided as an argument.

Arguments

  • parent: An object to use for the new objects internal prototype.

Examples

var appleObject = {color: 'green'}
var appleInstance = create(appleObject);

appleInstance.hasOwnProperty('color'); //=> false
appleInstance.color === appleObject.color; //=> true

Use in Non Browser Environments

Usage with Node:

var inherit  = require('soak').inherit;
var mixin    = require('soak').mixin;
var MyObject = require('./lib/my-object');

module.exports = inherit(MyObject, {
  instanceMethod: function () {}
}, {
  staticProp: 'some-string',
  staticMethod: function () {}
});

Usage with AMD compatible script loader:

define(['soak', './lib/my-object'], function (soak, MyObject) {
  return soak.inherit(MyObject, {
    instanceMethod: function () {}
  }, {
    staticProp: 'some-string',
    staticMethod: function () {}
  });
});

Development

Tests require Node and Vows to run. To install Vows using npm run:

$ npm install vows

Then to run the tests simply enter:

$ vows soak-test.js

License

Released under the MIT license

npm loves you