cabloy 5.1.50 → 5.1.52

package/cabloy-docs/backend/crud-workflow.md

@@ -0,0 +1,118 @@
+# CRUD Workflow
+
+This guide explains the Vona CRUD generator workflow in the Cabloy monorepo.
+
+## Why this page matters
+
+CRUD is one of the clearest places where Cabloy’s CLI-first philosophy pays off.
+
+Instead of creating controller, service, model, entity, DTO, metadata, locale, and test files by hand, Vona already provides generators that create the initial backend thread.
+
+## Generate a CRUD skeleton
+
+Example: generate a CRUD workflow for `student` in module `demo-student`.
+
+```bash
+npm run vona :tools:crud student -- --module=demo-student
+```
+
+A lighter variant also exists:
+
+```bash
+npm run vona :tools:crudBasic student -- --module=demo-student
+```
+
+This is important because the repo already encodes both the full CRUD thread and a lighter CRUD-basic workflow in the CLI surface.
+
+## Generated structure
+
+The generator creates a connected set of files, typically including:
+
+- controller
+- service
+- model
+- entity
+- create/update DTOs
+- meta version and index files
+- locale files
+- tests
+
+This is exactly why this generator should be the default starting point. It gives a consistent starting shape across the backend thread.
+
+A practical generated-output checklist usually includes:
+
+- controller
+- service
+- model
+- entity
+- create/update DTOs
+- `meta.version`
+- locale assets
+- test file
+- package-version update for the next schema step
+
+That checklist is useful because it makes the generated thread easier to inspect after the CLI run instead of treating CRUD generation as a black box.
+
+## The generated backend thread
+
+The CRUD generator is not a shortcut around the architecture. It instantiates the same backend contract loop documented elsewhere.
+
+A practical thread is:
+
+1. controller exposes the HTTP contract
+2. service owns orchestration
+3. model owns persistence behavior
+4. entity defines the field/data contract
+5. DTOs define operation-specific request/response contracts
+6. meta.version handles schema lifecycle
+7. tests verify the resulting contract through action execution
+
+Read this guide together with:
+
+- [Controller Guide](/backend/controller-guide)
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [DTO Guide](/backend/dto-guide)
+- [Migration and Changes](/backend/migration-and-changes)
+- [Unit Testing](/backend/unit-testing)
+
+## Recommended workflow
+
+1. run the CRUD generator
+2. inspect the generated files
+3. refine entity, DTO, model, service, and controller behavior for the real business case
+4. verify routes, model behavior, migration behavior, and tests
+
+A practical expectation is that the generated test should already help verify the full contract thread rather than only file existence. In other words, generation should leave you with something that can immediately participate in CRUD-oriented action testing, migration verification, and later OpenAPI/frontend contract refinement.
+
+This is the preferred path because it preserves framework conventions first, then applies domain-specific refinement second.
+
+## When to keep generated defaults vs refine them manually
+
+A practical rule is:
+
+- keep generated defaults when the backend thread already matches the business shape
+- refine the generated code when response contracts, DTO behavior, controller metadata, model behavior, or test flow need stronger domain-specific semantics
+- avoid replacing the generated thread wholesale unless the framework shape truly does not fit the use case
+
+## Relationship to DTO inference and OpenAPI
+
+The generated thread is also part of the broader contract-emission path.
+
+That means generated entity, DTO, controller, and validation structure can feed:
+
+- backend OpenAPI output
+- DTO inference and generation
+- frontend SDK generation
+
+For the cross-stack side of this loop, also see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+## Generated workflow checklist
+
+When you see a request like “create a student CRUD” or “scaffold backend resources,” the correct default should be:
+
+1. inspect the Vona CLI
+2. use `:tools:crud` or `:tools:crudBasic` if one matches the need
+3. modify the generated output instead of hand-building the whole thread from scratch
+4. verify the resulting migration, controller, and test path instead of stopping at file creation

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

@@ -0,0 +1,161 @@
+# DTO Guide
+
+This guide explains how DTOs work in Vona within the Cabloy monorepo.
+
+## Why DTOs matter
+
+DTOs are not only transport classes. In Vona, they are part of one contract system shared across:
+
+- validation
+- OpenAPI metadata
+- serializer-facing response shape
+- model-aware DTO inference
+- frontend-facing generated contracts
+
+That is why DTO design should be treated as a framework concern instead of only a controller-local convenience.
+
+## Create a DTO
+
+Example: create a DTO named `studentCreate` in module `demo-student`.
+
+```bash
+npm run vona :create:bean dto studentCreate -- --module=demo-student
+```
+
+## DTO definition
+
+Representative pattern:
+
+```typescript
+@Dto<IDtoOptionsStudentCreate>()
+export class DtoStudentCreate {}
+```
+
+## DTOs in the backend contract loop
+
+DTOs are the most explicit named contracts in the backend contract loop.
+
+A useful split is:
+
+- entities define reusable field/data structure close to persistence
+- DTOs define explicit request/response contract artifacts
+- inferred DTOs reduce duplication when the model/query shape is already strong enough
+
+Read this guide together with:
+
+- [Entity Guide](/backend/entity-guide)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+- [Validation Guide](/backend/validation-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+
+## `@Api.field`
+
+DTO field definitions use the same `@Api.field` mental model as entities.
+
+That means DTOs can express:
+
+- validation rules
+- field metadata
+- OpenAPI-facing schema information
+- serializer-oriented response metadata when needed
+
+For response-shaping behavior built on the same field metadata surface, see [Serialization Guide](/backend/serialization-guide).
+
+Representative pattern:
+
+```typescript
+class DtoStudentCreate {
+  @Api.field(v.title($locale('Name')), v.min(3))
+  name: string;
+
+  @Api.field(v.title($locale('Description')), v.optional())
+  description?: string;
+}
+```
+
+## DTO options
+
+Three especially important DTO option areas are:
+
+- `independent`
+- `openapi`
+- `fields`
+
+These options make DTOs configurable as reusable schema objects, not just local TypeScript classes.
+
+A useful ownership rule is:
+
+- DTO metadata defines the contract shape close to the class
+- app config can still override broader DTO behavior
+- inference tools can reduce how much hand-authored DTO code is needed
+
+## App-config override support
+
+DTO options can also be configured through app config.
+
+That matters because the DTO layer participates in the broader framework configuration system instead of being fully hardcoded in one file.
+
+## Mapped class tools
+
+One of the most valuable DTO topics is reuse through mapped-class helpers.
+
+Representative tools include:
+
+- `$Class.pick`
+- `$Class.partial`
+- `$Class.omit`
+- `$Class.mixin`
+
+These let you derive DTOs from existing entities or DTOs instead of re-declaring the same field sets repeatedly.
+
+## Operation-specific DTO thinking
+
+A practical way to think about DTO families is by operation shape.
+
+Common operation families include:
+
+- create DTOs
+- update DTOs
+- get DTOs
+- list-and-count DTOs
+- query DTOs
+- query-page DTOs
+- aggregate DTOs
+- group DTOs
+
+Some of these are hand-authored DTO classes. Others are better expressed through Vona’s inference helpers.
+
+The important point is not to force every operation shape into one generic DTO when the framework already distinguishes them more precisely.
+
+## Explicit DTOs vs inferred DTOs
+
+A practical split is:
+
+- use explicit DTO classes when the contract needs a stable named artifact
+- use inferred DTOs when the contract closely follows model structure or query shape
+- wrap inferred DTOs in a named DTO class when reuse or discoverability becomes more important
+
+For the inference side, see [DTO Infer and Generation](/backend/dto-infer-generation).
+
+## Relationship to ORM and controller contracts
+
+DTOs sit between backend data structure and backend API contracts.
+
+That means DTO design should often be read together with:
+
+- [Model Guide](/backend/model-guide)
+- [Relations Guide](/backend/relations-guide)
+- [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Controller Guide](/backend/controller-guide)
+
+## Implementation checks for DTO changes
+
+When creating DTOs:
+
+1. prefer reuse through mapped-class helpers when the shape is derived from existing classes
+2. keep DTO validation and OpenAPI concerns aligned through `@Api.field`
+3. decide whether the contract should be an explicit DTO class or an inferred DTO
+4. avoid re-declaring fields manually if Vona’s DTO-generation or class-derivation tools already solve the problem
+5. treat DTO design as part of the contract between backend handlers, models, and frontend integration
+6. choose explicit DTOs when named long-lived contracts matter, and inferred DTOs when the model/query shape already expresses the contract clearly

package/cabloy-docs/backend/dto-infer-generation.md

@@ -0,0 +1,153 @@
+# DTO Infer and Generation
+
+This guide explains how DTO inference and generation work in Vona within the Cabloy monorepo.
+
+## Why DTO inference matters
+
+DTOs are essential for validation and OpenAPI metadata, but manually maintaining them becomes expensive and error-prone as models and relationships grow more complex.
+
+Vona addresses that by dynamically inferring and generating DTOs from model structure and query shape.
+
+## DTO tools
+
+Several DTO-oriented tools are available, including:
+
+- `$Dto.get`
+- `$Dto.listAndCount`
+- `$Dto.query`
+- `$Dto.queryPage`
+- `$Dto.create`
+- `$Dto.update`
+- `$Dto.aggregate`
+- `$Dto.group`
+
+These tools let DTOs emerge from model-aware structure instead of always being hand-authored from scratch.
+
+## When each inferred DTO shape is useful
+
+A practical mental model is:
+
+- use `$Dto.get` for one-item read contracts
+- use `$Dto.listAndCount` for paginated or list-plus-total contracts
+- use `$Dto.query` and `$Dto.queryPage` for query-input or query-result patterns
+- use `$Dto.create` and `$Dto.update` for write contracts derived from model structure
+- use `$Dto.aggregate` and `$Dto.group` for summary-oriented result shapes
+
+This matters because different ORM operations naturally produce different API contracts.
+
+## When inference should replace handwritten DTOs
+
+A practical rule is:
+
+- prefer inferred DTOs when the contract closely follows model structure or query shape
+- prefer explicit DTO classes when the contract is long-lived, heavily customized, or needs a strong named public identity
+- wrap inferred DTOs into named DTO classes when reuse becomes more important than one-off convenience
+
+This is one of the most important distinctions in the backend contract loop.
+
+## Main-details example
+
+A representative example uses an `Order -> Product` relation.
+
+The key lesson is that when the return shape is richer than a simple entity array, an inferred DTO can capture the actual result shape more accurately than a hand-waved entity annotation.
+
+Representative pattern:
+
+```typescript
+@Api.body(v.array($Dto.get(() => ModelOrder, { include: { products: true } })))
+```
+
+This shows the dynamic DTO layer participating directly in controller return contracts.
+
+Another useful inferred pattern is action-derived contract reuse:
+
+```typescript
+@Web.get('getUserDynamic')
+@Api.body($Dto.get('test-vona:post'))
+getPostDynamic() {}
+```
+
+This is especially useful when a controller wants to expose the same contract shape that the model/action thread already defines elsewhere.
+
+## Relation-aware inference
+
+DTO inference becomes especially powerful when the result shape depends on relations.
+
+Examples include:
+
+- static relations loaded through `include`
+- dynamic relations loaded through `with`
+- grouped or aggregated related substructures
+
+That means DTO inference should often be considered together with relation design rather than only after the fact.
+
+A representative relation-aware response pattern is:
+
+```typescript
+@Api.body(v.array($Dto.get(() => ModelOrder, { include: { products: true } })))
+```
+
+A practical rule is:
+
+- keep inference inline when one action needs one contract shape only once
+- wrap the inferred DTO into a named DTO class when the same relation-aware shape becomes part of a reusable public contract
+
+## Aggregate and group DTO inference
+
+Summary-oriented ORM queries often benefit from inferred DTOs because the result shape is driven by `aggrs`, `groups`, and relation configuration.
+
+A practical rule is:
+
+- if the summary shape comes directly from ORM query structure, inference is often the cleanest option
+- if the same summary contract is reused broadly, wrap the inferred DTO into a named DTO class
+
+For the query side of this topic, also see [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide).
+
+## Relationship to CRUD generation
+
+Inferred DTOs are not separate from the CRUD workflow. They sit on the same contract loop.
+
+A useful split is:
+
+- CRUD generation gives you the initial backend thread
+- explicit DTOs give you stable named operation contracts
+- inferred DTOs let the contract stay close to model and query truth when a separate handwritten class would add little value
+
+This helps keep the generated thread productive instead of forcing redundant DTO maintenance everywhere.
+
+## Encapsulating inferred DTOs
+
+Inferred DTO logic can also be wrapped inside an explicit DTO class for reuse.
+
+That is useful because it gives teams a spectrum of options:
+
+- use inference directly for one endpoint
+- wrap the inferred DTO into a named reusable class when the contract is important elsewhere too
+
+## Relationship to generation and metadata refresh
+
+DTO inference and generation are not isolated authoring tricks. They are part of a broader backend contract workflow.
+
+When model, relation, or controller contracts change, remember to consider the downstream metadata and generated-contract path as well.
+
+Read this guide together with:
+
+- [DTO Guide](/backend/dto-guide)
+- [Relations Guide](/backend/relations-guide)
+- [ORM Select Guide](/backend/orm-select-guide)
+- [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+## Implementation checks for DTO inference and generation changes
+
+When evaluating a return shape or input contract that closely follows model structure, ask:
+
+1. should this DTO be inferred instead of handwritten?
+2. does model relationship structure already contain enough information?
+3. is the contract get/list/query/create/update/aggregate/group oriented?
+4. should the inferred DTO stay inline or be wrapped in a named DTO class?
+5. does the resulting DTO also affect OpenAPI and frontend generation paths?
+6. is CRUD generation already giving enough contract structure that another handwritten DTO would be redundant?
+
+That helps reduce redundant type work and keeps contracts closer to the model truth.

package/cabloy-docs/backend/dynamic-datasource-guide.md

@@ -0,0 +1,70 @@
+# Dynamic Datasource Guide
+
+This guide points from the backend docs to the deeper Cabloy dynamic-datasource architecture.
+
+## Current source of truth
+
+This page is intentionally a backend-facing pointer page rather than a full standalone tutorial.
+
+The older ORM page for dynamic datasource is intentionally brief because the deeper capability is provided by the `a-cabloy` suite.
+
+In the new docs structure, treat dynamic datasource as a Cabloy-level capability with strong backend implications.
+
+## Why this matters
+
+Dynamic datasource selection affects:
+
+- how model operations are routed
+- how related queries are resolved
+- how transactions and cache behavior should be coordinated
+- how queue and distributed flows should remain datasource-safe
+- how multi-tenant or multi-project data architectures can be organized
+
+So this is not only an implementation tweak. It is part of the system architecture.
+
+## Do not confuse three different routing layers
+
+A useful distinction is:
+
+- **ordinary datasource selection** can live in model metadata or app config
+- **isolated-instance routing** can change the effective default datasource through instance config such as `isolateClient` and is primarily explained in [Multi-Database and Datasource Guide](/backend/multi-database-datasource) together with [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution)
+- **dynamic datasource** begins when the routing decision depends on runtime context that cannot be declared once up front
+
+This distinction matters because many backend tasks do not actually need dynamic datasource.
+
+## When a task becomes truly dynamic
+
+A practical rule is:
+
+- static datasource choice can live in model metadata or app config
+- relation-level datasource choice can live in relation metadata
+- instance-sensitive default routing can live in instance config
+- dynamic datasource begins when routing depends on live context beyond those declarative mechanisms
+
+That helps avoid overusing dynamic datasource when ordinary datasource configuration is sufficient.
+
+## Guidance for contributors and AI workflows
+
+When a task mentions dynamic datasource behavior, do not stop at ordinary model configuration.
+
+Instead:
+
+1. identify whether the routing decision is static, relation-level, instance-sensitive, model-level, or truly dynamic
+2. inspect the Cabloy-level datasource architecture and source code
+3. verify whether transactions, cache, relation loading, and queue behavior still align with the datasource routing strategy
+4. confirm that instance isolation or app-config defaults are not already enough for the task
+
+## Relationship to the broader ORM family
+
+Read this guide together with:
+
+- [Config Guide](/backend/config-guide)
+- [Model Guide](/backend/model-guide)
+- [Multi-Database and Datasource Guide](/backend/multi-database-datasource)
+- [Relations Guide](/backend/relations-guide)
+- [Queue Guide](/backend/queue-guide)
+- [Sharding Guide](/backend/sharding-guide)
+
+## Documentation placement rule
+
+Keep this page as the backend-facing pointer, but treat the Cabloy-level dynamic-datasource material as the deeper source of truth.

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

@@ -0,0 +1,141 @@
+# Election Guide
+
+## Why election matters
+
+In a distributed backend, multiple worker processes may all be capable of running the same logic, but some responsibilities should be owned only by one worker or by a small fixed number of workers.
+
+Vona provides election for exactly that scenario.
+
+This matters when backend code needs to:
+
+- start a standalone service
+- own a leader-like runtime responsibility
+- recover ownership automatically when a worker exits
+- allow limited parallel ownership instead of full fan-out execution
+
+## Core election model
+
+The election model works like this:
+
+1. workers compete to obtain ownership of a named resource
+2. one worker, or a configured number of workers, acquires that ownership
+3. only the worker that obtains ownership starts the protected logic
+4. if an owning worker exits, other workers compete again and ownership can move automatically
+
+That makes election a coordination primitive, not just a boolean lock.
+
+## Create `meta.election`
+
+Example: create `meta.election` in module `demo-student`.
+
+```bash
+npm run vona :create:bean meta election -- --module=demo-student
+```
+
+Representative definition:
+
+```typescript
+export type TypeElectionObtainResource = 'echo';
+
+@Meta()
+export class MetaElection extends BeanElectionBase<TypeElectionObtainResource> {}
+```
+
+The resource type expresses which logical resources can be competed for inside the module.
+
+## Obtain ownership from a module monkey
+
+Election usually participates in backend lifecycle hooks rather than ordinary request handlers.
+
+Representative pattern:
+
+```typescript
+export class Monkey extends BeanSimple implements IMonkeyAppStarted {
+  async appStarted() {
+    const scope = this.app.scope(__ThisModule__);
+    scope.election.obtain(
+      'echo',
+      () => {
+        // custom logic
+      },
+      async () => {
+        // cleanup
+      },
+    );
+  }
+}
+```
+
+A useful mental model is:
+
+- `appStarted()` is where the backend decides to compete for ownership
+- `obtain(...)` starts the owned logic only on the worker that wins
+- the cleanup callback releases or cleans up local resources when ownership ends
+
+## Tickets: allow more than one owner
+
+Sometimes one owner is too restrictive, but full broadcast fan-out is too broad.
+
+In that case, election supports `tickets`:
+
+```typescript
+scope.election.obtain(
+  'echo',
+  () => {
+    // custom logic
+  },
+  async () => {
+    // cleanup
+  },
+  { tickets: 2 },
+);
+```
+
+A practical interpretation is:
+
+- `tickets: 1` means one owner
+- `tickets: 2` means two workers may own the same resource simultaneously
+
+This makes election useful for limited parallel ownership patterns.
+
+## When to use election vs queue vs broadcast
+
+Read this guide together with:
+
+- [Backend Startup Guide](/backend/startup-guide)
+- [Queue Guide](/backend/queue-guide)
+- [Broadcast Guide](/backend/broadcast-guide)
+- [Worker Guide](/backend/worker-guide)
+- [Redlock Guide](/backend/redlock-guide)
+
+A practical boundary is:
+
+- use **election** when only one worker, or a fixed small number of workers, should own the responsibility
+- use **queue** when work should be pushed asynchronously to background execution
+- use **broadcast** when many workers should all receive the message
+
+This distinction is important because these abstractions solve different distributed coordination problems.
+
+## Relationship to startup lifecycle
+
+Election often starts from backend startup hooks.
+
+That means a common pattern is:
+
+1. backend startup reaches `appStarted`
+2. the module competes for an election resource
+3. the winning worker starts the protected service or loop
+4. ownership can fail over to another worker if the current owner exits
+
+So startup answers _when lifecycle hooks fire_, while election answers _which worker should own a singleton-like responsibility_.
+
+## Implementation checks for distributed-election changes
+
+When editing distributed backend coordination, ask:
+
+1. is this really a singleton-like ownership problem?
+2. should one worker own the responsibility, or should there be multiple tickets?
+3. does the ownership logic belong in backend startup hooks rather than a request path?
+4. would queue or broadcast be the wrong abstraction for this job?
+
+That helps AI choose election only when the underlying coordination problem truly matches it.