@nextrush/errors 3.0.0

package/src/__tests__/middleware.test.ts

@@ -0,0 +1,385 @@
+/**
+ * @nextrush/errors - Middleware Tests
+ */
+
+import type { Context } from '@nextrush/types';
+import { describe, expect, it, vi } from 'vitest';
+import { BadRequestError, InternalServerError, NotFoundError } from '../http-errors';
+import { catchAsync, errorHandler, notFoundHandler } from '../middleware';
+
+function createMockContext(): Context {
+  const ctx = {
+    method: 'GET',
+    url: '/test',
+    path: '/test',
+    query: {},
+    headers: {},
+    ip: '127.0.0.1',
+    body: undefined,
+    params: {},
+    status: 200,
+    json: vi.fn(),
+    send: vi.fn(),
+    html: vi.fn(),
+    redirect: vi.fn(),
+    set: vi.fn(),
+    get: vi.fn(),
+    next: vi.fn().mockResolvedValue(undefined),
+    state: {},
+    responded: false,
+    raw: { req: {} as never, res: {} as never },
+  } as unknown as Context;
+  return ctx;
+}
+
+const noop = async (): Promise<void> => {};
+
+describe('errorHandler', () => {
+  describe('basic functionality', () => {
+    it('should pass through when no error', async () => {
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        ctx.json({ ok: true });
+      });
+
+      expect(ctx.json).toHaveBeenCalledWith({ ok: true });
+    });
+
+    it('should catch and handle HttpError', async () => {
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new NotFoundError('User not found');
+      });
+
+      expect(ctx.status).toBe(404);
+      expect(ctx.json).toHaveBeenCalledWith({
+        error: 'NotFoundError',
+        message: 'User not found',
+        code: 'NOT_FOUND',
+        status: 404,
+      });
+    });
+
+    it('should catch and handle regular Error', async () => {
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new Error('Something went wrong');
+      });
+
+      expect(ctx.status).toBe(500);
+      expect(ctx.json).toHaveBeenCalledWith({
+        error: 'Internal Server Error',
+        message: 'Internal Server Error',
+        code: 'INTERNAL_ERROR',
+        status: 500,
+      });
+    });
+
+    it('should handle non-Error thrown values', async () => {
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw 'string error';
+      });
+
+      expect(ctx.status).toBe(500);
+      expect(ctx.json).toHaveBeenCalled();
+    });
+  });
+
+  describe('includeStack option', () => {
+    it('should include stack when enabled', async () => {
+      const handler = errorHandler({ includeStack: true });
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new BadRequestError('Invalid');
+      });
+
+      const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+      expect(jsonCall.stack).toBeDefined();
+      expect(Array.isArray(jsonCall.stack)).toBe(true);
+    });
+
+    it('should not include stack by default', async () => {
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new BadRequestError('Invalid');
+      });
+
+      const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+      expect(jsonCall.stack).toBeUndefined();
+    });
+  });
+
+  describe('logger option', () => {
+    it('should call custom logger', async () => {
+      const logger = vi.fn();
+      const handler = errorHandler({ logger });
+      const ctx = createMockContext();
+      const error = new NotFoundError('Not found');
+
+      await handler(ctx, async () => {
+        throw error;
+      });
+
+      expect(logger).toHaveBeenCalledWith(error, ctx);
+    });
+
+    it('should use default logger', async () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new NotFoundError('Not found');
+      });
+
+      expect(consoleSpy).toHaveBeenCalled();
+      consoleSpy.mockRestore();
+    });
+
+    it('should log 5xx errors as error level', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new InternalServerError('Server error');
+      });
+
+      expect(consoleSpy).toHaveBeenCalled();
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe('transform option', () => {
+    it('should use custom transform', async () => {
+      const transform = vi.fn().mockReturnValue({ customError: true });
+      const handler = errorHandler({ transform });
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new BadRequestError('Invalid');
+      });
+
+      expect(transform).toHaveBeenCalled();
+      expect(ctx.json).toHaveBeenCalledWith({ customError: true });
+    });
+  });
+
+  describe('handlers option', () => {
+    it('should use custom handler for specific error type', async () => {
+      const customHandler = vi.fn();
+      const handlers = new Map<
+        new (...args: unknown[]) => Error,
+        (error: Error, ctx: Context) => void
+      >([[NotFoundError as unknown as new (...args: unknown[]) => Error, customHandler]]);
+      const handler = errorHandler({ handlers });
+      const ctx = createMockContext();
+      const error = new NotFoundError('Not found');
+
+      await handler(ctx, async () => {
+        throw error;
+      });
+
+      expect(customHandler).toHaveBeenCalledWith(error, ctx);
+      expect(ctx.json).not.toHaveBeenCalled();
+    });
+
+    it('should fall back to default for unhandled types', async () => {
+      const customHandler = vi.fn();
+      const handlers = new Map<
+        new (...args: unknown[]) => Error,
+        (error: Error, ctx: Context) => void
+      >([[NotFoundError as unknown as new (...args: unknown[]) => Error, customHandler]]);
+      const handler = errorHandler({ handlers });
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new BadRequestError('Invalid');
+      });
+
+      expect(customHandler).not.toHaveBeenCalled();
+      expect(ctx.json).toHaveBeenCalled();
+    });
+  });
+
+  describe('error details', () => {
+    it('should include details for exposed errors', async () => {
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new BadRequestError('Invalid', { details: { field: 'email' } });
+      });
+
+      const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+      expect(jsonCall.details).toEqual({ field: 'email' });
+    });
+
+    it('should not include details for non-exposed errors', async () => {
+      const handler = errorHandler();
+      const ctx = createMockContext();
+
+      await handler(ctx, async () => {
+        throw new InternalServerError('Error');
+      });
+
+      const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+      expect(jsonCall.details).toBeUndefined();
+    });
+  });
+});
+
+describe('notFoundHandler', () => {
+  it('should return 404 response', async () => {
+    const handler = notFoundHandler();
+    const ctx = createMockContext();
+    ctx.status = 404;
+
+    await handler(ctx, noop);
+
+    expect(ctx.status).toBe(404);
+    expect(ctx.json).toHaveBeenCalledWith({
+      error: 'NotFoundError',
+      message: 'Not Found',
+      code: 'NOT_FOUND',
+      status: 404,
+    });
+  });
+
+  it('should accept custom message', async () => {
+    const handler = notFoundHandler('Resource does not exist');
+    const ctx = createMockContext();
+    ctx.status = 404;
+
+    await handler(ctx, noop);
+
+    expect(ctx.json).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'Resource does not exist' })
+    );
+  });
+
+  it('should not handle 200 status (response was sent)', async () => {
+    const handler = notFoundHandler();
+    const ctx = createMockContext();
+    ctx.status = 200;
+
+    await handler(ctx, noop);
+
+    expect(ctx.status).toBe(200);
+    expect(ctx.json).not.toHaveBeenCalled();
+  });
+
+  it('should handle 404 status', async () => {
+    const handler = notFoundHandler();
+    const ctx = createMockContext();
+    ctx.status = 404;
+
+    await handler(ctx, noop);
+
+    expect(ctx.json).toHaveBeenCalled();
+  });
+
+  it('should not override non-404/200 status', async () => {
+    const handler = notFoundHandler();
+    const ctx = createMockContext();
+    ctx.status = 201;
+
+    await handler(ctx, noop);
+
+    expect(ctx.status).toBe(201);
+    expect(ctx.json).not.toHaveBeenCalled();
+  });
+});
+
+describe('catchAsync', () => {
+  it('should pass through successful handlers', async () => {
+    const innerHandler = vi.fn().mockResolvedValue(undefined);
+    const handler = catchAsync(innerHandler);
+    const ctx = createMockContext();
+
+    await handler(ctx, noop);
+
+    expect(innerHandler).toHaveBeenCalledWith(ctx, noop);
+  });
+
+  it('should re-throw errors', async () => {
+    const error = new NotFoundError('Not found');
+    const innerHandler = vi.fn().mockRejectedValue(error);
+    const handler = catchAsync(innerHandler);
+    const ctx = createMockContext();
+
+    await expect(handler(ctx, noop)).rejects.toThrow(error);
+  });
+
+  it('should pass next to inner handler', async () => {
+    const innerHandler = vi.fn().mockResolvedValue(undefined);
+    const handler = catchAsync(innerHandler);
+    const ctx = createMockContext();
+    const next = vi.fn();
+
+    await handler(ctx, next);
+
+    expect(innerHandler).toHaveBeenCalledWith(ctx, next);
+  });
+});
+
+describe('Integration scenarios', () => {
+  it('should work with errorHandler and notFoundHandler together', async () => {
+    const errHandler = errorHandler();
+    const notFoundHdlr = notFoundHandler();
+    const ctx = createMockContext();
+    ctx.status = 404;
+
+    await errHandler(ctx, async () => {
+      await notFoundHdlr(ctx, noop);
+    });
+
+    expect(ctx.status).toBe(404);
+    expect(ctx.json).toHaveBeenCalledWith(expect.objectContaining({ code: 'NOT_FOUND' }));
+  });
+
+  it('should handle thrown NotFoundError in route', async () => {
+    const errHandler = errorHandler();
+    const ctx = createMockContext();
+
+    await errHandler(ctx, async () => {
+      throw new NotFoundError('User with ID 123 not found');
+    });
+
+    expect(ctx.status).toBe(404);
+    expect(ctx.json).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'User with ID 123 not found' })
+    );
+  });
+
+  it('should handle validation errors with details', async () => {
+    const errHandler = errorHandler();
+    const ctx = createMockContext();
+
+    await errHandler(ctx, async () => {
+      throw new BadRequestError('Validation failed', {
+        details: {
+          issues: [
+            { path: 'email', message: 'Invalid email' },
+            { path: 'name', message: 'Name is required' },
+          ],
+        },
+      });
+    });
+
+    const jsonCall = (ctx.json as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(jsonCall.details.issues).toHaveLength(2);
+  });
+});

package/src/__tests__/validation.test.ts

@@ -0,0 +1,315 @@
+/**
+ * @nextrush/errors - Validation Error Tests
+ */
+
+import { describe, expect, it } from 'vitest';
+import { NextRushError } from '../base';
+import {
+  InvalidEmailError,
+  InvalidUrlError,
+  LengthError,
+  PatternError,
+  RangeValidationError,
+  RequiredFieldError,
+  TypeMismatchError,
+  ValidationError,
+} from '../validation';
+
+describe('ValidationError', () => {
+  describe('constructor', () => {
+    it('should create error with issues', () => {
+      const issues = [
+        { path: 'email', message: 'Invalid email' },
+        { path: 'name', message: 'Name is required' },
+      ];
+      const error = new ValidationError(issues);
+
+      expect(error.status).toBe(400);
+      expect(error.code).toBe('VALIDATION_ERROR');
+      expect(error.expose).toBe(true);
+      expect(error.issues).toEqual(issues);
+      expect(error.message).toBe('Validation failed');
+    });
+
+    it('should accept custom message', () => {
+      const error = new ValidationError(
+        [{ path: 'field', message: 'error' }],
+        'Form validation failed'
+      );
+      expect(error.message).toBe('Form validation failed');
+    });
+
+    it('should be instanceof NextRushError', () => {
+      const error = new ValidationError([{ path: 'field', message: 'error' }]);
+      expect(error).toBeInstanceOf(NextRushError);
+      expect(error).toBeInstanceOf(Error);
+    });
+
+    it('should store issues as canonical source without duplicating in details', () => {
+      const issues = [{ path: 'email', message: 'Invalid' }];
+      const error = new ValidationError(issues);
+      expect(error.issues).toEqual(issues);
+      expect(error.details).toBeUndefined();
+    });
+  });
+
+  describe('fromField', () => {
+    it('should create error from single field', () => {
+      const error = ValidationError.fromField('email', 'Invalid email format', 'email');
+
+      expect(error.issues).toHaveLength(1);
+      expect(error.issues[0]).toEqual({
+        path: 'email',
+        message: 'Invalid email format',
+        rule: 'email',
+      });
+    });
+
+    it('should work without rule', () => {
+      const error = ValidationError.fromField('name', 'Name is required');
+      expect(error.issues[0].rule).toBeUndefined();
+    });
+  });
+
+  describe('fromFields', () => {
+    it('should create error from multiple fields', () => {
+      const error = ValidationError.fromFields({
+        email: 'Invalid email',
+        name: 'Name is required',
+        age: 'Must be at least 18',
+      });
+
+      expect(error.issues).toHaveLength(3);
+      expect(error.issues[0].path).toBe('email');
+      expect(error.issues[1].path).toBe('name');
+      expect(error.issues[2].path).toBe('age');
+    });
+  });
+
+  describe('hasErrorFor', () => {
+    it('should return true if field has errors', () => {
+      const error = new ValidationError([
+        { path: 'email', message: 'Invalid' },
+        { path: 'name', message: 'Required' },
+      ]);
+
+      expect(error.hasErrorFor('email')).toBe(true);
+      expect(error.hasErrorFor('name')).toBe(true);
+      expect(error.hasErrorFor('age')).toBe(false);
+    });
+  });
+
+  describe('getErrorsFor', () => {
+    it('should return errors for specific field', () => {
+      const error = new ValidationError([
+        { path: 'email', message: 'Invalid format' },
+        { path: 'email', message: 'Already exists' },
+        { path: 'name', message: 'Required' },
+      ]);
+
+      const emailErrors = error.getErrorsFor('email');
+      expect(emailErrors).toHaveLength(2);
+      expect(emailErrors[0].message).toBe('Invalid format');
+      expect(emailErrors[1].message).toBe('Already exists');
+    });
+
+    it('should return empty array if no errors', () => {
+      const error = new ValidationError([{ path: 'email', message: 'Invalid' }]);
+      expect(error.getErrorsFor('name')).toEqual([]);
+    });
+  });
+
+  describe('getFirstError', () => {
+    it('should return first error message for field', () => {
+      const error = new ValidationError([
+        { path: 'email', message: 'First error' },
+        { path: 'email', message: 'Second error' },
+      ]);
+
+      expect(error.getFirstError('email')).toBe('First error');
+    });
+
+    it('should return undefined if no errors', () => {
+      const error = new ValidationError([{ path: 'email', message: 'Invalid' }]);
+      expect(error.getFirstError('name')).toBeUndefined();
+    });
+  });
+
+  describe('toFlatObject', () => {
+    it('should convert to flat object', () => {
+      const error = new ValidationError([
+        { path: 'email', message: 'Invalid' },
+        { path: 'name', message: 'Required' },
+      ]);
+
+      expect(error.toFlatObject()).toEqual({
+        email: 'Invalid',
+        name: 'Required',
+      });
+    });
+
+    it('should use first error for duplicate fields', () => {
+      const error = new ValidationError([
+        { path: 'email', message: 'First' },
+        { path: 'email', message: 'Second' },
+      ]);
+
+      expect(error.toFlatObject()).toEqual({ email: 'First' });
+    });
+  });
+
+  describe('toJSON', () => {
+    it('should include issues in JSON', () => {
+      const issues = [{ path: 'email', message: 'Invalid' }];
+      const error = new ValidationError(issues);
+      const json = error.toJSON();
+
+      expect(json).toEqual({
+        error: 'ValidationError',
+        message: 'Validation failed',
+        code: 'VALIDATION_ERROR',
+        status: 400,
+        issues,
+      });
+    });
+  });
+});
+
+describe('RequiredFieldError', () => {
+  it('should create required field error', () => {
+    const error = new RequiredFieldError('name');
+
+    expect(error.status).toBe(400);
+    expect(error.message).toBe('name is required');
+    expect(error.issues).toHaveLength(1);
+    expect(error.issues[0]).toEqual({
+      path: 'name',
+      message: 'name is required',
+      rule: 'required',
+    });
+  });
+});
+
+describe('TypeMismatchError', () => {
+  it('should create type mismatch error', () => {
+    const error = new TypeMismatchError('age', 'number', 'string');
+
+    expect(error.status).toBe(400);
+    expect(error.message).toBe('age must be of type number');
+    expect(error.issues[0]).toEqual({
+      path: 'age',
+      message: 'Expected number, received string',
+      rule: 'type',
+      expected: 'number',
+      received: 'string',
+    });
+  });
+});
+
+describe('RangeValidationError', () => {
+  it('should create range error with min', () => {
+    const error = new RangeValidationError('age', 18);
+    expect(error.message).toBe('age must be at least 18');
+  });
+
+  it('should create range error with max', () => {
+    const error = new RangeValidationError('quantity', undefined, 100);
+    expect(error.message).toBe('quantity must be at most 100');
+  });
+
+  it('should create range error with min and max', () => {
+    const error = new RangeValidationError('rating', 1, 5);
+    expect(error.message).toBe('rating must be at least 1 and at most 5');
+    expect(error.issues[0].expected).toEqual({ min: 1, max: 5 });
+  });
+});
+
+describe('LengthError', () => {
+  it('should create length error with min', () => {
+    const error = new LengthError('password', 8);
+    expect(error.message).toBe('password must be at least 8 characters');
+  });
+
+  it('should create length error with max', () => {
+    const error = new LengthError('username', undefined, 20);
+    expect(error.message).toBe('username must be at most 20 characters');
+  });
+
+  it('should create length error with min and max', () => {
+    const error = new LengthError('bio', 10, 500);
+    expect(error.message).toBe('bio must be at least 10 characters and at most 500 characters');
+  });
+});
+
+describe('PatternError', () => {
+  it('should create pattern error with default message', () => {
+    const error = new PatternError('phone', '^\\d{10}$');
+
+    expect(error.message).toBe('phone does not match required pattern');
+    expect(error.issues[0].expected).toBe('^\\d{10}$');
+    expect(error.issues[0].rule).toBe('pattern');
+  });
+
+  it('should create pattern error with custom message', () => {
+    const error = new PatternError('phone', '^\\d{10}$', 'Phone must be 10 digits');
+    expect(error.message).toBe('Phone must be 10 digits');
+  });
+});
+
+describe('InvalidEmailError', () => {
+  it('should create email error with default field', () => {
+    const error = new InvalidEmailError();
+
+    expect(error.message).toBe('Invalid email address');
+    expect(error.issues[0].path).toBe('email');
+    expect(error.issues[0].rule).toBe('email');
+  });
+
+  it('should create email error with custom field', () => {
+    const error = new InvalidEmailError('contactEmail');
+    expect(error.issues[0].path).toBe('contactEmail');
+  });
+});
+
+describe('InvalidUrlError', () => {
+  it('should create URL error with default field', () => {
+    const error = new InvalidUrlError();
+
+    expect(error.message).toBe('Invalid URL');
+    expect(error.issues[0].path).toBe('url');
+    expect(error.issues[0].rule).toBe('url');
+  });
+
+  it('should create URL error with custom field', () => {
+    const error = new InvalidUrlError('website');
+    expect(error.issues[0].path).toBe('website');
+  });
+});
+
+describe('Complex validation scenarios', () => {
+  it('should handle nested field paths', () => {
+    const error = new ValidationError([
+      { path: 'user.address.city', message: 'City is required' },
+      { path: 'user.address.zipCode', message: 'Invalid zip code' },
+      { path: 'items[0].quantity', message: 'Quantity must be positive' },
+    ]);
+
+    expect(error.hasErrorFor('user.address.city')).toBe(true);
+    expect(error.hasErrorFor('items[0].quantity')).toBe(true);
+  });
+
+  it('should handle issues with all properties', () => {
+    const error = new ValidationError([
+      {
+        path: 'age',
+        message: 'Age must be between 18 and 120',
+        rule: 'range',
+        expected: { min: 18, max: 120 },
+        received: 150,
+      },
+    ]);
+
+    expect(error.issues[0].expected).toEqual({ min: 18, max: 120 });
+    expect(error.issues[0].received).toBe(150);
+  });
+});