cabloy 5.1.50 → 5.1.52

package/cabloy-docs/backend/runtime-and-flavors.md

@@ -0,0 +1,304 @@
+# Runtime Environments and Flavors
+
+This guide explains how runtime environments and flavors work in Vona within the Cabloy monorepo.
+
+## Why this model exists
+
+Vona does not treat backend runtime selection as a single switch.
+
+In practice, backend behavior is chosen by combining:
+
+- **runtime environment**
+- **flavor**
+
+That gives Cabloy enough room for development, testing, Playground, Docker, CI, and deployment-specific behavior without flattening everything into one axis.
+
+## Runtime environments
+
+Vona provides three main runtime environments:
+
+| Name   | Description             |
+| ------ | ----------------------- |
+| `test` | testing environment     |
+| `dev`  | development environment |
+| `prod` | production environment  |
+
+## How runtime environment is activated in the current repo
+
+In Cabloy Basic, the active mode is usually implied by which command you run.
+
+### Root-level contributor workflow
+
+```bash
+npm run dev
+npm run test
+npm run build
+npm run start
+```
+
+These root scripts delegate to the backend or frontend layer as needed, so they are the preferred monorepo-facing entrypoints.
+
+### Direct Vona workflow
+
+Representative backend-side scripts include:
+
+```bash
+cd vona && npm run dev
+cd vona && npm run dev:one
+cd vona && npm run test
+cd vona && npm run cov
+cd vona && npm run db:reset
+cd vona && npm run build
+cd vona && npm run build:docker
+cd vona && npm run start
+cd vona && npm run start:one
+cd vona && npm run start:docker
+```
+
+In the current repo, those scripts map naturally to:
+
+- `dev` commands -> development mode
+- `test` / `cov` / `db:reset` -> test mode
+- `build` / `start` -> production mode
+
+## Flavors
+
+For more specific scenarios, Vona adds the `flavor` dimension.
+
+The combination of runtime environment and flavor lets the framework support more precise operational contexts without inventing a separate environment for every case.
+
+### Built-in flavors used in this repo
+
+| Name     | Description                                   |
+| -------- | --------------------------------------------- |
+| `normal` | default contributor/runtime flavor            |
+| `play`   | used by the Playground workflow               |
+| `docker` | used for Docker-oriented build/runtime output |
+| `ci`     | used for CI-oriented production variants      |
+
+Representative current scripts include:
+
+```bash
+cd vona && npm run play
+cd vona && npm run build
+cd vona && npm run build:docker
+cd vona && npm run start
+cd vona && npm run start:docker
+```
+
+These scripts show that the same `prod` mode can still branch into different output/runtime shapes through flavor.
+
+## What the CLI injects automatically
+
+The current Vona CLI does not only read env files. It also injects key meta variables for the running process.
+
+The important ones are:
+
+- `NODE_ENV`
+- `META_MODE`
+- `META_FLAVOR`
+- `SERVER_WORKERS`
+
+A practical interpretation is:
+
+- `META_MODE` is the backend runtime mode source of truth
+- `META_FLAVOR` carries the flavor dimension
+- `NODE_ENV` is derived from mode (`test`, `development`, or `production`)
+- `SERVER_WORKERS` is normalized so the runtime always has an explicit worker count
+
+In the current CLI behavior:
+
+- prod defaults `SERVER_WORKERS` to CPU count when not provided
+- non-prod defaults `SERVER_WORKERS` to `1`
+
+## Curated built-in env variable catalog
+
+The current repo uses many env variables, but these are the most important ones for understanding the runtime/config family.
+
+| Variable family        | Representative variables                                                                                                                     | Why it matters                                                                                |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Runtime meta           | `META_MODE`, `META_FLAVOR`, `NODE_ENV`                                                                                                       | chooses the active runtime and flavor shape                                                   |
+| Worker/runtime process | `SERVER_WORKERS`                                                                                                                             | controls worker count and is normalized by the CLI/bootstrap path                             |
+| HTTP server            | `SERVER_LISTEN_HOSTNAME`, `SERVER_LISTEN_PORT`, `SERVER_LISTEN_DISABLE`, `SERVER_SERVE_PROTOCOL`, `SERVER_SERVE_HOST`, `SERVER_GLOBALPREFIX` | controls listen/serve behavior and URL shaping                                                |
+| Database               | `DATABASE_DEFAULT_CLIENT`, `DATABASE_CLIENT_SQLITE3_FILENAME`, `DATABASE_CLIENT_PG_*`, `DATABASE_CLIENT_MYSQL_*`                             | controls datasource defaults and concrete client connection settings                          |
+| Redis                  | `REDIS_DEFAULT_HOST`, `REDIS_DEFAULT_PORT`, `REDIS_DEFAULT_DB`                                                                               | controls the backend Redis baseline used by queue, cache, broadcast, and related capabilities |
+| Logger                 | `LOGGER_DIR`, `LOGGER_ROTATE_*`                                                                                                              | controls log path and rotation behavior                                                       |
+
+Use this page as the runtime-facing overview, then inspect the current app config when you need to see how those values are translated into backend config.
+
+## How to determine runtime metadata in code
+
+### Via environment variables
+
+```typescript
+process.env.META_MODE === 'test';
+process.env.META_MODE === 'dev';
+process.env.META_MODE === 'prod';
+
+process.env.META_FLAVOR === 'normal';
+process.env.META_FLAVOR === 'docker';
+process.env.META_FLAVOR === 'ci';
+```
+
+Using environment variables is especially useful when behavior needs to participate in build-time replacement or tree-shaking.
+
+### Via config
+
+```typescript
+app.config.meta.mode === 'test';
+app.config.meta.mode === 'dev';
+app.config.meta.mode === 'prod';
+
+app.config.meta.flavor === 'normal';
+app.config.meta.flavor === 'docker';
+app.config.meta.flavor === 'ci';
+```
+
+### Via simplified helpers
+
+```typescript
+app.meta.isTest;
+app.meta.isDev;
+app.meta.isProd;
+```
+
+A practical rule is:
+
+- use `process.env` when the logic is environment-driven and may affect bundling or compile-time replacement
+- use `app.config.meta` or `app.meta` when the logic belongs to normal runtime behavior inside the running backend
+
+## Env-file resolution and precedence
+
+This page owns the env-file and mode/flavor precedence view. For config surfaces and config layering, see [Config Guide](/backend/config-guide). For the fuller instance-aware merge view used by request-scoped behavior, see [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution).
+
+In the current repo, env values are loaded from the `vona/env/` directory.
+
+Representative files include:
+
+- `.env`
+- `.env.dev`
+- `.env.dev.play`
+- `.env.test`
+- `.env.prod`
+- `.env.prod.ci`
+- `.env.prod.docker`
+- `.env.local`
+- `.env.prod.local`
+- `.env.prod.docker.local`
+- `.env.prod.normal.local`
+
+The current loader builds the env-file chain from runtime metadata shaped like:
+
+- `mode`
+- `flavor`
+- `local`
+
+That means the loader can cascade from general files to more specific files such as:
+
+1. `.env`
+2. `.env.prod`
+3. `.env.prod.docker`
+4. `.env.prod.docker.local`
+
+The important rule is:
+
+- `.local` variants are treated as highest-priority local overrides
+
+Representative effective chains in the current repo look like this:
+
+- `dev + normal` -> `.env` -> `.env.dev` -> `.env.local`
+- `dev + play` -> `.env` -> `.env.dev` -> `.env.dev.play` -> `.env.local`
+- `prod + docker + local` -> `.env` -> `.env.prod` -> `.env.prod.docker` -> `.env.local` -> `.env.prod.local` -> `.env.prod.docker.local`
+
+One more practical detail matters during bootstrap:
+
+- after the env files are prepared, already-present `process.env` values still win when the runtime assembles the final env object
+
+So when you document or debug backend configuration, do not assume one flat `.env` file. Inspect the active `mode`, `flavor`, local override files, and any externally injected environment variables together.
+
+## Custom flavors
+
+Flavors are not limited to the built-in ones. You can introduce your own flavor for needs such as:
+
+- customer-specific behavior
+- deployment-specific behavior
+- project-specific behavior
+- organization-specific behavior
+
+Example:
+
+```bash
+npm run dev -- --flavor=customA
+```
+
+And in code:
+
+```typescript
+process.env.META_FLAVOR === 'customA';
+app.config.meta.flavor === 'customA';
+```
+
+## Type support for custom flavors
+
+Custom flavor names can also be added to type definitions for better editor support.
+
+Representative pattern:
+
+```typescript
+declare module '@cabloy/module-info' {
+  export interface VonaMetaFlavorExtend {
+    customA: never;
+  }
+}
+```
+
+## How runtime metadata becomes backend config
+
+Runtime env values do not stop at `process.env`.
+
+In the current Vona app config, they are folded into config such as:
+
+- `config.meta.mode`
+- `config.meta.flavor`
+- `config.server.*`
+- `config.database.defaultClient`
+- `config.logger.*`
+- `config.redis.*`
+
+This is why runtime environment and config should be read together, not as separate concerns.
+
+For the config-layering view, also see [Config Guide](/backend/config-guide).
+
+## Relationship to startup, instance, and datasource behavior
+
+Runtime environment and flavor are not only configuration concerns. They also shape:
+
+- startup enable/disable rules
+- startup hook behavior in different modes
+- distributed capability activation
+- datasource defaults
+- local-vs-prod operational differences
+
+Read this guide together with:
+
+- [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)
+- [Queue Guide](/backend/queue-guide)
+- [Schedule Guide](/backend/schedule-guide)
+- [Broadcast Guide](/backend/broadcast-guide)
+
+## Implementation checks for runtime and flavor changes
+
+When evaluating backend runtime or configuration guidance, do not assume that `dev/test/prod` is the whole story.
+
+Also inspect:
+
+1. which repo command actually drives the workflow
+2. whether the active behavior depends on flavor
+3. whether `.local` overrides may be changing the effective env values
+4. whether the runtime check should use `process.env`, `app.config.meta`, or `app.meta`
+5. whether a datasource, startup, or distributed feature is mode- or flavor-sensitive
+
+These environment differences also matter for operational concerns such as log directories, log levels, worker count, and runtime output layout; see [Logger Guide](/backend/logger-guide).

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

@@ -0,0 +1,81 @@
+# Schedule Guide
+
+This guide explains how schedules work in Vona within the Cabloy monorepo.
+
+## Why schedules matter
+
+Vona provides schedules on top of BullMQ, treating schedule as a specialized queue-driven execution path.
+
+This matters because recurring work is modeled with the same broader distributed-execution vocabulary rather than as an isolated timer hack.
+
+## Create a schedule
+
+Example: create a schedule named `log` in module `demo-student`.
+
+```bash
+npm run vona :create:bean schedule log -- --module=demo-student
+```
+
+## Schedule definition
+
+Representative shape:
+
+```typescript
+@Schedule({ repeat: { every: 3000 } })
+export class ScheduleLog extends BeanBase implements IScheduleExecute {
+  async execute() {
+    console.log(Date.now());
+  }
+}
+```
+
+The important point is that recurring execution is declared explicitly through schedule metadata.
+
+## Repeat configuration
+
+Two main repeat modes are supported:
+
+- interval-based repetition with `every`
+- cron-style repetition with `pattern`
+
+A practical distinction is:
+
+- use `every` when the schedule should repeat by a fixed interval
+- use `pattern` when the schedule should follow a cron-style calendar expression
+
+That gives schedules a flexible operational model without leaving the framework abstraction.
+
+## Queue and transaction interaction
+
+Schedule parameters can also include:
+
+- which queue to use
+- repeat options
+- template options
+- datasource context
+- whether to enable transaction behavior
+
+This matters because recurring jobs often have the same consistency concerns as ordinary queue jobs.
+
+## Enable/disable and environment scoping
+
+Like queues, schedules can be enabled or disabled and scoped to flavor or mode.
+
+That is important in Cabloy because recurring behavior is often environment-sensitive.
+
+## Load behavior and inspection
+
+Enabled schedules are loaded through the broader runtime/onion startup flow, and changed or disabled schedule definitions should be understood through that effective runtime context rather than as isolated timer state.
+
+The effective schedule list can be inspected, which helps operational debugging and understanding of what is actually active.
+
+## Implementation checks for scheduled backend changes
+
+When asked to add recurring backend behavior, ask:
+
+1. is this better modeled as a schedule rather than an ad hoc loop?
+2. should it repeat by interval or by cron pattern?
+3. does it need transaction behavior?
+4. should it be active in all modes and flavors or only specific ones?
+
+That keeps recurring backend work aligned with Vona’s distributed model.

package/cabloy-docs/backend/scripts.md

@@ -0,0 +1,116 @@
+# Backend Scripts
+
+This guide explains the main Vona script workflows in the Cabloy monorepo.
+
+## Shared rule
+
+Even though the underlying backend scripts still live in `vona/package.json`, contributors should usually start from the root scripts in the monorepo because they are the shared workflow surface.
+
+## Root scripts vs Vona CLI
+
+A practical distinction is:
+
+- use root scripts for normal runtime workflows such as install, dev, build, start, test, and typecheck
+- use `npm run vona ...` when you need backend command discovery, generation, initialization, or backend-specific tool flows
+
+That means [Backend CLI](/backend/cli) and this page are complementary, not redundant.
+
+## Development
+
+Start the backend in the root repository:
+
+```bash
+npm run dev
+```
+
+The underlying Vona package also distinguishes multi-worker and single-worker development modes:
+
+```bash
+cd vona && npm run dev
+cd vona && npm run dev:one
+```
+
+## Build
+
+From the root repository:
+
+```bash
+npm run build
+npm run build:docker
+```
+
+The backend-side build behavior is driven by Vona scripts such as:
+
+- `build`
+- `build:docker`
+
+## Start
+
+From the root repository:
+
+```bash
+npm run start
+```
+
+Vona also supports single-process and docker-oriented start modes inside its own package:
+
+```bash
+cd vona && npm run start
+cd vona && npm run start:one
+cd vona && npm run start:docker
+```
+
+## Test and typecheck
+
+From the root repository:
+
+```bash
+npm run test
+npm run tsc
+```
+
+The backend-specific script surface also includes:
+
+- `cov`
+- `db:reset`
+- `play`
+
+## Playground
+
+The Playground remains a high-value verification path for fast backend checks.
+
+```bash
+cd vona && npm run play
+```
+
+Or through the CLI wrapper:
+
+```bash
+npm run vona :bin:play -- --flavor=play --dummy
+```
+
+## Database reset
+
+```bash
+cd vona && npm run db:reset
+```
+
+## Relationship to backend essentials
+
+These scripts are part of the backend essentials workflow because they define how contributors actually enter the backend runtime.
+
+A useful split is:
+
+- scripts answer how the monorepo runs backend workflows
+- the CLI answers how backend resources are discovered and generated
+- modules and suites answer where generated resources belong
+
+For the structural side of that story, also see [Backend Essentials](/backend/backend-essentials) and [Package Map](/reference/package-map).
+
+## Guidance
+
+When documenting or automating backend scripts:
+
+- prefer root scripts for normal contributor workflows
+- drop to `vona/package.json` only when you need backend-specific detail
+- verify commands against current scripts before publishing examples

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

@@ -0,0 +1,192 @@
+# Serialization Guide
+
+## Why serialization matters in Vona
+
+Vona provides serialization so backend APIs can transform response data before it leaves the request path.
+
+That matters because response shaping often needs to do more than return raw entity fields. Real systems frequently need to:
+
+- exclude sensitive fields
+- mask values such as email or mobile data
+- derive new output fields
+- apply custom transforms to response values
+
+## Core serialization model
+
+Serialization in Vona is built around two layers:
+
+- enabling serialization for an API
+- attaching serializer behavior to fields through metadata helpers
+
+The framework can then transform response data using typed, reusable rules instead of ad hoc post-processing logic.
+
+## Enabling serialization for an API
+
+Serialization is enabled per API with:
+
+```typescript
+@Core.serializer()
+```
+
+Representative pattern:
+
+```typescript
+@Web.get(':id')
+@Api.body(v.optional(), v.object(EntityStudent))
+@Core.serializer()
+async findOne(id) {
+  return await this.scope.service.student.findOne(id);
+}
+```
+
+This makes serialization an explicit request-path capability rather than an invisible response-side convention.
+
+## Serializer transforms
+
+Vona supports custom serializer transforms through `@SerializerTransform(...)`.
+
+Representative generation workflow:
+
+```bash
+npm run vona :create:bean serializerTransform upper -- --module=demo-student
+```
+
+Representative pattern:
+
+```typescript
+@SerializerTransform<ISerializerTransformOptionsUpper>()
+export class SerializerTransformUpper {
+  async transform(value: string) {
+    return value.toUpperCase();
+  }
+}
+```
+
+A transform can define:
+
+- input value type
+- parent data type
+- result type
+- transform options
+
+This makes serializer behavior reusable and typed.
+
+## Applying a serializer transform
+
+Field-level serialization is attached through `@Api.field(...)` metadata helpers.
+
+Representative pattern:
+
+```typescript
+@Api.field(v.serializerTransform('demo-student:upper'))
+name: string;
+```
+
+This means response transformation is part of the same field-oriented contract model used for validation and OpenAPI metadata.
+
+## Filtered serializer execution
+
+A serializer transform can include a filter function so the transform only runs when the filter allows it.
+
+This is useful when serialization behavior depends on the current user, request context, or other runtime conditions.
+
+## Serializer transform parameters
+
+Serializer transforms can define options with:
+
+- default values
+- per-usage overrides
+- app-config overrides
+
+This lets projects tune serializer behavior without rewriting the transform implementation each time.
+
+A representative precedence model is:
+
+- usage-site override in `v.serializerTransform(...)`
+- then `config.onions.serializerTransform`
+- then decorator default values
+
+## Serializer helper tools
+
+Vona also provides a set of serializer-oriented helpers under the `v` helper surface.
+
+Representative helpers include:
+
+- `v.serializerTransform(...)`
+- `v.serializerExclude()`
+- `v.serializerReplace(...)`
+- `v.serializerGetter(...)`
+- `v.serializerCustom(...)`
+
+## `v.serializerExclude()`
+
+Use this to remove a field from serialized output.
+
+This is useful for fields that should exist in the backend model but should not appear in API responses.
+
+## `v.serializerReplace(...)`
+
+Use this to mask or rewrite a field value.
+
+A representative use case is partially masking a string such as an email, mobile number, or other sensitive value.
+
+## `v.serializerGetter(...)`
+
+Use this to derive a new serialized field value from the parent object.
+
+This is useful for fields such as `fullName` that are better expressed as output-only computed values.
+
+## `v.serializerCustom(...)`
+
+Use this when the transformation should be expressed inline as a custom function rather than through a named reusable transform bean.
+
+## App-config override patterns
+
+Serializer metadata can also be adjusted through app config, including field-level metadata updates for entities.
+
+That means serialization participates in the broader backend metadata and schema configuration system instead of being locked into only one code location.
+
+Representative patterns include:
+
+- direct metadata replacement with `$makeMetadata(...)`
+- schema reconstruction with `$makeSchema(...)`
+
+That choice matters because sometimes you only want to swap serialization metadata, while other times you want to rebuild the field schema surface more explicitly.
+
+## Relationship to DTOs, entities, validation, and OpenAPI
+
+Serialization should be read together with:
+
+- [DTO Guide](/backend/dto-guide)
+- [Entity Guide](/backend/entity-guide)
+- [Validation Guide](/backend/validation-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+
+These guides explain the same field-oriented metadata system from the perspectives of contract design, persistence shape, validation, and machine-readable API output.
+
+## When to use serialization instead of service-layer mutation
+
+Use serialization when:
+
+- the underlying backend object should remain unchanged
+- the output should vary by API response needs
+- the transformation belongs to response presentation or exposure policy
+
+Use service- or model-layer mutation when the underlying business data itself should change.
+
+A useful rule of thumb is:
+
+- choose a named serializer transform when the rule should be reusable across fields or entities
+- choose `v.serializerCustom(...)` when the rule is local to one field and does not deserve its own bean
+- choose `v.serializerExclude`, `v.serializerReplace`, or `v.serializerGetter` when the intent is one of those standard output policies
+
+## Implementation checks for backend serialization changes
+
+When changing backend response behavior, ask:
+
+1. should this be a serialization concern instead of modifying the underlying entity or service result?
+2. is a reusable named serializer transform better than an inline custom transform?
+3. should the field be excluded, masked, derived, or otherwise transformed through `v.serializer*` helpers?
+4. does the same field metadata also interact with validation, DTO design, or OpenAPI output?
+
+That helps AI keep response shaping aligned with Vona’s contract and metadata model.