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

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

@@ -0,0 +1,267 @@
+import { Injectable, Inject, Optional, ForbiddenException } from '@nestjs/common';
+import {
+  DISMISSIBLE_HOOKS,
+  IDismissibleLifecycleHook,
+  IHookResult,
+} from './lifecycle-hook.interface';
+import { DISMISSIBLE_LOGGER, IDismissibleLogger } from '@dismissible/nestjs-logger';
+import { BaseMetadata, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+import { IRequestContext } from '../request/request-context.interface';
+
+/**
+ * Result from running pre-hooks.
+ */
+export interface IHookRunResult {
+  /** Whether the operation should proceed */
+  proceed: boolean;
+
+  /** The (potentially mutated) item ID */
+  id: string;
+
+  /** The (potentially mutated) user ID */
+  userId: string;
+
+  /** The (potentially mutated) request context */
+  context?: IRequestContext;
+
+  /** Reason for blocking (if proceed is false) */
+  reason?: string;
+}
+
+/**
+ * Service responsible for running lifecycle hooks.
+ */
+@Injectable()
+export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
+  private readonly sortedHooks: IDismissibleLifecycleHook<TMetadata>[];
+
+  constructor(
+    @Optional()
+    @Inject(DISMISSIBLE_HOOKS)
+    hooks: IDismissibleLifecycleHook<TMetadata>[] = [],
+    @Inject(DISMISSIBLE_LOGGER)
+    private readonly logger: IDismissibleLogger,
+  ) {
+    // Sort hooks by priority (lower numbers first)
+    this.sortedHooks = [...hooks].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+  }
+
+  /**
+   * Run pre-getOrCreate hooks.
+   */
+  async runPreGetOrCreate(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookRunResult> {
+    return this.runPreHooks('onBeforeGetOrCreate', itemId, userId, context);
+  }
+
+  /**
+   * Run post-getOrCreate hooks.
+   */
+  async runPostGetOrCreate(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    await this.runPostHooks('onAfterGetOrCreate', itemId, item, userId, context);
+  }
+
+  /**
+   * Run pre-create hooks.
+   */
+  async runPreCreate(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookRunResult> {
+    return this.runPreHooks('onBeforeCreate', itemId, userId, context);
+  }
+
+  /**
+   * Run post-create hooks.
+   */
+  async runPostCreate(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    await this.runPostHooks('onAfterCreate', itemId, item, userId, context);
+  }
+
+  /**
+   * Run pre-dismiss hooks.
+   */
+  async runPreDismiss(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookRunResult> {
+    return this.runPreHooks('onBeforeDismiss', itemId, userId, context);
+  }
+
+  /**
+   * Run post-dismiss hooks.
+   */
+  async runPostDismiss(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    await this.runPostHooks('onAfterDismiss', itemId, item, userId, context);
+  }
+
+  /**
+   * Run pre-restore hooks.
+   */
+  async runPreRestore(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookRunResult> {
+    return this.runPreHooks('onBeforeRestore', itemId, userId, context);
+  }
+
+  /**
+   * Run post-restore hooks.
+   */
+  async runPostRestore(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    await this.runPostHooks('onAfterRestore', itemId, item, userId, context);
+  }
+
+  /**
+   * Internal method to run pre-hooks.
+   */
+  private async runPreHooks(
+    hookName: keyof IDismissibleLifecycleHook<TMetadata>,
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookRunResult> {
+    let currentId = itemId;
+    let currentUserId = userId;
+    let currentContext = context ? { ...context } : undefined;
+
+    for (const hook of this.sortedHooks) {
+      const hookFn = hook[hookName] as
+        | ((
+            itemId: string,
+            userId: string,
+            context?: IRequestContext,
+          ) => Promise<IHookResult> | IHookResult)
+        | undefined;
+
+      if (hookFn) {
+        try {
+          const result = await hookFn.call(hook, currentId, currentUserId, currentContext);
+
+          if (!result.proceed) {
+            this.logger.debug(`Hook ${hook.constructor.name}.${hookName} blocked operation`, {
+              itemId: currentId,
+              userId: currentUserId,
+              reason: result.reason,
+            });
+
+            return {
+              proceed: false,
+              id: currentId,
+              userId: currentUserId,
+              context: currentContext,
+              reason: result.reason,
+            };
+          }
+
+          // Apply mutations if present
+          if (result.mutations) {
+            if (result.mutations.id !== undefined) {
+              currentId = result.mutations.id;
+            }
+            if (result.mutations.userId !== undefined) {
+              currentUserId = result.mutations.userId;
+            }
+            if (result.mutations.context && currentContext) {
+              currentContext = { ...currentContext, ...result.mutations.context };
+            }
+          }
+        } catch (error) {
+          this.logger.error(
+            `Error in hook ${hook.constructor.name}.${hookName}`,
+            error instanceof Error ? error : new Error(String(error)),
+            {
+              itemId: currentId,
+              userId: currentUserId,
+            },
+          );
+          throw error;
+        }
+      }
+    }
+
+    return {
+      proceed: true,
+      id: currentId,
+      userId: currentUserId,
+      context: currentContext,
+    };
+  }
+
+  /**
+   * Internal method to run post-hooks.
+   * Post-hooks run in reverse priority order.
+   */
+  private async runPostHooks(
+    hookName: keyof IDismissibleLifecycleHook<TMetadata>,
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    // Run in reverse order for post-hooks
+    const reversedHooks = [...this.sortedHooks].reverse();
+
+    for (const hook of reversedHooks) {
+      const hookFn = hook[hookName] as
+        | ((
+            itemId: string,
+            item: DismissibleItemDto<TMetadata>,
+            userId: string,
+            context?: IRequestContext,
+          ) => Promise<void> | void)
+        | undefined;
+
+      if (hookFn) {
+        try {
+          await hookFn.call(hook, itemId, item, userId, context);
+        } catch (error) {
+          this.logger.error(
+            `Error in hook ${hook.constructor.name}.${hookName}`,
+            error instanceof Error ? error : new Error(String(error)),
+            {
+              itemId,
+              userId,
+            },
+          );
+          // Post-hooks errors are logged but don't block the operation
+        }
+      }
+    }
+  }
+
+  /**
+   * Throw ForbiddenException if the hook result indicates the operation was blocked.
+   */
+  static throwIfBlocked(result: IHookRunResult): void {
+    if (!result.proceed) {
+      throw new ForbiddenException(result.reason ?? 'Operation blocked by lifecycle hook');
+    }
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,6 @@
+export * from './lifecycle-hook.interface';
+export * from './service-responses.interface';
+export * from './dismissible-core.service';
+export * from './hook-runner.service';
+export * from './dismissible.service';
+export * from './create-options';

package/src/core/lifecycle-hook.interface.ts

@@ -0,0 +1,122 @@
+import { BaseMetadata, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+import { IRequestContext } from '../request/request-context.interface';
+
+/**
+ * Injection token for lifecycle hooks.
+ */
+export const DISMISSIBLE_HOOKS = Symbol('DISMISSIBLE_HOOKS');
+
+/**
+ * Mutations that can be applied by pre-hooks.
+ */
+export interface IHookMutations {
+  /** Mutated item ID */
+  id?: string;
+
+  /** Mutated user ID */
+  userId?: string;
+
+  /** Mutated request context */
+  context?: Partial<IRequestContext>;
+}
+
+/**
+ * Result returned by pre-hooks.
+ */
+export interface IHookResult {
+  /** Whether the operation should proceed */
+  proceed: boolean;
+
+  /** Optional reason if the operation is blocked */
+  reason?: string;
+
+  /** Optional mutations to apply */
+  mutations?: IHookMutations;
+}
+
+/**
+ * Interface for lifecycle hooks that can intercept dismissible operations.
+ */
+export interface IDismissibleLifecycleHook<TMetadata extends BaseMetadata = BaseMetadata> {
+  /**
+   * Priority for hook execution (lower numbers run first).
+   * Default is 0.
+   */
+  readonly priority?: number;
+
+  /**
+   * Called before getOrCreate operation.
+   */
+  onBeforeGetOrCreate?(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookResult> | IHookResult;
+
+  /**
+   * Called after getOrCreate operation.
+   */
+  onAfterGetOrCreate?(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> | void;
+
+  /**
+   * Called before creating a new item.
+   */
+  onBeforeCreate?(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookResult> | IHookResult;
+
+  /**
+   * Called after creating a new item.
+   */
+  onAfterCreate?(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> | void;
+
+  /**
+   * Called before dismissing an item.
+   */
+  onBeforeDismiss?(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookResult> | IHookResult;
+
+  /**
+   * Called after dismissing an item.
+   */
+  onAfterDismiss?(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> | void;
+
+  /**
+   * Called before restoring an item.
+   */
+  onBeforeRestore?(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookResult> | IHookResult;
+
+  /**
+   * Called after restoring an item.
+   */
+  onAfterRestore?(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> | void;
+}

package/src/core/service-responses.interface.ts

@@ -0,0 +1,34 @@
+import { BaseMetadata, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+
+/**
+ * Response from getOrCreate operation.
+ */
+export interface IGetOrCreateServiceResponse<TMetadata extends BaseMetadata = BaseMetadata> {
+  /** The item (either retrieved or created) */
+  item: DismissibleItemDto<TMetadata>;
+
+  /** Whether the item was newly created */
+  created: boolean;
+}
+
+/**
+ * Response from dismiss operation.
+ */
+export interface IDismissServiceResponse<TMetadata extends BaseMetadata = BaseMetadata> {
+  /** The dismissed item */
+  item: DismissibleItemDto<TMetadata>;
+
+  /** The item state before dismissal */
+  previousItem: DismissibleItemDto<TMetadata>;
+}
+
+/**
+ * Response from restore operation.
+ */
+export interface IRestoreServiceResponse<TMetadata extends BaseMetadata = BaseMetadata> {
+  /** The restored item */
+  item: DismissibleItemDto<TMetadata>;
+
+  /** The item state before restoration */
+  previousItem: DismissibleItemDto<TMetadata>;
+}

package/src/dismissible.module.ts

@@ -0,0 +1,83 @@
+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 './core/lifecycle-hook.interface';
+import { LoggerModule, IDismissibleLoggerModuleOptions } from '@dismissible/nestjs-logger';
+import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
+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<TMetadata extends BaseMetadata = BaseMetadata> =
+  IDismissibleLoggerModuleOptions &
+    IDismissibleStorageModuleOptions & {
+      hooks?: Type<IDismissibleLifecycleHook<TMetadata>>[];
+    };
+
+@Module({})
+export class DismissibleModule {
+  static forRoot<TMetadata extends BaseMetadata = BaseMetadata>(
+    options: IDismissibleModuleOptions<TMetadata>,
+  ): 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<TMetadata>[]) => 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,105 @@
+import { BaseMetadata, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+import { IRequestContext } from '../request/request-context.interface';
+
+/**
+ * Base class for all dismissible events.
+ */
+abstract class BaseDismissibleEvent<TMetadata extends BaseMetadata = BaseMetadata> {
+  /** The item identifier */
+  readonly id: string;
+
+  /** The current state of the item */
+  readonly item: DismissibleItemDto<TMetadata>;
+
+  /** The user identifier */
+  readonly userId: string;
+
+  /** The request context (optional) */
+  readonly context?: IRequestContext;
+
+  constructor(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    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<
+  TMetadata extends BaseMetadata = BaseMetadata,
+> extends BaseDismissibleEvent<TMetadata> {
+  constructor(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ) {
+    super(itemId, item, userId, context);
+  }
+}
+
+/**
+ * Event emitted when a new item is created.
+ */
+export class ItemCreatedEvent<
+  TMetadata extends BaseMetadata = BaseMetadata,
+> extends BaseDismissibleEvent<TMetadata> {
+  constructor(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ) {
+    super(itemId, item, userId, context);
+  }
+}
+
+/**
+ * Event emitted when an item is dismissed.
+ */
+export class ItemDismissedEvent<
+  TMetadata extends BaseMetadata = BaseMetadata,
+> extends BaseDismissibleEvent<TMetadata> {
+  /** The item state before dismissal */
+  readonly previousItem: DismissibleItemDto<TMetadata>;
+
+  constructor(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    previousItem: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ) {
+    super(itemId, item, userId, context);
+    this.previousItem = previousItem;
+  }
+}
+
+/**
+ * Event emitted when a dismissed item is restored.
+ */
+export class ItemRestoredEvent<
+  TMetadata extends BaseMetadata = BaseMetadata,
+> extends BaseDismissibleEvent<TMetadata> {
+  /** The item state before restoration */
+  readonly previousItem: DismissibleItemDto<TMetadata>;
+
+  constructor(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    previousItem: DismissibleItemDto<TMetadata>,
+    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');
+    });
+  });
+});