cabloy 5.1.57 → 5.1.58

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 5.1.58
+
+### Features
+
+- Support nullable query filters.
+- Deliver several feature updates across the library.
+
+### Improvements
+
+- Add a Docker Compose quickstart flow to the documentation.
+- Refresh the framework performance documentation.
+
 ## 5.1.57
 
 ### Features

package/cabloy-docs/.vitepress/config.mjs

@@ -53,6 +53,7 @@ const fullstackGroups = [
         text: 'Comparison with Other Frameworks',
         link: '/fullstack/comparison-with-other-frameworks',
       },
+      { text: 'Framework Performance', link: '/fullstack/framework-performance' },
       { text: 'Vona + Zova Integration', link: '/fullstack/vona-zova-integration' },
       { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
       {

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

@@ -73,6 +73,13 @@ class DtoStudentCreate {
 }
 ```
 
+For query-oriented DTOs, another important distinction is optional vs nullable:
+
+- `v.optional()` means the field may be omitted
+- `v.nullable()` means the field may carry a real `null`
+
+That becomes especially important for DTO query filters. A field declared with `v.optional(), v.nullable()` can preserve real `null` through query parsing so the downstream ORM filter can express SQL `IS NULL` instead of silently treating the value as omitted.
+
 ## DTO options
 
 Three especially important DTO option areas are:

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

@@ -146,6 +146,8 @@ await this.scope.model.post.select({
 
 This lets a query builder remove one condition cleanly without rebuilding the whole `where` object by hand, while `null` remains available for SQL `IS NULL` semantics.
 
+That distinction also matters at the request-contract layer: omitting a nullable filter and passing a real `null` are different operations. When a query DTO needs `IS NULL` behavior from frontend query params, the parsing contract must explicitly preserve `null` instead of collapsing it to omission.
+
 ## Joint operators and subqueries
 
 The query language also supports joint operators such as:

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

@@ -37,12 +37,20 @@ findOne(@Arg.query('id', z.number().min(6)) id: number) {}
 Inferred schemas can also be extended through helper tools like:
 
 - `v.optional`
+- `v.nullable`
 - `v.default`
 - `v.array`
 - `v.lazy`
 
 That is important because many real validation cases need augmentation rather than total replacement.
 
+A useful distinction is:
+
+- `v.optional` means the field may be omitted
+- `v.nullable` means the field may carry a real `null`
+
+For query parameters, that distinction matters because plain optional values still collapse `null` to omission, while `v.optional(), v.nullable()` allows a real `null` to survive parsing when the contract needs SQL `IS NULL` semantics downstream.
+
 ## `@Arg.filter`
 
 The validation layer also supports more advanced query-style inputs through `@Arg.filter`, which ties into DTO/query helper structures.

package/cabloy-docs/fullstack/comparison-with-other-frameworks.md

@@ -11,6 +11,7 @@ That means the comparison is not only about a backend runtime or only about a fr
 For the broader Cabloy model, start with these pages:
 
 - [Fullstack Introduction](/fullstack/introduction)
+- [Framework Performance](/fullstack/framework-performance)
 - [Vona + Zova Integration](/fullstack/vona-zova-integration)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)

package/cabloy-docs/fullstack/framework-performance.md

@@ -0,0 +1,89 @@
+# Framework Performance
+
+Cabloy is designed to stay fast where real systems usually become fragile: under growing business complexity.
+
+Its performance story is not only about looking fast in simplified demos. It is about keeping real business systems maintainable, expressive, and performant as they grow in size and complexity.
+
+This page explains that philosophy first, then shows a concrete runtime example from an internally generated project.
+
+## Philosophy
+
+Many frameworks highlight performance with simplified cases, but real systems face a different challenge: as business complexity grows, performance work can easily turn into a growing pile of special-case optimization code.
+
+Cabloy takes a different direction.
+
+At the framework level, the goal is not only to make one isolated path faster. The goal is to let teams build large-scale systems in a way that stays elegant, maintainable, and performance-aware over time.
+
+That philosophy comes from the earlier Vona design direction:
+
+- performance should be considered under real business complexity
+- framework support should reduce the amount of ad hoc optimization code that teams need to write themselves
+- maintainability and performance should improve together instead of fighting each other
+
+In other words, Cabloy does not treat performance as a last-minute patch. It treats performance-related capability as part of the framework design.
+
+## What supports this philosophy
+
+A practical example is **Vona** on the backend side.
+
+Vona moves caching into the framework core instead of treating caching as something every project must rebuild from scratch. That includes framework-managed cache behavior such as:
+
+- entity cache
+- query cache
+- broader cache-centered workflow support for complex data access paths
+
+This matters because large systems usually do not become slow only because one query is inefficient. They become slow because optimization logic gets scattered across the codebase and becomes difficult to keep correct.
+
+By making caching first-class, Cabloy helps teams keep performance work closer to the framework model and farther away from repetitive custom optimization code.
+
+For the current public explanation of this backend capability, see [Cache Guide](/backend/cache-guide).
+
+## Runtime example
+
+This is the kind of result Cabloy is designed to support: a framework that stays operationally calm even when the system keeps running for long periods.
+
+One internally generated project was kept running continuously for **33 hours**. At one representative PM2 snapshot, the process looked like this:
+
+```text
+┌────┬─────────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
+│ id │ name            │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
+├────┼─────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
+│ 0  │ cabloy_store    │ default     │ N/A     │ cluster │ 226947   │ 33h    │ 17   │ online    │ 0%       │ 401.9mb  │ ubuntu   │ disabled │
+└────┴─────────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘
+```
+
+For this 33-hour continuous run, the observed result was **0 memory leak**.
+
+The value of this example is not that it is a synthetic micro-benchmark. The value is that it reflects a real long-running project process with a clear, inspectable runtime footprint.
+
+## How to read this example
+
+This example is meant to show a real runtime stability observation from an internal project.
+
+It should not be read as:
+
+- a formal benchmark against other frameworks
+- a universal guarantee for every Cabloy workload
+- proof that every deployment will show the same memory profile
+
+Actual memory usage still depends on factors such as:
+
+- enabled modules and features
+- request traffic patterns
+- data volume
+- deployment topology
+- operational configuration
+
+If you want to check your own SSR workload, you can use the `detect-ssr-leak` Claude skill in the Vona workspace to investigate long-running memory behavior and verify whether the system shows leak signals.
+
+This is a diagnostic workflow, not a universal guarantee that every deployment is leak-free.
+
+So the point of the example is not that one PM2 snapshot explains everything. The point is that Cabloy’s framework design is intended to support long-running, real business systems without forcing teams into constant performance firefighting.
+
+## Where to go next
+
+If you want to continue from the performance philosophy into the concrete framework mechanisms behind it, these pages are the best next stops:
+
+- [Cache Guide](/backend/cache-guide) — how Vona makes caching first-class in the backend model
+- [Vona + Zova Integration](/fullstack/vona-zova-integration) — how the backend and frontend stay aligned as one framework system
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) — one example of how Cabloy reduces repetitive cross-stack work at scale

package/cabloy-docs/fullstack/introduction.md

@@ -41,6 +41,7 @@ Start here when you want the shortest route to a working monorepo mental model:
 Use this path when the task is about how backend and frontend stay aligned inside one framework system:
 
 - [Comparison with Other Frameworks](/fullstack/comparison-with-other-frameworks)
+- [Framework Performance](/fullstack/framework-performance)
 - [Vona + Zova Integration](/fullstack/vona-zova-integration)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)

package/cabloy-docs/fullstack/quickstart.md

@@ -57,13 +57,29 @@ If you are not sure which edition you are using or which one to choose, read:
 - [Cabloy Basic](/editions/cabloy-basic)
 - [Cabloy Start](/editions/cabloy-start)
 
-## 5. Upgrade an existing project
+## 5. Run with Docker Compose
+
+Both Cabloy Basic and Cabloy Start support the same Docker Compose command flow. Run these commands from the repository for the edition you are using:
+
+```bash
+npm run build:docker
+cd docker-compose
+sudo COMPOSE_BAKE=true docker-compose build
+sudo docker-compose up
+```
+
+- Web: http://localhost/
+- Admin: http://localhost/admin/
+
+These commands build the edition-specific frontend flavors from the repository you are using.
+
+## 6. Upgrade an existing project
 
 ```bash
 npm run upgrade
 ```
 
-## 6. Next steps for framework-aware development
+## 7. Next steps for framework-aware development
 
 If you are contributing to framework-aware workflows or using Cabloy CLI generation directly, prefer CLI-backed generation over manual scaffolding.
 
@@ -76,7 +92,7 @@ npm run zova :create
 
 Then narrow into the specific command family you need.
 
-## 7. Shared verification commands for deeper workflow checks
+## 8. Shared verification commands for deeper workflow checks
 
 If you are validating framework-aware changes or a broader workflow, use the shared project scripts before declaring a workflow correct:
 

package/cabloy-docs/fullstack/vona-zova-integration.md

@@ -23,6 +23,8 @@ Cabloy uses a frontend-backend separation architecture:
 - generated or built frontend output is consumed by the backend-side fullstack flow
 - type sharing is coordinated through OpenAPI, generated SDKs, and frontend-generated route/component typing
 
+For the framework-level performance philosophy behind this fullstack model, see [Framework Performance](/fullstack/framework-performance).
+
 ## Cabloy Basic
 
 In Cabloy Basic, the root repository already exposes these shared entrypoints:

package/cabloy-docs/index.md

@@ -42,6 +42,7 @@ Start here to learn the shared Cabloy architecture, see how Vona and Zova fit to
 - **Get started quickly** with the fullstack quickstart and core Cabloy concepts
 - **Learn the shared fullstack architecture** across Cabloy, Vona, and Zova
 - **Explore backend and frontend workflows** without losing the cross-stack picture
+- **Understand Cabloy’s performance philosophy and runtime stability story** with [Framework Performance](/fullstack/framework-performance)
 - **See how Cabloy Basic and Cabloy Start differ by edition** when UI assumptions, flavors, modules, SSR sites, or AI workflow guidance matter
 - **Follow source-grounded AI vibe coding guidance** for prompting, workflow selection, and verification
 
@@ -63,6 +64,13 @@ Start here to learn the shared Cabloy architecture, see how Vona and Zova fit to
 5. [Reference Introduction](/reference/introduction)
 6. [Editions Overview](/editions/overview)
 
+### For performance-oriented reading
+
+1. [Fullstack Introduction](/fullstack/introduction)
+2. [Framework Performance](/fullstack/framework-performance)
+3. [Cache Guide](/backend/cache-guide)
+4. [Vona + Zova Integration](/fullstack/vona-zova-integration)
+
 ## Documentation scope labels
 
 Use these labels throughout the site:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.57",
+  "version": "5.1.58",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/vona/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.108",
+  "version": "1.1.109",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.106",
+  "version": "1.1.107",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

package/vona/packages-utils/zod-query/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabloy/zod-query",
-  "version": "2.1.8",
+  "version": "2.1.9",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "zod-query",
   "keywords": [

package/vona/packages-utils/zod-query/src/index.ts

@@ -1 +1,2 @@
 export * from './lib/query.ts';
+export * from './lib/zod-is-type.ts';

package/vona/packages-utils/zod-query/src/lib/query.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 import { Metadata } from './metadata.ts';
 import { isNil } from './utils.ts';
-import { isZodType } from './zod-is-type.ts';
+import { isNullableSchema, isZodType } from './zod-is-type.ts';
 
 interface IParsePayload {
   value: any;
@@ -33,6 +33,8 @@ function __parseAdapter(inst: z.ZodType, parse) {
         return __parseObject(inst, parse, payload, _);
       case 'array':
         return __parseArray(inst, parse, payload, _);
+      case 'nullable':
+        return __parseNullable(inst, parse, payload, _);
       case 'optional':
         return __parseOptional(inst, parse, payload, _);
       case 'default':
@@ -171,17 +173,27 @@ function __parseArray(_inst, parse, payload: IParsePayload, _) {
 ///////////////////////////////////////////
 
 function __parseOptional(_inst, parse, payload: IParsePayload, _) {
-  if (isZodType(Metadata.unwrapUntil(_inst), 'ZodString')) {
-    _coerceString(payload);
-  } else {
-    _coerceWithNil(payload);
-  }
-  if (payload.value === null) {
+  const nullable = isNullableSchema(_inst);
+  _coerceNullable(_inst, payload, nullable);
+  if (payload.value === null && !nullable) {
     payload.value = undefined;
   }
   return parse(payload, _);
 }
 
+////////////////////////////////////////////
+////////////////////////////////////////////
+/// ///////                       //////////
+/// ///////      ZodNullable      /////////
+/// ///////                       //////////
+////////////////////////////////////////////
+////////////////////////////////////////////
+
+function __parseNullable(_inst, parse, payload: IParsePayload, _) {
+  _coerceNullable(_inst, payload, true);
+  return parse(payload, _);
+}
+
 ////////////////////////////////////////////
 ////////////////////////////////////////////
 /// ///////                        /////////
@@ -191,11 +203,7 @@ function __parseOptional(_inst, parse, payload: IParsePayload, _) {
 ////////////////////////////////////////////
 
 function __parseDefault(_inst, parse, payload: IParsePayload, _) {
-  if (isZodType(Metadata.unwrapUntil(_inst), 'ZodString')) {
-    _coerceString(payload);
-  } else {
-    _coerceWithNil(payload);
-  }
+  _coerceNullable(_inst, payload, isNullableSchema(_inst));
   return parse(payload, _);
 }
 
@@ -225,6 +233,17 @@ function _coerceString(payload: IParsePayload, fn?: Function) {
   }
 }
 
+function _coerceNullable(inst: z.ZodType, payload: IParsePayload, nullable: boolean) {
+  if (isZodType(Metadata.unwrapUntil(inst), 'ZodString')) {
+    _coerceString(payload);
+    if (nullable && payload.value === 'null') {
+      payload.value = null;
+    }
+  } else {
+    _coerceWithNil(payload);
+  }
+}
+
 function _coerceWithNil(payload: IParsePayload, fn?: Function) {
   if (!isNil(payload.value)) {
     if (payload.value === 'undefined' || payload.value === '') {

package/vona/packages-utils/zod-query/src/lib/zod-is-type.ts

@@ -90,17 +90,59 @@ export function isAnyZodType(schema: object): schema is z.ZodType {
 }
 
 /**
- * The schema.isNullable() is deprecated. This is the suggested replacement
- * as this was how isNullable operated beforehand.
+ * The schema.isNullable() is deprecated. This is the suggested replacement.
  */
 export function isNullableSchema(schema: z.ZodType) {
-  return schema.safeParse(null).success;
+  return _isNullableSchema(schema);
 }
 
 /**
- * The schema.isOptional() is deprecated. This is the suggested replacement
- * as this was how isOptional operated beforehand.
+ * The schema.isOptional() is deprecated. This is the suggested replacement.
  */
 export function isOptionalSchema(schema: z.ZodType) {
-  return schema.safeParse(undefined).success;
+  return _isOptionalSchema(schema);
+}
+
+function _isNullableSchema(schema: z.ZodType): boolean {
+  if (isZodType(schema, 'ZodNullable')) return true;
+  if (isZodType(schema, 'ZodNonOptional')) return false;
+  if (
+    isZodType(schema, ['ZodOptional', 'ZodDefault', 'ZodReadonly']) &&
+    isAnyZodType(schema._zod.def.innerType)
+  ) {
+    return _isNullableSchema(schema._zod.def.innerType);
+  }
+  if (isZodType(schema, 'ZodPipe')) {
+    const inSchema = schema._zod.def.in;
+    const outSchema = schema._zod.def.out;
+    if (isZodType(inSchema, 'ZodTransform') && isAnyZodType(outSchema)) {
+      return _isNullableSchema(outSchema);
+    }
+    if (isAnyZodType(inSchema)) {
+      return _isNullableSchema(inSchema);
+    }
+  }
+  return false;
+}
+
+function _isOptionalSchema(schema: z.ZodType): boolean {
+  if (isZodType(schema, ['ZodOptional', 'ZodDefault'])) return true;
+  if (isZodType(schema, 'ZodNonOptional')) return false;
+  if (
+    isZodType(schema, ['ZodNullable', 'ZodReadonly']) &&
+    isAnyZodType(schema._zod.def.innerType)
+  ) {
+    return _isOptionalSchema(schema._zod.def.innerType);
+  }
+  if (isZodType(schema, 'ZodPipe')) {
+    const inSchema = schema._zod.def.in;
+    const outSchema = schema._zod.def.out;
+    if (isZodType(inSchema, 'ZodTransform') && isAnyZodType(outSchema)) {
+      return _isOptionalSchema(outSchema);
+    }
+    if (isAnyZodType(inSchema)) {
+      return _isOptionalSchema(inSchema);
+    }
+  }
+  return false;
 }

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.44",
+  "version": "5.1.45",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [

package/vona/packages-vona/vona-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-core",
-  "version": "5.1.20",
+  "version": "5.1.21",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona",
   "keywords": [

package/vona/packages-vona/vona-mock/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-mock",
-  "version": "6.1.20",
+  "version": "6.1.21",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona mock",
   "keywords": [