@joepie91/unreachable

This is a simple utility for throwing an error when a certain code path is reached, asking the user to file a bug. This is useful for code which should never be reached, eg. the else condition in a supposedly-exhaustive else if chain, or the default case in a switch.

The initialization syntax is very similar to that of debug; you call the exported function with the name of your module, and that then produces a customized unreachable function for you, that mentions the module name in its output.

The exact error message may change over time, where and as needed to make it easier for users to understand. For the purposes of semver, the API guarantee is that the error message will:

1. mention the module name you specified as the origin, and
2. request from the user to file a bug.

License, donations, and other boilerplate

Licensed under either the WTFPL or CC0, at your choice. In practice, that means it's more or less public domain, and you can do whatever you want with it. Giving credit is not required, but still very much appreciated! I'd love to hear from you if this module was useful to you.

Creating and maintaining open-source modules is a lot of work. A donation is also not required, but much appreciated! You can donate here.

Example

A runnable version of this example can be found in the repository as example.js.

"use strict";

const unreachable = require("@joepie91/unreachable")("unreachable-demo");

function someFunction(ducksEaten) {
	let mapping = {
		1: "one",
		2: "two",
		3: "three"
	};

	let mappedValue = mapping[ducksEaten];

	if (mappedValue == null) {
		throw new Error(`Invalid value specified`);
	} else if (mappedValue === "one") {
		return "Only four little ducks came back";
	} else if (mappedValue === "two") {
		return "Only three little ducks came back";
	} else { // Oops, we forgot to add a case for "three"! Good thing we have a safety check here.
		unreachable(`Encountered unexpected mapped value '${mappedValue}'`);
	}
}

console.log(someFunction(1)); // Only four little ducks came back

console.log(someFunction(2)); // Only three little ducks came back

console.log(someFunction(3)); /*
	Error: Encountered unexpected mapped value 'three' -- this should never happen and it's a bug in 'unreachable-demo', please report it!
		at unreachable (/home/sven/projects/unreachable/index.js:5:9)
		at someFunction (/home/sven/projects/unreachable/example.js:21:3)
		at Object.<anonymous> (/home/sven/projects/unreachable/example.js:29:13)
		[ ... ]
*/

API

createUnreachable(moduleName)

This is the function exported by this module. It's a factory function, that will create and return a custom unreachable function for the specified moduleName.

• moduleName: The name of your module. Ideally, this should be the name on npm, or some other kind of unique identifier that makes it easy for users to find the correct issue tracker.

unreachable(reason)

This is the function returned by createUnreachable, and can be called to produce an error. The specified reason may be suffixed or prefixed with instructions to the user. For optimal readability, start the reason with a capital letter, and end it without a period.

This function will throw the resulting error, not return it. If needed to make your linter happy, you can write it as throw unreachable(reason) as well - since the actual error throwing happens inside the unreachable, your own throw statement will be a no-op; but your linter doesn't need to know that!

The decision to make it throw from within the unreachable function itself, is an intentional one, meant to make code fail safe; other languages, like Rust, have an unreachable statement or macro that terminates the application by itself, and it's likely that people working in multiple languages will forget the throw in JS every now and then. If this function just returned an Error, that mistake would result in the error going silently ignored. Throwing it internally makes sure it will always fail loudly.

• reason: The reason, as a string, to display in the thrown error.