itlab-internal-services 2.15.7 → 2.16.1

package/README.md

@@ -1,4 +1,5 @@
 # IT Lab Internal Services
+
 > Diese Library funktioniert nur mit NestJs
 
 [![npm version](https://img.shields.io/npm/v/itlab-internal-services.svg?style=flat-square)](https://www.npmjs.org/package/itlab-internal-services)
@@ -17,190 +18,3 @@ To begin using it, we first install the required dependency.
 ```bash
 yarn add itlab-internal-services
 ```
-
-### Getting started
-
-Once the installation process is complete, to use the `InternalServices`, first import `InternalModule`.
-
-```typescript
-@Module({
-  imports: [InternalModule],
-  providers: [NewsService],
-})
-export class NewsModule {}
-```
-
-Next, inject `CommentService`, `ContentService` or `SearchService` using normal constructor injection.
-
-> **Hint** `InternalModule`, `CommentService`, `ContentService` & `SearchService` are imported from `itlab-internal-services` package.
-
-```typescript
-@Injectable()
-export class NewsService {
-  constructor(
-    private readonly commentService: CommentService,
-    private readonly contentService: ContentService,
-    private readonly searchService: SearchService,
-  ) {}
-}
-```
-
-### Comment Service
-```typescript
-async post(targetId: string, authorId: string, comment: Comment): Promise<Comment>
-```
-
-```typescript
-async delete(targetId: string): Promise<void>
-```
-
-### Content Service
-
-```typescript
-async verify(content: Content): Promise<void>
-```
-
-```typescript
-async post(targetId: string, content: Content): Promise<void>
-```
-
-```typescript
-async delete(targetId: string): Promise<void>
-```
-
-### Pipes
-```typescript
-@Controller("news")
-export class NewsController {
-
-  @ApiTarget("target")
-  @Get(":target")
-  getNews(@Target("target") target: string) {}
-
-}
-```
-
-```typescript
-@Controller("news")
-export class NewsController {
-
-  @ApiHid("hid")
-  @Get(":hid")
-  getNews(@Hid("hid") hid: string) {}
-
-}
-```
-
-```typescript
-@Controller("news")
-export class NewsController {
-
-  @ApiId("id")
-  @Get(":id")
-  getNews(@Id("id") id: string) {}
-
-}
-```
-
-### Guards
-```typescript
-@Internal()
-@Controller()
-export class NewsController {}
-```
-
-```typescript
-@Jwt()
-@Controller()
-export class NewsController {
-  @Get("")
-  getNews(@Account() account: LAccount) {}
-
-  @Get("")
-  getNews(@AccountId() accountId: string) {}
-
-  @Perms("perms.get", "perms.list")
-  @Get("")
-  getNews(@AccountId() accountId: string, @AccountPerms() accountPerms: string[]) {}
-}
-```
-
-### Configuration
-
-To configure the underlying service instance, pass an optional options object to the `register()` method of `InternalModule` when importing it. This options object will be passed directly to the underlying service constructor.
-
-```typescript
-@Module({
-  imports: [
-    InternalModule.register({
-      target: Targets.NEWSROOM,
-      token: 'itlab token',
-      jwt_secret: 'secret',
-    }),
-  ],
-  providers: [NewsService],
-})
-export class NewsModule {}
-```
-
-### Async configuration
-
-When you need to pass module options asynchronously instead of statically, use the `registerAsync()` method. As with most dynamic modules, this package provides several techniques to deal with async configuration.
-
-One technique is to use a factory function:
-
-```typescript
-InternalModule.registerAsync({
-  useFactory: () => ({
-    target: Targets.NEWSROOM,
-    token: 'itlab token',
-    jwt_secret: 'secret',
-  }),
-});
-```
-
-Like other factory providers, our factory function can be [async](https://docs.nestjs.com/fundamentals/custom-providers#factory-providers-usefactory) and can inject dependencies through `inject`.
-
-```typescript
-InternalModule.registerAsync({
-  imports: [ConfigModule],
-  useFactory: (configService: ConfigService) => ({
-    target: Targets.NEWSROOM,
-    token: configService.get<string>('K8S_TOKEN'),
-    jwt_secret: configService.get<string>('JWT_SECRET'),
-  }),
-  inject: [ConfigService],
-});
-```
-
-Alternatively, you can configure the `InternalModule` using a class instead of a factory, as shown below.
-
-```typescript
-InternalModule.registerAsync({
-  useClass: InternalConfigService,
-});
-```
-
-The construction above instantiates `InternalConfigService` inside `InternalModule`, using it to create an options object. Note that in this example, the `InternalConfigService` has to implement `InternalModuleOptionsFactory` interface as shown below. The `InternalModule` will call the `createInternalOptions()` method on the instantiated object of the supplied class.
-
-```typescript
-@Injectable()
-class InternalConfigService implements InternalModuleOptionsFactory {
-  createInternalOptions(): InternalModuleOptions {
-    return {
-      target: Targets.NEWSROOM,
-      token: 'itlab token',
-      jwt_secret: 'secret',
-    };
-  }
-}
-```
-
-If you want to reuse an existing options provider instead of creating a private copy inside the `InternalModule`, use the `useExisting` syntax.
-
-```typescript
-InternalModule.registerAsync({
-  imports: [ConfigModule],
-  useExisting: InternalConfigService,
-});
-```

package/dist/classes/document-merger.class.js

@@ -51,8 +51,7 @@ class DocumentMerger {
     async merge(transform) {
         const startTime = Date.now();
         const cursor = this.model.find().cursor();
-        // Process documents one by one to handle large collections efficiently
-        for (let doc = await cursor.next(); doc != null; doc = await cursor.next()) {
+        await cursor.eachAsync(async (doc) => {
             // Apply user-defined transformation if provided
             if (transform) {
                 doc = transform(doc);
@@ -74,7 +73,7 @@ class DocumentMerger {
             }
             // Save changes to the database without updating timestamps
             await doc.save({ timestamps: false });
-        }
+        });
         const elapsedTime = Date.now() - startTime;
         // Log completion with fields merged and time taken
         this.logger.log(`Successfully merged fields: ${(0, itlab_functions_1.formatList)(this.fields)} (took ${elapsedTime} ms)`);

package/dist/classes/index.d.ts

@@ -1,2 +1,5 @@
 export { DocumentMerger } from './document-merger.class';
-export { DocumentUpdater } from './document-updater.class';
+export { ReportCategory } from './report-category.class';
+export { SchemaBuilder } from './schema-builder.class';
+export type { SchemaBuilderDocument, SchemaBuilderModel, SchemaBuilderOptions } from './schema-builder.class';
+export { TaskManager } from './task-manager.class';

package/dist/classes/index.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DocumentUpdater = exports.DocumentMerger = void 0;
+exports.TaskManager = exports.SchemaBuilder = exports.ReportCategory = exports.DocumentMerger = void 0;
 var document_merger_class_1 = require("./document-merger.class");
 Object.defineProperty(exports, "DocumentMerger", { enumerable: true, get: function () { return document_merger_class_1.DocumentMerger; } });
-var document_updater_class_1 = require("./document-updater.class");
-Object.defineProperty(exports, "DocumentUpdater", { enumerable: true, get: function () { return document_updater_class_1.DocumentUpdater; } });
+var report_category_class_1 = require("./report-category.class");
+Object.defineProperty(exports, "ReportCategory", { enumerable: true, get: function () { return report_category_class_1.ReportCategory; } });
+var schema_builder_class_1 = require("./schema-builder.class");
+Object.defineProperty(exports, "SchemaBuilder", { enumerable: true, get: function () { return schema_builder_class_1.SchemaBuilder; } });
+var task_manager_class_1 = require("./task-manager.class");
+Object.defineProperty(exports, "TaskManager", { enumerable: true, get: function () { return task_manager_class_1.TaskManager; } });

package/dist/classes/report-category.class.d.ts

@@ -0,0 +1,55 @@
+import { Document } from 'mongoose';
+/**
+ * Defines which array-type attributes of a document should be tracked,
+ * along with human-readable labels for reporting.
+ *
+ * Only attributes of type `string[]` are tracked.
+ *
+ * Example:
+ * { genres: "Genres", tags: "Tags" }
+ */
+type ReportCategoryAttributes<T extends Document> = Partial<{
+    [K in keyof Omit<T, keyof Document> as T[K] extends string[] ? K : never]: string;
+}>;
+type ReportCategoryExport = Array<{
+    id: string;
+} & Record<string, number>>;
+/**
+ * ReportCategory
+ *
+ * Manages multiple AttributeAggregator instances, each associated
+ * with a unique entity key (e.g., organization, category).
+ * Provides methods to insert documents and export aggregated reports.
+ *
+ * @template T - A Mongoose document type with array attributes to track.
+ */
+export declare class ReportCategory<T extends Document> {
+    private aggregators;
+    private attributes;
+    /**
+     * Initializes the report manager with the attributes to track.
+     *
+     * @param attributes - Mapping of document array attributes to display labels.
+     */
+    constructor(attributes: ReportCategoryAttributes<T>);
+    /**
+     * Inserts a document into one or multiple entity aggregators.
+     * Automatically creates the aggregator if it does not exist.
+     *
+     * @param document - The document to insert.
+     * @param entityKeys - Single or multiple entity identifiers.
+     */
+    insertDocument(document: T, entityKeys: string[] | string): void;
+    /**
+     * Exports aggregated statistics for all entities.
+     *
+     * Each object contains:
+     * - id: Entity key
+     * - documents: Number of documents processed for this entity
+     * - totalX / uniqueX: Aggregated counts for each tracked attribute
+     *
+     * @returns An array of aggregated reports for all entities.
+     */
+    export(): ReportCategoryExport;
+}
+export {};

package/dist/classes/report-category.class.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportCategory = void 0;
+const itlab_functions_1 = require("itlab-functions");
+/**
+ * AttributeAggregator
+ *
+ * Responsible for aggregating statistics for specified array attributes
+ * across multiple document records. Tracks both total counts and
+ * unique values for each attribute.
+ *
+ * @template T - A Mongoose document type with array attributes to track.
+ */
+class AttributeAggregator {
+    /**
+     * Initializes the aggregator with the attributes to track.
+     *
+     * @param attributes - Mapping of document array attributes to display labels.
+     */
+    constructor(attributes) {
+        this.documents = 0;
+        this.totalCounts = new Map();
+        this.uniqueValues = new Map();
+        this.attributes = attributes;
+    }
+    /**
+     * Processes a single document, updating the total and unique value counts
+     * for each tracked attribute.
+     *
+     * @param document - The document to include in aggregation.
+     */
+    processDocument(document) {
+        this.documents++;
+        for (const attribute of Object.keys(this.attributes)) {
+            const values = document[attribute];
+            // Only handle array attributes
+            if (!Array.isArray(values))
+                continue;
+            // Update total count for this attribute
+            const previousTotal = this.totalCounts.get(attribute) || 0;
+            this.totalCounts.set(attribute, previousTotal + values.length);
+            // Update the set of unique values for this attribute
+            const currentUnique = this.uniqueValues.get(attribute) || new Set();
+            values.forEach((value) => currentUnique.add(String(value)));
+            this.uniqueValues.set(attribute, currentUnique);
+        }
+    }
+    /**
+     * Exports aggregated statistics for this aggregator.
+     *
+     * Returns an object containing:
+     * - documents: Number of documents processed
+     * - totalX: Total count of values for each attribute
+     * - uniqueX: Count of unique values for each attribute
+     *
+     * @returns An object representing the aggregated data.
+     */
+    export() {
+        var _a;
+        const report = {};
+        for (const [attribute, label] of Object.entries(this.attributes)) {
+            const capitalizedLabel = (0, itlab_functions_1.capitalize)(label);
+            report[`total${capitalizedLabel}`] = this.totalCounts.get(attribute) || 0;
+            report[`unique${capitalizedLabel}`] = ((_a = this.uniqueValues.get(attribute)) === null || _a === void 0 ? void 0 : _a.size) || 0;
+        }
+        return Object.assign({ documents: this.documents }, report);
+    }
+}
+/**
+ * ReportCategory
+ *
+ * Manages multiple AttributeAggregator instances, each associated
+ * with a unique entity key (e.g., organization, category).
+ * Provides methods to insert documents and export aggregated reports.
+ *
+ * @template T - A Mongoose document type with array attributes to track.
+ */
+class ReportCategory {
+    /**
+     * Initializes the report manager with the attributes to track.
+     *
+     * @param attributes - Mapping of document array attributes to display labels.
+     */
+    constructor(attributes) {
+        this.aggregators = new Map();
+        this.attributes = attributes;
+    }
+    /**
+     * Inserts a document into one or multiple entity aggregators.
+     * Automatically creates the aggregator if it does not exist.
+     *
+     * @param document - The document to insert.
+     * @param entityKeys - Single or multiple entity identifiers.
+     */
+    insertDocument(document, entityKeys) {
+        var _a;
+        const keys = Array.isArray(entityKeys) ? entityKeys : [entityKeys];
+        for (const key of keys) {
+            const aggregator = (_a = this.aggregators.get(key)) !== null && _a !== void 0 ? _a : new AttributeAggregator(this.attributes);
+            aggregator.processDocument(document);
+            this.aggregators.set(key, aggregator);
+        }
+    }
+    /**
+     * Exports aggregated statistics for all entities.
+     *
+     * Each object contains:
+     * - id: Entity key
+     * - documents: Number of documents processed for this entity
+     * - totalX / uniqueX: Aggregated counts for each tracked attribute
+     *
+     * @returns An array of aggregated reports for all entities.
+     */
+    export() {
+        return Array.from(this.aggregators.entries()).map(([id, aggregator]) => {
+            return Object.assign({ id }, aggregator.export());
+        });
+    }
+}
+exports.ReportCategory = ReportCategory;

package/dist/classes/schema-builder.class.d.ts

@@ -0,0 +1,75 @@
+import { Type } from '@nestjs/common';
+import { Document, Model, Schema } from 'mongoose';
+import { Likeable, Viewable } from '../types';
+/**
+ * Options that determine how the schema should be extended.
+ *
+ * @template TClass - The document type for the schema.
+ */
+export type SchemaBuilderOptions<TClass extends Document> = {
+    /** Whether this schema should support view tracking. */
+    viewable?: boolean;
+    /** Whether this schema should support like tracking. */
+    likeable?: boolean;
+    /**
+     * A set of keys that uniquely identify the document.
+     * These keys are used when checking for duplicates.
+     */
+    criticalKeys?: (keyof Omit<TClass, keyof Document>)[];
+};
+/**
+ * Computes the augmented document type based on SchemaOptions.
+ */
+export type SchemaBuilderDocument<TClass extends Document, TOptions extends SchemaBuilderOptions<TClass>> = TClass & (TOptions['viewable'] extends true ? Viewable : object) & (TOptions['likeable'] extends true ? Likeable : object);
+/**
+ * Extends a standard Mongoose model with custom static methods
+ * injected by the SchemaBuilder.
+ */
+export type SchemaBuilderModel<TClass extends Document> = Model<TClass> & {
+    /**
+     * Checks if the given object is a duplicate of an existing document.
+     *
+     * @param dto - Partial object with properties to check for duplicates.
+     * @param updateTarget - The document being updated, if applicable.
+     * @returns {Promise<boolean>} - True if a duplicate exists, false otherwise.
+     */
+    isDuplicate(dto: Partial<TClass>, updateTarget?: TClass): Promise<boolean>;
+};
+/**
+ * Generic builder for creating extended Mongoose schemas.
+ *
+ * This class wraps Nest's SchemaFactory and automatically injects common
+ * behaviors such as:
+ * - View tracking (who viewed, view counts)
+ * - Like tracking (who liked, like counts)
+ * - Duplicate checking based on critical keys
+ *
+ * @template TClass - A class extending Mongoose Document.
+ */
+export declare class SchemaBuilder<TClass extends Document> {
+    private schema;
+    readonly options: SchemaBuilderOptions<TClass>;
+    constructor(target: Type<TClass>, options?: SchemaBuilderOptions<TClass>);
+    /**
+     * Adds interaction tracking (likes or views) to a schema.
+     * This method generalizes the shared logic between "viewable" and "likeable".
+     *
+     * @param field - The internal array field storing account IDs. (e.g. _viewedBy or _likedBy)
+     * @param counter - The numeric counter field tracking totals. (e.g. views or likes)
+     */
+    provideInteraction(field: string, counter: string): this;
+    /**
+     * Adds a duplicate-checking static method to the schema.
+     * This method compares critical keys to detect conflicts.
+     */
+    private provideDuplicateChecker;
+    /**
+     * Finalizes the schema and injects any selected behaviors (viewable, likeable, duplicate checking).
+     *
+     * @returns An object containing:
+     * - `schema`: The Mongoose schema.
+     * - `modelType`: A strongly typed model with additional static methods.
+     * - `documentType`: The inferred document type with injected properties.
+     */
+    build(): Schema;
+}

package/dist/classes/schema-builder.class.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaBuilder = void 0;
+const mongoose_1 = require("@nestjs/mongoose");
+const class_validator_1 = require("class-validator");
+/**
+ * Generic builder for creating extended Mongoose schemas.
+ *
+ * This class wraps Nest's SchemaFactory and automatically injects common
+ * behaviors such as:
+ * - View tracking (who viewed, view counts)
+ * - Like tracking (who liked, like counts)
+ * - Duplicate checking based on critical keys
+ *
+ * @template TClass - A class extending Mongoose Document.
+ */
+class SchemaBuilder {
+    constructor(target, options = {}) {
+        this.schema = mongoose_1.SchemaFactory.createForClass(target);
+        this.options = options;
+        /**
+         * Create a wildcard index required for CosmosDB to support sorting on all fields.
+         *
+         * This is a workaround for CosmosDB's partial MongoDB API compatibility.
+         * See: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/indexing#wildcard-indexes
+         */
+        this.schema.index({ '$**': 1 }, { name: 'Sort Index' });
+        this.provideDuplicateChecker();
+    }
+    /**
+     * Adds interaction tracking (likes or views) to a schema.
+     * This method generalizes the shared logic between "viewable" and "likeable".
+     *
+     * @param field - The internal array field storing account IDs. (e.g. _viewedBy or _likedBy)
+     * @param counter - The numeric counter field tracking totals. (e.g. views or likes)
+     */
+    provideInteraction(field, counter) {
+        // Add fields to the schema
+        this.schema.add({ [field]: { type: [String], default: [] }, [counter]: { type: Number, default: 0 } });
+        // Expose a virtual property (without underscore) for convenience
+        this.schema.virtual(field.replace(/^_/, ''));
+        // Add method to increment counter
+        this.schema.methods[`add${counter[0].toUpperCase() + counter.slice(1)}`] = async function (accountId) {
+            if (!(0, class_validator_1.isMongoId)(accountId))
+                return Number(this[counter]);
+            // Ensure uniqueness by converting to a Set
+            this[field] = Array.from(new Set([...this[field], accountId]));
+            this[counter] = this[field].length;
+            await this.save({ timestamps: false });
+            return this[counter];
+        };
+        // Add method to decrement counter
+        this.schema.methods[`remove${counter[0].toUpperCase() + counter.slice(1)}`] = async function (accountId) {
+            if (!(0, class_validator_1.isMongoId)(accountId))
+                return Number(this[counter]);
+            // Remove the accountId from the list
+            this[field] = this[field].filter((id) => id !== accountId);
+            this[counter] = this[field].length;
+            await this.save({ timestamps: false });
+            return this[counter];
+        };
+        return this;
+    }
+    /**
+     * Adds a duplicate-checking static method to the schema.
+     * This method compares critical keys to detect conflicts.
+     */
+    provideDuplicateChecker() {
+        var _a;
+        const criticalKeys = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.criticalKeys) || [];
+        this.schema.statics.isDuplicate = async function (dto, updateTarget) {
+            var _a;
+            if (criticalKeys.length === 0)
+                return false;
+            // Build a filter using the critical keys
+            const filterQuery = criticalKeys.reduce((query, key) => {
+                if (dto && key in dto)
+                    query[String(key)] = dto[key];
+                else if (updateTarget && key in updateTarget)
+                    query[String(key)] = updateTarget[key];
+                return query;
+            }, {});
+            // If a matching document exists, check whether it’s the same entity
+            const potentialDuplicate = await this.findOne(filterQuery);
+            if (!potentialDuplicate)
+                return false;
+            const potentialId = potentialDuplicate._id.toString().toLowerCase();
+            const targetId = (_a = updateTarget === null || updateTarget === void 0 ? void 0 : updateTarget._id) === null || _a === void 0 ? void 0 : _a.toString().toLowerCase();
+            return potentialId !== targetId;
+        };
+    }
+    /**
+     * Finalizes the schema and injects any selected behaviors (viewable, likeable, duplicate checking).
+     *
+     * @returns An object containing:
+     * - `schema`: The Mongoose schema.
+     * - `modelType`: A strongly typed model with additional static methods.
+     * - `documentType`: The inferred document type with injected properties.
+     */
+    build() {
+        var _a, _b;
+        if ((_a = this.options) === null || _a === void 0 ? void 0 : _a.viewable)
+            this.provideInteraction('_viewedBy', 'views');
+        if ((_b = this.options) === null || _b === void 0 ? void 0 : _b.likeable)
+            this.provideInteraction('_likedBy', 'likes');
+        return this.schema;
+    }
+}
+exports.SchemaBuilder = SchemaBuilder;

package/dist/classes/task-manager.class.d.ts

@@ -0,0 +1,71 @@
+import { Account, User } from '../models';
+import { AccountsService } from '../modules';
+/**
+ * TaskManager is a utility class that collects asynchronous tasks
+ * and executes them in parallel.
+ *
+ * This is especially useful for orchestrating optional async operations
+ * where not all tasks need to be executed every time.
+ *
+ * Example:
+ * ```ts
+ * const taskManager = new TaskManager();
+ * taskManager.add(async () => { ... });
+ * taskManager.add(async () => { ... });
+ * await taskManager.run();
+ * ```
+ */
+export declare class TaskManager {
+    private tasks;
+    /**
+     * Fetches all users for the given ID groups and returns a mapping.
+     * Ensures each user is fetched only once.
+     * @param userIdGroups Array of arrays of user IDs (e.g., authors, likedBy, viewedBy)
+     * @param accountsService Service responsible for fetching users
+     * @returns Map of userId -> user
+     */
+    static fetchAndMapUsers(userIdGroups: string[][], accountsService: AccountsService): Promise<Map<string, User>>;
+    /**
+     * Fetches all users for the given ID groups and returns a mapping.
+     * Ensures each user is fetched only once.
+     * @param accountIdGroups Array of arrays of user IDs (e.g., authors, likedBy, viewedBy)
+     * @param accountsService Service responsible for fetching users
+     * @returns Map of userId -> user
+     */
+    static fetchAndMapAccounts(accountIdGroups: string[][], accountsService: AccountsService): Promise<Map<string, Account>>;
+    /**
+     * Maps an array of IDs to user objects using a userMap.
+     * Filters out any IDs that don’t have a corresponding user.
+     * @param userIds Array of user IDs to map
+     * @param userMap Map of userId -> user object
+     * @returns Array of user objects
+     */
+    static mapIdsToUsers(userIds: string[], userMap: Map<string, User>): any[];
+    /**
+     * Maps an array of IDs to user objects using a userMap.
+     * Filters out any IDs that don’t have a corresponding user.
+     * @param accountIds Array of user IDs to map
+     * @param accountMap Map of userId -> user object
+     * @returns Array of user objects
+     */
+    static mapIdsToAccounts(accountIds: string[], accountMap: Map<string, Account>): any[];
+    /**
+     * Adds a new asynchronous task to the queue.
+     *
+     * @param task - A function that returns a Promise.
+     *               It should contain the actual async logic to be executed.
+     */
+    add(task: () => Promise<void>): void;
+    /**
+     * Executes all queued tasks in parallel and waits for their completion.
+     *
+     * - Tasks are executed concurrently using `Promise.all`.
+     * - If one task fails, the error will propagate and stop execution.
+     */
+    run(): Promise<void>;
+    /**
+     * Clears all tasks from the queue without executing them.
+     * Useful if you want to reset and reuse the TaskManager instance.
+     */
+    clear(): void;
+}