@tmlmobilidade/go-interfaces-godb 20260717.1316.58

package/dist/databases/core.d.ts

@@ -0,0 +1,16 @@
+import type { MongoClient } from '@tmlmobilidade/go-clients-mongo';
+import type { Agency, CreateAgencyDto, CreateFileDto, CreateFileExportDto, CreateOrganizationDto, CreateRoleDto, CreateSessionDto, CreateUserDto, CreateVerificationTokenDto, File, FileExport, Organization, Role, Session, UpdateAgencyDto, UpdateFileDto, UpdateOrganizationDto, UpdateRoleDto, UpdateSessionDto, UpdateUserDto, UpdateVerificationTokenDto, User, VerificationToken } from '@tmlmobilidade/types';
+import { MongoInterfaceTemplate } from '../interface.template.js';
+export declare class CoreDatabase {
+    readonly agencies: MongoInterfaceTemplate<Agency, CreateAgencyDto, UpdateAgencyDto>;
+    readonly exports: MongoInterfaceTemplate<FileExport, CreateFileExportDto<any>, Partial<FileExport>>;
+    readonly files: MongoInterfaceTemplate<File, CreateFileDto, UpdateFileDto>;
+    readonly organizations: MongoInterfaceTemplate<Organization, CreateOrganizationDto, UpdateOrganizationDto>;
+    readonly roles: MongoInterfaceTemplate<Role, CreateRoleDto, UpdateRoleDto>;
+    readonly sessions: MongoInterfaceTemplate<Session, CreateSessionDto, UpdateSessionDto>;
+    readonly users: MongoInterfaceTemplate<User, CreateUserDto, UpdateUserDto>;
+    readonly verificationTokens: MongoInterfaceTemplate<VerificationToken, CreateVerificationTokenDto, UpdateVerificationTokenDto>;
+    private readonly database;
+    private readonly databaseName;
+    constructor(instance: MongoClient);
+}

package/dist/databases/core.js

@@ -0,0 +1,33 @@
+/* * */
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { CreateAgencySchema, CreateFileExportSchema, CreateFileSchema, CreateOrganizationSchema, CreateRoleSchema, CreateSessionSchema, CreateUserSchema, CreateVerificationTokenSchema, UpdateAgencySchema, UpdateFileExportSchema, UpdateFileSchema, UpdateOrganizationSchema, UpdateRoleSchema, UpdateSessionSchema, UpdateUserSchema, UpdateVerificationTokenSchema } from '@tmlmobilidade/types';
+/* * */
+export class CoreDatabase {
+    //
+    //
+    // Collections
+    agencies;
+    exports;
+    files;
+    organizations;
+    roles;
+    sessions;
+    users;
+    verificationTokens;
+    //
+    database;
+    databaseName = 'core';
+    constructor(instance) {
+        // Create the database instance
+        this.database = instance.db(this.databaseName);
+        // Create collection interfaces
+        this.agencies = new MongoInterfaceTemplate('agencies', this.database, CreateAgencySchema, UpdateAgencySchema);
+        this.exports = new MongoInterfaceTemplate('exports', this.database, CreateFileExportSchema, UpdateFileExportSchema);
+        this.organizations = new MongoInterfaceTemplate('organizations', this.database, CreateOrganizationSchema, UpdateOrganizationSchema);
+        this.roles = new MongoInterfaceTemplate('roles', this.database, CreateRoleSchema, UpdateRoleSchema);
+        this.sessions = new MongoInterfaceTemplate('sessions', this.database, CreateSessionSchema, UpdateSessionSchema);
+        this.users = new MongoInterfaceTemplate('users', this.database, CreateUserSchema, UpdateUserSchema);
+        this.verificationTokens = new MongoInterfaceTemplate('verificationTokens', this.database, CreateVerificationTokenSchema, UpdateVerificationTokenSchema);
+        this.files = new MongoInterfaceTemplate('files', this.database, CreateFileSchema, UpdateFileSchema);
+    }
+}

package/dist/databases/infrastructure.d.ts

@@ -0,0 +1,9 @@
+import type { MongoClient } from '@tmlmobilidade/go-clients-mongo';
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { CreateStopDto, Stop, UpdateStopDto } from '@tmlmobilidade/types';
+export declare class InfrastructureDatabase {
+    readonly stops: MongoInterfaceTemplate<Stop, CreateStopDto, UpdateStopDto>;
+    private readonly database;
+    private readonly databaseName;
+    constructor(instance: MongoClient);
+}

package/dist/databases/infrastructure.js

@@ -0,0 +1,19 @@
+/* * */
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { CreateStopSchema, UpdateStopSchema } from '@tmlmobilidade/types';
+/* * */
+export class InfrastructureDatabase {
+    //
+    //
+    // Collections
+    stops;
+    //
+    database;
+    databaseName = 'infrastructure';
+    constructor(instance) {
+        // Create the database instance
+        this.database = instance.db(this.databaseName);
+        // Create collection interfaces
+        this.stops = new MongoInterfaceTemplate('stops', this.database, CreateStopSchema, UpdateStopSchema);
+    }
+}

package/dist/databases/locations.d.ts

@@ -0,0 +1,12 @@
+import type { MongoClient } from '@tmlmobilidade/go-clients-mongo';
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { District, Locality, Municipality, Parish } from '@tmlmobilidade/types';
+export declare class LocationsDatabase {
+    readonly districts: MongoInterfaceTemplate<District, null, null>;
+    readonly localities: MongoInterfaceTemplate<Locality, null, null>;
+    readonly municipalities: MongoInterfaceTemplate<Municipality, null, null>;
+    readonly parishes: MongoInterfaceTemplate<Parish, null, null>;
+    private readonly database;
+    private readonly databaseName;
+    constructor(instance: MongoClient);
+}

package/dist/databases/locations.js

@@ -0,0 +1,24 @@
+/* * */
+import { MongoInterfaceTemplate } from '../interface.template.js';
+/* * */
+export class LocationsDatabase {
+    //
+    //
+    // Collections
+    districts;
+    localities;
+    municipalities;
+    parishes;
+    //
+    database;
+    databaseName = 'locations';
+    constructor(instance) {
+        // Create the database instance
+        this.database = instance.db(this.databaseName);
+        // Create collection interfaces
+        this.districts = new MongoInterfaceTemplate('districts', this.database, null, null);
+        this.localities = new MongoInterfaceTemplate('localities', this.database, null, null);
+        this.municipalities = new MongoInterfaceTemplate('municipalities', this.database, null, null);
+        this.parishes = new MongoInterfaceTemplate('parishes', this.database, null, null);
+    }
+}

package/dist/databases/offer.d.ts

@@ -0,0 +1,18 @@
+import type { Db, MongoClient } from '@tmlmobilidade/go-clients-mongo';
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { Annotation, CreateAnnotationDto, CreateEventDto, CreateFareDto, CreateHolidayDto, CreateLineDto, CreatePatternDto, CreateRouteDto, CreateTypologyDto, CreateYearPeriodDto, CreateZoneDto, Event, Fare, Holiday, Line, Pattern, Route, Typology, UpdateAnnotationDto, UpdateEventDto, UpdateFareDto, UpdateHolidayDto, UpdateLineDto, UpdatePatternDto, UpdateRouteDto, UpdateTypologyDto, UpdateYearPeriodDto, UpdateZoneDto, YearPeriod, Zone } from '@tmlmobilidade/types';
+export declare class OfferDatabase {
+    readonly annotations: MongoInterfaceTemplate<Annotation, CreateAnnotationDto, UpdateAnnotationDto>;
+    readonly events: MongoInterfaceTemplate<Event, CreateEventDto, UpdateEventDto>;
+    readonly fares: MongoInterfaceTemplate<Fare, CreateFareDto, UpdateFareDto>;
+    readonly holidays: MongoInterfaceTemplate<Holiday, CreateHolidayDto, UpdateHolidayDto>;
+    readonly lines: MongoInterfaceTemplate<Line, CreateLineDto, UpdateLineDto>;
+    readonly patterns: MongoInterfaceTemplate<Pattern, CreatePatternDto, UpdatePatternDto>;
+    readonly routes: MongoInterfaceTemplate<Route, CreateRouteDto, UpdateRouteDto>;
+    readonly typologies: MongoInterfaceTemplate<Typology, CreateTypologyDto, UpdateTypologyDto>;
+    readonly yearPeriods: MongoInterfaceTemplate<YearPeriod, CreateYearPeriodDto, UpdateYearPeriodDto>;
+    readonly zones: MongoInterfaceTemplate<Zone, CreateZoneDto, UpdateZoneDto>;
+    readonly database: Db;
+    readonly databaseName = "offer";
+    constructor(instance: MongoClient);
+}

package/dist/databases/offer.js

@@ -0,0 +1,37 @@
+/* * */
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { CreateAnnotationSchema, CreateEventSchema, CreateFareSchema, CreateHolidaySchema, CreateLineSchema, CreatePatternSchema, CreateRouteSchema, CreateTypologySchema, CreateYearPeriodSchema, CreateZoneSchema, UpdateAnnotationSchema, UpdateEventSchema, UpdateFareSchema, UpdateHolidaySchema, UpdateLineSchema, UpdatePatternSchema, UpdateRouteSchema, UpdateTypologySchema, UpdateYearPeriodSchema, UpdateZoneSchema } from '@tmlmobilidade/types';
+/* * */
+export class OfferDatabase {
+    //
+    //
+    // Collections
+    annotations;
+    events;
+    fares;
+    holidays;
+    lines;
+    patterns;
+    routes;
+    typologies;
+    yearPeriods;
+    zones;
+    //
+    database;
+    databaseName = 'offer';
+    constructor(instance) {
+        // Create the database instance
+        this.database = instance.db(this.databaseName);
+        // Create collection interfaces
+        this.annotations = new MongoInterfaceTemplate('annotations', this.database, CreateAnnotationSchema, UpdateAnnotationSchema);
+        this.events = new MongoInterfaceTemplate('events', this.database, CreateEventSchema, UpdateEventSchema);
+        this.fares = new MongoInterfaceTemplate('fares', this.database, CreateFareSchema, UpdateFareSchema);
+        this.holidays = new MongoInterfaceTemplate('holidays', this.database, CreateHolidaySchema, UpdateHolidaySchema);
+        this.lines = new MongoInterfaceTemplate('lines', this.database, CreateLineSchema, UpdateLineSchema);
+        this.patterns = new MongoInterfaceTemplate('patterns', this.database, CreatePatternSchema, UpdatePatternSchema);
+        this.routes = new MongoInterfaceTemplate('routes', this.database, CreateRouteSchema, UpdateRouteSchema);
+        this.typologies = new MongoInterfaceTemplate('typologies', this.database, CreateTypologySchema, UpdateTypologySchema);
+        this.yearPeriods = new MongoInterfaceTemplate('yearPeriods', this.database, CreateYearPeriodSchema, UpdateYearPeriodSchema);
+        this.zones = new MongoInterfaceTemplate('zones', this.database, CreateZoneSchema, UpdateZoneSchema);
+    }
+}

package/dist/databases/operation.d.ts

@@ -0,0 +1,17 @@
+import type { MongoClient } from '@tmlmobilidade/go-clients-mongo';
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { CreateGtfsValidationDto, CreatePlanDto, CreateRideAcceptanceDto, CreateRideDto, CreateSamDto, CreateVehicleDto, GtfsValidation, HashedPattern, HashedShape, HashedTrip, Plan, Ride, RideAcceptance, Sam, UpdateGtfsValidationDto, UpdatePlanDto, UpdateRideAcceptanceDto, UpdateRideDto, UpdateSamDto, UpdateVehicleDto, Vehicle } from '@tmlmobilidade/types';
+export declare class OperationDatabase {
+    readonly gtfsValidations: MongoInterfaceTemplate<GtfsValidation, CreateGtfsValidationDto, UpdateGtfsValidationDto>;
+    readonly hashedPatterns: MongoInterfaceTemplate<HashedPattern, HashedPattern, HashedPattern>;
+    readonly hashedShapes: MongoInterfaceTemplate<HashedShape, HashedShape, HashedShape>;
+    readonly hashedTrips: MongoInterfaceTemplate<HashedTrip, HashedTrip, HashedTrip>;
+    readonly plans: MongoInterfaceTemplate<Plan, CreatePlanDto, UpdatePlanDto>;
+    readonly rideAcceptances: MongoInterfaceTemplate<RideAcceptance, CreateRideAcceptanceDto, UpdateRideAcceptanceDto>;
+    readonly rides: MongoInterfaceTemplate<Ride, CreateRideDto, UpdateRideDto>;
+    readonly sams: MongoInterfaceTemplate<Sam, CreateSamDto, UpdateSamDto>;
+    readonly vehicles: MongoInterfaceTemplate<Vehicle, CreateVehicleDto, UpdateVehicleDto>;
+    private readonly database;
+    private readonly databaseName;
+    constructor(instance: MongoClient);
+}

package/dist/databases/operation.js

@@ -0,0 +1,35 @@
+/* * */
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { CreateGtfsValidationSchema, CreatePlanSchema, CreateRideAcceptanceSchema, CreateRideSchema, CreateSamSchema, CreateVehicleSchema, DocumentSchema, HashedPatternSchema, HashedTripSchema, UpdateGtfsValidationSchema, UpdatePlanSchema, UpdateRideAcceptanceSchema, UpdateRideSchema, UpdateSamSchema, UpdateVehicleSchema } from '@tmlmobilidade/types';
+/* * */
+export class OperationDatabase {
+    //
+    //
+    // Collections
+    gtfsValidations;
+    hashedPatterns;
+    hashedShapes;
+    hashedTrips;
+    plans;
+    rideAcceptances;
+    rides;
+    sams;
+    vehicles;
+    //
+    database;
+    databaseName = 'operation';
+    constructor(instance) {
+        // Create the database instance
+        this.database = instance.db(this.databaseName);
+        // Create collection interfaces
+        this.gtfsValidations = new MongoInterfaceTemplate('gtfsValidations', this.database, CreateGtfsValidationSchema, UpdateGtfsValidationSchema);
+        this.hashedPatterns = new MongoInterfaceTemplate('hashedPatterns', this.database, HashedPatternSchema, HashedPatternSchema);
+        this.hashedShapes = new MongoInterfaceTemplate('hashedShapes', this.database, DocumentSchema, DocumentSchema);
+        this.hashedTrips = new MongoInterfaceTemplate('hashedTrips', this.database, HashedTripSchema, HashedTripSchema);
+        this.plans = new MongoInterfaceTemplate('plans', this.database, CreatePlanSchema, UpdatePlanSchema);
+        this.rideAcceptances = new MongoInterfaceTemplate('rideAcceptances', this.database, CreateRideAcceptanceSchema, UpdateRideAcceptanceSchema);
+        this.rides = new MongoInterfaceTemplate('rides', this.database, CreateRideSchema, UpdateRideSchema);
+        this.sams = new MongoInterfaceTemplate('sams', this.database, CreateSamSchema, UpdateSamSchema);
+        this.vehicles = new MongoInterfaceTemplate('vehicles', this.database, CreateVehicleSchema, UpdateVehicleSchema);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { CoreDatabase } from './databases/core.js';
+import { InfrastructureDatabase } from './databases/infrastructure.js';
+import { LocationsDatabase } from './databases/locations.js';
+import { OfferDatabase } from './databases/offer.js';
+import { OperationDatabase } from './databases/operation.js';
+declare class GoDBClass {
+    private static _instance;
+    private mongoClient;
+    readonly core: CoreDatabase;
+    readonly infrastructure: InfrastructureDatabase;
+    readonly locations: LocationsDatabase;
+    readonly offer: OfferDatabase;
+    readonly operation: OperationDatabase;
+    /**
+     * Establishes a connection to the Mongo database and initializes the collection.
+     * @param options Optional Mongo client connection options.
+     * @throws Error if the environment variable for the database URI is missing or if the connection fails.
+     */
+    static getInstance(): Promise<GoDBClass>;
+    private constructor();
+}
+export declare const goDb: GoDBClass;
+export {};

package/dist/index.js

@@ -0,0 +1,47 @@
+/* * */
+import { MongoDatabaseClient } from '@tmlmobilidade/go-clients-mongo';
+import { asyncSingletonProxy } from '@tmlmobilidade/utils';
+import { CoreDatabase } from './databases/core.js';
+import { InfrastructureDatabase } from './databases/infrastructure.js';
+import { LocationsDatabase } from './databases/locations.js';
+import { OfferDatabase } from './databases/offer.js';
+import { OperationDatabase } from './databases/operation.js';
+/* * */
+class GoDBClass {
+    //
+    //
+    //
+    static _instance;
+    mongoClient;
+    //
+    // Databases
+    core;
+    infrastructure;
+    locations;
+    offer;
+    operation;
+    /**
+     * Establishes a connection to the Mongo database and initializes the collection.
+     * @param options Optional Mongo client connection options.
+     * @throws Error if the environment variable for the database URI is missing or if the connection fails.
+     */
+    static async getInstance() {
+        if (!GoDBClass._instance) {
+            const mongoClient = await MongoDatabaseClient.getClient({ prefix: 'GODB' });
+            GoDBClass._instance = new GoDBClass(mongoClient);
+        }
+        return GoDBClass._instance;
+    }
+    //
+    // Constructor
+    //
+    // Constructor
+    constructor(mongoClient) {
+        this.core = new CoreDatabase(mongoClient);
+        this.infrastructure = new InfrastructureDatabase(mongoClient);
+        this.locations = new LocationsDatabase(mongoClient);
+        this.offer = new OfferDatabase(mongoClient);
+        this.operation = new OperationDatabase(mongoClient);
+    }
+}
+export const goDb = asyncSingletonProxy(GoDBClass);

package/dist/interface.template.d.ts

@@ -0,0 +1,189 @@
+import type { AggregationPipeline } from '@tmlmobilidade/go-clients-mongo';
+import type { AggregateOptions, AggregationCursor, BulkWriteOptions, Collection, Db, DeleteOptions, DeleteResult, Document, Filter, FindOptions, Flatten, InsertManyResult, InsertOneOptions, InsertOneResult, UpdateOptions, UpdateResult, WithId } from '@tmlmobilidade/go-clients-mongo';
+import { UnixTimestamp } from '@tmlmobilidade/go-types-shared';
+import z from 'zod';
+export declare class MongoInterfaceTemplate<T extends Document, TCreate, TUpdate> {
+    private readonly createSchema;
+    private readonly mongoCollection;
+    private readonly updateSchema;
+    /**
+     * @param collectionName - The name of the collection to create the interface for.
+     * @param databaseName - The name of the database to create the interface for.
+     * @param createSchema - The schema to use for creating documents.
+     * @param updateSchema - The schema to use for updating documents.
+     */
+    constructor(collectionName: string, database: Db, createSchema: null | z.ZodSchema, updateSchema: null | z.ZodSchema);
+    /**
+     * Gets the MongoDB collection instance.
+     * @returns The MongoDB collection instance
+     */
+    getCollection(): Promise<Collection<T>>;
+    /**
+     * Finds all distinct values for a key in the collection.
+     * @param key The key to find distinct values for.
+     * @returns A promise that resolves to an array of distinct values for the given key.
+     */
+    distinct<Key extends keyof WithId<T>>(key: Key, filter?: Filter<T>): Promise<Array<Flatten<WithId<T>[Key]>>>;
+    /**
+     * Checks if a document with the given key and value exists in the collection.
+     * @param key The key to check for existence.
+     * @param value The value of the key to check for existence.
+     * @returns A promise that resolves to true if the document exists, false otherwise.
+     */
+    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.
+     * @returns A promise that resolves to true if the document exists, false otherwise.
+     */
+    existsById(id: T['_id']): Promise<boolean>;
+    /**
+     * 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.
+     */
+    findMany(filter?: Filter<T>, options?: FindOptions): Promise<WithId<T>[]>;
+    /**
+     * Finds a document by its ID.
+     * @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.
+     */
+    findById(id: T['_id'], options?: FindOptions): Promise<null | 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.
+     */
+    findOne(filter: Filter<T>, options?: FindOptions): Promise<null | WithId<T>>;
+    /**
+     * Inserts multiple documents into the collection.
+     * @param docs - The documents to insert
+     * @param options - The options for the insert operation
+     * @returns A promise that resolves to the result of the insert operation
+     */
+    insertMany(docs: (TCreate & {
+        _id?: T['_id'];
+        created_at?: UnixTimestamp;
+        created_by?: string;
+        updated_at?: UnixTimestamp;
+        updated_by?: string;
+    })[], { options, unsafe }?: {
+        options?: BulkWriteOptions;
+        unsafe?: boolean;
+    }): 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.
+     */
+    insertOne<TReturnDocument extends boolean = true>(doc: TCreate & {
+        _id?: T['_id'];
+        created_at?: UnixTimestamp;
+        created_by?: string;
+        updated_at?: UnixTimestamp;
+        updated_by?: string;
+    }, { options, unsafe }?: {
+        options?: InsertOneOptions & {
+            returnResult?: TReturnDocument;
+        };
+        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>;
+    /**
+     * Toggle 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 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 & {
+        forceIfLocked?: boolean;
+        returnResult?: TReturnDocument;
+    }): Promise<TReturnDocument extends true ? WithId<T> : UpdateResult<T>>;
+    /**
+     * Updates multiple documents matching the filter criteria.
+     * @param filter - The filter criteria to match documents to update
+     * @param updateFields - The fields to update in the documents
+     * @param options - The options for the update operation
+     * @returns A promise that resolves to the result of the update operation
+     */
+    updateMany<TReturnDocument extends boolean = true>(filter: Filter<T>, updateFields: TUpdate & {
+        updated_at?: UnixTimestamp;
+        updated_by?: string;
+    }, options?: UpdateOptions & {
+        returnResults?: TReturnDocument;
+    }): 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.
+     */
+    updateOne<TReturnDocument extends boolean = true>(filter: Filter<T>, updateFields: TUpdate, options?: UpdateOptions & {
+        forceIfLocked?: boolean;
+        returnResult?: TReturnDocument;
+    }): Promise<TReturnDocument extends true ? WithId<T> : UpdateResult<T>>;
+    /**
+     * 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.
+     */
+    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.
+     */
+    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.
+     * @returns A promise that resolves to the result of the delete many operation.
+     */
+    deleteMany(filter: Filter<T>): Promise<DeleteResult>;
+    /**
+     * Deletes a single document matching the filter criteria.
+     * @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 & {
+        forceIfLocked?: boolean;
+    }): Promise<DeleteResult>;
+    /**
+     * 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.
+     */
+    aggregate(pipeline: AggregationPipeline<T>, options?: AggregateOptions & {
+        returnResult?: true;
+    }): Promise<T[]>;
+    aggregate(pipeline: AggregationPipeline<T>, options: AggregateOptions & {
+        returnResult: false;
+    }): Promise<AggregationCursor<T>>;
+}

package/dist/interface.template.js

@@ -0,0 +1,376 @@
+/* * */
+import { HTTP_STATUS, HttpException } from '@tmlmobilidade/consts';
+import { Dates } from '@tmlmobilidade/dates';
+import { generateRandomString } from '@tmlmobilidade/strings';
+/* * */
+export class MongoInterfaceTemplate {
+    //
+    createSchema = null;
+    mongoCollection;
+    updateSchema = null;
+    /**
+     * @param collectionName - The name of the collection to create the interface for.
+     * @param databaseName - The name of the database to create the interface for.
+     * @param createSchema - The schema to use for creating documents.
+     * @param updateSchema - The schema to use for updating documents.
+     */
+    constructor(collectionName, database, createSchema, updateSchema) {
+        this.mongoCollection = database.collection(collectionName);
+        this.createSchema = createSchema;
+        this.updateSchema = updateSchema;
+    }
+    /**
+     * Gets the MongoDB collection instance.
+     * @returns The MongoDB collection instance
+     */
+    async getCollection() {
+        return this.mongoCollection;
+    }
+    /**
+     * Finds all distinct values for a key in the collection.
+     * @param key The key to find distinct values for.
+     * @returns A promise that resolves to an array of distinct values for the given key.
+     */
+    async distinct(key, filter = {}) {
+        return this.mongoCollection.distinct(key, filter);
+    }
+    /**
+     * Checks if a document with the given key and value exists in the collection.
+     * @param key The key to check for existence.
+     * @param value The value of the key to check for existence.
+     * @returns A promise that resolves to true if the document exists, false otherwise.
+     */
+    async exists(key, value) {
+        const filter = { [key]: value };
+        const doc = await this.mongoCollection.findOne(filter, { projection: { [key]: 1 } });
+        return !!doc;
+    }
+    /**
+     * Checks if a document with the given ID exists in the collection.
+     * @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 foundDoc = await this.mongoCollection.findOne({ _id: id }, { projection: { _id: 1 } });
+        return !!foundDoc;
+    }
+    /**
+     * 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.
+     */
+    async findMany(filter, options) {
+        return await this.mongoCollection.find(filter ?? {}, options).toArray();
+    }
+    /**
+     * Finds a document by its ID.
+     * @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.
+     */
+    async findById(id, options) {
+        return this.mongoCollection.findOne({ _id: { $eq: id } }, options);
+    }
+    /**
+     * 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.
+     */
+    async findOne(filter, options) {
+        return await this.mongoCollection.findOne(filter, options);
+    }
+    /**
+     * Inserts multiple documents into the collection.
+     * @param docs - The documents to insert
+     * @param options - The options for the insert operation
+     * @returns A promise that resolves to the result of the insert operation
+     */
+    async insertMany(docs, { options, unsafe = false } = {}) {
+        const newDocuments = [];
+        const usedIds = new Set((await this.mongoCollection.find({ _id: { $in: docs.map(doc => doc._id).filter(Boolean) } }, { projection: { _id: 1 } }).toArray()).map(doc => doc._id));
+        for (const doc of docs) {
+            let id = doc._id;
+            if (!id || usedIds.has(id)) {
+                do {
+                    id = generateRandomString({ length: 5 });
+                } while (usedIds.has(id));
+            }
+            usedIds.add(id);
+            newDocuments.push({
+                ...doc,
+                _id: id,
+                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',
+            });
+        }
+        const parsedDocuments = [];
+        for (const newDocument of newDocuments) {
+            let parsedDocument = newDocument;
+            if (!unsafe) {
+                try {
+                    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);
+                }
+                catch (error) {
+                    throw new HttpException(HTTP_STATUS.BAD_REQUEST, error.message, { cause: error });
+                }
+            }
+            parsedDocuments.push(parsedDocument);
+        }
+        return await this.mongoCollection.insertMany(parsedDocuments, options);
+    }
+    /**
+     * 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.
+     */
+    async insertOne(doc, { options, unsafe = false } = {}) {
+        // Setup a copy of the document to be inserted with defaults
+        let parsedDocument = {
+            ...doc,
+            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',
+        };
+        // Validate the document against the create schema if unsafe is false
+        if (!unsafe) {
+            try {
+                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(parsedDocument);
+            }
+            catch (error) {
+                throw new HttpException(HTTP_STATUS.BAD_REQUEST, error.message, { cause: error });
+            }
+        }
+        // Add the ID if it is missing from the original document
+        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);
+        // Check if the insert operation was acknowledged
+        if (!result.acknowledged)
+            throw new HttpException(HTTP_STATUS.INTERNAL_SERVER_ERROR, 'Failed to insert document', result);
+        // If returnResult is false, return the insert result directly
+        if (options?.returnResult === false)
+            return result;
+        // Otherwise, fetch and return the inserted document
+        const insertedDoc = await this.findOne({ _id: { $eq: result.insertedId } }, options);
+        if (!insertedDoc)
+            throw new HttpException(HTTP_STATUS.INTERNAL_SERVER_ERROR, 'Failed to find inserted document', result);
+        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 an 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;
+    }
+    /**
+     * Toggle 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 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) {
+        // 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(HTTP_STATUS.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.
+     * @param filter - The filter criteria to match documents to update
+     * @param updateFields - The fields to update in the documents
+     * @param options - The options for the update operation
+     * @returns A promise that resolves to the result of the update operation
+     */
+    async updateMany(filter, updateFields, options) {
+        let parsedUpdateFields = {
+            ...updateFields,
+            updated_at: updateFields.updated_at || Dates.now('utc').unix_timestamp,
+            updated_by: updateFields.updated_by || 'system',
+        };
+        if (this.updateSchema) {
+            try {
+                parsedUpdateFields = this.updateSchema.parse(updateFields);
+            }
+            catch (error) {
+                throw new HttpException(HTTP_STATUS.BAD_REQUEST, error.message, { cause: error });
+            }
+        }
+        const result = await this.mongoCollection.updateMany(filter, { $set: { ...parsedUpdateFields, updated_at: Dates.now('utc').unix_timestamp } }, options);
+        if (options?.returnResults === false)
+            return result;
+        if (!result.acknowledged) {
+            throw new HttpException(HTTP_STATUS.INTERNAL_SERVER_ERROR, 'Failed to update documents', result);
+        }
+        const updatedDocuments = await this.findMany(filter, options);
+        if (!updatedDocuments) {
+            throw new HttpException(HTTP_STATUS.INTERNAL_SERVER_ERROR, 'Failed to find updated documents', result);
+        }
+        return updatedDocuments;
+    }
+    /**
+     * 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.
+     */
+    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(HTTP_STATUS.FORBIDDEN, 'Document is locked and cannot be updated');
+        }
+        // Perform the update operation
+        let parsedUpdateFields = updateFields;
+        if (this.updateSchema) {
+            try {
+                parsedUpdateFields = this.updateSchema.parse(updateFields);
+            }
+            catch (error) {
+                throw new HttpException(HTTP_STATUS.BAD_REQUEST, error.message, { cause: error });
+            }
+        }
+        const result = await this.mongoCollection.updateOne(filter, { $set: { ...parsedUpdateFields, updated_at: Dates.now('utc').unix_timestamp } }, options);
+        if (options?.returnResult === false)
+            return result;
+        if (!result.acknowledged) {
+            throw new HttpException(HTTP_STATUS.INTERNAL_SERVER_ERROR, 'Failed to update documents', result);
+        }
+        const updatedDocument = await this.findOne(filter, options);
+        if (!updatedDocument)
+            throw new HttpException(HTTP_STATUS.INTERNAL_SERVER_ERROR, 'Failed to find updated document', result);
+        return updatedDocument;
+    }
+    /**
+     * 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.
+     */
+    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.
+     */
+    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(HTTP_STATUS.FORBIDDEN, 'Document is locked and cannot be deleted');
+        }
+        // Perform the delete operation
+        const result = await this.deleteOne({ _id: { $eq: id } }, options);
+        // Check if the delete operation was acknowledged
+        if (!result.acknowledged)
+            throw new HttpException(HTTP_STATUS.INTERNAL_SERVER_ERROR, 'Failed to delete documents', result);
+        // Return the result of the delete operation
+        return result;
+    }
+    /**
+     * Deletes multiple documents matching the filter criteria.
+     * @param filter The filter criteria to match documents to delete.
+     * @returns A promise that resolves to the result of the delete many operation.
+     */
+    async deleteMany(filter) {
+        const result = await this.mongoCollection.deleteMany(filter);
+        if (!result.acknowledged)
+            throw new HttpException(HTTP_STATUS.INTERNAL_SERVER_ERROR, 'Failed to delete documents', result);
+        return result;
+    }
+    /**
+     * Deletes a single document matching the filter criteria.
+     * @param filter The filter criteria to match the document to delete.
+     * @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(HTTP_STATUS.FORBIDDEN, 'Document is locked and cannot be deleted');
+        }
+        // Perform the delete operation
+        const result = await this.mongoCollection.deleteOne(filter, options);
+        if (!result.acknowledged)
+            throw new HttpException(HTTP_STATUS.INTERNAL_SERVER_ERROR, 'Failed to delete document', result);
+        return result;
+    }
+    async aggregate(pipeline, options) {
+        // 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();
+    }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "@tmlmobilidade/go-interfaces-godb",
+	"version": "20260717.1316.58",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@tmlmobilidade/consts": "*",
+		"@tmlmobilidade/dates": "*",
+		"@tmlmobilidade/go-clients-mongo": "*",
+		"@tmlmobilidade/go-types-shared": "*",
+		"@tmlmobilidade/logger": "*",
+		"@tmlmobilidade/strings": "*",
+		"@tmlmobilidade/types": "*",
+		"@tmlmobilidade/utils": "*",
+		"bcryptjs": "3.0.3",
+		"luxon": "3.7.2",
+		"zod": "3.25.76"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/tsconfig": "*",
+		"@types/luxon": "3.7.2",
+		"@types/node": "26.1.1",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}