xcally-nest-library 0.0.35 → 0.0.37-XM3778-bae91

package/src/core/application/base.mongo.service.ts

@@ -0,0 +1,170 @@
+import { GrpcNotFoundException } from 'nestjs-grpc-exceptions';
+import { Paginated, PaginateQuery } from 'nestjs-paginate';
+import { IBaseMongoRepository } from '@/core/domain/interfaces/base.mongo.repository.interface';
+import { instanceToPlain } from 'class-transformer';
+import { ObjectId } from 'mongodb';
+import { BaseMongoEntity } from '../infrastracture/databases/base.mongo.entity';
+import { IBaseService } from './base.interface';
+
+export class BaseMongoService<
+  Entity,
+  CreateMessage,
+  UpdateMessage extends { id: string },
+  Message,
+> implements IBaseService<CreateMessage, UpdateMessage, Message>
+{
+  constructor(private readonly repository: IBaseMongoRepository<Entity>) {}
+
+  /**
+   * Finds a single entity by its ID.
+   * @param id - The ID of the entity to find (string or ObjectId).
+   * @returns A promise that resolves to the mapped message.
+   * @throws GrpcNotFoundException if the entity is not found.
+   */
+  async findOne(id: string): Promise<Message> {
+    const entity = (await this.repository.findById(id)) as BaseMongoEntity;
+    const message = this.transformMongoEntityToMessage(entity);
+    if (!entity) {
+      throw new GrpcNotFoundException(`${this.constructor.name.replace('Service', '')} not found`);
+    }
+    return message;
+  }
+
+  /**
+   * Retrieves all entities.
+   * @returns A promise that resolves to an object containing an array of mapped messages.
+   */
+  async findAll(): Promise<{ data: Message[] }> {
+    const entities: Entity[] = await this.repository.find();
+    return {
+      data: entities as unknown as Message[],
+    };
+  }
+
+  /**
+   * Retrieves paginated entities based on the provided query.
+   * @param query - Pagination and filter criteria.
+   * @returns A promise that resolves to the paginated result with rows and count.
+   */
+  async getMany(query?: PaginateQuery): Promise<Paginated<Message>> {
+    if (!query)
+      return this.transformPaginatedMongoEntityToPaginatedMessage(
+        (await this.repository.getMany({ path: '' })) as unknown as Paginated<BaseMongoEntity>,
+      );
+
+
+    const modifiedQuery: PaginateQuery = { ...query };
+
+    //
+    // select → switch "id" to "_id"
+    //
+    if (Array.isArray(modifiedQuery.select)) {
+      modifiedQuery.select = modifiedQuery.select.map(f => (f === 'id' ? '_id' : f));
+    }
+
+    //
+    // sortBy → array of arrays [[field, direction]] and switch "id" to "_id"
+    //
+    if (Array.isArray(modifiedQuery.sortBy)) {
+      modifiedQuery.sortBy = modifiedQuery.sortBy.map(([field, dir]) => [field === 'id' ? '_id' : field, dir]);
+    }
+
+    //
+    // filter → complex object { fieldName: value } and switch "id" to "_id"
+    //
+    if (modifiedQuery.filter && typeof modifiedQuery.filter === 'object') {
+      const newFilter: Record<string, any> = {};
+      for (const [key, val] of Object.entries(modifiedQuery.filter)) {
+        const newKey = key.startsWith('id') ? key.replace(/^id\b/, '_id') : key === 'id' ? '_id' : key;
+        newFilter[newKey] = val;
+      }
+      modifiedQuery.filter = newFilter;
+    }
+
+    //
+    // cursorColumn switch "id" to "_id"
+    //
+    if (modifiedQuery.cursorColumn === 'id') {
+      modifiedQuery.cursorColumn = '_id';
+    }
+
+    const entities = (await this.repository.getMany(modifiedQuery)) as unknown as Paginated<BaseMongoEntity>;
+
+    // switch back _id to id for the response
+    return this.transformPaginatedMongoEntityToPaginatedMessage(entities);
+  }
+
+  // simple switch id to _id
+  protected transformMongoEntityToMessage(entity: BaseMongoEntity): Message {
+    return { ...entity, id: entity._id.toString() } as unknown as Message;
+  }
+
+  // switch id to _id in the pagination object
+  public transformPaginatedMongoEntityToPaginatedMessage(
+    paginatedEntities: Paginated<BaseMongoEntity>,
+  ): Paginated<Message> {
+    const transformedData = paginatedEntities.data.map(entity => {
+      return this.transformMongoEntityToMessage(entity);
+    });
+
+    const paginatedMessages: Paginated<Message> = {
+      links: { ...paginatedEntities.links },
+      meta: { ...paginatedEntities.meta } as unknown as Paginated<Message>['meta'],
+      data: transformedData,
+    };
+
+    return paginatedMessages;
+  }
+
+  /**
+   * Creates a new entity from the provided DTO.
+   * @param createDTO - The data transfer object for creating an entity.
+   * @returns A promise that resolves to the mapped message of the created entity.
+   */
+  async create(createDTO: CreateMessage): Promise<Message> {
+    const entity = this.repository.create(createDTO as unknown as Entity);
+    for (const key of this.repository.paginateConfig.dateColumns) {
+      entity[key] = createDTO[key] ? new Date(createDTO[key]) : null;
+    }
+    const savedEntity = await this.repository.save(entity);
+    return this.transformMongoEntityToMessage(savedEntity as unknown as BaseMongoEntity);
+  }
+
+  /**
+   * Updates an existing entity with the provided DTO.
+   * @param updateDTO - The data transfer object for updating an entity.
+   * @returns A promise that resolves to the mapped message of the updated entity.
+   * @throws GrpcNotFoundException if the entity is not found.
+   */
+  async update(updateDTO: UpdateMessage): Promise<Message> {
+    const entity = await this.repository.findById(updateDTO.id);
+    if (!entity) {
+      throw new GrpcNotFoundException(`${this.constructor.name.replace('Service', '')} not found`);
+    }
+
+    const objectId = new ObjectId(updateDTO.id);
+    await this.repository.update(objectId as any, instanceToPlain(updateDTO) as any);
+    const updatedEntity: Entity = await this.repository.findById(updateDTO.id);
+    return this.transformMongoEntityToMessage(updatedEntity as unknown as BaseMongoEntity);
+  }
+
+  /**
+   * Deletes an entity by its ID.
+   * @param id - The ID of the entity to delete (string).
+   * @returns A promise that resolves when the entity is deleted.
+   */
+  async remove(id: string): Promise<void> {
+    const objectId = new ObjectId(id);
+    await this.repository.delete(objectId as any);
+  }
+
+  /**
+   * Counts all entities.
+   * @param options - Optional query options for counting entities.
+   * @returns A promise that resolves to an object containing the count.
+   */
+  async count(options?: any): Promise<{ count: number }> {
+    const count = await this.repository.count(options || {});
+    return { count };
+  }
+}

package/src/core/application/base.service.ts

@@ -1,6 +1,6 @@
 import { GrpcNotFoundException } from 'nestjs-grpc-exceptions';
 import { Paginated, PaginateQuery } from 'nestjs-paginate';
-import { IBaseRepository } from '@domain/interfaces/base.repository.interface';
+import { IBaseRepository } from '@/core/domain/interfaces/base.repository.interface';
 import { instanceToPlain } from 'class-transformer';
 import { IBaseService } from './base.interface';
 
@@ -9,7 +9,7 @@ export class BaseService<
   CreateMessage extends Partial<Entity>,
   UpdateMessage extends Partial<Entity> & { id: number },
   Message,
-> implements IBaseService<Entity, CreateMessage, UpdateMessage, Message>
+> implements IBaseService<CreateMessage, UpdateMessage, Message>
 {
   constructor(private readonly repository: IBaseRepository<Entity>) {}
 

package/src/core/application/cached-base.service.ts

@@ -0,0 +1,119 @@
+import { LoggerService } from '@/modules/logger/pino/logger.service';
+import { Cache } from '@nestjs/cache-manager';
+import { Paginated, PaginateQuery } from 'nestjs-paginate';
+import { CacheConfiguration, InvalidationStrategy } from '../domain/interfaces/cache-configuration.interface';
+import { IBaseService } from './base.interface';
+import { CachedService } from './cached.service';
+
+/**
+ * Base CRUD service with caching capabilities.
+ */
+export class CachedBaseService<
+  Entity,
+  CreateMessage,
+  UpdateMessage extends { id: number | string },
+  Message,
+> extends CachedService implements IBaseService<CreateMessage, UpdateMessage, Message> {
+
+  /**
+   * Creates an instance of CachedBaseService.
+   *
+   * @param {LoggerService} logger - The logger service.
+   * @param {IBaseService<CreateMessage, UpdateMessage, Message>} service - The service to add the caching layer to.
+   * @param {Cache} cacheManager - The NestJS cache manager.
+   * @param {CacheConfiguration} cacheConfig - The cache configuration.
+   */
+  constructor(
+    protected readonly logger: LoggerService,
+    protected readonly service: IBaseService<CreateMessage, UpdateMessage, Message>,
+    protected readonly cacheManager: Cache,
+    protected readonly cacheConfig: CacheConfiguration,
+  ) {
+    super(logger, cacheManager, cacheConfig);
+   }
+
+  /**
+   * Finds a single entity by its ID with caching.
+   *
+   * @param {number | string} id - The ID of the entity to find.
+   * @returns {Promise<Message>} A promise that resolves to the mapped message.
+   */
+  async findOne(id: number | string): Promise<Message> {
+    const cacheKey = this.generateCacheKey('findOne', { id });
+    return await this.getOrSetCache<Message>(cacheKey, async () => await this.service.findOne(id));
+  }
+
+  /**
+   * Retrieves all entities with caching.
+   *
+   * @returns {Promise<{ data: Message[] }>} A promise that resolves to an object containing an array of mapped messages.
+   */
+  async findAll(): Promise<{ data: Message[] }> {
+    const cacheKey = this.generateCacheKey('findAll');
+    return await this.getOrSetCache(cacheKey, async () => await this.service.findAll());
+  }
+
+  /**
+   * Retrieves paginated entities based on the provided query with caching.
+   * The cache key includes filters to ensure correct results for different queries.
+   *
+   * @param {PaginateQuery} query - Pagination and filter criteria.
+   * @returns {Promise<Paginated<Message>>} A promise that resolves to the paginated result.
+   */
+  async getMany(query?: PaginateQuery): Promise<Paginated<Message>> {
+    const cacheKey = this.generateCacheKey('getMany', query);
+    return await this.getOrSetCache(cacheKey, async () => await this.service.getMany(query));
+  }
+
+  /**
+   * Creates a new entity and invalidates cache.
+   *
+   * @param {CreateMessage} createDTO - The data transfer object for creating an entity.
+   * @returns {Promise<Message>} A promise that resolves to the mapped message of the created entity.
+   */
+  async create(createDTO: CreateMessage): Promise<Message> {
+    const result = await this.service.create(createDTO);
+    if (this.cacheConfig.invalidationStrategy === InvalidationStrategy.OnChange) {
+      await this.invalidateCache();
+    }
+    return result;
+  }
+
+  /**
+   * Updates an existing entity and invalidates cache.
+   *
+   * @param {UpdateMessage} updateDTO - The data transfer object for updating an entity.
+   * @returns {Promise<Message>} A promise that resolves to the mapped message of the updated entity.
+   */
+  async update(updateDTO: UpdateMessage): Promise<Message> {
+    const result = await this.service.update(updateDTO);
+    if (this.cacheConfig.invalidationStrategy === InvalidationStrategy.OnChange) {
+      await this.invalidateCache();
+    }
+    return result;
+  }
+
+  /**
+   * Deletes an entity by its ID and invalidates cache.
+   *
+   * @param {number | string} id - The ID of the entity to delete.
+   * @returns {Promise<void>} A promise that resolves when the entity is deleted.
+   */
+  async remove(id: number | string): Promise<void> {
+    await this.service.remove(id);
+    if (this.cacheConfig.invalidationStrategy === InvalidationStrategy.OnChange) {
+      await this.invalidateCache();
+    }
+  }
+
+  /**
+   * Counts all entities with caching.
+   *
+   * @param {any} options - Optional query options for counting entities.
+   * @returns {Promise<{ count: number }>} A promise that resolves to an object containing the count.
+   */
+  async count(options?: any): Promise<{ count: number }> {
+    const cacheKey = this.generateCacheKey('count', options);
+    return await this.getOrSetCache(cacheKey, async () => await this.service.count(options));
+  }
+}

package/src/core/application/cached.service.ts

@@ -0,0 +1,96 @@
+import { LoggerService } from '@/modules/logger/pino/logger.service';
+import { Cache } from '@nestjs/cache-manager';
+import { createHash } from 'crypto';
+import { CacheConfiguration } from '../domain/interfaces/cache-configuration.interface';
+
+/**
+ * Base service with caching capabilities.
+ */
+export class CachedService {
+
+  protected readonly serviceName = this.constructor.name.toLowerCase().replace('service', '');
+
+  /**
+   * Creates an instance of CachedBaseService.
+   *
+   * @param {LoggerService} logger - The logger service.
+   * @param {Cache} cacheManager - The NestJS cache manager.
+   * @param {CacheConfiguration} cacheConfig - The cache configuration.
+   */
+  constructor(
+    protected readonly logger: LoggerService,
+    protected readonly cacheManager: Cache,
+    protected readonly cacheConfig: CacheConfiguration,
+  ) { }
+
+  /**
+   * Generates a cache key based on the service name, method, and parameters.
+   *
+   * @param {string} method - The method name.
+   * @param {any} params - The parameters to include in the key.
+   * @returns {string} The generated cache key.
+   */
+  protected generateCacheKey(method: string, params?: any): string {
+    const paramsHash = params ? createHash('md5').update(JSON.stringify(params)).digest('hex') : 'all';
+    return `${this.serviceName}:${method}:${paramsHash}`;
+  }
+
+  /**
+   * Gets data from cache or executes the provided function and caches the result.
+   *
+   * @param {string} key - The cache key.
+   * @param {() => Promise<T>} fn - The function to execute if cache miss.
+   * @returns {Promise<T>} The cached or freshly fetched data.
+   */
+  protected async getOrSetCache<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    try {
+      // Try to get from cache
+      const cached = await this.cacheManager.get<string>(key);
+      
+      if (cached) {
+        this.logger.debug(`Cache hit for key: ${key}`);
+        return JSON.parse(cached) as T;
+      }
+
+      this.logger.debug(`Cache miss for key: ${key}`);
+
+      // Cache miss - fetch fresh data
+      const result = await fn();
+
+      // Store in cache
+      await this.cacheManager.set(key, JSON.stringify(result));
+
+      return result;
+    } catch (error) {
+      this.logger.error(`An error occurred while fetching cache for key: ${key}`);
+      this.logger.error(error);
+      // On failure, fallback to freshly fetched data
+      return await fn();
+    }
+  }
+
+  /**
+   * Invalidates cache.
+   *
+   * @returns {Promise<void>}
+   */
+  protected async invalidateCache(): Promise<void> {
+    try {
+      this.logger.debug(`Invalidating cache for service: ${this.serviceName}`);
+      const storeIterator = this.cacheManager.stores[0].iterator;
+      const keys: Array<string> = [];
+      if (storeIterator) { 
+        for await (const [key, value] of storeIterator('namespace')) {
+          if (key.split(':')[0] === this.serviceName) {
+            keys.push(key);
+          }
+        }
+        await this.cacheManager.mdel(keys);
+      }
+    } catch (error) {
+      // Silently fail cache invalidation to not break the main flow
+      this.logger.error(`An error occurred while invalidating cache for service: ${this.serviceName}`);
+      this.logger.error(error);
+    }
+  }
+}

package/src/core/domain/interfaces/base.mongo.repository.interface.ts

@@ -0,0 +1,14 @@
+import { PaginateQuery, Paginated } from 'nestjs-paginate';
+import { MongoRepository } from 'typeorm';
+import { ObjectId } from 'mongodb';
+import { ExtendedPaginateConfig } from 'index';
+
+export interface IBaseMongoId {
+  _id: ObjectId;
+}
+
+export interface IBaseMongoRepository<E> extends MongoRepository<E> {
+  getMany(query: PaginateQuery): Promise<Paginated<E>>;
+  findById(id: string | ObjectId): Promise<E>;
+  paginateConfig: ExtendedPaginateConfig<E>;
+}

package/src/core/domain/interfaces/base.repository.interface.ts

@@ -1,5 +1,6 @@
 import { PaginateQuery, Paginated } from 'nestjs-paginate';
 import { Repository } from 'typeorm';
+
 export interface IId {
   id: number;
 }

package/src/core/domain/interfaces/cache-configuration.interface.ts

@@ -0,0 +1,10 @@
+export const CACHE_CONF = Symbol('CACHE_CONF');
+
+export enum InvalidationStrategy {
+  TTL = 'TTL',
+  OnChange = 'OnChange',
+};
+
+export interface CacheConfiguration {
+  invalidationStrategy: InvalidationStrategy;
+}

package/src/core/infrastracture/databases/base.mongo.entity.interface.ts

@@ -0,0 +1,12 @@
+import { ObjectId } from 'mongodb';
+import { PaginateConfig } from 'nestjs-paginate/lib/paginate';
+
+export interface IBaseMongoEntity {
+  _id: ObjectId;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface ExtendedPaginateConfig<E> extends PaginateConfig<E> {
+  dateColumns?: string[];
+}

package/src/core/infrastracture/databases/base.mongo.entity.ts

@@ -0,0 +1,65 @@
+import { ObjectId } from 'mongodb';
+import {
+  CreateDateColumn,
+  EntitySubscriberInterface,
+  EventSubscriber,
+  InsertEvent,
+  ObjectIdColumn,
+  UpdateDateColumn,
+  UpdateEvent,
+} from 'typeorm';
+import { ExtendedPaginateConfig, IBaseMongoEntity } from './base.mongo.entity.interface';
+
+export class BaseMongoEntity implements IBaseMongoEntity {
+  @ObjectIdColumn()
+  _id: ObjectId;
+
+  @CreateDateColumn({
+    type: 'timestamp',
+  })
+  createdAt: Date;
+
+  @UpdateDateColumn({
+    type: 'timestamp',
+  })
+  updatedAt: Date;
+}
+
+@EventSubscriber()
+export class BaseMongoEntitySubscriber implements EntitySubscriberInterface<BaseMongoEntity> {
+  /**
+   * Indicates that this subscriber only listens to BaseMongoEntity events.
+   */
+  public listenTo() {
+    return BaseMongoEntity;
+  }
+
+  /**
+   * Called before entity insertion.
+   */
+  public beforeInsert(event: InsertEvent<BaseMongoEntity>) {
+    const now = new Date();
+    now.setMilliseconds((now.getMilliseconds() + 1) % 1000);
+    event.entity.createdAt = now;
+    event.entity.updatedAt = now;
+  }
+
+  public beforeUpdate(event: UpdateEvent<BaseMongoEntity>): void | Promise<any> {
+    const now = new Date();
+    now.setMilliseconds((now.getMilliseconds() + 1) % 1000);
+    event.entity.updatedAt = now;
+  }
+}
+
+export const paginationConfig: ExtendedPaginateConfig<BaseMongoEntity> = {
+  sortableColumns: ['_id', 'createdAt', 'updatedAt'],
+  searchableColumns: ['_id', 'createdAt', 'updatedAt'],
+  filterableColumns: {
+    _id: true,
+    createdAt: true,
+    updatedAt: true,
+  },
+  select: ['_id', 'createdAt', 'updatedAt'],
+  relativePath: true,
+  dateColumns: ['createdAt', 'updatedAt'],
+};