@opensaas/stack-core 0.1.0

package/src/access/types.ts

@@ -0,0 +1,103 @@
+/**
+ * Session type - can be extended by users
+ */
+export type Session = {
+  userId?: string
+  [key: string]: unknown
+} | null
+
+/**
+ * Generic Prisma model delegate type
+ */
+export type PrismaModelDelegate = {
+  findUnique: (args: unknown) => Promise<unknown>
+  findFirst: (args: unknown) => Promise<unknown>
+  findMany: (args: unknown) => Promise<unknown[]>
+  create: (args: unknown) => Promise<unknown>
+  update: (args: unknown) => Promise<unknown>
+  delete: (args: unknown) => Promise<unknown>
+  count: (args?: unknown) => Promise<number>
+}
+
+/**
+ * Generic Prisma client type
+ * This is intentionally permissive to allow actual PrismaClient types
+ * Uses `any` because Prisma generates highly complex client types that are difficult to constrain
+ * This type is used as a generic constraint and the actual type safety comes from TPrisma parameter
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PrismaClientLike = any
+
+/**
+ * Map Prisma client to access-controlled database context
+ * Preserves Prisma's type information for each model
+ */
+export type AccessControlledDB<TPrisma extends PrismaClientLike> = {
+  [K in keyof TPrisma]: TPrisma[K] extends {
+    // Uses `any` in conditional type checks to verify Prisma model shape
+    // This is a standard TypeScript pattern for checking if a property exists with any signature
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findUnique: any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findMany: any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    create: any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    update: any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    delete: any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    count: any
+  }
+    ? {
+        findUnique: TPrisma[K]['findUnique']
+        findMany: TPrisma[K]['findMany']
+        create: TPrisma[K]['create']
+        update: TPrisma[K]['update']
+        delete: TPrisma[K]['delete']
+        count: TPrisma[K]['count']
+      }
+    : never
+} & {
+  // Add index signature for runtime string access (e.g., db[getDbKey(listName)])
+  // Uses `any` because models can have any shape from Prisma schema
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any
+}
+
+/**
+ * Context type (simplified for access control)
+ */
+export type AccessContext<TPrisma extends PrismaClientLike = PrismaClientLike> = {
+  session: Session
+  prisma: TPrisma
+  db: AccessControlledDB<TPrisma>
+  [key: string]: unknown
+}
+
+/**
+ * Prisma filter type - represents a where clause
+ * Uses Partial to allow filtering by any subset of fields
+ */
+export type PrismaFilter<T = Record<string, unknown>> = Partial<Record<keyof T, unknown>>
+
+/**
+ * Access control function type
+ * Can return:
+ * - boolean: true = allow, false = deny
+ * - PrismaFilter: Prisma where clause to filter results
+ */
+export type AccessControl<T = Record<string, unknown>> = (args: {
+  session: Session
+  item?: T // Present for update/delete operations
+  context: AccessContext
+}) => boolean | PrismaFilter<T> | Promise<boolean | PrismaFilter<T>>
+
+/**
+ * Field-level access control
+ */
+export type FieldAccess = {
+  read?: AccessControl
+  create?: AccessControl
+  update?: AccessControl
+}

package/src/config/index.ts

@@ -0,0 +1,71 @@
+import type { OpenSaasConfig, ListConfig, FieldConfig, OperationAccess, Hooks } from './types.js'
+
+/**
+ * Helper function to define configuration with type safety
+ */
+export function config(config: OpenSaasConfig): OpenSaasConfig {
+  return config
+}
+
+/**
+ * Helper function to define a list with type safety
+ *
+ * Accepts raw field configs and transforms them to inject the item type T
+ * This enables proper typing in field hooks where item: T
+ *
+ * @example
+ * ```typescript
+ * import type { User } from './.opensaas/types'
+ *
+ * User: list<User>({
+ *   fields: {
+ *     password: password({
+ *       hooks: {
+ *         resolveInput: async ({ inputValue, item }) => {
+ *           // item is typed as User | undefined
+ *           // inputValue is typed as string | undefined
+ *           return hashPassword(inputValue)
+ *         }
+ *       }
+ *     })
+ *   }
+ * })
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function list<T = any>(config: {
+  fields: Record<string, FieldConfig>
+  access?: {
+    operation?: OperationAccess<T>
+  }
+  hooks?: Hooks<T>
+}): ListConfig<T> {
+  // At runtime, field configs are unchanged
+  // At type level, they're transformed to inject T as the item type
+  return config as ListConfig<T>
+}
+
+// Re-export all types
+export type {
+  OpenSaasConfig,
+  ListConfig,
+  FieldConfig,
+  BaseFieldConfig,
+  TextField,
+  IntegerField,
+  CheckboxField,
+  TimestampField,
+  PasswordField,
+  SelectField,
+  RelationshipField,
+  OperationAccess,
+  Hooks,
+  FieldHooks,
+  FieldsWithItemType,
+  DatabaseConfig,
+  SessionConfig,
+  UIConfig,
+  ThemeConfig,
+  ThemePreset,
+  ThemeColors,
+} from './types.js'

package/src/config/types.ts

@@ -0,0 +1,478 @@
+import type { AccessControl, FieldAccess } from '../access/types.js'
+import type { z } from 'zod'
+
+/**
+ * Field configuration types
+ */
+export type FieldType =
+  | 'text'
+  | 'integer'
+  | 'checkbox'
+  | 'timestamp'
+  | 'password'
+  | 'select'
+  | 'relationship'
+  | string // Allow custom field types from third-party packages
+
+/**
+ * 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
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type FieldHooks<TInput = any, TOutput = TInput, TItem = any> = {
+  /**
+   * Transform field value before database write
+   * Called during create/update operations after list-level resolveInput but before validation
+   * This is where you should transform input data (e.g., hash passwords, normalize values)
+   *
+   * @example
+   * ```typescript
+   * resolveInput: async ({ inputValue, operation }) => {
+   *   if (typeof inputValue === 'string' && !isHashedPassword(inputValue)) {
+   *     return await hashPassword(inputValue)
+   *   }
+   *   return inputValue
+   * }
+   * ```
+   */
+  resolveInput?: (args: {
+    operation: 'create' | 'update'
+    inputValue: TInput | undefined
+    item?: TItem
+    listKey: string
+    fieldName: string
+    context: import('../access/types.js').AccessContext
+  }) => Promise<TInput | undefined> | TInput | undefined
+
+  /**
+   * Perform side effects before database write
+   * Called during create/update/delete operations after validation and access control
+   * This should ONLY contain side effects (logging, notifications, etc.), not data transformation
+   *
+   * @example
+   * ```typescript
+   * beforeOperation: async ({ resolvedValue, operation, item }) => {
+   *   console.log(`About to ${operation} field with value:`, resolvedValue)
+   *   await sendAuditLog({ operation, item })
+   * }
+   * ```
+   */
+  beforeOperation?: (args: {
+    operation: 'create' | 'update' | 'delete'
+    resolvedValue: TInput | undefined
+    item?: TItem
+    listKey: string
+    fieldName: string
+    context: import('../access/types.js').AccessContext
+  }) => Promise<void> | void
+
+  /**
+   * Perform side effects after database operation
+   * Called after any database operation (create/update/delete/query)
+   * This should ONLY contain side effects (logging, cache invalidation, etc.), not data transformation
+   *
+   * @example
+   * ```typescript
+   * afterOperation: async ({ operation, value, item }) => {
+   *   await invalidateCache({ listKey, itemId: item.id })
+   *   await sendWebhook({ operation, item })
+   * }
+   * ```
+   */
+  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
+
+  /**
+   * Transform field value after database read
+   * Called when returning results from query operations
+   * This is where you should transform output data (e.g., wrap passwords, format values)
+   *
+   * @example
+   * ```typescript
+   * resolveOutput: ({ value }) => {
+   *   if (typeof value === 'string' && value.length > 0) {
+   *     return new HashedPassword(value)
+   *   }
+   *   return value
+   * }
+   * ```
+   */
+  resolveOutput?: (args: {
+    operation: 'query'
+    value: TInput | undefined
+    item: TItem
+    listKey: string
+    fieldName: string
+    context: import('../access/types.js').AccessContext
+  }) => TOutput | undefined
+}
+
+/**
+ * Configuration for patching Prisma-generated types
+ * Allows fields to transform their types in query results
+ */
+export type TypePatchConfig = {
+  /**
+   * The TypeScript type to use in Prisma result types (e.g., Payload scalars)
+   * This is an import statement like: "import('@opensaas/stack-core').HashedPassword"
+   */
+  resultType: string
+  /**
+   * Optional: Where to apply the patch
+   * - 'scalars-only': Only patch in Payload scalars (default, safest)
+   * - 'all': Patch everywhere the field appears (including inputs)
+   */
+  patchScope?: 'scalars-only' | 'all'
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type BaseFieldConfig<TInput = any, TOutput = TInput> = {
+  type: string
+  access?: FieldAccess
+  defaultValue?: unknown
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  hooks?: FieldHooks<TInput, TOutput, any>
+  /**
+   * 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
+   */
+  typePatch?: TypePatchConfig
+  ui?: {
+    /**
+     * Custom React component to render this field
+     * Overrides the default component for this field type
+     * Uses `any` to accept any React component type without overly complex generics
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    component?: any
+    /**
+     * Custom field type name to use from the global registry
+     * e.g., "color" to use a globally registered ColorPickerField
+     */
+    fieldType?: string
+    /**
+     * Transform field value before sending to client (browser)
+     * Useful for sensitive fields (e.g., passwords) or complex data structures
+     * that shouldn't be serialized in their raw form
+     *
+     * @example
+     * ```typescript
+     * // Password field: send only whether it's set, not the hash
+     * valueForClientSerialization: ({ value }) => ({ isSet: !!value })
+     * ```
+     */
+    valueForClientSerialization?: (args: { value: unknown }) => unknown
+    /**
+     * Additional UI-specific configuration
+     */
+    [key: string]: unknown
+  }
+  /**
+   * Generate Zod schema for this field
+   * @param fieldName - The name of the field (for error messages)
+   * @param operation - Whether this is a create or update operation
+   */
+  getZodSchema?: (fieldName: string, operation: 'create' | 'update') => z.ZodTypeAny
+  /**
+   * Get Prisma type and modifiers for schema generation
+   * @param fieldName - The name of the field (for generating modifiers)
+   * @returns Prisma type string and optional modifiers
+   */
+  getPrismaType?: (fieldName: string) => {
+    type: string
+    modifiers?: string
+  }
+  /**
+   * Get TypeScript type information for type generation
+   * @returns TypeScript type string and optionality
+   */
+  getTypeScriptType?: () => {
+    type: string
+    optional: boolean
+  }
+}
+
+export type TextField = BaseFieldConfig<string, string> & {
+  type: 'text'
+  validation?: {
+    isRequired?: boolean
+    length?: {
+      min?: number
+      max?: number
+    }
+  }
+  isIndexed?: boolean | 'unique'
+  ui?: {
+    displayMode?: 'input' | 'textarea'
+  }
+}
+
+export type IntegerField = BaseFieldConfig<number, number> & {
+  type: 'integer'
+  validation?: {
+    isRequired?: boolean
+    min?: number
+    max?: number
+  }
+}
+
+export type CheckboxField = BaseFieldConfig<boolean, boolean> & {
+  type: 'checkbox'
+}
+
+export type TimestampField = BaseFieldConfig<Date, Date> & {
+  type: 'timestamp'
+  defaultValue?: { kind: 'now' } | Date
+}
+
+export type PasswordField = BaseFieldConfig<
+  string,
+  import('../utils/password.js').HashedPassword
+> & {
+  type: 'password'
+  validation?: {
+    isRequired?: boolean
+  }
+}
+
+export type SelectField = BaseFieldConfig<string, string> & {
+  type: 'select'
+  options: Array<{ label: string; value: string }>
+  validation?: {
+    isRequired?: boolean
+  }
+  ui?: {
+    displayMode?: 'select' | 'segmented-control' | 'radio'
+  }
+}
+
+export type RelationshipField = BaseFieldConfig<string | string[], string | string[]> & {
+  type: 'relationship'
+  ref: string // Format: 'ListName.fieldName'
+  many?: boolean
+  ui?: {
+    displayMode?: 'select' | 'cards'
+  }
+}
+
+export type FieldConfig =
+  | TextField
+  | IntegerField
+  | CheckboxField
+  | TimestampField
+  | PasswordField
+  | SelectField
+  | RelationshipField
+  | BaseFieldConfig // Allow any field extending BaseFieldConfig (for third-party fields)
+
+/**
+ * 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
+ */
+type WithItemType<TField extends FieldConfig, TItem> =
+  TField extends BaseFieldConfig<infer TInput, infer TOutput>
+    ? Omit<TField, 'hooks'> & {
+        hooks?: FieldHooks<TInput, TOutput, TItem>
+      }
+    : TField
+
+/**
+ * Utility type to transform all fields in a record to inject item type
+ * Maps over each field and applies WithItemType 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>
+}
+
+// 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
+export type OperationAccess<T = any> = {
+  query?: AccessControl<T>
+  create?: AccessControl<T>
+  update?: AccessControl<T>
+  delete?: AccessControl<T>
+}
+
+export type HookArgs<T = Record<string, unknown>> = {
+  operation: 'create' | 'update' | 'delete'
+  resolvedData?: Partial<T>
+  item?: T
+  context: import('../access/types.js').AccessContext
+}
+
+export type Hooks<T = Record<string, unknown>> = {
+  resolveInput?: (args: HookArgs<T> & { operation: 'create' | 'update' }) => Promise<Partial<T>>
+  validateInput?: (
+    args: HookArgs<T> & {
+      operation: 'create' | 'update'
+      addValidationError: (msg: string) => void
+    },
+  ) => Promise<void>
+  beforeOperation?: (args: HookArgs<T>) => Promise<void>
+  afterOperation?: (args: HookArgs<T>) => 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>
+  access?: {
+    operation?: OperationAccess<T>
+  }
+  hooks?: Hooks<T>
+}
+
+/**
+ * Database configuration
+ */
+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
+   *
+   * @example
+   * ```typescript
+   * import { PrismaNeon } from '@prisma/adapter-neon'
+   * import { neonConfig } from '@neondatabase/serverless'
+   * import ws from 'ws'
+   *
+   * prismaClientConstructor: (PrismaClient) => {
+   *   neonConfig.webSocketConstructor = ws
+   *   const adapter = new PrismaNeon({
+   *     connectionString: process.env.DATABASE_URL
+   *   })
+   *   return new PrismaClient({ adapter })
+   * }
+   * ```
+   */
+  // 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
+}
+
+/**
+ * Session configuration
+ */
+export type SessionConfig = {
+  // Uses `any` return type because session structure is user-defined and varies per application
+  // The stack doesn't enforce a specific session shape - users can use NextAuth, Clerk, etc.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  getSession: () => Promise<any>
+}
+
+/**
+ * Theme preset options
+ */
+export type ThemePreset = 'modern' | 'classic' | 'neon'
+
+/**
+ * Custom theme colors (HSL values without hsl() wrapper)
+ * Format: "220 20% 97%" (hue saturation lightness)
+ */
+export type ThemeColors = {
+  background?: string
+  foreground?: string
+  card?: string
+  cardForeground?: string
+  popover?: string
+  popoverForeground?: string
+  primary?: string
+  primaryForeground?: string
+  secondary?: string
+  secondaryForeground?: string
+  muted?: string
+  mutedForeground?: string
+  accent?: string
+  accentForeground?: string
+  destructive?: string
+  destructiveForeground?: string
+  border?: string
+  input?: string
+  ring?: string
+  gradientFrom?: string
+  gradientTo?: string
+}
+
+/**
+ * Theme configuration
+ */
+export type ThemeConfig = {
+  /**
+   * Preset theme to use
+   * @default "modern"
+   */
+  preset?: ThemePreset
+  /**
+   * Custom color overrides for light mode
+   */
+  colors?: ThemeColors
+  /**
+   * Custom color overrides for dark mode
+   */
+  darkColors?: ThemeColors
+  /**
+   * Border radius in rem
+   * @default 0.75
+   */
+  radius?: number
+}
+
+/**
+ * UI configuration
+ */
+export type UIConfig = {
+  basePath?: string
+  /**
+   * Theme configuration for the admin UI
+   */
+  theme?: ThemeConfig
+}
+
+/**
+ * Main configuration type
+ */
+export type OpenSaasConfig = {
+  db: DatabaseConfig
+  lists: Record<string, ListConfig>
+  session?: SessionConfig
+  ui?: UIConfig
+  /**
+   * Path where OpenSaas generates files (context, types, patched Prisma client)
+   * @default ".opensaas"
+   */
+  opensaasPath?: string
+}