aegisnode 0.0.5 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,76 +2,24 @@
2
2
 
3
3
  ![AegisNode Banner](assets/aegisnode-banner.svg)
4
4
 
5
- AegisNode is a modular, view-first Node.js framework for building web apps, JSON APIs, and hybrid projects without spending the first part of the project wiring the same infrastructure again and again.
6
- It gives you a structured project layout, runtime injection, CLI scaffolding, and production-ready defaults while still keeping the Node.js and Express ecosystem familiar.
5
+ AegisNode is a modular, view-first Node.js framework for building web apps, JSON APIs, and hybrid projects.
6
+ It gives you a structured project layout, runtime injection, CLI scaffolding, and production-ready defaults so you can start building features instead of first wiring routing, config loading, auth, uploads, and other framework glue.
7
7
 
8
8
  AegisNode is designed for developers who want more structure than raw Express, but do not want a framework that hides the Node.js runtime behind too many abstractions.
9
- It keeps the request/response model familiar while organizing the codebase around clear app boundaries, runtime-injected dependencies, and reusable layers such as views, services, models, validators, and subscribers.
9
+ It keeps the request/response model familiar while organizing the codebase around clear app boundaries and reusable layers such as views, services, models, validators, subscribers, and app-local utilities.
10
10
 
11
11
  It works well for projects that mix server-rendered pages and JSON endpoints, for teams that want a consistent project shape from the start, and for codebases that need built-in support for common backend concerns like auth, uploads, i18n, mail, maintenance mode, and environment-driven configuration.
12
- The goal is to reduce setup time, remove repetitive infrastructure work, and give the project a cleaner long-term structure without making day-to-day development feel heavy.
13
-
14
- ## Documentation Guide
15
-
16
- If you are new to AegisNode, read this README in this order:
17
- - Quick Start: create a project, install dependencies, run the server, and understand startup mode rules.
18
- - Core Concepts And App Structure: understand apps, layers, injected runtime context, and project flow.
19
- - Common Tasks And Feature Guides: uploads, API apps, auth, templates, i18n, mail, and related features.
20
- - Full Settings Reference: use this as the complete config manual once you already know what feature you need.
21
- - Runtime Patterns And Advanced Topics: validators, strict layers, subscribers, and security details.
22
-
23
- Standalone HTML handbook:
24
- - Open `docs/index.html` in a browser for a sidebar-based documentation view.
25
-
26
- ## How AegisNode Helps
27
-
28
- AegisNode helps by standardizing the parts that usually consume time early in a project:
29
- - project scaffolding and app generation,
30
- - route and layer organization,
31
- - dependency injection and shared runtime context,
32
- - config loading and environment overrides,
33
- - auth, upload, mail, websocket, and i18n integration,
34
- - operational helpers such as health checks, maintenance mode, and project diagnostics.
35
-
36
- This means you spend less time writing framework glue and more time writing business features.
37
-
38
- ## Why Use AegisNode
39
-
40
- Choose AegisNode if you want a project starter that remains readable as it grows.
41
- It keeps the development model simple, but adds enough structure and tooling to make larger codebases easier to navigate, extend, and maintain.
42
-
43
- Core features:
44
-
45
- - CLI generators (`startproject`, `createapp`, `runserver`)
46
- - App scaffold repair command (`fix`)
47
- - Startup entry generator (`generateloader`)
48
- - Project health checker (`doctor`)
49
- - Dependency updater (`updatedeps`)
50
- - Maintenance mode with custom HTML responses
51
- - Generators for app artifacts (`generate view|model|validator|dto|service|subscriber|route`)
52
- - DI container
53
- - Event system with subscribers
54
- - Modular app structure
55
- - SQL/NoSQL bootstrap via QueryMesh/Mongoose
56
- - WebSocket bootstrap using Socket.IO
57
- - Built-in file uploads with size/type limits (`route.upload`)
58
- - Built-in mail transport wrapper (`mail.send`, `req.aegis.mail.send`)
59
- - Centralized config and loaders
60
- - Security headers via Helmet (configurable CSP) + CSRF protection for form submissions
61
- - Built-in rate limiting for basic DDoS resistance
62
- - Root route file `routes.js` (not `routes/` folder)
63
- - Automatic default confirmation page on `/` when no custom `/` route exists
64
- - App folder uses `views.js` (not `controllers/` folder)
65
- - `createapp` uses file modules: `views.js`, `models.js`, `validators.js`, `routes.js`, `subscribers.js`, `services.js`, `utils.js`
66
- - `createapp` also generates app tests in `apps/<app>/tests`
67
- - EJS templates configurable in `settings.js` with Django-style base layout flow
68
- - Built-in runtime helpers (`money`, `number`, `dateTime`, `timeElapsed`, `toObjectId`) + `jlive` bridge
69
-
70
- `startproject` creates `app.js`, `loader.cjs`, `.env`, `settings.js`, and `routes.js` without creating any default app.
71
- It does not create `public/` or `logs/`; create your own folders and set them in `settings.js`.
72
-
73
- Environment files are loaded automatically before `settings.js` is imported.
74
- Supported files:
12
+
13
+ Read this README in this order:
14
+ 1. Quick Start: get a project created, installed, and running.
15
+ 2. Core Concepts And App Structure: understand where code lives and how layers fit together.
16
+ 3. Common Tasks And Feature Guides: jump to the feature you need once the basics are clear.
17
+ 4. Full Settings Reference: use this when you already know which config block you are looking for.
18
+ 5. Runtime Patterns And Advanced Topics: read this last for middleware, validators, subscribers, and strict-layer behavior.
19
+
20
+ If you prefer a sidebar-based handbook, open `docs/index.html` in a browser.
21
+
22
+ Environment files are loaded automatically before `settings.js` or `settings.ts` is imported:
75
23
  - `.env`
76
24
  - `.env.local`
77
25
  - `.env.<NODE_ENV>`
@@ -81,191 +29,132 @@ Shell or hosting-panel environment variables win over values from `.env` files.
81
29
 
82
30
  ## Quick Start
83
31
 
84
- ### CLI
32
+ Use this section to get a project running first. Skip to later sections only when you need a specific feature or configuration block.
33
+
34
+ ### Create A Project
85
35
 
86
36
  ```bash
87
37
  npm install -g aegisnode
88
38
 
39
+ mkdir blog && cd blog
89
40
  aegisnode startproject blog
90
- npm --prefix blog install
91
- aegisnode runserver --project blog
92
-
93
- aegisnode createapp users --project blog
94
- aegisnode fix --app users --project blog
95
- aegisnode generate view profile --app users --project blog
96
- aegisnode generate route profile --app users --project blog
97
- aegisnode generateloader --project blog
98
- aegisnode doctor --project blog
99
- aegisnode doctor --app users --project blog
100
- aegisnode updatedeps --project blog
101
41
  ```
102
42
 
103
- `cd blog` is optional. You can run commands from parent folder with `--project blog`.
104
-
105
- `createapp`, `fix`, `generate`, `runserver`, `generateloader`, `doctor`, and `updatedeps` are project-level commands.
106
- Run them from the project root; do not `cd` into `apps/<app>`.
107
- Startup mode rules:
108
- - Development (`env === development`): start with `aegisnode runserver` only.
109
- - Non-development (`env !== development`): start with `node loader.cjs` (or your process manager/host pointing to `loader.cjs`).
110
- - `node app.js` and `node loader.cjs` are rejected in development mode.
111
- - `aegisnode runserver` is rejected outside development mode.
112
-
113
- ### Trust Proxy
114
-
115
- If your app runs behind Nginx, Apache, Passenger, or another reverse proxy that terminates HTTPS before the Node process, set top-level `trustProxy` in `settings.js`:
43
+ Create and enter the project directory first. `startproject` scaffolds into the current empty directory; it does not create a nested folder for you.
44
+ Use plain `startproject` for a JavaScript project. Add `--typescript` once if you want the whole scaffold to use `.ts`.
45
+ For a TypeScript project, use `aegisnode startproject blog --typescript` inside the target folder instead.
116
46
 
117
- ```js
118
- export default {
119
- trustProxy: 1,
120
- };
121
- ```
122
-
123
- This is the AegisNode equivalent of `app.set('trust proxy', 1)` in raw Express. It makes `req.secure`, `req.protocol`, client IP detection, secure cookies, and HTTPS-aware auth logic behave correctly behind the proxy.
124
-
125
- Prefer an exact value such as `1`, `'loopback'`, or a subnet string instead of `true`.
47
+ `startproject` creates `app.js`, `loader.cjs`, `.env`, `settings.js`, and `routes.js` in the current directory without creating any default app.
48
+ Use `startproject --typescript` to generate `app.ts`, `settings.ts`, `routes.ts`, app `*.ts` files, and `tsconfig.json` instead.
49
+ It also creates `public/` and `templates/` so the default `staticDir` and `templates.dir` targets already exist.
50
+ Create any additional folders such as `logs/` yourself when needed.
126
51
 
127
- ### Deploy On Phusion Passenger
128
-
129
- AegisNode supports Passenger-style startup using the generated `loader.cjs`.
130
-
131
- Passenger setup (Apache/Nginx/Plesk/cPanel/etc.):
132
- 1. Set **Application Root** to your project folder.
133
- 2. Set **Startup File** to `loader.cjs`.
134
- 3. Install dependencies in project root (for example: `npm install --omit=dev`).
135
- 4. Set environment variables (at minimum `NODE_ENV=production`; keep `PORT` managed by Passenger).
136
- 5. Restart the Node app from your hosting panel/service.
137
-
138
- Plesk note: these map to **Application Root** and **Application Startup File** fields.
139
-
140
- HTTPS note:
141
- - If TLS is terminated by Passenger/Apache/Nginx, keep `https.enabled` off and set top-level `trustProxy` to `1` (or another exact proxy-hop/subnet value) so `req.secure`, secure cookies, and OAuth2 HTTPS checks work correctly.
142
- - Only enable `https` in `settings.js` when Node itself should serve TLS directly.
143
-
144
- How it works:
145
- - `loader.cjs` imports `app.js`.
146
- - `app.js` starts AegisNode with project root resolved from its own file location, so it works correctly under Passenger.
147
-
148
-
149
- Generated routes are auto-wired into `apps/<app>/routes.js`.
150
- `createapp` auto-detects the project root when run inside the project or from a parent folder containing exactly one AegisNode project.
151
- After `createapp user`, `routes.js` is updated with central mapping style:
152
- `route.use('/user', user);`
153
- Only apps declared in `settings.apps` are allowed to load/mount. Startup fails when routes reference an undeclared app.
154
- `--mount` accepts only safe path segments (`a-z`, `A-Z`, `0-9`, `_`, `-`, `:`).
155
-
156
- By default, new app routes are API-ready:
157
- - `GET /<mount>` list
158
- - `POST /<mount>` create
159
- - `GET /<mount>/:id` read
160
- - `PUT /<mount>/:id` update
161
- - `DELETE /<mount>/:id` delete
162
-
163
- Default flow is `route -> validator -> service -> model`.
164
- Default app tests generated by `createapp`:
165
- - `apps/<app>/tests/models.test.js`
166
- - `apps/<app>/tests/validators.test.js`
167
- - `apps/<app>/tests/services.test.js`
168
- - `apps/<app>/tests/routes.test.js`
169
-
170
- Run all project tests:
52
+ ### Install Dependencies And Run The Server
171
53
 
172
54
  ```bash
173
- npm test
55
+ npm install
56
+ aegisnode runserver
174
57
  ```
175
58
 
176
- Run project preflight checks:
59
+ If you choose to stay outside the project folder, the project-level commands also accept `--project <path>`.
60
+
61
+ ### Create Your First App
177
62
 
178
63
  ```bash
179
- aegisnode doctor
64
+ aegisnode createapp users
65
+ aegisnode generate view profile --app users
66
+ aegisnode generate route profile --app users
180
67
  ```
181
68
 
182
- `doctor` checks:
183
- - Project structure (`settings.js`, `routes.js`, app folders)
184
- - Startup entry files (`app.js`, `loader.cjs`), with production errors when `loader.cjs` is missing
185
- - App declarations vs filesystem
186
- - Security baseline (`appSecret`, csrf/headers/ddos toggles)
187
- - Auth safety checks (JWT secret, OAuth2 `allowHttp` in production)
188
- - Template directory availability
69
+ `createapp` updates `settings.apps` and the root `routes.js` or `routes.ts` mapping for you.
70
+ It also generates default app tests under `apps/<app>/tests`.
189
71
 
190
- Run app-level scaffold checks for one app:
72
+ ### Startup Mode Rules
191
73
 
192
- ```bash
193
- aegisnode doctor --app users
194
- ```
74
+ - Development (`env === 'development'`): start with `aegisnode runserver`.
75
+ - Non-development (`env !== 'development'`): start with `node loader.cjs`.
76
+ - `node app.js` and `node loader.cjs` are blocked in development mode.
77
+ - `aegisnode runserver` is blocked outside development mode.
195
78
 
196
- App-level doctor focuses on the named app:
197
- - Missing `views.js`, `models.js`, `services.js`, `validators.js`, `routes.js`, `subscribers.js`, `utils.js`
198
- - Missing generated test files under `apps/<app>/tests`
199
- - Missing `settings.apps` declaration for that app
200
- - Missing central `routes.js` import/mount when `autoMountApps` is off
79
+ ### Project Maintenance Commands
201
80
 
202
- Repair a partially missing app scaffold:
81
+ Use these after the project already exists:
203
82
 
204
83
  ```bash
84
+ aegisnode doctor
85
+ aegisnode doctor --app users
205
86
  aegisnode fix --app users
87
+ aegisnode generateloader
88
+ aegisnode updatedeps
206
89
  ```
207
90
 
208
- `fix` recreates missing default app files and tests without overwriting existing files. If the app is missing from `settings.apps` or central `routes.js`, it restores those registrations too.
91
+ What they do:
92
+ - `doctor`: checks project structure, startup entry files, app declarations, and security/auth basics.
93
+ - `doctor --app`: checks one app for missing scaffold files, tests, and registrations.
94
+ - `fix --app`: recreates missing app scaffold files without overwriting existing files.
95
+ - `generateloader`: restores `loader.cjs` and `app.js` when startup files are missing.
96
+ - `updatedeps`: rewrites package dependency ranges to the current npm `latest` versions and reinstalls.
209
97
 
210
- Regenerate project startup entry files if needed:
98
+ Run project tests with:
211
99
 
212
100
  ```bash
213
- aegisnode generateloader
101
+ npm test
214
102
  ```
215
103
 
216
- This restores `loader.cjs` and also recreates `app.js` if it is missing.
104
+ ### JavaScript vs TypeScript Projects
217
105
 
218
- Update project dependencies to the current npm `latest` dist-tag:
106
+ The project type is chosen once at `startproject` time:
107
+ - `aegisnode startproject blog` scaffolds a JavaScript project in the current directory
108
+ - `aegisnode startproject blog --typescript` scaffolds a TypeScript project in the current directory
219
109
 
220
- ```bash
221
- aegisnode updatedeps
222
- ```
110
+ After that, the rest of the CLI follows the project automatically:
111
+ - `createapp` generates `views.js` / `services.js` / `routes.js` in JavaScript projects, or `views.ts` / `services.ts` / `routes.ts` in TypeScript projects
112
+ - `generate` creates artifacts with the same extension as the project, for example `profile.view.js` or `profile.view.ts`
113
+ - `fix`, `doctor`, and `generateloader` also check and repair the matching project file type automatically
223
114
 
224
- `updatedeps` rewrites `dependencies`, `devDependencies`, `optionalDependencies`, and
225
- `peerDependencies` in the project `package.json`, then runs the detected package manager's
226
- `install`. It skips non-registry specs such as `file:`, `workspace:`, and git/http sources.
115
+ `createapp`, `fix`, `generate`, `runserver`, `generateloader`, `doctor`, and `updatedeps` are project-level commands.
116
+ Run them from the project root; do not `cd` into `apps/<app>`.
227
117
 
228
- ### Maintenance Mode
118
+ ## Core Concepts And App Structure
229
119
 
230
- Enable maintenance mode in `settings.js` to serve a maintenance route with `503 Service Unavailable`.
231
- If that route is missing or does not respond, AegisNode renders its internal maintenance fallback view:
120
+ Use this section to understand the project shape before you start adding more features. The goal here is to make it clear where code belongs and what each layer is responsible for.
232
121
 
233
- ```js
234
- export default {
235
- maintenance: {
236
- enabled: true,
237
- route: '/maintenance',
238
- excludePaths: ['/health'],
239
- retryAfter: 120,
240
- },
241
- };
242
- ```
122
+ ### Generated Project Shape
243
123
 
244
- ```js
245
- export default {
246
- register(route) {
247
- route.get('/maintenance', (req, res) => {
248
- res.render('maintenance', {
249
- title: 'Scheduled maintenance',
250
- });
251
- });
252
- },
253
- };
254
- ```
124
+ `startproject` creates the runtime entry files and base config for you in the current directory:
125
+ - JavaScript projects: `app.js`, `loader.cjs`, `.env`, `settings.js`, `routes.js`
126
+ - TypeScript projects: `app.ts`, `loader.cjs`, `.env`, `settings.ts`, `routes.ts`, `tsconfig.json`
255
127
 
256
- Notes:
257
- - `maintenance.route` is internally rewritten, so requests like `/users` can display your maintenance page without a redirect.
258
- - If `maintenance.route` is not defined, or the route does not answer, the bundled fallback view is rendered.
259
- - `excludePaths` lets selected endpoints keep running during maintenance.
260
- - `retryAfter` sets the HTTP `Retry-After` header.
261
- - `maintenance: true` uses the built-in default maintenance page.
262
- - `maintenance: '<html>...</html>'` is still accepted as a shorthand for direct custom HTML.
128
+ `createapp` then adds feature modules under `apps/<app>/`:
129
+ - `views.js` or `views.ts`
130
+ - `models.js` or `models.ts`
131
+ - `services.js` or `services.ts`
132
+ - `validators.js` or `validators.ts`
133
+ - `routes.js` or `routes.ts`
134
+ - `subscribers.js` or `subscribers.ts`
135
+ - `utils.js` or `utils.ts`
136
+ - `tests/`
137
+
138
+ Other scaffold rules to know:
139
+ - `createapp` auto-detects the project root when you run it inside the project or from a parent folder containing exactly one AegisNode project.
140
+ - New apps are registered in `settings.apps` and mounted in the root `routes.js` or `routes.ts`.
141
+ - Only apps declared in `settings.apps` are allowed to load or mount.
142
+ - `--mount` accepts only safe path segments (`a-z`, `A-Z`, `0-9`, `_`, `-`, `:`).
143
+ - New app routes are generated in an API-ready CRUD shape by default:
144
+ - `GET /<mount>`
145
+ - `POST /<mount>`
146
+ - `GET /<mount>/:id`
147
+ - `PUT /<mount>/:id`
148
+ - `DELETE /<mount>/:id`
149
+ - Default app tests generated by `createapp` are:
150
+ - JavaScript projects: `apps/<app>/tests/models.test.js`, `validators.test.js`, `services.test.js`, `routes.test.js`
151
+ - TypeScript projects: `apps/<app>/tests/models.test.ts`, `validators.test.ts`, `services.test.ts`, `routes.test.ts`
263
152
 
264
- ### Generated Settings Config
153
+ ### Generated Settings Shape
265
154
 
266
- `startproject` generates a minimal `settings.js` and runtime defaults fill the rest.
155
+ `startproject` generates a minimal `settings.js` or `settings.ts`, and runtime defaults fill the rest.
267
156
 
268
- Access environment values anywhere with `process.env`:
157
+ Access environment values directly with `process.env` in the settings file:
269
158
 
270
159
  ```js
271
160
  export default {
@@ -276,9 +165,9 @@ export default {
276
165
  };
277
166
  ```
278
167
 
279
- Injected app layers also receive `env`, so views/services/models/validators/controllers/subscribers/loaders can use `env.MY_NAME` without importing `process.env`.
168
+ Injected app layers also receive `env`, so views, services, models, validators, controllers, subscribers, and loaders can use `env.MY_NAME` without importing `process.env`.
280
169
 
281
- `settings.js` (generated shape):
170
+ Generated shape:
282
171
 
283
172
  ```js
284
173
  export default {
@@ -287,6 +176,13 @@ export default {
287
176
  host: process.env.HOST || '0.0.0.0',
288
177
  port: process.env.PORT ? Number(process.env.PORT) : 3000,
289
178
  trustProxy: false,
179
+ staticDir: 'public',
180
+ templates: {
181
+ enabled: true,
182
+ engine: 'ejs',
183
+ dir: 'templates',
184
+ base: 'base',
185
+ },
290
186
  security: {
291
187
  appSecret: process.env.APP_SECRET || '<generated-at-scaffold-time>',
292
188
  },
@@ -313,12 +209,11 @@ export default {
313
209
 
314
210
  Notes:
315
211
  - Keep `AEGIS_APPS_START/END` markers; `createapp` updates this list automatically.
316
- - `startproject` writes a local `.env` with a generated `APP_SECRET` and also embeds the same generated secret in `settings.js` as a fallback.
317
- - Add optional blocks manually only when needed: `https`, `templates`, `i18n`, `helpers`, `staticDir`, `websocket`, `uploads`, `mail`, `auth`, `api`, `swagger`, `loaders`, `environments`, `architecture`, `security.headers/ddos/csrf`.
212
+ - `startproject` writes a local `.env` with a generated `APP_SECRET` and also embeds the same generated secret in `settings.js` or `settings.ts` as a fallback.
213
+ - The scaffold already includes `staticDir: 'public'` and a default `templates` block, and it creates those directories for you.
214
+ - Add optional blocks only when you need them: `https`, `i18n`, `helpers`, `websocket`, `uploads`, `mail`, `auth`, `api`, `swagger`, `loaders`, `environments`, `architecture`, `security.headers/ddos/csrf`.
318
215
  - Any section you omit uses framework defaults from `src/runtime/config.js`.
319
216
 
320
- ## Core Concepts And App Structure
321
-
322
217
  ### App File Usage Examples
323
218
 
324
219
  Each generated app usually contains:
@@ -329,6 +224,8 @@ Each generated app usually contains:
329
224
  - `apps/<app>/subscribers.js`
330
225
  - `apps/<app>/routes.js`
331
226
 
227
+ If the project was created with `--typescript`, the same generated files use `.ts` instead of `.js`.
228
+
332
229
  Usage by file:
333
230
  - `views.js`: HTTP handlers (`req`, `res`, `next`). Default signature can be context-first: `handler({ service, validator, services, validators, ... }, req, res, next)`.
334
231
  Keep `views.js` thin: prefer only the view class and its imports. Avoid defining extra local helper/utility functions in the view file. Move reusable pure logic to `utils.js` and app workflows to `services.js`.
@@ -540,6 +437,77 @@ export default {
540
437
 
541
438
  ## Common Tasks And Feature Guides
542
439
 
440
+ Use this section once the project is already running and you need a specific feature, integration, or deployment-related behavior.
441
+
442
+ ### Reverse Proxies And Passenger
443
+
444
+ If HTTPS is terminated by Nginx, Apache, Passenger, or another reverse proxy before the Node process, set top-level `trustProxy` in `settings.js` or `settings.ts`:
445
+
446
+ ```js
447
+ export default {
448
+ trustProxy: 1,
449
+ };
450
+ ```
451
+
452
+ This is the AegisNode equivalent of `app.set('trust proxy', 1)` in raw Express. It makes `req.secure`, `req.protocol`, client IP detection, secure cookies, and HTTPS-aware auth logic behave correctly behind the proxy.
453
+
454
+ Prefer an exact value such as `1`, `'loopback'`, or a subnet string instead of `true`.
455
+
456
+ AegisNode also supports Passenger-style startup using the generated `loader.cjs`.
457
+
458
+ Passenger setup (Apache, Nginx, Plesk, cPanel, and similar hosts):
459
+ 1. Set **Application Root** to your project folder.
460
+ 2. Set **Startup File** to `loader.cjs`.
461
+ 3. Install dependencies in the project root, for example `npm install --omit=dev`.
462
+ 4. Set environment variables. At minimum, make sure the resolved app env is production and let Passenger manage `PORT`.
463
+ 5. Restart the Node app from the hosting panel or service manager.
464
+
465
+ Plesk note: these map to **Application Root** and **Application Startup File** fields.
466
+
467
+ HTTPS note:
468
+ - If TLS is terminated by Passenger, Apache, or Nginx, keep `https.enabled` off and use `trustProxy`.
469
+ - Only enable `https` in `settings.js` or `settings.ts` when Node itself should serve TLS directly.
470
+
471
+ How it works:
472
+ - `loader.cjs` imports `app.js` in JavaScript projects or `app.ts` in TypeScript projects.
473
+ - `app.js` or `app.ts` starts AegisNode with project root resolved from its own file location, so the same entry works under process managers and hosting panels.
474
+
475
+ ### Maintenance Mode
476
+
477
+ Enable maintenance mode in `settings.js` or `settings.ts` to serve a maintenance route with `503 Service Unavailable`.
478
+ If that route is missing or does not respond, AegisNode renders its internal maintenance fallback view.
479
+
480
+ ```js
481
+ export default {
482
+ maintenance: {
483
+ enabled: true,
484
+ route: '/maintenance',
485
+ excludePaths: ['/health'],
486
+ retryAfter: 120,
487
+ },
488
+ };
489
+ ```
490
+
491
+ ```js
492
+ export default {
493
+ register(route) {
494
+ route.get('/maintenance', (req, res) => {
495
+ res.render('maintenance', {
496
+ title: 'Scheduled maintenance',
497
+ });
498
+ });
499
+ },
500
+ };
501
+ ```
502
+
503
+ Notes:
504
+ - `maintenance.route` is internally rewritten, so requests like `/users` can display your maintenance page without a redirect.
505
+ - If `maintenance.route` is not defined, or the route does not answer, the bundled fallback view is rendered.
506
+ - `excludePaths` lets selected endpoints keep running during maintenance.
507
+ - `retryAfter` sets the HTTP `Retry-After` header.
508
+ - `maintenance: true` uses the built-in default maintenance page.
509
+ - `maintenance: '<html>...</html>'` is still accepted as a shorthand for direct custom HTML.
510
+
543
511
  ### File Uploads
544
512
 
545
513
  AegisNode provides built-in upload middleware on route API as `route.upload`.
@@ -880,7 +848,7 @@ export default {
880
848
  },
881
849
  security: {
882
850
  ddos: {
883
- maxRequests: 120,
851
+ maxRequests: 300,
884
852
  },
885
853
  },
886
854
  environments: {
@@ -1661,6 +1629,8 @@ Then in EJS:
1661
1629
  <!-- SETTINGS_REFERENCE_START -->
1662
1630
  ## Full Settings Reference
1663
1631
 
1632
+ Use this section as a config manual. It is intentionally reference-heavy and is easier to use after you already know which feature or runtime block you need to configure.
1633
+
1664
1634
  All fields below are supported in `settings.js`. If you omit a field, AegisNode uses the runtime default.
1665
1635
 
1666
1636
  Merge order used at startup:
@@ -1888,7 +1858,7 @@ security: {
1888
1858
  | --- | --- | --- |
1889
1859
  | `enabled` | `boolean` / `true` | Enable rate limiter. |
1890
1860
  | `windowMs` | `number` / `60000` | Rate limit window in milliseconds. |
1891
- | `maxRequests` | `number` / `120` | Max requests per window per key. |
1861
+ | `maxRequests` | `number` / `300` | Max requests per window per key. |
1892
1862
  | `message` | `string` / `'Too many requests, please try again later.'` | JSON error message text. |
1893
1863
  | `statusCode` | `number` / `429` | Response status code when limited. |
1894
1864
  | `standardHeaders` | `boolean` / `true` | Emit modern rate-limit headers. |
@@ -2176,6 +2146,8 @@ Behavior:
2176
2146
 
2177
2147
  ## Runtime Patterns And Advanced Topics
2178
2148
 
2149
+ Use this section after the basics are clear. It covers the runtime contracts that matter once you are shaping larger apps or enforcing stricter boundaries.
2150
+
2179
2151
  ### Middleware
2180
2152
 
2181
2153
  Route API supports Express-style middleware chains:
@@ -2541,7 +2513,7 @@ security: {
2541
2513
  ddos: {
2542
2514
  enabled: true,
2543
2515
  windowMs: 60000,
2544
- maxRequests: 120,
2516
+ maxRequests: 300,
2545
2517
  message: 'Too many requests, please try again later.',
2546
2518
  statusCode: 429,
2547
2519
  standardHeaders: true,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aegisnode",
3
- "version": "0.0.5",
3
+ "version": "0.1.1",
4
4
  "description": "A view-first Node.js framework for modular web apps and JSON APIs with CLI scaffolding, runtime injection, auth, uploads, i18n, mail, and WebSocket support.",
5
5
  "type": "module",
6
6
  "main": "./src/index.js",
@@ -44,17 +44,18 @@
44
44
  },
45
45
  "license": "MIT",
46
46
  "dependencies": {
47
- "ejs": "^3.1.10",
48
- "express": "^4.21.2",
49
- "express-rate-limit": "^8.3.1",
47
+ "ejs": "^5.0.2",
48
+ "express": "^5.2.1",
49
+ "express-rate-limit": "^8.5.2",
50
50
  "helmet": "^8.1.0",
51
51
  "jlive": "^0.1.2",
52
- "jsonwebtoken": "^9.0.2",
53
- "mongoose": "^8.12.1",
54
- "multer": "^2.1.0",
55
- "nodemailer": "^8.0.2",
56
- "querymesh": "^0.0.7",
57
- "socket.io": "^4.8.1",
58
- "swagger-ui-express": "^5.0.1"
52
+ "jsonwebtoken": "^9.0.3",
53
+ "mongoose": "^9.6.2",
54
+ "multer": "^2.1.1",
55
+ "nodemailer": "^8.0.7",
56
+ "querymesh": "^0.1.0",
57
+ "socket.io": "^4.8.3",
58
+ "swagger-ui-express": "^5.0.1",
59
+ "tsx": "^4.22.0"
59
60
  }
60
61
  }