fix orm onUpdate timestamp normalization (#251)

Author: zbeyens

.changeset/stale-onupdate-dates.md

@@ -0,0 +1,7 @@
+---
+"kitcn": patch
+---
+
+## Patches
+
+- Fix ORM updates so timestamp `$onUpdateFn` hooks can return `Date` values.

convex/orm/constraints.test.ts

@@ -16,6 +16,7 @@ import {
   isNull,
   or,
   text,
+  timestamp,
   unique,
   unsetToken,
 } from 'kitcn/orm';
@@ -48,6 +49,14 @@ const hookUsers = convexTable(
   (t) => [index('by_name').on(t.name)]
 );
 
+const timestampHookUsers = convexTable('timestamp_hook_users', {
+  name: text().notNull(),
+  updatedAt: timestamp()
+    .notNull()
+    .defaultNow()
+    .$onUpdateFn(() => new Date('2026-04-27T09:02:18.240Z')),
+});
+
 const checkUsers = convexTable(
   'check_users',
   {
@@ -126,6 +135,7 @@ const polymorphicComments = convexTable(
 const rawSchema = {
   default_users: defaultUsers,
   hook_users: hookUsers,
+  timestamp_hook_users: timestampHookUsers,
   check_users: checkUsers,
   unique_column_users: uniqueColumnUsers,
   unique_table_users: uniqueTableUsers,
@@ -214,6 +224,23 @@ describe('column hooks', () => {
       }
     }));
 
+  it('normalizes timestamp $onUpdateFn Date values before patching', async () =>
+    withCtx(async ({ orm }) => {
+      const [user] = await orm
+        .insert(timestampHookUsers)
+        .values({ name: 'Ada' })
+        .returning();
+
+      const [updated] = await orm
+        .update(timestampHookUsers)
+        .set({ name: 'Updated' })
+        .where(eq(timestampHookUsers.id, user.id))
+        .returning();
+
+      expect(updated.name).toBe('Updated');
+      expect(updated.updatedAt).toEqual(new Date('2026-04-27T09:02:18.240Z'));
+    }));
+
   it('$onUpdateFn does not override explicit set', async () =>
     withCtx(async ({ orm }) => {
       hookUpdatedAtCalls = 0;

docs/plans/2026-04-27-issue-249-onupdate-date-normalization.md

@@ -0,0 +1,25 @@
+# Issue 249 onUpdate date normalization
+
+## Source
+
+- GitHub issue: https://github.com/udecode/kitcn/issues/249
+- Type: bug
+- Expected outcome: ORM update hooks returning `Date` for timestamp columns are
+  normalized before Convex `db.patch`.
+
+## Scope
+
+- Package code: `packages/kitcn/src/orm/update.ts`
+- Regression: `convex/orm/constraints.test.ts`
+- Release artifact: create or update an unreleased changeset.
+- Browser: not applicable.
+
+## Verification
+
+- Red regression for `timestamp().$onUpdateFn(() => new Date())`: confirmed
+  with `bunx vitest run convex/orm/constraints.test.ts -t "normalizes timestamp"`.
+- Targeted ORM test: `bunx vitest run convex/orm/constraints.test.ts`.
+- Package build: `bun --cwd packages/kitcn build`.
+- Lint fix: `bun lint:fix`.
+- Typecheck: `bun typecheck`.
+- PR gate: `bun check`.

packages/kitcn/src/orm/update.ts

@@ -464,6 +464,10 @@ export class ConvexUpdateBuilder<
       ...onUpdateSet,
       ...(normalizedSetValues as any),
     } as UpdateSet<TTable>;
+    const writeSet = normalizeDateFieldsForWrite(
+      this.table,
+      effectiveSet as any
+    ) as UpdateSet<TTable>;
 
     const tableName = getTableName(this.table);
 
@@ -636,7 +640,7 @@ export class ConvexUpdateBuilder<
 
     const updates = await Promise.all(
       rows.map(async (row) => {
-        const updatedRow = { ...(row as any), ...(effectiveSet as any) };
+        const updatedRow = { ...(row as any), ...(writeSet as any) };
         const decision = await evaluateUpdateDecision({
           table: this.table,
           existingRow: row as Record<string, unknown>,
@@ -669,11 +673,11 @@ export class ConvexUpdateBuilder<
         continue;
       }
       enforcePolymorphicWrite(this.table, updatedRow, {
-        changedFields: new Set(Object.keys(effectiveSet as any)),
+        changedFields: new Set(Object.keys(writeSet as any)),
       });
       enforceCheckConstraints(this.table, updatedRow);
       await enforceForeignKeys(this.db, this.table, updatedRow, {
-        changedFields: new Set(Object.keys(effectiveSet as any)),
+        changedFields: new Set(Object.keys(writeSet as any)),
       });
 
       await applyIncomingForeignKeyActionsOnUpdate(
@@ -698,9 +702,9 @@ export class ConvexUpdateBuilder<
       );
       await enforceUniqueIndexes(this.db, this.table, updatedRow, {
         currentId: (row as any)._id,
-        changedFields: new Set(Object.keys(effectiveSet as any)),
+        changedFields: new Set(Object.keys(writeSet as any)),
       });
-      await this.db.patch(tableName, (row as any)._id, effectiveSet as any);
+      await this.db.patch(tableName, (row as any)._id, writeSet as any);
       numAffected++;
 
       if (!this.returningFields) {