@forinda/kickjs 3.2.0 → 4.1.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.
Files changed (193) hide show
  1. package/README.md +13 -212
  2. package/dist/adapter-6Pp4kFdM.d.mts +296 -0
  3. package/dist/adapter-6Pp4kFdM.d.mts.map +1 -0
  4. package/dist/{app-module-ERR9jhow.d.mts → app-module-Blgz4Rti.d.mts} +4 -4
  5. package/dist/app-module-Blgz4Rti.d.mts.map +1 -0
  6. package/dist/application-Bepa-pFw.d.mts +302 -0
  7. package/dist/application-Bepa-pFw.d.mts.map +1 -0
  8. package/dist/{application-x8CXLOlv.mjs → application-DvmPMUgF.mjs} +28 -9
  9. package/dist/application-DvmPMUgF.mjs.map +1 -0
  10. package/dist/bootstrap-B4T3X2B6.d.mts +28 -0
  11. package/dist/bootstrap-B4T3X2B6.d.mts.map +1 -0
  12. package/dist/{bootstrap-CYnxozL_.mjs → bootstrap-THfr8phJ.mjs} +6 -6
  13. package/dist/{bootstrap-CYnxozL_.mjs.map → bootstrap-THfr8phJ.mjs.map} +1 -1
  14. package/dist/{cache-V91BNTIM.d.mts → cache-XrNWj1KQ.d.mts} +3 -3
  15. package/dist/{cache-V91BNTIM.d.mts.map → cache-XrNWj1KQ.d.mts.map} +1 -1
  16. package/dist/config/index.d.mts +1 -1
  17. package/dist/config/index.mjs +3 -3
  18. package/dist/{config-aWxKLk4A.mjs → config-BEjgF1fI.mjs} +4 -4
  19. package/dist/{config-aWxKLk4A.mjs.map → config-BEjgF1fI.mjs.map} +1 -1
  20. package/dist/{container-Dnk43k54.mjs → container-BYuMSnqW.mjs} +314 -9
  21. package/dist/container-BYuMSnqW.mjs.map +1 -0
  22. package/dist/{container-fIS1uLx-.d.mts → container-CnWDsxi-.d.mts} +9 -7
  23. package/dist/container-CnWDsxi-.d.mts.map +1 -0
  24. package/dist/{context-OktlOQBQ.mjs → context-CyQbqSz-.mjs} +33 -41
  25. package/dist/context-CyQbqSz-.mjs.map +1 -0
  26. package/dist/context-Ymvv-85x.d.mts +260 -0
  27. package/dist/context-Ymvv-85x.d.mts.map +1 -0
  28. package/dist/{context-decorator-GA8-hDLe.d.mts → context-decorator-DrPvQ9Ag.d.mts} +62 -12
  29. package/dist/context-decorator-DrPvQ9Ag.d.mts.map +1 -0
  30. package/dist/core/adapter.d.mts +1 -1
  31. package/dist/core/adapter.mjs +1 -1
  32. package/dist/core/app-module.d.mts +1 -1
  33. package/dist/core/app-module.mjs +1 -1
  34. package/dist/core/cache.d.mts +1 -1
  35. package/dist/core/cache.mjs +3 -3
  36. package/dist/core/cache.mjs.map +1 -1
  37. package/dist/core/container.d.mts +1 -1
  38. package/dist/core/container.mjs +2 -2
  39. package/dist/core/cron.d.mts +1 -1
  40. package/dist/core/cron.mjs +3 -3
  41. package/dist/core/cron.mjs.map +1 -1
  42. package/dist/core/decorators.d.mts +2 -2
  43. package/dist/core/decorators.mjs +48 -16
  44. package/dist/core/decorators.mjs.map +1 -1
  45. package/dist/core/errors.d.mts +1 -1
  46. package/dist/core/errors.mjs +1 -1
  47. package/dist/core/interfaces.d.mts +1 -1
  48. package/dist/core/interfaces.mjs +35 -18
  49. package/dist/core/interfaces.mjs.map +1 -1
  50. package/dist/core/logger.d.mts +2 -2
  51. package/dist/core/logger.mjs +2 -4
  52. package/dist/core/logger.mjs.map +1 -1
  53. package/dist/core/path.d.mts +1 -1
  54. package/dist/core/path.mjs +1 -1
  55. package/dist/core/plugin.d.mts +1 -1
  56. package/dist/core/plugin.mjs +1 -1
  57. package/dist/core/reactivity.d.mts +1 -1
  58. package/dist/core/reactivity.mjs +1 -1
  59. package/dist/{core-DANnH5-e.mjs → core-Dj3iVQ3t.mjs} +305 -8
  60. package/dist/core-Dj3iVQ3t.mjs.map +1 -0
  61. package/dist/cors-BfgqfLPd.d.mts +48 -0
  62. package/dist/cors-BfgqfLPd.d.mts.map +1 -0
  63. package/dist/{cron-CfsPdi7R.d.mts → cron-GNoYydfg.d.mts} +2 -2
  64. package/dist/cron-GNoYydfg.d.mts.map +1 -0
  65. package/dist/csrf-DiK9zept.d.mts +52 -0
  66. package/dist/csrf-DiK9zept.d.mts.map +1 -0
  67. package/dist/{decorators-H42oPg0m.d.mts → decorators-BMvaLliz.d.mts} +147 -12
  68. package/dist/decorators-BMvaLliz.d.mts.map +1 -0
  69. package/dist/{env-Cs8Wt8A_.mjs → env-DMqv56Bb.mjs} +3 -4
  70. package/dist/{env-Cs8Wt8A_.mjs.map → env-DMqv56Bb.mjs.map} +1 -1
  71. package/dist/error-handler-Xud_3Lah.d.mts +20 -0
  72. package/dist/error-handler-Xud_3Lah.d.mts.map +1 -0
  73. package/dist/{errors-D_CWI7Bl.d.mts → errors-uaHCeXRz.d.mts} +1 -1
  74. package/dist/{errors-D_CWI7Bl.d.mts.map → errors-uaHCeXRz.d.mts.map} +1 -1
  75. package/dist/{execution-context-Dl2CKqSo.d.mts → execution-context-DKnt61pY.d.mts} +1 -1
  76. package/dist/{execution-context-Dl2CKqSo.d.mts.map → execution-context-DKnt61pY.d.mts.map} +1 -1
  77. package/dist/helmet-CaMbjzBG.d.mts +41 -0
  78. package/dist/helmet-CaMbjzBG.d.mts.map +1 -0
  79. package/dist/http/application.d.mts +2 -293
  80. package/dist/http/application.mjs +2 -2
  81. package/dist/http/bootstrap.d.mts +2 -27
  82. package/dist/http/bootstrap.mjs +2 -2
  83. package/dist/http/context.d.mts +3 -251
  84. package/dist/http/context.mjs +2 -2
  85. package/dist/http/middleware/cors.d.mts +2 -47
  86. package/dist/http/middleware/cors.mjs +1 -1
  87. package/dist/http/middleware/csrf.d.mts +2 -51
  88. package/dist/http/middleware/csrf.mjs +2 -2
  89. package/dist/http/middleware/csrf.mjs.map +1 -1
  90. package/dist/http/middleware/error-handler.d.mts +2 -19
  91. package/dist/http/middleware/error-handler.mjs +2 -2
  92. package/dist/http/middleware/helmet.d.mts +2 -40
  93. package/dist/http/middleware/helmet.mjs +1 -1
  94. package/dist/http/middleware/rate-limit.d.mts +2 -55
  95. package/dist/http/middleware/rate-limit.mjs +2 -2
  96. package/dist/http/middleware/rate-limit.mjs.map +1 -1
  97. package/dist/http/middleware/request-id.d.mts +2 -9
  98. package/dist/http/middleware/request-id.mjs +12 -3
  99. package/dist/http/middleware/request-id.mjs.map +1 -1
  100. package/dist/http/middleware/request-logger.d.mts +2 -31
  101. package/dist/http/middleware/request-logger.mjs +2 -2
  102. package/dist/http/middleware/session.d.mts +2 -69
  103. package/dist/http/middleware/session.mjs +1 -1
  104. package/dist/http/middleware/spa.d.mts +2 -100
  105. package/dist/http/middleware/spa.mjs +5 -5
  106. package/dist/http/middleware/spa.mjs.map +1 -1
  107. package/dist/http/middleware/upload.d.mts +2 -78
  108. package/dist/http/middleware/upload.mjs +1 -1
  109. package/dist/http/middleware/validate.d.mts +2 -22
  110. package/dist/http/middleware/validate.mjs +2 -2
  111. package/dist/http/middleware/views.d.mts +2 -61
  112. package/dist/http/middleware/views.mjs +16 -15
  113. package/dist/http/middleware/views.mjs.map +1 -1
  114. package/dist/http/query/index.d.mts +1 -1
  115. package/dist/http/query/index.mjs +2 -2
  116. package/dist/http/router-builder.d.mts +2 -32
  117. package/dist/http/router-builder.mjs +10 -14
  118. package/dist/http/router-builder.mjs.map +1 -1
  119. package/dist/{index-RNK41JPE.d.mts → index-B9cyOQAe.d.mts} +1 -1
  120. package/dist/{index-RNK41JPE.d.mts.map → index-B9cyOQAe.d.mts.map} +1 -1
  121. package/dist/{index-Cf-MGrqT.d.mts → index-D-qhXg9M.d.mts} +3 -3
  122. package/dist/{index-Cf-MGrqT.d.mts.map → index-D-qhXg9M.d.mts.map} +1 -1
  123. package/dist/{index-BQM9pJrV.d.mts → index-Yhs9sTMW.d.mts} +241 -5
  124. package/dist/index-Yhs9sTMW.d.mts.map +1 -0
  125. package/dist/index.d.mts +34 -152
  126. package/dist/index.mjs +50 -14
  127. package/dist/index.mjs.map +1 -1
  128. package/dist/interfaces-B50n7dwl.d.mts +71 -0
  129. package/dist/{interfaces-CwcdqfNq.d.mts.map → interfaces-B50n7dwl.d.mts.map} +1 -1
  130. package/dist/{logger-GK8yT0BD.d.mts → logger-CLVRZf2N.d.mts} +2 -4
  131. package/dist/{logger-GK8yT0BD.d.mts.map → logger-CLVRZf2N.d.mts.map} +1 -1
  132. package/dist/{metadata-BFuoSEX6.mjs → metadata-BF1WDBOh.mjs} +2 -2
  133. package/dist/{metadata-BFuoSEX6.mjs.map → metadata-BF1WDBOh.mjs.map} +1 -1
  134. package/dist/{path-Bj3vZMUY.d.mts → path-Diviu6hv.d.mts} +1 -1
  135. package/dist/path-Diviu6hv.d.mts.map +1 -0
  136. package/dist/{plugin-3rKA0Loy.d.mts → plugin-DDjoN4XI.d.mts} +46 -8
  137. package/dist/plugin-DDjoN4XI.d.mts.map +1 -0
  138. package/dist/{query-BcYEjYyX.mjs → query-BrYRQMa5.mjs} +2 -2
  139. package/dist/{query-BcYEjYyX.mjs.map → query-BrYRQMa5.mjs.map} +1 -1
  140. package/dist/rate-limit-DUwoICtI.d.mts +56 -0
  141. package/dist/rate-limit-DUwoICtI.d.mts.map +1 -0
  142. package/dist/{reactivity-CczHu3R-.d.mts → reactivity-CfJceo4H.d.mts} +1 -1
  143. package/dist/{reactivity-CczHu3R-.d.mts.map → reactivity-CfJceo4H.d.mts.map} +1 -1
  144. package/dist/request-id-BgglvZHN.d.mts +19 -0
  145. package/dist/request-id-BgglvZHN.d.mts.map +1 -0
  146. package/dist/request-logger-CWHbAzTE.d.mts +32 -0
  147. package/dist/request-logger-CWHbAzTE.d.mts.map +1 -0
  148. package/dist/router-builder-zsX4Oq7c.d.mts +31 -0
  149. package/dist/router-builder-zsX4Oq7c.d.mts.map +1 -0
  150. package/dist/session-N0hActOO.d.mts +70 -0
  151. package/dist/session-N0hActOO.d.mts.map +1 -0
  152. package/dist/spa-CwIbdvPc.d.mts +101 -0
  153. package/dist/spa-CwIbdvPc.d.mts.map +1 -0
  154. package/dist/upload-BueOnnLw.d.mts +79 -0
  155. package/dist/upload-BueOnnLw.d.mts.map +1 -0
  156. package/dist/validate-HwAyWTwH.d.mts +23 -0
  157. package/dist/validate-HwAyWTwH.d.mts.map +1 -0
  158. package/dist/views-v05_dP1I.d.mts +181 -0
  159. package/dist/views-v05_dP1I.d.mts.map +1 -0
  160. package/package.json +6 -9
  161. package/dist/adapter-DLEHb0K6.d.mts +0 -151
  162. package/dist/adapter-DLEHb0K6.d.mts.map +0 -1
  163. package/dist/app-module-ERR9jhow.d.mts.map +0 -1
  164. package/dist/application-x8CXLOlv.mjs.map +0 -1
  165. package/dist/chunk-Bt-rz0Tp.mjs +0 -15
  166. package/dist/container-Dnk43k54.mjs.map +0 -1
  167. package/dist/container-fIS1uLx-.d.mts.map +0 -1
  168. package/dist/context-OktlOQBQ.mjs.map +0 -1
  169. package/dist/context-decorator-GA8-hDLe.d.mts.map +0 -1
  170. package/dist/core-DANnH5-e.mjs.map +0 -1
  171. package/dist/cron-CfsPdi7R.d.mts.map +0 -1
  172. package/dist/decorators-H42oPg0m.d.mts.map +0 -1
  173. package/dist/http/application.d.mts.map +0 -1
  174. package/dist/http/bootstrap.d.mts.map +0 -1
  175. package/dist/http/context.d.mts.map +0 -1
  176. package/dist/http/middleware/cors.d.mts.map +0 -1
  177. package/dist/http/middleware/csrf.d.mts.map +0 -1
  178. package/dist/http/middleware/error-handler.d.mts.map +0 -1
  179. package/dist/http/middleware/helmet.d.mts.map +0 -1
  180. package/dist/http/middleware/rate-limit.d.mts.map +0 -1
  181. package/dist/http/middleware/request-id.d.mts.map +0 -1
  182. package/dist/http/middleware/request-logger.d.mts.map +0 -1
  183. package/dist/http/middleware/session.d.mts.map +0 -1
  184. package/dist/http/middleware/spa.d.mts.map +0 -1
  185. package/dist/http/middleware/upload.d.mts.map +0 -1
  186. package/dist/http/middleware/validate.d.mts.map +0 -1
  187. package/dist/http/middleware/views.d.mts.map +0 -1
  188. package/dist/http/router-builder.d.mts.map +0 -1
  189. package/dist/index-BQM9pJrV.d.mts.map +0 -1
  190. package/dist/index.d.mts.map +0 -1
  191. package/dist/interfaces-CwcdqfNq.d.mts +0 -54
  192. package/dist/path-Bj3vZMUY.d.mts.map +0 -1
  193. package/dist/plugin-3rKA0Loy.d.mts.map +0 -1
package/README.md CHANGED
@@ -1,244 +1,45 @@
1
- # KickJS
1
+ # @forinda/kickjs
2
2
 
3
- A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript.
3
+ Decorator-driven Node.js framework on Express 5 + TypeScript. Custom DI, module system, code generators, Zod-native validation, Vite HMR.
4
4
 
5
- NestJS ergonomics without the complexity — decorators, DI, module system, and code generators, powered by Zod and Vite.
6
-
7
- ## Install Manually
5
+ ## Install
8
6
 
9
7
  ```bash
10
- pnpm init
8
+ # Scaffold a new project (recommended)
9
+ npx @forinda/kickjs-cli new my-api && cd my-api && pnpm dev
10
+
11
+ # Or add to an existing project
11
12
  pnpm add @forinda/kickjs express reflect-metadata zod
12
13
  pnpm add -D @forinda/kickjs-cli
13
14
  ```
14
15
 
15
- ## Scaffold with CLI
16
-
17
- ```bash
18
- # Using npx
19
- npx @forinda/kickjs-cli new my-api
20
- # Using global install
21
- pnpm add -g @forinda/kickjs-cli
22
- kick new my-api
23
- # pnpm
24
- pnpm dlx @forinda/kickjs-cli new my-api
25
- # yarn
26
- yarn dlx @forinda/kickjs-cli new my-api
27
- ```
28
-
29
- ## Quick Start
30
-
31
- ```bash
32
- kick new my-api && cd my-api && kick dev
33
- ```
34
-
35
- ## Hello World
36
-
37
- A fresh `kick new my-api` scaffolds a complete project. Here are the files
38
- that matter, exactly as the CLI generates them:
39
-
40
- ```ts
41
- // src/modules/hello/hello.service.ts
42
- import { Service } from '@forinda/kickjs'
43
-
44
- @Service()
45
- export class HelloService {
46
- greet(name: string) {
47
- return { message: `Hello ${name} from KickJS!`, timestamp: new Date().toISOString() }
48
- }
49
-
50
- healthCheck() {
51
- return { status: 'ok', uptime: process.uptime() }
52
- }
53
- }
54
- ```
16
+ ## Quick Example
55
17
 
56
18
  ```ts
57
19
  // src/modules/hello/hello.controller.ts
58
- import { Controller, Get, Autowired, type Ctx } from '@forinda/kickjs'
59
- import { HelloService } from './hello.service'
20
+ import { Controller, Get, type RequestContext } from '@forinda/kickjs'
60
21
 
61
- @Controller()
22
+ @Controller('/hello')
62
23
  export class HelloController {
63
- @Autowired() private readonly helloService!: HelloService
64
-
65
24
  @Get('/')
66
- index(ctx: Ctx<KickRoutes.HelloController['index']>) {
67
- ctx.json(this.helloService.greet('World'))
68
- }
69
-
70
- @Get('/health')
71
- health(ctx: Ctx<KickRoutes.HelloController['health']>) {
72
- ctx.json(this.helloService.healthCheck())
73
- }
74
- }
75
- ```
76
-
77
- ```ts
78
- // src/modules/hello/hello.module.ts
79
- import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'
80
- import { HelloController } from './hello.controller'
81
-
82
- export class HelloModule implements AppModule {
83
- routes(): ModuleRoutes {
84
- return {
85
- path: '/hello',
86
- router: buildRoutes(HelloController),
87
- controller: HelloController,
88
- }
25
+ hello(ctx: RequestContext) {
26
+ ctx.json({ message: 'Hello from KickJS' })
89
27
  }
90
28
  }
91
29
  ```
92
30
 
93
- ```ts
94
- // src/modules/index.ts
95
- import type { AppModuleClass } from '@forinda/kickjs'
96
- import { HelloModule } from './hello/hello.module'
97
-
98
- export const modules: AppModuleClass[] = [HelloModule]
99
- ```
100
-
101
31
  ```ts
102
32
  // src/index.ts
103
33
  import 'reflect-metadata'
104
- import './config' // registers env schema before bootstrap
105
34
  import { bootstrap } from '@forinda/kickjs'
106
35
  import { modules } from './modules'
107
36
 
108
37
  export const app = await bootstrap({ modules })
109
38
  ```
110
39
 
111
- ## What's Included
112
-
113
- Everything you need for a production API — one import:
114
-
115
- ```typescript
116
- import {
117
- // DI + Decorators
118
- Controller, Get, Post, Put, Delete, Patch,
119
- Service, Repository, Autowired, Inject, Value, Middleware,
120
- createToken, // typed DI tokens: createToken<T>('name')
121
-
122
- // Application
123
- bootstrap, Application, buildRoutes,
124
- RequestContext, type Ctx, type RouteShape,
125
-
126
- // Middleware
127
- helmet, cors, csrf, rateLimit, requestId, requestLogger,
128
- validate, upload, session, traceContext,
129
-
130
- // Query parsing
131
- parseQuery, type QueryFieldConfig, type ParsedQuery,
132
-
133
- // Utilities
134
- Container, HttpException, createLogger,
135
- ref, computed, watch,
136
-
137
- // Types
138
- type AppAdapter, type AdapterContext, type AppModule,
139
- type MiddlewareHandler, type ModuleRoutes,
140
- } from '@forinda/kickjs'
141
- ```
142
-
143
- ## Typed Routes, Body, Query, and Env
144
-
145
- `kick typegen` (auto-runs on `kick dev`) generates `KickRoutes` and `KickEnv`
146
- from your codebase. Route handlers, request bodies, query strings, and
147
- `@Value` injections are all type-checked end-to-end:
148
-
149
- ```ts
150
- import { Controller, Post, Value, type Ctx } from '@forinda/kickjs'
151
- import { z } from 'zod'
152
-
153
- const createUserBody = z.object({ name: z.string(), email: z.string().email() })
154
-
155
- @Controller('/users')
156
- class UserController {
157
- // Typed env injection — keys come from KickEnv (your src/config/index.ts)
158
- @Value('DATABASE_URL') private dbUrl!: string
159
-
160
- @Post('/', { body: createUserBody, name: 'CreateUser' })
161
- create(ctx: Ctx<KickRoutes.UserController['create']>) {
162
- ctx.body.email // ✅ string — inferred from the Zod schema
163
- ctx.created({ id: '1', ...ctx.body })
164
- }
165
- }
166
- ```
167
-
168
- ## Typed DI Tokens
169
-
170
- ```typescript
171
- import { createToken, Inject, Service } from '@forinda/kickjs'
172
-
173
- export const USER_REPO = createToken<UserRepository>('user.repo')
174
-
175
- @Service()
176
- class UserService {
177
- constructor(@Inject(USER_REPO) private readonly repo: UserRepository) {}
178
- // repo is typed as UserRepository — no casts
179
- }
180
- ```
181
-
182
- ## Typed Adapter Hooks
183
-
184
- ```typescript
185
- import type { AppAdapter, AdapterContext } from '@forinda/kickjs'
186
-
187
- class MyAdapter implements AppAdapter {
188
- name = 'MyAdapter'
189
-
190
- beforeMount({ app, container, isProduction }: AdapterContext) {
191
- // app: Express, container: Container, isProduction: boolean
192
- app.use(myMiddleware())
193
- }
194
-
195
- afterStart({ server }: AdapterContext) {
196
- // server: http.Server — attach WebSocket, etc.
197
- }
198
-
199
- async shutdown() {
200
- await cleanup()
201
- }
202
- }
203
- ```
204
-
205
- ## Ecosystem
206
-
207
- | Package | Description |
208
- |---------|-------------|
209
- | [`@forinda/kickjs`](https://www.npmjs.com/package/@forinda/kickjs) | Core framework (DI, decorators, Express 5, middleware) |
210
- | [`@forinda/kickjs-config`](https://www.npmjs.com/package/@forinda/kickjs-config) | Zod-based env validation, ConfigService, `@Value` |
211
- | [`@forinda/kickjs-swagger`](https://www.npmjs.com/package/@forinda/kickjs-swagger) | Auto OpenAPI from decorators + Zod schemas |
212
- | [`@forinda/kickjs-cli`](https://www.npmjs.com/package/@forinda/kickjs-cli) | Scaffolding, DDD generators, custom commands |
213
- | [`@forinda/kickjs-testing`](https://www.npmjs.com/package/@forinda/kickjs-testing) | `createTestApp`, `createTestModule` |
214
- | [`@forinda/kickjs-prisma`](https://www.npmjs.com/package/@forinda/kickjs-prisma) | Prisma adapter (v5/6/7) |
215
- | [`@forinda/kickjs-drizzle`](https://www.npmjs.com/package/@forinda/kickjs-drizzle) | Drizzle adapter, query builder |
216
- | [`@forinda/kickjs-auth`](https://www.npmjs.com/package/@forinda/kickjs-auth) | JWT, API key, OAuth strategies |
217
- | [`@forinda/kickjs-ws`](https://www.npmjs.com/package/@forinda/kickjs-ws) | WebSocket with `@WsController` |
218
- | [`@forinda/kickjs-queue`](https://www.npmjs.com/package/@forinda/kickjs-queue) | BullMQ, RabbitMQ, Kafka |
219
- | [`@forinda/kickjs-cron`](https://www.npmjs.com/package/@forinda/kickjs-cron) | `@Cron` decorator scheduling |
220
- | [`@forinda/kickjs-mailer`](https://www.npmjs.com/package/@forinda/kickjs-mailer) | SMTP, Resend, SES |
221
- | [`@forinda/kickjs-graphql`](https://www.npmjs.com/package/@forinda/kickjs-graphql) | `@Resolver`, `@Query`, `@Mutation` |
222
- | [`@forinda/kickjs-otel`](https://www.npmjs.com/package/@forinda/kickjs-otel) | OpenTelemetry tracing + metrics |
223
- | [`@forinda/kickjs-devtools`](https://www.npmjs.com/package/@forinda/kickjs-devtools) | Debug dashboard at `/_debug` |
224
- | [`@forinda/kickjs-notifications`](https://www.npmjs.com/package/@forinda/kickjs-notifications) | Email, Slack, Discord, webhook |
225
- | [`@forinda/kickjs-multi-tenant`](https://www.npmjs.com/package/@forinda/kickjs-multi-tenant) | Tenant resolution middleware |
226
- | [`@forinda/kickjs-ai`](https://www.npmjs.com/package/@forinda/kickjs-ai) | Providers (OpenAI, Anthropic), `@AiTool`, memory, RAG, agent loop |
227
- | [`@forinda/kickjs-mcp`](https://www.npmjs.com/package/@forinda/kickjs-mcp) | Model Context Protocol server adapter + `kick mcp` CLI |
228
-
229
- ## CLI
230
-
231
- ```bash
232
- kick new my-api # Scaffold project
233
- kick dev # Vite HMR dev server
234
- kick build # Production build
235
- kick g module users # Generate full DDD module (18 files)
236
- kick g module users --repo prisma # With Prisma repository
237
- ```
238
-
239
40
  ## Documentation
240
41
 
241
- [forinda.github.io/kick-js](https://forinda.github.io/kick-js/)
42
+ [forinda.github.io/kick-js](https://forinda.github.io/kick-js/) — full guide, API reference, tutorials, and example apps.
242
43
 
243
44
  ## License
244
45
 
@@ -0,0 +1,296 @@
1
+
2
+ import { i as Constructor, o as MaybePromise } from "./interfaces-B50n7dwl.mjs";
3
+ import { t as Container } from "./container-CnWDsxi-.mjs";
4
+ import { o as ContributorRegistrations } from "./context-decorator-DrPvQ9Ag.mjs";
5
+ import http from "node:http";
6
+ import { Express } from "express";
7
+
8
+ //#region src/core/augmentation.d.ts
9
+ /**
10
+ * Augmentation registry — runtime no-op + the canonical
11
+ * `KickJsPluginRegistry` interface that `kick typegen` augments.
12
+ *
13
+ * See `architecture.md` §21.2.1 (typegen for `dependsOn`) and §21.3.3
14
+ * (standardized augmentation registry) for the design rationale.
15
+ *
16
+ * @module @forinda/kickjs/core/augmentation
17
+ */
18
+ /**
19
+ * Marker interface that lists every plugin/adapter in the project. The
20
+ * keys are the literal `name` field passed to `defineAdapter` /
21
+ * `definePlugin` (or declared on a `class implements AppAdapter`); the
22
+ * values are the kind tag (`'plugin' | 'adapter'`).
23
+ *
24
+ * The framework ships this empty. `kick typegen` augments it from
25
+ * source so `keyof KickJsPluginRegistry` resolves to a string-literal
26
+ * union of every name in scope — and therefore so do `dependsOn`
27
+ * declarations on plugins/adapters.
28
+ */
29
+ interface KickJsPluginRegistry {}
30
+ /**
31
+ * Resolves to a string-literal union of every registered plugin/adapter
32
+ * name when the project's typegen has populated `KickJsPluginRegistry`,
33
+ * or to `string` when the registry is empty (no typegen pass yet).
34
+ *
35
+ * Falling back to `string` keeps fresh projects compiling — the typegen
36
+ * narrowing is a progressive enhancement, not a hard prerequisite.
37
+ */
38
+ type KickJsPluginName = keyof KickJsPluginRegistry extends never ? string : keyof KickJsPluginRegistry & string;
39
+ /**
40
+ * Metadata attached to a `defineAugmentation` call. The fields are
41
+ * documentation-only — `kick typegen` surfaces them in the generated
42
+ * `.kickjs/types/augmentations.d.ts` so adopters can browse every
43
+ * augmentable interface from one place.
44
+ *
45
+ * `description` and `example` may both be multi-line — typegen preserves
46
+ * line breaks when rendering them as JSDoc. There is no upper limit on
47
+ * the example size; entire shape definitions or worked snippets are fine.
48
+ */
49
+ interface AugmentationMeta {
50
+ /**
51
+ * Free-form description of what the augmentation customises. May be
52
+ * multi-line — newlines are preserved in the generated JSDoc.
53
+ */
54
+ description?: string;
55
+ /**
56
+ * TS snippet showing a typical shape. May be multi-line; rendered
57
+ * inside a fenced code block in the generated catalogue. Use this
58
+ * for anything from `'{ foo: string }'` up to a full interface body
59
+ * — typegen no longer flattens newlines.
60
+ */
61
+ example?: string;
62
+ }
63
+ /**
64
+ * Advertise an augmentable interface so `kick typegen` can list it in
65
+ * `.kickjs/types/augmentations.d.ts` for project-wide discovery.
66
+ *
67
+ * **This function is a runtime AND type-level no-op.** It does NOT
68
+ * augment the interface for TypeScript. The actual augmentation is
69
+ * the `declare module` block — `defineAugmentation` only adds an
70
+ * entry to the typegen catalogue so other contributors / adopters
71
+ * can find the interface and know its expected shape.
72
+ *
73
+ * Both calls are needed:
74
+ *
75
+ * ```ts
76
+ * import { defineAugmentation } from '@forinda/kickjs'
77
+ *
78
+ * // (1) The actual TS augmentation — what `ctx.get('tenant')` reads.
79
+ * declare module '@forinda/kickjs' {
80
+ * interface ContextMeta {
81
+ * tenant: { id: string; name: string }
82
+ * }
83
+ * }
84
+ *
85
+ * // (2) Catalogue entry — what `kick typegen` lists in
86
+ * // `.kickjs/types/augmentations.d.ts` for browseability.
87
+ * defineAugmentation('ContextMeta', {
88
+ * description: 'Tenant resolved from x-tenant-id by TenantAdapter',
89
+ * example: `{
90
+ * tenant: {
91
+ * id: string
92
+ * name: string
93
+ * plan: 'free' | 'pro' | 'enterprise'
94
+ * featureFlags: Record<string, boolean>
95
+ * }
96
+ * }`,
97
+ * })
98
+ * ```
99
+ *
100
+ * Skip `defineAugmentation` if you don't care about the catalogue — the
101
+ * `declare module` block alone is enough for runtime + type behaviour.
102
+ */
103
+ declare function defineAugmentation(name: string, meta?: AugmentationMeta): void;
104
+ //#endregion
105
+ //#region src/core/adapter.d.ts
106
+ /**
107
+ * Where in the middleware pipeline an adapter's middleware should be inserted.
108
+ *
109
+ * beforeGlobal → runs before any user-defined global middleware
110
+ * afterGlobal → runs after global middleware, before module routes
111
+ * beforeRoutes → just before module routes are mounted
112
+ * afterRoutes → after module routes but before error handlers
113
+ */
114
+ type MiddlewarePhase = 'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes';
115
+ /** A middleware entry contributed by an adapter */
116
+ interface AdapterMiddleware {
117
+ /** Express-compatible handler: (req, res, next) => void */
118
+ handler: any;
119
+ /** Which phase to insert into (default: 'afterGlobal') */
120
+ phase?: MiddlewarePhase;
121
+ /** Optional path to scope the middleware to (e.g. '/api/v1/auth') */
122
+ path?: string;
123
+ }
124
+ /**
125
+ * Context passed to adapter lifecycle hooks.
126
+ * Populated by the Application — provides access to the Express app,
127
+ * DI container, http.Server, and environment info without requiring
128
+ * external type imports. Cast `app` or `server` if you need specific types.
129
+ *
130
+ * @example
131
+ * ```ts
132
+ * beforeMount({ app, container }: AdapterContext) {
133
+ * app.use(myMiddleware())
134
+ * }
135
+ * ```
136
+ */
137
+ interface AdapterContext {
138
+ /** Express application instance — fully typed */
139
+ app: Express;
140
+ /** DI container */
141
+ container: Container;
142
+ /** Node.js http.Server — only available in afterStart */
143
+ server?: http.Server;
144
+ /** Current NODE_ENV value (default: 'development') */
145
+ env: string;
146
+ /** true when NODE_ENV === 'production' */
147
+ isProduction: boolean;
148
+ }
149
+ /**
150
+ * Adapters plug into the Application lifecycle.
151
+ * Implement this to add WebSocket, database, rate limiting, docs, etc.
152
+ *
153
+ * All hooks receive an `AdapterContext` populated by the framework.
154
+ * No external type imports needed — the context is fully typed from KickJS internals.
155
+ *
156
+ * @example
157
+ * ```ts
158
+ * import type { AppAdapter, AdapterContext } from '@forinda/kickjs/adapter'
159
+ *
160
+ * class SentryAdapter implements AppAdapter {
161
+ * name = 'SentryAdapter'
162
+ *
163
+ * beforeMount({ app, container }: AdapterContext) {
164
+ * app.use(Sentry.expressRequestHandler())
165
+ * }
166
+ *
167
+ * afterStart({ server }: AdapterContext) {
168
+ * // server is the http.Server — available after listen()
169
+ * }
170
+ *
171
+ * async shutdown() {
172
+ * await Sentry.close(2000)
173
+ * }
174
+ * }
175
+ * ```
176
+ */
177
+ interface AppAdapter {
178
+ /**
179
+ * Human-readable name for logging and `dependsOn` resolution.
180
+ * Required when the adapter (or any other in the same set) declares
181
+ * `dependsOn` — sort errors will reference adapters by name.
182
+ */
183
+ name?: string;
184
+ /**
185
+ * Other adapter names that must mount before this one. The framework
186
+ * topologically sorts adapters at boot — cycles or unknown names throw
187
+ * via `MountCycleError` / `MissingMountDepError` so bad configurations
188
+ * fail boot rather than corrupt live traffic.
189
+ *
190
+ * Common pattern: `TenantAdapter` populates `req.tenant` and
191
+ * `AuthAdapter` reads it for tenant-scoped RBAC, so AuthAdapter
192
+ * declares `dependsOn = ['TenantAdapter']`. Adapters without
193
+ * `dependsOn` retain their declaration order.
194
+ *
195
+ * @example
196
+ * ```ts
197
+ * class AuthAdapter implements AppAdapter {
198
+ * name = 'AuthAdapter'
199
+ * dependsOn = ['TenantAdapter']
200
+ * }
201
+ * ```
202
+ */
203
+ dependsOn?: readonly KickJsPluginName[];
204
+ /**
205
+ * Return middleware entries to be inserted into the pipeline.
206
+ * The `phase` controls ordering relative to global middleware and routes.
207
+ */
208
+ middleware?(): AdapterMiddleware[];
209
+ /**
210
+ * Return Context Contributors (#107) that apply to every route in the
211
+ * application. Adapter-level contributors merge into the per-route
212
+ * pipeline at the `'adapter'` precedence level — they win over global
213
+ * contributors but lose to module, class, and method decorators.
214
+ *
215
+ * Useful for cross-cutting concerns: an auth adapter contributing
216
+ * `user`, a multi-tenant adapter contributing `tenant`, etc. Optional.
217
+ */
218
+ contributors?(): ContributorRegistrations;
219
+ /**
220
+ * Called before global middleware — register early routes (docs UI, health).
221
+ * May return a Promise — async rejections are caught and logged.
222
+ */
223
+ beforeMount?(ctx: AdapterContext): void | Promise<void>;
224
+ /**
225
+ * Called for each module route that gets mounted.
226
+ * Use this to collect route metadata (e.g. for OpenAPI spec generation).
227
+ */
228
+ onRouteMount?(controllerClass: Constructor, mountPath: string): void;
229
+ /**
230
+ * Called after modules are registered and the DI container is bootstrapped,
231
+ * before the HTTP server starts listening. **This is the correct hook for
232
+ * adapters that register DI bindings, resolve services, or otherwise prepare
233
+ * container-side state** (e.g. `container.registerInstance(MAILER, ...)`).
234
+ *
235
+ * `beforeStart` runs inside `app.setup()`, which means it also fires under
236
+ * `createTestApp` — adapters using this hook work in unit tests without
237
+ * needing a live HTTP server. See {@link afterStart} for the contrast.
238
+ *
239
+ * May return a Promise — async rejections are caught and logged.
240
+ */
241
+ beforeStart?(ctx: AdapterContext): void | Promise<void>;
242
+ /**
243
+ * Called after the HTTP server is listening — `ctx.server` is the live
244
+ * `http.Server`. **Use this hook only for work that genuinely needs a
245
+ * listening server**: attaching Socket.IO / WS upgrades, reading the bound
246
+ * port via `server.address()`, dispatching to the local server over HTTP,
247
+ * etc.
248
+ *
249
+ * `afterStart` does NOT fire under `createTestApp`, since tests call
250
+ * `app.setup()` and never `app.start()`. If your adapter only registers DI
251
+ * bindings or resolves services, use {@link beforeStart} — that hook runs
252
+ * in both production (`start()`) and tests (`setup()`).
253
+ *
254
+ * May return a Promise — async rejections are caught and logged.
255
+ */
256
+ afterStart?(ctx: AdapterContext): void | Promise<void>;
257
+ /**
258
+ * Called by the /health/ready endpoint. Return the health status of your adapter's
259
+ * backing service (database, Redis, queue, etc.).
260
+ */
261
+ onHealthCheck?(): Promise<{
262
+ name: string;
263
+ status: 'up' | 'down';
264
+ }>;
265
+ /** Called on shutdown — clean up connections */
266
+ shutdown?(): MaybePromise;
267
+ /**
268
+ * Optional DevTools introspection hook (architecture.md §23). Returns
269
+ * a snapshot describing this adapter's current state, metrics, and DI
270
+ * tokens. DevTools awaits the result, so async work is fine — but keep
271
+ * the implementation cheap (counters + flags, no DB round trips) since
272
+ * the topology endpoint polls on a short interval.
273
+ *
274
+ * The return type is intentionally untyped at this layer to avoid
275
+ * `@forinda/kickjs` taking on a runtime dep on `@forinda/kickjs-devtools-kit`.
276
+ * Adapter authors should import and return `IntrospectionSnapshot`
277
+ * from `@forinda/kickjs-devtools-kit` directly.
278
+ */
279
+ introspect?(): unknown | Promise<unknown>;
280
+ /**
281
+ * Optional DevTools tabs this adapter contributes (architecture.md §23).
282
+ * Returns an array of `DevtoolsTabDescriptor` shapes — typically one
283
+ * entry per adapter-owned panel (iframe / launch / html view).
284
+ *
285
+ * Same untyped-at-this-layer convention as {@link introspect}: adapter
286
+ * authors import `defineDevtoolsTab` (or the bare type) from
287
+ * `@forinda/kickjs-devtools-kit` so `@forinda/kickjs` doesn't take on
288
+ * a runtime dep on the kit.
289
+ */
290
+ devtoolsTabs?(): readonly unknown[];
291
+ }
292
+ /** Constructor type for AppAdapter classes */
293
+ type AppAdapterClass = new () => AppAdapter;
294
+ //#endregion
295
+ export { MiddlewarePhase as a, KickJsPluginRegistry as c, AppAdapterClass as i, defineAugmentation as l, AdapterMiddleware as n, AugmentationMeta as o, AppAdapter as r, KickJsPluginName as s, AdapterContext as t };
296
+ //# sourceMappingURL=adapter-6Pp4kFdM.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapter-6Pp4kFdM.d.mts","names":[],"sources":["../src/core/augmentation.ts","../src/core/adapter.ts"],"mappings":";;;;;;;;;;;;;;;AAqBA;;;;;AAUA;;;;;AAcA;;;UAxBiB,oBAAA;AA+EjB;;;;;;;;AAAA,KArEY,gBAAA,SAAyB,oBAAA,gCAE3B,oBAAA;;;;AClBV;;;;;AAGA;;UD2BiB,gBAAA;ECvBQ;;;;ED4BvB,WAAA;EC1BI;;AAgBN;;;;EDiBE,OAAA;AAAA;;;;;;;;;;;;;;ACwBF;;;;;;;;;;;;;;;;;;;;;;;;;;;iBDmBgB,kBAAA,CAAmB,IAAA,UAAc,IAAA,GAAO,gBAAA;;;;AA/ExD;;;;;AAUA;;KChBY,eAAA;;UAGK,iBAAA;ED2BA;ECzBf,OAAA;;EAEA,KAAA,GAAQ,eAAA;EDmCD;ECjCP,IAAA;AAAA;;;;;;;;;;;AATF;;;UAyBiB,cAAA;EAzBU;EA2BzB,GAAA,EAAK,OAAA;EAxB2B;EA0BhC,SAAA,EAAW,SAAA;EAtBY;EAwBvB,MAAA,GAAS,IAAA,CAAK,MAAA;EAxBd;EA0BA,GAAA;EAxBA;EA0BA,YAAA;AAAA;AAVF;;;;;;;;;;;;;;;;;;;AAyCA;;;;;;;;;AAzCA,UAyCiB,UAAA;EAsE2B;;;;;EAhE1C,IAAA;EAuGgC;;;;;;;;;;;;;;;;;;;EAlFhC,SAAA,YAAqB,gBAAA;EA2CqB;;;;EArC1C,UAAA,KAAe,iBAAA;EA2Df;;;;;;;;;EAhDA,YAAA,KAAiB,wBAAA;EA6EL;AAId;;;EA3EE,WAAA,EAAa,GAAA,EAAK,cAAA,UAAwB,OAAA;EA2EM;;;;EArEhD,YAAA,EAAc,eAAA,EAAiB,WAAA,EAAa,SAAA;;;;;;;;;;;;;EAc5C,WAAA,EAAa,GAAA,EAAK,cAAA,UAAwB,OAAA;;;;;;;;;;;;;;;EAgB1C,UAAA,EAAY,GAAA,EAAK,cAAA,UAAwB,OAAA;;;;;EAMzC,aAAA,KAAkB,OAAA;IAAU,IAAA;IAAc,MAAA;EAAA;;EAG1C,QAAA,KAAa,YAAA;;;;;;;;;;;;;EAcb,UAAA,eAAyB,OAAA;;;;;;;;;;;EAYzB,YAAA;AAAA;;KAIU,eAAA,aAA4B,UAAA"}
@@ -1,6 +1,6 @@
1
1
 
2
- import { t as Container } from "./container-fIS1uLx-.mjs";
3
- import { r as ContributorRegistration } from "./context-decorator-GA8-hDLe.mjs";
2
+ import { t as Container } from "./container-CnWDsxi-.mjs";
3
+ import { o as ContributorRegistrations } from "./context-decorator-DrPvQ9Ag.mjs";
4
4
 
5
5
  //#region src/core/app-module.d.ts
6
6
  /**
@@ -39,7 +39,7 @@ interface AppModule {
39
39
  *
40
40
  * Optional — modules without per-module contributors omit this hook.
41
41
  */
42
- contributors?(): ContributorRegistration[] | readonly ContributorRegistration[];
42
+ contributors?(): ContributorRegistrations;
43
43
  /** Return route definitions for this module, or null for non-HTTP modules */
44
44
  routes(): ModuleRoutes | ModuleRoutes[] | null;
45
45
  }
@@ -47,4 +47,4 @@ interface AppModule {
47
47
  type AppModuleClass = new () => AppModule;
48
48
  //#endregion
49
49
  export { AppModuleClass as n, ModuleRoutes as r, AppModule as t };
50
- //# sourceMappingURL=app-module-ERR9jhow.d.mts.map
50
+ //# sourceMappingURL=app-module-Blgz4Rti.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"app-module-Blgz4Rti.d.mts","names":[],"sources":["../src/core/app-module.ts"],"mappings":";;;;;;;AAOA;;UAAiB,YAAA;EAAY;EAE3B,IAAA;EAEA;EAAA,MAAA;EAIA;EAFA,OAAA;EAEU;EAAV,UAAA;AAAA;;;;;;;;;;;;UAce,SAAA;EAaf;EAXA,QAAA,EAAU,SAAA,EAAW,SAAA;EAWI;;;AAI3B;;;;;EANE,YAAA,KAAiB,wBAAA;;EAEjB,MAAA,IAAU,YAAA,GAAe,YAAA;AAAA;;KAIf,cAAA,aAA2B,SAAA"}