@via-profit/ability 2.1.0 → 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/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/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

@@ -2,6 +2,7 @@ import AbilityRuleSet, { AbilityRuleSetConfig } from './AbilityRuleSet';
 import AbilityMatch from './AbilityMatch';
 import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
 import AbilityPolicyEffect, { AbilityPolicyEffectCodeType } from './AbilityPolicyEffect';
+import { AbilityExplain } from '~/AbilityExplain';
 export type AbilityPolicyConfig = {
     readonly action: string;
     readonly effect: AbilityPolicyEffectCodeType;
@@ -15,6 +16,7 @@ export type AbilityPolicyConstructorProps = {
     name: string;
     action: string;
     effect: AbilityPolicyEffect;
+    compareMethod?: AbilityCompare;
 };
 export declare class AbilityPolicy<Resources extends object = object> {
     matchState: AbilityMatch;
@@ -42,7 +44,8 @@ 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: AbilityPolicyConstructorProps);
@@ -56,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/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, { 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'
      */
@@ -66,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

@@ -2,14 +2,14 @@ import AbilityRule, { AbilityRuleConfig } from './AbilityRule';
 import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
 import AbilityMatch from './AbilityMatch';
 export type AbilityRuleSetConfig = {
-    readonly id: string;
-    readonly name: string;
+    readonly id?: string | null;
+    readonly name?: string | null;
     readonly compareMethod: AbilityCompareCodeType;
     readonly rules: readonly AbilityRuleConfig[];
 };
 export type AbilityRuleSetConstructorProps = {
-    readonly id: string;
-    readonly name: string;
+    readonly id?: string | null;
+    readonly name?: string | null;
     readonly compareMethod: AbilityCompare;
 };
 export declare class AbilityRuleSet<Resources extends object = object> {
@@ -42,5 +42,7 @@ export declare class AbilityRuleSet<Resources extends object = object> {
      */
     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';