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

package/README.md

@@ -0,0 +1,131 @@
+# @dismissible/nestjs-dismissible-item
+
+Core data models and factory for dismissible items in NestJS applications.
+
+> **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.
+
+## Overview
+
+This library provides the foundational data structures for the Dismissible system:
+
+- `DismissibleItemDto` - The core data transfer object representing a dismissible item
+- `DismissibleItemFactory` - Factory for creating and manipulating dismissible items
+- `BaseMetadata` - Type definition for item metadata
+
+## Installation
+
+```bash
+npm install @dismissible/nestjs-dismissible-item
+```
+
+## Getting Started
+
+### Basic Usage
+
+The `DismissibleItemDto` class represents a dismissible item with the following properties:
+
+- `id` - Unique identifier for the item
+- `userId` - User identifier who owns the item
+- `createdAt` - Timestamp when the item was created
+- `dismissedAt` - Optional timestamp when the item was dismissed
+- `metadata` - Optional metadata object (type-safe with generics)
+
+```typescript
+import { DismissibleItemDto, BaseMetadata } from '@dismissible/nestjs-dismissible-item';
+
+interface MyMetadata extends BaseMetadata {
+  version: number;
+  category: string;
+}
+
+const item: DismissibleItemDto<MyMetadata> = {
+  id: 'welcome-banner',
+  userId: 'user-123',
+  createdAt: new Date(),
+  metadata: {
+    version: 2,
+    category: 'onboarding',
+  },
+};
+```
+
+### Using the Factory
+
+The `DismissibleItemFactory` provides methods for creating and manipulating items:
+
+```typescript
+import { Module } from '@nestjs/common';
+import {
+  DismissibleItemModule,
+  DismissibleItemFactory,
+} from '@dismissible/nestjs-dismissible-item';
+
+@Module({
+  imports: [DismissibleItemModule],
+})
+export class AppModule {}
+
+// In your service
+import { Injectable } from '@nestjs/common';
+import { DismissibleItemFactory, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+
+@Injectable()
+export class MyService {
+  constructor(private readonly itemFactory: DismissibleItemFactory) {}
+
+  createItem(): DismissibleItemDto {
+    return this.itemFactory.create({
+      id: 'welcome-banner',
+      userId: 'user-123',
+      createdAt: new Date(),
+    });
+  }
+
+  dismissItem(item: DismissibleItemDto): DismissibleItemDto {
+    return this.itemFactory.createDismissed(item, new Date());
+  }
+
+  restoreItem(item: DismissibleItemDto): DismissibleItemDto {
+    return this.itemFactory.createRestored(item);
+  }
+}
+```
+
+## API Reference
+
+### DismissibleItemDto
+
+The main data transfer object for dismissible items.
+
+```typescript
+class DismissibleItemDto<TMetadata extends BaseMetadata = BaseMetadata> {
+  id: string;
+  userId: string;
+  createdAt: Date;
+  dismissedAt?: Date;
+  metadata?: TMetadata;
+}
+```
+
+### DismissibleItemFactory
+
+Factory for creating and manipulating dismissible items.
+
+#### Methods
+
+- `create(options)` - Create a new item from options
+- `clone(item)` - Create a clone of an existing item
+- `createDismissed(item, dismissedAt)` - Create a dismissed version of an item
+- `createRestored(item)` - Create a restored (non-dismissed) version of an item
+
+## Related Packages
+
+This library is typically used alongside other Dismissible packages:
+
+- `@dismissible/nestjs-dismissible` - Main dismissible service and module
+- `@dismissible/nestjs-storage` - Storage interface and adapters
+- `@dismissible/nestjs-postgres-storage` - PostgreSQL storage adapter
+
+## License
+
+MIT

package/jest.config.ts

@@ -0,0 +1,10 @@
+export default {
+  displayName: 'dismissible-item',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/libs/dismissible-item',
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dismissible/nestjs-dismissible-item",
+  "version": "0.0.2-canary.738340d.0",
+  "description": "Dismissible item library",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.mjs",
+      "require": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": false
+    }
+  },
+  "keywords": [
+    "nestjs",
+    "dismissible",
+    "dismissible-item"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/project.json

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

package/src/dismissible-item.factory.spec.ts

@@ -0,0 +1,124 @@
+import { DismissibleItemFactory } from './dismissible-item.factory';
+import { DismissibleItemDto } from './dismissible-item';
+
+describe('DismissibleItemFactory', () => {
+  let factory: DismissibleItemFactory;
+
+  beforeEach(() => {
+    factory = new DismissibleItemFactory();
+  });
+
+  describe('create', () => {
+    it('should create a DismissibleItemDto instance', () => {
+      const item = factory.create({
+        id: 'test-id',
+        createdAt: new Date('2024-01-15T10:00:00.000Z'),
+      });
+
+      expect(item).toBeInstanceOf(DismissibleItemDto);
+      expect(item.id).toBe('test-id');
+      expect(item.createdAt).toEqual(new Date('2024-01-15T10:00:00.000Z'));
+    });
+
+    it('should handle optional properties when undefined', () => {
+      const item = factory.create({
+        id: 'test-id',
+        createdAt: new Date('2024-01-15T10:00:00.000Z'),
+        userId: undefined,
+        metadata: undefined,
+        dismissedAt: undefined,
+      });
+
+      expect(item.id).toBe('test-id');
+      expect(item.createdAt).toEqual(new Date('2024-01-15T10:00:00.000Z'));
+      expect(item.userId).toBeUndefined();
+      expect(item.metadata).toBeUndefined();
+      expect(item.dismissedAt).toBeUndefined();
+    });
+
+    it('should include optional properties when provided', () => {
+      const metadata = { version: 2, category: 'test' };
+      const item = factory.create({
+        id: 'test-id',
+        createdAt: new Date('2024-01-15T10:00:00.000Z'),
+        userId: 'user-123',
+        metadata,
+        dismissedAt: new Date('2024-01-15T12:00:00.000Z'),
+      });
+
+      expect(item.userId).toBe('user-123');
+      expect(item.metadata).toEqual(metadata);
+      expect(item.dismissedAt).toEqual(new Date('2024-01-15T12:00:00.000Z'));
+    });
+  });
+
+  describe('clone', () => {
+    it('should create an identical copy of an item', () => {
+      const original = factory.create({
+        id: 'test-id',
+        createdAt: new Date('2024-01-15T10:00:00.000Z'),
+        userId: 'user-123',
+        metadata: { key: 'value' },
+      });
+
+      const cloned = factory.clone(original);
+
+      expect(cloned).toBeInstanceOf(DismissibleItemDto);
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original); // Different object reference
+    });
+  });
+
+  describe('createDismissed', () => {
+    it('should create a dismissed version with dismissedAt set', () => {
+      const original = factory.create({
+        id: 'test-id',
+        createdAt: new Date('2024-01-15T10:00:00.000Z'),
+        userId: 'user-123',
+      });
+
+      const dismissed = factory.createDismissed(original, new Date('2024-01-15T12:00:00.000Z'));
+
+      expect(dismissed).toBeInstanceOf(DismissibleItemDto);
+      expect(dismissed.id).toBe(original.id);
+      expect(dismissed.createdAt).toEqual(original.createdAt);
+      expect(dismissed.userId).toBe(original.userId);
+      expect(dismissed.dismissedAt).toEqual(new Date('2024-01-15T12:00:00.000Z'));
+    });
+  });
+
+  describe('createRestored', () => {
+    it('should create a restored version without dismissedAt', () => {
+      const dismissed = factory.create({
+        id: 'test-id',
+        createdAt: new Date('2024-01-15T10:00:00.000Z'),
+        userId: 'user-123',
+        dismissedAt: new Date('2024-01-15T12:00:00.000Z'),
+      });
+
+      const restored = factory.createRestored(dismissed);
+
+      expect(restored).toBeInstanceOf(DismissibleItemDto);
+      expect(restored.id).toBe(dismissed.id);
+      expect(restored.createdAt).toEqual(dismissed.createdAt);
+      expect(restored.userId).toBe(dismissed.userId);
+      expect(restored.dismissedAt).toBeUndefined();
+    });
+
+    it('should preserve metadata when restoring', () => {
+      const metadata = { key: 'value', count: 42 };
+      const dismissed = factory.create({
+        id: 'test-id',
+        createdAt: new Date('2024-01-15T10:00:00.000Z'),
+        userId: 'user-123',
+        metadata,
+        dismissedAt: new Date('2024-01-15T12:00:00.000Z'),
+      });
+
+      const restored = factory.createRestored(dismissed);
+
+      expect(restored.metadata).toEqual(metadata);
+      expect(restored.metadata).not.toBe(dismissed.metadata); // Different object reference
+    });
+  });
+});

package/src/dismissible-item.factory.ts

@@ -0,0 +1,81 @@
+import { Injectable } from '@nestjs/common';
+import { plainToInstance } from 'class-transformer';
+import { BaseMetadata, DismissibleItemDto } from './dismissible-item';
+
+/**
+ * Options for creating a dismissible item.
+ */
+export interface ICreateDismissibleItemOptions<TMetadata extends BaseMetadata> {
+  id: string;
+  createdAt: Date;
+  userId?: string;
+  metadata?: TMetadata;
+  dismissedAt?: Date;
+}
+
+/**
+ * Factory for creating DismissibleItemDto instances.
+ * Uses class-transformer to ensure proper class instantiation.
+ */
+@Injectable()
+export class DismissibleItemFactory {
+  /**
+   * Create a new DismissibleItemDto instance from the provided options.
+   * Uses plainToInstance to ensure the result is a proper class instance.
+   */
+  create<TMetadata extends BaseMetadata = BaseMetadata>(
+    options: ICreateDismissibleItemOptions<TMetadata>,
+  ): DismissibleItemDto<TMetadata> {
+    return plainToInstance(DismissibleItemDto<TMetadata>, options, {
+      excludeExtraneousValues: false,
+      enableImplicitConversion: true,
+    });
+  }
+
+  /**
+   * Create a clone of an existing DismissibleItemDto.
+   */
+  clone<TMetadata extends BaseMetadata = BaseMetadata>(
+    item: DismissibleItemDto<TMetadata>,
+  ): DismissibleItemDto<TMetadata> {
+    return this.create({
+      id: item.id,
+      createdAt: item.createdAt,
+      userId: item.userId,
+      metadata: item.metadata,
+      dismissedAt: item.dismissedAt,
+    });
+  }
+
+  /**
+   * Create a dismissed version of an existing item.
+   */
+  createDismissed<TMetadata extends BaseMetadata = BaseMetadata>(
+    item: DismissibleItemDto<TMetadata>,
+    dismissedAt: Date,
+  ): DismissibleItemDto<TMetadata> {
+    return this.create({
+      id: item.id,
+      createdAt: item.createdAt,
+      userId: item.userId,
+      metadata: item.metadata,
+      dismissedAt,
+    });
+  }
+
+  /**
+   * Create a restored (non-dismissed) version of an existing item.
+   * Removes the dismissedAt property.
+   */
+  createRestored<TMetadata extends BaseMetadata = BaseMetadata>(
+    item: DismissibleItemDto<TMetadata>,
+  ): DismissibleItemDto<TMetadata> {
+    return this.create({
+      id: item.id,
+      createdAt: item.createdAt,
+      userId: item.userId,
+      metadata: item.metadata,
+      dismissedAt: undefined,
+    });
+  }
+}

package/src/dismissible-item.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { DismissibleItemFactory } from './dismissible-item.factory';
+
+@Module({
+  providers: [DismissibleItemFactory],
+  exports: [DismissibleItemFactory],
+})
+export class DismissibleItemModule {}

package/src/dismissible-item.ts

@@ -0,0 +1,55 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsString, IsDate, IsOptional, IsObject } from 'class-validator';
+import { Type } from 'class-transformer';
+
+/**
+ * Base metadata type for dismissible items.
+ * Can be extended with custom metadata fields.
+ */
+export type BaseMetadata = Record<string, unknown>;
+
+/**
+ * Represents a dismissible item in the system.
+ */
+export class DismissibleItemDto<TMetadata extends BaseMetadata = BaseMetadata> {
+  @ApiProperty({
+    description: 'Unique identifier for the item',
+    example: 'welcome-banner-v2',
+  })
+  @IsString()
+  id!: string;
+
+  @ApiProperty({
+    description: 'User identifier who created the item',
+    example: 'user-123',
+  })
+  @IsString()
+  userId!: string;
+
+  @ApiProperty({
+    description: 'When the item was created',
+    example: '2024-01-15T10:30:00.000Z',
+  })
+  @IsDate()
+  @Type(() => Date)
+  createdAt!: Date;
+
+  @ApiPropertyOptional({
+    description: 'When the item was dismissed, if applicable',
+    example: '2024-01-15T12:00:00.000Z',
+  })
+  @IsOptional()
+  @IsDate()
+  @Type(() => Date)
+  dismissedAt?: Date;
+
+  @ApiPropertyOptional({
+    description: 'Optional metadata associated with the item',
+    example: { version: 2, category: 'promotional' },
+    type: 'object',
+    additionalProperties: true,
+  })
+  @IsOptional()
+  @IsObject()
+  metadata?: TMetadata;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './dismissible-item';
+export * from './dismissible-item.factory';
+export * from './dismissible-item.module';

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ],
+  "compilerOptions": {
+    "esModuleInterop": true
+  }
+}

package/tsconfig.lib.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "module": "commonjs",
+    "types": ["node"],
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "target": "ES2021"
+  },
+  "exclude": ["node_modules", "**/*.spec.ts", "**/*.test.ts"],
+  "include": ["src/**/*.ts"]
+}