@forinda/kickjs 0.1.6 → 1.4.1-alpha.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/README.md CHANGED
@@ -1,566 +1,645 @@
1
1
  # KickJS
2
2
 
3
- 🚀 A modern, decorator-driven TypeScript framework built on Express with dependency injection, reactive state management, and enterprise-ready features.
3
+ A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript.
4
4
 
5
- ## ✨ Features
5
+ KickJS gives you the DX of NestJS — decorators, dependency injection, module system, code generators — without the weight. No RxJS, no class-transformer, no class-validator. Just TypeScript, Zod, and decorators.
6
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
7
+ ## Highlights
16
8
 
17
- ## 📦 Installation
9
+ - **Custom DI container** — constructor and property injection, no external dependency
10
+ - **Decorator-driven** — `@Controller`, `@Get`, `@Post`, `@Service`, `@Autowired`, `@Middleware`
11
+ - **Zod-native validation** — schemas double as OpenAPI documentation
12
+ - **Vite HMR** — zero-downtime hot reload in development, preserves DB/Redis/Socket connections
13
+ - **DDD generators** — `kick g module users` scaffolds entity, repository, service, use-cases, DTOs, controller
14
+ - **Auto OpenAPI** — Swagger UI and ReDoc generated from your decorators and Zod schemas
15
+ - **Pluggable** — adapters for database, auth, cache, swagger; schema parsers for Zod/Yup/Joi; query builders for Drizzle/Prisma/Sequelize
16
+ - **Extensible CLI** — register project-specific commands in `kick.config.ts`
17
+ - **ESM + TypeScript strict** — modern stack, tree-shakeable packages
18
+
19
+ ## Install the CLI
18
20
 
19
21
  ```bash
20
- npm install @forinda/kickjs
21
- # or
22
- pnpm add @forinda/kickjs
23
- # or
24
- yarn add @forinda/kickjs
22
+ # Global install (recommended)
23
+ pnpm add -g @forinda/kickjs-cli
24
+
25
+ # Or use npx without installing
26
+ npx @forinda/kickjs-cli new my-api
25
27
  ```
26
28
 
27
- ## 🏗️ Creating Your First App
29
+ ### For contributors (link local build)
28
30
 
29
- ### Basic Setup
31
+ ```bash
32
+ git clone https://github.com/forinda/kick-js.git
33
+ cd kick-js
34
+ pnpm install && pnpm build
35
+ cd packages/cli && pnpm link --global
36
+ ```
30
37
 
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
- });
38
+ Now `kick` uses your local build. After changes, just `pnpm build` — no re-link needed.
39
+
40
+ ## Quick Start
41
+
42
+ ```bash
43
+ # Scaffold a new project (interactive prompts for PM, git, install)
44
+ kick new my-api
45
+
46
+ # Or scaffold in the current directory
47
+ kick new .
48
+
49
+ # Start development with HMR
50
+ kick dev
51
+
52
+ # Generate a DDD module
53
+ kick g module users
51
54
  ```
52
55
 
53
- ### Creating Controllers
56
+ ## Minimal Example
54
57
 
55
- Controllers are the heart of your KickJS application. They handle HTTP requests and contain your business logic.
58
+ ```typescript
59
+ // src/index.ts
60
+ import 'reflect-metadata'
61
+ import { bootstrap } from '@forinda/kickjs-http'
62
+ import { UserModule } from './modules/users'
63
+
64
+ bootstrap({ modules: [UserModule] })
65
+ ```
56
66
 
57
67
  ```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")
68
+ // src/modules/users/presentation/user.controller.ts
69
+ import { Controller, Get, Post, Autowired } from '@forinda/kickjs-core'
70
+ import { RequestContext } from '@forinda/kickjs-http'
71
+ import { z } from 'zod'
72
+
73
+ const createUserSchema = z.object({
74
+ name: z.string().min(1),
75
+ email: z.string().email(),
76
+ })
77
+
78
+ @Controller()
69
79
  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
- }
80
+ @Autowired() private userService!: UserService
86
81
 
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
- }
82
+ @Get('/')
83
+ async list(ctx: RequestContext) {
84
+ ctx.json(await this.userService.findAll())
85
+ }
97
86
 
98
- const user = await this.userService.create(req.body);
99
- res.status(201).json({
100
- user,
101
- requestId: context.meta.requestId
102
- });
87
+ @Post('/', { body: createUserSchema })
88
+ async create(ctx: RequestContext) {
89
+ const user = await this.userService.create(ctx.body)
90
+ ctx.created(user)
103
91
  }
104
92
  }
105
93
  ```
106
94
 
107
- ### Configuration
108
-
109
- KickJS supports flexible configuration through `kick.config.ts` files. This provides type safety and prevents configuration errors.
110
-
111
95
  ```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'
96
+ // src/modules/users/index.ts
97
+ import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs-core'
98
+ import { buildRoutes } from '@forinda/kickjs-http'
99
+ import { UserController } from './presentation/user.controller'
100
+ import './domain/services/user.service'
101
+
102
+ export class UserModule implements AppModule {
103
+ register(container: Container): void {
104
+ // Bind interfaces to implementations
105
+ }
106
+
107
+ routes(): ModuleRoutes {
108
+ return {
109
+ path: '/users',
110
+ router: buildRoutes(UserController),
111
+ controller: UserController, // enables auto OpenAPI docs
139
112
  }
140
113
  }
141
- });
114
+ }
142
115
  ```
143
116
 
144
- #### Using Configuration in Your App
117
+ ## Packages
118
+
119
+ | Package | npm | Description |
120
+ |---------|-----|-------------|
121
+ | [`@forinda/kickjs-core`](packages/core/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-core)](https://www.npmjs.com/package/@forinda/kickjs-core) | DI container, 20+ decorators, module system, logger |
122
+ | [`@forinda/kickjs-http`](packages/http/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-http)](https://www.npmjs.com/package/@forinda/kickjs-http) | Express 5 app, routing, middleware, query parsing |
123
+ | [`@forinda/kickjs-config`](packages/config/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-config)](https://www.npmjs.com/package/@forinda/kickjs-config) | Zod-based env validation, ConfigService, `@Value` |
124
+ | [`@forinda/kickjs-cli`](packages/cli/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-cli)](https://www.npmjs.com/package/@forinda/kickjs-cli) | Scaffolding, generators, `kick add`, `kick rm` |
125
+ | [`@forinda/kickjs-swagger`](packages/swagger/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-swagger)](https://www.npmjs.com/package/@forinda/kickjs-swagger) | OpenAPI from decorators, Swagger UI, ReDoc |
126
+ | [`@forinda/kickjs-testing`](packages/testing/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-testing)](https://www.npmjs.com/package/@forinda/kickjs-testing) | `createTestApp`, `createTestModule` helpers |
127
+ | [`@forinda/kickjs-prisma`](packages/prisma/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-prisma)](https://www.npmjs.com/package/@forinda/kickjs-prisma) | Prisma adapter (v5/6/7), PrismaModelDelegate |
128
+ | [`@forinda/kickjs-drizzle`](packages/drizzle/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-drizzle)](https://www.npmjs.com/package/@forinda/kickjs-drizzle) | Drizzle adapter, query builder |
129
+ | [`@forinda/kickjs-auth`](packages/auth/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-auth)](https://www.npmjs.com/package/@forinda/kickjs-auth) | JWT, API key, OAuth, `@Public`, `@Roles` |
130
+ | [`@forinda/kickjs-ws`](packages/ws/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-ws)](https://www.npmjs.com/package/@forinda/kickjs-ws) | WebSocket with `@WsController`, rooms |
131
+ | [`@forinda/kickjs-queue`](packages/queue/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-queue)](https://www.npmjs.com/package/@forinda/kickjs-queue) | BullMQ, RabbitMQ, Kafka job processing |
132
+ | [`@forinda/kickjs-cron`](packages/cron/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-cron)](https://www.npmjs.com/package/@forinda/kickjs-cron) | `@Cron` decorator, pluggable schedulers |
133
+ | [`@forinda/kickjs-mailer`](packages/mailer/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-mailer)](https://www.npmjs.com/package/@forinda/kickjs-mailer) | SMTP, Resend, SES, ConsoleProvider |
134
+ | [`@forinda/kickjs-graphql`](packages/graphql/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-graphql)](https://www.npmjs.com/package/@forinda/kickjs-graphql) | `@Resolver`, `@Query`, `@Mutation`, GraphiQL |
135
+ | [`@forinda/kickjs-otel`](packages/otel/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-otel)](https://www.npmjs.com/package/@forinda/kickjs-otel) | OpenTelemetry tracing and metrics |
136
+ | [`@forinda/kickjs-devtools`](packages/devtools/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-devtools)](https://www.npmjs.com/package/@forinda/kickjs-devtools) | Debug dashboard at `/_debug` |
137
+ | [`@forinda/kickjs-notifications`](packages/notifications/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-notifications)](https://www.npmjs.com/package/@forinda/kickjs-notifications) | Email, Slack, Discord, webhook channels |
138
+ | [`@forinda/kickjs-multi-tenant`](packages/multi-tenant/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-multi-tenant)](https://www.npmjs.com/package/@forinda/kickjs-multi-tenant) | Tenant resolution middleware |
139
+
140
+ ## Bundle Sizes
141
+
142
+ All packages ship minified ESM with no sourcemaps. External dependencies (Express, Zod, Pino, etc.) are never bundled — only framework code is included.
143
+
144
+ | Package | JS Bundle | Description |
145
+ |---------|-----------|-------------|
146
+ | `@forinda/kickjs-core` | **13.9 kB** | DI container, decorators, module system, logger |
147
+ | `@forinda/kickjs-http` | **22.7 kB** | Express 5 app, routing, middleware, query parsing |
148
+ | `@forinda/kickjs-config` | **2.6 kB** | Zod-based env validation, ConfigService |
149
+ | `@forinda/kickjs-swagger` | **9.2 kB** | OpenAPI spec generation, Swagger UI, ReDoc |
150
+ | `@forinda/kickjs-cli` | **221.6 kB** | Project scaffolding, DDD generators, CLAUDE.md/AGENTS.md generation |
151
+ | `@forinda/kickjs-testing` | **0.7 kB** | `createTestApp`, `createTestModule` helpers |
152
+ | `@forinda/kickjs-auth` | **8.0 kB** | JWT/API key strategies, auth guards |
153
+ | `@forinda/kickjs-prisma` | **2.4 kB** | Prisma adapter, PrismaModelDelegate, query builder |
154
+ | `@forinda/kickjs-drizzle` | **4.1 kB** | Drizzle adapter, query builder |
155
+ | `@forinda/kickjs-ws` | **6.3 kB** | WebSocket adapter with decorators |
156
+ | `@forinda/kickjs-queue` | **8.0 kB** | BullMQ/AMQP/Kafka job processing |
157
+ | `@forinda/kickjs-graphql` | **4.4 kB** | GraphQL adapter |
158
+ | `@forinda/kickjs-mailer` | **4.3 kB** | Pluggable email transports |
159
+ | `@forinda/kickjs-cron` | **3.4 kB** | Scheduled task runner |
160
+ | `@forinda/kickjs-otel` | **2.6 kB** | OpenTelemetry tracing/metrics |
161
+ | `@forinda/kickjs-devtools` | **6.0 kB** | Dev dashboard adapter |
162
+ | `@forinda/kickjs-notifications` | **2.9 kB** | Notification channels |
163
+ | `@forinda/kickjs-multi-tenant` | **1.4 kB** | Multi-tenancy middleware |
164
+
165
+ > **Total framework JS:** ~276 kB minified (core + http + config + swagger). A typical app using core, http, config, and swagger ships under 50 kB of framework code — the rest is your application logic.
166
+
167
+ ## Full-Featured Bootstrap
145
168
 
146
169
  ```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();
170
+ import 'reflect-metadata'
171
+ import express from 'express'
172
+ import helmet from 'helmet'
173
+ import cors from 'cors'
174
+ import compression from 'compression'
175
+ import { bootstrap, requestId } from '@forinda/kickjs-http'
176
+ import { SwaggerAdapter } from '@forinda/kickjs-swagger'
177
+ import { modules } from './modules'
178
+
179
+ bootstrap({
180
+ modules,
181
+ apiPrefix: '/api',
182
+ defaultVersion: 1,
183
+ trustProxy: true,
184
+
185
+ adapters: [
186
+ new HealthAdapter(),
187
+ new DatabaseAdapter({ url: process.env.DATABASE_URL }),
188
+ new SwaggerAdapter({
189
+ info: { title: 'My API', version: '1.0.0' },
190
+ bearerAuth: true,
191
+ }),
192
+ ],
193
+
194
+ middleware: [
195
+ requestId(),
196
+ helmet(),
197
+ cors({ origin: process.env.CORS_ORIGIN }),
198
+ compression(),
199
+ express.json({ limit: '1mb' }),
200
+ ],
201
+ })
171
202
  ```
172
203
 
173
- #### CLI Configuration Support
204
+ ## Decorators
174
205
 
175
- The KickJS CLI automatically loads your configuration:
206
+ ### Class Decorators
176
207
 
177
- ```bash
178
- # Uses config file values
179
- kick dev
208
+ | Decorator | Purpose |
209
+ |-----------|---------|
210
+ | `@Injectable()` | Mark a class for DI registration |
211
+ | `@Service()` | Semantic alias for business logic |
212
+ | `@Repository()` | Semantic alias for data access |
213
+ | `@Controller(path?)` | HTTP controller with optional route prefix |
214
+ | `@Configuration()` | Factory class for `@Bean` methods |
215
+ | `@Component()` | Generic managed component |
180
216
 
181
- # Override specific values
182
- kick dev --port 8080 --host 0.0.0.0
217
+ ### Method Decorators
183
218
 
184
- # Production mode
185
- kick start --port 3000
186
- ```
219
+ | Decorator | Purpose |
220
+ |-----------|---------|
221
+ | `@Get(path?, validation?)` | HTTP GET route |
222
+ | `@Post(path?, validation?)` | HTTP POST route with optional Zod body/query/params validation |
223
+ | `@Put(path?, validation?)` | HTTP PUT route |
224
+ | `@Delete(path?, validation?)` | HTTP DELETE route |
225
+ | `@Patch(path?, validation?)` | HTTP PATCH route |
226
+ | `@Bean(options?)` | Factory method inside `@Configuration` |
227
+ | `@PostConstruct()` | Lifecycle hook called after instantiation |
228
+ | `@Transactional()` | Wrap method in DB transaction (auto commit/rollback) |
229
+ | `@Middleware(...handlers)` | Attach middleware to class or method |
230
+ | `@FileUpload(config)` | Configure file upload handling |
187
231
 
188
- ### Creating Services
232
+ ### Property Decorators
189
233
 
190
- Services contain your business logic and can be injected into controllers and other services.
234
+ | Decorator | Purpose |
235
+ |-----------|---------|
236
+ | `@Autowired(token?)` | Lazy property injection from container |
237
+ | `@Inject(token)` | Constructor parameter injection with explicit token |
238
+ | `@Value(envKey, default?)` | Inject environment variable (throws if missing with no default) |
191
239
 
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
- }
240
+ ### Swagger Decorators
202
241
 
203
- @KickInjectable()
204
- export class UserService {
205
- private users: User[] = [];
242
+ | Decorator | Purpose |
243
+ |-----------|---------|
244
+ | `@ApiTags(...tags)` | Tag controller or method |
245
+ | `@ApiOperation({ summary })` | Describe an endpoint |
246
+ | `@ApiResponse({ status, description, schema? })` | Document response (stackable) |
247
+ | `@ApiBearerAuth()` | Mark as requiring auth |
248
+ | `@ApiExclude()` | Hide from OpenAPI spec |
206
249
 
207
- async findAll(): Promise<User[]> {
208
- return this.users;
209
- }
250
+ ## Query String Parsing
210
251
 
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
- }
252
+ Built-in ORM-agnostic query parser supporting filtering, sorting, pagination, and full-text search.
222
253
 
223
- async findById(id: string): Promise<User | undefined> {
224
- return this.users.find(user => user.id === id);
225
- }
254
+ ```typescript
255
+ @Get('/')
256
+ async list(ctx: RequestContext) {
257
+ const parsed = ctx.qs({
258
+ filterable: ['status', 'priority'],
259
+ sortable: ['createdAt', 'title'],
260
+ searchable: ['title', 'description'],
261
+ })
262
+
263
+ // Pass to your ORM query builder adapter
264
+ const q = drizzleAdapter.build(parsed, { columns, searchColumns })
265
+ const rows = await db.select().from(todos)
266
+ .where(q.where).orderBy(...q.orderBy)
267
+ .limit(q.limit).offset(q.offset)
268
+
269
+ ctx.json(rows)
226
270
  }
227
271
  ```
228
272
 
229
- ### Creating Modules
230
-
231
- Modules help organize your application by grouping related controllers, services, and middlewares.
273
+ ### Query Format
232
274
 
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
243
- });
275
+ ```
276
+ GET /api/v1/todos?page=2&limit=25&q=urgent&filter=status:eq:active&filter=priority:gte:3&sort=createdAt:desc
244
277
  ```
245
278
 
246
- ## 🛠️ Creating Middlewares
279
+ | Parameter | Format | Example |
280
+ |-----------|--------|---------|
281
+ | `page` | Number (default: 1) | `?page=2` |
282
+ | `limit` | Number (default: 20, max: 100) | `?limit=50` |
283
+ | `q` | Search string | `?q=hello` |
284
+ | `filter` | `field:operator:value` (repeatable) | `?filter=status:eq:active` |
285
+ | `sort` | `field:asc\|desc` (repeatable) | `?sort=name:asc` |
247
286
 
248
- KickJS supports two types of middlewares: global middlewares and DI-managed middlewares.
287
+ **Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `contains`, `starts`, `ends`
249
288
 
250
- ### DI-Managed Middlewares (Recommended)
289
+ ### Custom Query Builder Adapter
251
290
 
252
- These middlewares are managed by the dependency injection container and can inject services.
291
+ Implement `QueryBuilderAdapter` to translate `ParsedQuery` into your ORM's query format:
253
292
 
254
293
  ```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";
265
-
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();
294
+ import { type QueryBuilderAdapter, type ParsedQuery } from '@forinda/kickjs-http'
295
+
296
+ // Prisma adapter
297
+ class PrismaQueryAdapter implements QueryBuilderAdapter<PrismaQuery, PrismaConfig> {
298
+ name = 'prisma'
299
+ build(parsed: ParsedQuery, config: PrismaConfig): PrismaQuery {
300
+ return {
301
+ where: buildPrismaWhere(parsed.filters, config.fieldMap),
302
+ orderBy: parsed.sort.map(s => ({ [s.field]: s.direction })),
303
+ skip: parsed.pagination.offset,
304
+ take: parsed.pagination.limit,
305
+ }
289
306
  }
290
307
  }
291
- ```
292
-
293
- ### Global Middlewares
294
308
 
295
- Global middlewares are not managed by DI and are useful for framework-level concerns like CORS.
296
-
297
- ```typescript
298
- // src/middlewares/cors.middleware.ts
299
- import { KickAppMiddleware, KickRequest, KickResponse, KickNextFn } from "@forinda/kickjs";
300
-
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;
309
+ // Sequelize adapter
310
+ class SequelizeQueryAdapter implements QueryBuilderAdapter<SequelizeQuery, SequelizeConfig> {
311
+ name = 'sequelize'
312
+ build(parsed: ParsedQuery, config: SequelizeConfig): SequelizeQuery {
313
+ return {
314
+ where: buildSequelizeWhere(parsed.filters, config.columns),
315
+ order: parsed.sort.map(s => [s.field, s.direction.toUpperCase()]),
316
+ offset: parsed.pagination.offset,
317
+ limit: parsed.pagination.limit,
310
318
  }
311
-
312
- next();
313
319
  }
314
320
  }
315
- ```
316
321
 
317
- Register global middlewares when creating your app:
318
-
319
- ```typescript
320
- const corsMiddleware = new CorsMiddleware();
321
-
322
- const server = createKickApp({
323
- name: "MyApp",
324
- app,
325
- globalMiddlewares: [corsMiddleware], // Global middlewares
326
- modules: [AppModule] // DI-managed middlewares are in modules
327
- });
322
+ // Drizzle adapter
323
+ class DrizzleQueryAdapter implements QueryBuilderAdapter<DrizzleQuery, DrizzleConfig> {
324
+ name = 'drizzle'
325
+ build(parsed: ParsedQuery, config: DrizzleConfig): DrizzleQuery {
326
+ return {
327
+ where: buildDrizzleWhere(parsed.filters, config.columns),
328
+ orderBy: buildDrizzleSort(parsed.sort, config.columns),
329
+ limit: parsed.pagination.limit,
330
+ offset: parsed.pagination.offset,
331
+ }
332
+ }
333
+ }
328
334
  ```
329
335
 
330
- ## 🔌 Creating Plugins
336
+ ## Pluggable Schema Parser (Swagger)
331
337
 
332
- Plugins allow you to extend the application context during initialization.
338
+ Swagger uses Zod by default to convert validation schemas into OpenAPI JSON Schema. Override for Yup, Joi, Valibot, ArkType, or any other validation library:
333
339
 
334
340
  ```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
- }
341
+ import Joi from 'joi'
342
+ import joiToJson from 'joi-to-json'
343
+ import { type SchemaParser, SwaggerAdapter } from '@forinda/kickjs-swagger'
344
+
345
+ const joiParser: SchemaParser = {
346
+ name: 'joi',
347
+ supports: (schema) => Joi.isSchema(schema),
348
+ toJsonSchema: (schema) => joiToJson(schema),
350
349
  }
350
+
351
+ new SwaggerAdapter({
352
+ info: { title: 'My API', version: '1.0.0' },
353
+ schemaParser: joiParser,
354
+ })
351
355
  ```
352
356
 
353
- Use plugins in your app:
357
+ ## Adapter Pattern
358
+
359
+ Adapters hook into the application lifecycle to add functionality like database connections, auth, caching, or documentation.
354
360
 
355
361
  ```typescript
356
- const dbPlugin = new DatabasePlugin();
357
-
358
- const server = createKickApp({
359
- name: "MyApp",
360
- app,
361
- plugins: [dbPlugin],
362
- modules: [AppModule]
363
- });
364
- ```
362
+ import { type AppAdapter, type Container } from '@forinda/kickjs-core'
363
+ import type { Express } from 'express'
365
364
 
366
- ## 🎯 Advanced Features
365
+ export class RedisAdapter implements AppAdapter {
366
+ name = 'RedisAdapter'
367
367
 
368
- ### Request Context
368
+ beforeMount(app: Express, container: Container) {
369
+ container.registerInstance(REDIS, redisClient)
370
+ }
369
371
 
370
- Every controller method receives a `KickRequestContext` with rich metadata:
372
+ middleware() {
373
+ return [{ handler: rateLimiter(), phase: 'afterGlobal' as const }]
374
+ }
371
375
 
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
- };
376
+ async shutdown() {
377
+ await redisClient.quit()
378
+ }
385
379
  }
386
380
  ```
387
381
 
388
- ### Reactive State Management
382
+ **Lifecycle hooks:** `beforeMount` > `middleware` (4 phases) > `beforeStart` > `afterStart` > `shutdown`
389
383
 
390
- KickApp includes reactive state management:
384
+ **Middleware phases:** `beforeGlobal` > user middleware > `afterGlobal` > module registration > `beforeRoutes` > routes > `afterRoutes`
391
385
 
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
- ```
386
+ ## Module System
404
387
 
405
- ### Event System
406
-
407
- Listen to application events:
388
+ Modules encapsulate a feature domain. Each module registers its dependencies and declares its routes.
408
389
 
409
390
  ```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
- });
391
+ export class OrderModule implements AppModule {
392
+ register(container: Container): void {
393
+ container.registerFactory(ORDER_REPOSITORY, () =>
394
+ container.resolve(DrizzleOrderRepository),
395
+ )
396
+ }
417
397
 
418
- server.kickApp.on('controller:mapped', (controller) => {
419
- console.log(`Controller mapped: ${controller.controller}`);
420
- });
398
+ routes(): ModuleRoutes {
399
+ return {
400
+ path: '/orders',
401
+ version: 2, // mounts at /api/v2/orders
402
+ router: buildRoutes(OrderController),
403
+ controller: OrderController,
404
+ }
405
+ }
406
+ }
421
407
  ```
422
408
 
423
- ### Error Handling
409
+ ## DDD Module Structure
424
410
 
425
- Add global error handlers:
411
+ Generated by `kick g module <name>`:
426
412
 
427
- ```typescript
428
- server.addErrorHandler((errorData) => {
429
- console.error('Application error:', errorData);
430
- // Send to logging service, etc.
431
- });
413
+ ```
414
+ src/modules/<name>/
415
+ presentation/
416
+ <name>.controller.ts
417
+ domain/
418
+ entities/<name>.entity.ts
419
+ value-objects/<name>-id.vo.ts
420
+ repositories/<name>.repository.ts # interface + DI token
421
+ services/<name>-domain.service.ts
422
+ application/
423
+ use-cases/
424
+ create-<name>.use-case.ts
425
+ list-<names>.use-case.ts
426
+ get-<name>.use-case.ts
427
+ update-<name>.use-case.ts
428
+ delete-<name>.use-case.ts
429
+ dtos/
430
+ create-<name>.dto.ts
431
+ update-<name>.dto.ts
432
+ infrastructure/
433
+ repositories/
434
+ in-memory-<name>.repository.ts
435
+ index.ts # module definition
432
436
  ```
433
437
 
434
- ## 🚀 Running Your Application
435
-
436
- ### Development
438
+ ## CLI Commands
437
439
 
438
440
  ```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
441
+ # Project lifecycle
442
+ kick new <project-name> # Scaffold new project
443
+ kick dev # Dev server with Vite HMR
444
+ kick build # Production build via Vite
445
+ kick start # Run production build
446
+ kick info # Print versions and environment
447
+
448
+ # Code generation
449
+ kick g module <name> # Full DDD module scaffold
450
+ kick g controller <name> # Single controller
451
+ kick g service <name> # Service class
452
+ kick g middleware <name> # Middleware handler
453
+ kick g guard <name> # Auth guard
454
+ kick g adapter <name> # Lifecycle adapter
455
+ kick g dto <name> # DTO with Zod schema
444
456
  ```
445
457
 
446
- ### Production
458
+ ### Generator Flags
447
459
 
448
460
  ```bash
449
- # Build your TypeScript
450
- npx tsc
451
-
452
- # Run the compiled JavaScript
453
- node dist/index.js
461
+ kick g module users --no-entity # Skip entity/value objects
462
+ kick g module users --no-tests # Skip test files
463
+ kick g module users --minimal # Only index.ts + controller
464
+ kick g module users --dry-run # Preview without writing
465
+ kick g module users --repo prisma # Prisma repository (working code)
466
+ kick g module users --repo drizzle # Drizzle repository (working code)
467
+ kick g module users --no-pluralize # Singular: src/modules/user/
454
468
  ```
455
469
 
456
- ### Example Scripts (package.json)
470
+ ### Configuration
457
471
 
458
- ```json
459
- {
460
- "scripts": {
461
- "dev": "tsx watch src/index.ts",
462
- "build": "tsc",
463
- "start": "node dist/index.js",
464
- "test": "vitest"
465
- }
466
- }
467
- ```
472
+ Configure module generation, custom commands, and more in `kick.config.ts`:
468
473
 
469
- ## 📁 Project Structure
474
+ ```typescript
475
+ import { defineConfig } from '@forinda/kickjs-cli'
470
476
 
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
- ```
477
+ export default defineConfig({
478
+ pattern: 'ddd',
479
+
480
+ // Module generation settings
481
+ modules: {
482
+ dir: 'src/modules',
483
+ repo: 'prisma', // 'drizzle' | 'inmemory' | 'prisma' | { name: 'custom' }
484
+ pluralize: true, // false → singular folder/route names
485
+ schemaDir: 'prisma/',
486
+ },
491
487
 
492
- ## 📚 API Reference
488
+ // Custom CLI commands — the whole team uses kick db:migrate etc.
489
+ commands: [
490
+ {
491
+ name: 'db:migrate',
492
+ description: 'Run database migrations',
493
+ steps: 'npx prisma migrate dev',
494
+ },
495
+ {
496
+ name: 'db:seed',
497
+ description: 'Seed the database',
498
+ steps: 'npx prisma db seed',
499
+ },
500
+ ],
501
+ })
502
+ ```
493
503
 
494
- ### Decorators
504
+ ## Environment Configuration
495
505
 
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
+ ```typescript
507
+ import { defineEnv, loadEnv } from '@forinda/kickjs-config'
508
+ import { z } from 'zod'
509
+
510
+ const envSchema = defineEnv((base) =>
511
+ base.extend({
512
+ DATABASE_URL: z.string().url(),
513
+ JWT_SECRET: z.string().min(32),
514
+ REDIS_URL: z.string().url().optional(),
515
+ }),
516
+ )
517
+
518
+ // Validates on first call — throws with clear errors on misconfiguration
519
+ const env = loadEnv(envSchema)
520
+ ```
506
521
 
507
- ### Core Functions
522
+ ## Testing
508
523
 
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
524
+ ```typescript
525
+ import { createTestApp, createTestModule } from '@forinda/kickjs-testing'
526
+ import { describe, it, expect } from 'vitest'
527
+ import supertest from 'supertest'
528
+
529
+ describe('TodoController', () => {
530
+ it('creates a todo', async () => {
531
+ const { expressApp } = createTestApp({
532
+ modules: [TodoModule],
533
+ overrides: {
534
+ [TODO_REPOSITORY]: new InMemoryTodoRepository(),
535
+ },
536
+ })
537
+
538
+ const res = await supertest(expressApp)
539
+ .post('/api/v1/todos')
540
+ .send({ title: 'Write tests' })
541
+
542
+ expect(res.status).toBe(201)
543
+ expect(res.body.title).toBe('Write tests')
544
+ })
545
+ })
546
+ ```
513
547
 
514
- ### Types
548
+ ## HMR Architecture
515
549
 
516
- - `KickRequestContext` - Request context interface
517
- - `KickAppMiddleware` - Middleware interface
518
- - `KickAppPlugin` - Plugin interface
519
- - `KickApplicationContext` - Application context interface
550
+ `kick dev` uses `vite-node --watch` for true hot module replacement:
520
551
 
521
- ## 🤝 Contributing
552
+ ```
553
+ File change detected
554
+ |
555
+ import.meta.hot.accept()
556
+ |
557
+ main() re-executes
558
+ |
559
+ g.__app exists? --- YES -> app.rebuild()
560
+ \-- NO -> app.start()
561
+ |
562
+ rebuild():
563
+ 1. Reset DI container (fresh singletons)
564
+ 2. Create new Express app
565
+ 3. Re-run setup (middleware + routes)
566
+ 4. Swap handler on existing http.Server
567
+ |
568
+ Preserved: HTTP server, DB pool, Redis, Socket.IO, port binding
569
+ ```
522
570
 
523
- We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on how to get started.
571
+ ## Repository Structure
524
572
 
525
- ### Quick Start for Contributors
573
+ ```
574
+ kick-js/
575
+ packages/
576
+ core/ @forinda/kickjs-core
577
+ http/ @forinda/kickjs-http
578
+ config/ @forinda/kickjs-config
579
+ swagger/ @forinda/kickjs-swagger
580
+ cli/ @forinda/kickjs-cli
581
+ testing/ @forinda/kickjs-testing
582
+ examples/
583
+ jira-drizzle-api/ Full Jira clone (PostgreSQL + Drizzle)
584
+ jira-mongoose-api/ Full Jira clone (MongoDB + Mongoose)
585
+ minimal-api/ Simplest possible app
586
+ joi-api/ Joi schema parser for Swagger
587
+ graphql-api/ GraphQL with resolvers
588
+ devtools-api/ DevTools + reactive state
589
+ microservice-api/ Microservice template
590
+ otel-api/ OpenTelemetry tracing
591
+ turbo.json
592
+ pnpm-workspace.yaml
593
+ tsconfig.base.json
594
+ ```
526
595
 
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
- ```
596
+ ## Dependency Graph
533
597
 
534
- 2. **Run tests to ensure everything works**
535
- ```bash
536
- pnpm test
537
- pnpm build
538
- ```
598
+ ```
599
+ @forinda/kickjs-testing --> @forinda/kickjs-http --> @forinda/kickjs-core
600
+ ^
601
+ @forinda/kickjs-config --------------------------+
602
+ @forinda/kickjs-swagger --> @forinda/kickjs-core
539
603
 
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
- ```
604
+ @forinda/kickjs-cli (standalone -- generates code, no runtime dependency)
605
+ ```
546
606
 
547
- 4. **Submit a pull request**
607
+ ## Technical Decisions
548
608
 
549
- For detailed guidelines, development setup, coding standards, and more, please read our [Contributing Guide](CONTRIBUTING.md).
609
+ | Area | Choice | Why |
610
+ |------|--------|-----|
611
+ | DI | Custom container | Lightweight, no external dep, full control |
612
+ | Module system | ESM only | Tree-shaking, native Node.js support |
613
+ | Runtime | Node.js 20+ | LTS with native ESM |
614
+ | HTTP | Express 5 | Mature, async middleware, wide ecosystem |
615
+ | Validation | Zod | Runtime + static types, doubles as OpenAPI schema |
616
+ | Build | Vite 8 | Unified toolchain — library builds, HMR, SSR |
617
+ | Test | Vitest | ESM-native, fast, Vite-compatible |
618
+ | Logging | Pino | Fastest Node.js logger, structured JSON in prod |
619
+ | Monorepo | pnpm + Turborepo | Efficient deps, build caching |
550
620
 
551
- ### 📞 Getting Help
621
+ ## Roadmap
552
622
 
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
623
+ Key upcoming packages:
557
624
 
558
- Thank you for contributing to KickJS! 🚀
625
+ - **`@forinda/kickjs-database`** -- Drizzle adapter, transaction propagation, query builder adapter
626
+ - **`@forinda/kickjs-auth`** -- JWT/API key strategies, `@Authenticated`, `@Roles` guards
627
+ - **`@forinda/kickjs-cache`** -- `@Cacheable`/`@CacheEvict` with Redis or in-memory stores
628
+ - **`@forinda/kickjs-websocket`** -- Socket.IO with `@Gateway`/`@OnEvent` decorators
629
+ - **`@forinda/kickjs-queue`** -- BullMQ job processing with `@Worker` decorator
630
+ - **`@forinda/kickjs-mail`** -- Pluggable transports (Resend, SMTP), EJS templates
631
+ - **Plugin system** -- Third-party packages extend framework with adapters, CLI generators, Vite plugins
559
632
 
560
- ## 📄 License
633
+ ## Contributing
561
634
 
562
- MIT License - see [LICENSE](LICENSE) file for details.
635
+ ```bash
636
+ git clone https://github.com/forinda/kick-js.git
637
+ cd kick-js
638
+ pnpm install
639
+ pnpm build
640
+ pnpm test
641
+ ```
563
642
 
564
- ---
643
+ ## License
565
644
 
566
- **Made with ❤️ by the KickJS team**
645
+ MIT License - see [LICENSE](LICENSE) for details.