hola-server 1.0.10 → 2.0.1

package/http/params.js

@@ -1,57 +1,85 @@
+/**
+ * @fileoverview Request parameter extraction utilities.
+ * @module http/params
+ */
+
 const { has_value, is_undefined } = require('../core/validate');
 
-const parse_params = function (input, params) {
+/**
+ * Extract parameters from input object using a filter function.
+ * @param {Object} input - Source object (req.query or req.body)
+ * @param {string[]} params - Parameter names to extract
+ * @param {Function} filter_fn - Function to determine if param should be included
+ * @returns {Object} Object containing extracted parameters
+ */
+const extract_params = (input, params, filter_fn) => {
     const obj = {};
-    params.forEach(function (param) {
-        if (has_value(input[param])) {
+    for (const param of params) {
+        if (filter_fn(input[param])) {
             obj[param] = input[param];
         }
-    });
+    }
     return obj;
 };
 
-const get_params = function (req, params) {
-    return parse_params(req.query, params);
-};
+/**
+ * Extract specified parameters from input object (only if values are present).
+ * @param {Object} input - Source object (req.query or req.body)
+ * @param {string[]} params - Parameter names to extract
+ * @returns {Object} Object containing extracted parameters
+ */
+const parse_params = (input, params) => extract_params(input, params, has_value);
 
-const post_params = function (req, params) {
-    return parse_params(req.body, params);
-};
+/**
+ * Extract query parameters from request.
+ * @param {Object} req - Express request
+ * @param {string[]} params - Parameter names to extract
+ * @returns {Object} Extracted parameters
+ */
+const get_params = (req, params) => parse_params(req.query, params);
 
-const post_update_params = function (req, params) {
-    const input = req.body;
-    const obj = {};
-    params.forEach(function (param) {
-        if (!is_undefined(input[param])) {
-            obj[param] = input[param];
-        }
-    });
-    return obj;
-};
+/**
+ * Extract body parameters from request.
+ * @param {Object} req - Express request
+ * @param {string[]} params - Parameter names to extract
+ * @returns {Object} Extracted parameters
+ */
+const post_params = (req, params) => parse_params(req.body, params);
 
-const required_params = function (input, params) {
-    const obj = {};
-    let passed = true;
-    params.forEach(function (param) {
-        if (!has_value(input[param])) {
-            passed = false;
-        } else {
-            obj[param] = input[param];
-        }
-    });
-    if (passed === false) {
-        return null;
-    } else {
-        return obj;
-    }
-};
+/**
+ * Extract update parameters from request body, including undefined values.
+ * Used for partial updates where undefined means "don't change".
+ * @param {Object} req - Express request
+ * @param {string[]} params - Parameter names to extract
+ * @returns {Object} Extracted parameters
+ */
+const post_update_params = (req, params) => extract_params(req.body, params, v => !is_undefined(v));
 
-const required_get_params = function (req, params) {
-    return required_params(req.query, params);
+/**
+ * Extract required parameters, returning null if any are missing.
+ * @param {Object} input - Source object
+ * @param {string[]} params - Required parameter names
+ * @returns {Object|null} Extracted parameters or null if any missing
+ */
+const required_params = (input, params) => {
+    const result = parse_params(input, params);
+    return Object.keys(result).length === params.length ? result : null;
 };
 
-const required_post_params = function (req, params) {
-    return required_params(req.body, params);
-};
+/**
+ * Extract required query parameters from request.
+ * @param {Object} req - Express request
+ * @param {string[]} params - Required parameter names
+ * @returns {Object|null} Extracted parameters or null if any missing
+ */
+const required_get_params = (req, params) => required_params(req.query, params);
+
+/**
+ * Extract required body parameters from request.
+ * @param {Object} req - Express request
+ * @param {string[]} params - Required parameter names
+ * @returns {Object|null} Extracted parameters or null if any missing
+ */
+const required_post_params = (req, params) => required_params(req.body, params);
 
-module.exports = { get_params, post_params, post_update_params, required_get_params, required_post_params, required_params }
+module.exports = { get_params, post_params, post_update_params, required_get_params, required_post_params, required_params };

package/http/router.js

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Express router initialization and loading utilities.
+ * @module http/router
+ */
+
 const path = require("path");
 const fs = require("fs");
 const express = require('express');
@@ -10,63 +15,69 @@ const { init_clone_router } = require('../router/clone');
 const { init_delete_router } = require('../router/delete');
 const { get_settings } = require('../setting');
 
+/** CRUD operation configurations: [capability_key, init_function] */
+const CRUD_OPERATIONS = [
+    ['creatable', init_create_router],
+    ['readable', init_read_router],
+    ['updatable', init_update_router],
+    ['cloneable', init_clone_router],
+    ['deleteable', init_delete_router],
+];
+
 /**
- * Automatically load all the routers from the router directory
- * @param {express app} app 
- * @param {base dir of the project} base_dir 
+ * Automatically load all router modules from configured directories.
+ * Scans directories specified in settings.server.routes and mounts each router.
+ * After loading, validates all entity metadata definitions.
+ * @param {Object} app - Express application instance.
+ * @param {string} base_dir - Base directory of the project.
  */
 const init_router_dirs = (app, base_dir) => {
-    const route_dirs = get_settings().server.routes;
+    const settings = get_settings();
+    if (!settings?.server?.routes) {
+        return;
+    }
+
+    for (const route_dir of settings.server.routes) {
+        const full_route_dir = path.join(base_dir, route_dir);
+        if (!fs.existsSync(full_route_dir)) {
+            continue;
+        }
 
-    if (route_dirs) {
-        route_dirs.forEach(route_dir => {
-            const full_route_dir = path.join(base_dir, route_dir);
-            const routes = fs.readdirSync(full_route_dir);
-            routes.forEach(route => {
-                const router = require(`${base_dir}/${route_dir}/${route}`);
-                const basename = path.basename(route, '.js');
-                app.use('/' + basename, router);
-            });
-        });
+        for (const route of fs.readdirSync(full_route_dir)) {
+            if (!route.endsWith('.js')) {
+                continue;
+            }
 
-        //after init all the router, then validate all the meta informations
-        validate_all_metas();
+            const router = require(`${base_dir}/${route_dir}/${route}`);
+            const basename = path.basename(route, '.js');
+            app.use('/' + basename, router);
+        }
     }
-}
+
+    validate_all_metas();
+};
 
 /**
- * Init all the router for the entity
- * @param {meta config of the entity} meta 
+ * Initialize Express router for an entity with CRUD operations.
+ * Registers routes based on entity metadata capabilities (creatable, readable, etc.).
+ * @param {Object} meta - Entity metadata configuration.
+ * @returns {Object} Configured Express router.
  */
-const init_router = function (meta) {
+const init_router = (meta) => {
     const router = express.Router();
     const meta_entity = new EntityMeta(meta);
 
-    if (meta_entity.creatable) {
-        init_create_router(router, meta_entity);
-    }
-
-    if (meta_entity.readable) {
-        init_read_router(router, meta_entity);
-    }
-
-    if (meta_entity.updatable) {
-        init_update_router(router, meta_entity);
-    }
-
-    if (meta_entity.cloneable) {
-        init_clone_router(router, meta_entity);
-    }
-
-    if (meta_entity.deleteable) {
-        init_delete_router(router, meta_entity);
+    for (const [capability, init_fn] of CRUD_OPERATIONS) {
+        if (meta_entity[capability]) {
+            init_fn(router, meta_entity);
+        }
     }
 
-    if (meta.route) {
+    if (typeof meta.route === 'function') {
         meta.route(router, meta_entity);
     }
 
     return router;
-}
+};
 
 module.exports = { init_router_dirs, init_router };

package/http/session.js

@@ -1,50 +1,73 @@
+/**
+ * @fileoverview Session middleware initialization and helpers.
+ * @module http/session
+ */
+
 const express_session = require('express-session');
 const MongoStore = require('connect-mongo');
 const { get_settings } = require('../setting');
 const { is_root_user } = require('../core/role');
 
+/**
+ * Initialize session middleware with MongoDB store.
+ * @param {Object} app - Express application instance
+ */
 const init_session = (app) => {
-    const server = get_settings().server;
-    const mongo = get_settings().mongo;
-
-    if (server.keep_session && mongo) {
-        const session = server.session;
-
-        app.use(express_session({
-            secret: session.secret,
-            resave: true,
-            saveUninitialized: true,
-            cookie: { maxAge: session.cookie_max_age },
-            store: MongoStore.create({ mongoUrl: mongo.url })
-        }));
+    const { server, mongo } = get_settings();
+    if (!server?.keep_session) return;
+    if (!server.session?.secret) {
+        throw new Error('Session secret required when keep_session is enabled');
     }
-}
 
-const get_session_userid = (req) => {
-    const user = req && req.session ? req.session.user : null;
-    return user ? user.id : null;
-}
+    app.use(express_session({
+        secret: server.session.secret,
+        resave: true,
+        saveUninitialized: true,
+        cookie: { maxAge: server.session.cookie_max_age || 86400000 },
+        store: MongoStore.create({ mongoUrl: mongo.url })
+    }));
+};
+
+/**
+ * Get a value from the session.
+ * @param {Object} req - Express request
+ * @param {string} key - Session key
+ * @returns {*} Session value or null
+ */
+const get_session_value = (req, key) => req?.session?.[key] ?? null;
+
+/**
+ * Get current user ID from session.
+ * @param {Object} req - Express request
+ * @returns {string|null} User ID or null
+ */
+const get_session_user_id = (req) => get_session_value(req, 'user')?.id ?? null;
 
+/**
+ * Get current user groups from session.
+ * @param {Object} req - Express request
+ * @returns {string[]|null} User group IDs or null
+ */
 const get_session_user_groups = (req) => {
-    const group = req && req.session ? req.session.group : null;
-    return group && Array.isArray(group) ? group : null;
-}
+    const group = get_session_value(req, 'group');
+    return Array.isArray(group) ? group : null;
+};
 
+/**
+ * Check if current user owns the entity.
+ * @param {Object} req - Express request
+ * @param {Object} meta - Entity meta
+ * @param {Object} entity - Entity instance
+ * @param {Object} query - MongoDB query
+ * @returns {Promise<boolean>} True if owner or root
+ */
 const is_owner = async (req, meta, entity, query) => {
-    if (is_root_user(req)) {
-        return true;
-    }
+    if (is_root_user(req) || !meta.user_field) return true;
 
-    if (meta.user_field) {
-        const user_id = get_session_userid(req);
-        if (user_id == null) {
-            throw new Error("no user id is found in session");
-        }
-        const user_query = {};
-        user_query[meta.user_field] = user_id;
-        return await entity.count({ ...query, ...user_query }) == 1;
-    }
-    return true;
-}
+    const user_id = get_session_user_id(req);
+    if (!user_id) throw new Error("no user id found in session");
+
+    return await entity.count({ ...query, [meta.user_field]: user_id }) === 1;
+};
 
-module.exports = { init_session, get_session_userid, get_session_user_groups, is_owner };
+module.exports = { init_session, get_session_user_id, get_session_user_groups, is_owner };

package/index.js

@@ -1,11 +1,33 @@
+/**
+ * @fileoverview Hola Server - Main entry point and public API.
+ * @module index
+ */
+
+// Database
 const { get_db } = require('./db/db');
 const { Entity } = require('./db/entity');
+const { log_debug, log_info, log_warn, log_error, is_log_debug, is_log_info, is_log_warn, is_log_error, get_session_user_id, oid_queries, oid_query } = require('./db/db');
+const gridfs = require('./db/gridfs');
+
+// Settings and Configuration
 const { init_settings } = require('./setting');
+
+// HTTP Layer
 const { init_router } = require('./http/router');
 const { init_express_server } = require('./http/express');
+const code = require('./http/code');
+const err = require('./http/error');
+const params = require('./http/params');
+const context = require('./http/context');
+
+// Core Type System
 const { register_type, get_type } = require('./core/type');
 const { EntityMeta, get_entity_meta } = require('./core/meta');
+
+// Core Role System
 const { is_root_role, is_root_user, check_user_role, get_user_role_right, get_session_user } = require('./core/role');
+
+// Core Utilities
 const { url } = require('./core/url');
 const array = require('./core/array');
 const bash = require('./core/bash');
@@ -20,17 +42,71 @@ const obj = require('./core/obj');
 const random = require('./core/random');
 const thread = require('./core/thread');
 const validate = require('./core/validate');
-const code = require('./http/code');
-const err = require('./http/error');
-const params = require('./http/params');
-const context = require('./http/context');
-const gridfs = require('./db/gridfs');
 
+// Tools
 const { gen_i18n } = require('./tool/gen_i18n');
-const { log_debug, log_info, log_warn, log_error, is_log_debug, is_log_info, is_log_warn, is_log_error, get_session_userid, oid_queries, oid_query } = require('./db/db');
 
 module.exports = {
-    init_settings, is_root_role, is_root_user, check_user_role, get_user_role_right, get_session_user, init_express_server, init_router, register_type, get_type, get_db, url,
-    Entity, EntityMeta, get_entity_meta, array, bash, chart, cron, date, file, lhs, msg, number, obj, random, thread, validate, code, err, params, context, gridfs, gen_i18n,
-    log_debug, log_info, log_warn, log_error, is_log_debug, is_log_info, is_log_warn, is_log_error, get_session_userid, oid_queries, oid_query
+    // Settings
+    init_settings,
+
+    // Express Server
+    init_express_server,
+    init_router,
+
+    // Database
+    get_db,
+    Entity,
+    oid_queries,
+    oid_query,
+    gridfs,
+
+    // Logging
+    log_debug,
+    log_info,
+    log_warn,
+    log_error,
+    is_log_debug,
+    is_log_info,
+    is_log_warn,
+    is_log_error,
+
+    // Type System
+    register_type,
+    get_type,
+    EntityMeta,
+    get_entity_meta,
+
+    // Role & Auth
+    is_root_role,
+    is_root_user,
+    check_user_role,
+    get_user_role_right,
+    get_session_user,
+    get_session_user_id,
+
+    // HTTP Utilities
+    url,
+    code,
+    err,
+    params,
+    context,
+
+    // Core Utilities
+    array,
+    bash,
+    chart,
+    cron,
+    date,
+    file,
+    lhs,
+    msg,
+    number,
+    obj,
+    random,
+    thread,
+    validate,
+
+    // Tools
+    gen_i18n
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hola-server",
-  "version": "1.0.10",
+  "version": "2.0.1",
   "description": "a meta programming framework used to build nodejs restful api",
   "main": "index.js",
   "scripts": {
@@ -43,4 +43,4 @@
     "url": "https://github.com/hery-node/hola-server/issues"
   },
   "homepage": "https://github.com/hery-node/hola-server#readme"
-}
+}

package/router/clone.js

@@ -1,6 +1,11 @@
+/**
+ * @fileoverview Entity clone router handlers.
+ * @module router/clone
+ */
+
 const { set_file_fields, save_file_fields_to_db } = require('../db/gridfs');
 const { SUCCESS, NO_PARAMS, NO_RIGHTS } = require('../http/code');
-const { get_session_userid, is_owner } = require('../http/session');
+const { get_session_user_id, is_owner } = require('../http/session');
 const { wrap_http } = require('../http/error');
 const { post_params, required_post_params } = require('../http/params');
 const { has_value } = require('../core/validate');
@@ -12,62 +17,49 @@ const multer = require('multer');
 const upload_file = multer({ dest: 'file_tmp/' });
 
 /**
- * init http clone router
- * @param {express router} router 
- * @param {entity meta info} meta 
+ * Initialize clone router for entity.
+ * @param {Object} router - Express router
+ * @param {Object} meta - Entity metadata
  */
-const init_clone_router = function (router, meta) {
+const init_clone_router = (router, meta) => {
     const entity = new Entity(meta);
     const cp_upload = meta.upload_fields.length > 0 ? upload_file.fields(meta.upload_fields) : upload_file.none();
 
-    router.post('/clone', cp_upload, wrap_http(async function (req, res) {
-        //which view to clone the entity
-        let { _view } = post_params(req, ["_view"]);
-        if (!_view) {
-            _view = "*";
-        }
+    router.post('/clone', cp_upload, wrap_http(async (req, res) => {
+        const _view = post_params(req, ["_view"])._view || "*";
 
-        const has_right = check_user_role(req, meta, "o", _view);
-        if (!has_right) {
-            res.json({ code: NO_RIGHTS, err: "no rights error" });
-            return;
+        if (!check_user_role(req, meta, "o", _view)) {
+            return res.json({ code: NO_RIGHTS, err: "no rights to clone" });
         }
 
-        let params = required_post_params(req, ["_id"]);
-        if (params === null) {
-            res.json({ code: NO_PARAMS, err: '[_id] checking params are failed!' });
-            return;
+        const params = required_post_params(req, ["_id"]);
+        if (!params) {
+            return res.json({ code: NO_PARAMS, err: "[_id] required for clone" });
         }
 
         const param_obj = post_params(req, meta.field_names);
         set_file_fields(meta, req, param_obj);
 
-        const query = params["_id"] ? oid_query(params["_id"]) : entity.primary_key_query(param_obj);
-        const owner = await is_owner(req, meta, entity, query);
-        if (!owner) {
-            res.json({ code: NO_RIGHTS, err: "no rights error" });
-            return;
+        const query = params._id ? oid_query(params._id) : entity.primary_key_query(param_obj);
+        if (!await is_owner(req, meta, entity, query)) {
+            return res.json({ code: NO_RIGHTS, err: "no ownership rights" });
         }
 
         if (meta.user_field) {
-            const user_id = get_session_userid(req);
-            if (user_id == null) {
-                throw new Error("no user is found in session");
-            }
+            const user_id = get_session_user_id(req);
+            if (user_id == null) throw new Error("no user found in session for clone");
             param_obj[meta.user_field] = user_id;
         }
 
-        const { code, err } = await entity.clone_entity(params["_id"], param_obj, _view);
-        if (!has_value(code)) {
-            throw new Error("the method should return code");
-        }
+        const { code, err } = await entity.clone_entity(params._id, param_obj, _view);
+        if (!has_value(code)) throw new Error("clone_entity must return code");
 
-        if (code == SUCCESS) {
+        if (code === SUCCESS) {
             await save_file_fields_to_db(meta.collection, meta.file_fields, req, param_obj);
         }
 
-        res.json({ code: code, err: err });
+        res.json({ code, err });
     }));
-}
+};
 
-module.exports = { init_clone_router }
+module.exports = { init_clone_router };

package/router/create.js

@@ -1,6 +1,11 @@
+/**
+ * @fileoverview Create router initialization.
+ * @module router/create
+ */
+
 const { set_file_fields, save_file_fields_to_db } = require('../db/gridfs');
 const { SUCCESS, NO_RIGHTS } = require('../http/code');
-const { get_session_userid } = require('../http/session');
+const { get_session_user_id } = require('../http/session');
 const { wrap_http } = require('../http/error');
 const { post_params } = require('../http/params');
 const { has_value } = require('../core/validate');
@@ -11,49 +16,39 @@ const multer = require('multer');
 const upload_file = multer({ dest: 'file_tmp/' });
 
 /**
- * init http create router
- * @param {express router} router 
- * @param {entity meta info} meta 
+ * Initialize HTTP create router.
+ * @param {Object} router - Express router
+ * @param {Object} meta - Entity metadata
  */
-const init_create_router = function (router, meta) {
+const init_create_router = (router, meta) => {
     const entity = new Entity(meta);
     const cp_upload = meta.upload_fields.length > 0 ? upload_file.fields(meta.upload_fields) : upload_file.none();
 
-    router.post('/create', cp_upload, wrap_http(async function (req, res) {
-        //which view to create the entity
-        let { _view } = post_params(req, ["_view"]);
-        if (!_view) {
-            _view = "*";
-        }
+    router.post('/create', cp_upload, wrap_http(async (req, res) => {
+        const _view = post_params(req, ["_view"])._view || "*";
 
-        const has_right = check_user_role(req, meta, "c", _view);
-        if (!has_right) {
-            res.json({ code: NO_RIGHTS, err: "no rights error" });
-            return;
+        if (!check_user_role(req, meta, "c", _view)) {
+            return res.json({ code: NO_RIGHTS, err: "no rights" });
         }
 
         const param_obj = post_params(req, meta.field_names);
         set_file_fields(meta, req, param_obj);
 
         if (meta.user_field) {
-            const user_id = get_session_userid(req);
-            if (user_id == null) {
-                throw new Error("no user is found in session");
-            }
+            const user_id = get_session_user_id(req);
+            if (user_id == null) throw new Error("no user found in session");
             param_obj[meta.user_field] = user_id;
         }
 
         const { code, err } = await entity.create_entity(param_obj, _view);
-        if (!has_value(code)) {
-            throw new Error("the method should return code");
-        }
+        if (!has_value(code)) throw new Error("create_entity must return code");
 
-        if (code == SUCCESS) {
+        if (code === SUCCESS) {
             await save_file_fields_to_db(meta.collection, meta.file_fields, req, param_obj);
         }
 
-        res.json({ code: code, err: err });
+        res.json({ code, err });
     }));
-}
+};
 
-module.exports = { init_create_router }
+module.exports = { init_create_router };