@forinda/kickjs 0.2.0 → 1.5.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/package.json +50 -79
- package/README.md +0 -560
- package/dist/cli.js +0 -1324
- package/dist/cli.js.map +0 -1
- package/dist/index.d.ts +0 -613
- package/dist/index.js +0 -883
- package/dist/index.js.map +0 -1
package/package.json
CHANGED
|
@@ -1,96 +1,67 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@forinda/kickjs",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "Express
|
|
5
|
-
"main": "dist/index.js",
|
|
6
|
-
"types": "dist/index.d.ts",
|
|
7
|
-
"exports": {
|
|
8
|
-
".": {
|
|
9
|
-
"require": "./dist/index.js",
|
|
10
|
-
"types": "./dist/index.d.ts"
|
|
11
|
-
}
|
|
12
|
-
},
|
|
13
|
-
"files": [
|
|
14
|
-
"dist",
|
|
15
|
-
"LICENSE",
|
|
16
|
-
"README.md"
|
|
17
|
-
],
|
|
18
|
-
"bin": {
|
|
19
|
-
"kick": "dist/cli.js"
|
|
20
|
-
},
|
|
21
|
-
"scripts": {
|
|
22
|
-
"clean": "rm -rf dist",
|
|
23
|
-
"dev": "tsup --watch src/index.ts",
|
|
24
|
-
"check": "tsc --noEmit",
|
|
25
|
-
"build": "tsup",
|
|
26
|
-
"start": "node dist/index.js",
|
|
27
|
-
"prepublishOnly": "npm run build && npm run check && npm test",
|
|
28
|
-
"test": "vitest run",
|
|
29
|
-
"test:watch": "vitest",
|
|
30
|
-
"prepare": "husky",
|
|
31
|
-
"prerelease": "npm run clean && npm run build && npm run check && npm test",
|
|
32
|
-
"release:patch": "node scripts/release.js patch",
|
|
33
|
-
"release:minor": "node scripts/release.js minor",
|
|
34
|
-
"release:major": "node scripts/release.js major",
|
|
35
|
-
"release:prerelease": "node scripts/release.js prerelease",
|
|
36
|
-
"release:dry": "node scripts/release.js patch --dry-run",
|
|
37
|
-
"version": "git add package.json && git commit -m \"chore: bump version to $(node -p \"require('./package.json').version\")\""
|
|
38
|
-
},
|
|
3
|
+
"version": "1.5.0",
|
|
4
|
+
"description": "A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript. This is the umbrella package — install individual @forinda/kickjs-* packages for the framework.",
|
|
39
5
|
"keywords": [
|
|
40
|
-
"
|
|
6
|
+
"kickjs",
|
|
7
|
+
"nodejs",
|
|
41
8
|
"typescript",
|
|
42
|
-
"
|
|
9
|
+
"express",
|
|
43
10
|
"decorators",
|
|
44
|
-
"
|
|
11
|
+
"dependency-injection",
|
|
12
|
+
"backend",
|
|
13
|
+
"api",
|
|
14
|
+
"framework",
|
|
15
|
+
"ddd",
|
|
16
|
+
"cqrs",
|
|
17
|
+
"rest",
|
|
18
|
+
"vite",
|
|
19
|
+
"zod",
|
|
20
|
+
"swagger",
|
|
21
|
+
"openapi",
|
|
22
|
+
"@forinda/kickjs-core",
|
|
23
|
+
"@forinda/kickjs-http",
|
|
24
|
+
"@forinda/kickjs-config",
|
|
25
|
+
"@forinda/kickjs-cli",
|
|
26
|
+
"@forinda/kickjs-swagger",
|
|
27
|
+
"@forinda/kickjs-testing",
|
|
28
|
+
"@forinda/kickjs-prisma",
|
|
29
|
+
"@forinda/kickjs-drizzle",
|
|
30
|
+
"@forinda/kickjs-auth",
|
|
31
|
+
"@forinda/kickjs-cron",
|
|
32
|
+
"@forinda/kickjs-mailer",
|
|
33
|
+
"@forinda/kickjs-queue",
|
|
34
|
+
"@forinda/kickjs-ws",
|
|
35
|
+
"@forinda/kickjs-graphql",
|
|
36
|
+
"@forinda/kickjs-otel",
|
|
37
|
+
"@forinda/kickjs-devtools",
|
|
38
|
+
"@forinda/kickjs-multi-tenant",
|
|
39
|
+
"@forinda/kickjs-notifications"
|
|
45
40
|
],
|
|
46
|
-
"
|
|
47
|
-
"
|
|
48
|
-
"
|
|
49
|
-
|
|
41
|
+
"type": "module",
|
|
42
|
+
"main": "index.js",
|
|
43
|
+
"types": "index.d.ts",
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"@forinda/kickjs-core": "1.5.0",
|
|
46
|
+
"@forinda/kickjs-http": "1.5.0",
|
|
47
|
+
"@forinda/kickjs-config": "1.5.0"
|
|
50
48
|
},
|
|
51
49
|
"publishConfig": {
|
|
52
50
|
"access": "public"
|
|
53
51
|
},
|
|
54
|
-
"
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
"express": "^5.1.0",
|
|
59
|
-
"inversify": "^7.10.0",
|
|
60
|
-
"reflect-metadata": "^0.2.2"
|
|
61
|
-
},
|
|
62
|
-
"devDependencies": {
|
|
63
|
-
"@swc/core": "^1.7.28",
|
|
64
|
-
"@types/express": "^5.0.3",
|
|
65
|
-
"@types/node": "^24.5.2",
|
|
66
|
-
"@types/supertest": "^6.0.3",
|
|
67
|
-
"@vitest/coverage-v8": "^3.2.4",
|
|
68
|
-
"express": "^5.1.0",
|
|
69
|
-
"husky": "^9.1.7",
|
|
70
|
-
"inversify": "^7.10.0",
|
|
71
|
-
"joi": "^18.0.1",
|
|
72
|
-
"node-mocks-http": "^1.17.2",
|
|
73
|
-
"reflect-metadata": "^0.2.2",
|
|
74
|
-
"supertest": "^7.1.4",
|
|
75
|
-
"ts-node": "^10.9.2",
|
|
76
|
-
"ts-node-dev": "^2.0.0",
|
|
77
|
-
"tsup": "^8.5.0",
|
|
78
|
-
"tsx": "^4.20.6",
|
|
79
|
-
"typescript": "^5.9.2",
|
|
80
|
-
"vitest": "^3.2.4",
|
|
81
|
-
"zod": "^4.1.9"
|
|
82
|
-
},
|
|
83
|
-
"directories": {
|
|
84
|
-
"doc": "docs",
|
|
85
|
-
"example": "examples",
|
|
86
|
-
"test": "tests"
|
|
52
|
+
"license": "MIT",
|
|
53
|
+
"author": "Felix Orinda",
|
|
54
|
+
"engines": {
|
|
55
|
+
"node": ">=20.0"
|
|
87
56
|
},
|
|
57
|
+
"homepage": "https://forinda.github.io/kick-js/",
|
|
88
58
|
"repository": {
|
|
89
59
|
"type": "git",
|
|
90
|
-
"url": "
|
|
60
|
+
"url": "https://github.com/forinda/kick-js.git",
|
|
61
|
+
"directory": "packages/kickjs"
|
|
91
62
|
},
|
|
92
63
|
"bugs": {
|
|
93
64
|
"url": "https://github.com/forinda/kick-js/issues"
|
|
94
65
|
},
|
|
95
|
-
"
|
|
96
|
-
}
|
|
66
|
+
"scripts": {}
|
|
67
|
+
}
|
package/README.md
DELETED
|
@@ -1,560 +0,0 @@
|
|
|
1
|
-
# KickJS
|
|
2
|
-
|
|
3
|
-
🚀 A modern, decorator-driven TypeScript framework built on Express with dependency injection, reactive state management, and enterprise-ready features.
|
|
4
|
-
|
|
5
|
-
## ✨ Features
|
|
6
|
-
|
|
7
|
-
- **Decorator-Driven Architecture**: Spring Boot-style controllers with `@KickController`, `@KickGet`, `@KickPost`, etc.
|
|
8
|
-
- **Dependency Injection**: Powered by Inversify with automatic binding and container management
|
|
9
|
-
- **Reactive State Management**: Built-in EventEmitter-based state with observable properties
|
|
10
|
-
- **Middleware System**: Priority-based middleware with both global and DI-managed middlewares
|
|
11
|
-
- **Request Context Injection**: Automatic injection of request context with metadata
|
|
12
|
-
- **Route Prefixing**: Flexible API prefixing for better organization
|
|
13
|
-
- **Module System**: Organize your application into reusable, self-contained modules
|
|
14
|
-
- **Auto-Binding**: Automatic method binding with `@AutoBind` decorator
|
|
15
|
-
- **Type Safety**: Full TypeScript support with comprehensive type definitions
|
|
16
|
-
|
|
17
|
-
## 📦 Installation
|
|
18
|
-
|
|
19
|
-
```bash
|
|
20
|
-
npm install @forinda/kickjs
|
|
21
|
-
# or
|
|
22
|
-
pnpm add @forinda/kickjs
|
|
23
|
-
# or
|
|
24
|
-
yarn add @forinda/kickjs
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
## 🏗️ Creating Your First App
|
|
28
|
-
|
|
29
|
-
### Basic Setup
|
|
30
|
-
|
|
31
|
-
```typescript
|
|
32
|
-
// src/index.ts
|
|
33
|
-
import express from "express";
|
|
34
|
-
import { createKickApp, KickController, KickGet, KickRequestContext } from "@forinda/kickjs";
|
|
35
|
-
import { AppModule } from "./app.module";
|
|
36
|
-
|
|
37
|
-
const app = express();
|
|
38
|
-
app.use(express.json());
|
|
39
|
-
|
|
40
|
-
const server = createKickApp({
|
|
41
|
-
name: "MyApp",
|
|
42
|
-
prefix: "/api/v1", // Optional: prefix all routes
|
|
43
|
-
app,
|
|
44
|
-
modules: [AppModule]
|
|
45
|
-
});
|
|
46
|
-
|
|
47
|
-
server.listen(3000, () => {
|
|
48
|
-
console.log("🚀 Server running on http://localhost:3000");
|
|
49
|
-
console.log("📊 App Stats:", server.getStats());
|
|
50
|
-
});
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### Creating Controllers
|
|
54
|
-
|
|
55
|
-
Controllers are the heart of your KickJS application. They handle HTTP requests and contain your business logic.
|
|
56
|
-
|
|
57
|
-
```typescript
|
|
58
|
-
// src/controllers/users.controller.ts
|
|
59
|
-
import {
|
|
60
|
-
KickController,
|
|
61
|
-
KickGet,
|
|
62
|
-
KickPost,
|
|
63
|
-
KickRequestContext,
|
|
64
|
-
KickInject
|
|
65
|
-
} from "@forinda/kickjs";
|
|
66
|
-
import { UserService } from "../services/user.service";
|
|
67
|
-
|
|
68
|
-
@KickController("/users")
|
|
69
|
-
export class UserController {
|
|
70
|
-
constructor(
|
|
71
|
-
@KickInject(UserService)
|
|
72
|
-
private readonly userService: UserService
|
|
73
|
-
) {}
|
|
74
|
-
|
|
75
|
-
@KickGet("/")
|
|
76
|
-
async getUsers(context: KickRequestContext) {
|
|
77
|
-
const { res } = context;
|
|
78
|
-
const users = await this.userService.findAll();
|
|
79
|
-
|
|
80
|
-
res.json({
|
|
81
|
-
users,
|
|
82
|
-
requestId: context.meta.requestId,
|
|
83
|
-
timestamp: context.meta.startTime
|
|
84
|
-
});
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
@KickPost("/")
|
|
88
|
-
async createUser(context: KickRequestContext) {
|
|
89
|
-
const { req, res } = context;
|
|
90
|
-
|
|
91
|
-
if (!req.body.name || !req.body.email) {
|
|
92
|
-
return res.status(400).json({
|
|
93
|
-
error: "Name and email are required",
|
|
94
|
-
requestId: context.meta.requestId
|
|
95
|
-
});
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
const user = await this.userService.create(req.body);
|
|
99
|
-
res.status(201).json({
|
|
100
|
-
user,
|
|
101
|
-
requestId: context.meta.requestId
|
|
102
|
-
});
|
|
103
|
-
}
|
|
104
|
-
}
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
### Configuration
|
|
108
|
-
|
|
109
|
-
KickJS supports flexible configuration through `kick.config.ts` files. This provides type safety and prevents configuration errors.
|
|
110
|
-
|
|
111
|
-
```typescript
|
|
112
|
-
// kick.config.ts
|
|
113
|
-
import { createKickConfig } from "@forinda/kickjs";
|
|
114
|
-
|
|
115
|
-
export default createKickConfig({
|
|
116
|
-
app: {
|
|
117
|
-
name: 'My App',
|
|
118
|
-
port: 3000,
|
|
119
|
-
host: 'localhost',
|
|
120
|
-
prefix: '/api/v1',
|
|
121
|
-
env: 'development'
|
|
122
|
-
},
|
|
123
|
-
dev: {
|
|
124
|
-
port: 3000,
|
|
125
|
-
host: 'localhost',
|
|
126
|
-
entry: 'src/index.ts',
|
|
127
|
-
watch: true,
|
|
128
|
-
env: {
|
|
129
|
-
NODE_ENV: 'development',
|
|
130
|
-
DEBUG: 'app:*'
|
|
131
|
-
}
|
|
132
|
-
},
|
|
133
|
-
start: {
|
|
134
|
-
port: 3000,
|
|
135
|
-
host: '0.0.0.0',
|
|
136
|
-
entry: 'dist/index.js',
|
|
137
|
-
env: {
|
|
138
|
-
NODE_ENV: 'production'
|
|
139
|
-
}
|
|
140
|
-
}
|
|
141
|
-
});
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
#### Using Configuration in Your App
|
|
145
|
-
|
|
146
|
-
```typescript
|
|
147
|
-
// src/index.ts
|
|
148
|
-
import { createKickAppWithConfig } from "@forinda/kickjs";
|
|
149
|
-
import { AppModule } from "./app.module";
|
|
150
|
-
|
|
151
|
-
async function startApp() {
|
|
152
|
-
const server = await createKickAppWithConfig({
|
|
153
|
-
app: express(),
|
|
154
|
-
modules: [AppModule]
|
|
155
|
-
});
|
|
156
|
-
|
|
157
|
-
// Access config in your app
|
|
158
|
-
console.log('App Name:', server.kickApp.getConfig('name'));
|
|
159
|
-
console.log('API Prefix:', server.kickApp.getConfig('prefix'));
|
|
160
|
-
|
|
161
|
-
// Config with fallback
|
|
162
|
-
const theme = server.kickApp.getConfigOrDefault('ui.theme', 'dark');
|
|
163
|
-
|
|
164
|
-
const port = server.kickApp.getConfig('port') || 3000;
|
|
165
|
-
server.listen(port, () => {
|
|
166
|
-
console.log(`🚀 ${server.kickApp.getConfig('name')} running on port ${port}`);
|
|
167
|
-
});
|
|
168
|
-
}
|
|
169
|
-
|
|
170
|
-
startApp();
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
#### CLI Configuration Support
|
|
174
|
-
|
|
175
|
-
The KickJS CLI automatically loads your configuration:
|
|
176
|
-
|
|
177
|
-
```bash
|
|
178
|
-
# Uses config file values
|
|
179
|
-
kick dev
|
|
180
|
-
|
|
181
|
-
# Override specific values
|
|
182
|
-
kick dev --port 8080 --host 0.0.0.0
|
|
183
|
-
|
|
184
|
-
# Production mode
|
|
185
|
-
kick start --port 3000
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
### Creating Services
|
|
189
|
-
|
|
190
|
-
Services contain your business logic and can be injected into controllers and other services.
|
|
191
|
-
|
|
192
|
-
```typescript
|
|
193
|
-
// src/services/user.service.ts
|
|
194
|
-
import { KickInjectable } from "@forinda/kickjs";
|
|
195
|
-
|
|
196
|
-
export interface User {
|
|
197
|
-
id: string;
|
|
198
|
-
name: string;
|
|
199
|
-
email: string;
|
|
200
|
-
createdAt: Date;
|
|
201
|
-
}
|
|
202
|
-
|
|
203
|
-
@KickInjectable()
|
|
204
|
-
export class UserService {
|
|
205
|
-
private users: User[] = [];
|
|
206
|
-
|
|
207
|
-
async findAll(): Promise<User[]> {
|
|
208
|
-
return this.users;
|
|
209
|
-
}
|
|
210
|
-
|
|
211
|
-
async create(userData: { name: string; email: string }): Promise<User> {
|
|
212
|
-
const user: User = {
|
|
213
|
-
id: Math.random().toString(36).substr(2, 9),
|
|
214
|
-
name: userData.name,
|
|
215
|
-
email: userData.email,
|
|
216
|
-
createdAt: new Date()
|
|
217
|
-
};
|
|
218
|
-
|
|
219
|
-
this.users.push(user);
|
|
220
|
-
return user;
|
|
221
|
-
}
|
|
222
|
-
|
|
223
|
-
async findById(id: string): Promise<User | undefined> {
|
|
224
|
-
return this.users.find(user => user.id === id);
|
|
225
|
-
}
|
|
226
|
-
}
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
### Creating Modules
|
|
230
|
-
|
|
231
|
-
Modules help organize your application by grouping related controllers, services, and middlewares.
|
|
232
|
-
|
|
233
|
-
```typescript
|
|
234
|
-
// src/app.module.ts
|
|
235
|
-
import { createModule } from "@forinda/kickjs";
|
|
236
|
-
import { UserController } from "./controllers/user.controller";
|
|
237
|
-
import { UserService } from "./services/user.service";
|
|
238
|
-
import { LoggingMiddleware } from "./middlewares/logging.middleware";
|
|
239
|
-
|
|
240
|
-
export const AppModule = createModule("app", {
|
|
241
|
-
controllers: [UserController],
|
|
242
|
-
services: [UserService], // Register your services
|
|
243
|
-
middlewares: [LoggingMiddleware] // Optional: DI-managed middlewares
|
|
244
|
-
});
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
## 🛠️ Creating Middlewares
|
|
248
|
-
|
|
249
|
-
KickJS supports two types of middlewares: global middlewares and DI-managed middlewares.
|
|
250
|
-
|
|
251
|
-
### DI-Managed Middlewares (Recommended)
|
|
252
|
-
|
|
253
|
-
These middlewares are managed by the dependency injection container and can inject services.
|
|
254
|
-
|
|
255
|
-
```typescript
|
|
256
|
-
// src/middlewares/logging.middleware.ts
|
|
257
|
-
import {
|
|
258
|
-
KickMiddleware,
|
|
259
|
-
KickAppMiddleware,
|
|
260
|
-
KickRequest,
|
|
261
|
-
KickResponse,
|
|
262
|
-
KickNextFn
|
|
263
|
-
} from "@forinda/kickjs";
|
|
264
|
-
|
|
265
|
-
@KickMiddleware({
|
|
266
|
-
name: "RequestLogger",
|
|
267
|
-
priority: 1, // Lower numbers execute first
|
|
268
|
-
global: true,
|
|
269
|
-
tags: ["logging", "development"]
|
|
270
|
-
})
|
|
271
|
-
export class LoggingMiddleware implements KickAppMiddleware {
|
|
272
|
-
use(req: KickRequest, res: KickResponse, next: KickNextFn): void {
|
|
273
|
-
const start = Date.now();
|
|
274
|
-
|
|
275
|
-
console.log(`→ ${req.method} ${req.url}`);
|
|
276
|
-
|
|
277
|
-
res.on('finish', () => {
|
|
278
|
-
const duration = Date.now() - start;
|
|
279
|
-
console.log(`← ${req.method} ${req.url} ${res.statusCode} (${duration}ms)`);
|
|
280
|
-
});
|
|
281
|
-
|
|
282
|
-
next();
|
|
283
|
-
}
|
|
284
|
-
}
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
### Global Middlewares
|
|
288
|
-
|
|
289
|
-
Global middlewares are not managed by DI and are useful for framework-level concerns like CORS.
|
|
290
|
-
|
|
291
|
-
```typescript
|
|
292
|
-
// src/middlewares/cors.middleware.ts
|
|
293
|
-
import { KickAppMiddleware, KickRequest, KickResponse, KickNextFn } from "@forinda/kickjs";
|
|
294
|
-
|
|
295
|
-
export class CorsMiddleware implements KickAppMiddleware {
|
|
296
|
-
use(req: KickRequest, res: KickResponse, next: KickNextFn): void {
|
|
297
|
-
res.setHeader('Access-Control-Allow-Origin', '*');
|
|
298
|
-
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
|
|
299
|
-
res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
|
|
300
|
-
|
|
301
|
-
if (req.method === 'OPTIONS') {
|
|
302
|
-
res.status(200).end();
|
|
303
|
-
return;
|
|
304
|
-
}
|
|
305
|
-
|
|
306
|
-
next();
|
|
307
|
-
}
|
|
308
|
-
}
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
Register global middlewares when creating your app:
|
|
312
|
-
|
|
313
|
-
```typescript
|
|
314
|
-
const corsMiddleware = new CorsMiddleware();
|
|
315
|
-
|
|
316
|
-
const server = createKickApp({
|
|
317
|
-
name: "MyApp",
|
|
318
|
-
app,
|
|
319
|
-
globalMiddlewares: [corsMiddleware], // Global middlewares
|
|
320
|
-
modules: [AppModule] // DI-managed middlewares are in modules
|
|
321
|
-
});
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
## 🔌 Creating Plugins
|
|
325
|
-
|
|
326
|
-
Plugins allow you to extend the application context during initialization.
|
|
327
|
-
|
|
328
|
-
```typescript
|
|
329
|
-
// src/plugins/database.plugin.ts
|
|
330
|
-
import { KickAppPlugin, KickApplicationContext } from "@forinda/kickjs";
|
|
331
|
-
|
|
332
|
-
export class DatabasePlugin implements KickAppPlugin {
|
|
333
|
-
install(context: KickApplicationContext): void {
|
|
334
|
-
// Initialize database connection
|
|
335
|
-
console.log("🗄️ Database plugin initialized");
|
|
336
|
-
|
|
337
|
-
// Add database middleware or modify app
|
|
338
|
-
context.app.use((req, res, next) => {
|
|
339
|
-
// Add database connection to request
|
|
340
|
-
(req as any).db = /* your database connection */;
|
|
341
|
-
next();
|
|
342
|
-
});
|
|
343
|
-
}
|
|
344
|
-
}
|
|
345
|
-
```
|
|
346
|
-
|
|
347
|
-
Use plugins in your app:
|
|
348
|
-
|
|
349
|
-
```typescript
|
|
350
|
-
const dbPlugin = new DatabasePlugin();
|
|
351
|
-
|
|
352
|
-
const server = createKickApp({
|
|
353
|
-
name: "MyApp",
|
|
354
|
-
app,
|
|
355
|
-
plugins: [dbPlugin],
|
|
356
|
-
modules: [AppModule]
|
|
357
|
-
});
|
|
358
|
-
```
|
|
359
|
-
|
|
360
|
-
## 🎯 Advanced Features
|
|
361
|
-
|
|
362
|
-
### Request Context
|
|
363
|
-
|
|
364
|
-
Every controller method receives a `KickRequestContext` with rich metadata:
|
|
365
|
-
|
|
366
|
-
```typescript
|
|
367
|
-
interface KickRequestContext {
|
|
368
|
-
req: KickRequest; // Express request
|
|
369
|
-
res: KickResponse; // Express response
|
|
370
|
-
next: KickNextFn; // Express next function
|
|
371
|
-
meta: {
|
|
372
|
-
routePath: string; // Route pattern
|
|
373
|
-
method: string; // HTTP method
|
|
374
|
-
controllerName: string; // Controller class name
|
|
375
|
-
handlerName: string; // Method name
|
|
376
|
-
startTime: number; // Request start timestamp
|
|
377
|
-
requestId: string; // Unique request ID
|
|
378
|
-
};
|
|
379
|
-
}
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
### Reactive State Management
|
|
383
|
-
|
|
384
|
-
KickApp includes reactive state management:
|
|
385
|
-
|
|
386
|
-
```typescript
|
|
387
|
-
// Set state
|
|
388
|
-
server.kickApp.setState('userCount', 42);
|
|
389
|
-
|
|
390
|
-
// Listen to state changes
|
|
391
|
-
server.kickApp.onStateChange('userCount', (data) => {
|
|
392
|
-
console.log(`User count changed: ${data.oldValue} → ${data.value}`);
|
|
393
|
-
});
|
|
394
|
-
|
|
395
|
-
// Get current state
|
|
396
|
-
const currentState = server.kickApp.state;
|
|
397
|
-
```
|
|
398
|
-
|
|
399
|
-
### Event System
|
|
400
|
-
|
|
401
|
-
Listen to application events:
|
|
402
|
-
|
|
403
|
-
```typescript
|
|
404
|
-
server.kickApp.on('route:registered', (route) => {
|
|
405
|
-
console.log(`Route registered: ${route.method} ${route.path}`);
|
|
406
|
-
});
|
|
407
|
-
|
|
408
|
-
server.kickApp.on('middleware:registered', (middleware) => {
|
|
409
|
-
console.log(`Middleware registered: ${middleware.count} middlewares`);
|
|
410
|
-
});
|
|
411
|
-
|
|
412
|
-
server.kickApp.on('controller:mapped', (controller) => {
|
|
413
|
-
console.log(`Controller mapped: ${controller.controller}`);
|
|
414
|
-
});
|
|
415
|
-
```
|
|
416
|
-
|
|
417
|
-
### Error Handling
|
|
418
|
-
|
|
419
|
-
Add global error handlers:
|
|
420
|
-
|
|
421
|
-
```typescript
|
|
422
|
-
server.addErrorHandler((errorData) => {
|
|
423
|
-
console.error('Application error:', errorData);
|
|
424
|
-
// Send to logging service, etc.
|
|
425
|
-
});
|
|
426
|
-
```
|
|
427
|
-
|
|
428
|
-
## 🚀 Running Your Application
|
|
429
|
-
|
|
430
|
-
### Development
|
|
431
|
-
|
|
432
|
-
```bash
|
|
433
|
-
# Using tsx for development
|
|
434
|
-
npx tsx watch src/index.ts
|
|
435
|
-
|
|
436
|
-
# Or with nodemon
|
|
437
|
-
npx nodemon --exec tsx src/index.ts
|
|
438
|
-
```
|
|
439
|
-
|
|
440
|
-
### Production
|
|
441
|
-
|
|
442
|
-
```bash
|
|
443
|
-
# Build your TypeScript
|
|
444
|
-
npx tsc
|
|
445
|
-
|
|
446
|
-
# Run the compiled JavaScript
|
|
447
|
-
node dist/index.js
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
### Example Scripts (package.json)
|
|
451
|
-
|
|
452
|
-
```json
|
|
453
|
-
{
|
|
454
|
-
"scripts": {
|
|
455
|
-
"dev": "tsx watch src/index.ts",
|
|
456
|
-
"build": "tsc",
|
|
457
|
-
"start": "node dist/index.js",
|
|
458
|
-
"test": "vitest"
|
|
459
|
-
}
|
|
460
|
-
}
|
|
461
|
-
```
|
|
462
|
-
|
|
463
|
-
## 📁 Project Structure
|
|
464
|
-
|
|
465
|
-
```
|
|
466
|
-
src/
|
|
467
|
-
├── controllers/ # HTTP controllers
|
|
468
|
-
│ ├── user.controller.ts
|
|
469
|
-
│ └── auth.controller.ts
|
|
470
|
-
├── services/ # Business logic services
|
|
471
|
-
│ ├── user.service.ts
|
|
472
|
-
│ └── auth.service.ts
|
|
473
|
-
├── middlewares/ # Custom middlewares
|
|
474
|
-
│ ├── logging.middleware.ts
|
|
475
|
-
│ └── auth.middleware.ts
|
|
476
|
-
├── plugins/ # Application plugins
|
|
477
|
-
│ └── database.plugin.ts
|
|
478
|
-
├── types/ # Type definitions
|
|
479
|
-
│ └── user.types.ts
|
|
480
|
-
├── modules/ # Application modules
|
|
481
|
-
│ ├── user.module.ts
|
|
482
|
-
│ └── auth.module.ts
|
|
483
|
-
└── index.ts # Application entry point
|
|
484
|
-
```
|
|
485
|
-
|
|
486
|
-
## 📚 API Reference
|
|
487
|
-
|
|
488
|
-
### Decorators
|
|
489
|
-
|
|
490
|
-
- `@KickController(path)` - Define a controller class
|
|
491
|
-
- `@KickGet(path)` - HTTP GET route
|
|
492
|
-
- `@KickPost(path)` - HTTP POST route
|
|
493
|
-
- `@KickPut(path)` - HTTP PUT route
|
|
494
|
-
- `@KickPatch(path)` - HTTP PATCH route
|
|
495
|
-
- `@KickDelete(path)` - HTTP DELETE route
|
|
496
|
-
- `@KickMiddleware(options)` - Define a middleware class
|
|
497
|
-
- `@KickInject(token)` - Inject dependencies
|
|
498
|
-
- `@KickInjectable()` - Mark class as injectable service
|
|
499
|
-
- `@AutoBind` - Automatically bind class methods
|
|
500
|
-
|
|
501
|
-
### Core Functions
|
|
502
|
-
|
|
503
|
-
- `createKickApp(options)` - Create a KickJS application
|
|
504
|
-
- `createModule(name, options)` - Create a module
|
|
505
|
-
- `isKickMiddleware(target)` - Check if class is a middleware
|
|
506
|
-
- `getMiddlewareMetadata(target)` - Get middleware metadata
|
|
507
|
-
|
|
508
|
-
### Types
|
|
509
|
-
|
|
510
|
-
- `KickRequestContext` - Request context interface
|
|
511
|
-
- `KickAppMiddleware` - Middleware interface
|
|
512
|
-
- `KickAppPlugin` - Plugin interface
|
|
513
|
-
- `KickApplicationContext` - Application context interface
|
|
514
|
-
|
|
515
|
-
## 🤝 Contributing
|
|
516
|
-
|
|
517
|
-
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on how to get started.
|
|
518
|
-
|
|
519
|
-
### Quick Start for Contributors
|
|
520
|
-
|
|
521
|
-
1. **Fork and clone the repository**
|
|
522
|
-
```bash
|
|
523
|
-
git clone https://github.com/yourusername/kickjs.git
|
|
524
|
-
cd kickjs
|
|
525
|
-
pnpm install
|
|
526
|
-
```
|
|
527
|
-
|
|
528
|
-
2. **Run tests to ensure everything works**
|
|
529
|
-
```bash
|
|
530
|
-
pnpm test
|
|
531
|
-
pnpm build
|
|
532
|
-
```
|
|
533
|
-
|
|
534
|
-
3. **Create a feature branch and make your changes**
|
|
535
|
-
```bash
|
|
536
|
-
git checkout -b feature/amazing-feature
|
|
537
|
-
# Make your changes...
|
|
538
|
-
git commit -m "feat: add amazing feature"
|
|
539
|
-
```
|
|
540
|
-
|
|
541
|
-
4. **Submit a pull request**
|
|
542
|
-
|
|
543
|
-
For detailed guidelines, development setup, coding standards, and more, please read our [Contributing Guide](CONTRIBUTING.md).
|
|
544
|
-
|
|
545
|
-
### 📞 Getting Help
|
|
546
|
-
|
|
547
|
-
- 📖 Check the [documentation](README.md) and [examples](examples/)
|
|
548
|
-
- 🐛 Search [existing issues](https://github.com/forinda/kickjs/issues)
|
|
549
|
-
- 💬 Join our community discussions
|
|
550
|
-
- 📧 Contact maintainers for security issues
|
|
551
|
-
|
|
552
|
-
Thank you for contributing to KickJS! 🚀
|
|
553
|
-
|
|
554
|
-
## 📄 License
|
|
555
|
-
|
|
556
|
-
MIT License - see [LICENSE](LICENSE) file for details.
|
|
557
|
-
|
|
558
|
-
---
|
|
559
|
-
|
|
560
|
-
**Made with ❤️ by the KickJS team**
|