cabloy 5.1.50 → 5.1.52

package/cabloy-docs/backend/entity-guide.md

@@ -0,0 +1,150 @@
+# Entity Guide
+
+This guide explains how entities work in Vona within the Cabloy monorepo.
+
+## Why entities matter in the contract loop
+
+Entities are not only persistence records. In Vona, they also participate in validation, OpenAPI metadata, serializer-facing response shape, and downstream DTO design.
+
+That makes entity design one of the main places where database structure and API contract structure meet.
+
+## Create an entity
+
+Example: create an entity named `student` in module `demo-student`.
+
+```bash
+npm run vona :create:bean entity student -- --module=demo-student
+```
+
+## Entity definition
+
+Representative pattern:
+
+```typescript
+@Entity<IEntityOptionsStudent>('demoStudent')
+export class EntityStudent extends EntityBase {}
+```
+
+The entity defines the table-oriented data shape that the model layer works with.
+
+## Entities in the backend contract loop
+
+Entities sit at an important boundary:
+
+- models bind to entities
+- DTOs can reuse entity field structure
+- validation can infer schema from entity field declarations
+- OpenAPI metadata can be emitted from the same field surface
+
+Read this guide together with:
+
+- [Model Guide](/backend/model-guide)
+- [DTO Guide](/backend/dto-guide)
+- [Validation Guide](/backend/validation-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+
+## Table-name convention
+
+Vona’s modular system needs a safe table-naming convention to reduce conflicts.
+
+General pattern:
+
+```text
+tableName = moduleName + entityName
+```
+
+If the entity name duplicates the module name, Vona removes the duplicate fragment.
+
+This convention matters because AI systems should not invent arbitrary table names when the framework already has a stable naming model.
+
+## `@Api.field` as the shared contract surface
+
+A key Vona idea is that entity fields can simultaneously express:
+
+- field type
+- validation rules
+- OpenAPI metadata
+- serializer-oriented response metadata
+
+That is why entity fields are centered around `@Api.field`.
+
+Representative pattern:
+
+```typescript
+class EntityStudent {
+  @Api.field()
+  name: string;
+}
+```
+
+This is one of the strongest backend-contract-loop ideas: the same field definition can drive runtime validation and machine-readable API description without duplicating the contract in several places.
+
+## Automatic schema inference
+
+If the field type is a basic type, DTO, or entity, Vona can automatically infer the corresponding schema and OpenAPI output.
+
+Representative automatically inferred types include:
+
+- `string`
+- `number`
+- `boolean`
+- DTO classes
+- Entity classes
+
+This matters because entity design is not only about persistence columns. It also affects how much explicit schema authoring you need later.
+
+## Explicit schema extension
+
+When inference is not enough, you can extend the field definition with richer schema and metadata.
+
+Representative examples include:
+
+- explicit schema rules such as `z.number().min(18)`
+- helpers such as `v.default`, `v.optional`, `v.array`
+- OpenAPI metadata such as `v.title`, `v.description`, `v.example`, `v.openapi`
+
+A practical rule is:
+
+- use inference for straightforward fields
+- add explicit schema or metadata only where the contract really needs more detail
+
+## Entity options
+
+Important entity-option areas include:
+
+- `table`
+- `independent`
+- `openapi`
+- `fields`
+
+These options matter because the entity can influence not only table mapping but also how the entity appears in the machine-readable contract layer.
+
+## App-config overrides
+
+Entity options can also be configured through app config.
+
+This matters because entity-facing contract metadata can be refined at the project level without rewriting the entity class directly.
+
+## Base class and identity type
+
+By default, entities inherit from `EntityBase`, which provides common fields such as:
+
+- `id`
+- `createdAt`
+- `updatedAt`
+- `deleted`
+- `iid`
+
+The `id` field uses `TableIdentity`, which supports both string and number representations depending on the configured identity strategy.
+
+That matters because contract types should not assume a narrower identity shape than the backend actually supports.
+
+## Implementation checks for entity changes
+
+When creating or updates entities:
+
+1. preserve Vona table-naming conventions unless there is a deliberate reason to override them
+2. use `@Api.field` rather than scattering schema and metadata concerns inconsistently
+3. keep validation, OpenAPI, serializer, and entity structure aligned
+4. remember that entities feed DTO, model, and OpenAPI workflows downstream
+5. keep identity and base-field assumptions consistent with the actual backend contract loop

package/cabloy-docs/backend/error-guide.md

@@ -0,0 +1,108 @@
+# Error Guide
+
+## Why error matters as a backend scope resource
+
+In Vona, module errors are not only thrown values. They are part of a module-scoped resource model that connects error codes, localized messages, and cross-module reuse.
+
+That matters because backend contracts often need errors that are:
+
+- typed by convention
+- localized through module locale resources
+- reusable through module scope
+- override-friendly at the project level when wording changes are needed
+
+## Initialize the error skeleton
+
+Example: initialize error resources for module `demo-student`.
+
+```bash
+npm run vona :init:error demo-student
+```
+
+This gives the module the standard files for defining error codes and their language resources.
+
+## Define module errors
+
+Defining an error takes two main steps.
+
+### 1. Define the error codes
+
+Representative pattern:
+
+```typescript
+export const errors = {
+  ErrorTest: 1001,
+} as const;
+```
+
+A useful convention is that business error codes should stay above `1000`.
+
+### 2. Define the localized error messages
+
+Representative locale pattern:
+
+```typescript
+export default {
+  ErrorTest: 'This is a error test',
+};
+```
+
+This is the key architectural point: the error definition and the localized wording are related, but they live in separate resources.
+
+## Use error within the current module
+
+The current module’s errors can be reached through scope.
+
+Representative pattern:
+
+```typescript
+this.scope.error.ErrorTest.throw();
+```
+
+## Use error across modules
+
+Cross-module error access uses the cross-module scope surface.
+
+Representative pattern:
+
+```typescript
+this.$scope.demoStudent.error.ErrorTest.throw();
+```
+
+A practical distinction is:
+
+- `this.scope.error` for the current module
+- `this.$scope.<module>.error` for another module
+
+## Relationship to locale resources
+
+Module errors are closely connected to module locale resources.
+
+That means this guide should be read together with [I18n Guide](/backend/i18n-guide).
+
+A useful ownership rule is:
+
+- the error code defines the backend exception identity
+- locale resources define the user-facing or developer-facing wording
+- scope makes both available through the module resource model
+
+## Relationship to backend essentials
+
+Errors are one of the clearest examples of why backend scope matters.
+
+Read this guide together with:
+
+- [Backend Essentials](/backend/backend-essentials)
+- [Backend Foundation](/backend/foundation)
+- [I18n Guide](/backend/i18n-guide)
+
+## Implementation checks for backend error-handling changes
+
+When editing backend error behavior, ask:
+
+1. should this error be defined as a module-scoped error instead of an inline throw?
+2. does the error need localized wording in locale resources?
+3. should the error be consumed from the current module or across modules?
+4. is the existing module error skeleton the right place to extend instead of inventing a separate error pattern?
+
+That helps AI keep backend error handling aligned with Vona’s module-resource model and localization system.

package/cabloy-docs/backend/event-guide.md

@@ -0,0 +1,183 @@
+# Event Guide
+
+## Why events matter in Vona
+
+Vona provides a framework-native event mechanism so backend code can publish extensible business signals without hardwiring every downstream action into one method body.
+
+That matters because registration, activation, auditing, notifications, and other backend workflows often need layered reactions that should remain composable.
+
+## Core event model
+
+Vona’s event system is built around two concepts:
+
+- **event**
+- **event listener**
+
+An event can have multiple listeners, and listeners execute with an onion-style chaining model.
+
+That means listeners can:
+
+- observe the event
+- modify the event data before passing it onward
+- wrap the next listener or default method
+- contribute to the final result
+
+## Event definition
+
+An event is defined as a typed bean.
+
+Representative generation workflow:
+
+```bash
+npm run vona :create:bean event echo -- --module=demo-student
+```
+
+Representative pattern:
+
+```typescript
+export type TypeEventEchoData = string;
+export type TypeEventEchoResult = string | undefined;
+
+@Event()
+export class EventEcho extends BeanEventBase<TypeEventEchoData, TypeEventEchoResult> {}
+```
+
+This makes event payload and result types part of the framework model instead of untyped side-channel data.
+
+## Emitting events
+
+### Asynchronous emit
+
+```typescript
+const result = await this.scope.event.echo.emit('Hello World');
+```
+
+### Synchronous emit
+
+```typescript
+const result = this.scope.event.echo.emitSync('Hello World');
+```
+
+## Default method support
+
+Both `emit` and `emitSync` can accept a default method.
+
+Representative pattern:
+
+```typescript
+const result = await this.scope.event.echo.emit('Hello World', async data => {
+  return `default: ${data}`;
+});
+```
+
+The default method receives the latest event data after listener processing, which is important because listeners can transform the payload before passing it onward.
+
+## Event listener definition
+
+Event listeners attach through `@EventListener({ match: ... })`.
+
+Representative generation workflow:
+
+```bash
+npm run vona :create:bean eventListener echo -- --module=demo-student
+```
+
+Representative pattern:
+
+```typescript
+@EventListener({ match: 'demo-student:echo' })
+export class EventListenerEcho implements IEventExecute<TypeEventData, TypeEventResult> {
+  execute(data: TypeEventData, next: NextEventSync<TypeEventData, TypeEventResult>) {
+    const dataNew = `${data}!`;
+    return next(dataNew);
+  }
+}
+```
+
+This pattern shows the key ideas:
+
+- listeners match one or more named events
+- listeners can transform event data
+- listeners pass control onward through `next(...)`
+
+A practical typing rule is to import the event’s data/result types into the listener instead of redefining them independently, so the event contract stays coupled at the type level while remaining decoupled at the execution level.
+
+## Event ordering
+
+Multiple listeners can attach to the same event.
+
+Vona supports execution ordering through:
+
+- `dependencies`
+- `dependents`
+
+That allows event listener chains to stay explicit instead of relying on accidental load order.
+
+A useful rule of thumb is:
+
+- use `dependencies` when another listener must run before the current one
+- use `dependents` when the current listener must run before another named listener
+
+## Enable/disable and runtime scope
+
+Event listeners can be controlled through:
+
+- app-config enable/disable
+- `mode`
+- `flavor`
+
+This is important because some event-driven behavior should only apply in certain environments.
+
+## Inspection
+
+Vona can inspect the effective event-listener list for a named event.
+
+Representative pattern:
+
+```typescript
+this.bean.onion.eventListener.inspectEventListener('demo-student:echo');
+```
+
+This is useful for debugging event composition and verifying which listeners are active.
+
+That inspect step is especially valuable before changing ordering metadata, because it lets you confirm the effective chain first instead of guessing from module load order.
+
+## Relationship to user-access workflows
+
+The event model is especially important in user-access flows.
+
+Representative examples include:
+
+- registration events
+- activation events
+- post-registration follow-up such as email confirmation
+- role-assignment follow-up logic
+
+Mail delivery is a common downstream effect in these flows; see [Mail Guide](/backend/mail-guide).
+
+Read this together with [User Access Guide](/backend/user-access-guide) when the event flow is tied to identity lifecycle behavior.
+
+## When to use events instead of direct calls
+
+Use events when:
+
+- one business action may need multiple follow-up behaviors
+- extension logic should remain decoupled from the initiating method
+- you want project-level customization without rewriting the original flow
+
+Use direct calls when:
+
+- the behavior is tightly bound to the core logic and should not be extensible as a chain
+
+A practical example from the user-access layer is registration and activation: the core user flow can stay small, while follow-up concerns such as mail confirmation or role assignment move into listeners.
+
+## Implementation checks for event-driven backend changes
+
+When editing event-driven backend behavior, ask:
+
+1. should this be an event instead of a direct call chain?
+2. is the payload/result shape already captured by an existing typed event?
+3. does the workflow need synchronous or asynchronous event emission?
+4. should listener ordering, enable/disable, or runtime environment rules be explicit?
+
+That helps AI keep extension logic aligned with Vona’s event model instead of embedding it into unrelated service methods.

package/cabloy-docs/backend/external-aop-guide.md

@@ -0,0 +1,149 @@
+# External AOP Guide
+
+## Why external AOP matters
+
+External AOP lets Vona attach behavior to another class from the outside without editing that class directly.
+
+This matters when the extension logic should remain decoupled from the target class source while still participating in the framework’s typed bean model.
+
+## Core model
+
+External AOP uses `@Aop({ match: ... })` to associate an aspect class with one or more target classes by bean name.
+
+Representative CLI generation pattern:
+
+```bash
+npm run vona :create:bean aop log -- --module=demo-student
+```
+
+Representative shape:
+
+```typescript
+@Aop({ match: 'demo-student.service.test' })
+export class AopLog extends BeanAopBase {}
+```
+
+The `match` option determines which classes the external aspect applies to.
+
+## What external AOP can intercept
+
+External AOP can extend:
+
+- synchronous methods
+- asynchronous methods
+- getters
+- setters
+- `__init__`
+- `__dispose__`
+- generic method dispatch through `__method__`
+- magic-method style behavior such as `__get__` and `__set__`
+
+## Representative method interception
+
+### Synchronous method
+
+```typescript
+actionSync: AopAction<ServiceTest, 'actionSync'> = (_args, next) => {
+  const timeBegin = Date.now();
+  const res = next();
+  const timeEnd = Date.now();
+  console.log('actionSync: ', timeEnd - timeBegin);
+  return res;
+};
+```
+
+### Asynchronous method
+
+```typescript
+actionAsync: AopAction<ServiceTest, 'actionAsync'> = async (_args, next) => {
+  const timeBegin = Date.now();
+  const res = await next();
+  const timeEnd = Date.now();
+  console.log('actionAsync: ', timeEnd - timeBegin);
+  return res;
+};
+```
+
+## Getter and setter interception
+
+External AOP can also wrap property access:
+
+```typescript
+protected __get_name__: AopActionGetter<ServiceTest, 'name'> = function (next) {
+  const value = next();
+  return value;
+};
+
+protected __set_name__: AopActionSetter<ServiceTest, 'name'> = function (value, next) {
+  return next(value);
+};
+```
+
+This is especially useful when you want to observe or constrain property access without moving that concern into the target class source.
+
+## Lifecycle interception
+
+You can extend lifecycle hooks such as:
+
+- `__init__`
+- `__dispose__`
+
+That allows setup and teardown behavior to be wrapped externally when needed.
+
+## Generic magic-method interception
+
+External AOP also supports broader interception points such as:
+
+- `__get__`
+- `__set__`
+- `__method__`
+
+This makes it possible to add dynamic behavior such as custom virtual properties or broad method-level logging without editing the target class source.
+
+## Ordering and runtime controls
+
+External AOP supports the same kinds of runtime controls seen elsewhere in Vona:
+
+- `dependencies`
+- `dependents`
+- enable/disable
+- `mode`
+- `flavor`
+- inspection of the effective AOP list
+
+Representative inspect pattern:
+
+```typescript
+this.bean.onion.aop.inspect();
+```
+
+That becomes especially helpful when more than one external aspect matches the same target bean and you need to confirm the effective chain before changing ordering metadata.
+
+## When to use external AOP instead of internal AOP
+
+Use this rule of thumb:
+
+- use **internal AOP** when the behavior belongs naturally inside the target class or its decorator surface
+- use **external AOP** when the behavior should be attached from outside by bean match and remain decoupled from the target class definition
+
+A good concrete signal for external AOP is when one extension should apply to an existing service or bean without forcing that bean to import new decorators or framework logic just to host the concern.
+
+## Relationship to internal AOP
+
+External AOP and internal AOP solve similar extension problems, but with different ownership models:
+
+- **internal AOP** decorates the class from within its own source
+- **external AOP** attaches behavior from the outside by match
+
+Read this page together with [Internal AOP Guide](/backend/internal-aop-guide).
+
+## Questions for external AOP changes
+
+When extending a backend class, ask:
+
+1. should this behavior live in the class source or outside it?
+2. is the target identified more naturally by bean name matching?
+3. does the extension need to intercept methods, accessors, lifecycle hooks, or magic-method behavior?
+4. does ordering or runtime environment control matter for this aspect?
+
+That helps AI choose a Vona-native extension model instead of patching behavior manually into unrelated code.

package/cabloy-docs/backend/field-indexes.md

@@ -0,0 +1,79 @@
+# Field Indexes
+
+This guide explains how field indexes work in Vona within the Cabloy monorepo.
+
+## Why field indexes are a first-class concept
+
+Vona provides a framework-level mechanism for declaring field indexes and having the system create them automatically.
+
+That is important because indexing is not treated as an afterthought. It is part of module metadata.
+
+## `meta.index`
+
+Vona uses a bean named `meta.index` to configure a module’s field indexes.
+
+Create it with:
+
+```bash
+npm run vona :create:bean meta index -- --module=demo-student
+```
+
+Representative shell:
+
+```typescript
+@Meta()
+export class MetaIndex extends BeanBase {}
+```
+
+## Configure indexes: direct style
+
+Representative pattern:
+
+```typescript
+@Meta({
+  indexes: {
+    demoStudent: 'name',
+  },
+})
+class MetaIndex {}
+```
+
+This expresses:
+
+- table name
+- field name or field-name list
+
+## Configure indexes: typed style
+
+A typed style is also supported:
+
+```typescript
+import { $tableColumns } from 'vona-module-a-ormutils';
+
+@Meta({
+  indexes: {
+    ...$tableColumns('demoStudent', 'name'),
+  },
+})
+class MetaIndex {}
+```
+
+This is especially valuable for maintainability because it reduces stringly-typed drift.
+
+## App-config override support
+
+Field indexes can also be configured through app config.
+
+That means index behavior participates in the broader configuration system rather than being locked into one metadata file only.
+
+## Implementation checks for persistence changes
+
+When changing persistence design, do not stop at entity fields and model methods.
+
+Also ask:
+
+1. does this access pattern need an index?
+2. should the index belong in `meta.index`?
+3. is the typed style a better fit than raw string declarations?
+
+That leads to backend changes that are more production-aware and more aligned with Vona’s module metadata model.