hola-server 1.0.10 → 2.0.1

package/core/meta.js

@@ -1,359 +1,283 @@
-const { is_undefined } = require('./validate');
+/**
+ * @fileoverview Meta programming core - Entity definition and validation.
+ * @module core/meta
+ *
+ * Field attributes:
+ * - name: Field name (required).
+ * - type: Data type (string, int, float, etc., default: "string").
+ * - required: Whether field is required (default: false).
+ * - default: Default value for the field. Value must be valid for the field type.
+ * - ref: Reference to another entity (collection name).
+ * - link: Link to another field in this entity (must be a field of type 'ref').
+ *         This field's value will be auto-populated from the referenced entity.
+ *         Only supports { name, link, list } attributes.
+ * - delete: Deletion behavior for ref fields.
+ *         - "keep": Keep this record when referenced entity is deleted.
+ *         - "cascade": Delete this record when referenced entity is deleted.
+ *         - Default: undefined (no action).
+ * - create: Show in create form (default: true).
+ * - list: Show in table list (default: true).
+ * - search: Show in search form (default: true).
+ * - update: Allow update (default: true).
+ * - clone: Include in clone (default: true).
+ * - sys: System field (server-side only, not sent to client unless explicitly needed).
+ * - secure: Hidden from client entirely (e.g., password hash).
+ * - group: User group sharing control (field name containing group ID).
+ * - view: Form view identifier - controls which form view(s) display this field.
+ *         - "*": All views (default for editable fields).
+ *         - "view_name": Specific view only.
+ *         Only applicable to editable fields (create !== false or update !== false).
+ *         Multiple form views can reference different subsets of fields for different contexts.
+ */
+
 const { get_type } = require('./type');
 const { validate_meta_role } = require('./role');
 
 const meta_manager = {};
-/**
- * create: this field can be shown in create form
- * list: this field can be shown in table list
- * search: this field can be shown in search form
- * update: if is false, in update form, it will be readonly status
- * delete: delete is only used for ref field, it decide when the ref entity will be deleted, how to handle this entity,no value, will not let the refered entity be deleted, keep: keep this entity(no data consistency), cascade: also delete this entity also,
- * sys: this field is used to control the user can set the value or not. sys field can only be set in the server side(before callback is good place to do this)
- * create is false, this attribute can be shown in property list but sys property can't be shown in property list 
- * secure: secure properties will not be read by client, this is useful for password
- * group: this is used to control user sharing entities, this means the entity is shared by user group, this is only valid for user field
- * view: this is used to control for edit form, for one entity, may have many forms to edit the entity, so use view to seperate them, this can be string or array
- * 
- * routes: configure customer defined routes
- * link property: field link property link to entity field and the field should ref to an entity.
- * and the field name should be the same with the ref entity field name and shouldn't make as required and no other property
- * 
- * 
-*/
-const field_attrs = ["name", "type", "required", "ref", "link", "delete", "create", "list", "search", "update", "clone", "sys", "secure", "group", "view"];
-const meta_attrs = ["collection", "roles", "primary_keys", "fields", "creatable", "readable", "updatable", "deleteable", "cloneable", "after_read", "list_query",
-    "before_create", "after_create", "before_clone", "after_clone", "before_update", "after_update", "before_delete", "after_delete", "create", "clone", "update", "batch_update", "after_batch_update", "delete",
-    "ref_label", "ref_filter", "route", "user_field"];
-
-const DELETE_MODE = Object.freeze({
-    all: ["keep", "cascade"],
-    keep: "keep",
-    cascade: "cascade"
-});
+
+const FIELD_ATTRS = ["name", "type", "required", "default", "ref", "link", "delete", "create", "list", "search", "update", "clone", "sys", "secure", "group", "view"];
+const LINK_FIELD_ATTRS = ["name", "link", "list"];
+const CALLBACK_NAMES = ["after_read", "list_query", "before_create", "before_clone", "before_update", "before_delete",
+    "after_create", "after_clone", "after_update", "after_delete", "create", "clone", "update", "batch_update", "after_batch_update", "delete"];
+const OPERATION_FLAGS = ["creatable", "readable", "updatable", "deleteable", "cloneable", "importable", "exportable"];
+const MODE_MAP = { creatable: "c", readable: "rs", updatable: "u", deleteable: "db", cloneable: "o", importable: "i", exportable: "e" };
+
+const META_ATTRS = ["collection", "roles", "primary_keys", "fields", ...OPERATION_FLAGS, ...CALLBACK_NAMES, "ref_label", "ref_filter", "route", "user_field"];
+const DELETE_MODE = Object.freeze({ all: ["keep", "cascade"], keep: "keep", cascade: "cascade" });
+
+/** Convert fields array to name-keyed map. */
+const to_fields_map = (fields) => fields.reduce((m, f) => { m[f.name] = f; return m; }, {});
+
+/** Format error message with meta context. */
+const meta_error = (collection, msg, field = null) => {
+    const prefix = field ? `meta:${collection},field:${field.name}` : `meta:${collection}`;
+    return new Error(`${prefix} ${msg}`);
+};
 
 /**
- * Validate the field attributes and keep them correct(also set default value)
- * @param {entity meta} meta 
- * @param {meta attribute field} field 
+ * Validate and normalize field definition.
+ * @param {Object} meta - Entity meta.
+ * @param {Object} field - Field definition.
+ * @throws {Error} If field configuration is invalid.
  */
 const validate_field = (meta, field) => {
-    if (!field.name) {
-        throw new Error("name attr is required for field:" + field + ", and meta:" + meta.collection);
-    }
+    if (!field.name) throw meta_error(meta.collection, `name attr required for field:${JSON.stringify(field)}`);
 
-    if (field.type) {
-        get_type(field.type);
-    } else {
-        if (!field.link) {
-            field.type = "string"
-        }
-    }
+    if (field.type) get_type(field.type);
+    else if (!field.link) field.type = "string";
 
-    if (meta.primary_keys.includes(field.name)) {
-        field.required = true;
+    if (meta.primary_keys.includes(field.name)) field.required = true;
+
+    // Validate default value against field type
+    if (field.default !== undefined && field.type) {
+        const type = get_type(field.type);
+        const result = type.convert(field.default);
+        if (result.err) throw meta_error(meta.collection, `invalid default value [${field.default}] for type [${field.type}]`, field);
     }
 
     if (field.ref && !field.link) {
         const ref_meta = meta_manager[field.ref];
-        if (!ref_meta) {
-            throw new Error("meta:" + meta.collection + ",field:" + field.name + " refers invalid meta:" + field.ref + "]");
-        }
+        if (!ref_meta) throw meta_error(meta.collection, `refers invalid meta:${field.ref}`, field);
+        if (!ref_meta.ref_label) throw meta_error(meta.collection, `refers meta:${field.ref} without ref_label`, field);
 
-        if (!ref_meta.ref_label) {
-            throw new Error("meta:" + meta.collection + ",field:" + field.name + " refers an meta:" + field.ref + " without ref_label");
-        }
-
-        const ref_by_collections = ref_meta.ref_by_metas.map(m => m.collection);
-        if (!ref_by_collections.includes(this.collection)) {
-            ref_meta.ref_by_metas.push(meta_manager[meta.collection]);
-        }
+        const ref_by_collections = ref_meta.ref_by_metas.map((m) => m.collection);
+        if (!ref_by_collections.includes(this.collection)) ref_meta.ref_by_metas.push(meta_manager[meta.collection]);
     }
 
     if (field.delete) {
-        if (!field.ref) {
-            throw new Error("meta:" + meta.collection + ",field:" + field.name + " doesn't let define delete in none ref field.");
-        }
-
-        const all_modes = DELETE_MODE.all;
-        if (!all_modes.includes(field.delete)) {
-            throw new Error("meta:" + meta.collection + ",field:" + field.name + " has invalid delete:" + field.delete + ", valid values:" + JSON.stringify(all_modes));
-        }
+        if (!field.ref) throw meta_error(meta.collection, `delete not allowed on non-ref field`, field);
+        if (!DELETE_MODE.all.includes(field.delete)) throw meta_error(meta.collection, `invalid delete:${field.delete}, valid:${JSON.stringify(DELETE_MODE.all)}`, field);
     }
 
     if (field.link) {
-        const keys = Object.keys(field);
-        const support_keys_for_links = ["name", "link", "list"]
-        keys.forEach(key => {
-            if (!support_keys_for_links.includes(key)) {
-                throw new Error("Link field just supports name, link,list property. The attribute [" + key + "] isn't supported for LINK field:" + JSON.stringify(field) + " and meta:" + meta.collection);
-            }
-        });
+        const invalid_keys = Object.keys(field).filter((k) => !LINK_FIELD_ATTRS.includes(k));
+        if (invalid_keys.length) throw meta_error(meta.collection, `Link field only supports ${LINK_FIELD_ATTRS.join(",")}. Unsupported:${invalid_keys.join(",")}`);
     }
 
-    const editable = (field.create != false) || (field.update != false);
-
-    if (field.view) {
-        if (!editable) {
-            throw new Error("view can just defined for editable (create/update) field only. Field:" + JSON.stringify(field) + "] and meta:" + meta.collection);
-        }
-    } else {
-        //no view defined for create/update field, then set view to default value "0"
-        if (editable) {
-            field.view = "0";
-        }
-    }
+    const editable = (field.create !== false) || (field.update !== false);
+    if (field.view && !editable) throw meta_error(meta.collection, `view only for editable fields`);
+    if (!field.view && editable) field.view = "*";
 
-    const keys = Object.keys(field);
-    keys.forEach(key => {
-        if (!field_attrs.includes(key)) {
-            throw new Error("The attribute [" + key + "] isn't supported now for field:" + JSON.stringify(field) + " and meta:" + meta.collection);
-        }
-    });
-}
+    const invalid_attrs = Object.keys(field).filter((k) => !FIELD_ATTRS.includes(k));
+    if (invalid_attrs.length) throw meta_error(meta.collection, `Unsupported attribute [${invalid_attrs.join(",")}] for field:${JSON.stringify(field)}`);
+};
 
 /**
- * Validate all the fields
- * @param {entity meta} meta 
- * @param {meta fields} fields 
+ * Validate all fields in meta definition.
+ * @param {Object} meta - Entity meta.
+ * @param {Object[]} fields - Field definitions.
+ * @returns {boolean} True if valid.
+ * @throws {Error} If validation fails.
  */
 const validate_fields = (meta, fields) => {
-    const fields_map = fields.reduce((map, field) => { map[field.name] = field; return map; }, {});
-    const check_duplicate_field_names = [];
+    const fields_map = to_fields_map(fields);
+    const seen_names = new Set();
 
-    fields.forEach(field => {
+    for (const field of fields) {
         validate_field(meta, field);
-        if (check_duplicate_field_names.includes(field.name)) {
-            throw new Error("Duplicate field defined [" + JSON.stringify(field) + "] for meta:" + meta.collection);
-        } else {
-            check_duplicate_field_names.push(field.name);
-        }
+
+        if (seen_names.has(field.name)) throw meta_error(meta.collection, `Duplicate field [${JSON.stringify(field)}]`);
+        seen_names.add(field.name);
+
         if (field.link) {
             const link_field = fields_map[field.link];
-            if (!link_field) {
-                throw new Error("link field [" + JSON.stringify(field) + "] should link to one field defined in meta:" + meta.collection);
-            } else {
-                if (!link_field.ref) {
-                    throw new Error("link field [" + JSON.stringify(field) + "] link to field [" + JSON.stringify(link_field) + "] should ref to one entity in meta:" + meta.collection);
-                }
-                const entity = get_entity_meta(link_field.ref);
-                const link_entity_field = entity.fields_map[field.name];
-                if (!link_entity_field) {
-                    throw new Error("link field [" + JSON.stringify(field) + "] should link to one field defined in meta:" + entity.collection);
-                }
+            if (!link_field) throw meta_error(meta.collection, `link field [${JSON.stringify(field)}] should link to field`);
+            if (!link_field.ref) throw meta_error(meta.collection, `link field [${JSON.stringify(field)}] target [${JSON.stringify(link_field)}] must ref entity`);
 
-                //set type to link field type
-                field.type = link_entity_field.type;
-                field.required = false;
-                field.create = false;
-                field.search = false;
-                field.update = false;
-                field.clone = false;
-                field.delete = "cascade";
-
-                if (link_entity_field.ref) {
-                    field.ref = link_entity_field.ref;
-                }
-            }
-        }
-    });
+            const entity = get_entity_meta(link_field.ref);
+            const link_entity_field = entity.fields_map[field.name];
+            if (!link_entity_field) throw meta_error(entity.collection, `link field [${JSON.stringify(field)}] should link to field`);
 
+            Object.assign(field, { type: link_entity_field.type, required: false, create: false, search: false, update: false, clone: false, delete: "cascade" });
+            if (link_entity_field.ref) field.ref = link_entity_field.ref;
+        }
+    }
     return true;
-}
+};
 
-/**
- * Validate all the metas information after loading all the meta information
- */
-const validate_all_metas = () => {
-    const metas = Object.keys(meta_manager);
-    metas.forEach(meta_name => {
-        const meta = meta_manager[meta_name];
-        meta.validate_meta_info();
-    });
-}
+/** Validate all registered metas after loading. */
+const validate_all_metas = () => Object.values(meta_manager).forEach((m) => m.validate_meta_info());
 
 /**
- * Set function name for the entity 
- * @param {entity meta} entity_meta 
- * @param {cb function name} cb_name 
- * @param {callback function} cb 
+ * Set callback function on entity meta.
+ * @param {Object} entity_meta - Entity meta object.
+ * @param {string} cb_name - Callback name.
+ * @param {Function} cb - Callback function.
+ * @throws {Error} If callback is not a function.
  */
 const set_callback = (entity_meta, cb_name, cb) => {
-    if (cb) {
-        if (cb instanceof Function) {
-            entity_meta[cb_name] = cb;
-        } else {
-            throw new Error("callback [" + cb_name + "] configured for meta:" + meta.collection + " isn't function object");
-        }
-    }
-}
+    if (!cb) return;
+    if (!(cb instanceof Function)) throw new Error(`callback [${cb_name}] for meta:${entity_meta.collection} isn't function`);
+    entity_meta[cb_name] = cb;
+};
 
-/**
- * Get entity meta object
- * @param {meta collection name} collection 
- * @returns 
- */
-const get_entity_meta = (collection) => {
-    return meta_manager[collection];
-}
+/** Get entity meta by collection name. */
+const get_entity_meta = (collection) => meta_manager[collection];
 
-/**
- * Get all the meta name
- * @returns 
- */
-const get_all_metas = () => {
-    return Object.keys(meta_manager);
-}
+/** Get all registered meta collection names. */
+const get_all_metas = () => Object.keys(meta_manager);
 
 
 /**
- * Wrap the meta info from user side:
- * 1) validate the meta structure and keep it is valid
- * 2) set the default values of the meta
+ * Entity Meta wrapper class.
+ * Validates meta structure and sets default values.
  */
 class EntityMeta {
-
+    /**
+     * Create EntityMeta instance.
+     * @param {Object} meta - Meta definition object.
+     * @throws {Error} If duplicate meta registered.
+     */
     constructor(meta) {
         this.meta = meta;
-        this.collection = this.meta.collection;
-        this.roles = this.meta.roles;
-
-        this.creatable = is_undefined(meta.creatable) ? false : meta.creatable;
-        this.readable = is_undefined(meta.readable) ? false : meta.readable;
-        this.updatable = is_undefined(meta.updatable) ? false : meta.updatable;
-        this.deleteable = is_undefined(meta.deleteable) ? false : meta.deleteable;
-        this.cloneable = is_undefined(meta.cloneable) ? false : meta.cloneable;
-        this.importable = is_undefined(meta.importable) ? false : meta.importable;
-        this.exportable = is_undefined(meta.exportable) ? false : meta.exportable;
+        this.collection = meta.collection;
+        this.roles = meta.roles;
+        this.primary_keys = meta.primary_keys;
+        this.user_field = meta.user_field;
+        this.ref_label = meta.ref_label;
+        this.ref_filter = meta.ref_filter;
+
+        // Set operation flags with defaults
+        OPERATION_FLAGS.forEach((flag) => { this[flag] = meta[flag] ?? false; });
         this.editable = this.creatable || this.updatable;
 
-        //b:batch mode, c:create, d:delete, e:export, i:import, o:clone, p:page, r: refresh, s:search, u:update
-        const modes = [];
-        this.creatable && (modes.push("c"));
-        //prefer the infinite scrolling mode, so doesn't include p mode
-        this.readable && (modes.push("rs"));
-        this.updatable && (modes.push("u"));
-        this.deleteable && (modes.push("db"));
-        this.cloneable && (modes.push("o"));
-        this.importable && (modes.push("i"));
-        this.exportable && (modes.push("e"));
-        this.mode = modes.join("");
-
-        this.ref_label = this.meta.ref_label;
-        this.ref_filter = this.meta.ref_filter;
-        this.ref_fields = this.meta.fields.filter(field => field.ref);
-        this.ref_by_metas = [];
+        // Build mode string
+        this.mode = OPERATION_FLAGS.filter((f) => this[f]).map((f) => MODE_MAP[f]).join("");
 
-        this.link_fields = this.meta.fields.filter(field => field.link);
-        this.fields_map = meta.fields.reduce((map, field) => { map[field.name] = field; return map; }, {});
+        // Field organization
         this.fields = meta.fields;
-        this.primary_keys = meta.primary_keys;
-        this.field_names = this.fields.map(field => field.name);
-        this.user_field = meta.user_field;
+        this.fields_map = to_fields_map(meta.fields);
+        this.field_names = this.fields.map((f) => f.name);
+        this._init_field_subsets(meta);
 
-        this.client_fields = this.fields.filter(field => field.sys != true);
-        this.property_fields = this.fields.filter(field => field.sys != true && field.secure != true);
-        this.create_fields = this.fields.filter(field => field.create != false && field.sys != true);
-        this.update_fields = this.fields.filter(field => field.create != false && field.update != false && field.sys != true);
-        this.search_fields = this.fields.filter(field => field.search != false && field.sys != true);
-        this.clone_fields = this.fields.filter(field => field.clone != false && field.sys != true);
-        this.list_fields = this.fields.filter(field => field.list != false && field.sys != true && field.secure != true);
-        this.primary_key_fields = this.fields.filter(field => meta.primary_keys.includes(field.name));
-        this.required_field_names = this.fields.filter(field => field.required == true || this.primary_keys.includes(field.name)).map(field => field.name);
-
-        this.file_fields = meta.fields.filter(f => f.type === 'file');
-        this.upload_fields = this.file_fields && this.file_fields.length > 0 ? this.file_fields.map(f => ({ name: f.name })) : [];
-
-        set_callback(this, "after_read", meta.after_read);
-        set_callback(this, "list_query", meta.list_query);
-        set_callback(this, "before_create", meta.before_create);
-        set_callback(this, "before_clone", meta.before_clone);
-        set_callback(this, "before_update", meta.before_update);
-        set_callback(this, "before_delete", meta.before_delete);
-        set_callback(this, "after_create", meta.after_create);
-        set_callback(this, "after_clone", meta.after_clone);
-        set_callback(this, "after_update", meta.after_update);
-        set_callback(this, "after_delete", meta.after_delete);
-        set_callback(this, "create", meta.create);
-        set_callback(this, "clone", meta.clone);
-        set_callback(this, "update", meta.update);
-        set_callback(this, "batch_update", meta.batch_update);
-        set_callback(this, "after_batch_update", meta.after_batch_update);
-        set_callback(this, "delete", meta.delete);
-
-        if (meta_manager[meta.collection]) {
-            throw new Error("Duplicate meta info:" + this.collection);
-        } else {
-            meta_manager[meta.collection] = this;
-        }
+        // Reference handling
+        this.ref_fields = this.fields.filter((f) => f.ref);
+        this.link_fields = this.fields.filter((f) => f.link);
+        this.ref_by_metas = [];
+
+        // Set callbacks and register meta
+        CALLBACK_NAMES.forEach((cb) => set_callback(this, cb, meta[cb]));
+        if (meta_manager[meta.collection]) throw new Error(`Duplicate meta info:${this.collection}`);
+        meta_manager[meta.collection] = this;
     }
 
-    validate_meta_info() {
-        if (!this.collection) {
-            throw new Error("no collection defined for meta:" + this.meta);
-        }
+    /** Initialize field subsets for different operations. @private */
+    _init_field_subsets(meta) {
+        const not_sys = (f) => f.sys !== true;
+        const not_secure = (f) => f.secure !== true;
+
+        this.client_fields = this.fields.filter(not_sys);
+        this.property_fields = this.fields.filter((f) => not_sys(f) && not_secure(f));
+        this.create_fields = this.fields.filter((f) => f.create !== false && not_sys(f));
+        this.update_fields = this.fields.filter((f) => f.create !== false && f.update !== false && not_sys(f));
+        this.search_fields = this.fields.filter((f) => f.search !== false && not_sys(f));
+        this.clone_fields = this.fields.filter((f) => f.clone !== false && not_sys(f));
+        this.list_fields = this.fields.filter((f) => f.list !== false && not_sys(f) && not_secure(f));
+        this.primary_key_fields = this.fields.filter((f) => meta.primary_keys.includes(f.name));
+        this.required_field_names = this.fields.filter((f) => f.required === true || this.primary_keys.includes(f.name)).map((f) => f.name);
+        this.file_fields = this.fields.filter((f) => f.type === 'file');
+        this.upload_fields = this.file_fields.map((f) => ({ name: f.name }));
+    }
 
-        const keys = Object.keys(this.meta);
-        keys.forEach(key => {
-            if (!meta_attrs.includes(key)) {
-                throw new Error("The attribute [" + key + "] isn't supported now for meta:" + this.meta.collection);
-            }
-        });
-
-        if (!this.primary_keys) {
-            throw new Error("no primary_keys configured for meta:" + this.collection);
-        } else if (!Array.isArray(this.primary_keys)) {
-            throw new Error("primary_keys of meta [" + this.collection + "] should be array");
-        } else {
-            this.primary_keys.forEach(key => {
-                if (!this.field_names.includes(key)) {
-                    throw new Error("wrong primary_key " + key + " configured in meta:" + this.collection);
-                }
-            });
-        }
+    /**
+     * Validate meta information.
+     * @returns {boolean} True if valid.
+     * @throws {Error} If validation fails.
+     */
+    validate_meta_info() {
+        if (!this.collection) throw new Error(`no collection defined for meta:${JSON.stringify(this.meta)}`);
 
-        if (this.roles) {
-            if (!Array.isArray(this.roles)) {
-                throw new Error("roles of meta [" + this.collection + "] should be array");
-            }
+        const invalid_attrs = Object.keys(this.meta).filter((k) => !META_ATTRS.includes(k));
+        if (invalid_attrs.length) throw meta_error(this.collection, `Unsupported attribute [${invalid_attrs.join(",")}]`);
 
-            this.roles.forEach(role => {
-                const role_config = role.split(":");
-                if (!(role_config.length == 2 || role_config.length == 3)) {
-                    throw new Error("wrong role config [" + role + "] in meta [" + this.collection + "]. You should use : to seperate the role name with mode.");
-                }
+        this._validate_primary_keys();
+        this._validate_roles();
+        this._validate_field_exists("ref_label", this.ref_label);
+        this._validate_field_exists("user_field", this.user_field);
+        if (this.ref_filter && this.ref_filter.constructor !== Object) {
+            throw meta_error(this.collection, `ref_filter should be object`);
+        }
 
-                const role_name = role_config[0];
-                if (!validate_meta_role(role_name)) {
-                    throw new Error("role [" + role_name + "] in meta [" + this.collection + "] not defined in setting's role config.");
-                }
+        return validate_fields(this.meta, this.fields);
+    }
 
-                const role_mode = role_config[1];
-                if (role_mode != "*") {
-                    for (let i = 0; i < role_mode.length; i++) {
-                        const mode = role_mode.charAt(i);
-                        if (!this.mode.includes(mode)) {
-                            throw new Error("role [" + role_name + "] in meta [" + this.collection + "] with mode [" + mode + "] doesn't comply with entity mode [" + this.mode + "]");
-                        }
-                    }
-                }
-            });
+    /** Validate primary keys configuration. @private */
+    _validate_primary_keys() {
+        if (!this.primary_keys) throw meta_error(this.collection, `no primary_keys defined`);
+        if (!Array.isArray(this.primary_keys)) throw meta_error(this.collection, `primary_keys should be array`);
+        for (const key of this.primary_keys) {
+            if (!this.field_names.includes(key)) throw meta_error(this.collection, `wrong primary_key ${key}`);
         }
+    }
 
-        if (this.ref_label && !this.field_names.includes(this.ref_label)) {
-            throw new Error("ref_label [" + this.ref_label + "] configured in meta:" + this.collection + " not found in field names");
+    /** Validate a field name exists in fields. @private */
+    _validate_field_exists(attr_name, value) {
+        if (value && !this.field_names.includes(value)) {
+            throw meta_error(this.collection, `${attr_name} [${value}] not found in fields`);
         }
+    }
 
-        if (this.user_field && !this.field_names.includes(this.user_field)) {
-            throw new Error("user_field [" + this.user_field + "] configured in meta:" + this.collection + " not found in field names");
-        }
+    /** Validate roles configuration. @private */
+    _validate_roles() {
+        if (!this.roles) return;
+        if (!Array.isArray(this.roles)) throw meta_error(this.collection, `roles should be array`);
 
-        if (this.ref_filter && (this.ref_filter.constructor != Object)) {
-            throw new Error("ref_filter [" + this.ref_filter + "] configured in meta:" + this.collection + " should be object");
-        }
+        for (const role of this.roles) {
+            const parts = role.split(":");
+            if (parts.length < 2 || parts.length > 3) {
+                throw meta_error(this.collection, `wrong role config [${role}]. Use : to separate role name with mode.`);
+            }
 
-        return validate_fields(this.meta, this.fields);
+            const [role_name, role_mode] = parts;
+            if (!validate_meta_role(role_name)) throw meta_error(this.collection, `role [${role_name}] not defined in settings`);
+
+            if (role_mode !== "*") {
+                for (const mode of role_mode) {
+                    if (!this.mode.includes(mode)) throw meta_error(this.collection, `role [${role_name}] mode [${mode}] doesn't match entity mode [${this.mode}]`);
+                }
+            }
+        }
     }
 }
 
-module.exports = { EntityMeta, validate_all_metas, get_entity_meta, get_all_metas, DELETE_MODE }
+module.exports = { EntityMeta, validate_all_metas, get_entity_meta, get_all_metas, DELETE_MODE };

package/core/msg.js

@@ -1,11 +1,24 @@
+/**
+ * @fileoverview Message sending utility functions using wxmnode.
+ * @module core/msg
+ */
+
 const wxm = require('wxmnode');
 
-const init_wxm = (name, password) => {
-    wxm.init(name, password);
-}
+/**
+ * Initialize wxm with credentials.
+ * @param {string} name - Account name.
+ * @param {string} password - Account password.
+ */
+const init_wxm = (name, password) => wxm.init(name, password);
 
-const send_msg = async (content, type, detail) => {
-    return await wxm.sendMsg(content, type, detail);
-}
+/**
+ * Send message via wxm.
+ * @param {string} content - Message content.
+ * @param {string} type - Message type.
+ * @param {Object} detail - Additional message details.
+ * @returns {Promise<Object>} Message send result.
+ */
+const send_msg = async (content, type, detail) => await wxm.sendMsg(content, type, detail);
 
-module.exports = { init_wxm, send_msg }
+module.exports = { init_wxm, send_msg };