sovrium 0.0.2

package/src/infrastructure/database/sql/sql-check-constraints.ts

@@ -0,0 +1,252 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { escapeSqlString } from './sql-utils'
+import type { Fields } from '@/domain/models/app/table/fields'
+
+/**
+ * Generate CHECK constraints for array fields with maxItems
+ */
+export const generateArrayConstraints = (fields: readonly Fields[number][]): readonly string[] =>
+  fields
+    .filter(
+      (field): field is Fields[number] & { type: 'array'; maxItems: number } =>
+        field.type === 'array' && 'maxItems' in field && typeof field.maxItems === 'number'
+    )
+    .map(
+      (field) =>
+        `CONSTRAINT check_${field.name}_max_items CHECK (array_length(${field.name}, 1) IS NULL OR array_length(${field.name}, 1) <= ${field.maxItems})`
+    )
+
+/**
+ * Generate CHECK constraints for multiple-attachments fields with maxFiles
+ */
+export const generateMultipleAttachmentsConstraints = (
+  fields: readonly Fields[number][]
+): readonly string[] =>
+  fields
+    .filter(
+      (field): field is Fields[number] & { type: 'multiple-attachments'; maxFiles: number } =>
+        field.type === 'multiple-attachments' &&
+        'maxFiles' in field &&
+        typeof field.maxFiles === 'number'
+    )
+    .map(
+      (field) =>
+        `CONSTRAINT check_${field.name}_max_files CHECK (jsonb_array_length(${field.name}) IS NULL OR jsonb_array_length(${field.name}) <= ${field.maxFiles})`
+    )
+
+/**
+ * Generate CHECK constraints for numeric fields with min/max values
+ * Supports: integer, decimal, currency, percentage, rating
+ */
+export const generateNumericConstraints = (fields: readonly Fields[number][]): readonly string[] =>
+  fields
+    .filter(
+      (
+        field
+      ): field is Fields[number] & {
+        type: 'integer' | 'decimal' | 'currency' | 'percentage' | 'rating'
+      } =>
+        (field.type === 'integer' ||
+          field.type === 'decimal' ||
+          field.type === 'currency' ||
+          field.type === 'percentage' ||
+          field.type === 'rating') &&
+        (('min' in field && typeof field.min === 'number') ||
+          ('max' in field && typeof field.max === 'number'))
+    )
+    .map((field) => {
+      const hasMin = 'min' in field && typeof field.min === 'number'
+      const hasMax = 'max' in field && typeof field.max === 'number'
+
+      // Rating fields always have a minimum of 1 (ratings start from 1, not 0)
+      const effectiveMin = field.type === 'rating' && !hasMin ? 1 : hasMin ? field.min : undefined
+
+      const conditions = [
+        ...(effectiveMin !== undefined ? [`${field.name} >= ${effectiveMin}`] : []),
+        ...(hasMax ? [`${field.name} <= ${field.max}`] : []),
+      ]
+
+      const constraintName = `check_${field.name}_range`
+      const constraintCondition = conditions.join(' AND ')
+      return `CONSTRAINT ${constraintName} CHECK (${constraintCondition})`
+    })
+
+/**
+ * Generate CHECK constraints for progress fields (automatic 0-100 range)
+ */
+export const generateProgressConstraints = (fields: readonly Fields[number][]): readonly string[] =>
+  fields
+    .filter((field): field is Fields[number] & { type: 'progress' } => field.type === 'progress')
+    .map((field) => {
+      const constraintName = `check_${field.name}_range`
+      return `CONSTRAINT ${constraintName} CHECK (${field.name} >= 0 AND ${field.name} <= 100)`
+    })
+
+/**
+ * Extract string values from field options
+ * Handles both simple string arrays (single-select) and object arrays with value property (status)
+ */
+const extractOptionValues = (
+  field: Fields[number]
+): readonly string[] | readonly { value: string }[] => {
+  if ('options' in field && Array.isArray(field.options)) {
+    return field.options as readonly string[] | readonly { value: string }[]
+  }
+  return []
+}
+
+/**
+ * Generate CHECK constraint for enum-based fields (single-select, status)
+ *
+ * SECURITY NOTE: Options come from validated Effect Schema (SingleSelectFieldSchema, StatusFieldSchema).
+ * We escape single quotes to prevent SQL injection following defense-in-depth security principles.
+ *
+ * DRY PRINCIPLE: This function consolidates enum constraint generation for both single-select
+ * (simple string options) and status (object options with value property) field types.
+ */
+const generateEnumCheckConstraint = (
+  field: Fields[number] & { readonly options: readonly unknown[] }
+): string => {
+  const options = extractOptionValues(field)
+  const values = options
+    .map((opt) => {
+      const value = typeof opt === 'string' ? opt : (opt as { value: string }).value
+      return `'${escapeSqlString(value)}'`
+    })
+    .join(', ')
+  const constraintName = `check_${field.name}_enum`
+  return `CONSTRAINT ${constraintName} CHECK (${field.name} IN (${values}))`
+}
+
+/**
+ * Generate CHECK constraints for single-select fields with enum options
+ */
+export const generateEnumConstraints = (fields: readonly Fields[number][]): readonly string[] =>
+  fields
+    .filter(
+      (field): field is Fields[number] & { type: 'single-select'; options: readonly string[] } =>
+        field.type === 'single-select' && 'options' in field && Array.isArray(field.options)
+    )
+    .map(generateEnumCheckConstraint)
+
+/**
+ * Generate CHECK constraints for status fields with status options
+ */
+export const generateStatusConstraints = (fields: readonly Fields[number][]): readonly string[] =>
+  fields
+    .filter(
+      (
+        field
+      ): field is Fields[number] & {
+        type: 'status'
+        options: readonly { value: string; color?: string }[]
+      } => field.type === 'status' && 'options' in field && Array.isArray(field.options)
+    )
+    .map(generateEnumCheckConstraint)
+
+/**
+ * Generate CHECK constraints for rich-text fields with maxLength
+ */
+export const generateRichTextConstraints = (fields: readonly Fields[number][]): readonly string[] =>
+  fields
+    .filter(
+      (field): field is Fields[number] & { type: 'rich-text'; maxLength: number } =>
+        field.type === 'rich-text' && 'maxLength' in field && typeof field.maxLength === 'number'
+    )
+    .map((field) => {
+      const constraintName = `check_${field.name}_max_length`
+      return `CONSTRAINT ${constraintName} CHECK (LENGTH(${field.name}) <= ${field.maxLength})`
+    })
+
+/**
+ * Barcode format validation patterns
+ * Uses PostgreSQL regex patterns to validate barcode formats
+ */
+const barcodeFormatPatterns: Record<string, string> = {
+  'EAN-13': '^[0-9]{13}$',
+  'EAN-8': '^[0-9]{8}$',
+  'UPC-A': '^[0-9]{12}$',
+  'UPC-E': '^[0-9]{6,8}$',
+  'CODE-128': '^[\\x00-\\x7F]+$',
+  'CODE-39': '^[A-Z0-9\\-\\.\\$\\/\\+\\%\\ ]+$',
+}
+
+/**
+ * Generate CHECK constraints for barcode fields with format validation
+ */
+export const generateBarcodeConstraints = (fields: readonly Fields[number][]): readonly string[] =>
+  fields
+    .filter(
+      (field): field is Fields[number] & { type: 'barcode'; format: string } =>
+        field.type === 'barcode' && 'format' in field && typeof field.format === 'string'
+    )
+    .map((field) => {
+      const pattern = barcodeFormatPatterns[field.format]
+      if (!pattern) {
+        return ''
+      }
+      const constraintName = `check_${field.name}_format`
+      return `CONSTRAINT ${constraintName} CHECK (${field.name} ~ '${pattern}')`
+    })
+    .filter((constraint) => constraint !== '')
+
+/**
+ * Generate CHECK constraints for color fields with hex color format validation
+ */
+export const generateColorConstraints = (fields: readonly Fields[number][]): readonly string[] =>
+  fields
+    .filter((field): field is Fields[number] & { type: 'color' } => field.type === 'color')
+    .map((field) => {
+      const constraintName = `check_${field.name}_format`
+      return `CONSTRAINT ${constraintName} CHECK (${field.name} ~ '^#[0-9a-fA-F]{6}$')`
+    })
+
+/**
+ * Generate CHECK constraints for multi-select fields with options
+ * Validates that all selected values are from the predefined options list
+ * Uses PostgreSQL <@ (contained by) operator for array validation
+ *
+ * @example
+ * Field: { type: 'multi-select', options: ['work', 'personal'] }
+ * Constraint: CHECK (tags <@ ARRAY['work', 'personal']::text[])
+ */
+export const generateMultiSelectConstraints = (
+  fields: readonly Fields[number][]
+): readonly string[] =>
+  fields
+    .filter(
+      (field): field is Fields[number] & { type: 'multi-select'; options: readonly string[] } =>
+        field.type === 'multi-select' && 'options' in field && Array.isArray(field.options)
+    )
+    .map((field) => {
+      const escapedOptions = field.options.map((opt) => `'${escapeSqlString(opt)}'`).join(', ')
+      const constraintName = `check_${field.name}_options`
+      return `CONSTRAINT ${constraintName} CHECK (${field.name} <@ ARRAY[${escapedOptions}]::text[])`
+    })
+
+/**
+ * Generate custom CHECK constraints defined at table level
+ *
+ * Used for complex business rules that involve multiple fields or
+ * conditional validation beyond field-level constraints.
+ *
+ * @example
+ * ```typescript
+ * const constraints = [{
+ *   name: 'chk_active_members_have_email',
+ *   check: '(is_active = false) OR (email IS NOT NULL)'
+ * }]
+ * ```
+ */
+export const generateCustomCheckConstraints = (
+  constraints?: readonly { readonly name: string; readonly check: string }[]
+): readonly string[] =>
+  constraints
+    ? constraints.map((constraint) => `CONSTRAINT ${constraint.name} CHECK (${constraint.check})`)
+    : []

package/src/infrastructure/database/sql/sql-column-generators.ts

@@ -0,0 +1,174 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import {
+  isFormulaVolatile,
+  isFormulaReturningArray,
+  translateFormulaToPostgres,
+} from '../formula/formula-utils'
+import { isAutoTimestampField, isFieldNotNull, shouldUseSerial } from './sql-field-predicates'
+import { mapFieldTypeToPostgres, mapFormulaResultTypeToPostgres } from './sql-type-mappings'
+import { escapeSqlString } from './sql-utils'
+import type { Fields } from '@/domain/models/app/table/fields'
+
+/**
+ * Format default value for SQL
+ * Numbers and booleans are unquoted, strings are quoted and escaped
+ */
+const formatDefaultValue = (defaultValue: unknown): string => {
+  if (typeof defaultValue === 'boolean') {
+    return String(defaultValue)
+  }
+  if (typeof defaultValue === 'number') {
+    return String(defaultValue)
+  }
+  return `'${escapeSqlString(String(defaultValue))}'`
+}
+
+/**
+ * Generate SERIAL column definition for auto-increment fields
+ * When isPrimaryKey is true and it's a single-field PK, add PRIMARY KEY inline for better PostgreSQL constraint recognition
+ */
+const generateSerialColumn = (fieldName: string, isPrimaryKey: boolean = false): string =>
+  isPrimaryKey ? `${fieldName} SERIAL PRIMARY KEY` : `${fieldName} SERIAL NOT NULL`
+
+/**
+ * Generate NOT NULL constraint
+ */
+const generateNotNullConstraint = (
+  field: Fields[number],
+  isPrimaryKey: boolean,
+  hasAuthConfig: boolean = true
+): string => {
+  return isFieldNotNull(field, isPrimaryKey, hasAuthConfig) ? ' NOT NULL' : ''
+}
+
+/**
+ * Format array default value as PostgreSQL ARRAY literal
+ */
+const formatArrayDefault = (defaultValue: readonly unknown[]): string => {
+  const arrayValues = defaultValue.map((val) => `'${escapeSqlString(String(val))}'`).join(', ')
+  return ` DEFAULT ARRAY[${arrayValues}]`
+}
+
+/**
+ * Format special default values (PostgreSQL functions, INTERVAL, etc.)
+ */
+const formatSpecialDefault = (field: Fields[number], defaultValue: unknown): string | undefined => {
+  // PostgreSQL functions like CURRENT_DATE, NOW() should not be quoted
+  if (typeof defaultValue === 'string' && defaultValue.toUpperCase() === 'CURRENT_DATE') {
+    return ' DEFAULT CURRENT_DATE'
+  }
+  if (typeof defaultValue === 'string' && defaultValue.toUpperCase() === 'NOW()') {
+    return ' DEFAULT NOW()'
+  }
+  // Duration fields: convert seconds to INTERVAL
+  if (field.type === 'duration' && typeof defaultValue === 'number') {
+    return ` DEFAULT INTERVAL '${defaultValue} seconds'`
+  }
+  // Array fields (multi-select): convert to PostgreSQL array literal
+  if (Array.isArray(defaultValue)) {
+    return formatArrayDefault(defaultValue)
+  }
+  return undefined
+}
+
+/**
+ * Generate DEFAULT clause
+ */
+const generateDefaultClause = (field: Fields[number]): string => {
+  // Auto-timestamp fields get CURRENT_TIMESTAMP default (PostgreSQL function for current timestamp)
+  if (isAutoTimestampField(field)) {
+    return ' DEFAULT CURRENT_TIMESTAMP'
+  }
+
+  // Progress fields with required=true get DEFAULT 0 automatically
+  if (field.type === 'progress' && field.required === true && !('default' in field)) {
+    return ' DEFAULT 0'
+  }
+
+  // Explicit default values
+  if ('default' in field && field.default !== undefined) {
+    const defaultValue = field.default
+    const specialDefault = formatSpecialDefault(field, defaultValue)
+    if (specialDefault) {
+      return specialDefault
+    }
+    return ` DEFAULT ${formatDefaultValue(defaultValue)}`
+  }
+
+  return ''
+}
+
+/**
+ * Generate formula column definition (GENERATED ALWAYS AS or trigger-based)
+ *
+ * NOTE: Formula fields with volatile functions (CURRENT_DATE, NOW(), etc.) cannot use
+ * GENERATED ALWAYS AS because PostgreSQL requires generated columns to be immutable.
+ * For volatile formulas, we create regular columns and handle computation via triggers.
+ */
+const generateFormulaColumn = (
+  field: Fields[number] & { readonly type: 'formula'; readonly formula: string },
+  allFields?: readonly Fields[number][]
+): string => {
+  const baseResultType =
+    'resultType' in field && field.resultType
+      ? mapFormulaResultTypeToPostgres(field.resultType)
+      : 'TEXT'
+
+  // Auto-detect array return type for functions like STRING_TO_ARRAY
+  // If formula returns an array but resultType doesn't specify array, append []
+  const resultType =
+    isFormulaReturningArray(field.formula) && !baseResultType.endsWith('[]')
+      ? `${baseResultType}[]`
+      : baseResultType
+
+  // Translate formula to PostgreSQL syntax with field type context
+  // Note: translateFormulaToPostgres handles ROUND with double precision by casting to NUMERIC
+  // and converts date::TEXT to TO_CHAR(date, 'format') which is STABLE (not IMMUTABLE)
+  const translatedFormula = translateFormulaToPostgres(field.formula, allFields)
+
+  // Volatile formulas (contain CURRENT_DATE, NOW(), etc.) need trigger-based computation
+  // because PostgreSQL GENERATED columns must be immutable
+  // Check volatility on TRANSLATED formula since date::TEXT becomes TO_CHAR (STABLE)
+  if (isFormulaVolatile(translatedFormula)) {
+    // Create regular column - trigger will populate it
+    return `${field.name} ${resultType}`
+  }
+
+  // Immutable formulas can use GENERATED ALWAYS AS
+  return `${field.name} ${resultType} GENERATED ALWAYS AS (${translatedFormula}) STORED`
+}
+
+/**
+ * Generate column definition with constraints
+ *
+ * NOTE: UNIQUE constraints are NOT generated inline. Named UNIQUE constraints
+ * are generated at the table level via generateUniqueConstraints() to ensure
+ * they appear in information_schema.table_constraints with queryable constraint names.
+ */
+export const generateColumnDefinition = (
+  field: Fields[number],
+  isPrimaryKey: boolean,
+  allFields?: readonly Fields[number][],
+  hasAuthConfig: boolean = true
+): string => {
+  // SERIAL columns for auto-increment fields
+  if (shouldUseSerial(field, isPrimaryKey)) {
+    return generateSerialColumn(field.name, isPrimaryKey)
+  }
+
+  // Formula fields: check if formula is volatile
+  if (field.type === 'formula' && 'formula' in field && field.formula) {
+    return generateFormulaColumn(field, allFields)
+  }
+
+  const columnType = mapFieldTypeToPostgres(field)
+  const notNull = generateNotNullConstraint(field, isPrimaryKey, hasAuthConfig)
+  const defaultValue = generateDefaultClause(field)
+  return `${field.name} ${columnType}${notNull}${defaultValue}`
+}

package/src/infrastructure/database/sql/sql-execution.ts

@@ -0,0 +1,245 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Data, Effect } from 'effect'
+
+/**
+ * Type definition for a database transaction that can execute raw SQL
+ */
+export interface TransactionLike {
+  readonly unsafe: (sql: string) => Promise<readonly unknown[]>
+}
+
+/**
+ * Error type for SQL execution failures
+ */
+export class SQLExecutionError extends Data.TaggedError('SQLExecutionError')<{
+  readonly message: string
+  readonly sql?: string
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Type definition for information_schema.columns row
+ */
+export interface ColumnInfo {
+  readonly column_name: string
+  readonly data_type: string
+  readonly is_nullable: string
+  readonly column_default: string | null
+}
+
+/**
+ * Type definition for table existence query result
+ */
+interface TableExistsResult {
+  readonly exists: boolean
+}
+
+/**
+ * Type definition for table name query result
+ */
+interface TableNameResult {
+  readonly tablename: string
+}
+
+/**
+ * Type definition for view name query result
+ */
+interface ViewNameResult {
+  readonly viewname: string
+}
+
+/**
+ * Type definition for materialized view name query result
+ */
+interface MatViewNameResult {
+  readonly matviewname: string
+}
+
+// ============================================================================
+// SQL Statement Execution Helpers
+// ============================================================================
+
+/**
+ * Execute a single SQL statement within an Effect context
+ *
+ * SECURITY NOTE: This function uses tx.unsafe() which is intentional for DDL execution.
+ * See schema-initializer.ts for detailed security rationale.
+ */
+export const executeSQL = (
+  tx: TransactionLike,
+  sql: string
+): Effect.Effect<readonly unknown[], SQLExecutionError> =>
+  Effect.tryPromise({
+    try: () => tx.unsafe(sql),
+    catch: (error) =>
+      new SQLExecutionError({
+        message: `SQL execution failed: ${String(error)}`,
+        sql,
+        cause: error,
+      }),
+  })
+
+/**
+ * Execute multiple SQL statements sequentially
+ * Use this when statements must be executed in order (e.g., DDL that depends on previous statements)
+ */
+/* eslint-disable functional/no-loop-statements */
+export const executeSQLStatements = (
+  tx: TransactionLike,
+  statements: readonly string[]
+): Effect.Effect<void, SQLExecutionError> =>
+  statements.length === 0
+    ? Effect.void
+    : Effect.gen(function* () {
+        for (const sql of statements) {
+          yield* executeSQL(tx, sql)
+        }
+      })
+/* eslint-enable functional/no-loop-statements */
+
+/**
+ * Execute multiple SQL statements in parallel
+ * Use this when statements are independent (e.g., DROP VIEW statements, index creation)
+ *
+ * Note: PostgreSQL allows concurrent DDL operations within a transaction,
+ * but some operations may still serialize at the database level.
+ */
+export const executeSQLStatementsParallel = (
+  tx: TransactionLike,
+  statements: readonly string[]
+): Effect.Effect<void, SQLExecutionError> =>
+  statements.length === 0
+    ? Effect.void
+    : Effect.all(
+        statements.map((sql) => executeSQL(tx, sql)),
+        { concurrency: 'unbounded' }
+      ).pipe(Effect.asVoid)
+
+// ============================================================================
+// Information Schema Query Helpers
+// ============================================================================
+
+/**
+ * Check if a table exists in the database
+ *
+ * SECURITY NOTE: String interpolation is used for tableName.
+ * This is SAFE because:
+ * 1. tableName comes from validated Effect Schema (Table.name field)
+ * 2. Table names are defined in schema configuration, not user input
+ * 3. The App schema is validated before reaching this code
+ * 4. information_schema queries are read-only (no data modification risk)
+ */
+export const tableExists = (
+  tx: TransactionLike,
+  tableName: string
+): Effect.Effect<boolean, SQLExecutionError> =>
+  executeSQL(
+    tx,
+    `
+    SELECT EXISTS (
+      SELECT 1
+      FROM information_schema.tables
+      WHERE table_name = '${tableName}'
+        AND table_schema = 'public'
+    ) as exists
+  `
+  ).pipe(Effect.map((result) => (result as readonly TableExistsResult[])[0]?.exists ?? false))
+
+/**
+ * Get existing columns from a table
+ *
+ * SECURITY NOTE: String interpolation is used for tableName.
+ * This is SAFE because tableName comes from validated schema configuration.
+ */
+export const getExistingColumns = (
+  tx: TransactionLike,
+  tableName: string
+): Effect.Effect<
+  ReadonlyMap<string, { dataType: string; isNullable: string; columnDefault: string | null }>,
+  SQLExecutionError
+> =>
+  executeSQL(
+    tx,
+    `
+    SELECT column_name, data_type, is_nullable, column_default
+    FROM information_schema.columns
+    WHERE table_name = '${tableName}'
+      AND table_schema = 'public'
+  `
+  ).pipe(
+    Effect.map((result) => {
+      const rows = result as readonly ColumnInfo[]
+      return new Map(
+        rows.map((row) => [
+          row.column_name,
+          {
+            dataType: row.data_type,
+            isNullable: row.is_nullable,
+            columnDefault: row.column_default,
+          },
+        ])
+      )
+    })
+  )
+
+/**
+ * Get all existing table names in the public schema
+ *
+ * SECURITY NOTE: This query is read-only and uses pg_tables system catalog.
+ * No user input is involved.
+ */
+export const getExistingTableNames = (
+  tx: TransactionLike
+): Effect.Effect<readonly string[], SQLExecutionError> =>
+  executeSQL(
+    tx,
+    `
+    SELECT tablename
+    FROM pg_tables
+    WHERE schemaname = 'public'
+  `
+  ).pipe(Effect.map((result) => (result as readonly TableNameResult[]).map((row) => row.tablename)))
+
+/**
+ * Get all existing view names in the public schema
+ *
+ * SECURITY NOTE: This query is read-only and uses pg_views system catalog.
+ * No user input is involved.
+ */
+export const getExistingViews = (
+  tx: TransactionLike
+): Effect.Effect<readonly string[], SQLExecutionError> =>
+  executeSQL(
+    tx,
+    `
+    SELECT viewname
+    FROM pg_views
+    WHERE schemaname = 'public'
+  `
+  ).pipe(Effect.map((result) => (result as readonly ViewNameResult[]).map((row) => row.viewname)))
+
+/**
+ * Get all existing materialized view names in the public schema
+ *
+ * SECURITY NOTE: This query is read-only and uses pg_matviews system catalog.
+ * No user input is involved.
+ */
+export const getExistingMaterializedViews = (
+  tx: TransactionLike
+): Effect.Effect<readonly string[], SQLExecutionError> =>
+  executeSQL(
+    tx,
+    `
+    SELECT matviewname
+    FROM pg_matviews
+    WHERE schemaname = 'public'
+  `
+  ).pipe(
+    Effect.map((result) => (result as readonly MatViewNameResult[]).map((row) => row.matviewname))
+  )