sovrium 0.0.2

package/src/infrastructure/database/table-queries/crud/crud-write.ts

@@ -0,0 +1,399 @@
+/**
+ * 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, UniqueConstraintViolationError } from '@/infrastructure/database'
+import {
+  injectCreateAuthorship,
+  injectUpdateAuthorship,
+} from '../mutation-helpers/authorship-helpers'
+import {
+  buildInsertClauses,
+  isUniqueConstraintViolation,
+} from '../mutation-helpers/create-record-helpers'
+import {
+  cascadeSoftDelete,
+  executeSoftDelete,
+  executeHardDelete,
+  checkDeletedAtColumn,
+} from '../mutation-helpers/delete-helpers'
+import { fetchRecordById } from '../mutation-helpers/record-fetch-helpers'
+import {
+  validateFieldsNotEmpty,
+  buildUpdateSetClauseCRUD,
+  executeRecordUpdateCRUD,
+} from '../mutation-helpers/update-helpers'
+import { logActivity } from '../query-helpers/activity-log-helpers'
+import { wrapDatabaseError } from '../shared/error-handling'
+import { typedExecute } from '../shared/typed-execute'
+import { validateTableName } from '../shared/validation'
+import type { App } from '@/domain/models/app'
+import type { Session } from '@/infrastructure/auth/better-auth/schema'
+
+/**
+ * Create a new record
+ *
+ * @param session - Better Auth session
+ * @param tableName - Name of the table
+ * @param fields - Record fields
+ * @returns Effect resolving to created record
+ */
+export function createRecord(
+  session: Readonly<Session>,
+  tableName: string,
+  fields: Readonly<Record<string, unknown>>
+): Effect.Effect<Record<string, unknown>, SessionContextError | UniqueConstraintViolationError> {
+  return Effect.gen(function* () {
+    const record = yield* Effect.tryPromise({
+      try: () =>
+        db.transaction(async (tx) => {
+          validateTableName(tableName)
+
+          // Validate we have fields to insert
+          if (Object.keys(fields).length === 0) {
+            // eslint-disable-next-line functional/no-throw-statements -- Required for transaction error handling
+            throw new SessionContextError('Cannot create record with no fields', undefined)
+          }
+
+          // Inject authorship metadata (created_by, updated_by) from session
+          const fieldsWithAuthorship = await injectCreateAuthorship(
+            fields,
+            session.userId,
+            tx,
+            tableName
+          )
+
+          // Build INSERT query
+          const { columnsClause, valuesClause } = buildInsertClauses(fieldsWithAuthorship)
+
+          // Execute INSERT directly (avoid Effect.runPromise which wraps errors in FiberFailure)
+          const insertResult = (await tx.execute(
+            sql`INSERT INTO ${sql.identifier(tableName)} (${columnsClause}) VALUES (${valuesClause}) RETURNING *`
+          )) as readonly Record<string, unknown>[]
+          return insertResult[0] ?? {}
+        }),
+      catch: (error) => {
+        if (error instanceof SessionContextError) return error
+        if (error instanceof UniqueConstraintViolationError) return error
+        if (isUniqueConstraintViolation(error)) {
+          return new UniqueConstraintViolationError('Unique constraint violation', error)
+        }
+        return new SessionContextError(`Failed to create record in ${tableName}`, error)
+      },
+    })
+
+    // Log activity for record creation
+    yield* logActivity({
+      session,
+      tableName,
+      action: 'create',
+      recordId: String(record.id),
+      changes: { after: record },
+    })
+
+    return record
+  })
+}
+
+/**
+ * Log activity for record update
+ */
+function logRecordUpdateActivity(config: {
+  readonly session: Readonly<Session>
+  readonly tableName: string
+  readonly recordId: string
+  readonly changes: {
+    readonly before: Record<string, unknown> | undefined
+    readonly after: Record<string, unknown>
+  }
+  readonly app?: App
+}): Effect.Effect<void, never> {
+  const { session, tableName, recordId, changes, app } = config
+  return logActivity({
+    session,
+    tableName,
+    action: 'update',
+    recordId,
+    changes,
+    app,
+  })
+}
+
+/**
+ * Update a record
+ *
+ * @param session - Better Auth session
+ * @param tableName - Name of the table
+ * @param recordId - Record ID
+ * @param params - Update parameters
+ * @returns Effect resolving to updated record
+ */
+export function updateRecord(
+  session: Readonly<Session>,
+  tableName: string,
+  recordId: string,
+  params: {
+    readonly fields: Readonly<Record<string, unknown>>
+    readonly app?: App
+  }
+): Effect.Effect<Record<string, unknown>, SessionContextError> {
+  const { fields, app } = params
+  return Effect.gen(function* () {
+    const { recordBefore, updatedRecord } = yield* Effect.tryPromise({
+      try: () =>
+        db.transaction(async (tx) => {
+          validateTableName(tableName)
+
+          // Inject updated_by from session
+          const fieldsWithUpdatedBy = await injectUpdateAuthorship(
+            fields,
+            session.userId,
+            tx,
+            tableName
+          )
+
+          const entries = await validateFieldsNotEmpty(fieldsWithUpdatedBy)
+          const before = await fetchRecordById(tx, tableName, recordId)
+          const setClause = buildUpdateSetClauseCRUD(entries)
+          const updated = await executeRecordUpdateCRUD(tx, tableName, recordId, setClause)
+          return { recordBefore: before, updatedRecord: updated }
+        }),
+      catch: wrapDatabaseError(`Failed to update record in ${tableName}`),
+    })
+
+    yield* logRecordUpdateActivity({
+      session,
+      tableName,
+      recordId,
+      changes: {
+        before: recordBefore,
+        after: updatedRecord,
+      },
+      app,
+    })
+
+    return updatedRecord
+  })
+}
+
+/**
+ * Delete a record (soft delete if deleted_at field exists)
+ *
+ * Implements soft delete pattern:
+ * - If table has deleted_at field: Sets deleted_at to NOW() (soft delete)
+ * - If no deleted_at field: Performs hard delete
+ * - Permissions applied via application layer
+ * - Cascade soft delete to related records if configured with onDelete: 'cascade'
+ * - Activity logging captures record state before deletion (non-blocking)
+ *
+ * @param session - Better Auth session
+ * @param tableName - Name of the table
+ * @param recordId - Record ID
+ * @param app - App schema (optional, for cascade delete logic)
+ * @returns Effect resolving to success boolean
+ */
+// eslint-disable-next-line max-lines-per-function -- Delete logic requires soft-delete check, cascade, and hard-delete fallback
+export function deleteRecord(
+  session: Readonly<Session>,
+  tableName: string,
+  recordId: string,
+  app?: {
+    readonly tables?: ReadonlyArray<{
+      readonly name: string
+      readonly fields: ReadonlyArray<{
+        readonly name: string
+        readonly type: string
+        readonly relatedTable?: string
+        readonly onDelete?: string
+      }>
+    }>
+  }
+): Effect.Effect<boolean, SessionContextError> {
+  return Effect.gen(function* () {
+    const result = yield* Effect.tryPromise({
+      try: () =>
+        db.transaction(async (tx) => {
+          validateTableName(tableName)
+
+          // Check if table supports soft delete
+          const hasSoftDelete = await checkDeletedAtColumn(tx, tableName)
+
+          // Fetch record before deletion for activity logging
+          const recordBeforeData = await fetchRecordById(tx, tableName, recordId)
+
+          if (hasSoftDelete) {
+            // Execute soft delete
+            const success = await executeSoftDelete(tx, tableName, recordId, session.userId)
+
+            if (!success) {
+              return { success: false, recordBeforeData: undefined }
+            }
+
+            // Cascade to related records if configured
+            if (app) {
+              // eslint-disable-next-line functional/no-expression-statements -- Required for cascade operation
+              await cascadeSoftDelete(tx, tableName, recordId, app, session.userId)
+            }
+
+            return { success: true, recordBeforeData }
+          } else {
+            // Execute hard delete
+            const success = await executeHardDelete(tx, tableName, recordId)
+            return { success, recordBeforeData: undefined }
+          }
+        }),
+      catch: wrapDatabaseError(`Failed to delete record from ${tableName}`),
+    })
+
+    // Log activity for soft delete (outside transaction)
+    if (result.success && result.recordBeforeData) {
+      yield* logActivity({
+        session,
+        tableName,
+        action: 'delete',
+        recordId,
+        changes: { before: result.recordBeforeData },
+      })
+    }
+
+    return result.success
+  })
+}
+
+/**
+ * Permanently delete a record (hard delete)
+ *
+ * Permanently removes the record from the database, regardless of deleted_at field.
+ * This operation is irreversible and should only be allowed for admin roles.
+ * Permissions applied via application layer.
+ * Activity logging captures record state before deletion (non-blocking).
+ *
+ * @param session - Better Auth session
+ * @param tableName - Name of the table
+ * @param recordId - Record ID
+ * @returns Effect resolving to success boolean
+ */
+export function permanentlyDeleteRecord(
+  session: Readonly<Session>,
+  tableName: string,
+  recordId: string
+): Effect.Effect<boolean, SessionContextError> {
+  return Effect.gen(function* () {
+    const result = yield* Effect.tryPromise({
+      try: () =>
+        db.transaction(async (tx) => {
+          validateTableName(tableName)
+
+          // Fetch record before deletion for activity logging
+          const recordBeforeData = await fetchRecordById(tx, tableName, recordId)
+
+          // Execute hard delete
+          const success = await executeHardDelete(tx, tableName, recordId)
+
+          return { success, recordBeforeData: success ? recordBeforeData : undefined }
+        }),
+      catch: wrapDatabaseError(`Failed to permanently delete record from ${tableName}`),
+    })
+
+    // Log activity for permanent delete (outside transaction)
+    if (result.success && result.recordBeforeData) {
+      yield* logActivity({
+        session,
+        tableName,
+        action: 'delete',
+        recordId,
+        changes: { before: result.recordBeforeData },
+      })
+    }
+
+    return result.success
+  })
+}
+
+/**
+ * Restore a soft-deleted record
+ *
+ * Clears the deleted_at timestamp to restore a soft-deleted record.
+ * Returns error if record doesn't exist or is not soft-deleted.
+ * Permissions applied via application layer.
+ *
+ * @param session - Better Auth session
+ * @param tableName - Name of the table
+ * @param recordId - Record ID
+ * @returns Effect resolving to restored record or null
+ */
+// eslint-disable-next-line max-lines-per-function -- Restore logic requires deleted_by column check and conditional restore
+export function restoreRecord(
+  session: Readonly<Session>,
+  tableName: string,
+  recordId: string
+): Effect.Effect<Record<string, unknown> | null, SessionContextError> {
+  return Effect.gen(function* () {
+    const restoredRecord = yield* Effect.tryPromise({
+      try: () =>
+        db.transaction(async (tx) => {
+          validateTableName(tableName)
+          const tableIdent = sql.identifier(tableName)
+
+          // Check if record exists (including soft-deleted records)
+          const checkResult = await typedExecute(
+            tx,
+            sql`SELECT id, deleted_at FROM ${tableIdent} WHERE id = ${recordId} LIMIT 1`
+          )
+
+          if (checkResult.length === 0) {
+            // eslint-disable-next-line unicorn/no-null -- Null is intentional for non-existent records
+            return null // Record not found
+          }
+
+          const record = checkResult[0]
+
+          // Check if record is soft-deleted
+          if (!record?.deleted_at) {
+            // Record exists but is not deleted - return error via special marker
+            return { _error: 'not_deleted' } as Record<string, unknown>
+          }
+
+          // Check if table has deleted_by column
+          const deletedByCheck = await typedExecute(
+            tx,
+            sql`SELECT column_name FROM information_schema.columns WHERE table_name = ${tableName} AND column_name = 'deleted_by'`
+          )
+
+          const hasDeletedBy = deletedByCheck.length > 0
+
+          // Restore record by clearing deleted_at and deleted_by (if column exists)
+          const result = hasDeletedBy
+            ? await typedExecute(
+                tx,
+                sql`UPDATE ${tableIdent} SET deleted_at = NULL, deleted_by = NULL WHERE id = ${recordId} RETURNING *`
+              )
+            : await typedExecute(
+                tx,
+                sql`UPDATE ${tableIdent} SET deleted_at = NULL WHERE id = ${recordId} RETURNING *`
+              )
+
+          return result[0] ?? {}
+        }),
+      catch: wrapDatabaseError(`Failed to restore record ${recordId} from ${tableName}`),
+    })
+
+    // Log activity for record restoration (outside transaction)
+    if (restoredRecord && !('_error' in restoredRecord)) {
+      yield* logActivity({
+        session,
+        tableName,
+        action: 'restore',
+        recordId,
+        changes: { after: restoredRecord },
+      })
+    }
+
+    return restoredRecord
+  })
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 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 CRUD operations from modular files
+export { listRecords, computeAggregations, listTrash, getRecord } from './crud-read'
+export {
+  createRecord,
+  updateRecord,
+  deleteRecord,
+  permanentlyDeleteRecord,
+  restoreRecord,
+} from './crud-write'

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

@@ -0,0 +1,11 @@
+/**
+ * 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 table query functions from modular files
+export * from './shared/validation'
+export * from './crud/crud'
+export * from './batch/batch'

package/src/infrastructure/database/table-queries/mutation-helpers/authorship-helpers.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 { typedExecute } from '../shared/typed-execute'
+import type { DrizzleTransaction } from '@/infrastructure/database'
+
+/**
+ * Authorship field names used across the system
+ */
+export const AUTHORSHIP_FIELDS = {
+  CREATED_BY: 'created_by',
+  UPDATED_BY: 'updated_by',
+  DELETED_BY: 'deleted_by',
+} as const
+
+/**
+ * Check if table has specific authorship columns
+ * Queries information_schema once per transaction for efficiency
+ *
+ * @param tx - Database transaction
+ * @param tableName - Table name
+ * @param columnNames - Column names to check
+ * @returns Set of existing column names
+ */
+async function checkAuthorshipColumns(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  columnNames: readonly string[]
+): Promise<Set<string>> {
+  // Query information_schema for column existence
+  const rows = await typedExecute<{ column_name: string }>(
+    tx,
+    sql.raw(
+      `SELECT column_name FROM information_schema.columns WHERE table_name = '${tableName}' AND column_name IN (${columnNames.map((name) => `'${name}'`).join(', ')})`
+    )
+  )
+
+  return new Set(rows.map((row) => row.column_name))
+}
+
+/**
+ * Normalize user ID for database storage
+ * Converts 'guest' to NULL for unauthenticated users
+ *
+ * @param userId - User ID from session
+ * @returns Normalized user ID or NULL for guest users
+ */
+function normalizeUserIdForDb(userId: string | undefined): string | null {
+  // eslint-disable-next-line unicorn/no-null -- NULL is intentional for database columns when no auth configured
+  if (!userId || userId === 'guest') return null
+  return userId
+}
+
+/**
+ * Inject authorship fields into record for INSERT operations
+ * Sets both created_by and updated_by to the same user ID on creation
+ *
+ * @param fields - Original record fields
+ * @param userId - User ID from session
+ * @param tx - Database transaction
+ * @param tableName - Table name
+ * @returns Fields with authorship metadata injected
+ */
+export async function injectCreateAuthorship(
+  fields: Readonly<Record<string, unknown>>,
+  userId: string | undefined,
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string
+): Promise<Record<string, unknown>> {
+  // Check which authorship columns exist
+  const existingColumns = await checkAuthorshipColumns(tx, tableName, [
+    AUTHORSHIP_FIELDS.CREATED_BY,
+    AUTHORSHIP_FIELDS.UPDATED_BY,
+  ])
+
+  // Normalize user ID for database
+  const authorUserId = normalizeUserIdForDb(userId)
+
+  // Build fields object with authorship metadata (immutable)
+  return {
+    ...fields,
+    ...(existingColumns.has(AUTHORSHIP_FIELDS.CREATED_BY)
+      ? { [AUTHORSHIP_FIELDS.CREATED_BY]: authorUserId }
+      : {}),
+    ...(existingColumns.has(AUTHORSHIP_FIELDS.UPDATED_BY)
+      ? { [AUTHORSHIP_FIELDS.UPDATED_BY]: authorUserId }
+      : {}),
+  }
+}
+
+/**
+ * Inject updated_by field for UPDATE operations
+ *
+ * @param fields - Original record fields
+ * @param userId - User ID from session
+ * @param tx - Database transaction
+ * @param tableName - Table name
+ * @returns Fields with updated_by injected
+ */
+export async function injectUpdateAuthorship(
+  fields: Readonly<Record<string, unknown>>,
+  userId: string | undefined,
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string
+): Promise<Record<string, unknown>> {
+  // Check if updated_by column exists
+  const existingColumns = await checkAuthorshipColumns(tx, tableName, [
+    AUTHORSHIP_FIELDS.UPDATED_BY,
+  ])
+
+  const authorUserId = normalizeUserIdForDb(userId)
+
+  return {
+    ...fields,
+    ...(existingColumns.has(AUTHORSHIP_FIELDS.UPDATED_BY)
+      ? { [AUTHORSHIP_FIELDS.UPDATED_BY]: authorUserId }
+      : {}),
+  }
+}
+
+/**
+ * Check if table has deleted_by column for soft delete authorship tracking
+ *
+ * @param tx - Database transaction
+ * @param tableName - Table name
+ * @returns True if deleted_by column exists
+ */
+export async function hasDeletedByColumn(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string
+): Promise<boolean> {
+  const existingColumns = await checkAuthorshipColumns(tx, tableName, [
+    AUTHORSHIP_FIELDS.DELETED_BY,
+  ])
+  return existingColumns.has(AUTHORSHIP_FIELDS.DELETED_BY)
+}
+
+/**
+ * Get normalized user ID for soft delete operations
+ * Returns NULL for guest users, user ID otherwise
+ *
+ * @param userId - User ID from session
+ * @returns Normalized user ID or NULL
+ */
+export function getDeletedByValue(userId: string | undefined): string | null {
+  return normalizeUserIdForDb(userId)
+}

package/src/infrastructure/database/table-queries/mutation-helpers/create-record-helpers.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 {
+  SessionContextError,
+  UniqueConstraintViolationError,
+  type DrizzleTransaction,
+} from '@/infrastructure/database'
+import { validateColumnName } from '../shared/validation'
+
+/**
+ * Shape of PostgreSQL driver error objects that may contain unique constraint info.
+ * Compatible with bun:sql, postgres.js, and pg error objects.
+ */
+interface PostgresErrorLike {
+  readonly code?: string
+  readonly constraint?: string
+  readonly message?: string
+  readonly cause?: PostgresErrorLike
+}
+
+/**
+ * Check if an object has PostgreSQL unique constraint violation markers
+ * (code 23505, constraint name, or 'unique constraint' in message)
+ */
+function hasUniqueViolationMarkers(obj: PostgresErrorLike | null | undefined): boolean {
+  return obj?.code === '23505' || !!obj?.constraint || !!obj?.message?.includes('unique constraint')
+}
+
+/**
+ * Check if an error is a PostgreSQL unique constraint violation (code 23505)
+ * Checks the error itself and its cause for violation markers.
+ */
+export function isUniqueConstraintViolation(error: unknown): boolean {
+  const err = error as PostgresErrorLike | null | undefined
+  return hasUniqueViolationMarkers(err) || hasUniqueViolationMarkers(err?.cause)
+}
+
+/**
+ * Build SQL columns and values for INSERT query
+ */
+export function buildInsertClauses(
+  fields: Readonly<Record<string, unknown>>
+): Readonly<{ columnsClause: unknown; valuesClause: unknown }> {
+  const entries = Object.entries(fields)
+
+  // Build column identifiers and values
+  const columnIdentifiers = entries.map(([key]) => {
+    validateColumnName(key)
+    return sql.identifier(key)
+  })
+  const valueParams = entries.map(([, value]) => sql`${value}`)
+
+  // Build INSERT query using sql.join for columns and values
+  const columnsClause = sql.join(columnIdentifiers, sql.raw(', '))
+  const valuesClause = sql.join(valueParams, sql.raw(', '))
+
+  return { columnsClause, valuesClause }
+}
+
+/**
+ * Execute INSERT query and handle errors
+ */
+export function executeInsert(
+  tableName: string,
+  columnsClause: unknown,
+  valuesClause: unknown,
+  tx: Readonly<DrizzleTransaction>
+): Effect.Effect<Record<string, unknown>, SessionContextError | UniqueConstraintViolationError> {
+  return Effect.tryPromise({
+    try: async () => {
+      const insertResult = (await tx.execute(
+        sql`INSERT INTO ${sql.identifier(tableName)} (${columnsClause}) VALUES (${valuesClause}) RETURNING *`
+      )) as readonly Record<string, unknown>[]
+      return insertResult[0] ?? {}
+    },
+    catch: (error) => {
+      if (isUniqueConstraintViolation(error)) {
+        return new UniqueConstraintViolationError('Unique constraint violation', error)
+      }
+      return new SessionContextError(`Failed to create record in ${tableName}`, error)
+    },
+  })
+}