lazy-ass

What is lazy-ass?

The lazy-ass npm package is a utility for making assertions with lazy evaluation. It allows developers to write assertions that are only evaluated if the assertion condition is false. This can be useful for performance reasons, as the assertion message, which might include string concatenation or other computations, is only calculated if the assertion fails.

What are lazy-ass's main functionalities?

Lazy assertions

This feature allows you to make assertions that are only evaluated if the condition is false. In the code sample, `lazyAss` checks if 'foo' is a string, and if it's not, it will throw an error with the message 'expected a string'.

var lazyAss = require('lazy-ass');
var is = require('check-more-types');
lazyAss(is.string('foo'), 'expected a string');

Lazy assertions with callback

This feature allows you to provide a callback function for the assertion message. The callback is only called if the assertion fails, which can save performance for expensive computations that are only needed for the error message.

var lazyAss = require('lazy-ass');
var is = require('check-more-types');
function expensiveComputation() {
  // some expensive computation here
  return 'computed value';
}
lazyAss(is.number(expensiveComputation), function () {
  return 'expected a number, got ' + expensiveComputation();
});

Other packages similar to lazy-ass

chai

Chai is a BDD / TDD assertion library for node and the browser that can be delightfully paired with any javascript testing framework. It offers a richer and more comprehensive set of assertions compared to lazy-ass, including property assertions, deep equality, and chainable language constructs.

assert

Assert is a simple assertion library that comes built-in with Node.js. It provides a simple set of assertion tests and is less feature-rich compared to lazy-ass. It does not support lazy evaluation of error messages.

expect.js

Expect.js is a minimalistic BDD assertion toolkit for Node.js and the browser. It provides a similar set of assertions to lazy-ass but does not support lazy evaluation. It has a fluent API and supports assertions like 'to.be', 'to.have', and 'to.contain'.

README

lazy-ass

Lazy assertions without performance penalty

Demo

Note: only tested against Node 4+

Example

Regular assertions evaluate all arguments and concatenate message EVERY time, even if the condition is true.

console.assert(typeof foo === 'object',
  'expected ' + JSON.stringify(foo, null, 2) + ' to be an object');

Lazy assertion function evaluates its arguments and forms a message ONLY IF the condition is false

const {lazyAss} = require('lazy-ass')
lazyAss(typeof foo === 'object', 'expected', foo, 'to be an object');
// shorter version
const {lazyAss: la} = require('lazy-ass')
la(typeof foo === 'object', 'expected', foo, 'to be an object');

Concatenates strings, stringifies objects, calls functions - only if condition is false.

function environment() {
  // returns string
}
var user = {} // an object
lazyAsync(condition, 'something went wrong for', user, 'in', environment);
// throws an error with message equivalent of
// 'something went wrong for ' + JSON.stringify(user) + ' in ' + environment()

Why?

• Passing an object reference to a function is about 2000-3000 times faster than serializing an object and passing it as a string.
• Concatenating 2 strings before passing to a function is about 30% slower than passing 2 separate strings.

Install

Node: npm install lazy-ass --save then var la = require('lazy-ass');. You can attach the methods to the global object using require('lazy-ass').globalRegister();.

Browser: bower install lazy-ass --save, include index.js, attaches functions lazyAss and la to window object.

Notes

You can pass as many arguments to lazyAss after the condition. The condition will be evaluated every time (this is required for any assertion). The rest of arguments will be concatenated according to rules

• string will be left unchanged.
• function will be called and its output will be concatenated.
• any array or object will be JSON stringified.

There will be single space between the individual parts.

Lazy async assertions

Sometimes you do not want to throw an error synchronously, breaking the entire execution stack. Instead you can throw an error asynchronously using lazyAssync, which internally implements logic like this:

if (!condition) {
  setTimeout(function () {
    throw new Error('Conditions is false!');
  }, 0);
}

This allows the execution to continue, while your global error handler (like my favorite Sentry) can still forward the error with all specified information to your server.

lazyAss.async(false, 'foo');
console.log('after assync');
// output
after assync
Uncaught Error: foo

In this case, there is no meaningful error stack, so use good message arguments - there is no performance penalty!

Rethrowing errors

If the condition itself is an instance of Error, it is simply rethrown (synchronously or asynchronously).

lazyAss(new Error('foo'));
// Uncaught Error: foo

Useful to make sure errors in the promise chains are not silently ignored.

For example, a rejected promise below this will be ignored.

var p = new Promise(function (resolve, reject) {
  reject(new Error('foo'));
});
p.then(...);

We can catch it and rethrow it synchronously, but it will be ignored too (same way, only one step further)

var p = new Promise(function (resolve, reject) {
  reject(new Error('foo'));
});
p.then(..., lazyAss);

But we can actually trigger global error if we rethrow the error asynchronously

var p = new Promise(function (resolve, reject) {
  reject(new Error('foo'));
});
p.then(..., lazyAssync);
// Uncaught Error: foo

Predicate function as a condition

Typically, JavaScript evaluates the condition expression first, then calls lazyAss. This means the function itself sees only the true / false result, and not the expression itself. This makes makes the error messages cryptic

lazyAss(2 + 2 === 5);
// Error

We usually get around this by giving at least one additional message argument to explain the condition tested

lazyAss(2 + 2 === 5, 'addition')
// Error: addition

lazyAss has a better solution: if you give a function that evaluates the condition expression, if the function returns false, the error message will include the source of the function, making the extra arguments unnecessary

lazyAss(function () { return 2 + 2 === 5; });
// Error: function () { return 2 + 2 === 5; }

The condition function has access to any variables in the scope, making it extremely powerful

var foo = 2, bar = 2;
lazyAss(function () { return foo + bar === 5; });
// Error: function () { return foo + bar === 5; }

In practical terms, I recommend using separate predicates function and passing relevant values to the lazyAss function. Remember, there is no performance penalty!

var foo = 2, bar = 2;
function isValidPair() {
  return foo + bar === 5;
}
lazyAss(isValidPair, 'foo', foo, 'bar', bar);
// Error: function isValidPair() {
//   return foo + bar === 5;
// } foo 2 bar 2

Testing

This library is fully tested under Node and inside browser environment (CasperJs). I described how one can test asynchronous assertion throwing in your own projects using Jasmine in a blog post.

TypeScript

If you use this function from a TypeScript project, we provide ambient type definition file. Because this is CommonJS library, use it like this

import la = require('lazy-ass')
// la should have type signature

Small print

Author: Gleb Bahmutov © 2014

• @bahmutov
• glebbahmutov.com
• blog
• videos
• presentations
• cypress.tips

License: MIT - do anything with the code, but don't blame me if it does not work.

Spread the word: tweet, star on github, etc.

Support: if you find any problems with this module, email / tweet / open issue on Github

MIT License

Copyright (c) 2014 Gleb Bahmutov

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.