hola-server 1.0.11 → 2.0.1

package/db/db.js

@@ -1,376 +1,446 @@
+/**
+ * @fileoverview Database utilities for MongoDB using mongoist.
+ * @module db/db
+ */
+
 const mongoist = require("mongoist");
 
 const { get_settings } = require("../setting");
 const { get_context_value } = require("../http/context");
 const { format_date_time } = require("../core/date");
 
+// Log level constants
 const LOG_LEVEL_DEBUG = 0;
 const LOG_LEVEL_INFO = 1;
 const LOG_LEVEL_WARN = 2;
 const LOG_LEVEL_ERROR = 3;
 
+// Log category constants
 const LOG_DB = "database";
 const LOG_ENTITY = "entity";
 const LOG_SYSTEM = "system";
 
-const get_session_userid = () => {
-  const req = get_context_value("req");
-  return req && req.session && req.session.user ? req.session.user.id : "";
-};
-
-const log_msg = (category, level, msg, extra) => {
-  const time = format_date_time(new Date());
-  const db = get_db();
-  const { col_log } = get_settings().log;
-
-  const req = get_context_value("req");
-  const path = req ? req.originalUrl : "";
-  const user = req && req.session && req.session.user ? req.session.user.id : "";
-
-  db.create(col_log, { time: time, category: category, level: level, msg: msg, user: user, path: path, ...extra }).then(() => { });
-};
-
-const is_log_debug = () => {
-  const { save_db, log_level } = get_settings().log;
-  return save_db && log_level <= LOG_LEVEL_DEBUG;
-};
-
-const is_log_info = () => {
-  const { save_db, log_level } = get_settings().log;
-  return save_db && log_level <= LOG_LEVEL_INFO;
-};
-
-const is_log_warn = () => {
-  const { save_db, log_level } = get_settings().log;
-  return save_db && log_level <= LOG_LEVEL_WARN;
-};
+/**
+ * Resolve user id from request context if available.
+ * @returns {string} user id or empty string when unauthenticated
+ */
+const get_session_user_id = () => get_context_value("req")?.session?.user?.id || "";
 
-const is_log_error = () => {
+/**
+ * Check if logging is enabled for the given level.
+ * @param {number} level - Log level to check
+ * @returns {boolean} true if logging is enabled
+ */
+const is_log_enabled = (level) => {
   const { save_db, log_level } = get_settings().log;
-  return save_db && log_level <= LOG_LEVEL_ERROR;
+  return save_db && log_level <= level;
 };
 
-const log_debug = (category, msg, extra) => {
-  if (is_log_debug()) {
-    log_msg(category, LOG_LEVEL_DEBUG, msg, extra);
-  }
-};
+// Log level checkers using the unified helper
+const is_log_debug = () => is_log_enabled(LOG_LEVEL_DEBUG);
+const is_log_info = () => is_log_enabled(LOG_LEVEL_INFO);
+const is_log_warn = () => is_log_enabled(LOG_LEVEL_WARN);
+const is_log_error = () => is_log_enabled(LOG_LEVEL_ERROR);
 
-const log_info = (category, msg, extra) => {
-  if (is_log_info()) {
-    log_msg(category, LOG_LEVEL_INFO, msg, extra);
-  }
+/**
+ * Write a log entry to the database.
+ * @param {string} category - Log category
+ * @param {number} level - Log level
+ * @param {string} message - Log message
+ * @param {Object} extra - Additional data
+ */
+const log_message = (category, level, message, extra = {}) => {
+  const req = get_context_value("req");
+  const entry = {
+    time: format_date_time(new Date()),
+    category,
+    level,
+    msg: message,
+    user: req?.session?.user?.id || "",
+    path: req?.originalUrl || "",
+    ...extra
+  };
+
+  get_db().create(get_settings().log.col_log, entry).catch(() => { });
 };
 
-const log_warn = (category, msg, extra) => {
-  if (is_log_warn()) {
-    log_msg(category, LOG_LEVEL_WARN, msg, extra);
+/**
+ * Create a log function for a specific level.
+ * @param {number} level - Log level
+ * @param {Function} check_fn - Function to check if logging is enabled
+ * @returns {Function} Log function
+ */
+const create_log_fn = (level, check_fn) => (category, msg, extra) => {
+  if (check_fn()) {
+    log_message(category, level, msg, extra);
   }
 };
 
-const log_error = (category, msg, extra) => {
-  if (is_log_error()) {
-    log_msg(category, LOG_LEVEL_ERROR, msg, extra);
-  }
-};
+const log_debug = create_log_fn(LOG_LEVEL_DEBUG, is_log_debug);
+const log_info = create_log_fn(LOG_LEVEL_INFO, is_log_info);
+const log_warn = create_log_fn(LOG_LEVEL_WARN, is_log_warn);
+const log_error = create_log_fn(LOG_LEVEL_ERROR, is_log_error);
 
 /**
  * Construct mongodb ObjectId
- * @param {string value of the id} id
- * @returns
+ * @param {string} id - String value of the id
+ * @returns {ObjectId} MongoDB ObjectId
  */
-const oid = (id) => {
-  return mongoist.ObjectId(id);
-};
+const oid = (id) => mongoist.ObjectId(id);
 
 /**
  * Construct objectId query object
- * @param {string value of the id} id
- * @returns id query if id is valid otherwise return null
+ * @param {string} id - String value of the id
+ * @returns {Object|null} id query if id is valid, otherwise null
  */
 const oid_query = (id) => {
   try {
     return { _id: oid(id) };
-  } catch (e) {
+  } catch {
     return null;
   }
 };
 
 /**
- * Construct in query of ObjectId array
- * @param {string value of the id} ids
- * @returns id in query if id is valid otherwise return null
+ * Construct $in query of ObjectId array
+ * @param {string[]} ids - Array of string ids
+ * @returns {Object|null} id $in query if valid, otherwise null
  */
 const oid_queries = (ids) => {
   try {
-    const id_array = ids.map((id) => oid(id));
-    return { _id: { $in: id_array } };
-  } catch (e) {
+    return { _id: { $in: ids.map(oid) } };
+  } catch {
     return null;
   }
 };
 
 /**
  * Execute bulk update using the items
- * @param {mongodb collection} col
- * @param {the items to execute bulk update} items
- * @param {the attributes used as search criteria} attrs
- * @returns
+ * @param {Object} col - MongoDB collection
+ * @param {Object[]} items - Items to execute bulk update
+ * @param {string[]} attrs - Attributes used as search criteria
+ * @returns {Promise} Bulk operation result
  */
 const bulk_update = async (col, items, attrs) => {
   const bulk = col.initializeOrderedBulkOp();
   for (const item of items) {
-    const query = {};
-    attrs.forEach(function (attr) {
-      query[attr] = item[attr];
-    });
-    delete item["_id"];
-    bulk.find(query).upsert().update({ $set: item }, true);
+    const query = attrs.reduce((acc, attr) => ({ ...acc, [attr]: item[attr] }), {});
+    const { _id, ...without_id } = item;
+    bulk.find(query).upsert().update({ $set: without_id }, true);
   }
-  return await bulk.execute();
+  return bulk.execute();
+};
+
+/**
+ * Log debug message for DB operations.
+ * @param {string} operation - Operation name
+ * @param {string} code - Collection name
+ * @param {Object} params - Operation parameters
+ */
+const debug_log = (operation, code, params = {}) => {
+  if (!is_log_debug()) return;
+
+  const parts = Object.entries(params)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => `${k}:${JSON.stringify(v)}`);
+
+  log_debug(LOG_DB, `${operation} for [${code}]${parts.length ? ` with ${parts.join(", ")}` : ""}`);
 };
 
 class DB {
   constructor(url, options, callback) {
     if (!url) {
-      return;
+      throw new Error("Mongo url is required to initialize DB");
     }
 
     this.db = mongoist(url, options);
+    this.closed = false;
 
-    this.db.on("error", function (err) {
-      if (is_log_error()) {
-        log_error(LOG_DB, err);
-      }
-    });
-
-    this.db.on('connect', function () {
-      callback && callback();
+    this.db.on("error", (err) => log_error(LOG_DB, err));
+    this.db.on("close", () => { this.closed = true; });
+    this.db.on("connect", () => {
+      this.closed = false;
+      callback?.();
     });
   }
 
   /**
-   * get db collection
-   * @param {mongodb collection name} code
-   * @returns 
+   * Get db collection
+   * @param {string} code - Collection name
+   * @returns {Object} MongoDB collection
    */
-  get_col(code) {
+  col(code) {
     return this.db[code];
   }
 
   /**
-   * Insert Object to db
-   * @param {mongodb collection name} code
-   * @param {inserted object} obj
-   * @returns
+   * Insert object to db
+   * @param {string} code - Collection name
+   * @param {Object} obj - Object to insert
+   * @returns {Promise} Insert result
    */
   create(code, obj) {
-    const col = this.db[code];
     delete obj["_id"];
-    return col.insert(obj, { checkKeys: false });
+    return this.col(code).insert(obj, { checkKeys: false });
   }
 
   /**
-   * Update the object, upsert:true, multi:true
-   * @param {mongodb collection name} code
-   * @param {*} query
-   * @param {*} obj
-   * @returns
+   * Update objects with upsert and multi enabled
+   * @param {string} code - Collection name
+   * @param {Object} query - Query criteria
+   * @param {Object} obj - Object to update
+   * @returns {Promise} Update result
    */
   update(code, query, obj) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "updating obj:" + JSON.stringify(obj) + ", for [" + code + "] with query:" + JSON.stringify(query));
-    }
-
-    const col = this.db[code];
+    debug_log("updating", code, { query, obj });
     delete obj["_id"];
-    return col.update(query, { $set: obj }, { upsert: true, multi: true });
+    return this.col(code).update(query, { $set: obj }, { upsert: true, multi: true });
   }
 
   /**
-   * Remove the records from mongodb
-   * @param {mongodb collection name} code
-   * @param {query to execute delete op} query
-   * @returns
+   * Remove records from mongodb
+   * @param {string} code - Collection name
+   * @param {Object} query - Query to execute delete
+   * @returns {Promise} Delete result
    */
   delete(code, query) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "deleting objects for [" + code + "] with query:" + JSON.stringify(query));
-    }
-
-    const col = this.db[code];
-    return col.remove(query);
+    debug_log("deleting", code, { query });
+    return this.col(code).remove(query);
   }
 
   /**
-   * Search the db using query
-   * @param {mongodb collection name} code
-   * @param {search criteria} query
-   * @param {the attributes to load from db} attr
-   * @returns
+   * Find records by query
+   * @param {string} code - Collection name
+   * @param {Object} query - Search criteria
+   * @param {Object} attr - Attributes to load
+   * @returns {Promise} Query result
    */
   find(code, query, attr) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "find objects for [" + code + "] with query:" + JSON.stringify(query) + " and attr:" + JSON.stringify(attr));
-    }
-
-    const col = this.db[code];
-    return col.find(query, attr);
+    debug_log("find", code, { query, attr });
+    return this.col(code).find(query, attr);
   }
 
   /**
-   * Find one record from db
-   * @param {mongodb collection name} code
-   * @param {search criteria} query
-   * @param {the attributes to load from db} attr
-   * @returns
+   * Find one record
+   * @param {string} code - Collection name
+   * @param {Object} query - Search criteria
+   * @param {Object} attr - Attributes to load
+   * @returns {Promise} Single record or null
    */
   find_one(code, query, attr) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "find_one for [" + code + "] with query:" + JSON.stringify(query) + " and attr:" + JSON.stringify(attr));
-    }
-
-    const col = this.db[code];
-    return col.findOne(query, attr);
+    debug_log("find_one", code, { query, attr });
+    return this.col(code).findOne(query, attr);
   }
 
   /**
-   * Find the records from db using sort to do sorting
-   * @param {mongodb collection name} code
-   * @param {search criteria} query
-   * @param {sort object to sort the result} sort
-   * @param {the attributes of the object to load from db} attr
-   * @returns
+   * Find records with sorting
+   * @param {string} code - Collection name
+   * @param {Object} query - Search criteria
+   * @param {Object} sort - Sort specification
+   * @param {Object} attr - Attributes to load
+   * @returns {Promise} Sorted query result
    */
   find_sort(code, query, sort, attr) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "find_sort for [" + code + "] with query:" + JSON.stringify(query) + " and attr:" + JSON.stringify(attr) + " and sort:" + JSON.stringify(sort));
-    }
-
-    const col = this.db[code];
-    return col.find(query, attr, { sort: sort });
+    debug_log("find_sort", code, { query, attr, sort });
+    return this.col(code).find(query, attr, { sort });
   }
 
   /**
-   * Find the page records
-   * @param {mongodb collection name} code
-   * @param {search criteria} query
-   * @param {sort object to sort the results} sort
-   * @param {the page index to load} page
-   * @param {page size } limit
-   * @param {the attributes of the object to load from db} attr
-   * @returns
+   * Find paginated records
+   * @param {string} code - Collection name
+   * @param {Object} query - Search criteria
+   * @param {Object} sort - Sort specification
+   * @param {number} page - Page index (1-based)
+   * @param {number} limit - Page size
+   * @param {Object} attr - Attributes to load
+   * @returns {Promise} Paginated query result
    */
   find_page(code, query, sort, page, limit, attr) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "find_page for [" + code + "] with query:" + JSON.stringify(query) + " and attr:" + JSON.stringify(attr) + " and sort:" + JSON.stringify(sort) + ", page:" + page + ",limit:" + limit);
-    }
-
-    const skip = (page - 1) * limit > 0 ? (page - 1) * limit : 0;
-    const col = this.db[code];
-    return col.find(query, attr, { sort: sort, skip: skip, limit: limit });
+    debug_log("find_page", code, { query, attr, sort, page, limit });
+    const skip = Math.max((page - 1) * limit, 0);
+    return this.col(code).find(query, attr, { sort, skip, limit });
   }
 
   /**
-   * The count number of the query
-   * @param {mongodb collection name} code
-   * @param {search criteria} query
-   * @returns
+   * Count records matching query
+   * @param {string} code - Collection name
+   * @param {Object} query - Search criteria
+   * @returns {Promise<number>} Count result
    */
   count(code, query) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "count for [" + code + "] with query:" + JSON.stringify(query));
-    }
-
-    const col = this.db[code];
-    return col.count(query);
+    debug_log("count", code, { query });
+    return this.col(code).count(query);
   }
 
   /**
-   * Calculate the sum value based on the field and query criteria
-   * @param {mongodb collection name} code
-   * @param {search criteria} query
-   * @param {field name to calculate sum} field
-   * @returns
+   * Calculate sum of a field
+   * @param {string} code - Collection name
+   * @param {Object} query - Search criteria
+   * @param {string} field - Field name to sum
+   * @returns {Promise<number>} Sum result
    */
   sum(code, query, field) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "sum for [" + code + "] with query:" + JSON.stringify(query) + ", and field:" + JSON.stringify(field));
-    }
-
-    const col = this.db[code];
-    return col.aggregate([{ $match: query }, { $group: { _id: null, total: { $sum: "$" + field + "" } } }]).then((result) => (result.length > 0 ? result[0].total : 0));
+    debug_log("sum", code, { query, field });
+    return this.col(code)
+      .aggregate([{ $match: query }, { $group: { _id: null, total: { $sum: `$${field}` } } }])
+      .then((result) => result[0]?.total ?? 0);
   }
 
   /**
-   * Pull the object from array
-   * @param {mongodb collection name} code
-   * @param {search criteria} query
-   * @param {object pulled from the array} ele
-   * @returns
+   * Pull element from array field
+   * @param {string} code - Collection name
+   * @param {Object} query - Search criteria
+   * @param {Object} ele - Element to pull
+   * @returns {Promise} Update result
    */
   pull(code, query, ele) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "pull ele [" + JSON.stringify(ele) + "] with query:" + JSON.stringify(query) + ",code:" + code);
-    }
-
-    const col = this.db[code];
-    return col.update(query, { $pull: ele }, { multi: true });
+    debug_log("pull", code, { query, ele });
+    return this.col(code).update(query, { $pull: ele }, { multi: true });
   }
 
   /**
-   * Push the object to array
-   * @param {mongodb collection name} code
-   * @param {search criteria} query
-   * @param {object push to the array} ele
-   * @returns
+   * Push element to array field
+   * @param {string} code - Collection name
+   * @param {Object} query - Search criteria
+   * @param {Object} ele - Element to push
+   * @returns {Promise} Update result
    */
   push(code, query, ele) {
-    if (is_log_debug()) {
-      log_debug(LOG_DB, "push ele [" + JSON.stringify(ele) + "] with query:" + JSON.stringify(query) + ",code:" + code);
-    }
-
-    const col = this.db[code];
-    return col.update(query, { $push: ele });
+    debug_log("push", code, { query, ele });
+    return this.col(code).update(query, { $push: ele });
   }
 
   /**
-   * add the object to set
-   * @param {mongodb collection name} code
-   * @param {search criteria} query
-   * @param {object added to the set} ele
-   * @returns
+   * Add element to set field
+   * @param {string} code - Collection name
+   * @param {Object} query - Search criteria
+   * @param {Object} ele - Element to add
+   * @returns {Promise} Update result
    */
   add_to_set(code, query, ele) {
-    const col = this.db[code];
-    return col.update(query, { $addToSet: ele }, { upsert: true });
+    return this.col(code).update(query, { $addToSet: ele }, { upsert: true });
   }
 
   /**
-   * Get the mongodb collection
-   * @param {mongodb collection name} code
-   * @returns
+   * Close the underlying Mongo connection
    */
-  col(code) {
-    return this.db[code];
+  async close() {
+    if (!this.db || this.closed) return;
+    if (typeof this.db.close === "function") {
+      await this.db.close();
+    }
+    this.closed = true;
   }
 }
 
 let db_instance = null;
 
 /**
- *
- * @returns db instance of mongodb
+ * Get or create the database instance
+ * @param {Function} callback - Called when connected
+ * @returns {DB} Database instance
  */
 const get_db = (callback) => {
-  if (db_instance && db_instance.db) {
+  if (db_instance?.db && !db_instance.closed) {
     return db_instance;
-  } else {
-    const mongo = get_settings().mongo;
+  }
 
-    db_instance = new DB(mongo.url, mongo.options, callback);
-    return db_instance;
+  const { url, options } = get_settings().mongo || {};
+  if (!url) {
+    throw new Error("Mongo settings are missing url");
   }
+
+  db_instance = new DB(url, options, callback);
+  return db_instance;
 };
 
-module.exports = { oid, oid_query, oid_queries, bulk_update, get_db, log_debug, log_info, log_warn, log_error, is_log_debug, is_log_info, is_log_warn, is_log_error, LOG_DB, LOG_SYSTEM, LOG_ENTITY, get_session_userid };
+/**
+ * Close the database connection
+ */
+const close_db = async () => {
+  if (db_instance) {
+    await db_instance.close();
+    db_instance = null;
+  }
+};
+
+/**
+ * Auto-create indexes based on entity metadata.
+ * Safe to call multiple times - MongoDB's createIndex is idempotent.
+ * Should be called after all entity metas are registered (after validate_all_metas).
+ */
+const ensure_entity_indexes = async () => {
+  const { get_all_metas, get_entity_meta } = require('../core/meta');
+  const db = get_db();
+
+  for (const collection of get_all_metas()) {
+    const meta = get_entity_meta(collection);
+    const col = db.col(collection);
+
+    try {
+      // 1. Primary key compound index (unique)
+      if (meta.primary_keys?.length > 0) {
+        const key = meta.primary_keys.reduce((k, f) => ({ ...k, [f]: 1 }), {});
+        await col.createIndex(key, { unique: true, background: true });
+        log_debug(LOG_DB, `index created for [${collection}] primary_keys: ${JSON.stringify(key)}`);
+      }
+
+      // 2. Search fields (individual indexes for query performance)
+      for (const field of meta.search_fields || []) {
+        if (!meta.primary_keys.includes(field.name)) {
+          await col.createIndex({ [field.name]: 1 }, { background: true });
+          log_debug(LOG_DB, `index created for [${collection}] search field: ${field.name}`);
+        }
+      }
+
+      // 3. Ref label (for reference lookups)
+      if (meta.ref_label && !meta.primary_keys.includes(meta.ref_label)) {
+        await col.createIndex({ [meta.ref_label]: 1 }, { background: true });
+        log_debug(LOG_DB, `index created for [${collection}] ref_label: ${meta.ref_label}`);
+      }
+
+      // 4. Ref fields (foreign key lookups)
+      for (const field of meta.ref_fields || []) {
+        if (!meta.primary_keys.includes(field.name)) {
+          await col.createIndex({ [field.name]: 1 }, { background: true });
+          log_debug(LOG_DB, `index created for [${collection}] ref field: ${field.name}`);
+        }
+      }
+    } catch (err) {
+      log_error(LOG_DB, `index creation failed for [${collection}]: ${err.message}`);
+    }
+  }
+
+  log_info(LOG_DB, `entity indexes ensured for ${get_all_metas().length} collections`);
+};
+
+module.exports = {
+  // ObjectId utilities
+  oid,
+  oid_query,
+  oid_queries,
+  bulk_update,
+
+  // Database access
+  get_db,
+  close_db,
+  ensure_entity_indexes,
+
+  // Logging functions
+  log_debug,
+  log_info,
+  log_warn,
+  log_error,
+  is_log_debug,
+  is_log_info,
+  is_log_warn,
+  is_log_error,
+
+  // Log categories
+  LOG_DB,
+  LOG_SYSTEM,
+  LOG_ENTITY,
+
+  // Session
+  get_session_user_id
+};