@stexcore/http-status NPM

@stexcore/http-status

NPM Version License

A collection of HTTP status codes for general use in any HTTP framework.
Simplifies the management of HTTP responses and errors with a clean and easy-to-use interface. Fully compatible with TypeScript and any HTTP framework.

🚀 Installation

Install the package from NPM using the following command:

npm install @stexcore/http-status

📦 Usage

Basic Import and Example

import httpStatus from "@stexcore/http-status";

// Create a successful response (200 OK)
const response = httpStatus.ok("Operation successful", { id: 123 });
console.log(response);

// Handle an error (404 Not Found)
const error = httpStatus.notFound("The requested resource was not found");
console.log(error);

// Validate if an object is an HttpError
if (httpStatus.isHttpError(error)) {
    console.error("This is an HTTP error!", error.message);
}

🌟 Main Methods

Success Responses (2xx)

Method	Description
`ok`	Creates a 200 OK response.
`created`	Creates a 201 Created response.
`accepted`	Creates a 202 Accepted response.
`nonAuthoritativeInfo`	Creates a 203 Non-Authoritative Information response.
`noContent`	Creates a 204 No Content response.
`resetContent`	Creates a 205 Reset Content response.
`partialContent`	Creates a 206 Partial Content response.
`multiStatus`	Creates a 207 Multi-Status response.
`alreadyReported`	Creates a 208 Already Reported response.
`imUsed`	Creates a 226 IM Used response.

Redirections (3xx)

Method	Description
`movedPermanently`	Creates a 301 Moved Permanently response.
`found`	Creates a 302 Found response.
`seeOther`	Creates a 303 See Other response.
`notModified`	Creates a 304 Not Modified response.
`useProxy`	Creates a 305 Use Proxy response.
`temporaryRedirect`	Creates a 307 Temporary Redirect response.
`permanentRedirect`	Creates a 308 Permanent Redirect response.

Client Errors (4xx)

Method	Description
`badRequest`	Creates a 400 Bad Request error.
`unauthorized`	Creates a 401 Unauthorized error.
`paymentRequired`	Creates a 402 Payment Required error.
`forbidden`	Creates a 403 Forbidden error.
`notFound`	Creates a 404 Not Found error.
`methodNotAllowed`	Creates a 405 Method Not Allowed error.
`notAcceptable`	Creates a 406 Not Acceptable error.
`proxyAuthRequired`	Creates a 407 Proxy Authentication Required error.
`requestTimeout`	Creates a 408 Request Timeout error.
`conflict`	Creates a 409 Conflict error.
`gone`	Creates a 410 Gone error.
`lengthRequired`	Creates a 411 Length Required error.
`preconditionFailed`	Creates a 412 Precondition Failed error.

Server Errors (5xx)

Method	Description
`internalServerError`	Creates a 500 Internal Server Error.
`notImplemented`	Creates a 501 Not Implemented error.
`badGateway`	Creates a 502 Bad Gateway error.
`serviceUnavailable`	Creates a 503 Service Unavailable error.
`gatewayTimeout`	Creates a 504 Gateway Timeout error.
`httpVersionNotSupported`	Creates a 505 HTTP Version Not Supported error.
`variantAlsoNegotiates`	Creates a 506 Variant Also Negotiates error.
`insufficientStorage`	Creates a 507 Insufficient Storage error.
`loopDetected`	Creates a 508 Loop Detected error.
`bandwidthLimitExceeded`	Creates a 509 Bandwidth Limit Exceeded error.
`notExtended`	Creates a 510 Not Extended error.
`networkAuthenticationRequired`	Creates a 511 Network Authentication Required error.

⚙️ Configuration

This library is ready to use directly out of the box. TypeScript is optional and supported: declaration files (.d.ts) are included to enable seamless integration for TypeScript projects. If you're using JavaScript, simply install the library and start using it without additional setup.

📖 Technical Details

This package includes key classes for managing HTTP statuses and errors:

HttpStatus: A base class for representing HTTP responses.
HttpError: Extends Error to represent HTTP errors.

💡 Example with Express

Here's a possible use case for integrating this library with Express, a widely used Node.js framework:

import express from "express";
import httpStatus from "@stexcore/http-status";

const app = express();

// A sample route to return a successful response
app.get("/success", (req, res) => {
    res.json(httpStatus.ok("The operation was successful!", { data: "Example data" }));
});

// A route to simulate a server error
app.get("/error", (req, res) => {
    res.status(500).json(httpStatus.internalServerError("An unexpected error occurred.", { traceId: "123-abc" }));
});

// Start the server
const PORT = 3000;
app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:\${PORT}`);
});

In this example:

The /success route demonstrates a typical 200 OK response with additional data.
The /error route showcases how you can return a structured 500 Internal Server Error.

🛠️ Development

If you'd like to contribute or report issues, visit our GitHub repository:
https://github.com/stexcore/http-status

📝 License

This project is licensed under the MIT license. See the LICENSE file for more details.

http errors status standard

4 months ago

4 months ago

4 months ago