@dismissible/nestjs-dismissible 0.0.2-canary.6b97aa7.0

package/src/core/dismissible.service.spec.ts

@@ -0,0 +1,226 @@
+import { mock } from 'ts-jest-mocker';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { DismissibleService } from './dismissible.service';
+import { DismissibleCoreService } from './dismissible-core.service';
+import { HookRunner, IHookRunResult } from './hook-runner.service';
+import { IDismissibleLogger } from '@dismissible/nestjs-logger';
+import { ValidationService } from '@dismissible/nestjs-validation';
+import { DismissibleEvents } from '../events';
+import { createTestItem, createTestContext } from '../testing/factories';
+
+describe('DismissibleService', () => {
+  let service: DismissibleService;
+  let mockCoreService: jest.Mocked<DismissibleCoreService>;
+  let mockHookRunner: jest.Mocked<HookRunner>;
+  let mockEventEmitter: jest.Mocked<EventEmitter2>;
+  let mockLogger: jest.Mocked<IDismissibleLogger>;
+  let mockValidationService: jest.Mocked<ValidationService>;
+
+  const testUserId = 'test-user-id';
+
+  const createHookResult = (id: string, userId = testUserId): IHookRunResult => ({
+    proceed: true,
+    id,
+    userId,
+    context: createTestContext(),
+  });
+
+  beforeEach(() => {
+    mockCoreService = mock(DismissibleCoreService, { failIfMockNotProvided: false });
+    mockHookRunner = mock(HookRunner, { failIfMockNotProvided: false });
+    mockEventEmitter = mock(EventEmitter2, { failIfMockNotProvided: false });
+    mockLogger = mock<IDismissibleLogger>({ failIfMockNotProvided: false });
+    mockValidationService = mock(ValidationService, { failIfMockNotProvided: false });
+
+    mockValidationService.validateDto.mockResolvedValue({} as never);
+
+    service = new DismissibleService(
+      mockCoreService,
+      mockHookRunner,
+      mockEventEmitter,
+      mockLogger,
+      mockValidationService,
+    );
+  });
+
+  describe('getOrCreate', () => {
+    it('should run request and get hooks for existing item', async () => {
+      const item = createTestItem({ id: 'existing-item' });
+      const context = createTestContext();
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('existing-item'));
+      mockHookRunner.runPreGet.mockResolvedValue(createHookResult('existing-item'));
+      mockCoreService.get.mockResolvedValue(item);
+
+      const result = await service.getOrCreate('existing-item', testUserId, context);
+
+      expect(mockHookRunner.runPreRequest).toHaveBeenCalled();
+      expect(mockCoreService.get).toHaveBeenCalledWith('existing-item', testUserId);
+      expect(mockHookRunner.runPreGet).toHaveBeenCalledWith(
+        'existing-item',
+        item,
+        testUserId,
+        expect.anything(),
+      );
+      expect(mockHookRunner.runPostGet).toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).toHaveBeenCalled();
+      expect(mockCoreService.create).not.toHaveBeenCalled();
+      expect(mockHookRunner.runPreCreate).not.toHaveBeenCalled();
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        DismissibleEvents.ITEM_RETRIEVED,
+        expect.anything(),
+      );
+      expect(result.created).toBe(false);
+    });
+
+    it('should run pre-create hooks BEFORE creating for new item', async () => {
+      const item = createTestItem({ id: 'new-item' });
+      const context = createTestContext();
+      const callOrder: string[] = [];
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('new-item'));
+      mockCoreService.get.mockResolvedValue(null);
+      mockHookRunner.runPreCreate.mockImplementation(async () => {
+        callOrder.push('runPreCreate');
+        return createHookResult('new-item');
+      });
+      mockCoreService.create.mockImplementation(async () => {
+        callOrder.push('create');
+        return item;
+      });
+
+      const result = await service.getOrCreate('new-item', testUserId, context);
+
+      expect(callOrder).toEqual(['runPreCreate', 'create']);
+      expect(mockHookRunner.runPreRequest).toHaveBeenCalled();
+      expect(mockHookRunner.runPreCreate).toHaveBeenCalled();
+      expect(mockCoreService.create).toHaveBeenCalledWith('new-item', testUserId);
+      expect(mockHookRunner.runPostCreate).toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).toHaveBeenCalled();
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        DismissibleEvents.ITEM_CREATED,
+        expect.anything(),
+      );
+      expect(result.created).toBe(true);
+    });
+
+    it('should NOT create item when pre-create hook blocks the operation', async () => {
+      const context = createTestContext();
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('new-item'));
+      mockCoreService.get.mockResolvedValue(null);
+      mockHookRunner.runPreCreate.mockResolvedValue({
+        proceed: false,
+        reason: 'Plan limit reached',
+        id: 'new-item',
+        userId: testUserId,
+        context: createTestContext(),
+      });
+
+      await expect(service.getOrCreate('new-item', testUserId, context)).rejects.toThrow();
+
+      expect(mockCoreService.create).not.toHaveBeenCalled();
+      expect(mockHookRunner.runPostCreate).not.toHaveBeenCalled();
+      expect(mockEventEmitter.emit).not.toHaveBeenCalledWith(
+        DismissibleEvents.ITEM_CREATED,
+        expect.anything(),
+      );
+    });
+
+    it('should NOT return existing item when pre-get hook blocks the operation', async () => {
+      const item = createTestItem({ id: 'existing-item' });
+      const context = createTestContext();
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('existing-item'));
+      mockCoreService.get.mockResolvedValue(item);
+      mockHookRunner.runPreGet.mockResolvedValue({
+        proceed: false,
+        reason: 'Item access denied',
+        id: 'existing-item',
+        userId: testUserId,
+        context: createTestContext(),
+      });
+
+      await expect(service.getOrCreate('existing-item', testUserId, context)).rejects.toThrow();
+
+      expect(mockHookRunner.runPostGet).not.toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).not.toHaveBeenCalled();
+      expect(mockEventEmitter.emit).not.toHaveBeenCalledWith(
+        DismissibleEvents.ITEM_RETRIEVED,
+        expect.anything(),
+      );
+    });
+  });
+
+  describe('dismiss', () => {
+    it('should run hooks, call core service, and emit ITEM_DISMISSED event', async () => {
+      const item = createTestItem({ id: 'test-item' });
+      const previousItem = createTestItem({ id: 'test-item' });
+      const context = createTestContext();
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('test-item'));
+      mockHookRunner.runPreDismiss.mockResolvedValue(createHookResult('test-item'));
+      mockCoreService.dismiss.mockResolvedValue({ item, previousItem });
+
+      const result = await service.dismiss('test-item', testUserId, context);
+
+      expect(mockHookRunner.runPreRequest).toHaveBeenCalled();
+      expect(mockHookRunner.runPreDismiss).toHaveBeenCalled();
+      expect(mockCoreService.dismiss).toHaveBeenCalledWith('test-item', testUserId);
+      expect(mockHookRunner.runPostDismiss).toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).toHaveBeenCalled();
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        DismissibleEvents.ITEM_DISMISSED,
+        expect.anything(),
+      );
+      expect(result.item).toEqual(item);
+    });
+  });
+
+  describe('restore', () => {
+    it('should run hooks, call core service, and emit ITEM_RESTORED event', async () => {
+      const item = createTestItem({ id: 'test-item' });
+      const previousItem = createTestItem({ id: 'test-item' });
+      const context = createTestContext();
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('test-item'));
+      mockHookRunner.runPreRestore.mockResolvedValue(createHookResult('test-item'));
+      mockCoreService.restore.mockResolvedValue({ item, previousItem });
+
+      const result = await service.restore('test-item', testUserId, context);
+
+      expect(mockHookRunner.runPreRequest).toHaveBeenCalled();
+      expect(mockHookRunner.runPreRestore).toHaveBeenCalled();
+      expect(mockCoreService.restore).toHaveBeenCalledWith('test-item', testUserId);
+      expect(mockHookRunner.runPostRestore).toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).toHaveBeenCalled();
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        DismissibleEvents.ITEM_RESTORED,
+        expect.anything(),
+      );
+      expect(result.item).toEqual(item);
+    });
+  });
+
+  describe('logging', () => {
+    it('should log debug messages for operations', async () => {
+      const item = createTestItem({ id: 'test-item' });
+      const context = createTestContext();
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('test-item'));
+      mockHookRunner.runPreGet.mockResolvedValue(createHookResult('test-item'));
+      mockCoreService.get.mockResolvedValue(item);
+
+      await service.getOrCreate('test-item', testUserId, context);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        expect.stringContaining('getOrCreate called'),
+        expect.any(Object),
+      );
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        expect.stringContaining('getOrCreate completed'),
+        expect.any(Object),
+      );
+    });
+  });
+});

package/src/core/dismissible.service.ts

@@ -0,0 +1,227 @@
+import { Injectable, Inject } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { DismissibleCoreService } from './dismissible-core.service';
+import { HookRunner } from './hook-runner.service';
+import { DISMISSIBLE_LOGGER, IDismissibleLogger } from '@dismissible/nestjs-logger';
+import {
+  IGetOrCreateServiceResponse,
+  IDismissServiceResponse,
+  IRestoreServiceResponse,
+} from './service-responses.interface';
+import { IRequestContext } from '../request/request-context.interface';
+import { DismissibleEvents } from '../events';
+import {
+  ItemCreatedEvent,
+  ItemRetrievedEvent,
+  ItemDismissedEvent,
+  ItemRestoredEvent,
+} from '../events';
+import { ValidationService } from '@dismissible/nestjs-validation';
+import { DismissibleInputDto } from '../validation';
+
+/**
+ * Main orchestration service for dismissible operations.
+ * Coordinates core logic, hooks, and events.
+ */
+@Injectable()
+export class DismissibleService {
+  constructor(
+    private readonly coreService: DismissibleCoreService,
+    private readonly hookRunner: HookRunner,
+    private readonly eventEmitter: EventEmitter2,
+    @Inject(DISMISSIBLE_LOGGER)
+    private readonly logger: IDismissibleLogger,
+    private readonly validationService: ValidationService,
+  ) {}
+
+  /**
+   * Validates input parameters for all service methods.
+   * Provides defense in depth when the service is used directly without controllers.
+   */
+  private async validateInput(itemId: string, userId: string): Promise<void> {
+    await this.validationService.validateDto(DismissibleInputDto, { itemId, userId });
+  }
+
+  /**
+   * Get an existing item or create a new one.
+   * @param itemId The item identifier
+   * @param userId The user identifier (required)
+   * @param context Optional request context for tracing
+   */
+  async getOrCreate(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IGetOrCreateServiceResponse> {
+    this.logger.debug(`getOrCreate called`, { itemId, userId });
+
+    await this.validateInput(itemId, userId);
+
+    const preResult = await this.hookRunner.runPreRequest(itemId, userId, context);
+    HookRunner.throwIfBlocked(preResult);
+
+    const resolvedId = preResult.id;
+    const resolvedUserId = preResult.userId;
+    const resolvedContext = preResult.context;
+
+    const existingItem = await this.coreService.get(resolvedId, resolvedUserId);
+
+    if (existingItem) {
+      const preGetResult = await this.hookRunner.runPreGet(
+        resolvedId,
+        existingItem,
+        resolvedUserId,
+        resolvedContext,
+      );
+      HookRunner.throwIfBlocked(preGetResult);
+
+      this.eventEmitter.emit(
+        DismissibleEvents.ITEM_RETRIEVED,
+        new ItemRetrievedEvent(resolvedId, existingItem, resolvedUserId, resolvedContext),
+      );
+
+      await this.hookRunner.runPostGet(resolvedId, existingItem, resolvedUserId, resolvedContext);
+
+      await this.hookRunner.runPostRequest(
+        resolvedId,
+        existingItem,
+        resolvedUserId,
+        resolvedContext,
+      );
+
+      this.logger.debug(`getOrCreate completed`, { itemId, created: false });
+
+      return {
+        item: existingItem,
+        created: false,
+      };
+    }
+
+    const preCreateResult = await this.hookRunner.runPreCreate(
+      resolvedId,
+      resolvedUserId,
+      resolvedContext,
+    );
+    HookRunner.throwIfBlocked(preCreateResult);
+
+    const createdItem = await this.coreService.create(resolvedId, resolvedUserId);
+
+    await this.hookRunner.runPostCreate(resolvedId, createdItem, resolvedUserId, resolvedContext);
+
+    this.eventEmitter.emit(
+      DismissibleEvents.ITEM_CREATED,
+      new ItemCreatedEvent(resolvedId, createdItem, resolvedUserId, resolvedContext),
+    );
+
+    await this.hookRunner.runPostRequest(resolvedId, createdItem, resolvedUserId, resolvedContext);
+
+    this.logger.debug(`getOrCreate completed`, { itemId, created: true });
+
+    return {
+      item: createdItem,
+      created: true,
+    };
+  }
+
+  /**
+   * Dismiss an item.
+   * @param itemId The item identifier
+   * @param userId The user identifier (required)
+   * @param context Optional request context for tracing
+   */
+  async dismiss(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IDismissServiceResponse> {
+    this.logger.debug(`dismiss called`, { itemId, userId });
+
+    await this.validateInput(itemId, userId);
+
+    const preRequestResult = await this.hookRunner.runPreRequest(itemId, userId, context);
+    HookRunner.throwIfBlocked(preRequestResult);
+
+    const resolvedId = preRequestResult.id;
+    const resolvedUserId = preRequestResult.userId;
+    const resolvedContext = preRequestResult.context;
+
+    const preDismissResult = await this.hookRunner.runPreDismiss(
+      resolvedId,
+      resolvedUserId,
+      resolvedContext,
+    );
+    HookRunner.throwIfBlocked(preDismissResult);
+
+    const result = await this.coreService.dismiss(resolvedId, resolvedUserId);
+
+    await this.hookRunner.runPostDismiss(resolvedId, result.item, resolvedUserId, resolvedContext);
+
+    this.eventEmitter.emit(
+      DismissibleEvents.ITEM_DISMISSED,
+      new ItemDismissedEvent(
+        resolvedId,
+        result.item,
+        result.previousItem,
+        resolvedUserId,
+        resolvedContext,
+      ),
+    );
+
+    await this.hookRunner.runPostRequest(resolvedId, result.item, resolvedUserId, resolvedContext);
+
+    this.logger.debug(`dismiss completed`, { itemId });
+
+    return result;
+  }
+
+  /**
+   * Restore a dismissed item.
+   * @param itemId The item identifier
+   * @param userId The user identifier (required)
+   * @param context Optional request context for tracing
+   */
+  async restore(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IRestoreServiceResponse> {
+    this.logger.debug(`restore called`, { itemId, userId });
+
+    await this.validateInput(itemId, userId);
+
+    const preRequestResult = await this.hookRunner.runPreRequest(itemId, userId, context);
+    HookRunner.throwIfBlocked(preRequestResult);
+
+    const resolvedId = preRequestResult.id;
+    const resolvedUserId = preRequestResult.userId;
+    const resolvedContext = preRequestResult.context;
+
+    const preRestoreResult = await this.hookRunner.runPreRestore(
+      resolvedId,
+      resolvedUserId,
+      resolvedContext,
+    );
+    HookRunner.throwIfBlocked(preRestoreResult);
+
+    const result = await this.coreService.restore(resolvedId, resolvedUserId);
+
+    await this.hookRunner.runPostRestore(resolvedId, result.item, resolvedUserId, resolvedContext);
+
+    this.eventEmitter.emit(
+      DismissibleEvents.ITEM_RESTORED,
+      new ItemRestoredEvent(
+        resolvedId,
+        result.item,
+        result.previousItem,
+        resolvedUserId,
+        resolvedContext,
+      ),
+    );
+
+    await this.hookRunner.runPostRequest(resolvedId, result.item, resolvedUserId, resolvedContext);
+
+    this.logger.debug(`restore completed`, { itemId });
+
+    return result;
+  }
+}