@forinda/kickjs 0.1.0 → 0.1.3

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
@@ -5,6 +5,9 @@ Opinionated Express + TypeScript framework starter that feels like Spring Boot:
5
5
  ## Highlights
6
6
 
7
7
  - Spring Boot-style controllers via `@Controller`, `@Get`, etc., auto-registered at decoration time
8
+ - Nuxt-style, file-system driven controller discovery powered by verb-specific base controllers (`src/domains/app/controllers/users.get.controller.ts` ➜ `GET /users`)
9
+ - Batteries-included `kick` CLI for bootstrapping projects, generating controllers, and wiring custom commands
10
+ - Domain-first scaffolding with configurable folder layout for controllers, services, and domain logic
8
11
  - Schema-aware route decorators (Zod/Joi) with duplicate-route protection hashed at bootstrap
9
12
  - Built-in `BaseController` helper with structured responses, request logging, and `fail()` AppError helpers
10
13
  - `configureApp` and per-call `config` options for prefixes, health endpoints, logging levels, and telemetry limits
@@ -23,46 +26,47 @@ npm install @forinda/kickjs
23
26
 
24
27
  ```ts
25
28
  // app.ts
26
- import 'reflect-metadata';
27
- import type { Request, Response } from 'express';
28
- import { z } from 'zod';
29
+ import "reflect-metadata";
30
+ import type { Request, Response } from "express";
29
31
  import {
30
32
  BaseController,
31
33
  Controller,
32
34
  Get,
33
- Inject,
34
- RequestTracker,
35
- TYPES,
36
35
  bootstrap,
37
- configureApp
38
- } from '@forinda/kickjs';
36
+ configureApp,
37
+ } from "@forinda/kickjs";
39
38
 
40
- configureApp({ prefix: '/api' });
39
+ configureApp({ prefix: "/api/v1" });
41
40
 
42
- @Controller('/hello')
41
+ @Controller("/hello")
43
42
  class HelloController extends BaseController {
44
- constructor(@Inject(TYPES.RequestTracker) tracker: RequestTracker) {
45
- super(tracker);
46
- }
47
-
48
43
  protected controllerId(): string {
49
- return 'HelloController';
44
+ return "HelloController";
50
45
  }
51
46
 
52
47
  @Get({
53
- path: '/',
54
- validate: {
55
- query: z.object({ name: z.string().optional() })
56
- }
48
+ path: "/",
49
+ middlewares: [],
50
+ validate: {},
57
51
  })
58
52
  handle(req: Request, res: Response) {
59
- const name = typeof req.query.name === 'string' ? req.query.name : 'World';
53
+ const name = typeof req.query.name === "string" ? req.query.name : "World";
60
54
  this.mergeRequestMetadata(res, { greeted: name });
61
55
  return this.ok(res, { message: `Hello ${name}` });
62
56
  }
63
57
  }
64
58
 
65
- bootstrap();
59
+ async function main() {
60
+ const port = Number(process.env.PORT ?? 3000);
61
+ await bootstrap({ port });
62
+ console.log(`Server started on http://localhost:${port}`);
63
+ }
64
+
65
+ main().catch((error) => {
66
+ console.error("Failed to bootstrap application", error);
67
+ process.exitCode = 1;
68
+ });
69
+
66
70
  ```
67
71
 
68
72
  `bootstrap` wires Express, the Inversify container, and the request tracker. Controllers extending `BaseController` get ergonomic helpers for responses, structured logging, request metadata annotations, and a `fail()` helper for consistent error payloads. Route decorators accept Zod/Joi schemas for request validation without additional middleware.
@@ -77,6 +81,12 @@ import {
77
81
  Put,
78
82
  Patch,
79
83
  Delete,
84
+ HttpVerbController,
85
+ GetController,
86
+ PostController,
87
+ PutController,
88
+ PatchController,
89
+ DeleteController,
80
90
  Inject,
81
91
  Injectable,
82
92
  Optional,
@@ -85,6 +95,7 @@ import {
85
95
  Tagged,
86
96
  Unmanaged,
87
97
  BaseController,
98
+ discoverControllersFromFilesystem,
88
99
  RequestTracker,
89
100
  AppDiagnostics,
90
101
  TYPES,
@@ -101,15 +112,178 @@ import {
101
112
 
102
113
  - `Controller`, `Get`, `Post`, `Put`, `Patch`, `Delete`: decorators for routing with built-in schema validation and duplicate-route protection
103
114
  - `Inject`, `Injectable`, `Optional`, `MultiInject`, `Named`, `Tagged`, `Unmanaged`: DI helpers wrapping Inversify without exposing its API surface
104
- - `BaseController`: abstract class with response + logging helpers
115
+ - `HttpVerbController` & the verb-specific subclasses (`GetController`, `PostController`, …): enforce single-verb controllers with shared response/logging helpers and Nuxt-style route derivation
116
+ - `BaseController`: abstract class with response + logging helpers for traditional decorator-driven controllers. The request tracker is injected automatically, so subclasses never pass it through `super()`.
105
117
  - `configureApp(config)`: set global prefix, logging level, telemetry limits, and health endpoint before bootstrapping
106
- - `createApp(options)`: create an Express application with auto-registered controllers (optionally override config per call)
118
+ - `createApp(options)`: create an Express application with auto-registered controllers (optionally override config per call) and get back a `discovery.controllers` list for diagnostics
107
119
  - `bootstrap(options)`: create & start the HTTP server (accepts `port`, config overrides, extra middleware)
108
120
  - `RequestTracker`: injectable request context tracker used internally by `BaseController`
109
121
  - `AppDiagnostics`: inspect application/request telemetry without touching internal reactive state
110
122
  - `createError` / `AppError` / `isAppError`: structured error helpers for consistent codes and statuses
123
+ - `discoverControllersFromFilesystem(config)`: manually trigger file-system discovery when building custom tooling or CLIs
111
124
  - `TYPES`: symbol map to wire container bindings
112
125
  - `resetControllerRegistry()` / `resetAppConfig()`: utilities for clearing global state in integration tests
126
+ - `createKickConfig(options)`: compose environment-aware app configuration objects that can be passed to `configureApp` or `createApp`
127
+
128
+ ## File-based controllers
129
+
130
+ Kick bootstraps controllers automatically by scanning `src/http` (configurable) for files that follow Nuxt-style naming. Each file becomes a single-verb controller by extending the appropriate base class:
131
+
132
+ ```
133
+ src/http/
134
+ └─ users.get.controller.ts ➜ GET /users
135
+ └─ users.post.controller.ts ➜ POST /users
136
+ └─ admin/reports.[id].get.controller.ts ➜ GET /admin/reports/:id
137
+ ```
138
+
139
+ ```ts
140
+ // src/http/users.get.controller.ts
141
+ import type { Request, Response } from 'express';
142
+ import { GetController } from '@forinda/kickjs';
143
+
144
+ export default class UsersGetController extends GetController {
145
+ handle(_req: Request, res: Response) {
146
+ return this.ok(res, { users: ['Ada', 'Linus'] });
147
+ }
148
+ }
149
+ ```
150
+
151
+ Naming rules:
152
+
153
+ - `<segments>.<verb>.controller.(ts|js)` – the last token before `.controller` defines the HTTP method
154
+ - Directory names and file segments turn into URL fragments (`[id]` → `:id`, `[...slug]` → `:slug*`, `index` is omitted)
155
+ - Set `static route = '/custom/path'` on the class to override the derived path, and `static tags = ['admin']` to enrich diagnostics metadata
156
+
157
+ Discovery can be customised through `configureApp({ api: { discovery: { ... } } })`:
158
+
159
+ ```ts
160
+ configureApp({
161
+ prefix: '/api',
162
+ api: {
163
+ discovery: {
164
+ roots: ['apps/api/http'],
165
+ baseRoute: '/',
166
+ ignore: ['__mocks__']
167
+ }
168
+ }
169
+ });
170
+ ```
171
+
172
+ Disable discovery (e.g. for legacy decorator-driven projects) with `configureApp({ api: { discovery: { enabled: false } } })` and pass controllers explicitly to `createApp({ controllers: [...] })`.
173
+
174
+ ## CLI
175
+
176
+ Kick ships with a `kick` executable once the package is installed locally (`npx kick --help`).
177
+
178
+ ### Bootstrapping a project
179
+
180
+ ```bash
181
+ npm create kick@latest my-app
182
+ cd my-app
183
+ npm install
184
+ npm run dev
185
+ ```
186
+
187
+ The initializer mirrors running `kick init my-app` inside an empty directory: it scaffolds a domain-first folder layout, creates `kick.config.ts` at the repo root for CLI defaults, and generates `src/config/kick.config.ts` for runtime configuration. Both files are plain TypeScript modules you can edit.
188
+
189
+ During `bootstrap`, load the runtime config and pass it to `configureApp` once before invoking `createApp`/`bootstrap`:
190
+
191
+ ```ts
192
+ // src/main.ts
193
+ import 'reflect-metadata';
194
+ import { bootstrap, configureApp } from '@forinda/kickjs';
195
+ import appConfig from './config/kick.config';
196
+
197
+ configureApp(appConfig);
198
+
199
+ async function main() {
200
+ const { shutdown } = await bootstrap({ port: process.env.PORT ?? 3000 });
201
+ process.once('SIGINT', shutdown);
202
+ process.once('SIGTERM', shutdown);
203
+ }
204
+
205
+ main().catch((error) => {
206
+ console.error('Failed to bootstrap Kick app', error);
207
+ process.exitCode = 1;
208
+ });
209
+ ```
210
+
211
+ `createKickConfig` handles `.env`, `.env.<NODE_ENV>`, and `.env.local` files automatically, so populating `src/config/kick.config.ts` with env bindings ensures local and production deployments share a single source of truth.
212
+
213
+ ### `kick init [directory]`
214
+
215
+ Scaffold a fresh project with a minimal `package.json`, `tsconfig.json`, `kick.config.ts`, `src/main.ts`, and a sample domain under `src/domains/app`. Use `--force` to overwrite existing files and `--name` to control the package name.
216
+
217
+ ### `kick generate controller <name>`
218
+
219
+ Generate a convention-based controller file. The command derives the proper filename and class name, so:
220
+
221
+ ```bash
222
+ kick generate controller admin/reports/[id] --method get --tags admin,reports
223
+ ```
224
+
225
+ creates `src/domains/admin/controllers/reports.[id].get.controller.ts` when using the default domain layout. Override the discovery root with `--root` when your project stores controllers elsewhere.
226
+
227
+ ### `kick generate domain <name>`
228
+
229
+ Create a domain folder following your configured layout (defaults to `src/domains/<name>/(controllers|services|domain)`) and, unless `--no-controller` is passed, drop in a starter `index.get.controller.ts` file you can immediately extend.
230
+
231
+ ### Custom commands
232
+
233
+ Add `kick.config.ts` (or `.js`/`.json`) to declare shorthand commands that proxy to shell steps:
234
+
235
+ ```ts
236
+ import type { KickConfig } from '@forinda/kickjs';
237
+
238
+ const config: KickConfig = {
239
+ structure: {
240
+ domainRoot: 'src/domains',
241
+ domainFolders: ['controllers', 'services', 'domain'],
242
+ defaultDomain: 'app'
243
+ },
244
+ generators: { controllerRoot: 'src/domains/app/controllers' },
245
+ commands: [
246
+ { name: 'dev', description: 'Start the dev server', steps: 'npm run dev' },
247
+ { name: 'lint', steps: ['npm run lint', 'npm run typecheck'] }
248
+ ]
249
+ };
250
+
251
+ export default config;
252
+ ```
253
+
254
+ Any command listed becomes available directly, so `kick lint` runs the declared steps. The `structure` block informs both discovery defaults and the CLI generators/initialiser.
255
+
256
+ ## Configuration helper
257
+
258
+ Use `createKickConfig` to compose application settings that blend defaults, environment variables, and ad-hoc overrides:
259
+
260
+ ```ts
261
+ // src/config/kick.config.ts
262
+ import { createKickConfig } from '@forinda/kickjs';
263
+
264
+ export default createKickConfig({
265
+ defaults: {
266
+ prefix: '/api',
267
+ api: {
268
+ discovery: {
269
+ roots: ['src/domains/app/controllers', 'src/http']
270
+ }
271
+ }
272
+ },
273
+ env: {
274
+ KICK_PREFIX: 'prefix',
275
+ KICK_HEALTH: 'healthEndpoint',
276
+ KICK_LOG_LEVEL: { path: 'logging.level' }
277
+ },
278
+ overrides: (current) => ({
279
+ telemetry: {
280
+ trackReactiveHistory: process.env.NODE_ENV !== 'production'
281
+ }
282
+ })
283
+ });
284
+ ```
285
+
286
+ You can pass the resulting `AppConfig` to `configureApp(config)` during bootstrap or supply it via `createApp({ config })` when composing tests. Environment bindings auto-cast booleans/numbers and accept custom transformers for complex structures.
113
287
 
114
288
  ## Diagnostics & telemetry
115
289