@adaptivestone/framework 5.0.0-rc.6 → 5.0.0-rc.8

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/CHANGELOG.md ADDED
@@ -0,0 +1,822 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [5.0.0-rc.8] - 2026-06-15
9
+
10
+ - **[FIX]** Instance methods are now callable on the hydrated document without
11
+ `this`-binding casts. A method whose body needs a narrower shape can declare an
12
+ explicit `this: <bridge>` (a populated ref, a non-null plugin-reshaped field,
13
+ reassignable sibling methods); that bridge was carried verbatim onto the
14
+ document type, so a direct `doc.method(...)` call failed the this-context check
15
+ (`TS2684`) — the framework-computed hydrated doc is deliberately not assignable
16
+ to the narrower bridge — and every call site needed a
17
+ `(schema.methods.x as …).call(doc, …)` cast. The caller-facing projection now
18
+ strips the authored `this` (a method accessed on its own document always has
19
+ the right `this` at runtime), while method bodies stay type-checked against
20
+ their declared `this`. Purely a type change, no runtime impact; a `tsc`-gate
21
+ test pins it.
22
+
23
+ - **[FIX]** A virtual now resolves to its getter's return type on the document
24
+ (e.g. `doc.fullName` is `string`) instead of the leaked raw definition
25
+ (`string & { get(): string; options: … }`). The virtuals slot fed to
26
+ Mongoose's inner document type was the raw `{ get, set, options }` object; it
27
+ is now the resolved `VirtualType<…>`, matching the override slot. Type-only.
28
+
29
+ - **[FIX]** `createdAt` / `updatedAt` are now typed as a non-null `Date` on the
30
+ hydrated document instead of `Date | null | undefined`. Mongoose always sets
31
+ the timestamps, so the nullable type only forced a needless guard at every
32
+ read. Type-only change.
33
+
34
+ - **[FIX]** Cleaner `TsTypeOverride` typing (rc.7 feature). The override mapping
35
+ no longer recurses into built-in instances (`ObjectId` refs, `Date`, `Map`) —
36
+ they showed as `ApplyTsOverrides<ObjectId, …>` in hovers though the recursion
37
+ was a no-op — and a marker-free schema (the common case) now skips the mapping
38
+ entirely, so its document type is the plain Mongoose inference with no wrapper
39
+ in hovers and no extra compile work. Type-only; no change to which types
40
+ resolve, only how cleanly.
41
+
42
+ ## [5.0.0-rc.7] - 2026-06-15
43
+
44
+ - **[NEW]** Per-field compile-time type overrides for plugin-reshaped fields. A
45
+ schema field intersected with the new `TsTypeOverride<T>` marker is typed as
46
+ `T` on `getModel(...).findOne()` results and method `this`, instead of the type
47
+ Mongoose infers from `type:` — so a field a runtime plugin reshapes
48
+ (`mongoose-intl`, encrypted fields, custom getters) keeps its static and
49
+ runtime types in sync, removing the casts that previously bridged the gap. The
50
+ marker is a phantom (`__tsType`, never set at runtime); applied by a deep
51
+ mapped type (`ApplyTsOverrides`) that recurses into nested objects and
52
+ subdocument arrays. Opt-in and a strict **no-op** for any field without the
53
+ marker, so existing models are unchanged.
54
+
55
+ ## [5.0.0-rc.6] - 2026-06-14
56
+
57
+ - **[FIX]** The `User` auth helpers are now reusable on a **customized** `User`
58
+ model without `this`-binding casts. The statics (`getUserByEmailAndPassword`,
59
+ `getUserBy{Token,Email,VerificationToken,PasswordRecoveryToken}`) and instance
60
+ methods (`generateToken`, `getPublic`, `send{Verification,PasswordRecovery}Email`)
61
+ were typed against the framework's own schema (`this: UserModelLite`), so on a
62
+ project model with a different shape every call site hit `TS2684` and needed a
63
+ cast. They're now typed against small structural contracts (`UserAuthDoc` /
64
+ `UserAuthInstance` / `UserAuthModel`, all newly exported) describing only the
65
+ fields each helper touches — the framework's `User` and a project's replacement
66
+ both satisfy them, and return types stay precise. This makes the supported
67
+ customization paths cast-free: `extends User` to **add** fields, or compose
68
+ (`extends BaseModel` + spread `User.modelStatics` / `modelInstanceMethods`) to
69
+ **reshape** them (an i18n `name`, a singular `role`, …) — a field-type
70
+ *replacement* can't go through `extends` (static-getter covariance, `TS2417`).
71
+ Both paths are documented on the `User` class. A `tsc`-gate test pins them.
72
+
73
+ - **[FIX]** Config-type codegen no longer drops env-only keys. A config value
74
+ read straight from the environment with no default (`saltSecret:
75
+ process.env.AUTH_SALT`) is `undefined` at gen time, so the value-based pass
76
+ omitted it from `getConfig('…')`'s type and every read needed an `as` cast.
77
+ Codegen now reads the config **source** (via `oxc-parser`, no value import) and
78
+ types a bare `process.env.X` as `string | undefined` (and `process.env.X!` as
79
+ `string`) — from the source, so the result is the same whether or not the var
80
+ happened to be set during codegen (deterministic output, no `--check` drift).
81
+ Keys without an env read (literals, `process.env.X || default`) are still typed
82
+ from their value as before. Secrets are never serialized (types only). Nested
83
+ keys and `NODE_ENV`-specific config files are handled.
84
+
85
+ ## [5.0.0-rc.5] - 2026-06-14
86
+
87
+ - **[FIX]** Route-type codegen extends the rc.4 untyped-`.js` degradation to
88
+ middleware in the `appInfo` provides chain. A controller guarded by an untyped
89
+ `.js` middleware (no sibling `.d.ts`) produced a gen file that did `import type
90
+ Mw from './Mw.js'` to build its `UnionAppInfoProvides<…>` chain — a `TS7016` in
91
+ a strict consumer build with no `allowJs`. Such a middleware is now dropped
92
+ from both the import and the chain (it contributes nothing to `appInfo`)
93
+ instead of breaking the typecheck. Typed middleware — `.ts`, `.js` with a
94
+ sibling `.d.ts`, or the framework's own (bare specifiers ship declarations) —
95
+ keep their precise `appInfo` contributions. Same incremental `.js` → `.ts`
96
+ migration goal as rc.4, now covering middleware as well as controllers.
97
+
98
+ ## [5.0.0-rc.4] - 2026-06-14
99
+
100
+ - **[FIX]** Route-type codegen no longer emits an untyped self-import for `.js`
101
+ controllers. A schema-bearing controller still written in JavaScript with no
102
+ sibling `.d.ts` produced a gen file that did `import type Ctrl from
103
+ './Ctrl.js'`, which fails with `TS7016` ("could not find a declaration file")
104
+ in a `strict` consumer build without `allowJs` — turning `rc.3`'s
105
+ now-succeeding `npm run gen` into a red typecheck. Such controllers now degrade
106
+ gracefully: the gen file skips the self-import and their inline request/query
107
+ schemas fall back to the base `Record<string, unknown>`. `.ts` controllers (and
108
+ `.js` with a sibling `.d.ts`) keep precise `InferOutput` types. Unblocks
109
+ incremental `.js` → `.ts` migration.
110
+
111
+ ## [5.0.0-rc.3] - 2026-06-13
112
+
113
+ - **[CHANGE]** Route-type codegen now skips controllers it can't statically
114
+ analyze instead of aborting the whole run. A controller whose `routes` /
115
+ `middleware` / `getHttpPath` uses a loop, conditional, computed value, or
116
+ `super` (e.g. one that extends another controller and merges `super.routes`) is
117
+ skipped with a warning; types are still generated for every other controller,
118
+ and the skipped one works at runtime (only its generated request types are
119
+ omitted). Previously a single such controller failed `npm run gen` for the
120
+ entire project.
121
+
122
+ ## [5.0.0-rc.2] - 2026-06-13
123
+
124
+ Patch over `rc.1`, fixing a regression for consumers that extend the framework.
125
+
126
+ - **[FIX]** Restored `./config/*` to the package `exports` map (it was dropped in
127
+ `rc.1`). Extending a framework default config — `import http from
128
+ '@adaptivestone/framework/config/http.js'`, then re-exporting an edited copy
129
+ from your own `src/config/http.ts` — threw `ERR_PACKAGE_PATH_NOT_EXPORTED` and
130
+ broke app boot. `config/*` is the intended Tier-2 extension surface and is
131
+ importable again.
132
+
133
+ ## [5.0.0-rc.1] - 2026-06-13
134
+
135
+ This is a big release that contains a lot of new features and breaking changes.
136
+ Main feature of that release is full TypeScript support including mongoose models.
137
+
138
+ ### New Features
139
+
140
+ - **[NEW]** Full TypeScript support, including Mongoose models.
141
+ - **[NEW]** New model type: `BaseModel`, simplifying work with TypeScript and based on statics.
142
+ - **[NEW]** `AppInstance` helper to access the app instance from anywhere without passing it.
143
+ - **[NEW]** `GenerateTypes` command added.
144
+ - **[NEW]** `Lock` model for working with locks via MongoDB.
145
+ - **[NEW]** `FrameworkFolder` folder added to the app for module usage.
146
+ - **[NEW]** Ability to skip Mongo model initialization in CLI environments.
147
+ - **[NEW]** Mongo connections in CLI now have unique names, including the command name.
148
+ - **[NEW]** Graceful shutdown on `SIGTERM`/`SIGINT`. `Server.startServer()` now installs signal handlers (once per process, skipped under vitest) that stop accepting connections, drain in-flight requests (`httpServer.shutdown()` awaits `close()` and drops idle keep-alive sockets), then tear down mongo/redis/logger via the `shutdown` event — with a single 10s force-exit safety net (the only force-exit timer; the previous per-`shutdown`-event 5s timer in the `Server` constructor is removed). A second `Ctrl-C` falls through to Node's default immediate termination.
149
+ - **[NEW]** `GenerateRandomBytes` command added.
150
+ - **[NEW]** `IpDetector` middleware for detecting proxies and `X-Forwarded-For` headers.
151
+ - **[NEW]** Test helpers getTestServerURL and serverInstance.
152
+ - **[NEW]** Rate limiter middleware - add consumeResult function to allow user middleware as a regular rate limiter
153
+ - **[NEW]** Ip detector middleware - add getIpAdressFromIncomingMessage function to allow user middleware as a detector of id adresses without middleware
154
+ - **[NEW]** Introduce i18nService (ability to user i18n not only inside middleware)
155
+ - **[NEW]** [Standard Schema](https://standardschema.dev/) validation. Yup ≥1.7, Zod, Valibot, ArkType supported.
156
+ - **[NEW]** Pluggable `ValidatorDriver` + `ValidateService.register(driver)` for custom validators.
157
+ - **[NEW]** `StandardSchemaV1.InferOutput<typeof schema>` for compile-time handler types.
158
+ - **[NEW]** Framework-owned `ValidationError` with structured `.issues`. Wire-compatible.
159
+ - **[NEW]** Tree-based `RouteRegistry` replaces Express's hidden router internally. Lives on `app.httpServer.routeRegistry`. One global tree, walkable by codegen / OpenAPI / MCP emitters. The Express adapter mounts once (`app.express.use(adapter)`); path matching, parameter extraction, method dispatch, and middleware ordering all live in framework code now. 405 with `Allow` header, 400 on malformed paths, HEAD → GET fallback. Per-segment URL decoding (Spring's `PathPatternParser` model).
160
+ - **[NEW]** `app.controllerManager.registerController(ControllerClass, prefix?)` for explicit/programmatic controller registration. Auto-loading uses the same entry point internally. Register late via `Server.startServer`'s `callbackBefore404` hook so routes mount before the 404 handler.
161
+ - **[NEW]** Per-controller route type generation: `npm run gen` (alias for `npm run cli generatetypes`) emits `<File>.routes.gen.ts` next to each controller plus `genTypes.d.ts` at the project root. Handler signatures use `import type { PostLoginRequest } from './Auth.routes.gen.ts'` instead of hand-written `req: FrameworkRequest & { appInfo: { request: { ... } } }` intersections. Codegen walks `RouteRegistry.flatten()` so resolved middleware chains exactly match what the runtime executes (no parallel matcher). Gen files are gitignored — recommend `**/*.routes.gen.ts` in your `.gitignore` and `npm run gen && tsc --noEmit` in your `check:types` script.
162
+ - **[NEW]** Type contracts in `services/http/types`: `BaseRequestContext`, `BaseAppInfo`, `AppInfoExtensions` (module-augmentation point for app-wide globals), `ProvidesOf<T>`, `UnionAppInfoProvides<MWs>`. Codegen output composes these into per-handler `<MethodName>Request` aliases.
163
+ - **[NEW]** `static get provides()` convention on middlewares — declares what the middleware adds to `req.appInfo` (e.g., `GetUserByToken.provides` returns `{ user?: InstanceType<TUser> }`). Codegen reads this; runtime ignores it. Type-only phantom.
164
+ - **[NEW]** Boot-time route tree log at `verbose` log level. After all controllers register, the framework prints the full route registry: path structure, per-node attached middlewares (with inherited chain marked separately as `pmw:`), per-method handlers with their absolute path, schema flags (`[body]` / `[query]`), and route-level middleware (`[mw: ...]`). HTTP verbs are color-coded (blue GET, green POST, yellow PUT/PATCH, red DELETE, gray OPTIONS); `:param` and `*splat` segments stand out in magenta. ANSI codes are emitted unconditionally — looks right in TTY consoles, raw codes appear in file/Sentry transports for the one-time boot output.
165
+ - **[NEW]** `Server#getLogger()` registers a `shutdown` listener that drains the winston logger (`logger.close()`). Fixes 5s exit stall in CLI commands (`generatetypes`, etc.) caused by winston transport sockets keeping the event loop alive past the shutdown signal. The force-exit safety timer (zombie-prevention) now lives in the graceful-shutdown signal handler — see the SIGTERM/SIGINT entry above.
166
+ - **[NEW]** Boot-time warnings on misconfigured routes / middleware Maps. Framework now logs at `warn` level when it sees: unknown verb in the `routes` getter (anything other than `get/post/put/patch/delete/head/options`), a route object missing a callable `handler` field, a non-string key in the middleware `Map`, or an unknown method prefix on a `Map` key (e.g., a typo like `'PATC/login'`). Previously these silently produced 404s at request time.
167
+ - **[NEW]** Codegen emits typed `params` for route path segments. `:name` segments and `{*name}` splats are extracted from the path string and emitted as `& { params: { name: string } }` on the generated `<Method>Request` alias. Splats capture multiple segments joined with `/` — typed as `string` (not `string[]`), matching the matcher's behavior. Removes the need for hand-rolled `& { params: { id: string } }` intersections on every handler with a `:param` route.
168
+ - **[NEW]** Codegen emits `appInfo.query: StandardSchemaV1.InferOutput<...>` from route-level `query:` schemas. Mirrors how `request:` schemas are already handled — declares it on the route, handlers read typed `req.appInfo.query.X`.
169
+ - **[NEW]** Codegen deduplicates identical union branches when one handler serves multiple routes with the same resolved chain + path params + schemas. Prevents `Foo = (X & {...}) | (X & {...})` output in `.routes.gen.ts`.
170
+ - **[NEW]** `Pagination` middleware declares `static get provides()` returning `PaginationMiddlewareAppInfo['appInfo']`. Routes with `Pagination` in their chain get `req.appInfo.pagination: { page, limit, skip }` typed automatically.
171
+ - **[NEW]** Middleware request/query schemas can be declared **statically** — `static get relatedRequestParameters()` / `static get relatedQueryParameters()`. The framework reads them without instantiating the middleware (avoids constructor side effects during route setup / codegen). Framework middlewares (`Pagination`) migrated.
172
+ - **[DEPRECATED]** The **instance** form of those getters (`get relatedRequestParameters()` / `relatedQueryParameters` / `relatedReqParameters`) is deprecated and **will be removed in v6** — migrate to the static form. It still works (the framework detects the override, instantiates as a fallback, and emits a one-per-class `DeprecationWarning`, code `ASF_DEP_MW_INSTANCE_SCHEMA`).
173
+ - **[FIX]** `setupVitest.ts` no longer imports framework-internal fixtures. The test-fixture controller (`SomeController`) is now registered inside its own test file via late `controllerManager.registerController()` (the adapter reads the registry live, so registration after `startServer` works). Consumer projects can use `@adaptivestone/framework/tests/setupVitest.js` without `Cannot find module './fixtures/...'` errors. `frameworkVitestSetup.*` is now `.npmignore`'d as framework-only.
174
+ - **[FIX]** Codegen now walks the `extends` chain when resolving middleware import paths. A child controller that inherits `static get middleware()` from its parent class no longer has those middlewares filtered out of its generated chain — codegen scans the parent's source file for the import line and emits the right `import type` in the child's `.routes.gen.ts`. Bare-package ancestors (e.g. a consumer extending the framework's `AbstractController` via `@adaptivestone/framework/modules/...`) are resolved too (since beta.55): codegen reads the installed package file through the importing file's module resolution (honoring the package `exports` map) and rewrites the ancestor's relative middleware imports into bare specifiers the consumer's gen file can resolve — the public subpath tree mirrors `src/`.
175
+ - **[FIX]** `getConfig()` types in `genTypes.d.ts` are emitted as inline **value-shape** types — each config value's structure rendered with value *types* (`string`, `number`), never the literal values and never an `import()` reference. This avoids baking secret values into the generated file and avoids over-narrow literal types, while staying robust: the type is fully inline (no module resolution, so it can't silently degrade to `any` under stricter or preview TypeScript toolchains), and arrays stay **tuples** so per-element patterns like `Object.values(config.list[0])` keep precise types. (Replaces an earlier `typeof import('./config/foo.ts').default` reference form, which inferred array elements as a union with `?: undefined` keys — breaking `Object.values()` — and could resolve to `any` on some compilers.)
176
+
177
+ ### Breaking changes (please read carefully)
178
+
179
+ - **[BREAKING]** No more global variables for testing and default user will not be created by default
180
+ - **[BREAKING]** All models now should be extended from `BaseModel`. This is a potential breaking change specially for `User` model.
181
+ - **[BREAKING]** Remove jest support for testing.
182
+ - **[BREAKING]** Move email module to separate package `@adaptivestone/framework-module-email`. Please use it if you want to send emails.
183
+ - **[BREAKING]** Remove `VIEWS` folders at all. Should not affect any user as this was not used internally.
184
+ - **[BREAKING]** Removed `noidemailer-sendmail-transport`. Not needed anymore and not recommended to use as well.
185
+ - **[BREAKING]** Remove `minimist` CLI parsing and replace it by `commandArguments` parser.
186
+ - **[BREAKING]** `vitest` v3 <https://vitest.dev/guide/migration.html>.
187
+ - **[BREAKING]** `i18next` v24 <https://www.i18next.com/misc/migration-guide#v23.x.x-to-v24.0.0>.
188
+ - **[BREAKING]** Possible breaking. Framework start using express 5 instead of express 4. Please follow express migration guide too <https://expressjs.com/en/guide/migrating-5.html>.
189
+ - **[BREAKING]** As part of express 5 migration `_` in rotes (middlewares) should have perameter. please replace `_` to `*splat`.
190
+ - **[BREAKING]** Default auth response changed to be unified. `{token, user}` => `{data:{token, user}}`.
191
+ - **[BREAKING]** `RateLimiter` now need to have `IpDetector` middleware before.
192
+ - **[BREAKING]** Removing `staticFiles` middleware as it not used in projects anymore. Docs with nginx config will be provided.
193
+ - **[BREAKING]** Remove default `AUTH_SALT`. It should be provided on a app level now.
194
+ - **[BREAKING]** Auth tokens & password hashing hardened (security). Session, password-recovery, and email-verification tokens are now random (`randomBytes`) and stored as SHA-256 hashes with an enforced expiry filter; passwords use a per-user random salt + a versioned scrypt scheme (`v2:scrypt:…`) with `AUTH_SALT` as a pepper. **On upgrade, all existing sessions, password-recovery links, and email-verification links become invalid** — stored plaintext tokens no longer match the hashed lookups, so users must log in again / request new links. Passwords migrate silently: a legacy hash is re-hashed to the new scheme on the user's next successful login (no batch migration is possible — the plaintext only exists at login). The login/recovery wire format is unchanged.
195
+ - **[BREAKING]** Minimum Node version is **24.0.0** (enforced via `engines`). The framework runs your TypeScript sources directly, with no build step, which relies on Node's native type stripping.
196
+ - **[BREAKING]** ESM only. No more commonJS. That help to fix a lot of bugs with tests and provides better development expirience.
197
+ - **[BREAKING]** Mongoose v8. <https://mongoosejs.com/docs/migrating_to_8.html>.
198
+ - **[BREAKING]** Mongoose v9. <https://mongoosejs.com/docs/migrating_to_9.html>.
199
+ - **[BREAKING]** Vitest v4 <https://vitest.dev/guide/migration.html#vitest-4>
200
+ - **[BREAKING]** `@redis/client` v6. Now defaults to the RESP3 protocol (was RESP2) and requires a Redis ≥6 server; pass `createClient({ RESP: 2 })` to keep v5 wire behavior. Also adds a default 5s command timeout. <https://github.com/redis/node-redis/blob/master/docs/v5-to-v6.md>
201
+ - **[BREAKING]** Yup is no longer bundled — it's now an **optional peer dependency** (`^1.7.0`). The framework runtime is validator-agnostic (Standard Schema) and fully decoupled from yup; built-in controllers use the zero-dependency `defineSchema` helper. Bring your own validator only if you want one — yup (≥1.7, which implements Standard Schema natively), zod, valibot, or arktype. If your own schemas use yup, add it to your `dependencies`.
202
+ - **[BREAKING]** Legacy `{validate, cast}` plain-object validators removed. Wrap as Standard Schema (~10 lines).
203
+ - **[BREAKING]** Yup `req:` context inside `.test()` / `.when()` removed. Use `this.parent` or move logic to handler.
204
+ - **[BREAKING]** Internal driver classes (`AbstractValidator`, `YupValidator`, `CustomValidator`) removed.
205
+ - **[BREAKING]** `ValidateService` surface trimmed to `{constructor, validate, resolve, register}`. Helpers like `validateReqData` removed.
206
+ - **[BREAKING]** `AbstractMiddleware.relatedQueryParameters` / `relatedRequestParameters` defaults changed from `yup.object().shape({})` to `null`. Override with any Standard Schema-conformant schema.
207
+ - **[BREAKING]** `BaseAppInfo.i18n` is now required (was optional in `FrameworkRequest`). Reflects runtime reality: `I18nMiddleware` is part of `HttpServer`'s default chain. If you removed I18n from your global chain, augment `BaseAppInfo` to relax the field.
208
+ - **[BREAKING]** OpenAPI / documentation generation removed: `framework documentation` and `framework getOpenApiJson` CLI commands, `DocumentationGenerator`, and `app.documentation` field deleted. Output was already partial after Standard Schema migration. Will return in later with per-vendor `toJsonSchema` support.
209
+ - **[BREAKING]** Path-pattern syntax narrowed. The new tree-based router supports literal segments, `:name` params (exactly one segment), and `{*name}` splats (zero or more segments to end of path). **Express 5's optional-param `{:name}` and inline regex are NOT supported.** If you had routes like `/fullpath/:paramOne/{:paramTwo}`, split into two explicit routes (`/fullpath/:paramOne` + `/fullpath/:paramOne/:paramTwo`) or restructure. Specificity is structural (static > param > splat); URL decoding is per-segment.
210
+ - **[BREAKING]** `AbstractController` constructor third argument `isExpressMergeParams` removed. The old default Express-router behavior of stripping parent params is gone — all matched params (across the full path, including the controller prefix) are available on `req.params`. If you relied on the merge-params toggle, no action needed in most cases; if you specifically depended on the strip behavior, restructure your handler to filter `req.params` keys.
211
+ - **[BREAKING]** The built-in `Home` controller no longer runs `GetUserByToken` globally. It previously declared `'/{*splat}': [GetUserByToken]`, and since `Home` mounts at `/` that landed on the route-tree root and ran on **every request**. `Home` now adds no middleware. Controllers still parse the token via their own/inherited `[GetUserByToken, Auth]`; only routes that don't include it themselves (e.g. ad-hoc `registerRoute` endpoints) lose the implicit `req.appInfo.user`. See the beta.55 note below.
212
+
213
+ ### Bug Fixes
214
+
215
+ - **[FIX]** Codegen's `extends`-walk now follows the *exported* controller's parent, not the first `class … extends` in the file. A helper or secondary class declared before the controller (e.g. `class Helper extends X` … `export default class Ctrl extends Y`) used to hijack the walk, so middleware inherited from the controller's real parent was silently dropped from the generated `req.appInfo` types. The parent is now resolved from the `export default`/`export class` declaration (falling back to the last `class … extends`).
216
+ - **[FIX]** Codegen's import scanner now parses semicolon-less (ASI) imports. Statements were terminated only at `;` or end-of-file, so under a no-semicolon style (Prettier `semi: false`, StandardJS) consecutive `import` lines collapsed into one and all but the first binding were dropped — quietly losing those middlewares' type narrowing. A statement now also ends at the newline after its specifier string closes; `;`-terminated, multi-line `{ … }`, and side-effect (`import './x'`) imports are unaffected.
217
+ - **[FIX]** The `extends`-walk no longer mistakes a **regex literal** for a class declaration. `parseExtendsParent` scanned the whole file, so a regex such as `/export default class Z extends Wrong/` lexically before the real controller hijacked the walk and dropped the controller's inherited middleware. Regex-literal bodies are now blanked (alongside comments and strings) before the scan.
218
+ - **[FIX]** A controller whose exported class has **no `extends`** (`export default class Ctrl {}`) no longer inherits a helper class's parent. The scan used to fall through to the last `class … extends` in the file — a sibling helper's — and merge its middleware; it now returns "no parent" when the exported class declares none.
219
+ - **[FIX]** A malformed import specifier with a **trailing backslash** (`import X from './a\'`) no longer breaks the generated file or swallows the imports that follow it. Specifiers containing a backslash or a Unicode line separator (U+2028 / U+2029) are now rejected, and the scanner no longer honors `\`-escapes inside a specifier (a real one has none), so the string closes at its quote.
220
+ - **[FIX]** Multi-line import-attributes clauses (`import x from './x.json'` then `with { type: 'json' }` on the next line) no longer end the import prologue early and drop every later import; the clause is folded into the statement.
221
+ - **[FIX]** `req.appInfo.user` is typed as the hydrated **document**, not the Mongoose model class. Codegen's `AppModels` augmentation emitted `User: GetModelTypeFromClass<…>` (the model class) where the runtime assigns `InstanceType<…>`, so after `npm run gen` `user.id` / `user.email` stopped type-checking. The augmentation now wraps the model in `InstanceType<GetModelTypeFromClass<…>>` (while `getModel('User')` correctly keeps returning the class). Verified with a `tsc` probe.
222
+ - **[FIX]** Codegen now skips colocated `.d.ts` / `.gen.d.ts` files when discovering controllers, matching the runtime loader. A capitalized declaration file next to your controllers passed the `.ts`-only filter, reached the AST extractor, parsed as "no controller class," and — since non-analyzable controllers are a hard error — made `npm run gen` throw, blocking route-type generation for *every* controller.
223
+ - **[FIX]** A non-literal `static get middleware()` in an **ancestor** controller is no longer silently dropped. The `extends`-walk treated "this ancestor builds its middleware Map dynamically" the same as "this ancestor declares no middleware," so it walked past and emitted the child with an empty middleware chain (and `req.appInfo` missing those fields) with no error. It now stops and throws, naming the controller — symmetric with the same getter on the controller itself.
224
+ - **[FIX]** A route entry with no statically identifiable handler — object shorthand (`{ handler }`), an optional-chained handler (`this?.x`), or a spread (`{ ...defaults, handler }`) — now throws instead of silently dropping the route from the generated types.
225
+ - **[FIX]** Codegen's `extends`-walk now also follows the `export { Ctrl as default }` form (including the ES2022 string-literal name `export { Ctrl as "default" }`). Previously only `export default …` was recognized; the `as default` re-export fell through to "last class wins," so a trailing helper class could hijack the walk (wrong `extends` / routes).
226
+ - **[FIX]** Codegen now discovers **`.js` controllers** like the runtime loader does. A plain-JavaScript controller used to be invisible to `npm run gen`: it got no `.routes.gen.ts`, and — since codegen computes cross-controller middleware bleed from all controllers at once — its root-scoped middleware was missing from *other* controllers' generated `req.appInfo` types. `.js` sources are parsed by the same AST front-end (`.gen.js` / `.test.js` are skipped, mirroring the loader), and the gen file's self-import keeps the controller's real extension.
227
+ - **[FIX]** `RateLimiter` no longer turns a **backing-store outage into a 429 for everyone**. `rate-limiter-flexible` rejects with a `RateLimiterRes` when the limit is hit but with an `Error` when the store (Redis/Mongo) fails; the middleware treated both as "limit hit" and returned `429 Retry-After: 1` on every request during an outage (and logged "Too many requests", misdirecting investigators). Store errors are now distinguished (`instanceof Error`) and **fail open** with an error-level log; the redis/mongo limiters also get a `RateLimiterMemory` **insurance limiter** so brute-force protection degrades to per-process memory instead of vanishing.
228
+ - **[FIX]** `Cache.getSetValue` no longer **deadlocks a key forever** when Redis fails mid-request. The request-coalescing map entry was only cleared on the happy path, so a Redis error after the entry was stored left a permanently-pending promise that every future call for that key awaited — surviving Redis recovery. The whole body is now wrapped so the entry always settles and clears (`finally`); the in-flight promise gets a no-op `.catch` (no `unhandledRejection` when a single caller's `onNotFound` throws), the cache write is best-effort (logged, never fails the request), and an `undefined` result skips the write instead of crashing. A cache **read/connect failure now degrades to computing the value via `onNotFound`** (cache outage ≠ request outage — slow, not broken) rather than throwing; only `onNotFound`'s own errors propagate.
229
+ - **[FIX]** A failed HTTP `listen()` (`EADDRINUSE` / `EACCES`) no longer leaves a **silent zombie process**. The server socket had no `'error'` listener, so a bind failure surfaced as an `uncaughtException` that the global handler only logged — the process kept running, healthy-looking to a supervisor that doesn't probe the port, while serving nothing. The bind error is now caught and the process exits non-zero so a supervisor restarts it with backoff.
230
+ - **[FIX]** Custom (non-console, non-sentry) winston transports now actually load. The constructor check in `#createLogger` was **inverted** — a transport whose default export *is* the constructor (every normally-published winston transport) failed the guard, got a "not a constructor" log, and was silently dropped; only an unusual CJS double-wrapped shape happened to load. The export is now unwrapped (default export, then the CJS-interop `default.default`) and validated **once** before `new`, and the dynamic `import()` has a `.catch` so a typo'd module name logs a friendly error instead of an unhandled rejection.
231
+ - **[FIX]** Boolean environment variables are no longer coerced backwards. `config/log.ts` read `process.env.LOGGER_SENTRY_ENABLE || false` and `… || true`, but env values are strings — `"false"`/`"0"` are **truthy**, so `LOGGER_SENTRY_ENABLE=false` *enabled* Sentry and `LOGGER_CONSOLE_ENABLE` could never disable the console. A new `envBool(name, default)` helper (`src/helpers/env.ts`) parses them explicitly (only `"true"`/`"1"` are `true`; unset/empty falls back to the default), and both log flags now use it.
232
+ - **[FIX]** The migration runner no longer silently skips **branch-merged migrations**. Pending files were chosen by comparing each filename timestamp against the timestamp of the *most recently applied* record — so a migration merged in later but stamped earlier than one already deployed was filtered out and **never ran** (no error, no log). Pending is now a **set difference** against the applied filenames (`distinct('migrationFile')`), so any unapplied file runs regardless of timestamp ordering, executed in filename order (run-then-record preserved). The run is also wrapped in the `Lock` model (`acquireLock('migrations')`) so two simultaneous deploys can't run migrations twice; a run that can't take the lock warns and returns `false`.
233
+ - **[FIX]** `Lock` model correctness. (1) `acquireLock` **steals an expired lock atomically** — `findOneAndUpdate({ _id, expiredAt: { $lt: now } }, …, { upsert: true })` instead of `create`, so a crashed holder's lock is reclaimable immediately rather than after Mongo's TTL-reaper lag (up to ~60s); the unique-`_id` upsert race still yields exactly one winner under contention. (2) `waitForUnlock` registers its change stream **before** re-checking existence (closing a missed-delete window where the promise could hang forever), adds an `'error'` handler (an unhandled stream error — e.g. on a non-replica-set Mongo — would otherwise crash the process), and accepts an optional `timeoutMs`. Locks remain **advisory** — no ownership token, `releaseLock` is unconditional; release only from the flow that acquired it — now documented on the statics.
234
+ - **[FIX]** `RequestParser` (the global multipart/urlencoded/json body parser) now bounds and cleans up file uploads, and normalizes field shapes. **(1) Limits:** it ran on every request with formidable's defaults (~200 MB/file, no total/count cap), so any unauthenticated client could spool large bodies to any path. Conservative limits now come from `config.http.requestParser` (`maxFileSize` 20 MB, `maxTotalFileSize` 50 MB, `maxFiles` 10, `maxFields` 1000, `maxFieldsSize` 2 MB; per-mount params override), and limit-exceeded errors return **413** instead of 400. **(2) Temp-file cleanup:** spooled files were **never deleted** (disk exhaustion over time). Every file formidable opens is now unlinked when the response finishes (`finish`) or aborts (`close`) — a handler that wants to keep an upload must move/copy it before responding. **(3) Field shapes:** multipart/urlencoded fields arrive as arrays while json fields are scalars; a single-value field is now collapsed to a scalar (json untouched, repeated keys stay arrays), fixing consumers like `GetUserByToken` that did `token.replace(...)` and threw a 500 on a urlencoded token.
235
+ - **[DOCS]** The per-route `bodyParsing` option now documents that **only `'parsed'` takes effect** — `'raw'` and `'none'` are reserved for v5.1 and currently do nothing (the parser is mounted globally, so `req.rawBody` is never set and the stream is always consumed). The matcher plumbing for the mode ships in v5; the implementation (parser registry + `req.rawBody`, enabling webhook signature verification) is planned for v5.1. Previously the type/JSDoc advertised `'raw'`/`'none'` as working.
236
+ - **[BREAKING]** **[SECURITY]** `POST /auth/send-recovery-email` and `POST /auth/send-verification` no longer leak account existence. They returned **400** (`auth.errorUExist`) for an unknown email and **200** for a known one — a clean unauthenticated oracle for "does this address have an account." Both now return an identical **200** regardless (the work happens only for a real account), with a generic message (`auth.recoveryEmailSent` / `auth.verificationEmailSent`, added to `en`/`ru`). The email dispatch is **fire-and-forget** (errors logged), so the known-email path doesn't block on token generation + SMTP — closing the response-latency timing oracle too. **Wire change:** frontends that branched on the old 400 must update — treat 200 as "if the account exists, an email was sent." (`register` still reports duplicate email/nickname — registration inherently confirms existence — and stays rate-limited via the controller's `RateLimiter`.)
237
+ - **[SECURITY]** Stop writing live credentials to logs. `GetUserByToken` logged the raw body token **and** the full `Authorization` header at `verbose`; `Auth.ts` logged the **entire user document** (password hash + all session/recovery/verification tokens) at `debug` during verify/recovery; `CreateUser` logged `JSON.stringify(user)` at `info`. With Sentry wired or debug/verbose enabled, those reached log storage / a third party. All now log identifiers only — token/header **presence** (not value), and `user.id` / `email` instead of the document.
238
+ - **[NEW]** **[SECURITY]** Standard security response headers, **on by default**, applied to every response path (routes, 404, 405, errors — mounted globally before the adapter). `config.http.securityHeaders` ships `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, and `Referrer-Policy: no-referrer`. `Strict-Transport-Security` is in the config but **off by default** (sending HSTS while also serving plain HTTP in dev causes browser lock-in — set `max-age=…; includeSubDomains` when always behind TLS). Set any header value to `null` to omit it, or `enabled: false` to turn the whole set off. No `helmet` dependency. `x-powered-by` remains disabled.
239
+ - **[SECURITY]** CORS config hardening (docs + boot warning, no behavior change). `config.http.corsDomains` no longer recommends `[/./]` (which reflects **every** origin); the comment now points to explicit origin strings and **anchored** regex examples — an unanchored `/example\.com/` also matches `evil-example.com` and `example.com.attacker.io`. The `Cors` middleware logs a boot-time warning for any regex origin that isn't anchored (`^…$`). Matching semantics and the (still-absent) `Access-Control-Allow-Credentials` are unchanged.
240
+ - **[BREAKING]** Package `exports` are scoped to the intended public surface instead of a global `"./*": "./dist/*"` wildcard, which had made **every** internal file (`codegen/*`, `commands/*`, `config/*`, routing internals, …) importable and therefore semver-frozen the moment 5.0 lands. Exported now: `server.js`, `Cli.js`, `types.js`, `folderConfig.js`, `modules/*`, `models/*`, `helpers/*`, `services/*`, `controllers/*`, `tests/*`, `migrations/*` (`Cli.js` is the consumer CLI bootstrap — `import Cli from '@adaptivestone/framework/Cli.js'`). Internal subpaths (`codegen/*`, `commands/*`, `locales/*`, top-level entries) are no longer importable as `@adaptivestone/framework/<path>` — they were never intended public API, and the CLI loads commands/migrations by filesystem path (unaffected). The bare-specifier paths codegen emits (`server.js`, `models/*`, `modules/*`, `services/*`) all remain exported. See the README "Public API & stability" section for the tier policy that licenses refactoring `helpers/*` and `services/*` in minors.
241
+ - **[FIX]** **Fail fast at boot** (policy: fail at boot, stay up per-request). (1) A model that fails to initialize now **throws** — naming the model and its file — so `startServer` rejects, instead of being logged-and-skipped and resurfacing later as a confusing request-time crash. (2) `AUTH_SALT` is asserted at boot when the auth flow is active; missing → boot throws with the `npm run cli generateRandomBytes` hint (`config/auth.ts` now reads `process.env.AUTH_SALT` honestly — the boot check owns the messaging). (3) `uncaughtException` now logs and `process.exit(1)` — after an uncaught throw the process state is undefined, so a visible crash-loop under an orchestrator beats serving from a corrupted state (`unhandledRejection` stays log-only). (4) The Express 500 handler logs via winston and guards `res.headersSent` — a handler that throws mid-stream no longer crashes with `ERR_HTTP_HEADERS_SENT`.
242
+ - **[NEW]** **Mongo is required, and boot enforces it.** `startServer` now throws if no Mongo connection string is configured (`MONGO_DSN`) — rather than lazily skipping models and letting every database-using route 500 at request time. The AUTH_SALT boot check is correspondingly unconditional. Disable or replace any built-in controller (e.g. the built-in auth) by filename-shadowing it in your controllers folder (documented in the README). The default controller middleware stays `[GetUserByToken, Auth]` (secure-by-default).
243
+ - **[FIX]** One-Server-per-process is now an explicit contract. The second-`Server` throw — previously a bare "App instance is already set" — explains the rule and points at the fix (per-file test isolation, or the new **test-only** `resetAppInstance()` from `helpers/appInstance.ts`, which clears the singleton but NOT mongoose/redis/env state). Documented in the README.
244
+ - **[FIX]** `Sequence.getSequence` passes the id to `findByIdAndUpdate` directly (was a filter object that only worked by accidental Mongoose casting) and retries once on the E11000 upsert race.
245
+ - **[FIX]** Pagination `?limit=abc` / `?limit=-5` no longer become an unbounded query — a malformed or non-positive limit falls back to the configured default and is clamped to `maxLimit` (`0` meant "no limit" to Mongoose and bypassed the cap).
246
+ - **[FIX]** The route adapter stops the middleware chain when the client aborts mid-request (`res.destroyed`), not just on normal completion; the controller validation wrapper guards `res.headersSent` before its 400/500 (a handler that already streamed no longer crashes with `ERR_HTTP_HEADERS_SENT`).
247
+ - **[FIX]** CLI argument handling (`BaseCli`): required-check uses `=== undefined` (so `--flag=false` / `--name=""` satisfy a required option), an unknown flag prints usage instead of crashing, the extension strip uses a suffix regex, and a user-set `MONGO_APP_NAME` is no longer clobbered.
248
+ - **[FIX]** Request logs record the path, not `req.url` — the query string can carry secrets (e.g. `?verification_token=…`). `clearNamespace` uses non-blocking `SCAN` with a `${namespace}-` prefix instead of `KEYS *namespace*`. A missing configured folder throws a message naming the folder/path instead of a raw `ENOENT`.
249
+ - **[NEW]** Clustered deployments: the primary forwards `SIGTERM`/`SIGINT` to workers (each drains via its own handler) and exits once they're gone.
250
+ - **[CHANGE]** The auth config option `isAuthWithVefificationFlow` was renamed to `isAuthWithVerificationFlow` (the previous spelling was a typo). The old key still works but logs a one-time deprecation warning and will be removed in v6.
251
+ - **[SECURITY]** Resetting a password (`POST /auth/recover-password`) now revokes all of the user's existing session tokens, so any session created before the reset is invalidated.
252
+ - **[CHANGE]** Removed dead code: the unused `src/views/*.pug` templates (no `pug` dependency), the unread `config.validate.controllerValidationAbortEarly`, the no-op `consoleLogger` level filter, and the debug `console.log` on the prod entrypoint.
253
+ - **[CHANGE]** Added a packaging smoke test (`npm run smoke`, CI workflow `packaging.yml`): packs the tarball, installs it into a throwaway consumer, and verifies the **published dist** — public entry points import (catching broken built-import paths, the cluster-bug class) and internal subpaths stay unexported (the exports map). The TS-source test suite can't see dist-only breakage.
254
+ - **[FIX]** Router static-child lookup is now **O(1)** instead of a per-request linear scan. The tree matcher's `lookupStaticChild` walked every static child of every node on the path with a `toLowerCase()` allocation per child — and since `caseSensitive` is always `false` in production, that scan was the *only* path requests took (the O(1) branch was dead). Static children are now keyed by lowercase segment at registration time, so the now-always case-insensitive match is a single `Map.get`. Nodes keep their original-cased `segment` (display / `formatTree` / codegen paths unchanged — gen output byte-identical). Segments differing only by case now fold onto one node (case-insensitive matching already treated them as one); a same-method collision surfaces via the existing conflicting-handler error.
255
+ - **[FIX]** Redis connection helper now caches the **connect promise**, not the bare client. A second concurrent caller could get the client before its `connect()` resolved (double-connect on a half-built socket), a failed first connect cached a dead client forever (no retry), and the synchronous accessor fired `connect()` in an uncaught IIFE (process-level `unhandledRejection` when Redis was down at boot). Concurrent callers now await one connect, a failed connect clears the cache so the next call retries, and the sync accessor logs connection failures instead of crashing.
256
+
257
+ ### Internal
258
+
259
+ - **[CHANGE]** `npm run gen` now generates types from a single **AST front-end** (`oxc-parser`) — the boot-based codegen (`importResolution`, the ghost controller, app boot) has been removed. It parses controller and model sources directly, reuses the real `RouteRegistry.flatten()` for middleware chains, and emits — with **no app boot, no model imports (no Mongoose load), and no live-class identity matching** (the binding is read straight off the import node, retiring the whole regex reconstruction bug class). For declarative controllers the output is **byte-identical** to the old codegen (proven against the framework's own `Auth`/`Home` + fixtures before the boot path was removed); literal `routes`, `static get middleware()`, `getHttpPath()`, content-type request maps, and route-level `middleware` are all supported. Adds `oxc-parser` as a dependency (codegen runs in consumer projects).
260
+ - **[BREAKING]** Route-type codegen requires **statically analyzable controllers**. A controller whose `routes` / `static get middleware()` / `getHttpPath()` is built dynamically (loops, conditionals, computed values) can no longer be reflected — `npm run gen` now throws and names the controller instead of booting the app to read it. Make those getters return literal structures (the framework's own controllers and the audited consumer projects already do).
261
+
262
+ ---
263
+ ## [5.0.0-beta.55] - 2026-06-06
264
+
265
+ - **[FIX]** Codegen no longer emits an empty middleware chain for a controller's root (`/`) route. `chainFor` keyed the flattened-route lookup with a trailing slash for a `/` route under a non-root prefix (e.g. `POST /` on a controller mounted at `/file` was looked up as `POST /file/` while `RouteRegistry.flatten()` emits `POST /file`), so the route's middleware came back empty and the generated `req.appInfo` lost every middleware-provided field. Path joining now mirrors the registry (segment join, no trailing slash).
266
+ - **[FIX]** Codegen resolves middleware whose local import binding differs from its exported class name. The emit step matched chain entries against the controller's imports by class name, but the import map is keyed by the local binding — so a default export imported under another name (e.g. `import Auth from '.../Auth.js'` where the class is `AuthMiddleware`) was dropped from the generated type (and would otherwise have emitted an unbound `typeof AuthMiddleware`). The live class is now carried through and matched by module identity to recover the real binding (`Auth`). Affected the built-in `Auth` and `Role` middlewares.
267
+ - **[FIX]** Codegen resolves inherited default middleware through **bare-package** ancestors. A consumer controller relying on `AbstractController`'s default `static get middleware()` (without re-declaring it) extends the framework via a bare specifier (`@adaptivestone/framework/modules/AbstractController.js`); codegen previously skipped such ancestors, leaving the inherited `[GetUserByToken, Auth]` out of the generated `req.appInfo` type. Codegen now resolves the ancestor through the importing file's module resolution (honoring the package `exports` map) and rewrites the ancestor's relative middleware imports into bare specifiers the consumer's gen file can resolve. Re-declaring the middleware Map is no longer required to get typed `appInfo`.
268
+ - **[FIX]** Codegen rebases inherited middleware import paths when the parent controller lives in a **different directory** than the child. The `extends`-chain walk previously emitted the ancestor's relative import paths verbatim — correct only when parent and child share a folder — so a controller inheriting middleware from a parent elsewhere in the tree got a wrong relative path (and the middleware was then silently dropped from the type when the path failed to resolve). Ancestor relative imports are now rebased to the child's gen-file directory.
269
+ - **[NEW]** Golden-fixture codegen test (`src/codegen/routeTypes.golden.test.ts`): runs the real boot-free `generateRouteTypes` over fixture controllers, then `tsc`-checks the generated types against handlers that read `req.appInfo.user` without a guard. String-level assertions can't catch a wrong *type* (e.g. an empty `UnionAppInfoProvides<readonly []>`); this gate type-checks the output and would have caught every codegen bug fixed in this release.
270
+ - **[FIX]** `Auth` middleware now narrows `req.appInfo.user` to **required**. `AuthMiddleware` rejects unauthenticated requests at runtime but declared no `provides`, so behind `[GetUserByToken, Auth]` the user stayed optional (`user?`) and every handler needed an `if (!user)` guard purely to satisfy types. It now declares `static get provides()` returning `{ user: InstanceType<TUser> }`; `UnionAppInfoProvides` intersects it with `GetUserByToken`'s optional `user?` and collapses to a required `user`. Type-only — runtime unchanged.
271
+ - **[FIX]** `req.appInfo.user` now follows a project's OWN `User` model when it replaces the framework's, instead of always typing as the framework `User`. `GetUserByToken`/`Auth` resolve the user type through an augmentable `AppModels` interface (exported from `models/User.ts`), and `npm run gen` emits the binding into `genTypes.d.ts` automatically — the same mechanism that already types `app.getModel('User')`. Falls back to the framework `User` when not replaced; no consumer action needed beyond running codegen. (Previously the middleware `provides` hardcoded the framework `User`, so a replaced model's fields were missing from `appInfo.user` even though `getModel('User')` was correct.)
272
+ - **[CHANGE]** Removed the unused `source` field from `MiddlewareEntry` (`services/http/routing`). It was a write-only placeholder that no code read — codegen resolves middleware import paths from controller source instead — so it and its plumbing through `normalizeMiddleware`/`normalizeMiddlewares` are gone. If you constructed `MiddlewareEntry` objects directly (rare), drop the `source` property.
273
+ - **[BREAKING]** The built-in `Home` controller no longer registers `GetUserByToken` on a root-level `'/{*splat}'` scope. Because `Home` mounts at `/`, that middleware landed on the route-tree root and ran on **every request app-wide** — a hidden global default that couldn't be opted out of (a controller declaring empty middleware still ran it). `Home` now adds no middleware (it's a public route); controllers still parse the user token via their own/inherited `[GetUserByToken, Auth]`. **Impact:** if you relied on `req.appInfo.user` being populated on routes that don't themselves include `GetUserByToken` (e.g. ad-hoc `registerRoute` endpoints), add the middleware explicitly. Re-add `[GetUserByToken]` to your home controller for a token-aware home.
274
+
275
+ ---
276
+ ## [5.0.0-beta.54] - 2026-06-05
277
+
278
+ - **[FIX]** `getConfig()` types in `genTypes.d.ts` are now inline **value-shape** types (value *types* like `string`, with arrays kept as **tuples**) instead of the `typeof import('./config/foo.ts').default` reference form introduced in beta.52. The reference form inferred array config elements as a union with `?: undefined` keys, which broke `Object.values()` over a config item (it widened to `any`) and could resolve to `any` outright on stricter/preview TypeScript (e.g. older `tsgo` builds) — a regression that surfaced only in CI for projects whose local type-checker differed. The value-shape form keeps `Object.values()` and per-element typing precise and is robust across compilers (it resolves no module), while still never serializing a literal config value into the generated file.
279
+
280
+ ---
281
+ ## [5.0.0-beta.53] - 2026-06-05
282
+
283
+ - **[NEW]** Codegen reads controllers without running their constructors. `generatetypes` now introspects each controller via a prototype-only "ghost" (`Object.create(Class.prototype)`) instead of `new Controller(app, prefix)`, so config reads, client construction, and other constructor side effects no longer fire during type generation. Runtime is unchanged — handlers still bind to real instances.
284
+ - **[DEPRECATED]** A controller whose `routes` getter reads **constructor-set state** is deprecated. Codegen transparently falls back to instantiating it (so nothing breaks) and emits a one-per-class `DeprecationWarning`, code `ASF_DEP_CTOR_ROUTES`. Make `routes` independent of constructor state; the instantiation fallback **will be removed in v6**.
285
+ - **[FIX]** Model-using CLI commands now wait for the MongoDB connection before running. Previously `#mongooseConnect()` was fire-and-forget, so a CLI command (`isShouldInitModels`) could fire its first query before the connection was established and rely on mongoose's buffer (default 10s `bufferTimeoutMS`) — causing intermittent "buffering timed out" failures on slow connects. Now `initAllModels({ waitForConnection: true })` (used only by model-using CLI commands) blocks until the connection is ready, with explicit progress logs (`Connecting to MongoDB…`, `MongoDB connection established in Nms`, `waiting … → ready after Nms`). Modelless commands (e.g. `generatetypes`) and the HTTP server are unaffected — the server stays lazy (requests buffer until ready).
286
+ ---
287
+
288
+
289
+ ## [5.0.0-beta.52] - 2026-06-04
290
+
291
+ - **[NEW]** Middleware request/query schemas can be declared **statically** — `static get relatedRequestParameters()` / `static get relatedQueryParameters()`. The framework reads them without instantiating the middleware (avoids constructor side effects during route setup / codegen). Framework middlewares (`Pagination`) migrated.
292
+ - **[DEPRECATED]** The **instance** form of those getters (`get relatedRequestParameters()` / `relatedQueryParameters` / `relatedReqParameters`) is deprecated and **will be removed in v6** — migrate to the static form. It still works (the framework detects the override, instantiates as a fallback, and emits a one-per-class `DeprecationWarning`, code `ASF_DEP_MW_INSTANCE_SCHEMA`).
293
+ - **[FIX]** `getConfig()` types in `genTypes.d.ts` are now emitted as references to each config module's type (`typeof import('./config/foo.ts').default`) instead of a serialized snapshot of the resolved runtime value. The old value-based approach had two real problems: env-only fields (e.g. `connectionString: process.env.MONGO_DSN`) **silently vanished** from the type when the env var was unset at gen time (`JSON.stringify` drops `undefined`), and populating the env var to keep them **baked the secret value into the committed file**. Reference-based types keep env-only fields (typed `string | undefined`), never serialize a value, and avoid over-narrow literal types (`port` is `string | number`, not `3300`). _(Superseded in beta.54 — see above.)_
294
+
295
+
296
+
297
+ ---
298
+ ## [5.0.0-beta.51] - 2026-05-31
299
+
300
+ - **[NEW]** `KeyValue` model: a minimal persistent key/value store backed by MongoDB for lightweight caching, runtime config, and feature flags.
301
+ - **[NEW]** `defineSchema<Output>(validate)` helper (`@adaptivestone/framework/services/validate/defineSchema.js`) — wrap a plain validate function into a zero-dependency Standard Schema. Codegen reads its `Output` generic for handler request types via `StandardSchemaV1.InferOutput`.
302
+ - **[NEW]** `File` type exported from `@adaptivestone/framework/types.js` — vendor-neutral uploaded-file type (aliases formidable's `PersistentFile` today; re-points at the web-standard `File` after the P3 parser swap). Validate uploads with your validator's idiom, e.g. `z.instanceof(File)`.
303
+ - **[NEW]** Content-type-keyed request schemas: a route's `request` can be a map (`{ 'application/json': schemaA, 'multipart/form-data': schemaB }`, mirrors OpenAPI `requestBody.content`). The framework validates with the schema matching the request's `Content-Type` (415 on no match) and `req.appInfo.request` becomes a `contentType`-discriminated union; codegen emits the union automatically. Media-type matching is case-insensitive and ignores parameters (`; charset=...`); `contentType` is a reserved field on the validated request object.
304
+ - **[CHANGE]** Built-in `Auth` controller and `Pagination` middleware now validate with `defineSchema` instead of yup. The framework runtime and built-ins are yup-free.
305
+ - **[BREAKING]** `yup` moved from `dependencies` to an optional `peerDependency`. It is no longer bundled. Apps that use yup schemas (including `YupFile`) must add `yup` to their own `dependencies`. Zod/Valibot/ArkType users are unaffected.
306
+ - **[BREAKING]** `@redis/client` v6. Now defaults to the RESP3 protocol (was RESP2) and requires a Redis ≥6 server; pass `createClient({ RESP: 2 })` to keep v5 wire behavior. Also adds a default 5s command timeout. <https://github.com/redis/node-redis/blob/master/docs/v5-to-v6.md>
307
+ - **[DEPRECATED]** `YupFile` (`@adaptivestone/framework/helpers/yup.js`) — removed in v6. Validate files via the new `File` export + your validator's `instanceof` idiom instead.
308
+
309
+ ---
310
+ ## [5.0.0-beta.50] - 2026-05-25
311
+
312
+ - **[FIX]** Tree-based router: different HTTP methods at the same param position can now use different `:name` segments. Previously, `PUT /:slug` and `POST /:event` on the same controller would either throw at boot ("conflicting param children") or silently use the first-registered name for all methods (`req.params.event` → `undefined`). Each `HandlerEntry` now carries its own `paramNames` array — the tree is structural only, param naming is per-handler.
313
+
314
+ ---
315
+ ## [5.0.0-beta.49] - 2026-05-18
316
+
317
+ - **[FIX]** Codegen: fix router name resolution in generated route types.
318
+ - **[UPDATE]** Codegen output improvements.
319
+
320
+ ---
321
+ ## [5.0.0-beta.48] - 2026-05-11
322
+
323
+ - **[NEW]** Codegen emits route metadata (`methodName`, `controllerClass`, `sourceFile`) on `HandlerEntry.meta`.
324
+ - **[NEW]** `Pagination` middleware declares `static get provides()` — routes with `Pagination` in their chain get `req.appInfo.pagination` typed automatically.
325
+ - **[NEW]** Codegen emits `appInfo.query` from route-level `query:` schemas.
326
+ - **[NEW]** Codegen deduplicates identical union branches.
327
+
328
+ ---
329
+ ## [5.0.0-beta.47] - 2026-05-11
330
+
331
+ - **[UPDATE]** Tree-based route type generation improvements.
332
+ - **[UPDATE]** Dependencies update.
333
+
334
+ ---
335
+ ## [5.0.0-beta.46] - 2026-05-11
336
+
337
+ - **[NEW]** Tree-based `RouteRegistry` replaces Express's hidden router internally. One global tree, walkable by codegen / OpenAPI / MCP emitters.
338
+ - **[NEW]** Per-controller route type generation (`npm run gen` emits `<File>.routes.gen.ts`).
339
+ - **[NEW]** Standard Schema validation (Yup ≥1.7, Zod, Valibot, ArkType supported).
340
+ - **[NEW]** Boot-time route tree log at `verbose` level.
341
+ - **[NEW]** Boot-time warnings on misconfigured routes / middleware Maps.
342
+ - **[NEW]** `app.controllerManager.registerController(ControllerClass, prefix?)` for explicit registration.
343
+ - **[FIX]** `setupVitest.ts` no longer imports framework-internal fixtures.
344
+ - **[FIX]** Codegen walks the `extends` chain when resolving middleware import paths.
345
+ - **[BREAKING]** Path-pattern syntax narrowed (no Express 5 optional-param `{:name}` or inline regex).
346
+ - **[BREAKING]** `AbstractController` constructor third argument `isExpressMergeParams` removed.
347
+ - **[BREAKING]** Legacy `{validate, cast}` plain-object validators removed.
348
+ - **[BREAKING]** Yup ≥1.7 required. Schemas must implement Standard Schema.
349
+ - **[BREAKING]** `ValidateService` surface trimmed. Helpers like `validateReqData` removed.
350
+ - **[BREAKING]** OpenAPI / documentation generation removed (will return later).
351
+
352
+ ---
353
+ ## [5.0.0-beta.45] - 2026-03-28
354
+ - **[BREAKING]** rate-limiter-flexible v9->v10
355
+ - **[BREAKING]** typecript v5->v6
356
+
357
+ ---
358
+ ## [5.0.0-beta.44] - 2026-02-22
359
+
360
+ - **[NEW]** Logout method
361
+ - **[Update]** set model typing
362
+
363
+
364
+
365
+ ---
366
+ ## [5.0.0-beta.43] - 2026-01-24
367
+
368
+ - **[FIX]** Fix typo in peerDeps
369
+
370
+
371
+ ---
372
+ ## [5.0.0-beta.42] - 2026-01-24
373
+
374
+ - **[BREAKING]** Mongoose v9. <https://mongoosejs.com/docs/migrating_to_9.html>.
375
+
376
+ ---
377
+ ## [5.0.0-beta.41] - 2026-01-17
378
+
379
+ - **[UPDATE]** Update deps
380
+ - **[NEW]** Bearer scheme support
381
+ - **[NEW]** redisConnection helper
382
+
383
+
384
+
385
+ ---
386
+ ## [5.0.0-beta.40] - 2025-12-15
387
+
388
+ - **[UPDATE]** Update `rate-limiter-flexible` to v9.
389
+ - **[UPDATE]** Remove 'winston-transport-sentry' and implementcustom logic based on 'sentry' itself (from v9.14 sentry have native winston support)
390
+
391
+
392
+ ## [5.0.0-beta.39] - 2025-10-25
393
+
394
+ - **[UPDATE]** rete limiter. Do not create index on mongo if we have "process.env.test === 'true'"
395
+
396
+ ---
397
+
398
+ ## [5.0.0-beta.38] - 2025-10-25
399
+
400
+ - **[UPDATE]** update dependencies
401
+ - **[UPDATE]** update rate limiter Mongo option to not create an index by default when NODE_ENV=test
402
+ - **[UPDATE]** the default User model now uses roles and permissions with the String type (previously was any, for historical reasons). To avoid changes on Mongoose 8.19 as it affects User model https://github.com/Automattic/mongoose/issues/15699
403
+ - **[BREAKING]** Vitest v4 <https://vitest.dev/guide/migration.html#vitest-4>
404
+
405
+ ---
406
+
407
+ ## [5.0.0-beta.36] - 2025-08-24
408
+
409
+ - **[UPDATE]** i18nService update loading to avoid race conditions
410
+ ---
411
+
412
+ ## [5.0.0-beta.36] - 2025-08-24
413
+
414
+ - **[UPDATE]** i18nService update method names
415
+
416
+ ---
417
+
418
+ ## [5.0.0-beta.35] - 2025-08-24
419
+
420
+ - **[NEW]** Introduce i18nService (ability to user i18n not only inside middleware)
421
+
422
+ ---
423
+
424
+ ## [5.0.0-beta.34] - 2025-08-23
425
+
426
+ - **[NEW]** I18nMiddlewareAppInfo type
427
+
428
+ ---
429
+
430
+ ## [5.0.0-beta.33] - 2025-08-21
431
+
432
+ - **[NEW]** consumeResult changed to be more flexible
433
+
434
+ ---
435
+
436
+ ## [5.0.0-beta.32] - 2025-08-21
437
+
438
+ - **[NEW]** Ip detector middleware - add getIpAdressFromIncomingMessage function to allow user middleware as a detector of id adresses without middleware
439
+
440
+ ---
441
+
442
+ ## [5.0.0-beta.31] - 2025-08-21
443
+
444
+ - **[NEW]** Rate limiter middleware - add consumeResult function to allow user middleware as a regular rate limiter
445
+
446
+
447
+ ---
448
+
449
+ ## [5.0.0-beta.30] - 2025-08-01
450
+
451
+ - **[FIX]** Fix CLI mongo app name generation (64 symbols limit)
452
+
453
+
454
+ ---
455
+
456
+ ## [5.0.0-beta.29] - 2025-07-31
457
+
458
+ - **[FIX]** Fix CLI mongo app name generation (128 symbols limit)
459
+
460
+ ---
461
+
462
+ ## [5.0.0-beta.28] - 2025-07-29
463
+
464
+ - **[UPDATE]** Inside CLI allow to have a negative values
465
+ - **[UPDATE]** Update deps.
466
+
467
+ ---
468
+
469
+ ## [5.0.0-beta.27] - 2025-06-27
470
+
471
+ - **[UPDATE]** Remove eslint, prettiver and move to biome
472
+ - **[UPDATE]** Update types.
473
+ - **[UPDATE]** Update deps.
474
+
475
+
476
+ ---
477
+
478
+ ## [5.0.0-beta.26] - 2025-06-19
479
+
480
+ - **[UPDATE]** Update types.
481
+ - **[UPDATE]** Update tests (more ts).
482
+
483
+ ---
484
+
485
+ ## [5.0.0-beta.25] - 2025-06-17
486
+
487
+ - **[UPDATE]** Update types.
488
+
489
+ ---
490
+
491
+ ## [5.0.0-beta.24] - 2025-06-16
492
+
493
+ - **[UPDATE]** Update types.
494
+
495
+ ---
496
+
497
+ ## [5.0.0-beta.23] - 2025-06-16
498
+
499
+ - **[BREAKING]** No more global variables for testing and default user will not be created by default
500
+ - **[NEW]** Test helpers getTestServerURL, serverInstance, setDefaultUser, setDefaultAuthToken and createDefaultTestUser.
501
+
502
+ ---
503
+
504
+ ## [5.0.0-beta.22] - 2025-06-10
505
+
506
+ - **[UPDATE]** Update types.
507
+
508
+ ---
509
+
510
+ ## [5.0.0-beta.21] - 2025-06-09
511
+
512
+ - **[FIX]** Fix bug with missed model options.
513
+
514
+ ---
515
+
516
+ ## [5.0.0-beta.20] - 2025-06-09
517
+
518
+ - **[FIX]** Fix bug with `Lock` model index.
519
+ - **[NEW]** `BaseModel` add `Virtuals`.
520
+
521
+ ---
522
+
523
+ ## [5.0.0-beta.19] - 2025-06-08
524
+
525
+ - **[NEW]** Introducing new model type. `BaseModel`. Features - simplifie works with typescript. And based on statics.
526
+ - **[BREAKING]** All models now should be extended from `BaseModel`. This is a potential breaking change specially for `User` model.
527
+
528
+ ---
529
+
530
+ ## [5.0.0-beta.18] - 2025-06-08
531
+
532
+ - **[UPDATE]** Move away connection from `mongooseModels` to server itself (preparation for different model types).
533
+ - **[BREAKING]** potential. We are removed callback from `mongooseModels` contrctuctor. It was not used in code.
534
+ - **[NEW]** Add `appInstance` helper to access app instance from anywhere without passing it.
535
+
536
+ ---
537
+
538
+ ## [5.0.0-beta.17] - 2025-05-26
539
+
540
+ - **[NEW]** Add `GenerateTypes` command.
541
+
542
+ ---
543
+
544
+ ## [5.0.0-beta.16] - 2025-05-26
545
+
546
+ - **[UPDATE]** Update deps.
547
+ - **[UPDATE]** New app getter `internalFilesCache`.
548
+ - **[UPDATE]** Command new static props to load `isShouldGetModelPaths`.
549
+
550
+ ---
551
+
552
+ ## [5.0.0-beta.15] - 2025-04-24
553
+
554
+ - **[FIX]** Fix missing folder `migrations` in `dist` folder (hope that will be finally).
555
+
556
+ ---
557
+
558
+ ## [5.0.0-beta.14] - 2025-04-24
559
+
560
+ - **[FIX]** Fix missing folder `migrations` in `dist` folder.
561
+
562
+ ---
563
+
564
+ ## [5.0.0-beta.13] - 2025-04-23
565
+
566
+ - **[UPDATE]** Only process `.ts` or `.js` files (not `.map` files).
567
+
568
+ ---
569
+
570
+ ## [5.0.0-beta.12] - 2025-04-23
571
+
572
+ - **[BREAKING]** Remove jest support for testing.
573
+ - **[NEW]** Initial move to typescript. potentially breaking.
574
+ - **[NEW]** Introduce `src` and `dist` folders.
575
+
576
+ ---
577
+
578
+ ## [5.0.0-beta.11] - 2025-04-02
579
+
580
+ - **[NEW]** Commands typing.
581
+ - **[NEW]** Commands support TS files.
582
+ - **[UPDATE]** Update deps.
583
+
584
+ ---
585
+
586
+ ## [5.0.0-beta.9] - 2025-02-19
587
+
588
+ - **[BREAKING]** Move email module to separate package `@adaptivestone/framework-module-email`. Please use it if you want to send emails.
589
+ - **[NEW]** App now contains `frameworkFolder` folder the framework located. Mostly for modules usage.
590
+ - **[BREAKING]** Remove `VIEWS` folders at all. Should not afffect any user as this was not used internally.
591
+ - **[UPDATE]** Update typing.
592
+ - **[UPDATE]** Change `redis` -> `@redis/client` as we are using only client from pakage.
593
+ - **[BREAKING]** Removed `noidemailer-sendmail-transport`. Not needed anymore and not recommended to use as well.
594
+
595
+ ---
596
+
597
+ ## [5.0.0-beta.8] - 2025-02-16
598
+
599
+ - **[UPDATE]** Update deps.
600
+ - **[NEW]** `Lock` model for working locks via mongoDB.
601
+
602
+ ---
603
+
604
+ ## [5.0.0-beta.7] - 2025-02-09
605
+
606
+ - **[UPDATE]** Update deps.
607
+ - **[UPDATE]** Change `vitest` shutdown behavior as mongo driver v6.13 change befaviur that affect us (`MongoClient.close` now closes any outstanding cursors).
608
+
609
+ ---
610
+
611
+ ## [5.0.0-beta.5] - 2025-01-26
612
+
613
+ - **[BREAKING]** Remove `minimist` CLI parsing and replace it by `commandArguments` parser.
614
+ - **[UPDATE]** Migrated from `eslint-plugin-import` to `eslint-plugin-import-x`.
615
+ - **[UPDATE]** Migrate to eslint 9 and away from aibnb styles (they are abonded).
616
+
617
+ ---
618
+
619
+ ## [5.0.0-beta.4] - 2025-01-26
620
+
621
+ - **[NEW]** On shutdown event now after timeout we are forcing to shutdown.
622
+
623
+ ---
624
+
625
+ ## [5.0.0-beta.2] - 2025-01-26
626
+
627
+ - **[UPDATE]** Update deps.
628
+ - **[NEW]** Add ability to skip mongo model init in CLI env.
629
+ - **[NEW]** Now each mongo connection on CLI have own name and inslude command name there too (`getMongoConnectionName` in command).
630
+
631
+ ---
632
+
633
+ ## [5.0.0-beta.1] - 2025-01-21
634
+
635
+ - **[UPDATE]** Update deps.
636
+ - **[BREAKING]** `vitest` v3 <https://vitest.dev/guide/migration.html>.
637
+
638
+ ---
639
+
640
+ ## [5.0.0-alpha.26] - 2025-01-04
641
+
642
+ - **[UPDATE]** Update deps.
643
+ - **[UPDATE]** New commands view in CLI.
644
+
645
+ ---
646
+
647
+ ## [5.0.0-alpha.24] - 2024-11-22
648
+
649
+ - **[UPDATE]** Update deps.
650
+ - **[BREAKING]** `i18next` v24 <https://www.i18next.com/misc/migration-guide#v23.x.x-to-v24.0.0>.
651
+
652
+ ---
653
+
654
+ ## [5.0.0-alpha.23] - 2024-11-10
655
+
656
+ - **[UPDATE]** Update deps.
657
+
658
+ ---
659
+
660
+ ## [5.0.0-alpha.22] - 2024-10-29
661
+
662
+ - **[UPDATE]** Update deps.
663
+ - **[FIX]** Fix optional routing parameters.
664
+
665
+ ---
666
+
667
+ ## [5.0.0-alpha.21] - 2024-10-27
668
+
669
+ - **[BREAKING]** Possible breaking. Framework start using express 5 instead of express 4. Please follow express migration guide too <https://expressjs.com/en/guide/migrating-5.html>.
670
+ - **[BREAKING]** As part of express 5 migration `_` in rotes (middlewares) should have perameter. please replace `_` to `*splat`.
671
+ - **[UPDATE]** Update deps.
672
+ - **[UPDATE]** Mailer uses `await import()` for startup speedup.
673
+
674
+ ---
675
+
676
+ ## [5.0.0-alpha.20] - 2024-10-26
677
+
678
+ - **[UPDATE]** Update deps.
679
+ - **[UPDATE]** `#realLogger` do not throw error in a scecific cases (`model.toJSON({virtual:true})`).
680
+
681
+ ---
682
+
683
+ ## [5.0.0-alpha.19] - 2024-10-23
684
+
685
+ - **[NEW]** Added `modelSchemaOptions` for models.
686
+
687
+ ---
688
+
689
+ ## [5.0.0-alpha.18] - 2024-10-07
690
+
691
+ - **[BREAKING]** Default auth response changed to be unified. `{token, user}` => `{data:{token, user}}`.
692
+ - **[UPDATE]** `RateLimiter` updae key generation.
693
+
694
+ ---
695
+
696
+ ## [5.0.0-alpha.17] - 2024-10-05
697
+
698
+ - **[NEW]** `generateRandomBytes` command.
699
+ - **[UPDATE]** Update deps.
700
+
701
+ ---
702
+
703
+ ## [5.0.0-alpha.16] - 2024-10-02
704
+
705
+ - **[UPDATE]** No warning of direct usage `body` and `query`.
706
+ - **[UPDATE]** Update deps.
707
+
708
+ ---
709
+
710
+ ## [5.0.0-alpha.15] - 2024-09-26
711
+
712
+ - **[BUG]** Fix bug with pagination.
713
+ - **[UPDATE]** Update deps.
714
+
715
+ ---
716
+
717
+ ## [5.0.0-alpha.14] - 2024-09-23
718
+
719
+ - **[NEW]** Add types for `Abstract` model (wip).
720
+
721
+ ---
722
+
723
+ ## [5.0.0-alpha.13] - 2024-09-06
724
+
725
+ - **[UPDATE]** Update deps.
726
+ - **[UPDATE]** Update `i18n` internal implementation.
727
+ - **[CHANGE]** Disable https server view.
728
+
729
+ ---
730
+
731
+ ## [5.0.0-alpha.12] - 2024-09-04
732
+
733
+ - **[UPDATE]** Update deps.
734
+
735
+ ---
736
+
737
+ ## [5.0.0-alpha.11] - 2024-08-08
738
+
739
+ - **[UPDATE]** Update deps.
740
+
741
+ ---
742
+
743
+ ## [5.0.0-alpha.10] - 2024-07-29
744
+
745
+ - **[UPDATE]** Update deps.
746
+ - **[NEW]** `IpDetector` middleware that support detecting proxy and `X-Forwarded-For` header.
747
+ - **[BREAKING]** `RateLimiter` now need to have `IpDetector` middleware before.
748
+
749
+ ---
750
+
751
+ ## [5.0.0-alpha.9] - 2024-07-15
752
+
753
+ - **[UPDATE]** Update deps.
754
+ - **[BREAKING]** Removing `staticFiles` middleware as it not used in projects anymore. Docs with nginx config will be provided.
755
+ - **[BREAKING]** Remove default `AUTH_SALT`. It should be provided on a app level now.
756
+ - **[BREAKING]** Vitest 2.0.0 <https://vitest.dev/guide/migration.html#migrating-to-vitest-2-0>.
757
+
758
+ ---
759
+
760
+ ## [5.0.0-alpha.8] - 2024-05-10
761
+
762
+ - **[UPDATE]** Replace `dotenv` with `loadEnvFile`.
763
+ - **[UPDATE]** Replace `nodemon` with `node --watch` (dev only).
764
+ - **[BREAKING]** Minimum node version is 20.12 as for now (`process.loadEnvFile`).
765
+
766
+ ---
767
+
768
+ ## [5.0.0-alpha.7] - 2024-04-12
769
+
770
+ - **[UPDATE]** Deps update.
771
+
772
+ ---
773
+
774
+ ## [5.0.0-alpha.6] - 2024-03-03
775
+
776
+ - **[UPDATE]** Update internal documentation (`jsdoc`, `d.ts`).
777
+
778
+ ---
779
+
780
+ ## [5.0.0-alpha.5] - 2024-02-29
781
+
782
+ - **[UPDATE]** More verbose errors for rapsing body request.
783
+ - **[UPDATE]** Deps update.
784
+
785
+ ---
786
+
787
+ ## [5.0.0-alpha.4] - 2024-02-17
788
+
789
+ - **[UPDATE]** Update `rate-limiter-flexible` to v5.
790
+ - **[CHANGE]** Cache update `redis.setEX` to `redis.set(..,..,{EX:xx})` as `setEX` deprecated.
791
+
792
+ ---
793
+
794
+ ## [5.0.0-alpha.3] - 2024-02-14
795
+
796
+ - **[UPDATE]** Deps update.
797
+ - **[FIX]** `Migration` commands apply.
798
+
799
+ ---
800
+
801
+ ## [5.0.0-alpha.2] - 2024-01-25
802
+
803
+ - **[UPDATE]** Deps update.
804
+
805
+ ---
806
+
807
+ ## [5.0.0-alpha.1] - 2023-12-04
808
+
809
+ - **[BREAKING]** Vitest 1.0.0 <https://vitest.dev/guide/migration.html#migrating-from-vitest-0-34-6>.
810
+ - **[BREAKING]** ESM only. No more commonJS. That help to fix a lot of bugs with tests and provides better development expirience.
811
+ - **[BREAKING]** Mongoose v8. <https://mongoosejs.com/docs/migrating_to_8.html>.
812
+
813
+ ---
814
+
815
+ ## Older versions
816
+
817
+ Release notes for previous major versions are archived in separate files:
818
+
819
+ - [v4.x](./CHANGELOG_V4.md)
820
+ - [v3.x](./CHANGELOG_V3.md)
821
+ - [v2.x](./CHANGELOG_V2.md)
822
+ - [v1.x](./CHANGELOG_V1.md)
@@ -1,22 +1,92 @@
1
1
  import type { HydratedDocument, InferRawDocType, Schema } from 'mongoose';
2
2
  import { type Model } from 'mongoose';
3
3
  export type Merge<M, N> = Omit<M, keyof N> & N;
4
+ /** The timestamp fields Mongoose adds when `timestamps` is on (the default).
5
+ * Typed `required: true` so `InferRawDocType` resolves them to a non-null `Date`
6
+ * on the hydrated doc — Mongoose always sets them, so a `| null | undefined`
7
+ * would force a needless guard at every read. */
8
+ type Timestamps = {
9
+ createdAt: {
10
+ type: DateConstructor;
11
+ required: true;
12
+ };
13
+ updatedAt: {
14
+ type: DateConstructor;
15
+ required: true;
16
+ };
17
+ };
4
18
  export type WithTimestamps<TOptions> = TOptions extends {
5
19
  timestamps: true;
6
- } ? {
7
- createdAt: Schema.Types.Date;
8
- updatedAt: Schema.Types.Date;
9
- } : TOptions extends {
20
+ } ? Timestamps : TOptions extends {
10
21
  timestamps: false;
11
- } ? object : {
12
- createdAt: Schema.Types.Date;
13
- updatedAt: Schema.Types.Date;
14
- };
22
+ } ? object : Timestamps;
15
23
  export type ExtractProperty<T, K extends PropertyKey, Default = object> = T extends {
16
24
  [P in K]: infer R;
17
25
  } ? R : Default;
18
- export type GetModelSchemaTypeFromClass<T extends typeof BaseModel> = Schema<InferRawDocType<ExtractProperty<T, 'modelSchema'> & WithTimestamps<Merge<typeof defaultOptions, ExtractProperty<T, 'schemaOptions'>>>>, // TRawDocType
19
- Model<InferRawDocType<ExtractProperty<T, 'modelSchema'> & WithTimestamps<Merge<typeof defaultOptions, ExtractProperty<T, 'schemaOptions'>>>>, object, // TQueryHelpers
26
+ /**
27
+ * Phantom per-field type override. Intersect a schema field with this to type
28
+ * that field as `T` instead of the type Mongoose infers from `type:` — for
29
+ * fields a plugin reshapes at runtime (`mongoose-intl`, encrypted fields,
30
+ * custom getters), so the static type matches what's actually stored. `__tsType`
31
+ * is never set at runtime; only the compile-time type changes. Opt-in and a
32
+ * strict no-op for any field that doesn't carry the marker.
33
+ *
34
+ * @example
35
+ * // app-side, ideally behind a small factory:
36
+ * title: { type: String, intl: true } as { type: StringConstructor; intl: true } &
37
+ * TsTypeOverride<IntlSubDocValue<string>>;
38
+ */
39
+ export interface TsTypeOverride<T> {
40
+ readonly __tsType?: T;
41
+ }
42
+ /**
43
+ * A leaf field definition — a bare constructor (`String`, `ObjectId`) or a
44
+ * `{ type: SomeConstructor, … }` form (String, Number, ObjectId, Date, Map,
45
+ * Buffer, …). This mirrors how Mongoose itself decides "leaf field" vs "nested
46
+ * schema", so {@link ApplyTsOverrides} recurses only into nested *schemas* (a
47
+ * record of field defs) and leaves built-in instances (ObjectId, Date, Map)
48
+ * untouched — instead of mapping over their internals, which only bloated the
49
+ * displayed type and wasted compile work (it was always a structural no-op).
50
+ */
51
+ type IsLeafFieldDef<S> = S extends abstract new (...args: never) => unknown ? true : S extends {
52
+ type: infer Tp;
53
+ } ? Tp extends abstract new (...args: never) => unknown ? true : false : false;
54
+ /**
55
+ * Walk an inferred raw-doc type alongside its schema and replace each field
56
+ * marked with {@link TsTypeOverride} by the declared override type. Recurses
57
+ * into nested objects and subdocument arrays (a reshaped field can appear at any
58
+ * depth); leaves everything else — including arrays of primitives and built-in
59
+ * instances (ObjectId/Date/Map, via {@link IsLeafFieldDef}) — untouched. A
60
+ * schema with no markers maps to a structurally identical type, so existing
61
+ * models are unaffected. The marker is detected by the *presence* of the
62
+ * `__tsType` key (not by `extends TsTypeOverride`, which an optional property
63
+ * would match on every field).
64
+ */
65
+ export type ApplyTsOverrides<Doc, Schema> = {
66
+ [K in keyof Doc]: K extends keyof Schema ? '__tsType' extends keyof Schema[K] ? Schema[K] extends TsTypeOverride<infer U> ? U : Doc[K] : NonNullable<Schema[K]> extends readonly (infer E)[] ? NonNullable<Doc[K]> extends readonly (infer D)[] ? D extends object ? IsLeafFieldDef<E> extends true ? Doc[K] : ApplyTsOverrides<D, E>[] | Exclude<Doc[K], readonly unknown[]> : Doc[K] : Doc[K] : NonNullable<Schema[K]> extends object ? NonNullable<Doc[K]> extends object ? IsLeafFieldDef<NonNullable<Schema[K]>> extends true ? Doc[K] : ApplyTsOverrides<NonNullable<Doc[K]>, NonNullable<Schema[K]>> | Exclude<Doc[K], object> : Doc[K] : Doc[K] : Doc[K];
67
+ };
68
+ /**
69
+ * True when a schema carries at least one {@link TsTypeOverride} marker anywhere
70
+ * — at the top level, inside a nested object, or inside a subdocument array.
71
+ * Recurses with the same leaf/array/object shape as {@link ApplyTsOverrides}, so
72
+ * it cannot miss a marker the override pass would have applied. Used to skip the
73
+ * whole override mapping for the overwhelmingly common marker-free model, so its
74
+ * doc type is the plain Mongoose inference with no `ApplyTsOverrides<…>` wrapper
75
+ * in hovers and no extra compile work.
76
+ */
77
+ type HasTsOverride<S> = S extends object ? '__tsType' extends keyof S ? true : IsLeafFieldDef<S> extends true ? false : S extends readonly (infer E)[] ? HasTsOverride<E> : true extends {
78
+ [K in keyof S]: HasTsOverride<S[K]>;
79
+ }[keyof S] ? true : false : false;
80
+ /** {@link ApplyTsOverrides} only when the schema actually has a marker;
81
+ * otherwise the inferred doc verbatim (a strict no-op, but without the wrapper). */
82
+ type MaybeApplyOverrides<Doc, Schema> = HasTsOverride<Schema> extends true ? ApplyTsOverrides<Doc, Schema> : Doc;
83
+ /** The raw doc type Mongoose infers from a class's `modelSchema` + timestamps. */
84
+ type InferredRawDoc<T extends typeof BaseModel> = InferRawDocType<ExtractProperty<T, 'modelSchema'> & WithTimestamps<Merge<typeof defaultOptions, ExtractProperty<T, 'schemaOptions'>>>>;
85
+ /** {@link InferredRawDoc} with any per-field `__tsType` overrides applied —
86
+ * and, for a marker-free schema, exactly {@link InferredRawDoc} with no wrapper. */
87
+ type OverriddenRawDoc<T extends typeof BaseModel> = MaybeApplyOverrides<InferredRawDoc<T>, ExtractProperty<T, 'modelSchema'>>;
88
+ export type GetModelSchemaTypeFromClass<T extends typeof BaseModel> = Schema<OverriddenRawDoc<T>, // TRawDocType
89
+ Model<OverriddenRawDoc<T>, object, // TQueryHelpers
20
90
  ExtractProperty<T, 'modelInstanceMethods'>, // TInstanceMethods
21
91
  ExtractProperty<T, 'modelVirtuals'>>, // TModelType
22
92
  ExtractProperty<T, 'modelInstanceMethods'>, // TInstanceMethods
@@ -29,18 +99,42 @@ export type VirtualType<T> = {
29
99
  get: () => infer R;
30
100
  } ? R : never;
31
101
  };
32
- export type GetModelTypeFromClass<T extends typeof BaseModel> = Model<InferRawDocType<ExtractProperty<T, 'modelSchema'> & WithTimestamps<Merge<typeof defaultOptions, ExtractProperty<T, 'schemaOptions'>>>>, // TRawDocType
102
+ /**
103
+ * Caller-facing view of instance methods: drop the authored `this` constraint
104
+ * from each method when projecting them onto the document type. A method body
105
+ * may declare an explicit `this: <bridge>` (a narrower hand-written shape the
106
+ * body needs — e.g. a populated ref or a plugin-reshaped field); that bridge is
107
+ * deliberately not assignable-from the framework-computed hydrated doc, so a
108
+ * direct `doc.method(...)` call would otherwise fail the this-context check
109
+ * (TS2684) even though `this` is always correctly bound at runtime. Stripping it
110
+ * here fixes the false positive while leaving the authored definitions
111
+ * untouched, so method bodies stay type-checked against their declared `this`.
112
+ * `OmitThisParameter` returns non-function members (and methods with no explicit
113
+ * `this`) unchanged, so this is a strict no-op for ordinary instance methods.
114
+ *
115
+ * Known limitation: a method that is BOTH generic AND declares an explicit
116
+ * `this` loses its type parameters here (they collapse to their constraint) —
117
+ * `OmitThisParameter` rebuilds the signature via `infer`, which can't carry
118
+ * generics. This is rare (instance methods are seldom generic), and the
119
+ * alternative was worse: such a method was previously uncallable (TS2684). A
120
+ * generic method WITHOUT an explicit `this` is untouched (no-op) and keeps its
121
+ * generics; drop the `this` annotation if generic inference matters.
122
+ */
123
+ export type DocFacingMethods<M> = {
124
+ [K in keyof M]: OmitThisParameter<M[K]>;
125
+ };
126
+ export type GetModelTypeFromClass<T extends typeof BaseModel> = Model<OverriddenRawDoc<T>, // TRawDocType
33
127
  object, // TQueryHelpers
34
- ExtractProperty<T, 'modelInstanceMethods'>, // TInstanceMethods
128
+ DocFacingMethods<ExtractProperty<T, 'modelInstanceMethods'>>, // TInstanceMethods
35
129
  ExtractProperty<T, 'modelVirtuals'>, // TVirtuals
36
- HydratedDocument<InferRawDocType<ExtractProperty<T, 'modelSchema'> & WithTimestamps<Merge<typeof defaultOptions, ExtractProperty<T, 'schemaOptions'>>>>, //TRawDocType
37
- //TRawDocType
38
- VirtualType<ExtractProperty<T, 'modelVirtuals'>> & ExtractProperty<T, 'modelInstanceMethods'> & {
130
+ HydratedDocument<OverriddenRawDoc<T>, // TRawDocType
131
+ // TRawDocType
132
+ VirtualType<ExtractProperty<T, 'modelVirtuals'>> & DocFacingMethods<ExtractProperty<T, 'modelInstanceMethods'>> & {
39
133
  id: string;
40
- }, // TVirtuals & TInstanceMethods
134
+ }, // TVirtuals & TInstanceMethods (caller-facing `this` stripped)
41
135
  object, // TQueryHelpers
42
- ExtractProperty<T, 'modelVirtuals'>>, GetModelSchemaTypeFromClass<T>> & ExtractProperty<T, 'modelStatics'>;
43
- export type GetModelTypeLiteFromSchema<T extends typeof BaseModel.modelSchema, TOptions = object> = Model<InferRawDocType<T & WithTimestamps<Merge<typeof defaultOptions, TOptions>>>>;
136
+ VirtualType<ExtractProperty<T, 'modelVirtuals'>>>, GetModelSchemaTypeFromClass<T>> & ExtractProperty<T, 'modelStatics'>;
137
+ export type GetModelTypeLiteFromSchema<T extends typeof BaseModel.modelSchema, TOptions = object> = Model<MaybeApplyOverrides<InferRawDocType<T & WithTimestamps<Merge<typeof defaultOptions, TOptions>>>, T>>;
44
138
  export declare const defaultOptions: {
45
139
  readonly timestamps: true;
46
140
  readonly minimize: false;
@@ -55,3 +149,4 @@ export declare class BaseModel {
55
149
  static initHooks(_schema: Schema): void;
56
150
  static initialize<T extends typeof BaseModel>(this: T): GetModelTypeFromClass<T>;
57
151
  }
152
+ export {};
@@ -1 +1 @@
1
- {"version":3,"file":"BaseModel.js","sourceRoot":"","sources":["../../src/modules/BaseModel.ts"],"names":[],"mappings":"AAOA,OAAO,QAAQ,EAAE,EAAc,MAAM,UAAU,CAAC;AAgFhD,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAW,CAAC;AAG7E,gFAAgF;AAChF,MAAM,OAAO,SAAS;IACpB,MAAM,KAAK,WAAW;QACpB,OAAO,EAAW,CAAC;IACrB,CAAC;IAED,MAAM,KAAK,aAAa;QACtB,OAAO,EAAW,CAAC;IACrB,CAAC;IAED,MAAM,KAAK,oBAAoB;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,aAAa;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,YAAY;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,OAAe;QAC9B,iBAAiB;IACnB,CAAC;IAED,wDAAwD;IACjD,MAAM,CAAC,UAAU;QACtB,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE;YACnD,GAAG,cAAc;YACjB,GAAI,IAAI,CAAC,aAA+B;YACxC,OAAO,EAAE,IAAI,CAAC,oBAAoB;YAClC,OAAO,EAAE,IAAI,CAAC,YAAY;YAC1B,QAAQ,EAAE,IAAI,CAAC,aAAa;SAC7B,CAAmC,CAAC;QAErC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAEvB,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAClC,IAAI,CAAC,IAAI,EACT,MAAM,CACqB,CAAC;QAE9B,OAAO,aAAa,CAAC;IACvB,CAAC;CACF"}
1
+ {"version":3,"file":"BaseModel.js","sourceRoot":"","sources":["../../src/modules/BaseModel.ts"],"names":[],"mappings":"AAOA,OAAO,QAAQ,EAAE,EAAc,MAAM,UAAU,CAAC;AAiOhD,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAW,CAAC;AAG7E,gFAAgF;AAChF,MAAM,OAAO,SAAS;IACpB,MAAM,KAAK,WAAW;QACpB,OAAO,EAAW,CAAC;IACrB,CAAC;IAED,MAAM,KAAK,aAAa;QACtB,OAAO,EAAW,CAAC;IACrB,CAAC;IAED,MAAM,KAAK,oBAAoB;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,aAAa;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,YAAY;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,OAAe;QAC9B,iBAAiB;IACnB,CAAC;IAED,wDAAwD;IACjD,MAAM,CAAC,UAAU;QACtB,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE;YACnD,GAAG,cAAc;YACjB,GAAI,IAAI,CAAC,aAA+B;YACxC,OAAO,EAAE,IAAI,CAAC,oBAAoB;YAClC,OAAO,EAAE,IAAI,CAAC,YAAY;YAC1B,QAAQ,EAAE,IAAI,CAAC,aAAa;SAC7B,CAAmC,CAAC;QAErC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAEvB,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAClC,IAAI,CAAC,IAAI,EACT,MAAM,CACqB,CAAC;QAE9B,OAAO,aAAa,CAAC;IACvB,CAAC;CACF"}
@@ -10,10 +10,10 @@ export declare const setDefaultAuthToken: (tokenToSet: string) => void;
10
10
  export declare const getTestServerURL: (urlPart?: string) => string;
11
11
  export declare const createDefaultTestUser: () => Promise<false | {
12
12
  user: import("mongoose").Document<unknown, object, {
13
+ createdAt: NativeDate;
14
+ updatedAt: NativeDate;
13
15
  isVerified: boolean;
14
16
  locale: string;
15
- createdAt?: NativeDate | null | undefined;
16
- updatedAt?: NativeDate | null | undefined;
17
17
  name?: {
18
18
  first?: string | null | undefined;
19
19
  last?: string | null | undefined;
@@ -45,11 +45,11 @@ export declare const createDefaultTestUser: () => Promise<false | {
45
45
  languages?: string[] | null | undefined;
46
46
  } & {
47
47
  _id: import("mongoose").Types.ObjectId;
48
- }, {}, import("mongoose").DefaultSchemaOptions> & Omit<{
48
+ }, import("../modules/BaseModel.ts").VirtualType<{}>, import("mongoose").DefaultSchemaOptions> & Omit<{
49
+ createdAt: NativeDate;
50
+ updatedAt: NativeDate;
49
51
  isVerified: boolean;
50
52
  locale: string;
51
- createdAt?: NativeDate | null | undefined;
52
- updatedAt?: NativeDate | null | undefined;
53
53
  name?: {
54
54
  first?: string | null | undefined;
55
55
  last?: string | null | undefined;
@@ -85,7 +85,7 @@ export declare const createDefaultTestUser: () => Promise<false | {
85
85
  _id: import("mongoose").Types.ObjectId;
86
86
  }> & {
87
87
  __v: number;
88
- }, "id" | "generateToken" | "sendPasswordRecoveryEmail" | "sendVerificationEmail" | "getPublic"> & import("../modules/BaseModel.ts").VirtualType<{}> & {
88
+ }, "id" | "generateToken" | "sendPasswordRecoveryEmail" | "sendVerificationEmail" | "getPublic"> & import("../modules/BaseModel.ts").VirtualType<{}> & import("../modules/BaseModel.ts").DocFacingMethods<{
89
89
  readonly generateToken: (this: {
90
90
  email?: string | null;
91
91
  sessionTokens?: {
@@ -126,7 +126,7 @@ export declare const createDefaultTestUser: () => Promise<false | {
126
126
  permissions: string[] | null | undefined;
127
127
  locale: string;
128
128
  };
129
- } & {
129
+ }> & {
130
130
  id: string;
131
131
  } & {
132
132
  id: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adaptivestone/framework",
3
- "version": "5.0.0-rc.6",
3
+ "version": "5.0.0-rc.8",
4
4
  "description": "Adaptive stone node js framework",
5
5
  "type": "module",
6
6
  "engines": {