sovrium 0.0.2

package/src/infrastructure/database/table-operations/table-features.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 { Effect } from 'effect'
+import { sanitizeTableName } from '../field-utils'
+import { createVolatileFormulaTriggers } from '../formula/formula-trigger-generators'
+import { generateIndexStatements } from '../generators/index-generators'
+import {
+  generateCreatedAtTriggers,
+  generateAutonumberTriggers,
+  generateUpdatedByTriggers,
+  generateUpdatedAtTriggers,
+} from '../generators/trigger-generators'
+import { shouldUseView, getBaseTableName } from '../lookup/lookup-view-generators'
+import {
+  executeSQLStatements,
+  executeSQLStatementsParallel,
+  type TransactionLike,
+  type SQLExecutionError,
+} from '../sql/sql-execution'
+import type { Table } from '@/domain/models/app/table'
+
+/**
+ * Apply table features (indexes, triggers)
+ * Shared by both createNewTable and migrateExistingTable
+ * Note: Triggers are applied to the base table, not the VIEW
+ *
+ * Field-level permissions are enforced at the application layer,
+ * not via PostgreSQL column-level GRANTs.
+ */
+export const applyTableFeatures = (
+  tx: TransactionLike,
+  table: Table
+): Effect.Effect<void, SQLExecutionError> =>
+  Effect.gen(function* () {
+    // Sanitize table name for PostgreSQL
+    const sanitized = sanitizeTableName(table.name)
+    // Determine actual table name (base table if using VIEW)
+    const physicalTableName = shouldUseView(table) ? getBaseTableName(sanitized) : sanitized
+
+    // Create table object with physical table name for trigger generation
+    const physicalTable = shouldUseView(table) ? { ...table, name: physicalTableName } : table
+
+    // Indexes and triggers (can run in parallel - all independent)
+    // These create IF NOT EXISTS so order doesn't matter
+    yield* Effect.all(
+      [
+        executeSQLStatementsParallel(tx, generateIndexStatements(physicalTable)),
+        executeSQLStatements(tx, generateCreatedAtTriggers(physicalTable)),
+        executeSQLStatements(tx, generateAutonumberTriggers(physicalTable)),
+        executeSQLStatements(tx, generateUpdatedByTriggers(physicalTable)),
+        executeSQLStatements(tx, generateUpdatedAtTriggers(physicalTable)),
+        Effect.promise(() => createVolatileFormulaTriggers(tx, physicalTableName, table.fields)),
+      ],
+      { concurrency: 'unbounded' }
+    )
+  })
+
+/**
+ * Apply table features without indexes (triggers only)
+ * Used during migration when indexes are handled separately by syncIndexes
+ * Note: Triggers are applied to the base table, not the VIEW
+ *
+ * Field-level permissions are enforced at the application layer,
+ * not via PostgreSQL column-level GRANTs.
+ */
+export const applyTableFeaturesWithoutIndexes = (
+  tx: TransactionLike,
+  table: Table
+): Effect.Effect<void, SQLExecutionError> =>
+  Effect.gen(function* () {
+    // Sanitize table name for PostgreSQL
+    const sanitized = sanitizeTableName(table.name)
+    // Determine actual table name (base table if using VIEW)
+    const physicalTableName = shouldUseView(table) ? getBaseTableName(sanitized) : sanitized
+
+    // Create table object with physical table name for trigger generation
+    const physicalTable = shouldUseView(table) ? { ...table, name: physicalTableName } : table
+
+    // Triggers (can run in parallel - all independent)
+    // These create IF NOT EXISTS so order doesn't matter
+    yield* Effect.all(
+      [
+        executeSQLStatements(tx, generateCreatedAtTriggers(physicalTable)),
+        executeSQLStatements(tx, generateAutonumberTriggers(physicalTable)),
+        executeSQLStatements(tx, generateUpdatedByTriggers(physicalTable)),
+        executeSQLStatements(tx, generateUpdatedAtTriggers(physicalTable)),
+        Effect.promise(() => createVolatileFormulaTriggers(tx, physicalTableName, table.fields)),
+      ],
+      { concurrency: 'unbounded' }
+    )
+  })

package/src/infrastructure/database/table-operations/type-compatibility.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+
+/**
+ * Normalize PostgreSQL type names by removing size specifications
+ */
+export const normalizeType = (type: string): string =>
+  type
+    .replace(/\(\d+\)/, '') // Remove (N) like varchar(255) -> varchar
+    .replace(/\(\d+,\s*\d+\)/, '') // Remove (N,M) like numeric(10,2) -> numeric
+    .trim()
+
+/**
+ * Type compatibility groups - types within a group can be safely copied between each other
+ */
+const TYPE_COMPATIBILITY_GROUPS: readonly (readonly string[])[] = [
+  // Integer types (can be widened but not narrowed, but for recreation we allow same family)
+  ['smallint', 'integer', 'bigint', 'int2', 'int4', 'int8'],
+  // Text types
+  ['text', 'varchar', 'character varying', 'char', 'character', 'bpchar'],
+  // Boolean
+  ['boolean', 'bool'],
+  // Floating point
+  ['real', 'double precision', 'float4', 'float8'],
+  // Numeric/Decimal
+  ['numeric', 'decimal'],
+  // Date/Time
+  ['timestamp', 'timestamp without time zone', 'timestamp with time zone', 'timestamptz'],
+  ['date'],
+  ['time', 'time without time zone', 'time with time zone', 'timetz'],
+  // UUID
+  ['uuid'],
+  // JSON
+  ['json', 'jsonb'],
+]
+
+/**
+ * Check if two PostgreSQL data types are compatible for data copying
+ * Returns true if data can be safely copied from oldType to newType
+ */
+export const areTypesCompatible = (oldType: string, newType: string): boolean => {
+  // Exact match is always compatible
+  if (oldType === newType) return true
+
+  const normalizedOld = normalizeType(oldType)
+  const normalizedNew = normalizeType(newType)
+
+  if (normalizedOld === normalizedNew) return true
+
+  // Check if both types are in the same compatibility group
+  return TYPE_COMPATIBILITY_GROUPS.some(
+    (group) => group.includes(normalizedOld) && group.includes(normalizedNew)
+  )
+}

package/src/infrastructure/database/table-operations.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+
+/**
+ * Table Operations - Re-export Module
+ *
+ * This file re-exports all table operation utilities from the split module structure.
+ * Maintained for backwards compatibility with existing imports.
+ *
+ * @see ./table-operations/ for the actual implementations
+ */
+
+// Type exports
+export type { MigrationConfig } from './table-operations/'
+
+// All function exports
+export {
+  // Type compatibility utilities
+  normalizeType,
+  areTypesCompatible,
+  // Column generators
+  generateIdColumn,
+  needsAutomaticIdColumn,
+  generateCreatedAtColumn,
+  generateUpdatedAtColumn,
+  generateDeletedAtColumn,
+  generatePrimaryKeyConstraintIfNeeded,
+  // CREATE TABLE SQL generation
+  generateCreateTableSQL,
+  // Table features (indexes, triggers, field permissions)
+  applyTableFeatures,
+  applyTableFeaturesWithoutIndexes,
+  // Migration utilities
+  getCompatibleColumns,
+  copyDataAndResetSequences,
+  recreateTableWithDataEffect,
+  // Table effect operations
+  migrateExistingTableEffect,
+  createNewTableEffect,
+  createLookupViewsEffect,
+  createTableViewsEffect,
+  createOrMigrateTableEffect,
+} from './table-operations/'

package/src/infrastructure/database/table-queries/batch/batch-create.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 { Effect } from 'effect'
+import { db, SessionContextError } from '@/infrastructure/database'
+import { injectCreateAuthorship } from '../mutation-helpers/authorship-helpers'
+import { logActivity } from '../query-helpers/activity-log-helpers'
+import { wrapDatabaseErrorWithValidation } from '../shared/error-handling'
+import { validateTableName } from '../shared/validation'
+import { createSingleRecordInBatch, runEffectInTx } from './batch-helpers'
+import type { Session } from '@/infrastructure/auth/better-auth/schema'
+import type { ValidationError } from '@/infrastructure/database'
+
+/**
+ * Batch create records
+ *
+ * Creates multiple records in a single transaction.
+ * Permissions applied via application layer.
+ *
+ * @param session - Better Auth session
+ * @param tableName - Name of the table
+ * @param recordsData - Array of field objects to insert
+ * @returns Effect resolving to array of created records
+ */
+export function batchCreateRecords(
+  session: Readonly<Session>,
+  tableName: string,
+  recordsData: readonly Record<string, unknown>[]
+): Effect.Effect<readonly Record<string, unknown>[], SessionContextError | ValidationError> {
+  return Effect.gen(function* () {
+    const createdRecords = yield* Effect.tryPromise({
+      try: () =>
+        db.transaction(async (tx) => {
+          validateTableName(tableName)
+
+          if (recordsData.length === 0) {
+            // eslint-disable-next-line functional/no-throw-statements -- Required for transaction error handling
+            throw new SessionContextError('Cannot create batch with no records', undefined)
+          }
+
+          // Inject authorship metadata for each record
+          const recordsWithAuthorship = await Promise.all(
+            recordsData.map((fields) =>
+              injectCreateAuthorship(fields, session.userId, tx, tableName)
+            )
+          )
+
+          // Use Effect.reduce with runEffectInTx to properly propagate ValidationError
+          return await runEffectInTx(
+            Effect.reduce(
+              recordsWithAuthorship,
+              [] as readonly Record<string, unknown>[],
+              (acc, fields) =>
+                createSingleRecordInBatch(tx, tableName, fields).pipe(
+                  Effect.map((record) => (record ? [...acc, record] : acc))
+                )
+            )
+          )
+        }),
+      catch: wrapDatabaseErrorWithValidation(`Failed to create batch records in ${tableName}`),
+    })
+
+    // Log activity for each created record
+    yield* Effect.forEach(createdRecords, (record) =>
+      logActivity({
+        session,
+        tableName,
+        action: 'create',
+        recordId: String(record.id),
+        changes: { after: record },
+      })
+    ).pipe(Effect.asVoid)
+
+    return createdRecords
+  })
+}

package/src/infrastructure/database/table-queries/batch/batch-delete.ts

@@ -0,0 +1,212 @@
+/**
+ * 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 { sql } from 'drizzle-orm'
+import { Effect } from 'effect'
+import { db, SessionContextError, type DrizzleTransaction } from '@/infrastructure/database'
+import { fetchRecordsByIds } from '../mutation-helpers/record-fetch-helpers'
+import { logActivity } from '../query-helpers/activity-log-helpers'
+import { wrapDatabaseError } from '../shared/error-handling'
+import { validateTableName } from '../shared/validation'
+import { runEffectInTx } from './batch-helpers'
+import type { Session } from '@/infrastructure/auth/better-auth/schema'
+
+/**
+ * Validate records exist for batch delete
+ */
+async function validateRecordsForDelete(
+  tx: Readonly<DrizzleTransaction>,
+  tableIdent: Readonly<ReturnType<typeof sql.identifier>>,
+  recordIds: readonly string[]
+): Promise<void> {
+  const validationResults = await Promise.all(
+    recordIds.map(async (recordId) => {
+      const checkResult = (await tx.execute(
+        sql`SELECT id FROM ${tableIdent} WHERE id = ${recordId} LIMIT 1`
+      )) as readonly Record<string, unknown>[]
+
+      if (checkResult.length === 0) {
+        return { recordId, error: 'not found' }
+      }
+
+      return { recordId, error: undefined }
+    })
+  )
+
+  const firstError = validationResults.find((result) => result.error !== undefined)
+  if (firstError) {
+    // eslint-disable-next-line functional/no-throw-statements -- Required for Effect.tryPromise error handling
+    throw new Error(`Record ${firstError.recordId} not found`)
+  }
+}
+
+/**
+ * Validate records exist for batch delete with Effect error handling
+ */
+function validateRecordsForDeleteWithEffect(
+  tx: Readonly<DrizzleTransaction>,
+  tableIdent: Readonly<ReturnType<typeof sql.identifier>>,
+  recordIds: readonly string[]
+): Effect.Effect<void, SessionContextError> {
+  return Effect.tryPromise({
+    try: () => validateRecordsForDelete(tx, tableIdent, recordIds),
+    catch: (error) => {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      return new SessionContextError(`Validation failed: ${errorMessage}`, error)
+    },
+  })
+}
+
+/**
+ * Check if table supports soft delete (has deleted_at column)
+ */
+function checkSoftDeleteSupport(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string
+): Effect.Effect<boolean, SessionContextError> {
+  return Effect.tryPromise({
+    try: async () => {
+      const columnCheck = (await tx.execute(
+        sql`SELECT column_name FROM information_schema.columns WHERE table_name = ${tableName} AND column_name = 'deleted_at'`
+      )) as readonly Record<string, unknown>[]
+      return columnCheck.length > 0
+    },
+    catch: (error) => new SessionContextError('Failed to check deleted_at column', error),
+  })
+}
+
+/**
+ * Check if table has deleted_by column for authorship tracking
+ */
+function checkDeletedBySupport(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string
+): Effect.Effect<boolean, SessionContextError> {
+  return Effect.tryPromise({
+    try: async () => {
+      const columnCheck = (await tx.execute(
+        sql`SELECT column_name FROM information_schema.columns WHERE table_name = ${tableName} AND column_name = 'deleted_by'`
+      )) as readonly Record<string, unknown>[]
+      return columnCheck.length > 0
+    },
+    catch: (error) => new SessionContextError('Failed to check deleted_by column', error),
+  })
+}
+
+/**
+ * Execute delete query (soft or hard delete based on parameters)
+ */
+function executeDeleteQuery(
+  tx: Readonly<DrizzleTransaction>,
+  params: {
+    readonly tableName: string
+    readonly recordIds: readonly string[]
+    readonly hasSoftDelete: boolean
+    readonly hasDeletedBy: boolean
+    readonly permanent: boolean
+    readonly userId: string
+  }
+): Effect.Effect<number, SessionContextError> {
+  return Effect.tryPromise({
+    try: async () => {
+      const tableIdent = sql.identifier(params.tableName)
+      const idParams = sql.join(
+        params.recordIds.map((id) => sql`${id}`),
+        sql.raw(', ')
+      )
+
+      // Determine query type: permanent delete, soft delete, or hard delete (no soft delete support)
+      const query = params.permanent
+        ? sql`DELETE FROM ${tableIdent} WHERE id IN (${idParams}) RETURNING id`
+        : params.hasSoftDelete
+          ? params.hasDeletedBy
+            ? sql`UPDATE ${tableIdent} SET deleted_at = NOW(), deleted_by = ${params.userId} WHERE id IN (${idParams}) AND deleted_at IS NULL RETURNING id`
+            : sql`UPDATE ${tableIdent} SET deleted_at = NOW() WHERE id IN (${idParams}) AND deleted_at IS NULL RETURNING id`
+          : sql`DELETE FROM ${tableIdent} WHERE id IN (${idParams}) RETURNING id`
+
+      const result = (await tx.execute(query)) as readonly Record<string, unknown>[]
+      return result.length
+    },
+    catch: (error) =>
+      new SessionContextError(`Failed to delete records in ${params.tableName}`, error),
+  })
+}
+
+/**
+ * Log delete activities for all deleted records
+ */
+function logDeleteActivities(
+  session: Readonly<Session>,
+  tableName: string,
+  recordsBefore: readonly Record<string, unknown>[]
+): Effect.Effect<void, never> {
+  return Effect.forEach(recordsBefore, (record) =>
+    logActivity({
+      session,
+      tableName,
+      action: 'delete',
+      recordId: String(record.id),
+      changes: { before: record },
+    })
+  ).pipe(Effect.asVoid)
+}
+
+/**
+ * Batch delete records
+ *
+ * Deletes multiple records (soft or hard delete based on parameters).
+ * Validates all records exist before deleting any.
+ * Rolls back if any record is not found.
+ * Permissions applied via application layer.
+ *
+ * @param session - Better Auth session
+ * @param tableName - Name of the table
+ * @param recordIds - Array of record IDs to delete
+ * @param permanent - If true, performs hard delete; otherwise soft delete (if supported)
+ * @returns Effect resolving to number of deleted records
+ */
+export function batchDeleteRecords(
+  session: Readonly<Session>,
+  tableName: string,
+  recordIds: readonly string[],
+  permanent = false
+): Effect.Effect<number, SessionContextError> {
+  return Effect.gen(function* () {
+    const { deletedCount, recordsBefore } = yield* Effect.tryPromise({
+      try: () =>
+        db.transaction(async (tx) => {
+          validateTableName(tableName)
+          const tableIdent = sql.identifier(tableName)
+
+          // eslint-disable-next-line functional/no-expression-statements -- Required for transaction validation
+          await runEffectInTx(validateRecordsForDeleteWithEffect(tx, tableIdent, recordIds))
+
+          const before = await runEffectInTx(fetchRecordsByIds(tx, tableName, recordIds))
+          const hasSoftDelete = await runEffectInTx(checkSoftDeleteSupport(tx, tableName))
+          const hasDeletedBy = await runEffectInTx(checkDeletedBySupport(tx, tableName))
+
+          const count = await runEffectInTx(
+            executeDeleteQuery(tx, {
+              tableName,
+              recordIds,
+              hasSoftDelete,
+              hasDeletedBy,
+              permanent,
+              userId: session.userId,
+            })
+          )
+
+          return { deletedCount: count, recordsBefore: before }
+        }),
+      catch: wrapDatabaseError(`Failed to delete records in ${tableName}`),
+    })
+
+    yield* logDeleteActivities(session, tableName, recordsBefore)
+
+    return deletedCount
+  })
+}

package/src/infrastructure/database/table-queries/batch/batch-helpers.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 { sql } from 'drizzle-orm'
+import { Data, Effect, Exit, Cause } from 'effect'
+import { ValidationError, type DrizzleTransaction } from '@/infrastructure/database'
+import { validateColumnName } from '../shared/validation'
+
+/**
+ * Batch validation error - returned when batch validation fails
+ */
+export class BatchValidationError extends Data.TaggedError('BatchValidationError')<{
+  readonly message: string
+  readonly details?: readonly string[]
+}> {}
+
+/**
+ * Run an Effect inside a database transaction, properly unwrapping errors.
+ *
+ * Unlike Effect.runPromise which wraps errors in FiberFailure (breaking instanceof checks
+ * in outer catch handlers), this helper extracts the original error via Cause.squash
+ * and re-throws it directly. This ensures SessionContextError, ValidationError, etc.
+ * are properly detected by instanceof in Effect.tryPromise catch handlers.
+ */
+export async function runEffectInTx<A, E>(effect: Effect.Effect<A, E, never>): Promise<A> {
+  const exit = await Effect.runPromiseExit(effect)
+  if (Exit.isSuccess(exit)) return exit.value
+  // eslint-disable-next-line functional/no-throw-statements -- Required to propagate Effect errors in async transaction context
+  throw Cause.squash(exit.cause)
+}
+
+/**
+ * Build INSERT SQL clauses from fields object.
+ * Returns undefined if fields is empty.
+ */
+function buildInsertClauses(fields: Readonly<Record<string, unknown>>):
+  | {
+      readonly columnsClause: ReturnType<typeof sql.join>
+      readonly valuesClause: ReturnType<typeof sql.join>
+    }
+  | undefined {
+  const entries = Object.entries(fields)
+  if (entries.length === 0) return undefined
+
+  const columnIdentifiers = entries.map(([key]) => {
+    validateColumnName(key)
+    return sql.identifier(key)
+  })
+  const valueParams = entries.map(([, value]) => sql`${value}`)
+
+  return {
+    columnsClause: sql.join(columnIdentifiers, sql.raw(', ')),
+    valuesClause: sql.join(valueParams, sql.raw(', ')),
+  }
+}
+
+/**
+ * Handle PostgreSQL NOT NULL violation errors, converting to ValidationError.
+ */
+// eslint-disable-next-line functional/prefer-immutable-types -- called from Effect.tryPromise catch
+function handleInsertError(error: unknown): ValidationError {
+  const pgError = error as { code?: string; message?: string }
+  if (pgError.code === '23502' || pgError.message?.includes('null value in column')) {
+    return new ValidationError('Validation failed: Required field is missing', [
+      { record: 0, field: 'unknown', error: 'Required field is missing' },
+    ])
+  }
+  const errorMessage: string =
+    pgError.message !== undefined ? pgError.message : 'Insert failed due to constraint violation'
+  return new ValidationError(errorMessage, [])
+}
+
+/**
+ * Helper to create a single record within a transaction
+ */
+export async function createSingleRecord(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  fields: Readonly<Record<string, unknown>>
+): Promise<Readonly<Record<string, unknown>> | undefined> {
+  const clauses = buildInsertClauses(fields)
+  if (!clauses) return undefined
+
+  try {
+    const result = (await tx.execute(
+      sql`INSERT INTO ${sql.identifier(tableName)} (${clauses.columnsClause}) VALUES (${clauses.valuesClause}) RETURNING *`
+    )) as readonly Record<string, unknown>[]
+
+    return result[0] ?? undefined
+  } catch (error) {
+    // eslint-disable-next-line functional/no-throw-statements -- Required for error propagation
+    throw handleInsertError(error)
+  }
+}
+
+/**
+ * Effect-based helper to create a single record within a batch operation
+ *
+ * This is the Effect version of createSingleRecord, used by batchCreateRecords
+ * to properly propagate ValidationError through Effect.reduce.
+ */
+export function createSingleRecordInBatch(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  fields: Readonly<Record<string, unknown>>
+): Effect.Effect<Record<string, unknown> | undefined, ValidationError> {
+  return Effect.tryPromise({
+    try: async () => {
+      const clauses = buildInsertClauses(fields)
+      if (!clauses) return undefined
+
+      const result = (await tx.execute(
+        sql`INSERT INTO ${sql.identifier(tableName)} (${clauses.columnsClause}) VALUES (${clauses.valuesClause}) RETURNING *`
+      )) as readonly Record<string, unknown>[]
+
+      return result[0] ?? undefined
+    },
+    catch: handleInsertError,
+  })
+}