@opensaas/stack-core 0.1.0

package/src/fields/index.ts

@@ -0,0 +1,438 @@
+import { z } from 'zod'
+import type {
+  TextField,
+  IntegerField,
+  CheckboxField,
+  TimestampField,
+  PasswordField,
+  SelectField,
+  RelationshipField,
+} from '../config/types.js'
+import { hashPassword, isHashedPassword, HashedPassword } from '../utils/password.js'
+
+/**
+ * Format field name for display in error messages
+ */
+function formatFieldName(fieldName: string): string {
+  return fieldName
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, (str) => str.toUpperCase())
+    .trim()
+}
+
+/**
+ * Text field
+ */
+export function text(options?: Omit<TextField, 'type'>): TextField {
+  return {
+    type: 'text',
+    ...options,
+    getZodSchema: (fieldName: string, operation: 'create' | 'update') => {
+      const validation = options?.validation
+      const isRequired = validation?.isRequired
+      const length = validation?.length
+      const minLength = length?.min && length.min > 0 ? length.min : 1
+
+      const baseSchema = z.string({
+        message: `${formatFieldName(fieldName)} must be text`,
+      })
+
+      const withMin =
+        isRequired || length?.min !== undefined
+          ? baseSchema.min(minLength, {
+              message:
+                minLength > 1
+                  ? `${formatFieldName(fieldName)} must be at least ${minLength} characters`
+                  : `${formatFieldName(fieldName)} is required`,
+            })
+          : baseSchema
+
+      const withMax =
+        length?.max !== undefined
+          ? withMin.max(length.max, {
+              message: `${formatFieldName(fieldName)} must be at most ${length.max} characters`,
+            })
+          : withMin
+
+      if (isRequired && operation === 'update') {
+        return z.union([withMax, z.undefined()])
+      }
+
+      return !isRequired ? withMax.optional() : withMax
+    },
+    getPrismaType: () => {
+      const validation = options?.validation
+      const isRequired = validation?.isRequired
+      let modifiers = ''
+
+      // Optional modifier
+      if (!isRequired) {
+        modifiers += '?'
+      }
+
+      // Unique/index modifiers
+      if (options?.isIndexed === 'unique') {
+        modifiers += ' @unique'
+      } else if (options?.isIndexed === true) {
+        modifiers += ' @index'
+      }
+
+      return {
+        type: 'String',
+        modifiers: modifiers || undefined,
+      }
+    },
+    getTypeScriptType: () => {
+      const validation = options?.validation
+      const isRequired = validation?.isRequired
+
+      return {
+        type: 'string',
+        optional: !isRequired,
+      }
+    },
+  }
+}
+
+/**
+ * Integer field
+ */
+export function integer(options?: Omit<IntegerField, 'type'>): IntegerField {
+  return {
+    type: 'integer',
+    ...options,
+    getZodSchema: (fieldName: string, operation: 'create' | 'update') => {
+      const baseSchema = z.number({
+        message: `${formatFieldName(fieldName)} must be a number`,
+      })
+
+      const withMin =
+        options?.validation?.min !== undefined
+          ? baseSchema.min(options.validation.min, {
+              message: `${formatFieldName(fieldName)} must be at least ${options.validation.min}`,
+            })
+          : baseSchema
+
+      const withMax =
+        options?.validation?.max !== undefined
+          ? withMin.max(options.validation.max, {
+              message: `${formatFieldName(fieldName)} must be at most ${options.validation.max}`,
+            })
+          : withMin
+
+      return !options?.validation?.isRequired || operation === 'update'
+        ? withMax.optional()
+        : withMax
+    },
+    getPrismaType: () => {
+      const isRequired = options?.validation?.isRequired
+
+      return {
+        type: 'Int',
+        modifiers: isRequired ? undefined : '?',
+      }
+    },
+    getTypeScriptType: () => {
+      const isRequired = options?.validation?.isRequired
+
+      return {
+        type: 'number',
+        optional: !isRequired,
+      }
+    },
+  }
+}
+
+/**
+ * Checkbox (boolean) field
+ */
+export function checkbox(options?: Omit<CheckboxField, 'type'>): CheckboxField {
+  return {
+    type: 'checkbox',
+    ...options,
+    getZodSchema: () => {
+      return z.boolean().optional()
+    },
+    getPrismaType: () => {
+      const hasDefault = options?.defaultValue !== undefined
+      let modifiers = ''
+
+      if (hasDefault) {
+        modifiers = ` @default(${options.defaultValue})`
+      }
+
+      return {
+        type: 'Boolean',
+        modifiers: modifiers || undefined,
+      }
+    },
+    getTypeScriptType: () => {
+      return {
+        type: 'boolean',
+        optional: options?.defaultValue === undefined,
+      }
+    },
+  }
+}
+
+/**
+ * Timestamp (DateTime) field
+ */
+export function timestamp(options?: Omit<TimestampField, 'type'>): TimestampField {
+  return {
+    type: 'timestamp',
+    ...options,
+    getZodSchema: () => {
+      return z.union([z.date(), z.iso.datetime()]).optional()
+    },
+    getPrismaType: () => {
+      let modifiers = '?'
+
+      // Check for default value
+      if (
+        options?.defaultValue &&
+        typeof options.defaultValue === 'object' &&
+        'kind' in options.defaultValue &&
+        options.defaultValue.kind === 'now'
+      ) {
+        modifiers = ' @default(now())'
+      }
+
+      return {
+        type: 'DateTime',
+        modifiers,
+      }
+    },
+    getTypeScriptType: () => {
+      const hasDefault =
+        options?.defaultValue &&
+        typeof options.defaultValue === 'object' &&
+        'kind' in options.defaultValue &&
+        options.defaultValue.kind === 'now'
+
+      return {
+        type: 'Date',
+        optional: !hasDefault,
+      }
+    },
+  }
+}
+
+/**
+ * Password field (automatically hashed using bcrypt)
+ *
+ * **Security Features:**
+ * - Passwords are automatically hashed during create/update operations
+ * - Uses bcrypt with cost factor 10 (good balance of security and performance)
+ * - Already-hashed passwords are not re-hashed (idempotent)
+ * - Password values in query results include a `compare()` method for authentication
+ *
+ * **Usage Example:**
+ * ```typescript
+ * // In opensaas.config.ts
+ * fields: {
+ *   password: password({
+ *     validation: { isRequired: true }
+ *   })
+ * }
+ *
+ * // Creating a user - password is automatically hashed
+ * const user = await context.db.user.create({
+ *   data: {
+ *     email: 'user@example.com',
+ *     password: 'plaintextPassword' // Automatically hashed before storage
+ *   }
+ * })
+ *
+ * // Authenticating - use the compare() method
+ * const user = await context.db.user.findUnique({
+ *   where: { email: 'user@example.com' }
+ * })
+ *
+ * if (user && await user.password.compare('plaintextPassword')) {
+ *   // Password is correct - login successful
+ * }
+ * ```
+ *
+ * **Important Notes:**
+ * - Password fields are excluded from read operations by default in access control
+ * - Always use the `compare()` method to verify passwords - never compare strings directly
+ * - The password field value has type `HashedPassword` which extends string with compare()
+ * - Empty strings and undefined values are skipped (not hashed) to allow partial updates
+ *
+ * **Implementation Details:**
+ * - Uses field-level hooks (`resolveInput` and `resolveOutput`) for automatic transformations
+ * - The hashing happens via `hooks.resolveInput` during create/update operations
+ * - The wrapping happens via `hooks.resolveOutput` during read operations
+ * - This pattern allows third-party field types to define their own transformations
+ *
+ * @param options - Field configuration options
+ * @returns Password field configuration
+ */
+export function password(options?: Omit<PasswordField, 'type'>): PasswordField {
+  return {
+    type: 'password',
+    ...options,
+    typePatch: {
+      resultType: "import('@opensaas/stack-core').HashedPassword",
+      patchScope: 'scalars-only',
+    },
+    ui: {
+      ...options?.ui,
+      valueForClientSerialization: ({ value }) => ({ isSet: !!value }),
+    },
+    hooks: {
+      // Hash password before writing to database
+      resolveInput: async ({ inputValue }) => {
+        // Skip if undefined or null (allows partial updates)
+        if (inputValue === undefined || inputValue === null) {
+          return inputValue
+        }
+
+        // Skip if not a string
+        if (typeof inputValue !== 'string') {
+          return inputValue
+        }
+
+        // Skip empty strings (let validation handle this)
+        if (inputValue.length === 0) {
+          return inputValue
+        }
+
+        // Skip if already hashed (idempotent)
+        if (isHashedPassword(inputValue)) {
+          return inputValue
+        }
+
+        // Hash the password
+        return await hashPassword(inputValue)
+      },
+      // Wrap password with HashedPassword class after reading from database
+      resolveOutput: ({ value }) => {
+        // Only wrap string values (hashed passwords)
+        if (typeof value === 'string' && value.length > 0) {
+          return new HashedPassword(value)
+        }
+        return undefined
+      },
+      // Merge with user-provided hooks if any
+      ...options?.hooks,
+    },
+    getZodSchema: (fieldName: string, operation: 'create' | 'update') => {
+      const validation = options?.validation
+      const isRequired = validation?.isRequired
+
+      if (isRequired && operation === 'create') {
+        // Required in create mode: reject undefined and empty strings
+        return z
+          .string({
+            message: `${formatFieldName(fieldName)} must be text`,
+          })
+          .min(1, {
+            message: `${formatFieldName(fieldName)} is required`,
+          })
+      } else if (isRequired && operation === 'update') {
+        // Required in update mode: if provided, reject empty strings
+        return z.union([
+          z.string().min(1, {
+            message: `${formatFieldName(fieldName)} is required`,
+          }),
+          z.undefined(),
+        ])
+      } else {
+        // Not required: can be undefined or any string
+        return z
+          .string({
+            message: `${formatFieldName(fieldName)} must be text`,
+          })
+          .optional()
+      }
+    },
+    getPrismaType: () => {
+      const isRequired = options?.validation?.isRequired
+
+      return {
+        type: 'String',
+        modifiers: isRequired ? undefined : '?',
+      }
+    },
+    getTypeScriptType: () => {
+      const isRequired = options?.validation?.isRequired
+
+      return {
+        type: 'string',
+        optional: !isRequired,
+      }
+    },
+  }
+}
+
+/**
+ * Select field (enum-like)
+ */
+export function select(options: Omit<SelectField, 'type'>): SelectField {
+  if (!options.options || options.options.length === 0) {
+    throw new Error('Select field must have at least one option')
+  }
+
+  return {
+    type: 'select',
+    ...options,
+    getZodSchema: (fieldName: string, operation: 'create' | 'update') => {
+      const values = options.options.map((opt) => opt.value)
+      let schema: z.ZodTypeAny = z.enum(values as [string, ...string[]], {
+        message: `${formatFieldName(fieldName)} must be one of: ${values.join(', ')}`,
+      })
+
+      if (!options.validation?.isRequired || operation === 'update') {
+        schema = schema.optional()
+      }
+
+      return schema
+    },
+    getPrismaType: () => {
+      let modifiers = '?'
+
+      // Add default value if provided
+      if (options.defaultValue !== undefined) {
+        modifiers = ` @default("${options.defaultValue}")`
+      }
+
+      return {
+        type: 'String',
+        modifiers,
+      }
+    },
+    getTypeScriptType: () => {
+      // Generate union type from options
+      const unionType = options.options.map((opt) => `'${opt.value}'`).join(' | ')
+
+      return {
+        type: unionType,
+        optional: !options.validation?.isRequired || options.defaultValue !== undefined,
+      }
+    },
+  }
+}
+
+/**
+ * Relationship field
+ */
+export function relationship(options: Omit<RelationshipField, 'type'>): RelationshipField {
+  if (!options.ref) {
+    throw new Error('Relationship field must have a ref')
+  }
+
+  // Validate ref format: 'ListName.fieldName'
+  const refParts = options.ref.split('.')
+  if (refParts.length !== 2) {
+    throw new Error(
+      `Invalid relationship ref format: "${options.ref}". Expected format: "ListName.fieldName"`,
+    )
+  }
+
+  return {
+    type: 'relationship',
+    ...options,
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,132 @@
+import type { Hooks } from '../config/types.js'
+import type { AccessContext } from '../access/types.js'
+import type { FieldConfig } from '../config/types.js'
+import { validateWithZod } from '../validation/schema.js'
+
+/**
+ * Validation error collection
+ */
+export class ValidationError extends Error {
+  public errors: string[]
+  public fieldErrors: Record<string, string>
+
+  constructor(errors: string[], fieldErrors: Record<string, string> = {}) {
+    super(`Validation failed: ${errors.join(', ')}`)
+    this.name = 'ValidationError'
+    this.errors = errors
+    this.fieldErrors = fieldErrors
+  }
+}
+
+/**
+ * Execute resolveInput hook
+ * Allows modification of input data before validation
+ */
+export async function executeResolveInput<T = Record<string, unknown>>(
+  hooks: Hooks<T> | undefined,
+  args: {
+    operation: 'create' | 'update'
+    resolvedData: Partial<T>
+    item?: T
+    context: AccessContext
+  },
+): Promise<Partial<T>> {
+  if (!hooks?.resolveInput) {
+    return args.resolvedData
+  }
+
+  const result = await hooks.resolveInput(args)
+  return result
+}
+
+/**
+ * Execute validateInput hook
+ * Allows custom validation logic
+ */
+export async function executeValidateInput<T = Record<string, unknown>>(
+  hooks: Hooks<T> | undefined,
+  args: {
+    operation: 'create' | 'update'
+    resolvedData: Partial<T>
+    item?: T
+    context: AccessContext
+  },
+): Promise<void> {
+  if (!hooks?.validateInput) {
+    return
+  }
+
+  const errors: string[] = []
+
+  const addValidationError = (msg: string) => {
+    errors.push(msg)
+  }
+
+  await hooks.validateInput({
+    ...args,
+    addValidationError,
+  })
+
+  if (errors.length > 0) {
+    throw new ValidationError(errors)
+  }
+}
+
+/**
+ * Execute beforeOperation hook
+ * Runs before database operation (cannot modify data)
+ */
+export async function executeBeforeOperation<T = Record<string, unknown>>(
+  hooks: Hooks<T> | undefined,
+  args: {
+    operation: 'create' | 'update' | 'delete'
+    item?: T
+    context: AccessContext
+  },
+): Promise<void> {
+  if (!hooks?.beforeOperation) {
+    return
+  }
+
+  await hooks.beforeOperation(args)
+}
+
+/**
+ * Execute afterOperation hook
+ * Runs after database operation
+ */
+export async function executeAfterOperation<T = Record<string, unknown>>(
+  hooks: Hooks<T> | undefined,
+  args: {
+    operation: 'create' | 'update' | 'delete'
+    item: T
+    context: AccessContext
+  },
+): Promise<void> {
+  if (!hooks?.afterOperation) {
+    return
+  }
+
+  await hooks.afterOperation(args)
+}
+
+/**
+ * Validate field-level validation rules using Zod
+ * Checks isRequired, length constraints, etc.
+ */
+export function validateFieldRules(
+  data: Record<string, unknown>,
+  fieldConfigs: Record<string, FieldConfig>,
+  operation: 'create' | 'update' = 'create',
+): { errors: string[]; fieldErrors: Record<string, string> } {
+  const result = validateWithZod(data, fieldConfigs, operation)
+
+  if (result.success) {
+    return { errors: [], fieldErrors: {} }
+  }
+
+  // Convert field errors to array of error messages
+  const errors = Object.entries(result.errors).map(([_field, message]) => message)
+
+  return { errors, fieldErrors: result.errors }
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+// Config system
+export { config, list } from './config/index.js'
+export type {
+  OpenSaasConfig,
+  ListConfig,
+  FieldConfig,
+  BaseFieldConfig,
+  TextField,
+  IntegerField,
+  CheckboxField,
+  TimestampField,
+  PasswordField,
+  SelectField,
+  RelationshipField,
+  OperationAccess,
+  Hooks,
+  FieldHooks,
+  DatabaseConfig,
+  SessionConfig,
+  UIConfig,
+  ThemeConfig,
+  ThemePreset,
+  ThemeColors,
+} from './config/index.js'
+
+// Access control
+export type {
+  AccessControl,
+  FieldAccess,
+  Session,
+  AccessContext,
+  PrismaFilter,
+  AccessControlledDB,
+} from './access/index.js'
+
+// Context
+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'
+
+// Hooks and validation
+export { ValidationError } from './hooks/index.js'
+export { validateWithZod, generateZodSchema } from './validation/schema.js'
+
+// Password utilities
+export {
+  hashPassword,
+  comparePassword,
+  isHashedPassword,
+  HashedPassword,
+} from './utils/password.js'