@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 CHANGED
@@ -1,96 +1,67 @@
1
1
  {
2
2
  "name": "@forinda/kickjs",
3
- "version": "0.2.0",
4
- "description": "Express + TypeScript + Inversify starter with reactive state, request telemetry, and Spring Boot-style decorators.",
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
- "express",
6
+ "kickjs",
7
+ "nodejs",
41
8
  "typescript",
42
- "inversify",
9
+ "express",
43
10
  "decorators",
44
- "starter"
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
- "author": "Felix Orinda",
47
- "license": "MIT",
48
- "engines": {
49
- "node": ">=20.0"
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
- "dependencies": {
55
- "commander": "^11.1.0"
56
- },
57
- "peerDependencies": {
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": "git+https://github.com/forinda/kick-js.git"
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
- "homepage": "https://github.com/forinda/kick-js#readme"
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**