@tmlmobilidade/go-interfaces-rawdb 20260717.1316.58

package/dist/databases/raw.d.ts

@@ -0,0 +1,11 @@
+import type { MongoClient } from '@tmlmobilidade/go-clients-mongo';
+import type { RawVehicleEvent } from '@tmlmobilidade/types';
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { RawApexTransaction } from '@tmlmobilidade/go-types-apex';
+export declare class RawDatabase {
+    readonly rawApexTransactions: MongoInterfaceTemplate<RawApexTransaction, RawApexTransaction>;
+    readonly rawVehicleEvents: MongoInterfaceTemplate<RawVehicleEvent, RawVehicleEvent>;
+    private readonly database;
+    private readonly databaseName;
+    constructor(instance: MongoClient);
+}

package/dist/databases/raw.js

@@ -0,0 +1,22 @@
+/* * */
+import { MongoInterfaceTemplate } from '../interface.template.js';
+import { RawApexTransactionSchema } from '@tmlmobilidade/go-types-apex';
+import { RawVehicleEventSchema } from '@tmlmobilidade/types';
+/* * */
+export class RawDatabase {
+    //
+    //
+    // Collections
+    rawApexTransactions;
+    rawVehicleEvents;
+    //
+    database;
+    databaseName = 'raw';
+    constructor(instance) {
+        // Create the database instance
+        this.database = instance.db(this.databaseName);
+        // Create collection interfaces
+        this.rawApexTransactions = new MongoInterfaceTemplate('raw_apex_transactions', this.database, RawApexTransactionSchema);
+        this.rawVehicleEvents = new MongoInterfaceTemplate('raw_vehicle_events', this.database, RawVehicleEventSchema);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { RawDatabase } from './databases/raw.js';
+declare class RawDBClass {
+    private static _instance;
+    private readonly mongoClient;
+    readonly raw: RawDatabase;
+    /**
+     * Establishes a connection to the Mongo database and initializes the collection.
+     * @throws Error if required RAW_DB_* environment variables are missing or if the connection fails.
+     */
+    static getInstance(): Promise<RawDBClass>;
+    private constructor();
+}
+export declare const rawDb: RawDBClass;
+export {};

package/dist/index.js

@@ -0,0 +1,33 @@
+/* * */
+import { MongoDatabaseClient } from '@tmlmobilidade/go-clients-mongo';
+import { asyncSingletonProxy } from '@tmlmobilidade/utils';
+import { RawDatabase } from './databases/raw.js';
+/* * */
+class RawDBClass {
+    //
+    //
+    //
+    static _instance;
+    mongoClient;
+    //
+    // Databases
+    raw;
+    /**
+     * Establishes a connection to the Mongo database and initializes the collection.
+     * @throws Error if required RAW_DB_* environment variables are missing or if the connection fails.
+     */
+    static async getInstance() {
+        if (!RawDBClass._instance) {
+            const mongoClient = await MongoDatabaseClient.getClient({ prefix: 'RAWDB' });
+            RawDBClass._instance = new RawDBClass(mongoClient);
+        }
+        return RawDBClass._instance;
+    }
+    //
+    // Constructor
+    constructor(mongoClient) {
+        this.mongoClient = mongoClient;
+        this.raw = new RawDatabase(this.mongoClient);
+    }
+}
+export const rawDb = asyncSingletonProxy(RawDBClass);

package/dist/interface.template.d.ts

@@ -0,0 +1,99 @@
+import { AnyBulkWriteOperation, BulkWriteOptions, BulkWriteResult, Collection, Db, Document, Filter, FindOptions, InsertOneOptions, SimplifiedMongoIndex, WithId } from '@tmlmobilidade/go-clients-mongo';
+import { z } from 'zod';
+export declare class MongoInterfaceTemplate<T extends Document, TCreate> {
+    private readonly collectionName;
+    private readonly createSchema;
+    private readonly database;
+    private readonly indexDescription;
+    private readonly collection;
+    private initPromise;
+    /**
+     * @param collectionName - The name of the collection to create the interface for.
+     * @param database - The database to create the interface for.
+     * @param createSchema - The schema to use for creating documents.
+     * @param indexDescription - The index description to use for the collection.
+     */
+    constructor(collectionName: string, database: Db, createSchema: z.ZodSchema, indexDescription?: false | SimplifiedMongoIndex<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>;
+    /**
+     * Finds all distinct values for a key in the collection.
+     * @param key The key to find distinct values for.
+     * @param filter Optional filter criteria to match documents before extracting distinct values.
+     * @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<import("mongodb").Flatten<WithId<T>[Key]>[]>;
+    /**
+     * 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 single document matching the filter criteria.
+     * @param filter The filter criteria to match the document.
+     * @param options Optional options.
+     * @returns A promise that resolves to the matching document or null if not found.
+     */
+    findOne(filter: Filter<T>, options?: FindOptions): Promise<T | null>;
+    /**
+     * Provides access to the MongoDB collection instance,
+     * initializing it if it has not already been created.
+     * @returns A promise that resolves to the MongoDB collection instance.
+     * @warning Use with caution: direct access to the collection allows for executing arbitrary queries.
+     */
+    getCollection(): Promise<Collection<T>>;
+    /**
+     * This method allows for performing multiple write operations
+     * in a single request, which can improve performance.
+     * The operations can include inserts, updates, deletes, and replacements.
+     * @param operations An array of bulk write operations to execute on the collection.
+     * @param options The options for the bulk write operation.
+     * @returns A promise that resolves to the result of the bulk write operation.
+     * @warning This method does not perform schema validation on the operations.
+     * It is the responsibility of the caller to ensure that the operations are valid and conform to the expected schemas.
+     */
+    bulkWrite(operations: AnyBulkWriteOperation<T>[], options?: BulkWriteOptions): Promise<BulkWriteResult>;
+    /**
+     * Inserts multiple documents into the collection after validating them against the create schema.
+     * @param data An array of documents to insert, conforming to the TCreate type.
+     * @param options Optional insert options to configure the behavior of the insert operation.
+     * @returns A promise that resolves to the result of the insertMany operation.
+     */
+    insertMany(data: TCreate[], options?: BulkWriteOptions): Promise<import("mongodb").InsertManyResult<T>>;
+    insertOne(data: TCreate, options?: InsertOneOptions): Promise<import("mongodb").InsertOneResult<T>>;
+    /**
+     * Initializes the MongoDB client and ensures that the specified database and collection exist.
+     * This method should be called before performing any operations on the database or collection.
+     * It handles the asynchronous setup process and logs any errors that occur during initialization.
+     * @throws Will throw an error if the client initialization or database/collection setup fails.
+     * @returns A promise that resolves when the initialization process is complete.
+     */
+    protected init(): Promise<void>;
+    private ensureInitialized;
+    /**
+     * Optional override for custom setup logic:
+     * indexes, materialized views, constraints, etc.
+     */
+    protected postInit(): Promise<void>;
+    /**
+     * Ensures that the specified collection exists in the MongoDB database,
+     * creating it if it does not already exist.
+     * @returns A promise that resolves when the collection is ensured to exist.
+     */
+    private createCollectionIfNotExists;
+    /**
+     * Ensures that the specified indexes exist in MongoDB, creating them if they do not already exist.
+     * This method performs input validation to prevent unsafe operations and logs the outcome of the operation.
+     * It constructs the necessary index creation queries based on the provided index descriptions and executes them using the client.
+     * @throws Will throw an error if any of the inputs are unsafe or if the index creation query fails.
+     * @returns A promise that resolves when the indexes are ensured to exist.
+     */
+    private syncIndexes;
+}

package/dist/interface.template.js

@@ -0,0 +1,210 @@
+/* * */
+import { isSameIndex, prepareMongoIndexOptions } from '@tmlmobilidade/go-clients-mongo';
+import { Logger } from '@tmlmobilidade/logger';
+/* * */
+export class MongoInterfaceTemplate {
+    //
+    collectionName;
+    createSchema;
+    database;
+    indexDescription;
+    //
+    collection;
+    initPromise = null;
+    /**
+     * @param collectionName - The name of the collection to create the interface for.
+     * @param database - The database to create the interface for.
+     * @param createSchema - The schema to use for creating documents.
+     * @param indexDescription - The index description to use for the collection.
+     */
+    constructor(collectionName, database, createSchema, indexDescription = []) {
+        this.collectionName = collectionName;
+        this.collection = database.collection(collectionName);
+        this.database = database;
+        this.createSchema = createSchema;
+        this.indexDescription = indexDescription;
+        this.initPromise = this.init().catch((error) => {
+            Logger.error({ error, message: `MONGODB [${this.collectionName}]: Error @ constructor(): ${error.message}` });
+            throw error;
+        });
+    }
+    /**
+     * 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) {
+        await this.ensureInitialized();
+        return await this.collection.countDocuments(filter);
+    }
+    /**
+     * Finds all distinct values for a key in the collection.
+     * @param key The key to find distinct values for.
+     * @param filter Optional filter criteria to match documents before extracting distinct values.
+     * @returns A promise that resolves to an array of distinct values for the given key.
+     */
+    async distinct(key, filter) {
+        await this.ensureInitialized();
+        return this.collection.distinct(key, filter);
+    }
+    /**
+     * 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) {
+        await this.ensureInitialized();
+        return await this.collection.find(filter, options).toArray();
+    }
+    /**
+     * Finds a single document matching the filter criteria.
+     * @param filter The filter criteria to match the document.
+     * @param options Optional options.
+     * @returns A promise that resolves to the matching document or null if not found.
+     */
+    async findOne(filter, options) {
+        await this.ensureInitialized();
+        return await this.collection.findOne(filter, options);
+    }
+    /**
+     * Provides access to the MongoDB collection instance,
+     * initializing it if it has not already been created.
+     * @returns A promise that resolves to the MongoDB collection instance.
+     * @warning Use with caution: direct access to the collection allows for executing arbitrary queries.
+     */
+    async getCollection() {
+        await this.ensureInitialized();
+        return this.collection;
+    }
+    /**
+     * This method allows for performing multiple write operations
+     * in a single request, which can improve performance.
+     * The operations can include inserts, updates, deletes, and replacements.
+     * @param operations An array of bulk write operations to execute on the collection.
+     * @param options The options for the bulk write operation.
+     * @returns A promise that resolves to the result of the bulk write operation.
+     * @warning This method does not perform schema validation on the operations.
+     * It is the responsibility of the caller to ensure that the operations are valid and conform to the expected schemas.
+     */
+    async bulkWrite(operations, options) {
+        await this.ensureInitialized();
+        return await this.collection.bulkWrite(operations, options);
+    }
+    /**
+     * Inserts multiple documents into the collection after validating them against the create schema.
+     * @param data An array of documents to insert, conforming to the TCreate type.
+     * @param options Optional insert options to configure the behavior of the insert operation.
+     * @returns A promise that resolves to the result of the insertMany operation.
+     */
+    async insertMany(data, options) {
+        await this.ensureInitialized();
+        // If no create schema is defined, throw an error.
+        if (!this.createSchema)
+            throw new Error(`No schema defined for insert operation for ${this.collectionName} collection.`);
+        // Validate each document against the create schema
+        const parsedDocuments = data.map((doc) => {
+            const parseResult = this.createSchema.safeParse(doc);
+            if (!parseResult.success)
+                throw new Error(`Document validation failed: ${parseResult.error.message}`);
+            return parseResult.data;
+        });
+        // Attempt to insert the documents into the collection
+        return await this.collection.insertMany(parsedDocuments, options);
+    }
+    async insertOne(data, options) {
+        await this.ensureInitialized();
+        // If no create schema is defined, throw an error.
+        if (!this.createSchema)
+            throw new Error(`No schema defined for insert operation for ${this.collectionName} collection.`);
+        // Validate the document against the create schema
+        const parseResult = this.createSchema.safeParse(data);
+        if (!parseResult.success)
+            throw new Error(`Document validation failed: ${parseResult.error.message}`);
+        // Attempt to insert the document into the collection
+        return await this.collection.insertOne(parseResult.data, options);
+    }
+    /**
+     * Initializes the MongoDB client and ensures that the specified database and collection exist.
+     * This method should be called before performing any operations on the database or collection.
+     * It handles the asynchronous setup process and logs any errors that occur during initialization.
+     * @throws Will throw an error if the client initialization or database/collection setup fails.
+     * @returns A promise that resolves when the initialization process is complete.
+     */
+    async init() {
+        // Ensure the collection exists and its indexes are in sync
+        // with the provided index description.
+        await this.createCollectionIfNotExists();
+        await this.syncIndexes();
+        // Call postInit for any additional setup logic defined in subclasses
+        await this.postInit();
+    }
+    async ensureInitialized() {
+        if (!this.initPromise)
+            this.initPromise = this.init();
+        await this.initPromise;
+    }
+    /**
+     * Optional override for custom setup logic:
+     * indexes, materialized views, constraints, etc.
+     */
+    async postInit() {
+        // no-op by default
+    }
+    /**
+     * Ensures that the specified collection exists in the MongoDB database,
+     * creating it if it does not already exist.
+     * @returns A promise that resolves when the collection is ensured to exist.
+     */
+    async createCollectionIfNotExists() {
+        const collections = await this.database.listCollections({ name: this.collectionName }).toArray();
+        if (collections.length)
+            return;
+        await this.database.createCollection(this.collectionName);
+        Logger.info({ message: `MONGODB [${this.collectionName}]: Collection created.` });
+    }
+    /**
+     * Ensures that the specified indexes exist in MongoDB, creating them if they do not already exist.
+     * This method performs input validation to prevent unsafe operations and logs the outcome of the operation.
+     * It constructs the necessary index creation queries based on the provided index descriptions and executes them using the client.
+     * @throws Will throw an error if any of the inputs are unsafe or if the index creation query fails.
+     * @returns A promise that resolves when the indexes are ensured to exist.
+     */
+    async syncIndexes() {
+        try {
+            if (this.indexDescription === false) {
+                Logger.info({ message: `MONGODB [${this.collectionName}]: Skipping index synchronization.` });
+                return;
+            }
+            // Start index synchronization process
+            Logger.info({ message: `MONGODB [${this.collectionName}]: Synchronizing indexes...` });
+            // Normalize already applied and new indexes
+            // and filter the default _id index.
+            const existingIndexes = await this.collection.indexes();
+            const filteredExisting = existingIndexes.filter(idx => JSON.stringify(idx.key) !== JSON.stringify({ _id: 1 }));
+            // Setup desired indexes based on indexDescription
+            const indexesToCreate = [];
+            // Find indexes to create
+            for (const desiredIdx of this.indexDescription) {
+                // For the list of desired indexes,
+                // check if they are present in the existing indexes.
+                const found = filteredExisting.some(existingIdx => isSameIndex(existingIdx, desiredIdx));
+                // If not, mark them for creation.
+                if (!found)
+                    indexesToCreate.push(desiredIdx);
+            }
+            // Create indexes
+            for (const idx of indexesToCreate) {
+                Logger.info({ message: `MONGODB [${this.collectionName}]: Creating index on keys ${JSON.stringify(idx.key)} with options ${JSON.stringify(prepareMongoIndexOptions(idx))}.` });
+                await this.collection.createIndex(idx.key, prepareMongoIndexOptions(idx));
+                Logger.success(`MONGODB [${this.collectionName}]: Created index on keys ${JSON.stringify(idx.key)}.`);
+            }
+            Logger.success(`MONGODB [${this.collectionName}]: Indexes synchronized.`);
+        }
+        catch (error) {
+            Logger.error({ error, message: `MONGODB [${this.collectionName}]: Error @ syncIndexes(): ${error.message}` });
+            throw error;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@tmlmobilidade/go-interfaces-rawdb",
+	"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-apex": "*",
+		"@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"
+	}
+}