@dismissible/nestjs-dismissible 0.0.2-canary.5daf195.0

package/src/dismissible.module.ts

@@ -0,0 +1,82 @@
+import { Module, DynamicModule, Type, Provider } from '@nestjs/common';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { GetOrCreateController } from './api/use-cases/get-or-create/get-or-create.controller';
+import { DismissController } from './api/use-cases/dismiss/dismiss.controller';
+import { RestoreController } from './api/use-cases/restore/restore.controller';
+import { DismissibleService } from './core/dismissible.service';
+import { DismissibleCoreService } from './core/dismissible-core.service';
+import { HookRunner } from './core/hook-runner.service';
+import { DismissibleItemMapper } from './api/dismissible-item.mapper';
+import { DateService } from './utils/date/date.service';
+import {
+  DISMISSIBLE_HOOKS,
+  IDismissibleLifecycleHook,
+} from '@dismissible/nestjs-dismissible-hooks';
+import { LoggerModule, IDismissibleLoggerModuleOptions } from '@dismissible/nestjs-logger';
+import { ResponseService, ResponseModule } from './response';
+import { ValidationModule } from '@dismissible/nestjs-validation';
+import { IDismissibleStorageModuleOptions, StorageModule } from '@dismissible/nestjs-storage';
+import { DismissibleHelper } from './utils/dismissible.helper';
+import { DismissibleItemModule } from '@dismissible/nestjs-dismissible-item';
+
+/**
+ * Module configuration options.
+ */
+export type IDismissibleModuleOptions = IDismissibleLoggerModuleOptions &
+  IDismissibleStorageModuleOptions & {
+    hooks?: Type<IDismissibleLifecycleHook>[];
+  };
+
+@Module({})
+export class DismissibleModule {
+  static forRoot(options: IDismissibleModuleOptions): DynamicModule {
+    const providers: Provider[] = [
+      DateService,
+      ResponseService,
+      DismissibleCoreService,
+      HookRunner,
+      DismissibleService,
+      DismissibleItemMapper,
+      DismissibleHelper,
+    ];
+
+    if (options.hooks && options.hooks.length > 0) {
+      for (const hook of options.hooks) {
+        providers.push(hook);
+      }
+
+      providers.push({
+        provide: DISMISSIBLE_HOOKS,
+        useFactory: (...hooks: IDismissibleLifecycleHook[]) => hooks,
+        inject: options.hooks,
+      });
+    } else {
+      providers.push({
+        provide: DISMISSIBLE_HOOKS,
+        useValue: [],
+      });
+    }
+
+    return {
+      module: DismissibleModule,
+      imports: [
+        EventEmitterModule.forRoot(),
+        LoggerModule.forRoot(options),
+        ValidationModule,
+        ResponseModule,
+        options.storage ?? StorageModule,
+        DismissibleItemModule,
+      ],
+      controllers: [GetOrCreateController, DismissController, RestoreController],
+      providers,
+      exports: [
+        DismissibleService,
+        DismissibleCoreService,
+        DismissibleItemMapper,
+        DateService,
+        ResponseService,
+        DISMISSIBLE_HOOKS,
+      ],
+    };
+  }
+}

package/src/events/dismissible.events.ts

@@ -0,0 +1,82 @@
+import { DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+import { IRequestContext } from '@dismissible/nestjs-dismissible-request';
+
+/**
+ * Base class for all dismissible events.
+ */
+abstract class BaseDismissibleEvent {
+  /** The item identifier */
+  readonly id: string;
+
+  /** The current state of the item */
+  readonly item: DismissibleItemDto;
+
+  /** The user identifier */
+  readonly userId: string;
+
+  /** The request context (optional) */
+  readonly context?: IRequestContext;
+
+  constructor(itemId: string, item: DismissibleItemDto, userId: string, context?: IRequestContext) {
+    this.id = itemId;
+    this.item = item;
+    this.userId = userId;
+    this.context = context;
+  }
+}
+
+/**
+ * Event emitted when an existing item is retrieved.
+ */
+export class ItemRetrievedEvent extends BaseDismissibleEvent {
+  constructor(itemId: string, item: DismissibleItemDto, userId: string, context?: IRequestContext) {
+    super(itemId, item, userId, context);
+  }
+}
+
+/**
+ * Event emitted when a new item is created.
+ */
+export class ItemCreatedEvent extends BaseDismissibleEvent {
+  constructor(itemId: string, item: DismissibleItemDto, userId: string, context?: IRequestContext) {
+    super(itemId, item, userId, context);
+  }
+}
+
+/**
+ * Event emitted when an item is dismissed.
+ */
+export class ItemDismissedEvent extends BaseDismissibleEvent {
+  /** The item state before dismissal */
+  readonly previousItem: DismissibleItemDto;
+
+  constructor(
+    itemId: string,
+    item: DismissibleItemDto,
+    previousItem: DismissibleItemDto,
+    userId: string,
+    context?: IRequestContext,
+  ) {
+    super(itemId, item, userId, context);
+    this.previousItem = previousItem;
+  }
+}
+
+/**
+ * Event emitted when a dismissed item is restored.
+ */
+export class ItemRestoredEvent extends BaseDismissibleEvent {
+  /** The item state before restoration */
+  readonly previousItem: DismissibleItemDto;
+
+  constructor(
+    itemId: string,
+    item: DismissibleItemDto,
+    previousItem: DismissibleItemDto,
+    userId: string,
+    context?: IRequestContext,
+  ) {
+    super(itemId, item, userId, context);
+    this.previousItem = previousItem;
+  }
+}

package/src/events/events.constants.ts

@@ -0,0 +1,21 @@
+/**
+ * Event names for dismissible operations.
+ */
+export const DismissibleEvents = {
+  /** Emitted when an existing item is retrieved */
+  ITEM_RETRIEVED: 'dismissible.item.retrieved',
+
+  /** Emitted when a new item is created */
+  ITEM_CREATED: 'dismissible.item.created',
+
+  /** Emitted when an item is dismissed */
+  ITEM_DISMISSED: 'dismissible.item.dismissed',
+
+  /** Emitted when a dismissed item is restored */
+  ITEM_RESTORED: 'dismissible.item.restored',
+} as const;
+
+/**
+ * Type representing all dismissible event names.
+ */
+export type DismissibleEventType = (typeof DismissibleEvents)[keyof typeof DismissibleEvents];

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export * from './events.constants';
+export * from './dismissible.events';

package/src/exceptions/dismissible.exceptions.spec.ts

@@ -0,0 +1,50 @@
+import { HttpStatus } from '@nestjs/common';
+import {
+  ItemNotFoundException,
+  ItemAlreadyDismissedException,
+  ItemNotDismissedException,
+} from './dismissible.exceptions';
+
+describe('Dismissible Exceptions', () => {
+  describe('ItemNotFoundException', () => {
+    it('should create exception with correct structure', () => {
+      const exception = new ItemNotFoundException('test-item');
+
+      expect(exception.getStatus()).toBe(HttpStatus.BAD_REQUEST);
+
+      const response = exception.getResponse() as any;
+      expect(response.statusCode).toBe(HttpStatus.BAD_REQUEST);
+      expect(response.code).toBe('ITEM_NOT_FOUND');
+      expect(response.message).toContain('test-item');
+      expect(response.itemId).toBe('test-item');
+    });
+  });
+
+  describe('ItemAlreadyDismissedException', () => {
+    it('should create exception with correct structure', () => {
+      const exception = new ItemAlreadyDismissedException('test-item');
+
+      expect(exception.getStatus()).toBe(HttpStatus.BAD_REQUEST);
+
+      const response = exception.getResponse() as any;
+      expect(response.statusCode).toBe(HttpStatus.BAD_REQUEST);
+      expect(response.code).toBe('ITEM_ALREADY_DISMISSED');
+      expect(response.message).toContain('test-item');
+      expect(response.itemId).toBe('test-item');
+    });
+  });
+
+  describe('ItemNotDismissedException', () => {
+    it('should create exception with correct structure', () => {
+      const exception = new ItemNotDismissedException('test-item');
+
+      expect(exception.getStatus()).toBe(HttpStatus.BAD_REQUEST);
+
+      const response = exception.getResponse() as any;
+      expect(response.statusCode).toBe(HttpStatus.BAD_REQUEST);
+      expect(response.code).toBe('ITEM_NOT_DISMISSED');
+      expect(response.message).toContain('test-item');
+      expect(response.itemId).toBe('test-item');
+    });
+  });
+});

package/src/exceptions/dismissible.exceptions.ts

@@ -0,0 +1,69 @@
+import { HttpException, HttpStatus } from '@nestjs/common';
+
+/**
+ * Error response structure for dismissible exceptions.
+ */
+interface IDismissibleErrorResponse {
+  statusCode: number;
+  error: string;
+  code: string;
+  message: string;
+  itemId?: string;
+}
+
+/**
+ * Base exception class for dismissible errors.
+ */
+abstract class DismissibleException extends HttpException {
+  constructor(message: string, code: string, statusCode: HttpStatus, itemId?: string) {
+    const response: IDismissibleErrorResponse = {
+      statusCode,
+      error: HttpStatus[statusCode].replace(/_/g, ' '),
+      code,
+      message,
+    };
+
+    if (itemId) {
+      response.itemId = itemId;
+    }
+
+    super(response, statusCode);
+  }
+}
+
+/**
+ * Exception thrown when an item is not found.
+ */
+export class ItemNotFoundException extends DismissibleException {
+  constructor(itemId: string) {
+    super(`Item with id "${itemId}" not found`, 'ITEM_NOT_FOUND', HttpStatus.BAD_REQUEST, itemId);
+  }
+}
+
+/**
+ * Exception thrown when trying to dismiss an already dismissed item.
+ */
+export class ItemAlreadyDismissedException extends DismissibleException {
+  constructor(itemId: string) {
+    super(
+      `Item with id "${itemId}" is already dismissed`,
+      'ITEM_ALREADY_DISMISSED',
+      HttpStatus.BAD_REQUEST,
+      itemId,
+    );
+  }
+}
+
+/**
+ * Exception thrown when trying to restore an item that is not dismissed.
+ */
+export class ItemNotDismissedException extends DismissibleException {
+  constructor(itemId: string) {
+    super(
+      `Item with id "${itemId}" is not dismissed`,
+      'ITEM_NOT_DISMISSED',
+      HttpStatus.BAD_REQUEST,
+      itemId,
+    );
+  }
+}

package/src/exceptions/index.ts

@@ -0,0 +1 @@
+export * from './dismissible.exceptions';

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './dismissible.module';
+export * from './core';
+export * from './api';
+export * from './utils';
+export * from './events';
+export * from './exceptions';
+export * from './testing';
+export * from './validation';

package/src/response/dtos/base-response.dto.ts

@@ -0,0 +1,11 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+/**
+ * Base response DTO that wraps all successful API responses
+ */
+export class BaseResponseDto<T> {
+  @ApiProperty({
+    description: 'Response data',
+  })
+  data: T;
+}

package/src/response/dtos/error-response.dto.ts

@@ -0,0 +1,36 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export type IErrorResponseDto = {
+  error: {
+    message: string;
+    code: number;
+  };
+};
+
+/**
+ * DTO representing error details in API responses
+ */
+export class ErrorDetailsDto {
+  @ApiProperty({
+    description: 'Error message',
+    example: 'Item not found',
+  })
+  message: string;
+
+  @ApiProperty({
+    description: 'HTTP status code',
+    example: 404,
+  })
+  code: number;
+}
+
+/**
+ * DTO for error responses
+ */
+export class ErrorResponseDto implements IErrorResponseDto {
+  @ApiProperty({
+    description: 'Error details',
+    type: ErrorDetailsDto,
+  })
+  error: ErrorDetailsDto;
+}

package/src/response/dtos/index.ts

@@ -0,0 +1,3 @@
+export * from './base-response.dto';
+export * from './error-response.dto';
+export * from './success-response.dto';

package/src/response/dtos/success-response.dto.ts

@@ -0,0 +1,34 @@
+import { Type } from '@nestjs/common';
+import { ApiProperty } from '@nestjs/swagger';
+
+export type ISuccessResponseDto<T> = {
+  data: T;
+};
+
+/**
+ * Factory function to create a success response DTO wrapper.
+ *
+ * This allows wrapping any data class in a consistent `{ data: T }` structure
+ * with proper Swagger documentation.
+ *
+ * @example
+ * ```ts
+ * class UserDto {
+ *   @ApiProperty()
+ *   id: string;
+ *
+ *   @ApiProperty()
+ *   name: string;
+ * }
+ *
+ * export class GetUserResponseDto extends SuccessResponseDto(UserDto) {}
+ * ```
+ */
+export function SuccessResponseDto<T extends Type>(dataClass: T) {
+  class SuccessResponse implements ISuccessResponseDto<T> {
+    @ApiProperty({ type: dataClass })
+    data!: InstanceType<T>;
+  }
+
+  return SuccessResponse;
+}

package/src/response/http-exception-filter.spec.ts

@@ -0,0 +1,179 @@
+import { mock } from 'ts-jest-mocker';
+import { HttpException, HttpStatus, ArgumentsHost } from '@nestjs/common';
+import { FastifyReply } from 'fastify';
+import { HttpExceptionFilter } from './http-exception-filter';
+
+describe('HttpExceptionFilter', () => {
+  let filter: HttpExceptionFilter;
+  let mockArgumentsHost: jest.Mocked<ArgumentsHost>;
+  let mockHttpArgumentsHost: {
+    getResponse: jest.Mock;
+    getRequest: jest.Mock;
+    getNext: jest.Mock;
+  };
+  let mockResponse: jest.Mocked<FastifyReply>;
+
+  beforeEach(() => {
+    filter = new HttpExceptionFilter();
+
+    mockResponse = mock<FastifyReply>({ failIfMockNotProvided: false });
+    mockResponse.status = jest.fn().mockReturnThis();
+    mockResponse.send = jest.fn().mockReturnThis();
+
+    mockHttpArgumentsHost = {
+      getResponse: jest.fn().mockReturnValue(mockResponse),
+      getRequest: jest.fn(),
+      getNext: jest.fn(),
+    };
+
+    mockArgumentsHost = mock<ArgumentsHost>({ failIfMockNotProvided: false });
+    mockArgumentsHost.switchToHttp = jest.fn().mockReturnValue(mockHttpArgumentsHost);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('catch', () => {
+    it('should handle HttpException with 404 status', () => {
+      const exception = new HttpException('Not found', HttpStatus.NOT_FOUND);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockArgumentsHost.switchToHttp).toHaveBeenCalled();
+      expect(mockHttpArgumentsHost.getResponse).toHaveBeenCalled();
+      expect(mockResponse.status).toHaveBeenCalledWith(404);
+      expect(mockResponse.send).toHaveBeenCalledWith({
+        error: {
+          message: 'Not found',
+          code: 404,
+        },
+      });
+    });
+
+    it('should handle HttpException with 400 status', () => {
+      const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockResponse.status).toHaveBeenCalledWith(400);
+      expect(mockResponse.send).toHaveBeenCalledWith({
+        error: {
+          message: 'Bad request',
+          code: 400,
+        },
+      });
+    });
+
+    it('should handle HttpException with 401 status', () => {
+      const exception = new HttpException('Unauthorized', HttpStatus.UNAUTHORIZED);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockResponse.status).toHaveBeenCalledWith(401);
+      expect(mockResponse.send).toHaveBeenCalledWith({
+        error: {
+          message: 'Unauthorized',
+          code: 401,
+        },
+      });
+    });
+
+    it('should handle HttpException with 403 status', () => {
+      const exception = new HttpException('Forbidden', HttpStatus.FORBIDDEN);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockResponse.status).toHaveBeenCalledWith(403);
+      expect(mockResponse.send).toHaveBeenCalledWith({
+        error: {
+          message: 'Forbidden',
+          code: 403,
+        },
+      });
+    });
+
+    it('should handle HttpException with 500 status', () => {
+      const exception = new HttpException(
+        'Internal server error',
+        HttpStatus.INTERNAL_SERVER_ERROR,
+      );
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockResponse.status).toHaveBeenCalledWith(500);
+      expect(mockResponse.send).toHaveBeenCalledWith({
+        error: {
+          message: 'Internal server error',
+          code: 500,
+        },
+      });
+    });
+
+    it('should handle HttpException with custom status code', () => {
+      const exception = new HttpException('Custom error', 418);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockResponse.status).toHaveBeenCalledWith(418);
+      expect(mockResponse.send).toHaveBeenCalledWith({
+        error: {
+          message: 'Custom error',
+          code: 418,
+        },
+      });
+    });
+
+    it('should handle HttpException with empty message', () => {
+      const exception = new HttpException('', HttpStatus.BAD_REQUEST);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockResponse.status).toHaveBeenCalledWith(400);
+      expect(mockResponse.send).toHaveBeenCalledWith({
+        error: {
+          message: '',
+          code: 400,
+        },
+      });
+    });
+
+    it('should handle HttpException with long message', () => {
+      const longMessage =
+        'This is a very long error message that contains multiple words and should be handled correctly by the filter';
+      const exception = new HttpException(longMessage, HttpStatus.BAD_REQUEST);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockResponse.status).toHaveBeenCalledWith(400);
+      expect(mockResponse.send).toHaveBeenCalledWith({
+        error: {
+          message: longMessage,
+          code: 400,
+        },
+      });
+    });
+
+    it('should chain status and send methods correctly', () => {
+      const exception = new HttpException('Test error', HttpStatus.NOT_FOUND);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockResponse.status).toHaveBeenCalled();
+      expect(mockResponse.send).toHaveBeenCalled();
+      expect(mockResponse.status).toHaveReturnedWith(mockResponse);
+      const statusCallOrder = (mockResponse.status as jest.Mock).mock.invocationCallOrder[0];
+      const sendCallOrder = (mockResponse.send as jest.Mock).mock.invocationCallOrder[0];
+      expect(statusCallOrder).toBeLessThan(sendCallOrder);
+    });
+
+    it('should extract response from HTTP context correctly', () => {
+      const exception = new HttpException('Test', HttpStatus.BAD_REQUEST);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockArgumentsHost.switchToHttp).toHaveBeenCalledTimes(1);
+      expect(mockHttpArgumentsHost.getResponse).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/response/http-exception-filter.ts

@@ -0,0 +1,21 @@
+import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
+import { FastifyReply } from 'fastify';
+import { IErrorResponseDto } from './dtos';
+
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  catch(exception: HttpException, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<FastifyReply>();
+    const status = exception.getStatus();
+
+    const errorResponse: IErrorResponseDto = {
+      error: {
+        message: exception.message,
+        code: status,
+      },
+    };
+
+    response.status(status).send(errorResponse);
+  }
+}

package/src/response/index.ts

@@ -0,0 +1,4 @@
+export * from './response.module';
+export * from './response.service';
+export * from './http-exception-filter';
+export * from './dtos';

package/src/response/response.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from '@nestjs/common';
+import { ResponseService } from './response.service';
+
+@Global()
+@Module({
+  providers: [ResponseService],
+  exports: [ResponseService],
+})
+export class ResponseModule {}