@forinda/kickjs 3.1.3 → 4.0.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 (192) hide show
  1. package/README.md +13 -212
  2. package/dist/adapter-BNw2pGbg.d.mts +261 -0
  3. package/dist/adapter-BNw2pGbg.d.mts.map +1 -0
  4. package/dist/{app-module-Cotu9TIC.d.mts → app-module-CO0ksPCm.d.mts} +12 -2
  5. package/dist/app-module-CO0ksPCm.d.mts.map +1 -0
  6. package/dist/{application-BVl6L8xo.mjs → application-Ce4DQN6m.mjs} +114 -25
  7. package/dist/application-Ce4DQN6m.mjs.map +1 -0
  8. package/dist/application-Czwm7Gty.d.mts +302 -0
  9. package/dist/application-Czwm7Gty.d.mts.map +1 -0
  10. package/dist/{bootstrap-D6leYXz2.mjs → bootstrap-CB7bJeJG.mjs} +6 -6
  11. package/dist/{bootstrap-D6leYXz2.mjs.map → bootstrap-CB7bJeJG.mjs.map} +1 -1
  12. package/dist/bootstrap-NxFRaNTh.d.mts +28 -0
  13. package/dist/bootstrap-NxFRaNTh.d.mts.map +1 -0
  14. package/dist/{cache-CcTzzNdr.d.mts → cache-BStrqXSZ.d.mts} +2 -2
  15. package/dist/{cache-CcTzzNdr.d.mts.map → cache-BStrqXSZ.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-gkVEnxVm.mjs → config-wZ_TgBfs.mjs} +4 -4
  19. package/dist/{config-gkVEnxVm.mjs.map → config-wZ_TgBfs.mjs.map} +1 -1
  20. package/dist/{container-BJb34faa.d.mts → container-CnWDsxi-.d.mts} +9 -7
  21. package/dist/container-CnWDsxi-.d.mts.map +1 -0
  22. package/dist/{container-BBZLlK6y.mjs → container-DYYSu58w.mjs} +313 -9
  23. package/dist/container-DYYSu58w.mjs.map +1 -0
  24. package/dist/context-BAGzqT7-.mjs +319 -0
  25. package/dist/context-BAGzqT7-.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-B5v3VQCN.d.mts +111 -0
  29. package/dist/context-decorator-B5v3VQCN.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 +2 -2
  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 +2 -2
  41. package/dist/core/decorators.d.mts +2 -2
  42. package/dist/core/decorators.mjs +48 -16
  43. package/dist/core/decorators.mjs.map +1 -1
  44. package/dist/core/errors.d.mts +1 -1
  45. package/dist/core/errors.mjs +1 -1
  46. package/dist/core/interfaces.d.mts +1 -1
  47. package/dist/core/interfaces.mjs +35 -16
  48. package/dist/core/interfaces.mjs.map +1 -1
  49. package/dist/core/logger.d.mts +2 -2
  50. package/dist/core/logger.mjs +2 -4
  51. package/dist/core/logger.mjs.map +1 -1
  52. package/dist/core/path.d.mts +1 -1
  53. package/dist/core/path.mjs +1 -1
  54. package/dist/core/plugin.d.mts +1 -1
  55. package/dist/core/plugin.mjs +1 -1
  56. package/dist/core/reactivity.d.mts +1 -1
  57. package/dist/core/reactivity.mjs +1 -1
  58. package/dist/core-DBcoqPHM.mjs +709 -0
  59. package/dist/core-DBcoqPHM.mjs.map +1 -0
  60. package/dist/cors-BfgqfLPd.d.mts +48 -0
  61. package/dist/cors-BfgqfLPd.d.mts.map +1 -0
  62. package/dist/{cron-H-IyLcOr.d.mts → cron-7zqvsmMI.d.mts} +1 -1
  63. package/dist/{cron-H-IyLcOr.d.mts.map → cron-7zqvsmMI.d.mts.map} +1 -1
  64. package/dist/csrf-DiK9zept.d.mts +52 -0
  65. package/dist/csrf-DiK9zept.d.mts.map +1 -0
  66. package/dist/{decorators-C9_SN7ge.d.mts → decorators-BMvaLliz.d.mts} +147 -12
  67. package/dist/decorators-BMvaLliz.d.mts.map +1 -0
  68. package/dist/{env-Cu5hWsuE.mjs → env-CdH5-dM_.mjs} +3 -4
  69. package/dist/{env-Cu5hWsuE.mjs.map → env-CdH5-dM_.mjs.map} +1 -1
  70. package/dist/error-handler-Xud_3Lah.d.mts +20 -0
  71. package/dist/error-handler-Xud_3Lah.d.mts.map +1 -0
  72. package/dist/{errors-BOUCRl-p.d.mts → errors-uaHCeXRz.d.mts} +1 -1
  73. package/dist/{errors-BOUCRl-p.d.mts.map → errors-uaHCeXRz.d.mts.map} +1 -1
  74. package/dist/execution-context-DKnt61pY.d.mts +57 -0
  75. package/dist/execution-context-DKnt61pY.d.mts.map +1 -0
  76. package/dist/helmet-CaMbjzBG.d.mts +41 -0
  77. package/dist/helmet-CaMbjzBG.d.mts.map +1 -0
  78. package/dist/http/application.d.mts +2 -239
  79. package/dist/http/application.mjs +2 -2
  80. package/dist/http/bootstrap.d.mts +2 -27
  81. package/dist/http/bootstrap.mjs +2 -2
  82. package/dist/http/context.d.mts +3 -262
  83. package/dist/http/context.mjs +2 -271
  84. package/dist/http/middleware/cors.d.mts +2 -47
  85. package/dist/http/middleware/cors.mjs +1 -1
  86. package/dist/http/middleware/csrf.d.mts +2 -51
  87. package/dist/http/middleware/csrf.mjs +2 -2
  88. package/dist/http/middleware/csrf.mjs.map +1 -1
  89. package/dist/http/middleware/error-handler.d.mts +2 -19
  90. package/dist/http/middleware/error-handler.mjs +2 -2
  91. package/dist/http/middleware/helmet.d.mts +2 -40
  92. package/dist/http/middleware/helmet.mjs +1 -1
  93. package/dist/http/middleware/rate-limit.d.mts +2 -55
  94. package/dist/http/middleware/rate-limit.mjs +2 -2
  95. package/dist/http/middleware/rate-limit.mjs.map +1 -1
  96. package/dist/http/middleware/request-id.d.mts +2 -9
  97. package/dist/http/middleware/request-id.mjs +12 -3
  98. package/dist/http/middleware/request-id.mjs.map +1 -1
  99. package/dist/http/middleware/request-logger.d.mts +2 -31
  100. package/dist/http/middleware/request-logger.mjs +2 -2
  101. package/dist/http/middleware/session.d.mts +2 -69
  102. package/dist/http/middleware/session.mjs +1 -1
  103. package/dist/http/middleware/spa.d.mts +2 -100
  104. package/dist/http/middleware/spa.mjs +5 -5
  105. package/dist/http/middleware/spa.mjs.map +1 -1
  106. package/dist/http/middleware/upload.d.mts +2 -78
  107. package/dist/http/middleware/upload.mjs +1 -1
  108. package/dist/http/middleware/validate.d.mts +2 -22
  109. package/dist/http/middleware/validate.mjs +2 -2
  110. package/dist/http/middleware/views.d.mts +2 -61
  111. package/dist/http/middleware/views.mjs +16 -15
  112. package/dist/http/middleware/views.mjs.map +1 -1
  113. package/dist/http/query/index.d.mts +1 -1
  114. package/dist/http/query/index.mjs +2 -2
  115. package/dist/http/router-builder.d.mts +2 -20
  116. package/dist/http/router-builder.mjs +58 -10
  117. package/dist/http/router-builder.mjs.map +1 -1
  118. package/dist/{index-Co7a3Zat.d.mts → index-B9cyOQAe.d.mts} +1 -1
  119. package/dist/{index-Co7a3Zat.d.mts.map → index-B9cyOQAe.d.mts.map} +1 -1
  120. package/dist/{index-DNVfGjF9.d.mts → index-D-qhXg9M.d.mts} +3 -3
  121. package/dist/{index-DNVfGjF9.d.mts.map → index-D-qhXg9M.d.mts.map} +1 -1
  122. package/dist/index-DQyWtyp0.d.mts +511 -0
  123. package/dist/index-DQyWtyp0.d.mts.map +1 -0
  124. package/dist/index.d.mts +34 -133
  125. package/dist/index.mjs +14 -14
  126. package/dist/interfaces-B50n7dwl.d.mts +71 -0
  127. package/dist/{interfaces-DXjE8Re1.d.mts.map → interfaces-B50n7dwl.d.mts.map} +1 -1
  128. package/dist/{logger-CW6FHtvU.d.mts → logger-CLVRZf2N.d.mts} +2 -4
  129. package/dist/{logger-CW6FHtvU.d.mts.map → logger-CLVRZf2N.d.mts.map} +1 -1
  130. package/dist/{metadata-BwRJ69bC.mjs → metadata-VQM9wChy.mjs} +2 -2
  131. package/dist/{metadata-BwRJ69bC.mjs.map → metadata-VQM9wChy.mjs.map} +1 -1
  132. package/dist/{path-B4JcbwKX.d.mts → path-Diviu6hv.d.mts} +1 -1
  133. package/dist/path-Diviu6hv.d.mts.map +1 -0
  134. package/dist/plugin-WdrDgNzk.d.mts +165 -0
  135. package/dist/plugin-WdrDgNzk.d.mts.map +1 -0
  136. package/dist/{query-BQ2UT3oi.mjs → query-DJMxdx5r.mjs} +2 -2
  137. package/dist/{query-BQ2UT3oi.mjs.map → query-DJMxdx5r.mjs.map} +1 -1
  138. package/dist/rate-limit-DUwoICtI.d.mts +56 -0
  139. package/dist/rate-limit-DUwoICtI.d.mts.map +1 -0
  140. package/dist/{reactivity-I8nDlg4c.d.mts → reactivity-CfJceo4H.d.mts} +1 -1
  141. package/dist/{reactivity-I8nDlg4c.d.mts.map → reactivity-CfJceo4H.d.mts.map} +1 -1
  142. package/dist/request-id-BgglvZHN.d.mts +19 -0
  143. package/dist/request-id-BgglvZHN.d.mts.map +1 -0
  144. package/dist/request-logger-CWHbAzTE.d.mts +32 -0
  145. package/dist/request-logger-CWHbAzTE.d.mts.map +1 -0
  146. package/dist/router-builder-C799BAf0.d.mts +31 -0
  147. package/dist/router-builder-C799BAf0.d.mts.map +1 -0
  148. package/dist/session-N0hActOO.d.mts +70 -0
  149. package/dist/session-N0hActOO.d.mts.map +1 -0
  150. package/dist/spa-CrFR2_cz.d.mts +101 -0
  151. package/dist/spa-CrFR2_cz.d.mts.map +1 -0
  152. package/dist/upload-BueOnnLw.d.mts +79 -0
  153. package/dist/upload-BueOnnLw.d.mts.map +1 -0
  154. package/dist/validate-HwAyWTwH.d.mts +23 -0
  155. package/dist/validate-HwAyWTwH.d.mts.map +1 -0
  156. package/dist/views-DhQSXV2P.d.mts +176 -0
  157. package/dist/views-DhQSXV2P.d.mts.map +1 -0
  158. package/package.json +6 -9
  159. package/dist/adapter-DjL8ql5d.d.mts +0 -140
  160. package/dist/adapter-DjL8ql5d.d.mts.map +0 -1
  161. package/dist/app-module-Cotu9TIC.d.mts.map +0 -1
  162. package/dist/application-BVl6L8xo.mjs.map +0 -1
  163. package/dist/chunk-CVPG7JJl.mjs +0 -15
  164. package/dist/container-BBZLlK6y.mjs.map +0 -1
  165. package/dist/container-BJb34faa.d.mts.map +0 -1
  166. package/dist/core-qyPNtpKp.mjs +0 -121
  167. package/dist/core-qyPNtpKp.mjs.map +0 -1
  168. package/dist/decorators-C9_SN7ge.d.mts.map +0 -1
  169. package/dist/http/application.d.mts.map +0 -1
  170. package/dist/http/bootstrap.d.mts.map +0 -1
  171. package/dist/http/context.d.mts.map +0 -1
  172. package/dist/http/context.mjs.map +0 -1
  173. package/dist/http/middleware/cors.d.mts.map +0 -1
  174. package/dist/http/middleware/csrf.d.mts.map +0 -1
  175. package/dist/http/middleware/error-handler.d.mts.map +0 -1
  176. package/dist/http/middleware/helmet.d.mts.map +0 -1
  177. package/dist/http/middleware/rate-limit.d.mts.map +0 -1
  178. package/dist/http/middleware/request-id.d.mts.map +0 -1
  179. package/dist/http/middleware/request-logger.d.mts.map +0 -1
  180. package/dist/http/middleware/session.d.mts.map +0 -1
  181. package/dist/http/middleware/spa.d.mts.map +0 -1
  182. package/dist/http/middleware/upload.d.mts.map +0 -1
  183. package/dist/http/middleware/validate.d.mts.map +0 -1
  184. package/dist/http/middleware/views.d.mts.map +0 -1
  185. package/dist/http/router-builder.d.mts.map +0 -1
  186. package/dist/index-CwqjAF6I.d.mts +0 -112
  187. package/dist/index-CwqjAF6I.d.mts.map +0 -1
  188. package/dist/index.d.mts.map +0 -1
  189. package/dist/interfaces-DXjE8Re1.d.mts +0 -52
  190. package/dist/path-B4JcbwKX.d.mts.map +0 -1
  191. package/dist/plugin-Cvacmm7N.d.mts +0 -95
  192. package/dist/plugin-Cvacmm7N.d.mts.map +0 -1
@@ -0,0 +1,57 @@
1
+
2
+ //#region src/core/execution-context.d.ts
3
+ /**
4
+ * Transport-agnostic execution context primitives.
5
+ *
6
+ * `ExecutionContext` is the minimal contract every transport-specific
7
+ * context object satisfies — `RequestContext` (HTTP) implements it today;
8
+ * `WsContext`, `QueueContext`, and `CronContext` will adopt it in V2.
9
+ *
10
+ * `ContextMeta` is the augmentable per-request key/type registry. Apps and
11
+ * plugins extend it via module augmentation to get type-safe `ctx.get/set`
12
+ * across the codebase. It lives in core/ (not http/) so non-HTTP transports
13
+ * share a single declaration site.
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * declare module '@forinda/kickjs' {
18
+ * interface ContextMeta {
19
+ * user: { id: string; email: string }
20
+ * tenant: { id: string; name: string }
21
+ * }
22
+ * }
23
+ *
24
+ * function loadProject(ctx: ExecutionContext) {
25
+ * const user = ctx.get('user') // typed: { id: string; email: string } | undefined
26
+ * }
27
+ * ```
28
+ */
29
+ /**
30
+ * Augmentable per-request metadata registry.
31
+ *
32
+ * Extend via module augmentation to give `ctx.get()` / `ctx.set()` static
33
+ * type information for a given key. Unknown keys still resolve via an
34
+ * explicit generic: `ctx.get<MyType>('custom')`.
35
+ */
36
+ interface ContextMeta {}
37
+ /** Resolve a {@link ContextMeta} value type, falling back to `Fallback` for unknown keys. */
38
+ type MetaValue<K extends string, Fallback = unknown> = K extends keyof ContextMeta ? ContextMeta[K] : Fallback;
39
+ /**
40
+ * Minimal transport-agnostic execution context.
41
+ *
42
+ * `RequestContext` (HTTP) implements this directly; future `WsContext`,
43
+ * `QueueContext`, and `CronContext` (V2) will too. The Context Contributor
44
+ * pipeline only depends on this interface — contributors authored against
45
+ * `ExecutionContext` work across every transport that adopts it.
46
+ */
47
+ interface ExecutionContext {
48
+ /** Read a typed value from per-request metadata. */
49
+ get<K extends string>(key: K): MetaValue<K> | undefined;
50
+ /** Write a typed value into per-request metadata. */
51
+ set<K extends string>(key: K, value: MetaValue<K>): void;
52
+ /** Unique per-request identifier (HTTP: x-request-id; WS/queue/cron: transport-defined). */
53
+ readonly requestId: string | undefined;
54
+ }
55
+ //#endregion
56
+ export { ExecutionContext as n, MetaValue as r, ContextMeta as t };
57
+ //# sourceMappingURL=execution-context-DKnt61pY.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"execution-context-DKnt61pY.d.mts","names":[],"sources":["../src/core/execution-context.ts"],"mappings":";;;AAmCA;;;;;AAGA;;;;;;;;;;;;;;;;;;;AAYA;;;;;;;;UAfiB,WAAA;;KAGL,SAAA,yCAAkD,CAAA,eAAgB,WAAA,GAC1E,WAAA,CAAY,CAAA,IACZ,QAAA;;;;;;;;;UAUa,gBAAA;EAIsB;EAFrC,GAAA,mBAAsB,GAAA,EAAK,CAAA,GAAI,SAAA,CAAU,CAAA;EAEX;EAA9B,GAAA,mBAAsB,GAAA,EAAK,CAAA,EAAG,KAAA,EAAO,SAAA,CAAU,CAAA;EAE7B;EAAA,SAAT,SAAA;AAAA"}
@@ -0,0 +1,41 @@
1
+
2
+ import { NextFunction, Request, Response } from "express";
3
+
4
+ //#region src/http/middleware/helmet.d.ts
5
+ interface HelmetOptions {
6
+ /** Set Content-Security-Policy header (default: self-only policy) */
7
+ contentSecurityPolicy?: boolean | Record<string, string[]>;
8
+ /** Set X-Content-Type-Options: nosniff (default: true) */
9
+ noSniff?: boolean;
10
+ /** Set X-Frame-Options (default: 'DENY') */
11
+ frameguard?: false | 'DENY' | 'SAMEORIGIN';
12
+ /** Set Strict-Transport-Security (default: max-age=31536000; includeSubDomains) */
13
+ hsts?: false | {
14
+ maxAge?: number;
15
+ includeSubDomains?: boolean;
16
+ preload?: boolean;
17
+ };
18
+ /** Set X-DNS-Prefetch-Control (default: off) */
19
+ dnsPrefetch?: boolean;
20
+ /** Remove X-Powered-By header (default: true) */
21
+ hidePoweredBy?: boolean;
22
+ /** Set Referrer-Policy (default: 'no-referrer') */
23
+ referrerPolicy?: false | string;
24
+ /** Set X-XSS-Protection: 0 (default: true — disables legacy XSS auditor) */
25
+ xssFilter?: boolean;
26
+ }
27
+ /**
28
+ * Security headers middleware. Lightweight alternative to the `helmet` npm package
29
+ * with sensible defaults for API servers.
30
+ *
31
+ * @example
32
+ * ```ts
33
+ * bootstrap({
34
+ * middleware: [helmet(), requestId(), express.json()],
35
+ * })
36
+ * ```
37
+ */
38
+ declare function helmet(options?: HelmetOptions): (req: Request, res: Response, next: NextFunction) => void;
39
+ //#endregion
40
+ export { helmet as n, HelmetOptions as t };
41
+ //# sourceMappingURL=helmet-CaMbjzBG.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"helmet-CaMbjzBG.d.mts","names":[],"sources":["../src/http/middleware/helmet.ts"],"mappings":";;;;UAEiB,aAAA;;EAEf,qBAAA,aAAkC,MAAA;EAFN;EAI5B,OAAA;EAFwC;EAIxC,UAAA;EAJkC;EAMlC,IAAA;IAAiB,MAAA;IAAiB,iBAAA;IAA6B,OAAA;EAAA;EAAA;EAE/D,WAAA;EAEA;EAAA,aAAA;EAIA;EAFA,cAAA;EAES;EAAT,SAAA;AAAA;;;;;;;;;;;;iBAcc,MAAA,CAAO,OAAA,GAAS,aAAA,IAYtB,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,EAAU,IAAA,EAAM,YAAA"}
@@ -1,240 +1,3 @@
1
1
 
2
- import { t as Container } from "../container-BJb34faa.mjs";
3
- import { r as AppAdapter } from "../adapter-DjL8ql5d.mjs";
4
- import { n as AppModuleClass } from "../app-module-Cotu9TIC.mjs";
5
- import { t as KickPlugin } from "../plugin-Cvacmm7N.mjs";
6
- import http from "node:http";
7
- import { Express, RequestHandler } from "express";
8
-
9
- //#region src/http/application.d.ts
10
- /**
11
- * A middleware entry in the declarative pipeline.
12
- * Can be a bare handler or an object with path scoping.
13
- */
14
- type MiddlewareEntry = RequestHandler | {
15
- path: string;
16
- handler: RequestHandler;
17
- };
18
- interface ApplicationOptions {
19
- /** Feature modules to load */
20
- modules: AppModuleClass[];
21
- /** Adapters that hook into the lifecycle (DB, Redis, Swagger, etc.) */
22
- adapters?: AppAdapter[];
23
- /** Server port (falls back to PORT env var, then 3000) */
24
- port?: number;
25
- /** Global API prefix (default: '/api') */
26
- apiPrefix?: string;
27
- /** Default API version (default: 1) — routes become /{prefix}/v{version}/{path} */
28
- defaultVersion?: number;
29
- /**
30
- * Global middleware pipeline. Declared in order.
31
- * Replaces the hardcoded middleware stack — you control exactly what runs.
32
- *
33
- * @example
34
- * ```ts
35
- * bootstrap({
36
- * modules,
37
- * middleware: [
38
- * helmet(),
39
- * cors(),
40
- * compression(),
41
- * morgan('dev'),
42
- * express.json({ limit: '1mb' }),
43
- * ],
44
- * })
45
- * ```
46
- *
47
- * If omitted, a sensible default is applied:
48
- * requestId(), express.json({ limit: '100kb' })
49
- */
50
- middleware?: MiddlewareEntry[];
51
- /** Plugins that bundle modules, adapters, middleware, and DI bindings */
52
- plugins?: KickPlugin[];
53
- /** Express `trust proxy` setting */
54
- trustProxy?: boolean | number | string | ((ip: string, hopIndex: number) => boolean);
55
- /** Maximum JSON body size (only used when middleware is not provided) */
56
- jsonLimit?: string | number;
57
- /**
58
- * Log route summary on startup. Default: true in dev, false in production.
59
- * Set to `true` to always log, `false` to always suppress.
60
- */
61
- logRoutesTable?: boolean;
62
- /**
63
- * Maximum time (ms) to wait for graceful shutdown before forcing exit.
64
- * Default: 30000 (30 seconds). Set to 0 to disable forced exit.
65
- */
66
- shutdownTimeout?: number;
67
- /**
68
- * Enable cluster mode for multi-core utilization.
69
- *
70
- * When enabled, the primary process forks worker processes that share the
71
- * same port via Node's built-in `cluster` module (OS load balancing).
72
- *
73
- * - `true` — use all available CPU cores
74
- * - `{ workers: N }` — use exactly N workers
75
- *
76
- * Workers are auto-restarted on crash. SIGTERM/SIGINT on the primary is
77
- * forwarded to all workers.
78
- *
79
- * @example
80
- * ```ts
81
- * bootstrap({ modules, cluster: true })
82
- * bootstrap({ modules, cluster: { workers: 4 } })
83
- * ```
84
- */
85
- cluster?: boolean | {
86
- workers?: number;
87
- };
88
- /**
89
- * Custom 404 handler for unmatched routes. Receives the raw Express
90
- * `(req, res, next)` args. When omitted, the built-in handler returns
91
- * `{ message: 'Not Found' }` with status 404.
92
- *
93
- * @example
94
- * ```ts
95
- * bootstrap({
96
- * modules,
97
- * onNotFound: (req, res) => {
98
- * res.status(404).json({ error: 'Route not found', path: req.originalUrl })
99
- * },
100
- * })
101
- * ```
102
- */
103
- onNotFound?: (req: any, res: any, next: any) => void;
104
- /**
105
- * Custom global error handler. Receives `(err, req, res, next)` — the
106
- * standard Express error-handling signature. When omitted, the built-in
107
- * handler formats ZodError, HttpException, and unexpected errors.
108
- *
109
- * @example
110
- * ```ts
111
- * bootstrap({
112
- * modules,
113
- * onError: (err, req, res, next) => {
114
- * logger.error(err)
115
- * res.status(err.status ?? 500).json({ error: err.message })
116
- * },
117
- * })
118
- * ```
119
- */
120
- onError?: (err: any, req: any, res: any, next: any) => void;
121
- /**
122
- * Security defaults applied automatically unless opted out.
123
- *
124
- * When not specified, secure defaults are applied:
125
- * - Helmet security headers are auto-injected
126
- * - JSON body limit defaults to 1MB
127
- *
128
- * @example
129
- * ```ts
130
- * bootstrap({
131
- * modules,
132
- * security: {
133
- * helmet: false, // disable auto-helmet
134
- * },
135
- * })
136
- * ```
137
- */
138
- security?: {
139
- /** Auto-inject helmet security headers. Default: true */helmet?: boolean;
140
- };
141
- }
142
- /**
143
- * The main application class. Wires together Express, the DI container,
144
- * feature modules, adapters, and the middleware pipeline.
145
- */
146
- declare class Application {
147
- private readonly options;
148
- private app;
149
- private container;
150
- private httpServer;
151
- private adapters;
152
- private plugins;
153
- /** Number of HTTP requests currently being processed */
154
- private _inFlightRequests;
155
- /** Whether the application is draining (shutting down gracefully) */
156
- private _draining;
157
- /** Whether shutdown has already been initiated (prevents double-shutdown) */
158
- private _shutdownInitiated;
159
- /** Resolvers waiting for in-flight requests to reach zero */
160
- private _drainResolvers;
161
- constructor(options: ApplicationOptions);
162
- /** Whether the application is currently draining in-flight requests */
163
- get isDraining(): boolean;
164
- /** Number of HTTP requests currently being processed */
165
- get inFlightRequests(): number;
166
- /** Get the DI container instance */
167
- getContainer(): Container;
168
- /**
169
- * Express request handler — delegates to the internal Express app.
170
- *
171
- * Used by the Vite dev-server plugin to route requests through KickJS:
172
- * ```ts
173
- * const mod = await ssrLoadModule('virtual:kickjs/app')
174
- * mod.app.handle(req, res, next)
175
- * ```
176
- *
177
- * Also works as a standard Node.js request handler for production:
178
- * ```ts
179
- * http.createServer(app.handle.bind(app))
180
- * ```
181
- */
182
- handle(req: http.IncomingMessage, res: http.ServerResponse, next?: (err?: any) => void): void;
183
- /**
184
- * Full setup pipeline:
185
- * 1. Adapter beforeMount hooks (early routes — docs, health)
186
- * 2. Adapter middleware (phase: beforeGlobal)
187
- * 3. Global middleware (user-declared or defaults)
188
- * 4. Adapter middleware (phase: afterGlobal)
189
- * 5. Module registration + DI bootstrap
190
- * 6. Adapter middleware (phase: beforeRoutes)
191
- * 7. Module route mounting
192
- * 8. Adapter middleware (phase: afterRoutes)
193
- * 9. Error handlers (notFound + global)
194
- * 10. Adapter beforeStart hooks
195
- */
196
- /** Build the adapter context object (shared across all hooks) */
197
- private adapterCtx;
198
- /** Call an adapter hook, awaiting async hooks and catching errors */
199
- private callHook;
200
- setup(): Promise<void>;
201
- /** Register modules and DI without starting the HTTP server (used by kick tinker) */
202
- registerOnly(): Promise<void>;
203
- /**
204
- * Start the HTTP server.
205
- *
206
- * In **dev mode** (Vite plugin active): reuses `globalThis.__kickjs_httpServer`
207
- * created by Vite. Adapters (WsAdapter, Socket.IO, etc.) receive the real
208
- * `http.Server` through `afterStart({ server })` — zero adapter changes needed.
209
- *
210
- * In **production**: creates its own `http.Server` and binds to the port.
211
- */
212
- start(): Promise<void>;
213
- /** HMR rebuild: swap Express handler without restarting the server */
214
- rebuild(): Promise<void>;
215
- /**
216
- * Graceful shutdown with request draining.
217
- *
218
- * 1. Stops accepting new connections (server.close())
219
- * 2. Waits for in-flight requests to complete (up to shutdownTimeout)
220
- * 3. Calls adapter.shutdown() for all registered adapters
221
- * 4. Force-closes after timeout
222
- *
223
- * Safe to call multiple times — subsequent calls return the same promise.
224
- */
225
- shutdown(): Promise<void>;
226
- getExpressApp(): Express;
227
- /** Get registered adapters — used by DevToolsAdapter for peer discovery */
228
- getAdapters(): AppAdapter[];
229
- getHttpServer(): http.Server | null;
230
- private collectAdapterMiddleware;
231
- private mountMiddlewareList;
232
- private mountMiddlewareEntry;
233
- /** Middleware that tracks in-flight requests for graceful draining */
234
- private requestTrackingMiddleware;
235
- /** Mount /health/live and /health/ready endpoints at the root (no API prefix) */
236
- private mountHealthEndpoints;
237
- }
238
- //#endregion
239
- export { Application, ApplicationOptions, MiddlewareEntry };
240
- //# sourceMappingURL=application.d.mts.map
2
+ import { n as ApplicationOptions, r as MiddlewareEntry, t as Application } from "../application-Czwm7Gty.mjs";
3
+ export { Application, ApplicationOptions, MiddlewareEntry };
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @forinda/kickjs v3.1.3
2
+ * @forinda/kickjs v4.0.0
3
3
  *
4
4
  * Copyright (c) Felix Orinda
5
5
  *
@@ -8,5 +8,5 @@
8
8
  *
9
9
  * @license MIT
10
10
  */
11
- import { t as Application } from "../application-BVl6L8xo.mjs";
11
+ import { t as Application } from "../application-Ce4DQN6m.mjs";
12
12
  export { Application };
@@ -1,28 +1,3 @@
1
1
 
2
- import { Application, ApplicationOptions } from "./application.mjs";
3
-
4
- //#region src/http/bootstrap.d.ts
5
- /**
6
- * Bootstrap a KickJS application.
7
- *
8
- * Creates the Express app, registers modules and adapters, and starts
9
- * the HTTP server. In dev mode (`kick dev`), the Vite plugin manages
10
- * the server and HMR — source changes are picked up instantly without
11
- * losing database connections or WebSocket state.
12
- *
13
- * @returns The {@link Application} instance.
14
- *
15
- * @example
16
- * ```ts
17
- * // src/index.ts
18
- * import 'reflect-metadata'
19
- * import { bootstrap } from '@forinda/kickjs'
20
- * import { modules } from './modules'
21
- *
22
- * export const app = await bootstrap({ modules })
23
- * ```
24
- */
25
- declare function bootstrap(options: ApplicationOptions): Promise<Application>;
26
- //#endregion
27
- export { bootstrap };
28
- //# sourceMappingURL=bootstrap.d.mts.map
2
+ import { t as bootstrap } from "../bootstrap-NxFRaNTh.mjs";
3
+ export { bootstrap };
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @forinda/kickjs v3.1.3
2
+ * @forinda/kickjs v4.0.0
3
3
  *
4
4
  * Copyright (c) Felix Orinda
5
5
  *
@@ -8,5 +8,5 @@
8
8
  *
9
9
  * @license MIT
10
10
  */
11
- import { t as bootstrap } from "../bootstrap-D6leYXz2.mjs";
11
+ import { t as bootstrap } from "../bootstrap-CB7bJeJG.mjs";
12
12
  export { bootstrap };
@@ -1,263 +1,4 @@
1
1
 
2
- import { g as QueryFieldConfig, y as TypedParsedQuery } from "../index-Co7a3Zat.mjs";
3
- import * as _$node_http0 from "node:http";
4
- import { NextFunction, Request, Response } from "express";
5
-
6
- //#region src/http/context.d.ts
7
- /**
8
- * Augmentable per-request metadata registry.
9
- *
10
- * Extend this interface via module augmentation to get type-safe
11
- * `ctx.get()` / `ctx.set()` across your app. Unknown keys still
12
- * work with an explicit generic: `ctx.get<MyType>('custom')`.
13
- *
14
- * @example
15
- * ```ts
16
- * // src/types.ts
17
- * declare module '@forinda/kickjs' {
18
- * interface ContextMeta {
19
- * user: { id: string; email: string; roles: string[] }
20
- * tenant: { id: string; name: string }
21
- * requestStartedAt: number
22
- * }
23
- * }
24
- *
25
- * // controller — fully typed, no generics needed
26
- * ctx.get('user') // { id: string; email: string; roles: string[] } | undefined
27
- * ctx.set('tenant', info) // type-checked value
28
- * ```
29
- */
30
- interface ContextMeta {}
31
- /** Resolve a ContextMeta value type, falling back to `Fallback` for unknown keys. */
32
- type MetaValue<K extends string, Fallback = unknown> = K extends keyof ContextMeta ? ContextMeta[K] : Fallback;
33
- /**
34
- * The shape of a single route entry in `KickRoutes`. Generated by
35
- * `kick typegen` and consumed via the `Ctx<T>` helper. Each field is
36
- * `unknown` by default and is filled in as the typegen learns more
37
- * about the route (URL params from the path, body/query from validation
38
- * schemas, etc.).
39
- */
40
- interface RouteShape {
41
- params?: unknown;
42
- body?: unknown;
43
- query?: unknown;
44
- response?: unknown;
45
- }
46
- /**
47
- * Unified request/response abstraction passed to every controller method.
48
- * Shields handlers from raw Express objects and provides convenience methods.
49
- */
50
- declare class RequestContext<TBody = any, TParams = any, TQuery = any> {
51
- readonly req: Request;
52
- readonly res: Response;
53
- readonly next: NextFunction;
54
- constructor(req: Request, res: Response, next: NextFunction);
55
- /**
56
- * Per-request metadata map shared across all RequestContext instances
57
- * for the same request. Stored on `req` so middleware can pass data
58
- * to handlers via `ctx.set()` / `ctx.get()`.
59
- */
60
- private get metadata();
61
- get body(): TBody;
62
- get params(): TParams;
63
- get query(): TQuery;
64
- get headers(): _$node_http0.IncomingHttpHeaders;
65
- get requestId(): string | undefined;
66
- /** Session data (requires session middleware) */
67
- get session(): any;
68
- /**
69
- * The authenticated user set by AuthAdapter.
70
- * Reads from the per-request metadata store first (`ctx.set('user', ...)`),
71
- * then falls back to `req.user` (set directly by AuthAdapter middleware).
72
- *
73
- * Extend the `AuthUser` interface via module augmentation in `@forinda/kickjs-auth`
74
- * to get full typing.
75
- *
76
- * @example
77
- * ```ts
78
- * @Get('/me')
79
- * @Authenticated()
80
- * getProfile(ctx: RequestContext) {
81
- * const user = ctx.user
82
- * if (!user) return ctx.notFound()
83
- * return ctx.json({ user })
84
- * }
85
- * ```
86
- */
87
- get user(): MetaValue<'user', Record<string, any>> | undefined;
88
- /**
89
- * Tenant identifier for multi-tenant apps. Reads `user.tenantId` —
90
- * populated either by `AuthAdapter.testMode({ tenantId })`, a tenant
91
- * resolver middleware, or manually on the strategy's `mapPayload`.
92
- *
93
- * Augment `AuthUser` (or `ContextMeta['user']`) to widen the return
94
- * type if your user shape guarantees a non-`string | undefined` id.
95
- */
96
- get tenantId(): string | undefined;
97
- /**
98
- * Effective role list for the current user. Prefers `user.tenantRoles`
99
- * (populated by `AuthAdapterOptions.roleResolver` under a tenant) and
100
- * falls back to `user.roles`. Returns an empty array when the user is
101
- * absent or the shape has neither field.
102
- */
103
- get roles(): string[];
104
- /**
105
- * Parse the request query string into structured filters, sort, pagination, and search.
106
- * Pass the result to an ORM query builder adapter (Drizzle, Prisma, Sequelize, etc.).
107
- *
108
- * Generic over the field config: when passed an inline literal (or
109
- * `as const`), `filters[].field` and `sort[].field` are narrowed to
110
- * the exact whitelisted field names. Pass nothing or a non-literal
111
- * config and you get the loose `string` fallback.
112
- *
113
- * @param fieldConfig - Optional whitelist for filterable, sortable, and searchable fields
114
- *
115
- * @example
116
- * ```ts
117
- * @Get('/')
118
- * async list(ctx: RequestContext) {
119
- * const parsed = ctx.qs({
120
- * filterable: ['status', 'priority'],
121
- * sortable: ['createdAt', 'title'],
122
- * } as const)
123
- * parsed.filters[0].field // typed as 'status' | 'priority'
124
- * parsed.sort[0].field // typed as 'createdAt' | 'title'
125
- * }
126
- * ```
127
- */
128
- qs<TConfig extends QueryFieldConfig | undefined = undefined>(fieldConfig?: TConfig): TypedParsedQuery<TConfig>;
129
- /** Single uploaded file (requires @FileUpload({ mode: 'single' })) */
130
- get file(): any;
131
- /** Array of uploaded files (requires @FileUpload({ mode: 'array' })) */
132
- get files(): any[] | undefined;
133
- /**
134
- * Read a value from the per-request metadata store.
135
- *
136
- * When `ContextMeta` has been augmented with a matching key, the return
137
- * type is inferred automatically. For ad-hoc keys, pass a generic:
138
- * `ctx.get<MyType>('custom')`.
139
- */
140
- get<K extends string>(key: K): MetaValue<K> | undefined;
141
- /**
142
- * Write a value to the per-request metadata store.
143
- *
144
- * When `ContextMeta` has been augmented with a matching key, the value
145
- * type is checked at compile time.
146
- */
147
- set<K extends string>(key: K, value: MetaValue<K>): void;
148
- json(data: any, status?: number): Response<any, Record<string, any>>;
149
- created(data: any): Response<any, Record<string, any>>;
150
- noContent(): Response<any, Record<string, any>>;
151
- notFound(message?: string): Response<any, Record<string, any>>;
152
- badRequest(message: string): Response<any, Record<string, any>>;
153
- html(content: string, status?: number): Response<any, Record<string, any>>;
154
- download(buffer: Buffer, filename: string, contentType?: string): Response<any, Record<string, any>>;
155
- /**
156
- * Render a template using the registered view engine (EJS, Pug, Handlebars, etc.).
157
- * Requires a ViewAdapter to be configured in bootstrap().
158
- *
159
- * @param template - Template name (without extension, relative to viewsDir)
160
- * @param data - Data to pass to the template
161
- *
162
- * @example
163
- * ```ts
164
- * ctx.render('dashboard', { user, title: 'Dashboard' })
165
- * ctx.render('emails/welcome', { name: 'Alice' })
166
- * ```
167
- */
168
- render(template: string, data?: Record<string, any>): void;
169
- /**
170
- * Parse query params and return a standardized paginated response.
171
- * Calls `ctx.qs()` internally, then wraps your data with pagination meta.
172
- *
173
- * @param fetcher - Async function that receives ParsedQuery and returns `{ data, total }`
174
- * @param fieldConfig - Optional whitelist for filterable, sortable, searchable fields
175
- *
176
- * @example
177
- * ```ts
178
- * @Get('/')
179
- * async list(ctx: RequestContext) {
180
- * return ctx.paginate(
181
- * async (parsed) => {
182
- * const data = await db.select().from(users)
183
- * .where(query.where).limit(parsed.pagination.limit)
184
- * .offset(parsed.pagination.offset).all()
185
- * const total = await db.select({ count: count() }).from(users).get()
186
- * return { data, total: total?.count ?? 0 }
187
- * },
188
- * { filterable: ['name', 'role'], sortable: ['createdAt'] },
189
- * )
190
- * }
191
- * ```
192
- */
193
- paginate<T, TConfig extends QueryFieldConfig | undefined = undefined>(fetcher: (parsed: TypedParsedQuery<TConfig>) => Promise<{
194
- data: T[];
195
- total: number;
196
- }>, fieldConfig?: TConfig): Promise<Response<any, Record<string, any>>>;
197
- /**
198
- * Start an SSE (Server-Sent Events) stream.
199
- * Sets the correct headers and returns helpers to send events.
200
- *
201
- * @example
202
- * ```ts
203
- * @Get('/events')
204
- * async stream(ctx: RequestContext) {
205
- * const sse = ctx.sse()
206
- *
207
- * const interval = setInterval(() => {
208
- * sse.send({ time: new Date().toISOString() }, 'tick')
209
- * }, 1000)
210
- *
211
- * sse.onClose(() => clearInterval(interval))
212
- * }
213
- * ```
214
- */
215
- sse(): {
216
- /** Send an SSE event with optional event name and id */send: (data: any, event?: string, id?: string) => void; /** Send a comment (keeps connection alive) */
217
- comment: (text: string) => void; /** Register a callback when the client disconnects */
218
- onClose: (fn: () => void) => void; /** End the SSE stream */
219
- close: () => void;
220
- };
221
- }
222
- /**
223
- * Short alias for `RequestContext` parameterised by a route shape.
224
- *
225
- * Use with `kick typegen`'s generated `KickRoutes` namespace for
226
- * fully-typed `ctx.params`, `ctx.body`, and `ctx.query`. Metadata
227
- * typing (`ctx.get()`, `ctx.set()`, `ctx.user`) comes from
228
- * `ContextMeta` augmentation and works on all `RequestContext` instances.
229
- *
230
- * @example
231
- * ```ts
232
- * @Get('/:id')
233
- * getUser(ctx: Ctx<KickRoutes.UserController['getUser']>) {
234
- * ctx.params.id // typed from RouteShape
235
- * ctx.body // typed from RouteShape
236
- * ctx.user // typed from ContextMeta
237
- * ctx.get('tenant') // typed from ContextMeta
238
- * }
239
- * ```
240
- */
241
- type Ctx<TRoute extends RouteShape = RouteShape> = RequestContext<TRoute extends {
242
- body: infer B;
243
- } ? B : any, TRoute extends {
244
- params: infer P;
245
- } ? P : any, TRoute extends {
246
- query: infer Q;
247
- } ? Q : any>;
248
- /**
249
- * Global ambient registry of typed routes, populated by `kick typegen`.
250
- *
251
- * Each interface inside `KickRoutes` corresponds to a controller class;
252
- * each property is one route method on that controller. The values
253
- * conform to `RouteShape`.
254
- *
255
- * Empty by default — declarations come from `.kickjs/types/routes.d.ts`
256
- * generated alongside the rest of the typegen output.
257
- */
258
- declare global {
259
- namespace KickRoutes {}
260
- }
261
- //#endregion
262
- export { ContextMeta, Ctx, RequestContext, RouteShape };
263
- //# sourceMappingURL=context.d.mts.map
2
+ import { t as ContextMeta } from "../execution-context-DKnt61pY.mjs";
3
+ import { n as RequestContext, r as RouteShape, t as Ctx } from "../context-Ymvv-85x.mjs";
4
+ export { ContextMeta, Ctx, RequestContext, RouteShape };