@opensaas/stack-core 0.18.2 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-core",
-  "version": "0.18.2",
+  "version": "0.19.1",
   "description": "Core stack for OpenSaas - schema definition, access control, and runtime utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
   },
   "devDependencies": {
     "@prisma/client": "^7.1.0",
-    "@types/node": "^24.10.1",
+    "@types/node": "^24.11.0",
     "@vitest/coverage-v8": "^4.0.15",
     "typescript": "^5.9.3",
     "vitest": "^4.0.15"

package/src/config/types.ts

@@ -374,6 +374,52 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
      * ```
      */
     map?: string
+    /**
+     * Controls DB-level nullability independently of validation.isRequired.
+     * When specified, overrides the default behavior where nullability is inferred
+     * from validation.isRequired (required = non-nullable, optional = nullable).
+     *
+     * This allows you to:
+     * - Make a field non-nullable at the DB level without making it API-required
+     * - Explicitly mark a field as nullable even when it has isRequired validation
+     *
+     * @example
+     * ```typescript
+     * // DB non-nullable, but API optional (relies on a default value or hook)
+     * fields: {
+     *   phoneNumber: text({
+     *     db: { isNullable: false }
+     *   })
+     *   // Generates: phoneNumber String (non-nullable)
+     *
+     *   // DB nullable (explicit), regardless of validation
+     *   lastMessagePreview: text({
+     *     db: { isNullable: true }
+     *   })
+     *   // Generates: lastMessagePreview String? (nullable)
+     * }
+     * ```
+     */
+    isNullable?: boolean
+    /**
+     * Override the native database type for the column.
+     * Generates a @db.<nativeType> attribute in the Prisma schema.
+     * The available types depend on your database provider.
+     *
+     * @example
+     * ```typescript
+     * // PostgreSQL: use TEXT instead of VARCHAR
+     * fields: {
+     *   description: text({ db: { nativeType: 'Text' } })
+     *   // Generates: description String? @db.Text
+     *
+     *   // PostgreSQL: use SMALLINT instead of INT
+     *   count: integer({ db: { nativeType: 'SmallInt' } })
+     *   // Generates: count Int? @db.SmallInt
+     * }
+     * ```
+     */
+    nativeType?: string
   }
   ui?: {
     /**
@@ -415,14 +461,21 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
    * Get Prisma type and modifiers for schema generation
    * @param fieldName - The name of the field (for generating modifiers)
    * @param provider - Optional database provider ('sqlite', 'postgresql', 'mysql', etc.)
-   * @returns Prisma type string and optional modifiers
+   * @param listName - Optional list name (used for generating enum type names)
+   * @returns Prisma type string, optional modifiers, and optional enum values
    */
   getPrismaType?: (
     fieldName: string,
     provider?: string,
+    listName?: string,
   ) => {
     type: string
     modifiers?: string
+    /**
+     * If set, this field requires a Prisma enum definition with these values.
+     * The enum name is the value of `type`.
+     */
+    enumValues?: string[]
   }
   /**
    * Get TypeScript type information for type generation
@@ -465,37 +518,6 @@ export type TextField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<T
     }
   }
   isIndexed?: boolean | 'unique'
-  db?: {
-    map?: string
-    /**
-     * Prisma native database type attribute
-     * Allows overriding the default String type for the database provider
-     * @example
-     * ```typescript
-     * // PostgreSQL/MySQL
-     * fields: {
-     *   description: text({ db: { nativeType: 'Text' } })
-     *   // Generates: description String @db.Text
-     * }
-     * ```
-     */
-    nativeType?: string
-    /**
-     * Controls nullability in the database schema
-     * When specified, overrides the default behavior (isRequired determines nullability)
-     * @example
-     * ```typescript
-     * fields: {
-     *   description: text({
-     *     validation: { isRequired: true },
-     *     db: { isNullable: false }
-     *   })
-     *   // Generates: description String (non-nullable)
-     * }
-     * ```
-     */
-    isNullable?: boolean
-  }
   ui?: {
     displayMode?: 'input' | 'textarea'
   }
@@ -515,10 +537,6 @@ export type DecimalField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfi
   defaultValue?: string
   precision?: number
   scale?: number
-  db?: {
-    map?: string
-    isNullable?: boolean
-  }
   validation?: {
     isRequired?: boolean
     min?: string
@@ -539,10 +557,6 @@ export type TimestampField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldCon
 export type CalendarDayField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'calendarDay'
   defaultValue?: string
-  db?: {
-    map?: string
-    isNullable?: boolean
-  }
   validation?: {
     isRequired?: boolean
   }
@@ -559,6 +573,21 @@ export type PasswordField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConf
 export type SelectField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'select'
   options: Array<{ label: string; value: string }>
+  defaultValue?: string
+  db?: {
+    /**
+     * Whether to store as a native database enum type.
+     * - 'string' (default): stores as a plain string/varchar column
+     * - 'enum': stores as a Prisma enum, generating a native enum type in the schema
+     *
+     * Note: enum values must be valid Prisma identifiers (letters, numbers, underscores,
+     * starting with a letter) when using 'enum' type.
+     *
+     * @default 'string'
+     */
+    type?: 'string' | 'enum'
+    map?: string
+  }
   validation?: {
     isRequired?: boolean
   }

package/src/context/index.ts

@@ -893,8 +893,10 @@ function createCreate<TPrisma extends PrismaClientLike>(
     // Access Prisma model dynamically - required because model names are generated at runtime
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const model = (prisma as any)[getDbKey(listName)]
+    // Singleton lists use Int @id with value always 1 (matching Keystone 6 behaviour)
+    const createData = isSingletonList(listConfig) ? { id: 1, ...data } : data
     const item = await model.create({
-      data,
+      data: createData,
     })
 
     // 9. Execute list-level afterOperation hook

package/src/fields/index.ts

@@ -97,7 +97,7 @@ export function text<
 
       return {
         type: 'String',
-        modifiers: modifiers || undefined,
+        modifiers: modifiers.trimStart() || undefined,
       }
     },
     getTypeScriptType: () => {
@@ -145,22 +145,30 @@ export function integer<
         : withMax
     },
     getPrismaType: (_fieldName: string) => {
-      const isRequired = options?.validation?.isRequired
+      const validation = options?.validation
+      const db = options?.db
+      const isRequired = validation?.isRequired
+      const isNullable = db?.isNullable ?? !isRequired
       let modifiers = ''
 
       // Optional modifier
-      if (!isRequired) {
+      if (isNullable) {
         modifiers += '?'
       }
 
+      // Native type modifier (e.g., @db.SmallInt, @db.BigInt)
+      if (db?.nativeType) {
+        modifiers += ` @db.${db.nativeType}`
+      }
+
       // Map modifier
-      if (options?.db?.map) {
-        modifiers += ` @map("${options.db.map}")`
+      if (db?.map) {
+        modifiers += ` @map("${db.map}")`
       }
 
       return {
         type: 'Int',
-        modifiers: modifiers || undefined,
+        modifiers: modifiers.trimStart() || undefined,
       }
     },
     getTypeScriptType: () => {
@@ -353,21 +361,28 @@ export function checkbox<
       return z.boolean().optional().nullable()
     },
     getPrismaType: (_fieldName: string) => {
+      const db = options?.db
       const hasDefault = options?.defaultValue !== undefined
       let modifiers = ''
 
+      // Nullable modifier - checkbox fields are non-nullable by default (must be true or false)
+      // Use db.isNullable: true to allow NULL values in the database
+      if (db?.isNullable === true) {
+        modifiers += '?'
+      }
+
       if (hasDefault) {
-        modifiers = ` @default(${options.defaultValue})`
+        modifiers += ` @default(${options.defaultValue})`
       }
 
       // Map modifier
-      if (options?.db?.map) {
-        modifiers += ` @map("${options.db.map}")`
+      if (db?.map) {
+        modifiers += ` @map("${db.map}")`
       }
 
       return {
         type: 'Boolean',
-        modifiers: modifiers || undefined,
+        modifiers: modifiers.trimStart() || undefined,
       }
     },
     getTypeScriptType: () => {
@@ -392,26 +407,41 @@ export function timestamp<
       return z.union([z.date(), z.iso.datetime()]).optional().nullable()
     },
     getPrismaType: (_fieldName: string) => {
-      let modifiers = '?'
-
-      // Check for default value
-      if (
+      const db = options?.db
+      const hasDefaultNow =
         options?.defaultValue &&
         typeof options.defaultValue === 'object' &&
         'kind' in options.defaultValue &&
         options.defaultValue.kind === 'now'
-      ) {
-        modifiers = ' @default(now())'
+
+      // Nullability: explicit db.isNullable overrides the default (nullable unless @default(now()))
+      const isNullable = db?.isNullable ?? !hasDefaultNow
+
+      let modifiers = ''
+
+      // Optional modifier
+      if (isNullable) {
+        modifiers += '?'
+      }
+
+      // Default value
+      if (hasDefaultNow) {
+        modifiers += ' @default(now())'
+      }
+
+      // Native type modifier (e.g., @db.Timestamptz for PostgreSQL)
+      if (db?.nativeType) {
+        modifiers += ` @db.${db.nativeType}`
       }
 
       // Map modifier
-      if (options?.db?.map) {
-        modifiers += ` @map("${options.db.map}")`
+      if (db?.map) {
+        modifiers += ` @map("${db.map}")`
       }
 
       return {
         type: 'DateTime',
-        modifiers,
+        modifiers: modifiers.trimStart() || undefined,
       }
     },
     getTypeScriptType: () => {
@@ -689,22 +719,30 @@ export function password<TTypeInfo extends import('../config/types.js').TypeInfo
       }
     },
     getPrismaType: (_fieldName: string) => {
-      const isRequired = options?.validation?.isRequired
+      const validation = options?.validation
+      const db = options?.db
+      const isRequired = validation?.isRequired
+      const isNullable = db?.isNullable ?? !isRequired
       let modifiers = ''
 
       // Optional modifier
-      if (!isRequired) {
+      if (isNullable) {
         modifiers += '?'
       }
 
+      // Native type modifier (e.g., @db.Text)
+      if (db?.nativeType) {
+        modifiers += ` @db.${db.nativeType}`
+      }
+
       // Map modifier
-      if (options?.db?.map) {
-        modifiers += ` @map("${options.db.map}")`
+      if (db?.map) {
+        modifiers += ` @map("${db.map}")`
       }
 
       return {
         type: 'String',
-        modifiers: modifiers || undefined,
+        modifiers: modifiers.trimStart() || undefined,
       }
     },
     getTypeScriptType: () => {
@@ -718,6 +756,11 @@ export function password<TTypeInfo extends import('../config/types.js').TypeInfo
   }
 }
 
+/**
+ * Valid Prisma enum value pattern: starts with a letter, followed by letters, digits, or underscores
+ */
+const PRISMA_ENUM_VALUE_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/
+
 /**
  * Select field (enum-like)
  */
@@ -728,6 +771,20 @@ export function select<
     throw new Error('Select field must have at least one option')
   }
 
+  const isNativeEnum = options.db?.type === 'enum'
+
+  if (isNativeEnum) {
+    const invalidValues = options.options
+      .map((opt) => opt.value)
+      .filter((value) => !PRISMA_ENUM_VALUE_PATTERN.test(value))
+
+    if (invalidValues.length > 0) {
+      throw new Error(
+        `Enum select field values must be valid Prisma identifiers (letters, numbers, and underscores, starting with a letter). Invalid values: ${invalidValues.join(', ')}`,
+      )
+    }
+  }
+
   return {
     type: 'select',
     ...options,
@@ -743,10 +800,39 @@ export function select<
 
       return schema
     },
-    getPrismaType: (_fieldName: string) => {
+    getPrismaType: (fieldName: string, _provider?: string, listName?: string) => {
       const isRequired = options.validation?.isRequired
       let modifiers = ''
 
+      if (isNativeEnum) {
+        // Derive enum name from list name + field name in PascalCase
+        const capitalizedField = fieldName.charAt(0).toUpperCase() + fieldName.slice(1)
+        const enumName = listName ? `${listName}${capitalizedField}` : capitalizedField
+
+        // Required fields don't get the ? modifier
+        if (!isRequired) {
+          modifiers = '?'
+        }
+
+        // Add default value if provided (no quotes for enum values)
+        if (options.defaultValue !== undefined) {
+          modifiers = ` @default(${options.defaultValue})`
+        }
+
+        // Map modifier
+        if (options.db?.map) {
+          modifiers += ` @map("${options.db.map}")`
+        }
+
+        return {
+          type: enumName,
+          modifiers: modifiers || undefined,
+          enumValues: options.options.map((opt) => opt.value),
+        }
+      }
+
+      // String type (default)
+
       // Required fields don't get the ? modifier
       if (!isRequired) {
         modifiers = '?'
@@ -768,7 +854,7 @@ export function select<
       }
     },
     getTypeScriptType: () => {
-      // Generate union type from options
+      // Generate union type from options (same for both string and enum db types)
       const unionType = options.options.map((opt) => `'${opt.value}'`).join(' | ')
 
       return {
@@ -890,22 +976,30 @@ export function json<
       }
     },
     getPrismaType: (_fieldName: string) => {
-      const isRequired = options?.validation?.isRequired
+      const validation = options?.validation
+      const db = options?.db
+      const isRequired = validation?.isRequired
+      const isNullable = db?.isNullable ?? !isRequired
       let modifiers = ''
 
       // Optional modifier
-      if (!isRequired) {
+      if (isNullable) {
         modifiers += '?'
       }
 
+      // Native type modifier
+      if (db?.nativeType) {
+        modifiers += ` @db.${db.nativeType}`
+      }
+
       // Map modifier
-      if (options?.db?.map) {
-        modifiers += ` @map("${options.db.map}")`
+      if (db?.map) {
+        modifiers += ` @map("${db.map}")`
       }
 
       return {
         type: 'Json',
-        modifiers: modifiers || undefined,
+        modifiers: modifiers.trimStart() || undefined,
       }
     },
     getTypeScriptType: () => {