inline-loops.macro

Iteration helpers that inline to native loops for performance

Table of Contents

• inline-loops.macro
  • Table of Contents
  • Summary
  • Usage
  • Methods
  • How it works
    • Aggressive inlining
    • Bailout scenarios
  • Gotchas
    • *Object methods do not perform hasOwnProperty check
    • findIndex vs findKey
  • Development

Summary

inline-loops.macro is a babel macro that will inline calls to the iteration methods provided, replacing them with for loops (or for-in in the case of objects). While this adds more code, it is also considerably more performant than the native versions of these methods. When working in non-JIT environments this is also faster than equivalent runtime helpers, as it avoids function calls and inlines operations when possible.

This is inspired by the work done on babel-plugin-loop-optimizer, but aims to be both more targeted and more full-featured. Rather than globally replace all native calls, the use of macros allow a controlled, opt-in usage. This macro also supports decrementing array and object iteration, as well as nested usage.

You can use it for everything, only for hotpaths, as a replacement for lodash with legacy support, whatever you see fit for your project. The support should be the same as the support for babel-plugin-macros.

Usage

import { map, reduce, someObject } from 'inline-loops.macro';

function contrivedExample(array) {
    const doubled = map(array, (value) => value * 2);
    const doubleObject = reduce(doubled, (object, value) => ({
      ...object,
      [value]: value
    }, {});

    if (someObject(doubleObject, (value) => value > 100)) {
        console.log('I am large!');
    }
}

Methods

• every (MDN documentation)
  • everyRight => same as every, but iterating in reverse
  • everyObject => same as every but iterating over objects intead of arrays
• filter (MDN documentation)
  • filterRight => same as filter, but iterating in reverse
  • filterObject => same as filter but iterating over objects intead of arrays
• find (MDN documentation)
  • findRight => same as find, but iterating in reverse
  • findObject => same as find but iterating over objects intead of arrays
• findIndex (MDN documentation)
  • findIndexRight => same as findIndex, but iterating in reverse
  • findKey => same as findIndex but iterating over objects intead of arrays
• flatMap (MDN documentation)
  • flatMapRight => same as flatMap, but iterating in reverse
  • There is no object method, as the use cases and expected results are not clearly defined, nor is the expected outcome obvious
• forEach (MDN documentation)
  • forEachRight => same as forEach, but iterating in reverse
  • forEachObject => same as forEach but iterating over objects intead of arrays
• map (MDN documentation)
  • mapRight => same as map, but iterating in reverse
  • mapObject => same as map but iterating over objects intead of arrays
• reduce (MDN documentation)
  • reduceRight => same as reduce, but iterating in reverse
  • reduceObject => same as reduce but iterating over objects intead of arrays
• some (MDN documentation)
  • someRight => same as some, but iterating in reverse
  • someObject => same as some but iterating over objects intead of arrays

How it works

Internally Babel will transform these calls to their respective loop-driven alternatives. Example

// this
const foo = map(array, fn);

// becomes this
let _result = [];

for (let _key = 0, _length = array.length, _value; _key < _length; ++_key) {
  _value = array[_key];
  _result.push(fn(_value, _key, array));
}

const foo = _result;

If you are passing uncached values as the array or the handler, it will store those values as local variables and execute the same loop based on those variables.

Aggressive inlining

One extra performance boost is that inline-loops will try to inline the callback operations when possible. For example:

// this
const doubled = map(array, value => value * 2);

// becomes this
let _result = [];

for (let _key = 0, _length = array.length, _value; _key < _length; ++_key) {
  _value = array[_key];
  _result.push(_value * 2);
}

const doubled = _result;

Notice that there is no reference to the original function, because it used the return directly. This even works with nested calls!

// this
const isAllTuples = every(array, tuple => every(tuple, value => Array.isArray(value) && value.length === 2));

// becomes this
let _result = true;

for (let _key = 0, _length = array.length, _value; _key < _length; ++_key) {
  _value = array[_key];

  let _result2 = true;

  for (let _key2 = 0, _length2 = _value.length, _value2; _key2 < _length2; ++_key2) {
    _value2 = _value[_key2];

    if (!(Array.isArray(_value2) && _value2.length === 2)) {
      _result2 = false;
      break;
    }
  }

  if (!_result2) {
    _result = false;
    break;
  }
}

const isAllTuples = _result;

Bailout scenarios

Inevitably not everything can be inlined, so there are known bailout scenarios:

• When using a cached function reference (we can only inline functions that are statically declared in the macro scope)
• When there are multiple return statements (as there is no scope to return from, the conversion of the logic would be highly complex)
• When the return statement is not top-level (same reason as with multiple returns)

That means if you are cranking every last ounce of performance out of this macro, you want to get cozy with ternaries.

import { map } from 'inline-loops.macro';

// this will bail out to storing the function and calling it in the loop
const deopted = map(array, value => {
  if (value % 2 === 0) {
    return 'even';
  }

  return 'odd';
});

// this will inline the operation and avoid function calls
const inlined = map(array, value => (value % 2 === 0 ? 'even' : 'odd'));

Gotchas

Some aspects of implementing this macro that you should be aware of:

Conditionals do not delay execution

If you do something like this with standard JS:

return isFoo ? array.map(v => v * 2) : array;

The array is only mapped over if isFoo is true. However, because we are inlining these calls into for loops in the scope they operate in, this conditional calling does not apply with this macro.

// this
return isFoo ? map(array, v => v * 2) : array;

// turns into this
let _result = [];

for (let _key = 0, _length = array.length, _value; _key < _length; ++_key) {
  _value = array[_key];
  _result[_key] = _value * 2;
}

return isFoo ? _result : array;

Notice the mapping occurs whether the condition is met or not. If you want to ensure this conditionality is maintained, you should use an if block instead:

// this
if (isFoo) {
  return map(array, v => v * 2);
}

return array;

// turns into this
if (isFoo) {
  let _result = [];

  for (let _key = 0, _length = array.length, _value; _key < _length; ++_key) {
    _value = array[_key];
    _result[_key] = _value * 2;
  }

  return _result;
}

return array;

This will ensure the potentially expensive computation only occurs when necessary.

*Object methods do not perform hasOwnProperty check

The object methods will do operations in for-in loop, but will not guard via a hasOwnProperty check. For example:

// this
const doubled = mapObject(object, value => value * 2);

// becomes this
let _result = {};

let _value;

for (let _key in object) {
  _value = object[_key];
  _result[key] = _value * 2;
}

const doubled = _result;

This works in a vast majority of cases, as the need for hasOwnProperty checks are often an edge case; it only matters when using objects created via a custom constructor, iterating over static properties on functions, or other non-standard operations. hasOwnProperty is a slowdown, but can be especially expensive in legacy browsers or non-JIT environments.

If you need to incorporate this, you can do it one of two ways:

Add filtering (iterates twice, but arguably cleaner semantics)

const raw = mapObject(object, (value, key) => (object.hasOwnProperty(key) ? value * 2 : null));
const doubled = filterObject(raw, value => value !== null);

Use reduce instead (iterates only once, but a little harder to grok)

const doubled = reduceObject(object, (_doubled, value, key) => {
  if (object.hasOwnProperty(key)) {
    _doubled[key] = value * 2;
  }

  return _doubled;
});

findIndex vs findKey

Most of the operations follow the same naming conventions:

• {method} (incrementing array)
• {method}Right (decrementing array)
• {method}Object (object)

The exception to this is findIndex / findIndexRight (which are specific to arrays) and findKey (which is specific to objects). The rationale should be obvious (arrays only have indices, objects only have keys), but because it is the only exception to the rule I wanted to call it out.

Development

Standard stuff, clone the repo and npm install dependencies. The npm scripts available:

• build => runs babel to transform the macro for legacy NodeJS support
• copy:types => copies index.d.ts to build
• dist => runs build and copy:types
• lint => runs ESLint against all files in the src folder
• lint:fix => runs lint, fixing any errors if possible
• prepublishOnly => run lint, test, test:coverage, and dist
• release => release new version (expects globally-installed release-it)
• release:beta => release new beta version (expects globally-installed release-it)
• test => run jest tests
• test:watch => run test, but with persistent watcher