@valkyriestudios/mongo/index.d.ts

MongoDB Adapter Library

import { Query } from './Query';
import { Db, type CreateIndexesOptions, type Document, type AuthMechanismProperties, type IndexDirection, type ClientSession, type TransactionOptions } from 'mongodb';
import { type Protocol, type ReadPreference, LogLevel, type LogFn } from './Types';
type MongoHostFullOptions = {
    debug: boolean;
    debug_levels: LogLevel[];
    pool_size: number;
    /** Minimum pool size (defaults to 1) */
    min_pool_size: number;
    host: string;
    user: string;
    pass: string;
    db: string;
    auth_db: string;
    replset: string | boolean;
    protocol: Protocol;
    read_preference: ReadPreference;
    retry_reads: boolean;
    retry_writes: boolean;
    connect_timeout_ms: number;
    socket_timeout_ms: number;
    server_selection_timeout_ms: number;
    max_idle_time_ms: number;
    app_name?: string;
};
type MongoUriFullOptions = {
    debug: boolean;
    debug_levels: LogLevel[];
    pool_size: number;
    /** Minimum pool size (defaults to 1) */
    min_pool_size: number;
    uri: string;
    db: string;
    read_preference: ReadPreference;
    retry_reads: boolean;
    retry_writes: boolean;
    connect_timeout_ms: number;
    socket_timeout_ms: number;
    server_selection_timeout_ms: number;
    max_idle_time_ms: number;
    auth_mechanism_properties?: AuthMechanismProperties;
    app_name?: string;
};
type MongoHostOptions = Partial<MongoHostFullOptions> & Required<Pick<MongoHostFullOptions, 'user' | 'pass' | 'db'>> & {
    logger?: LogFn;
};
type MongoUriOptions = Partial<MongoUriFullOptions> & Required<Pick<MongoUriFullOptions, 'uri'>> & {
    logger?: LogFn;
};
export type MongoOptions = MongoHostOptions | MongoUriOptions;
type CollectionIndexStructure = {
    name: string;
    spec: {
        [key: string]: 1 | -1;
    };
    options?: CreateIndexesOptions;
};
type CollectionStructure = {
    name: string;
    idx?: CollectionIndexStructure[];
};
declare class Mongo {
    #private;
    constructor(connection_opts: MongoOptions);
    /**
     * Returns a hashed identifier for the Mongo instance comprised of several configuration options.
     *
     * @returns {string}
     */
    get uid(): string;
    /**
     * Getter which returns the configured log function
     */
    get log(): LogFn;
    /**
     * Whether or not the instance is connected
     *
     * @returns {boolean}
     */
    get isConnected(): boolean;
    /**
     * Whether or not debug is enabled
     *
     * @returns {boolean}
     */
    get isDebugEnabled(): boolean;
    /**
     * Bootstrap mongo, this does several things:
     * 1) Test whether or not we can connect to the database
     * 2) (optional) Ensures structural integrity through automated collection/index creation
     *
     * @returns {Promise<void>}
     * @throws {Error} If connectivity check fails, structure is invalid or structure creation fails
     */
    bootstrap(structure?: CollectionStructure[]): Promise<void>;
    /**
     * Establish connection to mongodb using the instance configuration.
     * Take Note: this will not establish multiple connections if a client pool already exists
     *
     * @returns {Promise<Db>} Database instance
     * @throws {Error} When failing to establish a connection
     */
    connect(): Promise<Db>;
    /**
     * Verify whether or not a collection exists on the database
     *
     * @param {string} collection - Collection to verify exists
     * @returns {Promise<boolean>} Whether or not the collection exists
     * @throws {Error} When invalid options are passed or we fail to connect
     */
    hasCollection(collection: string): Promise<boolean>;
    /**
     * Create a collection on the database
     *
     * @param {string} collection - Collection to create
     * @returns {Promise<boolean>} Whether or not the collection was created
     * @throws {Error} When invalid options are passed or we fail to connect
     */
    createCollection(collection: string): Promise<boolean>;
    /**
     * Drop a collection on the database
     *
     * @param {string} collection - Collection to drop
     * @returns {Promise<boolean>} Whether or not the collection was dropped
     * @throws {Error} When invalid options are passed or we fail to connect
     */
    dropCollection(collection: string): Promise<boolean>;
    /**
     * Verify whether or not an index exists for a particular collection on the database
     *
     * @param {string} collection - Collection to verify on
     * @param {string} name - Name of the index to verify exists
     * @returns {Promise<boolean>} Whether or not the index exists on the collection
     * @throws {Error} When invalid options are passed or we fail to connect
     */
    hasIndex(collection: string, name: string): Promise<boolean>;
    /**
     * Create an index on a collection on the database
     *
     * @param {string} collection - Collection to create the index for
     * @param {string} name - Name of the index to be created
     * @param {{[key:string]:1|-1}} spec - Index key specification
     * @param {CreateIndexesOptions} options - (optional) Index options
     * @returns {Promise<boolean>} Whether or not the operation was successful
     * @throws {Error} When invalid options are passed or we fail to connect
     */
    createIndex(collection: string, name: string, spec: {
        [key: string]: IndexDirection;
    }, options?: CreateIndexesOptions): Promise<boolean>;
    /**
     * Drop an index on a collection on the database
     *
     * @param {string} collection - Collection to drop the index for
     * @param {string} name - Name of the index to drop
     * @returns {Promise<boolean>} Whether or not the operation was successful
     * @throws {Error} When invalid options are passed or we fail to connect
     */
    dropIndex(collection: string, name: string): Promise<boolean>;
    /**
     * Get a query instance for a specific collection
     *
     * @param {string} collection - Collection to query from
     * @returns {Promise<Query>} Instance of query
     * @throws {Error} When invalid options are passed
     */
    query<T extends Document>(collection: string): Query<T>;
    /**
     * Aggregate query handler - Compatible with ValkyrieStudios/Beam
     *
     * @param {string} collection - Collection to query from
     * @param {{[key:string]:any}[]} pipeline - Aggregation pipeline to run]
     * @returns {Promise<Document[]>}
     * @throws {Error} When invalid options are passed
     */
    aggregate<T = Document>(collection: string, pipeline: Document[]): Promise<T[]>;
    /**
     * Run a function within a transaction
     */
    withTransaction<T>(fn: (session: ClientSession) => Promise<T>, options?: TransactionOptions): Promise<T>;
    /**
     * Close the client pool
     *
     * @returns {Promise<void>} Resolves when connection is successfully terminated
     * @throws {Error} When failing to terminate client pool
     */
    close(): Promise<void>;
}
export { Mongo, Mongo as default };