cabloy 5.1.50 → 5.1.51

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

@@ -0,0 +1,195 @@
+# ORM Mutation Guide
+
+This guide explains how ORM mutation operations work in Vona within the Cabloy monorepo.
+
+## Why mutation operations matter
+
+Mutation is where data shape, persistence behavior, soft deletion, relation-aware writes, and business rules intersect.
+
+Vona ORM provides a structured mutation surface rather than forcing every change through raw SQL or hand-written branching.
+
+## Basic mutation operations
+
+Representative operations include:
+
+- `insert`
+- `insertBulk`
+- `update`
+- `updateBulk`
+- `delete`
+- `deleteBulk`
+
+Representative examples:
+
+```typescript
+await this.scope.model.post.insert({ title: 'Post001' });
+await this.scope.model.post.update({ id: 1, title: 'Post001-Update' });
+await this.scope.model.post.delete({ id: 1 });
+```
+
+These operations are the clearest fit when the caller already knows the exact write intent.
+
+## Conditional update and delete paths
+
+Write operations do not have to target one row only by primary key.
+
+Representative patterns:
+
+```typescript
+await this.scope.model.post.update(
+  {
+    title: 'Post001-Update',
+  },
+  {
+    where: {
+      title: { _startsWith_: 'Post001' },
+    },
+  },
+);
+```
+
+```typescript
+await this.scope.model.post.delete({
+  title: {
+    _startsWith_: 'Post',
+  },
+});
+```
+
+That matters because the mutation layer still participates in the same structured query language used by select operations.
+
+## Bulk mutation operations
+
+Representative bulk patterns:
+
+```typescript
+await this.scope.model.post.insertBulk([{ title: 'Post001' }, { title: 'Post002' }]);
+```
+
+```typescript
+await this.scope.model.post.updateBulk([
+  { id: 1, title: 'Post001-Update' },
+  { id: 2, title: 'Post002-Update' },
+]);
+```
+
+```typescript
+await this.scope.model.post.deleteBulk([1, 2]);
+```
+
+Bulk methods are useful when the business flow already has a set of independent records to process in one operation family.
+
+## `mutate` and `mutateBulk`
+
+One of the most interesting Vona ideas is the `mutate` model.
+
+Instead of forcing callers to choose insert/update/delete up front, Vona can infer the mutation kind from data characteristics.
+
+Representative logic:
+
+- no `id` → insert
+- `id` present → update
+- `id` present and `deleted: true` → delete
+
+Representative pattern:
+
+```typescript
+const post = await this.scope.model.post.mutate({
+  title: 'Post001',
+});
+
+await this.scope.model.post.mutate({
+  id: post.id,
+  title: 'Post001-Update',
+});
+
+await this.scope.model.post.mutate({
+  id: post.id,
+  deleted: true,
+});
+```
+
+`mutateBulk` applies the same inference to a list of rows:
+
+```typescript
+await this.scope.model.post.mutateBulk([
+  { title: 'Post003' },
+  { id: 1, title: 'Post001-Update' },
+  { id: 2, deleted: true },
+]);
+```
+
+This is important because many CRUD-oriented business flows naturally arrive as mixed create/update/delete batches.
+
+## Explicit operations vs `mutate`
+
+A practical rule is:
+
+- use explicit `insert` / `update` / `delete` when write intent should stay obvious at the call site
+- use `mutate` when the business payload itself should drive the write behavior
+- use `mutateBulk` when one payload contains mixed create/update/delete rows
+
+That keeps write APIs expressive without overcomplicating caller logic.
+
+## Relation-aware writes and nested CRUD
+
+Mutation is also where relations become operational, not only descriptive.
+
+For `hasOne`, `hasMany`, and `belongsToMany` scenarios, nested writes can be expressed by combining the write payload with `include` or `with` relation definitions.
+
+A representative `hasMany` pattern is:
+
+```typescript
+await this.scope.model.order.update(
+  {
+    id: orderCreate.id,
+    orderNo: 'Order001-Update',
+    products: [
+      { name: 'Peach' },
+      { id: orderCreate.products?.[0].id, name: 'Apple-Update' },
+      { id: orderCreate.products?.[1].id, deleted: true },
+    ],
+  },
+  {
+    include: {
+      products: true,
+    },
+  },
+);
+```
+
+This is one of the strongest reasons mutation guidance must be read together with relation guidance.
+
+## Relationship to soft deletion
+
+Deletion behavior is not always hard deletion. In Vona, mutation semantics may also interact with soft-delete behavior, model defaults, and cleanup policies.
+
+Read this guide together with:
+
+- [ORM Configuration Guide](/backend/orm-configuration-guide)
+- [Relations Guide](/backend/relations-guide)
+- [Transaction Guide](/backend/transaction-guide)
+
+## Relationship to magic methods
+
+Legacy ORM docs also highlighted model-level convenience methods such as `getByName`, `updateById`, or custom helper methods that wrap ordinary mutation/select behavior.
+
+The important rule is:
+
+- magic-style methods are convenience entry points
+- the underlying write semantics still come from the standard ORM mutation surface
+- custom model methods take precedence when business-specific behavior is needed
+
+That means mutation should stay conceptually grounded in the standard model methods even when convenience wrappers are present.
+
+## Implementation checks for ORM mutation changes
+
+When writing mutation logic, ask:
+
+1. is this best expressed as explicit insert/update/delete?
+2. or is `mutate` a cleaner fit for the business flow?
+3. does the deletion behavior depend on Vona soft-delete semantics?
+4. does the write path also update related records through `include` or `with`?
+5. should the mutation contract be reflected in DTO or controller definitions too?
+
+That helps keep write-path logic aligned with the ORM’s intended abstractions.

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

@@ -0,0 +1,243 @@
+# ORM Select Guide
+
+This guide explains how ORM select operations work in Vona within the Cabloy monorepo.
+
+## Why select operations matter
+
+Select operations are where model definitions, relationships, filters, ordering, pagination, and caching behavior begin to interact.
+
+Vona does not treat queries as untyped string fragments. It provides a richer model-aware query surface.
+
+## Basic select operations
+
+Representative patterns:
+
+```typescript
+await this.scope.model.post.select();
+await this.scope.model.post.count();
+await this.scope.model.post.selectAndCount();
+await this.scope.model.post.get({ id });
+await this.scope.model.post.mget(ids);
+```
+
+These operations show the basic query vocabulary that services can build on.
+
+## Rich select parameters
+
+`select` can combine:
+
+- `distinct`
+- `columns`
+- `where`
+- `joins`
+- `orders`
+- `offset`
+- `limit`
+- `include`
+- `with`
+
+Representative pattern:
+
+```typescript
+await this.scope.model.post.select(
+  {
+    columns: ['id', 'title', 'userId'],
+    where: {
+      'id': { _gt_: 1 },
+      'testVonaUser.id': 1,
+    },
+    joins: [['innerJoin', 'testVonaUser', ['userId', 'testVonaUser.id']]],
+    offset: 0,
+    limit: 20,
+    orders: [['createdAt', 'desc']],
+  },
+  {
+    disableDeleted: false,
+  },
+  'test-vona:user',
+);
+```
+
+This matters because Vona ORM encourages structured query building rather than ad hoc query scattering.
+
+## Query options
+
+Representative option areas include:
+
+- `disableDeleted`
+- `disableCreateTime`
+- `disableUpdateTime`
+- `disableCacheQuery`
+- `disableCacheEntity`
+- `deleted`
+
+This is important because select behavior may depend on caching and soft-deletion policy, not only on columns and filters.
+
+## `joins`, `include`, and `with`
+
+A useful distinction is:
+
+- `joins` shapes table-level join behavior
+- `include` loads declared static relations
+- `with` loads dynamic relations declared at the usage site
+
+That means joins are not floating SQL trivia. They are part of a model-aware query system that can move between table-level control and relation-level convenience.
+
+## Type-guided joins
+
+A key insight is that joinable tables often come from relationships already declared on the model.
+
+In broader systems, not every useful join is declared on the current model. In those cases, the `_modelJoins` parameter can provide additional model hints so the join surface remains typed and discoverable.
+
+## `where` operators
+
+The operator model is broad and includes examples like:
+
+- `_eq_`
+- `_notEq_`
+- `_gt_`
+- `_gte_`
+- `_lt_`
+- `_lte_`
+- `_in_`
+- `_notIn_`
+- `_is_`
+- `_isNot_`
+- `_between_`
+- `_notBetween_`
+- `_startsWith_`
+- `_endsWith_`
+- `_includes_`
+- case-insensitive variants
+- `_ref_`
+- `_skip_`
+
+That operator vocabulary is part of the Cabloy data language and should be reused consistently.
+
+A practical operator-family reading is:
+
+- comparison: `_eq_`, `_notEq_`, `_gt_`, `_gte_`, `_lt_`, `_lte_`
+- membership/range: `_in_`, `_notIn_`, `_between_`, `_notBetween_`
+- null checks: `_is_`, `_isNot_`
+- string matching: `_startsWith_`, `_endsWith_`, `_includes_`, and case-insensitive variants
+- composition/subquery: `_and_`, `_or_`, `_not_`, `_exists_`, `_notExists_`
+- identifier or composition helpers: `_ref_`, `_skip_`
+
+### `_skip_`
+
+`_skip_` is especially useful when building query objects compositionally.
+
+Representative pattern:
+
+```typescript
+const where = {
+  title: { _includes_: 'ai' },
+  stars: { _gt_: 20 },
+};
+
+await this.scope.model.post.select({
+  where: {
+    ...where,
+    stars: '_skip_' as const,
+  },
+});
+```
+
+This lets a query builder remove one condition cleanly without rebuilding the whole `where` object by hand.
+
+## Joint operators and subqueries
+
+The query language also supports joint operators such as:
+
+- `_and_`
+- `_or_`
+- `_not_`
+- `_exists_`
+- `_notExists_`
+
+These operators matter because many real queries are not flat field comparisons.
+
+Representative `_exists_` pattern:
+
+```typescript
+await this.scope.model.post.select({
+  where: {
+    _exists_: function (builder: Knex.QueryBuilder) {
+      builder
+        .select('*')
+        .from('testVonaPostContent')
+        .where('postId', this.scope.model.post.ref('testVonaPost.id'));
+    } as any,
+  },
+});
+```
+
+## `raw` and `ref`
+
+The structured query language is the default, but Vona still exposes escape hatches when they are truly needed.
+
+Representative `raw` pattern:
+
+```typescript
+await this.scope.model.post.select({
+  where: this.scope.model.post.raw('?? > ?', ['stars', 20]) as any,
+});
+```
+
+Representative `ref` pattern:
+
+```typescript
+await this.scope.model.post.select({
+  where: {
+    title: {
+      _eq_: this.scope.model.post.ref('testVonaPost.title') as any,
+    },
+  },
+});
+```
+
+A practical rule is:
+
+- start with structured operators first
+- use `ref` when comparisons need identifier semantics
+- use `raw` only when the structured surface is not sufficient
+
+## `selectAndCount` and pagination-shaped results
+
+`selectAndCount` is especially useful when one backend query should return both rows and pagination metadata together.
+
+A practical result shape includes:
+
+- `list`
+- `total`
+- `pageCount`
+- `pageSize`
+- `pageNo`
+
+This matters because page-query contracts often need more than a plain row array. They need a stable list-plus-metadata response shape that can map directly into DTOs and controller response contracts.
+
+## Relationship to aggregate/group and DTOs
+
+Read this guide together with:
+
+- [Relations Guide](/backend/relations-guide)
+- [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+
+A practical split is:
+
+- use this guide for row-oriented query structure
+- use the aggregate/group guide when the result shape is summary-oriented
+- use DTO guidance when query shape must become an explicit API contract
+
+## Implementation checks for ORM select changes
+
+When writing or editing select logic:
+
+1. start from model relationships and typed query structure
+2. choose deliberately among `joins`, `include`, and `with`
+3. prefer the ORM query surface before dropping to raw SQL
+4. remember that soft-delete, cache, and datasource behavior may affect query semantics
+5. think about whether the query shape should also drive DTO or OpenAPI-facing output
+
+That keeps query logic aligned with Vona’s intended abstractions.

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

@@ -0,0 +1,271 @@
+# Queue Guide
+
+This guide explains how queues work in Vona within the Cabloy monorepo.
+
+## Why queues matter
+
+Vona provides a queue component based on BullMQ so business logic can be executed asynchronously and reliably through framework-native job handling.
+
+This is one of the main bridges between synchronous application code and distributed background execution.
+
+## Create a queue
+
+Example: create a queue named `add` in module `demo-student`.
+
+```bash
+npm run vona :create:bean queue add -- --module=demo-student
+```
+
+## Queue definition
+
+Representative shape:
+
+```typescript
+@Queue()
+export class QueueAdd
+  extends BeanQueueBase<TypeQueueAddJobData, TypeQueueAddJobResult>
+  implements IQueueExecute<TypeQueueAddJobData, TypeQueueAddJobResult>
+{
+  async execute(
+    data: TypeQueueAddJobData,
+    _options?: IQueuePushOptions,
+  ): Promise<TypeQueueAddJobResult> {
+    return data.a + data.b;
+  }
+}
+```
+
+The important point is that queue jobs are strongly typed at both input and output boundaries.
+
+## Push jobs
+
+Two main modes are supported:
+
+- `push` for fire-and-forget jobs
+- `pushAsync` for jobs where the caller awaits a result
+
+Representative patterns:
+
+```typescript
+this.scope.queue.add.push({ a: 1, b: 2 });
+```
+
+```typescript
+const result = await this.scope.queue.add.pushAsync({ a: 1, b: 2 });
+```
+
+This is important because it gives queue usage a clear business-level interface.
+
+## Push options and propagated context
+
+`push` and `pushAsync` both support queue-push options.
+
+Representative option areas include:
+
+- `queueNameSub`
+- `jobName`
+- `jobOptions`
+- `dbInfo`
+- `locale`
+- `instanceName`
+- `extraData`
+
+This matters because a queue push can propagate more than business payload alone. It can also carry runtime context that affects how the worker executes the job.
+
+A practical push-context reading is:
+
+| Field           | Typical purpose                                     |
+| --------------- | --------------------------------------------------- |
+| `data`          | business payload                                    |
+| `queueNameSub`  | refine queue routing                                |
+| `jobName`       | identify the job kind                               |
+| `jobOptions`    | pass BullMQ job options                             |
+| `dbInfo`        | control datasource/runtime database context         |
+| `locale` / `tz` | preserve request-oriented locale/timezone context   |
+| `instanceName`  | preserve instance-aware execution context           |
+| `extraData`     | pass selected request metadata or auxiliary context |
+
+## Datasource-level isolation and deadlock avoidance
+
+One of the most important distributed queue details is datasource-level isolation.
+
+A common risk looks like this:
+
+1. a request opens a database transaction
+2. the request pushes a queue job and awaits its result
+3. the worker handling the job also needs a database connection
+4. both sides could wait on the same constrained datasource pool
+
+Vona avoids this by using datasource levels so queue work can run with an isolated datasource context.
+
+A useful practical rule is:
+
+- ordinary request code uses the current datasource level
+- queued job execution is pushed to `current.level + 1`
+
+Representative pattern:
+
+```typescript
+await this.scope.queue.add.pushAsync(data);
+```
+
+This behaves like passing:
+
+```typescript
+await this.scope.queue.add.pushAsync(data, {
+  dbInfo: {
+    level: this.bean.database.current.level + 1,
+  },
+});
+```
+
+So queue behavior is not only “run later.” It also participates in connection-pool isolation and distributed consistency design.
+
+A practical refinement is:
+
+- queue push helpers prepare and carry runtime context explicitly before execution
+- that is why queue jobs can preserve datasource, locale, and instance-aware behavior without forcing the business payload itself to hold every context field
+
+For the surrounding datasource architecture, also see [Multi-Database and Datasource Guide](/backend/multi-database-datasource) and [Dynamic Datasource Guide](/backend/dynamic-datasource-guide).
+
+## Extra data and header passthrough
+
+Queue pushes can also include `extraData`.
+
+Representative pattern:
+
+```typescript
+this.scope.queue.add.push(data, {
+  extraData: {
+    request: {
+      headers: {
+        'x-custom': 'xxxx',
+      },
+    },
+  },
+});
+```
+
+The job can then read the propagated header value from request context:
+
+```typescript
+@Queue()
+class QueueAdd {
+  async execute(data, _options) {
+    console.log(this.ctx.headers['x-custom']);
+  }
+}
+```
+
+Vona also provides a header passthrough convention: headers prefixed with `x-vona-data-` are appended automatically to extra data and passed through to the job context.
+
+This is useful when background work needs selected request metadata without manually copying every field into the main business payload.
+
+## Queue options
+
+The queue system supports options around:
+
+- concurrency
+- transaction behavior
+- Bull queue/worker/job options
+- redlock-backed serial execution behavior
+
+Representative decorator pattern:
+
+```typescript
+@Queue({
+  concurrency: false,
+  transaction: false,
+  options: {
+    queue: {},
+    worker: {},
+    job: {},
+    redlock: {},
+  },
+})
+class QueueAdd {}
+```
+
+That means queue behavior is not only asynchronous. It also participates in concurrency, isolation, and consistency policy.
+
+## Configure queues in app config
+
+Queue options can also be overridden in app config.
+
+Representative pattern:
+
+```typescript
+config.onions = {
+  queue: {
+    'demo-student:add': {
+      concurrency: false,
+      transaction: false,
+      options: {
+        queue: {},
+        worker: {},
+        job: {},
+        redlock: {},
+      },
+    },
+  },
+};
+```
+
+## Enable/disable and environment scoping
+
+Queues can also be enabled or limited by environment metadata such as flavor or mode.
+
+Representative pattern:
+
+```typescript
+@Queue({
+  meta: {
+    flavor: 'normal',
+    mode: 'dev',
+  },
+})
+class QueueAdd {}
+```
+
+This is especially important in Cabloy because runtime environment and flavor are first-class concepts.
+
+## Relationship to startup, election, and broadcast
+
+Read this guide together with:
+
+- [Backend Startup Guide](/backend/startup-guide)
+- [Election Guide](/backend/election-guide)
+- [Broadcast Guide](/backend/broadcast-guide)
+- [Worker Guide](/backend/worker-guide)
+- [Schedule Guide](/backend/schedule-guide)
+- [Redlock Guide](/backend/redlock-guide)
+
+A practical split is:
+
+- startup initializes queue workers and other runtime capabilities
+- election decides which worker should own singleton-like responsibilities
+- queue handles asynchronous point-to-point work
+- broadcast sends the same message to multiple workers
+- redlock helps serialize queue behavior when concurrent execution must be restricted
+
+## Inspection
+
+The queue system can expose the effective queue list for inspection, which is useful for debugging and operational visibility.
+
+Representative pattern:
+
+```typescript
+this.bean.onion.queue.inspect();
+```
+
+## Implementation checks for background-job changes
+
+When asked to move work into the background, ask:
+
+1. is this a queue job instead of an inline request-path operation?
+2. should the caller use `push` or `pushAsync`?
+3. does the queue need transactional, serialized, or datasource-isolated behavior?
+4. does the job need request metadata through `extraData` or header passthrough?
+5. should enable/disable rules depend on flavor or mode?
+
+That keeps background work aligned with Vona’s distributed execution model.