@via-profit/ability 2.1.0 → 3.0.1

package/dist/index.js

@@ -70,11 +70,26 @@ class AbilityCondition extends AbilityCode_1.default {
     static in = new AbilityCondition('in');
     static not_in = new AbilityCondition('not in');
     static fromLiteral(literal) {
-        const code = AbilityCondition[literal]?.code || null;
-        if (code === null) {
-            throw new AbilityError_1.AbilityParserError(`Literal ${literal} does not found in AbilityCondition class`);
+        switch (literal) {
+            case 'equal':
+                return this.equal;
+            case 'not_equal':
+                return this.not_equal;
+            case 'more_than':
+                return this.more_than;
+            case 'less_than':
+                return this.less_than;
+            case 'less_or_equal':
+                return this.less_or_equal;
+            case 'more_or_equal':
+                return this.more_or_equal;
+            case 'in':
+                return this.in;
+            case 'not_in':
+                return this.not_in;
+            default:
+                throw new AbilityError_1.AbilityParserError(`Literal ${literal} does not found in AbilityCondition class`);
         }
-        return new AbilityCondition(code);
     }
     get literal() {
         const literal = Object.keys(AbilityCondition).find(member => {
@@ -113,6 +128,74 @@ class AbilityParserError extends Error {
 exports.AbilityParserError = AbilityParserError;
 
 
+/***/ }),
+
+/***/ 363:
+/***/ (function(__unused_webpack_module, exports, __webpack_require__) {
+
+
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.AbilityExplainPolicy = exports.AbilityExplainRuleSet = exports.AbilityExplainRule = exports.AbilityExplain = void 0;
+const AbilityMatch_1 = __importDefault(__webpack_require__(909));
+class AbilityExplain {
+    type;
+    children;
+    name;
+    match;
+    constructor(config, children = []) {
+        this.type = config.type;
+        this.children = children;
+        this.name = config.name;
+        this.match = config.match;
+    }
+    toString(indent = 0) {
+        const pad = ' '.repeat(indent);
+        const mark = this.match.code === AbilityMatch_1.default.match.code ? '✓' : '✗';
+        let out = `${pad}${mark} ${this.type} «${this.name}» is ${this.match.code}`;
+        this.children.forEach(child => {
+            out += '\n' + child.toString(indent + 1);
+        });
+        return out;
+    }
+}
+exports.AbilityExplain = AbilityExplain;
+class AbilityExplainRule extends AbilityExplain {
+    constructor(rule) {
+        super({
+            type: 'rule',
+            match: rule.state,
+            name: rule.name,
+        });
+    }
+}
+exports.AbilityExplainRule = AbilityExplainRule;
+class AbilityExplainRuleSet extends AbilityExplain {
+    constructor(ruleSet) {
+        const children = ruleSet.rules.map(rule => new AbilityExplainRule(rule));
+        super({
+            type: 'ruleSet',
+            match: ruleSet.state,
+            name: ruleSet.name,
+        }, children);
+    }
+}
+exports.AbilityExplainRuleSet = AbilityExplainRuleSet;
+class AbilityExplainPolicy extends AbilityExplain {
+    constructor(policy) {
+        const children = policy.ruleSet.map(ruleSet => new AbilityExplainRuleSet(ruleSet));
+        super({
+            type: 'policy',
+            name: policy.name,
+            match: policy.matchState,
+        }, children);
+    }
+}
+exports.AbilityExplainPolicy = AbilityExplainPolicy;
+
+
 /***/ }),
 
 /***/ 909:
@@ -148,20 +231,6 @@ exports.AbilityParser = void 0;
 const AbilityError_1 = __webpack_require__(122);
 const AbilityCondition_1 = __importDefault(__webpack_require__(261));
 class AbilityParser {
-    /*
-     *
-     *  readonly ['order.update']: {
-     *     readonly user: {
-     *       readonly roles: readonly string[];
-     *       readonly department: string;
-     *     };
-     *     readonly order: {
-     *       readonly estimatedArrivalAt: number;
-     *       readonly status: string;
-     *     }
-     *  }
-     *
-     * */
     /**
      * Sets a value in a nested object structure based on a dot/bracket notation path.
      * @param object - The target object to modify.
@@ -169,52 +238,222 @@ class AbilityParser {
      * @param value - The value to set at the specified path.
      */
     static setValueDotValue(object, path, value) {
-        const way = path.replace(/\[/g, '.').replace(/\]/g, '').split('.');
+        if (!path || path.trim().length === 0) {
+            throw new AbilityError_1.AbilityParserError(`Invalid path provided on a [${path}]`);
+        }
+        const way = path.replace(/\[/g, '.').replace(/]/g, '').split('.');
         const last = way.pop();
         if (!last) {
             throw new AbilityError_1.AbilityParserError(`Invalid path provided on a [${path}]`);
         }
-        way.reduce((o, k, i, kk) => {
-            if (!o[k]) {
-                o[k] = isFinite(Number(kk[i + 1])) ? [] : {};
+        const lastObj = way.reduce((acc, key, index, array) => {
+            const currentValue = acc[key];
+            const nextKey = array[index + 1];
+            const shouldBeArray = nextKey !== undefined && isFinite(Number(nextKey));
+            if (currentValue === undefined || currentValue === null) {
+                // Create missing property
+                const newValue = shouldBeArray ? [] : {};
+                acc[key] = newValue;
+                return newValue;
             }
-            return o[k];
-        }, object)[last] = value;
+            if (typeof currentValue !== 'object') {
+                throw new AbilityError_1.AbilityParserError(`Cannot set property '${key}' on non-object value at path: ${path}`);
+            }
+            return currentValue;
+        }, object);
+        const existingValue = lastObj[last];
+        if (existingValue !== undefined &&
+            typeof existingValue === 'object' &&
+            existingValue !== null &&
+            !Array.isArray(existingValue)) {
+            throw new AbilityError_1.AbilityParserError(`Cannot set primitive value on existing object at path: ${path}`);
+        }
+        lastObj[last] = value;
     }
     /**
      * Generates TypeScript type definitions based on the provided policies.
      * @param policies - An array of AbilityPolicy instances.
-     * @param outPath - The output path for the generated type definitions.
-     * @returns A record containing the generated type definitions.
+     * @returns A generated type definitions.
      */
-    static generateTypeDefs(policies, outPath) {
-        const record = {};
+    static generateTypeDefs(policies) {
+        // Structure to store types: { [action]: { [subjectPath]: type } }
+        const typeStructure = {};
+        // Iterate through all policies
         policies.forEach(policy => {
+            const action = policy.action;
+            // Initialize object for action if it doesn't exist
+            if (!typeStructure[action]) {
+                typeStructure[action] = {};
+            }
+            // Iterate through all ruleSets in the policy
             policy.ruleSet.forEach(ruleSet => {
+                // Iterate through all rules in the ruleSet
                 ruleSet.rules.forEach(rule => {
-                    let value = 'any';
-                    switch (true) {
-                        case rule.condition.isEqual(AbilityCondition_1.default.not_equal):
-                        case rule.condition.isEqual(AbilityCondition_1.default.equal):
-                            value = typeof rule.resource;
-                            break;
-                        case rule.condition.isEqual(AbilityCondition_1.default.in):
-                        case rule.condition.isEqual(AbilityCondition_1.default.not_in):
-                            value = `${typeof rule.resource}[]`;
-                            break;
-                        case rule.condition.isEqual(AbilityCondition_1.default.more_or_equal):
-                        case rule.condition.isEqual(AbilityCondition_1.default.more_than):
-                        case rule.condition.isEqual(AbilityCondition_1.default.less_or_equal):
-                        case rule.condition.isEqual(AbilityCondition_1.default.less_than):
-                            value = 'number';
-                            break;
+                    const subjectPath = rule.subject;
+                    const existingType = typeStructure[action][subjectPath];
+                    const ruleType = this.determineTypeFromRule(rule);
+                    // If a type already exists for this path, create a union
+                    if (existingType && existingType !== ruleType) {
+                        typeStructure[action][subjectPath] = `${existingType} | ${ruleType}`;
+                    }
+                    else {
+                        typeStructure[action][subjectPath] = ruleType;
                     }
-                    AbilityParser.setValueDotValue(record, rule.subject, value);
                 });
             });
         });
-        console.log(JSON.stringify(record));
-        return record;
+        // Transform flat structure into nested structure for easier use
+        const nestedStructure = this.buildNestedStructure(typeStructure);
+        return this.formatTypeDefinitions(nestedStructure);
+    }
+    /**
+     * Determines TypeScript type based on the rule
+     * @param rule - The rule to analyze
+     * @returns TypeScript type as string
+     */
+    static determineTypeFromRule(rule) {
+        // Numeric comparisons - always number
+        if (rule.condition.isEqual(AbilityCondition_1.default.more_than) ||
+            rule.condition.isEqual(AbilityCondition_1.default.less_than) ||
+            rule.condition.isEqual(AbilityCondition_1.default.more_or_equal) ||
+            rule.condition.isEqual(AbilityCondition_1.default.less_or_equal)) {
+            return 'number';
+        }
+        // Array operations
+        if (rule.condition.isEqual(AbilityCondition_1.default.in) ||
+            rule.condition.isEqual(AbilityCondition_1.default.not_in)) {
+            return this.getArrayType(rule.resource);
+        }
+        // Equality/Inequality operations
+        if (rule.condition.isEqual(AbilityCondition_1.default.equal) ||
+            rule.condition.isEqual(AbilityCondition_1.default.not_equal)) {
+            return this.getPrimitiveType(rule.resource);
+        }
+        return 'any';
+    }
+    /**
+     * Gets TypeScript type for array values
+     * @param resource - The resource value to analyze
+     * @returns TypeScript array type as string
+     */
+    static getArrayType(resource) {
+        if (Array.isArray(resource)) {
+            if (resource.length === 0)
+                return 'any[]';
+            // Determine types of array elements
+            const elementTypes = new Set(resource.map(item => this.getPrimitiveType(item)));
+            const elementType = elementTypes.size === 1
+                ? Array.from(elementTypes)[0]
+                : `(${Array.from(elementTypes).join(' | ')})`;
+            return `${elementType}[]`;
+        }
+        // If resource is not an array but condition is in/not_in,
+        // it expects an array of such elements
+        return `${this.getPrimitiveType(resource)}[]`;
+    }
+    /**
+     * Gets primitive TypeScript type for a value
+     * @param value - The value to analyze
+     * @returns TypeScript primitive type as string
+     */
+    static getPrimitiveType(value) {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        switch (typeof value) {
+            case 'string':
+                return 'string';
+            case 'number':
+                return 'number';
+            case 'boolean':
+                return 'boolean';
+            case 'object':
+                if (Array.isArray(value)) {
+                    return 'array'; // special marker, handled separately
+                }
+                return 'object';
+            default:
+                return 'any';
+        }
+    }
+    /**
+     * Builds nested structure from flat paths
+     * Example: 'user.profile.name' -> { user: { profile: { name: 'string' } } }
+     * @param flatStructure - Flat structure with dot notation paths
+     * @returns Nested object structure
+     */
+    static buildNestedStructure(flatStructure) {
+        const result = {};
+        Object.entries(flatStructure).forEach(([action, paths]) => {
+            result[action] = {};
+            Object.entries(paths).forEach(([path, type]) => {
+                const parts = path.split('.');
+                let current = result[action];
+                // Iterate through all parts except the last one
+                for (let i = 0; i < parts.length - 1; i++) {
+                    const part = parts[i];
+                    const currentValue = current[part];
+                    if (!currentValue || typeof currentValue !== 'object') {
+                        const newObj = {};
+                        current[part] = newObj;
+                        current = newObj;
+                    }
+                    else {
+                        current = currentValue;
+                    }
+                }
+                // Set type for the last part
+                const lastPart = parts[parts.length - 1];
+                current[lastPart] = type;
+            });
+        });
+        return result;
+    }
+    /**
+     * Formats type structure into a string
+     * @param structure - Nested type structure
+     * @returns Formatted TypeScript type definition string
+     */
+    static formatTypeDefinitions(structure) {
+        let output = '// Automatically generated by via-profit/ability\n';
+        output += '// Do not edit manually\n\n';
+        output += 'export type Resources = {\n';
+        // Sort actions for stable output
+        const sortedActions = Object.keys(structure).sort();
+        sortedActions.forEach(action => {
+            output += `  ['${action}']: {\n`;
+            output += this.formatNestedObject(structure[action], 4);
+            output += '  };\n';
+        });
+        output += '}\n';
+        return output;
+    }
+    /**
+     * Recursively formats nested object
+     * @param obj - Object to format
+     * @param indent - Current indentation level
+     * @returns Formatted string
+     */
+    static formatNestedObject(obj, indent) {
+        const spaces = ' '.repeat(indent);
+        let output = '';
+        // Sort keys for stable output
+        const sortedKeys = Object.keys(obj).sort();
+        sortedKeys.forEach(key => {
+            const value = obj[key];
+            if (typeof value === 'object' && value !== null) {
+                // Nested object
+                output += `${spaces}readonly ${key}: {\n`;
+                output += this.formatNestedObject(value, indent + 2);
+                output += `${spaces}};\n`;
+            }
+            else {
+                // Primitive type
+                output += `${spaces}readonly ${key}: ${value};\n`;
+            }
+        });
+        return output;
     }
 }
 exports.AbilityParser = AbilityParser;
@@ -236,6 +475,8 @@ const AbilityRuleSet_1 = __importDefault(__webpack_require__(402));
 const AbilityMatch_1 = __importDefault(__webpack_require__(909));
 const AbilityCompare_1 = __importDefault(__webpack_require__(923));
 const AbilityPolicyEffect_1 = __importDefault(__webpack_require__(277));
+const AbilityExplain_1 = __webpack_require__(363);
+const AbilityError_1 = __webpack_require__(122);
 class AbilityPolicy {
     matchState = AbilityMatch_1.default.pending;
     /**
@@ -262,15 +503,17 @@ class AbilityPolicy {
      */
     id;
     /**
-     * Soon
+     * Running the `enforce` or `resolve` method
+     * will select only those from all passed policies that fall under the specified action.
      */
     action;
     constructor(params) {
-        const { name, id, action, effect } = params;
+        const { name, id, action, effect, compareMethod = AbilityCompare_1.default.and } = params;
         this.name = name;
         this.id = id;
         this.action = action;
         this.effect = effect;
+        this.compareMethod = compareMethod;
     }
     /**
      * Add rule set to the policy
@@ -304,6 +547,20 @@ class AbilityPolicy {
         }
         return this.matchState;
     }
+    explain() {
+        if (this.matchState === AbilityMatch_1.default.pending) {
+            throw new AbilityError_1.AbilityError('First, run the check method, then explain');
+        }
+        return new AbilityExplain_1.AbilityExplainPolicy(this);
+    }
+    /**
+     * Parses an array of policy configurations into an array of AbilityPolicy instances.
+     * @param configs - Array of policy configurations
+     * @returns Array of AbilityPolicy instances
+     */
+    static parseAll(configs) {
+        return configs.map(config => this.parse(config));
+    }
     /**
      * Parse the config JSON format to Policy class instance
      */
@@ -371,6 +628,7 @@ exports.AbilityResolver = void 0;
 const AbilityPolicyEffect_1 = __importDefault(__webpack_require__(277));
 const AbilityMatch_1 = __importDefault(__webpack_require__(909));
 const AbilityError_1 = __webpack_require__(122);
+const AbilityExplain_1 = __webpack_require__(363);
 class AbilityResolver {
     policies;
     constructor(policyOrListOfPolicies) {
@@ -392,6 +650,11 @@ class AbilityResolver {
         this.policies = filteredPolicies;
         return this;
     }
+    resolveWithExplain(action, resource) {
+        return this.resolve(action, resource).policies.map(policy => {
+            return new AbilityExplain_1.AbilityExplainPolicy(policy);
+        });
+    }
     enforce(action, resource) {
         const resolver = this.resolve(action, resource);
         if (resolver.isDeny()) {
@@ -489,8 +752,8 @@ class AbilityRule {
      */
     constructor(params) {
         const { id, name, subject, resource, condition } = params;
-        this.id = id;
-        this.name = name;
+        this.name = name || `${JSON.stringify(subject)} ${condition.code} ${JSON.stringify(resource)}`;
+        this.id = id || this.name;
         this.subject = subject;
         this.resource = resource;
         this.condition = condition;
@@ -628,6 +891,62 @@ class AbilityRule {
             condition: this.condition.code,
         };
     }
+    static equal(subject, resource) {
+        return new AbilityRule({
+            condition: AbilityCondition_1.default.equal,
+            subject,
+            resource,
+        });
+    }
+    static notIn(subject, resource) {
+        return new AbilityRule({
+            condition: AbilityCondition_1.default.not_in,
+            subject,
+            resource,
+        });
+    }
+    static in(subject, resource) {
+        return new AbilityRule({
+            condition: AbilityCondition_1.default.in,
+            subject,
+            resource,
+        });
+    }
+    static notEqual(subject, resource) {
+        return new AbilityRule({
+            condition: AbilityCondition_1.default.not_equal,
+            subject,
+            resource,
+        });
+    }
+    static lessThan(subject, resource) {
+        return new AbilityRule({
+            condition: AbilityCondition_1.default.less_than,
+            subject,
+            resource,
+        });
+    }
+    static lessOrEqual(subject, resource) {
+        return new AbilityRule({
+            condition: AbilityCondition_1.default.less_or_equal,
+            subject,
+            resource,
+        });
+    }
+    static moreThan(subject, resource) {
+        return new AbilityRule({
+            condition: AbilityCondition_1.default.more_than,
+            subject,
+            resource,
+        });
+    }
+    static moreOrEqual(subject, resource) {
+        return new AbilityRule({
+            condition: AbilityCondition_1.default.more_or_equal,
+            subject,
+            resource,
+        });
+    }
 }
 exports.AbilityRule = AbilityRule;
 exports["default"] = AbilityRule;
@@ -670,8 +989,8 @@ class AbilityRuleSet {
     id;
     constructor(params) {
         const { name, id, compareMethod } = params;
-        this.name = name;
-        this.id = id;
+        this.name = name || 'No name';
+        this.id = id || this.name;
         this.compareMethod = compareMethod;
     }
     addRule(rule) {
@@ -727,6 +1046,16 @@ class AbilityRuleSet {
             rules: this.rules.map(rule => rule.export()),
         };
     }
+    static and(rules) {
+        return new AbilityRuleSet({
+            compareMethod: AbilityCompare_1.default.and,
+        }).addRules(rules);
+    }
+    static or(rules) {
+        return new AbilityRuleSet({
+            compareMethod: AbilityCompare_1.default.or,
+        }).addRules(rules);
+    }
 }
 exports.AbilityRuleSet = AbilityRuleSet;
 exports["default"] = AbilityRuleSet;
@@ -764,6 +1093,7 @@ __exportStar(__webpack_require__(277), exports);
 __exportStar(__webpack_require__(668), exports);
 __exportStar(__webpack_require__(476), exports);
 __exportStar(__webpack_require__(402), exports);
+__exportStar(__webpack_require__(363), exports);
 
 
 /***/ })

package/package.json

@@ -1,21 +1,30 @@
 {
   "name": "@via-profit/ability",
   "support": "https://via-profit.ru",
-  "version": "2.1.0",
+  "version": "3.0.1",
   "description": "Via-Profit Ability service",
   "keywords": [
     "ability",
     "access",
     "via-profit"
-],
+  ],
   "main": "./dist/index.js",
   "engines": {
     "node": ">= 17.0.0",
     "npm": ">= 8.19.3"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
   "scripts": {
     "lint": "tsc --noEmit && eslint --fix .",
     "pretty": "prettier --write ./src",
+    "build": "npm run build:dist",
     "build:dev": "cross-env NODE_ENV=development webpack --config ./webpack/webpack-config.ts --color --progress",
     "build:dist": "cross-env NODE_ENV=production webpack --config ./webpack/webpack-config.ts --color --progress",
     "build:playground": "cross-env NODE_ENV=development webpack --config ./webpack/webpack-config-playground.ts --color --progress",