@tmlmobilidade/interfaces 20251217.1540.37 → 20251222.1537.24

package/dist/common/mongo-collection.d.ts

@@ -1,7 +1,7 @@
-import { AggregationPipeline } from './aggregation-pipeline.js';
+import { type AggregationPipeline } from './aggregation-pipeline.js';
 import { MongoConnector } from '@tmlmobilidade/mongo';
 import { type UnixTimestamp } from '@tmlmobilidade/types';
-import { AggregateOptions, AggregationCursor, Collection, DeleteOptions, DeleteResult, Document, Filter, FindOptions, IndexDescription, InsertManyResult, InsertOneOptions, InsertOneResult, MongoClientOptions, UpdateOptions, UpdateResult, WithId } from 'mongodb';
+import { type AggregateOptions, type AggregationCursor, type Collection, type DeleteOptions, type DeleteResult, type Document, type Filter, type FindOptions, type IndexDescription, type InsertManyResult, type InsertOneOptions, type InsertOneResult, type MongoClientOptions, type UpdateOptions, type UpdateResult, type WithId } from 'mongodb';
 import { z } from 'zod';
 export declare abstract class MongoCollectionClass<T extends Document, TCreate, TUpdate> {
     protected createSchema: null | z.ZodSchema;
@@ -10,9 +10,9 @@ export declare abstract class MongoCollectionClass<T extends Document, TCreate,
     protected updateSchema: null | z.ZodSchema;
     /**
      * Aggregates documents in the collection.
-     * @param pipeline - The aggregation pipeline to execute
-     * @param options - The options for the aggregation operation
-     * @returns A promise that resolves to an array of aggregated documents
+     * @param pipeline The aggregation pipeline to execute.
+     * @param options The options for the aggregation operation.
+     * @returns A promise that resolves to an array of aggregated documents.
      */
     aggregate(pipeline: AggregationPipeline<T>, options?: AggregateOptions & {
         returnResult?: true;
@@ -27,22 +27,24 @@ export declare abstract class MongoCollectionClass<T extends Document, TCreate,
     all(): Promise<WithId<T>[]>;
     /**
      * Establishes a connection to the Mongo database and initializes the collection.
-     * @param options Optional Mongo client connection options
-     * @throws {Error} If connection fails
+     * @param options Optional Mongo client connection options.
+     * @throws Error if the environment variable for the database URI is missing or if the connection fails.
      */
     connect(options?: MongoClientOptions): Promise<void>;
     /**
      * Counts documents matching the filter criteria.
-     * @param filter - The filter criteria to match documents
-     * @returns A promise that resolves to the count of matching documents
+     * @param filter The filter criteria to match documents.
+     * @returns A promise that resolves to the count of matching documents.
      */
     count(filter?: Filter<T>): Promise<number>;
     /**
      * Deletes a single document by its ID.
-     * @param id - The ID of the document to delete
-     * @returns A promise that resolves to the result of the delete operation
+     * @param id The ID of the document to delete.
+     * @returns A promise that resolves to the result of the delete operation.
      */
-    deleteById(id: string, options?: DeleteOptions): Promise<DeleteResult>;
+    deleteById(id: T['_id'], options?: DeleteOptions & {
+        forceIfLocked?: boolean;
+    }): Promise<DeleteResult>;
     /**
      * Deletes multiple documents matching the filter criteria.
      * @param filter - The filter criteria to match documents to delete
@@ -54,7 +56,9 @@ export declare abstract class MongoCollectionClass<T extends Document, TCreate,
      * @param filter - The filter criteria to match the document to delete
      * @returns A promise that resolves to the result of the delete operation
      */
-    deleteOne(filter: Filter<T>, options?: DeleteOptions): Promise<DeleteResult>;
+    deleteOne(filter: Filter<T>, options?: DeleteOptions & {
+        forceIfLocked?: boolean;
+    }): Promise<DeleteResult>;
     /**
      * Disconnects from the MongoDB database.
      */
@@ -74,29 +78,29 @@ export declare abstract class MongoCollectionClass<T extends Document, TCreate,
     exists<K extends keyof T>(key: K, value: T[K]): Promise<boolean>;
     /**
      * Checks if a document with the given ID exists in the collection.
-     * @param _id The ID of the document to check for existence.
+     * @param id The ID of the document to check for existence.
      * @returns A promise that resolves to true if the document exists, false otherwise.
      */
-    existsById(_id: T['_id']): Promise<boolean>;
+    existsById(id: T['_id']): Promise<boolean>;
     /**
      * Finds a document by its ID.
-     * @param _id The ID of the document to find.
+     * @param id The ID of the document to find.
      * @param options Optional find options.
-     * @returns A promise that resolves to the matching document or null if not found
+     * @returns A promise that resolves to the matching document or null if not found.
      */
-    findById(_id: T['_id'], options?: FindOptions): Promise<null | WithId<T>>;
+    findById(id: T['_id'], options?: FindOptions): Promise<null | WithId<T>>;
     /**
      * Finds multiple documents matching the filter criteria with optional pagination and sorting.
-     * @param filter - (Optional) filter criteria to match documents
-     * @param options - (Optional) find options
-     * @returns A promise that resolves to an array of matching documents
+     * @param filter (Optional) filter criteria to match documents.
+     * @param options (Optional) find options.
+     * @returns A promise that resolves to an array of matching documents.
      */
     findMany(filter?: Filter<T>, options?: FindOptions): Promise<WithId<T>[]>;
     /**
      * Finds a single document matching the filter criteria.
-     * @param filter - The filter criteria to match the document
-     * @param options - (Optional) find options
-     * @returns A promise that resolves to the matching document or null if not found
+     * @param filter The filter criteria to match the document.
+     * @param options (Optional) find options.
+     * @returns A promise that resolves to the matching document or null if not found.
      */
     findOne(filter: Filter<T>, options?: FindOptions): Promise<null | WithId<T>>;
     /**
@@ -127,9 +131,9 @@ export declare abstract class MongoCollectionClass<T extends Document, TCreate,
     }): Promise<InsertManyResult<T>>;
     /**
      * Inserts a single document into the collection.
-     * @param doc - The document to insert
-     * @param options - The options for the insert operation
-     * @returns A promise that resolves to the result of the insert operation
+     * @param doc The document to insert.
+     * @param options The options for the insert operation.
+     * @returns A promise that resolves to the result of the insert operation.
      */
     insertOne<TReturnDocument extends boolean = true>(doc: TCreate & {
         _id?: string;
@@ -143,14 +147,34 @@ export declare abstract class MongoCollectionClass<T extends Document, TCreate,
         };
         unsafe?: boolean;
     }): Promise<TReturnDocument extends true ? WithId<T> : InsertOneResult<T>>;
+    /**
+     * Checks if a document with the given ID is locked or not.
+     * @param id The ID of the document to check.
+     * @returns A promise that resolves to the result of the check operation.
+     */
+    isLocked(filter: Filter<T>): Promise<boolean>;
+    /**
+     * Checks if a document with the given ID is locked or not.
+     * @param id The ID of the document to check.
+     * @returns A promise that resolves to the result of the check operation.
+     */
+    isLockedById(id: T['_id']): Promise<boolean>;
+    /**
+     * Toogle the lock status of a document by its ID.
+     * @param id The ID of the document to toggle lock status.
+     * @param forceValue Optional boolean to explicitly set the lock status.
+     * @returns A promise that resolves to the result of the update operation.
+     */
+    toggleLockById(id: T['_id'], forceValue?: boolean): Promise<void>;
     /**
      * Updates a document by its ID.
-     * @param _id The ID of the document to update.
+     * @param id The ID of the document to update.
      * @param updateFields The fields to update in the document.
      * @param options Optional options for the update operation.
      * @returns A promise that resolves to the result of the update operation.
      */
-    updateById<TReturnDocument extends boolean = true>(_id: T['_id'], updateFields: TUpdate, options?: UpdateOptions & {
+    updateById<TReturnDocument extends boolean = true>(id: T['_id'], updateFields: TUpdate, options?: UpdateOptions & {
+        forceIfLocked?: boolean;
         returnResult?: TReturnDocument;
     }): Promise<TReturnDocument extends true ? WithId<T> : UpdateResult<T>>;
     /**
@@ -168,12 +192,13 @@ export declare abstract class MongoCollectionClass<T extends Document, TCreate,
     }): Promise<TReturnDocument extends true ? WithId<T>[] : UpdateResult<T>>;
     /**
      * Updates a single document matching the filter criteria.
-     * @param filter - The filter criteria to match the document to update
-     * @param updateFields - The fields to update in the document
-     * @param options - The options for the update operation
-     * @returns A promise that resolves to the result of the update operation
+     * @param filter The filter criteria to match the document to update.
+     * @param updateFields The fields to update in the document.
+     * @param options The options for the update operation.
+     * @returns A promise that resolves to the result of the update operation.
      */
     updateOne<TReturnDocument extends boolean = true>(filter: Filter<T>, updateFields: TUpdate, options?: UpdateOptions & {
+        forceIfLocked?: boolean;
         returnResult?: TReturnDocument;
     }): Promise<TReturnDocument extends true ? WithId<T> : UpdateResult<T>>;
     protected abstract getCollectionIndexes(): IndexDescription[];

package/dist/common/mongo-collection.js

@@ -5,16 +5,19 @@ import { MongoConnector } from '@tmlmobilidade/mongo';
 import { generateRandomString } from '@tmlmobilidade/strings';
 /* * */
 export class MongoCollectionClass {
+    //
     createSchema = null;
     mongoCollection;
     mongoConnector;
     updateSchema = null;
     async aggregate(pipeline, options) {
-        const aggregation = this.mongoCollection.aggregate(pipeline, options);
-        if (options?.returnResult === false) {
-            return aggregation;
-        }
-        return aggregation.toArray();
+        // Perform the aggregation pipeline
+        const aggregationResult = this.mongoCollection.aggregate(pipeline, options);
+        // If returnResult is false, return the cursor directly
+        if (options?.returnResult === false)
+            return aggregationResult;
+        // Otherwise, return the aggregated documents as an array
+        return aggregationResult.toArray();
     }
     /**
      * Gets all documents in the collection.
@@ -25,15 +28,15 @@ export class MongoCollectionClass {
     }
     /**
      * Establishes a connection to the Mongo database and initializes the collection.
-     * @param options Optional Mongo client connection options
-     * @throws {Error} If connection fails
+     * @param options Optional Mongo client connection options.
+     * @throws Error if the environment variable for the database URI is missing or if the connection fails.
      */
     async connect(options) {
-        //
+        // Extract the database URI from environment variables
         const dbUri = process.env[this.getEnvName()];
-        if (!dbUri) {
+        if (!dbUri)
             throw new Error(`Missing ${this.getEnvName()} environment variable`);
-        }
+        // Attempt to connect to the database
         try {
             // Connect to the MongoDB database
             this.mongoConnector = new MongoConnector(dbUri, options);
@@ -52,22 +55,31 @@ export class MongoCollectionClass {
     }
     /**
      * Counts documents matching the filter criteria.
-     * @param filter - The filter criteria to match documents
-     * @returns A promise that resolves to the count of matching documents
+     * @param filter The filter criteria to match documents.
+     * @returns A promise that resolves to the count of matching documents.
      */
     async count(filter) {
         return await this.mongoCollection.countDocuments(filter);
     }
     /**
      * Deletes a single document by its ID.
-     * @param id - The ID of the document to delete
-     * @returns A promise that resolves to the result of the delete operation
+     * @param id The ID of the document to delete.
+     * @returns A promise that resolves to the result of the delete operation.
      */
     async deleteById(id, options) {
+        // If forceIfLocked is not set then check if the document is locked.
+        // If it is locked, then throw an error to prevent the operation.
+        if (!options?.forceIfLocked) {
+            const isLocked = await this.isLockedById(id);
+            if (isLocked)
+                throw new HttpException(HttpStatus.FORBIDDEN, 'Document is locked and cannot be deleted');
+        }
+        // Perform the delete operation
         const result = await this.deleteOne({ _id: { $eq: id } }, options);
-        if (!result.acknowledged) {
+        // Check if the delete operation was acknowledged
+        if (!result.acknowledged)
             throw new HttpException(HttpStatus.INTERNAL_SERVER_ERROR, 'Failed to delete documents', result);
-        }
+        // Return the result of the delete operation
         return result;
     }
     /**
@@ -77,9 +89,8 @@ export class MongoCollectionClass {
      */
     async deleteMany(filter) {
         const result = await this.mongoCollection.deleteMany(filter);
-        if (!result.acknowledged) {
+        if (!result.acknowledged)
             throw new HttpException(HttpStatus.INTERNAL_SERVER_ERROR, 'Failed to delete documents', result);
-        }
         return result;
     }
     /**
@@ -88,10 +99,17 @@ export class MongoCollectionClass {
      * @returns A promise that resolves to the result of the delete operation
      */
     async deleteOne(filter, options) {
+        // If forceIfLocked is not set then check if the document is locked.
+        // If it is locked, then throw an error to prevent the operation.
+        if (!options?.forceIfLocked) {
+            const isLocked = await this.isLocked(filter);
+            if (isLocked)
+                throw new HttpException(HttpStatus.FORBIDDEN, 'Document is locked and cannot be deleted');
+        }
+        // Perform the delete operation
         const result = await this.mongoCollection.deleteOne(filter, options);
-        if (!result.acknowledged) {
+        if (!result.acknowledged)
             throw new HttpException(HttpStatus.INTERNAL_SERVER_ERROR, 'Failed to delete document', result);
-        }
         return result;
     }
     /**
@@ -121,37 +139,36 @@ export class MongoCollectionClass {
     }
     /**
      * Checks if a document with the given ID exists in the collection.
-     * @param _id The ID of the document to check for existence.
+     * @param id The ID of the document to check for existence.
      * @returns A promise that resolves to true if the document exists, false otherwise.
      */
-    async existsById(_id) {
-        const doc = await this.mongoCollection.findOne({ _id: _id }, { projection: { _id: 1 } });
-        return doc !== null;
+    async existsById(id) {
+        const foundDoc = await this.mongoCollection.findOne({ _id: id }, { projection: { _id: 1 } });
+        return foundDoc !== null;
     }
     /**
      * Finds a document by its ID.
-     * @param _id The ID of the document to find.
+     * @param id The ID of the document to find.
      * @param options Optional find options.
-     * @returns A promise that resolves to the matching document or null if not found
+     * @returns A promise that resolves to the matching document or null if not found.
      */
-    async findById(_id, options) {
-        const filter = { _id: { $eq: _id } };
-        return this.mongoCollection.findOne(filter, options);
+    async findById(id, options) {
+        return this.mongoCollection.findOne({ _id: { $eq: id } }, options);
     }
     /**
      * Finds multiple documents matching the filter criteria with optional pagination and sorting.
-     * @param filter - (Optional) filter criteria to match documents
-     * @param options - (Optional) find options
-     * @returns A promise that resolves to an array of matching documents
+     * @param filter (Optional) filter criteria to match documents.
+     * @param options (Optional) find options.
+     * @returns A promise that resolves to an array of matching documents.
      */
     async findMany(filter, options) {
         return await this.mongoCollection.find(filter ?? {}, options).toArray();
     }
     /**
      * Finds a single document matching the filter criteria.
-     * @param filter - The filter criteria to match the document
-     * @param options - (Optional) find options
-     * @returns A promise that resolves to the matching document or null if not found
+     * @param filter The filter criteria to match the document.
+     * @param options (Optional) find options.
+     * @returns A promise that resolves to the matching document or null if not found.
      */
     async findOne(filter, options) {
         return await this.mongoCollection.findOne(filter, options);
@@ -214,58 +231,121 @@ export class MongoCollectionClass {
     }
     /**
      * Inserts a single document into the collection.
-     * @param doc - The document to insert
-     * @param options - The options for the insert operation
-     * @returns A promise that resolves to the result of the insert operation
+     * @param doc The document to insert.
+     * @param options The options for the insert operation.
+     * @returns A promise that resolves to the result of the insert operation.
      */
     async insertOne(doc, { options, unsafe = false } = {}) {
-        const newDocument = {
-            ...doc,
-            _id: doc._id || generateRandomString({ length: 5 }),
-            created_at: doc.created_at || Dates.now('utc').unix_timestamp,
-            created_by: doc.created_by || 'system',
-            updated_at: doc.updated_at || Dates.now('utc').unix_timestamp,
-            updated_by: doc.updated_by || 'system',
-        };
-        if (!doc._id) {
-            while (await this.findById(newDocument._id)) {
-                newDocument._id = generateRandomString({ length: 5 });
-            }
-        }
-        let parsedDocument = newDocument;
+        // Setup a copy of the document to be inserted
+        let parsedDocument = { ...doc };
+        // Validate the document against the create schema if unsafe is false
         if (!unsafe) {
             try {
-                if (!this.createSchema) {
+                // If no create schema is defined, throw an error.
+                // In safe mode, a schema is required to validate the document.
+                if (!this.createSchema)
                     throw new Error('No schema defined for insert operation. This is either an internal interface error or you should pass unsafe=true to the insert operation.');
-                }
-                parsedDocument = this.createSchema.parse(newDocument);
+                // Validate the document against the create schema
+                parsedDocument = this.createSchema.parse(parsedDocument);
             }
             catch (error) {
                 throw new HttpException(HttpStatus.BAD_REQUEST, error.message, { cause: error });
             }
         }
+        // Add default fields if they are missing from the original document
+        if (!doc.created_at)
+            parsedDocument.created_at = Dates.now('utc').unix_timestamp;
+        if (!doc.created_by)
+            parsedDocument.created_by = 'system';
+        if (!doc.updated_at)
+            parsedDocument.updated_at = Dates.now('utc').unix_timestamp;
+        if (!doc.updated_by)
+            parsedDocument.updated_by = 'system';
+        // Add the ID if it is missing from the original document
+        // If the document is missing any default fields, add them
+        if (!doc._id) {
+            parsedDocument._id = generateRandomString({ length: 5 });
+            while (await this.findById(parsedDocument._id)) {
+                parsedDocument._id = generateRandomString({ length: 5 });
+            }
+        }
+        // Attempt to insert the document into the collection
         const result = await this.mongoCollection.insertOne(parsedDocument, options);
-        if (!result.acknowledged) {
+        // Check if the insert operation was acknowledged
+        if (!result.acknowledged)
             throw new HttpException(HttpStatus.INTERNAL_SERVER_ERROR, 'Failed to insert document', result);
-        }
+        // If returnResult is false, return the insert result directly
         if (options && options.returnResult === false)
             return result;
-        const inserted_doc = await this.findOne({ _id: { $eq: result.insertedId } }, options);
-        if (!inserted_doc) {
+        // Otherwise, fetch and return the inserted document
+        const insertedDoc = await this.findOne({ _id: { $eq: result.insertedId } }, options);
+        if (!insertedDoc)
             throw new HttpException(HttpStatus.INTERNAL_SERVER_ERROR, 'Failed to find inserted document', result);
-        }
-        return inserted_doc;
+        return insertedDoc;
+    }
+    /**
+     * Checks if a document with the given ID is locked or not.
+     * @param id The ID of the document to check.
+     * @returns A promise that resolves to the result of the check operation.
+     */
+    async isLocked(filter) {
+        // Fetch the document by its ID from the database
+        const foundDoc = await this.findOne(filter);
+        // If the document has a is_locked field and it resolves to a truthy value,
+        // then the document is considered locked.
+        if (foundDoc?.is_locked)
+            return true;
+        // Otherwise, the document is not locked.
+        return false;
+    }
+    /**
+     * Checks if a document with the given ID is locked or not.
+     * @param id The ID of the document to check.
+     * @returns A promise that resolves to the result of the check operation.
+     */
+    async isLockedById(id) {
+        // Fetch the document by its ID from the database
+        const foundDoc = await this.findById(id);
+        // If the document has a is_locked field and it resolves to a truthy value,
+        // then the document is considered locked.
+        if (foundDoc?.is_locked)
+            return true;
+        // Otherwise, the document is not locked.
+        return false;
+    }
+    /**
+     * Toogle the lock status of a document by its ID.
+     * @param id The ID of the document to toggle lock status.
+     * @param forceValue Optional boolean to explicitly set the lock status.
+     * @returns A promise that resolves to the result of the update operation.
+     */
+    async toggleLockById(id, forceValue) {
+        // Get the current document from the database
+        const foundDoc = await this.findById(id);
+        if (!foundDoc)
+            throw new Error('Document not found');
+        // Determine the new lock status
+        const newLockStatus = forceValue !== undefined ? forceValue : !foundDoc.is_locked;
+        // Update the document with the new lock status
+        await this.mongoCollection.updateOne({ _id: { $eq: id } }, { $set: { is_locked: newLockStatus } });
     }
     /**
      * Updates a document by its ID.
-     * @param _id The ID of the document to update.
+     * @param id The ID of the document to update.
      * @param updateFields The fields to update in the document.
      * @param options Optional options for the update operation.
      * @returns A promise that resolves to the result of the update operation.
      */
-    async updateById(_id, updateFields, options) {
-        const filter = { _id: { $eq: _id } };
-        return this.updateOne(filter, updateFields, options);
+    async updateById(id, updateFields, options) {
+        // If forceIfLocked is not set then check if the document is locked.
+        // If it is locked, then throw an error to prevent the operation.
+        if (!options?.forceIfLocked) {
+            const isLocked = await this.isLockedById(id);
+            if (isLocked)
+                throw new HttpException(HttpStatus.FORBIDDEN, 'Document is locked and cannot be updated');
+        }
+        // Perform the update operation
+        return this.updateOne({ _id: { $eq: id } }, updateFields, options);
     }
     /**
      * Updates multiple documents matching the filter criteria.
@@ -302,12 +382,20 @@ export class MongoCollectionClass {
     }
     /**
      * Updates a single document matching the filter criteria.
-     * @param filter - The filter criteria to match the document to update
-     * @param updateFields - The fields to update in the document
-     * @param options - The options for the update operation
-     * @returns A promise that resolves to the result of the update operation
+     * @param filter The filter criteria to match the document to update.
+     * @param updateFields The fields to update in the document.
+     * @param options The options for the update operation.
+     * @returns A promise that resolves to the result of the update operation.
      */
     async updateOne(filter, updateFields, options) {
+        // If forceIfLocked is not set then check if the document is locked.
+        // If it is locked, then throw an error to prevent the operation.
+        if (!options?.forceIfLocked) {
+            const isLocked = await this.isLocked(filter);
+            if (isLocked)
+                throw new HttpException(HttpStatus.FORBIDDEN, 'Document is locked and cannot be updated');
+        }
+        // Perform the update operation
         let parsedUpdateFields = updateFields;
         if (this.updateSchema) {
             try {

package/dist/interfaces/agencies/agencies.d.ts

@@ -13,6 +13,7 @@ declare class AgenciesClass extends MongoCollectionClass<Agency, CreateAgencyDto
         created_at: number & {
             __brand: "UnixTimestamp";
         };
+        is_locked: boolean;
         updated_at: number & {
             __brand: "UnixTimestamp";
         };
@@ -24,9 +25,7 @@ declare class AgenciesClass extends MongoCollectionClass<Agency, CreateAgencyDto
             vkm_per_month: number[];
         };
         name: string;
-        operation_start_date: string & {
-            __brand: "OperationalDate";
-        };
+        operation_start_date: import("@tmlmobilidade/types").OperationalDate | null;
         phone: string;
         public_email: string;
         short_name: string;
@@ -40,6 +39,7 @@ declare class AgenciesClass extends MongoCollectionClass<Agency, CreateAgencyDto
         created_at: number & {
             __brand: "UnixTimestamp";
         };
+        is_locked: boolean;
         updated_at: number & {
             __brand: "UnixTimestamp";
         };
@@ -51,9 +51,7 @@ declare class AgenciesClass extends MongoCollectionClass<Agency, CreateAgencyDto
             vkm_per_month: number[];
         };
         name: string;
-        operation_start_date: string & {
-            __brand: "OperationalDate";
-        };
+        operation_start_date: import("@tmlmobilidade/types").OperationalDate | null;
         phone: string;
         public_email: string;
         short_name: string;