@venizia/ignis-docs 0.0.7-2 → 0.0.8-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.
- package/dist/mcp-server/common/paths.d.ts +4 -2
- package/dist/mcp-server/common/paths.d.ts.map +1 -1
- package/dist/mcp-server/common/paths.js +8 -6
- package/dist/mcp-server/common/paths.js.map +1 -1
- package/dist/mcp-server/tools/docs/get-document-content.tool.d.ts +1 -1
- package/dist/mcp-server/tools/docs/get-document-content.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/docs/get-document-content.tool.js +7 -7
- package/dist/mcp-server/tools/docs/get-document-metadata.tool.js +3 -3
- package/dist/mcp-server/tools/docs/get-package-overview.tool.d.ts +1 -1
- package/dist/mcp-server/tools/docs/get-package-overview.tool.js +1 -1
- package/package.json +1 -1
- package/wiki/best-practices/api-usage-examples.md +9 -9
- package/wiki/best-practices/architectural-patterns.md +19 -3
- package/wiki/best-practices/architecture-decisions.md +6 -6
- package/wiki/best-practices/code-style-standards/advanced-patterns.md +1 -1
- package/wiki/best-practices/code-style-standards/control-flow.md +1 -1
- package/wiki/best-practices/code-style-standards/function-patterns.md +2 -2
- package/wiki/best-practices/code-style-standards/index.md +2 -2
- package/wiki/best-practices/code-style-standards/naming-conventions.md +1 -1
- package/wiki/best-practices/code-style-standards/route-definitions.md +4 -4
- package/wiki/best-practices/data-modeling.md +1 -1
- package/wiki/best-practices/deployment-strategies.md +1 -1
- package/wiki/best-practices/error-handling.md +2 -2
- package/wiki/best-practices/performance-optimization.md +3 -3
- package/wiki/best-practices/security-guidelines.md +2 -2
- package/wiki/best-practices/troubleshooting-tips.md +1 -1
- package/wiki/{references → extensions}/components/authentication/api.md +12 -20
- package/wiki/{references → extensions}/components/authentication/errors.md +1 -1
- package/wiki/{references → extensions}/components/authentication/index.md +5 -8
- package/wiki/{references → extensions}/components/authentication/usage.md +20 -36
- package/wiki/{references → extensions}/components/authorization/api.md +62 -13
- package/wiki/{references → extensions}/components/authorization/errors.md +12 -7
- package/wiki/{references → extensions}/components/authorization/index.md +93 -6
- package/wiki/{references → extensions}/components/authorization/usage.md +42 -4
- package/wiki/{references → extensions}/components/health-check.md +5 -4
- package/wiki/{references → extensions}/components/index.md +2 -0
- package/wiki/{references → extensions}/components/mail/index.md +1 -1
- package/wiki/{references → extensions}/components/request-tracker.md +1 -1
- package/wiki/{references → extensions}/components/socket-io/api.md +2 -2
- package/wiki/{references → extensions}/components/socket-io/errors.md +2 -0
- package/wiki/{references → extensions}/components/socket-io/index.md +24 -20
- package/wiki/{references → extensions}/components/socket-io/usage.md +2 -2
- package/wiki/{references → extensions}/components/static-asset/api.md +14 -15
- package/wiki/{references → extensions}/components/static-asset/errors.md +3 -1
- package/wiki/{references → extensions}/components/static-asset/index.md +158 -89
- package/wiki/{references → extensions}/components/static-asset/usage.md +8 -5
- package/wiki/{references → extensions}/components/swagger.md +3 -3
- package/wiki/{references → extensions}/components/template/index.md +4 -4
- package/wiki/{references → extensions}/components/template/setup-page.md +1 -1
- package/wiki/{references → extensions}/components/template/single-page.md +1 -1
- package/wiki/{references → extensions}/components/websocket/api.md +7 -6
- package/wiki/{references → extensions}/components/websocket/errors.md +17 -3
- package/wiki/{references → extensions}/components/websocket/index.md +17 -11
- package/wiki/{references → extensions}/components/websocket/usage.md +2 -2
- package/wiki/{references → extensions}/helpers/crypto/index.md +1 -1
- package/wiki/{references → extensions}/helpers/env/index.md +9 -5
- package/wiki/{references → extensions}/helpers/error/index.md +2 -7
- package/wiki/{references → extensions}/helpers/index.md +18 -6
- package/wiki/{references → extensions}/helpers/kafka/admin.md +33 -16
- package/wiki/extensions/helpers/kafka/consumer.md +384 -0
- package/wiki/extensions/helpers/kafka/examples.md +361 -0
- package/wiki/extensions/helpers/kafka/index.md +639 -0
- package/wiki/{references → extensions}/helpers/kafka/producer.md +100 -96
- package/wiki/extensions/helpers/kafka/schema-registry.md +214 -0
- package/wiki/{references → extensions}/helpers/logger/index.md +2 -2
- package/wiki/{references → extensions}/helpers/queue/index.md +400 -4
- package/wiki/{references → extensions}/helpers/storage/api.md +170 -10
- package/wiki/{references → extensions}/helpers/storage/index.md +44 -8
- package/wiki/{references → extensions}/helpers/template/index.md +1 -1
- package/wiki/{references → extensions}/helpers/testing/index.md +4 -4
- package/wiki/{references → extensions}/helpers/types/index.md +63 -16
- package/wiki/{references → extensions}/helpers/websocket/index.md +1 -1
- package/wiki/extensions/index.md +48 -0
- package/wiki/guides/core-concepts/application/bootstrapping.md +55 -37
- package/wiki/guides/core-concepts/application/index.md +95 -35
- package/wiki/guides/core-concepts/components-guide.md +23 -19
- package/wiki/guides/core-concepts/components.md +34 -10
- package/wiki/guides/core-concepts/dependency-injection.md +99 -34
- package/wiki/guides/core-concepts/grpc-controllers.md +295 -0
- package/wiki/guides/core-concepts/persistent/datasources.md +27 -8
- package/wiki/guides/core-concepts/persistent/models.md +43 -1
- package/wiki/guides/core-concepts/persistent/repositories.md +75 -8
- package/wiki/guides/core-concepts/persistent/transactions.md +38 -8
- package/wiki/guides/core-concepts/{controllers.md → rest-controllers.md} +30 -33
- package/wiki/guides/core-concepts/services.md +19 -5
- package/wiki/guides/get-started/5-minute-quickstart.md +6 -7
- package/wiki/guides/get-started/philosophy.md +1 -1
- package/wiki/guides/index.md +2 -2
- package/wiki/guides/reference/glossary.md +7 -7
- package/wiki/guides/reference/mcp-docs-server.md +1 -1
- package/wiki/guides/tutorials/building-a-crud-api.md +2 -2
- package/wiki/guides/tutorials/complete-installation.md +17 -14
- package/wiki/guides/tutorials/ecommerce-api.md +18 -18
- package/wiki/guides/tutorials/realtime-chat.md +8 -8
- package/wiki/guides/tutorials/testing.md +2 -2
- package/wiki/index.md +4 -3
- package/wiki/references/base/application.md +341 -21
- package/wiki/references/base/bootstrapping.md +43 -13
- package/wiki/references/base/components.md +259 -8
- package/wiki/references/base/controllers.md +556 -253
- package/wiki/references/base/datasources.md +159 -79
- package/wiki/references/base/dependency-injection.md +299 -48
- package/wiki/references/base/filter-system/application-usage.md +18 -2
- package/wiki/references/base/filter-system/array-operators.md +14 -6
- package/wiki/references/base/filter-system/comparison-operators.md +9 -3
- package/wiki/references/base/filter-system/default-filter.md +28 -3
- package/wiki/references/base/filter-system/fields-order-pagination.md +17 -13
- package/wiki/references/base/filter-system/index.md +169 -11
- package/wiki/references/base/filter-system/json-filtering.md +51 -18
- package/wiki/references/base/filter-system/list-operators.md +4 -3
- package/wiki/references/base/filter-system/logical-operators.md +7 -2
- package/wiki/references/base/filter-system/null-operators.md +50 -0
- package/wiki/references/base/filter-system/quick-reference.md +82 -243
- package/wiki/references/base/filter-system/range-operators.md +7 -1
- package/wiki/references/base/filter-system/tips.md +34 -7
- package/wiki/references/base/filter-system/use-cases.md +6 -5
- package/wiki/references/base/grpc-controllers.md +984 -0
- package/wiki/references/base/index.md +32 -24
- package/wiki/references/base/middleware.md +347 -0
- package/wiki/references/base/models.md +390 -46
- package/wiki/references/base/providers.md +14 -14
- package/wiki/references/base/repositories/advanced.md +84 -69
- package/wiki/references/base/repositories/index.md +447 -12
- package/wiki/references/base/repositories/mixins.md +103 -98
- package/wiki/references/base/repositories/relations.md +129 -45
- package/wiki/references/base/repositories/soft-deletable.md +104 -23
- package/wiki/references/base/services.md +94 -14
- package/wiki/references/index.md +12 -10
- package/wiki/references/quick-reference.md +98 -65
- package/wiki/references/utilities/crypto.md +21 -4
- package/wiki/references/utilities/date.md +25 -7
- package/wiki/references/utilities/index.md +26 -24
- package/wiki/references/utilities/jsx.md +54 -54
- package/wiki/references/utilities/module.md +8 -6
- package/wiki/references/utilities/parse.md +16 -9
- package/wiki/references/utilities/performance.md +22 -7
- package/wiki/references/utilities/promise.md +19 -16
- package/wiki/references/utilities/request.md +48 -26
- package/wiki/references/utilities/schema.md +69 -6
- package/wiki/references/utilities/statuses.md +131 -140
- package/wiki/references/helpers/kafka/consumer.md +0 -473
- package/wiki/references/helpers/kafka/examples.md +0 -234
- package/wiki/references/helpers/kafka/index.md +0 -482
- /package/wiki/{references → extensions}/components/mail/api.md +0 -0
- /package/wiki/{references → extensions}/components/mail/errors.md +0 -0
- /package/wiki/{references → extensions}/components/mail/usage.md +0 -0
- /package/wiki/{references → extensions}/components/template/api-page.md +0 -0
- /package/wiki/{references → extensions}/components/template/errors-page.md +0 -0
- /package/wiki/{references → extensions}/components/template/usage-page.md +0 -0
- /package/wiki/{references → extensions}/helpers/cron/index.md +0 -0
- /package/wiki/{references → extensions}/helpers/inversion/index.md +0 -0
- /package/wiki/{references → extensions}/helpers/network/api.md +0 -0
- /package/wiki/{references → extensions}/helpers/network/index.md +0 -0
- /package/wiki/{references → extensions}/helpers/redis/index.md +0 -0
- /package/wiki/{references → extensions}/helpers/socket-io/api.md +0 -0
- /package/wiki/{references → extensions}/helpers/socket-io/index.md +0 -0
- /package/wiki/{references → extensions}/helpers/template/single-page.md +0 -0
- /package/wiki/{references → extensions}/helpers/uid/index.md +0 -0
- /package/wiki/{references → extensions}/helpers/websocket/api.md +0 -0
- /package/wiki/{references → extensions}/helpers/worker-thread/index.md +0 -0
- /package/wiki/{references → extensions}/src-details/mcp-server.md +0 -0
|
@@ -11,43 +11,135 @@ Technical reference for `AbstractApplication` and `BaseApplication` - the founda
|
|
|
11
11
|
**Files:**
|
|
12
12
|
- `packages/core/src/base/applications/abstract.ts`
|
|
13
13
|
- `packages/core/src/base/applications/base.ts`
|
|
14
|
+
- `packages/core/src/base/applications/types.ts`
|
|
14
15
|
|
|
15
16
|
## Quick Reference
|
|
16
17
|
|
|
17
18
|
| Class | Purpose | Key Methods |
|
|
18
19
|
|-------|---------|-------------|
|
|
19
|
-
| **AbstractApplication** | Base class with lifecycle management | `
|
|
20
|
-
| **BaseApplication** | Concrete implementation with resource registration | `component()`, `controller()`, `service()`, `repository()`, `dataSource()` |
|
|
20
|
+
| **AbstractApplication** | Base class with lifecycle management, server start/stop | `start()`, `stop()`, `init()`, `validateEnvs()` |
|
|
21
|
+
| **BaseApplication** | Concrete implementation with resource registration and boot support | `component()`, `controller()`, `service()`, `repository()`, `dataSource()`, `boot()` |
|
|
21
22
|
|
|
22
23
|
## `AbstractApplication`
|
|
23
24
|
|
|
24
|
-
Base class responsible for core lifecycle and server management.
|
|
25
|
+
Base class responsible for core lifecycle and server management. Extends `Container` (IoC container) and implements `IApplication`.
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
abstract class AbstractApplication<
|
|
29
|
+
AppEnv extends Env = Env,
|
|
30
|
+
AppSchema extends Schema = {},
|
|
31
|
+
BasePath extends string = '/',
|
|
32
|
+
> extends Container implements IApplication<AppEnv, AppSchema, BasePath>
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Constructor
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
constructor(opts: { scope: string; config: IApplicationConfigs })
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The constructor:
|
|
42
|
+
1. Merges the provided config with defaults (host from `HOST` or `APP_ENV_SERVER_HOST` env, port from `PORT` or `APP_ENV_SERVER_PORT` env, defaults to `localhost:3000`)
|
|
43
|
+
2. Enables `asyncContext` by default (`{ enable: true }`)
|
|
44
|
+
3. Sets `strictPath` to `true` by default for the Hono instance
|
|
45
|
+
4. Creates two `OpenAPIHono` instances: the main server and a `rootRouter`
|
|
46
|
+
5. Auto-detects the runtime (Bun or Node.js)
|
|
25
47
|
|
|
26
48
|
### Key Features
|
|
27
49
|
|
|
28
50
|
| Feature | Description |
|
|
29
51
|
| :--- | :--- |
|
|
30
|
-
| **Hono Instance** | Creates and holds
|
|
31
|
-
| **Runtime Detection** | Auto-detects Bun or Node.js and uses appropriate server implementation |
|
|
32
|
-
| **Core Bindings** | Registers
|
|
33
|
-
| **Lifecycle Management** | Defines abstract methods (`preConfigure`, `postConfigure`, `setupMiddlewares`) |
|
|
34
|
-
| **Environment Validation** | Validates all
|
|
52
|
+
| **Hono Instance** | Creates and holds two `OpenAPIHono` instances — a main server and a root router |
|
|
53
|
+
| **Runtime Detection** | Auto-detects Bun or Node.js via `RuntimeModules.detect()` and uses the appropriate server implementation |
|
|
54
|
+
| **Core Bindings** | Registers `CoreBindings.APPLICATION_INSTANCE`, `CoreBindings.APPLICATION_SERVER`, and `CoreBindings.APPLICATION_ROOT_ROUTER` |
|
|
55
|
+
| **Lifecycle Management** | Defines abstract methods (`preConfigure`, `postConfigure`, `setupMiddlewares`, `staticConfigure`, `initialize`, `getAppInfo`) |
|
|
56
|
+
| **Environment Validation** | Validates all registered `applicationEnvironment` keys are non-empty (unless `ALLOW_EMPTY_ENV_VALUE` is set) |
|
|
57
|
+
| **Post-Start Hooks** | Supports registering hooks that execute after the server starts |
|
|
58
|
+
|
|
59
|
+
### Abstract Methods
|
|
60
|
+
|
|
61
|
+
These must be implemented by subclasses:
|
|
62
|
+
|
|
63
|
+
| Method | Signature | Purpose |
|
|
64
|
+
| :--- | :--- | :--- |
|
|
65
|
+
| `getAppInfo()` | `() => ValueOrPromise<IApplicationInfo>` | Return application metadata (name, version, description) |
|
|
66
|
+
| `preConfigure()` | `() => ValueOrPromise<void>` | Register resources before framework auto-configuration |
|
|
67
|
+
| `postConfigure()` | `() => ValueOrPromise<void>` | Logic after all resources are configured |
|
|
68
|
+
| `staticConfigure()` | `() => void` | Pre-DI static setup (synchronous) |
|
|
69
|
+
| `setupMiddlewares(opts?)` | `(opts?: { middlewares?: Record<string \| symbol, any> }) => ValueOrPromise<void>` | Register Hono middlewares |
|
|
70
|
+
| `initialize()` | `() => Promise<void>` | Full initialization sequence |
|
|
71
|
+
|
|
72
|
+
### Public Methods
|
|
73
|
+
|
|
74
|
+
| Method | Return Type | Description |
|
|
75
|
+
| :--- | :--- | :--- |
|
|
76
|
+
| `getProjectConfigs()` | `IApplicationConfigs` | Returns the merged application config |
|
|
77
|
+
| `getProjectRoot()` | `string` | Returns `process.cwd()` and binds it to `CoreBindings.APPLICATION_PROJECT_ROOT` |
|
|
78
|
+
| `getRootRouter()` | `OpenAPIHono` | Returns the root router instance |
|
|
79
|
+
| `getServerHost()` | `string` | Returns the configured host |
|
|
80
|
+
| `getServerPort()` | `number` | Returns the configured port |
|
|
81
|
+
| `getServerAddress()` | `string` | Returns `host:port` string |
|
|
82
|
+
| `getServer()` | `OpenAPIHono` | Returns the main Hono server instance |
|
|
83
|
+
| `getServerInstance()` | `TBunServerInstance \| TNodeServerInstance \| undefined` | Returns the underlying runtime server instance |
|
|
84
|
+
| `registerPostStartHook(opts)` | `void` | Register a hook to run after server start |
|
|
85
|
+
| `init()` | `void` | Calls `registerCoreBindings()` |
|
|
86
|
+
| `start()` | `Promise<void>` | Runs `initialize()`, `setupMiddlewares()`, mounts root router, starts the server, then runs post-start hooks |
|
|
87
|
+
| `stop()` | `void` | Stops the server (calls `.stop()` for Bun, `.close()` for Node.js) |
|
|
88
|
+
|
|
89
|
+
### `start()` Method Flow
|
|
90
|
+
|
|
91
|
+
```mermaid
|
|
92
|
+
graph TD
|
|
93
|
+
A(start) --> B(initialize);
|
|
94
|
+
B --> C(setupMiddlewares);
|
|
95
|
+
C --> D(Mount rootRouter on base path);
|
|
96
|
+
D --> E{Runtime?};
|
|
97
|
+
E -->|Bun| F(Bun.serve);
|
|
98
|
+
E -->|Node.js| G(@hono/node-server serve);
|
|
99
|
+
F --> H(executePostStartHooks);
|
|
100
|
+
G --> H;
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Server Types
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
// Bun server instance
|
|
107
|
+
type TBunServerInstance = ReturnType<typeof Bun.serve>;
|
|
108
|
+
|
|
109
|
+
// Node.js server instance (from @hono/node-server)
|
|
110
|
+
type TNodeServerInstance = any;
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The server is stored as a discriminated union based on runtime:
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
protected server:
|
|
117
|
+
| { hono: OpenAPIHono; runtime: 'bun'; instance?: TBunServerInstance }
|
|
118
|
+
| { hono: OpenAPIHono; runtime: 'node'; instance?: TNodeServerInstance };
|
|
119
|
+
```
|
|
35
120
|
|
|
36
121
|
## `BaseApplication`
|
|
37
122
|
|
|
38
|
-
Extends `AbstractApplication` with concrete lifecycle implementations and
|
|
123
|
+
Extends `AbstractApplication` with concrete lifecycle implementations, resource registration, and boot support. Implements `IRestApplication` and `IBootableApplication`.
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
abstract class BaseApplication
|
|
127
|
+
extends AbstractApplication
|
|
128
|
+
implements IRestApplication, IBootableApplication
|
|
129
|
+
```
|
|
39
130
|
|
|
40
131
|
### Resource Registration Methods
|
|
41
132
|
|
|
42
133
|
`BaseApplication` provides a set of convenient methods for registering your application's building blocks. These methods bind the provided classes to the DI container with conventional keys.
|
|
43
134
|
|
|
44
|
-
| Method | DI Binding Key Convention |
|
|
45
|
-
| :--- | :--- |
|
|
46
|
-
| `component(
|
|
47
|
-
| `controller(
|
|
48
|
-
| `service(
|
|
49
|
-
| `repository(
|
|
50
|
-
| `dataSource(
|
|
135
|
+
| Method | DI Binding Key Convention | Scope |
|
|
136
|
+
| :--- | :--- | :--- |
|
|
137
|
+
| `component(ctor, opts?)` | `components.{Name}` | Singleton |
|
|
138
|
+
| `controller(ctor, opts?)` | `controllers.{Name}` | Transient |
|
|
139
|
+
| `service(ctor, opts?)` | `services.{Name}` | Transient |
|
|
140
|
+
| `repository(ctor, opts?)` | `repositories.{Name}` | Transient |
|
|
141
|
+
| `dataSource(ctor, opts?)` | `datasources.{Name}` | Singleton |
|
|
142
|
+
| `booter(ctor, opts?)` | `booters.{Name}` | Tagged with `'booter'` |
|
|
51
143
|
|
|
52
144
|
> [!TIP]
|
|
53
145
|
> All registration methods accept an optional `opts.binding` parameter to override the default namespace-based key:
|
|
@@ -57,6 +149,75 @@ Extends `AbstractApplication` with concrete lifecycle implementations and resour
|
|
|
57
149
|
> });
|
|
58
150
|
> ```
|
|
59
151
|
|
|
152
|
+
### Method Signatures
|
|
153
|
+
|
|
154
|
+
```typescript
|
|
155
|
+
component<Base extends BaseComponent, Args extends AnyObject = any>(
|
|
156
|
+
ctor: TClass<Base>,
|
|
157
|
+
opts?: TMixinOpts<Args>,
|
|
158
|
+
): Binding<Base>
|
|
159
|
+
|
|
160
|
+
controller<Base, Args extends AnyObject = any>(
|
|
161
|
+
ctor: TClass<Base>,
|
|
162
|
+
opts?: TMixinOpts<Args>,
|
|
163
|
+
): Binding<Base>
|
|
164
|
+
|
|
165
|
+
service<Base extends IService, Args extends AnyObject = any>(
|
|
166
|
+
ctor: TClass<Base>,
|
|
167
|
+
opts?: TMixinOpts<Args>,
|
|
168
|
+
): Binding<Base>
|
|
169
|
+
|
|
170
|
+
repository<Base extends IRepository<TTableSchemaWithId>, Args extends AnyObject = any>(
|
|
171
|
+
ctor: TClass<Base>,
|
|
172
|
+
opts?: TMixinOpts<Args>,
|
|
173
|
+
): Binding<Base>
|
|
174
|
+
|
|
175
|
+
dataSource<Base extends IDataSource, Args extends AnyObject = any>(
|
|
176
|
+
ctor: TClass<Base>,
|
|
177
|
+
opts?: TMixinOpts<Args>,
|
|
178
|
+
): Binding<Base>
|
|
179
|
+
|
|
180
|
+
booter<Base extends IBooter, Args extends AnyObject = any>(
|
|
181
|
+
ctor: TClass<Base>,
|
|
182
|
+
opts?: TMixinOpts<Args>,
|
|
183
|
+
): Binding<Base>
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Where `TMixinOpts` is:
|
|
187
|
+
|
|
188
|
+
```typescript
|
|
189
|
+
type TMixinOpts<Args extends AnyObject = any> = {
|
|
190
|
+
binding: { namespace: string; key: string };
|
|
191
|
+
args?: Args;
|
|
192
|
+
};
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Static File Serving
|
|
196
|
+
|
|
197
|
+
```typescript
|
|
198
|
+
static(opts: { restPath?: string; folderPath: string }): this
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Serves static files using the appropriate runtime handler (`hono/bun` for Bun, `@hono/node-server/serve-static` for Node.js). The `restPath` defaults to `'*'`.
|
|
202
|
+
|
|
203
|
+
```typescript
|
|
204
|
+
this.static({ restPath: '/public/*', folderPath: './public' });
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Boot Support
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
boot(): Promise<IBootReport>
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Registers default booters (`DatasourceBooter`, `RepositoryBooter`, `ServiceBooter`, `ControllerBooter`) and runs the bootstrapper. The boot options come from `this.configs.bootOptions`.
|
|
214
|
+
|
|
215
|
+
```typescript
|
|
216
|
+
async registerBooters(): Promise<void>
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Registers the `Bootstrapper` singleton and all four default booters with the `'booter'` tag.
|
|
220
|
+
|
|
60
221
|
### registerDynamicBindings
|
|
61
222
|
|
|
62
223
|
Protected method for handling late-registration and circular dependency patterns. Iterates bindings in a namespace, configuring each instance and re-fetching to pick up dynamically added bindings.
|
|
@@ -71,9 +232,9 @@ protected async registerDynamicBindings<T extends IConfigurable>(opts: {
|
|
|
71
232
|
|
|
72
233
|
| Parameter | Type | Description |
|
|
73
234
|
|-----------|------|-------------|
|
|
74
|
-
| `namespace` | `TBindingNamespace` | Binding namespace to scan (e.g., `'components'`, `'
|
|
75
|
-
| `onBeforeConfigure` | callback | Called before each binding's `configure()`
|
|
76
|
-
| `onAfterConfigure` | callback | Called after `configure()`
|
|
235
|
+
| `namespace` | `TBindingNamespace` | Binding namespace to scan (e.g., `'components'`, `'datasources'`) |
|
|
236
|
+
| `onBeforeConfigure` | callback | Called before each binding's `configure()` |
|
|
237
|
+
| `onAfterConfigure` | callback | Called after `configure()` |
|
|
77
238
|
|
|
78
239
|
The method tracks already-configured bindings to prevent duplicates and re-fetches after each configuration to handle bindings registered during the configure phase.
|
|
79
240
|
|
|
@@ -96,9 +257,167 @@ graph TD
|
|
|
96
257
|
|
|
97
258
|
| Hook | When to Use | Notes |
|
|
98
259
|
|------|-------------|-------|
|
|
260
|
+
| **`staticConfigure()`** | Pre-DI static setup (static files, etc.) | Synchronous, called before `preConfigure` |
|
|
99
261
|
| **`preConfigure()`** | Register all resources (datasources, services, controllers) | Nothing instantiated yet - order doesn't matter |
|
|
100
262
|
| **`register...()`** | Framework iterates bindings and instantiates classes | DataSources initialized first (other layers depend on them) |
|
|
101
|
-
| **`postConfigure()`** | Logic after all resources configured |
|
|
263
|
+
| **`postConfigure()`** | Logic after all resources configured | Do not register new datasources/components/controllers here - they won't auto-configure |
|
|
264
|
+
|
|
265
|
+
### registerDefaultMiddlewares
|
|
266
|
+
|
|
267
|
+
Automatically registers these default middlewares during `initialize()`:
|
|
268
|
+
|
|
269
|
+
1. **Error handler** (`appErrorHandler`) - with optional `rootKey` from `configs.error.rootKey`
|
|
270
|
+
2. **Async context storage** (`contextStorage`) - enabled by default via `configs.asyncContext.enable`
|
|
271
|
+
3. **Not-found handler** (`notFoundHandler`)
|
|
272
|
+
4. **RequestTrackerComponent** - assigns `x-request-id` to every request, includes request body parsing
|
|
273
|
+
5. **Emoji favicon** - defaults to the flame emoji, configurable via `configs.favicon`
|
|
274
|
+
|
|
275
|
+
### registerControllers and Transport Support
|
|
276
|
+
|
|
277
|
+
The `registerControllers()` method supports multiple transport protocols via the `transports` config:
|
|
278
|
+
|
|
279
|
+
```typescript
|
|
280
|
+
// In your application config
|
|
281
|
+
{
|
|
282
|
+
transports: ['rest'], // Default: REST only
|
|
283
|
+
transports: ['rest', 'grpc'], // Enable both REST and gRPC
|
|
284
|
+
transports: ['grpc'], // gRPC only
|
|
285
|
+
}
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
For each transport in the array, the corresponding component (`RestComponent` or `GrpcComponent`) is instantiated and configured. If gRPC controllers are discovered but the `'grpc'` transport is not enabled, a warning is logged.
|
|
289
|
+
|
|
290
|
+
### registerComponents
|
|
291
|
+
|
|
292
|
+
When registering components, after each component's `configure()` completes, the framework also re-registers any datasources that the component may have added. This handles the pattern where components bring their own datasources.
|
|
293
|
+
|
|
294
|
+
## `IApplicationConfigs`
|
|
295
|
+
|
|
296
|
+
```typescript
|
|
297
|
+
interface IApplicationConfigs {
|
|
298
|
+
host?: string; // Server host (default: process.env.HOST || 'localhost')
|
|
299
|
+
port?: number; // Server port (default: process.env.PORT || 3000)
|
|
300
|
+
path: { base: string; isStrict: boolean }; // Base path config (required)
|
|
301
|
+
requestId?: { isStrict: boolean }; // Request ID validation
|
|
302
|
+
favicon?: string; // Favicon emoji (default: '🔥')
|
|
303
|
+
error?: { rootKey: string }; // Error response root key
|
|
304
|
+
asyncContext?: { enable: boolean }; // Hono async context storage (default: true)
|
|
305
|
+
bootOptions?: IBootOptions; // Boot system configuration
|
|
306
|
+
debug?: { shouldShowRoutes?: boolean }; // Show registered routes on startup
|
|
307
|
+
transports?: TControllerTransport[]; // Controller transports: 'rest' | 'grpc' (default: ['rest'])
|
|
308
|
+
strictPath?: boolean; // Hono strict path matching (default: true)
|
|
309
|
+
[key: string]: any; // Extensible
|
|
310
|
+
}
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
### `IBootOptions`
|
|
314
|
+
|
|
315
|
+
```typescript
|
|
316
|
+
interface IBootOptions {
|
|
317
|
+
controllers?: IArtifactOptions;
|
|
318
|
+
services?: IArtifactOptions;
|
|
319
|
+
repositories?: IArtifactOptions;
|
|
320
|
+
datasources?: IArtifactOptions;
|
|
321
|
+
[artifactType: string]: IArtifactOptions | undefined;
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
interface IArtifactOptions {
|
|
325
|
+
dirs?: string[];
|
|
326
|
+
extensions?: string[];
|
|
327
|
+
isNested?: boolean;
|
|
328
|
+
glob?: string;
|
|
329
|
+
}
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
### `TControllerTransport`
|
|
333
|
+
|
|
334
|
+
```typescript
|
|
335
|
+
class ControllerTransports {
|
|
336
|
+
static readonly REST = 'rest';
|
|
337
|
+
static readonly GRPC = 'grpc';
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
type TControllerTransport = 'rest' | 'grpc';
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
## `IApplicationInfo`
|
|
344
|
+
|
|
345
|
+
```typescript
|
|
346
|
+
interface IApplicationInfo {
|
|
347
|
+
name: string;
|
|
348
|
+
version: string;
|
|
349
|
+
description: string;
|
|
350
|
+
author?: { name: string; email: string; url?: string };
|
|
351
|
+
[extra: string | symbol]: any;
|
|
352
|
+
}
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
## `CoreBindings`
|
|
356
|
+
|
|
357
|
+
Core binding keys used for fundamental application components:
|
|
358
|
+
|
|
359
|
+
| Key | Value | Description |
|
|
360
|
+
| :--- | :--- | :--- |
|
|
361
|
+
| `APPLICATION_INSTANCE` | `'@app/instance'` | The application instance itself |
|
|
362
|
+
| `APPLICATION_SERVER` | `'@app/server'` | The server object (hono + runtime + instance) |
|
|
363
|
+
| `APPLICATION_CONFIG` | `'@app/config'` | Application configuration |
|
|
364
|
+
| `APPLICATION_PROJECT_ROOT` | `'@app/project_root'` | Project root directory (`process.cwd()`) |
|
|
365
|
+
| `APPLICATION_ROOT_ROUTER` | `'@app/router/root'` | The root OpenAPIHono router |
|
|
366
|
+
| `APPLICATION_ENVIRONMENTS` | `'@app/environments'` | Application environment variables |
|
|
367
|
+
| `APPLICATION_MIDDLEWARE_OPTIONS` | `'@app/middleware_options'` | Middleware configuration options |
|
|
368
|
+
|
|
369
|
+
## `BindingNamespaces`
|
|
370
|
+
|
|
371
|
+
Standard namespaces for organizing DI bindings:
|
|
372
|
+
|
|
373
|
+
| Namespace | Value | Used By |
|
|
374
|
+
| :--- | :--- | :--- |
|
|
375
|
+
| `COMPONENT` | `'components'` | `component()` |
|
|
376
|
+
| `DATASOURCE` | `'datasources'` | `dataSource()` |
|
|
377
|
+
| `REPOSITORY` | `'repositories'` | `repository()` |
|
|
378
|
+
| `MODEL` | `'models'` | Model bindings |
|
|
379
|
+
| `SERVICE` | `'services'` | `service()` |
|
|
380
|
+
| `MIDDLEWARE` | `'middlewares'` | Middleware bindings |
|
|
381
|
+
| `PROVIDER` | `'providers'` | Provider bindings |
|
|
382
|
+
| `CONTROLLER` | `'controllers'` | `controller()` |
|
|
383
|
+
| `BOOTERS` | `'booters'` | `booter()` |
|
|
384
|
+
|
|
385
|
+
## Mixin Interfaces
|
|
386
|
+
|
|
387
|
+
`BaseApplication` implements several mixin interfaces that define its capabilities:
|
|
388
|
+
|
|
389
|
+
| Interface | Methods | Description |
|
|
390
|
+
| :--- | :--- | :--- |
|
|
391
|
+
| `IComponentMixin` | `component()`, `registerComponents()` | Component registration and lifecycle |
|
|
392
|
+
| `IControllerMixin` | `controller()`, `registerControllers()` | Controller registration and route mounting |
|
|
393
|
+
| `IRepositoryMixin` | `dataSource()`, `repository()` | DataSource and repository registration |
|
|
394
|
+
| `IServiceMixin` | `service()` | Service registration |
|
|
395
|
+
| `IStaticServeMixin` | `static()` | Static file serving |
|
|
396
|
+
|
|
397
|
+
> [!NOTE]
|
|
398
|
+
> There is also an `IServerConfigMixin` interface defined in the mixins types that declares `staticConfigure()`, `preConfigure()`, `postConfigure()`, and `getApplicationVersion()`, though `BaseApplication` inherits the first three from `AbstractApplication`.
|
|
399
|
+
|
|
400
|
+
## Middleware Configuration Types
|
|
401
|
+
|
|
402
|
+
These types are used when configuring middlewares via `setupMiddlewares()`:
|
|
403
|
+
|
|
404
|
+
```typescript
|
|
405
|
+
interface IMiddlewareConfigs {
|
|
406
|
+
requestId?: IRequestIdOptions;
|
|
407
|
+
compress?: ICompressOptions;
|
|
408
|
+
cors?: ICORSOptions;
|
|
409
|
+
csrf?: ICSRFOptions;
|
|
410
|
+
bodyLimit?: IBodyLimitOptions;
|
|
411
|
+
ipRestriction?: IBaseMiddlewareOptions & IIPRestrictionRules;
|
|
412
|
+
[extra: string | symbol]: any;
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
interface IBaseMiddlewareOptions {
|
|
416
|
+
enable: boolean;
|
|
417
|
+
path?: string;
|
|
418
|
+
[extra: string | symbol]: any;
|
|
419
|
+
}
|
|
420
|
+
```
|
|
102
421
|
|
|
103
422
|
## See Also
|
|
104
423
|
|
|
@@ -106,11 +425,12 @@ graph TD
|
|
|
106
425
|
- [Application Guide](/guides/core-concepts/application/) - Creating your first application
|
|
107
426
|
- [Bootstrapping](/guides/core-concepts/application/bootstrapping) - Auto-discovery of artifacts
|
|
108
427
|
- [Dependency Injection](/guides/core-concepts/dependency-injection) - How DI works in IGNIS
|
|
109
|
-
- [Controllers](/guides/core-concepts/controllers) - Registering HTTP endpoints
|
|
428
|
+
- [REST Controllers](/guides/core-concepts/rest-controllers) | [gRPC Controllers](/guides/core-concepts/grpc-controllers) - Registering HTTP/gRPC endpoints
|
|
110
429
|
|
|
111
430
|
- **References:**
|
|
112
431
|
- [Bootstrapping API](/references/base/bootstrapping) - Boot system reference
|
|
113
432
|
- [Components API](/references/base/components) - Component system
|
|
433
|
+
- [gRPC Controllers](/references/base/grpc-controllers) - gRPC transport reference
|
|
114
434
|
- [Environment Variables](/references/configuration/environment-variables) - Configuration management
|
|
115
435
|
- [Middlewares](/references/base/middlewares) - Request interceptors
|
|
116
436
|
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
title: Bootstrapping Reference
|
|
3
3
|
description: Technical reference for application bootstrapping and initialization
|
|
4
4
|
difficulty: advanced
|
|
5
|
+
lastUpdated: 2026-03-15
|
|
5
6
|
---
|
|
6
7
|
|
|
7
8
|
# Bootstrapping API Reference
|
|
@@ -32,24 +33,18 @@ Interface that applications must implement to support bootstrapping.
|
|
|
32
33
|
|
|
33
34
|
```typescript
|
|
34
35
|
interface IBootableApplication {
|
|
35
|
-
bootOptions?: IBootOptions;
|
|
36
36
|
boot(): Promise<IBootReport>;
|
|
37
37
|
}
|
|
38
38
|
```
|
|
39
39
|
|
|
40
40
|
| Member | Type | Description |
|
|
41
41
|
|--------|------|-------------|
|
|
42
|
-
| `bootOptions` | `IBootOptions \| undefined` | Configuration for artifact discovery |
|
|
43
42
|
| `boot()` | `() => Promise<IBootReport>` | Execute boot process |
|
|
44
43
|
|
|
45
44
|
**Example:**
|
|
46
45
|
|
|
47
46
|
```typescript
|
|
48
47
|
export class Application extends BaseApplication implements IBootableApplication {
|
|
49
|
-
bootOptions = {
|
|
50
|
-
controllers: { dirs: ['controllers'] }
|
|
51
|
-
};
|
|
52
|
-
|
|
53
48
|
async boot() {
|
|
54
49
|
const bootstrapper = this.get<Bootstrapper>({ key: 'bootstrapper' });
|
|
55
50
|
return bootstrapper.boot({});
|
|
@@ -57,6 +52,8 @@ export class Application extends BaseApplication implements IBootableApplication
|
|
|
57
52
|
}
|
|
58
53
|
```
|
|
59
54
|
|
|
55
|
+
> **Note:** The `BootMixin` adds an optional `bootOptions?: IBootOptions` property to the mixed class, but it is not part of the `IBootableApplication` interface itself.
|
|
56
|
+
|
|
60
57
|
|
|
61
58
|
### IBootOptions
|
|
62
59
|
|
|
@@ -143,12 +140,14 @@ Interface that all booters must implement.
|
|
|
143
140
|
|
|
144
141
|
```typescript
|
|
145
142
|
interface IBooter {
|
|
146
|
-
configure
|
|
147
|
-
discover
|
|
148
|
-
load
|
|
143
|
+
configure(): ValueOrPromise<void>;
|
|
144
|
+
discover(): ValueOrPromise<void>;
|
|
145
|
+
load(): ValueOrPromise<void>;
|
|
149
146
|
}
|
|
150
147
|
```
|
|
151
148
|
|
|
149
|
+
> **Note:** `ValueOrPromise<T>` is `T | Promise<T>`. While the interface requires all three methods, the `Bootstrapper` gracefully skips any phase method that is not a function at runtime, so partial implementations are tolerated in practice.
|
|
150
|
+
|
|
152
151
|
| Method | Phase | Description |
|
|
153
152
|
|--------|-------|-------------|
|
|
154
153
|
| `configure()` | Configure | Setup discovery patterns and options |
|
|
@@ -468,7 +467,13 @@ Generate glob pattern from artifact options.
|
|
|
468
467
|
protected getPattern(): string
|
|
469
468
|
```
|
|
470
469
|
|
|
471
|
-
**Returns:** Glob pattern string
|
|
470
|
+
**Returns:** Glob pattern string. Examples:
|
|
471
|
+
- Single dir/ext: `controllers/{**/*,*}.controller.js`
|
|
472
|
+
- Multiple dirs/exts: `{dir1,dir2}/{**/*,*}.{ext1,ext2}`
|
|
473
|
+
- Non-nested (`isNested: false`): `controllers/*.controller.js`
|
|
474
|
+
- Custom `glob` option overrides pattern generation entirely
|
|
475
|
+
|
|
476
|
+
> **Note:** The nested pattern `{**/*,*}` currently supports one level of nesting.
|
|
472
477
|
|
|
473
478
|
#### Properties
|
|
474
479
|
|
|
@@ -586,6 +591,9 @@ constructor(
|
|
|
586
591
|
| Directories | `['datasources']` |
|
|
587
592
|
| Extensions | `['.datasource.js']` |
|
|
588
593
|
| Binding Key | `datasources.{ClassName}` |
|
|
594
|
+
| Binding Scope | `singleton` |
|
|
595
|
+
|
|
596
|
+
> **Key difference:** `DatasourceBooter` is the only built-in booter that sets bindings to `singleton` scope (via `.setScope('singleton')`). This ensures connection pooling and resource sharing across the application. All other booters use the default transient scope.
|
|
589
597
|
|
|
590
598
|
|
|
591
599
|
## Types
|
|
@@ -667,7 +675,7 @@ Load class constructors from files.
|
|
|
667
675
|
async function loadClasses(opts: {
|
|
668
676
|
files: string[];
|
|
669
677
|
root: string;
|
|
670
|
-
}): Promise<
|
|
678
|
+
}): Promise<AnyType[]>
|
|
671
679
|
```
|
|
672
680
|
|
|
673
681
|
| Parameter | Type | Description |
|
|
@@ -675,7 +683,7 @@ async function loadClasses(opts: {
|
|
|
675
683
|
| `files` | `string[]` | Array of file paths to load |
|
|
676
684
|
| `root` | `string` | Project root (for error messages) |
|
|
677
685
|
|
|
678
|
-
**Returns:** `Promise<
|
|
686
|
+
**Returns:** `Promise<AnyType[]>` - Array of loaded class constructors (filtered by `isClass` type guard)
|
|
679
687
|
|
|
680
688
|
**Example:**
|
|
681
689
|
|
|
@@ -721,9 +729,21 @@ for (const exported of Object.values(module)) {
|
|
|
721
729
|
|
|
722
730
|
## Constants
|
|
723
731
|
|
|
732
|
+
### BootPhases
|
|
733
|
+
|
|
734
|
+
Static class defining boot phase constants.
|
|
735
|
+
|
|
736
|
+
```typescript
|
|
737
|
+
class BootPhases {
|
|
738
|
+
static readonly CONFIGURE = 'configure';
|
|
739
|
+
static readonly DISCOVER = 'discover';
|
|
740
|
+
static readonly LOAD = 'load';
|
|
741
|
+
}
|
|
742
|
+
```
|
|
743
|
+
|
|
724
744
|
### BOOT_PHASES
|
|
725
745
|
|
|
726
|
-
Array of all boot phases in execution order.
|
|
746
|
+
Array of all boot phases in execution order (derived from `BootPhases`).
|
|
727
747
|
|
|
728
748
|
```typescript
|
|
729
749
|
const BOOT_PHASES: TBootPhase[] = ['configure', 'discover', 'load']
|
|
@@ -756,6 +776,14 @@ function BootMixin<T extends TMixinTarget<Container>>(
|
|
|
756
776
|
|
|
757
777
|
**Returns:** Mixed class implementing `IBootableApplication`
|
|
758
778
|
|
|
779
|
+
**Auto-registers in constructor:**
|
|
780
|
+
- `@app/boot-options` -- user boot config (from `this.bootOptions`)
|
|
781
|
+
- `booter.DatasourceBooter` -- tagged `'booter'`
|
|
782
|
+
- `booter.RepositoryBooter` -- tagged `'booter'`
|
|
783
|
+
- `booter.ServiceBooter` -- tagged `'booter'`
|
|
784
|
+
- `booter.ControllerBooter` -- tagged `'booter'`
|
|
785
|
+
- `bootstrapper` -- singleton `Bootstrapper` instance
|
|
786
|
+
|
|
759
787
|
**Example:**
|
|
760
788
|
|
|
761
789
|
```typescript
|
|
@@ -772,6 +800,8 @@ const app = new MyApp();
|
|
|
772
800
|
await app.boot();
|
|
773
801
|
```
|
|
774
802
|
|
|
803
|
+
> **Note:** `BaseApplication` does not use `BootMixin`. Instead, it registers the same booters and bootstrapper in its own `registerBooters()` method using `this.booter()` and reads boot options from `this.configs.bootOptions`.
|
|
804
|
+
|
|
775
805
|
|
|
776
806
|
## See Also
|
|
777
807
|
|