@via-profit/ability 3.0.1 → 3.1.0

package/dist/cache/AbilityCacheAdapter.d.ts

@@ -0,0 +1,8 @@
+export interface AbilityCacheAdapter {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    serialize<T = unknown>(input: T): string;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    deleteByPrefix(prefix: string): Promise<void>;
+}

package/dist/cache/AbilityInMemoryCache.d.ts

@@ -0,0 +1,12 @@
+import { AbilityCacheAdapter } from '../cache/AbilityCacheAdapter';
+export declare class AbilityInMemoryCache implements AbilityCacheAdapter {
+    private store;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    serialize(input: unknown): string;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    deleteByPrefix(prefix: string): Promise<void>;
+    private fastHash;
+    private stableStringify;
+}

package/dist/core/AbilityCondition.d.ts

@@ -0,0 +1,21 @@
+import AbilityCode from './AbilityCode';
+export type AbilityConditionCodeType = '=' | '<>' | '>' | '<' | '>=' | '<=' | 'in' | 'not in' | 'contains' | 'not contains' | 'length greater than' | 'length less than' | 'length equals';
+export type AbilityConditionLiteralType = 'equals' | 'not_equals' | 'contains' | 'no_contains' | 'in' | 'not_in' | 'greater_than' | 'less_than' | 'less_or_equal' | 'greater_or_equal' | 'length_greater_than' | 'length_less_than' | 'length_equals';
+export declare class AbilityCondition extends AbilityCode<AbilityConditionCodeType> {
+    static equals: AbilityCondition;
+    static not_equals: AbilityCondition;
+    static greater_than: AbilityCondition;
+    static less_than: AbilityCondition;
+    static less_or_equal: AbilityCondition;
+    static greater_or_equal: AbilityCondition;
+    static in: AbilityCondition;
+    static not_in: AbilityCondition;
+    static contains: AbilityCondition;
+    static not_contains: AbilityCondition;
+    static length_greater_than: AbilityCondition;
+    static length_less_than: AbilityCondition;
+    static length_equals: AbilityCondition;
+    static fromLiteral(literal: AbilityConditionLiteralType): AbilityCondition;
+    get literal(): AbilityConditionLiteralType;
+}
+export default AbilityCondition;

package/dist/{AbilityExplain.d.ts → core/AbilityExplain.d.ts}

@@ -1,7 +1,7 @@
 import AbilityRule from './AbilityRule';
-import AbilityRuleSet from '~/AbilityRuleSet';
-import AbilityPolicy from '~/AbilityPolicy';
-import AbilityMatch from '~/AbilityMatch';
+import AbilityRuleSet from '../core/AbilityRuleSet';
+import AbilityPolicy from '../core/AbilityPolicy';
+import AbilityMatch from '../core/AbilityMatch';
 export type AbilityExplainConfig = {
     readonly type: AbilityExplainType;
     readonly name: string;

package/dist/{AbilityParser.d.ts → core/AbilityParser.d.ts}

@@ -3,6 +3,8 @@ export type Primitive = string | number | boolean | null | undefined;
 export type NestedDict<T = Primitive> = {
     [key: string]: NestedDict<T> | T;
 };
+export type ResourceObject = Record<string, unknown>;
+export type ResourcesMap = Record<string, ResourceObject>;
 export declare class AbilityParser {
     /**
      * Sets a value in a nested object structure based on a dot/bracket notation path.

package/dist/{AbilityPolicy.d.ts → core/AbilityPolicy.d.ts}

@@ -2,9 +2,10 @@ import AbilityRuleSet, { AbilityRuleSetConfig } from './AbilityRuleSet';
 import AbilityMatch from './AbilityMatch';
 import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
 import AbilityPolicyEffect, { AbilityPolicyEffectCodeType } from './AbilityPolicyEffect';
-import { AbilityExplain } from '~/AbilityExplain';
+import { AbilityExplain } from './AbilityExplain';
+import { ResourceObject } from './AbilityParser';
 export type AbilityPolicyConfig = {
-    readonly action: string;
+    readonly permission: string;
     readonly effect: AbilityPolicyEffectCodeType;
     readonly compareMethod: AbilityCompareCodeType;
     readonly ruleSet: readonly AbilityRuleSetConfig[];
@@ -14,16 +15,16 @@ export type AbilityPolicyConfig = {
 export type AbilityPolicyConstructorProps = {
     id: string;
     name: string;
-    action: string;
+    permission: string;
     effect: AbilityPolicyEffect;
     compareMethod?: AbilityCompare;
 };
-export declare class AbilityPolicy<Resources extends object = object> {
+export declare class AbilityPolicy<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown> {
     matchState: AbilityMatch;
     /**
      * List of rules
      */
-    ruleSet: AbilityRuleSet[];
+    ruleSet: AbilityRuleSet<Resource, Environment>[];
     /**
      * Policy effect
      */
@@ -45,31 +46,39 @@ export declare class AbilityPolicy<Resources extends object = object> {
     id: string;
     /**
      * Running the `enforce` or `resolve` method
-     * will select only those from all passed policies that fall under the specified action.
+     * will select only those from all passed policies that fall under the specified permission key.
      */
-    action: string;
+    permission: string;
     constructor(params: AbilityPolicyConstructorProps);
     /**
      * Add rule set to the policy
      * @param ruleSet - The rule set to add
      */
-    addRuleSet(ruleSet: AbilityRuleSet): this;
+    addRuleSet(ruleSet: AbilityRuleSet<Resource, Environment>): this;
+    /**
+     * Add rule set to the policy
+     * @param ruleSets - The array of rule set to add
+     */
+    addRuleSets(ruleSets: readonly AbilityRuleSet<Resource, Environment>[]): this;
     /**
      * Check if the policy is matched
-     * @param resources - The resource to check
+     * @param resource - The resource to check
+     * @param environment - The user environment object
      */
-    check(resources: Resources): AbilityMatch;
+    check(resource: Resource, environment?: Environment): Promise<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>[];
+    static fromJSONAll<Resource extends ResourceObject, Environment = unknown>(configs: readonly AbilityPolicyConfig[]): AbilityPolicy<Resource, Environment>[];
     /**
      * Parse the config JSON format to Policy class instance
      */
-    static parse<Resources extends object = object>(config: AbilityPolicyConfig): AbilityPolicy<Resources>;
-    export(): AbilityPolicyConfig;
+    static fromJSON<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(config: AbilityPolicyConfig): AbilityPolicy<Resource, Environment>;
+    static fromDSL<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(dsl: string): AbilityPolicy<Resource, Environment>;
+    toJSON(): AbilityPolicyConfig;
+    toString(): string;
 }
 export default AbilityPolicy;

package/dist/core/AbilityResolver.d.ts

@@ -0,0 +1,35 @@
+import AbilityPolicy from './AbilityPolicy';
+import { AbilityResult } from './AbilityResult';
+import { ResourcesMap } from './AbilityParser';
+import { AbilityCacheAdapter } from '../cache/AbilityCacheAdapter';
+export type AbilityResolverOptions = {
+    readonly cache?: AbilityCacheAdapter | null;
+};
+export declare class AbilityResolver<Resources extends ResourcesMap, Environment = unknown> {
+    private policies;
+    private readonly cache?;
+    constructor(
+    /**
+     * `Important!` The incorrect Resources type was intentionally passed to AbilityPolicy so that TypeScript could suggest the name of the permission and the structure of its resource in the parse method.
+     */
+    policyOrListOfPolicies: readonly AbilityPolicy<Resources>[] | AbilityPolicy<Resources>, options?: AbilityResolverOptions);
+    /**
+     * Resolve policy for the resource and permission key
+     *
+     * @param permission - Permission key
+     * @param resource - Resource
+     * @param environment
+     */
+    resolve<Permission extends keyof Resources>(permission: Permission, resource: Resources[Permission], environment?: Environment): Promise<AbilityResult<Resources[Permission]>>;
+    enforce<Permission extends keyof Resources>(permission: Permission, resource: Resources[Permission], environment?: Environment): Promise<void | never>;
+    /**
+     * Check if the permission key is contained in another permission key
+     * @param permissionA - The first permission to check
+     * @param permissionB - The second permission to check
+     */
+    static isInPermissionContain(permissionA: string, permissionB: string): boolean;
+    private makeCacheKey;
+    invalidatePolicy(policyId: string): Promise<void>;
+    invalidateCache(): Promise<void>;
+}
+export default AbilityResolver;

package/dist/core/AbilityResult.d.ts

@@ -0,0 +1,27 @@
+import { AbilityExplain } from './AbilityExplain';
+import { ResourceObject } from './AbilityParser';
+import AbilityPolicy from './AbilityPolicy';
+import AbilityPolicyEffect from './AbilityPolicyEffect';
+export declare class AbilityResult<Resource extends ResourceObject = Record<string, unknown>> {
+    /**
+     * Already checked policies (after call the policy.check())
+     */
+    readonly policies: readonly AbilityPolicy<Resource>[];
+    constructor(policies: readonly AbilityPolicy<Resource>[]);
+    /**
+     * Returns a list of explanations for each policy involved in the ability evaluation.
+     * Each item describes how a specific policy contributed to the final permission result.
+     *
+     * Useful for debugging, logging, or building UI tools that visualize permission logic.
+     */
+    explain(): readonly AbilityExplain[];
+    getLastMatchedPolicy(): AbilityPolicy<Resource> | null;
+    isAllowed(): boolean;
+    isDenied(): boolean;
+    /**
+     * Get the last effect of the policy
+     *
+     * @returns {AbilityPolicyEffect | null}
+     */
+    getLastEffectOfMatchedPolicy(): AbilityPolicyEffect | null;
+}

package/dist/core/AbilityRule.d.ts

@@ -0,0 +1,77 @@
+import AbilityMatch from './AbilityMatch';
+import AbilityCondition, { AbilityConditionCodeType } from './AbilityCondition';
+export type AbilityRuleConfig = {
+    readonly id?: string | null;
+    readonly name?: string | null;
+    /**
+     * Subject key path like a 'user.name'
+     */
+    readonly subject: string;
+    /**
+     * Resource key path like a 'user.name' or value
+     */
+    readonly resource: string | number | boolean | null | (string | number | boolean | null)[];
+    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, Environment = unknown> {
+    /**
+     * Subject key path like a 'user.name'
+     */
+    subject: string;
+    /**
+     * Resource key path like a 'user.name' or value
+     */
+    resource: AbilityRuleConfig['resource'];
+    condition: AbilityCondition;
+    name: string;
+    id: string;
+    state: AbilityMatch;
+    /**
+     * Creates an instance of AbilityRule.
+     * @param {string} params.id - The unique identifier of the rule.
+     * @param {string} params.name - The name of the rule.
+     * @param {AbilityCondition} params.condition - The condition to evaluate.
+     * @param {string} params.subject - The subject of the rule.
+     * @param {string} params.resource - The resource to compare against.
+     * @param params
+     */
+    constructor(params: AbilityRuleConstructorProps);
+    /**
+     * Check if the rule is matched
+     * @param resource - The resource to check
+     * @param environment
+     */
+    check(resource: Resources | null, environment?: Environment): Promise<AbilityMatch>;
+    /**
+     * Extract values from the resourceData
+     * @param resourceData - The resourceData to extract values from
+     * @param environment - Environment data
+     */
+    extractValues(resourceData: Resources | null, environment?: Environment | null): [AbilityRuleConfig['resource'] | undefined, AbilityRuleConfig['resource'] | undefined];
+    /**
+     * Get the value of the object by dot notation
+     * @param resource - The object to get the value from
+     * @param desc - The dot notation string
+     */
+    getDotNotationValue<T = unknown>(resource: unknown, desc: string): T | undefined;
+    toString(): string;
+    static fromJSON<Resources extends object, Environment = unknown>(config: AbilityRuleConfig): AbilityRule<Resources, Environment>;
+    static equals<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notEquals<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static contains<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notContains<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notIn<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static in<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notEqual<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static lessThan<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static lessOrEqual<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static moreThan<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static moreOrEqual<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+}
+export default AbilityRule;

package/dist/{AbilityRuleSet.d.ts → core/AbilityRuleSet.d.ts}

@@ -1,6 +1,7 @@
 import AbilityRule, { AbilityRuleConfig } from './AbilityRule';
 import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
 import AbilityMatch from './AbilityMatch';
+import { ResourceObject } from './AbilityParser';
 export type AbilityRuleSetConfig = {
     readonly id?: string | null;
     readonly name?: string | null;
@@ -12,12 +13,12 @@ export type AbilityRuleSetConstructorProps = {
     readonly name?: string | null;
     readonly compareMethod: AbilityCompare;
 };
-export declare class AbilityRuleSet<Resources extends object = object> {
+export declare class AbilityRuleSet<Resources extends ResourceObject = Record<string, unknown>, Environment = unknown> {
     state: AbilityMatch;
     /**
      * List of rules
      */
-    rules: AbilityRule[];
+    rules: AbilityRule<Resources, Environment>[];
     /**
      * Rules compare method.\
      * For the «and» method the rule will be permitted if all\
@@ -34,15 +35,15 @@ export declare class AbilityRuleSet<Resources extends object = object> {
      */
     id: string;
     constructor(params: AbilityRuleSetConstructorProps);
-    addRule(rule: AbilityRule): this;
-    addRules(rules: AbilityRule[]): this;
-    check(resources: Resources | null): AbilityMatch;
+    addRule(rule: AbilityRule<Resources, Environment>): this;
+    addRules(rules: AbilityRule<Resources, Environment>[]): this;
+    check(resources: Resources | null, environment?: Environment): Promise<AbilityMatch>;
+    toString(): string;
     /**
      * 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>;
+    static fromJSON<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(config: AbilityRuleSetConfig): AbilityRuleSet<Resource, Environment>;
+    static and(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, unknown>;
+    static or(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, unknown>;
 }
 export default AbilityRuleSet;

package/dist/index.d.ts

@@ -1,12 +1,19 @@
-export * from './AbilityCode';
-export * from './AbilityCompare';
-export * from './AbilityCondition';
-export * from './AbilityError';
-export * from './AbilityMatch';
-export * from './AbilityParser';
-export * from './AbilityPolicy';
-export * from './AbilityPolicyEffect';
-export * from './AbilityResolver';
-export * from './AbilityRule';
-export * from './AbilityRuleSet';
-export * from './AbilityExplain';
+export * from './core/AbilityCode';
+export * from './core/AbilityCompare';
+export * from './core/AbilityCondition';
+export * from './core/AbilityError';
+export * from './core/AbilityMatch';
+export * from './core/AbilityParser';
+export * from './core/AbilityPolicy';
+export * from './core/AbilityPolicyEffect';
+export * from './core/AbilityResolver';
+export * from './core/AbilityRule';
+export * from './core/AbilityRuleSet';
+export * from './core/AbilityExplain';
+export * from './core/AbilityResult';
+export * from './cache/AbilityCacheAdapter';
+export * from './cache/AbilityInMemoryCache';
+export * from './parsers/json/AbilityJSONParser';
+export * from './parsers/dsl/AbilityDSLParser';
+export * from './parsers/dsl/AbilityDSLLexer';
+export * from './parsers/dsl/AbilityDSLToken';