cabloy 5.1.50 → 5.1.51

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

@@ -0,0 +1,274 @@
+# Model Guide
+
+This guide explains how models work in Vona within the Cabloy monorepo.
+
+## Why models matter in the backend contract loop
+
+Models are the persistence-facing layer of the backend contract loop.
+
+A useful split is:
+
+- controllers define HTTP-facing contracts
+- services orchestrate business flow
+- models own ORM-facing persistence behavior
+- entities and DTOs shape the data contract around that behavior
+
+That means model design affects not only SQL behavior, but also CRUD defaults, DTO assumptions, OpenAPI-facing contracts, and test setup.
+
+## Create a model
+
+Example: create a model named `student` in module `demo-student`.
+
+```bash
+npm run vona :create:bean model student -- --module=demo-student
+```
+
+## Model definition
+
+Representative pattern:
+
+```typescript
+import { BeanModelBase, Model } from 'vona-module-a-orm';
+import { EntityStudent } from '../entity/student.ts';
+
+@Model({ entity: EntityStudent })
+export class ModelStudent extends BeanModelBase<EntityStudent> {}
+```
+
+The key relationship is that a model is bound to an entity and exposes ORM-oriented operations for that entity.
+
+## Using a model
+
+Using models in Vona supports both dependency injection and dependency lookup, but dependency lookup is usually the clearer default.
+
+### Lookup in the current module
+
+```typescript
+class ServiceStudent {
+  async findAll(): Promise<EntityStudent[]> {
+    return await this.scope.model.student.select();
+  }
+}
+```
+
+### Lookup across modules
+
+```typescript
+class ServiceStudent {
+  async findAll(): Promise<EntityStudent[]> {
+    return await this.$scope.demoStudent.model.student.select();
+  }
+}
+```
+
+### Direct container access
+
+```typescript
+class ServiceStudent {
+  async findAll(): Promise<EntityStudent[]> {
+    return await this.bean._getBean('demo-student.model.student').select();
+  }
+}
+```
+
+This is one of the important backend layer boundaries:
+
+- services should usually orchestrate through models
+- models should remain the main persistence-facing abstraction instead of bypassing directly to ad hoc SQL everywhere
+
+## Basic CRUD patterns
+
+### Create
+
+```typescript
+return await this.scope.model.student.insert(student);
+```
+
+### Read
+
+```typescript
+return await this.scope.model.student.select();
+return await this.scope.model.student.getById(id);
+```
+
+### Update
+
+```typescript
+return await this.scope.model.student.updateById(id, student);
+```
+
+### Delete
+
+```typescript
+return await this.scope.model.student.deleteById(id);
+```
+
+These methods are also part of the generated CRUD thread; see [CRUD Workflow](/backend/crud-workflow).
+
+## Query-builder support
+
+Vona models are built on Knex, so the model layer also supports lower-level query builder access when needed.
+
+Representative patterns:
+
+```typescript
+this.scope.model.student.builder().where('name', 'tom').orderBy('name');
+this.scope.model.student.builderSelect().where('name', 'tom').orderBy('name');
+this.scope.model.student.query('select * from demoStudent');
+```
+
+A practical rule is:
+
+- prefer model methods and model-aware query paths first
+- use builder or raw SQL only when the higher-level model surface is not enough
+
+## Important model options
+
+Several important model options include:
+
+- `entity`
+- `table`
+- `disableDeleted`
+- `disableInstance`
+- `disableCreateTime`
+- `disableUpdateTime`
+- `softDeletionPrune`
+- `client`
+- `cache`
+- `relations`
+
+These options matter because Vona models are not only raw database adapters. They also carry framework-level behavior such as soft deletion, multi-instance support, datasource selection, caching, and relations.
+
+## App-config overrides
+
+Model options can also be configured in app config.
+
+Representative pattern:
+
+```typescript
+config.onions = {
+  model: {
+    'demo-student:student': {
+      disableDeleted: true,
+      disableInstance: true,
+      client: 'mysql',
+      cache: false,
+    },
+  },
+};
+```
+
+This is one of the key contract-loop ideas: model behavior is not defined only inside the model file. It can also be refined through project configuration.
+
+## Dynamic table partitioning
+
+Model supports dynamic table partitioning.
+
+Representative pattern:
+
+```typescript
+@Model({
+  table: (ctx: VonaContext, where: EntityOrder | undefined, defaultTable: keyof ITableRecord) => {
+    return `${defaultTable}_${moment().format('YYYYMMDD')}`;
+  },
+})
+class ModelOrder {}
+```
+
+This matters because some persistence decisions belong at the model abstraction level even when they materially change how the table is resolved.
+
+## Soft deletion and multi-instance defaults
+
+By default, Vona models support:
+
+- soft deletion
+- multi-instance or multi-tenancy filtering
+
+That means model behavior can be richer than a naïve SQL wrapper. For example, a normal `select()` already participates in instance filtering and deleted-record filtering unless configured otherwise.
+
+A practical implication is:
+
+- contract and test behavior should not assume raw-table semantics when the model layer is active
+
+## Instance-aware model semantics
+
+One important current-runtime distinction is that ordinary model usage is instance-aware by default.
+
+A practical interpretation is:
+
+- normal model operations participate in the current instance context
+- instance-aware filtering is part of normal model behavior unless disabled
+- request-scoped code should usually preserve that behavior instead of bypassing it casually
+
+This is why `disableInstance` is a meaningful semantic choice rather than a minor ORM toggle.
+
+Use it only when the model truly should ignore the active instance boundary.
+
+Another practical implication is:
+
+- lower-level builder or raw-SQL flows may need extra care when you are reproducing behavior that the ordinary model path would have applied automatically
+
+For the broader instance/config story, also see [Config Guide](/backend/config-guide).
+
+## Datasource selection
+
+Vona supports `multi-database` and `multi-datasource` behavior at the model layer.
+
+Representative modes include:
+
+- default datasource
+- static datasource in model options
+- app-config datasource override
+- adaptive datasource through a function
+- dynamic datasource chosen in code with `newInstance(...)`
+
+Representative dynamic pattern:
+
+```typescript
+const modelMysql = this.scope.model.student.newInstance('mysql');
+return await modelMysql.select();
+```
+
+This matters because backend contract behavior can depend on datasource choice, not just on query shape.
+
+In the current runtime, datasource choice can also change indirectly through instance isolation. If the active instance is configured as isolated, the effective default datasource may switch through that instance’s `isolateClient` setting even when the calling code did not name a datasource explicitly.
+
+That is why model behavior should be read together with:
+
+- [Config Guide](/backend/config-guide)
+- [Multi-Database and Datasource Guide](/backend/multi-database-datasource)
+
+## Cache behavior
+
+Vona models enable cache behavior by default.
+
+A practical distinction is:
+
+- entity cache stores entity records
+- query cache stores query-derived entity id sets
+
+That means model behavior affects performance and consistency semantics, not only data retrieval.
+
+For the broader cache story, also see [Cache Guide](/backend/cache-guide).
+
+## Relationship to the backend contract loop
+
+Read this guide together with:
+
+- [Service Guide](/backend/service-guide)
+- [Entity Guide](/backend/entity-guide)
+- [DTO Guide](/backend/dto-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [CRUD Workflow](/backend/crud-workflow)
+- [Migration and Changes](/backend/migration-and-changes)
+
+## Implementation checks for model-layer changes
+
+When creating backend persistence logic:
+
+1. start from the model and entity pairing
+2. prefer model methods and model-aware query paths
+3. preserve Vona soft-delete and instance-aware behavior unless there is a real reason not to
+4. choose deliberately among local scope, cross-module scope, and direct bean access
+5. remember that datasource, cache, and model options can change the behavior of the backend contract loop
+6. drop to raw SQL or lower-level query builder logic only when the higher-level model surface is insufficient

package/cabloy-docs/backend/multi-database-datasource.md

@@ -0,0 +1,171 @@
+# Multi-Database and Datasource Guide
+
+This guide explains how multi-database and multi-datasource support works in Vona within the Cabloy monorepo.
+
+## Why this matters
+
+Vona ORM is designed for business systems that may need:
+
+- multiple database engines
+- multiple datasources
+- cross-datasource relation queries
+- datasource-aware topology decisions
+- isolated-instance database routing
+
+This is an important part of the framework’s large-system positioning.
+
+## Core model
+
+A representative example uses related models such as `User` and `Order`.
+
+The key idea is that model relations can remain meaningful even when the participating data lives on different datasources.
+
+## Datasource setup
+
+Three important pieces define the datasource setup:
+
+1. datasource type definitions
+2. datasource configuration in app config
+3. model or relation-level selection of which datasource to use
+
+That means datasource choice is part of the typed application model, not just a hidden runtime string.
+
+## Default datasource selection
+
+In the current runtime, ordinary datasource selection starts from `config.database.defaultClient`.
+
+A practical order is:
+
+1. use the explicitly requested datasource when one is provided
+2. otherwise fall back to the configured default datasource
+3. if the current instance is isolated, allow the instance’s `isolateClient` to override the ordinary default
+
+This is why datasource selection belongs partly to config and partly to request/runtime context.
+
+## Explicit client selection
+
+One pattern is to create a model instance bound to a chosen datasource dynamically.
+
+Representative pattern:
+
+```typescript
+const modelMysql = this.scope.model.student.newInstance('mysql');
+return await modelMysql.select();
+```
+
+This is useful when the decision is explicit in business logic rather than implied by config defaults.
+
+## Model-level, relation-level, and app-config-level defaults
+
+You can simplify ordinary usage by declaring datasource choices in:
+
+- model options
+- relation options
+- app config
+
+That reduces repeated dynamic selection in ordinary business code.
+
+A practical distinction is:
+
+- use model or app-config defaults when one datasource should usually win
+- use relation metadata when different parts of a graph need different datasources
+- use explicit runtime selection when the current task truly needs to choose in code
+
+## Ordinary multi-datasource behavior vs isolated-instance routing
+
+One of the most important backend distinctions is:
+
+- **ordinary multi-datasource behavior** chooses among datasources for business or topology reasons
+- **isolated-instance routing** changes the effective default datasource because the active instance is configured as isolated
+
+In the current repo, an isolated instance can declare:
+
+- `isolate: true`
+- `isolateClient: 'isolateTest'`
+
+That means a request can remain model-native while still landing on a different default datasource because of instance configuration.
+
+## Instance-aware database strategy
+
+This matters because backend database strategy is not only about choosing MySQL vs PostgreSQL vs Sqlite3.
+
+It is also about deciding whether:
+
+- all instances share one datasource layout
+- some instances share data while others isolate storage
+- a test or tenant-specific instance should use a dedicated client
+
+A practical example in the current repo is the `isolateTest` client used together with an isolated test instance.
+
+## Concrete isolated datasource pattern in this repo
+
+In the current app config, `isolateTest` is created by cloning the currently selected default client into a dedicated isolated client slot.
+
+That pattern matters because it shows that isolated-instance routing does not require a completely separate datasource architecture from day one. It can start from the ordinary default client and then create an isolated variant for instance-aware routing.
+
+A practical runtime split in the current repo is:
+
+- base config defines `isolateTest` from the current default client
+- dev/test config enables an isolated instance that points at `isolateClient: 'isolateTest'`
+- prod config can explicitly unset `isolateTest` when that isolated test-oriented client should not remain active
+
+## Relation-level datasource selection
+
+Relation options can also specify datasource metadata.
+
+That matters because different parts of a related object graph may need different datasource bindings.
+
+## Datasource levels and execution isolation
+
+Datasource architecture is not only about routing to the right database. It is also about isolation across execution contexts.
+
+In distributed flows such as `pushAsync`, Vona can move work to a higher datasource level so background execution does not contend with the current request context for the same constrained connection pool.
+
+That is why datasource design should be read together with:
+
+- queue behavior
+- transaction behavior
+- relation loading
+- runtime and distributed execution patterns
+
+## Topology guidance
+
+A practical way to think about topology is:
+
+- use ordinary datasource selection for routine multi-datasource routing
+- use isolated-instance config when the default database route should vary by instance
+- use relation metadata when cross-datasource object graphs must still feel model-native
+- use explicit runtime selection when business flow must choose a datasource directly
+- escalate to sharding or deeper Cabloy architecture when the problem is no longer just datasource choice but data-distribution design
+
+## Relationship to config, model, and dynamic datasource
+
+Read this guide together with:
+
+- [Config Guide](/backend/config-guide)
+- [Runtime and Flavors](/backend/runtime-and-flavors)
+- [Model Guide](/backend/model-guide)
+- [Dynamic Datasource Guide](/backend/dynamic-datasource-guide)
+- [Sharding Guide](/backend/sharding-guide)
+- [Queue Guide](/backend/queue-guide)
+- [Relations Guide](/backend/relations-guide)
+
+A practical split is:
+
+- this guide explains ordinary multi-database and multi-datasource behavior
+- config and instance docs explain why the effective default may differ by runtime or instance
+- the dynamic datasource guide points to deeper routing architecture
+- the sharding guide points to deeper data-distribution architecture
+
+## Implementation checks for multi-datasource changes
+
+When changing backend data flow in a multi-datasource system, ask:
+
+1. is the model using an explicit datasource, a model default, or the current effective default datasource?
+2. does the active instance change that default through `isolateClient`?
+3. do related models need different datasource bindings?
+4. should the datasource choice live in runtime logic, relation metadata, model metadata, or app config?
+5. does the transaction, queue, or cache path need to match the same datasource choice?
+6. is the problem still ordinary datasource routing, or has it become a dynamic-datasource or sharding concern?
+
+That keeps multi-datasource logic coherent instead of fragile.

package/cabloy-docs/backend/multi-instance-and-instance-resolution.md

@@ -0,0 +1,196 @@
+# Multi-Instance and Instance Resolution
+
+This guide explains how multi-instance behavior works in Vona within the Cabloy monorepo.
+
+## Why this matters
+
+In Vona, backend runtime behavior is not always global-only.
+
+A backend application may need:
+
+- a shared default instance
+- named instances for tenant-like separation
+- isolated instances with their own datasource routing
+- instance-aware config, startup, and model behavior
+
+That is why multi-instance behavior should be understood as part of the backend runtime/config family, not only as an ORM detail.
+
+## Three practical layers
+
+A useful mental model is:
+
+- runtime and config decide how instances are declared
+- request context decides which instance is active
+- model and datasource behavior decide how that instance affects persistence
+
+## Instance config shape
+
+In the current runtime, instance behavior is configured under `config.instance`.
+
+Representative shape:
+
+```typescript
+config.instance = {
+  getInstanceName: undefined,
+  queryField: $protocolKey('x-vona-instance-name'),
+  headerField: $protocolKey('x-vona-instance-name'),
+  instances: {
+    '': { password: '', title: '' },
+    'shareTest': { password: '', title: '' },
+    'isolateTest': {
+      password: '',
+      title: '',
+      id: 1000,
+      isolate: true,
+      isolateClient: 'isolateTest',
+    },
+  },
+};
+```
+
+The important fields are:
+
+- `getInstanceName`
+- `queryField`
+- `headerField`
+- `instances`
+- per-instance options such as `id`, `isolate`, `isolateClient`, and `config`
+
+## Shared instance vs isolated instance
+
+A practical distinction is:
+
+- a **shared** instance participates in the normal shared datasource strategy
+- an **isolated** instance can route to its own datasource through `isolateClient`
+
+This means multi-instance behavior is not only a naming concern. It can materially change which database path the backend uses.
+
+## How the active instance name is resolved
+
+In the current runtime, the instance name is resolved in this order:
+
+1. `getInstanceName(ctx)` if provided
+2. the configured query field
+3. the configured header field
+4. subdomain-derived instance name
+
+This matters because request routing, config, and datasource behavior may all depend on the resolved instance name.
+
+A special case is also supported:
+
+- `'null'` is normalized to `null`
+
+A practical fallback rule is:
+
+- subdomain-based instance resolution only becomes relevant if custom getter, query-field, and header-field resolution did not already determine the instance name
+
+## Instance edge cases to remember
+
+A few current-runtime edge cases are worth remembering:
+
+- disabled instances can be declared with `false`
+- isolated instances require an explicit `id`
+- instance-name resolution is cached on the current context once determined
+- the instance record can be created or refreshed through the instance service before the effective config is cached
+
+## What context exposes
+
+Once instance resolution is active, the request context can expose:
+
+- `ctx.instanceName`
+- `ctx.instance`
+- `ctx.config`
+
+A practical distinction is:
+
+- `ctx.instanceName` identifies the active instance
+- `ctx.instance` is the loaded instance record
+- `ctx.config` is the effective config merged for that instance-aware context
+
+That means request-scoped backend code can stay instance-aware without manually reassembling config or routing rules.
+
+## How instance config affects effective backend config
+
+This page owns the request-context and instance-aware merge view. For env-file precedence and mode/flavor selection, see [Runtime and Flavors](/backend/runtime-and-flavors). For the broader config-layering surface, see [Config Guide](/backend/config-guide).
+
+In the current runtime, instance-aware config is built by merging:
+
+1. `app.config`
+2. static config under `config.instance.instances[instanceName].config`
+3. any persisted config stored on the instance record
+
+This is why instance behavior belongs partly to config docs and partly to runtime docs.
+
+A practical merge-order mental model is:
+
+1. start from `app.config`
+2. merge static instance config from `config.instance.instances[instanceName].config`
+3. merge persisted config stored on the instance record
+4. expose the result through `ctx.config`
+
+For the broader config-layering story, also see [Config Guide](/backend/config-guide).
+
+## How instance affects startup behavior
+
+Startup is also instance-aware.
+
+A practical split is:
+
+- app startup handles backend-wide initialization
+- instance startup handles per-instance initialization after the app is ready for instances
+
+In the current runtime:
+
+- `test` and `dev` eagerly start the default instance
+- production-style flows iterate configured static instances
+- instance startup work is queued and coordinated so one instance can initialize cleanly
+
+For the lifecycle view, also see [Backend Startup Guide](/backend/startup-guide).
+
+## How instance affects datasource selection
+
+One of the most important multi-instance consequences is datasource routing.
+
+In the current runtime, datasource selection can work like this:
+
+1. use an explicit datasource when code names one
+2. otherwise use the configured default datasource
+3. if the active instance is isolated, let `isolateClient` override that default
+
+This is why instance isolation should be understood together with datasource strategy rather than documented as an unrelated feature.
+
+For the datasource view, also see [Multi-Database and Datasource Guide](/backend/multi-database-datasource).
+
+## How instance affects model behavior
+
+Ordinary model operations are instance-aware by default.
+
+That means:
+
+- normal model flows participate in instance filtering
+- instance-aware config and startup can influence model behavior indirectly
+- `disableInstance` changes semantics and should be used deliberately
+
+For the model-layer perspective, also see [Model Guide](/backend/model-guide).
+
+## Relationship to runtime and config docs
+
+Read this guide together with:
+
+- [Runtime and Flavors](/backend/runtime-and-flavors)
+- [Config Guide](/backend/config-guide)
+- [Backend Startup Guide](/backend/startup-guide)
+- [Model Guide](/backend/model-guide)
+- [Multi-Database and Datasource Guide](/backend/multi-database-datasource)
+
+## Implementation checks for instance-resolution changes
+
+When editing backend runtime, datasource, or tenant-like behavior, ask:
+
+1. how is the current instance name resolved?
+2. is the task about shared-instance behavior or isolated-instance behavior?
+3. should the logic read `app.config` or `ctx.config`?
+4. does instance startup or instance config need to change as well?
+5. does datasource routing change indirectly through `isolateClient` even if no model call names a client explicitly?
+
+That keeps multi-instance behavior aligned with the current Vona runtime rather than treating it as a loose convention.