@opensaas/stack-core 0.23.0 → 0.25.0

package/src/hooks/index.ts

@@ -214,6 +214,271 @@ export async function executeAfterOperation<
   await hooks.afterOperation(args as Parameters<typeof hooks.afterOperation>[0])
 }
 
+/**
+ * Execute list-level beforeTransaction hook (#590 / ADR-0010).
+ *
+ * Transaction-boundary hook: runs OUTSIDE the write's transaction, BEFORE it
+ * opens. A throw here aborts the write (the transaction never opens). The
+ * arguments mirror `beforeOperation` minus `resolvedData` (no input-shaping has
+ * run yet at the transaction boundary).
+ */
+export async function executeBeforeTransaction<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+>(
+  hooks: Hooks<TOutput, TCreateInput, TUpdateInput> | undefined,
+  args:
+    | {
+        listKey: string
+        operation: 'create'
+        inputData: TCreateInput
+        context: AccessContext
+      }
+    | {
+        listKey: string
+        operation: 'update'
+        inputData: TUpdateInput
+        item: TOutput | undefined
+        context: AccessContext
+      }
+    | {
+        listKey: string
+        operation: 'delete'
+        item: TOutput | undefined
+        context: AccessContext
+      },
+): Promise<void> {
+  if (!hooks?.beforeTransaction) {
+    return
+  }
+  await hooks.beforeTransaction(args as Parameters<typeof hooks.beforeTransaction>[0])
+}
+
+/**
+ * Execute list-level afterTransaction hook (#590 / ADR-0010).
+ *
+ * Transaction-boundary hook: runs OUTSIDE the write's transaction, AFTER it
+ * settles, and ALWAYS runs when the paired `beforeTransaction` ran. The
+ * `status` discriminant tells the hook whether the write committed (persisted
+ * `item` present) or rolled back (no `item`, `error` present).
+ */
+export async function executeAfterTransaction<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+>(
+  hooks: Hooks<TOutput, TCreateInput, TUpdateInput> | undefined,
+  args:
+    | {
+        listKey: string
+        operation: 'create'
+        status: 'committed'
+        inputData: TCreateInput
+        item: TOutput
+        context: AccessContext
+      }
+    | {
+        listKey: string
+        operation: 'create'
+        status: 'rolled-back'
+        inputData: TCreateInput
+        error: unknown
+        context: AccessContext
+      }
+    | {
+        listKey: string
+        operation: 'update'
+        status: 'committed'
+        inputData: TUpdateInput
+        originalItem: TOutput
+        item: TOutput
+        context: AccessContext
+      }
+    | {
+        listKey: string
+        operation: 'update'
+        status: 'rolled-back'
+        inputData: TUpdateInput
+        originalItem: TOutput | undefined
+        error: unknown
+        context: AccessContext
+      }
+    | {
+        listKey: string
+        operation: 'delete'
+        status: 'committed'
+        originalItem: TOutput
+        context: AccessContext
+      }
+    | {
+        listKey: string
+        operation: 'delete'
+        status: 'rolled-back'
+        originalItem: TOutput | undefined
+        error: unknown
+        context: AccessContext
+      },
+): Promise<void> {
+  if (!hooks?.afterTransaction) {
+    return
+  }
+  await hooks.afterTransaction(args as Parameters<typeof hooks.afterTransaction>[0])
+}
+
+/**
+ * Execute field-level beforeTransaction hooks (#590 / ADR-0010).
+ *
+ * Runs each field's `beforeTransaction` (side effects only). Like the list-level
+ * hook, these run OUTSIDE the transaction before it opens; a throw aborts the
+ * write. For create/update the field is only invoked when it appears in
+ * `inputData` (mirroring the field beforeOperation gate); for delete all fields
+ * with the hook run against the existing `item`.
+ */
+export async function executeFieldBeforeTransactionHooks(
+  inputData: Record<string, unknown> | undefined,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update' | 'delete',
+  context: AccessContext,
+  listKey: string,
+  item?: Record<string, unknown>,
+): Promise<void> {
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    if (!fieldConfig.hooks?.beforeTransaction) continue
+    if (operation !== 'delete' && !(inputData && fieldKey in inputData)) continue
+
+    if (operation === 'delete') {
+      await fieldConfig.hooks.beforeTransaction({
+        listKey,
+        fieldKey,
+        operation: 'delete',
+        item,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.beforeTransaction>[0])
+    } else if (operation === 'create') {
+      await fieldConfig.hooks.beforeTransaction({
+        listKey,
+        fieldKey,
+        operation: 'create',
+        inputData,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.beforeTransaction>[0])
+    } else {
+      await fieldConfig.hooks.beforeTransaction({
+        listKey,
+        fieldKey,
+        operation: 'update',
+        inputData,
+        item,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.beforeTransaction>[0])
+    }
+  }
+}
+
+/**
+ * Outcome of a settled write transaction, passed to afterTransaction hooks.
+ *
+ *  - `committed`: the write persisted; the persisted `item` (and, for
+ *    update/delete, `originalItem`) is available.
+ *  - `rolled-back`: the write was aborted/rolled back; NO persisted `item` —
+ *    only `inputData`/`originalItem` and the `error` that caused the rollback,
+ *    so hooks can compensate.
+ */
+export type TransactionOutcome =
+  | { status: 'committed'; item: Record<string, unknown> }
+  | { status: 'rolled-back'; error: unknown }
+
+/**
+ * Execute field-level afterTransaction hooks (#590 / ADR-0010).
+ *
+ * Runs each field's `afterTransaction` (side effects only) with the settled
+ * transaction outcome. On commit the field receives the persisted `item`/
+ * `originalItem` — but ONLY for the top-level list (`isTopLevel`); for nested
+ * lists they are `undefined`, since `outcome.item` is the top-level persisted
+ * row and handing it to a nested field's hook would be unsound. On rollback the
+ * field receives the `error` and NO `item`. Unlike the field `afterOperation`
+ * gate, EVERY field with the hook runs (compensation must not depend on the
+ * field appearing in the payload).
+ */
+export async function executeFieldAfterTransactionHooks(
+  outcome: TransactionOutcome,
+  inputData: Record<string, unknown> | undefined,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update' | 'delete',
+  context: AccessContext,
+  listKey: string,
+  isTopLevel: boolean,
+  originalItem?: Record<string, unknown>,
+): Promise<void> {
+  // The persisted/pre-write rows are surfaced only for the top-level list.
+  const committedItem = outcome.status === 'committed' && isTopLevel ? outcome.item : undefined
+  const committedOriginalItem = isTopLevel ? originalItem : undefined
+
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    if (!fieldConfig.hooks?.afterTransaction) continue
+
+    const base = { listKey, fieldKey, context }
+
+    if (outcome.status === 'rolled-back') {
+      if (operation === 'delete') {
+        await fieldConfig.hooks.afterTransaction({
+          ...base,
+          operation: 'delete',
+          status: 'rolled-back',
+          originalItem,
+          error: outcome.error,
+        } as Parameters<typeof fieldConfig.hooks.afterTransaction>[0])
+      } else if (operation === 'create') {
+        await fieldConfig.hooks.afterTransaction({
+          ...base,
+          operation: 'create',
+          status: 'rolled-back',
+          inputData,
+          error: outcome.error,
+        } as Parameters<typeof fieldConfig.hooks.afterTransaction>[0])
+      } else {
+        await fieldConfig.hooks.afterTransaction({
+          ...base,
+          operation: 'update',
+          status: 'rolled-back',
+          inputData,
+          originalItem,
+          error: outcome.error,
+        } as Parameters<typeof fieldConfig.hooks.afterTransaction>[0])
+      }
+      continue
+    }
+
+    // committed
+    if (operation === 'delete') {
+      await fieldConfig.hooks.afterTransaction({
+        ...base,
+        operation: 'delete',
+        status: 'committed',
+        originalItem: committedOriginalItem,
+      } as Parameters<typeof fieldConfig.hooks.afterTransaction>[0])
+    } else if (operation === 'create') {
+      await fieldConfig.hooks.afterTransaction({
+        ...base,
+        operation: 'create',
+        status: 'committed',
+        inputData,
+        item: committedItem,
+      } as Parameters<typeof fieldConfig.hooks.afterTransaction>[0])
+    } else {
+      await fieldConfig.hooks.afterTransaction({
+        ...base,
+        operation: 'update',
+        status: 'committed',
+        inputData,
+        originalItem: committedOriginalItem,
+        item: committedItem,
+      } as Parameters<typeof fieldConfig.hooks.afterTransaction>[0])
+    }
+  }
+}
+
 /**
  * Execute field-level resolveInput hooks
  * Allows fields to transform their input values before database write

package/src/validation/schema.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest'
 import { generateZodSchema, validateWithZod } from './schema.js'
 import type { FieldConfig } from '../config/types.js'
-import { text, integer, select } from '../fields/index.js'
+import { text, integer, select, calendarDay, json, password } from '../fields/index.js'
 
 describe('Zod Schema Generation', () => {
   describe('generateZodSchema', () => {
@@ -219,4 +219,269 @@ describe('Zod Schema Generation', () => {
       expect(result.success).toBe(true)
     })
   })
+
+  // Regression: issue #570
+  // Under zod 4.4, `z.union([schema, z.undefined()])` rejects a MISSING key,
+  // so partial updates that omit a required-on-create field used to throw a
+  // ValidationError before the DB write. Update-shapes must use key-optionality
+  // (`.optional()`) so validation only checks the keys actually present.
+  describe('omitted required field on update (issue #570)', () => {
+    it('passes when a required text field is omitted while another field is present', () => {
+      const fields: Record<string, FieldConfig> = {
+        name: text({ validation: { isRequired: true } }),
+        bio: text(),
+      }
+
+      const result = validateWithZod({ bio: 'hello' }, fields, 'update')
+      expect(result.success).toBe(true)
+    })
+
+    it('still enforces present-value rules for a required text field on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        name: text({ validation: { isRequired: true } }),
+      }
+
+      // Empty string must still be rejected when the key IS present
+      const result = validateWithZod({ name: '' }, fields, 'update')
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.errors).toHaveProperty('name')
+      }
+    })
+
+    it('still enforces length rules for a required text field present on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        title: text({ validation: { isRequired: true, length: { min: 5 } } }),
+      }
+
+      const result = validateWithZod({ title: 'Hi' }, fields, 'update')
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.errors.title).toContain('at least 5 characters')
+      }
+    })
+
+    it('keeps required text fields required on create', () => {
+      const fields: Record<string, FieldConfig> = {
+        name: text({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({}, fields, 'create')
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.errors).toHaveProperty('name')
+      }
+    })
+
+    it('allows an omitted required calendarDay field on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        startsOn: calendarDay({ validation: { isRequired: true } }),
+        label: text(),
+      }
+
+      const result = validateWithZod({ label: 'x' }, fields, 'update')
+      expect(result.success).toBe(true)
+    })
+
+    it('still rejects an invalid calendarDay value when present on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        startsOn: calendarDay({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({ startsOn: 'not-a-date' }, fields, 'update')
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.errors).toHaveProperty('startsOn')
+      }
+    })
+
+    it('allows an omitted required json field on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+        label: text(),
+      }
+
+      const result = validateWithZod({ label: 'x' }, fields, 'update')
+      expect(result.success).toBe(true)
+    })
+
+    it('allows an omitted required password field on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        secret: password({ validation: { isRequired: true } }),
+        label: text(),
+      }
+
+      const result = validateWithZod({ label: 'x' }, fields, 'update')
+      expect(result.success).toBe(true)
+    })
+
+    it('still rejects an empty required password value when present on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        secret: password({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({ secret: '' }, fields, 'update')
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.errors).toHaveProperty('secret')
+      }
+    })
+  })
+
+  // Regression: issue #597
+  // A bare `z.unknown()` is treated as optional inside `z.object(...)`, so a
+  // required-on-create json field used to pass when the key was omitted. The
+  // create branch now refines the schema to reject undefined/absent keys while
+  // still accepting any present non-null JSON value (object, array, primitive).
+  // A present null is rejected by the issue #604 tightening below.
+  describe('required json on create (issue #597)', () => {
+    it('rejects an omitted required json field on create (key absent)', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+        label: text(),
+      }
+
+      const result = validateWithZod({ label: 'x' }, fields, 'create')
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.errors).toHaveProperty('meta')
+        expect(result.errors.meta).toContain('is required')
+      }
+    })
+
+    it('rejects an explicit undefined required json field on create', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({ meta: undefined }, fields, 'create')
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.errors).toHaveProperty('meta')
+      }
+    })
+
+    it('accepts a present object value for a required json field on create', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({ meta: { a: 1 } }, fields, 'create')
+      expect(result.success).toBe(true)
+    })
+
+    it('accepts a present array value for a required json field on create', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({ meta: [] }, fields, 'create')
+      expect(result.success).toBe(true)
+    })
+
+    it('accepts a present primitive (0) value for a required json field on create', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({ meta: 0 }, fields, 'create')
+      expect(result.success).toBe(true)
+    })
+
+    it('allows an omitted non-required json field on create', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json(),
+        label: text(),
+      }
+
+      const result = validateWithZod({ label: 'x' }, fields, 'create')
+      expect(result.success).toBe(true)
+    })
+  })
+
+  // Regression: issue #604
+  // A required json field means non-null. A present `null` must be rejected at
+  // the validation layer (with a clear message) instead of surfacing later as a
+  // DB NOT NULL violation. Omission on update must still pass (#570), and
+  // omission on create must still be rejected (#597). Present non-null values
+  // — including falsy 0/""/false — are accepted. The Prisma column stays NOT
+  // NULL; only validation behaviour changes.
+  describe('required json is non-null (issue #604)', () => {
+    it('rejects a present null for a required json field on create', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({ meta: null }, fields, 'create')
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.errors).toHaveProperty('meta')
+        expect(result.errors.meta).toContain('is required')
+      }
+    })
+
+    it('rejects a present null for a required json field on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({ meta: null }, fields, 'update')
+      expect(result.success).toBe(false)
+      if (!result.success) {
+        expect(result.errors).toHaveProperty('meta')
+        expect(result.errors.meta).toContain('is required')
+      }
+    })
+
+    it('still allows an omitted required json field on update (preserves #570)', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+        label: text(),
+      }
+
+      const result = validateWithZod({ label: 'x' }, fields, 'update')
+      expect(result.success).toBe(true)
+    })
+
+    it('accepts a present object value for a required json field on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+      }
+
+      const result = validateWithZod({ meta: { a: 1 } }, fields, 'update')
+      expect(result.success).toBe(true)
+    })
+
+    it('accepts a present falsy non-null value for a required json field on update', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+      }
+
+      expect(validateWithZod({ meta: 0 }, fields, 'update').success).toBe(true)
+      expect(validateWithZod({ meta: '' }, fields, 'update').success).toBe(true)
+      expect(validateWithZod({ meta: false }, fields, 'update').success).toBe(true)
+    })
+
+    it('accepts present falsy non-null values for a required json field on create', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json({ validation: { isRequired: true } }),
+      }
+
+      expect(validateWithZod({ meta: 0 }, fields, 'create').success).toBe(true)
+      expect(validateWithZod({ meta: '' }, fields, 'create').success).toBe(true)
+      expect(validateWithZod({ meta: false }, fields, 'create').success).toBe(true)
+    })
+
+    it('accepts an omitted or present null value for a non-required json field', () => {
+      const fields: Record<string, FieldConfig> = {
+        meta: json(),
+        label: text(),
+      }
+
+      expect(validateWithZod({ label: 'x' }, fields, 'create').success).toBe(true)
+      expect(validateWithZod({ meta: null }, fields, 'create').success).toBe(true)
+      expect(validateWithZod({ label: 'x' }, fields, 'update').success).toBe(true)
+      expect(validateWithZod({ meta: null }, fields, 'update').success).toBe(true)
+    })
+  })
 })

package/tests/access.test.ts

@@ -9,6 +9,7 @@ import {
   isPrismaFilter,
 } from '../src/access/index.js'
 import type { AccessControl, FieldAccess, AccessContext } from '../src/access/types.js'
+import { ValidationError } from '../src/hooks/index.js'
 
 describe('Access Control', () => {
   const mockContext: AccessContext = {
@@ -406,7 +407,9 @@ describe('Access Control', () => {
       expect(result.name).toBe('John')
     })
 
-    it('should filter out fields with denied write access', async () => {
+    // #568: a denied write field must THROW (Keystone fail-loud parity), rather
+    // than being silently stripped. Updated from the old silent-strip contract.
+    it('should throw when a field with denied write access is supplied', async () => {
       const data = {
         name: 'John',
         email: 'john@example.com',
@@ -424,16 +427,21 @@ describe('Access Control', () => {
         },
       }
 
-      const result = await filterWritableFields(data, fieldConfigs, 'create', {
-        session: null,
-        context: mockContext,
-      })
-
-      expect(result.name).toBe('John')
-      expect(result.email).toBe('john@example.com')
-      expect(result.role).toBeUndefined()
+      await expect(
+        filterWritableFields(data, fieldConfigs, 'create', {
+          session: null,
+          context: mockContext,
+        }),
+      ).rejects.toThrow(ValidationError)
+      await expect(
+        filterWritableFields(data, fieldConfigs, 'create', {
+          session: null,
+          context: mockContext,
+        }),
+      ).rejects.toThrow(/role/)
     })
 
+    // #568: create-allowed / update-denied — create passes, update THROWS.
     it('should respect different access for create vs update', async () => {
       const data = {
         email: 'john@example.com',
@@ -457,13 +465,13 @@ describe('Access Control', () => {
 
       expect(createResult.email).toBe('john@example.com')
 
-      // Deny on update
-      const updateResult = await filterWritableFields(data, fieldConfigs, 'update', {
-        session: null,
-        context: mockContext,
-      })
-
-      expect(updateResult.email).toBeUndefined()
+      // Deny on update — now throws instead of silently dropping the field.
+      await expect(
+        filterWritableFields(data, fieldConfigs, 'update', {
+          session: null,
+          context: mockContext,
+        }),
+      ).rejects.toThrow(/email/)
     })
 
     it('should pass item to field access on update', async () => {

package/tests/config.test.ts

@@ -208,5 +208,35 @@ describe('config helpers', () => {
       expect(testList.hooks).toBeDefined()
       expect(testList.hooks?.resolveInput).toBeDefined()
     })
+
+    it('should accept ui.listView config (initialColumns + initialSort)', () => {
+      const testList = list({
+        fields: {
+          title: { type: 'text' },
+          status: { type: 'text' },
+          createdAt: { type: 'timestamp' },
+        },
+        ui: {
+          listView: {
+            initialColumns: ['title', 'status'],
+            initialSort: { field: 'createdAt', direction: 'desc' },
+          },
+        },
+      })
+
+      expect(testList.ui?.listView?.initialColumns).toEqual(['title', 'status'])
+      expect(testList.ui?.listView?.initialSort).toEqual({
+        field: 'createdAt',
+        direction: 'desc',
+      })
+    })
+
+    it('should leave ui undefined when not configured', () => {
+      const testList = list({
+        fields: { title: { type: 'text' } },
+      })
+
+      expect(testList.ui).toBeUndefined()
+    })
   })
 })