@opensaas/stack-core 0.1.6 → 0.3.0

package/src/config/types.ts

@@ -345,6 +345,42 @@ export type FieldsWithItemType<TFields extends Record<string, FieldConfig>, TIte
   [K in keyof TFields]: WithItemType<TFields[K], TItem>
 }
 
+/**
+ * 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 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'
+ *   item: Post
+ *   inputs: {
+ *     create: Prisma.PostCreateInput
+ *     update: Prisma.PostUpdateInput
+ *   }
+ * }
+ * ```
+ */
+export interface TypeInfo<
+  TKey extends string = string,
+  TItem = any, // eslint-disable-line @typescript-eslint/no-explicit-any
+  TCreateInput = any, // eslint-disable-line @typescript-eslint/no-explicit-any
+  TUpdateInput = any, // eslint-disable-line @typescript-eslint/no-explicit-any
+> {
+  key: TKey
+  item: TItem
+  inputs: {
+    create: TCreateInput
+    update: TUpdateInput
+  }
+}
+
 // Generic `any` default allows OperationAccess 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
@@ -355,36 +391,74 @@ 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> = {
+export type ListConfig<TOutput = any, TCreateInput = any, TUpdateInput = 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>
+  fields: FieldsWithItemType<Record<string, FieldConfig>, TOutput>
   access?: {
-    operation?: OperationAccess<T>
+    operation?: OperationAccess<TOutput>
   }
-  hooks?: Hooks<T>
+  hooks?: Hooks<TOutput, TCreateInput, TUpdateInput>
   /**
    * MCP server configuration for this list
    */
@@ -396,12 +470,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 +518,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
 }
 
 /**
@@ -846,12 +945,38 @@ 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>
   session?: SessionConfig
@@ -881,4 +1006,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[]
 }