@forinda/kickjs 1.4.1-alpha.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,6 +1,6 @@
1
1
  {
2
2
  "name": "@forinda/kickjs",
3
- "version": "1.4.1-alpha.0",
3
+ "version": "1.5.0",
4
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.",
5
5
  "keywords": [
6
6
  "kickjs",
@@ -42,9 +42,9 @@
42
42
  "main": "index.js",
43
43
  "types": "index.d.ts",
44
44
  "dependencies": {
45
- "@forinda/kickjs-config": "1.4.1-alpha.0",
46
- "@forinda/kickjs-core": "1.4.1-alpha.0",
47
- "@forinda/kickjs-http": "1.4.1-alpha.0"
45
+ "@forinda/kickjs-core": "1.5.0",
46
+ "@forinda/kickjs-http": "1.5.0",
47
+ "@forinda/kickjs-config": "1.5.0"
48
48
  },
49
49
  "publishConfig": {
50
50
  "access": "public"
package/README.md DELETED
@@ -1,645 +0,0 @@
1
- # KickJS
2
-
3
- A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript.
4
-
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
-
7
- ## Highlights
8
-
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
20
-
21
- ```bash
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
27
- ```
28
-
29
- ### For contributors (link local build)
30
-
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
- ```
37
-
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
54
- ```
55
-
56
- ## Minimal Example
57
-
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
- ```
66
-
67
- ```typescript
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()
79
- export class UserController {
80
- @Autowired() private userService!: UserService
81
-
82
- @Get('/')
83
- async list(ctx: RequestContext) {
84
- ctx.json(await this.userService.findAll())
85
- }
86
-
87
- @Post('/', { body: createUserSchema })
88
- async create(ctx: RequestContext) {
89
- const user = await this.userService.create(ctx.body)
90
- ctx.created(user)
91
- }
92
- }
93
- ```
94
-
95
- ```typescript
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
112
- }
113
- }
114
- }
115
- ```
116
-
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
168
-
169
- ```typescript
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
- })
202
- ```
203
-
204
- ## Decorators
205
-
206
- ### Class Decorators
207
-
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 |
216
-
217
- ### Method Decorators
218
-
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 |
231
-
232
- ### Property Decorators
233
-
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) |
239
-
240
- ### Swagger Decorators
241
-
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 |
249
-
250
- ## Query String Parsing
251
-
252
- Built-in ORM-agnostic query parser supporting filtering, sorting, pagination, and full-text search.
253
-
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)
270
- }
271
- ```
272
-
273
- ### Query Format
274
-
275
- ```
276
- GET /api/v1/todos?page=2&limit=25&q=urgent&filter=status:eq:active&filter=priority:gte:3&sort=createdAt:desc
277
- ```
278
-
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` |
286
-
287
- **Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `contains`, `starts`, `ends`
288
-
289
- ### Custom Query Builder Adapter
290
-
291
- Implement `QueryBuilderAdapter` to translate `ParsedQuery` into your ORM's query format:
292
-
293
- ```typescript
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
- }
306
- }
307
- }
308
-
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,
318
- }
319
- }
320
- }
321
-
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
- }
334
- ```
335
-
336
- ## Pluggable Schema Parser (Swagger)
337
-
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:
339
-
340
- ```typescript
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),
349
- }
350
-
351
- new SwaggerAdapter({
352
- info: { title: 'My API', version: '1.0.0' },
353
- schemaParser: joiParser,
354
- })
355
- ```
356
-
357
- ## Adapter Pattern
358
-
359
- Adapters hook into the application lifecycle to add functionality like database connections, auth, caching, or documentation.
360
-
361
- ```typescript
362
- import { type AppAdapter, type Container } from '@forinda/kickjs-core'
363
- import type { Express } from 'express'
364
-
365
- export class RedisAdapter implements AppAdapter {
366
- name = 'RedisAdapter'
367
-
368
- beforeMount(app: Express, container: Container) {
369
- container.registerInstance(REDIS, redisClient)
370
- }
371
-
372
- middleware() {
373
- return [{ handler: rateLimiter(), phase: 'afterGlobal' as const }]
374
- }
375
-
376
- async shutdown() {
377
- await redisClient.quit()
378
- }
379
- }
380
- ```
381
-
382
- **Lifecycle hooks:** `beforeMount` > `middleware` (4 phases) > `beforeStart` > `afterStart` > `shutdown`
383
-
384
- **Middleware phases:** `beforeGlobal` > user middleware > `afterGlobal` > module registration > `beforeRoutes` > routes > `afterRoutes`
385
-
386
- ## Module System
387
-
388
- Modules encapsulate a feature domain. Each module registers its dependencies and declares its routes.
389
-
390
- ```typescript
391
- export class OrderModule implements AppModule {
392
- register(container: Container): void {
393
- container.registerFactory(ORDER_REPOSITORY, () =>
394
- container.resolve(DrizzleOrderRepository),
395
- )
396
- }
397
-
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
- }
407
- ```
408
-
409
- ## DDD Module Structure
410
-
411
- Generated by `kick g module <name>`:
412
-
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
436
- ```
437
-
438
- ## CLI Commands
439
-
440
- ```bash
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
456
- ```
457
-
458
- ### Generator Flags
459
-
460
- ```bash
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/
468
- ```
469
-
470
- ### Configuration
471
-
472
- Configure module generation, custom commands, and more in `kick.config.ts`:
473
-
474
- ```typescript
475
- import { defineConfig } from '@forinda/kickjs-cli'
476
-
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
- },
487
-
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
- ```
503
-
504
- ## Environment Configuration
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
- ```
521
-
522
- ## Testing
523
-
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
- ```
547
-
548
- ## HMR Architecture
549
-
550
- `kick dev` uses `vite-node --watch` for true hot module replacement:
551
-
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
- ```
570
-
571
- ## Repository Structure
572
-
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
- ```
595
-
596
- ## Dependency Graph
597
-
598
- ```
599
- @forinda/kickjs-testing --> @forinda/kickjs-http --> @forinda/kickjs-core
600
- ^
601
- @forinda/kickjs-config --------------------------+
602
- @forinda/kickjs-swagger --> @forinda/kickjs-core
603
-
604
- @forinda/kickjs-cli (standalone -- generates code, no runtime dependency)
605
- ```
606
-
607
- ## Technical Decisions
608
-
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 |
620
-
621
- ## Roadmap
622
-
623
- Key upcoming packages:
624
-
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
632
-
633
- ## Contributing
634
-
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
- ```
642
-
643
- ## License
644
-
645
- MIT License - see [LICENSE](LICENSE) for details.
package/index.d.ts DELETED
@@ -1,3 +0,0 @@
1
- export * from '@forinda/kickjs-core'
2
- export { bootstrap, RequestContext, buildRoutes } from '@forinda/kickjs-http'
3
- export { defineEnv, loadEnv, getEnv, ConfigService } from '@forinda/kickjs-config'
package/index.js DELETED
@@ -1,13 +0,0 @@
1
- /**
2
- * @forinda/kickjs — umbrella package for KickJS framework.
3
- *
4
- * This package re-exports the core framework packages for convenience.
5
- * For granular control, install individual packages:
6
- *
7
- * pnpm add @forinda/kickjs-core @forinda/kickjs-http @forinda/kickjs-config
8
- *
9
- * Full list: https://forinda.github.io/kick-js/
10
- */
11
- export * from '@forinda/kickjs-core'
12
- export { bootstrap, RequestContext, buildRoutes } from '@forinda/kickjs-http'
13
- export { defineEnv, loadEnv, getEnv, ConfigService } from '@forinda/kickjs-config'