cabloy 5.1.49 → 5.1.51

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

@@ -0,0 +1,118 @@
+# OpenAPI Guide
+
+This guide explains how OpenAPI works in Vona within the Cabloy monorepo.
+
+## Why OpenAPI matters in Cabloy
+
+OpenAPI is one of the main fullstack contract bridges between Vona and Zova.
+
+The backend emits machine-readable contract metadata, and the frontend can consume that metadata through generated SDKs, schema-driven behavior, and API tooling.
+
+That is why OpenAPI belongs in the core Cabloy knowledge graph rather than in an isolated backend appendix.
+
+The same field metadata surface also connects naturally to response serialization; see [Serialization Guide](/backend/serialization-guide).
+
+## OpenAPI in the backend contract loop
+
+A useful split is:
+
+- controllers define request and response contracts
+- DTOs and entities provide schema and metadata surfaces
+- validation contributes runtime constraints and inferred schema
+- OpenAPI emits the machine-readable contract from those backend declarations
+- frontend SDK generation is a downstream consumer of that emitted contract
+
+This distinction matters because backend authoring and frontend consumption are related, but not the same step.
+
+## Built-in endpoints
+
+Several built-in endpoints are available, including:
+
+- Swagger UI
+- OpenAPI JSON output
+- versioned OpenAPI JSON output
+- RapiDoc
+
+This makes the contract easy to inspect both manually and programmatically.
+
+## `bean.openapi`
+
+Vona provides a global bean for OpenAPI-related generation tasks.
+
+Representative capabilities include generating JSON for:
+
+- a specific DTO class
+- multiple DTO classes
+- the entire system
+- a specific controller action
+
+This is important because OpenAPI is treated as a first-class framework service, not as an external afterthought.
+
+## Validation and OpenAPI are linked
+
+A major theme is that the same validation-oriented declaration surface also drives OpenAPI metadata generation.
+
+That means:
+
+- inferred schemas can become OpenAPI metadata
+- explicit schema rules can become OpenAPI metadata
+- `v` helper extensions can enrich OpenAPI output
+
+This tight linkage is one of the reasons the Cabloy contract story can stay productive at scale.
+
+## Controllers, DTOs, entities, and examples all contribute
+
+OpenAPI output is not owned by one layer only.
+
+In practice, the emitted contract can be influenced by:
+
+- controller route and action metadata
+- request-parameter decorators
+- response schema declarations and wrapper behavior
+- DTO field metadata and options
+- entity field metadata and options
+- validation rules and helper extensions
+- examples, titles, descriptions, and related metadata
+
+That is why contract changes should often be reviewed across several backend pages, not only in one file.
+
+## I18n support
+
+OpenAPI metadata can also participate in i18n.
+
+That is useful because contract descriptions and titles are not only for machines. They are also developer-facing assets. For the broader locale/timezone and localization model behind this, see [I18n Guide](/backend/i18n-guide).
+
+## Configuration
+
+The OpenAPI behavior is configurable through the `a-openapi` module config.
+
+This matters because API contract output is part of the application configuration surface, not a fixed global constant.
+
+## Relationship to frontend SDK generation
+
+OpenAPI emission on the backend is the backend-contract-loop side of a broader fullstack contract bridge.
+
+For the downstream bridge and consumption path, also see:
+
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+
+A practical split is:
+
+- this page explains backend contract authoring and emission
+- the fullstack page explains the bridge from emitted OpenAPI to generated frontend SDK
+- the frontend page explains how Zova consumes that contract in its own workflows
+
+## Implementation checks for backend contract changes
+
+When changing backend contracts, ask:
+
+1. does this change affect Swagger/OpenAPI output?
+2. do the controller, DTO, entity, and validation layers still agree on the contract?
+3. does the frontend SDK or schema-driven frontend behavior need to be regenerated?
+4. should metadata such as title, description, or examples be improved at the same time?
+5. is this a place where validation and OpenAPI should be edited together rather than separately?
+
+That helps keep the backend/frontend contract loop coherent.
+
+Upload-oriented endpoints often combine multipart request handling with explicit response metadata such as `@Api.contentType('application/json')`; see [Upload Guide](/backend/upload-guide).

package/cabloy-docs/backend/orm-aggregate-group-guide.md

@@ -0,0 +1,210 @@
+# ORM Aggregate and Group Guide
+
+## Why aggregate and group matter
+
+Many backend queries do not need raw rows only. They need derived results such as counts, sums, averages, grouped totals, or grouped summaries attached to related records.
+
+Vona ORM provides aggregate and group operations as typed model-level capabilities rather than forcing every summary query into ad hoc SQL.
+
+## `count`
+
+The simplest aggregate is `count`.
+
+Representative pattern:
+
+```typescript
+const total = await this.scope.model.post.count();
+```
+
+A count operation can still depend on:
+
+- `column`
+- `distinct`
+- `where`
+- `joins`
+
+So even the simplest summary query still participates in the wider ORM query model.
+
+## `aggregate`
+
+Use `aggregate` when the query should return one summary object.
+
+Representative pattern:
+
+```typescript
+const result = await this.scope.model.post.aggregate({
+  aggrs: {
+    count: ['*', 'stars'],
+    sum: 'stars',
+    avg: 'stars',
+    min: 'stars',
+    max: 'stars',
+  },
+});
+```
+
+A useful mental model is:
+
+- `aggrs` declares which aggregate functions should run
+- Vona infers the returned shape from the aggregate declaration
+- `aggregate` returns one summary object rather than grouped rows
+
+Representative parameter areas include:
+
+- `aggrs`
+- `distinct`
+- `where`
+- `joins`
+
+## `group`
+
+Use `group` when the query should return grouped rows instead of one summary object.
+
+Representative pattern:
+
+```typescript
+const result = await this.scope.model.post.group({
+  groups: 'userId',
+  aggrs: {
+    count: '*',
+    sum: 'stars',
+  },
+});
+```
+
+Representative parameter areas include:
+
+- `groups`
+- `columns`
+- `aggrs`
+- `distinct`
+- `where`
+- `joins`
+- `limit`
+- `offset`
+- `having`
+- `orders`
+
+This matters because grouped results are still part of the structured ORM query language, not a separate unmanaged SQL world.
+
+A practical result-shape distinction is:
+
+- `aggregate` returns one summary object
+- `group` returns grouped rows keyed by the chosen group columns and aggregate aliases
+
+## `having` and grouped ordering
+
+Grouped queries often need filtering and ordering on derived fields.
+
+Representative pattern:
+
+```typescript
+const result = await this.scope.model.post.group({
+  groups: 'userId',
+  aggrs: {
+    count: '*',
+    sum: 'stars',
+  },
+  having: {
+    count_all: {
+      _gt_: 20,
+    },
+    sum_stars: {
+      _gt_: 30,
+      _lt_: 50,
+    },
+  },
+  orders: [['count_all', 'desc']],
+});
+```
+
+This is one of the reasons aggregate/group deserves dedicated documentation instead of being hidden inside a basic select page.
+
+A practical alias rule is:
+
+- aggregate aliases such as `count_all` and `sum_stars` become the names used in `having` and grouped ordering
+
+That is also why grouped or summary outputs often deserve explicit DTO treatment once they become stable API contracts.
+
+## Aggregate and group on relations
+
+Aggregate and group are not limited to top-level model queries. They can also participate in relations.
+
+### Dynamic relation example
+
+Representative aggregate-on-relation pattern:
+
+```typescript
+const users = await this.scope.model.user.select({
+  with: {
+    posts: $relationDynamic.hasMany('test-vona:post', 'userId', {
+      aggrs: {
+        count: '*',
+        sum: 'stars',
+      },
+    }),
+  },
+});
+```
+
+Representative group-on-relation pattern:
+
+```typescript
+const users = await this.scope.model.user.select({
+  with: {
+    posts: $relationDynamic.hasMany('test-vona:post', 'userId', {
+      groups: 'id',
+      aggrs: {
+        count: '*',
+        sum: 'stars',
+      },
+    }),
+  },
+});
+```
+
+### Static relation example
+
+Representative static relation pattern:
+
+```typescript
+@Model({
+  entity: EntityUser,
+  relations: {
+    posts: $relation.hasMany('test-vona:post', 'userId', {
+      aggrs: {
+        count: '*',
+        sum: 'stars',
+      },
+    }),
+  },
+})
+class ModelUserStats {}
+```
+
+That means summary-shaped relations can still be expressed through model metadata instead of living outside the ORM relation system.
+
+## Relationship to select and relations
+
+Read this guide together with:
+
+- [ORM Select Guide](/backend/orm-select-guide)
+- [Relations Guide](/backend/relations-guide)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+
+A practical split is:
+
+- use the select guide for row-oriented query structure and operators
+- use this guide when the result shape is aggregate- or group-oriented
+- use the relations guide when the summary is attached through relation metadata or dynamic relations
+
+## Implementation checks for aggregate and grouped query changes
+
+When editing summary-oriented backend queries, ask:
+
+1. is this a row-oriented select, a one-object aggregate, or a grouped result set?
+2. should the summary live at the top level or inside a relation?
+3. do `having` and derived-field ordering belong in the group definition?
+4. should DTO inference or OpenAPI output reflect the summary shape explicitly?
+
+That helps AI keep statistical and reporting queries aligned with Vona’s typed ORM model.

package/cabloy-docs/backend/orm-configuration-guide.md

@@ -0,0 +1,165 @@
+# ORM Configuration Guide
+
+## Why ORM configuration matters
+
+Vona ORM is not only shaped by model code. It is also shaped by framework-level configuration in the `a-orm` module.
+
+That matters because ORM behavior depends on more than query syntax alone:
+
+- table identity strategy
+- model defaults
+- soft-deletion cleanup
+- supported database dialects
+- two-layer cache behavior
+
+## Configure the `a-orm` module
+
+ORM configuration lives under `config.modules['a-orm']`.
+
+Representative pattern:
+
+```typescript
+config.modules = {
+  'a-orm': {
+    table: {
+      identityType: 'bigint',
+    },
+    softDeletionPrune: {
+      enable: true,
+    },
+  },
+};
+```
+
+This is the main backend-level control surface for framework-wide ORM behavior.
+
+## Main configuration areas
+
+The most important ORM config areas are:
+
+- `table`
+- `model`
+- `softDeletionPrune`
+- `dialects`
+- `summer`
+
+A representative framework config shape is:
+
+```typescript
+config.modules = {
+  'a-orm': {
+    table: {
+      identityType: 'bigint',
+    },
+    model: {
+      disableDeleted: false,
+      disableInstance: false,
+      disableCreateTime: false,
+      disableUpdateTime: false,
+    },
+    softDeletionPrune: {
+      enable: true,
+      expired: 14 * 24 * 3600 * 1000,
+    },
+    dialects: {
+      mysql: 'a-ormdialect.databaseDialect.mysql',
+      mysql2: 'a-ormdialect.databaseDialect.mysql3',
+      pg: 'a-ormdialect.databaseDialect.pg',
+    },
+    summer: {
+      enable: true,
+      presetDefault: 'redis',
+      redis: {
+        client: 'model',
+      },
+    },
+  },
+};
+```
+
+## `table.identityType`
+
+`table.identityType` controls the type of the primary `id` field, such as:
+
+- `number`
+- `bigint`
+
+This matters because identity shape propagates into entity typing, DTO typing, and model-facing contracts.
+
+## `model` defaults
+
+The `model` block provides broad defaults for ORM behavior.
+
+Representative concerns include:
+
+- `disableDeleted`
+- `disableInstance`
+- `disableCreateTime`
+- `disableUpdateTime`
+
+A useful ownership rule is:
+
+- model config establishes framework-wide defaults
+- model metadata can specialize a specific model
+- method options can still override behavior at the usage site when needed
+
+That is why ORM behavior should be understood as layered configuration rather than as one fixed decorator-only setting.
+
+## `softDeletionPrune`
+
+Soft deletion is not only about marking a row as deleted. It also has a cleanup lifecycle.
+
+The `softDeletionPrune` block controls:
+
+- whether prune is enabled
+- how long deleted data is retained before prune
+
+This matters because teams often need a deliberate retention window for recoverability, audits, or operational cleanup.
+
+## `dialects`
+
+The `dialects` block defines the supported database dialect adapters.
+
+This is important because ORM behavior is framework-level and must remain portable across different backend database engines rather than assuming one hardcoded SQL target.
+
+## `summer` and two-layer cache behavior
+
+The `summer` block controls two-layer cache behavior for ORM workloads.
+
+Representative concerns include:
+
+- whether cache is enabled
+- which preset is the default
+- which Redis client should back the model cache path
+
+This matters because ORM query behavior, cache behavior, and invalidation expectations are part of one data-system design.
+
+For surrounding cache concepts, also see [Cache Guide](/backend/cache-guide).
+
+## Relationship to model and query behavior
+
+Read this guide together with:
+
+- [ORM Guide](/backend/orm-guide)
+- [Model Guide](/backend/model-guide)
+- [ORM Select Guide](/backend/orm-select-guide)
+- [ORM Mutation Guide](/backend/orm-mutation-guide)
+- [Cache Guide](/backend/cache-guide)
+- [Multi-Database and Datasource Guide](/backend/multi-database-datasource)
+
+A practical split is:
+
+- ORM configuration defines framework-wide defaults and infrastructure behavior
+- model metadata defines model-local behavior
+- select/mutation calls decide the per-operation query and write shape
+
+## Implementation checks for ORM configuration changes
+
+When editing ORM-sensitive backend code, ask:
+
+1. is this behavior controlled by app-level ORM config, model metadata, or a usage-site option?
+2. does the change affect identity type, soft deletion, or timestamp behavior?
+3. does the cache path depend on `summer` settings?
+4. does a database-engine assumption actually belong in the dialect layer instead?
+
+That helps AI keep ORM behavior aligned with Vona’s layered configuration model.

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

@@ -0,0 +1,109 @@
+# ORM Guide
+
+## Why Vona ORM matters
+
+Vona ORM is an intuitive and powerful ORM engine built around TypeScript, strong typing, and dynamic DTO inference.
+
+For the Cabloy docs, the most important takeaway is that Vona ORM is not just a thin query wrapper. It is a framework-level data system that connects:
+
+- models and entities
+- query behavior
+- mutation behavior
+- relationships
+- caching
+- multi-datasource support
+- transactions
+- DTO inference and generation
+- frontend integration through OpenAPI and generated contracts
+
+## Core capabilities
+
+Its core ORM capabilities include:
+
+- multiple databases and multiple datasources
+- dynamic datasource support
+- sharded databases and tables
+- read-write separation
+- dynamic DTO inference and generation
+- aggregate and grouping queries
+- static and dynamic relationships
+- query cache and entity cache
+- transaction and transaction-propagation support
+- transaction compensation for data and cache consistency
+
+## Recommended ORM reading path
+
+Use this page as the ORM overview, then move into the deeper leaves in roughly this order:
+
+1. [Model Guide](/backend/model-guide)
+2. [Entity Guide](/backend/entity-guide)
+3. [ORM Configuration Guide](/backend/orm-configuration-guide)
+4. [ORM Select Guide](/backend/orm-select-guide)
+5. [ORM Mutation Guide](/backend/orm-mutation-guide)
+6. [Relations Guide](/backend/relations-guide)
+7. [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide)
+8. [DTO Guide](/backend/dto-guide)
+9. [DTO Infer and Generation](/backend/dto-infer-generation)
+10. [Transaction Guide](/backend/transaction-guide)
+11. [Cache Guide](/backend/cache-guide)
+12. [Multi-Database and Datasource Guide](/backend/multi-database-datasource)
+13. [Dynamic Datasource Guide](/backend/dynamic-datasource-guide)
+14. [Sharding Guide](/backend/sharding-guide)
+
+Use [Dynamic Datasource Guide](/backend/dynamic-datasource-guide) as a backend-facing pointer page into deeper Cabloy datasource architecture, not as a parallel full ORM tutorial.
+
+This keeps the overview page focused while pushing depth into the pages that own each concern.
+
+## The main ORM concern clusters
+
+A useful mental model is to treat Vona ORM as several connected concern clusters:
+
+### Structure cluster
+
+- entities define persistence-facing fields
+- models define data behavior and relationships
+- ORM config defines framework-wide defaults
+
+### Query cluster
+
+- select operations shape row-oriented reads
+- aggregate/group operations shape summary-oriented reads
+- static and dynamic relations shape cross-model retrieval
+
+### Write cluster
+
+- insert/update/delete express explicit write intent
+- mutate/mutateBulk provide higher-level write inference
+- relation-aware writes support nested CRUD workflows
+
+### Infrastructure cluster
+
+- transactions protect consistency
+- cache affects query and entity behavior
+- datasource selection affects routing, isolation, and scale
+- sharding and advanced topology move the ORM into larger-system architecture
+
+## Relationship to fullstack contracts
+
+ORM is closely connected to DTO inference, OpenAPI, and frontend-facing contract generation.
+
+That means backend data modeling is not an isolated persistence concern. It also shapes:
+
+- controller contracts
+- generated SDKs
+- relation-aware DTOs
+- aggregate/group result contracts
+
+## Implementation checks for ORM changes
+
+Vona ORM should be treated as a knowledge hub rather than as an implementation detail.
+
+When changing backend data logic, ask:
+
+1. is this a model/entity/DTO problem rather than a raw SQL problem?
+2. does the change affect query shape, mutation semantics, relation behavior, or summary shape?
+3. does the change affect caching, transactions, or datasource behavior?
+4. should DTO inference or OpenAPI generation be updated as a consequence?
+5. does frontend integration depend on the ORM-facing contract shape?
+
+That perspective produces more Cabloy-native results.