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

package/README.md

@@ -0,0 +1,150 @@
+# @dismissible/nestjs-storage
+
+Storage interface and in-memory adapter for the Dismissible system.
+
+> **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:
+
+- `IDismissibleStorage` - Interface that all storage adapters must implement
+- `MemoryStorageAdapter` - In-memory storage implementation (useful for development and testing)
+- Storage abstraction layer for the Dismissible system
+
+## Installation
+
+```bash
+npm install @dismissible/nestjs-storage
+```
+
+## Getting Started
+
+### Using In-Memory Storage
+
+The in-memory storage adapter is useful for development, testing, or when you don't need persistence:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { StorageModule, MemoryStorageAdapter } from '@dismissible/nestjs-storage';
+import { LoggerModule } from '@dismissible/nestjs-logger';
+import { DismissibleItemModule } from '@dismissible/nestjs-dismissible-item';
+
+@Module({
+  imports: [
+    LoggerModule.forRoot({}),
+    DismissibleItemModule,
+    StorageModule.forRoot({
+      adapter: MemoryStorageAdapter,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Implementing a Custom Storage Adapter
+
+You can implement your own storage adapter by implementing the `IDismissibleStorage` interface:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IDismissibleStorage, DISMISSIBLE_STORAGE_ADAPTER } from '@dismissible/nestjs-storage';
+import { DismissibleItemDto, BaseMetadata } from '@dismissible/nestjs-dismissible-item';
+import { DISMISSIBLE_LOGGER, IDismissibleLogger } from '@dismissible/nestjs-logger';
+
+@Injectable()
+export class MyCustomStorageAdapter<
+  TMetadata extends BaseMetadata,
+> implements IDismissibleStorage<TMetadata> {
+  constructor(@Inject(DISMISSIBLE_LOGGER) private readonly logger: IDismissibleLogger) {}
+
+  async get(userId: string, itemId: string): Promise<DismissibleItemDto<TMetadata> | null> {
+    // Your implementation
+    this.logger.debug('Getting item', { userId, itemId });
+    // ...
+  }
+
+  async create(item: DismissibleItemDto<TMetadata>): Promise<DismissibleItemDto<TMetadata>> {
+    // Your implementation
+    this.logger.debug('Creating item', { itemId: item.id });
+    // ...
+  }
+
+  async update(item: DismissibleItemDto<TMetadata>): Promise<DismissibleItemDto<TMetadata>> {
+    // Your implementation
+    this.logger.debug('Updating item', { itemId: item.id });
+    // ...
+  }
+}
+
+// Register your adapter
+@Module({
+  providers: [
+    MyCustomStorageAdapter,
+    {
+      provide: DISMISSIBLE_STORAGE_ADAPTER,
+      useExisting: MyCustomStorageAdapter,
+    },
+  ],
+  exports: [DISMISSIBLE_STORAGE_ADAPTER],
+})
+export class MyStorageModule {}
+```
+
+## API Reference
+
+### IDismissibleStorage Interface
+
+```typescript
+interface IDismissibleStorage<TMetadata extends BaseMetadata = BaseMetadata> {
+  get(userId: string, itemId: string): Promise<DismissibleItemDto<TMetadata> | null>;
+  create(item: DismissibleItemDto<TMetadata>): Promise<DismissibleItemDto<TMetadata>>;
+  update(item: DismissibleItemDto<TMetadata>): Promise<DismissibleItemDto<TMetadata>>;
+}
+```
+
+### MemoryStorageAdapter
+
+An in-memory implementation of `IDismissibleStorage`. Data is stored in a `Map` and will be lost when the application restarts.
+
+**Note:** This adapter is suitable for development and testing only. For production use, consider using `@dismissible/nestjs-postgres-storage` or implementing your own persistent storage adapter.
+
+### StorageModule
+
+#### `StorageModule.forRoot(options)`
+
+Configures the storage module with the provided adapter.
+
+**Options:**
+
+- `adapter: Type<IDismissibleStorage>` - The storage adapter class to use
+
+**Returns:** `DynamicModule`
+
+## Injection Token
+
+The storage adapter is provided via the `DISMISSIBLE_STORAGE_ADAPTER` injection token:
+
+```typescript
+import { Inject } from '@nestjs/common';
+import { DISMISSIBLE_STORAGE_ADAPTER, IDismissibleStorage } from '@dismissible/nestjs-storage';
+
+@Injectable()
+export class MyService {
+  constructor(
+    @Inject(DISMISSIBLE_STORAGE_ADAPTER)
+    private readonly storage: IDismissibleStorage,
+  ) {}
+}
+```
+
+## Related Packages
+
+- `@dismissible/nestjs-dismissible` - Main dismissible service (uses storage adapters)
+- `@dismissible/nestjs-postgres-storage` - PostgreSQL storage adapter implementation
+- `@dismissible/nestjs-dismissible-item` - Data models used by storage adapters
+- `@dismissible/nestjs-logger` - Logging used by storage adapters
+
+## License
+
+MIT

package/jest.config.ts

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

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dismissible/nestjs-storage",
+  "version": "0.0.2-canary.738340d.0",
+  "description": "In-memory storage adapter for Dismissible",
+  "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",
+    "@dismissible/nestjs-logger": "^0.0.2-canary.738340d.0",
+    "@dismissible/nestjs-dismissible-item": "^0.0.2-canary.738340d.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": false
+    },
+    "@dismissible/nestjs-logger": {
+      "optional": false
+    },
+    "@dismissible/nestjs-dismissible-item": {
+      "optional": false
+    }
+  },
+  "keywords": [
+    "nestjs",
+    "dismissible",
+    "storage",
+    "storage",
+    "adapter"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/project.json

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

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './memory-storage.adapter';
+export * from './storage.interface';
+export * from './storage.module';

package/src/memory-storage.adapter.ts

@@ -0,0 +1,70 @@
+import { Injectable, Inject } from '@nestjs/common';
+import { DISMISSIBLE_LOGGER, IDismissibleLogger } from '@dismissible/nestjs-logger';
+import { IDismissibleStorage } from './storage.interface';
+import { BaseMetadata, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+
+/**
+ * In-memory storage provider for dismissible items.
+ * Suitable for development and testing; not for production use.
+ */
+@Injectable()
+export class MemoryStorageAdapter<
+  TMetadata extends BaseMetadata = BaseMetadata,
+> implements IDismissibleStorage<TMetadata> {
+  private readonly storage = new Map<string, DismissibleItemDto<TMetadata>>();
+
+  constructor(@Inject(DISMISSIBLE_LOGGER) private readonly logger: IDismissibleLogger) {}
+
+  /**
+   * Create a storage key from userId and itemId.
+   */
+  private createKey(userId: string, itemId: string): string {
+    return `${userId}:${itemId}`;
+  }
+
+  async get(userId: string, itemId: string): Promise<DismissibleItemDto<TMetadata> | null> {
+    const key = this.createKey(userId, itemId);
+    this.logger.debug(`Storage get`, { userId, itemId, key });
+
+    const item = this.storage.get(key);
+
+    if (!item) {
+      this.logger.debug(`Storage miss`, { userId, itemId });
+      return null;
+    }
+
+    this.logger.debug(`Storage hit`, { userId, itemId });
+    return item;
+  }
+
+  async create(item: DismissibleItemDto<TMetadata>): Promise<DismissibleItemDto<TMetadata>> {
+    const key = this.createKey(item.userId, item.id);
+    this.logger.debug(`Storage create`, { userId: item.userId, itemId: item.id, key });
+    this.storage.set(key, item);
+    return item;
+  }
+
+  async update(item: DismissibleItemDto<TMetadata>): Promise<DismissibleItemDto<TMetadata>> {
+    const key = this.createKey(item.userId, item.id);
+    this.logger.debug(`Storage update`, { userId: item.userId, itemId: item.id, key });
+    this.storage.set(key, item);
+    return item;
+  }
+
+  /**
+   * Clear all stored items.
+   * Useful for testing.
+   */
+  clear(): void {
+    this.logger.debug(`Storage clear`, { previousSize: this.storage.size });
+    this.storage.clear();
+  }
+
+  /**
+   * Get the number of stored items.
+   * Useful for testing/debugging.
+   */
+  get size(): number {
+    return this.storage.size;
+  }
+}

package/src/storage.interface.ts

@@ -0,0 +1,34 @@
+import { BaseMetadata, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+
+/**
+ * Injection token for the storage provider.
+ */
+export const DISMISSIBLE_STORAGE_ADAPTER = Symbol('DISMISSIBLE_STORAGE_ADAPTER');
+
+/**
+ * Interface for storage providers.
+ * Implementations handle the persistence of dismissible items.
+ */
+export interface IDismissibleStorage<TMetadata extends BaseMetadata = BaseMetadata> {
+  /**
+   * Retrieve an item by user ID and item ID.
+   * @param userId The user identifier
+   * @param itemId The item identifier
+   * @returns The item or null if not found
+   */
+  get(userId: string, itemId: string): Promise<DismissibleItemDto<TMetadata> | null>;
+
+  /**
+   * Create a new item.
+   * @param item The item to create (contains userId and id)
+   * @returns The created item
+   */
+  create(item: DismissibleItemDto<TMetadata>): Promise<DismissibleItemDto<TMetadata>>;
+
+  /**
+   * Update an existing item.
+   * @param item The item to update (contains userId and id)
+   * @returns The updated item
+   */
+  update(item: DismissibleItemDto<TMetadata>): Promise<DismissibleItemDto<TMetadata>>;
+}

package/src/storage.module.ts

@@ -0,0 +1,18 @@
+import { DynamicModule, Module, Type } from '@nestjs/common';
+import { DISMISSIBLE_STORAGE_ADAPTER } from './storage.interface';
+import { MemoryStorageAdapter } from './memory-storage.adapter';
+
+export type IDismissibleStorageModuleOptions = {
+  storage?: Type<any> | DynamicModule;
+};
+
+@Module({
+  providers: [
+    {
+      provide: DISMISSIBLE_STORAGE_ADAPTER,
+      useClass: MemoryStorageAdapter,
+    },
+  ],
+  exports: [DISMISSIBLE_STORAGE_ADAPTER],
+})
+export class StorageModule {}

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"]
+}