nodecraft-toolkit 1.0.0 → 1.0.1
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 +351 -115
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,245 +1,481 @@
|
|
|
1
|
-
|
|
2
1
|
# NodeCraft Toolkit
|
|
3
2
|
|
|
4
|
-
A reusable Node.js backend development toolkit
|
|
3
|
+
A reusable Node.js backend development toolkit that provides commonly used utilities for core Node.js operations, HTTP responses, Express middleware, database operations, and input validation.
|
|
4
|
+
|
|
5
|
+
NodeCraft Toolkit helps developers avoid rewriting common backend code by providing simple, reusable, and organized utility functions.
|
|
5
6
|
|
|
6
7
|
## Features
|
|
7
8
|
|
|
8
|
-
- **Core Utilities:** CLI argument parsing,
|
|
9
|
-
- **HTTP
|
|
10
|
-
- **Express Middleware:** Request
|
|
11
|
-
- **Database Utilities:** Pagination, reusable CRUD service, and
|
|
9
|
+
- **Core Utilities:** CLI argument parsing, file system helpers, streams, and event management.
|
|
10
|
+
- **HTTP Helpers:** Standardized JSON success and error responses.
|
|
11
|
+
- **Express Middleware:** Request logging, async error handling, authentication, and error handling.
|
|
12
|
+
- **Database Utilities:** Pagination, reusable CRUD service, and database error handling.
|
|
12
13
|
- **Validation:** Input validation and environment variable validation.
|
|
14
|
+
- **Easy Integration:** Modular exports and simple CommonJS syntax.
|
|
13
15
|
|
|
14
16
|
## Requirements
|
|
15
17
|
|
|
16
|
-
- Node.js 18 or
|
|
17
|
-
-
|
|
18
|
-
-
|
|
18
|
+
- Node.js 18 or higher
|
|
19
|
+
- npm
|
|
20
|
+
- Express (optional, required only for Express-related functionality)
|
|
21
|
+
- Prisma (optional, required only for the Prisma example)
|
|
19
22
|
|
|
20
23
|
## Installation
|
|
21
24
|
|
|
25
|
+
Install the package using npm:
|
|
26
|
+
|
|
22
27
|
```bash
|
|
23
28
|
npm install nodecraft-toolkit
|
|
24
29
|
```
|
|
25
30
|
|
|
26
|
-
For Express
|
|
31
|
+
For Express-related functionality, install Express:
|
|
27
32
|
|
|
28
33
|
```bash
|
|
29
34
|
npm install express
|
|
30
35
|
```
|
|
31
36
|
|
|
37
|
+
For the Prisma example, install Prisma and Prisma Client:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install @prisma/client
|
|
41
|
+
npm install -D prisma
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Clone the Repository
|
|
45
|
+
|
|
46
|
+
To access the source code and examples:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
git clone https://github.com/Chhavi-2407/nodecraft-toolkit.git
|
|
50
|
+
cd nodecraft-toolkit
|
|
51
|
+
npm install
|
|
52
|
+
```
|
|
53
|
+
|
|
32
54
|
## Usage
|
|
33
55
|
|
|
34
|
-
Import the
|
|
56
|
+
Import the required utilities from the package:
|
|
35
57
|
|
|
36
|
-
```
|
|
58
|
+
```javascript
|
|
37
59
|
const toolkit = require("nodecraft-toolkit");
|
|
60
|
+
|
|
61
|
+
const { core, http, express, database, validation } = toolkit;
|
|
38
62
|
```
|
|
39
63
|
|
|
40
|
-
|
|
64
|
+
The package is divided into five main modules.
|
|
41
65
|
|
|
42
|
-
|
|
66
|
+
## 1. Core Utilities
|
|
43
67
|
|
|
44
|
-
|
|
45
|
-
const { parseArgs } = toolkit.core;
|
|
68
|
+
Provides utilities for common Node.js operations.
|
|
46
69
|
|
|
47
|
-
|
|
70
|
+
### CLI Argument Parser
|
|
48
71
|
|
|
49
|
-
|
|
72
|
+
Parse command-line arguments into a structured object.
|
|
73
|
+
|
|
74
|
+
```javascript
|
|
75
|
+
const { core } = require("nodecraft-toolkit");
|
|
76
|
+
|
|
77
|
+
const args = core.parseArgs(process.argv.slice(2));
|
|
78
|
+
|
|
79
|
+
console.log(args);
|
|
50
80
|
```
|
|
51
81
|
|
|
52
|
-
|
|
82
|
+
### File System Helpers
|
|
53
83
|
|
|
54
|
-
|
|
55
|
-
const { writeFile, readFile } = toolkit.core;
|
|
84
|
+
Provides reusable asynchronous file operations.
|
|
56
85
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
const content = await readFile("demo.txt");
|
|
86
|
+
```javascript
|
|
87
|
+
const { core } = require("nodecraft-toolkit");
|
|
60
88
|
|
|
89
|
+
async function fileOperations() {
|
|
90
|
+
await core.writeFile("demo.txt", "Hello NodeCraft!");
|
|
91
|
+
|
|
92
|
+
const content = await core.readFile("demo.txt");
|
|
61
93
|
console.log(content);
|
|
94
|
+
|
|
95
|
+
await core.appendFile("demo.txt", "\nNew content");
|
|
96
|
+
|
|
97
|
+
const exists = await core.fileExists("demo.txt");
|
|
98
|
+
console.log(exists);
|
|
62
99
|
}
|
|
63
100
|
|
|
64
|
-
|
|
101
|
+
fileOperations();
|
|
65
102
|
```
|
|
66
103
|
|
|
67
|
-
|
|
104
|
+
### Event Manager
|
|
105
|
+
|
|
106
|
+
Provides a simple wrapper around Node.js EventEmitter.
|
|
68
107
|
|
|
69
|
-
```
|
|
70
|
-
const {
|
|
108
|
+
```javascript
|
|
109
|
+
const { core } = require("nodecraft-toolkit");
|
|
71
110
|
|
|
72
|
-
const events =
|
|
111
|
+
const events = new core.EventManager();
|
|
73
112
|
|
|
74
|
-
events.
|
|
113
|
+
events.on("userCreated", (user) => {
|
|
75
114
|
console.log("New user:", user);
|
|
76
115
|
});
|
|
77
116
|
|
|
78
|
-
events.
|
|
117
|
+
events.emit("userCreated", {
|
|
118
|
+
id: 1,
|
|
119
|
+
name: "Chhavi"
|
|
120
|
+
});
|
|
79
121
|
```
|
|
80
122
|
|
|
81
|
-
|
|
123
|
+
### Stream Utilities
|
|
124
|
+
|
|
125
|
+
Provides helper functions for working with Node.js streams.
|
|
82
126
|
|
|
83
|
-
```
|
|
84
|
-
const {
|
|
127
|
+
```javascript
|
|
128
|
+
const { core } = require("nodecraft-toolkit");
|
|
85
129
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
.
|
|
130
|
+
async function streamOperations() {
|
|
131
|
+
const readStream = core.createReadStream("input.txt");
|
|
132
|
+
const writeStream = core.createWriteStream("output.txt");
|
|
133
|
+
|
|
134
|
+
await core.pipeStream(readStream, writeStream);
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
streamOperations();
|
|
89
138
|
```
|
|
90
139
|
|
|
91
|
-
|
|
140
|
+
## 2. HTTP Utilities
|
|
92
141
|
|
|
93
|
-
|
|
94
|
-
const { http } = toolkit;
|
|
142
|
+
Provides helper functions for sending standardized HTTP responses.
|
|
95
143
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
});
|
|
144
|
+
### Send JSON Response
|
|
145
|
+
|
|
146
|
+
```javascript
|
|
147
|
+
const { http } = require("nodecraft-toolkit");
|
|
101
148
|
|
|
102
|
-
|
|
149
|
+
http.sendJSON(res, 200, {
|
|
150
|
+
message: "Success"
|
|
151
|
+
});
|
|
103
152
|
```
|
|
104
153
|
|
|
105
|
-
|
|
154
|
+
### Success Response
|
|
106
155
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
156
|
+
```javascript
|
|
157
|
+
const response = http.successResponse(
|
|
158
|
+
"User fetched successfully",
|
|
159
|
+
{ id: 1, name: "Chhavi" }
|
|
160
|
+
);
|
|
161
|
+
|
|
162
|
+
console.log(response);
|
|
163
|
+
```
|
|
112
164
|
|
|
113
|
-
###
|
|
165
|
+
### Error Response
|
|
114
166
|
|
|
115
|
-
```
|
|
116
|
-
const
|
|
117
|
-
|
|
167
|
+
```javascript
|
|
168
|
+
const response = http.errorResponse(
|
|
169
|
+
"Something went wrong",
|
|
170
|
+
500
|
|
171
|
+
);
|
|
172
|
+
|
|
173
|
+
console.log(response);
|
|
174
|
+
```
|
|
118
175
|
|
|
119
|
-
|
|
176
|
+
### Express Response Helpers
|
|
120
177
|
|
|
121
|
-
|
|
122
|
-
|
|
178
|
+
```javascript
|
|
179
|
+
const { http } = require("nodecraft-toolkit");
|
|
123
180
|
|
|
124
|
-
app.get("/", (req, res) => {
|
|
125
|
-
|
|
181
|
+
app.get("/users", (req, res) => {
|
|
182
|
+
http.expressSuccess(res, "Users fetched successfully", []);
|
|
126
183
|
});
|
|
184
|
+
```
|
|
127
185
|
|
|
128
|
-
|
|
129
|
-
app.use(toolkit.express.errorHandler);
|
|
186
|
+
## 3. Express Middleware
|
|
130
187
|
|
|
131
|
-
|
|
188
|
+
Provides reusable middleware functions for Express applications.
|
|
189
|
+
|
|
190
|
+
### Request Logger
|
|
191
|
+
|
|
192
|
+
Logs incoming HTTP requests.
|
|
193
|
+
|
|
194
|
+
```javascript
|
|
195
|
+
const { express } = require("nodecraft-toolkit");
|
|
196
|
+
|
|
197
|
+
app.use(express.requestLogger);
|
|
132
198
|
```
|
|
133
199
|
|
|
134
|
-
|
|
200
|
+
### Async Handler
|
|
135
201
|
|
|
136
|
-
|
|
137
|
-
- `asyncHandler()`
|
|
138
|
-
- `authMiddleware()`
|
|
139
|
-
- `notFound`
|
|
140
|
-
- `errorHandler`
|
|
202
|
+
Wraps asynchronous route handlers and forwards errors to Express error middleware.
|
|
141
203
|
|
|
142
|
-
|
|
204
|
+
```javascript
|
|
205
|
+
const { express } = require("nodecraft-toolkit");
|
|
143
206
|
|
|
144
|
-
|
|
207
|
+
app.get(
|
|
208
|
+
"/users",
|
|
209
|
+
express.asyncHandler(async (req, res) => {
|
|
210
|
+
const users = await getUsers();
|
|
145
211
|
|
|
146
|
-
|
|
147
|
-
|
|
212
|
+
res.json(users);
|
|
213
|
+
})
|
|
214
|
+
);
|
|
215
|
+
```
|
|
148
216
|
|
|
149
|
-
|
|
150
|
-
page: 2,
|
|
151
|
-
limit: 10
|
|
152
|
-
});
|
|
217
|
+
### Authentication Middleware
|
|
153
218
|
|
|
154
|
-
|
|
219
|
+
Checks whether a request contains a valid authentication token.
|
|
220
|
+
|
|
221
|
+
```javascript
|
|
222
|
+
const { express } = require("nodecraft-toolkit");
|
|
223
|
+
|
|
224
|
+
app.use(express.authMiddleware((req) => {
|
|
225
|
+
return req.headers.authorization === "Bearer demo-token";
|
|
226
|
+
}));
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
### Not Found Middleware
|
|
230
|
+
|
|
231
|
+
Handles requests to routes that do not exist.
|
|
232
|
+
|
|
233
|
+
```javascript
|
|
234
|
+
app.use(express.notFound);
|
|
155
235
|
```
|
|
156
236
|
|
|
157
|
-
|
|
237
|
+
### Error Handler
|
|
158
238
|
|
|
159
|
-
|
|
160
|
-
|
|
239
|
+
Handles errors forwarded through Express middleware.
|
|
240
|
+
|
|
241
|
+
```javascript
|
|
242
|
+
app.use(express.errorHandler);
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
**Important:** Register `notFound` and `errorHandler` after your application routes. The error handler should be the last middleware.
|
|
246
|
+
|
|
247
|
+
## 4. Database Utilities
|
|
248
|
+
|
|
249
|
+
Provides reusable helpers for pagination, CRUD operations, and database error handling.
|
|
250
|
+
|
|
251
|
+
### Pagination
|
|
252
|
+
|
|
253
|
+
Calculate pagination values from page number and page size.
|
|
254
|
+
|
|
255
|
+
```javascript
|
|
161
256
|
const { database } = require("nodecraft-toolkit");
|
|
162
257
|
|
|
163
|
-
const
|
|
258
|
+
const pagination = database.getPagination(2, 10);
|
|
259
|
+
|
|
260
|
+
console.log(pagination);
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### Pagination Metadata
|
|
264
|
+
|
|
265
|
+
Generate metadata for paginated results.
|
|
266
|
+
|
|
267
|
+
```javascript
|
|
268
|
+
const meta = database.getPaginationMeta(100, 2, 10);
|
|
269
|
+
|
|
270
|
+
console.log(meta);
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### CRUD Service
|
|
274
|
+
|
|
275
|
+
Create a reusable CRUD service using a database model.
|
|
276
|
+
|
|
277
|
+
```javascript
|
|
278
|
+
const { database } = require("nodecraft-toolkit");
|
|
164
279
|
|
|
165
280
|
const userService = database.createCrudService(prisma.user);
|
|
166
281
|
|
|
167
|
-
async function
|
|
168
|
-
const users = await userService.
|
|
169
|
-
|
|
170
|
-
|
|
282
|
+
async function operations() {
|
|
283
|
+
const users = await userService.findAll();
|
|
284
|
+
|
|
285
|
+
const user = await userService.findById(1);
|
|
286
|
+
|
|
287
|
+
const newUser = await userService.create({
|
|
288
|
+
name: "Chhavi",
|
|
289
|
+
email: "chhavi@example.com"
|
|
290
|
+
});
|
|
291
|
+
|
|
292
|
+
await userService.update(1, {
|
|
293
|
+
name: "Updated Name"
|
|
171
294
|
});
|
|
172
295
|
|
|
173
|
-
|
|
296
|
+
await userService.delete(1);
|
|
174
297
|
}
|
|
298
|
+
```
|
|
175
299
|
|
|
176
|
-
|
|
300
|
+
This example assumes that Prisma Client has been initialized and a compatible `user` model exists in your Prisma schema.
|
|
301
|
+
|
|
302
|
+
### Database Error Handling
|
|
303
|
+
|
|
304
|
+
Convert common database errors into readable application errors.
|
|
305
|
+
|
|
306
|
+
```javascript
|
|
307
|
+
const { database } = require("nodecraft-toolkit");
|
|
308
|
+
|
|
309
|
+
try {
|
|
310
|
+
// Database operation
|
|
311
|
+
} catch (error) {
|
|
312
|
+
const handledError = database.handleDatabaseError(error);
|
|
313
|
+
|
|
314
|
+
console.log(handledError);
|
|
315
|
+
}
|
|
177
316
|
```
|
|
178
317
|
|
|
179
|
-
|
|
318
|
+
## 5. Validation Utilities
|
|
180
319
|
|
|
181
|
-
|
|
320
|
+
Provides helpers for validating input data and environment variables.
|
|
182
321
|
|
|
183
|
-
|
|
322
|
+
### Input Validation
|
|
184
323
|
|
|
185
|
-
```
|
|
186
|
-
const { validation } = toolkit;
|
|
324
|
+
```javascript
|
|
325
|
+
const { validation } = require("nodecraft-toolkit");
|
|
187
326
|
|
|
188
327
|
const result = validation.validateInput(
|
|
189
|
-
{ name: "Chhavi",
|
|
328
|
+
{ name: "Chhavi", email: "chhavi@example.com" },
|
|
190
329
|
{
|
|
191
|
-
name: {
|
|
192
|
-
|
|
193
|
-
type: "string",
|
|
194
|
-
minLength: 3
|
|
195
|
-
},
|
|
196
|
-
age: {
|
|
197
|
-
required: true,
|
|
198
|
-
type: "number",
|
|
199
|
-
min: 18
|
|
200
|
-
}
|
|
330
|
+
name: { required: true },
|
|
331
|
+
email: { required: true, type: "email" }
|
|
201
332
|
}
|
|
202
333
|
);
|
|
203
334
|
|
|
204
335
|
console.log(result);
|
|
205
336
|
```
|
|
206
337
|
|
|
207
|
-
|
|
338
|
+
### Environment Variable Validation
|
|
208
339
|
|
|
209
|
-
```
|
|
210
|
-
const { validation } = toolkit;
|
|
340
|
+
```javascript
|
|
341
|
+
const { validation } = require("nodecraft-toolkit");
|
|
211
342
|
|
|
212
|
-
validation.validateEnv(
|
|
343
|
+
const env = validation.validateEnv(
|
|
344
|
+
["PORT", "DATABASE_URL"]
|
|
345
|
+
);
|
|
346
|
+
|
|
347
|
+
console.log(env);
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
## Running Examples
|
|
351
|
+
|
|
352
|
+
The repository includes example applications demonstrating how to use the toolkit.
|
|
353
|
+
|
|
354
|
+
### Basic Node.js Server
|
|
355
|
+
|
|
356
|
+
```bash
|
|
357
|
+
node examples/basic-node-server.js
|
|
213
358
|
```
|
|
214
359
|
|
|
360
|
+
### Express Application
|
|
361
|
+
|
|
362
|
+
```bash
|
|
363
|
+
node examples/express-app.js
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
### HTTP Demo
|
|
367
|
+
|
|
368
|
+
```bash
|
|
369
|
+
node examples/http-demo.js
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
### Prisma Demo
|
|
373
|
+
|
|
374
|
+
```bash
|
|
375
|
+
node examples/prisma-demo.js
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
The Prisma demo requires a configured database connection and a generated Prisma Client.
|
|
379
|
+
|
|
215
380
|
## Running Tests
|
|
216
381
|
|
|
217
|
-
|
|
382
|
+
Run the test suite using:
|
|
218
383
|
|
|
219
384
|
```bash
|
|
220
|
-
npm install
|
|
221
385
|
npm test
|
|
222
386
|
```
|
|
223
387
|
|
|
224
|
-
The project uses Node.js built-in test runner.
|
|
388
|
+
The project uses Node.js's built-in test runner.
|
|
389
|
+
|
|
390
|
+
Tests cover:
|
|
391
|
+
|
|
392
|
+
- Core utilities
|
|
393
|
+
- HTTP helpers
|
|
394
|
+
- Express middleware
|
|
395
|
+
- Express integration
|
|
396
|
+
- Database utilities
|
|
397
|
+
- Validation functions
|
|
225
398
|
|
|
226
399
|
## Project Structure
|
|
227
400
|
|
|
228
401
|
```text
|
|
229
402
|
nodecraft-toolkit/
|
|
403
|
+
│
|
|
230
404
|
├── src/
|
|
231
405
|
│ ├── core/
|
|
406
|
+
│ │ ├── cli.js
|
|
407
|
+
│ │ ├── filesystem.js
|
|
408
|
+
│ │ ├── streams.js
|
|
409
|
+
│ │ └── events.js
|
|
410
|
+
│ │
|
|
232
411
|
│ ├── http/
|
|
412
|
+
│ │ └── response.js
|
|
413
|
+
│ │
|
|
233
414
|
│ ├── express/
|
|
415
|
+
│ │ ├── logger.js
|
|
416
|
+
│ │ ├── asyncHandler.js
|
|
417
|
+
│ │ ├── errorHandler.js
|
|
418
|
+
│ │ ├── notFound.js
|
|
419
|
+
│ │ └── authMiddleware.js
|
|
420
|
+
│ │
|
|
234
421
|
│ ├── database/
|
|
235
|
-
│
|
|
422
|
+
│ │ ├── pagination.js
|
|
423
|
+
│ │ ├── crudService.js
|
|
424
|
+
│ │ └── databaseError.js
|
|
425
|
+
│ │
|
|
426
|
+
│ ├── validation/
|
|
427
|
+
│ │ ├── validateInput.js
|
|
428
|
+
│ │ └── envValidator.js
|
|
429
|
+
│ │
|
|
430
|
+
│ └── index.js
|
|
431
|
+
│
|
|
236
432
|
├── test/
|
|
433
|
+
│ ├── core/
|
|
434
|
+
│ ├── http/
|
|
435
|
+
│ ├── express/
|
|
436
|
+
│ ├── database/
|
|
437
|
+
│ └── validation/
|
|
438
|
+
│
|
|
237
439
|
├── examples/
|
|
440
|
+
│ ├── basic-node-server.js
|
|
441
|
+
│ ├── express-app.js
|
|
442
|
+
│ ├── http-demo.js
|
|
443
|
+
│ └── prisma-demo.js
|
|
444
|
+
│
|
|
238
445
|
├── index.js
|
|
239
446
|
├── package.json
|
|
240
|
-
|
|
447
|
+
├── package-lock.json
|
|
448
|
+
├── README.md
|
|
449
|
+
├── LICENSE
|
|
450
|
+
└── .gitignore
|
|
241
451
|
```
|
|
242
452
|
|
|
453
|
+
## Technologies Used
|
|
454
|
+
|
|
455
|
+
- Node.js
|
|
456
|
+
- JavaScript
|
|
457
|
+
- Express.js
|
|
458
|
+
- Prisma ORM (for the example integration)
|
|
459
|
+
- npm
|
|
460
|
+
- Node.js Built-in Test Runner
|
|
461
|
+
|
|
462
|
+
## Package Information
|
|
463
|
+
|
|
464
|
+
- **Package Name:** nodecraft-toolkit
|
|
465
|
+
- **Current Published Version:** 1.0.0
|
|
466
|
+
- **Author:** Chhavi
|
|
467
|
+
- **License:** MIT
|
|
468
|
+
- **Node.js Requirement:** >=18
|
|
469
|
+
|
|
470
|
+
## Links
|
|
471
|
+
|
|
472
|
+
- **npm Package:** https://www.npmjs.com/package/nodecraft-toolkit
|
|
473
|
+
- **GitHub Repository:** https://github.com/Chhavi-2407/nodecraft-toolkit
|
|
474
|
+
|
|
243
475
|
## License
|
|
244
476
|
|
|
245
|
-
MIT
|
|
477
|
+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|
|
478
|
+
|
|
479
|
+
---
|
|
480
|
+
|
|
481
|
+
Made with Node.js by **Chhavi**.
|
package/package.json
CHANGED