@opensaas/stack-core 0.20.0 → 0.21.0

package/src/fields/index.ts

@@ -11,9 +11,30 @@ import type {
   RelationshipField,
   JsonField,
   VirtualField,
+  OpenSaasConfig,
+  FieldConfig,
+  PrismaRelationResult,
 } from '../config/types.js'
 import { hashPassword, isHashedPassword, HashedPassword } from '../utils/password.js'
 
+// Field-config types live here, alongside the builders that produce them.
+// (The umbrella `FieldConfig` and authoring `BaseFieldConfig` stay on the root
+// and `/extend` entry points respectively.)
+export type {
+  TextField,
+  IntegerField,
+  DecimalField,
+  CheckboxField,
+  TimestampField,
+  CalendarDayField,
+  PasswordField,
+  SelectField,
+  RelationshipField,
+  JsonField,
+  VirtualField,
+  PrismaRelationResult,
+} from '../config/types.js'
+
 /**
  * Format field name for display in error messages
  */
@@ -642,7 +663,7 @@ export function password<TTypeInfo extends import('../config/types.js').TypeInfo
     type: 'password',
     ...options,
     resultExtension: {
-      outputType: "import('@opensaas/stack-core').HashedPassword",
+      outputType: "import('@opensaas/stack-core/internal').HashedPassword",
       // No compute - delegates to resolveOutput hook
     },
     ui: {
@@ -865,6 +886,284 @@ export function select<
   }
 }
 
+/**
+ * Parse a relationship ref into its target list and optional target field.
+ * Supports both 'ListName.fieldName' (bidirectional) and 'ListName' (list-only) formats.
+ */
+function parseRelationshipRef(ref: string): { list: string; field?: string } {
+  const parts = ref.split('.')
+  if (parts.length === 1) {
+    const list = parts[0]
+    if (!list) {
+      throw new Error(`Invalid relationship ref: ${ref}`)
+    }
+    return { list }
+  } else if (parts.length === 2) {
+    const [list, field] = parts
+    if (!list || !field) {
+      throw new Error(`Invalid relationship ref: ${ref}`)
+    }
+    return { list, field }
+  } else {
+    throw new Error(`Invalid relationship ref: ${ref}`)
+  }
+}
+
+/**
+ * Check if a relationship is one-to-one (bidirectional with both sides having many: false).
+ */
+function isOneToOneRelationship(
+  fieldName: string,
+  field: RelationshipField,
+  config: OpenSaasConfig,
+): boolean {
+  const { list: targetList, field: targetField } = parseRelationshipRef(field.ref)
+  if (!targetField) {
+    return false
+  }
+
+  if (field.many) {
+    return false
+  }
+
+  const targetListConfig = config.lists[targetList]
+  if (!targetListConfig) {
+    throw new Error(`Referenced list "${targetList}" not found in config`)
+  }
+
+  const targetFieldConfig = targetListConfig.fields[targetField]
+  if (!targetFieldConfig) {
+    throw new Error(
+      `Referenced field "${targetList}.${targetField}" not found. If you want a one-sided relationship, use ref: "${targetList}" instead of ref: "${targetList}.${targetField}"`,
+    )
+  }
+  if (targetFieldConfig.type !== 'relationship') {
+    throw new Error(`Referenced field "${targetList}.${targetField}" is not a relationship field`)
+  }
+
+  return !(targetFieldConfig as RelationshipField).many
+}
+
+/**
+ * Determine if this side of a relationship should store the foreign key.
+ * For one-to-one relationships, only one side stores the foreign key.
+ */
+function shouldHaveForeignKey(
+  listKey: string,
+  fieldName: string,
+  field: RelationshipField,
+  config: OpenSaasConfig,
+): boolean {
+  const { list: targetList, field: targetField } = parseRelationshipRef(field.ref)
+  if (!targetField) {
+    return true
+  }
+
+  if (field.many) {
+    return false
+  }
+
+  const isOneToOne = isOneToOneRelationship(fieldName, field, config)
+  if (!isOneToOne) {
+    return true
+  }
+
+  const targetListConfig = config.lists[targetList]!
+  const targetFieldConfig = targetListConfig.fields[targetField] as RelationshipField
+
+  const thisSideExplicit = field.db?.foreignKey
+  const otherSideExplicit = targetFieldConfig.db?.foreignKey
+
+  if (thisSideExplicit === true && otherSideExplicit === true) {
+    throw new Error(
+      `Invalid one-to-one relationship: both "${listKey}.${fieldName}" and "${targetList}.${targetField}" have db.foreignKey set to true. Only one side can store the foreign key.`,
+    )
+  }
+
+  if (thisSideExplicit === true) {
+    return true
+  }
+
+  if (otherSideExplicit === true) {
+    return false
+  }
+
+  // Default: the alphabetically "smaller" list name gets the foreign key
+  const comparison = listKey.localeCompare(targetList)
+  if (comparison !== 0) {
+    return comparison < 0
+  }
+
+  // Self-referential: use field name ordering
+  return fieldName.localeCompare(targetField) < 0
+}
+
+/**
+ * Check whether a many relationship is a true many-to-many (both sides many).
+ */
+function isManyToMany(
+  fieldName: string,
+  field: RelationshipField,
+  config: OpenSaasConfig,
+): boolean {
+  if (!field.many) {
+    return false
+  }
+
+  const { list: targetList, field: targetField } = parseRelationshipRef(field.ref)
+
+  // List-only ref with many: true is implicitly many-to-many
+  if (!targetField) {
+    return true
+  }
+
+  const targetFieldConfig = config.lists[targetList]?.fields[targetField]
+  if (!targetFieldConfig || targetFieldConfig.type !== 'relationship') {
+    return false
+  }
+
+  return !!(targetFieldConfig as RelationshipField).many
+}
+
+/**
+ * Compute the explicit relation name for a bidirectional many-to-many relationship,
+ * or `undefined` when Prisma's default naming should be used.
+ *
+ * Honours per-field `db.relationName` (which must match on both sides) and the
+ * global `db.joinTableNaming: 'keystone'` setting, picking a deterministic owner
+ * for bidirectional relationships so both sides resolve to the same name.
+ */
+function computeManyToManyRelationName(
+  listKey: string,
+  fieldName: string,
+  field: RelationshipField,
+  config: OpenSaasConfig,
+): string | undefined {
+  const { list: targetList, field: targetField } = parseRelationshipRef(field.ref)
+  const joinTableNaming = config.db.joinTableNaming || 'prisma'
+
+  const sourceRelationName = field.db?.relationName
+  let targetRelationName: string | undefined
+  if (targetField) {
+    const targetFieldConfig = config.lists[targetList]?.fields[targetField]
+    if (targetFieldConfig?.type === 'relationship') {
+      targetRelationName = (targetFieldConfig as RelationshipField).db?.relationName
+    }
+  }
+
+  if (sourceRelationName && targetRelationName && sourceRelationName !== targetRelationName) {
+    throw new Error(
+      `Relation name mismatch: ${listKey}.${fieldName} has relationName "${sourceRelationName}" but ${targetList}.${targetField} has "${targetRelationName}". Both sides must use the same relationName.`,
+    )
+  }
+
+  const explicitRelationName = sourceRelationName || targetRelationName
+  if (explicitRelationName) {
+    return explicitRelationName
+  }
+
+  if (joinTableNaming === 'keystone') {
+    if (targetField) {
+      // Pick a deterministic owner so both sides agree on the relation name
+      const sourceKey = `${listKey}.${fieldName}`
+      const targetKey = `${targetList}.${targetField}`
+      return sourceKey.localeCompare(targetKey) < 0
+        ? `${listKey}_${fieldName}`
+        : `${targetList}_${targetField}`
+    }
+    return `${listKey}_${fieldName}`
+  }
+
+  // Default Prisma naming - no explicit relation name needed
+  return undefined
+}
+
+/**
+ * Build the Prisma schema contribution for a relationship field.
+ */
+function getPrismaRelation(
+  field: RelationshipField,
+  fieldName: string,
+  listKey: string,
+  config: OpenSaasConfig,
+): PrismaRelationResult {
+  const { list: targetList, field: targetField } = parseRelationshipRef(field.ref)
+  const paddedName = fieldName.padEnd(12)
+
+  // Synthetic back-relation for list-only refs (Prisma requires an opposite field)
+  let backRelation: PrismaRelationResult['backRelation']
+  if (!targetField) {
+    const syntheticFieldName = `from_${listKey}_${fieldName}`
+    const relationName = field.db?.relationName ?? `${listKey}_${fieldName}`
+    backRelation = {
+      targetList,
+      line: `  ${syntheticFieldName.padEnd(12)} ${listKey}[]  @relation("${relationName}")`,
+    }
+  }
+
+  if (field.many) {
+    let relationLine: string
+
+    if (targetField) {
+      // Bidirectional many side: use explicit relation name only for true many-to-many
+      const m2mName = isManyToMany(fieldName, field, config)
+        ? computeManyToManyRelationName(listKey, fieldName, field, config)
+        : undefined
+      relationLine = m2mName
+        ? `  ${paddedName} ${targetList}[]  @relation("${m2mName}")`
+        : `  ${paddedName} ${targetList}[]`
+    } else {
+      // List-only ref many side: always a named relation paired with the synthetic field
+      const relationName = field.db?.relationName ?? `${listKey}_${fieldName}`
+      relationLine = `  ${paddedName} ${targetList}[]  @relation("${relationName}")`
+    }
+
+    if (field.db?.extendPrismaSchema) {
+      relationLine = field.db.extendPrismaSchema({ relationLine }).relationLine
+    }
+
+    return { modelLines: [relationLine], backRelation }
+  }
+
+  // Single relationship
+  if (shouldHaveForeignKey(listKey, fieldName, field, config)) {
+    const foreignKeyField = `${fieldName}Id`
+    const fkPaddedName = foreignKeyField.padEnd(12)
+
+    const uniqueModifier = isOneToOneRelationship(fieldName, field, config) ? ' @unique' : ''
+
+    const mapModifier =
+      typeof field.db?.foreignKey === 'object' && field.db.foreignKey.map
+        ? ` @map("${field.db.foreignKey.map}")`
+        : ` @map("${fieldName}")`
+
+    let fkLine = `  ${fkPaddedName} String?${uniqueModifier}${mapModifier}`
+    let relationLine = targetField
+      ? `  ${paddedName} ${targetList}?  @relation(fields: [${foreignKeyField}], references: [id])`
+      : `  ${paddedName} ${targetList}?  @relation("${listKey}_${fieldName}", fields: [${foreignKeyField}], references: [id])`
+
+    if (field.db?.extendPrismaSchema) {
+      const extended = field.db.extendPrismaSchema({ fkLine, relationLine })
+      fkLine = extended.fkLine ?? fkLine
+      relationLine = extended.relationLine
+    }
+
+    // Default to indexing foreign keys (matching Keystone behaviour) unless disabled
+    const indexType = field.isIndexed ?? true
+    const foreignKeyIndex = indexType !== false ? { foreignKeyField, indexType } : undefined
+
+    return { modelLines: [fkLine, relationLine], foreignKeyIndex, backRelation }
+  }
+
+  // Non-FK side of a one-to-one relationship: just the relation field
+  let relationLine = `  ${paddedName} ${targetList}?`
+  if (field.db?.extendPrismaSchema) {
+    relationLine = field.db.extendPrismaSchema({ relationLine }).relationLine
+  }
+
+  return { modelLines: [relationLine], backRelation }
+}
+
 /**
  * Relationship field
  */
@@ -902,10 +1201,19 @@ export function relationship<
     }
   }
 
-  return {
+  const field: RelationshipField<TTypeInfo> = {
     type: 'relationship',
     ...options,
   }
+
+  field.getPrismaRelation = (
+    fieldName: string,
+    _allFields: Record<string, FieldConfig>,
+    listKey: string,
+    config: OpenSaasConfig,
+  ) => getPrismaRelation(field as RelationshipField, fieldName, listKey, config)
+
+  return field
 }
 
 /**

package/src/hooks/index.ts

@@ -213,6 +213,233 @@ export async function executeAfterOperation<
   await hooks.afterOperation(args as Parameters<typeof hooks.afterOperation>[0])
 }
 
+/**
+ * Execute field-level resolveInput hooks
+ * Allows fields to transform their input values before database write
+ */
+export async function executeFieldResolveInputHooks(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputData: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  resolvedData: Record<string, any>,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update',
+  context: AccessContext,
+  listKey: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item?: any,
+): Promise<Record<string, unknown>> {
+  let result = { ...resolvedData }
+
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    // Skip if field not in data
+    if (!(fieldKey in result)) continue
+
+    // Skip if no hooks defined
+    if (!fieldConfig.hooks?.resolveInput) continue
+
+    // Execute field hook
+    // Type assertion is safe here because hooks are typed correctly in field definitions
+    // and we're working with runtime values that match those types
+    const transformedValue = await fieldConfig.hooks.resolveInput({
+      listKey,
+      fieldKey,
+      operation,
+      inputData,
+      item,
+      resolvedData: { ...result }, // Pass a copy to avoid mutation affecting recorded args
+      context,
+    } as Parameters<typeof fieldConfig.hooks.resolveInput>[0])
+
+    // Create new object with updated field to avoid mutating the passed reference
+    result = { ...result, [fieldKey]: transformedValue }
+  }
+
+  return result
+}
+
+/**
+ * Execute field-level validate hooks
+ * Allows fields to perform custom validation after resolveInput but before database write
+ */
+export async function executeFieldValidateHooks(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputData: Record<string, any> | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  resolvedData: Record<string, any> | undefined,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update' | 'delete',
+  context: AccessContext,
+  listKey: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item?: any,
+): Promise<void> {
+  const errors: string[] = []
+  const fieldErrors: Record<string, string> = {}
+
+  const addValidationError = (fieldKey: string) => (msg: string) => {
+    errors.push(msg)
+    fieldErrors[fieldKey] = msg
+  }
+
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    // Support both 'validate' (new) and 'validateInput' (deprecated) for backwards compatibility
+    const validateHook = fieldConfig.hooks?.validate ?? fieldConfig.hooks?.validateInput
+    if (!validateHook) continue
+
+    // Execute field hook
+    // Type assertion is safe here because hooks are typed correctly in field definitions
+    if (operation === 'delete') {
+      await validateHook({
+        listKey,
+        fieldKey,
+        operation: 'delete',
+        item,
+        context,
+        addValidationError: addValidationError(fieldKey),
+      } as Parameters<typeof validateHook>[0])
+    } else if (operation === 'create') {
+      await validateHook({
+        listKey,
+        fieldKey,
+        operation: 'create',
+        inputData,
+        item: undefined,
+        resolvedData,
+        context,
+        addValidationError: addValidationError(fieldKey),
+      } as Parameters<typeof validateHook>[0])
+    } else {
+      // operation === 'update'
+      await validateHook({
+        listKey,
+        fieldKey,
+        operation: 'update',
+        inputData,
+        item,
+        resolvedData,
+        context,
+        addValidationError: addValidationError(fieldKey),
+      } as Parameters<typeof validateHook>[0])
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ValidationError(errors, fieldErrors)
+  }
+}
+
+/**
+ * Execute field-level beforeOperation hooks (side effects only)
+ * Allows fields to perform side effects before database write
+ */
+export async function executeFieldBeforeOperationHooks(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputData: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  resolvedData: Record<string, any>,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update' | 'delete',
+  context: AccessContext,
+  listKey: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item?: any,
+): Promise<void> {
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    // Skip if no hooks defined
+    if (!fieldConfig.hooks?.beforeOperation) continue
+    // Skip if field not in data (for create/update)
+    if (operation !== 'delete' && !(fieldKey in resolvedData)) continue
+
+    // Execute field hook (side effects only, no return value used)
+    // Type assertion is safe here because hooks are typed correctly in field definitions
+    if (operation === 'delete') {
+      await fieldConfig.hooks.beforeOperation({
+        listKey,
+        fieldKey,
+        operation: 'delete',
+        item,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.beforeOperation>[0])
+    } else if (operation === 'create') {
+      await fieldConfig.hooks.beforeOperation({
+        listKey,
+        fieldKey,
+        operation: 'create',
+        inputData,
+        resolvedData,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.beforeOperation>[0])
+    } else {
+      // operation === 'update'
+      await fieldConfig.hooks.beforeOperation({
+        listKey,
+        fieldKey,
+        operation: 'update',
+        inputData,
+        item,
+        resolvedData,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.beforeOperation>[0])
+    }
+  }
+}
+
+/**
+ * Execute field-level afterOperation hooks (side effects only)
+ * Allows fields to perform side effects after database operations
+ */
+export async function executeFieldAfterOperationHooks(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item: any,
+  inputData: Record<string, unknown> | undefined,
+  resolvedData: Record<string, unknown> | undefined,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update' | 'delete',
+  context: AccessContext,
+  listKey: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  originalItem?: any,
+): Promise<void> {
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    // Skip if no hooks defined
+    if (!fieldConfig.hooks?.afterOperation) continue
+
+    // Execute field hook (side effects only, no return value used)
+    if (operation === 'delete') {
+      await fieldConfig.hooks.afterOperation({
+        listKey,
+        fieldKey,
+        operation: 'delete',
+        originalItem,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.afterOperation>[0])
+    } else if (operation === 'create') {
+      await fieldConfig.hooks.afterOperation({
+        listKey,
+        fieldKey,
+        operation: 'create',
+        inputData,
+        item,
+        resolvedData,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.afterOperation>[0])
+    } else {
+      // operation === 'update'
+      await fieldConfig.hooks.afterOperation({
+        listKey,
+        fieldKey,
+        operation: 'update',
+        inputData,
+        originalItem,
+        item,
+        resolvedData,
+        context,
+      } as Parameters<typeof fieldConfig.hooks.afterOperation>[0])
+    }
+  }
+}
+
 /**
  * Validate field-level validation rules using Zod
  * Checks isRequired, length constraints, etc.

package/src/index.ts

@@ -1,105 +1,42 @@
-// Config system
+// ───────────────────────────────────────────────────────────────
+// @opensaas/stack-core — consumer entry point
+//
+// The everyday surface for defining a config and using a context.
+//   • Field builders            → '@opensaas/stack-core/fields'
+//   • Plugin / field authoring  → '@opensaas/stack-core/extend'
+//   • MCP runtime               → '@opensaas/stack-core/mcp'
+// Internal plumbing lives on '@opensaas/stack-core/internal' (unstable).
+// ───────────────────────────────────────────────────────────────
+
+// Config builders
 export { config, list } from './config/index.js'
-export type {
-  OpenSaasConfig,
-  ListConfig,
-  FieldConfig,
-  BaseFieldConfig,
-  TextField,
-  IntegerField,
-  CheckboxField,
-  TimestampField,
-  PasswordField,
-  SelectField,
-  RelationshipField,
-  JsonField,
-  VirtualField,
-  TypeDescriptor,
-  TypeInfo,
-  OperationAccess,
-  Hooks,
-  FieldHooks,
-  FieldsWithTypeInfo,
-  DatabaseConfig,
-  SessionConfig,
-  UIConfig,
-  ThemeConfig,
-  ThemePreset,
-  ThemeColors,
-  McpConfig,
-  McpToolsConfig,
-  McpAuthConfig,
-  ListMcpConfig,
-  McpCustomTool,
-  FileMetadata,
-  ImageMetadata,
-  ImageTransformationResult,
-  // Plugin system types
-  Plugin,
-  PluginContext,
-  GeneratedFiles,
-  // List-level hook argument types
-  ResolveInputHookArgs,
-  ValidateHookArgs,
-  BeforeOperationHookArgs,
-  AfterOperationHookArgs,
-  // Field-level hook argument types
-  FieldResolveInputHookArgs,
-  FieldValidateHookArgs,
-  FieldBeforeOperationHookArgs,
-  FieldAfterOperationHookArgs,
-  FieldResolveOutputHookArgs,
-} from './config/index.js'
 
-// Access control
+// Config types a consumer annotates with.
+// Concrete field-config types (TextField, …) live on '@opensaas/stack-core/fields'
+// alongside their builders.
+export type { OpenSaasConfig, ListConfig, FieldConfig, OperationAccess } from './config/index.js'
+
+// Access control — the types a consumer writes against
 export type {
   AccessControl,
   FieldAccess,
   Session,
   AccessContext,
   PrismaFilter,
-  AccessControlledDB,
-  StorageUtils,
-  AugmentedFindMany,
-  AugmentedFindUnique,
-  FindManyQueryArgs,
 } from './access/index.js'
 
-// Context
+// Context factory
 export { getContext } from './context/index.js'
-export type { PrismaClientLike } from './access/types.js'
-export type { ServerActionProps } from './context/index.js'
 
-// Utilities
-export {
-  getDbKey,
-  getUrlKey,
-  getListKeyFromUrl,
-  pascalToCamel,
-  pascalToKebab,
-  kebabToPascal,
-  kebabToCamel,
-} from './lib/case-utils.js'
+// Naming utilities (documented public helpers; used for URLs and db keys)
+export { getDbKey, getUrlKey, getListKeyFromUrl } from './lib/case-utils.js'
 
-// Hooks and validation
+// Validation error surfaced by write operations
 export { ValidationError } from './hooks/index.js'
-export { validateWithZod, generateZodSchema } from './validation/schema.js'
 
-// Password utilities
-export {
-  hashPassword,
-  comparePassword,
-  isHashedPassword,
-  HashedPassword,
-} from './utils/password.js'
-
-// Query utilities — fragment-based, type-safe query helpers
-export { defineFragment, runQuery, runQueryOne } from './query/index.js'
-export type {
-  Fragment,
-  FieldSelection,
-  ResultOf,
-  RelationSelector,
-  QueryArgs,
-  QueryRunnerContext,
-} from './query/index.js'
+// Field self-containment validation — checks each field implements the
+// generation contract (getPrismaType / getTypeScriptType / getZodSchema, or
+// getPrismaRelation for relationships) so a misimplemented field fails early
+// with a clear per-field message instead of deep inside generation.
+export { validateFieldConfig, validateConfigFields } from './validation/field-config.js'
+export type { FieldConfigValidationError } from './validation/field-config.js'