@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/LICENSE +21 -0
- package/README.md +522 -443
- package/index.d.ts +3 -0
- package/index.js +13 -0
- package/package.json +55 -71
- package/dist/cli.js +0 -1037
- package/dist/cli.js.map +0 -1
- package/dist/index.d.ts +0 -613
- package/dist/index.js +0 -882
- package/dist/index.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,566 +1,645 @@
|
|
|
1
1
|
# KickJS
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
#
|
|
24
|
-
|
|
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
|
-
|
|
29
|
+
### For contributors (link local build)
|
|
28
30
|
|
|
29
|
-
|
|
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
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
56
|
+
## Minimal Example
|
|
54
57
|
|
|
55
|
-
|
|
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/
|
|
59
|
-
import {
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
@
|
|
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
|
-
|
|
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
|
-
@
|
|
88
|
-
async
|
|
89
|
-
|
|
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
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
-
//
|
|
113
|
-
import {
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
117
|
+
## Packages
|
|
118
|
+
|
|
119
|
+
| Package | npm | Description |
|
|
120
|
+
|---------|-----|-------------|
|
|
121
|
+
| [`@forinda/kickjs-core`](packages/core/) | [](https://www.npmjs.com/package/@forinda/kickjs-core) | DI container, 20+ decorators, module system, logger |
|
|
122
|
+
| [`@forinda/kickjs-http`](packages/http/) | [](https://www.npmjs.com/package/@forinda/kickjs-http) | Express 5 app, routing, middleware, query parsing |
|
|
123
|
+
| [`@forinda/kickjs-config`](packages/config/) | [](https://www.npmjs.com/package/@forinda/kickjs-config) | Zod-based env validation, ConfigService, `@Value` |
|
|
124
|
+
| [`@forinda/kickjs-cli`](packages/cli/) | [](https://www.npmjs.com/package/@forinda/kickjs-cli) | Scaffolding, generators, `kick add`, `kick rm` |
|
|
125
|
+
| [`@forinda/kickjs-swagger`](packages/swagger/) | [](https://www.npmjs.com/package/@forinda/kickjs-swagger) | OpenAPI from decorators, Swagger UI, ReDoc |
|
|
126
|
+
| [`@forinda/kickjs-testing`](packages/testing/) | [](https://www.npmjs.com/package/@forinda/kickjs-testing) | `createTestApp`, `createTestModule` helpers |
|
|
127
|
+
| [`@forinda/kickjs-prisma`](packages/prisma/) | [](https://www.npmjs.com/package/@forinda/kickjs-prisma) | Prisma adapter (v5/6/7), PrismaModelDelegate |
|
|
128
|
+
| [`@forinda/kickjs-drizzle`](packages/drizzle/) | [](https://www.npmjs.com/package/@forinda/kickjs-drizzle) | Drizzle adapter, query builder |
|
|
129
|
+
| [`@forinda/kickjs-auth`](packages/auth/) | [](https://www.npmjs.com/package/@forinda/kickjs-auth) | JWT, API key, OAuth, `@Public`, `@Roles` |
|
|
130
|
+
| [`@forinda/kickjs-ws`](packages/ws/) | [](https://www.npmjs.com/package/@forinda/kickjs-ws) | WebSocket with `@WsController`, rooms |
|
|
131
|
+
| [`@forinda/kickjs-queue`](packages/queue/) | [](https://www.npmjs.com/package/@forinda/kickjs-queue) | BullMQ, RabbitMQ, Kafka job processing |
|
|
132
|
+
| [`@forinda/kickjs-cron`](packages/cron/) | [](https://www.npmjs.com/package/@forinda/kickjs-cron) | `@Cron` decorator, pluggable schedulers |
|
|
133
|
+
| [`@forinda/kickjs-mailer`](packages/mailer/) | [](https://www.npmjs.com/package/@forinda/kickjs-mailer) | SMTP, Resend, SES, ConsoleProvider |
|
|
134
|
+
| [`@forinda/kickjs-graphql`](packages/graphql/) | [](https://www.npmjs.com/package/@forinda/kickjs-graphql) | `@Resolver`, `@Query`, `@Mutation`, GraphiQL |
|
|
135
|
+
| [`@forinda/kickjs-otel`](packages/otel/) | [](https://www.npmjs.com/package/@forinda/kickjs-otel) | OpenTelemetry tracing and metrics |
|
|
136
|
+
| [`@forinda/kickjs-devtools`](packages/devtools/) | [](https://www.npmjs.com/package/@forinda/kickjs-devtools) | Debug dashboard at `/_debug` |
|
|
137
|
+
| [`@forinda/kickjs-notifications`](packages/notifications/) | [](https://www.npmjs.com/package/@forinda/kickjs-notifications) | Email, Slack, Discord, webhook channels |
|
|
138
|
+
| [`@forinda/kickjs-multi-tenant`](packages/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
|
-
|
|
148
|
-
import
|
|
149
|
-
import
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
}
|
|
169
|
-
|
|
170
|
-
|
|
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
|
-
|
|
204
|
+
## Decorators
|
|
174
205
|
|
|
175
|
-
|
|
206
|
+
### Class Decorators
|
|
176
207
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
-
|
|
182
|
-
kick dev --port 8080 --host 0.0.0.0
|
|
217
|
+
### Method Decorators
|
|
183
218
|
|
|
184
|
-
|
|
185
|
-
|
|
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
|
-
###
|
|
232
|
+
### Property Decorators
|
|
189
233
|
|
|
190
|
-
|
|
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
|
-
|
|
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
|
-
|
|
204
|
-
|
|
205
|
-
|
|
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
|
-
|
|
208
|
-
return this.users;
|
|
209
|
-
}
|
|
250
|
+
## Query String Parsing
|
|
210
251
|
|
|
211
|
-
|
|
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
|
-
|
|
224
|
-
|
|
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
|
-
###
|
|
230
|
-
|
|
231
|
-
Modules help organize your application by grouping related controllers, services, and middlewares.
|
|
273
|
+
### Query Format
|
|
232
274
|
|
|
233
|
-
```
|
|
234
|
-
|
|
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
|
-
|
|
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
|
-
|
|
287
|
+
**Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `contains`, `starts`, `ends`
|
|
249
288
|
|
|
250
|
-
###
|
|
289
|
+
### Custom Query Builder Adapter
|
|
251
290
|
|
|
252
|
-
|
|
291
|
+
Implement `QueryBuilderAdapter` to translate `ParsedQuery` into your ORM's query format:
|
|
253
292
|
|
|
254
293
|
```typescript
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
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
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
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
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
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
|
-
##
|
|
336
|
+
## Pluggable Schema Parser (Swagger)
|
|
331
337
|
|
|
332
|
-
|
|
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
|
-
|
|
336
|
-
import
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
365
|
+
export class RedisAdapter implements AppAdapter {
|
|
366
|
+
name = 'RedisAdapter'
|
|
367
367
|
|
|
368
|
-
|
|
368
|
+
beforeMount(app: Express, container: Container) {
|
|
369
|
+
container.registerInstance(REDIS, redisClient)
|
|
370
|
+
}
|
|
369
371
|
|
|
370
|
-
|
|
372
|
+
middleware() {
|
|
373
|
+
return [{ handler: rateLimiter(), phase: 'afterGlobal' as const }]
|
|
374
|
+
}
|
|
371
375
|
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
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
|
-
|
|
382
|
+
**Lifecycle hooks:** `beforeMount` > `middleware` (4 phases) > `beforeStart` > `afterStart` > `shutdown`
|
|
389
383
|
|
|
390
|
-
|
|
384
|
+
**Middleware phases:** `beforeGlobal` > user middleware > `afterGlobal` > module registration > `beforeRoutes` > routes > `afterRoutes`
|
|
391
385
|
|
|
392
|
-
|
|
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
|
-
|
|
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
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
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
|
-
|
|
419
|
-
|
|
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
|
-
|
|
409
|
+
## DDD Module Structure
|
|
424
410
|
|
|
425
|
-
|
|
411
|
+
Generated by `kick g module <name>`:
|
|
426
412
|
|
|
427
|
-
```
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
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
|
-
##
|
|
435
|
-
|
|
436
|
-
### Development
|
|
438
|
+
## CLI Commands
|
|
437
439
|
|
|
438
440
|
```bash
|
|
439
|
-
#
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
#
|
|
443
|
-
|
|
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
|
-
###
|
|
458
|
+
### Generator Flags
|
|
447
459
|
|
|
448
460
|
```bash
|
|
449
|
-
#
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
#
|
|
453
|
-
|
|
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
|
-
###
|
|
470
|
+
### Configuration
|
|
457
471
|
|
|
458
|
-
|
|
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
|
-
|
|
474
|
+
```typescript
|
|
475
|
+
import { defineConfig } from '@forinda/kickjs-cli'
|
|
470
476
|
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
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
|
-
|
|
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
|
-
|
|
504
|
+
## Environment Configuration
|
|
495
505
|
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
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
|
-
|
|
522
|
+
## Testing
|
|
508
523
|
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
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
|
-
|
|
548
|
+
## HMR Architecture
|
|
515
549
|
|
|
516
|
-
|
|
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
|
-
|
|
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
|
-
|
|
571
|
+
## Repository Structure
|
|
524
572
|
|
|
525
|
-
|
|
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
|
-
|
|
528
|
-
```bash
|
|
529
|
-
git clone https://github.com/yourusername/kickjs.git
|
|
530
|
-
cd kickjs
|
|
531
|
-
pnpm install
|
|
532
|
-
```
|
|
596
|
+
## Dependency Graph
|
|
533
597
|
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
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
|
-
|
|
541
|
-
|
|
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
|
-
|
|
607
|
+
## Technical Decisions
|
|
548
608
|
|
|
549
|
-
|
|
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
|
-
|
|
621
|
+
## Roadmap
|
|
552
622
|
|
|
553
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
633
|
+
## Contributing
|
|
561
634
|
|
|
562
|
-
|
|
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
|
-
|
|
645
|
+
MIT License - see [LICENSE](LICENSE) for details.
|