@forinda/kickjs 1.7.1-alpha.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,644 +2,145 @@
2
2
 
3
3
  A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript.
4
4
 
5
- KickJS gives you the DX of NestJS — decorators, dependency injection, module system, code generators — without the weight. No RxJS, no class-transformer, no class-validator. Just TypeScript, Zod, and decorators.
5
+ NestJS ergonomics without the complexity — decorators, DI, module system, and code generators, powered by Zod and Vite.
6
6
 
7
- ## Highlights
8
-
9
- - **Custom DI container** — constructor and property injection, no external dependency
10
- - **Decorator-driven** — `@Controller`, `@Get`, `@Post`, `@Service`, `@Autowired`, `@Middleware`
11
- - **Zod-native validation** — schemas double as OpenAPI documentation
12
- - **Vite HMR** — zero-downtime hot reload in development, preserves DB/Redis/Socket connections
13
- - **DDD generators** — `kick g module users` scaffolds entity, repository, service, use-cases, DTOs, controller
14
- - **Auto OpenAPI** — Swagger UI and ReDoc generated from your decorators and Zod schemas
15
- - **Pluggable** — adapters for database, auth, cache, swagger; schema parsers for Zod/Yup/Joi; query builders for Drizzle/Prisma/Sequelize
16
- - **Extensible CLI** — register project-specific commands in `kick.config.ts`
17
- - **ESM + TypeScript strict** — modern stack, tree-shakeable packages
18
-
19
- ## Install the CLI
7
+ ## Install Manually
20
8
 
21
9
  ```bash
22
- # Global install (recommended)
23
- pnpm add -g @forinda/kickjs-cli
24
-
25
- # Or use npx without installing
26
- npx @forinda/kickjs-cli new my-api
10
+ pnpm init
11
+ pnpm add @forinda/kickjs express reflect-metadata zod
12
+ pnpm add -D @forinda/kickjs-cli
27
13
  ```
28
14
 
29
- ### For contributors (link local build)
15
+ ## Scaffold with CLI
30
16
 
31
17
  ```bash
32
- git clone https://github.com/forinda/kick-js.git
33
- cd kick-js
34
- pnpm install && pnpm build
35
- cd packages/cli && pnpm link --global
18
+ # Using npx
19
+ npx @forinda/kickjs-cli new my-api
20
+ # Using global install
21
+ pnpm add -g @forinda/kickjs-cli
22
+ kick new my-api
23
+ # pnpm
24
+ pnpm dlx @forinda/kickjs-cli new my-api
25
+ # yarn
26
+ yarn dlx @forinda/kickjs-cli new my-api
36
27
  ```
37
28
 
38
- Now `kick` uses your local build. After changes, just `pnpm build` — no re-link needed.
39
-
40
29
  ## Quick Start
41
30
 
42
31
  ```bash
43
- # Scaffold a new project (interactive prompts for PM, git, install)
44
- kick new my-api
45
-
46
- # Or scaffold in the current directory
47
- kick new .
48
-
49
- # Start development with HMR
50
- kick dev
51
-
52
- # Generate a DDD module
53
- kick g module users
32
+ kick new my-api && cd my-api && kick dev
54
33
  ```
55
34
 
56
- ## Minimal Example
35
+ ## Hello World
57
36
 
58
37
  ```typescript
59
- // src/index.ts
60
38
  import 'reflect-metadata'
61
- import { bootstrap } from '@forinda/kickjs-http'
62
- import { UserModule } from './modules/users'
63
-
64
- bootstrap({ modules: [UserModule] })
65
- ```
39
+ import { Controller, Get, Service, Autowired, bootstrap, RequestContext } from '@forinda/kickjs'
66
40
 
67
- ```typescript
68
- // src/modules/users/presentation/user.controller.ts
69
- import { Controller, Get, Post, Autowired } from '@forinda/kickjs-core'
70
- import { RequestContext } from '@forinda/kickjs-http'
71
- import { z } from 'zod'
72
-
73
- const createUserSchema = z.object({
74
- name: z.string().min(1),
75
- email: z.string().email(),
76
- })
41
+ @Service()
42
+ class GreetService {
43
+ greet(name: string) { return `Hello ${name}` }
44
+ }
77
45
 
78
46
  @Controller()
79
- export class UserController {
80
- @Autowired() private userService!: UserService
47
+ class HelloController {
48
+ @Autowired() private greet!: GreetService
81
49
 
82
50
  @Get('/')
83
- async list(ctx: RequestContext) {
84
- ctx.json(await this.userService.findAll())
85
- }
86
-
87
- @Post('/', { body: createUserSchema })
88
- async create(ctx: RequestContext) {
89
- const user = await this.userService.create(ctx.body)
90
- ctx.created(user)
51
+ handle(ctx: RequestContext) {
52
+ ctx.json({ message: this.greet.greet('KickJS') })
91
53
  }
92
54
  }
93
- ```
94
55
 
95
- ```typescript
96
- // src/modules/users/index.ts
97
- import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs-core'
98
- import { buildRoutes } from '@forinda/kickjs-http'
99
- import { UserController } from './presentation/user.controller'
100
- import './domain/services/user.service'
101
-
102
- export class UserModule implements AppModule {
103
- register(container: Container): void {
104
- // Bind interfaces to implementations
105
- }
106
-
107
- routes(): ModuleRoutes {
108
- return {
109
- path: '/users',
110
- router: buildRoutes(UserController),
111
- controller: UserController, // enables auto OpenAPI docs
112
- }
113
- }
114
- }
56
+ bootstrap({ modules: [/* your modules */] })
115
57
  ```
116
58
 
117
- ## Packages
118
-
119
- | Package | npm | Description |
120
- |---------|-----|-------------|
121
- | [`@forinda/kickjs-core`](packages/core/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-core)](https://www.npmjs.com/package/@forinda/kickjs-core) | DI container, 20+ decorators, module system, logger |
122
- | [`@forinda/kickjs-http`](packages/http/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-http)](https://www.npmjs.com/package/@forinda/kickjs-http) | Express 5 app, routing, middleware, query parsing |
123
- | [`@forinda/kickjs-config`](packages/config/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-config)](https://www.npmjs.com/package/@forinda/kickjs-config) | Zod-based env validation, ConfigService, `@Value` |
124
- | [`@forinda/kickjs-cli`](packages/cli/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-cli)](https://www.npmjs.com/package/@forinda/kickjs-cli) | Scaffolding, generators, `kick add`, `kick rm` |
125
- | [`@forinda/kickjs-swagger`](packages/swagger/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-swagger)](https://www.npmjs.com/package/@forinda/kickjs-swagger) | OpenAPI from decorators, Swagger UI, ReDoc |
126
- | [`@forinda/kickjs-testing`](packages/testing/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-testing)](https://www.npmjs.com/package/@forinda/kickjs-testing) | `createTestApp`, `createTestModule` helpers |
127
- | [`@forinda/kickjs-prisma`](packages/prisma/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-prisma)](https://www.npmjs.com/package/@forinda/kickjs-prisma) | Prisma adapter (v5/6/7), PrismaModelDelegate |
128
- | [`@forinda/kickjs-drizzle`](packages/drizzle/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-drizzle)](https://www.npmjs.com/package/@forinda/kickjs-drizzle) | Drizzle adapter, query builder |
129
- | [`@forinda/kickjs-auth`](packages/auth/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-auth)](https://www.npmjs.com/package/@forinda/kickjs-auth) | JWT, API key, OAuth, `@Public`, `@Roles` |
130
- | [`@forinda/kickjs-ws`](packages/ws/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-ws)](https://www.npmjs.com/package/@forinda/kickjs-ws) | WebSocket with `@WsController`, rooms |
131
- | [`@forinda/kickjs-queue`](packages/queue/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-queue)](https://www.npmjs.com/package/@forinda/kickjs-queue) | BullMQ, RabbitMQ, Kafka job processing |
132
- | [`@forinda/kickjs-cron`](packages/cron/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-cron)](https://www.npmjs.com/package/@forinda/kickjs-cron) | `@Cron` decorator, pluggable schedulers |
133
- | [`@forinda/kickjs-mailer`](packages/mailer/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-mailer)](https://www.npmjs.com/package/@forinda/kickjs-mailer) | SMTP, Resend, SES, ConsoleProvider |
134
- | [`@forinda/kickjs-graphql`](packages/graphql/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-graphql)](https://www.npmjs.com/package/@forinda/kickjs-graphql) | `@Resolver`, `@Query`, `@Mutation`, GraphiQL |
135
- | [`@forinda/kickjs-otel`](packages/otel/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-otel)](https://www.npmjs.com/package/@forinda/kickjs-otel) | OpenTelemetry tracing and metrics |
136
- | [`@forinda/kickjs-devtools`](packages/devtools/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-devtools)](https://www.npmjs.com/package/@forinda/kickjs-devtools) | Debug dashboard at `/_debug` |
137
- | [`@forinda/kickjs-notifications`](packages/notifications/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-notifications)](https://www.npmjs.com/package/@forinda/kickjs-notifications) | Email, Slack, Discord, webhook channels |
138
- | [`@forinda/kickjs-multi-tenant`](packages/multi-tenant/) | [![npm](https://img.shields.io/npm/v/@forinda/kickjs-multi-tenant)](https://www.npmjs.com/package/@forinda/kickjs-multi-tenant) | Tenant resolution middleware |
139
-
140
- ## Bundle Sizes
141
-
142
- All packages ship minified ESM with no sourcemaps. External dependencies (Express, Zod, Pino, etc.) are never bundled — only framework code is included.
143
-
144
- | Package | JS Bundle | Description |
145
- |---------|-----------|-------------|
146
- | `@forinda/kickjs-core` | **13.9 kB** | DI container, decorators, module system, logger |
147
- | `@forinda/kickjs-http` | **22.7 kB** | Express 5 app, routing, middleware, query parsing |
148
- | `@forinda/kickjs-config` | **2.6 kB** | Zod-based env validation, ConfigService |
149
- | `@forinda/kickjs-swagger` | **9.2 kB** | OpenAPI spec generation, Swagger UI, ReDoc |
150
- | `@forinda/kickjs-cli` | **221.6 kB** | Project scaffolding, DDD generators, CLAUDE.md/AGENTS.md generation |
151
- | `@forinda/kickjs-testing` | **0.7 kB** | `createTestApp`, `createTestModule` helpers |
152
- | `@forinda/kickjs-auth` | **8.0 kB** | JWT/API key strategies, auth guards |
153
- | `@forinda/kickjs-prisma` | **2.4 kB** | Prisma adapter, PrismaModelDelegate, query builder |
154
- | `@forinda/kickjs-drizzle` | **4.1 kB** | Drizzle adapter, query builder |
155
- | `@forinda/kickjs-ws` | **6.3 kB** | WebSocket adapter with decorators |
156
- | `@forinda/kickjs-queue` | **8.0 kB** | BullMQ/AMQP/Kafka job processing |
157
- | `@forinda/kickjs-graphql` | **4.4 kB** | GraphQL adapter |
158
- | `@forinda/kickjs-mailer` | **4.3 kB** | Pluggable email transports |
159
- | `@forinda/kickjs-cron` | **3.4 kB** | Scheduled task runner |
160
- | `@forinda/kickjs-otel` | **2.6 kB** | OpenTelemetry tracing/metrics |
161
- | `@forinda/kickjs-devtools` | **6.0 kB** | Dev dashboard adapter |
162
- | `@forinda/kickjs-notifications` | **2.9 kB** | Notification channels |
163
- | `@forinda/kickjs-multi-tenant` | **1.4 kB** | Multi-tenancy middleware |
164
-
165
- > **Total framework JS:** ~276 kB minified (core + http + config + swagger). A typical app using core, http, config, and swagger ships under 50 kB of framework code — the rest is your application logic.
166
-
167
- ## Full-Featured Bootstrap
168
-
169
- ```typescript
170
- import 'reflect-metadata'
171
- import express from 'express'
172
- import helmet from 'helmet'
173
- import cors from 'cors'
174
- import compression from 'compression'
175
- import { bootstrap, requestId } from '@forinda/kickjs-http'
176
- import { SwaggerAdapter } from '@forinda/kickjs-swagger'
177
- import { modules } from './modules'
178
-
179
- bootstrap({
180
- modules,
181
- apiPrefix: '/api',
182
- defaultVersion: 1,
183
- trustProxy: true,
184
-
185
- adapters: [
186
- new HealthAdapter(),
187
- new DatabaseAdapter({ url: process.env.DATABASE_URL }),
188
- new SwaggerAdapter({
189
- info: { title: 'My API', version: '1.0.0' },
190
- bearerAuth: true,
191
- }),
192
- ],
193
-
194
- middleware: [
195
- requestId(),
196
- helmet(),
197
- cors({ origin: process.env.CORS_ORIGIN }),
198
- compression(),
199
- express.json({ limit: '1mb' }),
200
- ],
201
- })
202
- ```
59
+ ## What's Included
203
60
 
204
- ## Decorators
205
-
206
- ### Class Decorators
207
-
208
- | Decorator | Purpose |
209
- |-----------|---------|
210
- | `@Injectable()` | Mark a class for DI registration |
211
- | `@Service()` | Semantic alias for business logic |
212
- | `@Repository()` | Semantic alias for data access |
213
- | `@Controller(path?)` | HTTP controller with optional route prefix |
214
- | `@Configuration()` | Factory class for `@Bean` methods |
215
- | `@Component()` | Generic managed component |
216
-
217
- ### Method Decorators
218
-
219
- | Decorator | Purpose |
220
- |-----------|---------|
221
- | `@Get(path?, validation?)` | HTTP GET route |
222
- | `@Post(path?, validation?)` | HTTP POST route with optional Zod body/query/params validation |
223
- | `@Put(path?, validation?)` | HTTP PUT route |
224
- | `@Delete(path?, validation?)` | HTTP DELETE route |
225
- | `@Patch(path?, validation?)` | HTTP PATCH route |
226
- | `@Bean(options?)` | Factory method inside `@Configuration` |
227
- | `@PostConstruct()` | Lifecycle hook called after instantiation |
228
- | `@Transactional()` | Wrap method in DB transaction (auto commit/rollback) |
229
- | `@Middleware(...handlers)` | Attach middleware to class or method |
230
- | `@FileUpload(config)` | Configure file upload handling |
231
-
232
- ### Property Decorators
233
-
234
- | Decorator | Purpose |
235
- |-----------|---------|
236
- | `@Autowired(token?)` | Lazy property injection from container |
237
- | `@Inject(token)` | Constructor parameter injection with explicit token |
238
- | `@Value(envKey, default?)` | Inject environment variable (throws if missing with no default) |
239
-
240
- ### Swagger Decorators
241
-
242
- | Decorator | Purpose |
243
- |-----------|---------|
244
- | `@ApiTags(...tags)` | Tag controller or method |
245
- | `@ApiOperation({ summary })` | Describe an endpoint |
246
- | `@ApiResponse({ status, description, schema? })` | Document response (stackable) |
247
- | `@ApiBearerAuth()` | Mark as requiring auth |
248
- | `@ApiExclude()` | Hide from OpenAPI spec |
249
-
250
- ## Query String Parsing
251
-
252
- Built-in ORM-agnostic query parser supporting filtering, sorting, pagination, and full-text search.
61
+ Everything you need for a production API — one import:
253
62
 
254
63
  ```typescript
255
- @Get('/')
256
- async list(ctx: RequestContext) {
257
- const parsed = ctx.qs({
258
- filterable: ['status', 'priority'],
259
- sortable: ['createdAt', 'title'],
260
- searchable: ['title', 'description'],
261
- })
262
-
263
- // Pass to your ORM query builder adapter
264
- const q = drizzleAdapter.build(parsed, { columns, searchColumns })
265
- const rows = await db.select().from(todos)
266
- .where(q.where).orderBy(...q.orderBy)
267
- .limit(q.limit).offset(q.offset)
268
-
269
- ctx.json(rows)
270
- }
271
- ```
272
-
273
- ### Query Format
274
-
275
- ```
276
- GET /api/v1/todos?page=2&limit=25&q=urgent&filter=status:eq:active&filter=priority:gte:3&sort=createdAt:desc
277
- ```
278
-
279
- | Parameter | Format | Example |
280
- |-----------|--------|---------|
281
- | `page` | Number (default: 1) | `?page=2` |
282
- | `limit` | Number (default: 20, max: 100) | `?limit=50` |
283
- | `q` | Search string | `?q=hello` |
284
- | `filter` | `field:operator:value` (repeatable) | `?filter=status:eq:active` |
285
- | `sort` | `field:asc\|desc` (repeatable) | `?sort=name:asc` |
286
-
287
- **Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `contains`, `starts`, `ends`
288
-
289
- ### Custom Query Builder Adapter
290
-
291
- Implement `QueryBuilderAdapter` to translate `ParsedQuery` into your ORM's query format:
292
-
293
- ```typescript
294
- import { type QueryBuilderAdapter, type ParsedQuery } from '@forinda/kickjs-http'
295
-
296
- // Prisma adapter
297
- class PrismaQueryAdapter implements QueryBuilderAdapter<PrismaQuery, PrismaConfig> {
298
- name = 'prisma'
299
- build(parsed: ParsedQuery, config: PrismaConfig): PrismaQuery {
300
- return {
301
- where: buildPrismaWhere(parsed.filters, config.fieldMap),
302
- orderBy: parsed.sort.map(s => ({ [s.field]: s.direction })),
303
- skip: parsed.pagination.offset,
304
- take: parsed.pagination.limit,
305
- }
306
- }
307
- }
308
-
309
- // Sequelize adapter
310
- class SequelizeQueryAdapter implements QueryBuilderAdapter<SequelizeQuery, SequelizeConfig> {
311
- name = 'sequelize'
312
- build(parsed: ParsedQuery, config: SequelizeConfig): SequelizeQuery {
313
- return {
314
- where: buildSequelizeWhere(parsed.filters, config.columns),
315
- order: parsed.sort.map(s => [s.field, s.direction.toUpperCase()]),
316
- offset: parsed.pagination.offset,
317
- limit: parsed.pagination.limit,
318
- }
319
- }
320
- }
321
-
322
- // Drizzle adapter
323
- class DrizzleQueryAdapter implements QueryBuilderAdapter<DrizzleQuery, DrizzleConfig> {
324
- name = 'drizzle'
325
- build(parsed: ParsedQuery, config: DrizzleConfig): DrizzleQuery {
326
- return {
327
- where: buildDrizzleWhere(parsed.filters, config.columns),
328
- orderBy: buildDrizzleSort(parsed.sort, config.columns),
329
- limit: parsed.pagination.limit,
330
- offset: parsed.pagination.offset,
331
- }
332
- }
333
- }
334
- ```
64
+ import {
65
+ // DI + Decorators
66
+ Controller, Get, Post, Put, Delete, Patch,
67
+ Service, Repository, Autowired, Inject, Value, Middleware,
335
68
 
336
- ## Pluggable Schema Parser (Swagger)
69
+ // Application
70
+ bootstrap, Application, RequestContext, buildRoutes,
337
71
 
338
- Swagger uses Zod by default to convert validation schemas into OpenAPI JSON Schema. Override for Yup, Joi, Valibot, ArkType, or any other validation library:
72
+ // Middleware
73
+ helmet, cors, csrf, rateLimit, requestId, requestLogger,
74
+ validate, upload, session,
339
75
 
340
- ```typescript
341
- import Joi from 'joi'
342
- import joiToJson from 'joi-to-json'
343
- import { type SchemaParser, SwaggerAdapter } from '@forinda/kickjs-swagger'
344
-
345
- const joiParser: SchemaParser = {
346
- name: 'joi',
347
- supports: (schema) => Joi.isSchema(schema),
348
- toJsonSchema: (schema) => joiToJson(schema),
349
- }
76
+ // Utilities
77
+ Container, HttpException, createLogger,
78
+ ref, computed, watch,
79
+ parseQuery, normalizePath,
350
80
 
351
- new SwaggerAdapter({
352
- info: { title: 'My API', version: '1.0.0' },
353
- schemaParser: joiParser,
354
- })
81
+ // Types
82
+ type AppAdapter, type AdapterContext, type AppModule,
83
+ type MiddlewareHandler, type ModuleRoutes,
84
+ } from '@forinda/kickjs'
355
85
  ```
356
86
 
357
- ## Adapter Pattern
358
-
359
- Adapters hook into the application lifecycle to add functionality like database connections, auth, caching, or documentation.
87
+ ## Typed Adapter Hooks
360
88
 
361
89
  ```typescript
362
- import { type AppAdapter, type Container } from '@forinda/kickjs-core'
363
- import type { Express } from 'express'
90
+ import type { AppAdapter, AdapterContext } from '@forinda/kickjs'
364
91
 
365
- export class RedisAdapter implements AppAdapter {
366
- name = 'RedisAdapter'
92
+ class MyAdapter implements AppAdapter {
93
+ name = 'MyAdapter'
367
94
 
368
- beforeMount(app: Express, container: Container) {
369
- container.registerInstance(REDIS, redisClient)
95
+ beforeMount({ app, container, isProduction }: AdapterContext) {
96
+ // app: Express, container: Container, isProduction: boolean
97
+ app.use(myMiddleware())
370
98
  }
371
99
 
372
- middleware() {
373
- return [{ handler: rateLimiter(), phase: 'afterGlobal' as const }]
100
+ afterStart({ server }: AdapterContext) {
101
+ // server: http.Server — attach WebSocket, etc.
374
102
  }
375
103
 
376
104
  async shutdown() {
377
- await redisClient.quit()
378
- }
379
- }
380
- ```
381
-
382
- **Lifecycle hooks:** `beforeMount` > `middleware` (4 phases) > `beforeStart` > `afterStart` > `shutdown`
383
-
384
- **Middleware phases:** `beforeGlobal` > user middleware > `afterGlobal` > module registration > `beforeRoutes` > routes > `afterRoutes`
385
-
386
- ## Module System
387
-
388
- Modules encapsulate a feature domain. Each module registers its dependencies and declares its routes.
389
-
390
- ```typescript
391
- export class OrderModule implements AppModule {
392
- register(container: Container): void {
393
- container.registerFactory(ORDER_REPOSITORY, () =>
394
- container.resolve(DrizzleOrderRepository),
395
- )
396
- }
397
-
398
- routes(): ModuleRoutes {
399
- return {
400
- path: '/orders',
401
- version: 2, // mounts at /api/v2/orders
402
- router: buildRoutes(OrderController),
403
- controller: OrderController,
404
- }
105
+ await cleanup()
405
106
  }
406
107
  }
407
108
  ```
408
109
 
409
- ## DDD Module Structure
410
-
411
- Generated by `kick g module <name>`:
412
-
413
- ```
414
- src/modules/<name>/
415
- presentation/
416
- <name>.controller.ts
417
- domain/
418
- entities/<name>.entity.ts
419
- value-objects/<name>-id.vo.ts
420
- repositories/<name>.repository.ts # interface + DI token
421
- services/<name>-domain.service.ts
422
- application/
423
- use-cases/
424
- create-<name>.use-case.ts
425
- list-<names>.use-case.ts
426
- get-<name>.use-case.ts
427
- update-<name>.use-case.ts
428
- delete-<name>.use-case.ts
429
- dtos/
430
- create-<name>.dto.ts
431
- update-<name>.dto.ts
432
- infrastructure/
433
- repositories/
434
- in-memory-<name>.repository.ts
435
- index.ts # module definition
436
- ```
437
-
438
- ## CLI Commands
110
+ ## Ecosystem
111
+
112
+ | Package | Description |
113
+ |---------|-------------|
114
+ | `@forinda/kickjs` | Core framework (DI, decorators, Express 5, middleware) |
115
+ | `@forinda/kickjs-config` | Zod-based env validation, ConfigService, `@Value` |
116
+ | `@forinda/kickjs-swagger` | Auto OpenAPI from decorators + Zod schemas |
117
+ | `@forinda/kickjs-cli` | Scaffolding, DDD generators, custom commands |
118
+ | `@forinda/kickjs-testing` | `createTestApp`, `createTestModule` |
119
+ | `@forinda/kickjs-prisma` | Prisma adapter (v5/6/7) |
120
+ | `@forinda/kickjs-drizzle` | Drizzle adapter, query builder |
121
+ | `@forinda/kickjs-auth` | JWT, API key, OAuth strategies |
122
+ | `@forinda/kickjs-ws` | WebSocket with `@WsController` |
123
+ | `@forinda/kickjs-queue` | BullMQ, RabbitMQ, Kafka |
124
+ | `@forinda/kickjs-cron` | `@Cron` decorator scheduling |
125
+ | `@forinda/kickjs-mailer` | SMTP, Resend, SES |
126
+ | `@forinda/kickjs-graphql` | `@Resolver`, `@Query`, `@Mutation` |
127
+ | `@forinda/kickjs-otel` | OpenTelemetry tracing + metrics |
128
+ | `@forinda/kickjs-devtools` | Debug dashboard at `/_debug` |
129
+
130
+ ## CLI
439
131
 
440
132
  ```bash
441
- # Project lifecycle
442
- kick new <project-name> # Scaffold new project
443
- kick dev # Dev server with Vite HMR
444
- kick build # Production build via Vite
445
- kick start # Run production build
446
- kick info # Print versions and environment
447
-
448
- # Code generation
449
- kick g module <name> # Full DDD module scaffold
450
- kick g controller <name> # Single controller
451
- kick g service <name> # Service class
452
- kick g middleware <name> # Middleware handler
453
- kick g guard <name> # Auth guard
454
- kick g adapter <name> # Lifecycle adapter
455
- kick g dto <name> # DTO with Zod schema
456
- ```
457
-
458
- ### Generator Flags
459
-
460
- ```bash
461
- kick g module users --no-entity # Skip entity/value objects
462
- kick g module users --no-tests # Skip test files
463
- kick g module users --minimal # Only index.ts + controller
464
- kick g module users --dry-run # Preview without writing
465
- kick g module users --repo prisma # Prisma repository (working code)
466
- kick g module users --repo drizzle # Drizzle repository (working code)
467
- kick g module users --no-pluralize # Singular: src/modules/user/
468
- ```
469
-
470
- ### Configuration
471
-
472
- Configure module generation, custom commands, and more in `kick.config.ts`:
473
-
474
- ```typescript
475
- import { defineConfig } from '@forinda/kickjs-cli'
476
-
477
- export default defineConfig({
478
- pattern: 'ddd',
479
-
480
- // Module generation settings
481
- modules: {
482
- dir: 'src/modules',
483
- repo: 'prisma', // 'drizzle' | 'inmemory' | 'prisma' | { name: 'custom' }
484
- pluralize: true, // false → singular folder/route names
485
- schemaDir: 'prisma/',
486
- },
487
-
488
- // Custom CLI commands — the whole team uses kick db:migrate etc.
489
- commands: [
490
- {
491
- name: 'db:migrate',
492
- description: 'Run database migrations',
493
- steps: 'npx prisma migrate dev',
494
- },
495
- {
496
- name: 'db:seed',
497
- description: 'Seed the database',
498
- steps: 'npx prisma db seed',
499
- },
500
- ],
501
- })
133
+ kick new my-api # Scaffold project
134
+ kick dev # Vite HMR dev server
135
+ kick build # Production build
136
+ kick g module users # Generate full DDD module (18 files)
137
+ kick g module users --repo prisma # With Prisma repository
502
138
  ```
503
139
 
504
- ## Environment Configuration
140
+ ## Documentation
505
141
 
506
- ```typescript
507
- import { defineEnv, loadEnv } from '@forinda/kickjs-config'
508
- import { z } from 'zod'
509
-
510
- const envSchema = defineEnv((base) =>
511
- base.extend({
512
- DATABASE_URL: z.string().url(),
513
- JWT_SECRET: z.string().min(32),
514
- REDIS_URL: z.string().url().optional(),
515
- }),
516
- )
517
-
518
- // Validates on first call — throws with clear errors on misconfiguration
519
- const env = loadEnv(envSchema)
520
- ```
521
-
522
- ## Testing
523
-
524
- ```typescript
525
- import { createTestApp, createTestModule } from '@forinda/kickjs-testing'
526
- import { describe, it, expect } from 'vitest'
527
- import supertest from 'supertest'
528
-
529
- describe('TodoController', () => {
530
- it('creates a todo', async () => {
531
- const { expressApp } = createTestApp({
532
- modules: [TodoModule],
533
- overrides: {
534
- [TODO_REPOSITORY]: new InMemoryTodoRepository(),
535
- },
536
- })
537
-
538
- const res = await supertest(expressApp)
539
- .post('/api/v1/todos')
540
- .send({ title: 'Write tests' })
541
-
542
- expect(res.status).toBe(201)
543
- expect(res.body.title).toBe('Write tests')
544
- })
545
- })
546
- ```
547
-
548
- ## HMR Architecture
549
-
550
- `kick dev` uses `vite-node --watch` for true hot module replacement:
551
-
552
- ```
553
- File change detected
554
- |
555
- import.meta.hot.accept()
556
- |
557
- main() re-executes
558
- |
559
- g.__app exists? --- YES -> app.rebuild()
560
- \-- NO -> app.start()
561
- |
562
- rebuild():
563
- 1. Reset DI container (fresh singletons)
564
- 2. Create new Express app
565
- 3. Re-run setup (middleware + routes)
566
- 4. Swap handler on existing http.Server
567
- |
568
- Preserved: HTTP server, DB pool, Redis, Socket.IO, port binding
569
- ```
570
-
571
- ## Repository Structure
572
-
573
- ```
574
- kick-js/
575
- packages/
576
- core/ @forinda/kickjs-core
577
- http/ @forinda/kickjs-http
578
- config/ @forinda/kickjs-config
579
- swagger/ @forinda/kickjs-swagger
580
- cli/ @forinda/kickjs-cli
581
- testing/ @forinda/kickjs-testing
582
- examples/
583
- jira-drizzle-api/ Full Jira clone (PostgreSQL + Drizzle)
584
- jira-mongoose-api/ Full Jira clone (MongoDB + Mongoose)
585
- minimal-api/ Simplest possible app
586
- joi-api/ Joi schema parser for Swagger
587
- graphql-api/ GraphQL with resolvers
588
- devtools-api/ DevTools + reactive state
589
- microservice-api/ Microservice template
590
- otel-api/ OpenTelemetry tracing
591
- turbo.json
592
- pnpm-workspace.yaml
593
- tsconfig.base.json
594
- ```
595
-
596
- ## Dependency Graph
597
-
598
- ```
599
- @forinda/kickjs-testing --> @forinda/kickjs-http --> @forinda/kickjs-core
600
- ^
601
- @forinda/kickjs-config --------------------------+
602
- @forinda/kickjs-swagger --> @forinda/kickjs-core
603
-
604
- @forinda/kickjs-cli (standalone -- generates code, no runtime dependency)
605
- ```
606
-
607
- ## Technical Decisions
608
-
609
- | Area | Choice | Why |
610
- |------|--------|-----|
611
- | DI | Custom container | Lightweight, no external dep, full control |
612
- | Module system | ESM only | Tree-shaking, native Node.js support |
613
- | Runtime | Node.js 20+ | LTS with native ESM |
614
- | HTTP | Express 5 | Mature, async middleware, wide ecosystem |
615
- | Validation | Zod | Runtime + static types, doubles as OpenAPI schema |
616
- | Build | Vite 8 | Unified toolchain — library builds, HMR, SSR |
617
- | Test | Vitest | ESM-native, fast, Vite-compatible |
618
- | Logging | Pino | Fastest Node.js logger, structured JSON in prod |
619
- | Monorepo | pnpm + Turborepo | Efficient deps, build caching |
620
-
621
- ## Roadmap
622
-
623
- Key upcoming packages:
624
-
625
- - **`@forinda/kickjs-database`** -- Drizzle adapter, transaction propagation, query builder adapter
626
- - **`@forinda/kickjs-auth`** -- JWT/API key strategies, `@Authenticated`, `@Roles` guards
627
- - **`@forinda/kickjs-cache`** -- `@Cacheable`/`@CacheEvict` with Redis or in-memory stores
628
- - **`@forinda/kickjs-websocket`** -- Socket.IO with `@Gateway`/`@OnEvent` decorators
629
- - **`@forinda/kickjs-queue`** -- BullMQ job processing with `@Worker` decorator
630
- - **`@forinda/kickjs-mail`** -- Pluggable transports (Resend, SMTP), EJS templates
631
- - **Plugin system** -- Third-party packages extend framework with adapters, CLI generators, Vite plugins
632
-
633
- ## Contributing
634
-
635
- ```bash
636
- git clone https://github.com/forinda/kick-js.git
637
- cd kick-js
638
- pnpm install
639
- pnpm build
640
- pnpm test
641
- ```
142
+ [forinda.github.io/kick-js](https://forinda.github.io/kick-js/)
642
143
 
643
144
  ## License
644
145
 
645
- MIT License - see [LICENSE](LICENSE) for details.
146
+ MIT
@@ -103,18 +103,19 @@ export declare function normalizeApiQueryParamsConfig(config: ApiQueryParamsConf
103
103
  */
104
104
  export declare function ApiQueryParams(config: ApiQueryParamsConfig | ColumnApiQueryParamsConfig): MethodDecorator;
105
105
  /**
106
- * Middleware handler function with typed RequestContext.
106
+ * Middleware handler function.
107
+ * Pass `RequestContext` as the generic for full type safety:
107
108
  *
108
109
  * ```ts
109
- * import type { MiddlewareHandler } from '@forinda/kickjs'
110
+ * import type { MiddlewareHandler, RequestContext } from '@forinda/kickjs'
110
111
  *
111
- * const auth: MiddlewareHandler = (ctx, next) => {
112
- * ctx.body // fully typed — no generic needed
112
+ * const auth: MiddlewareHandler<RequestContext> = (ctx, next) => {
113
+ * ctx.body // fully typed
113
114
  * next()
114
115
  * }
115
116
  * ```
116
117
  */
117
- export type MiddlewareHandler = (ctx: import('../http/context').RequestContext, next: () => void) => void | Promise<void>;
118
+ export type MiddlewareHandler<TCtx = any> = (ctx: TCtx, next: () => void) => void | Promise<void>;
118
119
  /** Attach middleware handlers to a class or method */
119
120
  export declare function Middleware(...handlers: MiddlewareHandler[]): ClassDecorator & MethodDecorator;
120
121
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/core/decorators.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/core/decorators.ts"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -20,4 +20,6 @@ export { rateLimit, type RateLimitOptions, type RateLimitStore } from './http/mi
20
20
  export { session, type SessionOptions, type SessionStore, type SessionData, type Session, } from './http/middleware/session';
21
21
  export { upload, cleanupFiles, resolveMimeTypes, buildUploadMiddleware, type UploadOptions, } from './http/middleware/upload';
22
22
  export { parseQuery, parseFilters, parseSort, parsePagination, parseSearchQuery, buildQueryParams, FILTER_OPERATORS, type FilterOperator, type FilterItem, type SortItem, type PaginationParams, type ParsedQuery, type QueryFieldConfig, type QueryBuilderAdapter, type PaginatedResponse, } from './http/query';
23
+ export { ViewAdapter, type ViewAdapterOptions } from './http/middleware/views';
24
+ export { SpaAdapter, type SpaAdapterOptions } from './http/middleware/spa';
23
25
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,QAAQ,CAAA;AAGtB,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAE/F,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAGtE,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAC3E,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AAC/E,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAC3F,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACrE,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAA;AACpG,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,OAAO,GACb,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EACL,UAAU,EACV,YAAY,EACZ,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,QAAQ,CAAA;AAGtB,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAE/F,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAGtE,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAC3E,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AAC/E,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAC3F,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACrE,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAA;AACpG,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,OAAO,GACb,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EACL,UAAU,EACV,YAAY,EACZ,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC9E,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}
package/dist/index.js CHANGED
@@ -1,86 +1,90 @@
1
1
  import { METADATA as o, Scope as e } from "./core/interfaces.js";
2
2
  import { Container as i } from "./core/container.js";
3
- import { ApiQueryParams as a, Autowired as p, Builder as s, Component as f, Controller as l, Delete as n, FileUpload as u, Get as c, Inject as d, Injectable as g, Middleware as C, Patch as P, Post as h, PostConstruct as R, Put as A, Repository as E, Service as v, Value as y, normalizeApiQueryParamsConfig as b } from "./core/decorators.js";
3
+ import { ApiQueryParams as a, Autowired as p, Builder as s, Component as f, Controller as l, Delete as n, FileUpload as d, Get as u, Inject as c, Injectable as g, Middleware as C, Patch as P, Post as h, PostConstruct as A, Put as R, Repository as E, Service as v, Value as y, normalizeApiQueryParamsConfig as S } from "./core/decorators.js";
4
4
  import { CRON_META as T, Cron as L, getCronJobs as M } from "./core/cron.js";
5
- import { CacheEvict as F, Cacheable as H, MemoryCacheProvider as I, getCacheProvider as w, setCacheProvider as D } from "./core/cache.js";
5
+ import { CacheEvict as w, Cacheable as F, MemoryCacheProvider as H, getCacheProvider as I, setCacheProvider as D } from "./core/cache.js";
6
6
  import { Logger as j, createLogger as q, logger as x, rootLogger as O } from "./core/logger.js";
7
- import { HttpException as z, HttpStatus as B } from "./core/errors.js";
8
- import { joinPaths as J, normalizePath as N } from "./core/path.js";
7
+ import { HttpException as z, HttpStatus as V } from "./core/errors.js";
8
+ import { joinPaths as G, normalizePath as J } from "./core/path.js";
9
9
  import { computed as k, isRef as K, reactive as W, ref as X, toRefs as Y, unref as Z, watch as $ } from "./core/reactivity.js";
10
10
  import "./core-B6Okew3W.js";
11
11
  import { REQUEST_ID_HEADER as er, requestId as tr } from "./http/middleware/request-id.js";
12
12
  import { errorHandler as mr, notFoundHandler as ar } from "./http/middleware/error-handler.js";
13
13
  import { Application as sr } from "./http/application.js";
14
14
  import { bootstrap as lr } from "./http/bootstrap.js";
15
- import { a as ur, i as cr, n as dr, o as gr, r as Cr, s as Pr, t as hr } from "./query-Bym31XRp.js";
16
- import { RequestContext as Ar } from "./http/context.js";
15
+ import { a as dr, i as ur, n as cr, o as gr, r as Cr, s as Pr, t as hr } from "./query-Bym31XRp.js";
16
+ import { RequestContext as Rr } from "./http/context.js";
17
17
  import { validate as vr } from "./http/middleware/validate.js";
18
- import { buildUploadMiddleware as br, cleanupFiles as Sr, resolveMimeTypes as Tr, upload as Lr } from "./http/middleware/upload.js";
19
- import { buildRoutes as Qr, getControllerPath as Fr } from "./http/router-builder.js";
20
- import { csrf as Ir } from "./http/middleware/csrf.js";
18
+ import { buildUploadMiddleware as Sr, cleanupFiles as br, resolveMimeTypes as Tr, upload as Lr } from "./http/middleware/upload.js";
19
+ import { buildRoutes as Qr, getControllerPath as wr } from "./http/router-builder.js";
20
+ import { csrf as Hr } from "./http/middleware/csrf.js";
21
21
  import { requestLogger as Dr } from "./http/middleware/request-logger.js";
22
22
  import { helmet as jr } from "./http/middleware/helmet.js";
23
23
  import { cors as xr } from "./http/middleware/cors.js";
24
24
  import { rateLimit as Ur } from "./http/middleware/rate-limit.js";
25
- import { session as Br } from "./http/middleware/session.js";
25
+ import { session as Vr } from "./http/middleware/session.js";
26
+ import { ViewAdapter as Gr } from "./http/middleware/views.js";
27
+ import { SpaAdapter as Nr } from "./http/middleware/spa.js";
26
28
  export {
27
29
  a as ApiQueryParams,
28
30
  sr as Application,
29
31
  p as Autowired,
30
32
  s as Builder,
31
33
  T as CRON_META,
32
- F as CacheEvict,
33
- H as Cacheable,
34
+ w as CacheEvict,
35
+ F as Cacheable,
34
36
  f as Component,
35
37
  i as Container,
36
38
  l as Controller,
37
39
  L as Cron,
38
40
  n as Delete,
39
41
  Pr as FILTER_OPERATORS,
40
- u as FileUpload,
41
- c as Get,
42
+ d as FileUpload,
43
+ u as Get,
42
44
  z as HttpException,
43
- B as HttpStatus,
44
- d as Inject,
45
+ V as HttpStatus,
46
+ c as Inject,
45
47
  g as Injectable,
46
48
  j as Logger,
47
49
  o as METADATA,
48
- I as MemoryCacheProvider,
50
+ H as MemoryCacheProvider,
49
51
  C as Middleware,
50
52
  P as Patch,
51
53
  h as Post,
52
- R as PostConstruct,
53
- A as Put,
54
+ A as PostConstruct,
55
+ R as Put,
54
56
  er as REQUEST_ID_HEADER,
55
57
  E as Repository,
56
- Ar as RequestContext,
58
+ Rr as RequestContext,
57
59
  e as Scope,
58
60
  v as Service,
61
+ Nr as SpaAdapter,
59
62
  y as Value,
63
+ Gr as ViewAdapter,
60
64
  lr as bootstrap,
61
65
  hr as buildQueryParams,
62
66
  Qr as buildRoutes,
63
- br as buildUploadMiddleware,
64
- Sr as cleanupFiles,
67
+ Sr as buildUploadMiddleware,
68
+ br as cleanupFiles,
65
69
  k as computed,
66
70
  xr as cors,
67
71
  q as createLogger,
68
- Ir as csrf,
72
+ Hr as csrf,
69
73
  mr as errorHandler,
70
- w as getCacheProvider,
71
- Fr as getControllerPath,
74
+ I as getCacheProvider,
75
+ wr as getControllerPath,
72
76
  M as getCronJobs,
73
77
  jr as helmet,
74
78
  K as isRef,
75
- J as joinPaths,
79
+ G as joinPaths,
76
80
  x as logger,
77
- b as normalizeApiQueryParamsConfig,
78
- N as normalizePath,
81
+ S as normalizeApiQueryParamsConfig,
82
+ J as normalizePath,
79
83
  ar as notFoundHandler,
80
- dr as parseFilters,
84
+ cr as parseFilters,
81
85
  Cr as parsePagination,
82
- cr as parseQuery,
83
- ur as parseSearchQuery,
86
+ ur as parseQuery,
87
+ dr as parseSearchQuery,
84
88
  gr as parseSort,
85
89
  Ur as rateLimit,
86
90
  W as reactive,
@@ -89,7 +93,7 @@ export {
89
93
  Dr as requestLogger,
90
94
  Tr as resolveMimeTypes,
91
95
  O as rootLogger,
92
- Br as session,
96
+ Vr as session,
93
97
  D as setCacheProvider,
94
98
  Y as toRefs,
95
99
  Z as unref,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@forinda/kickjs",
3
- "version": "1.7.1-alpha.0",
3
+ "version": "2.0.1",
4
4
  "description": "A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript.",
5
5
  "keywords": [
6
6
  "kickjs",
@@ -79,6 +79,14 @@
79
79
  "./query": {
80
80
  "import": "./dist/http/query/index.js",
81
81
  "types": "./dist/http/query/index.d.ts"
82
+ },
83
+ "./views": {
84
+ "import": "./dist/http/middleware/views.js",
85
+ "types": "./dist/http/middleware/views.d.ts"
86
+ },
87
+ "./spa": {
88
+ "import": "./dist/http/middleware/spa.js",
89
+ "types": "./dist/http/middleware/spa.d.ts"
82
90
  }
83
91
  },
84
92
  "files": [