From d0be4da56c8fc17548291b920e061affffa12cda Mon Sep 17 00:00:00 2001
From: JohnDoe6345789 <john.doe6345789@gmail.com>
Date: Mon, 29 Dec 2025 22:21:12 +0000
Subject: [PATCH] feat: add error formatting tests and interfaces for
 consistent error handling

---
 .../src/lib/errors/format-error.test.ts       | 67 +++++++++++++++++++
 .../nextjs/src/lib/errors/format-error.ts     | 10 +--
 frontends/nextjs/src/lib/errors/index.ts      |  4 +-
 .../errors/interfaces/api-error-response.ts   |  6 ++
 .../lib/errors/interfaces/formatted-error.ts  |  8 +++
 .../src/lib/errors/interfaces/log-context.ts  |  6 ++
 6 files changed, 92 insertions(+), 9 deletions(-)
 create mode 100644 frontends/nextjs/src/lib/errors/format-error.test.ts
 create mode 100644 frontends/nextjs/src/lib/errors/interfaces/api-error-response.ts
 create mode 100644 frontends/nextjs/src/lib/errors/interfaces/formatted-error.ts
 create mode 100644 frontends/nextjs/src/lib/errors/interfaces/log-context.ts

diff --git a/frontends/nextjs/src/lib/errors/format-error.test.ts b/frontends/nextjs/src/lib/errors/format-error.test.ts
new file mode 100644
index 000000000..a1aedfcc2
--- /dev/null
+++ b/frontends/nextjs/src/lib/errors/format-error.test.ts
@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest'
+import { formatError } from './format-error'
+import { DBALError, DBALErrorCode } from '@/dbal/development/src/core/foundation/errors'
+
+describe('formatError', () => {
+  it.each([
+    {
+      error: new DBALError(DBALErrorCode.NOT_FOUND, 'Resource not found'),
+      expected: {
+        message: 'Resource not found',
+        code: 404,
+        details: undefined,
+      },
+      description: 'DBALError without details',
+    },
+    {
+      error: new DBALError(DBALErrorCode.VALIDATION_ERROR, 'Invalid input', {
+        fields: [{ field: 'email', error: 'Invalid format' }],
+      }),
+      expected: {
+        message: 'Invalid input',
+        code: 422,
+        details: { fields: [{ field: 'email', error: 'Invalid format' }] },
+      },
+      description: 'DBALError with details',
+    },
+    {
+      error: new Error('Standard error'),
+      expected: {
+        message: 'Standard error',
+        stack: expect.any(String),
+      },
+      description: 'Standard Error',
+    },
+    {
+      error: 'String error',
+      expected: {
+        message: 'String error',
+      },
+      description: 'String error',
+    },
+    {
+      error: { message: 'Custom error' },
+      expected: {
+        message: 'Custom error',
+      },
+      description: 'Error-like object',
+    },
+    {
+      error: null,
+      expected: {
+        message: 'An unknown error occurred',
+      },
+      description: 'null',
+    },
+    {
+      error: undefined,
+      expected: {
+        message: 'An unknown error occurred',
+      },
+      description: 'undefined',
+    },
+  ])('should format $description correctly', ({ error, expected }) => {
+    const result = formatError(error)
+    expect(result).toMatchObject(expected)
+  })
+})
diff --git a/frontends/nextjs/src/lib/errors/format-error.ts b/frontends/nextjs/src/lib/errors/format-error.ts
index d5f3a2fe2..0c66b3307 100644
--- a/frontends/nextjs/src/lib/errors/format-error.ts
+++ b/frontends/nextjs/src/lib/errors/format-error.ts
@@ -1,12 +1,6 @@
-import { DBALError, DBALErrorCode } from '@/dbal/development/src/core/foundation/errors'
+import { DBALError } from '@/dbal/core/foundation/errors'
 import { getErrorMessage, isError } from '@/lib/types/guards'
-
-export interface FormattedError {
-  message: string
-  code?: DBALErrorCode | number
-  stack?: string
-  details?: Record<string, unknown>
-}
+import type { FormattedError } from './interfaces/formatted-error'
 
 /**
  * Format any error into a consistent structure
diff --git a/frontends/nextjs/src/lib/errors/index.ts b/frontends/nextjs/src/lib/errors/index.ts
index baae8d32c..cd8d0ed42 100644
--- a/frontends/nextjs/src/lib/errors/index.ts
+++ b/frontends/nextjs/src/lib/errors/index.ts
@@ -1,6 +1,8 @@
-export { formatError, toUserMessage } from './format-error'
+export { formatError } from './format-error'
 export type { FormattedError } from './format-error'
 
+export { toUserMessage } from './to-user-message'
+
 export { handleAPIError } from './handle-api-error'
 export type { APIErrorResponse } from './handle-api-error'
 
diff --git a/frontends/nextjs/src/lib/errors/interfaces/api-error-response.ts b/frontends/nextjs/src/lib/errors/interfaces/api-error-response.ts
new file mode 100644
index 000000000..3519edad5
--- /dev/null
+++ b/frontends/nextjs/src/lib/errors/interfaces/api-error-response.ts
@@ -0,0 +1,6 @@
+export interface APIErrorResponse {
+  error: string
+  code?: number
+  details?: Record<string, unknown>
+  timestamp?: string
+}
diff --git a/frontends/nextjs/src/lib/errors/interfaces/formatted-error.ts b/frontends/nextjs/src/lib/errors/interfaces/formatted-error.ts
new file mode 100644
index 000000000..b2094f1c9
--- /dev/null
+++ b/frontends/nextjs/src/lib/errors/interfaces/formatted-error.ts
@@ -0,0 +1,8 @@
+import type { DBALErrorCode } from '@/dbal/development/src/core/foundation/errors'
+
+export interface FormattedError {
+  message: string
+  code?: DBALErrorCode | number
+  stack?: string
+  details?: Record<string, unknown>
+}
diff --git a/frontends/nextjs/src/lib/errors/interfaces/log-context.ts b/frontends/nextjs/src/lib/errors/interfaces/log-context.ts
new file mode 100644
index 000000000..18525dcb8
--- /dev/null
+++ b/frontends/nextjs/src/lib/errors/interfaces/log-context.ts
@@ -0,0 +1,6 @@
+export interface LogContext {
+  component?: string
+  userId?: string
+  action?: string
+  [key: string]: unknown
+}