@opensaas/stack-core 0.20.1 → 0.21.0

package/tests/field-hooks.test.ts

@@ -0,0 +1,410 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  ValidationError,
+  executeFieldResolveInputHooks,
+  executeFieldValidateHooks,
+  executeFieldBeforeOperationHooks,
+  executeFieldAfterOperationHooks,
+} from '../src/hooks/index.js'
+import { text } from '../src/fields/index.js'
+import type { AccessContext } from '../src/access/types.js'
+
+const mockContext = {
+  session: null,
+  prisma: {},
+  db: {},
+} as unknown as AccessContext
+
+describe('Field-level hook helpers', () => {
+  describe('executeFieldResolveInputHooks', () => {
+    it('should return data unchanged when no field hook is defined', async () => {
+      const fields = { name: text() }
+      const resolvedData = { name: 'john' }
+
+      const result = await executeFieldResolveInputHooks(
+        { name: 'john' },
+        resolvedData,
+        fields,
+        'create',
+        mockContext,
+        'User',
+      )
+
+      expect(result).toEqual({ name: 'john' })
+      // Should not mutate the passed reference
+      expect(result).not.toBe(resolvedData)
+    })
+
+    it('should transform field values via the field resolveInput hook', async () => {
+      const fields = {
+        name: text({
+          hooks: {
+            resolveInput: ({ resolvedData, fieldKey }) =>
+              (resolvedData[fieldKey] as string).toUpperCase(),
+          },
+        }),
+      }
+
+      const result = await executeFieldResolveInputHooks(
+        { name: 'john' },
+        { name: 'john' },
+        fields,
+        'create',
+        mockContext,
+        'User',
+      )
+
+      expect(result).toEqual({ name: 'JOHN' })
+    })
+
+    it('should pass the correct arguments to the field hook', async () => {
+      const resolveInput = vi.fn(({ resolvedData, fieldKey }) => resolvedData[fieldKey])
+      const fields = { name: text({ hooks: { resolveInput } }) }
+      const item = { id: '1', name: 'old' }
+
+      await executeFieldResolveInputHooks(
+        { name: 'john' },
+        { name: 'john' },
+        fields,
+        'update',
+        mockContext,
+        'User',
+        item,
+      )
+
+      expect(resolveInput).toHaveBeenCalledTimes(1)
+      expect(resolveInput).toHaveBeenCalledWith(
+        expect.objectContaining({
+          listKey: 'User',
+          fieldKey: 'name',
+          operation: 'update',
+          inputData: { name: 'john' },
+          item,
+          resolvedData: { name: 'john' },
+          context: mockContext,
+        }),
+      )
+    })
+
+    it('should skip fields that are not present in the data', async () => {
+      const resolveInput = vi.fn(({ resolvedData, fieldKey }) => resolvedData[fieldKey])
+      const fields = { name: text({ hooks: { resolveInput } }) }
+
+      const result = await executeFieldResolveInputHooks(
+        { other: 'value' },
+        { other: 'value' },
+        fields,
+        'create',
+        mockContext,
+        'User',
+      )
+
+      expect(resolveInput).not.toHaveBeenCalled()
+      expect(result).toEqual({ other: 'value' })
+    })
+  })
+
+  describe('executeFieldValidateHooks', () => {
+    it('should not throw when no field hook is defined', async () => {
+      const fields = { name: text() }
+
+      await expect(
+        executeFieldValidateHooks(
+          { name: 'john' },
+          { name: 'john' },
+          fields,
+          'create',
+          mockContext,
+          'User',
+        ),
+      ).resolves.toBeUndefined()
+    })
+
+    it('should accumulate errors from multiple fields and throw a ValidationError', async () => {
+      const fields = {
+        name: text({
+          hooks: {
+            validate: ({ addValidationError }) => {
+              addValidationError('name is invalid')
+            },
+          },
+        }),
+        email: text({
+          hooks: {
+            validate: ({ addValidationError }) => {
+              addValidationError('email is invalid')
+            },
+          },
+        }),
+      }
+
+      let caught: unknown
+      try {
+        await executeFieldValidateHooks(
+          { name: 'x', email: 'y' },
+          { name: 'x', email: 'y' },
+          fields,
+          'create',
+          mockContext,
+          'User',
+        )
+      } catch (error) {
+        caught = error
+      }
+
+      expect(caught).toBeInstanceOf(ValidationError)
+      const validationError = caught as ValidationError
+      expect(validationError.errors).toEqual(['name is invalid', 'email is invalid'])
+      expect(validationError.fieldErrors).toEqual({
+        name: 'name is invalid',
+        email: 'email is invalid',
+      })
+    })
+
+    it('should not throw when no validation errors are added', async () => {
+      const validate = vi.fn()
+      const fields = { name: text({ hooks: { validate } }) }
+
+      await expect(
+        executeFieldValidateHooks(
+          { name: 'john' },
+          { name: 'john' },
+          fields,
+          'create',
+          mockContext,
+          'User',
+        ),
+      ).resolves.toBeUndefined()
+      expect(validate).toHaveBeenCalledTimes(1)
+    })
+
+    it('should pass delete-shaped arguments for delete operations', async () => {
+      const validate = vi.fn()
+      const fields = { name: text({ hooks: { validate } }) }
+      const item = { id: '1', name: 'john' }
+
+      await executeFieldValidateHooks(
+        undefined,
+        undefined,
+        fields,
+        'delete',
+        mockContext,
+        'User',
+        item,
+      )
+
+      expect(validate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          listKey: 'User',
+          fieldKey: 'name',
+          operation: 'delete',
+          item,
+          context: mockContext,
+        }),
+      )
+    })
+
+    it('should support the deprecated validateInput hook', async () => {
+      const fields = {
+        name: text({
+          hooks: {
+            validateInput: ({ addValidationError }) => {
+              addValidationError('legacy error')
+            },
+          },
+        }),
+      }
+
+      await expect(
+        executeFieldValidateHooks(
+          { name: 'x' },
+          { name: 'x' },
+          fields,
+          'create',
+          mockContext,
+          'User',
+        ),
+      ).rejects.toBeInstanceOf(ValidationError)
+    })
+  })
+
+  describe('executeFieldBeforeOperationHooks', () => {
+    it('should do nothing when no field hook is defined', async () => {
+      const fields = { name: text() }
+
+      await expect(
+        executeFieldBeforeOperationHooks(
+          { name: 'john' },
+          { name: 'john' },
+          fields,
+          'create',
+          mockContext,
+          'User',
+        ),
+      ).resolves.toBeUndefined()
+    })
+
+    it('should call the hook with create-shaped arguments', async () => {
+      const beforeOperation = vi.fn()
+      const fields = { name: text({ hooks: { beforeOperation } }) }
+
+      await executeFieldBeforeOperationHooks(
+        { name: 'john' },
+        { name: 'john' },
+        fields,
+        'create',
+        mockContext,
+        'User',
+      )
+
+      expect(beforeOperation).toHaveBeenCalledWith(
+        expect.objectContaining({
+          listKey: 'User',
+          fieldKey: 'name',
+          operation: 'create',
+          inputData: { name: 'john' },
+          resolvedData: { name: 'john' },
+          context: mockContext,
+        }),
+      )
+    })
+
+    it('should skip fields not present in resolvedData for create/update', async () => {
+      const beforeOperation = vi.fn()
+      const fields = { name: text({ hooks: { beforeOperation } }) }
+
+      await executeFieldBeforeOperationHooks(
+        { other: 'value' },
+        { other: 'value' },
+        fields,
+        'update',
+        mockContext,
+        'User',
+      )
+
+      expect(beforeOperation).not.toHaveBeenCalled()
+    })
+
+    it('should run the hook for delete even when the field is not in resolvedData', async () => {
+      const beforeOperation = vi.fn()
+      const fields = { name: text({ hooks: { beforeOperation } }) }
+      const item = { id: '1', name: 'john' }
+
+      await executeFieldBeforeOperationHooks({}, {}, fields, 'delete', mockContext, 'User', item)
+
+      expect(beforeOperation).toHaveBeenCalledWith(
+        expect.objectContaining({
+          listKey: 'User',
+          fieldKey: 'name',
+          operation: 'delete',
+          item,
+          context: mockContext,
+        }),
+      )
+    })
+  })
+
+  describe('executeFieldAfterOperationHooks', () => {
+    it('should do nothing when no field hook is defined', async () => {
+      const fields = { name: text() }
+
+      await expect(
+        executeFieldAfterOperationHooks(
+          { id: '1', name: 'john' },
+          { name: 'john' },
+          { name: 'john' },
+          fields,
+          'create',
+          mockContext,
+          'User',
+        ),
+      ).resolves.toBeUndefined()
+    })
+
+    it('should call the hook with create-shaped arguments', async () => {
+      const afterOperation = vi.fn()
+      const fields = { name: text({ hooks: { afterOperation } }) }
+      const item = { id: '1', name: 'john' }
+
+      await executeFieldAfterOperationHooks(
+        item,
+        { name: 'john' },
+        { name: 'john' },
+        fields,
+        'create',
+        mockContext,
+        'User',
+      )
+
+      expect(afterOperation).toHaveBeenCalledWith(
+        expect.objectContaining({
+          listKey: 'User',
+          fieldKey: 'name',
+          operation: 'create',
+          inputData: { name: 'john' },
+          item,
+          resolvedData: { name: 'john' },
+          context: mockContext,
+        }),
+      )
+    })
+
+    it('should pass originalItem for update operations', async () => {
+      const afterOperation = vi.fn()
+      const fields = { name: text({ hooks: { afterOperation } }) }
+      const updated = { id: '1', name: 'new' }
+      const originalItem = { id: '1', name: 'old' }
+
+      await executeFieldAfterOperationHooks(
+        updated,
+        { name: 'new' },
+        { name: 'new' },
+        fields,
+        'update',
+        mockContext,
+        'User',
+        originalItem,
+      )
+
+      expect(afterOperation).toHaveBeenCalledWith(
+        expect.objectContaining({
+          listKey: 'User',
+          fieldKey: 'name',
+          operation: 'update',
+          inputData: { name: 'new' },
+          originalItem,
+          item: updated,
+          resolvedData: { name: 'new' },
+          context: mockContext,
+        }),
+      )
+    })
+
+    it('should pass delete-shaped arguments for delete operations', async () => {
+      const afterOperation = vi.fn()
+      const fields = { name: text({ hooks: { afterOperation } }) }
+      const originalItem = { id: '1', name: 'john' }
+
+      await executeFieldAfterOperationHooks(
+        originalItem,
+        undefined,
+        undefined,
+        fields,
+        'delete',
+        mockContext,
+        'User',
+        originalItem,
+      )
+
+      expect(afterOperation).toHaveBeenCalledWith(
+        expect.objectContaining({
+          listKey: 'User',
+          fieldKey: 'name',
+          operation: 'delete',
+          originalItem,
+          context: mockContext,
+        }),
+      )
+    })
+  })
+})

package/tests/field-types.test.ts

@@ -580,7 +580,7 @@ describe('Field Types', () => {
 
         expect(field.resultExtension).toBeDefined()
         expect(field.resultExtension?.outputType).toBe(
-          "import('@opensaas/stack-core').HashedPassword",
+          "import('@opensaas/stack-core/internal').HashedPassword",
         )
       })
     })

package/tests/hook-pipeline.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { hookPipeline } from '../src/context/hook-pipeline.js'
+import { ValidationError } from '../src/hooks/index.js'
+import { text } from '../src/fields/index.js'
+import type { ListConfig } from '../src/config/types.js'
+import type { AccessContext } from '../src/access/types.js'
+
+/**
+ * Unit tests for the Hook Pipeline — the module that owns the transform+validate
+ * span: list `resolveInput` → field `resolveInput` → list `validate` → field
+ * `validate` → built-in field rules (`validateFieldRules`). These drive
+ * `hookPipeline.run` directly (spy hooks + a list config), so the span order and
+ * the resolvedData threading become the test surface.
+ *
+ * Asserted here:
+ *   - the four hook phases + field rules run in the documented order;
+ *   - a list/field `validate` hook calling `addValidationError` THROWS
+ *     ValidationError (validation is never silent);
+ *   - a built-in field rule failure (isRequired) THROWS ValidationError;
+ *   - on success the pipeline returns the transformed `resolvedData`.
+ */
+
+// Shared ordered log of phase events for order assertions.
+let events: string[]
+
+/**
+ * Build a minimal AccessContext for the pipeline.
+ */
+function makeContext(): AccessContext {
+  return {
+    session: { userId: 'u1' },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    prisma: {} as any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    db: {} as any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    storage: {} as any,
+    plugins: {},
+    _isSudo: false,
+    _resolveOutputCounter: { depth: 0 },
+  }
+}
+
+/**
+ * A list config with a spy on every span hook, recording its phase into
+ * `events`. `title` is a required field so we can exercise built-in field rules.
+ */
+function makeListConfig(opts?: {
+  listValidateError?: string
+  fieldValidateError?: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+}): ListConfig<any> {
+  return {
+    fields: {
+      title: text({
+        validation: { isRequired: true },
+        hooks: {
+          resolveInput: async ({ resolvedData, fieldKey }) => {
+            events.push('field:resolveInput')
+            // Uppercase the value so we can assert resolvedData threads through.
+            const value = resolvedData[fieldKey]
+            return typeof value === 'string' ? value.toUpperCase() : value
+          },
+          validate: async ({ addValidationError }) => {
+            events.push('field:validate')
+            if (opts?.fieldValidateError) addValidationError(opts.fieldValidateError)
+          },
+        },
+      }),
+    },
+    access: {
+      operation: { query: () => true, create: () => true, update: () => true },
+    },
+    hooks: {
+      resolveInput: async ({ resolvedData }) => {
+        events.push('list:resolveInput')
+        return resolvedData
+      },
+      validate: async ({ addValidationError }) => {
+        events.push('list:validate')
+        if (opts?.listValidateError) addValidationError(opts.listValidateError)
+      },
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as ListConfig<any>
+}
+
+beforeEach(() => {
+  events = []
+})
+
+describe('Hook Pipeline — span order', () => {
+  it('runs create span phases in order: list resolveInput → field resolveInput → list validate → field validate → field rules', async () => {
+    const listConfig = makeListConfig()
+    const context = makeContext()
+
+    const { resolvedData } = await hookPipeline.run({
+      operation: 'create',
+      listName: 'Post',
+      listConfig,
+      inputData: { title: 'hi' },
+      item: undefined,
+      context,
+    })
+
+    expect(events).toEqual([
+      'list:resolveInput',
+      'field:resolveInput',
+      'list:validate',
+      'field:validate',
+    ])
+    expect(events.indexOf('list:resolveInput')).toBeLessThan(events.indexOf('field:resolveInput'))
+    expect(events.indexOf('field:resolveInput')).toBeLessThan(events.indexOf('list:validate'))
+    expect(events.indexOf('list:validate')).toBeLessThan(events.indexOf('field:validate'))
+    // resolvedData threads through the field resolveInput transform.
+    expect(resolvedData).toEqual({ title: 'HI' })
+  })
+
+  it('runs update span phases in order and passes the existing item through', async () => {
+    const listConfig = makeListConfig()
+    const context = makeContext()
+    const existing = { id: '1', title: 'old' }
+
+    const { resolvedData } = await hookPipeline.run({
+      operation: 'update',
+      listName: 'Post',
+      listConfig,
+      inputData: { title: 'new' },
+      item: existing,
+      context,
+    })
+
+    expect(events).toEqual([
+      'list:resolveInput',
+      'field:resolveInput',
+      'list:validate',
+      'field:validate',
+    ])
+    expect(resolvedData).toEqual({ title: 'NEW' })
+  })
+})
+
+describe('Hook Pipeline — validation throws (NOT silent)', () => {
+  it('throws ValidationError when a list validate hook calls addValidationError', async () => {
+    const listConfig = makeListConfig({ listValidateError: 'list says no' })
+    const context = makeContext()
+
+    await expect(
+      hookPipeline.run({
+        operation: 'create',
+        listName: 'Post',
+        listConfig,
+        inputData: { title: 'hi' },
+        item: undefined,
+        context,
+      }),
+    ).rejects.toBeInstanceOf(ValidationError)
+    // field:validate and field rules never run after a list validate failure.
+    expect(events).not.toContain('field:validate')
+  })
+
+  it('throws ValidationError when a field validate hook calls addValidationError', async () => {
+    const listConfig = makeListConfig({ fieldValidateError: 'field says no' })
+    const context = makeContext()
+
+    await expect(
+      hookPipeline.run({
+        operation: 'create',
+        listName: 'Post',
+        listConfig,
+        inputData: { title: 'hi' },
+        item: undefined,
+        context,
+      }),
+    ).rejects.toBeInstanceOf(ValidationError)
+    expect(events).toContain('field:validate')
+  })
+
+  it('throws ValidationError when a built-in field rule (isRequired) fails', async () => {
+    const listConfig = makeListConfig()
+    const context = makeContext()
+
+    await expect(
+      hookPipeline.run({
+        operation: 'create',
+        listName: 'Post',
+        listConfig,
+        inputData: {}, // title is required but absent
+        item: undefined,
+        context,
+      }),
+    ).rejects.toBeInstanceOf(ValidationError)
+    // The validate hooks ran before the rules threw.
+    expect(events).toContain('list:validate')
+    expect(events).toContain('field:validate')
+  })
+})
+
+describe('Hook Pipeline — resolvedData threading', () => {
+  it('returns the transformed resolvedData merged with list-level resolveInput changes', async () => {
+    const context = makeContext()
+    // List resolveInput injects an extra field; field resolveInput uppercases title.
+    const listConfig = {
+      fields: {
+        title: text({
+          hooks: {
+            resolveInput: async ({ resolvedData, fieldKey }) => {
+              const value = resolvedData[fieldKey]
+              return typeof value === 'string' ? value.toUpperCase() : value
+            },
+          },
+        }),
+        slug: text(),
+      },
+      access: { operation: { query: () => true, create: () => true } },
+      hooks: {
+        resolveInput: async ({ resolvedData }) => ({ ...resolvedData, slug: 'auto-slug' }),
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as ListConfig<any>
+
+    const { resolvedData } = await hookPipeline.run({
+      operation: 'create',
+      listName: 'Post',
+      listConfig,
+      inputData: { title: 'hello' },
+      item: undefined,
+      context,
+    })
+
+    expect(resolvedData).toEqual({ title: 'HELLO', slug: 'auto-slug' })
+  })
+})