@opensaas/stack-core 0.1.7 → 0.4.0

package/src/config/types.ts

@@ -18,12 +18,24 @@ export type FieldType =
  * Field-level hooks for data transformation and side effects
  * Allows field types to define custom behavior during operations
  *
- * @template TInput - Type of the input value (what goes into the database)
- * @template TOutput - Type of the output value (what comes out of the database)
- * @template TItem - Type of the parent item/record
+ * @template TTypeInfo - List type information including item and input types
+ * @template TFieldKey - The specific field name (defaults to any field in the list)
+ *
+ * @example
+ * ```typescript
+ * // For a 'title' field on Post list:
+ * FieldHooks<Lists.Post.TypeInfo, 'title'>
+ * // resolveOutput returns: string | undefined (field-specific)
+ *
+ * // Generic (for field builders):
+ * FieldHooks<TTypeInfo>
+ * // resolveOutput returns: union of all field types
+ * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type FieldHooks<TInput = any, TOutput = TInput, TItem = any> = {
+export type FieldHooks<
+  TTypeInfo extends TypeInfo,
+  TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
+> = {
   /**
    * Transform field value before database write
    * Called during create/update operations after list-level resolveInput but before validation
@@ -41,12 +53,15 @@ export type FieldHooks<TInput = any, TOutput = TInput, TItem = any> = {
    */
   resolveInput?: (args: {
     operation: 'create' | 'update'
-    inputValue: TInput | undefined
-    item?: TItem
+    inputValue: GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
+    item?: TTypeInfo['item']
     listKey: string
-    fieldName: string
+    fieldName: TFieldKey
     context: import('../access/types.js').AccessContext
-  }) => Promise<TInput | undefined> | TInput | undefined
+  }) =>
+    | Promise<GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined>
+    | GetFieldValueType<TTypeInfo['fields'], TFieldKey>
+    | undefined
 
   /**
    * Perform side effects before database write
@@ -63,10 +78,10 @@ export type FieldHooks<TInput = any, TOutput = TInput, TItem = any> = {
    */
   beforeOperation?: (args: {
     operation: 'create' | 'update' | 'delete'
-    resolvedValue: TInput | undefined
-    item?: TItem
+    resolvedValue: GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
+    item?: TTypeInfo['item']
     listKey: string
-    fieldName: string
+    fieldName: TFieldKey
     context: import('../access/types.js').AccessContext
   }) => Promise<void> | void
 
@@ -83,25 +98,14 @@ export type FieldHooks<TInput = any, TOutput = TInput, TItem = any> = {
    * }
    * ```
    */
-  afterOperation?: (
-    args:
-      | {
-          operation: 'create' | 'update' | 'delete'
-          value: TInput | undefined
-          item: TItem
-          listKey: string
-          fieldName: string
-          context: import('../access/types.js').AccessContext
-        }
-      | {
-          operation: 'query'
-          value: TOutput | undefined
-          item: TItem
-          listKey: string
-          fieldName: string
-          context: import('../access/types.js').AccessContext
-        },
-  ) => Promise<void> | void
+  afterOperation?: (args: {
+    operation: 'create' | 'update' | 'delete' | 'query'
+    value: GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
+    item: TTypeInfo['item']
+    listKey: string
+    fieldName: TFieldKey
+    context: import('../access/types.js').AccessContext
+  }) => Promise<void> | void
 
   /**
    * Transform field value after database read
@@ -120,45 +124,57 @@ export type FieldHooks<TInput = any, TOutput = TInput, TItem = any> = {
    */
   resolveOutput?: (args: {
     operation: 'query'
-    value: TInput | undefined
-    item: TItem
+    value: GetFieldValueType<TTypeInfo['fields'], TFieldKey>
+    item: TTypeInfo['item']
     listKey: string
-    fieldName: string
+    fieldName: TFieldKey
     context: import('../access/types.js').AccessContext
-  }) => TOutput | undefined
+  }) => GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined
 }
 
 /**
- * Configuration for patching Prisma-generated types
- * Allows fields to transform their types in query results
+ * Configuration for Prisma result extensions
+ * Allows fields to transform their runtime values and types in query results
+ *
+ * Runtime transformation is delegated to the field's resolveOutput hook.
+ * This config only specifies the TypeScript output type for generated types.
  */
-export type TypePatchConfig = {
+export type ResultExtensionConfig = {
   /**
-   * The TypeScript type to use in Prisma result types (e.g., Payload scalars)
-   * This is an import statement like: "import('@opensaas/stack-core').HashedPassword"
+   * The TypeScript type to use in query result types
+   * This is a type expression like: "import('@opensaas/stack-core').HashedPassword"
+   *
+   * The actual runtime transformation is performed by the field's resolveOutput hook.
+   * The Prisma extension will automatically call the hook if it exists.
+   *
+   * @example "import('@opensaas/stack-core').HashedPassword"
+   * @example "import('./types').MyCustomType"
    */
-  resultType: string
+  outputType: string
   /**
-   * Optional: Where to apply the patch
-   * - 'scalars-only': Only patch in Payload scalars (default, safest)
-   * - 'all': Patch everywhere the field appears (including inputs)
+   * @deprecated No longer used. Runtime transformations are handled by resolveOutput hooks.
+   * This field is kept for backwards compatibility but should not be used in new code.
    */
-  patchScope?: 'scalars-only' | 'all'
+  compute?: string
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type BaseFieldConfig<TInput = any, TOutput = TInput> = {
+export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
   type: string
   access?: FieldAccess
   defaultValue?: unknown
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  hooks?: FieldHooks<TInput, TOutput, any>
+  hooks?: FieldHooks<TTypeInfo>
   /**
-   * Type patching configuration for Prisma-generated types
-   * When specified, the generator will patch Prisma's types to use
-   * the specified type in query results instead of the original type
+   * Marks this field as virtual - not stored in database
+   * Virtual fields use resolveInput/resolveOutput hooks for computation
+   * They are excluded from Prisma schema and input types
+   * Only computed when explicitly selected/included in queries
    */
-  typePatch?: TypePatchConfig
+  virtual?: boolean
+  /**
+   * Prisma result extension configuration
+   * Transforms field values and types in query results using Prisma's native extension system
+   */
+  resultExtension?: ResultExtensionConfig
   ui?: {
     /**
      * Custom React component to render this field
@@ -235,7 +251,7 @@ export type BaseFieldConfig<TInput = any, TOutput = TInput> = {
   }>
 }
 
-export type TextField = BaseFieldConfig<string, string> & {
+export type TextField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'text'
   validation?: {
     isRequired?: boolean
@@ -250,7 +266,7 @@ export type TextField = BaseFieldConfig<string, string> & {
   }
 }
 
-export type IntegerField = BaseFieldConfig<number, number> & {
+export type IntegerField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'integer'
   validation?: {
     isRequired?: boolean
@@ -259,26 +275,23 @@ export type IntegerField = BaseFieldConfig<number, number> & {
   }
 }
 
-export type CheckboxField = BaseFieldConfig<boolean, boolean> & {
+export type CheckboxField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'checkbox'
 }
 
-export type TimestampField = BaseFieldConfig<Date, Date> & {
+export type TimestampField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'timestamp'
   defaultValue?: { kind: 'now' } | Date
 }
 
-export type PasswordField = BaseFieldConfig<
-  string,
-  import('../utils/password.js').HashedPassword
-> & {
+export type PasswordField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'password'
   validation?: {
     isRequired?: boolean
   }
 }
 
-export type SelectField = BaseFieldConfig<string, string> & {
+export type SelectField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'select'
   options: Array<{ label: string; value: string }>
   validation?: {
@@ -289,16 +302,17 @@ export type SelectField = BaseFieldConfig<string, string> & {
   }
 }
 
-export type RelationshipField = BaseFieldConfig<string | string[], string | string[]> & {
-  type: 'relationship'
-  ref: string // Format: 'ListName.fieldName'
-  many?: boolean
-  ui?: {
-    displayMode?: 'select' | 'cards'
+export type RelationshipField<TTypeInfo extends TypeInfo = TypeInfo> =
+  BaseFieldConfig<TTypeInfo> & {
+    type: 'relationship'
+    ref: string // Format: 'ListName.fieldName'
+    many?: boolean
+    ui?: {
+      displayMode?: 'select' | 'cards'
+    }
   }
-}
 
-export type JsonField = BaseFieldConfig<unknown, unknown> & {
+export type JsonField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'json'
   validation?: {
     isRequired?: boolean
@@ -310,39 +324,158 @@ export type JsonField = BaseFieldConfig<unknown, unknown> & {
   }
 }
 
-export type FieldConfig =
-  | TextField
-  | IntegerField
-  | CheckboxField
-  | TimestampField
-  | PasswordField
-  | SelectField
-  | RelationshipField
-  | JsonField
-  | BaseFieldConfig // Allow any field extending BaseFieldConfig (for third-party fields)
+export type VirtualField<TTypeInfo extends TypeInfo> = BaseFieldConfig<TTypeInfo> & {
+  type: 'virtual'
+  virtual: true
+  /**
+   * TypeScript type string for the virtual field output
+   * e.g., 'string', 'number', 'boolean', 'string[]', etc.
+   */
+  outputType: string
+}
+
+/**
+ * Generic field configuration type
+ * Simplified to just BaseFieldConfig to reduce type complexity
+ * Specific field types (TextField, IntegerField, etc.) are used by field builders
+ * but at the config level we treat all fields uniformly
+ */
+export type FieldConfig = BaseFieldConfig<TypeInfo>
 
 /**
  * List configuration types
  */
 
 /**
- * Utility type to inject item type into a single field config
- * Extracts TInput and TOutput from BaseFieldConfig<TInput, TOutput> and reconstructs with new hooks type
+ * Utility type to inject TypeInfo into a single field config
+ * Extracts TInput and TOutput from BaseFieldConfig and reconstructs with new TypeInfo
  */
-type WithItemType<TField extends FieldConfig, TItem> =
-  TField extends BaseFieldConfig<infer TInput, infer TOutput>
-    ? Omit<TField, 'hooks'> & {
-        hooks?: FieldHooks<TInput, TOutput, TItem>
-      }
-    : TField
+type WithTypeInfo<TTypeInfo extends TypeInfo> = BaseFieldConfig<TTypeInfo>
 
 /**
- * Utility type to transform all fields in a record to inject item type
- * Maps over each field and applies WithItemType transformation
+ * Utility type to transform all fields in a record to inject TypeInfo
+ * Maps over each field and applies WithTypeInfo transformation
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type FieldsWithItemType<TFields extends Record<string, FieldConfig>, TItem = any> = {
-  [K in keyof TFields]: WithItemType<TFields[K], TItem>
+export type FieldsWithTypeInfo<TTypeInfo extends TypeInfo> = {
+  [key: string]: WithTypeInfo<TTypeInfo>
+}
+
+/**
+ * Parse TypeScript type string to actual type
+ * Handles: 'string', 'number', 'boolean', 'Date', unions, string literals, imports
+ *
+ * @example
+ * ParseTypeString<'string'> => string
+ * ParseTypeString<'number'> => number
+ * ParseTypeString<"'draft' | 'published'"> => 'draft' | 'published'
+ * ParseTypeString<"import('@opensaas/stack-core').HashedPassword"> => any (fallback for imports)
+ */
+type ParseTypeString<T extends string> = T extends 'string'
+  ? string
+  : T extends 'number'
+    ? number
+    : T extends 'boolean'
+      ? boolean
+      : T extends 'Date'
+        ? Date
+        : T extends 'unknown'
+          ? unknown
+          : T extends `'${infer U}'`
+            ? U // String literal
+            : T extends `${infer U} | ${infer V}`
+              ? ParseTypeString<U> | ParseTypeString<V> // Union
+              : T extends `import(${string}).${string}`
+                ? any // eslint-disable-line @typescript-eslint/no-explicit-any -- Import types can't be resolved at compile time
+                : unknown // Fallback
+
+/**
+ * Extract field value type from a field config
+ * Uses the field's getTypeScriptType() method result
+ * If resultExtension is present, uses its outputType instead
+ *
+ * @example
+ * ExtractFieldValueType<TextField> => string | null | undefined (if optional)
+ * ExtractFieldValueType<IntegerField> => number
+ * ExtractFieldValueType<PasswordField> => HashedPassword (from resultExtension)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generic utility type needs to accept any BaseFieldConfig
+type ExtractFieldValueType<TField extends BaseFieldConfig<any>> = TField extends {
+  resultExtension: { outputType: infer O }
+}
+  ? ParseTypeString<O & string>
+  : TField extends { getTypeScriptType(): { type: infer T; optional: infer Opt } }
+    ? Opt extends true
+      ? ParseTypeString<T & string> | null | undefined
+      : ParseTypeString<T & string>
+    : unknown
+
+/**
+ * Extract field names as union of string literals
+ *
+ * @example
+ * FieldKeys<{ title: TextField, content: TextField }> => 'title' | 'content'
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generic utility type needs to accept any field record
+export type FieldKeys<TFields extends Record<string, any>> = keyof TFields & string
+
+/**
+ * Get field config for a specific field name
+ * Preserves the specific field type (TextField, PasswordField, etc.)
+ *
+ * @example
+ * GetFieldConfig<{ title: TextField }, 'title'> => TextField
+ */
+export type GetFieldConfig<
+  TFields extends Record<string, any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- Generic utility type needs to accept any field record
+  TFieldKey extends FieldKeys<TFields>,
+> = TFields[TFieldKey]
+
+/**
+ * Get value type for a specific field
+ *
+ * @example
+ * GetFieldValueType<{ title: TextField }, 'title'> => string
+ */
+export type GetFieldValueType<
+  TFields extends Record<string, any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- Generic utility type needs to accept any field record
+  TFieldKey extends FieldKeys<TFields>,
+> = ExtractFieldValueType<GetFieldConfig<TFields, TFieldKey>>
+
+/**
+ * TypeInfo interface for list type information
+ * Provides a structured way to pass all type information for a list
+ * Inspired by Keystone's TypeInfo pattern
+ *
+ * @template TKey - The list key/name (e.g., 'Post', 'User')
+ * @template TFields - The fields configuration for the list
+ * @template TItem - The output type (Prisma model type)
+ * @template TCreateInput - The Prisma create input type
+ * @template TUpdateInput - The Prisma update input type
+ *
+ * @example
+ * ```typescript
+ * type PostTypeInfo = {
+ *   key: 'Post'
+ *   fields: { title: TextField<...>, content: TextField<...> }
+ *   item: Post
+ *   inputs: {
+ *     create: Prisma.PostCreateInput
+ *     update: Prisma.PostUpdateInput
+ *   }
+ * }
+ * ```
+ */
+export interface TypeInfo<
+  TKey extends string = string,
+  TFields extends Record<string, any> = Record<string, any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- TypeInfo must accept any field record
+> {
+  key: TKey
+  fields: TFields
+  item: any // eslint-disable-line @typescript-eslint/no-explicit-any -- Item type is provided by Prisma and varies per list
+  inputs: {
+    create: any // eslint-disable-line @typescript-eslint/no-explicit-any -- Prisma input types are generated and vary per list
+    update: any // eslint-disable-line @typescript-eslint/no-explicit-any -- Prisma input types are generated and vary per list
+  }
 }
 
 // Generic `any` default allows OperationAccess to work with any list item type
@@ -355,36 +488,73 @@ export type OperationAccess<T = any> = {
   delete?: AccessControl<T>
 }
 
-export type HookArgs<T = Record<string, unknown>> = {
+/**
+ * Hook arguments for resolveInput hook
+ * 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
+ */
+export type ResolveInputHookArgs<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> =
+  | {
+      operation: 'create'
+      resolvedData: TCreateInput
+      item: undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      operation: 'update'
+      resolvedData: TUpdateInput
+      item: TOutput
+      context: import('../access/types.js').AccessContext
+    }
+
+/**
+ * Hook arguments for other hooks (validateInput, beforeOperation, afterOperation)
+ * These hooks receive the same structure regardless of operation
+ */
+export type HookArgs<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> = {
   operation: 'create' | 'update' | 'delete'
-  resolvedData?: Partial<T>
-  item?: T
+  resolvedData?: TCreateInput | TUpdateInput
+  item?: TOutput
   context: import('../access/types.js').AccessContext
 }
 
-export type Hooks<T = Record<string, unknown>> = {
-  resolveInput?: (args: HookArgs<T> & { operation: 'create' | 'update' }) => Promise<Partial<T>>
+export type Hooks<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> = {
+  resolveInput?: (
+    args: ResolveInputHookArgs<TOutput, TCreateInput, TUpdateInput>,
+  ) => Promise<TCreateInput | TUpdateInput>
   validateInput?: (
-    args: HookArgs<T> & {
+    args: HookArgs<TOutput, TCreateInput, TUpdateInput> & {
       operation: 'create' | 'update'
       addValidationError: (msg: string) => void
     },
   ) => Promise<void>
-  beforeOperation?: (args: HookArgs<T>) => Promise<void>
-  afterOperation?: (args: HookArgs<T>) => Promise<void>
+  beforeOperation?: (args: HookArgs<TOutput, TCreateInput, TUpdateInput>) => Promise<void>
+  afterOperation?: (args: HookArgs<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
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type ListConfig<T = any> = {
-  // Field configs are automatically transformed to inject the item type T
-  // This enables proper typing in field hooks where item: TItem
-  fields: FieldsWithItemType<Record<string, FieldConfig>, T>
+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?: {
-    operation?: OperationAccess<T>
+    operation?: OperationAccess<TTypeInfo['item']>
   }
-  hooks?: Hooks<T>
+  hooks?: Hooks<TTypeInfo['item'], TTypeInfo['inputs']['create'], TTypeInfo['inputs']['update']>
   /**
    * MCP server configuration for this list
    */
@@ -396,12 +566,37 @@ export type ListConfig<T = any> = {
  */
 export type DatabaseConfig = {
   provider: 'postgresql' | 'mysql' | 'sqlite'
-  url: string
   /**
-   * Optional factory function to create a custom Prisma client instance
-   * Receives the PrismaClient class and returns a configured instance
+   * Factory function to create a Prisma client instance with a database adapter
+   * Required in Prisma 7+ - receives the PrismaClient class and returns a configured instance
    *
-   * @example
+   * The connection URL is passed directly to the adapter, not to the config.
+   *
+   * @example SQLite with better-sqlite3
+   * ```typescript
+   * import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3'
+   * import Database from 'better-sqlite3'
+   *
+   * prismaClientConstructor: (PrismaClient) => {
+   *   const db = new Database(process.env.DATABASE_URL || './dev.db')
+   *   const adapter = new PrismaBetterSQLite3(db)
+   *   return new PrismaClient({ adapter })
+   * }
+   * ```
+   *
+   * @example PostgreSQL with pg
+   * ```typescript
+   * import { PrismaPg } from '@prisma/adapter-pg'
+   * import pg from 'pg'
+   *
+   * prismaClientConstructor: (PrismaClient) => {
+   *   const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
+   *   const adapter = new PrismaPg(pool)
+   *   return new PrismaClient({ adapter })
+   * }
+   * ```
+   *
+   * @example Neon serverless (PostgreSQL)
    * ```typescript
    * import { PrismaNeon } from '@prisma/adapter-neon'
    * import { neonConfig } from '@neondatabase/serverless'
@@ -419,7 +614,7 @@ export type DatabaseConfig = {
   // Uses `any` for maximum flexibility with Prisma client constructors and adapters
   // Different database adapters have varying type signatures that are hard to unify
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  prismaClientConstructor?: (PrismaClientClass: any) => any
+  prismaClientConstructor: (PrismaClientClass: any) => any
 }
 
 /**
@@ -763,7 +958,8 @@ export type PluginContext = {
    * Add a new list to the config
    * Throws error if list already exists (unless merge strategy used)
    */
-  addList: (name: string, listConfig: ListConfig) => void
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Plugin API must accept any list config
+  addList: (name: string, listConfig: ListConfig<any>) => void
 
   /**
    * Extend an existing list with additional fields, hooks, or access control
@@ -786,7 +982,8 @@ export type PluginContext = {
    * Register a field type globally
    * Useful for third-party field packages
    */
-  registerFieldType?: (type: string, builder: (options?: unknown) => BaseFieldConfig) => void
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Plugin API must accept any field config builder
+  registerFieldType?: (type: string, builder: (options?: unknown) => BaseFieldConfig<any>) => void
 
   /**
    * Register a custom MCP tool
@@ -846,14 +1043,41 @@ export type Plugin = {
    * Return value is stored in context.plugins[pluginName]
    */
   runtime?: (context: import('../access/types.js').AccessContext) => unknown
+
+  /**
+   * Optional: Type metadata for runtime services
+   * Enables type-safe code generation for context.plugins
+   *
+   * @example
+   * ```typescript
+   * {
+   *   import: "import type { AuthRuntimeServices } from '@opensaas/stack-auth/runtime'",
+   *   typeName: "AuthRuntimeServices"
+   * }
+   * ```
+   */
+  runtimeServiceTypes?: {
+    /**
+     * Import statement to include in generated types file
+     * Must be a complete import statement with 'import type' and quotes
+     */
+    import: string
+    /**
+     * TypeScript type name to use in PluginServices interface
+     * Should match the exported type from the import
+     */
+    typeName: string
+  }
 }
 
 /**
  * Main configuration type
+ * Using interface instead of type to allow module augmentation
  */
-export type OpenSaasConfig = {
+export interface OpenSaasConfig {
   db: DatabaseConfig
-  lists: Record<string, ListConfig>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Config must accept any list configuration
+  lists: Record<string, ListConfig<any>>
   session?: SessionConfig
   ui?: UIConfig
   /**
@@ -881,4 +1105,10 @@ export type OpenSaasConfig = {
    * @internal
    */
   _pluginData?: Record<string, unknown>
+  /**
+   * Sorted plugin instances (stored after plugin execution)
+   * Used at runtime to call plugin.runtime() functions
+   * @internal
+   */
+  _plugins?: Plugin[]
 }