@forinda/kickjs 0.1.4 → 0.1.6
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 +471 -252
- package/dist/cli.js +290 -18
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +568 -333
- package/dist/index.js +742 -1688
- package/dist/index.js.map +1 -1
- package/package.json +23 -6
package/README.md
CHANGED
|
@@ -1,347 +1,566 @@
|
|
|
1
|
-
#
|
|
1
|
+
# KickJS
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
🚀 A modern, decorator-driven TypeScript framework built on Express with dependency injection, reactive state management, and enterprise-ready features.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## ✨ Features
|
|
6
6
|
|
|
7
|
-
- Spring Boot-style controllers
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
- `tsup` build pipeline producing CommonJS bundles + type declarations
|
|
17
|
-
- GitHub Actions workflow for CI and optional npm publishing
|
|
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
|
|
18
16
|
|
|
19
|
-
##
|
|
17
|
+
## 📦 Installation
|
|
20
18
|
|
|
21
19
|
```bash
|
|
22
20
|
npm install @forinda/kickjs
|
|
21
|
+
# or
|
|
22
|
+
pnpm add @forinda/kickjs
|
|
23
|
+
# or
|
|
24
|
+
yarn add @forinda/kickjs
|
|
23
25
|
```
|
|
24
26
|
|
|
25
|
-
## Creating
|
|
26
|
-
|
|
27
|
-
```ts
|
|
28
|
-
// app.ts
|
|
29
|
-
import "reflect-metadata";
|
|
30
|
-
import type { Request, Response } from "express";
|
|
31
|
-
import {
|
|
32
|
-
BaseController,
|
|
33
|
-
Controller,
|
|
34
|
-
Get,
|
|
35
|
-
bootstrap,
|
|
36
|
-
configureApp,
|
|
37
|
-
} from "@forinda/kickjs";
|
|
38
|
-
|
|
39
|
-
configureApp({ prefix: "/api/v1" });
|
|
27
|
+
## 🏗️ Creating Your First App
|
|
40
28
|
|
|
41
|
-
|
|
42
|
-
class HelloController extends BaseController {
|
|
43
|
-
protected controllerId(): string {
|
|
44
|
-
return "HelloController";
|
|
45
|
-
}
|
|
29
|
+
### Basic Setup
|
|
46
30
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
handle(req: Request, res: Response) {
|
|
53
|
-
const name = typeof req.query.name === "string" ? req.query.name : "World";
|
|
54
|
-
this.mergeRequestMetadata(res, { greeted: name });
|
|
55
|
-
return this.ok(res, { message: `Hello ${name}` });
|
|
56
|
-
}
|
|
57
|
-
}
|
|
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";
|
|
58
36
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
await bootstrap({ port });
|
|
62
|
-
console.log(`Server started on http://localhost:${port}`);
|
|
63
|
-
}
|
|
37
|
+
const app = express();
|
|
38
|
+
app.use(express.json());
|
|
64
39
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
40
|
+
const server = createKickApp({
|
|
41
|
+
name: "MyApp",
|
|
42
|
+
prefix: "/api/v1", // Optional: prefix all routes
|
|
43
|
+
app,
|
|
44
|
+
modules: [AppModule]
|
|
68
45
|
});
|
|
69
46
|
|
|
47
|
+
server.listen(3000, () => {
|
|
48
|
+
console.log("🚀 Server running on http://localhost:3000");
|
|
49
|
+
console.log("📊 App Stats:", server.getStats());
|
|
50
|
+
});
|
|
70
51
|
```
|
|
71
52
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
## Public API surface
|
|
75
|
-
|
|
76
|
-
```ts
|
|
77
|
-
import {
|
|
78
|
-
Controller,
|
|
79
|
-
Get,
|
|
80
|
-
Post,
|
|
81
|
-
Put,
|
|
82
|
-
Patch,
|
|
83
|
-
Delete,
|
|
84
|
-
HttpVerbController,
|
|
85
|
-
GetController,
|
|
86
|
-
PostController,
|
|
87
|
-
PutController,
|
|
88
|
-
PatchController,
|
|
89
|
-
DeleteController,
|
|
90
|
-
Inject,
|
|
91
|
-
Injectable,
|
|
92
|
-
Optional,
|
|
93
|
-
MultiInject,
|
|
94
|
-
Named,
|
|
95
|
-
Tagged,
|
|
96
|
-
Unmanaged,
|
|
97
|
-
BaseController,
|
|
98
|
-
discoverControllersFromFilesystem,
|
|
99
|
-
RequestTracker,
|
|
100
|
-
AppDiagnostics,
|
|
101
|
-
TYPES,
|
|
102
|
-
configureApp,
|
|
103
|
-
createApp,
|
|
104
|
-
bootstrap,
|
|
105
|
-
createError,
|
|
106
|
-
AppError,
|
|
107
|
-
isAppError,
|
|
108
|
-
resetControllerRegistry,
|
|
109
|
-
resetAppConfig
|
|
110
|
-
} from '@forinda/kickjs';
|
|
111
|
-
```
|
|
53
|
+
### Creating Controllers
|
|
112
54
|
|
|
113
|
-
|
|
114
|
-
- `Inject`, `Injectable`, `Optional`, `MultiInject`, `Named`, `Tagged`, `Unmanaged`: DI helpers wrapping Inversify without exposing its API surface
|
|
115
|
-
- `HttpVerbController` & the verb-specific subclasses (`GetController`, `PostController`, …): enforce single-verb controllers with shared response/logging helpers and Nuxt-style route derivation
|
|
116
|
-
- `BaseController`: abstract class with response + logging helpers for traditional decorator-driven controllers. The request tracker is injected automatically, so subclasses never pass it through `super()`.
|
|
117
|
-
- `configureApp(config)`: set global prefix, logging level, telemetry limits, and health endpoint before bootstrapping
|
|
118
|
-
- `createApp(options)`: create an Express application with auto-registered controllers (optionally override config per call) and get back a `discovery.controllers` list for diagnostics
|
|
119
|
-
- `bootstrap(options)`: create & start the HTTP server (accepts `port`, config overrides, extra middleware)
|
|
120
|
-
- `RequestTracker`: injectable request context tracker used internally by `BaseController`
|
|
121
|
-
- `AppDiagnostics`: inspect application/request telemetry without touching internal reactive state
|
|
122
|
-
- `createError` / `AppError` / `isAppError`: structured error helpers for consistent codes and statuses
|
|
123
|
-
- `discoverControllersFromFilesystem(config)`: manually trigger file-system discovery when building custom tooling or CLIs
|
|
124
|
-
- `TYPES`: symbol map to wire container bindings
|
|
125
|
-
- `resetControllerRegistry()` / `resetAppConfig()`: utilities for clearing global state in integration tests
|
|
126
|
-
- `createKickConfig(options)`: compose environment-aware app configuration objects that can be passed to `configureApp` or `createApp`
|
|
127
|
-
|
|
128
|
-
## File-based controllers
|
|
129
|
-
|
|
130
|
-
Kick bootstraps controllers automatically by scanning `src/http` (configurable) for files that follow Nuxt-style naming. Each file becomes a single-verb controller by extending the appropriate base class:
|
|
55
|
+
Controllers are the heart of your KickJS application. They handle HTTP requests and contain your business logic.
|
|
131
56
|
|
|
132
|
-
```
|
|
133
|
-
src/
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
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
|
+
}
|
|
138
86
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
+
}
|
|
143
97
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
98
|
+
const user = await this.userService.create(req.body);
|
|
99
|
+
res.status(201).json({
|
|
100
|
+
user,
|
|
101
|
+
requestId: context.meta.requestId
|
|
102
|
+
});
|
|
147
103
|
}
|
|
148
104
|
}
|
|
149
105
|
```
|
|
150
106
|
|
|
151
|
-
|
|
107
|
+
### Configuration
|
|
152
108
|
|
|
153
|
-
|
|
154
|
-
- Directory names and file segments turn into URL fragments (`[id]` → `:id`, `[...slug]` → `:slug*`, `index` is omitted)
|
|
155
|
-
- Set `static route = '/custom/path'` on the class to override the derived path, and `static tags = ['admin']` to enrich diagnostics metadata
|
|
109
|
+
KickJS supports flexible configuration through `kick.config.ts` files. This provides type safety and prevents configuration errors.
|
|
156
110
|
|
|
157
|
-
|
|
111
|
+
```typescript
|
|
112
|
+
// kick.config.ts
|
|
113
|
+
import { createKickConfig } from "@forinda/kickjs";
|
|
158
114
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
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'
|
|
167
139
|
}
|
|
168
140
|
}
|
|
169
141
|
});
|
|
170
142
|
```
|
|
171
143
|
|
|
172
|
-
|
|
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
|
+
}
|
|
173
169
|
|
|
174
|
-
|
|
170
|
+
startApp();
|
|
171
|
+
```
|
|
175
172
|
|
|
176
|
-
|
|
173
|
+
#### CLI Configuration Support
|
|
177
174
|
|
|
178
|
-
|
|
175
|
+
The KickJS CLI automatically loads your configuration:
|
|
179
176
|
|
|
180
177
|
```bash
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
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
|
|
185
186
|
```
|
|
186
187
|
|
|
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";
|
|
188
195
|
|
|
189
|
-
|
|
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[] = [];
|
|
190
206
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
import { bootstrap, configureApp } from '@forinda/kickjs';
|
|
195
|
-
import appConfig from './config/kick.config';
|
|
207
|
+
async findAll(): Promise<User[]> {
|
|
208
|
+
return this.users;
|
|
209
|
+
}
|
|
196
210
|
|
|
197
|
-
|
|
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
|
+
}
|
|
198
222
|
|
|
199
|
-
async
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
process.once('SIGTERM', shutdown);
|
|
223
|
+
async findById(id: string): Promise<User | undefined> {
|
|
224
|
+
return this.users.find(user => user.id === id);
|
|
225
|
+
}
|
|
203
226
|
}
|
|
227
|
+
```
|
|
204
228
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
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
|
+
middlewares: [LoggingMiddleware] // Optional: DI-managed middlewares
|
|
208
243
|
});
|
|
209
244
|
```
|
|
210
245
|
|
|
211
|
-
|
|
246
|
+
## 🛠️ Creating Middlewares
|
|
212
247
|
|
|
213
|
-
|
|
248
|
+
KickJS supports two types of middlewares: global middlewares and DI-managed middlewares.
|
|
214
249
|
|
|
215
|
-
|
|
250
|
+
### DI-Managed Middlewares (Recommended)
|
|
216
251
|
|
|
217
|
-
|
|
252
|
+
These middlewares are managed by the dependency injection container and can inject services.
|
|
218
253
|
|
|
219
|
-
|
|
254
|
+
```typescript
|
|
255
|
+
// src/middlewares/logging.middleware.ts
|
|
256
|
+
import {
|
|
257
|
+
KickMiddleware,
|
|
258
|
+
KickAppMiddleware,
|
|
259
|
+
KickRequest,
|
|
260
|
+
KickResponse,
|
|
261
|
+
KickNextFn,
|
|
262
|
+
KickInject
|
|
263
|
+
} from "@forinda/kickjs";
|
|
264
|
+
import { LoggerService } from "../services/logger.service";
|
|
220
265
|
|
|
221
|
-
|
|
222
|
-
|
|
266
|
+
@KickMiddleware({
|
|
267
|
+
name: "RequestLogger",
|
|
268
|
+
priority: 1, // Lower numbers execute first
|
|
269
|
+
global: true,
|
|
270
|
+
tags: ["logging", "development"]
|
|
271
|
+
})
|
|
272
|
+
export class LoggingMiddleware implements KickAppMiddleware {
|
|
273
|
+
constructor(
|
|
274
|
+
@KickInject(LoggerService)
|
|
275
|
+
private readonly logger: LoggerService
|
|
276
|
+
) {}
|
|
277
|
+
|
|
278
|
+
use(req: KickRequest, res: KickResponse, next: KickNextFn): void {
|
|
279
|
+
const start = Date.now();
|
|
280
|
+
|
|
281
|
+
this.logger.info(`→ ${req.method} ${req.url}`);
|
|
282
|
+
|
|
283
|
+
res.on('finish', () => {
|
|
284
|
+
const duration = Date.now() - start;
|
|
285
|
+
this.logger.info(`← ${req.method} ${req.url} ${res.statusCode} (${duration}ms)`);
|
|
286
|
+
});
|
|
287
|
+
|
|
288
|
+
next();
|
|
289
|
+
}
|
|
290
|
+
}
|
|
223
291
|
```
|
|
224
292
|
|
|
225
|
-
|
|
293
|
+
### Global Middlewares
|
|
226
294
|
|
|
227
|
-
|
|
295
|
+
Global middlewares are not managed by DI and are useful for framework-level concerns like CORS.
|
|
228
296
|
|
|
229
|
-
|
|
297
|
+
```typescript
|
|
298
|
+
// src/middlewares/cors.middleware.ts
|
|
299
|
+
import { KickAppMiddleware, KickRequest, KickResponse, KickNextFn } from "@forinda/kickjs";
|
|
230
300
|
|
|
231
|
-
|
|
301
|
+
export class CorsMiddleware implements KickAppMiddleware {
|
|
302
|
+
use(req: KickRequest, res: KickResponse, next: KickNextFn): void {
|
|
303
|
+
res.setHeader('Access-Control-Allow-Origin', '*');
|
|
304
|
+
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
|
|
305
|
+
res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
|
|
306
|
+
|
|
307
|
+
if (req.method === 'OPTIONS') {
|
|
308
|
+
res.status(200).end();
|
|
309
|
+
return;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
next();
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
```
|
|
232
316
|
|
|
233
|
-
|
|
317
|
+
Register global middlewares when creating your app:
|
|
234
318
|
|
|
235
|
-
```
|
|
236
|
-
|
|
319
|
+
```typescript
|
|
320
|
+
const corsMiddleware = new CorsMiddleware();
|
|
237
321
|
|
|
238
|
-
const
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
322
|
+
const server = createKickApp({
|
|
323
|
+
name: "MyApp",
|
|
324
|
+
app,
|
|
325
|
+
globalMiddlewares: [corsMiddleware], // Global middlewares
|
|
326
|
+
modules: [AppModule] // DI-managed middlewares are in modules
|
|
327
|
+
});
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
## 🔌 Creating Plugins
|
|
331
|
+
|
|
332
|
+
Plugins allow you to extend the application context during initialization.
|
|
333
|
+
|
|
334
|
+
```typescript
|
|
335
|
+
// src/plugins/database.plugin.ts
|
|
336
|
+
import { KickAppPlugin, KickApplicationContext } from "@forinda/kickjs";
|
|
337
|
+
|
|
338
|
+
export class DatabasePlugin implements KickAppPlugin {
|
|
339
|
+
install(context: KickApplicationContext): void {
|
|
340
|
+
// Initialize database connection
|
|
341
|
+
console.log("🗄️ Database plugin initialized");
|
|
342
|
+
|
|
343
|
+
// Add database middleware or modify app
|
|
344
|
+
context.app.use((req, res, next) => {
|
|
345
|
+
// Add database connection to request
|
|
346
|
+
(req as any).db = /* your database connection */;
|
|
347
|
+
next();
|
|
348
|
+
});
|
|
349
|
+
}
|
|
350
|
+
}
|
|
252
351
|
```
|
|
253
352
|
|
|
254
|
-
|
|
353
|
+
Use plugins in your app:
|
|
255
354
|
|
|
256
|
-
|
|
355
|
+
```typescript
|
|
356
|
+
const dbPlugin = new DatabasePlugin();
|
|
257
357
|
|
|
258
|
-
|
|
358
|
+
const server = createKickApp({
|
|
359
|
+
name: "MyApp",
|
|
360
|
+
app,
|
|
361
|
+
plugins: [dbPlugin],
|
|
362
|
+
modules: [AppModule]
|
|
363
|
+
});
|
|
364
|
+
```
|
|
259
365
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
366
|
+
## 🎯 Advanced Features
|
|
367
|
+
|
|
368
|
+
### Request Context
|
|
369
|
+
|
|
370
|
+
Every controller method receives a `KickRequestContext` with rich metadata:
|
|
371
|
+
|
|
372
|
+
```typescript
|
|
373
|
+
interface KickRequestContext {
|
|
374
|
+
req: KickRequest; // Express request
|
|
375
|
+
res: KickResponse; // Express response
|
|
376
|
+
next: KickNextFn; // Express next function
|
|
377
|
+
meta: {
|
|
378
|
+
routePath: string; // Route pattern
|
|
379
|
+
method: string; // HTTP method
|
|
380
|
+
controllerName: string; // Controller class name
|
|
381
|
+
handlerName: string; // Method name
|
|
382
|
+
startTime: number; // Request start timestamp
|
|
383
|
+
requestId: string; // Unique request ID
|
|
384
|
+
};
|
|
385
|
+
}
|
|
386
|
+
```
|
|
263
387
|
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
388
|
+
### Reactive State Management
|
|
389
|
+
|
|
390
|
+
KickApp includes reactive state management:
|
|
391
|
+
|
|
392
|
+
```typescript
|
|
393
|
+
// Set state
|
|
394
|
+
server.kickApp.setState('userCount', 42);
|
|
395
|
+
|
|
396
|
+
// Listen to state changes
|
|
397
|
+
server.kickApp.onStateChange('userCount', (data) => {
|
|
398
|
+
console.log(`User count changed: ${data.oldValue} → ${data.value}`);
|
|
399
|
+
});
|
|
400
|
+
|
|
401
|
+
// Get current state
|
|
402
|
+
const currentState = server.kickApp.state;
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
### Event System
|
|
406
|
+
|
|
407
|
+
Listen to application events:
|
|
408
|
+
|
|
409
|
+
```typescript
|
|
410
|
+
server.kickApp.on('route:registered', (route) => {
|
|
411
|
+
console.log(`Route registered: ${route.method} ${route.path}`);
|
|
412
|
+
});
|
|
413
|
+
|
|
414
|
+
server.kickApp.on('middleware:registered', (middleware) => {
|
|
415
|
+
console.log(`Middleware registered: ${middleware.count} middlewares`);
|
|
416
|
+
});
|
|
417
|
+
|
|
418
|
+
server.kickApp.on('controller:mapped', (controller) => {
|
|
419
|
+
console.log(`Controller mapped: ${controller.controller}`);
|
|
283
420
|
});
|
|
284
421
|
```
|
|
285
422
|
|
|
286
|
-
|
|
423
|
+
### Error Handling
|
|
287
424
|
|
|
288
|
-
|
|
425
|
+
Add global error handlers:
|
|
289
426
|
|
|
290
|
-
|
|
427
|
+
```typescript
|
|
428
|
+
server.addErrorHandler((errorData) => {
|
|
429
|
+
console.error('Application error:', errorData);
|
|
430
|
+
// Send to logging service, etc.
|
|
431
|
+
});
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
## 🚀 Running Your Application
|
|
291
435
|
|
|
292
|
-
|
|
293
|
-
const { diagnostics } = createApp();
|
|
294
|
-
const stores = diagnostics.stores();
|
|
295
|
-
// -> [{ id, label, snapshot, history }, ... ]
|
|
436
|
+
### Development
|
|
296
437
|
|
|
297
|
-
|
|
298
|
-
|
|
438
|
+
```bash
|
|
439
|
+
# Using tsx for development
|
|
440
|
+
npx tsx watch src/index.ts
|
|
441
|
+
|
|
442
|
+
# Or with nodemon
|
|
443
|
+
npx nodemon --exec tsx src/index.ts
|
|
299
444
|
```
|
|
300
445
|
|
|
301
|
-
|
|
446
|
+
### Production
|
|
447
|
+
|
|
448
|
+
```bash
|
|
449
|
+
# Build your TypeScript
|
|
450
|
+
npx tsc
|
|
302
451
|
|
|
303
|
-
|
|
452
|
+
# Run the compiled JavaScript
|
|
453
|
+
node dist/index.js
|
|
454
|
+
```
|
|
304
455
|
|
|
305
|
-
|
|
456
|
+
### Example Scripts (package.json)
|
|
306
457
|
|
|
307
|
-
```
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
458
|
+
```json
|
|
459
|
+
{
|
|
460
|
+
"scripts": {
|
|
461
|
+
"dev": "tsx watch src/index.ts",
|
|
462
|
+
"build": "tsc",
|
|
463
|
+
"start": "node dist/index.js",
|
|
464
|
+
"test": "vitest"
|
|
312
465
|
}
|
|
313
|
-
})
|
|
314
|
-
createUser(req: Request, res: Response) {
|
|
315
|
-
return this.created(res, req.body);
|
|
316
466
|
}
|
|
317
467
|
```
|
|
318
468
|
|
|
319
|
-
|
|
469
|
+
## 📁 Project Structure
|
|
470
|
+
|
|
471
|
+
```
|
|
472
|
+
src/
|
|
473
|
+
├── controllers/ # HTTP controllers
|
|
474
|
+
│ ├── user.controller.ts
|
|
475
|
+
│ └── auth.controller.ts
|
|
476
|
+
├── services/ # Business logic services
|
|
477
|
+
│ ├── user.service.ts
|
|
478
|
+
│ └── auth.service.ts
|
|
479
|
+
├── middlewares/ # Custom middlewares
|
|
480
|
+
│ ├── logging.middleware.ts
|
|
481
|
+
│ └── auth.middleware.ts
|
|
482
|
+
├── plugins/ # Application plugins
|
|
483
|
+
│ └── database.plugin.ts
|
|
484
|
+
├── types/ # Type definitions
|
|
485
|
+
│ └── user.types.ts
|
|
486
|
+
├── modules/ # Application modules
|
|
487
|
+
│ ├── user.module.ts
|
|
488
|
+
│ └── auth.module.ts
|
|
489
|
+
└── index.ts # Application entry point
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
## 📚 API Reference
|
|
493
|
+
|
|
494
|
+
### Decorators
|
|
495
|
+
|
|
496
|
+
- `@KickController(path)` - Define a controller class
|
|
497
|
+
- `@KickGet(path)` - HTTP GET route
|
|
498
|
+
- `@KickPost(path)` - HTTP POST route
|
|
499
|
+
- `@KickPut(path)` - HTTP PUT route
|
|
500
|
+
- `@KickPatch(path)` - HTTP PATCH route
|
|
501
|
+
- `@KickDelete(path)` - HTTP DELETE route
|
|
502
|
+
- `@KickMiddleware(options)` - Define a middleware class
|
|
503
|
+
- `@KickInject(token)` - Inject dependencies
|
|
504
|
+
- `@KickInjectable()` - Mark class as injectable service
|
|
505
|
+
- `@AutoBind` - Automatically bind class methods
|
|
506
|
+
|
|
507
|
+
### Core Functions
|
|
508
|
+
|
|
509
|
+
- `createKickApp(options)` - Create a KickJS application
|
|
510
|
+
- `createModule(name, options)` - Create a module
|
|
511
|
+
- `isKickMiddleware(target)` - Check if class is a middleware
|
|
512
|
+
- `getMiddlewareMetadata(target)` - Get middleware metadata
|
|
513
|
+
|
|
514
|
+
### Types
|
|
515
|
+
|
|
516
|
+
- `KickRequestContext` - Request context interface
|
|
517
|
+
- `KickAppMiddleware` - Middleware interface
|
|
518
|
+
- `KickAppPlugin` - Plugin interface
|
|
519
|
+
- `KickApplicationContext` - Application context interface
|
|
520
|
+
|
|
521
|
+
## 🤝 Contributing
|
|
522
|
+
|
|
523
|
+
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on how to get started.
|
|
524
|
+
|
|
525
|
+
### Quick Start for Contributors
|
|
526
|
+
|
|
527
|
+
1. **Fork and clone the repository**
|
|
528
|
+
```bash
|
|
529
|
+
git clone https://github.com/yourusername/kickjs.git
|
|
530
|
+
cd kickjs
|
|
531
|
+
pnpm install
|
|
532
|
+
```
|
|
320
533
|
|
|
321
|
-
|
|
534
|
+
2. **Run tests to ensure everything works**
|
|
535
|
+
```bash
|
|
536
|
+
pnpm test
|
|
537
|
+
pnpm build
|
|
538
|
+
```
|
|
322
539
|
|
|
323
|
-
|
|
540
|
+
3. **Create a feature branch and make your changes**
|
|
541
|
+
```bash
|
|
542
|
+
git checkout -b feature/amazing-feature
|
|
543
|
+
# Make your changes...
|
|
544
|
+
git commit -m "feat: add amazing feature"
|
|
545
|
+
```
|
|
324
546
|
|
|
325
|
-
|
|
547
|
+
4. **Submit a pull request**
|
|
326
548
|
|
|
327
|
-
|
|
328
|
-
- `examples/medium-kanban` – workflow + metrics sample with the same structure (`node --loader ts-node/esm examples/medium-kanban/index.ts`).
|
|
329
|
-
- `examples/complex-analytics` – reactive event DB + aggregations with an additional `src/db/` layer (`node --loader ts-node/esm examples/complex-analytics/index.ts`).
|
|
549
|
+
For detailed guidelines, development setup, coding standards, and more, please read our [Contributing Guide](CONTRIBUTING.md).
|
|
330
550
|
|
|
331
|
-
|
|
551
|
+
### 📞 Getting Help
|
|
332
552
|
|
|
333
|
-
|
|
553
|
+
- 📖 Check the [documentation](README.md) and [examples](examples/)
|
|
554
|
+
- 🐛 Search [existing issues](https://github.com/forinda/kickjs/issues)
|
|
555
|
+
- 💬 Join our community discussions
|
|
556
|
+
- 📧 Contact maintainers for security issues
|
|
334
557
|
|
|
335
|
-
|
|
336
|
-
- `npm run build` – bundle library to `dist/`
|
|
337
|
-
- `npm run check` – type-check
|
|
338
|
-
- `npm test` – runs Vitest against the integration-style specs
|
|
558
|
+
Thank you for contributing to KickJS! 🚀
|
|
339
559
|
|
|
340
|
-
##
|
|
560
|
+
## 📄 License
|
|
341
561
|
|
|
342
|
-
|
|
562
|
+
MIT License - see [LICENSE](LICENSE) file for details.
|
|
343
563
|
|
|
344
|
-
|
|
345
|
-
2. The workflow is dispatched manually with `publish=true`.
|
|
564
|
+
---
|
|
346
565
|
|
|
347
|
-
|
|
566
|
+
**Made with ❤️ by the KickJS team**
|