feat: v2.2.0

changelog.md

@@ -6,6 +6,26 @@
 
 ## 🕘 | Changelog
 
+**v2.2.0**
+- Added `QuickMongo.values()` method; it works the same way as `QuickMongo.keys()`, but returns the object **values** instead of object **keys**.
+- Added **6** new **array-like** methods in `QuickMongo` class that simplify the **read** operations on **database object values**:
+  - `QuickMongo.find()`
+  - `QuickMongo.map()`
+  - `QuickMongo.findIndex()`
+  - `QuickMongo.filter()`
+  - `QuickMongo.some()`
+  - `QuickMongo.every()`
+- Fixed **caching** bug when **all** falsy values were represented as `null` in the cache.
+- Fixed any **falsy** result being represented as `null` in `QuickMongo.random()` method. 
+- Fully reworked some of the existing **unit tests**.
+- Added **references** to used **types/classes/interfaces/built-ins** in documentation.
+- Fixed **documentation** mismatches.
+- Fixed **JSDoc** mismatches.
+- Small documentation improvements.
+- Improved **descriptions** of some types.
+- Added **missing JSDoc** in `TypedObject` class and in `IDatabaseInternalStructure<T>` and `IDatabaseRequestsLatencyData` types.
+- Fixed typos.
+
 **v2.1.0**
 - Added a `size` property in `QuickMongo` class that determines the number of keys in the root of the database. Equivalent to `QuickMongo.keys().length`.
 - Added a `TKeys` type parameter in `QuickMongo.keys()` method that determines the type of returned keys.

docs/classes/QuickMongo.md

@@ -1,12 +1,33 @@
 # **`QuickMongo<K, V>` Class**
 
 # Intro
-This is the **full** documentation of all the database mathods of `QuickMongo` class.
+This is the **full** documentation of all the database methods of `QuickMongo` class.
 
 This includes all the methods, types, descriptions and **brief** examples on how each method could be used.
 
 You can see the **detailed** examples on usage of each method in both **JavaScript** and **TypeScript** [here](https://github.com/shadowplay1/quick-mongo-super/tree/main/examples).
 
+
+# References in this doc
+- Classes:
+  - [`QuickMongoClient<TInitialDatabaseData>`](../classes/QuickMongoClient.md)
+- Types:
+  - [`Maybe<T>`](../types/Maybe.md)
+  - [`If<T, IfTrue, IfFalse>`](../types/If.md)
+  - [`IsObject<T>`](../types/IsObject.md)
+  - [`RestOrArray<T>`](../types/RestOrArray.md)
+  - [`TupleOrArray<T>`](../types/TupleOrArray.md)
+  - [`ExtractFromArray<A>`](../types/ExtractFromArray.md)
+  - [`QueryFunction<T, R>`](../types/QueryFunction.md)
+- Interfaces:
+  - [`IDatabaseConfiguration`](../interfaces/IDatabaseConfiguration.md)
+  - [`IDatabaseInternalStructure<T>`](../interfaces/IDatabaseInternalStructure.md)
+- External Classes:
+  - [`Model<T>`](https://mongoosejs.com/docs/typescript.html)
+- Built-ins:
+  - [`Record<K, T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)
+
+
 ## Constructor
 ```ts
 new QuickMongo<K, V>(quickMongoClient: QuickMongoClient, databaseOptions?: IDatabaseConfiguration)
@@ -52,7 +73,7 @@ new QuickMongo<K, V>(quickMongoClient: QuickMongoClient, databaseOptions?: IData
   - `_model` (`Model<IDatabaseInternalStructure<any>>`): Internal Mongoose model to work with.
 
 
-# Events
+## Events
 *none*
 
 
@@ -121,7 +142,7 @@ Determines if the data is stored in database.
 Writes the specified value into database under the specified key.
 
 - **Type Parameters:**
-  - `TObjectReturnValue` (`any`, defaults to `any`): Type the return type fallbacks to if `TVa\lue` is an object.
+  - `TObjectReturnValue` (`any`, defaults to `any`): Type the return type fallbacks to if `TValue` is an object.
 
 - **Parameters:**
   - `key` (`string`): The key to write in the target.
@@ -238,6 +259,67 @@ Determines whether the specified target is a number.
 ```
 
 
+## `find(queryFunction: QueryFunction<V>): Maybe<V>`
+This method is the same 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.
+
+- **Parameters:**
+  - `queryFunction` (`QueryFunction<V>`): 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<V>`
+
+## `map<TReturnType>(queryFunction: QueryFunction<V, TReturnType>): TReturnType[]`
+This method is the same as `Array.map()`.
+
+Calls a defined callback function on each element of an array, and returns an array that contains the results.
+
+- **Parameters:**
+  - `queryFunction` (`QueryFunction<V, TReturnType>`): 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[]`
+
+## `findIndex(queryFunction: QueryFunction<V>): number`
+This method is the same 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.
+
+- **Parameters:**
+  - `queryFunction` (`QueryFunction<V>`): 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`
+
+## `filter(queryFunction: QueryFunction<V>): V[]`
+This method is the same 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.
+
+- **Parameters:**
+  - `queryFunction` (`QueryFunction<V>`): 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[]`
+
+## `some(queryFunction: QueryFunction<V>): boolean`
+This method is the same 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.
+
+- **Parameters:**
+  - `queryFunction` (`QueryFunction<V>`): 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`
+
+## `every(queryFunction: QueryFunction<V>): boolean`
+This method is the same 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.
+
+- **Parameters:**
+  - `queryFunction` (`QueryFunction<V>`): 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
+
+
 ## `push(key: K, ...values: RestOrArray<ExtractFromArray<V>>): Promise<ExtractFromArray<V>[]>`
 Pushes the specified value(s) into the target array in the database.
 
@@ -289,11 +371,11 @@ Removes the specified element(s) from the target array in the database.
   console.log(membersPopResult); // -> ['John', 'Tom']
 ```
 
-## `keys(key?: K): string[]`
+## `keys<TKeys extends TupleOrArray<string> = K[]>(key?: K): TKeys[]`
 Returns an array of object keys by specified database key.
 
 - **Type parameters:**
-  - `TKeys` (`TupleOrArray<string>`, defaults to `string[]`) - The tuple or array of a type of keys to be returned.
+  - `TValues` (`TupleOrArray<string>`, defaults to `K[]`) - The tuple or array of a type of keys to be returned.
 
 - **Parameters:**
   - `key` (`K`, **optional**): The key to access the target in database by. If omitted, returns object keys of the database root.
@@ -305,6 +387,22 @@ Returns an array of object keys by specified database key.
   console.log(prop3Keys); // -> ['prop4', 'prop5']
 ```
 
+## `values<TValues extends TupleOrArray<any> = V>(key?: K): TValues[]`
+Returns an array of object values by specified database key.
+
+- **Type parameters:**
+  - `TValues` (`TupleOrArray<any>`, defaults to `V[]`) - The tuple or array of a type of values to be returned.
+
+- **Parameters:**
+  - `key` (`K`, **optional**): The key to access the target in database by. If omitted, returns object values of the database root.
+
+- **Returns:** `V[]` - Database object values array.
+- **Example:**
+```ts
+  const prop3Values = quickMongo.va('prop3');
+  console.log(prop3Values); // -> [789, { prop6: 111 }]
+```
+
 
 ## `random(key: K): V`
 Picks a random element of array in the database and returns the picked array element.
@@ -386,16 +484,15 @@ Makes a database request and fetches the raw database content - the data as it i
   console.log(rawData) // -> [{_id: '6534ee98408514005215ad2d', __KEY: 'something', __VALUE: 'something', __v: 0}, ...]
 ```
 
-
-## `allFromDatabase<TValue extends Record<string, any> = V>(): Promise<TValue>`
+## `allFromDatabase<TValue = V>(): Promise<Record<string, TValue>>`
 Makes a direct request to the remote cluster and fetches all its contents.
 
 - **Type parameters:**
   - `TValue` (`object`): The type of object of all the database object to be returned.
 
 - **Returns:** `Promise<TValue>` - Fetched database contents.
 
-- **Eaxmple:**
+- **Example:**
 ```ts
   const allDatabase = quickMongo.allFromDatabase()
   console.log(allDatabase) // -> { ... (the object of all the data stored in database) }

docs/classes/QuickMongoClient.md

@@ -1,5 +1,10 @@
 # **`QuickMongoClient<TInitialDatabaseData>` Class**
 
+## References in this doc
+- Classes:
+  - [`QuickMongo<K, V>`](./QuickMongo.md)
+
+
 ## Constructor
 ```ts
 new QuickMongoClient<TInitialDatabaseData>(connectionURI: string, initialDatabaseData?: TInitialDatabaseData)

docs/classes/TypedObject.md

@@ -0,0 +1,45 @@
+# **`TypedObject` Class**
+
+# Intro
+Utility class for working with objects.
+
+Provides **static** methods for retrieving keys and values of an object.
+
+This class enhances type safety by providing better typings for object keys and values.
+
+
+# References in this doc
+- Types:
+  - [`TupleOrArray<T>`](../types/TupleOrArray.md)
+
+
+## Constructor
+*none*
+
+## Notice
+This class includes static methods to work with objects. It's **not intended** to create instances from this class.
+
+## Methods
+
+## `static keys<K extends TupleOrArray<string> = string[]>(obj: any): K `
+Returns the names of the enumerable string properties and methods of an object.
+
+- **Type Parameters:**
+  - `K` (`TupleOrArray<string>`, defaults to `string[]`): The type of the array containing the names of the enumerable string properties and methods.
+
+- **Parameters:**
+  - `obj` (`any`): Object that contains the properties and methods.
+
+- **Returns:** `K` - Array of names of the enumerable string properties and methods of the specified object.
+
+
+## `static values<V extends TupleOrArray<any> = any[]>(obj: any): V`
+Returns an array of values of the enumerable properties of an object.
+
+- **Type Parameters:**
+  - `TObjectReturnValue` (`TupleOrArray<any>`, defaults to `any[]`): The type of the array containing the values of the enumerable properties.
+
+- **Parameters:**
+  - `obj` (`any`): Object that contains the properties and methods.
+
+- **Returns:** `V` - Array of values of the enumerable properties of the specified object.

docs/events/QuickMongoClient/connect.md

@@ -5,7 +5,7 @@ Emits when the MongoDB connection is established successfully.
 - **Parameters:**
   - `connectedQuickMongoClient` (`QuickMongoClient<TInitialDatabaseData>`) - Connected `QuickMongoClient` instance.
 
-- **Eaxmple:**
+- **Example:**
 ```ts
 quickMongo.on('connect', connectedClient => {
     console.log(`Connected ${connectedClient.databases.length} databases to MongoDB.`)

docs/events/QuickMongoClient/disconnect.md

@@ -2,7 +2,7 @@
 
 Emits when the MongoDB connection was destroyed.
 
-- **Eaxmple:**
+- **Example:**
 ```ts
 quickMongo.on('disconnect', () => {
     console.log('Disconnected from MongoDB.')

docs/interfaces/IDatabaseConfiguration.md

@@ -2,7 +2,7 @@
 
 Represents the configuration object of the `QuickMongo` database instance.
 
-## Implemenatation
+## Implementation
 ```ts
 export interface IDatabaseConfiguration {
     name: string

docs/interfaces/IDatabaseInternalStructure.md

@@ -2,7 +2,7 @@
 
 Represents the object of the way data stored in the internal `[__KEY]-[__VALUE]` storage format that was made to achieve better data accessibility across the module.
 
-## Implemenatation
+## Implementation
 ```ts
 export interface IDatabaseInternalStructure<T = any> {
     __KEY: string
@@ -11,7 +11,7 @@ export interface IDatabaseInternalStructure<T = any> {
 ```
 
 - **Type Parameters:**
-  - `T` (`any`) - The type of `__VALUE` property in each raw data object.
+  - `T` (`any`, defaults to `any`) - The type of `__VALUE` property in each raw data object.
 
 - **Properties:**
   - `__KEY` (`string`): The key to store the data under.

docs/interfaces/IDatabaseRequestsLatencyData.md

@@ -2,7 +2,13 @@
 
 Represents the database operations latency object.
 
-## Implemenatation
+
+# References in this doc
+- Built-ins:
+  - [`Record<K, T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)
+
+
+## Implementation
 ```ts
 export type IDatabaseRequestsLatencyData = Record<
     'readLatency' | 'writeLatency' | 'deleteLatency',

docs/types/ExtractFromArray.md

@@ -1,8 +1,8 @@
 # **`ExtractFromArray<T>` Type**
 
-Extracts the type from the `Array<T>` type.
+From the type `A`, extracts the type `T` from the `Array<T>` type, or returns `A` if not array type was specified.
 
-## Implemenatation
+## Implementation
 ```ts
 export type ExtractFromArray<A> = A extends Array<infer T> ? T : A
 ```

docs/types/ExtractFromRestOrArray.md

@@ -6,7 +6,13 @@ Useful to prevent accidentally creating the `RestOrArray<RestOrArray<T>>` instan
 
 `T` is being extracted from `RestOrArray<RestOrArray<T>>` type and being passed into `RestOrArray<T>` type.
 
-## Implemenatation
+
+## References in this doc
+- Types:
+  - [`RestOrArray<T>`](./RestOrArray.md)
+
+
+## Implementation
 ```ts
 export type ExtractFromRestOrArray<T> = T extends RestOrArray<infer R>
     ? RestOrArray<R>

docs/types/If.md

@@ -4,7 +4,8 @@ Conditional type that returns the type based on the condition type result.
 
 ## Implementation
 ```ts
-export type If<T extends boolean,
+export type If<
+    T extends boolean,
     IfTrue,
     IfFalse = null
 > = T extends true ? IfTrue : IfFalse
@@ -13,5 +14,5 @@ export type If<T extends boolean,
 - **Type Parameters:**
   - `T` (`boolean`): The condition to return a boolean value.
   - `IfTrue` (`any`): The type to be returned if the condition type `T` is `true`
-  - `IfFalse` (`any`): The type to be returned if the condition type `T` is `false`
+  - `IfFalse` (`any`, defaults to `null`): The type to be returned if the condition type `T` is `false`
 

docs/types/IsObject.md

@@ -2,6 +2,12 @@
 
 Determines if the specified type is object and returns the checking result as boolean.
 
+
+# References in this doc
+- Built-ins:
+  - [`Record<K, T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)
+
+
 ## Implementation
 ```ts
 export type IsObject<T> = T extends null

docs/types/Maybe.md

@@ -2,7 +2,13 @@
 
 Represents the nullish type (`T` or `null`) and excludes `undefined` from it.
 
-## Implemenatation
+
+# References in this doc
+- Built-ins:
+  - [`Exclude<T, U>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#excludeuniontype-excludedmembers)
+
+
+## Implementation
 ```ts
 export type Maybe<T> = Exclude<T | null, undefined>
 ```