Skip to content

Commit 7ff91cf

Browse files
adoyle-hadoyle-h
committed
Merge branch 'release'
* release: update version to 0.2.0 docs(README): update docs(README): update chinese README chore(CI): cache node_modules and apt in Travis-CI chore(CI): test node v5.1 and v5 & if npm version > 3.3 upgrade it to latest before CI test style(test): change codes for eslint docs(README): update chinese README chore: update jsduck and package.json feat: refactoring Ero to be a class, no longer be singleton docs(README): add TOC chore(gulp-license): use my gulp-license style(eslint): upgrade eslint for my style docs(README): update copyright and license descriptions
2 parents 443f757 + 4f62fcb commit 7ff91cf

24 files changed

+837
-555
lines changed

‎.eslintrc

Lines changed: 1 addition & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,4 @@
11
{
22
"root": true,
3-
"rules": {
4-
"indent": [
5-
2,
6-
4
7-
],
8-
"quotes": [
9-
2,
10-
"single"
11-
],
12-
"linebreak-style": [
13-
2,
14-
"unix"
15-
],
16-
"semi": [
17-
2,
18-
"always"
19-
],
20-
"vars-on-top": 0,
21-
"func-names": 0,
22-
"no-param-reassign": 1,
23-
"strict": [2, "global"],
24-
"spaced-comment": [0, "always"],
25-
"no-param-reassign": [1, {"props": true}],
26-
"no-console": 2,
27-
"no-shadow": [0, {
28-
"builtinGlobals": true,
29-
"hoist": "all",
30-
"allow": ["callback"],
31-
}],
32-
"dot-notation": 1,
33-
"no-extra-parens": 1,
34-
"object-curly-spacing": [2, "never"],
35-
"space-before-function-paren": [2, {
36-
"anonymous": "never",
37-
"named": "never",
38-
}],
39-
"no-bitwise": 2,
40-
"no-else-return": 0,
41-
"no-multi-str": 0,
42-
},
43-
"env": {
44-
"node": true
45-
},
46-
"globals": {
47-
include: false
48-
},
49-
"extends": "airbnb/legacy"
3+
"extends": "adoyle-style"
504
}

‎.travis.yml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,35 @@
1+
cache:
2+
apt: true
3+
directories:
4+
- node_modules
5+
16
git:
27
depth: 2
8+
39
branches:
410
only:
511
- master
612
- develop
13+
714
language: node_js
15+
816
node_js:
17+
- "5"
18+
- "5.1"
19+
- "4"
20+
- "4.2"
921
- "4.1"
1022
- "4.0"
1123
- "0.12"
1224
- "0.11"
25+
26+
before_install:
27+
- t=3.3 && v=`npm -v` && x=`printf "$v\n$t" | sort -V | head -n 1` && [ $x != $t ] && npm install -g npm || echo "no need to upgrade npm."
28+
1329
install:
1430
- npm install
1531
- npm install -g gulp
32+
1633
script:
1734
- gulp lint
1835
- gulp test

‎ChangeLog.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,13 @@
1+
<a name="0.2.0"></a>
2+
# [0.2.0](https://github.com/adoyle-h/Ero.js/compare/v0.1.0...v0.2.0) (2016-04-05)
3+
4+
5+
### Features
6+
7+
* refactoring Ero to be a class, no longer be singleton ([7c25daf](https://github.com/adoyle-h/Ero.js/commit/7c25daf))
8+
9+
10+
111
<a name="0.1.0"></a>
212
# [0.1.0](https://github.com/adoyle-h/Ero.js/compare/v0.0.2...v0.1.0) (2016-01-11)
313

‎README.md

Lines changed: 110 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,34 @@ An error library provides simple functions for building your own customized erro
1313

1414
[简体中文](./doc/README.zh-Hans.md)
1515

16+
## TOC
17+
18+
<!-- MarkdownTOC -->
19+
20+
- [Installation](#installation)
21+
- [Quick Start](#quick-start)
22+
- [Basic Concepts](#basic-concepts)
23+
- [Ero Class](#ero-class)
24+
- [Error Template](#error-template)
25+
- [Error Definitions](#error-definitions)
26+
- [BaseError](#baseerror)
27+
- [Error Class](#error-class)
28+
- [Feature](#feature)
29+
- [Creating error instance without capturing stack trace](#creating-error-instance-without-capturing-stack-trace)
30+
- [Multi Ero Instances](#multi-ero-instances)
31+
- [API](#api)
32+
- [Versioning](#versioning)
33+
- [Copyright and License](#copyright-and-license)
34+
35+
<!-- /MarkdownTOC -->
36+
37+
38+
<a name="installation"></a>
1639
## Installation
1740

1841
`npm install --save ero`
1942

43+
<a name="quick-start"></a>
2044
## Quick Start
2145

2246
It is highly recommended that you should wrap the `ero` library to extend your own error module.
@@ -66,20 +90,20 @@ var definitions = {
6690
},
6791
};
6892

69-
// initialize the ero library
70-
Errors.init({
93+
// create an ero instance
94+
var ero = new Ero({
7195
template: errorTemplate,
7296
definitions: definitions,
7397
});
7498

75-
// export the Errors
76-
module.exports = Errors;
99+
module.exports = ero;
77100
```
78101

79102
In another file, require your error module:
80103

81104
```js
82-
var Errors = require('./error');
105+
vvar ero = require('./error');
106+
var Errors = ero.Errors;
83107

84108
// use the defined errors
85109
// assume that there is a meta obejct
@@ -105,7 +129,26 @@ console.log('statusCode: ', e.statusCode);
105129
console.log('logLevel: ', e.logLevel);
106130
```
107131

108-
## Error Template
132+
<a name="basic-concepts"></a>
133+
## Basic Concepts
134+
135+
<a name="ero-class"></a>
136+
### Ero Class
137+
138+
`new Ero()` create an ero instance, which is a space storing error classes, and providing some utility functions.
139+
140+
ero contains these members as below:
141+
142+
- [template](#error-template)
143+
- [BaseError](#baseerror)
144+
- [Errors](#error-class): All customized errors are put here.
145+
146+
Each ero space are independent.
147+
148+
Ero provides some utility functions, such as `Ero.isCustomError`. Please refer to [API document][API - Ero].
149+
150+
<a name="error-template"></a>
151+
### Error Template
109152

110153
The error template is used to constrain the properties of the error definition.
111154

@@ -114,17 +157,36 @@ Furthermore, the template can also set default values for the properties of all
114157

115158
The `message` property of template do nothing besides force the developer to explain the meaning of each property of error definition.
116159

117-
## Error Definitions
160+
<a name="error-definitions"></a>
161+
### Error Definitions
118162

119163
Each error definition is used to create the corresponding error class.
120164

121-
Each error definition is defined by `<error name>: <properties definitions>`, which `<error name>` should be unique.
165+
Each error definition is defined by a key/value pair `<error name>: <properties definitions>`, in which `<error name>` should be unique.
122166

123167
`Properties definitions` is an object composed of many key/value pairs.
124168
It will be assigned to the prototype of corresponding error class, as the default value for each error instance.
125169

126-
## Error Class
127-
Each error definitions provided will be used to generate corresponding error classes, which are inherited from the [`BaseError`](http://adoyle.me/Ero.js/#!/api/BaseError) base class.
170+
<a name="baseerror"></a>
171+
### BaseError
172+
173+
The Ero.js provides a `BaseError` class as the base class of all customized error classes.
174+
175+
`BaseError` class has properties as below:
176+
177+
- meta: {Object} The metadata for error.
178+
- message: {String} The error message.
179+
- [stack]: {String} The error stack. It is existed when `captureStackTrace` is `true`.
180+
- captureStackTrace: {Boolean} Whether to capture the stack trace. Default to `true`.
181+
- name: {String} The name of error class.
182+
- ERROR_STACK_SEPARATOR: {String} The separator between multi error stacks.
183+
- MESSAGE_CONNECTOR: {String} The connector between multi error messages.
184+
185+
Refer to [`API document - BaseError`][API - BaseError] for more details.
186+
187+
<a name="error-class"></a>
188+
### Error Class
189+
Each error definitions provided will be used to generate corresponding error classes, which are inherited from the [`BaseError`][BaseError] base class.
128190

129191
`BaseError` has a full featured constructor that is convenient for adding more useful information to error instance when you create it.
130192

@@ -157,16 +219,40 @@ console.log(thirdErr.meta); // The secondMeta and thirdMeta will be added to er
157219
console.log(thirdErr.stack); // These three error stacks will be together in a series.
158220
```
159221

160-
Certainly, error, meta, message can be optional:
222+
Certainly, error, meta, message are optional parameters:
161223

162224
```js
163225
var err = new Errors.Error();
164226
```
165227

228+
<a name="feature"></a>
229+
## Feature
230+
231+
<a name="creating-error-instance-without-capturing-stack-trace"></a>
232+
### Creating error instance without capturing stack trace
233+
234+
`error.stack` is not required. It means that calling `var error = new Errors.SubError();` could not capture the error stack.
235+
There is a scenario, developers need to create a error instance, while do not care about its error stack.
236+
237+
(It would not capture stack error, only when `SubError.captureStackTrace` is `false`. Refer to [BaseError][] for More informations)
238+
239+
<a name="multi-ero-instances"></a>
240+
### Multi Ero Instances
241+
242+
In most cases, like building a web server application, you only need one ero instance for customizing your errors.
243+
244+
For framework libraries, you could create multi ero instances, for providing the error classes for framework layer and user layer.
245+
246+
For class libraries, I think it is unnecessary to use this project and the native error class is enough.
247+
248+
**Attentions**, the `template`, `BaseError` and `Errors` are independent between different ero instances. Thus `ero.isCustomError` could only recognize the errors which created based on the `Errors` in an ero.
249+
250+
<a name="api"></a>
166251
## API
167252

168-
see http://adoyle.me/Ero.js/
253+
The specifications of API, and details not mentioned in README, would be referenced at [API document][API].
169254

255+
<a name="versioning"></a>
170256
## Versioning
171257

172258
The versioning follows the rules of SemVer 2.0.0.
@@ -175,19 +261,24 @@ The versioning follows the rules of SemVer 2.0.0.
175261

176262
For more information on SemVer, please visit http://semver.org/.
177263

264+
<a name="copyright-and-license"></a>
178265
## Copyright and License
179266

180-
Copyright 2015-2016 ADoyle
267+
Copyright (c) 2015-2016 ADoyle. The project is licensed under the **Apache License Version 2.0**.
268+
269+
See the [LICENSE][] file for the specific language governing permissions and limitations under the License.
181270

182-
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
183-
You may obtain a copy of the License at
271+
See the [NOTICE][] file distributed with this work for additional information regarding copyright ownership.
184272

185-
http://www.apache.org/licenses/LICENSE-2.0
186273

187-
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
188-
See the License for the specific language governing permissions and limitations under the License.
274+
<!-- Links -->
189275

190-
See the NOTICE file distributed with this work for additional information regarding copyright ownership.
276+
[LICENSE]: ./LICENSE
277+
[NOTICE]: ./NOTICE
278+
[BaseError]: #baseerror
279+
[API]: http://adoyle.me/Ero.js/
280+
[API - BaseError]: http://adoyle.me/Ero.js/#!/api/BaseError
281+
[API - Ero]: http://adoyle.me/Ero.js/#!/api/Ero
191282

192283

193284
<!-- links -->

0 commit comments

Comments
 (0)