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.
Files changed (2) hide show
  1. package/README.md +351 -115
  2. 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 containing utilities for core Node.js modules, HTTP responses, Express middleware, database operations, and input validation.
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, filesystem operations, streams, and event management.
9
- - **HTTP Utilities:** Standardized JSON success and error responses.
10
- - **Express Middleware:** Request logger, async handler, authentication middleware, 404 handler, and error handler.
11
- - **Database Utilities:** Pagination, reusable CRUD service, and Prisma error handling.
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 above
17
- - Express 4 or 5 (optional, required only for Express utilities)
18
- - Prisma Client (optional, required only when using Prisma integration)
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 projects:
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 toolkit:
56
+ Import the required utilities from the package:
35
57
 
36
- ```js
58
+ ```javascript
37
59
  const toolkit = require("nodecraft-toolkit");
60
+
61
+ const { core, http, express, database, validation } = toolkit;
38
62
  ```
39
63
 
40
- ### 1. Core Utilities
64
+ The package is divided into five main modules.
41
65
 
42
- #### CLI Argument Parser
66
+ ## 1. Core Utilities
43
67
 
44
- ```js
45
- const { parseArgs } = toolkit.core;
68
+ Provides utilities for common Node.js operations.
46
69
 
47
- const result = parseArgs(["server", "--port", "5000"]);
70
+ ### CLI Argument Parser
48
71
 
49
- console.log(result);
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
- #### Filesystem
82
+ ### File System Helpers
53
83
 
54
- ```js
55
- const { writeFile, readFile } = toolkit.core;
84
+ Provides reusable asynchronous file operations.
56
85
 
57
- async function main() {
58
- await writeFile("demo.txt", "Hello NodeCraft!");
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
- main();
101
+ fileOperations();
65
102
  ```
66
103
 
67
- #### Event Manager
104
+ ### Event Manager
105
+
106
+ Provides a simple wrapper around Node.js EventEmitter.
68
107
 
69
- ```js
70
- const { createEventManager } = toolkit.core;
108
+ ```javascript
109
+ const { core } = require("nodecraft-toolkit");
71
110
 
72
- const events = createEventManager();
111
+ const events = new core.EventManager();
73
112
 
74
- events.subscribe("userCreated", (user) => {
113
+ events.on("userCreated", (user) => {
75
114
  console.log("New user:", user);
76
115
  });
77
116
 
78
- events.publish("userCreated", { id: 1, name: "Chhavi" });
117
+ events.emit("userCreated", {
118
+ id: 1,
119
+ name: "Chhavi"
120
+ });
79
121
  ```
80
122
 
81
- #### Streams
123
+ ### Stream Utilities
124
+
125
+ Provides helper functions for working with Node.js streams.
82
126
 
83
- ```js
84
- const { copyFile } = toolkit.core;
127
+ ```javascript
128
+ const { core } = require("nodecraft-toolkit");
85
129
 
86
- copyFile("source.txt", "destination.txt")
87
- .then(() => console.log("File copied"))
88
- .catch(console.error);
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
- ### 2. HTTP Utilities
140
+ ## 2. HTTP Utilities
92
141
 
93
- ```js
94
- const { http } = toolkit;
142
+ Provides helper functions for sending standardized HTTP responses.
95
143
 
96
- const server = require("node:http").createServer((req, res) => {
97
- http.successResponse(res, {
98
- message: "Welcome to NodeCraft"
99
- });
100
- });
144
+ ### Send JSON Response
145
+
146
+ ```javascript
147
+ const { http } = require("nodecraft-toolkit");
101
148
 
102
- server.listen(3000);
149
+ http.sendJSON(res, 200, {
150
+ message: "Success"
151
+ });
103
152
  ```
104
153
 
105
- Available functions:
154
+ ### Success Response
106
155
 
107
- - `sendJSON()`
108
- - `successResponse()`
109
- - `errorResponse()`
110
- - `expressSuccess()`
111
- - `expressError()`
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
- ### 3. Express Middleware
165
+ ### Error Response
114
166
 
115
- ```js
116
- const express = require("express");
117
- const toolkit = require("nodecraft-toolkit");
167
+ ```javascript
168
+ const response = http.errorResponse(
169
+ "Something went wrong",
170
+ 500
171
+ );
172
+
173
+ console.log(response);
174
+ ```
118
175
 
119
- const app = express();
176
+ ### Express Response Helpers
120
177
 
121
- app.use(express.json());
122
- app.use(toolkit.express.requestLogger());
178
+ ```javascript
179
+ const { http } = require("nodecraft-toolkit");
123
180
 
124
- app.get("/", (req, res) => {
125
- res.json({ message: "Welcome" });
181
+ app.get("/users", (req, res) => {
182
+ http.expressSuccess(res, "Users fetched successfully", []);
126
183
  });
184
+ ```
127
185
 
128
- app.use(toolkit.express.notFound);
129
- app.use(toolkit.express.errorHandler);
186
+ ## 3. Express Middleware
130
187
 
131
- app.listen(3000);
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
- Available middleware:
200
+ ### Async Handler
135
201
 
136
- - `requestLogger()`
137
- - `asyncHandler()`
138
- - `authMiddleware()`
139
- - `notFound`
140
- - `errorHandler`
202
+ Wraps asynchronous route handlers and forwards errors to Express error middleware.
141
203
 
142
- ### 4. Database Utilities
204
+ ```javascript
205
+ const { express } = require("nodecraft-toolkit");
143
206
 
144
- #### Pagination
207
+ app.get(
208
+ "/users",
209
+ express.asyncHandler(async (req, res) => {
210
+ const users = await getUsers();
145
211
 
146
- ```js
147
- const { database } = toolkit;
212
+ res.json(users);
213
+ })
214
+ );
215
+ ```
148
216
 
149
- const pagination = database.getPagination({
150
- page: 2,
151
- limit: 10
152
- });
217
+ ### Authentication Middleware
153
218
 
154
- console.log(pagination);
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
- #### CRUD Service with Prisma
237
+ ### Error Handler
158
238
 
159
- ```js
160
- const { PrismaClient } = require("@prisma/client");
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 prisma = new PrismaClient();
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 main() {
168
- const users = await userService.getAll({
169
- page: 1,
170
- limit: 10
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
- console.log(users);
296
+ await userService.delete(1);
174
297
  }
298
+ ```
175
299
 
176
- main().finally(() => prisma.$disconnect());
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
- The CRUD service expects a Prisma-style model delegate.
318
+ ## 5. Validation Utilities
180
319
 
181
- ### 5. Validation
320
+ Provides helpers for validating input data and environment variables.
182
321
 
183
- #### Input Validation
322
+ ### Input Validation
184
323
 
185
- ```js
186
- const { validation } = toolkit;
324
+ ```javascript
325
+ const { validation } = require("nodecraft-toolkit");
187
326
 
188
327
  const result = validation.validateInput(
189
- { name: "Chhavi", age: 20 },
328
+ { name: "Chhavi", email: "chhavi@example.com" },
190
329
  {
191
- name: {
192
- required: true,
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
- #### Environment Validation
338
+ ### Environment Variable Validation
208
339
 
209
- ```js
210
- const { validation } = toolkit;
340
+ ```javascript
341
+ const { validation } = require("nodecraft-toolkit");
211
342
 
212
- validation.validateEnv(["PORT", "DATABASE_URL"]);
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
- Clone the repository and install its development dependencies:
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
- │ └── validation/
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
- └── README.md
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nodecraft-toolkit",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "A reusable Node.js backend development toolkit",
5
5
  "main": "index.js",
6
6
  "type": "commonjs",
@@ -34,4 +34,4 @@
34
34
  "optional": true
35
35
  }
36
36
  }
37
- }
37
+ }