improve docs

src/backend/database/index.ts

@@ -11,25 +11,25 @@ import { ObjectId } from 'mongodb';
 const Database = appConfig.database.driver === 'mongodb' ? MongoDatabaseDriver : LocalDatabaseDriver;
 
 /**
- *
+ * Convert a string to an EntityId (string or ObjectId depending on the database driver)
- * @param id
+ * @param id - id to convert
  */
 export function toEntityId(id: string): EntityId {
   return (appConfig.database.driver === 'mongodb' ? new ObjectId(id) : id) as EntityId;
 }
 
 /**
- *
+ * Check if provided ids are equal
- * @param id1
+ * @param id1 - first id
- * @param id2
+ * @param id2 - second id
  */
 export function isEqualIds(id1?: EntityId, id2?: EntityId): boolean {
   return id1?.toString() === id2?.toString();
 }
 
 /**
- *
+ * Check if provided ids are valid
- * @param id
+ * @param id - id to check
  */
 export function isEntityId(id?: EntityId): id is EntityId {
   return typeof id === 'string' || id instanceof ObjectId;

src/backend/database/local.ts

@@ -1,5 +1,5 @@
 import Datastore from 'nedb';
-import { DatabaseDriver, Options, RejectFunction, ResolveFunction } from './types.js';
+import { DatabaseDriver, Options } from './types.js';
 import path from 'path';
 import appConfig from '../utils/appConfig.js';
 
@@ -22,6 +22,21 @@ function initDb(name: string): Datastore {
   });
 }
 
+/**
+ * Resolve function helper
+ */
+export interface ResolveFunction {
+  (value: any): void;
+}
+
+/**
+ * Reject function helper
+ */
+export interface RejectFunction {
+  (reason?: unknown): void;
+}
+
+
 
 /**
  * Simple decorator class to work with nedb datastore

src/backend/database/mongodb.ts

@@ -6,18 +6,22 @@ const mongodbUri = appConfig.database.driver === 'mongodb' ? appConfig.database.
 const mongodbClient = mongodbUri ? await MongoClient.connect(mongodbUri): null;
 
 /**
- * Simple decorator class to work with nedb datastore
+ * MongoDB driver for working with database
  */
 export default class MongoDatabaseDriver<DocType> implements DatabaseDriver<DocType> {
   /**
    * Mongo client instance
    */
   private db: MongoClient;
+
+  /**
+   * Collection instance
+   */
   private collection: Collection<DocType>;
 
   /**
-   *
+   * Creates driver instance
-   * @param collectionName
+   * @param collectionName - collection to work with
    */
   constructor(collectionName: string) {
     if (!mongodbClient) {

src/backend/database/types.ts

@@ -1,13 +1,59 @@
 import { ObjectId } from 'mongodb';
 
+/**
+ * Represents database driver functionality
+ */
 export interface DatabaseDriver<DocType> {
+  /**
+   * Insert new document into the database
+   *
+   * @param {object} doc - object to insert
+   * @returns {Promise<object | Error>} - inserted doc or Error object
+   */
   insert(doc: DocType): Promise<DocType>;
+
+  /**
+   * Find documents that match passed query
+   *
+   * @param {object} query - query object
+   * @param {object} projection - projection object
+   * @returns {Promise<Array<object> | Error>} - found docs or Error object
+   */
   find(query: Record<string, unknown>, projection?: DocType): Promise<Array<DocType>>;
+
+  /**
+   * Find one document matches passed query
+   *
+   * @param {object} query - query object
+   * @param {object} projection - projection object
+   * @returns {Promise<object | Error>} - found doc or Error object
+   */
   findOne(query: Record<string, unknown>, projection?: DocType): Promise<DocType>;
+
+  /**
+   * Update document matches query
+   *
+   * @param {object} query - query object
+   * @param {object} update - fields to update
+   * @param {Options} options - optional params
+   * @returns {Promise<number | object | object[] | Error>} - number of updated rows or affected docs or Error object
+   */
   update(query: Record<string, unknown>, update: DocType, options: Options): Promise<number|boolean|Array<DocType>>
+
+  /**
+   * Remove document matches passed query
+   *
+   * @param {object} query - query object
+   * @param {Options} options - optional params
+   * @returns {Promise<number|Error>} - number of removed rows or Error object
+   */
   remove(query: Record<string, unknown>, options: Options): Promise<number>
 }
 
+/**
+ * Represents unique database entity id
+ * unique symbol to prevent type widening (read more https://todayilearned.net/2022/07/typescript-primitive-type-aliases-unique-symbols)
+ */
 export type EntityId = (string | ObjectId) & {readonly id: unique symbol};
 
 /**
@@ -22,11 +68,3 @@ export interface Options {
   upsert?: boolean;
   returnUpdatedDocs?: boolean;
 }
-
-export interface ResolveFunction {
-  (value: any): void;
-}
-
-export interface RejectFunction {
-  (reason?: unknown): void;
-}