• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# node-errno
2
3> Better [libuv](https://github.com/libuv/libuv)/[Node.js](https://nodejs.org)/[io.js](https://iojs.org) error handling & reporting. Available in npm as *errno*.
4
5[![npm](https://img.shields.io/npm/v/errno.svg)](https://www.npmjs.com/package/errno)
6[![Build Status](https://secure.travis-ci.org/rvagg/node-errno.png)](http://travis-ci.org/rvagg/node-errno)
7[![npm](https://img.shields.io/npm/dm/errno.svg)](https://www.npmjs.com/package/errno)
8
9* [errno exposed](#errnoexposed)
10* [Custom errors](#customerrors)
11
12<a name="errnoexposed"></a>
13## errno exposed
14
15Ever find yourself needing more details about Node.js errors? Me too, so *node-errno* contains the errno mappings direct from libuv so you can use them in your code.
16
17**By errno:**
18
19```js
20require('errno').errno[3]
21// → {
22//     "errno": 3,
23//     "code": "EACCES",
24//     "description": "permission denied"
25//   }
26```
27
28**By code:**
29
30```js
31require('errno').code.ENOTEMPTY
32// → {
33//     "errno": 53,
34//     "code": "ENOTEMPTY",
35//     "description": "directory not empty"
36//   }
37```
38
39**Make your errors more descriptive:**
40
41```js
42var errno = require('errno')
43
44function errmsg(err) {
45  var str = 'Error: '
46  // if it's a libuv error then get the description from errno
47  if (errno.errno[err.errno])
48    str += errno.errno[err.errno].description
49  else
50    str += err.message
51
52  // if it's a `fs` error then it'll have a 'path' property
53  if (err.path)
54    str += ' [' + err.path + ']'
55
56  return str
57}
58
59var fs = require('fs')
60
61fs.readFile('thisisnotarealfile.txt', function (err, data) {
62  if (err)
63    console.log(errmsg(err))
64})
65```
66
67**Use as a command line tool:**
68
69```
70~ $ errno 53
71{
72  "errno": 53,
73  "code": "ENOTEMPTY",
74  "description": "directory not empty"
75}
76~ $ errno EROFS
77{
78  "errno": 56,
79  "code": "EROFS",
80  "description": "read-only file system"
81}
82~ $ errno foo
83No such errno/code: "foo"
84```
85
86Supply no arguments for the full list. Error codes are processed case-insensitive.
87
88You will need to install with `npm install errno -g` if you want the `errno` command to be available without supplying a full path to the node_modules installation.
89
90<a name="customerrors"></a>
91## Custom errors
92
93Use `errno.custom.createError()` to create custom `Error` objects to throw around in your Node.js library. Create error hierarchies so `instanceof` becomes a useful tool in tracking errors. Call-stack is correctly captured at the time you create an instance of the error object, plus a `cause` property will make available the original error object if you pass one in to the constructor.
94
95```js
96var create = require('errno').custom.createError
97var MyError = create('MyError') // inherits from Error
98var SpecificError = create('SpecificError', MyError) // inherits from MyError
99var OtherError = create('OtherError', MyError)
100
101// use them!
102if (condition) throw new SpecificError('Eeek! Something bad happened')
103
104if (err) return callback(new OtherError(err))
105```
106
107Also available is a `errno.custom.FilesystemError` with in-built access to errno properties:
108
109```js
110fs.readFile('foo', function (err, data) {
111  if (err) return callback(new errno.custom.FilesystemError(err))
112  // do something else
113})
114```
115
116The resulting error object passed through the callback will have the following properties: `code`, `errno`, `path` and `message` will contain a descriptive human-readable message.
117
118## Contributors
119
120* [bahamas10](https://github.com/bahamas10) (Dave Eddy) - Added CLI
121* [ralphtheninja](https://github.com/ralphtheninja) (Lars-Magnus Skog)
122
123## Copyright & Licence
124
125*Copyright (c) 2012-2015 [Rod Vagg](https://github.com/rvagg) ([@rvagg](https://twitter.com/rvagg))*
126
127Made available under the MIT licence:
128
129Permission is hereby granted, free of charge, to any person obtaining a copy
130of this software and associated documentation files (the "Software"), to deal
131in the Software without restriction, including without limitation the rights
132to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
133copies of the Software, and to permit persons to whom the Software is furnished
134to do so, subject to the following conditions:
135
136The above copyright notice and this permission notice shall be included in all
137copies or substantial portions of the Software.
138
139THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
140IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
141FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
142AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
143LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
144OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
145SOFTWARE.
146