@tmlmobilidade/interfaces
Version:
This package provides SDK-style connectors for interacting with databases (e.g., stops, plans, rides, alerts) and external providers (e.g., authentication, storage). It simplifies data access and integration across projects.
208 lines (207 loc) • 9.76 kB
TypeScript
import { type AggregationPipeline } from './aggregation-pipeline.js';
import { MongoConnector } from '@tmlmobilidade/mongo';
import { type UnixTimestamp } from '@tmlmobilidade/types';
import { type AggregateOptions, type AggregationCursor, type Collection, type DeleteOptions, type DeleteResult, type Document, type Filter, type FindOptions, Flatten, 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;
protected mongoCollection: Collection<T>;
protected mongoConnector: MongoConnector;
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.
*/
aggregate(pipeline: AggregationPipeline<T>, options?: AggregateOptions & {
returnResult?: true;
}): Promise<T[]>;
aggregate(pipeline: AggregationPipeline<T>, options: AggregateOptions & {
returnResult: false;
}): Promise<AggregationCursor<T>>;
/**
* Gets all documents in the collection.
* @returns A promise that resolves to an array of all documents
*/
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 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.
*/
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>;
/**
* Disconnects from the MongoDB database.
*/
disconnect(): Promise<void>;
/**
* 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 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 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) 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>>;
/**
* Gets the MongoDB collection instance.
* @returns The MongoDB collection instance
*/
getCollection(): Promise<Collection<T>>;
/**
* Gets the MongoDB connector instance.
* @returns The MongoDB connector instance
*/
getMongoConnector(): MongoConnector;
/**
* 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?: InsertOneOptions;
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>>;
protected abstract getCollectionIndexes(): IndexDescription[];
protected abstract getCollectionName(): string;
protected abstract getEnvName(): string;
}