@dismissible/nestjs-dismissible 0.0.2-canary.738340d.0

package/src/core/dismissible.service.ts

@@ -0,0 +1,188 @@
+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 { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
+import { ICreateItemOptions } from './create-options';
+import { IRequestContext } from '../request/request-context.interface';
+import { DismissibleEvents } from '../events';
+import {
+  ItemCreatedEvent,
+  ItemRetrievedEvent,
+  ItemDismissedEvent,
+  ItemRestoredEvent,
+} from '../events';
+
+/**
+ * Main orchestration service for dismissible operations.
+ * Coordinates core logic, hooks, and events.
+ */
+@Injectable()
+export class DismissibleService<TMetadata extends BaseMetadata = BaseMetadata> {
+  constructor(
+    private readonly coreService: DismissibleCoreService<TMetadata>,
+    private readonly hookRunner: HookRunner<TMetadata>,
+    private readonly eventEmitter: EventEmitter2,
+    @Inject(DISMISSIBLE_LOGGER)
+    private readonly logger: IDismissibleLogger,
+  ) {}
+
+  /**
+   * Get an existing item or create a new one.
+   * @param itemId The item identifier
+   * @param userId The user identifier (required)
+   * @param options Optional creation options (metadata)
+   * @param context Optional request context for tracing
+   */
+  async getOrCreate(
+    itemId: string,
+    userId: string,
+    options?: ICreateItemOptions<TMetadata>,
+    context?: IRequestContext,
+  ): Promise<IGetOrCreateServiceResponse<TMetadata>> {
+    this.logger.debug(`getOrCreate called`, { itemId, userId });
+
+    // Run pre-getOrCreate hooks
+    const preResult = await this.hookRunner.runPreGetOrCreate(itemId, userId, context);
+    HookRunner.throwIfBlocked(preResult);
+
+    const resolvedId = preResult.id;
+    const resolvedUserId = preResult.userId;
+    const resolvedContext = preResult.context;
+
+    // Check if we need to run create hooks (for potential new item)
+    const result = await this.coreService.getOrCreate(resolvedId, resolvedUserId, options);
+
+    // If item was created, run create-specific hooks
+    if (result.created) {
+      // Run pre-create hooks
+      const preCreateResult = await this.hookRunner.runPreCreate(
+        resolvedId,
+        resolvedUserId,
+        resolvedContext,
+      );
+      HookRunner.throwIfBlocked(preCreateResult);
+
+      // Run post-create hooks
+      await this.hookRunner.runPostCreate(resolvedId, result.item, resolvedUserId, resolvedContext);
+
+      // Emit created event (async)
+      this.eventEmitter.emit(
+        DismissibleEvents.ITEM_CREATED,
+        new ItemCreatedEvent(resolvedId, result.item, resolvedUserId, resolvedContext),
+      );
+    } else {
+      // Emit retrieved event (async)
+      this.eventEmitter.emit(
+        DismissibleEvents.ITEM_RETRIEVED,
+        new ItemRetrievedEvent(resolvedId, result.item, resolvedUserId, resolvedContext),
+      );
+    }
+
+    // Run post-getOrCreate hooks
+    await this.hookRunner.runPostGetOrCreate(
+      resolvedId,
+      result.item,
+      resolvedUserId,
+      resolvedContext,
+    );
+
+    this.logger.debug(`getOrCreate completed`, { itemId, created: result.created });
+
+    return result;
+  }
+
+  /**
+   * 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<TMetadata>> {
+    this.logger.debug(`dismiss called`, { itemId, userId });
+
+    // Run pre-dismiss hooks
+    const preResult = await this.hookRunner.runPreDismiss(itemId, userId, context);
+    HookRunner.throwIfBlocked(preResult);
+
+    const resolvedId = preResult.id;
+    const resolvedUserId = preResult.userId;
+    const resolvedContext = preResult.context;
+
+    // Execute core dismiss operation
+    const result = await this.coreService.dismiss(resolvedId, resolvedUserId);
+
+    // Run post-dismiss hooks
+    await this.hookRunner.runPostDismiss(resolvedId, result.item, resolvedUserId, resolvedContext);
+
+    // Emit dismissed event (async)
+    this.eventEmitter.emit(
+      DismissibleEvents.ITEM_DISMISSED,
+      new ItemDismissedEvent(
+        resolvedId,
+        result.item,
+        result.previousItem,
+        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<TMetadata>> {
+    this.logger.debug(`restore called`, { itemId, userId });
+
+    // Run pre-restore hooks
+    const preResult = await this.hookRunner.runPreRestore(itemId, userId, context);
+    HookRunner.throwIfBlocked(preResult);
+
+    const resolvedId = preResult.id;
+    const resolvedUserId = preResult.userId;
+    const resolvedContext = preResult.context;
+
+    // Execute core restore operation
+    const result = await this.coreService.restore(resolvedId, resolvedUserId);
+
+    // Run post-restore hooks
+    await this.hookRunner.runPostRestore(resolvedId, result.item, resolvedUserId, resolvedContext);
+
+    // Emit restored event (async)
+    this.eventEmitter.emit(
+      DismissibleEvents.ITEM_RESTORED,
+      new ItemRestoredEvent(
+        resolvedId,
+        result.item,
+        result.previousItem,
+        resolvedUserId,
+        resolvedContext,
+      ),
+    );
+
+    this.logger.debug(`restore completed`, { itemId });
+
+    return result;
+  }
+}

package/src/core/hook-runner.service.spec.ts

@@ -0,0 +1,304 @@
+import { mock } from 'ts-jest-mocker';
+import { ForbiddenException } from '@nestjs/common';
+import { HookRunner } from './hook-runner.service';
+import { IDismissibleLifecycleHook } from './lifecycle-hook.interface';
+import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
+import { createTestItem, createTestContext } from '../testing/factories';
+import { IDismissibleLogger } from '@dismissible/nestjs-logger';
+
+describe('HookRunner', () => {
+  let hookRunner: HookRunner<BaseMetadata>;
+  let mockLogger: jest.Mocked<IDismissibleLogger>;
+
+  const testUserId = 'test-user-id';
+
+  beforeEach(() => {
+    mockLogger = mock<IDismissibleLogger>({ failIfMockNotProvided: false });
+  });
+
+  describe('with no hooks', () => {
+    beforeEach(() => {
+      hookRunner = new HookRunner([], mockLogger);
+    });
+
+    it('should return proceed: true for pre-getOrCreate', async () => {
+      const context = createTestContext();
+      const result = await hookRunner.runPreGetOrCreate('test-id', testUserId, context);
+
+      expect(result.proceed).toBe(true);
+      expect(result.id).toBe('test-id');
+      expect(result.userId).toBe(testUserId);
+      expect(result.context).toEqual(context);
+    });
+
+    it('should complete post-getOrCreate without error', async () => {
+      const item = createTestItem();
+      const context = createTestContext();
+
+      await expect(
+        hookRunner.runPostGetOrCreate('test-id', item, testUserId, context),
+      ).resolves.not.toThrow();
+    });
+  });
+
+  describe('with hooks', () => {
+    it('should execute hooks in priority order (low to high) for pre-hooks', async () => {
+      const executionOrder: number[] = [];
+
+      const hook1: IDismissibleLifecycleHook<BaseMetadata> = {
+        priority: 10,
+        onBeforeGetOrCreate: jest.fn(async () => {
+          executionOrder.push(10);
+          return { proceed: true };
+        }),
+      };
+
+      const hook2: IDismissibleLifecycleHook<BaseMetadata> = {
+        priority: 5,
+        onBeforeGetOrCreate: jest.fn(async () => {
+          executionOrder.push(5);
+          return { proceed: true };
+        }),
+      };
+
+      const hook3: IDismissibleLifecycleHook<BaseMetadata> = {
+        priority: 15,
+        onBeforeGetOrCreate: jest.fn(async () => {
+          executionOrder.push(15);
+          return { proceed: true };
+        }),
+      };
+
+      hookRunner = new HookRunner([hook1, hook2, hook3], mockLogger);
+      await hookRunner.runPreGetOrCreate('test-id', testUserId, createTestContext());
+
+      expect(executionOrder).toEqual([5, 10, 15]);
+    });
+
+    it('should execute hooks in reverse priority order for post-hooks', async () => {
+      const executionOrder: number[] = [];
+
+      const hook1: IDismissibleLifecycleHook<BaseMetadata> = {
+        priority: 10,
+        onAfterGetOrCreate: jest.fn(async () => {
+          executionOrder.push(10);
+        }),
+      };
+
+      const hook2: IDismissibleLifecycleHook<BaseMetadata> = {
+        priority: 5,
+        onAfterGetOrCreate: jest.fn(async () => {
+          executionOrder.push(5);
+        }),
+      };
+
+      const hook3: IDismissibleLifecycleHook<BaseMetadata> = {
+        priority: 15,
+        onAfterGetOrCreate: jest.fn(async () => {
+          executionOrder.push(15);
+        }),
+      };
+
+      hookRunner = new HookRunner([hook1, hook2, hook3], mockLogger);
+      await hookRunner.runPostGetOrCreate(
+        'test-id',
+        createTestItem(),
+        testUserId,
+        createTestContext(),
+      );
+
+      expect(executionOrder).toEqual([15, 10, 5]);
+    });
+
+    it('should block operation when pre-hook returns proceed: false', async () => {
+      const blockingHook: IDismissibleLifecycleHook<BaseMetadata> = {
+        onBeforeGetOrCreate: jest.fn(async () => ({
+          proceed: false,
+          reason: 'Rate limit exceeded',
+        })),
+      };
+
+      hookRunner = new HookRunner([blockingHook], mockLogger);
+      const result = await hookRunner.runPreGetOrCreate('test-id', testUserId, createTestContext());
+
+      expect(result.proceed).toBe(false);
+      expect(result.reason).toBe('Rate limit exceeded');
+    });
+
+    it('should apply mutations from pre-hooks', async () => {
+      const mutatingHook: IDismissibleLifecycleHook<BaseMetadata> = {
+        onBeforeGetOrCreate: jest.fn(async () => ({
+          proceed: true,
+          mutations: {
+            id: 'mutated-id',
+            userId: 'mutated-user',
+          },
+        })),
+      };
+
+      hookRunner = new HookRunner([mutatingHook], mockLogger);
+      const result = await hookRunner.runPreGetOrCreate(
+        'original-id',
+        testUserId,
+        createTestContext(),
+      );
+
+      expect(result.id).toBe('mutated-id');
+      expect(result.userId).toBe('mutated-user');
+    });
+
+    it('should pass mutations through multiple hooks', async () => {
+      const hook1: IDismissibleLifecycleHook<BaseMetadata> = {
+        priority: 1,
+        onBeforeGetOrCreate: jest.fn(async (itemId) => ({
+          proceed: true,
+          mutations: { id: `${itemId}-hook1` },
+        })),
+      };
+
+      const hook2: IDismissibleLifecycleHook<BaseMetadata> = {
+        priority: 2,
+        onBeforeGetOrCreate: jest.fn(async (itemId) => ({
+          proceed: true,
+          mutations: { id: `${itemId}-hook2` },
+        })),
+      };
+
+      hookRunner = new HookRunner([hook1, hook2], mockLogger);
+      const result = await hookRunner.runPreGetOrCreate(
+        'original',
+        testUserId,
+        createTestContext(),
+      );
+
+      expect(result.id).toBe('original-hook1-hook2');
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw error from pre-hook', async () => {
+      const errorHook: IDismissibleLifecycleHook<BaseMetadata> = {
+        onBeforeGetOrCreate: jest.fn(async () => {
+          throw new Error('Hook error');
+        }),
+      };
+
+      hookRunner = new HookRunner([errorHook], mockLogger);
+
+      await expect(
+        hookRunner.runPreGetOrCreate('test-id', testUserId, createTestContext()),
+      ).rejects.toThrow('Hook error');
+
+      expect(mockLogger.error).toHaveBeenCalled();
+    });
+
+    it('should log but not throw errors from post-hooks', async () => {
+      const errorHook: IDismissibleLifecycleHook<BaseMetadata> = {
+        onAfterGetOrCreate: jest.fn(async () => {
+          throw new Error('Post-hook error');
+        }),
+      };
+
+      hookRunner = new HookRunner([errorHook], mockLogger);
+
+      await expect(
+        hookRunner.runPostGetOrCreate('test-id', createTestItem(), testUserId, createTestContext()),
+      ).resolves.not.toThrow();
+
+      expect(mockLogger.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('throwIfBlocked', () => {
+    it('should throw ForbiddenException when blocked', () => {
+      expect(() =>
+        HookRunner.throwIfBlocked({
+          proceed: false,
+          id: 'test',
+          userId: testUserId,
+          context: createTestContext(),
+          reason: 'Not allowed',
+        }),
+      ).toThrow(ForbiddenException);
+    });
+
+    it('should not throw when not blocked', () => {
+      expect(() =>
+        HookRunner.throwIfBlocked({
+          proceed: true,
+          id: 'test',
+          userId: testUserId,
+          context: createTestContext(),
+        }),
+      ).not.toThrow();
+    });
+  });
+
+  describe('all hook methods', () => {
+    let allMethodsHook: IDismissibleLifecycleHook<BaseMetadata>;
+
+    beforeEach(() => {
+      allMethodsHook = {
+        priority: 0,
+        onBeforeGetOrCreate: jest.fn().mockResolvedValue({ proceed: true }),
+        onAfterGetOrCreate: jest.fn(),
+        onBeforeCreate: jest.fn().mockResolvedValue({ proceed: true }),
+        onAfterCreate: jest.fn(),
+        onBeforeDismiss: jest.fn().mockResolvedValue({ proceed: true }),
+        onAfterDismiss: jest.fn(),
+        onBeforeRestore: jest.fn().mockResolvedValue({ proceed: true }),
+        onAfterRestore: jest.fn(),
+      };
+
+      hookRunner = new HookRunner([allMethodsHook], mockLogger);
+    });
+
+    it('should run pre and post create hooks', async () => {
+      const context = createTestContext();
+      const item = createTestItem();
+
+      await hookRunner.runPreCreate('test-id', testUserId, context);
+      await hookRunner.runPostCreate('test-id', item, testUserId, context);
+
+      expect(allMethodsHook.onBeforeCreate).toHaveBeenCalledWith('test-id', testUserId, context);
+      expect(allMethodsHook.onAfterCreate).toHaveBeenCalledWith(
+        'test-id',
+        item,
+        testUserId,
+        context,
+      );
+    });
+
+    it('should run pre and post dismiss hooks', async () => {
+      const context = createTestContext();
+      const item = createTestItem();
+
+      await hookRunner.runPreDismiss('test-id', testUserId, context);
+      await hookRunner.runPostDismiss('test-id', item, testUserId, context);
+
+      expect(allMethodsHook.onBeforeDismiss).toHaveBeenCalledWith('test-id', testUserId, context);
+      expect(allMethodsHook.onAfterDismiss).toHaveBeenCalledWith(
+        'test-id',
+        item,
+        testUserId,
+        context,
+      );
+    });
+
+    it('should run pre and post restore hooks', async () => {
+      const context = createTestContext();
+      const item = createTestItem();
+
+      await hookRunner.runPreRestore('test-id', testUserId, context);
+      await hookRunner.runPostRestore('test-id', item, testUserId, context);
+
+      expect(allMethodsHook.onBeforeRestore).toHaveBeenCalledWith('test-id', testUserId, context);
+      expect(allMethodsHook.onAfterRestore).toHaveBeenCalledWith(
+        'test-id',
+        item,
+        testUserId,
+        context,
+      );
+    });
+  });
+});