@dismissible/nestjs-core 1.0.3-alpha.cdc64a4.0 → 2.0.2-alpha.72996f5.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://dismissible.io" target="_blank"><img src="../../docs/images/dismissible_logo.png" width="240" alt="Dismissible" /></a>
+  <a href="https://dismissible.io" target="_blank"><img src="https://raw.githubusercontent.com/DismissibleIo/dismissible-api/main/docs/images/dismissible_logo.png" width="240" alt="Dismissible" /></a>
 </p>
 
   <p align="center">Never Show The Same Thing Twice!</p>
@@ -14,10 +14,28 @@
 
 # @dismissible/nestjs-core
 
-A powerful NestJS library for managing dismissible state in your applications. Perfect for guided tours, user preferences, onboarding flows, and any scenario where you need to track whether a user has dismissed or interacted with specific items.
+The core NestJS library for managing dismissible state in your applications. This is the central package that ties together all the main Dismissible libraries and contains the domain logic for dismissible items.
+
+Perfect for guided tours, user preferences, onboarding flows, and any scenario where you need to track whether a user has dismissed or interacted with specific items.
 
 > **Part of the Dismissible API** - This library is part of the [Dismissible API](https://dismissible.io) ecosystem. Visit [dismissible.io](https://dismissible.io) for more information and documentation.
 
+## Related Packages
+
+This core library integrates with several lower-level packages:
+
+| Package                                                                                                      | Description                                  |
+| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
+| [@dismissible/nestjs-storage](https://www.npmjs.com/package/@dismissible/nestjs-storage)                     | Storage interfaces and base module           |
+| [@dismissible/nestjs-postgres-storage](https://www.npmjs.com/package/@dismissible/nestjs-postgres-storage)   | PostgreSQL storage adapter                   |
+| [@dismissible/nestjs-dynamodb-storage](https://www.npmjs.com/package/@dismissible/nestjs-dynamodb-storage)   | DynamoDB storage adapter                     |
+| [@dismissible/nestjs-hooks](https://www.npmjs.com/package/@dismissible/nestjs-hooks)                         | Lifecycle hook interfaces                    |
+| [@dismissible/nestjs-jwt-auth-hook](https://www.npmjs.com/package/@dismissible/nestjs-jwt-auth-hook)         | JWT authentication hook                      |
+| [@dismissible/nestjs-rate-limiter-hook](https://www.npmjs.com/package/@dismissible/nestjs-rate-limiter-hook) | Rate limiting hook                           |
+| [@dismissible/nestjs-logger](https://www.npmjs.com/package/@dismissible/nestjs-logger)                       | Logger interfaces and default implementation |
+| [@dismissible/nestjs-item](https://www.npmjs.com/package/@dismissible/nestjs-item)                           | Dismissible item DTOs and types              |
+| [@dismissible/react-client](https://www.npmjs.com/package/@dismissible/react-client)                         | React client for frontend integration        |
+
 ## Features
 
 - **Simple API** - Easy-to-use service methods for get-or-create, dismiss, and restore operations
@@ -48,7 +66,7 @@ import { Module } from '@nestjs/common';
 import { DismissibleModule } from '@dismissible/nestjs-core';
 
 @Module({
-  imports: [DismissibleModule.forRoot({})],
+  imports: [DismissibleModule.forRoot()],
 })
 export class AppModule {}
 ```
@@ -113,11 +131,39 @@ function WelcomeBanner() {
 
 The React client automatically uses the built-in REST API endpoints, so no additional configuration is needed on the backend.
 
-## Advanced Usage
+## Configuration Options
+
+All configuration is done through `DismissibleModule.forRoot()`. The following options are available:
+
+```typescript
+interface IDismissibleModuleOptions {
+  // Custom storage module (defaults to memory storage)
+  storage?: Type<any> | DynamicModule;
+
+  // Custom logger implementation
+  logger?: Type<IDismissibleLogger>;
+
+  // Lifecycle hooks to register
+  hooks?: Type<IDismissibleLifecycleHook>[];
+
+  // Additional modules to import
+  imports?: DynamicModule[];
+
+  // Additional providers to register
+  providers?: Provider[];
+
+  // Custom controllers (overrides default REST API controllers)
+  controllers?: Type<any>[];
+}
+```
+
+---
 
-### Using PostgreSQL Storage
+### `storage`
 
-To persist dismissible items in a PostgreSQL database, use the `PostgresStorageModule`:
+Specifies a custom storage module for persisting dismissible items. Defaults to in-memory storage.
+
+**Default:** In-memory storage (data lost on restart)
 
 ```typescript
 import { Module } from '@nestjs/common';
@@ -127,77 +173,100 @@ import { PostgresStorageModule } from '@dismissible/nestjs-postgres-storage';
 @Module({
   imports: [
     DismissibleModule.forRoot({
-      storage: PostgresStorageModule,
+      storage: PostgresStorageModule.forRoot({
+        connectionString: 'postgresql://user:password@localhost:5432/dismissible',
+      }),
     }),
   ],
 })
 export class AppModule {}
 ```
 
-**Prerequisites:**
-
-1. Install the PostgreSQL storage package:
+**Related packages:**
 
-   ```bash
-   npm install @dismissible/nestjs-postgres-storage
-   ```
+- [@dismissible/nestjs-storage](https://www.npmjs.com/package/@dismissible/nestjs-storage) - Storage interfaces and base module for implementing custom adapters
+- [@dismissible/nestjs-postgres-storage](https://www.npmjs.com/package/@dismissible/nestjs-postgres-storage) - PostgreSQL storage adapter
+- [@dismissible/nestjs-dynamodb-storage](https://www.npmjs.com/package/@dismissible/nestjs-dynamodb-storage) - DynamoDB storage adapter
 
-2. Set up your database connection string:
+---
 
-   ```env
-   DISMISSIBLE_STORAGE_POSTGRES_CONNECTION_STRING=postgresql://user:password@localhost:5432/dismissible
-   ```
+### `logger`
 
-3. Run Prisma migrations (if using Prisma):
-   ```bash
-   npx prisma migrate dev
-   ```
+Provides a custom logger implementation. The logger must implement the `IDismissibleLogger` interface.
 
-The PostgreSQL adapter uses Prisma and automatically handles schema migrations. The storage persists all dismissible items across application restarts.
-
-### Using the Service
-
-Instead of using the built-in REST API endpoints, you can inject `DismissibleService` directly into your controllers or other services for more control:
+**Default:** Built-in console logger
 
 ```typescript
-import { Controller, Get, Param, Delete, Post } from '@nestjs/common';
-import { DismissibleService } from '@dismissible/nestjs-core';
-
-@Controller('features')
-export class FeaturesController {
-  constructor(private readonly dismissibleService: DismissibleService) {}
+import { Injectable, Module } from '@nestjs/common';
+import { DismissibleModule } from '@dismissible/nestjs-core';
+import { IDismissibleLogger } from '@dismissible/nestjs-logger';
 
-  @Get(':userId/items/:itemId')
-  async getOrCreateItem(@Param('userId') userId: string, @Param('itemId') itemId: string) {
-    const result = await this.dismissibleService.getOrCreate(
-      itemId,
-      userId,
-      undefined, // optional request context
-    );
+@Injectable()
+class CustomLogger implements IDismissibleLogger {
+  debug(message: string, context?: any) {
+    console.log(`[DEBUG] ${message}`, context);
+  }
 
-    return {
-      item: result.item,
-      wasCreated: result.created,
-    };
+  info(message: string, context?: any) {
+    console.log(`[INFO] ${message}`, context);
   }
 
-  @Delete(':userId/items/:itemId')
-  async dismissItem(@Param('userId') userId: string, @Param('itemId') itemId: string) {
-    const result = await this.dismissibleService.dismiss(itemId, userId);
-    return { item: result.item };
+  warn(message: string, context?: any) {
+    console.warn(`[WARN] ${message}`, context);
   }
 
-  @Post(':userId/items/:itemId/restore')
-  async restoreItem(@Param('userId') userId: string, @Param('itemId') itemId: string) {
-    const result = await this.dismissibleService.restore(itemId, userId);
-    return { item: result.item };
+  error(message: string, context?: any) {
+    console.error(`[ERROR] ${message}`, context);
   }
 }
+
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      logger: CustomLogger,
+    }),
+  ],
+})
+export class AppModule {}
 ```
 
-### JWT Authentication
+**Related packages:**
+
+- [@dismissible/nestjs-logger](https://www.npmjs.com/package/@dismissible/nestjs-logger) - Logger interfaces and default implementation
+
+---
+
+### `hooks`
+
+Registers lifecycle hooks that intercept operations. Hooks can block operations, mutate parameters, or perform side effects.
+
+**Default:** No hooks
+
+```typescript
+import { Injectable, Module } from '@nestjs/common';
+import { DismissibleModule } from '@dismissible/nestjs-core';
+import { IDismissibleLifecycleHook, IHookResult } from '@dismissible/nestjs-hooks';
+
+@Injectable()
+class AuditHook implements IDismissibleLifecycleHook {
+  readonly priority = 10; // Lower runs first
+
+  async onAfterDismiss(itemId: string, userId: string): Promise<void> {
+    console.log(`User ${userId} dismissed ${itemId}`);
+  }
+}
+
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      hooks: [AuditHook],
+    }),
+  ],
+})
+export class AppModule {}
+```
 
-Secure your API endpoints using the JWT Auth Hook with any OIDC-compliant identity provider:
+For JWT authentication, use the [@dismissible/nestjs-jwt-auth-hook](https://www.npmjs.com/package/@dismissible/nestjs-jwt-auth-hook) package:
 
 ```typescript
 import { Module } from '@nestjs/common';
@@ -220,83 +289,170 @@ import { JwtAuthHookModule, JwtAuthHook } from '@dismissible/nestjs-jwt-auth-hoo
 export class AppModule {}
 ```
 
-See the [@dismissible/nestjs-jwt-auth-hook](https://www.npmjs.com/package/@dismissible/nestjs-jwt-auth-hook) package for detailed configuration options.
+**Related packages:**
+
+- [@dismissible/nestjs-hooks](https://www.npmjs.com/package/@dismissible/nestjs-hooks) - Hook interfaces and types for implementing custom lifecycle hooks
+- [@dismissible/nestjs-jwt-auth-hook](https://www.npmjs.com/package/@dismissible/nestjs-jwt-auth-hook) - JWT authentication hook for OIDC providers
+- [@dismissible/nestjs-rate-limiter-hook](https://www.npmjs.com/package/@dismissible/nestjs-rate-limiter-hook) - Rate limiting hook
+
+---
+
+### `imports`
 
-### Custom Lifecycle Hooks
+Adds additional modules to the DismissibleModule's imports. Useful for injecting dependencies that your hooks or providers need.
 
-Lifecycle hooks allow you to intercept operations and add custom logic, validation, or mutations:
+**Default:** None
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { IDismissibleLifecycleHook, IHookResult } from '@dismissible/nestjs-core';
-@Injectable()
-export class AuditHook implements IDismissibleLifecycleHook {
-  // Lower priority runs first (default is 0)
-  readonly priority = 10;
+import { Module } from '@nestjs/common';
+import { DismissibleModule } from '@dismissible/nestjs-core';
+import { HttpModule } from '@nestjs/axios';
 
-  async onBeforeDismiss(
-    itemId: string,
-    userId: string,
-    context?: IRequestContext,
-  ): Promise<IHookResult> {
-    // Block dismissal of critical items
-    if (itemId.startsWith('critical-')) {
-      return {
-        proceed: false,
-        reason: 'Cannot dismiss critical items',
-      };
-    }
-
-    // Allow the operation to proceed
-    return { proceed: true };
-  }
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      imports: [HttpModule],
+      hooks: [WebhookHook], // Hook that uses HttpService
+    }),
+  ],
+})
+export class AppModule {}
+```
 
-  async onAfterCreate(
-    itemId: string,
-    item: DismissibleItemDto,
-    userId: string,
-    context?: IRequestContext,
-  ): Promise<void> {
-    // Log item creation for analytics
-    console.log(`Item created: ${itemId} for user ${userId}`);
+---
+
+### `providers`
+
+Registers additional providers within the DismissibleModule. Useful for services that your hooks depend on.
+
+**Default:** None
+
+```typescript
+import { Injectable, Module } from '@nestjs/common';
+import { DismissibleModule, IDismissibleLifecycleHook } from '@dismissible/nestjs-core';
+
+@Injectable()
+class AnalyticsService {
+  track(event: string, data: any) {
+    // Send to analytics
   }
+}
 
-  // Mutate item ID before operation
-  async onBeforeGetOrCreate(
-    itemId: string,
-    userId: string,
-    context?: IRequestContext,
-  ): Promise<IHookResult> {
-    // Normalize item IDs (e.g., lowercase)
-    return {
-      proceed: true,
-      mutations: {
-        id: itemId.toLowerCase(),
-      },
-    };
+@Injectable()
+class AnalyticsHook implements IDismissibleLifecycleHook {
+  constructor(private analytics: AnalyticsService) {}
+
+  async onAfterDismiss(itemId: string, userId: string): Promise<void> {
+    this.analytics.track('item_dismissed', { itemId, userId });
   }
 }
+
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      providers: [AnalyticsService],
+      hooks: [AnalyticsHook],
+    }),
+  ],
+})
+export class AppModule {}
 ```
 
-Register hooks in your module:
+---
+
+### `controllers`
+
+Overrides the default REST API controllers. Use this when you want complete control over the API endpoints.
+
+**Default:** Built-in controllers for get-or-create, dismiss, and restore
 
 ```typescript
-import { DismissibleModule } from '@dismissible/nestjs-core';
-import { AuditHook } from './hooks/audit.hook';
+import { Controller, Get, Param, Module, Inject } from '@nestjs/common';
+import {
+  DismissibleModule,
+  IDismissibleService,
+  DISMISSIBLE_SERVICE,
+} from '@dismissible/nestjs-core';
+
+@Controller('custom')
+class CustomController {
+  constructor(
+    @Inject(DISMISSIBLE_SERVICE)
+    private dismissibleService: IDismissibleService,
+  ) {}
+
+  @Get(':userId/:itemId')
+  async getItem(@Param('userId') userId: string, @Param('itemId') itemId: string) {
+    return this.dismissibleService.getOrCreate(itemId, userId);
+  }
+}
 
 @Module({
   imports: [
     DismissibleModule.forRoot({
-      hooks: [AuditHook],
+      controllers: [CustomController],
     }),
   ],
 })
 export class AppModule {}
 ```
 
-### Listening to Events
+To disable the REST API entirely, pass an empty array:
 
-The library emits events for all operations. Listen to them using NestJS's `EventEmitter2`:
+```typescript
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      controllers: [],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Using the Service Directly
+
+Instead of using the built-in REST API, you can inject `DismissibleService` into your own controllers or services:
+
+```typescript
+import { Controller, Get, Param, Delete, Post, Inject } from '@nestjs/common';
+import { IDismissibleService, DISMISSIBLE_SERVICE } from '@dismissible/nestjs-core';
+
+@Controller('features')
+export class FeaturesController {
+  constructor(
+    @Inject(DISMISSIBLE_SERVICE)
+    private readonly dismissibleService: IDismissibleService,
+  ) {}
+
+  @Get(':userId/items/:itemId')
+  async getOrCreateItem(@Param('userId') userId: string, @Param('itemId') itemId: string) {
+    const result = await this.dismissibleService.getOrCreate(itemId, userId);
+    return {
+      item: result.item,
+      wasCreated: result.created,
+    };
+  }
+
+  @Delete(':userId/items/:itemId')
+  async dismissItem(@Param('userId') userId: string, @Param('itemId') itemId: string) {
+    const result = await this.dismissibleService.dismiss(itemId, userId);
+    return { item: result.item };
+  }
+
+  @Post(':userId/items/:itemId/restore')
+  async restoreItem(@Param('userId') userId: string, @Param('itemId') itemId: string) {
+    const result = await this.dismissibleService.restore(itemId, userId);
+    return { item: result.item };
+  }
+}
+```
+
+## Events
+
+The library emits events for all operations using NestJS's EventEmitter2:
 
 ```typescript
 import { Injectable } from '@nestjs/common';
@@ -305,7 +461,6 @@ import {
   ItemCreatedEvent,
   ItemDismissedEvent,
   ItemRestoredEvent,
-  ItemRetrievedEvent,
   DismissibleEvents,
 } from '@dismissible/nestjs-core';
 
@@ -313,188 +468,235 @@ import {
 export class AnalyticsService {
   @OnEvent(DismissibleEvents.ITEM_CREATED)
   handleItemCreated(event: ItemCreatedEvent) {
-    // Track item creation in analytics
-    console.log(`Analytics: Item ${event.id} created for user ${event.userId}`);
+    console.log(`Item ${event.id} created for user ${event.userId}`);
   }
 
   @OnEvent(DismissibleEvents.ITEM_DISMISSED)
   handleItemDismissed(event: ItemDismissedEvent) {
-    // Track dismissals
-    console.log(`Analytics: Item ${event.id} dismissed by user ${event.userId}`);
+    console.log(`Item ${event.id} dismissed by user ${event.userId}`);
   }
 
   @OnEvent(DismissibleEvents.ITEM_RESTORED)
   handleItemRestored(event: ItemRestoredEvent) {
-    // Track restorations
-    console.log(`Analytics: Item ${event.id} restored by user ${event.userId}`);
+    console.log(`Item ${event.id} restored by user ${event.userId}`);
   }
 }
 ```
 
-### Custom Logger
+Available events:
+
+- `DismissibleEvents.ITEM_CREATED` - New item created
+- `DismissibleEvents.ITEM_RETRIEVED` - Existing item retrieved
+- `DismissibleEvents.ITEM_DISMISSED` - Item dismissed
+- `DismissibleEvents.ITEM_RESTORED` - Item restored
+
+## Overriding Services
+
+All core services can be overridden using symbol-based dependency injection tokens. This allows you to provide custom implementations while maintaining type safety.
 
-Provide a custom logger implementation:
+### Available Service Tokens
+
+| Token                          | Interface                 | Description                                     |
+| ------------------------------ | ------------------------- | ----------------------------------------------- |
+| `DISMISSIBLE_SERVICE`          | `IDismissibleService`     | Main orchestration service                      |
+| `DISMISSIBLE_CORE_SERVICE`     | `IDismissibleCoreService` | Core business logic service                     |
+| `DISMISSIBLE_HOOK_RUNNER`      | `IHookRunner`             | Lifecycle hook execution                        |
+| `DISMISSIBLE_HELPER`           | `IDismissibleHelper`      | Helper utilities                                |
+| `DISMISSIBLE_DATE_SERVICE`     | `IDateService`            | Date operations                                 |
+| `DISMISSIBLE_RESPONSE_SERVICE` | `IResponseService`        | HTTP response formatting                        |
+| `DISMISSIBLE_ITEM_MAPPER`      | `IDismissibleItemMapper`  | Domain to DTO mapping                           |
+| `DISMISSIBLE_ITEM_FACTORY`     | `IDismissibleItemFactory` | Item creation (from `@dismissible/nestjs-item`) |
+
+### Example: Overriding the Date Service
+
+Override the date service to control time in tests or add custom behavior:
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { IDismissibleLogger } from '@dismissible/nestjs-logger';
-import { DismissibleModule } from '@dismissible/nestjs-core';
+import { Injectable, Module } from '@nestjs/common';
+import {
+  DismissibleModule,
+  IDateService,
+  DISMISSIBLE_DATE_SERVICE,
+} from '@dismissible/nestjs-core';
 
 @Injectable()
-export class CustomLogger implements IDismissibleLogger {
-  debug(message: string, context?: any) {
-    // Your custom logging logic
-    console.log(`[DEBUG] ${message}`, context);
+class CustomDateService implements IDateService {
+  getNow(): Date {
+    // Custom implementation - e.g., use a fixed time for testing
+    return new Date('2024-01-01T00:00:00.000Z');
   }
 
-  info(message: string, context?: any) {
-    console.log(`[INFO] ${message}`, context);
+  parseIso(isoString: string): Date {
+    return new Date(isoString);
   }
 
-  warn(message: string, context?: any) {
-    console.warn(`[WARN] ${message}`, context);
-  }
-
-  error(message: string, context?: any) {
-    console.error(`[ERROR] ${message}`, context);
+  toIso(date: Date): string {
+    return date.toISOString();
   }
 }
 
 @Module({
   imports: [
     DismissibleModule.forRoot({
-      logger: CustomLogger,
+      providers: [
+        CustomDateService,
+        { provide: DISMISSIBLE_DATE_SERVICE, useExisting: CustomDateService },
+      ],
     }),
   ],
 })
 export class AppModule {}
 ```
 
-## API Reference
-
-### DismissibleService
-
-The main service for interacting with dismissible items.
-
-#### Methods
-
-**`getOrCreate(itemId, userId, context?)`**
-
-Retrieves an existing item or creates a new one if it doesn't exist.
-
-- `itemId: string` - Unique identifier for the item
-- `userId: string` - User identifier (required)
-- `context?: IRequestContext` - Optional request context for tracing
-
-Returns: `Promise<IGetOrCreateServiceResponse>`
+### Example: Overriding the Main Service
 
-**`dismiss(itemId, userId, context?)`**
-
-Marks an item as dismissed.
-
-- `itemId: string` - Item identifier
-- `userId: string` - User identifier
-- `context?: IRequestContext` - Optional request context
-
-Returns: `Promise<IDismissServiceResponse>`
-
-**`restore(itemId, userId, context?)`**
-
-Restores a previously dismissed item.
-
-- `itemId: string` - Item identifier
-- `userId: string` - User identifier
-- `context?: IRequestContext` - Optional request context
-
-Returns: `Promise<IRestoreServiceResponse>`
-
-### Module Configuration
+Override the main dismissible service for custom orchestration logic:
 
 ```typescript
-interface IDismissibleModuleOptions {
-  // Custom storage module (defaults to memory storage)
-  storage?: DynamicModule | Type<any>;
-
-  // Custom logger implementation
-  logger?: Type<IDismissibleLogger>;
-
-  // Lifecycle hooks to register
-  hooks?: Type<IDismissibleLifecycleHook>[];
-}
-```
-
-## Events
-
-The library emits the following events:
-
-- `DismissibleEvents.ITEM_CREATED` - Emitted when a new item is created
-- `DismissibleEvents.ITEM_RETRIEVED` - Emitted when an existing item is retrieved
-- `DismissibleEvents.ITEM_DISMISSED` - Emitted when an item is dismissed
-- `DismissibleEvents.ITEM_RESTORED` - Emitted when an item is restored
-
-All events include:
-
-- `id: string` - The item identifier
-- `item: DismissibleItemDto` - The current item state
-- `userId: string` - The user identifier
-- `context?: IRequestContext` - Optional request context
+import { Injectable, Inject, Module } from '@nestjs/common';
+import {
+  DismissibleModule,
+  IDismissibleService,
+  IDismissibleCoreService,
+  DISMISSIBLE_SERVICE,
+  DISMISSIBLE_CORE_SERVICE,
+  IGetOrCreateServiceResponse,
+  IDismissServiceResponse,
+  IRestoreServiceResponse,
+} from '@dismissible/nestjs-core';
+import { IRequestContext } from '@dismissible/nestjs-request';
 
-Dismiss and restore events also include:
+@Injectable()
+class CustomDismissibleService implements IDismissibleService {
+  constructor(
+    @Inject(DISMISSIBLE_CORE_SERVICE)
+    private readonly coreService: IDismissibleCoreService,
+  ) {}
 
-- `previousItem: DismissibleItemDto` - The item state before the operation
+  async getOrCreate(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IGetOrCreateServiceResponse> {
+    // Add custom logic before/after core operation
+    console.log('Custom getOrCreate called');
+    return this.coreService.getOrCreate(itemId, userId);
+  }
 
-## Lifecycle Hooks
+  async dismiss(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IDismissServiceResponse> {
+    return this.coreService.dismiss(itemId, userId);
+  }
 
-Hooks can implement any of the following methods:
+  async restore(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IRestoreServiceResponse> {
+    return this.coreService.restore(itemId, userId);
+  }
+}
 
-- `onBeforeGetOrCreate()` - Called before get-or-create operation
-- `onAfterGetOrCreate()` - Called after get-or-create operation
-- `onBeforeCreate()` - Called before creating a new item
-- `onAfterCreate()` - Called after creating a new item
-- `onBeforeDismiss()` - Called before dismissing an item
-- `onAfterDismiss()` - Called after dismissing an item
-- `onBeforeRestore()` - Called before restoring an item
-- `onAfterRestore()` - Called after restoring an item
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      providers: [
+        CustomDismissibleService,
+        { provide: DISMISSIBLE_SERVICE, useExisting: CustomDismissibleService },
+      ],
+    }),
+  ],
+})
+export class AppModule {}
+```
 
-Hooks can:
+### Example: Overriding the Item Factory
 
-- **Block operations** by returning `{ proceed: false, reason: string }`
-- **Mutate parameters** by returning `{ proceed: true, mutations: { id?, userId?, context? } }`
-- **Perform side effects** in post-hooks (no return value needed)
+Override the item factory to customize how items are created:
 
-Hooks are executed in priority order (lower numbers first).
+```typescript
+import { Injectable, Module } from '@nestjs/common';
+import { DismissibleModule } from '@dismissible/nestjs-core';
+import {
+  DismissibleItemDto,
+  IDismissibleItemFactory,
+  ICreateDismissibleItemOptions,
+  DISMISSIBLE_ITEM_FACTORY,
+} from '@dismissible/nestjs-item';
 
-## Storage Adapters
+@Injectable()
+class CustomItemFactory implements IDismissibleItemFactory {
+  create(options: ICreateDismissibleItemOptions): DismissibleItemDto {
+    const item = new DismissibleItemDto();
+    item.id = options.id;
+    item.userId = options.userId;
+    item.createdAt = options.createdAt;
+    item.dismissedAt = options.dismissedAt;
+    return item;
+  }
 
-### In-Memory Storage (Default)
+  clone(item: DismissibleItemDto): DismissibleItemDto {
+    return this.create({
+      id: item.id,
+      createdAt: item.createdAt,
+      userId: item.userId,
+      dismissedAt: item.dismissedAt,
+    });
+  }
 
-The default storage adapter stores items in memory. Data is lost on application restart.
+  createDismissed(item: DismissibleItemDto, dismissedAt: Date): DismissibleItemDto {
+    return this.create({
+      id: item.id,
+      createdAt: item.createdAt,
+      userId: item.userId,
+      dismissedAt,
+    });
+  }
 
-### PostgreSQL Storage
+  createRestored(item: DismissibleItemDto): DismissibleItemDto {
+    return this.create({
+      id: item.id,
+      createdAt: item.createdAt,
+      userId: item.userId,
+      dismissedAt: undefined,
+    });
+  }
+}
 
-Use `PostgresStorageModule` for persistent storage. See the [Using PostgreSQL Storage](#using-postgresql-storage) section above.
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      providers: [
+        CustomItemFactory,
+        { provide: DISMISSIBLE_ITEM_FACTORY, useExisting: CustomItemFactory },
+      ],
+    }),
+  ],
+})
+export class AppModule {}
+```
 
-### Custom Storage Adapter
+### Injecting Overridable Services
 
-Implement the `IDismissibleStorage` interface to create a custom storage adapter:
+When injecting these services in your own code, use the symbol tokens for maximum flexibility:
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { IDismissibleStorage } from '@dismissible/nestjs-storage';
-import { DismissibleItemDto } from '@dismissible/nestjs-item';
+import { Injectable, Inject } from '@nestjs/common';
+import { IDismissibleService, DISMISSIBLE_SERVICE } from '@dismissible/nestjs-core';
 
 @Injectable()
-export class RedisStorageAdapter implements IDismissibleStorage {
-  async get(userId: string, itemId: string): Promise<DismissibleItemDto | null> {
-    // Your implementation
-  }
-
-  async create(userId: string, item: DismissibleItemDto): Promise<void> {
-    // Your implementation
-  }
-
-  async update(userId: string, item: DismissibleItemDto): Promise<void> {
-    // Your implementation
+export class MyService {
+  constructor(
+    @Inject(DISMISSIBLE_SERVICE)
+    private readonly dismissibleService: IDismissibleService,
+  ) {}
+
+  async myMethod(userId: string, itemId: string) {
+    // Your custom implementation will be injected if you've overridden it
+    return this.dismissibleService.getOrCreate(itemId, userId);
   }
 }
 ```