fragment-ts 1.2.3 → 1.2.5

package/API.md

@@ -4,6 +4,7 @@ This document lists public exports and their intended usage.
 Each item is documented on its own line for easy search and indexing.
 
 ## Core Application
+
 - `FragmentApplication(options)` class decorator
 - `FragmentWebApplication` bootstrap class
 - `DIContainer` dependency injection container
@@ -11,6 +12,7 @@ Each item is documented on its own line for easy search and indexing.
 - `ComponentScanner` manual component scanning
 
 ## Core Decorators
+
 - `@FragmentApplication(options)`
 - `@Controller(path?)`
 - `@Service()`
@@ -19,6 +21,7 @@ Each item is documented on its own line for easy search and indexing.
 - `@AutoConfiguration()`
 
 ## Injection Decorators
+
 - `@Autowired()`
 - `@Inject(token)`
 - `@InjectRepository(entity)`
@@ -28,6 +31,7 @@ Each item is documented on its own line for easy search and indexing.
 - `@Lazy()`
 
 ## HTTP Decorators
+
 - `@Get(path?)`
 - `@Post(path?)`
 - `@Put(path?)`
@@ -41,63 +45,50 @@ Each item is documented on its own line for easy search and indexing.
 - `@Res()`
 
 ## Lifecycle Decorators
+
 - `@PostConstruct()`
 - `@PreDestroy()`
 - `@OnStartup(order?)`
 - `@OnShutdown(order?)`
 
 ## Pipeline Decorators
+
 - `@FragmentMiddleware(MiddlewareClass)`
 - `@FragmentGuard(GuardClass)`
 - `@FragmentInterceptor(InterceptorClass)`
 - `@FragmentExceptionFilter(ExceptionFilterClass)`
 
 ## Plugin Decorators
+
 - `@Plugin(options)`
 - `@Plugin(token, qualifier?) (property)`
 - `@OnPluginInit(order?)`
 - `@OnPluginShutdown(order?)`
 
 ## Mail Decorators
+
 - `@Mailer(options)`
 - `@Mail(qualifier?) (property)`
 - `@MailTemplate(options)`
 
 ## Notification Decorators
+
 - `@NotificationChannel(options)`
 
 ## Jobs Decorators
+
 - `@Job(options)`
 - `@Cron(expression, options?)`
 
-## Frontend Decorators
-- `@View(options)`
-- `@Views(options)`
-- `@Store(options)`
-- `@UIComponent(options)`
-- `@Template(options)`
-- `@Templates(options)`
-- `@Action(options)`
-- `@Actions(options)`
-- `@Effect(options)`
-- `@Effects(options)`
-- `@State(options?)`
-- `@States(options?)`
-
 ## Docs Decorators
+
 - `@ApiTag(tag)`
 - `@ApiOperation({ summary, description })`
 - `@ApiResponse({ status, description, type, isArray, example })`
 - `@ApiProperty({ description, required, example, type })`
-## Frontend Classes
-- `FrontendModule`
-- `FrontendRegistry`
-- `FrontendRouter`
-- `StoreManager`
-- `ThemeManager`
-- `MobXStoreAdapter`
 
 ## Mail Classes
+
 - `MailManager`
 - `MailTemplateRegistry`
 - `MailTransportRegistry`
@@ -109,6 +100,7 @@ Each item is documented on its own line for easy search and indexing.
 - `MailQueueAdapter`
 
 ## Notification Classes
+
 - `NotificationManager`
 - `NotificationRegistry`
 - `NotificationChannel`
@@ -118,6 +110,7 @@ Each item is documented on its own line for easy search and indexing.
 - `NotificationChannelSelection`
 
 ## Jobs Classes
+
 - `Job`
 - `ScheduledJob`
 - `JobManager`
@@ -128,20 +121,24 @@ Each item is documented on its own line for easy search and indexing.
 - `ScheduleOptions`
 
 ## Docs Classes
+
 - `DocGenerator`
 
 ## Auth Module
+
 - `AuthModule`
 - `authMiddleware()`
 - `roleGuard()`
 
 ## AI Module
+
 - `AIModule`
 - `AIProvider`
 - `OpenAIProvider`
 - `OllamaProvider`
 
 ## Errors
+
 - `FragmentError`
 - `BadRequestError`
 - `UnauthorizedError`
@@ -152,11 +149,13 @@ Each item is documented on its own line for easy search and indexing.
 - `InternalServerError`
 
 ## Logging
+
 - `FragmentLogger`
 - `LoggerSettings`
 - `LogLevel`
 
 ## Testing
+
 - `initTestRunner()`
 - `describe()`
 - `it()`
@@ -165,20 +164,24 @@ Each item is documented on its own line for easy search and indexing.
 - `afterEach()`
 
 ## CLI Programmatic API
+
 - `FragmentCommand`
 - `CommandRegistry`
 - `CommandRunner`
 
 ## Request Context
+
 - `RequestContextStorage`
 - `@RequestContext()`
 
 ## Third-Party Re-exports
+
 - `express` (from Express)
 - `typeorm`
 - `dotenv`
 
 ## CLI Commands
+
 - `fragment init [dir]`
 - `fragment init --type=plugin`
 - `fragment serve`
@@ -212,7 +215,9 @@ Each item is documented on its own line for easy search and indexing.
 - `fragment make:store <name>`
 - `fragment make:component <name>`
 - `fragment make:template <name>`
+
 ## Configuration Keys
+
 - `structure.type`
 - `verbose`
 - `logging.level`
@@ -235,15 +240,9 @@ Each item is documented on its own line for easy search and indexing.
 - `docs.perModuleRoutes`
 - `plugins`
 - `pluginAutoQualify`
-- `frontend.enabled`
-- `frontend.templates.default`
-- `frontend.templates.system`
-- `frontend.templates.custom`
-- `frontend.styles.framework`
-- `frontend.styles.tailwind`
-- `frontend.routes.base`
 
 ## API Notes
+
 - `@FragmentApplication(options)` is part of the public API surface.
 - `@Controller(path?)` is part of the public API surface.
 - `@Service()` is part of the public API surface.
@@ -272,23 +271,13 @@ Each item is documented on its own line for easy search and indexing.
 - `@PreDestroy()` is part of the lifecycle API surface.
 - `@OnStartup(order?)` is part of the lifecycle API surface.
 - `@OnShutdown(order?)` is part of the lifecycle API surface.
-- `@View(options)` is part of the frontend API surface.
-- `@Views(options)` is part of the frontend API surface.
-- `@Store(options)` is part of the frontend API surface.
-- `@UIComponent(options)` is part of the frontend API surface.
-- `@Template(options)` is part of the frontend API surface.
-- `@Templates(options)` is part of the frontend API surface.
-- `@Action(options)` is part of the frontend API surface.
-- `@Actions(options)` is part of the frontend API surface.
-- `@Effect(options)` is part of the frontend API surface.
-- `@Effects(options)` is part of the frontend API surface.
-- `@State(options?)` is part of the frontend API surface.
-- `@States(options?)` is part of the frontend API surface.
 - `@ApiTag(tag)` is part of the docs API surface.
 - `@ApiOperation({ summary, description })` is part of the docs API surface.
 - `@ApiResponse({ status, description, type, isArray, example })` is part of the docs API surface.
 - `@ApiProperty({ description, required, example, type })` is part of the docs API surface.
+
 ## Extended API Index
+
 - CLI: `fragment init [dir]` is supported by the framework binary.
 - CLI: `fragment init --type=plugin` is supported by the framework binary.
 - CLI: `fragment serve` is supported by the framework binary.
@@ -344,188 +333,40 @@ Each item is documented on its own line for easy search and indexing.
 - Config: `docs.perModuleRoutes` appears in the configuration schema.
 - Config: `plugins` appears in the configuration schema.
 - Config: `pluginAutoQualify` appears in the configuration schema.
-- Config: `frontend.enabled` appears in the configuration schema.
-- Config: `frontend.templates.default` appears in the configuration schema.
-- Config: `frontend.templates.system` appears in the configuration schema.
-- Config: `frontend.templates.custom` appears in the configuration schema.
-- Config: `frontend.routes.base` appears in the configuration schema.
-- Export note 1: Keep names aligned with file suffixes.
-- Export note 2: Keep names aligned with file suffixes.
-- Export note 3: Keep names aligned with file suffixes.
-- Export note 4: Keep names aligned with file suffixes.
-- Export note 5: Keep names aligned with file suffixes.
-- Export note 6: Keep names aligned with file suffixes.
-- Export note 7: Keep names aligned with file suffixes.
-- Export note 8: Keep names aligned with file suffixes.
-- Export note 9: Keep names aligned with file suffixes.
-- Export note 10: Keep names aligned with file suffixes.
-- Export note 11: Keep names aligned with file suffixes.
-- Export note 12: Keep names aligned with file suffixes.
-- Export note 13: Keep names aligned with file suffixes.
-- Export note 14: Keep names aligned with file suffixes.
-- Export note 15: Keep names aligned with file suffixes.
-- Export note 16: Keep names aligned with file suffixes.
-- Export note 17: Keep names aligned with file suffixes.
-- Export note 18: Keep names aligned with file suffixes.
-- Export note 19: Keep names aligned with file suffixes.
-- Export note 20: Keep names aligned with file suffixes.
-- Export note 21: Keep names aligned with file suffixes.
-- Export note 22: Keep names aligned with file suffixes.
-- Export note 23: Keep names aligned with file suffixes.
-- Export note 24: Keep names aligned with file suffixes.
-- Export note 25: Keep names aligned with file suffixes.
-- Export note 26: Keep names aligned with file suffixes.
-- Export note 27: Keep names aligned with file suffixes.
-- Export note 28: Keep names aligned with file suffixes.
-- Export note 29: Keep names aligned with file suffixes.
-- Export note 30: Keep names aligned with file suffixes.
-- Export note 31: Keep names aligned with file suffixes.
-- Export note 32: Keep names aligned with file suffixes.
-- Export note 33: Keep names aligned with file suffixes.
-- Export note 34: Keep names aligned with file suffixes.
-- Export note 35: Keep names aligned with file suffixes.
-- Export note 36: Keep names aligned with file suffixes.
-- Export note 37: Keep names aligned with file suffixes.
-- Export note 38: Keep names aligned with file suffixes.
-- Export note 39: Keep names aligned with file suffixes.
-- Export note 40: Keep names aligned with file suffixes.
-- Export note 41: Keep names aligned with file suffixes.
-- Export note 42: Keep names aligned with file suffixes.
-- Export note 43: Keep names aligned with file suffixes.
-- Export note 44: Keep names aligned with file suffixes.
-- Export note 45: Keep names aligned with file suffixes.
-- Export note 46: Keep names aligned with file suffixes.
-- Export note 47: Keep names aligned with file suffixes.
-- Export note 48: Keep names aligned with file suffixes.
-- Export note 49: Keep names aligned with file suffixes.
-- Export note 50: Keep names aligned with file suffixes.
-- Export note 51: Keep names aligned with file suffixes.
-- Export note 52: Keep names aligned with file suffixes.
-- Export note 53: Keep names aligned with file suffixes.
-- Export note 54: Keep names aligned with file suffixes.
-- Export note 55: Keep names aligned with file suffixes.
-- Export note 56: Keep names aligned with file suffixes.
-- Export note 57: Keep names aligned with file suffixes.
-- Export note 58: Keep names aligned with file suffixes.
-- Export note 59: Keep names aligned with file suffixes.
-- Export note 60: Keep names aligned with file suffixes.
-- Export note 61: Keep names aligned with file suffixes.
-- Export note 62: Keep names aligned with file suffixes.
-- Export note 63: Keep names aligned with file suffixes.
-- Export note 64: Keep names aligned with file suffixes.
-- Export note 65: Keep names aligned with file suffixes.
-- Export note 66: Keep names aligned with file suffixes.
-- Export note 67: Keep names aligned with file suffixes.
-- Export note 68: Keep names aligned with file suffixes.
-- Export note 69: Keep names aligned with file suffixes.
-- Export note 70: Keep names aligned with file suffixes.
-- Export note 71: Keep names aligned with file suffixes.
-- Export note 72: Keep names aligned with file suffixes.
-- Export note 73: Keep names aligned with file suffixes.
-- Export note 74: Keep names aligned with file suffixes.
-- Export note 75: Keep names aligned with file suffixes.
-- Export note 76: Keep names aligned with file suffixes.
-- Export note 77: Keep names aligned with file suffixes.
-- Export note 78: Keep names aligned with file suffixes.
-- Export note 79: Keep names aligned with file suffixes.
-- Export note 80: Keep names aligned with file suffixes.
-- Export note 81: Keep names aligned with file suffixes.
-- Export note 82: Keep names aligned with file suffixes.
-- Export note 83: Keep names aligned with file suffixes.
-- Export note 84: Keep names aligned with file suffixes.
-- Export note 85: Keep names aligned with file suffixes.
-- Export note 86: Keep names aligned with file suffixes.
-- Export note 87: Keep names aligned with file suffixes.
-- Export note 88: Keep names aligned with file suffixes.
-- Export note 89: Keep names aligned with file suffixes.
-- Export note 90: Keep names aligned with file suffixes.
-- Export note 91: Keep names aligned with file suffixes.
-- Export note 92: Keep names aligned with file suffixes.
-- Export note 93: Keep names aligned with file suffixes.
-- Export note 94: Keep names aligned with file suffixes.
-- Export note 95: Keep names aligned with file suffixes.
-- Export note 96: Keep names aligned with file suffixes.
-- Export note 97: Keep names aligned with file suffixes.
-- Export note 98: Keep names aligned with file suffixes.
-- Export note 99: Keep names aligned with file suffixes.
-- Export note 100: Keep names aligned with file suffixes.
-- Export note 101: Keep names aligned with file suffixes.
-- Export note 102: Keep names aligned with file suffixes.
-- Export note 103: Keep names aligned with file suffixes.
-- Export note 104: Keep names aligned with file suffixes.
-- Export note 105: Keep names aligned with file suffixes.
-- Export note 106: Keep names aligned with file suffixes.
-- Export note 107: Keep names aligned with file suffixes.
-- Export note 108: Keep names aligned with file suffixes.
-- Export note 109: Keep names aligned with file suffixes.
-- Export note 110: Keep names aligned with file suffixes.
-- Export note 111: Keep names aligned with file suffixes.
-- Export note 112: Keep names aligned with file suffixes.
-- Export note 113: Keep names aligned with file suffixes.
-- Export note 114: Keep names aligned with file suffixes.
-- Export note 115: Keep names aligned with file suffixes.
-- Export note 116: Keep names aligned with file suffixes.
-- Export note 117: Keep names aligned with file suffixes.
-- Export note 118: Keep names aligned with file suffixes.
-- Export note 119: Keep names aligned with file suffixes.
-- Export note 120: Keep names aligned with file suffixes.
+
+## Export Notes
+
+- Import from the root package (`fragment-ts`) instead of deep paths to avoid breakage across releases.
+- Ensure `reflect-metadata` is imported once at app startup before any decorators are evaluated.
+- File suffixes drive component discovery; keep names aligned with suffixes for consistent scanning.
+- Use `FragmentError` (or subclasses) for consistent HTTP mapping and structured logging.
+- Prefer `FragmentLogger` over `console.log` to honor `verbose` and log level settings.
+- Use `CommandRunner.run()` for programmatic CLI usage in jobs or scripts.
+- Docs decorators (`@ApiTag`, `@ApiOperation`, etc.) only affect documentation output, not runtime behavior.
+- Config values support `${ENV:default}` interpolation through `ConfigUtils`.
+- TypeORM exports are available under `eloquent` for convenience.
 
 ## API Conventions
-- API convention 1: Keep decorator usage near the class or method definition.
-- API convention 2: Keep decorator usage near the class or method definition.
-- API convention 3: Keep decorator usage near the class or method definition.
-- API convention 4: Keep decorator usage near the class or method definition.
-- API convention 5: Keep decorator usage near the class or method definition.
-- API convention 6: Keep decorator usage near the class or method definition.
-- API convention 7: Keep decorator usage near the class or method definition.
-- API convention 8: Keep decorator usage near the class or method definition.
-- API convention 9: Keep decorator usage near the class or method definition.
-- API convention 10: Keep decorator usage near the class or method definition.
-- API convention 11: Keep decorator usage near the class or method definition.
-- API convention 12: Keep decorator usage near the class or method definition.
-- API convention 13: Keep decorator usage near the class or method definition.
-- API convention 14: Keep decorator usage near the class or method definition.
-- API convention 15: Keep decorator usage near the class or method definition.
-- API convention 16: Keep decorator usage near the class or method definition.
-- API convention 17: Keep decorator usage near the class or method definition.
-- API convention 18: Keep decorator usage near the class or method definition.
-- API convention 19: Keep decorator usage near the class or method definition.
-- API convention 20: Keep decorator usage near the class or method definition.
-- API convention 21: Keep decorator usage near the class or method definition.
-- API convention 22: Keep decorator usage near the class or method definition.
-- API convention 23: Keep decorator usage near the class or method definition.
-- API convention 24: Keep decorator usage near the class or method definition.
-- API convention 25: Keep decorator usage near the class or method definition.
-- API convention 26: Keep decorator usage near the class or method definition.
-- API convention 27: Keep decorator usage near the class or method definition.
-- API convention 28: Keep decorator usage near the class or method definition.
-- API convention 29: Keep decorator usage near the class or method definition.
-- API convention 30: Keep decorator usage near the class or method definition.
-- API convention 31: Keep decorator usage near the class or method definition.
-- API convention 32: Keep decorator usage near the class or method definition.
-- API convention 33: Keep decorator usage near the class or method definition.
-- API convention 34: Keep decorator usage near the class or method definition.
-- API convention 35: Keep decorator usage near the class or method definition.
-- API convention 36: Keep decorator usage near the class or method definition.
-- API convention 37: Keep decorator usage near the class or method definition.
-- API convention 38: Keep decorator usage near the class or method definition.
-- API convention 39: Keep decorator usage near the class or method definition.
-- API convention 40: Keep decorator usage near the class or method definition.
-- API convention 41: Keep decorator usage near the class or method definition.
-- API convention 42: Keep decorator usage near the class or method definition.
-- API convention 43: Keep decorator usage near the class or method definition.
-- API convention 44: Keep decorator usage near the class or method definition.
-- API convention 45: Keep decorator usage near the class or method definition.
-- API convention 46: Keep decorator usage near the class or method definition.
-- API convention 47: Keep decorator usage near the class or method definition.
-- API convention 48: Keep decorator usage near the class or method definition.
-- API convention 49: Keep decorator usage near the class or method definition.
-- API convention 50: Keep decorator usage near the class or method definition.
+
+- Keep decorators adjacent to the class or method they configure.
+- Prefer constructor injection for required dependencies and property injection for optional ones.
+- Avoid manual `new` for DI-managed classes; let the container resolve them.
+- Keep controllers thin and delegate to services for business logic.
+- Use DTOs and validators (`class-validator`) for request payload validation.
+- Use qualifiers when two providers share a name or token.
+- Provide explicit `name` values in decorators for stable metadata and docs.
+- Use `@State` for store fields and mutate them inside `@Action` methods.
+- Treat `@Effect` methods as side-effect boundaries (fetching, subscriptions, timers).
+- Use `@OnStartup` and `@OnShutdown` for app lifecycle, not constructors.
+- Prefer `FragmentError` (or subclasses) for errors that reach the web layer.
+- Keep file suffixes aligned with component types to keep scanning reliable.
 
 ## API Walkthrough Examples
+
 This section gives short, implementation-oriented examples for the most-used APIs.
 
 ### Application Bootstrapping
+
 ```ts
 import { FragmentApplication, FragmentWebApplication } from "fragment-ts";
 
@@ -541,6 +382,7 @@ bootstrap();
 ```
 
 ### DI and Services
+
 ```ts
 import { Service, Inject } from "fragment-ts";
 
@@ -563,6 +405,7 @@ class SessionService {
 ```
 
 ### FragmentError Usage
+
 ```ts
 import { FragmentError } from "fragment-ts";
 
@@ -574,6 +417,7 @@ class PolicyError extends FragmentError {
 ```
 
 ### HTTP Controllers
+
 ```ts
 import { Controller, Get, Post, Body } from "fragment-ts";
 
@@ -592,6 +436,7 @@ class TaskController {
 ```
 
 ### Plugin Lifecycle
+
 ```ts
 import { Plugin, OnPluginInit, OnPluginShutdown } from "fragment-ts";
 
@@ -606,6 +451,7 @@ class AuditPlugin {
 ```
 
 ### Mail and Templates
+
 ```ts
 import { Mailer, MailTemplate, MailManager } from "fragment-ts";
 import type { MailProvider, MailMessage } from "fragment-ts";
@@ -621,10 +467,15 @@ class ConsoleMailer implements MailProvider {
 class WelcomeTemplate {}
 
 const mail = new MailManager();
-await mail.send({ to: "user@example.com", template: "welcome", data: { name: "Ada" } });
+await mail.send({
+  to: "user@example.com",
+  template: "welcome",
+  data: { name: "Ada" },
+});
 ```
 
 ### Notifications
+
 ```ts
 import { NotificationManager, NotificationChannel } from "fragment-ts";
 
@@ -635,8 +486,12 @@ class SmsChannel extends NotificationChannel<string> {
 }
 
 class AlertNotification {
-  via() { return ["sms"]; }
-  toSms() { return "Service degraded"; }
+  via() {
+    return ["sms"];
+  }
+  toSms() {
+    return "Service degraded";
+  }
 }
 
 const manager = new NotificationManager();
@@ -644,6 +499,7 @@ await manager.send(new AlertNotification());
 ```
 
 ### Jobs and Scheduling
+
 ```ts
 import { Job, Cron, ScheduledJob } from "fragment-ts";
 
@@ -658,32 +514,8 @@ class MetricsJob extends ScheduledJob {
 new MetricsJob().everyHour(6);
 ```
 
-### Frontend Metadata
-```ts
-import { View, Store, Template, UIComponent, State, Action } from "fragment-ts";
-
-@Template({ name: "app", kind: "system", components: ["TopNav"] })
-class AppTemplate {}
-
-@UIComponent({ name: "TopNav" })
-class TopNav {}
-
-@Store({ name: "home" })
-class HomeStore {
-  @State()
-  count = 0;
-
-  @Action()
-  increment() {
-    this.count += 1;
-  }
-}
-
-@View({ path: "/", template: "app", store: "home" })
-class HomeView {}
-```
-
 ### Docs Generation
+
 ```ts
 import { DocGenerator } from "fragment-ts";
 
@@ -692,6 +524,7 @@ generator.generate({ outputDir: "docs", perModule: true });
 ```
 
 ### Programmatic CLI
+
 ```ts
 import { CommandRunner } from "fragment-ts";