@zerotal/orm 1.11.2 → 1.13.0

package/CHANGELOG.md

@@ -8,6 +8,37 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.12.0] — 2026-08-31
+
+### Changed — **BREAKING**
+
+- **A boolean written to a column declared to hold text is refused.** A bare
+  `@column()` resolves to `{ type: "string" }`, so a boolean property decorated with
+  one was stored as text — and a text column has text affinity, so `false` was stored
+  as `"0"`, which is truthy in JavaScript. Every `if (model.flag)` took the wrong
+  branch for a stored `false`, on every row, with nothing in the app or the database
+  registering a fault. An app found it when a feature flag read as enabled for every
+  record that had it turned off.
+
+  There is no correct coercion — `0` becomes `"0"` and `"false"` is truthy too — so
+  the value cannot survive the round trip and the write raises `ColumnTypeError`
+  instead, naming the property and the fix: `@column("boolean")`.
+
+  The decorator cannot infer it for you. `declare active: boolean` erases the
+  TypeScript type at runtime, so a bare `@column()` on a boolean is indistinguishable
+  from one on a string until a value arrives. Declaring the type is the only signal
+  there is.
+
+  An explicit `@column({ type: "string", cast: "boolean" })` is honoured — that is
+  someone saying what they meant. The guard is for the column that says nothing.
+
+  **This release stops new bad writes; it does not migrate old rows.** See
+  [the upgrade guide](https://zerotal.dev/docs/upgrade#1-11-to-1-12).
+
+### Added
+
+- **`ColumnTypeError`**, for the above.
+
 ## [1.11.0] — 2026-08-31
 
 ### Changed

package/api-surface.md

@@ -208,6 +208,13 @@ class ColumnBuilder = {
   wantsIndex: boolean
 }
 
+class ColumnTypeError = {
+  new (column: string, declared: string): ColumnTypeError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
 class DatabaseProvider = {
   new (app: Application): DatabaseProvider
   static dependsOn?: (new (app: Application) => ServiceProvider)[]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -31,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.11.2",
-    "@zerotal/validator": "1.11.2"
+    "@zerotal/core": "1.13.0",
+    "@zerotal/validator": "1.13.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/errors/ColumnTypeError.ts

@@ -0,0 +1,39 @@
+import { ZerotalError } from "@zerotal/core";
+
+/**
+ * Thrown when a boolean is written to a column declared to hold text.
+ *
+ * The reason this is an error rather than a coercion is that there is no correct
+ * coercion. SQLite gives a `TEXT` column text affinity, so an integer `0` written
+ * there is stored as the string `"0"` — and `"0"` is truthy in JavaScript. A
+ * `false` written to a text column therefore reads back as something that passes
+ * `if (model.flag)`, silently, on every row, forever. Writing `"false"` has the
+ * same problem. The value cannot survive the round trip, so the write is refused
+ * instead of being quietly made wrong.
+ *
+ * **A bare `@column()` is a text column.** With no argument it resolves to
+ * `{ type: "string" }`, which is the right default for the common case and the
+ * trap here: a boolean property decorated with a bare `@column()` looks declared
+ * and is stored as text. The `declare` keyword erases the property's TypeScript
+ * type at runtime, so the decorator cannot infer `boolean` and pick for you —
+ * which is exactly why the mistake is worth naming loudly rather than guessing at.
+ *
+ * Reported from production: a feature flag read as enabled for every record that
+ * had it turned off, and nothing in the app or the database registered a fault.
+ */
+export class ColumnTypeError extends ZerotalError {
+  constructor(column: string, declared: string) {
+    super(
+      `[Zerotal ORM] ${column} is declared as a \`${declared}\` column and was given a boolean. ` +
+        `A text column stores that as "0"/"1", and "0" is truthy in JavaScript — so a stored ` +
+        `\`false\` would read back as true and every \`if (…)\` on it would take the wrong branch. ` +
+        `Declare the column's type instead: \`@column("boolean")\`. ` +
+        `A bare \`@column()\` defaults to \`string\`, which is the usual cause. ` +
+        `If you genuinely want the text "true"/"false", assign a string.`,
+      "E_COLUMN_TYPE",
+      500,
+      { column, declared },
+    );
+    this.name = "ColumnTypeError";
+  }
+}

package/src/errors/index.ts

@@ -3,5 +3,6 @@ export { RelationNotLoadedError } from "./RelationNotLoadedError.ts";
 export { TransactionError } from "./TransactionError.ts";
 export { MigrationError } from "./MigrationError.ts";
 export { StateError } from "./StateError.ts";
+export { ColumnTypeError } from "./ColumnTypeError.ts";
 export { MassAssignmentError } from "./MassAssignmentError.ts";
 export { UnsupportedDialectError } from "./UnsupportedDialectError.ts";

package/src/index.ts

@@ -206,6 +206,7 @@ export {
   MigrationError,
   StateError,
   UnsupportedDialectError,
+  ColumnTypeError,
 } from "./errors/index.ts";
 
 // Provider

package/src/model/BaseModel.ts

@@ -30,6 +30,7 @@ import {
   ModelNotFoundError,
   RelationNotLoadedError,
   MassAssignmentError,
+  ColumnTypeError,
 } from "../errors/index.ts";
 import { type ManyToMany } from "./relations/RelationRegistry.ts";
 import { installReactiveAccessors, type ColumnOptions } from "./decorators/column.ts";
@@ -396,6 +397,13 @@ function _serializeForWrite(
     serializedVal = castOpt.set(val);
   } else if (typeof castOpt === "string") {
     serializedVal = applyCastSet(val, castOpt, model ? `${model}.${key}` : key);
+  } else if (typeof val === "boolean" && (colType === "string" || colType === "text")) {
+    // No coercion is correct here, so the write is refused rather than made wrong.
+    // A text column has text affinity: `0` is stored as "0", and "0" is truthy in
+    // JavaScript, so a stored `false` reads back as true on every row. "false" has
+    // the same problem. A bare `@column()` resolves to `{ type: "string" }`, which
+    // is how a boolean property ends up here looking perfectly declared.
+    throw new ColumnTypeError(model ? `${model}.${key}` : key, colType);
   } else if (colType === "boolean" && val !== null && val !== undefined) {
     serializedVal = val ? 1 : 0;
   } else if (colType === "json" && val !== null) {