@opensaas/stack-core 0.13.0 → 0.14.0

package/src/config/index.ts

@@ -1,5 +1,38 @@
-import type { OpenSaasConfig, ListConfig, OperationAccess, Hooks } from './types.js'
+import type {
+  OpenSaasConfig,
+  ListConfig,
+  ListConfigInput,
+  OperationAccess,
+  ListAccessControl,
+} from './types.js'
 import { executePlugins } from './plugin-engine.js'
+import type { AccessControl } from '../access/types.js'
+
+/**
+ * Normalize access control shorthand to object form
+ * Converts function shorthand to { operation: { query, create, update, delete } } form
+ */
+function normalizeListAccess<T>(
+  access: ListAccessControl<T> | undefined,
+): { operation?: OperationAccess<T> } | undefined {
+  if (!access) return undefined
+
+  // If it's a function, convert to object form applying to all operations
+  if (typeof access === 'function') {
+    const fn = access as AccessControl<T>
+    return {
+      operation: {
+        query: fn,
+        create: fn,
+        update: fn,
+        delete: fn,
+      },
+    }
+  }
+
+  // Already in object form
+  return access
+}
 
 /**
  * Helper function to define configuration with type safety
@@ -61,25 +94,37 @@ export function config(userConfig: OpenSaasConfig): OpenSaasConfig | Promise<Ope
  *   fields: { title: text() },
  *   hooks: { ... }
  * })
+ *
+ * // Access control shorthand
+ * const isAdmin = ({ session }) => session?.role === 'admin'
+ *
+ * Settings: list({
+ *   access: isAdmin,  // Applies to all operations
+ *   isSingleton: true,
+ *   fields: { ... }
+ * })
  * ```
  */
-export function list<TTypeInfo extends import('./types.js').TypeInfo>(config: {
-  fields: import('./types.js').FieldsWithTypeInfo<TTypeInfo>
-  access?: {
-    operation?: OperationAccess<TTypeInfo['item']>
+export function list<TTypeInfo extends import('./types.js').TypeInfo>(
+  config: ListConfigInput<TTypeInfo>,
+): ListConfig<TTypeInfo> {
+  // Normalize access control shorthand to object form
+  const normalizedConfig = {
+    ...config,
+    access: normalizeListAccess(config.access),
   }
-  hooks?: Hooks<TTypeInfo['item'], TTypeInfo['inputs']['create'], TTypeInfo['inputs']['update']>
-  mcp?: import('./types.js').ListMcpConfig
-}): ListConfig<TTypeInfo> {
+
   // At runtime, field configs are unchanged
   // At type level, they're transformed to inject TypeInfo types
-  return config as ListConfig<TTypeInfo>
+  return normalizedConfig as ListConfig<TTypeInfo>
 }
 
 // Re-export all types
 export type {
   OpenSaasConfig,
   ListConfig,
+  ListConfigInput,
+  ListAccessControl,
   FieldConfig,
   BaseFieldConfig,
   TextField,
@@ -115,4 +160,15 @@ export type {
   Plugin,
   PluginContext,
   GeneratedFiles,
+  // List-level hook argument types
+  ResolveInputHookArgs,
+  ValidateHookArgs,
+  BeforeOperationHookArgs,
+  AfterOperationHookArgs,
+  // Field-level hook argument types
+  FieldResolveInputHookArgs,
+  FieldValidateHookArgs,
+  FieldBeforeOperationHookArgs,
+  FieldAfterOperationHookArgs,
+  FieldResolveOutputHookArgs,
 } from './types.js'

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
@@ -55,25 +207,7 @@ export type FieldHooks<
    * ```
    */
   resolveInput?: (
-    args:
-      | {
-          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
-        },
+    args: FieldResolveInputHookArgs<TTypeInfo, TFieldKey>,
   ) =>
     | Promise<GetFieldValueType<TTypeInfo['fields'], TFieldKey> | undefined>
     | GetFieldValueType<TTypeInfo['fields'], TFieldKey>
@@ -95,37 +229,12 @@ export type FieldHooks<
    * }
    * ```
    */
-  validate?: (
-    args:
-      | {
-          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
-        },
-  ) => Promise<void> | void
+  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
@@ -146,31 +255,7 @@ export type FieldHooks<
    * ```
    */
   beforeOperation?: (
-    args:
-      | {
-          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
-        },
+    args: FieldBeforeOperationHookArgs<TTypeInfo, TFieldKey>,
   ) => Promise<void> | void
 
   /**
@@ -191,35 +276,7 @@ export type FieldHooks<
    * }
    * ```
    */
-  afterOperation?: (
-    args:
-      | {
-          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
-        },
-  ) => Promise<void> | void
+  afterOperation?: (args: FieldAfterOperationHookArgs<TTypeInfo, TFieldKey>) => Promise<void> | void
 
   /**
    * Transform field value after database read
@@ -236,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
 }
 
 /**
@@ -274,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>
   /**
@@ -539,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'
@@ -752,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
@@ -911,10 +1040,19 @@ export type Hooks<
 
 // 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']>
   }
@@ -923,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']>
 }
 
 /**