@opensaas/stack-core 0.12.1 → 0.14.0

package/src/config/types.ts

@@ -14,6 +14,158 @@ export type FieldType =
   | 'relationship'
   | string // Allow custom field types from third-party packages
 
+/**
+ * Field-level hook argument types (exported for user annotations)
+ */
+
+/**
+ * Arguments for field-level resolveInput hook
+ * Used to transform field values before database write
+ */
+export type FieldResolveInputHookArgs<
+  TTypeInfo extends TypeInfo,
+  TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
+> =
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'create'
+      inputData: TTypeInfo['inputs']['create']
+      item: undefined
+      resolvedData: TTypeInfo['inputs']['create']
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'update'
+      inputData: TTypeInfo['inputs']['update']
+      item: TTypeInfo['item']
+      resolvedData: TTypeInfo['inputs']['update']
+      context: import('../access/types.js').AccessContext
+    }
+
+/**
+ * Arguments for field-level validate hook
+ * Used for custom validation logic
+ */
+export type FieldValidateHookArgs<
+  TTypeInfo extends TypeInfo,
+  TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
+> =
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'create'
+      inputData: TTypeInfo['inputs']['create']
+      item: undefined
+      resolvedData: TTypeInfo['inputs']['create']
+      context: import('../access/types.js').AccessContext
+      addValidationError: (msg: string) => void
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'update'
+      inputData: TTypeInfo['inputs']['update']
+      item: TTypeInfo['item']
+      resolvedData: TTypeInfo['inputs']['update']
+      context: import('../access/types.js').AccessContext
+      addValidationError: (msg: string) => void
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'delete'
+      item: TTypeInfo['item']
+      context: import('../access/types.js').AccessContext
+      addValidationError: (msg: string) => void
+    }
+
+/**
+ * Arguments for field-level beforeOperation hook
+ * Used for side effects before database write
+ */
+export type FieldBeforeOperationHookArgs<
+  TTypeInfo extends TypeInfo,
+  TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
+> =
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'create'
+      inputData: TTypeInfo['inputs']['create']
+      resolvedData: TTypeInfo['inputs']['create']
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'update'
+      inputData: TTypeInfo['inputs']['update']
+      item: TTypeInfo['item']
+      resolvedData: TTypeInfo['inputs']['update']
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'delete'
+      item: TTypeInfo['item']
+      context: import('../access/types.js').AccessContext
+    }
+
+/**
+ * Arguments for field-level afterOperation hook
+ * Used for side effects after database operation
+ */
+export type FieldAfterOperationHookArgs<
+  TTypeInfo extends TypeInfo,
+  TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
+> =
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'create'
+      inputData: TTypeInfo['inputs']['create']
+      item: TTypeInfo['item']
+      resolvedData: TTypeInfo['inputs']['create']
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'update'
+      inputData: TTypeInfo['inputs']['update']
+      originalItem: TTypeInfo['item']
+      item: TTypeInfo['item']
+      resolvedData: TTypeInfo['inputs']['update']
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      fieldKey: TFieldKey
+      operation: 'delete'
+      originalItem: TTypeInfo['item']
+      context: import('../access/types.js').AccessContext
+    }
+
+/**
+ * Arguments for field-level resolveOutput hook
+ * Used to transform field values after database read
+ */
+export type FieldResolveOutputHookArgs<
+  TTypeInfo extends TypeInfo,
+  TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
+> = {
+  operation: 'query'
+  value: GetFieldValueType<TTypeInfo['fields'], TFieldKey>
+  item: TTypeInfo['item']
+  listKey: string
+  fieldName: TFieldKey
+  context: import('../access/types.js').AccessContext
+}
+
 /**
  * Field-level hooks for data transformation and side effects
  * Allows field types to define custom behavior during operations
@@ -43,39 +195,47 @@ export type FieldHooks<
    *
    * @example
    * ```typescript
-   * resolveInput: async ({ inputValue, operation, item }) => {
+   * resolveInput: async ({ listKey, fieldKey, operation, inputData, item, resolvedData, context }) => {
    *   // For create operations, item is undefined
    *   // For update operations, item is the existing record
-   *   if (typeof inputValue === 'string' && !isHashedPassword(inputValue)) {
-   *     return await hashPassword(inputValue)
+   *   const fieldValue = resolvedData[fieldKey]
+   *   if (typeof fieldValue === 'string' && !isHashedPassword(fieldValue)) {
+   *     return await hashPassword(fieldValue)
    *   }
-   *   return inputValue
+   *   return fieldValue
    * }
    * ```
    */
   resolveInput?: (
-    args:
-      | {
-          operation: 'create'
-          inputValue: GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
-          item: undefined
-          listKey: string
-          fieldName: TFieldKey
-          context: import('../access/types.js').AccessContext
-        }
-      | {
-          operation: 'update'
-          inputValue: GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
-          item: TTypeInfo['item']
-          listKey: string
-          fieldName: TFieldKey
-          context: import('../access/types.js').AccessContext
-        },
+    args: FieldResolveInputHookArgs<TTypeInfo, TFieldKey>,
   ) =>
     | Promise<GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined>
     | GetFieldValueType<TTypeInfo['fields'], TFieldKey>
     | undefined
 
+  /**
+   * Validate field value after resolveInput
+   * Called during create/update operations after resolveInput hooks but before database write
+   * Use addValidationError to report validation failures
+   *
+   * @example
+   * ```typescript
+   * validate: async ({ listKey, fieldKey, operation, inputData, item, resolvedData, context, addValidationError }) => {
+   *   if (operation === 'delete') return
+   *   const fieldValue = resolvedData[fieldKey]
+   *   if (typeof fieldValue === 'string' && fieldValue.includes('spam')) {
+   *     addValidationError('Field cannot contain spam')
+   *   }
+   * }
+   * ```
+   */
+  validate?: (args: FieldValidateHookArgs<TTypeInfo, TFieldKey>) => Promise<void> | void
+
+  /**
+   * @deprecated Use 'validate' instead. This alias is provided for backwards compatibility.
+   */
+  validateInput?: (args: FieldValidateHookArgs<TTypeInfo, TFieldKey>) => Promise<void> | void
+
   /**
    * Perform side effects before database write
    * Called during create/update/delete operations after validation and access control
@@ -83,75 +243,40 @@ export type FieldHooks<
    *
    * @example
    * ```typescript
-   * beforeOperation: async ({ resolvedValue, operation, item }) => {
+   * beforeOperation: async ({ listKey, fieldKey, operation, inputData, item, resolvedData, context }) => {
    *   // For create operations, item is undefined
    *   // For update/delete operations, item is the existing record
+   *   const fieldValue = resolvedData?.[fieldKey]
    *   if (operation === 'update' && item) {
-   *     console.log(`Updating field from ${item.fieldName} to ${resolvedValue}`)
+   *     console.log(`Updating field from ${item[fieldKey]} to ${fieldValue}`)
    *   }
    *   await sendAuditLog({ operation, item })
    * }
    * ```
    */
   beforeOperation?: (
-    args:
-      | {
-          operation: 'create'
-          resolvedValue: GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
-          item: undefined
-          listKey: string
-          fieldName: TFieldKey
-          context: import('../access/types.js').AccessContext
-        }
-      | {
-          operation: 'update' | 'delete'
-          resolvedValue: GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
-          item: TTypeInfo['item']
-          listKey: string
-          fieldName: TFieldKey
-          context: import('../access/types.js').AccessContext
-        },
+    args: FieldBeforeOperationHookArgs<TTypeInfo, TFieldKey>,
   ) => Promise<void> | void
 
   /**
    * Perform side effects after database operation
-   * Called after any database operation (create/update/delete/query)
+   * Called after any database operation (create/update/delete)
    * This should ONLY contain side effects (logging, cache invalidation, etc.), not data transformation
    *
    * @example
    * ```typescript
-   * afterOperation: async ({ operation, value, item, originalItem }) => {
-   *   // For query/create operations, originalItem is undefined
+   * afterOperation: async ({ listKey, fieldKey, operation, inputData, item, originalItem, resolvedData, context }) => {
+   *   // For create operations, originalItem is undefined
    *   // For update/delete operations, originalItem is the item before the operation
    *   if (operation === 'update' && originalItem) {
-   *     console.log('Changed from:', originalItem[fieldName], 'to:', value)
+   *     console.log('Changed from:', originalItem[fieldKey], 'to:', item[fieldKey])
    *   }
    *   await invalidateCache({ listKey, itemId: item.id })
    *   await sendWebhook({ operation, item })
    * }
    * ```
    */
-  afterOperation?: (
-    args:
-      | {
-          operation: 'query' | 'create'
-          value: GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
-          item: TTypeInfo['item']
-          originalItem: undefined
-          listKey: string
-          fieldName: TFieldKey
-          context: import('../access/types.js').AccessContext
-        }
-      | {
-          operation: 'update' | 'delete'
-          value: GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
-          item: TTypeInfo['item']
-          originalItem: TTypeInfo['item']
-          listKey: string
-          fieldName: TFieldKey
-          context: import('../access/types.js').AccessContext
-        },
-  ) => Promise<void> | void
+  afterOperation?: (args: FieldAfterOperationHookArgs<TTypeInfo, TFieldKey>) => Promise<void> | void
 
   /**
    * Transform field value after database read
@@ -168,14 +293,9 @@ export type FieldHooks<
    * }
    * ```
    */
-  resolveOutput?: (args: {
-    operation: 'query'
-    value: GetFieldValueType<TTypeInfo['fields'], TFieldKey>
-    item: TTypeInfo['item']
-    listKey: string
-    fieldName: TFieldKey
-    context: import('../access/types.js').AccessContext
-  }) => GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
+  resolveOutput?: (
+    args: FieldResolveOutputHookArgs<TTypeInfo, TFieldKey>,
+  ) => GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
 }
 
 /**
@@ -206,7 +326,11 @@ export type ResultExtensionConfig = {
 
 export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
   type: string
-  access?: FieldAccess
+  access?: FieldAccess<
+    TTypeInfo['item'],
+    TTypeInfo['inputs']['create'],
+    TTypeInfo['inputs']['update']
+  >
   defaultValue?: unknown
   hooks?: FieldHooks<TTypeInfo>
   /**
@@ -471,6 +595,37 @@ export type RelationshipField<TTypeInfo extends TypeInfo = TypeInfo> =
        * ```
        */
       foreignKey?: boolean | { map?: string }
+      /**
+       * Extend or modify the generated Prisma schema lines for this relationship field
+       * Receives the generated FK line (if applicable) and relation line
+       * Returns the modified lines
+       *
+       * @example Add onDelete cascade for self-referential relationship
+       * ```typescript
+       * parent: relationship({
+       *   ref: 'Category.children',
+       *   db: {
+       *     foreignKey: true,
+       *     extendPrismaSchema: ({ fkLine, relationLine }) => ({
+       *       fkLine,
+       *       relationLine: relationLine.replace(
+       *         '@relation(',
+       *         '@relation(onDelete: SetNull, '
+       *       )
+       *     })
+       *   }
+       * })
+       * ```
+       */
+      extendPrismaSchema?: (lines: {
+        /** The foreign key field line (e.g., "parentId String?"), only present for single relationships that own the FK */
+        fkLine?: string
+        /** The relation field line (e.g., "parent Category? @relation(...)") */
+        relationLine: string
+      }) => {
+        fkLine?: string
+        relationLine: string
+      }
     }
     ui?: {
       displayMode?: 'select' | 'cards'
@@ -684,6 +839,48 @@ export type OperationAccess<T = any> = {
   delete?: AccessControl<T>
 }
 
+/**
+ * List-level access control configuration
+ * Supports two patterns:
+ *
+ * 1. Function shorthand - applies to all CRUD operations:
+ *    `access: isAdmin`
+ *
+ * 2. Object form - configure operations individually:
+ *    `access: { operation: { query: () => true, create: isAdmin } }`
+ *
+ * @example Function shorthand
+ * ```typescript
+ * const isAdmin = ({ session }) => session?.role === 'admin'
+ *
+ * list({
+ *   access: isAdmin,  // Applies to query, create, update, delete
+ *   fields: { ... }
+ * })
+ * ```
+ *
+ * @example Object form
+ * ```typescript
+ * list({
+ *   access: {
+ *     operation: {
+ *       query: () => true,
+ *       create: isAdmin,
+ *       update: isOwner,
+ *       delete: isAdmin,
+ *     }
+ *   },
+ *   fields: { ... }
+ * })
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ListAccessControl<T = any> =
+  | AccessControl<T>
+  | {
+      operation?: OperationAccess<T>
+    }
+
 /**
  * Hook arguments for resolveInput hook
  * Uses discriminated union to provide proper types based on operation
@@ -696,58 +893,90 @@ export type ResolveInputHookArgs<
   TUpdateInput = Record<string, unknown>,
 > =
   | {
+      listKey: string
       operation: 'create'
+      inputData: TCreateInput
       resolvedData: TCreateInput
       item: undefined
       context: import('../access/types.js').AccessContext
     }
   | {
+      listKey: string
       operation: 'update'
+      inputData: TUpdateInput
       resolvedData: TUpdateInput
       item: TOutput
       context: import('../access/types.js').AccessContext
     }
 
 /**
- * Hook arguments for validateInput hook
+ * Hook arguments for validate hook (renamed from validateInput for Keystone compatibility)
  * Uses discriminated union to provide proper types based on operation
  * - create: resolvedData is CreateInput, item is undefined
  * - update: resolvedData is UpdateInput, item is the existing record
+ * - delete: item is the item being deleted
  */
-export type ValidateInputHookArgs<
+export type ValidateHookArgs<
   TOutput = Record<string, unknown>,
   TCreateInput = Record<string, unknown>,
   TUpdateInput = Record<string, unknown>,
 > =
   | {
+      listKey: string
       operation: 'create'
+      inputData: TCreateInput
       resolvedData: TCreateInput
       item: undefined
       context: import('../access/types.js').AccessContext
       addValidationError: (msg: string) => void
     }
   | {
+      listKey: string
       operation: 'update'
+      inputData: TUpdateInput
       resolvedData: TUpdateInput
       item: TOutput
       context: import('../access/types.js').AccessContext
       addValidationError: (msg: string) => void
     }
+  | {
+      listKey: string
+      operation: 'delete'
+      item: TOutput
+      context: import('../access/types.js').AccessContext
+      addValidationError: (msg: string) => void
+    }
 
 /**
  * Hook arguments for beforeOperation hook
  * Uses discriminated union to provide proper types based on operation
- * - create: no resolvedData, no item
- * - update: no resolvedData, has item
- * - delete: no resolvedData, has item
+ * - create: has inputData and resolvedData, no item
+ * - update: has inputData, resolvedData, and item
+ * - delete: has item only
  */
-export type BeforeOperationHookArgs<TOutput = Record<string, unknown>> =
+export type BeforeOperationHookArgs<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> =
   | {
+      listKey: string
       operation: 'create'
+      inputData: TCreateInput
+      resolvedData: TCreateInput
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      operation: 'update'
+      inputData: TUpdateInput
+      item: TOutput
+      resolvedData: TUpdateInput
       context: import('../access/types.js').AccessContext
     }
   | {
-      operation: 'update' | 'delete'
+      listKey: string
+      operation: 'delete'
       item: TOutput
       context: import('../access/types.js').AccessContext
     }
@@ -755,20 +984,35 @@ export type BeforeOperationHookArgs<TOutput = Record<string, unknown>> =
 /**
  * Hook arguments for afterOperation hook
  * Uses discriminated union to provide proper types based on operation
- * - create: has item, no originalItem
- * - update: has item, has originalItem
- * - delete: has item, has originalItem
+ * - create: has item, inputData, and resolvedData, no originalItem
+ * - update: has item, originalItem, inputData, and resolvedData
+ * - delete: has originalItem only
  */
-export type AfterOperationHookArgs<TOutput = Record<string, unknown>> =
+export type AfterOperationHookArgs<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> =
   | {
+      listKey: string
       operation: 'create'
+      inputData: TCreateInput
       item: TOutput
-      originalItem: undefined
+      resolvedData: TCreateInput
       context: import('../access/types.js').AccessContext
     }
   | {
-      operation: 'update' | 'delete'
+      listKey: string
+      operation: 'update'
+      inputData: TUpdateInput
+      originalItem: TOutput
       item: TOutput
+      resolvedData: TUpdateInput
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      listKey: string
+      operation: 'delete'
       originalItem: TOutput
       context: import('../access/types.js').AccessContext
     }
@@ -781,19 +1025,34 @@ export type Hooks<
   resolveInput?: (
     args: ResolveInputHookArgs<TOutput, TCreateInput, TUpdateInput>,
   ) => Promise<TCreateInput | TUpdateInput>
-  validateInput?: (
-    args: ValidateInputHookArgs<TOutput, TCreateInput, TUpdateInput>,
+  validate?: (args: ValidateHookArgs<TOutput, TCreateInput, TUpdateInput>) => Promise<void>
+  beforeOperation?: (
+    args: BeforeOperationHookArgs<TOutput, TCreateInput, TUpdateInput>,
+  ) => Promise<void>
+  afterOperation?: (
+    args: AfterOperationHookArgs<TOutput, TCreateInput, TUpdateInput>,
   ) => Promise<void>
-  beforeOperation?: (args: BeforeOperationHookArgs<TOutput>) => Promise<void>
-  afterOperation?: (args: AfterOperationHookArgs<TOutput>) => Promise<void>
+  /**
+   * @deprecated Use 'validate' instead. This alias is provided for backwards compatibility.
+   */
+  validateInput?: (args: ValidateHookArgs<TOutput, TCreateInput, TUpdateInput>) => Promise<void>
 }
 
 // Generic `any` default allows ListConfig to work with any list item type
 // This is needed because the item type varies per list and is inferred from Prisma models
+/**
+ * Internal list configuration type (after normalization by list() function)
+ * Access control is always in object form internally.
+ * Use list() function which accepts both function shorthand and object form.
+ */
 export type ListConfig<TTypeInfo extends TypeInfo> = {
   // Field configs are automatically transformed to inject the full TypeInfo
   // This enables proper typing in field hooks where item, create input, and update input are all typed
   fields: FieldsWithTypeInfo<TTypeInfo>
+  /**
+   * Access control configuration for this list (normalized object form).
+   * The list() function normalizes function shorthand to this object form.
+   */
   access?: {
     operation?: OperationAccess<TTypeInfo['item']>
   }
@@ -802,6 +1061,58 @@ export type ListConfig<TTypeInfo extends TypeInfo> = {
    * MCP server configuration for this list
    */
   mcp?: ListMcpConfig
+  /**
+   * Restricts this list to a single record (singleton pattern)
+   * When true:
+   * - Prevents creating multiple records
+   * - Auto-creates the single record on first access (if autoCreate: true, which is the default)
+   * - Provides a get() method for easy access to the singleton
+   * - Blocks delete and findMany operations
+   * - Changes UI to show edit form instead of list view
+   *
+   * @example Simple boolean (auto-create enabled)
+   * ```typescript
+   * isSingleton: true
+   * ```
+   *
+   * @example With options
+   * ```typescript
+   * isSingleton: {
+   *   autoCreate: false  // Don't auto-create, must be created manually
+   * }
+   * ```
+   */
+  isSingleton?:
+    | boolean
+    | {
+        /**
+         * Auto-create the singleton record on first access using field defaults
+         * @default true
+         */
+        autoCreate?: boolean
+      }
+}
+
+/**
+ * Input type for the list() function
+ * Accepts both function shorthand and object form for access control.
+ */
+export type ListConfigInput<TTypeInfo extends TypeInfo> = Omit<ListConfig<TTypeInfo>, 'access'> & {
+  /**
+   * Access control configuration for this list.
+   * Supports both function shorthand and object form.
+   *
+   * @example Function shorthand (applies to all operations)
+   * ```typescript
+   * access: isAdmin
+   * ```
+   *
+   * @example Object form (per-operation)
+   * ```typescript
+   * access: { operation: { query: () => true, create: isAdmin } }
+   * ```
+   */
+  access?: ListAccessControl<TTypeInfo['item']>
 }
 
 /**