karos 1.0.0 → 1.0.3
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 +127 -63
- package/package.json +14 -6
package/README.md
CHANGED
|
@@ -1,103 +1,167 @@
|
|
|
1
|
-
|
|
2
|
-
=====
|
|
1
|
+
# Karos
|
|
3
2
|
|
|
4
3
|
**Opinionated, minimal API response & error standardization for Express.**
|
|
5
4
|
|
|
6
|
-
Karos enforces predictable JSON response
|
|
5
|
+
Karos enforces a single, predictable JSON response contract across your entire Node.js API — without adding business logic, configuration, or framework lock-in.
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 🚫 The Problem
|
|
10
10
|
|
|
11
11
|
In most Express backends:
|
|
12
|
+
- ❌ Every route formats responses differently
|
|
13
|
+
- ❌ Errors are sometimes strings, sometimes objects
|
|
14
|
+
- ❌ Status codes are inconsistent
|
|
15
|
+
- ❌ Frontend logic becomes fragile and conditional-heavy
|
|
16
|
+
- ❌ Teams rewrite the same response boilerplate in every project
|
|
17
|
+
|
|
18
|
+
**There is no enforced backend–frontend contract.**
|
|
19
|
+
|
|
20
|
+
## ✅ The Solution
|
|
21
|
+
|
|
22
|
+
Karos fixes exactly this problem — nothing more, nothing less. It enforces **one response contract** for your entire API.
|
|
23
|
+
|
|
24
|
+
### Success Response
|
|
25
|
+
```json
|
|
26
|
+
{
|
|
27
|
+
"success": true,
|
|
28
|
+
"data": {
|
|
29
|
+
"id": 123,
|
|
30
|
+
"name": "Alice"
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Error Response
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"success": false,
|
|
39
|
+
"error": {
|
|
40
|
+
"code": "NOT_FOUND",
|
|
41
|
+
"message": "User not found"
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
12
45
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
* Errors are sometimes strings, sometimes objects
|
|
16
|
-
|
|
17
|
-
* Status codes are inconsistent
|
|
18
|
-
|
|
19
|
-
* Frontend logic becomes fragile and full of conditionals
|
|
20
|
-
|
|
21
|
-
* Teams re-implement the same response boilerplate in every project
|
|
22
|
-
|
|
46
|
+
No exceptions. No special cases.
|
|
23
47
|
|
|
24
|
-
|
|
48
|
+
---
|
|
25
49
|
|
|
26
|
-
|
|
27
|
-
-------------------
|
|
50
|
+
## 📦 Installation
|
|
28
51
|
|
|
29
|
-
|
|
52
|
+
```bash
|
|
53
|
+
npm install karos
|
|
54
|
+
```
|
|
30
55
|
|
|
31
|
-
|
|
32
|
-
-------
|
|
56
|
+
---
|
|
33
57
|
|
|
34
|
-
|
|
58
|
+
## 🚀 Quick Start (60 seconds)
|
|
35
59
|
|
|
36
|
-
|
|
37
|
-
-----
|
|
60
|
+
Karos replaces manual `try/catch` blocks and inconsistent response formatting.
|
|
38
61
|
|
|
39
|
-
|
|
62
|
+
### 1. Basic Setup
|
|
40
63
|
|
|
41
|
-
|
|
64
|
+
```js
|
|
65
|
+
const express = require('express');
|
|
66
|
+
const { ok, notFoundError, errorHandler } = require('karos');
|
|
67
|
+
|
|
68
|
+
const app = express();
|
|
69
|
+
app.use(express.json());
|
|
70
|
+
|
|
71
|
+
// --- Your Routes ---
|
|
72
|
+
|
|
73
|
+
app.get('/users/:id', async (req, res) => {
|
|
74
|
+
const user = await db.findUser(req.params.id);
|
|
75
|
+
|
|
76
|
+
if (!user) {
|
|
77
|
+
// Throws automatically -> Middleware catches it
|
|
78
|
+
notFoundError('User not found');
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// Returns standardized 200 OK
|
|
82
|
+
ok(res, user);
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
// --- ONE middleware catches everything ---
|
|
86
|
+
// Must be placed after all routes
|
|
87
|
+
app.use(errorHandler);
|
|
42
88
|
|
|
43
|
-
|
|
44
|
-
|
|
89
|
+
app.listen(3000, () => console.log('Server running on port 3000'));
|
|
90
|
+
```
|
|
45
91
|
|
|
46
|
-
|
|
92
|
+
**Zero try/catch needed.** If your DB crashes, Karos catches it and returns a clean 500 `INTERNAL_ERROR`.
|
|
47
93
|
|
|
48
|
-
|
|
94
|
+
---
|
|
49
95
|
|
|
50
|
-
|
|
96
|
+
## 📚 Core API
|
|
51
97
|
|
|
52
|
-
|
|
53
|
-
--------
|
|
98
|
+
### `ok(res, data, message?, meta?)`
|
|
54
99
|
|
|
55
|
-
|
|
100
|
+
Formats a successful response.
|
|
56
101
|
|
|
57
|
-
|
|
102
|
+
| Param | Type | Required | Description |
|
|
103
|
+
| :--- | :--- | :--- | :--- |
|
|
104
|
+
| `res` | `Response` | **Yes** | Express Response object |
|
|
105
|
+
| `data` | `any` | **Yes** | The payload (object, array, string) |
|
|
106
|
+
| `message` | `string` | No | Optional success message |
|
|
107
|
+
| `meta` | `object` | No | Optional metadata (e.g., pagination info) |
|
|
58
108
|
|
|
59
|
-
**
|
|
109
|
+
**Example:**
|
|
110
|
+
```js
|
|
111
|
+
ok(res, user);
|
|
112
|
+
ok(res, user, 'User fetched successfully');
|
|
113
|
+
```
|
|
60
114
|
|
|
61
|
-
|
|
115
|
+
---
|
|
62
116
|
|
|
63
|
-
|
|
117
|
+
### Error Helpers
|
|
64
118
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
* Formats unknown errors as INTERNAL\_ERROR
|
|
68
|
-
|
|
69
|
-
* Preserves correct HTTP status codes
|
|
70
|
-
|
|
119
|
+
Prebuilt helpers that throw standardized errors. These stop execution immediately, so you don't need `return`.
|
|
71
120
|
|
|
72
|
-
|
|
121
|
+
| Helper Function | HTTP Status | Error Code |
|
|
122
|
+
| :--- | :--- | :--- |
|
|
123
|
+
| `notFoundError(msg)` | **404** | `NOT_FOUND` |
|
|
124
|
+
| `validationError(msg)` | **400** | `VALIDATION_FAILED` |
|
|
125
|
+
| `unauthorizedError(msg)` | **401** | `UNAUTHORIZED` |
|
|
126
|
+
| `forbiddenError(msg)` | **403** | `FORBIDDEN` |
|
|
127
|
+
| `conflictError(msg)` | **409** | `CONFLICT` |
|
|
128
|
+
| `internalError(msg)` | **500** | `INTERNAL_ERROR` |
|
|
73
129
|
|
|
74
|
-
|
|
75
|
-
|
|
130
|
+
**Example:**
|
|
131
|
+
```js
|
|
132
|
+
if (emailInvalid) validationError('Invalid email format');
|
|
133
|
+
if (!isAdmin) forbiddenError('Admin access required');
|
|
134
|
+
```
|
|
76
135
|
|
|
77
|
-
|
|
136
|
+
---
|
|
78
137
|
|
|
79
|
-
|
|
138
|
+
### `errorHandler`
|
|
80
139
|
|
|
81
|
-
|
|
82
|
-
|
|
140
|
+
Express middleware that:
|
|
141
|
+
1. Catches all thrown Karos errors.
|
|
142
|
+
2. Catches unexpected crashes (DB down, undefined variables).
|
|
143
|
+
3. Formats unknown errors as `INTERNAL_ERROR` (500).
|
|
83
144
|
|
|
84
|
-
|
|
145
|
+
```js
|
|
146
|
+
// Add this as the very last middleware in your app
|
|
147
|
+
app.use(errorHandler);
|
|
148
|
+
```
|
|
85
149
|
|
|
86
|
-
|
|
150
|
+
---
|
|
87
151
|
|
|
88
|
-
|
|
89
|
-
----------------------------------
|
|
152
|
+
## TypeScript Support
|
|
90
153
|
|
|
91
|
-
|
|
154
|
+
Karos is written in TypeScript and includes full type definitions out of the box.
|
|
92
155
|
|
|
93
|
-
|
|
156
|
+
- ✅ Full type safety
|
|
157
|
+
- ✅ Autocomplete-safe error codes
|
|
94
158
|
|
|
95
|
-
|
|
96
|
-
|
|
159
|
+
```ts
|
|
160
|
+
import { ok, ErrorCode } from 'karos';
|
|
161
|
+
```
|
|
97
162
|
|
|
98
|
-
|
|
163
|
+
---
|
|
99
164
|
|
|
100
|
-
License
|
|
101
|
-
-------
|
|
165
|
+
## License
|
|
102
166
|
|
|
103
|
-
MIT
|
|
167
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,20 +1,28 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "karos",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.3",
|
|
4
4
|
"description": "Opinionated API response and error handling for Node.js",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
7
|
-
"files": [
|
|
7
|
+
"files": [
|
|
8
|
+
"dist"
|
|
9
|
+
],
|
|
8
10
|
"scripts": {
|
|
9
11
|
"build": "tsup src/index.ts --format cjs --dts",
|
|
10
12
|
"dev": "tsup src/index.ts --format cjs --watch --dts",
|
|
11
13
|
"test": "echo \"Error: no test specified\" && exit 1"
|
|
12
14
|
},
|
|
13
|
-
"keywords": [
|
|
14
|
-
|
|
15
|
+
"keywords": [
|
|
16
|
+
"api",
|
|
17
|
+
"express",
|
|
18
|
+
"error-handling",
|
|
19
|
+
"node",
|
|
20
|
+
"backend"
|
|
21
|
+
],
|
|
22
|
+
"author": "Krishna Shrivastava",
|
|
15
23
|
"license": "MIT",
|
|
16
|
-
"repository": "https://github.com/Krishna-Shrivastava-1/Karos",
|
|
17
|
-
"bugs": "https://github.com/Krishna-Shrivastava-1/Karos/issues",
|
|
24
|
+
"repository": "https://github.com/Krishna-Shrivastava-1/Karos",
|
|
25
|
+
"bugs": "https://github.com/Krishna-Shrivastava-1/Karos/issues",
|
|
18
26
|
"type": "commonjs",
|
|
19
27
|
"devDependencies": {
|
|
20
28
|
"@types/express": "^5.0.6",
|