|
|
|
|
@ -0,0 +1,75 @@
|
|
|
|
|
# @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](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), 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](mailto:admin@cryto.net) 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](http://cryto.net/~joepie91/donate.html).
|
|
|
|
|
|
|
|
|
|
## Example
|
|
|
|
|
|
|
|
|
|
A runnable version of this example can be found in the repository as `example.js`.
|
|
|
|
|
|
|
|
|
|
```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.
|
