hola-server 1.0.11 → 2.0.1

package/README.md

@@ -1 +1,196 @@
-# This is a meta programming framework used to build nodejs restful api
+# Hola Server
+
+A meta-programming framework for building Node.js RESTful APIs with MongoDB. Hola Server provides a declarative, metadata-driven approach to building CRUD APIs with built-in authentication, role-based access control, and file handling.
+
+## Features
+
+- **Meta-Driven CRUD**: Define entity schemas with metadata and get full CRUD APIs automatically
+- **Role-Based Access Control**: Fine-grained permissions per entity, operation, and view
+- **Type System**: Extensible type conversion and validation system
+- **File Handling**: Built-in GridFS integration for file uploads
+- **Session Management**: Express session with MongoDB store
+- **Entity Relationships**: Support for references with cascade/keep delete behavior
+- **Query Building**: Advanced search, filtering, and pagination
+- **Async Context**: Request-scoped context using AsyncLocalStorage
+- **Comprehensive Testing**: Full test suite with 111+ passing tests
+
+## Installation
+
+```bash
+npm install
+```
+
+## Quick Start
+
+### 1. Configure Settings
+
+```javascript
+const { init_settings } = require("hola-server");
+
+init_settings({
+  mongo: {
+    url: "mongodb://localhost/myapp",
+    pool: 10,
+  },
+  server: {
+    service_port: 8088,
+    client_web_url: ["http://localhost:3000"],
+    session: {
+      secret: "your-secret-key",
+      cookie_max_age: 86400000, // 1 day
+    },
+  },
+  roles: [{ name: "admin", root: true }, { name: "user" }],
+});
+```
+
+### 2. Define Entity Metadata
+
+```javascript
+const { EntityMeta } = require("hola-server");
+
+const user_meta = {
+  collection: "user",
+  mode: "crud",
+  fields: [
+    { name: "name", type: "string", required: true },
+    { name: "email", type: "string", required: true, primary: true },
+    { name: "age", type: "uint" },
+    { name: "role", type: "obj", ref: "role" },
+  ],
+  roles: ["admin:crud:*", "user:r:*"],
+};
+```
+
+### 3. Create Router
+
+```javascript
+const { init_router } = require("hola-server");
+
+const router = init_router(user_meta);
+module.exports = router;
+```
+
+### 4. Start Server
+
+```javascript
+const { init_express_server } = require("hola-server");
+
+init_express_server(__dirname, "service_port", async () => {
+  console.log("Server started on port 8088");
+});
+```
+
+## Entity Metadata
+
+### Field Types
+
+- `string` - String with trim
+- `int` - Integer
+- `uint` - Unsigned integer
+- `float` - Float with 2 decimal places
+- `ufloat` - Unsigned float
+- `number` - Any number
+- `boolean` - Boolean
+- `password` - Encrypted password
+- `array` - Array type
+- `obj` - Object/Reference type
+- `file` - File upload
+
+### Field Options
+
+- `required` - Field is required
+- `primary` - Primary key (unique)
+- `searchable` - Searchable in queries
+- `invisible` - Hidden from responses
+- `sys` - System field
+- `ref` - Reference to another entity
+- `delete` - Cascade behavior: `cascade` or `keep`
+
+### CRUD Modes
+
+- `c` - Create
+- `r` - Read
+- `u` - Update
+- `d` - Delete
+- `o` - Clone
+- `crud` - All operations
+
+### Role Configuration
+
+Format: `role_name:mode:view`
+
+Example:
+
+```javascript
+roles: [
+  "admin:crud:*", // Admin can do all operations on all views
+  "user:r:public", // User can only read public view
+  "editor:cru:edit", // Editor can create/read/update edit view
+];
+```
+
+## API Endpoints
+
+For an entity with `mode: 'crud'`:
+
+- `POST /{entity}/create` - Create entity
+- `POST /{entity}/query` - Query entities
+- `POST /{entity}/count` - Count entities
+- `POST /{entity}/update` - Update entity
+- `POST /{entity}/delete` - Delete entity
+- `POST /{entity}/clone` - Clone entity (if cloneable)
+
+## Core Utilities
+
+### Database
+
+```javascript
+const { get_db } = require("hola-server");
+
+const db = await get_db();
+const users = await db.collection("user").find({});
+```
+
+### Entity Operations
+
+```javascript
+const { Entity } = require("hola-server");
+
+const entity = new Entity(meta);
+await entity.create_entity(data);
+await entity.find_entity(query);
+await entity.update_entity(id, updates);
+await entity.delete_entity(id);
+```
+
+### Logging
+
+```javascript
+const { log_info, log_error } = require("hola-server");
+
+log_info("user", "User logged in", { user_id });
+log_error("auth", "Login failed", { email });
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Project Structure
+
+```
+hola-server/
+├── core/          # Core utilities (array, date, validate, etc.)
+├── db/            # Database layer (connection, entity, gridfs)
+├── http/          # HTTP layer (express, router, middleware)
+├── router/        # CRUD route handlers
+├── test/          # Test suite
+└── tool/          # Tools (i18n generation)
+```
+
+## License
+
+ISC

package/core/array.js

@@ -1,187 +1,124 @@
+/**
+ * @fileoverview Array manipulation utility functions.
+ * @module core/array
+ */
+
 const { round_to_fixed2 } = require('./number');
 
 /**
- * Shuffle the array randomly
- * 
- * @param {array to be shuffle} a 
+ * Shuffle array elements randomly in place.
+ * @param {Array} arr - Array to shuffle.
  */
-const shuffle = (a) => {
-    let j, x, i;
-    for (i = a.length; i; i--) {
-        j = Math.floor(Math.random() * i);
-        x = a[i - 1];
-        a[i - 1] = a[j];
-        a[j] = x;
+const shuffle = (arr) => {
+    for (let i = arr.length; i; i--) {
+        const j = Math.floor(Math.random() * i);
+        [arr[i - 1], arr[j]] = [arr[j], arr[i - 1]];
     }
-}
+};
 
 /**
- * Remove the object from array based on the attribute value of the object
- * @param {array of object} array 
- * @param {the attribute name of the object} field 
- * @param {the attribute value} value 
+ * Remove elements from array by matching field value.
+ * @param {Object[]} array - Array of objects to modify.
+ * @param {string} field - Field name to match.
+ * @param {*} value - Value to match for removal.
  */
 const remove_element = (array, field, value) => {
     for (let i = array.length - 1; i >= 0; --i) {
-        if (array[i][field] == value) {
-            array.splice(i, 1);
-        }
-    }
-}
-
-/**
- * Pop n elements from the array
- * @param {array of elements} array 
- * @param {n number of object to pop} n 
- * @returns 
- */
-const pop_n = (array, n) => {
-    const subarray = [];
-    while (subarray.length < n) {
-        const ele = array.pop();
-        if (ele) {
-            subarray.push(ele);
-        } else {
-            break;
-        }
-    }
-    if (subarray.length > 0) {
-        return subarray;
-    } else {
-        return undefined;
+        if (array[i][field] == value) array.splice(i, 1);
     }
-}
+};
 
 /**
- * Shift n elements from the array
- * @param {array of elements} array 
- * @param {n number of object to pop} n 
- * @returns 
+ * Extract n elements from array using specified method.
+ * @param {Array} array - Source array.
+ * @param {number} n - Number of elements to extract.
+ * @param {string} method - 'pop' or 'shift'.
+ * @returns {Array|undefined} Array of extracted elements or undefined if empty.
  */
-const shift_n = (array, n) => {
-    const subarray = [];
-    while (subarray.length < n) {
-        const ele = array.shift();
-        if (ele) {
-            subarray.push(ele);
-        } else {
-            break;
-        }
-    }
-    if (subarray.length > 0) {
-        return subarray;
-    } else {
-        return undefined;
+const extract_n = (array, n, method) => {
+    const result = [];
+    while (result.length < n) {
+        const ele = array[method]();
+        if (ele) result.push(ele);
+        else break;
     }
-}
-
-/**
- * Calculate the sum value of the array of the number
- * @param {array of number} arr 
- * @returns 
- */
-const sum = function (arr) {
-    return round_to_fixed2(arr.reduce((pre, cur) => pre + cur));
+    return result.length > 0 ? result : undefined;
 };
 
+const pop_n = (array, n) => extract_n(array, n, 'pop');
+const shift_n = (array, n) => extract_n(array, n, 'shift');
+
 /**
- * Calculate the average value of the array of number
- * @param {array of number} arr 
- * @returns 
+ * Calculate sum of number array.
+ * @param {number[]} arr - Array of numbers.
+ * @returns {number} Sum rounded to 2 decimal places.
  */
-const avg = function (arr) {
-    if (arr.length === 0) {
-        return 0;
-    } else {
-        return round_to_fixed2(sum(arr) / arr.length);
-    }
-};
+const sum = (arr) => round_to_fixed2(arr.reduce((pre, cur) => pre + cur, 0));
 
 /**
- * 
- * @param {array of object} arr 
- * @param {key attr of element as key} key_attr 
- * @param {value attr of element as value} value_attr 
- * @returns 
+ * Calculate average of number array.
+ * @param {number[]} arr - Array of numbers.
+ * @returns {number} Average rounded to 2 decimal places.
  */
-const map_array_to_obj = function (arr, key_attr, value_attr) {
-    const obj = {};
-    arr.forEach(element => {
-        obj[element[key_attr]] = element[value_attr];
-    });
-    return obj;
-}
+const avg = (arr) => arr.length === 0 ? 0 : round_to_fixed2(sum(arr) / arr.length);
 
 /**
- * Sort array of element based on the attr value in desc order
- * @param {array to be sort} arr 
- * @param {attribute used to do sorting} attr 
- * @returns 
+ * Convert array of objects to key-value object.
+ * @param {Object[]} arr - Array of objects.
+ * @param {string} key_attr - Attribute to use as key.
+ * @param {string} value_attr - Attribute to use as value.
+ * @returns {Object} Mapped object.
  */
-const sort_desc = function (arr, attr) {
-    arr.sort((a, b) => {
-        return b[attr] - a[attr];
-    });
-    return arr;
+const map_array_to_obj = (arr, key_attr, value_attr) => {
+    return arr.reduce((obj, el) => ({ ...obj, [el[key_attr]]: el[value_attr] }), {});
 };
 
 /**
- * Sort array of element based on the attr value in asc order
- * @param {array to be sort} arr 
- * @param {attribute used to do sorting} attr 
- * @returns 
+ * Sort array of objects by attribute.
+ * @param {Object[]} arr - Array to sort.
+ * @param {string} attr - Attribute name to sort by.
+ * @param {boolean} [desc=false] - Sort descending if true.
+ * @returns {Object[]} Sorted array.
  */
-const sort_asc = function (arr, attr) {
-    arr.sort((a, b) => {
-        return a[attr] - b[attr];
-    });
+const sort_by_attr = (arr, attr, desc = false) => {
+    arr.sort((a, b) => desc ? b[attr] - a[attr] : a[attr] - b[attr]);
     return arr;
 };
 
+const sort_desc = (arr, attr) => sort_by_attr(arr, attr, true);
+const sort_asc = (arr, attr) => sort_by_attr(arr, attr, false);
+
 /**
- * Use the keys sequence to sort the array
- * @param {array of object} arr 
- * @param {the attr used to do sorting } attr 
- * @param {the key values} keys 
- * @returns 
+ * Sort array by predefined key sequence.
+ * @param {Object[]} arr - Array to sort.
+ * @param {string} attr - Attribute name to sort by.
+ * @param {Array} keys - Ordered array of key values.
+ * @returns {Object[]} Sorted array.
  */
-const sort_by_key_seq = function (arr, attr, keys) {
-    arr.sort((a, b) => {
-        return keys.indexOf(a[attr]) - keys.indexOf(b[attr]);
-    });
+const sort_by_key_seq = (arr, attr, keys) => {
+    arr.sort((a, b) => keys.indexOf(a[attr]) - keys.indexOf(b[attr]));
     return arr;
 };
 
 /**
- * Create combination of two object, the size will be arr1.length * arr2.length
- * @param {array of object} arr1 
- * @param {array of object} arr2 
- * @returns 
+ * Create cartesian product of two object arrays.
+ * @param {Object[]} arr1 - First array.
+ * @param {Object[]} arr2 - Second array.
+ * @returns {Object[]} Combined array with length arr1.length * arr2.length.
  */
-const combine = (arr1, arr2) => {
-    const result = [];
-    for (let i = 0; i < arr1.length; i++) {
-        const obj1 = arr1[i];
-        for (let j = 0; j < arr2.length; j++) {
-            const obj2 = arr2[j];
-            result.push({ ...obj1, ...obj2 });
-        }
-    }
-    return result;
-}
+const combine = (arr1, arr2) => arr1.flatMap(obj1 => arr2.map(obj2 => ({ ...obj1, ...obj2 })));
 
 /**
- * Remove duplicate element and keep it unique
- * @param {array of elements} arr 
- * @returns 
+ * Remove duplicate elements from array.
+ * @param {Array} array - Array to deduplicate.
+ * @returns {Array} Array with unique elements.
  */
 const unique = (array) => {
-    return array.filter((value, index) => {
-        const _value = JSON.stringify(value);
-        return index === array.findIndex(obj => {
-            return JSON.stringify(obj) === _value;
-        });
+    const seen = new Map();
+    return array.filter(value => {
+        const key = JSON.stringify(value);
+        return seen.has(key) ? false : (seen.set(key, true), true);
     });
-}
+};
 
-module.exports = { shuffle, remove_element, pop_n, shift_n, sum, avg, combine, sort_desc, sort_asc, sort_by_key_seq, unique, map_array_to_obj }
+module.exports = { shuffle, remove_element, pop_n, shift_n, sum, avg, combine, sort_desc, sort_asc, sort_by_key_seq, unique, map_array_to_obj };