sovrium 0.0.2

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

@@ -0,0 +1,161 @@
+/**
+ * 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 { 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 and filter to only soft-deleted ones
+ * Returns array of record IDs that are actually soft-deleted
+ * Throws error if any record is not found (404)
+ */
+async function validateAndFilterRecordsForRestore(
+  tx: Readonly<DrizzleTransaction>,
+  tableIdent: Readonly<ReturnType<typeof sql.identifier>>,
+  recordIds: readonly string[]
+): Promise<readonly string[]> {
+  const validationResults = await Promise.all(
+    recordIds.map(async (recordId) => {
+      const checkResult = (await tx.execute(
+        sql`SELECT id, deleted_at FROM ${tableIdent} WHERE id = ${recordId} LIMIT 1`
+      )) as readonly Record<string, unknown>[]
+
+      if (checkResult.length === 0) return { recordId, error: 'not found', isDeleted: false }
+
+      const record = checkResult[0]
+      const isDeleted = Boolean(record?.deleted_at)
+
+      return { recordId, error: undefined, isDeleted }
+    })
+  )
+
+  // Check for "not found" errors first (these should return 404)
+  const notFoundError = validationResults.find((result) => result.error === 'not found')
+  if (notFoundError) {
+    // eslint-disable-next-line functional/no-throw-statements -- Required for Effect.tryPromise error handling
+    throw new Error(`Record ${notFoundError.recordId} not found`)
+  }
+
+  // Filter to only records that are actually soft-deleted (skip active records)
+  return validationResults.filter((result) => result.isDeleted).map((result) => result.recordId)
+}
+
+/**
+ * Validate and filter records for restore with Effect error handling
+ * Returns array of record IDs that are actually soft-deleted
+ */
+function validateAndFilterRecordsWithEffect(
+  tx: Readonly<DrizzleTransaction>,
+  tableIdent: Readonly<ReturnType<typeof sql.identifier>>,
+  recordIds: readonly string[]
+): Effect.Effect<readonly string[], SessionContextError> {
+  return Effect.tryPromise({
+    try: () => validateAndFilterRecordsForRestore(tx, tableIdent, recordIds),
+    catch: (error) => {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      return new SessionContextError(`Validation failed: ${errorMessage}`, error)
+    },
+  })
+}
+
+/**
+ * Execute restore query using parameterized IN clause
+ */
+function executeRestoreQuery(
+  tx: Readonly<DrizzleTransaction>,
+  tableIdent: Readonly<ReturnType<typeof sql.identifier>>,
+  tableName: string,
+  recordIds: readonly string[]
+): Effect.Effect<readonly Record<string, unknown>[], SessionContextError> {
+  return Effect.tryPromise({
+    try: async () => {
+      const idParams = sql.join(
+        recordIds.map((id) => sql`${id}`),
+        sql.raw(', ')
+      )
+      const result = (await tx.execute(
+        sql`UPDATE ${tableIdent} SET deleted_at = NULL WHERE id IN (${idParams}) RETURNING *`
+      )) as readonly Record<string, unknown>[]
+      return result
+    },
+    catch: (error) => new SessionContextError(`Failed to restore records in ${tableName}`, error),
+  })
+}
+
+/**
+ * Log restore activities for all restored records
+ */
+function logRestoreActivities(
+  session: Readonly<Session>,
+  tableName: string,
+  restoredRecords: readonly Record<string, unknown>[]
+): Effect.Effect<void, never> {
+  return Effect.forEach(restoredRecords, (record) =>
+    logActivity({
+      session,
+      tableName,
+      action: 'restore',
+      recordId: String(record.id),
+      changes: { after: record },
+    })
+  ).pipe(Effect.asVoid)
+}
+
+/**
+ * Batch restore soft-deleted records
+ *
+ * Restores multiple soft-deleted records in a transaction.
+ * Validates all records exist and are soft-deleted before restoring any.
+ * Rolls back if any record fails validation.
+ * Permissions enforced at the presentation layer (route handler).
+ *
+ * @param session - Better Auth session
+ * @param tableName - Name of the table
+ * @param recordIds - Array of record IDs to restore
+ * @returns Effect resolving to number of restored records or error
+ */
+export function batchRestoreRecords(
+  session: Readonly<Session>,
+  tableName: string,
+  recordIds: readonly string[]
+): Effect.Effect<number, SessionContextError> {
+  return Effect.gen(function* () {
+    const restoredRecords = yield* Effect.tryPromise({
+      try: () =>
+        db.transaction(async (tx) => {
+          validateTableName(tableName)
+          const tableIdent = sql.identifier(tableName)
+
+          // Validate and filter to only soft-deleted records
+          const deletedRecordIds = await runEffectInTx(
+            validateAndFilterRecordsWithEffect(tx, tableIdent, recordIds)
+          )
+
+          // If no records to restore, return empty array
+          if (deletedRecordIds.length === 0) {
+            return []
+          }
+
+          // Restore only the filtered soft-deleted records
+          return await runEffectInTx(
+            executeRestoreQuery(tx, tableIdent, tableName, deletedRecordIds)
+          )
+        }),
+      catch: wrapDatabaseError(`Failed to restore records in ${tableName}`),
+    })
+
+    yield* logRestoreActivities(session, tableName, restoredRecords)
+
+    return restoredRecords.length
+  })
+}

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

@@ -0,0 +1,146 @@
+/**
+ * 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,
+  ValidationError,
+  type DrizzleTransaction,
+  type SessionContextError,
+} from '@/infrastructure/database'
+import { injectUpdateAuthorship } from '../mutation-helpers/authorship-helpers'
+import { fetchRecordByIdEffect } from '../mutation-helpers/record-fetch-helpers'
+import { buildUpdateSetClauseCRUD } from '../mutation-helpers/update-helpers'
+import { logActivity } from '../query-helpers/activity-log-helpers'
+import { wrapDatabaseErrorWithValidation } from '../shared/error-handling'
+import { validateTableName } from '../shared/validation'
+import { runEffectInTx } from './batch-helpers'
+import type { Session } from '@/infrastructure/auth/better-auth/schema'
+
+/**
+ * Extract fields from update object (requires nested format)
+ */
+function extractFieldsFromUpdate(update: {
+  readonly id: string
+  readonly fields?: Readonly<Record<string, unknown>>
+}): Readonly<Record<string, unknown>> {
+  // Return fields property or empty object if not provided
+  return update.fields ?? {}
+}
+
+/**
+ * Execute UPDATE query and return updated record
+ */
+function executeRecordUpdate(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordId: string,
+  setClause: Readonly<ReturnType<typeof sql.join>>
+): Effect.Effect<Record<string, unknown> | undefined, ValidationError> {
+  return Effect.tryPromise({
+    try: async () => {
+      const result = (await tx.execute(
+        sql`UPDATE ${sql.identifier(tableName)} SET ${setClause} WHERE id = ${recordId} RETURNING *`
+      )) as readonly Record<string, unknown>[]
+      return result[0]
+    },
+    catch: (error) => {
+      // PostgreSQL error codes: https://www.postgresql.org/docs/current/errcodes-appendix.html
+      // 23502 = not_null_violation
+      const pgError = error as { code?: string; message?: string; constraint?: string }
+      if (pgError.code === '23502' || pgError.message?.includes('null value in column')) {
+        // Extract field name from error message if possible
+        const fieldMatch = pgError.message?.match(/column "([^"]+)"/)
+        const fieldName: string = fieldMatch?.[1] ?? 'unknown'
+        return new ValidationError(`Cannot set required field '${fieldName}' to null`, [
+          { record: 0, field: fieldName, error: 'Required field cannot be null' },
+        ])
+      }
+      // For other errors, return generic validation error
+      const errorMessage: string =
+        pgError.message !== undefined
+          ? pgError.message
+          : 'Update failed due to constraint violation'
+      return new ValidationError(errorMessage, [])
+    },
+  })
+}
+
+/**
+ * Update a single record within a batch operation
+ */
+function updateSingleRecordInBatch(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  session: Readonly<Session>,
+  update: { readonly id: string; readonly fields?: Record<string, unknown> }
+): Effect.Effect<Record<string, unknown> | undefined, ValidationError> {
+  return Effect.gen(function* () {
+    const fieldsToUpdate = extractFieldsFromUpdate(update)
+
+    if (Object.keys(fieldsToUpdate).length === 0) return undefined
+
+    // Inject updated_by authorship metadata
+    const fieldsWithAuthorship = yield* Effect.promise(() =>
+      injectUpdateAuthorship(fieldsToUpdate, session.userId, tx, tableName)
+    )
+
+    const entries = Object.entries(fieldsWithAuthorship)
+    const recordBefore = yield* fetchRecordByIdEffect(tx, tableName, update.id)
+    const setClause = buildUpdateSetClauseCRUD(entries)
+    const updatedRecord = yield* executeRecordUpdate(tx, tableName, update.id, setClause)
+
+    if (updatedRecord) {
+      yield* logActivity({
+        session,
+        tableName,
+        action: 'update',
+        recordId: String(update.id),
+        changes: { before: recordBefore, after: updatedRecord },
+      })
+      return updatedRecord
+    }
+
+    return undefined
+  })
+}
+
+/**
+ * Batch update records
+ *
+ * Updates multiple records in a transaction with permission enforcement.
+ * Only records the user has permission to update will be affected.
+ * Records without permission are silently skipped.
+ *
+ * @param session - Better Auth session
+ * @param tableName - Name of the table
+ * @param updates - Array of records with id and fields to update (requires nested format)
+ * @returns Effect resolving to array of updated records
+ */
+export function batchUpdateRecords(
+  session: Readonly<Session>,
+  tableName: string,
+  updates: readonly { readonly id: string; readonly fields?: Record<string, unknown> }[]
+): Effect.Effect<readonly Record<string, unknown>[], SessionContextError | ValidationError> {
+  return Effect.tryPromise({
+    try: () =>
+      db.transaction(async (tx) => {
+        validateTableName(tableName)
+
+        return await runEffectInTx(
+          // Process updates sequentially with immutable array building
+          Effect.reduce(updates, [] as readonly Record<string, unknown>[], (acc, update) =>
+            updateSingleRecordInBatch(tx, tableName, session, update).pipe(
+              Effect.map((record) => (record ? [...acc, record] : acc))
+            )
+          )
+        )
+      }),
+    catch: wrapDatabaseErrorWithValidation(`Failed to batch update records in ${tableName}`),
+  })
+}

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

@@ -0,0 +1,357 @@
+/**
+ * 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,
+  ValidationError,
+  type DrizzleTransaction,
+} from '@/infrastructure/database'
+import { logActivity } from '../query-helpers/activity-log-helpers'
+import { typedExecute } from '../shared/typed-execute'
+import { validateTableName, validateColumnName } from '../shared/validation'
+import { BatchValidationError, runEffectInTx, createSingleRecord } from './batch-helpers'
+import type { Session } from '@/infrastructure/auth/better-auth/schema'
+
+/**
+ * Helper to update existing record
+ */
+async function updateSingleRecord(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordId: string,
+  params: { readonly fields: Record<string, unknown>; readonly fieldsToMergeOn: readonly string[] }
+): Promise<Record<string, unknown> | undefined> {
+  const updateEntries = Object.entries(params.fields).filter(
+    ([key]) => !params.fieldsToMergeOn.includes(key)
+  )
+  if (updateEntries.length === 0) return undefined
+
+  const setExpressions = updateEntries.map(([key, value]) => {
+    validateColumnName(key)
+    return sql`${sql.identifier(key)} = ${value}`
+  })
+  const setClause = sql.join(setExpressions, sql.raw(', '))
+
+  const result = (await tx.execute(
+    sql`UPDATE ${sql.identifier(tableName)} SET ${setClause} WHERE id = ${recordId} RETURNING *`
+  )) as readonly Record<string, unknown>[]
+
+  return result[0] ?? undefined
+}
+
+type UpsertResult = {
+  readonly records: readonly Record<string, unknown>[]
+  readonly created: number
+  readonly updated: number
+}
+
+/**
+ * Check if record exists based on merge fields
+ */
+function findExistingRecord(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  fields: Readonly<Record<string, unknown>>,
+  fieldsToMergeOn: readonly string[]
+): Effect.Effect<Readonly<Record<string, unknown>> | undefined, SessionContextError> {
+  const whereConditions = fieldsToMergeOn.map((field) => {
+    validateColumnName(field)
+    return sql`${sql.identifier(field)} = ${fields[field]}`
+  })
+  const whereClause = sql.join(whereConditions, sql.raw(' AND '))
+
+  return Effect.tryPromise({
+    try: async () => {
+      const result = (await tx.execute(
+        sql`SELECT * FROM ${sql.identifier(tableName)} WHERE ${whereClause} LIMIT 1`
+      )) as readonly Record<string, unknown>[]
+      return result[0]
+    },
+    catch: (error) =>
+      new SessionContextError(`Failed to check existing record in ${tableName}`, error),
+  })
+}
+
+/**
+ * Handle update path in upsert
+ */
+function handleUpsertUpdate(
+  tx: Readonly<DrizzleTransaction>,
+  params: {
+    readonly session: Readonly<Session>
+    readonly tableName: string
+    readonly fields: Record<string, unknown>
+    readonly fieldsToMergeOn: readonly string[]
+    readonly existing: Record<string, unknown>
+    readonly acc: UpsertResult
+  }
+): Effect.Effect<UpsertResult, SessionContextError> {
+  return Effect.gen(function* () {
+    const recordId = String(params.existing.id)
+    const updated = yield* Effect.tryPromise({
+      try: async () =>
+        updateSingleRecord(tx, params.tableName, recordId, {
+          fields: params.fields,
+          fieldsToMergeOn: params.fieldsToMergeOn,
+        }),
+      catch: (error) =>
+        new SessionContextError(`Failed to update record in ${params.tableName}`, error),
+    })
+
+    if (!updated) {
+      return {
+        records: [...params.acc.records, params.existing],
+        created: params.acc.created,
+        updated: params.acc.updated + 1,
+      }
+    }
+
+    yield* logActivity({
+      session: params.session,
+      tableName: params.tableName,
+      action: 'update',
+      recordId,
+      changes: { before: params.existing, after: updated },
+    })
+
+    return {
+      records: [...params.acc.records, updated],
+      created: params.acc.created,
+      updated: params.acc.updated + 1,
+    }
+  })
+}
+
+/**
+ * Handle create path in upsert
+ */
+function handleUpsertCreate(
+  tx: Readonly<DrizzleTransaction>,
+  params: {
+    readonly session: Readonly<Session>
+    readonly tableName: string
+    readonly fields: Record<string, unknown>
+    readonly acc: UpsertResult
+  }
+): Effect.Effect<UpsertResult, SessionContextError | ValidationError> {
+  return Effect.gen(function* () {
+    const created = yield* Effect.tryPromise({
+      try: async () => createSingleRecord(tx, params.tableName, params.fields),
+      catch: (error) => {
+        // If this is a ValidationError, propagate it as-is
+        if (error instanceof ValidationError) {
+          return error
+        }
+        return new SessionContextError(`Failed to create record in ${params.tableName}`, error)
+      },
+    })
+
+    if (!created) return params.acc
+
+    yield* logActivity({
+      session: params.session,
+      tableName: params.tableName,
+      action: 'create',
+      recordId: String(created.id),
+      changes: { after: created },
+    })
+
+    return {
+      records: [...params.acc.records, created],
+      created: params.acc.created + 1,
+      updated: params.acc.updated,
+    }
+  })
+}
+
+/**
+ * Process single upsert operation
+ */
+function processSingleUpsert(
+  tx: Readonly<DrizzleTransaction>,
+  params: {
+    readonly session: Readonly<Session>
+    readonly tableName: string
+    readonly fields: Record<string, unknown>
+    readonly fieldsToMergeOn: readonly string[]
+    readonly acc: UpsertResult
+  }
+): Effect.Effect<UpsertResult, SessionContextError | ValidationError> {
+  return Effect.gen(function* () {
+    const existing = yield* findExistingRecord(
+      tx,
+      params.tableName,
+      params.fields,
+      params.fieldsToMergeOn
+    )
+
+    if (existing) {
+      return yield* handleUpsertUpdate(tx, { ...params, existing })
+    }
+
+    return yield* handleUpsertCreate(tx, params)
+  })
+}
+
+/**
+ * Validate merge fields are present in all records
+ */
+function validateMergeFieldsPresent(
+  recordsData: readonly Record<string, unknown>[],
+  fieldsToMergeOn: readonly string[]
+): Effect.Effect<void, BatchValidationError> {
+  const errors = recordsData.flatMap((record, index) => {
+    const missingFields = fieldsToMergeOn.filter((field) => !(field in record))
+    return missingFields.length > 0
+      ? [`Record ${index}: Missing merge field(s) ${missingFields.join(', ')}`]
+      : []
+  })
+
+  if (errors.length > 0) {
+    return Effect.fail(
+      new BatchValidationError({
+        message: 'Batch validation failed',
+        details: errors,
+      })
+    )
+  }
+
+  return Effect.void
+}
+
+/**
+ * Validate required fields are present in record (for creates)
+ * This prevents database NOT NULL constraint violations
+ */
+async function validateRequiredFieldsInRecord(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  record: Readonly<Record<string, unknown>>,
+  recordIndex: number
+): Promise<readonly string[]> {
+  // Query table schema to get required fields
+  const schemaQuery = await typedExecute<{ column_name: string }>(
+    tx,
+    sql`
+      SELECT column_name, is_nullable, column_default
+      FROM information_schema.columns
+      WHERE table_name = ${tableName}
+        AND table_schema = 'public'
+        AND is_nullable = 'NO'
+        AND column_default IS NULL
+    `
+  )
+
+  const requiredFields = schemaQuery.map((row) => row.column_name)
+
+  // System fields that are auto-generated (exclude from validation)
+  const autoFields = new Set(['id', 'created_at', 'updated_at'])
+
+  const missingFields = requiredFields.filter(
+    (field) => !autoFields.has(field) && !(field in record)
+  )
+
+  if (missingFields.length > 0) {
+    return [`Record ${recordIndex}: Missing required field(s) ${missingFields.join(', ')}`]
+  }
+
+  return []
+}
+
+/**
+ * Validate all records have required fields BEFORE processing
+ */
+function validateAllRecordsHaveRequiredFields(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordsData: readonly Record<string, unknown>[]
+): Effect.Effect<void, BatchValidationError> {
+  return Effect.gen(function* () {
+    const allErrors = yield* Effect.reduce(
+      recordsData,
+      [] as readonly string[],
+      (acc, record, index) =>
+        Effect.tryPromise({
+          try: () => validateRequiredFieldsInRecord(tx, tableName, record, index),
+          catch: (error) =>
+            new BatchValidationError({
+              message: 'Failed to validate record',
+              details: [String(error)],
+            }),
+        }).pipe(Effect.map((recordErrors) => [...acc, ...recordErrors]))
+    )
+
+    if (allErrors.length > 0) {
+      return yield* new BatchValidationError({
+        message: 'Batch validation failed',
+        details: allErrors,
+      })
+    }
+  })
+}
+
+/**
+ * Upsert records (create or update based on merge fields)
+ */
+export function upsertRecords(
+  session: Readonly<Session>,
+  tableName: string,
+  recordsData: readonly Record<string, unknown>[],
+  fieldsToMergeOn: readonly string[]
+): Effect.Effect<UpsertResult, SessionContextError | BatchValidationError | ValidationError> {
+  return Effect.gen(function* () {
+    validateTableName(tableName)
+
+    if (recordsData.length === 0) {
+      return yield* Effect.fail(
+        new SessionContextError('Cannot upsert batch with no records', undefined)
+      )
+    }
+
+    if (fieldsToMergeOn.length === 0) {
+      return yield* Effect.fail(
+        new SessionContextError('Cannot upsert without merge fields', undefined)
+      )
+    }
+
+    fieldsToMergeOn.forEach((field) => validateColumnName(field))
+
+    // Validate merge fields are present in all records BEFORE processing
+    yield* validateMergeFieldsPresent(recordsData, fieldsToMergeOn)
+
+    // Execute upsert in a transaction
+    const result = yield* Effect.tryPromise({
+      try: () =>
+        db.transaction(async (tx) => {
+          // eslint-disable-next-line functional/no-expression-statements -- Required for transaction validation
+          await runEffectInTx(validateAllRecordsHaveRequiredFields(tx, tableName, recordsData))
+
+          return await runEffectInTx(
+            Effect.reduce(
+              recordsData,
+              { records: [], created: 0, updated: 0 } as UpsertResult,
+              (acc, fields) =>
+                processSingleUpsert(tx, { session, tableName, fields, fieldsToMergeOn, acc })
+            )
+          )
+        }),
+      catch: (error) => {
+        if (error instanceof SessionContextError) return error
+        if (error instanceof BatchValidationError) {
+          // Re-wrap BatchValidationError as SessionContextError to match return type
+          return new SessionContextError(error.message, error)
+        }
+        return new SessionContextError(`Failed to upsert records in ${tableName}`, error)
+      },
+    })
+
+    return result
+  })
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+
+// Re-export all batch operations from modular files
+export { BatchValidationError } from './batch-helpers'
+export { batchCreateRecords } from './batch-create'
+export { upsertRecords } from './batch-upsert'
+export { batchRestoreRecords } from './batch-restore'
+export { batchUpdateRecords } from './batch-update'
+export { batchDeleteRecords } from './batch-delete'