feat(binary): Added standalone application of trace-unhandled

README.md

@@ -19,7 +19,18 @@ When this happens, it's not always obvious what promise is unhandled. The error
 
 **This package is not intended to be used in production, only to aid locating bugs**
 
-# API
+# Usage
+
+## As a standalone program
+
+`trace-unhandled` exports a program which can run JavaScript files and shebang scripts. Instead of running your program as `node index.js` you can do `trace-unhandled index.js` as long as `trace-unhandled` is globally installed.
+
+You can also use `npx`:
+
+`npx trace-unhandled index.js`
+
+
+## Programatically - API
 
 ```ts
 require( 'trace-unhandled/register' ); // As early as possible
@@ -34,6 +45,20 @@ const { register } = require( 'trace-unhandled' );
 register( );
 ```
 
+## Use in unit tests
+
+To use this package when running `jest`, install the package and configure jest with the following setup:
+
+```js
+{
+  setupFiles: [
+    "trace-unhandled/register"
+  ]
+}
+```
+
+The tests will now log much better information about unhandled promise rejections.
+
 
 [npm-image]: https://img.shields.io/npm/v/trace-unhandled.svg
 [npm-url]: https://npmjs.org/package/trace-unhandled

bin.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+const path = require( "path" );
+const { run } = require( "haxec" );
+
+const [ prog, ...args ] = process.argv.slice( 2 );
+
+if ( !prog )
+{
+	console.error( "Usage: trace-unhandled prog [args...]" );
+	console.error(
+		"  <prog> can be either a shebang script or a JavaScript file"
+	);
+	process.exit( 1 );
+}
+
+run( path.join( __dirname, "register.js" ), [ prog, ...args ] );

package.json

@@ -7,6 +7,9 @@
   "bugs": {
     "url": "https://github.com/grantila/trace-unhandled/issues"
   },
+  "bin": {
+    "trace-unhandled": "bin.js"
+  },
   "homepage": "https://github.com/grantila/trace-unhandled#readme",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -16,7 +19,8 @@
   "files": [
     "index.js",
     "index.d.ts",
-    "register.js"
+    "register.js",
+    "bin.js"
   ],
   "scripts": {
     "test": "node --expose-gc node_modules/.bin/jest --coverage",
@@ -36,6 +40,9 @@
     "stack",
     "stacktrace"
   ],
+  "dependencies": {
+    "haxec": "^1.1.0"
+  },
   "devDependencies": {
     "@types/jest": "^20",
     "@types/node": "^12",