@via-profit/ability 2.0.0-rc.8 → 3.0.1

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+I take the security of `@via-profit/ability` seriously. If you discover a security vulnerability, please report it responsibly.
+
+### How to Report a Vulnerability
+
+**Please DO NOT create a public GitHub issue for security vulnerabilities.**
+
+Instead, send the details directly to me:
+
+- **Email**: [delhsmail@gmail.com](mailto:delhsmail@gmail.com)
+- **Author**: Vasily Novosad
+- **Timezone**: UTC+5 (for coordinating response time)
+
+### What to Include
+
+To help me address the issue quickly, please include:
+
+- Description of the vulnerability
+- Steps to reproduce (if applicable)
+- Potential impact
+- Suggestions for fixing (if any)
+
+### Process
+
+1. I will acknowledge your report within 48 hours
+2. I will assess the vulnerability
+3. Work on a fix will begin depending on severity
+4. After the fix is released, I will notify you and acknowledge your contribution (if you agree)
+
+Thank you for helping keep this project secure!

package/dist/AbilityCode.d.ts

@@ -1,8 +1,8 @@
-export declare class AbilityCode<T extends string | number | undefined = number> {
-    code: T;
-    constructor(code: T);
-    isEqual(compareWith: AbilityCode<T> | null): boolean;
-    isNotEqual(compareWith: AbilityCode<T> | null): boolean;
-    static fromLiteral<T extends string | number>(literal: string | number): AbilityCode<T>;
+export declare class AbilityCode<Code extends string | number> {
+    _code: Code;
+    constructor(code: Code);
+    get code(): Code;
+    isEqual(compareWith: AbilityCode<Code> | null): boolean;
+    isNotEqual(compareWith: AbilityCode<Code> | null): boolean;
 }
 export default AbilityCode;

package/dist/AbilityCompare.d.ts

@@ -1,6 +1,6 @@
 import AbilityCode from './AbilityCode';
-export type AbilityCompareVariantType = 'and' | 'or';
-export declare class AbilityCompare extends AbilityCode<AbilityCompareVariantType> {
+export type AbilityCompareCodeType = 'and' | 'or';
+export declare class AbilityCompare extends AbilityCode<AbilityCompareCodeType> {
     static and: AbilityCompare;
     static or: AbilityCompare;
 }

package/dist/AbilityCondition.d.ts

@@ -1,13 +1,16 @@
 import AbilityCode from './AbilityCode';
-export type AbilityConditionVariantType = '=' | '<>' | '>' | '<' | '>=' | '<=' | 'in' | 'not in';
-export declare class AbilityCondition extends AbilityCode<AbilityConditionVariantType> {
-    static EQUAL: AbilityCondition;
-    static NOT_EQUAL: AbilityCondition;
-    static MORE_THAN: AbilityCondition;
-    static LESS_THAN: AbilityCondition;
-    static LESS_OR_EQUAL: AbilityCondition;
-    static MORE_OR_EQUAL: AbilityCondition;
-    static IN: AbilityCondition;
-    static NOT_IN: AbilityCondition;
+export type AbilityConditionCodeType = '=' | '<>' | '>' | '<' | '>=' | '<=' | 'in' | 'not in';
+export type AbilityConditionLiteralType = 'equal' | 'not_equal' | 'more_than' | 'less_than' | 'less_or_equal' | 'more_or_equal' | 'in' | 'not_in';
+export declare class AbilityCondition extends AbilityCode<AbilityConditionCodeType> {
+    static equal: AbilityCondition;
+    static not_equal: AbilityCondition;
+    static more_than: AbilityCondition;
+    static less_than: AbilityCondition;
+    static less_or_equal: AbilityCondition;
+    static more_or_equal: AbilityCondition;
+    static in: AbilityCondition;
+    static not_in: AbilityCondition;
+    static fromLiteral(literal: AbilityConditionLiteralType): AbilityCondition;
+    get literal(): AbilityConditionLiteralType;
 }
 export default AbilityCondition;

package/dist/AbilityError.d.ts

@@ -4,6 +4,3 @@ export declare class AbilityError extends Error {
 export declare class AbilityParserError extends Error {
     constructor(message: string);
 }
-export declare class PermissionError extends Error {
-    constructor(message: string);
-}

package/dist/AbilityExplain.d.ts

@@ -0,0 +1,27 @@
+import AbilityRule from './AbilityRule';
+import AbilityRuleSet from '~/AbilityRuleSet';
+import AbilityPolicy from '~/AbilityPolicy';
+import AbilityMatch from '~/AbilityMatch';
+export type AbilityExplainConfig = {
+    readonly type: AbilityExplainType;
+    readonly name: string;
+    readonly match: AbilityMatch;
+};
+export declare class AbilityExplain {
+    readonly type: AbilityExplainType;
+    readonly children: AbilityExplain[];
+    readonly name: string;
+    readonly match: AbilityMatch;
+    constructor(config: AbilityExplainConfig, children?: AbilityExplain[]);
+    toString(indent?: number): string;
+}
+export declare class AbilityExplainRule extends AbilityExplain {
+    constructor(rule: AbilityRule);
+}
+export declare class AbilityExplainRuleSet extends AbilityExplain {
+    constructor(ruleSet: AbilityRuleSet);
+}
+export declare class AbilityExplainPolicy extends AbilityExplain {
+    constructor(policy: AbilityPolicy);
+}
+export type AbilityExplainType = 'policy' | 'rule' | 'ruleSet';

package/dist/AbilityMatch.d.ts

@@ -1,6 +1,6 @@
 import AbilityCode from './AbilityCode';
-export type AbilityMatchVariantType = 'pending' | 'match' | 'mismatch';
-export declare class AbilityMatch extends AbilityCode<AbilityMatchVariantType> {
+export type AbilityMatchCodeType = 'pending' | 'match' | 'mismatch';
+export declare class AbilityMatch extends AbilityCode<AbilityMatchCodeType> {
     static pending: AbilityMatch;
     static match: AbilityMatch;
     static mismatch: AbilityMatch;

package/dist/AbilityParser.d.ts

@@ -1,4 +1,8 @@
 import AbilityPolicy from './AbilityPolicy';
+export type Primitive = string | number | boolean | null | undefined;
+export type NestedDict<T = Primitive> = {
+    [key: string]: NestedDict<T> | T;
+};
 export declare class AbilityParser {
     /**
      * Sets a value in a nested object structure based on a dot/bracket notation path.
@@ -6,13 +10,50 @@ export declare class AbilityParser {
      * @param path - The path to the property in dot/bracket notation.
      * @param value - The value to set at the specified path.
      */
-    static setValueDotValue(object: Record<string, any>, path: string, value: string | number | boolean): void;
+    static setValueDotValue<T extends Primitive>(object: NestedDict<T>, path: string, value: T): void;
     /**
      * 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: readonly AbilityPolicy[], outPath: string): Record<string, any>;
+    static generateTypeDefs(policies: readonly AbilityPolicy[]): string;
+    /**
+     * Determines TypeScript type based on the rule
+     * @param rule - The rule to analyze
+     * @returns TypeScript type as string
+     */
+    private static determineTypeFromRule;
+    /**
+     * Gets TypeScript type for array values
+     * @param resource - The resource value to analyze
+     * @returns TypeScript array type as string
+     */
+    private static getArrayType;
+    /**
+     * Gets primitive TypeScript type for a value
+     * @param value - The value to analyze
+     * @returns TypeScript primitive type as string
+     */
+    private static getPrimitiveType;
+    /**
+     * 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
+     */
+    private static buildNestedStructure;
+    /**
+     * Formats type structure into a string
+     * @param structure - Nested type structure
+     * @returns Formatted TypeScript type definition string
+     */
+    private static formatTypeDefinitions;
+    /**
+     * Recursively formats nested object
+     * @param obj - Object to format
+     * @param indent - Current indentation level
+     * @returns Formatted string
+     */
+    private static formatNestedObject;
 }
 export default AbilityParser;

package/dist/AbilityPolicy.d.ts

@@ -1,15 +1,23 @@
 import AbilityRuleSet, { AbilityRuleSetConfig } from './AbilityRuleSet';
 import AbilityMatch from './AbilityMatch';
-import AbilityCompare, { AbilityCompareVariantType } from './AbilityCompare';
-import AbilityPolicyEffect, { AbilityPolicyEffectVariantType } from './AbilityPolicyEffect';
+import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
+import AbilityPolicyEffect, { AbilityPolicyEffectCodeType } from './AbilityPolicyEffect';
+import { AbilityExplain } from '~/AbilityExplain';
 export type AbilityPolicyConfig = {
     readonly action: string;
-    readonly effect: AbilityPolicyEffectVariantType;
-    readonly compareMethod: AbilityCompareVariantType;
-    readonly ruleSet: AbilityRuleSetConfig[];
+    readonly effect: AbilityPolicyEffectCodeType;
+    readonly compareMethod: AbilityCompareCodeType;
+    readonly ruleSet: readonly AbilityRuleSetConfig[];
     readonly id: string;
     readonly name: string;
 };
+export type AbilityPolicyConstructorProps = {
+    id: string;
+    name: string;
+    action: string;
+    effect: AbilityPolicyEffect;
+    compareMethod?: AbilityCompare;
+};
 export declare class AbilityPolicy<Resources extends object = object> {
     matchState: AbilityMatch;
     /**
@@ -36,15 +44,11 @@ export declare class AbilityPolicy<Resources extends object = object> {
      */
     id: string;
     /**
-     * Soon
+     * Running the `enforce` or `resolve` method
+     * will select only those from all passed policies that fall under the specified action.
      */
     action: string;
-    constructor(params: {
-        id: string;
-        name: string;
-        action: string;
-        effect: AbilityPolicyEffect;
-    });
+    constructor(params: AbilityPolicyConstructorProps);
     /**
      * Add rule set to the policy
      * @param ruleSet - The rule set to add
@@ -55,6 +59,13 @@ export declare class AbilityPolicy<Resources extends object = object> {
      * @param resources - The resource to check
      */
     check(resources: Resources): AbilityMatch;
+    explain(): AbilityExplain;
+    /**
+     * 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<Resources extends object = object>(configs: readonly AbilityPolicyConfig[]): AbilityPolicy<Resources>[];
     /**
      * Parse the config JSON format to Policy class instance
      */

package/dist/AbilityPolicyEffect.d.ts

@@ -1,6 +1,6 @@
 import AbilityCode from './AbilityCode';
-export type AbilityPolicyEffectVariantType = 'deny' | 'permit';
-export declare class AbilityPolicyEffect extends AbilityCode<AbilityPolicyEffectVariantType> {
+export type AbilityPolicyEffectCodeType = 'deny' | 'permit';
+export declare class AbilityPolicyEffect extends AbilityCode<AbilityPolicyEffectCodeType> {
     static deny: AbilityPolicyEffect;
     static permit: AbilityPolicyEffect;
 }

package/dist/AbilityResolver.d.ts

@@ -1,5 +1,6 @@
 import AbilityPolicy from './AbilityPolicy';
 import AbilityPolicyEffect from './AbilityPolicyEffect';
+import { AbilityExplain } from '~/AbilityExplain';
 export declare class AbilityResolver<Resources extends object = object> {
     policies: readonly AbilityPolicy<Resources>[];
     constructor(policyOrListOfPolicies: readonly AbilityPolicy<Resources>[] | AbilityPolicy<Resources>);
@@ -10,6 +11,7 @@ export declare class AbilityResolver<Resources extends object = object> {
      * @param resource - Resource
      */
     resolve<Action extends keyof Resources>(action: Action, resource: Resources[Action]): this;
+    resolveWithExplain<Action extends keyof Resources>(action: Action, resource: Resources[Action]): readonly AbilityExplain[];
     enforce<Action extends keyof Resources>(action: Action, resource: Resources[Action]): void | never;
     /**
      * Get the last effect of the policy

package/dist/AbilityRule.d.ts

@@ -1,8 +1,8 @@
 import AbilityMatch from './AbilityMatch';
-import AbilityCondition, { AbilityConditionVariantType } from './AbilityCondition';
+import AbilityCondition, { AbilityConditionCodeType } from './AbilityCondition';
 export type AbilityRuleConfig = {
-    readonly id: string;
-    readonly name: string;
+    readonly id?: string | null;
+    readonly name?: string | null;
     /**
      * Subject key path like a 'user.name'
      */
@@ -11,8 +11,14 @@ export type AbilityRuleConfig = {
      * Resource key path like a 'user.name' or value
      */
     readonly resource: string | number | boolean | (string | number)[];
-    readonly condition: AbilityConditionVariantType;
+    readonly condition: AbilityConditionCodeType;
 };
+export type AbilityRuleConstructorProps = Omit<AbilityRuleConfig, 'condition'> & {
+    readonly condition: AbilityCondition;
+};
+/**
+ * Represents a rule that defines a condition to be checked against a subject and resource.
+ */
 export declare class AbilityRule<Resources extends object = object> {
     /**
      * Subject key path like a 'user.name'
@@ -26,7 +32,16 @@ export declare class AbilityRule<Resources extends object = object> {
     name: string;
     id: string;
     state: AbilityMatch;
-    constructor(params: AbilityRuleConfig);
+    /**
+     * Creates an instance of AbilityRule.
+     * @param {string} options.id - The unique identifier of the rule.
+     * @param {string} options.name - The name of the rule.
+     * @param {AbilityCondition} options.condition - The condition to evaluate.
+     * @param {string} options.subject - The subject of the rule.
+     * @param {string} options.resource - The resource to compare against.
+     * @param params
+     */
+    constructor(params: AbilityRuleConstructorProps);
     /**
      * Check if the rule is matched
      * @param resource - The resource to check
@@ -51,5 +66,13 @@ export declare class AbilityRule<Resources extends object = object> {
      * Export the rule to config object
      */
     export(): AbilityRuleConfig;
+    static equal<Resources extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources>;
+    static notIn<Resources extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources>;
+    static in<Resources extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources>;
+    static notEqual<Resources extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources>;
+    static lessThan<Resources extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources>;
+    static lessOrEqual<Resources extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources>;
+    static moreThan<Resources extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources>;
+    static moreOrEqual<Resources extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources>;
 }
 export default AbilityRule;

package/dist/AbilityRuleSet.d.ts

@@ -1,11 +1,16 @@
 import AbilityRule, { AbilityRuleConfig } from './AbilityRule';
-import AbilityCompare, { AbilityCompareVariantType } from './AbilityCompare';
+import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
 import AbilityMatch from './AbilityMatch';
 export type AbilityRuleSetConfig = {
-    readonly id: string;
-    readonly name: string;
-    readonly compareMethod: AbilityCompareVariantType;
-    readonly rules: AbilityRuleConfig[];
+    readonly id?: string | null;
+    readonly name?: string | null;
+    readonly compareMethod: AbilityCompareCodeType;
+    readonly rules: readonly AbilityRuleConfig[];
+};
+export type AbilityRuleSetConstructorProps = {
+    readonly id?: string | null;
+    readonly name?: string | null;
+    readonly compareMethod: AbilityCompare;
 };
 export declare class AbilityRuleSet<Resources extends object = object> {
     state: AbilityMatch;
@@ -28,14 +33,16 @@ export declare class AbilityRuleSet<Resources extends object = object> {
      * Group ID
      */
     id: string;
-    constructor(params: Pick<AbilityRuleSetConfig, 'id' | 'name' | 'compareMethod'>);
-    addRule(rule: AbilityRule, compareMethod: AbilityCompare): this;
-    addRules(rules: AbilityRule[], compareMethod: AbilityCompare): this;
+    constructor(params: AbilityRuleSetConstructorProps);
+    addRule(rule: AbilityRule): this;
+    addRules(rules: AbilityRule[]): this;
     check(resources: Resources | null): AbilityMatch;
     /**
      * Parse the config JSON format to Group class instance
      */
     static parse<Resource extends object = object>(config: AbilityRuleSetConfig): AbilityRuleSet<Resource>;
     export(): AbilityRuleSetConfig;
+    static and(rules: AbilityRule[]): AbilityRuleSet<object>;
+    static or(rules: AbilityRule[]): AbilityRuleSet<object>;
 }
 export default AbilityRuleSet;

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './AbilityPolicyEffect';
 export * from './AbilityResolver';
 export * from './AbilityRule';
 export * from './AbilityRuleSet';
+export * from './AbilityExplain';