@dismissible/nestjs-dismissible 0.0.2-canary.8976e84.0 → 0.0.2-canary.d2f56d7.0

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

@@ -5,7 +5,7 @@ import {
   IHookResult,
 } from './lifecycle-hook.interface';
 import { DISMISSIBLE_LOGGER, IDismissibleLogger } from '@dismissible/nestjs-logger';
-import { BaseMetadata, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+import { DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
 import { IRequestContext } from '../request/request-context.interface';
 
 /**
@@ -32,13 +32,13 @@ export interface IHookRunResult {
  * Service responsible for running lifecycle hooks.
  */
 @Injectable()
-export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
-  private readonly sortedHooks: IDismissibleLifecycleHook<TMetadata>[];
+export class HookRunner {
+  private readonly sortedHooks: IDismissibleLifecycleHook[];
 
   constructor(
     @Optional()
     @Inject(DISMISSIBLE_HOOKS)
-    hooks: IDismissibleLifecycleHook<TMetadata>[] = [],
+    hooks: IDismissibleLifecycleHook[] = [],
     @Inject(DISMISSIBLE_LOGGER)
     private readonly logger: IDismissibleLogger,
   ) {
@@ -46,29 +46,68 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
     this.sortedHooks = [...hooks].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Global Request Hooks
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * 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);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Get Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
-   * Run pre-getOrCreate hooks.
+   * Run pre-get hooks (when item exists and is about to be returned).
+   * Receives the item for access control based on item state.
    */
-  async runPreGetOrCreate(
+  async runPreGet(
     itemId: string,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<IHookRunResult> {
-    return this.runPreHooks('onBeforeGetOrCreate', itemId, userId, context);
+    return this.runPreHooksWithItem('onBeforeGet', itemId, item, userId, context);
   }
 
   /**
-   * Run post-getOrCreate hooks.
+   * Run post-get hooks (after item is returned).
    */
-  async runPostGetOrCreate(
+  async runPostGet(
     itemId: string,
-    item: DismissibleItemDto<TMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> {
-    await this.runPostHooks('onAfterGetOrCreate', itemId, item, userId, context);
+    await this.runPostHooks('onAfterGet', itemId, item, userId, context);
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Create Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Run pre-create hooks.
    */
@@ -85,13 +124,17 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
    */
   async runPostCreate(
     itemId: string,
-    item: DismissibleItemDto<TMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> {
     await this.runPostHooks('onAfterCreate', itemId, item, userId, context);
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Dismiss Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Run pre-dismiss hooks.
    */
@@ -108,13 +151,17 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
    */
   async runPostDismiss(
     itemId: string,
-    item: DismissibleItemDto<TMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> {
     await this.runPostHooks('onAfterDismiss', itemId, item, userId, context);
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Restore Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Run pre-restore hooks.
    */
@@ -131,7 +178,7 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
    */
   async runPostRestore(
     itemId: string,
-    item: DismissibleItemDto<TMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> {
@@ -142,7 +189,7 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
    * Internal method to run pre-hooks.
    */
   private async runPreHooks(
-    hookName: keyof IDismissibleLifecycleHook<TMetadata>,
+    hookName: keyof IDismissibleLifecycleHook,
     itemId: string,
     userId: string,
     context?: IRequestContext,
@@ -214,14 +261,93 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
     };
   }
 
+  /**
+   * 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,
+            };
+          }
+
+          // 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>,
+    hookName: keyof IDismissibleLifecycleHook,
     itemId: string,
-    item: DismissibleItemDto<TMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> {
@@ -232,7 +358,7 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
       const hookFn = hook[hookName] as
         | ((
             itemId: string,
-            item: DismissibleItemDto<TMetadata>,
+            item: DismissibleItemDto,
             userId: string,
             context?: IRequestContext,
           ) => Promise<void> | void)

package/src/core/index.ts

@@ -3,4 +3,3 @@ 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

@@ -1,4 +1,4 @@
-import { BaseMetadata, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+import { DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
 import { IRequestContext } from '../request/request-context.interface';
 
 /**
@@ -37,34 +37,72 @@ export interface IHookResult {
 /**
  * Interface for lifecycle hooks that can intercept dismissible operations.
  */
-export interface IDismissibleLifecycleHook<TMetadata extends BaseMetadata = BaseMetadata> {
+export interface IDismissibleLifecycleHook {
   /**
    * Priority for hook execution (lower numbers run first).
    * Default is 0.
    */
   readonly priority?: number;
 
+  // ─────────────────────────────────────────────────────────────────
+  // Global Request Hooks (run on ALL operations)
+  // ─────────────────────────────────────────────────────────────────
+
   /**
-   * Called before getOrCreate operation.
+   * Called at the start of any operation (getOrCreate, dismiss, restore).
+   * Use for global concerns like authentication, rate limiting, request validation.
    */
-  onBeforeGetOrCreate?(
+  onBeforeRequest?(
     itemId: string,
     userId: string,
     context?: IRequestContext,
   ): Promise<IHookResult> | IHookResult;
 
   /**
-   * Called after getOrCreate operation.
+   * Called at the end of any operation (getOrCreate, dismiss, restore).
+   * Use for global concerns like audit logging, metrics, cleanup.
    */
-  onAfterGetOrCreate?(
+  onAfterRequest?(
     itemId: string,
-    item: DismissibleItemDto<TMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> | void;
 
+  // ─────────────────────────────────────────────────────────────────
+  // Get Hooks (when retrieving existing item)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * 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;
+
+  // ─────────────────────────────────────────────────────────────────
+  // Create Hooks (when creating new item)
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Called before creating a new item.
+   * Use for plan limits, quota checks, etc.
    */
   onBeforeCreate?(
     itemId: string,
@@ -77,11 +115,15 @@ export interface IDismissibleLifecycleHook<TMetadata extends BaseMetadata = Base
    */
   onAfterCreate?(
     itemId: string,
-    item: DismissibleItemDto<TMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> | void;
 
+  // ─────────────────────────────────────────────────────────────────
+  // Dismiss Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Called before dismissing an item.
    */
@@ -96,11 +138,15 @@ export interface IDismissibleLifecycleHook<TMetadata extends BaseMetadata = Base
    */
   onAfterDismiss?(
     itemId: string,
-    item: DismissibleItemDto<TMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> | void;
 
+  // ─────────────────────────────────────────────────────────────────
+  // Restore Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Called before restoring an item.
    */
@@ -115,7 +161,7 @@ export interface IDismissibleLifecycleHook<TMetadata extends BaseMetadata = Base
    */
   onAfterRestore?(
     itemId: string,
-    item: DismissibleItemDto<TMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> | void;

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

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