Add description of what "invariant" is about invariant

[osidenate]

👍
What does this project do? I see it referenced in a lot of high profile projects, but it's description just says "A mirror of Facebook's invariant (e.g. React, flux)."

Since the links to React and Flux's invariant are broken, I can't tell what's going on here without looking at the source. Even just a simple one paragraph description would be nice.

[gajus]

From the source code:

/**
 * Use invariant() to assert state which your program assumes to be true.
 *
 * Provide sprintf-style format (only %s is supported) and arguments
 * to provide information about what broke and what you were
 * expecting.
 *
 * The invariant message will be stripped in production, but the invariant
 * will remain to ensure logic does not differ in production.
 */

Basically,

invariant(somethingThatMustBeTrue, 'Something that I thought is true is not true.');

Will throw an Error with a message "Something that I thought is true is not true." when somethingThatMustBeTrue is not truth-y.

[gajus]

Knowing that I would still like the explanation for how is this better than a simple condition, e.g.

if (somethingThatMustBeTrue) {
    throw new Error('Something that I thought is true is not true.');
}

[zertosh]

@gajus, you can very well use if -> throw, nothing wrong with that. I think it comes down to preference.

The way you'd write an invariant call is very similar to a test's assertion function:

// in a test:
assert.ok(someCondition, 'something bad happened!');
// in user code:
invariant(someCondition, 'something bad happened!');
// using an if:
if (!someCondition) {
  throw new Error('something bad happened!');
}

Some people like that. It's also worth noting that if and throw are statements, while an invariant call is an expression. So:

// this is invalid syntax
var mustBeTrue = true ? 'true string' : throw new Error('not true!');
// while this is valid syntax
var mustBeTrue = true ? 'true string' : invariant(false, 'not true!');

Some people find it convenient to throw errors from expressions. One last thing, invariant also provides printf-like string replacement:

// using an if:
if (!someCondition) {
  throw new Error(
   '[' + moduleName + '] got "' +
   someCondition + '" but expected something truthy'
  );
}
// using invariant:
invariant(
  someCondition,
  '[%s] got "%s" but expected something truthy',
  moduleName, someCondition);