Obj create perf fix (#270)

* Fix property access perf.
Fix some JSDoc comments. Run CI tests for node v7 too.
Add benchmarking test, make it run in CI only.

* Turns out Travis already declares that var by default:
https://docs.travis-ci.com/user/environment-variables/#Default-Environment-Variables

* Minor additions to the JSDoc

Author: koresar

.travis.yml

@@ -3,5 +3,6 @@ node_js:
   - "4"
   - "5"
   - "6"
+  - "7"
 script:
   - npm run check

package.json

@@ -28,6 +28,7 @@
   "devDependencies": {
     "babel-cli": "^6.10.1",
     "babel-preset-es2015": "^6.16.0",
+    "benchmark": "^2.1.1",
     "check-compose": "^3.2.0",
     "dependency-check": "^2.5.0",
     "eslint": "^3.7.0",

src/compose.js

@@ -7,12 +7,13 @@ const assign = Object.assign;
 
 /**
  * Creates new factory instance.
- * @param {object} descriptor The information about the object the factory will be creating.
+ * @param {Descriptor} descriptor The information about the object the factory will be creating.
  * @returns {Function} The new factory function.
  */
 function createFactory(descriptor) {
   return function Stamp(options, ...args) {
-    const obj = Object.create(descriptor.methods || {});
+    // Next line was optimized for most JS VMs. Please, be careful here!
+    const obj = Object.create(descriptor.methods || null);
 
     merge(obj, descriptor.deepProperties);
     assign(obj, descriptor.properties);
@@ -31,9 +32,9 @@ function createFactory(descriptor) {
 
 /**
  * Returns a new stamp given a descriptor and a compose function implementation.
- * @param {object} [descriptor={}] The information about the object the stamp will be creating.
- * @param {Function} composeFunction The "compose" function implementation.
- * @returns {Function}
+ * @param {Descriptor} [descriptor={}] The information about the object the stamp will be creating.
+ * @param {Compose} composeFunction The "compose" function implementation.
+ * @returns {Stamp}
  */
 function createStamp(descriptor, composeFunction) {
   const Stamp = createFactory(descriptor);
@@ -53,9 +54,10 @@ function createStamp(descriptor, composeFunction) {
 
 /**
  * Mutates the dstDescriptor by merging the srcComposable data into it.
- * @param {object} dstDescriptor The descriptor object to merge into.
- * @param {object} [srcComposable] The composable (either descriptor or stamp) to merge data form.
- * @returns {object} Returns the dstDescriptor argument.
+ * @param {Descriptor} dstDescriptor The descriptor object to merge into.
+ * @param {Composable} [srcComposable] The composable
+ * (either descriptor or stamp) to merge data form.
+ * @returns {Descriptor} Returns the dstDescriptor argument.
  */
 function mergeComposable(dstDescriptor, srcComposable) {
   const srcDescriptor = (srcComposable && srcComposable.compose) || srcComposable;
@@ -91,7 +93,8 @@ function mergeComposable(dstDescriptor, srcComposable) {
 /**
  * Given the list of composables (stamp descriptors and stamps) returns
  * a new stamp (composable factory function).
- * @param {...(object|Function)} [composables] The list of composables.
+ * @typedef {Function} Compose
+ * @param {...(Composable)} [composables] The list of composables.
  * @returns {Stamp} A new stamp (aka composable factory function)
  */
 export default function compose(...composables) {
@@ -125,3 +128,9 @@ export default function compose(...composables) {
  * @returns {*} Instantiated object
  * @property {Descriptor} compose - The Stamp descriptor and composition function
  */
+
+/**
+ * A composable object - stamp or descriptor
+ * @typedef {Stamp|Descriptor} Composable
+ */
+

src/isStamp.js

@@ -1,5 +1,10 @@
 import isFunction from './isFunction';
 
+/**
+ * Returns true if argument is a stamp.
+ * @param {*} obj
+ * @returns {Boolean}
+ */
 export default function isStamp(obj) {
   return isFunction(obj) && isFunction(obj.compose);
 }

src/stampit.js

@@ -96,6 +96,7 @@ const baseStampit = compose(
 
 /**
  * Infected compose
+ * @param {...(Composable)} [args] The list of composables.
  * @return {Stamp}
  */
 function stampit(...args) {

src/standardise-descriptor.js

@@ -4,6 +4,28 @@ import merge from './merge';
 
 const assign = Object.assign;
 
+/**
+ * Converts stampit extended descriptor to a standard one.
+ * @param [methods]
+ * @param [properties]
+ * @param [props]
+ * @param [refs]
+ * @param [initializers]
+ * @param [init]
+ * @param [deepProperties]
+ * @param [deepProps]
+ * @param [propertyDescriptors]
+ * @param [staticProperties]
+ * @param [statics]
+ * @param [staticDeepProperties]
+ * @param [deepStatics]
+ * @param [staticPropertyDescriptors]
+ * @param [configuration]
+ * @param [conf]
+ * @param [deepConfiguration]
+ * @param [deepConf]
+ * @returns {Descriptor}
+ */
 export default function ({
   methods,
 

test/benchmark/property-access.js

@@ -0,0 +1,77 @@
+import test from 'tape';
+import _ from 'lodash';
+
+const Benchmark = require('benchmark');
+const stampit = require('../..'); // Need to test the distributable
+
+
+test('benchmarking property access', (t) => {
+  const Position = stampit({
+    init() {
+      this.x = 10;
+      this.y = 10;
+    }
+  });
+
+  const Velocity = stampit({
+    init() {
+      this.vx = 10;
+      this.vy = 10;
+    }
+  });
+
+  const Entity = stampit({
+    deepProps: {
+      components: {}
+    },
+    init() {
+      this.components.position = Position();
+      this.components.velocity = Velocity();
+    }
+  });
+
+  const COUNT = 5000;
+  const stampitEntities = _.range(COUNT).map(() => Entity());
+  const normalEntities = _.range(COUNT).map(() => ({
+    components: {
+      position: {
+        x: 10,
+        y: 10,
+      },
+      velocity: {
+        vy: 10,
+        vx: 10,
+      },
+    },
+  }));
+
+  function runArray(arr) {
+    const DELTA = 16;
+    for (let i = 0; i < COUNT; i += 1) {
+      const entity = arr[i].components;
+
+      entity.position.x += (DELTA / 1000) * entity.velocity.vx;
+      entity.position.y += (DELTA / 1000) * entity.velocity.vy;
+    }
+  }
+
+  const suite = new Benchmark.Suite();
+  const results = [];
+  suite
+    .add('Stampit', () => {
+      runArray(stampitEntities);
+    })
+    .add('Plain object', () => {
+      runArray(normalEntities);
+    })
+    .on('cycle', (event) => {
+      results.push(String(event.target));
+    })
+    .on('complete', function () {
+      t.ok(this[0].hz / this[1].hz >= 0.5,
+        'object instances property access must be as fast as plain object.');
+      t.comment(results.join('. '));
+      t.end();
+    })
+    .run();
+});

test/index.js

@@ -1 +1,4 @@
-require('require-all')(__dirname);
+require('require-all')({
+  dirname: __dirname,
+  excludeDirs: process.env.CI ? /^\./ : /^\.|benchmark/
+});