@zerotal/orm 1.14.3 → 1.15.0

package/CHANGELOG.md

@@ -8,6 +8,27 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.15.0] — 2026-09-04
+
+### Changed — **BREAKING**
+
+- **BREAKING: `createdAt`, `updatedAt` and `deletedAt` are `Carbon`, not `Date`.** Every
+  `datetime` column hydrates as `Carbon`, these three included — so the declared type was
+  wrong on a freshly loaded row, and `order.createdAt.getTime()` type-checked and threw,
+  because `Carbon` has `toISOString()` and `valueOf()` but no `getTime()`.
+
+  Worse, the runtime class depended on how you got there: `Carbon` after a load, a raw
+  `Date` after a `save()`, a `touch()`, or a soft `delete()` wrote one straight back onto
+  the instance. The same property on the same model, matching its declared type in neither
+  case, and with no `@column` declaration to check the truth against.
+
+  All three are now `Carbon` everywhere, declared and at runtime. Code calling a `Date`
+  method on them was already failing at runtime and now fails to compile; `.toISOString()`
+  gives a string, `.valueOf()` epoch milliseconds, and `.toDate()` a native `Date`.
+
+  Compile and follow the errors — every one is a line that would have thrown against a
+  loaded row. See the [Upgrade Guide](/docs/upgrade#114-to-115).
+
 ## [1.12.0] — 2026-08-31
 
 ### Changed — **BREAKING**

package/api-surface.md

@@ -3,6 +3,9 @@
 <!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
      Run `bun run api:surface` to regenerate after an intentional API change. -->
 
+> Not a guide — this is a flat, alphabetical snapshot used to detect unintended
+> API changes. For how to use these, read the [documentation](https://zerotal.dev/docs).
+
 ## .  `(./src/index.ts)`
 
 class ArrayCast = {
@@ -78,7 +81,7 @@ class BaseModel = {
   $dirty: () => Record<string, unknown>
   append: (...keys: string[]) => BaseModel
   associate: (relation: string, model: BaseModel) => BaseModel
-  createdAt?: Date
+  createdAt?: Carbon
   decrement: (column: 'id' | 'createdAt' | 'updatedAt' | '__isZerotalModel' | 'fill' | 'forceFill' | 'save' | 'delete' | 'load' | 'loadMissing' | 'fresh' | 'refresh' | 'replicate' | 'touch' | 'is' | 'isNot' | 'increment' | 'decrement' | 'loadCount' | 'loadSum' | 'loadAvg' | 'loadMin' | 'loadMax' | 'makeHidden' | 'makeVisible' | 'append' | 'associate' | 'dissociate' | 'isDirty' | '$dirty' | 'markDirty' | 'toJSON', amount?: number) => Promise<BaseModel>
   delete: () => Promise<void>
   dissociate: (relation: string) => BaseModel
@@ -106,7 +109,7 @@ class BaseModel = {
   save: () => Promise<BaseModel>
   toJSON: () => Record<string, unknown>
   touch: () => Promise<BaseModel>
-  updatedAt?: Date
+  updatedAt?: Carbon
 }
 
 class Blueprint = {
@@ -392,7 +395,7 @@ class Model = {
   $dirty: () => Record<string, unknown>
   append: (...keys: string[]) => BaseModel
   associate: (relation: string, model: BaseModel) => BaseModel
-  createdAt?: Date
+  createdAt?: Carbon
   decrement: (column: 'id' | 'createdAt' | 'updatedAt' | '__isZerotalModel' | 'fill' | 'forceFill' | 'save' | 'delete' | 'load' | 'loadMissing' | 'fresh' | 'refresh' | 'replicate' | 'touch' | 'is' | 'isNot' | 'increment' | 'decrement' | 'loadCount' | 'loadSum' | 'loadAvg' | 'loadMin' | 'loadMax' | 'makeHidden' | 'makeVisible' | 'append' | 'associate' | 'dissociate' | 'isDirty' | '$dirty' | 'markDirty' | 'toJSON', amount?: number) => Promise<BaseModel>
   delete: () => Promise<void>
   dissociate: (relation: string) => BaseModel
@@ -420,7 +423,7 @@ class Model = {
   save: () => Promise<BaseModel>
   toJSON: () => Record<string, unknown>
   touch: () => Promise<BaseModel>
-  updatedAt?: Date
+  updatedAt?: Carbon
 }
 
 class ModelChanged = {

package/package.json

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

package/src/model/BaseModel.ts

@@ -930,16 +930,30 @@ export class BaseModel {
   /**
    * Creation timestamp, set on insert when {@link timestamps} is enabled.
    *
+   * A {@link Carbon}, like every other `datetime` column — not a `Date`. These
+   * two were declared as `Date` while hydration produced a `Carbon`, so
+   * `order.createdAt.getTime()` type-checked and threw, and `.slice(0, 10)` on
+   * a value assumed to be an ISO string threw differently. Neither has a column
+   * declaration in the model to read the truth off, which is exactly why the
+   * declaration here has to be right.
+   *
+   * Use `.toISOString()` for a string, `.valueOf()` for epoch milliseconds, and
+   * `.toDate()` when something really needs a native `Date`.
+   *
    * @category Timestamps
    */
-  createdAt?: Date;
+  createdAt?: Carbon;
 
   /**
    * Last-update timestamp, bumped on every save when {@link timestamps} is enabled.
    *
+   * A {@link Carbon} — see {@link createdAt}. It used to depend on how you got
+   * here: a `Carbon` on a freshly loaded row, a raw `Date` on one you had just
+   * saved, from the same property on the same model.
+   *
    * @category Timestamps
    */
-  updatedAt?: Date;
+  updatedAt?: Carbon;
 
   /** @internal Snapshot of attribute values at load/last-save, for dirty tracking. */
   private _original: Record<string, unknown> = {};
@@ -1849,7 +1863,10 @@ export class BaseModel {
       await HookRegistry.run(ModelClass, "beforeUpdate", this);
 
       const dirty = this.$dirty();
-      if (ModelClass.timestamps) dirty["updatedAt"] = new Date();
+      // Carbon, not `new Date()`. The entries below are written back onto the
+      // instance, so a plain Date here left `updatedAt` holding a different class
+      // after a save than after a load — with the declared type matching neither.
+      if (ModelClass.timestamps) dirty["updatedAt"] = Carbon.now();
 
       if (Object.keys(dirty).length > 0) {
         const entries = _writeDialect.run(dialect, () =>
@@ -1900,16 +1917,17 @@ export class BaseModel {
     await HookRegistry.run(ModelClass, "beforeDelete", this);
 
     if (ModelClass.softDeletes) {
-      const now = new Date();
+      const now = Carbon.now();
       await runSegs(conn, [
         `UPDATE ${ModelClass.table} SET deleted_at = `,
-        { val: _writeDialect.run(dialect, () => _serializeDate(now)) },
+        { val: _writeDialect.run(dialect, () => _serializeDate(now.toDate())) },
         ` WHERE ${ModelClass.primaryKey} = `,
         { val: this.id },
       ]);
       // `deletedAt` lives on the SoftDeletes mixin; this branch only runs for models
-      // that compose it (softDeletes === true).
-      (this as { deletedAt?: Date | null }).deletedAt = now;
+      // that compose it (softDeletes === true). Carbon, to match what a reload of
+      // this same row would put there.
+      (this as { deletedAt?: Carbon | null }).deletedAt = now;
     } else {
       await runSegs(conn, [
         `DELETE FROM ${ModelClass.table} WHERE ${ModelClass.primaryKey} = `,
@@ -2028,7 +2046,7 @@ export class BaseModel {
   async touch(): Promise<this> {
     const ModelClass = this.constructor as typeof BaseModel;
     if (!ModelClass.timestamps) return this;
-    this.updatedAt = new Date();
+    this.updatedAt = Carbon.now();
     this.markDirty("updatedAt" as keyof this);
     return this.save();
   }

package/src/model/SoftDeletes.ts

@@ -24,6 +24,7 @@ import { _resolveConn, type BaseModel } from "./BaseModel.ts";
 import { ModelQueryBuilder } from "./ModelQueryBuilder.ts";
 import { QueryBuilder } from "../db/QueryBuilder.ts";
 import type { Constructor } from "./mixins.ts";
+import type { Carbon } from "@zerotal/core/carbon";
 
 // Structural view of the concrete model class used by the static scopes.
 interface SoftDeleteModelClass<T extends BaseModel> {
@@ -63,8 +64,13 @@ export function SoftDeletes<TBase extends Constructor>(Base: TBase) {
     /** Engine switch — query scoping + schema `deleted_at` provisioning read this. */
     static softDeletes = true;
 
-    /** When the row was soft-deleted, or null/undefined when live. */
-    declare deletedAt?: Date | null;
+    /**
+     * When the row was soft-deleted, or null/undefined when live.
+     *
+     * A {@link Carbon}, like `createdAt`/`updatedAt` and every other `datetime`
+     * column — `.toISOString()` for a string, `.toDate()` for a native `Date`.
+     */
+    declare deletedAt?: Carbon | null;
 
     /** A query that INCLUDES soft-deleted rows (bypasses the default scope). */
     static withTrashed<T extends BaseModel>(this: SoftDeleteModelClass<T>): ModelQueryBuilder<T> {