sovrium 0.0.2

package/src/infrastructure/database/field-utils.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 type { Fields } from '@/domain/models/app/table/fields'
+
+/**
+ * Check if field is a many-to-many relationship
+ * Many-to-many relationships don't create columns in the table, they use junction tables instead
+ */
+export const isManyToManyRelationship = (
+  field: Fields[number]
+): field is Fields[number] & {
+  type: 'relationship'
+  relatedTable: string
+  relationType: 'many-to-many'
+} =>
+  field.type === 'relationship' &&
+  'relatedTable' in field &&
+  typeof field.relatedTable === 'string' &&
+  'relationType' in field &&
+  field.relationType === 'many-to-many'
+
+/**
+ * Check if field should create a database column
+ *
+ * Some field types are UI-only and don't need database columns:
+ * - button: UI-only action field (no data stored)
+ * - count: Virtual/computed field (calculated from relationships)
+ * - relationship with relationType='one-to-many': Foreign key is in the related table, not this table
+ * - relationship with relationType='many-to-many': Uses junction table, no column in this table
+ *
+ * This utility is used by:
+ * - table-operations.ts: CREATE TABLE generation
+ * - schema-migration-helpers.ts: ALTER TABLE generation
+ *
+ * @param field - Field configuration from table schema
+ * @returns true if field needs a database column, false if UI-only/virtual
+ */
+export const shouldCreateDatabaseColumn = (field: Fields[number]): boolean => {
+  if (field.type === 'button' || field.type === 'count') {
+    return false
+  }
+
+  // For one-to-many relationships, the foreign key is in the related table, not this table
+  if (
+    field.type === 'relationship' &&
+    'relationType' in field &&
+    field.relationType === 'one-to-many'
+  ) {
+    return false
+  }
+
+  // For many-to-many relationships, use junction table instead of column
+  if (isManyToManyRelationship(field)) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Sanitize table name for PostgreSQL identifier
+ *
+ * Converts table names from user-friendly format to PostgreSQL-safe identifiers:
+ * - Converts to lowercase
+ * - Replaces spaces with underscores
+ * - Removes special characters
+ * - Ensures result matches pattern ^[a-z_]+$
+ *
+ * Examples:
+ * - "My Projects" → "my_projects"
+ * - "User-Data" → "user_data"
+ * - "Sales 2024" → "sales_2024"
+ *
+ * @param tableName - User-provided table name from schema
+ * @returns Sanitized table name safe for PostgreSQL
+ */
+export const sanitizeTableName = (tableName: string): string =>
+  tableName
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '')

package/src/infrastructure/database/filter-operators.ts

@@ -0,0 +1,136 @@
+/**
+ * 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 { formatSqlValue, formatLikePattern, escapeSqlString } from './sql/sql-utils'
+
+/**
+ * SQL operator mapping for comparison operators
+ * Maps domain filter operators to SQL comparison operators
+ */
+export const SQL_OPERATOR_MAP: Record<string, string> = {
+  equals: '=',
+  notEquals: '!=',
+  greaterThan: '>',
+  lessThan: '<',
+  greaterThanOrEqual: '>=',
+  lessThanOrEqual: '<=',
+}
+
+/**
+ * Handle LIKE pattern operators (contains, startsWith, endsWith)
+ */
+const handlePatternOperator = (
+  field: string,
+  operator: string,
+  value: unknown
+): string | undefined => {
+  if (operator === 'contains' || operator === 'startsWith' || operator === 'endsWith') {
+    return `${field} LIKE ${formatLikePattern(value, operator)}`
+  }
+  return undefined
+}
+
+/**
+ * Handle NULL check operators (isNull, isNotNull, isEmpty)
+ */
+const handleNullOperator = (field: string, operator: string): string | undefined => {
+  if (operator === 'isNull') {
+    return `${field} IS NULL`
+  }
+  if (operator === 'isNotNull') {
+    return `${field} IS NOT NULL`
+  }
+  if (operator === 'isEmpty') {
+    return `(${field} IS NULL OR ${field} = '')`
+  }
+  return undefined
+}
+
+/**
+ * Handle boolean operators (isTrue, isFalse)
+ */
+const handleBooleanOperator = (field: string, operator: string): string | undefined => {
+  if (operator === 'isTrue') {
+    return `${field} = true`
+  }
+  if (operator === 'isFalse') {
+    return `${field} = false`
+  }
+  return undefined
+}
+
+/**
+ * Handle IN operator (field matches any value in array)
+ */
+const handleInOperator = (field: string, operator: string, value: unknown): string | undefined => {
+  if (operator === 'in') {
+    if (!Array.isArray(value)) {
+      return undefined
+    }
+    // Format each value in the array immutably
+    const formattedValues = value.map((v) => formatSqlValue(v))
+    return `${field} IN (${formattedValues.join(', ')})`
+  }
+  return undefined
+}
+
+/**
+ * Format value based on options
+ */
+const formatValue = (value: unknown, useEscapeSqlString: boolean): string => {
+  if (useEscapeSqlString && typeof value === 'string') {
+    return `'${escapeSqlString(value)}'`
+  }
+  return formatSqlValue(value)
+}
+
+/**
+ * Generate SQL condition from filter operator and value
+ * Handles both simple operators (equals, greaterThan, etc.) and pattern matching (contains, startsWith, etc.)
+ *
+ * @param field - Column name or expression
+ * @param operator - Filter operator (equals, greaterThan, contains, etc.)
+ * @param value - Filter value
+ * @param options - Optional configuration
+ * @param options.useEscapeSqlString - Use escapeSqlString instead of formatSqlValue for string values (for manual string formatting)
+ * @returns SQL condition string
+ */
+export const generateSqlCondition = (
+  field: string,
+  operator: string,
+  value: unknown,
+  options: { readonly useEscapeSqlString?: boolean } = {}
+): string => {
+  const useEscapeSqlString = options.useEscapeSqlString ?? false
+
+  // Handle LIKE pattern operators
+  const patternCondition = handlePatternOperator(field, operator, value)
+  if (patternCondition) return patternCondition
+
+  // Handle NULL operators
+  const nullCondition = handleNullOperator(field, operator)
+  if (nullCondition) return nullCondition
+
+  // Handle boolean operators
+  const booleanCondition = handleBooleanOperator(field, operator)
+  if (booleanCondition) return booleanCondition
+
+  // Handle IN operator
+  const inCondition = handleInOperator(field, operator, value)
+  if (inCondition) return inCondition
+
+  // Handle comparison operators
+  const sqlOperator = SQL_OPERATOR_MAP[operator]
+  if (sqlOperator) {
+    const formattedValue = formatValue(value, useEscapeSqlString)
+    return `${field} ${sqlOperator} ${formattedValue}`
+  }
+
+  // Fallback to equals if operator not recognized
+  const formattedValue = formatValue(value, useEscapeSqlString)
+  return `${field} = ${formattedValue}`
+}

package/src/infrastructure/database/formula/formula-trigger-generators.ts

@@ -0,0 +1,114 @@
+/**
+ * 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,
+  qualifyColumnReferences,
+  translateFormulaToPostgres,
+} from './formula-utils'
+import type { Fields } from '@/domain/models/app/table/fields'
+
+/**
+ * Type for formula fields with volatile functions
+ */
+type VolatileFormulaField = Fields[number] & { readonly type: 'formula'; readonly formula: string }
+
+/**
+ * Get formula fields that contain volatile functions
+ * These fields need trigger-based computation instead of GENERATED ALWAYS AS
+ *
+ * IMPORTANT: Check volatility on TRANSLATED formula because date::TEXT becomes
+ * TO_CHAR(date, 'format') which is STABLE, not IMMUTABLE.
+ */
+const getVolatileFormulaFields = (
+  fields: readonly Fields[number][]
+): readonly VolatileFormulaField[] =>
+  fields.filter((field): field is VolatileFormulaField => {
+    if (field.type !== 'formula' || !('formula' in field) || typeof field.formula !== 'string') {
+      return false
+    }
+    // Translate formula first, then check volatility
+    const translatedFormula = translateFormulaToPostgres(field.formula, fields)
+    return isFormulaVolatile(translatedFormula)
+  })
+
+/**
+ * Generate trigger function for volatile formula computation
+ * Creates a single trigger function that computes all volatile formula fields
+ */
+export const generateVolatileFormulaTriggerFunction = (
+  tableName: string,
+  fields: readonly Fields[number][]
+): string | undefined => {
+  const volatileFields = getVolatileFormulaFields(fields)
+  if (volatileFields.length === 0) {
+    return undefined
+  }
+
+  const functionName = `compute_${tableName}_formulas`
+  const assignments = volatileFields
+    .map((field) => {
+      // Translate formula to PostgreSQL syntax (e.g., SUBSTR → SUBSTRING, date::TEXT → TO_CHAR)
+      const translatedFormula = translateFormulaToPostgres(field.formula, fields)
+      // Qualify column references with 't.' prefix for the subquery alias
+      const qualifiedFormula = qualifyColumnReferences(translatedFormula, fields, 't')
+      return `  SELECT (${qualifiedFormula}) INTO NEW.${field.name} FROM (SELECT NEW.*) AS t;`
+    })
+    .join('\n')
+
+  return `
+CREATE OR REPLACE FUNCTION ${functionName}()
+RETURNS TRIGGER AS $$
+BEGIN
+${assignments}
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+`.trim()
+}
+
+/**
+ * Generate trigger that calls the formula computation function
+ * Fires BEFORE INSERT OR UPDATE to compute volatile formula values
+ */
+export const generateVolatileFormulaTrigger = (
+  tableName: string,
+  fields: readonly Fields[number][]
+): string | undefined => {
+  const volatileFields = getVolatileFormulaFields(fields)
+  if (volatileFields.length === 0) {
+    return undefined
+  }
+
+  const functionName = `compute_${tableName}_formulas`
+  const triggerName = `trigger_compute_${tableName}_formulas`
+
+  return `
+CREATE TRIGGER ${triggerName}
+BEFORE INSERT OR UPDATE ON ${tableName}
+FOR EACH ROW
+EXECUTE FUNCTION ${functionName}();
+`.trim()
+}
+
+/**
+ * Create volatile formula triggers for a table
+ * Helper function to create both trigger function and trigger in one call
+ */
+/* eslint-disable functional/no-expression-statements */
+export const createVolatileFormulaTriggers = async (
+  tx: { unsafe: (sql: string) => Promise<unknown> },
+  tableName: string,
+  fields: readonly Fields[number][]
+): Promise<void> => {
+  const triggerFunction = generateVolatileFormulaTriggerFunction(tableName, fields)
+  if (triggerFunction) await tx.unsafe(triggerFunction)
+
+  const trigger = generateVolatileFormulaTrigger(tableName, fields)
+  if (trigger) await tx.unsafe(trigger)
+}
+/* eslint-enable functional/no-expression-statements */