express-response-kit-sid 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,177 @@
1
- # Temporary Holding Version
2
1
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
2
+ # Express Response Kit
3
+
4
+ A lightweight Express.js toolkit for creating standardized API responses, handling errors, and managing pagination.
5
+
6
+ ## Features
7
+
8
+ - Standardized success responses
9
+ - Standardized error responses
10
+ - Pagination metadata
11
+ - Paginated API responses
12
+ - Async route error handling
13
+ - Centralized Express error middleware
14
+
15
+ ## Installation
16
+
17
+ ```bash
18
+ npm install express-response-kit-sid
19
+ ```
20
+
21
+ ## Usage
22
+
23
+ Import the required functions:
24
+
25
+ ```javascript
26
+ const {
27
+ sendSuccess,
28
+ sendError,
29
+ paginationMeta,
30
+ sendPaginated,
31
+ asyncHandler,
32
+ errorHandler
33
+ } = require("express-response-kit-sid");
34
+ ```
35
+
36
+ ## Available Functions
37
+
38
+ ### 1. sendSuccess()
39
+
40
+ Sends a standardized success response.
41
+
42
+ ```javascript
43
+ app.get("/users", (req, res) => {
44
+ sendSuccess(res, [{ id: 1, name: "Sid" }], "Users retrieved");
45
+ });
46
+ ```
47
+
48
+ ### 2. sendError()
49
+
50
+ Sends a standardized error response.
51
+
52
+ ```javascript
53
+ app.get("/users/:id", (req, res) => {
54
+ sendError(res, "User not found", 404, "NOT_FOUND");
55
+ });
56
+ ```
57
+
58
+ ### 3. paginationMeta()
59
+
60
+ Generates pagination metadata.
61
+
62
+ ```javascript
63
+ const meta = paginationMeta(100, 2, 10);
64
+
65
+ console.log(meta);
66
+ ```
67
+
68
+ The result includes:
69
+
70
+ - Current page
71
+ - Page limit
72
+ - Total records
73
+ - Total pages
74
+ - Whether a next page exists
75
+ - Whether a previous page exists
76
+
77
+ ### 4. sendPaginated()
78
+
79
+ Sends data along with pagination metadata.
80
+
81
+ ```javascript
82
+ app.get("/users", (req, res) => {
83
+ const users = [{ id: 1, name: "Sid" }];
84
+
85
+ sendPaginated(res, users, 100, 1, 10);
86
+ });
87
+ ```
88
+
89
+ ### 5. asyncHandler()
90
+
91
+ Forwards errors from asynchronous Express route handlers to error middleware.
92
+
93
+ ```javascript
94
+ app.get("/data", asyncHandler(async (req, res) => {
95
+ const data = await getData();
96
+
97
+ sendSuccess(res, data, "Data retrieved");
98
+ }));
99
+ ```
100
+
101
+ ### 6. errorHandler()
102
+
103
+ Centralized Express error-handling middleware.
104
+
105
+ Register it after your routes:
106
+
107
+ ```javascript
108
+ app.use(errorHandler);
109
+ ```
110
+
111
+ ## Complete Express Example
112
+
113
+ ```javascript
114
+ const express = require("express");
115
+
116
+ const {
117
+ sendSuccess,
118
+ sendError,
119
+ sendPaginated,
120
+ asyncHandler,
121
+ errorHandler
122
+ } = require("express-response-kit-sid");
123
+
124
+ const app = express();
125
+
126
+ app.get("/", (req, res) => {
127
+ sendSuccess(res, { status: "running" }, "Welcome");
128
+ });
129
+
130
+ app.get("/error", asyncHandler(async (req, res) => {
131
+ throw new Error("Example error");
132
+ }));
133
+
134
+ app.use(errorHandler);
135
+
136
+ app.listen(3000, () => {
137
+ console.log("Server running on port 3000");
138
+ });
139
+ ```
140
+
141
+ ## Running Tests
142
+
143
+ Clone the repository and install development dependencies:
144
+
145
+ ```bash
146
+ npm install
147
+ ```
148
+
149
+ Run the automated tests:
150
+
151
+ ```bash
152
+ npm test
153
+ ```
154
+
155
+ ## Project Structure
156
+
157
+ ```text
158
+ express-response-kit/
159
+ ├── src/
160
+ │ ├── response.js
161
+ │ ├── pagination.js
162
+ │ ├── asyncHandler.js
163
+ │ └── error.js
164
+ ├── test/
165
+ │ ├── response.test.js
166
+ │ ├── pagination.test.js
167
+ │ └── middleware.test.js
168
+ ├── examples/
169
+ │ └── express-app.js
170
+ ├── index.js
171
+ ├── package.json
172
+ └── README.md
173
+ ```
174
+
175
+ ## License
176
+
177
+ ISC
@@ -0,0 +1,59 @@
1
+
2
+ const express = require("express");
3
+
4
+ const {
5
+ sendSuccess,
6
+ sendError,
7
+ sendPaginated,
8
+ asyncHandler,
9
+ errorHandler
10
+ } = require("../index");
11
+
12
+ const app = express();
13
+
14
+ app.use(express.json());
15
+
16
+ const students = [
17
+ { id: 1, name: "Rahul", course: "Computer Science" },
18
+ { id: 2, name: "Priya", course: "Information Technology" },
19
+ { id: 3, name: "Arjun", course: "Computer Science" },
20
+ { id: 4, name: "Sneha", course: "Electronics" }
21
+ ];
22
+
23
+ app.get("/", (req, res) => {
24
+ sendSuccess(res, { status: "API is running" }, "Welcome");
25
+ });
26
+
27
+ app.get("/students", (req, res) => {
28
+ const page = Number(req.query.page) || 1;
29
+ const limit = Number(req.query.limit) || 2;
30
+
31
+ const start = (page - 1) * limit;
32
+ const paginatedStudents = students.slice(start, start + limit);
33
+
34
+ sendPaginated(res, paginatedStudents, students.length, page, limit);
35
+ });
36
+
37
+ app.get("/students/:id", (req, res) => {
38
+ const student = students.find(
39
+ (item) => item.id === Number(req.params.id)
40
+ );
41
+
42
+ if (!student) {
43
+ return sendError(res, "Student not found", 404, "NOT_FOUND");
44
+ }
45
+
46
+ sendSuccess(res, student, "Student retrieved successfully");
47
+ });
48
+
49
+ app.get("/error", asyncHandler(async (req, res) => {
50
+ throw new Error("Example error");
51
+ }));
52
+
53
+ app.use(errorHandler);
54
+
55
+ const PORT = 3000;
56
+
57
+ app.listen(PORT, () => {
58
+ console.log(`Example server running at http://localhost:${PORT}`);
59
+ });
package/index.js ADDED
@@ -0,0 +1,13 @@
1
+ const { sendSuccess, sendError } = require("./src/response");
2
+ const { paginationMeta, sendPaginated } = require("./src/pagination");
3
+ const asyncHandler = require("./src/asyncHandler");
4
+ const errorHandler = require("./src/error");
5
+
6
+ module.exports = {
7
+ sendSuccess,
8
+ sendError,
9
+ paginationMeta,
10
+ sendPaginated,
11
+ asyncHandler,
12
+ errorHandler
13
+ };
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
+
1
2
  {
2
3
  "name": "express-response-kit-sid",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
4
+ "version": "1.0.0",
5
+ "description": "A reusable Express.js toolkit for standardized API responses, pagination, and error handling",
6
+ "main": "index.js",
7
+ "type": "commonjs",
8
+ "engines": {
9
+ "node": ">=18"
10
+ },
11
+ "files": [
12
+ "index.js",
13
+ "src/",
14
+ "examples/",
15
+ "README.md"
16
+ ],
17
+ "scripts": {
18
+ "test": "jest",
19
+ "test:watch": "jest --watch"
20
+ },
21
+ "keywords": [
22
+ "express",
23
+ "nodejs",
24
+ "api",
25
+ "middleware",
26
+ "response-handler",
27
+ "pagination"
28
+ ],
29
+ "license": "ISC",
30
+ "devDependencies": {
31
+ "express": "^5.3.0",
32
+ "jest": "^30.5.2"
33
+ }
34
+ }
@@ -0,0 +1,7 @@
1
+ function asyncHandler(fn) {
2
+ return function (req, res, next) {
3
+ Promise.resolve(fn(req, res, next)).catch(next);
4
+ };
5
+ }
6
+
7
+ module.exports = asyncHandler;
package/src/error.js ADDED
@@ -0,0 +1,17 @@
1
+ function errorHandler(err, req, res, next) {
2
+ if (res.headersSent) {
3
+ return next(err);
4
+ }
5
+
6
+ const statusCode = err.statusCode || err.status || 500;
7
+
8
+ return res.status(statusCode).json({
9
+ success: false,
10
+ message: err.message || "Internal Server Error",
11
+ error: {
12
+ code: err.code || "INTERNAL_ERROR"
13
+ }
14
+ });
15
+ }
16
+
17
+ module.exports = errorHandler;
@@ -0,0 +1,48 @@
1
+
2
+ function paginationMeta(total, page, limit) {
3
+ if (!Number.isInteger(total) || total < 0) {
4
+ throw new Error("Total must be a non-negative integer");
5
+ }
6
+
7
+ if (!Number.isInteger(page) || page < 1) {
8
+ throw new Error("Page must be a positive integer");
9
+ }
10
+
11
+ if (!Number.isInteger(limit) || limit < 1) {
12
+ throw new Error("Limit must be a positive integer");
13
+ }
14
+
15
+ const totalPages = Math.ceil(total / limit);
16
+
17
+ return {
18
+ page,
19
+ limit,
20
+ total,
21
+ totalPages,
22
+ hasNextPage: page < totalPages,
23
+ hasPreviousPage: page > 1
24
+ };
25
+ }
26
+
27
+ function sendPaginated(
28
+ res,
29
+ data,
30
+ total,
31
+ page,
32
+ limit,
33
+ message = "Data retrieved successfully"
34
+ ) {
35
+ const meta = paginationMeta(total, page, limit);
36
+
37
+ return res.status(200).json({
38
+ success: true,
39
+ message,
40
+ data,
41
+ meta
42
+ });
43
+ }
44
+
45
+ module.exports = {
46
+ paginationMeta,
47
+ sendPaginated
48
+ };
@@ -0,0 +1,17 @@
1
+ function sendSuccess(res, data = null, message = "Success", statusCode = 200) {
2
+ return res.status(statusCode).json({
3
+ success: true,
4
+ message,
5
+ data
6
+ });
7
+ }
8
+
9
+ function sendError(res, message = "Something went wrong", statusCode = 500, code = "INTERNAL_ERROR") {
10
+ return res.status(statusCode).json({
11
+ success: false,
12
+ message,
13
+ error: { code }
14
+ });
15
+ }
16
+
17
+ module.exports = { sendSuccess, sendError };