@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.
Files changed (161) hide show
  1. package/dist/mcp-server/common/paths.d.ts +4 -2
  2. package/dist/mcp-server/common/paths.d.ts.map +1 -1
  3. package/dist/mcp-server/common/paths.js +8 -6
  4. package/dist/mcp-server/common/paths.js.map +1 -1
  5. package/dist/mcp-server/tools/docs/get-document-content.tool.d.ts +1 -1
  6. package/dist/mcp-server/tools/docs/get-document-content.tool.d.ts.map +1 -1
  7. package/dist/mcp-server/tools/docs/get-document-content.tool.js +7 -7
  8. package/dist/mcp-server/tools/docs/get-document-metadata.tool.js +3 -3
  9. package/dist/mcp-server/tools/docs/get-package-overview.tool.d.ts +1 -1
  10. package/dist/mcp-server/tools/docs/get-package-overview.tool.js +1 -1
  11. package/package.json +1 -1
  12. package/wiki/best-practices/api-usage-examples.md +9 -9
  13. package/wiki/best-practices/architectural-patterns.md +19 -3
  14. package/wiki/best-practices/architecture-decisions.md +6 -6
  15. package/wiki/best-practices/code-style-standards/advanced-patterns.md +1 -1
  16. package/wiki/best-practices/code-style-standards/control-flow.md +1 -1
  17. package/wiki/best-practices/code-style-standards/function-patterns.md +2 -2
  18. package/wiki/best-practices/code-style-standards/index.md +2 -2
  19. package/wiki/best-practices/code-style-standards/naming-conventions.md +1 -1
  20. package/wiki/best-practices/code-style-standards/route-definitions.md +4 -4
  21. package/wiki/best-practices/data-modeling.md +1 -1
  22. package/wiki/best-practices/deployment-strategies.md +1 -1
  23. package/wiki/best-practices/error-handling.md +2 -2
  24. package/wiki/best-practices/performance-optimization.md +3 -3
  25. package/wiki/best-practices/security-guidelines.md +2 -2
  26. package/wiki/best-practices/troubleshooting-tips.md +1 -1
  27. package/wiki/{references → extensions}/components/authentication/api.md +12 -20
  28. package/wiki/{references → extensions}/components/authentication/errors.md +1 -1
  29. package/wiki/{references → extensions}/components/authentication/index.md +5 -8
  30. package/wiki/{references → extensions}/components/authentication/usage.md +20 -36
  31. package/wiki/{references → extensions}/components/authorization/api.md +62 -13
  32. package/wiki/{references → extensions}/components/authorization/errors.md +12 -7
  33. package/wiki/{references → extensions}/components/authorization/index.md +93 -6
  34. package/wiki/{references → extensions}/components/authorization/usage.md +42 -4
  35. package/wiki/{references → extensions}/components/health-check.md +5 -4
  36. package/wiki/{references → extensions}/components/index.md +2 -0
  37. package/wiki/{references → extensions}/components/mail/index.md +1 -1
  38. package/wiki/{references → extensions}/components/request-tracker.md +1 -1
  39. package/wiki/{references → extensions}/components/socket-io/api.md +2 -2
  40. package/wiki/{references → extensions}/components/socket-io/errors.md +2 -0
  41. package/wiki/{references → extensions}/components/socket-io/index.md +24 -20
  42. package/wiki/{references → extensions}/components/socket-io/usage.md +2 -2
  43. package/wiki/{references → extensions}/components/static-asset/api.md +14 -15
  44. package/wiki/{references → extensions}/components/static-asset/errors.md +3 -1
  45. package/wiki/{references → extensions}/components/static-asset/index.md +158 -89
  46. package/wiki/{references → extensions}/components/static-asset/usage.md +8 -5
  47. package/wiki/{references → extensions}/components/swagger.md +3 -3
  48. package/wiki/{references → extensions}/components/template/index.md +4 -4
  49. package/wiki/{references → extensions}/components/template/setup-page.md +1 -1
  50. package/wiki/{references → extensions}/components/template/single-page.md +1 -1
  51. package/wiki/{references → extensions}/components/websocket/api.md +7 -6
  52. package/wiki/{references → extensions}/components/websocket/errors.md +17 -3
  53. package/wiki/{references → extensions}/components/websocket/index.md +17 -11
  54. package/wiki/{references → extensions}/components/websocket/usage.md +2 -2
  55. package/wiki/{references → extensions}/helpers/crypto/index.md +1 -1
  56. package/wiki/{references → extensions}/helpers/env/index.md +9 -5
  57. package/wiki/{references → extensions}/helpers/error/index.md +2 -7
  58. package/wiki/{references → extensions}/helpers/index.md +18 -6
  59. package/wiki/{references → extensions}/helpers/kafka/admin.md +33 -16
  60. package/wiki/extensions/helpers/kafka/consumer.md +384 -0
  61. package/wiki/extensions/helpers/kafka/examples.md +361 -0
  62. package/wiki/extensions/helpers/kafka/index.md +639 -0
  63. package/wiki/{references → extensions}/helpers/kafka/producer.md +100 -96
  64. package/wiki/extensions/helpers/kafka/schema-registry.md +214 -0
  65. package/wiki/{references → extensions}/helpers/logger/index.md +2 -2
  66. package/wiki/{references → extensions}/helpers/queue/index.md +400 -4
  67. package/wiki/{references → extensions}/helpers/storage/api.md +170 -10
  68. package/wiki/{references → extensions}/helpers/storage/index.md +44 -8
  69. package/wiki/{references → extensions}/helpers/template/index.md +1 -1
  70. package/wiki/{references → extensions}/helpers/testing/index.md +4 -4
  71. package/wiki/{references → extensions}/helpers/types/index.md +63 -16
  72. package/wiki/{references → extensions}/helpers/websocket/index.md +1 -1
  73. package/wiki/extensions/index.md +48 -0
  74. package/wiki/guides/core-concepts/application/bootstrapping.md +55 -37
  75. package/wiki/guides/core-concepts/application/index.md +95 -35
  76. package/wiki/guides/core-concepts/components-guide.md +23 -19
  77. package/wiki/guides/core-concepts/components.md +34 -10
  78. package/wiki/guides/core-concepts/dependency-injection.md +99 -34
  79. package/wiki/guides/core-concepts/grpc-controllers.md +295 -0
  80. package/wiki/guides/core-concepts/persistent/datasources.md +27 -8
  81. package/wiki/guides/core-concepts/persistent/models.md +43 -1
  82. package/wiki/guides/core-concepts/persistent/repositories.md +75 -8
  83. package/wiki/guides/core-concepts/persistent/transactions.md +38 -8
  84. package/wiki/guides/core-concepts/{controllers.md → rest-controllers.md} +30 -33
  85. package/wiki/guides/core-concepts/services.md +19 -5
  86. package/wiki/guides/get-started/5-minute-quickstart.md +6 -7
  87. package/wiki/guides/get-started/philosophy.md +1 -1
  88. package/wiki/guides/index.md +2 -2
  89. package/wiki/guides/reference/glossary.md +7 -7
  90. package/wiki/guides/reference/mcp-docs-server.md +1 -1
  91. package/wiki/guides/tutorials/building-a-crud-api.md +2 -2
  92. package/wiki/guides/tutorials/complete-installation.md +17 -14
  93. package/wiki/guides/tutorials/ecommerce-api.md +18 -18
  94. package/wiki/guides/tutorials/realtime-chat.md +8 -8
  95. package/wiki/guides/tutorials/testing.md +2 -2
  96. package/wiki/index.md +4 -3
  97. package/wiki/references/base/application.md +341 -21
  98. package/wiki/references/base/bootstrapping.md +43 -13
  99. package/wiki/references/base/components.md +259 -8
  100. package/wiki/references/base/controllers.md +556 -253
  101. package/wiki/references/base/datasources.md +159 -79
  102. package/wiki/references/base/dependency-injection.md +299 -48
  103. package/wiki/references/base/filter-system/application-usage.md +18 -2
  104. package/wiki/references/base/filter-system/array-operators.md +14 -6
  105. package/wiki/references/base/filter-system/comparison-operators.md +9 -3
  106. package/wiki/references/base/filter-system/default-filter.md +28 -3
  107. package/wiki/references/base/filter-system/fields-order-pagination.md +17 -13
  108. package/wiki/references/base/filter-system/index.md +169 -11
  109. package/wiki/references/base/filter-system/json-filtering.md +51 -18
  110. package/wiki/references/base/filter-system/list-operators.md +4 -3
  111. package/wiki/references/base/filter-system/logical-operators.md +7 -2
  112. package/wiki/references/base/filter-system/null-operators.md +50 -0
  113. package/wiki/references/base/filter-system/quick-reference.md +82 -243
  114. package/wiki/references/base/filter-system/range-operators.md +7 -1
  115. package/wiki/references/base/filter-system/tips.md +34 -7
  116. package/wiki/references/base/filter-system/use-cases.md +6 -5
  117. package/wiki/references/base/grpc-controllers.md +984 -0
  118. package/wiki/references/base/index.md +32 -24
  119. package/wiki/references/base/middleware.md +347 -0
  120. package/wiki/references/base/models.md +390 -46
  121. package/wiki/references/base/providers.md +14 -14
  122. package/wiki/references/base/repositories/advanced.md +84 -69
  123. package/wiki/references/base/repositories/index.md +447 -12
  124. package/wiki/references/base/repositories/mixins.md +103 -98
  125. package/wiki/references/base/repositories/relations.md +129 -45
  126. package/wiki/references/base/repositories/soft-deletable.md +104 -23
  127. package/wiki/references/base/services.md +94 -14
  128. package/wiki/references/index.md +12 -10
  129. package/wiki/references/quick-reference.md +98 -65
  130. package/wiki/references/utilities/crypto.md +21 -4
  131. package/wiki/references/utilities/date.md +25 -7
  132. package/wiki/references/utilities/index.md +26 -24
  133. package/wiki/references/utilities/jsx.md +54 -54
  134. package/wiki/references/utilities/module.md +8 -6
  135. package/wiki/references/utilities/parse.md +16 -9
  136. package/wiki/references/utilities/performance.md +22 -7
  137. package/wiki/references/utilities/promise.md +19 -16
  138. package/wiki/references/utilities/request.md +48 -26
  139. package/wiki/references/utilities/schema.md +69 -6
  140. package/wiki/references/utilities/statuses.md +131 -140
  141. package/wiki/references/helpers/kafka/consumer.md +0 -473
  142. package/wiki/references/helpers/kafka/examples.md +0 -234
  143. package/wiki/references/helpers/kafka/index.md +0 -482
  144. /package/wiki/{references → extensions}/components/mail/api.md +0 -0
  145. /package/wiki/{references → extensions}/components/mail/errors.md +0 -0
  146. /package/wiki/{references → extensions}/components/mail/usage.md +0 -0
  147. /package/wiki/{references → extensions}/components/template/api-page.md +0 -0
  148. /package/wiki/{references → extensions}/components/template/errors-page.md +0 -0
  149. /package/wiki/{references → extensions}/components/template/usage-page.md +0 -0
  150. /package/wiki/{references → extensions}/helpers/cron/index.md +0 -0
  151. /package/wiki/{references → extensions}/helpers/inversion/index.md +0 -0
  152. /package/wiki/{references → extensions}/helpers/network/api.md +0 -0
  153. /package/wiki/{references → extensions}/helpers/network/index.md +0 -0
  154. /package/wiki/{references → extensions}/helpers/redis/index.md +0 -0
  155. /package/wiki/{references → extensions}/helpers/socket-io/api.md +0 -0
  156. /package/wiki/{references → extensions}/helpers/socket-io/index.md +0 -0
  157. /package/wiki/{references → extensions}/helpers/template/single-page.md +0 -0
  158. /package/wiki/{references → extensions}/helpers/uid/index.md +0 -0
  159. /package/wiki/{references → extensions}/helpers/websocket/api.md +0 -0
  160. /package/wiki/{references → extensions}/helpers/worker-thread/index.md +0 -0
  161. /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 | `preConfigure()`, `postConfigure()`, `validateEnvs()` |
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 the `OpenAPIHono` instance (underlying web server) |
31
- | **Runtime Detection** | Auto-detects Bun or Node.js and uses appropriate server implementation |
32
- | **Core Bindings** | Registers essential services (`CoreBindings.APPLICATION_INSTANCE`, `CoreBindings.APPLICATION_SERVER`) |
33
- | **Lifecycle Management** | Defines abstract methods (`preConfigure`, `postConfigure`, `setupMiddlewares`) |
34
- | **Environment Validation** | Validates all required `APP_ENV_*` environment variables |
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 resource registration.
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(MyComponent, opts?)` | `components.MyComponent` (default) or custom key via `opts.binding` |
47
- | `controller(MyController, opts?)` | `controllers.MyController` (default) or custom key via `opts.binding` |
48
- | `service(MyService, opts?)` | `services.MyService` (default) or custom key via `opts.binding` |
49
- | `repository(MyRepository, opts?)`| `repositories.MyRepository` (default) or custom key via `opts.binding` |
50
- | `dataSource(MyDataSource, opts?)`| `datasources.MyDataSource` (default) or custom key via `opts.binding` |
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'`, `'controllers'`) |
75
- | `onBeforeConfigure` | callback | Called before each binding's `configure()` — use for validation |
76
- | `onAfterConfigure` | callback | Called after `configure()` — use for route mounting, post-setup |
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 | Example: fetch initial data from repository |
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?(): Promise<void> | void;
147
- discover?(): Promise<void> | void;
148
- load?(): Promise<void> | void;
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 (e.g., `{dir1,dir2}/**/*.{ext1,ext2}`)
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<TClass<any>[]>
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<TClass<any>[]>` - Array of loaded class constructors
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