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

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

@@ -0,0 +1,368 @@
+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 { 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 {
+  private readonly sortedHooks: IDismissibleLifecycleHook[];
+
+  constructor(
+    @Optional()
+    @Inject(DISMISSIBLE_HOOKS)
+    hooks: IDismissibleLifecycleHook[] = [],
+    @Inject(DISMISSIBLE_LOGGER)
+    private readonly logger: IDismissibleLogger,
+  ) {
+    this.sortedHooks = [...hooks].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+  }
+
+  /**
+   * Run pre-request hooks (global - runs at start of any operation).
+   * Use for authentication, rate limiting, request validation.
+   */
+  async runPreRequest(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookRunResult> {
+    return this.runPreHooks('onBeforeRequest', itemId, userId, context);
+  }
+
+  /**
+   * Run post-request hooks (global - runs at end of any operation).
+   * Use for audit logging, metrics, cleanup.
+   */
+  async runPostRequest(
+    itemId: string,
+    item: DismissibleItemDto,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    await this.runPostHooks('onAfterRequest', itemId, item, userId, context);
+  }
+
+  /**
+   * Run pre-get hooks (when item exists and is about to be returned).
+   * Receives the item for access control based on item state.
+   */
+  async runPreGet(
+    itemId: string,
+    item: DismissibleItemDto,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookRunResult> {
+    return this.runPreHooksWithItem('onBeforeGet', itemId, item, userId, context);
+  }
+
+  /**
+   * Run post-get hooks (after item is returned).
+   */
+  async runPostGet(
+    itemId: string,
+    item: DismissibleItemDto,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    await this.runPostHooks('onAfterGet', 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,
+    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,
+    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,
+    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,
+    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,
+            };
+          }
+
+          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 pre-hooks that receive the item (e.g., onBeforeGet).
+   * Unlike standard pre-hooks, these receive the item for inspection/access control.
+   */
+  private async runPreHooksWithItem(
+    hookName: keyof IDismissibleLifecycleHook,
+    itemId: string,
+    item: DismissibleItemDto,
+    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,
+            item: DismissibleItemDto,
+            userId: string,
+            context?: IRequestContext,
+          ) => Promise<IHookResult> | IHookResult)
+        | undefined;
+
+      if (hookFn) {
+        try {
+          const result = await hookFn.call(hook, currentId, item, 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,
+            };
+          }
+
+          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,
+    itemId: string,
+    item: DismissibleItemDto,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    const reversedHooks = [...this.sortedHooks].reverse();
+
+    for (const hook of reversedHooks) {
+      const hookFn = hook[hookName] as
+        | ((
+            itemId: string,
+            item: DismissibleItemDto,
+            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,
+            },
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * 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,5 @@
+export * from './lifecycle-hook.interface';
+export * from './service-responses.interface';
+export * from './dismissible-core.service';
+export * from './hook-runner.service';
+export * from './dismissible.service';

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

@@ -0,0 +1,148 @@
+import { 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 {
+  /**
+   * Priority for hook execution (lower numbers run first).
+   * Default is 0.
+   */
+  readonly priority?: number;
+
+  /**
+   * Called at the start of any operation (getOrCreate, dismiss, restore).
+   * Use for global concerns like authentication, rate limiting, request validation.
+   */
+  onBeforeRequest?(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookResult> | IHookResult;
+
+  /**
+   * Called at the end of any operation (getOrCreate, dismiss, restore).
+   * Use for global concerns like audit logging, metrics, cleanup.
+   */
+  onAfterRequest?(
+    itemId: string,
+    item: DismissibleItemDto,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> | void;
+
+  /**
+   * Called before returning an existing item.
+   * Only called when item exists in storage.
+   * Use for access control based on item state (e.g., block dismissed items).
+   */
+  onBeforeGet?(
+    itemId: string,
+    item: DismissibleItemDto,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookResult> | IHookResult;
+
+  /**
+   * Called after returning an existing item.
+   * Only called when item exists in storage.
+   */
+  onAfterGet?(
+    itemId: string,
+    item: DismissibleItemDto,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> | void;
+
+  /**
+   * Called before creating a new item.
+   * Use for plan limits, quota checks, etc.
+   */
+  onBeforeCreate?(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookResult> | IHookResult;
+
+  /**
+   * Called after creating a new item.
+   */
+  onAfterCreate?(
+    itemId: string,
+    item: DismissibleItemDto,
+    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,
+    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,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> | void;
+}

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

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