http-status-codes v2 (prettymuchbryce#49)

* V2 * Update README.md * Update README.md * Remove build files * Add generated doc comment, remove build files * Respond to feedback and fix eslint * Fix build * 2.0.0-beta.2 * Target es6 modules instead * 2.0.0-beta.3 * Fix build script for ts defs. Use es6 modules. Clarify breaking/non-breaking changes. * 2.0.0-beta.4 * Add breaking change * 2.0.0-beta.5 * 2.0.0-beta.6 * Fix comment * 2.0.0-beta.7 * Fix bug in update-codes * Simply docs * README changes * 2.0.0-beta.8 * Throw an error instead of returning undefined to match v1 behavior
mrgamza · Aug 23, 2020 · 3d013c0 · 3d013c0
1 parent 398fe56
commit 3d013c0
Show file tree

Hide file tree

Showing 19 changed files with 9,512 additions and 121 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -0,0 +1,3 @@
+test/v1.js
+test/v1.d.ts
+src/codes.ts
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -0,0 +1,14 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "rules": {
+    "import/no-extraneous-dependencies": ["error", {"devDependencies": ["**/*.test.js", "./scripts/*.ts"]}]
+  },
+  "extends": ["airbnb-typescript/base"],
+  "parserOptions": {
+    "project": "./tsconfig.eslint.json"
+  }
+}
diff --git a/.gitignore b/.gitignore
@@ -16,4 +16,5 @@ testing
 .coverage_data
 cover_html
 test.js
-.idea
+.idea
+/build/**
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@ Constants enumerating the HTTP status codes. Based on the [Java Apache HttpStatu
 
 All status codes defined in RFC1945 (HTTP/1.0), RFC2616 (HTTP/1.1), RFC2518 (WebDAV), RFC6585 (Additional HTTP Status Codes), and RFC7538 (Permanent Redirect) are supported.
 
-Completely library agnostic. No dependencies.
+TypeScript or JavaScript. Completely library agnostic. No dependencies.
 
 ## Installation
 
@@ -14,123 +14,121 @@ npm install http-status-codes --save
 
 ## Usage (express 4.x)
 
-```javascript
-var HttpStatus = require('http-status-codes');
+```typescript
+import {
+	ReasonPhrases,
+	StatusCodes,
+	getReasonPhrase,
+	getStatusCode,
+} from 'http-status-codes';
 
 response
-	.status(HttpStatus.OK)
-	.send('ok');
+	.status(StatusCodes.OK)
+	.send(ReasonPhrases.OK);
 
 response
-	.status(HttpStatus.INTERNAL_SERVER_ERROR)
+	.status(StatusCodes.INTERNAL_SERVER_ERROR)
 	.send({
-		error: HttpStatus.getStatusText(HttpStatus.INTERNAL_SERVER_ERROR)
+		error: getReasonPhrase(StatusCodes.INTERNAL_SERVER_ERROR)
 	});
 
 response
-	.status(HttpStatus.getStatusCode('Server Error'))
+	.status(getStatusCode('Internal Server Error'))
 	.send({
-		error: 'Server Error'
+		error: 'Internal Server Error'
 	});
 ```
 
 ## Codes
 
-Code  | Constant                            | Status Text
-------|-------------------------------------|-----------------------------------
-100   | CONTINUE                            | Continue
-101   | SWITCHING_PROTOCOLS                 | Switching Protocols
-102   | PROCESSING                          | Processing
-200   | OK                                  | OK
-201   | CREATED                             | Created
-202   | ACCEPTED                            | Accepted
-203   | NON_AUTHORITATIVE_INFORMATION       | Non Authoritative Information
-204   | NO_CONTENT                          | No Content
-205   | RESET_CONTENT                       | Reset Content
-206   | PARTIAL_CONTENT                     | Partial Content
-207   | MULTI_STATUS                        | Multi-Status
-300   | MULTIPLE_CHOICES                    | Multiple Choices
-301   | MOVED_PERMANENTLY                   | Moved Permanently
-302   | MOVED_TEMPORARILY                   | Moved Temporarily
-303   | SEE_OTHER                           | See Other
-304   | NOT_MODIFIED                        | Not Modified
-305   | USE_PROXY                           | Use Proxy
-307   | TEMPORARY_REDIRECT                  | Temporary Redirect
-308   | PERMANENT_REDIRECT                  | Permanent Redirect
-400   | BAD_REQUEST                         | Bad Request
-401   | UNAUTHORIZED                        | Unauthorized
-402   | PAYMENT_REQUIRED                    | Payment Required
-403   | FORBIDDEN                           | Forbidden
-404   | NOT_FOUND                           | Not Found
-405   | METHOD_NOT_ALLOWED                  | Method Not Allowed
-406   | NOT_ACCEPTABLE                      | Not Acceptable
-407   | PROXY_AUTHENTICATION_REQUIRED       | Proxy Authentication Required
-408   | REQUEST_TIMEOUT                     | Request Timeout
-409   | CONFLICT                            | Conflict
-410   | GONE                                | Gone
-411   | LENGTH_REQUIRED                     | Length Required
-412   | PRECONDITION_FAILED                 | Precondition Failed
-413   | REQUEST_TOO_LONG                    | Request Entity Too Large
-414   | REQUEST_URI_TOO_LONG                | Request-URI Too Long
-415   | UNSUPPORTED_MEDIA_TYPE              | Unsupported Media Type
-416   | REQUESTED_RANGE_NOT_SATISFIABLE     | Requested Range Not Satisfiable
-417   | EXPECTATION_FAILED                  | Expectation Failed
-418   | IM_A_TEAPOT                         | I'm a teapot
-419   | INSUFFICIENT_SPACE_ON_RESOURCE      | Insufficient Space on Resource
-420   | METHOD_FAILURE                      | Method Failure
-422   | UNPROCESSABLE_ENTITY                | Unprocessable Entity
-423   | LOCKED                              | Locked
-424   | FAILED_DEPENDENCY                   | Failed Dependency
-428   | PRECONDITION_REQUIRED               | Precondition Required
-429   | TOO_MANY_REQUESTS                   | Too Many Requests
-431   | REQUEST_HEADER_FIELDS_TOO_LARGE     | Request Header Fields Too Large
-500   | INTERNAL_SERVER_ERROR               | Server Error
-501   | NOT_IMPLEMENTED                     | Not Implemented
-502   | BAD_GATEWAY                         | Bad Gateway
-503   | SERVICE_UNAVAILABLE                 | Service Unavailable
-504   | GATEWAY_TIMEOUT                     | Gateway Timeout
-505   | HTTP_VERSION_NOT_SUPPORTED          | HTTP Version Not Supported
-507   | INSUFFICIENT_STORAGE                | Insufficient Storage
-511   | NETWORK_AUTHENTICATION_REQUIRED     | Network Authentication Required
-
-## TypeScript
-
-There is an included definition file that adds rules for use, comments, and links to official documentation.
-
-### Usage
-
-Option 1: Full import of package
-
-```typescript
-import * as HttpStatus from 'http-status-codes'
-
-response
-	.status(HttpStatus.OK)
-	.send('ok')
-
-response
-	.status(HttpStatus.INTERNAL_SERVER_ERROR)
-	.send({
-		error: HttpStatus.getStatusText(HttpStatus.INTERNAL_SERVER_ERROR)
-	})
-
-response
-	.status(HttpStatus.getStatusCode('Server Error'))
-	.send({
-		error: 'Server Error'
-	})
-```
-
-Option 2: Selective import
-
-```typescript
-import { OK, getStatusText, getStatusCode } from 'http-status-codes'
-
-response
-	.status(OK)
-	.send(getStatusText(OK))
-
-response
-	.status(getStatusCode('Server Error')
-	.send('Server Error')
+| Code | Constant                        | Reason Phrase                   |
+| ---- | ------------------------------- | ------------------------------- |
+| 100  | CONTINUE                        | Continue                        |
+| 101  | SWITCHING_PROTOCOLS             | Switching Protocols             |
+| 102  | PROCESSING                      | Processing                      |
+| 200  | OK                              | OK                              |
+| 201  | CREATED                         | Created                         |
+| 202  | ACCEPTED                        | Accepted                        |
+| 203  | NON_AUTHORITATIVE_INFORMATION   | Non Authoritative Information   |
+| 204  | NO_CONTENT                      | No Content                      |
+| 205  | RESET_CONTENT                   | Reset Content                   |
+| 206  | PARTIAL_CONTENT                 | Partial Content                 |
+| 207  | MULTI_STATUS                    | Multi-Status                    |
+| 300  | MULTIPLE_CHOICES                | Multiple Choices                |
+| 301  | MOVED_PERMANENTLY               | Moved Permanently               |
+| 302  | MOVED_TEMPORARILY               | Moved Temporarily               |
+| 303  | SEE_OTHER                       | See Other                       |
+| 304  | NOT_MODIFIED                    | Not Modified                    |
+| 305  | USE_PROXY                       | Use Proxy                       |
+| 307  | TEMPORARY_REDIRECT              | Temporary Redirect              |
+| 308  | PERMANENT_REDIRECT              | Permanent Redirect              |
+| 400  | BAD_REQUEST                     | Bad Request                     |
+| 401  | UNAUTHORIZED                    | Unauthorized                    |
+| 402  | PAYMENT_REQUIRED                | Payment Required                |
+| 403  | FORBIDDEN                       | Forbidden                       |
+| 404  | NOT_FOUND                       | Not Found                       |
+| 405  | METHOD_NOT_ALLOWED              | Method Not Allowed              |
+| 406  | NOT_ACCEPTABLE                  | Not Acceptable                  |
+| 407  | PROXY_AUTHENTICATION_REQUIRED   | Proxy Authentication Required   |
+| 408  | REQUEST_TIMEOUT                 | Request Timeout                 |
+| 409  | CONFLICT                        | Conflict                        |
+| 410  | GONE                            | Gone                            |
+| 411  | LENGTH_REQUIRED                 | Length Required                 |
+| 412  | PRECONDITION_FAILED             | Precondition Failed             |
+| 413  | REQUEST_TOO_LONG                | Request Entity Too Large        |
+| 414  | REQUEST_URI_TOO_LONG            | Request-URI Too Long            |
+| 415  | UNSUPPORTED_MEDIA_TYPE          | Unsupported Media Type          |
+| 416  | REQUESTED_RANGE_NOT_SATISFIABLE | Requested Range Not Satisfiable |
+| 417  | EXPECTATION_FAILED              | Expectation Failed              |
+| 418  | IM_A_TEAPOT                     | I'm a teapot                    |
+| 419  | INSUFFICIENT_SPACE_ON_RESOURCE  | Insufficient Space on Resource  |
+| 420  | METHOD_FAILURE                  | Method Failure                  |
+| 422  | UNPROCESSABLE_ENTITY            | Unprocessable Entity            |
+| 423  | LOCKED                          | Locked                          |
+| 424  | FAILED_DEPENDENCY               | Failed Dependency               |
+| 428  | PRECONDITION_REQUIRED           | Precondition Required           |
+| 429  | TOO_MANY_REQUESTS               | Too Many Requests               |
+| 431  | REQUEST_HEADER_FIELDS_TOO_LARGE | Request Header Fields Too Large |
+| 500  | INTERNAL_SERVER_ERROR           | Internal Server Error           |
+| 501  | NOT_IMPLEMENTED                 | Not Implemented                 |
+| 502  | BAD_GATEWAY                     | Bad Gateway                     |
+| 503  | SERVICE_UNAVAILABLE             | Service Unavailable             |
+| 504  | GATEWAY_TIMEOUT                 | Gateway Timeout                 |
+| 505  | HTTP_VERSION_NOT_SUPPORTED      | HTTP Version Not Supported      |
+| 507  | INSUFFICIENT_STORAGE            | Insufficient Storage            |
+| 511  | NETWORK_AUTHENTICATION_REQUIRED | Network Authentication Required |
+
+## Migrating from v1.x.x
+
+http-status-codes v2 is mostly backwards compatible with v1. There is a single breaking change and two recommended changes.
+
+#### [Breaking Change] 'Server Error'
+
+The reason phrase for the status code `500` has been changed from `"Server Error"` to `"Internal Server Error"`. This is the correct phrase according to RFC7231. If you are migrating from v1, and have code that relies on the result of `getStatusText(500)` or `getReasonPhrase('Server Error')`, then this could affect you.
+
+#### [Non-breaking change] getStatusText renamed getReasonPhrase
+
+The function `getStatusText` has been renamed to `getReasonPhrase`. The old function is still available, but may be deprecated in a future version. To fix this simply rename instances of `getStatusText()` to `getReasonPhrase()`. The function is otherwise the same as it was before.
+
+#### [Non-breaking change] StatusCodes
+
+In http-status-codes v1, Status Codes were exported directly from the top-level module. i.e. `HttpStatus.OK`. In v2 all Status Codes live under an object called `StatusCodes`. i.e. `HttpStatus.StatusCodes.OK`. We made this change to cater to TypeScript users who prefer a dedicated value with an enum type. The previous values are still exported, but we won't continue to update them. Please migrate if you're using the old-style imports.
+
+## Proposing a new status code
+
+If you'd like to propose a new status code, feel free to update "codes.json" with the necessary
+information and open a pull request. There is no need to modify source code or even this README.
+This is done automatically by `npm run update-codes`.
+
+In general, we try to include only codes that have an official RFC and have been approved, however
+exceptions can be made if the code is already in widespread use in the wild.
+
+## Steps to build and publish
+
+```shell
+npm run update-codes
+npm run test
+npm run build
+npm version [major | minor | patch]
+npm run publish
 ```