@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,260 @@
1
+
2
+ import { n as ExecutionContext, r as MetaValue } from "./execution-context-DKnt61pY.mjs";
3
+ import { g as QueryFieldConfig, y as TypedParsedQuery } from "./index-B9cyOQAe.mjs";
4
+ import * as _$node_http0 from "node:http";
5
+ import { NextFunction, Request, Response } from "express";
6
+
7
+ //#region src/http/context.d.ts
8
+ /**
9
+ * The shape of a single route entry in `KickRoutes`. Generated by
10
+ * `kick typegen` and consumed via the `Ctx<T>` helper. Each field is
11
+ * `unknown` by default and is filled in as the typegen learns more
12
+ * about the route (URL params from the path, body/query from validation
13
+ * schemas, etc.).
14
+ */
15
+ interface RouteShape {
16
+ params?: unknown;
17
+ body?: unknown;
18
+ query?: unknown;
19
+ response?: unknown;
20
+ }
21
+ /**
22
+ * Unified request/response abstraction passed to every controller method.
23
+ * Shields handlers from raw Express objects and provides convenience methods.
24
+ *
25
+ * Implements {@link ExecutionContext} so the transport-agnostic Context
26
+ * Contributor pipeline (#107) can run against this concrete HTTP context
27
+ * the same way it will run against future WS / queue / cron contexts.
28
+ */
29
+ declare class RequestContext<TBody = any, TParams = any, TQuery = any> implements ExecutionContext {
30
+ readonly req: Request;
31
+ readonly res: Response;
32
+ readonly next: NextFunction;
33
+ constructor(req: Request, res: Response, next: NextFunction);
34
+ /**
35
+ * Read-side accessor for the per-request metadata map.
36
+ *
37
+ * Returns the AsyncLocalStorage map (`requestStore.getStore().values`)
38
+ * shared with the Context Contributor pipeline when an ALS frame is
39
+ * active. Returns `null` outside any frame — read-side callers
40
+ * (`ctx.get`, `ctx.user`, `ctx.tenantId`, `ctx.roles`) treat that as
41
+ * "no metadata" and fall through to their `req.*` defaults. Reads
42
+ * never throw because outside an ALS frame nobody could have written
43
+ * via `ctx.set` anyway, so an empty answer is the truthful one.
44
+ */
45
+ private metadataReadOnly;
46
+ /**
47
+ * Write-side accessor for the per-request metadata map.
48
+ *
49
+ * Returns the same map as {@link metadataReadOnly} when an ALS frame
50
+ * is active. Throws otherwise — writing to a fallback map outside
51
+ * the ALS frame would silently lose data because other call sites
52
+ * (downstream contributors, request-logger, etc.) read from the
53
+ * canonical store and would never see it. Mount
54
+ * `requestScopeMiddleware()` (Application does this for you in
55
+ * `'auto'` mode) or wrap your test setup in
56
+ * `requestStore.run({...}, () => …)` to fix.
57
+ */
58
+ private metadataForWrite;
59
+ get body(): TBody;
60
+ get params(): TParams;
61
+ get query(): TQuery;
62
+ get headers(): _$node_http0.IncomingHttpHeaders;
63
+ get requestId(): string | undefined;
64
+ /** Session data (requires session middleware) */
65
+ get session(): any;
66
+ /**
67
+ * The authenticated user set by AuthAdapter.
68
+ * Reads from the per-request metadata store first (`ctx.set('user', ...)`),
69
+ * then falls back to `req.user` (set directly by AuthAdapter middleware).
70
+ *
71
+ * Extend the `AuthUser` interface via module augmentation in `@forinda/kickjs-auth`
72
+ * to get full typing.
73
+ *
74
+ * @example
75
+ * ```ts
76
+ * @Get('/me')
77
+ * @Authenticated()
78
+ * getProfile(ctx: RequestContext) {
79
+ * const user = ctx.user
80
+ * if (!user) return ctx.notFound()
81
+ * return ctx.json({ user })
82
+ * }
83
+ * ```
84
+ */
85
+ get user(): MetaValue<'user', Record<string, any>> | undefined;
86
+ /**
87
+ * Tenant identifier for multi-tenant apps. Reads `user.tenantId` —
88
+ * populated either by `AuthAdapter.testMode({ tenantId })`, a tenant
89
+ * resolver middleware, or manually on the strategy's `mapPayload`.
90
+ *
91
+ * Augment `AuthUser` (or `ContextMeta['user']`) to widen the return
92
+ * type if your user shape guarantees a non-`string | undefined` id.
93
+ */
94
+ get tenantId(): string | undefined;
95
+ /**
96
+ * Effective role list for the current user. Prefers `user.tenantRoles`
97
+ * (populated by `AuthAdapterOptions.roleResolver` under a tenant) and
98
+ * falls back to `user.roles`. Returns an empty array when the user is
99
+ * absent or the shape has neither field.
100
+ */
101
+ get roles(): string[];
102
+ /**
103
+ * Parse the request query string into structured filters, sort, pagination, and search.
104
+ * Pass the result to an ORM query builder adapter (Drizzle, Prisma, Sequelize, etc.).
105
+ *
106
+ * Generic over the field config: when passed an inline literal (or
107
+ * `as const`), `filters[].field` and `sort[].field` are narrowed to
108
+ * the exact whitelisted field names. Pass nothing or a non-literal
109
+ * config and you get the loose `string` fallback.
110
+ *
111
+ * @param fieldConfig - Optional whitelist for filterable, sortable, and searchable fields
112
+ *
113
+ * @example
114
+ * ```ts
115
+ * @Get('/')
116
+ * async list(ctx: RequestContext) {
117
+ * const parsed = ctx.qs({
118
+ * filterable: ['status', 'priority'],
119
+ * sortable: ['createdAt', 'title'],
120
+ * } as const)
121
+ * parsed.filters[0].field // typed as 'status' | 'priority'
122
+ * parsed.sort[0].field // typed as 'createdAt' | 'title'
123
+ * }
124
+ * ```
125
+ */
126
+ qs<TConfig extends QueryFieldConfig | undefined = undefined>(fieldConfig?: TConfig): TypedParsedQuery<TConfig>;
127
+ /** Single uploaded file (requires @FileUpload({ mode: 'single' })) */
128
+ get file(): any;
129
+ /** Array of uploaded files (requires @FileUpload({ mode: 'array' })) */
130
+ get files(): any[] | undefined;
131
+ /**
132
+ * Read a value from the per-request metadata store.
133
+ *
134
+ * When `ContextMeta` has been augmented with a matching key, the return
135
+ * type is inferred automatically. For ad-hoc keys, pass a generic:
136
+ * `ctx.get<MyType>('custom')`.
137
+ */
138
+ get<K extends string>(key: K): MetaValue<K> | undefined;
139
+ /**
140
+ * Write a value to the per-request metadata store. Throws when no
141
+ * AsyncLocalStorage frame is active — see {@link metadataForWrite}
142
+ * for why a silent fallback is the wrong default.
143
+ */
144
+ set<K extends string>(key: K, value: MetaValue<K>): void;
145
+ json(data: any, status?: number): Response<any, Record<string, any>>;
146
+ created(data: any): Response<any, Record<string, any>>;
147
+ noContent(): Response<any, Record<string, any>>;
148
+ notFound(message?: string): Response<any, Record<string, any>>;
149
+ badRequest(message: string): Response<any, Record<string, any>>;
150
+ html(content: string, status?: number): Response<any, Record<string, any>>;
151
+ download(buffer: Buffer, filename: string, contentType?: string): Response<any, Record<string, any>>;
152
+ /**
153
+ * Render a template using the registered view engine (EJS, Pug, Handlebars, etc.).
154
+ * Requires a ViewAdapter to be configured in bootstrap().
155
+ *
156
+ * @param template - Template name (without extension, relative to viewsDir)
157
+ * @param data - Data to pass to the template
158
+ *
159
+ * @example
160
+ * ```ts
161
+ * ctx.render('dashboard', { user, title: 'Dashboard' })
162
+ * ctx.render('emails/welcome', { name: 'Alice' })
163
+ * ```
164
+ */
165
+ render(template: string, data?: Record<string, any>): void;
166
+ /**
167
+ * Parse query params and return a standardized paginated response.
168
+ * Calls `ctx.qs()` internally, then wraps your data with pagination meta.
169
+ *
170
+ * @param fetcher - Async function that receives ParsedQuery and returns `{ data, total }`
171
+ * @param fieldConfig - Optional whitelist for filterable, sortable, searchable fields
172
+ *
173
+ * @example
174
+ * ```ts
175
+ * @Get('/')
176
+ * async list(ctx: RequestContext) {
177
+ * return ctx.paginate(
178
+ * async (parsed) => {
179
+ * const data = await db.select().from(users)
180
+ * .where(query.where).limit(parsed.pagination.limit)
181
+ * .offset(parsed.pagination.offset).all()
182
+ * const total = await db.select({ count: count() }).from(users).get()
183
+ * return { data, total: total?.count ?? 0 }
184
+ * },
185
+ * { filterable: ['name', 'role'], sortable: ['createdAt'] },
186
+ * )
187
+ * }
188
+ * ```
189
+ */
190
+ paginate<T, TConfig extends QueryFieldConfig | undefined = undefined>(fetcher: (parsed: TypedParsedQuery<TConfig>) => Promise<{
191
+ data: T[];
192
+ total: number;
193
+ }>, fieldConfig?: TConfig): Promise<Response<any, Record<string, any>>>;
194
+ /**
195
+ * Start an SSE (Server-Sent Events) stream.
196
+ * Sets the correct headers and returns helpers to send events.
197
+ *
198
+ * @example
199
+ * ```ts
200
+ * @Get('/events')
201
+ * async stream(ctx: RequestContext) {
202
+ * const sse = ctx.sse()
203
+ *
204
+ * const interval = setInterval(() => {
205
+ * sse.send({ time: new Date().toISOString() }, 'tick')
206
+ * }, 1000)
207
+ *
208
+ * sse.onClose(() => clearInterval(interval))
209
+ * }
210
+ * ```
211
+ */
212
+ sse(): {
213
+ /** Send an SSE event with optional event name and id */send: (data: any, event?: string, id?: string) => void; /** Send a comment (keeps connection alive) */
214
+ comment: (text: string) => void; /** Register a callback when the client disconnects */
215
+ onClose: (fn: () => void) => void; /** End the SSE stream */
216
+ close: () => void;
217
+ };
218
+ }
219
+ /**
220
+ * Short alias for `RequestContext` parameterised by a route shape.
221
+ *
222
+ * Use with `kick typegen`'s generated `KickRoutes` namespace for
223
+ * fully-typed `ctx.params`, `ctx.body`, and `ctx.query`. Metadata
224
+ * typing (`ctx.get()`, `ctx.set()`, `ctx.user`) comes from
225
+ * `ContextMeta` augmentation and works on all `RequestContext` instances.
226
+ *
227
+ * @example
228
+ * ```ts
229
+ * @Get('/:id')
230
+ * getUser(ctx: Ctx<KickRoutes.UserController['getUser']>) {
231
+ * ctx.params.id // typed from RouteShape
232
+ * ctx.body // typed from RouteShape
233
+ * ctx.user // typed from ContextMeta
234
+ * ctx.get('tenant') // typed from ContextMeta
235
+ * }
236
+ * ```
237
+ */
238
+ type Ctx<TRoute extends RouteShape = RouteShape> = RequestContext<TRoute extends {
239
+ body: infer B;
240
+ } ? B : any, TRoute extends {
241
+ params: infer P;
242
+ } ? P : any, TRoute extends {
243
+ query: infer Q;
244
+ } ? Q : any>;
245
+ /**
246
+ * Global ambient registry of typed routes, populated by `kick typegen`.
247
+ *
248
+ * Each interface inside `KickRoutes` corresponds to a controller class;
249
+ * each property is one route method on that controller. The values
250
+ * conform to `RouteShape`.
251
+ *
252
+ * Empty by default — declarations come from `.kickjs/types/routes.d.ts`
253
+ * generated alongside the rest of the typegen output.
254
+ */
255
+ declare global {
256
+ namespace KickRoutes {}
257
+ } //# sourceMappingURL=context.d.ts.map
258
+ //#endregion
259
+ export { RequestContext as n, RouteShape as r, Ctx as t };
260
+ //# sourceMappingURL=context-Ymvv-85x.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context-Ymvv-85x.d.mts","names":[],"sources":["../src/http/context.ts"],"mappings":";;;;;;;;;;;;;AAwCA;UAfiB,UAAA;EACf,MAAA;EACA,IAAA;EACA,KAAA;EACA,QAAA;AAAA;;;;;;;;;cAWW,cAAA,sDAAoE,gBAAA;EAAA,SAE7D,GAAA,EAAK,OAAA;EAAA,SACL,GAAA,EAAK,QAAA;EAAA,SACL,IAAA,EAAM,YAAA;cAFN,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,QAAA,EACL,IAAA,EAAM,YAAA;EAuKiB;;;;;;;;;;;EAAA,QAzJjC,gBAAA;EAoLsB;;;;;;;;;;;;EAAA,QApKtB,gBAAA;EAAA,IAYJ,IAAA,CAAA,GAAQ,KAAA;EAAA,IAIR,MAAA,CAAA,GAAU,OAAA;EAAA,IAIV,KAAA,CAAA,GAAS,MAAA;EAAA,IAIT,OAAA,CAAA,GAJe,YAAA,CAIR,mBAAA;EAAA,IAIP,SAAA,CAAA;EA9D2E;EAAA,IAmE3E,OAAA,CAAA;EAnE2F;;;;;;;;;;;;;;;;;;;EAAA,IA0F3F,IAAA,CAAA,GAAQ,SAAA,SAAkB,MAAA;EA5C1B;;;;;;;;EAAA,IAwDA,QAAA,CAAA;EAnCA;;;;;;EAAA,IA8CA,KAAA,CAAA;EA+BD;;;;;;;;;;;;;;;;;;;;;;;;EAAH,EAAA,iBAAmB,gBAAA,yBAAA,CACjB,WAAA,GAAc,OAAA,GACb,gBAAA,CAAiB,OAAA;EAwCQ;EAAA,IAjCxB,IAAA,CAAA;EAqCI;EAAA,IAhCJ,KAAA,CAAA;EAgCa;;;;;;;EAnBjB,GAAA,kBAAA,CAAsB,GAAA,EAAK,CAAA,GAAI,SAAA,CAAU,CAAA;EA+BzC;;;;;EAtBA,GAAA,kBAAA,CAAsB,GAAA,EAAK,CAAA,EAAG,KAAA,EAAO,SAAA,CAAU,CAAA;EAM/C,IAAA,CAAK,IAAA,OAAW,MAAA,YAAY,QAAA,MAAA,MAAA;EAI5B,OAAA,CAAQ,IAAA,QAAS,QAAA,MAAA,MAAA;EAIjB,SAAA,CAAA,GAAS,QAAA,MAAA,MAAA;EAIT,QAAA,CAAS,OAAA,YAAqB,QAAA,MAAA,MAAA;EAI9B,UAAA,CAAW,OAAA,WAAe,QAAA,MAAA,MAAA;EAI1B,IAAA,CAAK,OAAA,UAAiB,MAAA,YAAY,QAAA,MAAA,MAAA;EAIlC,QAAA,CAAS,MAAA,EAAQ,MAAA,EAAQ,QAAA,UAAkB,WAAA,YAAwC,QAAA,MAAA,MAAA;EAAxC;;;;;;;;;;;;;EAmB3C,MAAA,CAAO,QAAA,UAAkB,IAAA,GAAM,MAAA;EA6BmB;;;;;;;;;;;;;;;;;;;;;;AAoGpD;;EArGQ,QAAA,oBAA4B,gBAAA,yBAAA,CAChC,OAAA,GAAU,MAAA,EAAQ,gBAAA,CAAiB,OAAA,MAAa,OAAA;IAAU,IAAA,EAAM,CAAA;IAAK,KAAA;EAAA,IACrE,WAAA,GAAc,OAAA,GAAO,OAAA,CAAA,QAAA,MAAA,MAAA;EAqGvB;;;;;;;;;;;;;;;;;;EA3DA,GAAA,CAAA;IA4D8B,0EA3CV,KAAA,WAAgB,EAAA,oBA2CC;qCACtC;uCAAA;;;;;;;;;;;;;;;;;;;;;;;KAJW,GAAA,gBAAmB,UAAA,GAAa,UAAA,IAAc,cAAA,CACxD,MAAA;EAAiB,IAAA;AAAA,IAAkB,CAAA,QACnC,MAAA;EAAiB,MAAA;AAAA,IAAoB,CAAA,QACrC,MAAA;EAAiB,KAAA;AAAA,IAAmB,CAAA;;;;;;;;;;;QAa9B,MAAA;EAAA,UAEI,UAAA;AAAA"}
@@ -0,0 +1,111 @@
1
+
2
+ import { i as Constructor, o as MaybePromise } from "./interfaces-B50n7dwl.mjs";
3
+ import { s as InjectionToken } from "./container-CnWDsxi-.mjs";
4
+ import { n as ExecutionContext, r as MetaValue } from "./execution-context-DKnt61pY.mjs";
5
+ //#region src/core/context-decorator.d.ts
6
+ /**
7
+ * Maps a `deps` declaration object to its resolved-instance shape.
8
+ *
9
+ * `deps: { db: DB_TOKEN, cache: CacheService }` produces
10
+ * `{ db: Db, cache: CacheService }` — the runner resolves each value
11
+ * against the DI container and hands the result to `resolve()`.
12
+ */
13
+ type ResolvedDeps<D extends Record<string, unknown>> = { [K in keyof D]: D[K] extends InjectionToken<infer T> ? T : D[K] extends Constructor<infer T> ? T : unknown };
14
+ /**
15
+ * Spec passed to {@link defineContextDecorator}. Describes one entry in
16
+ * the per-request contributor pipeline.
17
+ *
18
+ * @typeParam K - The {@link ContextMeta} key this contributor populates.
19
+ * @typeParam D - DI dependency declaration shape (see {@link ResolvedDeps}).
20
+ * @typeParam Ctx - Concrete execution-context type. Defaults to the abstract
21
+ * {@link ExecutionContext}; HTTP contributors typically
22
+ * default to `RequestContext` at the call site.
23
+ */
24
+ interface ContextDecoratorSpec<K extends string = string, D extends Record<string, unknown> = Record<string, never>, Ctx extends ExecutionContext = ExecutionContext> {
25
+ /** ContextMeta key the resolved value is written to. */
26
+ key: K;
27
+ /**
28
+ * DI dependencies resolved by the runner before `resolve()` runs.
29
+ * Map entry keys become property names on the resolved-deps argument
30
+ * passed to `resolve()`.
31
+ */
32
+ deps?: D;
33
+ /**
34
+ * Other contributor keys that must populate before this one runs.
35
+ * Enforced via topo-sort at startup; missing deps and cycles fail boot.
36
+ */
37
+ dependsOn?: readonly string[];
38
+ /**
39
+ * If `true`, a thrown `resolve` skips the contributor instead of
40
+ * forwarding to the request error handler. The key is left unset
41
+ * and downstream consumers see `ctx.get(key) === undefined`.
42
+ */
43
+ optional?: boolean;
44
+ /**
45
+ * Hook invoked when `resolve()` throws and `optional` is `false`.
46
+ * Returning a value writes it to `ctx.set(key, …)`; returning
47
+ * `undefined` / `void` skips. Throwing inside the hook forwards
48
+ * the new error to the request error handler.
49
+ *
50
+ * Async-permitted by design — adopters frequently want to
51
+ * `await auditService.log(err)` or `await cache.fallback(...)`.
52
+ */
53
+ onError?: (err: unknown, ctx: Ctx) => MaybePromise<MetaValue<K> | undefined | void>;
54
+ /** Compute and return the value to write into `ctx.set(key, …)`. */
55
+ resolve: (ctx: Ctx, deps: ResolvedDeps<D>) => MaybePromise<MetaValue<K>>;
56
+ }
57
+ /**
58
+ * Internal, normalised registration produced by {@link defineContextDecorator}.
59
+ *
60
+ * Frozen and shared by every use site of the decorator (method, class,
61
+ * module, adapter, global). The pipeline builder dedupes by `key` using
62
+ * the precedence rule defined in §20.4 of `architecture.md`.
63
+ */
64
+ interface ContributorRegistration<K extends string = string, D extends Record<string, unknown> = Record<string, never>, Ctx extends ExecutionContext = ExecutionContext> {
65
+ readonly key: K;
66
+ readonly deps: D;
67
+ readonly dependsOn: readonly string[];
68
+ readonly optional: boolean;
69
+ readonly onError?: ContextDecoratorSpec<K, D, Ctx>['onError'];
70
+ readonly resolve: ContextDecoratorSpec<K, D, Ctx>['resolve'];
71
+ }
72
+ /**
73
+ * The value returned by {@link defineContextDecorator}. Callable as either
74
+ * a method or class decorator, and exposes the underlying frozen
75
+ * {@link ContributorRegistration} via `.registration` for non-decorator
76
+ * registration sites (module hooks, adapter hooks, bootstrap option).
77
+ */
78
+ interface ContextDecorator<K extends string = string, D extends Record<string, unknown> = Record<string, never>, Ctx extends ExecutionContext = ExecutionContext> {
79
+ (target: object, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): void;
80
+ readonly registration: ContributorRegistration<K, D, Ctx>;
81
+ }
82
+ /**
83
+ * Define a typed context contributor.
84
+ *
85
+ * The returned function works as a method or class decorator:
86
+ *
87
+ * ```ts
88
+ * const LoadTenant = defineContextDecorator({
89
+ * key: 'tenant',
90
+ * deps: { tenants: TenantsRepo },
91
+ * resolve: (ctx, { tenants }) => tenants.findByHost(ctx.requestId),
92
+ * })
93
+ *
94
+ * @LoadTenant
95
+ * @Get('/me')
96
+ * me(ctx: RequestContext) {
97
+ * ctx.get('tenant') // typed via ContextMeta
98
+ * }
99
+ * ```
100
+ *
101
+ * For non-decorator registration (module/adapter/bootstrap), pass
102
+ * `LoadTenant.registration` into the appropriate contributors list.
103
+ *
104
+ * **No runtime behaviour is wired in Phase 1.** This factory only writes
105
+ * metadata; the topo-sort, runner, and HTTP integration land in later
106
+ * phases. See `architecture.md` §20 for the full pipeline plan.
107
+ */
108
+ declare function defineContextDecorator<K extends string, D extends Record<string, unknown> = Record<string, never>, Ctx extends ExecutionContext = ExecutionContext>(spec: ContextDecoratorSpec<K, D, Ctx>): ContextDecorator<K, D, Ctx>;
109
+ //#endregion
110
+ export { defineContextDecorator as a, ResolvedDeps as i, ContextDecoratorSpec as n, ContributorRegistration as r, ContextDecorator as t };
111
+ //# sourceMappingURL=context-decorator-B5v3VQCN.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context-decorator-B5v3VQCN.d.mts","names":[],"sources":["../src/core/context-decorator.ts"],"mappings":";;;;;;;AAaA;;;;;KAAY,YAAA,WAAuB,MAAA,mCACrB,CAAA,GAAI,CAAA,CAAE,CAAA,UAAW,cAAA,YACzB,CAAA,GACA,CAAA,CAAE,CAAA,UAAW,WAAA,YACX,CAAA;;;;;;;;;;;UAcS,oBAAA,sCAEL,MAAA,oBAA0B,MAAA,6BACxB,gBAAA,GAAmB,gBAAA;EApBF;EAuB7B,GAAA,EAAK,CAAA;EAtBD;;;;;EA4BJ,IAAA,GAAO,CAAA;EA1BA;;AAcT;;EAiBE,SAAA;EAfU;;;;;EAqBV,QAAA;EAU8B;;;;;;;;;EAA9B,OAAA,IAAW,GAAA,WAAc,GAAA,EAAK,GAAA,KAAQ,YAAA,CAAa,SAAA,CAAU,CAAA;EAEH;EAA1D,OAAA,GAAU,GAAA,EAAK,GAAA,EAAK,IAAA,EAAM,YAAA,CAAa,CAAA,MAAO,YAAA,CAAa,SAAA,CAAU,CAAA;AAAA;;;;;;;;UAUtD,uBAAA,sCAEL,MAAA,oBAA0B,MAAA,6BACxB,gBAAA,GAAmB,gBAAA;EAAA,SAEtB,GAAA,EAAK,CAAA;EAAA,SACL,IAAA,EAAM,CAAA;EAAA,SACN,SAAA;EAAA,SACA,QAAA;EAAA,SACA,OAAA,GAAU,oBAAA,CAAqB,CAAA,EAAG,CAAA,EAAG,GAAA;EAAA,SACrC,OAAA,EAAS,oBAAA,CAAqB,CAAA,EAAG,CAAA,EAAG,GAAA;AAAA;;;;;;;UAS9B,gBAAA,sCAEL,MAAA,oBAA0B,MAAA,6BACxB,gBAAA,GAAmB,gBAAA;EAAA,CAE9B,MAAA,UAAgB,WAAA,oBAA+B,UAAA,GAAa,kBAAA;EAAA,SACpD,YAAA,EAAc,uBAAA,CAAwB,CAAA,EAAG,CAAA,EAAG,GAAA;AAAA;;;;;;AAzBvD;;;;;;;;;;;;;;;;;;;;;iBAsDgB,sBAAA,6BAEJ,MAAA,oBAA0B,MAAA,6BACxB,gBAAA,GAAmB,gBAAA,CAAA,CAC/B,IAAA,EAAM,oBAAA,CAAqB,CAAA,EAAG,CAAA,EAAG,GAAA,IAAO,gBAAA,CAAiB,CAAA,EAAG,CAAA,EAAG,GAAA"}
@@ -1,3 +1,3 @@
1
1
 
2
- import { a as MiddlewarePhase, i as AppAdapterClass, n as AdapterMiddleware, r as AppAdapter, t as AdapterContext } from "../adapter-DjL8ql5d.mjs";
2
+ import { a as MiddlewarePhase, i as AppAdapterClass, n as AdapterMiddleware, r as AppAdapter, t as AdapterContext } from "../adapter-BNw2pGbg.mjs";
3
3
  export { AdapterContext, AdapterMiddleware, AppAdapter, AppAdapterClass, MiddlewarePhase };
@@ -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
  *
@@ -1,3 +1,3 @@
1
1
 
2
- import { n as AppModuleClass, r as ModuleRoutes, t as AppModule } from "../app-module-Cotu9TIC.mjs";
2
+ import { n as AppModuleClass, r as ModuleRoutes, t as AppModule } from "../app-module-CO0ksPCm.mjs";
3
3
  export { AppModule, AppModuleClass, ModuleRoutes };
@@ -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
  *
@@ -1,3 +1,3 @@
1
1
 
2
- import { a as Cacheable, c as setCacheProvider, i as CacheProvider, n as CacheEvict, o as MemoryCacheProvider, r as CacheOptions, s as getCacheProvider, t as CACHEABLE_META } from "../cache-CcTzzNdr.mjs";
2
+ import { a as Cacheable, c as setCacheProvider, i as CacheProvider, n as CacheEvict, o as MemoryCacheProvider, r as CacheOptions, s as getCacheProvider, t as CACHEABLE_META } from "../cache-BStrqXSZ.mjs";
3
3
  export { CACHEABLE_META, CacheEvict, CacheOptions, CacheProvider, Cacheable, MemoryCacheProvider, getCacheProvider, setCacheProvider };
@@ -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
  *
@@ -50,7 +50,7 @@ let _cacheProvider = new MemoryCacheProvider();
50
50
  *
51
51
  * @example
52
52
  * ```ts
53
- * import { setCacheProvider } from '@forinda/kickjs-core'
53
+ * import { setCacheProvider } from '@forinda/kickjs'
54
54
  * import { RedisCacheProvider } from './redis-cache'
55
55
  *
56
56
  * setCacheProvider(new RedisCacheProvider(redisClient))
@@ -1 +1 @@
1
- {"version":3,"file":"cache.mjs","names":[],"sources":["../../src/core/cache.ts"],"sourcesContent":["import 'reflect-metadata'\n\nconst CACHEABLE_META = Symbol('kick:cacheable')\n\n// ── CacheProvider Interface ─────────────────────────────────────────────\n\n/**\n * Abstract cache backend. Implement this interface to use Redis, Memcached,\n * or any other cache store with @Cacheable and @CacheEvict.\n *\n * @example\n * ```ts\n * class RedisCacheProvider implements CacheProvider {\n * private client: RedisClient\n * constructor(client: RedisClient) { this.client = client }\n * async get(key: string) {\n * const val = await this.client.get(key)\n * return val ? JSON.parse(val) : null\n * }\n * async set(key: string, value: any, ttlMs: number) {\n * await this.client.set(key, JSON.stringify(value), 'PX', ttlMs)\n * }\n * async del(key: string) { await this.client.del(key) }\n * async delByPrefix(prefix: string) {\n * const keys = await this.client.keys(prefix + '*')\n * if (keys.length) await this.client.del(...keys)\n * }\n * }\n * ```\n */\nexport interface CacheProvider {\n /** Retrieve a cached value. Return null if not found or expired. */\n get(key: string): Promise<any | null>\n /** Store a value with a TTL in milliseconds. */\n set(key: string, value: any, ttlMs: number): Promise<void>\n /** Delete a specific cache key. */\n del(key: string): Promise<void>\n /** Delete all keys matching a prefix. Used by @CacheEvict. */\n delByPrefix?(prefix: string): Promise<void>\n /** Optional cleanup on shutdown. */\n shutdown?(): Promise<void>\n}\n\n// ── Built-in Memory Provider ────────────────────────────────────────────\n\n/**\n * Default in-memory cache provider using a Map.\n * Suitable for development and single-instance deployments.\n * For multi-instance or production, use a Redis-backed provider.\n */\nexport class MemoryCacheProvider implements CacheProvider {\n private store = new Map<string, { data: any; expiresAt: number }>()\n\n async get(key: string): Promise<any | null> {\n const entry = this.store.get(key)\n if (!entry) return null\n if (entry.expiresAt <= Date.now()) {\n this.store.delete(key)\n return null\n }\n return entry.data\n }\n\n async set(key: string, value: any, ttlMs: number): Promise<void> {\n this.store.set(key, { data: value, expiresAt: Date.now() + ttlMs })\n }\n\n async del(key: string): Promise<void> {\n this.store.delete(key)\n }\n\n async delByPrefix(prefix: string): Promise<void> {\n for (const key of this.store.keys()) {\n if (key.startsWith(prefix)) {\n this.store.delete(key)\n }\n }\n }\n\n async shutdown(): Promise<void> {\n this.store.clear()\n }\n}\n\n// ── Global Cache Registry ───────────────────────────────────────────────\n\nlet _cacheProvider: CacheProvider = new MemoryCacheProvider()\n\n/**\n * Set the global cache provider used by @Cacheable and @CacheEvict.\n * Call this before bootstrapping your app.\n *\n * @example\n * ```ts\n * import { setCacheProvider } from '@forinda/kickjs-core'\n * import { RedisCacheProvider } from './redis-cache'\n *\n * setCacheProvider(new RedisCacheProvider(redisClient))\n * ```\n */\nexport function setCacheProvider(provider: CacheProvider): void {\n _cacheProvider = provider\n}\n\n/** Get the current cache provider */\nexport function getCacheProvider(): CacheProvider {\n return _cacheProvider\n}\n\n// ── Cache Options ───────────────────────────────────────────────────────\n\nexport interface CacheOptions {\n /** Time-to-live in seconds (default: 60) */\n ttl?: number\n /** Cache key prefix (default: ClassName.methodName) */\n key?: string\n}\n\n// ── @Cacheable Decorator ────────────────────────────────────────────────\n\n/**\n * Cache the return value of a method for the specified TTL.\n * Uses the globally registered CacheProvider (default: MemoryCacheProvider).\n *\n * Call `setCacheProvider()` to use Redis or any custom backend.\n *\n * @param ttl - Time-to-live in seconds (default: 60)\n * @param options.key - Custom cache key prefix\n */\nexport function Cacheable(ttl?: number, options?: { key?: string }): MethodDecorator {\n return (_target, propertyKey, descriptor: PropertyDescriptor) => {\n const original = descriptor.value\n const cacheTtl = (ttl ?? 60) * 1000\n const keyPrefix = options?.key ?? String(propertyKey)\n\n descriptor.value = async function (...args: any[]) {\n const cacheKey = `${keyPrefix}:${JSON.stringify(args)}`\n const provider = getCacheProvider()\n\n const cached = await provider.get(cacheKey)\n if (cached !== null) {\n return cached\n }\n\n const result = await original.apply(this, args)\n await provider.set(cacheKey, result, cacheTtl)\n return result\n }\n\n return descriptor\n }\n}\n\n// ── @CacheEvict Decorator ───────────────────────────────────────────────\n\n/**\n * Evict cached values matching a key prefix after the method executes.\n * Works with any CacheProvider that implements `delByPrefix`.\n *\n * @param key - Cache key prefix to evict (matches the @Cacheable key)\n */\nexport function CacheEvict(key: string): MethodDecorator {\n return (_target, _propertyKey, descriptor: PropertyDescriptor) => {\n const original = descriptor.value\n\n descriptor.value = async function (...args: any[]) {\n const result = await original.apply(this, args)\n const provider = getCacheProvider()\n if (provider.delByPrefix) {\n await provider.delByPrefix(key)\n }\n return result\n }\n\n return descriptor\n }\n}\n\nexport { CACHEABLE_META }\n"],"mappings":";;;;;;;;;;;;AAEA,MAAM,iBAAiB,OAAO,iBAAiB;;;;;;AAgD/C,IAAa,sBAAb,MAA0D;CACxD,wBAAgB,IAAI,KAA+C;CAEnE,MAAM,IAAI,KAAkC;EAC1C,MAAM,QAAQ,KAAK,MAAM,IAAI,IAAI;AACjC,MAAI,CAAC,MAAO,QAAO;AACnB,MAAI,MAAM,aAAa,KAAK,KAAK,EAAE;AACjC,QAAK,MAAM,OAAO,IAAI;AACtB,UAAO;;AAET,SAAO,MAAM;;CAGf,MAAM,IAAI,KAAa,OAAY,OAA8B;AAC/D,OAAK,MAAM,IAAI,KAAK;GAAE,MAAM;GAAO,WAAW,KAAK,KAAK,GAAG;GAAO,CAAC;;CAGrE,MAAM,IAAI,KAA4B;AACpC,OAAK,MAAM,OAAO,IAAI;;CAGxB,MAAM,YAAY,QAA+B;AAC/C,OAAK,MAAM,OAAO,KAAK,MAAM,MAAM,CACjC,KAAI,IAAI,WAAW,OAAO,CACxB,MAAK,MAAM,OAAO,IAAI;;CAK5B,MAAM,WAA0B;AAC9B,OAAK,MAAM,OAAO;;;AAMtB,IAAI,iBAAgC,IAAI,qBAAqB;;;;;;;;;;;;;AAc7D,SAAgB,iBAAiB,UAA+B;AAC9D,kBAAiB;;;AAInB,SAAgB,mBAAkC;AAChD,QAAO;;;;;;;;;;;AAuBT,SAAgB,UAAU,KAAc,SAA6C;AACnF,SAAQ,SAAS,aAAa,eAAmC;EAC/D,MAAM,WAAW,WAAW;EAC5B,MAAM,YAAY,OAAO,MAAM;EAC/B,MAAM,YAAY,SAAS,OAAO,OAAO,YAAY;AAErD,aAAW,QAAQ,eAAgB,GAAG,MAAa;GACjD,MAAM,WAAW,GAAG,UAAU,GAAG,KAAK,UAAU,KAAK;GACrD,MAAM,WAAW,kBAAkB;GAEnC,MAAM,SAAS,MAAM,SAAS,IAAI,SAAS;AAC3C,OAAI,WAAW,KACb,QAAO;GAGT,MAAM,SAAS,MAAM,SAAS,MAAM,MAAM,KAAK;AAC/C,SAAM,SAAS,IAAI,UAAU,QAAQ,SAAS;AAC9C,UAAO;;AAGT,SAAO;;;;;;;;;AAYX,SAAgB,WAAW,KAA8B;AACvD,SAAQ,SAAS,cAAc,eAAmC;EAChE,MAAM,WAAW,WAAW;AAE5B,aAAW,QAAQ,eAAgB,GAAG,MAAa;GACjD,MAAM,SAAS,MAAM,SAAS,MAAM,MAAM,KAAK;GAC/C,MAAM,WAAW,kBAAkB;AACnC,OAAI,SAAS,YACX,OAAM,SAAS,YAAY,IAAI;AAEjC,UAAO;;AAGT,SAAO"}
1
+ {"version":3,"file":"cache.mjs","names":[],"sources":["../../src/core/cache.ts"],"sourcesContent":["import 'reflect-metadata'\n\nconst CACHEABLE_META = Symbol('kick:cacheable')\n\n// ── CacheProvider Interface ─────────────────────────────────────────────\n\n/**\n * Abstract cache backend. Implement this interface to use Redis, Memcached,\n * or any other cache store with @Cacheable and @CacheEvict.\n *\n * @example\n * ```ts\n * class RedisCacheProvider implements CacheProvider {\n * private client: RedisClient\n * constructor(client: RedisClient) { this.client = client }\n * async get(key: string) {\n * const val = await this.client.get(key)\n * return val ? JSON.parse(val) : null\n * }\n * async set(key: string, value: any, ttlMs: number) {\n * await this.client.set(key, JSON.stringify(value), 'PX', ttlMs)\n * }\n * async del(key: string) { await this.client.del(key) }\n * async delByPrefix(prefix: string) {\n * const keys = await this.client.keys(prefix + '*')\n * if (keys.length) await this.client.del(...keys)\n * }\n * }\n * ```\n */\nexport interface CacheProvider {\n /** Retrieve a cached value. Return null if not found or expired. */\n get(key: string): Promise<any | null>\n /** Store a value with a TTL in milliseconds. */\n set(key: string, value: any, ttlMs: number): Promise<void>\n /** Delete a specific cache key. */\n del(key: string): Promise<void>\n /** Delete all keys matching a prefix. Used by @CacheEvict. */\n delByPrefix?(prefix: string): Promise<void>\n /** Optional cleanup on shutdown. */\n shutdown?(): Promise<void>\n}\n\n// ── Built-in Memory Provider ────────────────────────────────────────────\n\n/**\n * Default in-memory cache provider using a Map.\n * Suitable for development and single-instance deployments.\n * For multi-instance or production, use a Redis-backed provider.\n */\nexport class MemoryCacheProvider implements CacheProvider {\n private store = new Map<string, { data: any; expiresAt: number }>()\n\n async get(key: string): Promise<any | null> {\n const entry = this.store.get(key)\n if (!entry) return null\n if (entry.expiresAt <= Date.now()) {\n this.store.delete(key)\n return null\n }\n return entry.data\n }\n\n async set(key: string, value: any, ttlMs: number): Promise<void> {\n this.store.set(key, { data: value, expiresAt: Date.now() + ttlMs })\n }\n\n async del(key: string): Promise<void> {\n this.store.delete(key)\n }\n\n async delByPrefix(prefix: string): Promise<void> {\n for (const key of this.store.keys()) {\n if (key.startsWith(prefix)) {\n this.store.delete(key)\n }\n }\n }\n\n async shutdown(): Promise<void> {\n this.store.clear()\n }\n}\n\n// ── Global Cache Registry ───────────────────────────────────────────────\n\nlet _cacheProvider: CacheProvider = new MemoryCacheProvider()\n\n/**\n * Set the global cache provider used by @Cacheable and @CacheEvict.\n * Call this before bootstrapping your app.\n *\n * @example\n * ```ts\n * import { setCacheProvider } from '@forinda/kickjs'\n * import { RedisCacheProvider } from './redis-cache'\n *\n * setCacheProvider(new RedisCacheProvider(redisClient))\n * ```\n */\nexport function setCacheProvider(provider: CacheProvider): void {\n _cacheProvider = provider\n}\n\n/** Get the current cache provider */\nexport function getCacheProvider(): CacheProvider {\n return _cacheProvider\n}\n\n// ── Cache Options ───────────────────────────────────────────────────────\n\nexport interface CacheOptions {\n /** Time-to-live in seconds (default: 60) */\n ttl?: number\n /** Cache key prefix (default: ClassName.methodName) */\n key?: string\n}\n\n// ── @Cacheable Decorator ────────────────────────────────────────────────\n\n/**\n * Cache the return value of a method for the specified TTL.\n * Uses the globally registered CacheProvider (default: MemoryCacheProvider).\n *\n * Call `setCacheProvider()` to use Redis or any custom backend.\n *\n * @param ttl - Time-to-live in seconds (default: 60)\n * @param options.key - Custom cache key prefix\n */\nexport function Cacheable(ttl?: number, options?: { key?: string }): MethodDecorator {\n return (_target, propertyKey, descriptor: PropertyDescriptor) => {\n const original = descriptor.value\n const cacheTtl = (ttl ?? 60) * 1000\n const keyPrefix = options?.key ?? String(propertyKey)\n\n descriptor.value = async function (...args: any[]) {\n const cacheKey = `${keyPrefix}:${JSON.stringify(args)}`\n const provider = getCacheProvider()\n\n const cached = await provider.get(cacheKey)\n if (cached !== null) {\n return cached\n }\n\n const result = await original.apply(this, args)\n await provider.set(cacheKey, result, cacheTtl)\n return result\n }\n\n return descriptor\n }\n}\n\n// ── @CacheEvict Decorator ───────────────────────────────────────────────\n\n/**\n * Evict cached values matching a key prefix after the method executes.\n * Works with any CacheProvider that implements `delByPrefix`.\n *\n * @param key - Cache key prefix to evict (matches the @Cacheable key)\n */\nexport function CacheEvict(key: string): MethodDecorator {\n return (_target, _propertyKey, descriptor: PropertyDescriptor) => {\n const original = descriptor.value\n\n descriptor.value = async function (...args: any[]) {\n const result = await original.apply(this, args)\n const provider = getCacheProvider()\n if (provider.delByPrefix) {\n await provider.delByPrefix(key)\n }\n return result\n }\n\n return descriptor\n }\n}\n\nexport { CACHEABLE_META }\n"],"mappings":";;;;;;;;;;;;AAEA,MAAM,iBAAiB,OAAO,iBAAiB;;;;;;AAgD/C,IAAa,sBAAb,MAA0D;CACxD,wBAAgB,IAAI,KAA+C;CAEnE,MAAM,IAAI,KAAkC;EAC1C,MAAM,QAAQ,KAAK,MAAM,IAAI,IAAI;AACjC,MAAI,CAAC,MAAO,QAAO;AACnB,MAAI,MAAM,aAAa,KAAK,KAAK,EAAE;AACjC,QAAK,MAAM,OAAO,IAAI;AACtB,UAAO;;AAET,SAAO,MAAM;;CAGf,MAAM,IAAI,KAAa,OAAY,OAA8B;AAC/D,OAAK,MAAM,IAAI,KAAK;GAAE,MAAM;GAAO,WAAW,KAAK,KAAK,GAAG;GAAO,CAAC;;CAGrE,MAAM,IAAI,KAA4B;AACpC,OAAK,MAAM,OAAO,IAAI;;CAGxB,MAAM,YAAY,QAA+B;AAC/C,OAAK,MAAM,OAAO,KAAK,MAAM,MAAM,CACjC,KAAI,IAAI,WAAW,OAAO,CACxB,MAAK,MAAM,OAAO,IAAI;;CAK5B,MAAM,WAA0B;AAC9B,OAAK,MAAM,OAAO;;;AAMtB,IAAI,iBAAgC,IAAI,qBAAqB;;;;;;;;;;;;;AAc7D,SAAgB,iBAAiB,UAA+B;AAC9D,kBAAiB;;;AAInB,SAAgB,mBAAkC;AAChD,QAAO;;;;;;;;;;;AAuBT,SAAgB,UAAU,KAAc,SAA6C;AACnF,SAAQ,SAAS,aAAa,eAAmC;EAC/D,MAAM,WAAW,WAAW;EAC5B,MAAM,YAAY,OAAO,MAAM;EAC/B,MAAM,YAAY,SAAS,OAAO,OAAO,YAAY;AAErD,aAAW,QAAQ,eAAgB,GAAG,MAAa;GACjD,MAAM,WAAW,GAAG,UAAU,GAAG,KAAK,UAAU,KAAK;GACrD,MAAM,WAAW,kBAAkB;GAEnC,MAAM,SAAS,MAAM,SAAS,IAAI,SAAS;AAC3C,OAAI,WAAW,KACb,QAAO;GAGT,MAAM,SAAS,MAAM,SAAS,MAAM,MAAM,KAAK;AAC/C,SAAM,SAAS,IAAI,UAAU,QAAQ,SAAS;AAC9C,UAAO;;AAGT,SAAO;;;;;;;;;AAYX,SAAgB,WAAW,KAA8B;AACvD,SAAQ,SAAS,cAAc,eAAmC;EAChE,MAAM,WAAW,WAAW;AAE5B,aAAW,QAAQ,eAAgB,GAAG,MAAa;GACjD,MAAM,SAAS,MAAM,SAAS,MAAM,MAAM,KAAK;GAC/C,MAAM,WAAW,kBAAkB;AACnC,OAAI,SAAS,YACX,OAAM,SAAS,YAAY,IAAI;AAEjC,UAAO;;AAGT,SAAO"}
@@ -1,3 +1,3 @@
1
1
 
2
- import { a as tokenName, i as KickJsRegistry, n as ContainerChangeEvent, r as ContainerChangeListener, t as Container } from "../container-BJb34faa.mjs";
2
+ import { a as tokenName, i as KickJsRegistry, n as ContainerChangeEvent, r as ContainerChangeListener, t as Container } from "../container-CnWDsxi-.mjs";
3
3
  export { Container, ContainerChangeEvent, ContainerChangeListener, KickJsRegistry, tokenName };
@@ -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 { n as tokenName, t as Container } from "../container-BBZLlK6y.mjs";
11
+ import { n as tokenName, t as Container } from "../container-DYYSu58w.mjs";
12
12
  export { Container, tokenName };
@@ -1,3 +1,3 @@
1
1
 
2
- import { i as getCronJobs, n as Cron, r as CronJobMeta, t as CRON_META } from "../cron-H-IyLcOr.mjs";
2
+ import { i as getCronJobs, n as Cron, r as CronJobMeta, t as CRON_META } from "../cron-7zqvsmMI.mjs";
3
3
  export { CRON_META, Cron, CronJobMeta, getCronJobs };
@@ -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,7 +8,7 @@
8
8
  *
9
9
  * @license MIT
10
10
  */
11
- import { c as pushClassMeta, t as getClassMeta } from "../metadata-BwRJ69bC.mjs";
11
+ import { c as pushClassMeta, t as getClassMeta } from "../metadata-VQM9wChy.mjs";
12
12
  //#region src/core/cron.ts
13
13
  const CRON_META = Symbol("kick:cron");
14
14
  /**
@@ -1,3 +1,3 @@
1
1
 
2
- import { C as Put, D as Value, E as Service, O as normalizeApiQueryParamsConfig, S as PostConstruct, T as RouteDefinition, _ as Injectable, a as Builder, b as Patch, c as Controller, d as EnvKey, f as FileTypeFilter, g as Inject, h as Get, i as BaseUploadOptions, l as Delete, m as FileUploadConfig, n as ApiQueryParamsConfig, o as ColumnApiQueryParamsConfig, p as FileUpload, r as Autowired, s as Component, t as ApiQueryParams, u as Env, v as Middleware, w as Repository, x as Post, y as MiddlewareHandler } from "../decorators-C9_SN7ge.mjs";
3
- export { ApiQueryParams, ApiQueryParamsConfig, Autowired, BaseUploadOptions, Builder, ColumnApiQueryParamsConfig, Component, Controller, Delete, Env, EnvKey, FileTypeFilter, FileUpload, FileUploadConfig, Get, Inject, Injectable, Middleware, MiddlewareHandler, Patch, Post, PostConstruct, Put, Repository, RouteDefinition, Service, Value, normalizeApiQueryParamsConfig };
2
+ import { A as normalizeApiQueryParamsConfig, C as Post, D as RouteDefinition, E as Repository, O as Service, S as Patch, T as Put, _ as Get, a as Autowired, b as Middleware, c as ColumnApiQueryParamsConfig, d as Delete, f as Env, g as FileUploadConfig, h as FileUpload, i as AssetKey, k as Value, l as Component, m as FileTypeFilter, n as ApiQueryParamsConfig, o as BaseUploadOptions, p as EnvKey, r as Asset, s as Builder, t as ApiQueryParams, u as Controller, v as Inject, w as PostConstruct, x as MiddlewareHandler, y as Injectable } from "../decorators-BMvaLliz.mjs";
3
+ export { ApiQueryParams, ApiQueryParamsConfig, Asset, AssetKey, Autowired, BaseUploadOptions, Builder, ColumnApiQueryParamsConfig, Component, Controller, Delete, Env, EnvKey, FileTypeFilter, FileUpload, FileUploadConfig, Get, Inject, Injectable, Middleware, MiddlewareHandler, Patch, Post, PostConstruct, Put, Repository, RouteDefinition, Service, Value, normalizeApiQueryParamsConfig };
@@ -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,9 +8,9 @@
8
8
  *
9
9
  * @license MIT
10
10
  */
11
+ import { t as Container } from "../container-DYYSu58w.mjs";
11
12
  import { METADATA, Scope } from "./interfaces.mjs";
12
- import { c as pushClassMeta, d as setInMetaMap, f as setInMetaRecord, l as pushMethodMeta, p as setMethodMeta, u as setClassMeta } from "../metadata-BwRJ69bC.mjs";
13
- import { t as Container } from "../container-BBZLlK6y.mjs";
13
+ import { c as pushClassMeta, d as setInMetaMap, f as setInMetaRecord, l as pushMethodMeta, p as setMethodMeta, u as setClassMeta } from "../metadata-VQM9wChy.mjs";
14
14
  import "reflect-metadata";
15
15
  //#region src/core/decorators.ts
16
16
  const pendingRegistrations = [];
@@ -72,16 +72,16 @@ function Repository(options) {
72
72
  /**
73
73
  * Mark a class as an HTTP controller and register it in the DI container.
74
74
  *
75
- * @param path - **Deprecated.** The path parameter is no longer used for routing.
76
- * Route prefixes are defined by the module's `routes().path` — the single source
77
- * of truth for where routes are mounted. This parameter will be removed in a
78
- * future major version.
75
+ * Route prefixes are defined by the module's `routes().path` — the single
76
+ * source of truth for where routes mount. The legacy
77
+ * `@Controller('/path')` parameter was removed in v4; if your code
78
+ * still passes a string, see `docs/guide/migration-v3-to-v4.md` for
79
+ * the rename map.
79
80
  */
80
- function Controller(path) {
81
+ function Controller() {
81
82
  return (target) => {
82
83
  setClassMeta(METADATA.CLASS_KIND, "controller", target);
83
84
  registerInContainer(target, Scope.SINGLETON);
84
- setClassMeta(METADATA.CONTROLLER_PATH, path || "/", target);
85
85
  };
86
86
  }
87
87
  /** Mark a method as a lifecycle hook called after instantiation */
@@ -96,12 +96,6 @@ function Autowired(token) {
96
96
  setInMetaMap(METADATA.AUTOWIRED, target, propertyKey, token);
97
97
  };
98
98
  }
99
- /**
100
- * Constructor parameter injection with an explicit token.
101
- *
102
- * **Constructor parameters only** — does not work as a property decorator.
103
- * For property injection with a token, use `@Autowired(token)` instead.
104
- */
105
99
  function Inject(token) {
106
100
  return (target, _propertyKey, parameterIndex) => {
107
101
  setInMetaRecord(METADATA.INJECT, target, parameterIndex, token);
@@ -130,6 +124,44 @@ function Value(envKey, defaultValue) {
130
124
  });
131
125
  };
132
126
  }
127
+ /**
128
+ * Inject the resolved file-system path for a typed asset. Mirrors
129
+ * `@Value`'s lazy-getter pattern — the asset is resolved on every
130
+ * property access, NOT at class instantiation, so:
131
+ *
132
+ * - Tests can swap fixtures + clear the cache without re-instantiating
133
+ * the consuming class.
134
+ * - The first access cost is paid once per process (the manifest cache
135
+ * in `core/assets.ts` makes subsequent calls cheap).
136
+ *
137
+ * Type-safety:
138
+ *
139
+ * - Without typegen, any string key is accepted (back-compat — same
140
+ * trick as `@Value`).
141
+ * - After typegen, `KickAssets` is populated and `AssetKey` is a
142
+ * union of every flattened `<namespace>/<key>` path. Unknown keys
143
+ * become a TS error.
144
+ *
145
+ * @example
146
+ * ```ts
147
+ * import { Service, Asset } from '@forinda/kickjs'
148
+ *
149
+ * `@Service()`
150
+ * class MailService {
151
+ * `@Asset('mails/welcome')`
152
+ * private welcomeTemplate!: string
153
+ *
154
+ * send(user: User) {
155
+ * return ejs.renderFile(this.welcomeTemplate, { user })
156
+ * }
157
+ * }
158
+ * ```
159
+ */
160
+ function Asset(assetKey) {
161
+ return (target, propertyKey) => {
162
+ setInMetaMap(METADATA.ASSET, target, propertyKey, { assetKey });
163
+ };
164
+ }
133
165
  function createRouteDecorator(method) {
134
166
  return (path, validation) => {
135
167
  return (target, propertyKey) => {
@@ -214,6 +246,6 @@ function Builder(target) {
214
246
  };
215
247
  }
216
248
  //#endregion
217
- export { ApiQueryParams, Autowired, Builder, Component, Controller, Delete, FileUpload, Get, Inject, Injectable, Middleware, Patch, Post, PostConstruct, Put, Repository, Service, Value, normalizeApiQueryParamsConfig };
249
+ export { ApiQueryParams, Asset, Autowired, Builder, Component, Controller, Delete, FileUpload, Get, Inject, Injectable, Middleware, Patch, Post, PostConstruct, Put, Repository, Service, Value, normalizeApiQueryParamsConfig };
218
250
 
219
251
  //# sourceMappingURL=decorators.mjs.map