@onroad/core 4.0.0-alpha.15 → 4.0.0-alpha.16

package/README.md

@@ -930,6 +930,70 @@ export class UserRepository extends BaseRepository<User> {
 
 ---
 
+### `import type` with relationship decorators
+
+TypeScript's `import type` is erased at compile time. If you use `import type { Foo }` and then reference `Foo` as a **runtime value** inside a decorator like `@HasMany(() => Foo, ...)`, the compiled JavaScript will throw `ReferenceError: Foo is not defined` because the import was stripped.
+
+```ts
+// ❌ Wrong — import type is erased, decorator callback fails at runtime
+import type { CampoDeVerificacao } from "./CampoDeVerificacao.js"
+
+@Entity("caderno", { engine: "sequelize" })
+export class CadernoDeVerificacao {
+  @HasMany(() => CampoDeVerificacao, "cadernoId") // 💥 ReferenceError
+  campos!: CampoDeVerificacao[]
+}
+```
+
+Fix: use a regular `import` for any class referenced inside a decorator callback:
+
+```ts
+// ✅ Correct — regular import keeps the binding at runtime
+import { CampoDeVerificacao } from "./CampoDeVerificacao.js"
+
+@Entity("caderno", { engine: "sequelize" })
+export class CadernoDeVerificacao {
+  @HasMany(() => CampoDeVerificacao, "cadernoId")
+  campos!: CampoDeVerificacao[]
+}
+```
+
+> **Tip:** `import type` is safe for type annotations and generics (`extends AbstractService<Foo>`), but never for decorator arguments, `instanceof`, or any expression evaluated at runtime.
+
+---
+
+### `emitDecoratorMetadata` causes TDZ errors with circular entity imports
+
+When `emitDecoratorMetadata: true` is set in `tsconfig.json`, TypeScript emits `__metadata("design:type", CampoDeVerificacao)` for decorated properties. This accesses the imported class **at class definition time**. If two entities import each other (circular dependency), ESM module evaluation order causes a **Temporal Dead Zone (TDZ)** error:
+
+```
+ReferenceError: Cannot access 'CampoDeVerificacao' before initialization
+```
+
+The `@HasMany(() => Foo, ...)` arrow function is lazy (only called later by `wireSequelizeAssociations`), but `__metadata("design:type", Foo)` is **eager** — it runs during class definition.
+
+```jsonc
+// ❌ Wrong — causes TDZ crash in circular ESM imports
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true  // 💥
+  }
+}
+```
+
+Fix: disable `emitDecoratorMetadata`. @onroad/core uses only custom metadata keys (`METADATA_KEY.ENTITY`, `ENTITY_COLUMNS`, etc.) and does **not** rely on `design:type`, `design:paramtypes`, or `design:returntype`.
+
+```jsonc
+// ✅ Correct — no TDZ, decorators still work
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": false
+  }
+}
+```
+
 ---
 
 ## Migration Guide — Lessons Learned (v3 → v4)

package/dist/database/ConnectionManager.d.ts

@@ -5,6 +5,7 @@ export interface DatabaseConfig {
     password?: string;
     database?: string;
     prefix?: string;
+    suffix?: string;
     uri?: string;
     pool?: {
         max?: number;

package/dist/database/ConnectionManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConnectionManager.d.ts","sourceRoot":"","sources":["../../src/database/ConnectionManager.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE;QACL,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE,MAAM,CAAA;KACd,CAAA;CACF;AAED,8BAAsB,iBAAiB,CAAC,WAAW;IACjD,SAAS,CAAC,WAAW,2BAAiC;IACtD,SAAS,CAAC,MAAM,EAAE,cAAc,CAAA;gBAEpB,MAAM,EAAE,cAAc;IAIlC,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAEjF,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAElC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;IAS/D,SAAS,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;CAI3E"}
+{"version":3,"file":"ConnectionManager.d.ts","sourceRoot":"","sources":["../../src/database/ConnectionManager.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE;QACL,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE,MAAM,CAAA;KACd,CAAA;CACF;AAED,8BAAsB,iBAAiB,CAAC,WAAW;IACjD,SAAS,CAAC,WAAW,2BAAiC;IACtD,SAAS,CAAC,MAAM,EAAE,cAAc,CAAA;gBAEpB,MAAM,EAAE,cAAc;IAIlC,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAEjF,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAElC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;IAS/D,SAAS,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;CAM3E"}

package/dist/database/ConnectionManager.js

@@ -18,7 +18,11 @@ export class ConnectionManager {
     resolveDatabaseName(tenant, dataSource) {
         if (this.config.database)
             return this.config.database;
-        return dataSource ?? `${this.config.prefix}_${tenant}`;
+        if (dataSource)
+            return dataSource;
+        if (this.config.suffix)
+            return `${tenant}_${this.config.suffix}`;
+        return `${this.config.prefix}_${tenant}`;
     }
 }
 //# sourceMappingURL=ConnectionManager.js.map

package/dist/database/ConnectionManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"ConnectionManager.js","sourceRoot":"","sources":["../../src/database/ConnectionManager.ts"],"names":[],"mappings":"AAgBA,MAAM,OAAgB,iBAAiB;IAC3B,WAAW,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC5C,MAAM,CAAgB;IAEhC,YAAY,MAAsB;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAQD,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAA;IAC9B,CAAC;IAES,QAAQ,CAAC,MAAc,EAAE,UAAmB;QACpD,0EAA0E;QAC1E,uEAAuE;QACvE,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAA;QACpF,CAAC;QACD,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;IACxD,CAAC;IAES,mBAAmB,CAAC,MAAc,EAAE,UAAmB;QAC/D,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAA;QACrD,OAAO,UAAU,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,EAAE,CAAA;IACxD,CAAC;CACF"}
+{"version":3,"file":"ConnectionManager.js","sourceRoot":"","sources":["../../src/database/ConnectionManager.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAgB,iBAAiB;IAC3B,WAAW,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC5C,MAAM,CAAgB;IAEhC,YAAY,MAAsB;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAQD,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAA;IAC9B,CAAC;IAES,QAAQ,CAAC,MAAc,EAAE,UAAmB;QACpD,0EAA0E;QAC1E,uEAAuE;QACvE,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAA;QACpF,CAAC;QACD,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;IACxD,CAAC;IAES,mBAAmB,CAAC,MAAc,EAAE,UAAmB;QAC/D,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAA;QACrD,IAAI,UAAU;YAAE,OAAO,UAAU,CAAA;QACjC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAA;QAChE,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,EAAE,CAAA;IAC1C,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onroad/core",
-  "version": "4.0.0-alpha.15",
+  "version": "4.0.0-alpha.16",
   "description": "TypeScript backend framework — DI Container, Filter Chain, EventBus, Provider Pattern",
   "type": "module",
   "main": "dist/index.js",