@onroad/core 4.0.0-alpha.1 → 4.0.0-alpha.2

package/README.md

@@ -2,7 +2,7 @@
 
 > TypeScript backend framework for multi-tenant Express APIs — DI Container, Filter Chain, EventBus, Provider Pattern.
 
-**v4.0.0-alpha.0** — Full TypeScript rewrite of the onRoad framework.
+**v4.0.0-alpha.1** — Full TypeScript rewrite of the onRoad framework.
 
 ---
 
@@ -27,6 +27,7 @@
 - [Graceful Shutdown](#graceful-shutdown)
 - [Testing](#testing)
 - [Subpath Exports](#subpath-exports)
+- [Known Pitfalls](#known-pitfalls)
 
 ---
 
@@ -665,6 +666,103 @@ import { StorageProvider } from "@onroad/core/storage"                 // Storag
 
 ---
 
+## Known Pitfalls
+
+### Controller base path must not be empty
+
+Always pass `/` or a non-empty path to `@Controller()`. An empty string is falsy and previously caused the route guard to **silently drop all routes** of that controller.
+
+```ts
+// ❌ Wrong — all routes silently skipped
+@Controller("")
+class UserController extends AbstractController<UserService> { ... }
+
+// ✅ Correct — root-level routes
+@Controller("/")
+class UserController extends AbstractController<UserService> { ... }
+
+// ✅ Correct — prefixed routes
+@Controller("/users")
+class UserController extends AbstractController<UserService> { ... }
+```
+
+> Since **v4.0.0-alpha.1** the path guard was tightened (`basePath === undefined || basePath === null`) and paths are normalized (`//auth` → `/auth`), so `@Controller("/")` + route `"/auth"` resolves correctly to `/auth` instead of `//auth`.
+
+---
+
+### Circular service dependencies
+
+When two services reference each other (e.g. `UserService ↔ CompanyService`), eager instantiation inside `configDependencies()` causes a `RangeError: Maximum call stack size exceeded` at startup because the constructors recurse infinitely.
+
+```ts
+// ❌ Wrong — infinite recursion on startup
+@Service()
+class UserService extends AbstractService<UserRepository> {
+  companySVC!: CompanyService
+
+  configDependencies() {
+    this.companySVC = new CompanyService() // → CompanyService() → new UserService() → ...
+  }
+}
+```
+
+Fix: replace the eager field with a **lazy getter**. The getter body only runs on first access, never during construction, which breaks the cycle:
+
+```ts
+// ✅ Correct — lazy getter breaks the circular chain
+@Service()
+class UserService extends AbstractService<UserRepository> {
+  private _companySVC?: CompanyService
+
+  protected get companySVC(): CompanyService {
+    if (!this._companySVC) this._companySVC = new CompanyService()
+    return this._companySVC
+  }
+}
+
+@Service()
+class CompanyService extends AbstractService<CompanyRepository> {
+  private _userSVC?: UserService
+
+  protected get userSVC(): UserService {
+    if (!this._userSVC) this._userSVC = new UserService()
+    return this._userSVC
+  }
+}
+```
+
+> **Why it was masked before**: the `if (!basePath)` bug meant controllers (and therefore services) were never instantiated during `buildServer()`. The circular dep crash only surfaced after fixing the route guard.
+
+---
+
+### Overriding `fullAssociation` in Repositories
+
+When using `@onroad/core`, the `@Repository` decorator automatically builds relations and injects the `fullAssociation` property populated with the appropriate Sequelize Models. Manually overriding this property in your repository class using raw ES classes will cause crashes during runtime (e.g., `TypeError: include.model.getTableName is not a function`) because Sequelize expects internal model objects, not raw classes.
+
+```ts
+// ❌ Wrong — overriding fullAssociation with raw ES classes crashes Sequelize
+@Repository({ entity: User })
+export class UserRepository extends BaseRepository<User> {
+  readonly fullAssociation = [{ model: FilterPref, as: "filters" }]
+}
+```
+
+**Fix:** Remove the hardcoded override. If you are extending a custom `BaseRepository` and need TypeScript to recognize the property without emitting an overriding value in the compiled JavaScript, use the `declare` modifier:
+
+```ts
+// ✅ Correct — Let the decorator inject the value and use `declare` for typings
+export abstract class BaseRepository<TEntity = unknown> extends SequelizeRepository<TEntity> {
+  declare readonly fullAssociation: any[] // Tells TS it exists without overriding it
+}
+
+@Repository({ entity: User })
+export class UserRepository extends BaseRepository<User> {
+  // No fullAssociation override here!
+}
+```
+
+---
+
 ## License
 
 UNLICENSED — HashCodeTI-Brasil

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onroad/core",
-  "version": "4.0.0-alpha.1",
-  "description": "TypeScript backend framework \u2014 DI Container, Filter Chain, EventBus, Provider Pattern",
+  "version": "4.0.0-alpha.2",
+  "description": "TypeScript backend framework — DI Container, Filter Chain, EventBus, Provider Pattern",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",