@opensaas/stack-core 0.3.0 → 0.5.0

package/src/context/nested-operations.ts

@@ -61,7 +61,8 @@ function isRelationshipField(fieldConfig: FieldConfig | undefined): boolean {
  */
 async function processNestedCreate(
   items: Record<string, unknown> | Array<Record<string, unknown>>,
-  relatedListConfig: ListConfig,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  relatedListConfig: ListConfig<any>,
   context: AccessContext,
   config: OpenSaasConfig,
 ): Promise<Record<string, unknown> | Array<Record<string, unknown>>> {
@@ -69,15 +70,17 @@ async function processNestedCreate(
 
   const processedItems = await Promise.all(
     itemsArray.map(async (item) => {
-      // 1. Check create access
-      const createAccess = relatedListConfig.access?.operation?.create
-      const accessResult = await checkAccess(createAccess, {
-        session: context.session,
-        context,
-      })
+      // 1. Check create access (skip if sudo mode)
+      if (!context._isSudo) {
+        const createAccess = relatedListConfig.access?.operation?.create
+        const accessResult = await checkAccess(createAccess, {
+          session: context.session,
+          context,
+        })
 
-      if (accessResult === false) {
-        throw new Error('Access denied: Cannot create related item')
+        if (accessResult === false) {
+          throw new Error('Access denied: Cannot create related item')
+        }
       }
 
       // 2. Execute list-level resolveInput hook
@@ -151,49 +154,52 @@ async function processNestedCreate(
 async function processNestedConnect(
   connections: Record<string, unknown> | Array<Record<string, unknown>>,
   relatedListName: string,
-  relatedListConfig: ListConfig,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  relatedListConfig: ListConfig<any>,
   context: AccessContext,
   prisma: unknown,
 ): Promise<Record<string, unknown> | Array<Record<string, unknown>>> {
   const connectionsArray = Array.isArray(connections) ? connections : [connections]
 
-  // Check update access for each item being connected
-  for (const connection of connectionsArray) {
-    // Access Prisma model dynamically - required because model names are generated at runtime
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const model = (prisma as any)[getDbKey(relatedListName)]
+  // Check update access for each item being connected (skip if sudo mode)
+  if (!context._isSudo) {
+    for (const connection of connectionsArray) {
+      // Access Prisma model dynamically - required because model names are generated at runtime
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const model = (prisma as any)[getDbKey(relatedListName)]
 
-    // Fetch the item to check access
-    const item = await model.findUnique({
-      where: connection,
-    })
+      // Fetch the item to check access
+      const item = await model.findUnique({
+        where: connection,
+      })
 
-    if (!item) {
-      throw new Error(`Cannot connect: Item not found`)
-    }
+      if (!item) {
+        throw new Error(`Cannot connect: Item not found`)
+      }
 
-    // Check update access (connecting modifies the relationship)
-    const updateAccess = relatedListConfig.access?.operation?.update
-    const accessResult = await checkAccess(updateAccess, {
-      session: context.session,
-      item,
-      context,
-    })
+      // Check update access (connecting modifies the relationship)
+      const updateAccess = relatedListConfig.access?.operation?.update
+      const accessResult = await checkAccess(updateAccess, {
+        session: context.session,
+        item,
+        context,
+      })
 
-    if (accessResult === false) {
-      throw new Error('Access denied: Cannot connect to this item')
-    }
+      if (accessResult === false) {
+        throw new Error('Access denied: Cannot connect to this item')
+      }
 
-    // If access returns a filter, check if item matches
-    if (typeof accessResult === 'object') {
-      // Simple field matching
-      for (const [key, value] of Object.entries(accessResult)) {
-        if (typeof value === 'object' && value !== null && 'equals' in value) {
-          if (item[key] !== (value as Record<string, unknown>).equals) {
+      // If access returns a filter, check if item matches
+      if (typeof accessResult === 'object') {
+        // Simple field matching
+        for (const [key, value] of Object.entries(accessResult)) {
+          if (typeof value === 'object' && value !== null && 'equals' in value) {
+            if (item[key] !== (value as Record<string, unknown>).equals) {
+              throw new Error('Access denied: Cannot connect to this item')
+            }
+          } else if (item[key] !== value) {
             throw new Error('Access denied: Cannot connect to this item')
           }
-        } else if (item[key] !== value) {
-          throw new Error('Access denied: Cannot connect to this item')
         }
       }
     }
@@ -209,7 +215,8 @@ async function processNestedConnect(
 async function processNestedUpdate(
   updates: Record<string, unknown> | Array<Record<string, unknown>>,
   relatedListName: string,
-  relatedListConfig: ListConfig,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  relatedListConfig: ListConfig<any>,
   context: AccessContext,
   config: OpenSaasConfig,
   prisma: unknown,
@@ -231,16 +238,18 @@ async function processNestedUpdate(
         throw new Error('Cannot update: Item not found')
       }
 
-      // Check update access
-      const updateAccess = relatedListConfig.access?.operation?.update
-      const accessResult = await checkAccess(updateAccess, {
-        session: context.session,
-        item,
-        context,
-      })
+      // Check update access (skip if sudo mode)
+      if (!context._isSudo) {
+        const updateAccess = relatedListConfig.access?.operation?.update
+        const accessResult = await checkAccess(updateAccess, {
+          session: context.session,
+          item,
+          context,
+        })
 
-      if (accessResult === false) {
-        throw new Error('Access denied: Cannot update related item')
+        if (accessResult === false) {
+          throw new Error('Access denied: Cannot update related item')
+        }
       }
 
       // Execute list-level resolveInput hook
@@ -313,7 +322,8 @@ async function processNestedUpdate(
 async function processNestedConnectOrCreate(
   operations: Record<string, unknown> | Array<Record<string, unknown>>,
   relatedListName: string,
-  relatedListConfig: ListConfig,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  relatedListConfig: ListConfig<any>,
   context: AccessContext,
   config: OpenSaasConfig,
   prisma: unknown,
@@ -331,30 +341,32 @@ async function processNestedConnectOrCreate(
         config,
       )
 
-      // Check access for the connect portion (try to find existing item)
-      try {
-        // Access Prisma model dynamically - required because model names are generated at runtime
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const model = (prisma as any)[getDbKey(relatedListName)]
-        const existingItem = await model.findUnique({
-          where: opRecord.where,
-        })
-
-        if (existingItem) {
-          // Check update access for connection
-          const updateAccess = relatedListConfig.access?.operation?.update
-          const accessResult = await checkAccess(updateAccess, {
-            session: context.session,
-            item: existingItem,
-            context,
+      // Check access for the connect portion (try to find existing item) (skip if sudo mode)
+      if (!context._isSudo) {
+        try {
+          // Access Prisma model dynamically - required because model names are generated at runtime
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const model = (prisma as any)[getDbKey(relatedListName)]
+          const existingItem = await model.findUnique({
+            where: opRecord.where,
           })
 
-          if (accessResult === false) {
-            throw new Error('Access denied: Cannot connect to existing item')
+          if (existingItem) {
+            // Check update access for connection
+            const updateAccess = relatedListConfig.access?.operation?.update
+            const accessResult = await checkAccess(updateAccess, {
+              session: context.session,
+              item: existingItem,
+              context,
+            })
+
+            if (accessResult === false) {
+              throw new Error('Access denied: Cannot connect to existing item')
+            }
           }
+        } catch {
+          // Item doesn't exist, will use create (already processed)
         }
-      } catch {
-        // Item doesn't exist, will use create (already processed)
       }
 
       return {

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,
@@ -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,
@@ -147,7 +152,9 @@ 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,
@@ -179,7 +186,9 @@ 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,
@@ -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
@@ -372,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')
   }
@@ -420,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')
   }
@@ -482,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,
@@ -522,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/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/field-types.test.ts

@@ -407,13 +407,14 @@ describe('Field Types', () => {
       })
     })
 
-    describe('typePatch', () => {
-      test('has type patch configured', () => {
+    describe('resultExtension', () => {
+      test('has result extension configured', () => {
         const field = password()
 
-        expect(field.typePatch).toBeDefined()
-        expect(field.typePatch?.resultType).toBe("import('@opensaas/stack-core').HashedPassword")
-        expect(field.typePatch?.patchScope).toBe('scalars-only')
+        expect(field.resultExtension).toBeDefined()
+        expect(field.resultExtension?.outputType).toBe(
+          "import('@opensaas/stack-core').HashedPassword",
+        )
       })
     })
   })