@forinda/kickjs 0.1.0 → 0.1.4
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 +197 -23
- package/dist/cli.js +765 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +133 -3
- package/dist/index.js +829 -100
- package/dist/index.js.map +1 -1
- package/package.json +5 -1
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
|
|
27
|
-
import type { Request, Response } from
|
|
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
|
|
36
|
+
configureApp,
|
|
37
|
+
} from "@forinda/kickjs";
|
|
39
38
|
|
|
40
|
-
configureApp({ prefix:
|
|
39
|
+
configureApp({ prefix: "/api/v1" });
|
|
41
40
|
|
|
42
|
-
@Controller(
|
|
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
|
|
44
|
+
return "HelloController";
|
|
50
45
|
}
|
|
51
46
|
|
|
52
47
|
@Get({
|
|
53
|
-
path:
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
}
|
|
48
|
+
path: "/",
|
|
49
|
+
middlewares: [],
|
|
50
|
+
validate: {},
|
|
57
51
|
})
|
|
58
52
|
handle(req: Request, res: Response) {
|
|
59
|
-
const name = typeof req.query.name ===
|
|
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
|
-
|
|
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
|
-
- `
|
|
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
|
|