@opensaas/stack-core 0.1.7 → 0.4.0

package/src/fields/index.ts

@@ -8,6 +8,7 @@ import type {
   SelectField,
   RelationshipField,
   JsonField,
+  VirtualField,
 } from '../config/types.js'
 import { hashPassword, isHashedPassword, HashedPassword } from '../utils/password.js'
 
@@ -24,7 +25,9 @@ function formatFieldName(fieldName: string): string {
 /**
  * Text field
  */
-export function text(options?: Omit<TextField, 'type'>): TextField {
+export function text<
+  TTypeInfo extends import('../config/types.js').TypeInfo = import('../config/types.js').TypeInfo,
+>(options?: Omit<TextField<TTypeInfo>, 'type'>): TextField<TTypeInfo> {
   return {
     type: 'text',
     ...options,
@@ -59,7 +62,7 @@ export function text(options?: Omit<TextField, 'type'>): TextField {
         return z.union([withMax, z.undefined()])
       }
 
-      return !isRequired ? withMax.optional() : withMax
+      return !isRequired ? withMax.optional().nullable() : withMax
     },
     getPrismaType: () => {
       const validation = options?.validation
@@ -98,7 +101,9 @@ export function text(options?: Omit<TextField, 'type'>): TextField {
 /**
  * Integer field
  */
-export function integer(options?: Omit<IntegerField, 'type'>): IntegerField {
+export function integer<
+  TTypeInfo extends import('../config/types.js').TypeInfo = import('../config/types.js').TypeInfo,
+>(options?: Omit<IntegerField<TTypeInfo>, 'type'>): IntegerField<TTypeInfo> {
   return {
     type: 'integer',
     ...options,
@@ -122,7 +127,7 @@ export function integer(options?: Omit<IntegerField, 'type'>): IntegerField {
           : withMin
 
       return !options?.validation?.isRequired || operation === 'update'
-        ? withMax.optional()
+        ? withMax.optional().nullable()
         : withMax
     },
     getPrismaType: () => {
@@ -147,12 +152,14 @@ export function integer(options?: Omit<IntegerField, 'type'>): IntegerField {
 /**
  * Checkbox (boolean) field
  */
-export function checkbox(options?: Omit<CheckboxField, 'type'>): CheckboxField {
+export function checkbox<
+  TTypeInfo extends import('../config/types.js').TypeInfo = import('../config/types.js').TypeInfo,
+>(options?: Omit<CheckboxField<TTypeInfo>, 'type'>): CheckboxField<TTypeInfo> {
   return {
     type: 'checkbox',
     ...options,
     getZodSchema: () => {
-      return z.boolean().optional()
+      return z.boolean().optional().nullable()
     },
     getPrismaType: () => {
       const hasDefault = options?.defaultValue !== undefined
@@ -179,12 +186,14 @@ export function checkbox(options?: Omit<CheckboxField, 'type'>): CheckboxField {
 /**
  * Timestamp (DateTime) field
  */
-export function timestamp(options?: Omit<TimestampField, 'type'>): TimestampField {
+export function timestamp<
+  TTypeInfo extends import('../config/types.js').TypeInfo = import('../config/types.js').TypeInfo,
+>(options?: Omit<TimestampField<TTypeInfo>, 'type'>): TimestampField<TTypeInfo> {
   return {
     type: 'timestamp',
     ...options,
     getZodSchema: () => {
-      return z.union([z.date(), z.iso.datetime()]).optional()
+      return z.union([z.date(), z.iso.datetime()]).optional().nullable()
     },
     getPrismaType: () => {
       let modifiers = '?'
@@ -270,33 +279,32 @@ export function timestamp(options?: Omit<TimestampField, 'type'>): TimestampFiel
  * @param options - Field configuration options
  * @returns Password field configuration
  */
-export function password(options?: Omit<PasswordField, 'type'>): PasswordField {
+export function password<TTypeInfo extends import('../config/types.js').TypeInfo>(
+  options?: Omit<PasswordField<TTypeInfo>, 'type'>,
+): PasswordField<TTypeInfo> {
   return {
     type: 'password',
     ...options,
-    typePatch: {
-      resultType: "import('@opensaas/stack-core').HashedPassword",
-      patchScope: 'scalars-only',
+    resultExtension: {
+      outputType: "import('@opensaas/stack-core').HashedPassword",
+      // No compute - delegates to resolveOutput hook
     },
     ui: {
       ...options?.ui,
       valueForClientSerialization: ({ value }) => ({ isSet: !!value }),
     },
+    // Cast hooks to any since field builders are generic and can't know the specific TFieldKey
     hooks: {
       // Hash password before writing to database
-      resolveInput: async ({ inputValue }) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks must be generic
+      resolveInput: async ({ inputValue }: { inputValue: any }) => {
         // Skip if undefined or null (allows partial updates)
         if (inputValue === undefined || inputValue === null) {
           return inputValue
         }
 
         // Skip if not a string
-        if (typeof inputValue !== 'string') {
-          return inputValue
-        }
-
-        // Skip empty strings (let validation handle this)
-        if (inputValue.length === 0) {
+        if (typeof inputValue !== 'string' || inputValue.length === 0) {
           return inputValue
         }
 
@@ -309,7 +317,8 @@ export function password(options?: Omit<PasswordField, 'type'>): PasswordField {
         return await hashPassword(inputValue)
       },
       // Wrap password with HashedPassword class after reading from database
-      resolveOutput: ({ value }) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks must be generic
+      resolveOutput: ({ value }: { value: any }) => {
         // Only wrap string values (hashed passwords)
         if (typeof value === 'string' && value.length > 0) {
           return new HashedPassword(value)
@@ -318,7 +327,8 @@ export function password(options?: Omit<PasswordField, 'type'>): PasswordField {
       },
       // Merge with user-provided hooks if any
       ...options?.hooks,
-    },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hook object needs type assertion for field builder
+    } as any,
     getZodSchema: (fieldName: string, operation: 'create' | 'update') => {
       const validation = options?.validation
       const isRequired = validation?.isRequired
@@ -347,6 +357,7 @@ export function password(options?: Omit<PasswordField, 'type'>): PasswordField {
             message: `${formatFieldName(fieldName)} must be text`,
           })
           .optional()
+          .nullable()
       }
     },
     getPrismaType: () => {
@@ -371,7 +382,9 @@ export function password(options?: Omit<PasswordField, 'type'>): PasswordField {
 /**
  * Select field (enum-like)
  */
-export function select(options: Omit<SelectField, 'type'>): SelectField {
+export function select<
+  TTypeInfo extends import('../config/types.js').TypeInfo = import('../config/types.js').TypeInfo,
+>(options: Omit<SelectField<TTypeInfo>, 'type'>): SelectField<TTypeInfo> {
   if (!options.options || options.options.length === 0) {
     throw new Error('Select field must have at least one option')
   }
@@ -386,7 +399,7 @@ export function select(options: Omit<SelectField, 'type'>): SelectField {
       })
 
       if (!options.validation?.isRequired || operation === 'update') {
-        schema = schema.optional()
+        schema = schema.optional().nullable()
       }
 
       return schema
@@ -419,7 +432,9 @@ export function select(options: Omit<SelectField, 'type'>): SelectField {
 /**
  * Relationship field
  */
-export function relationship(options: Omit<RelationshipField, 'type'>): RelationshipField {
+export function relationship<
+  TTypeInfo extends import('../config/types.js').TypeInfo = import('../config/types.js').TypeInfo,
+>(options: Omit<RelationshipField<TTypeInfo>, 'type'>): RelationshipField<TTypeInfo> {
   if (!options.ref) {
     throw new Error('Relationship field must have a ref')
   }
@@ -481,7 +496,9 @@ export function relationship(options: Omit<RelationshipField, 'type'>): Relation
  * @param options - Field configuration options
  * @returns JSON field configuration
  */
-export function json(options?: Omit<JsonField, 'type'>): JsonField {
+export function json<
+  TTypeInfo extends import('../config/types.js').TypeInfo = import('../config/types.js').TypeInfo,
+>(options?: Omit<JsonField<TTypeInfo>, 'type'>): JsonField<TTypeInfo> {
   return {
     type: 'json',
     ...options,
@@ -499,8 +516,8 @@ export function json(options?: Omit<JsonField, 'type'>): JsonField {
         // Required in update mode: can be undefined for partial updates
         return z.union([baseSchema, z.undefined()])
       } else {
-        // Not required: can be undefined
-        return baseSchema.optional()
+        // Not required: can be undefined or null
+        return baseSchema.optional().nullable()
       }
     },
     getPrismaType: () => {
@@ -521,3 +538,91 @@ export function json(options?: Omit<JsonField, 'type'>): JsonField {
     },
   }
 }
+
+/**
+ * Virtual field - not stored in database, computed via hooks
+ *
+ * **Features:**
+ * - Does not create a column in the database
+ * - Uses resolveOutput hook to compute value from other fields
+ * - Optionally uses resolveInput hook for write side effects (e.g., sync to external API)
+ * - Only computed when explicitly selected/included in queries
+ * - Supports both read and write operations via hooks
+ *
+ * **Usage Example:**
+ * ```typescript
+ * // Read-only computed field
+ * fields: {
+ *   firstName: text(),
+ *   lastName: text(),
+ *   fullName: virtual({
+ *     type: 'string',
+ *     hooks: {
+ *       resolveOutput: ({ item }) => `${item.firstName} ${item.lastName}`
+ *     }
+ *   })
+ * }
+ *
+ * // Write side effects (e.g., sync to external API)
+ * fields: {
+ *   externalSync: virtual({
+ *     type: 'boolean',
+ *     hooks: {
+ *       resolveInput: async ({ item }) => {
+ *         await syncToExternalAPI(item)
+ *         return undefined // Don't store anything
+ *       },
+ *       resolveOutput: () => true
+ *     }
+ *   })
+ * }
+ *
+ * // Query with select
+ * const user = await context.db.user.findUnique({
+ *   where: { id },
+ *   select: { firstName: true, lastName: true, fullName: true } // fullName computed
+ * })
+ * ```
+ *
+ * **Requirements:**
+ * - Must provide `type` (TypeScript type string)
+ * - Must provide `resolveOutput` hook (for reads)
+ * - Optional `resolveInput` hook (for write side effects)
+ *
+ * @param options - Virtual field configuration
+ * @returns Virtual field configuration
+ */
+export function virtual<TTypeInfo extends import('../config/types.js').TypeInfo>(
+  options: Omit<VirtualField<TTypeInfo>, 'virtual' | 'outputType' | 'type'> & { type: string },
+): VirtualField<TTypeInfo> {
+  // Validate that resolveOutput is provided
+  if (!options.hooks?.resolveOutput) {
+    throw new Error(
+      'Virtual fields must provide a resolveOutput hook to compute their value. ' +
+        'Example: hooks: { resolveOutput: ({ item }) => computeValue(item) }',
+    )
+  }
+
+  const { type: outputType, ...rest } = options
+
+  return {
+    type: 'virtual',
+    virtual: true,
+    outputType,
+    ...rest,
+    // Virtual fields don't create database columns
+    // Return undefined to signal generator to skip this field
+    getPrismaType: undefined,
+    // Virtual fields appear in output types with their specified type
+    getTypeScriptType: () => {
+      return {
+        type: options.type,
+        optional: false, // Virtual fields always compute a value
+      }
+    },
+    // Virtual fields never validate input (they don't accept database input)
+    getZodSchema: () => {
+      return z.never()
+    },
+  }
+}

package/src/hooks/index.ts

@@ -18,24 +18,53 @@ export class ValidationError extends Error {
   }
 }
 
+/**
+ * Database error with field-specific error information
+ * Used for Prisma errors like unique constraint violations
+ */
+export class DatabaseError extends Error {
+  public fieldErrors: Record<string, string>
+  public code?: string
+
+  constructor(message: string, fieldErrors: Record<string, string> = {}, code?: string) {
+    super(message)
+    this.name = 'DatabaseError'
+    this.fieldErrors = fieldErrors
+    this.code = code
+  }
+}
+
 /**
  * Execute resolveInput hook
  * Allows modification of input data before validation
  */
-export async function executeResolveInput<T = Record<string, unknown>>(
-  hooks: Hooks<T> | undefined,
-  args: {
-    operation: 'create' | 'update'
-    resolvedData: Partial<T>
-    item?: T
-    context: AccessContext
-  },
-): Promise<Partial<T>> {
+export async function executeResolveInput<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+>(
+  hooks: Hooks<TOutput, TCreateInput, TUpdateInput> | undefined,
+  args:
+    | {
+        operation: 'create'
+        resolvedData: TCreateInput
+        item?: undefined
+        context: AccessContext
+      }
+    | {
+        operation: 'update'
+        resolvedData: TUpdateInput
+        item?: TOutput
+        context: AccessContext
+      },
+): Promise<TCreateInput | TUpdateInput> {
   if (!hooks?.resolveInput) {
     return args.resolvedData
   }
 
-  const result = await hooks.resolveInput(args)
+  // Type assertion is safe because we've constrained the args type
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result = await hooks.resolveInput(args as any)
   return result
 }
 
@@ -43,12 +72,16 @@ export async function executeResolveInput<T = Record<string, unknown>>(
  * Execute validateInput hook
  * Allows custom validation logic
  */
-export async function executeValidateInput<T = Record<string, unknown>>(
-  hooks: Hooks<T> | undefined,
+export async function executeValidateInput<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+>(
+  hooks: Hooks<TOutput, TCreateInput, TUpdateInput> | undefined,
   args: {
     operation: 'create' | 'update'
-    resolvedData: Partial<T>
-    item?: T
+    resolvedData: TCreateInput | TUpdateInput
+    item?: TOutput
     context: AccessContext
   },
 ): Promise<void> {
@@ -76,11 +109,16 @@ export async function executeValidateInput<T = Record<string, unknown>>(
  * Execute beforeOperation hook
  * Runs before database operation (cannot modify data)
  */
-export async function executeBeforeOperation<T = Record<string, unknown>>(
-  hooks: Hooks<T> | undefined,
+export async function executeBeforeOperation<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+>(
+  hooks: Hooks<TOutput, TCreateInput, TUpdateInput> | undefined,
   args: {
     operation: 'create' | 'update' | 'delete'
-    item?: T
+    resolvedData?: TCreateInput | TUpdateInput
+    item?: TOutput
     context: AccessContext
   },
 ): Promise<void> {
@@ -95,11 +133,16 @@ export async function executeBeforeOperation<T = Record<string, unknown>>(
  * Execute afterOperation hook
  * Runs after database operation
  */
-export async function executeAfterOperation<T = Record<string, unknown>>(
-  hooks: Hooks<T> | undefined,
+export async function executeAfterOperation<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+>(
+  hooks: Hooks<TOutput, TCreateInput, TUpdateInput> | undefined,
   args: {
     operation: 'create' | 'update' | 'delete'
-    item: T
+    resolvedData?: TCreateInput | TUpdateInput
+    item: TOutput
     context: AccessContext
   },
 ): Promise<void> {

package/src/index.ts

@@ -12,15 +12,24 @@ export type {
   PasswordField,
   SelectField,
   RelationshipField,
+  JsonField,
+  VirtualField,
+  TypeInfo,
   OperationAccess,
   Hooks,
   FieldHooks,
+  FieldsWithTypeInfo,
   DatabaseConfig,
   SessionConfig,
   UIConfig,
   ThemeConfig,
   ThemePreset,
   ThemeColors,
+  McpConfig,
+  McpToolsConfig,
+  McpAuthConfig,
+  ListMcpConfig,
+  McpCustomTool,
   FileMetadata,
   ImageMetadata,
   ImageTransformationResult,

package/src/mcp/handler.ts

@@ -248,7 +248,8 @@ function generateFieldSchemas(
     if (
       operation === 'create' &&
       'validation' in fieldConfig &&
-      fieldConfig.validation?.isRequired
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Validation property varies by field type
+      (fieldConfig.validation as any)?.isRequired
     ) {
       required.push(fieldName)
     }

package/src/validation/schema.ts

@@ -11,10 +11,12 @@ export function generateZodSchema(
   const shape: Record<string, z.ZodTypeAny> = {}
 
   for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
-    // Skip system fields and relationships
+    // Skip system fields, relationships, and virtual fields
+    // Virtual fields don't accept input - they only compute output
     if (
       ['id', 'createdAt', 'updatedAt'].includes(fieldName) ||
-      fieldConfig.type === 'relationship'
+      fieldConfig.type === 'relationship' ||
+      fieldConfig.virtual
     ) {
       continue
     }

package/tests/context.test.ts

@@ -101,7 +101,7 @@ describe('getContext', () => {
       expect(mockPrisma.user.create).toHaveBeenCalledWith({
         data: { name: 'John', email: 'john@example.com' },
       })
-      expect(result).toEqual(mockCreatedUser)
+      expect(result).toEqual({ success: true, data: mockCreatedUser })
     })
 
     it('should update an item', async () => {
@@ -121,7 +121,7 @@ describe('getContext', () => {
 
       expect(mockPrisma.user.findUnique).toHaveBeenCalled()
       expect(mockPrisma.user.update).toHaveBeenCalled()
-      expect(result).toEqual(mockUpdatedUser)
+      expect(result).toEqual({ success: true, data: mockUpdatedUser })
     })
 
     it('should delete an item', async () => {
@@ -139,7 +139,7 @@ describe('getContext', () => {
 
       expect(mockPrisma.user.findUnique).toHaveBeenCalled()
       expect(mockPrisma.user.delete).toHaveBeenCalled()
-      expect(result).toEqual(mockDeletedUser)
+      expect(result).toEqual({ success: true, data: mockDeletedUser })
     })
 
     it('should convert listKey to lowercase for db operations', async () => {
@@ -147,16 +147,17 @@ describe('getContext', () => {
       mockPrisma.post.create.mockResolvedValue(mockCreatedPost)
 
       const context = await getContext(config, mockPrisma, null)
-      await context.serverAction({
+      const result = await context.serverAction({
         listKey: 'Post',
         action: 'create',
         data: { title: 'Test Post' },
       })
 
       expect(mockPrisma.post.create).toHaveBeenCalled()
+      expect(result).toEqual({ success: true, data: mockCreatedPost })
     })
 
-    it('should return null for unknown action', async () => {
+    it('should return error for unknown action', async () => {
       const context = await getContext(config, mockPrisma, null)
       const result = await context.serverAction({
         listKey: 'User',
@@ -164,7 +165,38 @@ describe('getContext', () => {
         data: {},
       })
 
-      expect(result).toBeNull()
+      expect(result).toEqual({ success: false, error: 'Access denied or operation failed' })
+    })
+
+    it('should return error for unknown list', async () => {
+      const context = await getContext(config, mockPrisma, null)
+      const result = await context.serverAction({
+        listKey: 'UnknownList',
+        action: 'create',
+        data: {},
+      })
+
+      expect(result).toEqual({
+        success: false,
+        error: 'List "UnknownList" not found in configuration',
+      })
+    })
+
+    it('should handle database errors', async () => {
+      const dbError = new Error('Database connection failed')
+      mockPrisma.user.create.mockRejectedValue(dbError)
+
+      const context = await getContext(config, mockPrisma, null)
+      const result = await context.serverAction({
+        listKey: 'User',
+        action: 'create',
+        data: { name: 'John', email: 'john@example.com' },
+      })
+
+      expect(result).toMatchObject({
+        success: false,
+        error: 'Database connection failed',
+      })
     })
   })