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

package/README.md

@@ -0,0 +1,506 @@
+# @dismissible/nestjs-dismissible
+
+A powerful NestJS library for managing dismissible state in your applications. Perfect for feature flags, 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.
+
+## Features
+
+- 🚀 **Simple API** - Easy-to-use service methods for get-or-create, dismiss, and restore operations
+- 💾 **Flexible Storage** - Default in-memory storage with support for custom storage adapters (PostgreSQL, Redis, etc.)
+- 🔌 **Lifecycle Hooks** - Intercept and customize operations with pre/post hooks
+- 📡 **Event-Driven** - Built-in event emission for all operations
+- 🎯 **Type-Safe** - Full TypeScript support with generic metadata types
+- 🛡️ **Validation** - Automatic validation of dismissible items
+- 📝 **Swagger Integration** - Auto-generated API documentation
+- ⚛️ **React Client** - Works out of the box with [@dismissible/react-client](https://www.npmjs.com/package/@dismissible/react-client)
+
+## Installation
+
+```bash
+npm install @dismissible/nestjs-dismissible
+```
+
+## Getting Started
+
+### Basic Setup
+
+The simplest way to get started is with the default configuration, which uses in-memory storage:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { DismissibleModule } from '@dismissible/nestjs-dismissible';
+
+@Module({
+  imports: [DismissibleModule.forRoot({})],
+})
+export class AppModule {}
+```
+
+### Built-in REST API
+
+The module automatically registers REST endpoints for all operations:
+
+- `GET /v1/user/:userId/dismissible-item/:itemId` - Get or create an item
+- `DELETE /v1/user/:userId/dismissible-item/:itemId` - Dismiss an item
+- `POST /v1/user/:userId/dismissible-item/:itemId` - Restore a dismissed item
+
+Example request:
+
+```bash
+# Get or create an item
+curl http://localhost:3000/v1/user/user-123/dismissible-item/welcome-banner?metadata=version:2&metadata=category:onboarding
+
+# Dismiss an item
+curl -X DELETE http://localhost:3000/v1/user/user-123/dismissible-item/welcome-banner
+
+# Restore a dismissed item
+curl -X POST http://localhost:3000/v1/user/user-123/dismissible-item/welcome-banner
+```
+
+### React Client Integration
+
+This library works seamlessly with the [@dismissible/react-client](https://www.npmjs.com/package/@dismissible/react-client) package. Once your NestJS backend is set up with the built-in REST API endpoints, you can use the React client in your frontend:
+
+```bash
+npm install @dismissible/react-client
+```
+
+```typescript
+import { DismissibleProvider, useDismissible } from '@dismissible/react-client';
+
+function App() {
+  return (
+    <DismissibleProvider
+      apiUrl="http://localhost:3000"
+      userId="user-123"
+    >
+      <WelcomeBanner />
+    </DismissibleProvider>
+  );
+}
+
+function WelcomeBanner() {
+  const { item, dismiss, isLoading } = useDismissible('welcome-banner');
+
+  if (isLoading) return <div>Loading...</div>;
+  if (item?.dismissedAt) return null;
+
+  return (
+    <div>
+      <h2>Welcome!</h2>
+      <button onClick={() => dismiss()}>Dismiss</button>
+    </div>
+  );
+}
+```
+
+The React client automatically uses the built-in REST API endpoints, so no additional configuration is needed on the backend.
+
+## Advanced Usage
+
+### Using PostgreSQL Storage
+
+To persist dismissible items in a PostgreSQL database, use the `PostgresStorageModule`:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { DismissibleModule } from '@dismissible/nestjs-dismissible';
+import { PostgresStorageModule } from '@dismissible/nestjs-postgres-storage';
+
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      storage: PostgresStorageModule,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+**Prerequisites:**
+
+1. Install the PostgreSQL storage package:
+
+   ```bash
+   npm install @dismissible/nestjs-postgres-storage
+   ```
+
+2. Set up your database connection string:
+
+   ```env
+   DISMISSIBLE_POSTGRES_STORAGE_CONNECTION_STRING=postgresql://user:password@localhost:5432/dismissible
+   ```
+
+3. Run Prisma migrations (if using Prisma):
+   ```bash
+   npx prisma migrate dev
+   ```
+
+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:
+
+```typescript
+import { Controller, Get, Param, Delete, Post } from '@nestjs/common';
+import { DismissibleService } from '@dismissible/nestjs-dismissible';
+
+@Controller('features')
+export class FeaturesController {
+  constructor(private readonly dismissibleService: DismissibleService) {}
+
+  @Get(':userId/items/:itemId')
+  async getOrCreateItem(@Param('userId') userId: string, @Param('itemId') itemId: string) {
+    const result = await this.dismissibleService.getOrCreate(
+      itemId,
+      userId,
+      {
+        metadata: { version: '1.0', category: 'onboarding' },
+      },
+      undefined, // optional request context
+    );
+
+    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 };
+  }
+}
+```
+
+### Custom Lifecycle Hooks
+
+Lifecycle hooks allow you to intercept operations and add custom logic, validation, or mutations:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IDismissibleLifecycleHook, IHookResult } from '@dismissible/nestjs-dismissible';
+import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
+
+@Injectable()
+export class AuditHook implements IDismissibleLifecycleHook<BaseMetadata> {
+  // Lower priority runs first (default is 0)
+  readonly priority = 10;
+
+  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 };
+  }
+
+  async onAfterCreate(
+    itemId: string,
+    item: DismissibleItemDto<BaseMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    // Log item creation for analytics
+    console.log(`Item created: ${itemId} for user ${userId}`);
+  }
+
+  // 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(),
+      },
+    };
+  }
+}
+```
+
+Register hooks in your module:
+
+```typescript
+import { DismissibleModule } from '@dismissible/nestjs-dismissible';
+import { AuditHook } from './hooks/audit.hook';
+
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      hooks: [AuditHook],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Listening to Events
+
+The library emits events for all operations. Listen to them using NestJS's `EventEmitter2`:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import {
+  ItemCreatedEvent,
+  ItemDismissedEvent,
+  ItemRestoredEvent,
+  ItemRetrievedEvent,
+  DismissibleEvents,
+} from '@dismissible/nestjs-dismissible';
+
+@Injectable()
+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}`);
+  }
+
+  @OnEvent(DismissibleEvents.ITEM_DISMISSED)
+  handleItemDismissed(event: ItemDismissedEvent) {
+    // Track dismissals
+    console.log(`Analytics: 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}`);
+  }
+}
+```
+
+### Custom Metadata Types
+
+Define custom metadata types for type-safe item properties:
+
+```typescript
+import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
+
+interface OnboardingMetadata extends BaseMetadata {
+  step: number;
+  completedAt?: string;
+  skipped: boolean;
+}
+
+// Use in your service
+@Injectable()
+export class OnboardingService {
+  constructor(private readonly dismissibleService: DismissibleService<OnboardingMetadata>) {}
+
+  async trackStep(userId: string, step: number) {
+    const result = await this.dismissibleService.getOrCreate(
+      `onboarding-step-${step}`,
+      userId,
+      {
+        metadata: {
+          step,
+          skipped: false,
+        },
+      },
+      undefined,
+    );
+
+    return result.item;
+  }
+}
+```
+
+### Custom Logger
+
+Provide a custom logger implementation:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IDismissibleLogger } from '@dismissible/nestjs-logger';
+import { DismissibleModule } from '@dismissible/nestjs-dismissible';
+
+@Injectable()
+export class CustomLogger implements IDismissibleLogger {
+  debug(message: string, context?: any) {
+    // Your custom logging logic
+    console.log(`[DEBUG] ${message}`, context);
+  }
+
+  info(message: string, context?: any) {
+    console.log(`[INFO] ${message}`, context);
+  }
+
+  warn(message: string, context?: any) {
+    console.warn(`[WARN] ${message}`, context);
+  }
+
+  error(message: string, context?: any) {
+    console.error(`[ERROR] ${message}`, context);
+  }
+}
+
+@Module({
+  imports: [
+    DismissibleModule.forRoot({
+      logger: CustomLogger,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## API Reference
+
+### DismissibleService
+
+The main service for interacting with dismissible items.
+
+#### Methods
+
+**`getOrCreate(itemId, userId, options?, 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)
+- `options?: ICreateItemOptions<TMetadata>` - Optional creation options
+  - `metadata?: TMetadata` - Custom metadata to attach to the item
+- `context?: IRequestContext` - Optional request context for tracing
+
+Returns: `Promise<IGetOrCreateServiceResponse<TMetadata>>`
+
+**`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<TMetadata>>`
+
+**`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<TMetadata>>`
+
+### Module Configuration
+
+```typescript
+interface IDismissibleModuleOptions<TMetadata extends BaseMetadata> {
+  // Custom storage module (defaults to in-memory storage)
+  storage?: DynamicModule | Type<any>;
+
+  // Custom logger implementation
+  logger?: Type<IDismissibleLogger>;
+
+  // Lifecycle hooks to register
+  hooks?: Type<IDismissibleLifecycleHook<TMetadata>>[];
+}
+```
+
+## 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<TMetadata>` - The current item state
+- `userId: string` - The user identifier
+- `context?: IRequestContext` - Optional request context
+
+Dismiss and restore events also include:
+
+- `previousItem: DismissibleItemDto<TMetadata>` - The item state before the operation
+
+## Lifecycle Hooks
+
+Hooks can implement any of the following methods:
+
+- `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
+
+Hooks can:
+
+- **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)
+
+Hooks are executed in priority order (lower numbers first).
+
+## Storage Adapters
+
+### In-Memory Storage (Default)
+
+The default storage adapter stores items in memory. Data is lost on application restart.
+
+### PostgreSQL Storage
+
+Use `PostgresStorageModule` for persistent storage. See the [Using PostgreSQL Storage](#using-postgresql-storage) section above.
+
+### Custom Storage Adapter
+
+Implement the `IDismissibleStorage` interface to create a custom storage adapter:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IDismissibleStorage } from '@dismissible/nestjs-storage';
+import { DismissibleItemDto, BaseMetadata } from '@dismissible/nestjs-dismissible-item';
+
+@Injectable()
+export class RedisStorageAdapter<
+  TMetadata extends BaseMetadata,
+> implements IDismissibleStorage<TMetadata> {
+  async get(userId: string, itemId: string): Promise<DismissibleItemDto<TMetadata> | null> {
+    // Your implementation
+  }
+
+  async create(userId: string, item: DismissibleItemDto<TMetadata>): Promise<void> {
+    // Your implementation
+  }
+
+  async update(userId: string, item: DismissibleItemDto<TMetadata>): Promise<void> {
+    // Your implementation
+  }
+}
+```
+
+## License
+
+MIT

package/jest.config.ts

@@ -0,0 +1,29 @@
+export default {
+  displayName: 'dismissible',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/libs/dismissible',
+  transformIgnorePatterns: ['node_modules/(?!(uuid)/)'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.spec.ts',
+    '!src/**/*.interface.ts',
+    '!src/**/*.dto.ts',
+    '!src/**/*.enum.ts',
+    '!src/**/index.ts',
+    '!src/**/*.module.ts',
+  ],
+  coverageReporters: ['text', 'text-summary', 'html'],
+  coverageThreshold: {
+    global: {
+      branches: 81,
+      functions: 84,
+      lines: 92,
+      statements: 92,
+    },
+  },
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@dismissible/nestjs-dismissible",
+  "version": "0.0.2-canary.738340d.0",
+  "description": "Dismissible state management library for NestJS applications",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.mjs",
+      "require": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@nestjs/event-emitter": "^3.0.0",
+    "uuid": "^11.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/swagger": "^11.0.0",
+    "@dismissible/nestjs-dismissible-item": "^0.0.2-canary.738340d.0",
+    "@dismissible/nestjs-storage": "^0.0.2-canary.738340d.0",
+    "class-validator": "^0.14.0",
+    "class-transformer": "^0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": false
+    },
+    "@nestjs/core": {
+      "optional": false
+    },
+    "@nestjs/swagger": {
+      "optional": false
+    },
+    "dismissible/nestjs-dismissible-item": {
+      "optional": false
+    },
+    "@dismissible/nestjs-storage": {
+      "optional": false
+    },
+    "class-validator": {
+      "optional": false
+    },
+    "class-transformer": {
+      "optional": false
+    }
+  },
+  "keywords": [
+    "nestjs",
+    "dismissible",
+    "state-management",
+    "feature-flags",
+    "dismissals"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/project.json

@@ -0,0 +1,42 @@
+{
+  "name": "dismissible",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/dismissible/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/dismissible",
+        "main": "libs/dismissible/src/index.ts",
+        "tsConfig": "libs/dismissible/tsconfig.lib.json",
+        "assets": ["libs/dismissible/package.json", "libs/dismissible/README.md"],
+        "generatePackageJson": true
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["libs/dismissible/**/*.ts"]
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/libs/dismissible"],
+      "options": {
+        "jestConfig": "libs/dismissible/jest.config.ts",
+        "passWithNoTests": true
+      }
+    },
+    "npm-publish": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "npm publish --access public",
+        "cwd": "dist/libs/dismissible"
+      }
+    }
+  }
+}

package/src/api/dismissible-item-response.dto.ts

@@ -0,0 +1,38 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+/**
+ * Response DTO for a dismissible item.
+ */
+export class DismissibleItemResponseDto {
+  @ApiProperty({
+    description: 'Unique identifier for the item',
+    example: 'welcome-banner-v2',
+  })
+  itemId!: string;
+
+  @ApiProperty({
+    description: 'User identifier who created the item',
+    example: 'user-123',
+  })
+  userId!: string;
+
+  @ApiProperty({
+    description: 'When the item was created (ISO 8601)',
+    example: '2024-01-15T10:30:00.000Z',
+  })
+  createdAt!: string;
+
+  @ApiPropertyOptional({
+    description: 'When the item was dismissed (ISO 8601)',
+    example: '2024-01-15T12:00:00.000Z',
+  })
+  dismissedAt?: string;
+
+  @ApiPropertyOptional({
+    description: 'Optional metadata associated with the item',
+    example: { version: 2, category: 'promotional' },
+    type: 'object',
+    additionalProperties: true,
+  })
+  metadata?: Record<string, unknown>;
+}