import { IDatabaseConfiguration, IDatabaseInternalStructure, IDatabaseRequestsLatencyData } from '../types/Database'; import { QuickMongoClient } from './QuickMongoClient'; import { AutocompletableString, ExtractFromArray, FirstObjectKey, If, IsObject, Maybe, ObjectPath, ObjectValue, QueryFunction, RestOrArray } from '../types/utils'; /** * Quick Mongo database class. * * Type parameters: * * - `K` (`string`) - The type of The key to access the target in database by. * - `V` (`any`) - The type of the values in the database. * * @template K (`string`) - The type of The key to access the target in database by. * @template V (`any`) - The type of the values in the database. * * @example * const { QuickMongoClient, QuickMongo } = require('quick-mongo-super') * * // Create a normal Quick Mongo client. * const quickMongoClient = new QuickMongoClient(connectionURI) * * // You can also specify the initial data that will be put * // on successful connection in every database if it's empty. * const quickMongoClient = new QuickMongoClient(connectionURI, { * somethingToSetInDatabase: 'something' * }) * * // Initialize the database. * const mongo = new QuickMongo(quickMongoClient, { * name: 'databaseName', * collectionName: 'collectionName' // optional * }) */ export declare class QuickMongo { /** * Cache Manager. * @type {CacheManager>} * @private */ private _cache; /** * Quick Mongo client the database instance is attached to. * @type {QuickMongoClient} * @private */ private _client; /** * Internal Mongoose model for the module to work with. * @type {Model>} * @private */ private _model; /** * Database name. * @type {string} */ name: string; /** * Collection name. * @type {string} */ collectionName: string; readonly [Symbol.toStringTag] = "QuickMongoDatabase"; /** * Creates a new instance of Quick Mongo database. * * Type parameters: * * - `K` (`string`) - The type of The key to access the target in database by. * - `V` (`any`) - The type of the values in the database. * * @param {QuickMongoClient} client Quick Mongo client to get attached to. * @param {IDatabaseConfiguration} databaseConfiguration Database configuration object. * * @template K (`string`) - The type of The key to access the target in database by. * @template V (`any`) - The type of the values in the database. * * @example * const { QuickMongoClient, QuickMongo } = require('quick-mongo-super') * * // Create a normal Quick Mongo client. * const quickMongoClient = new QuickMongoClient(connectionURI) * * // Initialize the normal database: * const mongo = new QuickMongo(quickMongoClient, { * name: 'databaseName', * collectionName: 'collectionName' // (optional) * }) * * // Alternatively, you can also specify the initial data that will be inserted * // on successful connection in every database if it's empty: * const quickMongoClientWithInitialData = new QuickMongoClient(connectionURI, { * somethingToSetInDatabase: 'something' * }) * * // Initialize the database with initial data being set: * const mongoWithInitialData = new QuickMongo(quickMongoClientWithInitialData, { * name: 'databaseName', * collectionName: 'collectionName' // (optional) * }) * * // Initial data will be available as soon as the database instance was created * // and initialized from the QuickMongoClient with the initial data being set, and the * // connection to your cluster is established: * console.log(mongoWithInitialData.all()) // -> { somethingToSetInDatabase: 'something' } */ constructor(client: QuickMongoClient, databaseConfiguration: IDatabaseConfiguration); /** * Determines the number of keys in the root of the database. Equivalent to `QuickMongo.keys().length`. * @type {number} */ get size(): number; /** * Sends a read, write and delete requests to the remote database and returns the request latencies in milliseconds. * @returns {Promise} Database requests latencies object. * * @example * const ping = await quickMongo.ping() * console.log(ping) // -> { readLatency: 123, writeLatency: 124, deleteLatency: 125 } */ ping(): Promise; /** * This method works the same way as `Array.find()`. * * Iterates over root database values, finds the element in database values array * by specified condition in the callback function and returns the result. * * @param {QueryFunction} queryFunction * A function that accepts up to three arguments. * The `find` method calls the `queryFunction` once for each element in database object values array. * * @returns {Maybe} The search */ find(queryFunction: QueryFunction): Maybe; /** * This method works the same way as `Array.map()`. * * Calls a defined callback function on each element of an array, * and returns an array that contains the results. * * @param {QueryFunction} queryFunction * A function that accepts up to three arguments. * The `map` method calls the `queryFunction` once for each element in database object values array. * * @returns {TReturnType[]} */ map(queryFunction: QueryFunction): TReturnType[]; /** * This method works the same way as `Array.findIndex()`. * * Iterates over root database values, finds the index of the element in database values array * by specified condition in the callback function and returns the result. * * @param {QueryFunction} queryFunction * A function that accepts up to three arguments. * The `findIndex` method calls the `queryFunction` once for each element in database object values array. * * @returns {number} */ findIndex(queryFunction: QueryFunction): number; /** * This method works the same way as `Array.filter()`. * * Iterates over root database values, finds all the element that match the * specified condition in the callback function and returns the result. * * @param {QueryFunction} queryFunction * A function that accepts up to three arguments. * The `filter` method calls the `queryFunction` once for each element in database object values array. * * @returns {V[]} */ filter(queryFunction: QueryFunction): V[]; /** * This method works the same way as `Array.some()`. * * Iterates over root database values and checks if the * specified condition in the callback function returns `true` * for **any** of the elements of the database object values array. * * @param {QueryFunction} queryFunction * A function that accepts up to three arguments. * The `some` method calls the `queryFunction` once for each element in database object values array. * * @returns {boolean} */ some(queryFunction: QueryFunction): boolean; /** * This method works the same way as `Array.every()`. * * Iterates over root database values and checks if the * specified condition in the callback function returns `true` * for **all** of the elements of the database object values array. * * @param {QueryFunction} queryFunction * A function that accepts up to three arguments. * The `every` method calls the `queryFunction` once for each element in database object values array. * * @returns {boolean} */ every(queryFunction: QueryFunction): boolean; /** * Retrieves a value from database by a key. * * @param {AutocompletableString

} key The key to access the target in database by. * @returns {Maybe>} The value of the target in database. * * @example * const simpleValue = quickMongo.get('simpleValue') * console.log(simpleValue) // -> 123 * * const databaseObjectPropertyAccessed = quickMongo.get('youCanAlso.accessDatabaseObjectProperties.likeThat') * console.log(databaseObjectPropertyAccessed) // -> 'hello world!' * * // ^ Assuming that the initial database object for this example is: * // { * // simpleValue: 123, * // youCanAlso: { * // accessDatabaseObjectProperties: { * // likeThat: 'hello world!' * // } * // } * // } */ get

>>(key: AutocompletableString

): Maybe>; /** * Retrieves a value from database by a key via sending a **direct request** * to remote cluster, **omitting** the cache. * * @param {AutocompletableString

} key The key to access the target in database by. * @returns {Promise>>} The value of the target in database. * * @example * const simpleValue = await quickMongo.getFromDatabase('simpleValue') * console.log(simpleValue) // -> 123 * * const databaseObjectProperty = await quickMongo.getFromDatabase('youCanAlso.accessDatabaseObjectProperties.likeThat') * console.log(databaseObjectProperty) // -> 'hello world!' * * // ^ Assuming that the initial database object for this example is: * // { * // simpleValue: 123, * // youCanAlso: { * // accessDatabaseObjectProperties: { * // likeThat: 'hello world!' * // } * // } * // } */ getFromDatabase

>>(key: AutocompletableString

): Promise>>; /** * Retrieves a value from database by a key. * * - This method is an alias for {@link QuickMongo.get()} method. * * @param {AutocompletableString

} key The key to access the target in database by. * @returns {Maybe>} The value from database. * * @example * const simpleValue = quickMongo.fetch('simpleValue') * console.log(simpleValue) // -> 123 * * // You can use the dot notation to access the database object properties: * const playerInventory = quickMongo.fetch('player.inventory') * console.log(playerInventory) // -> [] * * // ^ Assuming that the initial database object for this example is: * // { * // simpleValue: 123, * // player: { * // inventory: [] * // } * // } */ fetch

>>(key: AutocompletableString

): Maybe>; /** * Determines if the data is stored in database. * @param {AutocompletableString

} key The key to access the target in database by. * @returns {boolean} Whether the data is stored in database. * * @example * const isSimpleValueInDatabase = quickMongo.has('simpleValue') * console.log(isSimpleValueInDatabase) // -> true * * const somethingElse = quickMongo.has('somethingElse') * console.log(somethingElse) // -> false * * // You can use the dot notation to check the database object properties: * const isObjectInDatabase = quickMongo.has('youCanAlso.accessObjectProperties.likeThat') * console.log(isObjectInDatabase) // -> true * * // ^ Assuming that the initial database object for this example is: * // { * // simpleValue: 123, * // player: { * // inventory: [] * // }, * // youCanAlso: { * // accessObjectProperties: { * // likeThat: 'hello world!' * // } * // } * // } */ has

>>(key: AutocompletableString

): boolean; /** * Writes the specified value into database under the specified key. * * @param {AutocompletableString

} key The key to write in the target. * @param {ObjectValue} value The value to write. * * @returns {Promise, FirstObjectKey

, V>>} * - If the `value` parameter's type is not an object (string, number, boolean, etc), then the specified * `value` parameter (type of `ObjectValue`) will be returned. * * - If an object is specified in the `value` parameter, then the object of the first key will be returned. * (type of `FirstObjectKey

` - first object key (e.g. in key `member.user.id`, the first key will be `member`)) * * @example * // Assuming that the initial database object for this example is empty. * * await quickMongo.set('something', 'hello from quick-mongo-super!') * const hello = quickMongo.get('something') * * console.log(hello) // -> 'hello from quick-mongo-super!' * * // You can use the dot notation to write data in objects: * const dotNotationSetResult = await quickMongo.set('thats.an.object', 123) * console.log(dotNotationSetResult) // -> 123 * * await quickMongo.set('player.inventory', []) * const inventory = quickMongo.get('player') * * console.log(inventory) // -> { inventory: [] } * * // Using objects as value will return the object of key `thats`: * await quickMongo.set('thats.an.object', { hello: 'world' }) // -> { an: { object: { hello: 'world' } } } * * // ^ After these manipulations, the database object will look like this: * // { * // "something": "hello from quick-mongo-super!", * // "player": { * // "inventory": [] * // }, * // "thats": { * // "an": { * // "object": { * // hello: 'world' * // } * // } * // } * // } */ set

>>(key: AutocompletableString

, value: ObjectValue): Promise, ObjectValue>, V>>; /** * Deletes the data from database by key. * @param {AutocompletableString

} key The key to access the target in database by. * @returns {Promise} Whether the deletition was successful. * * @example * const databaseBefore = quickMongo.all() * console.log(databaseBefore) // -> { prop1: 123, prop2: { prop3: 456, prop4: 789 } } * * await quickMongo.delete('prop1') // deleting `prop1` from the database * await quickMongo.delete('prop2.prop3') // deleting `prop3` property from `prop2` object in database * * const databaseAfter = quickMongo.all() * console.log(databaseAfter) // -> { prop2: { prop4: 789 } } * * // ^ Assuming that the initial database object for this example is: * // { * // prop1: 123, * // prop2: { * // prop3: 456, * // prop4: 789 * // } * // } */ delete

>>(key: AutocompletableString

): Promise; /** * Performs an arithmetical addition on a target number in database. * * [!!!] The type of target value must be a number. * * @param {AutocompletableString

} key The key to access the target in database by. * @param {number} numberToAdd The number to add to the target number in database. * @returns {Promise} Addition operation result. * * @example * const additionResult = await quickMongo.add('points', 5) * console.log(additionResult) // -> 10 (5 + 5 = 10) * * // Notice that we don't need to assign a value to unexistent properties in database * // before performing an addition since the initial target value is 0 and will be used * // as the value of the unexistent property: * const unexistentAdditionResult = await quickMongo.add('somethingElse', 3) * * console.log(unexistentAdditionResult) // -> 3 (0 + = 3) * // ^ the property didn't exist in database, that's why 0 is added to 3 * * // ^ Assuming that the initial database object for this example is: * // { * // points: 5 * // } */ add

>>(key: AutocompletableString

, numberToAdd: number): Promise; /** * Performs an arithmetical subtraction on a target number in database. * * [!!!] The type of target value must be a number. * * @param {AutocompletableString

} key The key to access the target in database by. * @param {number} numberToSubtract The number to subtract from the target number in database. * @returns {Promise} Subtraction operation result. * * @example * const subtractionResult = await quickMongo.subtract('points', 5) * console.log(subtractionResult) // -> 5 (10 - 5 = 5) * * // Notice that we don't need to assign a value to unexistent properties in database * // before performing a subtraction since the initial target value is 0 and will be used * // as the value of the unexistent property: * const unexistentSubtractionitionResult = await quickMongo.subtract('somethingElse', 3) * * console.log(unexistentSubtractionitionResult) // -> 3 (0 - 3 = -3) * // ^ the property didn't exist in database, so 3 is subtracted from 0 * * // ^ Assuming that the initial database object for this example is: * // { * // points: 10 * // } */ subtract

>>(key: AutocompletableString

, numberToSubtract: number): Promise; /** * Determines whether the specified target is an array. * * @param {AutocompletableString

} key The key to access the target in database by. * @returns {boolean} Whether the target is an array. * * @example * const isArray = quickMongo.isTargetArray('array') * console.log(isArray) // -> true * * const notArray = quickMongo.isTargetArray('notArray') * console.log(notArray) // -> false * * // ^ Assuming that the initial database object for this example is: * // { * // array: [], * // notArray: 123 * // } */ isTargetArray

>>(key: AutocompletableString

): boolean; /** * Determines whether the specified target is a number. * * @param {AutocompletableString

} key The key to access the target in database by. * @returns {boolean} Whether the target is a number. * * @example * const isNumber = quickMongo.isTargetNumber('number') * console.log(isNumber) // -> true * * const notNumber = quickMongo.isTargetNumber('notNumber') * console.log(notNumber) // -> false * * // ^ Assuming that the initial database object for this example is: * // { * // number: 123, * // notNumber: [] * // } */ isTargetNumber

>>(key: AutocompletableString

): boolean; /** * Pushes the specified value(s) into the target array in database. * * [!!!] The type of target value must be an array. * * @param {AutocompletableString

} key The key to access the target in database by. * @param {RestOrArray>>} values * The value(s) to be pushed into the target array in database. * * @returns {Promise>>>} Updated target array from database. * * @example * const membersPushResult = await quickMongo.push('members', 'William') * console.log(membersPushResult) // -> ['John', 'William'] * * // You can also pass in multiple values to push into the target array: * const currenciesPushResult = await quickMongo.push('currencies', 'Euro', 'Rupee') * console.log(currenciesPushResult) // -> ['Dollar', 'Euro', 'Rupee'] * * // ^ Assuming that the initial database object for this example is: * // { * // members: ['John'], * // currencies: ['Dollar'] * // } */ push

>>(key: AutocompletableString

, ...values: RestOrArray>>): Promise>[]>; /** * Replaces the specified element in target array with the specified value in the target array in database. * * [!!!] The type of target value must be an array. * * @param {AutocompletableString

} key The key to access the target in database by. * @param {number} targetArrayElementIndex The index to find the element in target array by. * @param {V} value The value to be pushed into the target array in database. * @returns {Promise>>>} Updated target array from database. * * @example * const membersPullResult = await quickMongo.pull('members', 1, 'James') * console.log(membersPullResult) // -> ['John', 'James', 'Tom'] * * // ^ Assuming that the initial database object for this example is: * // { * // members: ['John', 'William', 'Tom'] * // } */ pull

>>(key: AutocompletableString

, targetArrayElementIndex: number, value: ObjectValue): Promise>[]>; /** * Removes the specified element(s) from the target array in database. * * [!!!] The type of target value must be an array. * * @param {AutocompletableString

} key The key to access the target in database by. * @param {RestOrArray>} targetArrayElementIndexes * The index(es) to find the element(s) in target array by. * * @returns {Promise>>>} Updated target array from database. * * @example * const membersPopResult = await quickMongo.pop('members', 1) * console.log(membersPopResult) // -> ['John', 'Tom'] * * const currenciesPopResult = await quickMongo.pop('currencies', 1) * console.log(currenciesPopResult) // -> ['Dollar', 'Euro'] * * // ^ Assuming that the initial database object for this example is: * // { * // members: ['John', 'William', 'Tom'], * // currencies: ['Dollar', 'Rupee', 'Euro'] * // } */ pop

>>(key: AutocompletableString

, ...targetArrayElementIndexes: RestOrArray>): Promise>[]>; /** * Returns an array of object keys by specified database key. * * If `key` parameter is omitted, then an array of object keys of database root object will be returned. * * Type parameters: * * - `TKeys` (`TupleOrArray`, defaults to `K[]`) - The tuple or array of a type of keys to be returned. * * @param {P} [key] The key to access the target in database by. * @returns {Array>} Database object keys array. * * @example * const prop3Keys = quickMongo.keys('prop3') * console.log(prop3Keys) // -> ['prop4', 'prop5'] * * const prop5Keys = quickMongo.keys('prop3.prop5') * console.log(prop5Keys) // -> ['prop6'] * * const prop6Keys = quickMongo.keys('prop3.prop5.prop6') * console.log(prop6Keys) * // ^ -> [] (empty since the value in `prop6`, 111, is a primitive value and not an actual object) * * const databaseKeys = quickMongo.keys() * // in this example, `key` parameter is omitted - object keys of database object are being returned * * console.log(databaseKeys) // -> ['prop1', 'prop2', 'prop3'] * * const unexistentKeys = quickMongo.keys('somethingElse') * console.log(unexistentKeys) // -> [] (empty since the key `somethingElse` does not exist in database) * * // ^ Assuming that the initial database object for this example is: * // { * // prop1: 123, * // prop2: 456, * // prop3: { prop4: 789, prop5: { prop6: 111 } } * // } */ keys

>>(key?: P): ObjectPath

[]; /** * Returns an array of object values by specified database key. * * If `key` parameter is omitted, then an array of object values of database root object will be returned. * * @param {P} [key] The key to access the target in database by. * @returns {Array>} Database object values array. * * @example * const prop3Values = quickMongo.values('prop3') * console.log(prop3Values) // -> [789, { prop6: 111 }] * * const prop5Values = quickMongo.values('prop3.prop5') * console.log(prop5Values) // -> [] * * const prop6Values = quickMongo.values('prop3.prop5.prop6') * console.log(prop6Values) * // ^ -> [] (empty since the value in `prop6`, 111, is a primitive value and not an actual object) * * const databaseValues = quickMongo.values() * // in this example, `key` parameter is omitted - object values of database object are being returned * * console.log(databaseValues) // -> [123, 456, { prop4: 789, prop5: { prop6: 111 } }] * * const unexistentValues = quickMongo.values('somethingElse') * console.log(unexistentValues) // -> [] (empty since the key `somethingElse` does not exist in database) * * // ^ Assuming that the initial database object for this example is: * // { * // prop1: 123, * // prop2: 456, * // prop3: { prop4: 789, prop5: { prop6: 111 } } * // } */ values

>>(key?: P): ObjectValue[]; /** * Picks a random element of array in database and returns the picked array element. * * [!!!] The type of target value must be an array. * * @param {AutocompletableString

} key The key to access the target in database by. * @returns {Maybe>} The randomly picked element in the database array. * * @example * const array = quickMongo.get('exampleArray') // assuming that the array is ['example1', 'example2', 'example3'] * console.log(array) // -> ['example1', 'example2', 'example3'] * * const randomArrayElement = quickMongo.random('exampleArray') * console.log(randomArrayElement) // -> randomly picked array element: either 'example1', 'example2', or 'example3' */ random

>>(key: AutocompletableString

): Maybe>; /** * Deletes everything from the database. * @returns {Promise} `true` if cleared successfully, `false` otherwise. * * @example * await quickMongo.clear() // this will delete all the data from the database */ clear(): Promise; /** * Deletes everything from the database. * * - This method is an alias for {@link QuickMongo.clear()} method. * @returns {Promise} `true` if cleared successfully, `false` otherwise. * * @example * await quickMongo.deleteAll() // this will delete all the data from the database */ deleteAll(): Promise; /** * Gets all the database contents from the cache. * * Type parameters: * * - `T` (`object`, defaults to `Record`) - The type of object of all the database object to be returned. * * @returns {T} Cached database contents. * * @template T (object, defaults to `Record`) - * The type of object of all the database object to be returned. * * @example * const database = quickMongo.all() * console.log(database) // -> { ... (the object of all the data stored in database) } */ all = Record>(): T; /** * Loads the database into cache. * * It's **not required** to run this method on starting or after any database operations - * cache management is performed automatically. * * @returns {Promise} * * @example * await quickMongo.loadCache() // this will download all the database contents into the cache */ loadCache(): Promise; /** * Makes a database request and fetches the raw database content - the data as it is * stored in the internal [__KEY]-[__VALUE] storage format that was made * to achieve better data accessibility across the module. * * Type parameters: * * - `TInternalDataValue` (`any`, defaults to `V`) - The type of `__VALUE` property in each raw data object. * * @returns {Promise>>} * Raw database content - the data as it is stored in internal [__KEY]-[__VALUE] storage format that was made * to achieve better data accessibility across the module. * * @template TInternalDataValue (any, defaults to `V`) - The type of `__VALUE` property in each raw data object. * * @example * const rawData = await quickMongo.raw() * console.log(rawData) // -> [{_id: '6534ee98408514005215ad2d', __KEY: 'something', __VALUE: 'something', __v: 0}, ...] */ raw(): Promise[]>; /** * Makes a direct request to the remote cluster and fetches all its contents. * * Type parameters: * * - `TValue` (`any`, defaults to `V`) - The type of object of all the database object to be returned. * * @template TValue (`object`) - The type of object of all the database object to be returned. * @returns {Promise>} Fetched database contents. * * @example * const allDatabase = quickMongo.allFromDatabase() * console.log(allDatabase) // -> { ... (the object of all the data stored in database) } */ allFromDatabase(): Promise>; }