@via-profit/ability 3.5.4 → 3.6.1

package/dist/index.d.ts

@@ -1,38 +1,38 @@
-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;
-}
-
-type AbilityCompareCodeType = 'and' | 'or';
-declare class AbilityCompare extends AbilityCode<AbilityCompareCodeType> {
-    static and: AbilityCompare;
-    static or: AbilityCompare;
-}
+type AbilityCompareCode = 'and' | 'or';
+type AbilityCompareType = AbilityCompareCode & {
+    __brand: 'AbilityCompare';
+};
+declare const AbilityCompare: {
+    readonly or: AbilityCompareType;
+    readonly and: AbilityCompareType;
+};
 
-type AbilityConditionCodeType = '=' | '<>' | '>' | '<' | '>=' | '<=' | 'in' | 'not in' | 'contains' | 'not contains' | 'length greater than' | 'length less than' | 'length equals' | 'always' | 'never';
-type AbilityConditionLiteralType = 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'greater_than' | 'less_than' | 'less_or_equal' | 'greater_or_equal' | 'length_greater_than' | 'length_less_than' | 'length_equals' | 'always' | 'never';
-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 always: AbilityCondition;
-    static never: AbilityCondition;
-    static fromLiteral(literal: AbilityConditionLiteralType): AbilityCondition;
-    get literal(): AbilityConditionLiteralType;
-}
+type AbilityConditionCode = '=' | '<>' | '>' | '<' | '>=' | '<=' | 'in' | 'not in' | 'contains' | 'not contains' | 'length greater than' | 'length less than' | 'length equals' | 'always' | 'never';
+type AbilityConditionLiteral = 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'greater_than' | 'less_than' | 'less_or_equal' | 'greater_or_equal' | 'length_greater_than' | 'length_less_than' | 'length_equals' | 'always' | 'never';
+type AbilityConditionType = AbilityConditionCode & {
+    __brand: 'AbilityCondition';
+};
+declare const AbilityCondition: {
+    readonly equals: AbilityConditionType;
+    readonly not_equals: AbilityConditionType;
+    readonly greater_than: AbilityConditionType;
+    readonly less_than: AbilityConditionType;
+    readonly less_or_equal: AbilityConditionType;
+    readonly greater_or_equal: AbilityConditionType;
+    readonly in: AbilityConditionType;
+    readonly not_in: AbilityConditionType;
+    readonly contains: AbilityConditionType;
+    readonly not_contains: AbilityConditionType;
+    readonly length_greater_than: AbilityConditionType;
+    readonly length_less_than: AbilityConditionType;
+    readonly length_equals: AbilityConditionType;
+    readonly always: AbilityConditionType;
+    readonly never: AbilityConditionType;
+};
+declare function fromLiteral(literal: AbilityConditionLiteral): AbilityConditionType;
+declare function toLiteral(cond: AbilityConditionType): AbilityConditionLiteral;
+declare function isConditionEqual(a: AbilityConditionType | null, b: AbilityConditionType | null): boolean;
+declare function isConditionNotEqual(a: AbilityConditionType | null, b: AbilityConditionType | null): boolean;
 
 declare class AbilityError extends Error {
     constructor(message: string, options?: ErrorOptions);
@@ -41,16 +41,22 @@ declare class AbilityParserError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
 
-type AbilityMatchCodeType = 'pending' | 'match' | 'mismatch';
-declare class AbilityMatch extends AbilityCode<AbilityMatchCodeType> {
-    static pending: AbilityMatch;
-    static match: AbilityMatch;
-    static mismatch: AbilityMatch;
-}
+type AbilityMatchCode = 'pending' | 'match' | 'mismatch' | 'except-mismatch' | 'disabled';
+type AbilityMatchType = AbilityMatchCode & {
+    __brand: 'AbilityMatch';
+};
+declare const AbilityMatch: {
+    readonly pending: AbilityMatchType;
+    readonly match: AbilityMatchType;
+    readonly mismatch: AbilityMatchType;
+    readonly exceptMismatch: AbilityMatchType;
+    readonly disabled: AbilityMatchType;
+};
 
 type AbilityRuleConfig = {
     readonly id?: string | null;
     readonly name?: string | null;
+    readonly description?: string | null;
     /**
      * Subject key path like a 'user.name'
      */
@@ -59,15 +65,16 @@ type AbilityRuleConfig = {
      * Resource key path like a 'user.name' or value
      */
     readonly resource: string | number | boolean | null | (string | number | boolean | null)[];
-    readonly condition: AbilityConditionCodeType;
+    readonly condition: AbilityConditionType;
+    readonly disabled?: boolean;
 };
 type AbilityRuleConstructorProps = Omit<AbilityRuleConfig, 'condition'> & {
-    readonly condition: AbilityCondition;
+    readonly condition: AbilityConditionType;
 };
 /**
  * Represents a rule that defines a condition to be checked against a subject and resource.
  */
-declare class AbilityRule<Resources extends object = object, Environment = unknown> {
+declare class AbilityRule<Resources extends object = object, Environment extends object = object> {
     /**
      * Subject key path like a 'user.name'
      */
@@ -76,10 +83,12 @@ declare class AbilityRule<Resources extends object = object, Environment = unkno
      * Resource key path like a 'user.name' or value
      */
     resource: AbilityRuleConfig['resource'];
-    condition: AbilityCondition;
+    condition: AbilityConditionType;
     name: string;
+    description?: string | null;
     id: string;
-    state: AbilityMatch;
+    state: AbilityMatchType;
+    disabled: boolean;
     /**
      * Creates an instance of AbilityRule.
      * @param {string} params.id - The unique identifier of the rule.
@@ -87,26 +96,29 @@ declare class AbilityRule<Resources extends object = object, Environment = unkno
      * @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 {boolean} params.disabled - Disabling flag.
      * @param params
      */
     constructor(params: AbilityRuleConstructorProps);
-    private isPrimitive;
-    private isNumber;
-    private isString;
-    private valueLen;
-    private operatorHandlers;
+    static isPrimitive(v: unknown): v is string | number | boolean | null;
+    static isNumber(v: unknown): v is number;
+    static isString(v: unknown): v is string;
+    static valueLen: (v: unknown) => number | null;
+    static operatorHandlers: { [K in AbilityConditionLiteral]: (a: unknown, b: unknown) => boolean; };
     /**
      * Check if the rule is matched
      * @param resource - The resource to check
      * @param environment
      */
-    check(resource: Resources | null, environment?: Environment): AbilityMatch;
+    check(resource: Resources | null, environment?: Environment): AbilityMatchType;
     /**
      * 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];
+    private static readonly _pathCache;
+    private static _parsePath;
     /**
      * Get the value of the object by dot notation
      * @param resource - The object to get the value from
@@ -117,86 +129,101 @@ declare class AbilityRule<Resources extends object = object, Environment = unkno
     copyWith(props: Partial<{
         id: string | null;
         name: string | null;
+        description: string | null;
         subject: string;
         resource: AbilityRuleConfig['resource'];
-        condition: AbilityCondition;
+        condition: AbilityConditionType;
     }>): 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>;
+    hash(): string;
+    static equals<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notEquals<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static contains<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notContains<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notIn<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static in<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notEqual<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static lessThan<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static lessOrEqual<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static moreThan<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static moreOrEqual<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
 }
 
 type AbilityRuleSetConfig = {
     readonly id?: string | null;
     readonly name?: string | null;
-    readonly compareMethod: AbilityCompareCodeType;
+    readonly description?: string | null;
+    readonly compareMethod: AbilityCompareType;
     readonly rules: readonly AbilityRuleConfig[];
+    readonly disabled?: boolean;
 };
 type AbilityRuleSetConstructorProps = {
     readonly id?: string | null;
     readonly name?: string | null;
-    readonly compareMethod: AbilityCompare;
+    readonly description?: string | null;
+    readonly compareMethod: AbilityCompareType;
+    readonly isExcept?: boolean;
+    readonly disabled?: boolean;
 };
-declare class AbilityRuleSet<Resources extends ResourceObject = Record<string, unknown>, Environment = unknown> {
-    state: AbilityMatch;
+declare class AbilityRuleSet<R extends ResourceObject = Record<string, unknown>, E extends EnvironmentObject = Record<string, unknown>> {
+    state: AbilityMatchType;
     /**
      * List of rules
      */
-    rules: AbilityRule<Resources, Environment>[];
+    rules: AbilityRule<R, E>[];
     /**
      * Rules compare method.\
      * For the «and» method the rule will be permitted if all\
      * rules will be returns «permit» status and for the «or» - if\
      * one of the rules returns as «permit»
      */
-    compareMethod: AbilityCompare;
+    compareMethod: AbilityCompareType;
     /**
      * Group name
      */
     name: string;
+    description?: string | null;
     /**
      * Group ID
      */
     id: string;
+    readonly isExcept?: boolean;
+    disabled: boolean;
     constructor(params: AbilityRuleSetConstructorProps);
-    addRule(rule: AbilityRule<Resources, Environment>): this;
-    addRules(rules: AbilityRule<Resources, Environment>[]): this;
-    check(resources: Resources | null, environment?: Environment): AbilityMatch;
+    addRule(rule: AbilityRule<R, E>): this;
+    addRules(rules: AbilityRule<R, E>[]): this;
+    check(resources: R | null, environment?: E): AbilityMatchType;
     toString(): string;
     copyWith(props: Partial<{
         id: string | null;
         name: string | null;
-        compareMethod: AbilityCompare;
-        rules: AbilityRule<Resources, Environment>[];
-    }>): AbilityRuleSet<Resources, Environment>;
-    static and(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, unknown>;
-    static or(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, unknown>;
+        description: string | null;
+        compareMethod: AbilityCompareType;
+        rules: AbilityRule<R, E>[];
+    }>): AbilityRuleSet<R, E>;
+    hash(): string;
+    static and(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, Record<string, unknown>>;
+    static or(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, Record<string, unknown>>;
 }
 
-type AbilityPolicyEffectCodeType = 'deny' | 'permit';
-declare class AbilityPolicyEffect extends AbilityCode<AbilityPolicyEffectCodeType> {
-    static deny: AbilityPolicyEffect;
-    static permit: AbilityPolicyEffect;
-}
+type AbilityPolicyEffectCode = 'deny' | 'permit';
+type AbilityPolicyEffectType = AbilityPolicyEffectCode & {
+    __brand: 'AbilityPolicyEffect';
+};
+declare const AbilityPolicyEffect: {
+    readonly deny: AbilityPolicyEffectType;
+    readonly permit: AbilityPolicyEffectType;
+};
 
 type AbilityExplainConfig = {
     readonly type: AbilityExplainType;
     readonly name: string;
-    readonly match: AbilityMatch;
+    readonly match: AbilityMatchType;
 };
 declare class AbilityExplain {
     readonly type: AbilityExplainType;
     readonly children: AbilityExplain[];
     readonly name: string;
-    readonly match: AbilityMatch;
+    readonly match: AbilityMatchType;
     constructor(config: AbilityExplainConfig, children?: AbilityExplain[]);
     toString(indent?: number): string;
 }
@@ -211,77 +238,96 @@ declare class AbilityExplainPolicy extends AbilityExplain {
 }
 type AbilityExplainType = 'policy' | 'rule' | 'ruleSet';
 
-type AbilityPolicyConfig = {
+type AbilityPolicyConfig<TTag extends string = string> = {
     readonly permission: string;
-    readonly effect: AbilityPolicyEffectCodeType;
-    readonly compareMethod: AbilityCompareCodeType;
+    readonly effect: AbilityPolicyEffectType;
+    readonly compareMethod: AbilityCompareType;
     readonly ruleSet: readonly AbilityRuleSetConfig[];
     readonly id: string;
     readonly name: string;
+    readonly description?: string | null;
+    readonly priority: number;
+    readonly disabled?: boolean;
+    readonly tags?: readonly TTag[];
 };
-type AbilityPolicyConstructorProps = {
-    id: string;
-    name: string;
+type AbilityPolicyConstructorProps<TTag extends string = string> = {
+    id: string | null;
+    name: string | null;
+    description?: string | null;
     permission: string;
-    effect: AbilityPolicyEffect;
-    compareMethod?: AbilityCompare;
+    effect: AbilityPolicyEffectType;
+    compareMethod?: AbilityCompareType;
+    priority?: number | null;
+    disabled?: boolean;
+    tags?: readonly TTag[];
 };
-declare class AbilityPolicy<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown> {
-    matchState: AbilityMatch;
+declare class AbilityPolicy<R extends ResourceObject = Record<string, unknown>, E extends EnvironmentObject = Record<string, unknown>, TTag extends string = string> {
+    matchState: AbilityMatchType;
     /**
      * List of rules
      */
-    ruleSet: AbilityRuleSet<Resource, Environment>[];
+    ruleSet: AbilityRuleSet<R, E>[];
     /**
      * Policy effect
      */
-    effect: AbilityPolicyEffect;
+    effect: AbilityPolicyEffectType;
     /**
      * Rules compare method.\
      * For the «and» method the rule will be permitted if all\
      * rules will be returns «permit» status and for the «or» - if\
      * one of the rules returns as «permit»
      */
-    compareMethod: AbilityCompare;
-    /**
-     * Policy name
-     */
-    name: string;
+    compareMethod: AbilityCompareType;
     /**
      * Policy ID
      */
     id: string;
+    /**
+     * Policy name
+     */
+    name: string;
+    description?: string | null;
     /**
      * Running the `enforce` or `resolve` method
      * will select only those from all passed policies that fall under the specified permission key.
      */
     permission: string;
+    priority: number;
+    disabled: boolean;
+    tags: readonly TTag[];
     constructor(params: AbilityPolicyConstructorProps);
     /**
      * Add rule set to the policy
      * @param ruleSet - The rule set to add
      */
-    addRuleSet(ruleSet: AbilityRuleSet<Resource, Environment>): this;
+    addRuleSet(ruleSet: AbilityRuleSet<R, E>): this;
     /**
      * Add rule set to the policy
      * @param ruleSets - The array of rule set to add
      */
-    addRuleSets(ruleSets: readonly AbilityRuleSet<Resource, Environment>[]): this;
+    addRuleSets(ruleSets: readonly AbilityRuleSet<R, E>[]): this;
+    /**
+     * Extract all rules of all ruleSets of this policy
+     */
+    extractRules(): readonly AbilityRule[];
     /**
      * Check if the policy is matched
      * @param resource - The resource to check
      * @param environment - The user environment object
      */
-    check(resource: Resource, environment?: Environment): AbilityMatch;
+    check(resource: R, environment?: E): AbilityMatchType;
     explain(): AbilityExplain;
     copyWith(props: Partial<{
         id: string;
         name: string;
+        description?: string | null;
+        priority: number;
         permission: string;
-        effect: AbilityPolicyEffect;
-        compareMethod: AbilityCompare;
-        ruleSet: AbilityRuleSet<Resource, Environment>[];
-    }>): AbilityPolicy<Resource, Environment>;
+        effect: AbilityPolicyEffectType;
+        compareMethod: AbilityCompareType;
+        ruleSet: AbilityRuleSet<R, E>[];
+    }>): AbilityPolicy<R, E>;
+    hash(): string;
 }
 
 type Primitive = string | number | boolean | null | undefined;
@@ -289,15 +335,18 @@ type NestedDict<T = Primitive> = {
     [key: string]: NestedDict<T> | T;
 };
 type ResourceObject = Record<string, unknown>;
+type EnvironmentObject = Record<string, unknown>;
 type ResourcesMap = Record<string, ResourceObject>;
 declare class AbilityTypeGenerator {
     readonly policies: readonly AbilityPolicy[];
+    private readonly policyEntries;
     constructor(policies: readonly AbilityPolicy[]);
     /**
      * Generates TypeScript type definitions based on the provided policies.
      * @returns A generated type definitions.
      */
     generateTypeDefs(): string;
+    private isPath;
     /**
      * Determines TypeScript type based on the rule
      * @param rule - The rule to analyze
@@ -310,6 +359,7 @@ declare class AbilityTypeGenerator {
      * @returns TypeScript array type as string
      */
     private getArrayType;
+    private getInArrayType;
     /**
      * Gets primitive TypeScript type for a value
      * @param value - The value to analyze
@@ -326,6 +376,8 @@ declare class AbilityTypeGenerator {
     /**
      * Formats type structure into a string
      * @param structure - Nested type structure
+     * @param environment
+     * @param allTags
      * @returns Formatted TypeScript type definition string
      */
     private formatTypeDefinitions;
@@ -338,19 +390,24 @@ declare class AbilityTypeGenerator {
     private formatNestedObject;
 }
 
-type AbilityResultStateCodeType = 'allow' | 'deny' | 'neutral';
-declare class AbilityResultState extends AbilityCode<AbilityResultStateCodeType> {
-    static allow: AbilityResultState;
-    static deny: AbilityResultState;
-    static neutral: AbilityResultState;
+declare abstract class AbilityStrategy<Resource extends ResourceObject = Record<string, unknown>, Environment extends EnvironmentObject = Record<string, unknown>> {
+    readonly policies: readonly AbilityPolicy<Resource, Environment>[];
+    private readonly matched;
+    constructor(policies: readonly AbilityPolicy<Resource, Environment>[]);
+    abstract evaluate(): AbilityPolicyEffectType;
+    matchedPolicies(): readonly AbilityPolicy<Resource, Environment, string>[];
+    protected firstMatched(): AbilityPolicy<Resource, Environment> | null;
+    protected lastMatched(): AbilityPolicy<Resource, Environment> | null;
+    protected hasPermit(): boolean;
+    protected hasDeny(): boolean;
+    isAllowed(): boolean;
+    isDenied(): boolean;
 }
 
-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>[]);
+declare class AbilityResult<R extends ResourceObject = Record<string, unknown>, E extends EnvironmentObject = Record<string, unknown>> {
+    protected readonly effect: AbilityPolicyEffectType;
+    protected readonly strategy: AbilityStrategy<R, E>;
+    constructor(effect: AbilityPolicyEffectType, strategy: AbilityStrategy<R, E>);
     /**
      * 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.
@@ -358,19 +415,26 @@ declare class AbilityResult<Resource extends ResourceObject = Record<string, unk
      * Useful for debugging, logging, or building UI tools that visualize permission logic.
      */
     explain(): readonly AbilityExplain[];
-    getLastMatchedPolicy(): AbilityPolicy<Resource> | null;
-    getFinalState(): AbilityResultState;
-    isAllowed(): boolean;
-    isDenied(): boolean;
+    isAllowed: () => boolean;
+    isDenied: () => boolean;
 }
 
-declare class AbilityResolver<Resources extends ResourcesMap, Environment = unknown> {
-    private policies;
+interface AbilityResolverOptions<TTags extends string> {
+    tags?: readonly TTags[];
+}
+type ExtractResources<P> = P extends AbilityPolicy<infer R, any, any> ? R : never;
+type ExtractEnvironment<P> = P extends AbilityPolicy<any, infer E, any> ? E : never;
+type ExtractPermission<R> = R extends AbilityResolver<infer P, any, any> ? keyof ExtractResources<P> & string : never;
+type ExtractResourceByPermission<P, Perm extends string> = P extends AbilityPolicy<infer R, any, any> ? (Perm extends keyof R ? R[Perm] : never) : never;
+type ExtractEnvironmentByPermission<P, Perm extends string> = P extends AbilityPolicy<any, infer E, any> ? (Perm extends keyof E ? E[Perm] : never) : never;
+declare class AbilityResolver<P extends AbilityPolicy<any, any, any>, S extends AbilityStrategy<P extends AbilityPolicy<infer R, infer E, any> ? R : never, P extends AbilityPolicy<any, infer E, any> ? E : never>, TTags extends string = P extends AbilityPolicy<any, any, infer T> ? T : never> {
+    private readonly StrategyClass;
+    private readonly policyEntries;
     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>);
+    policyOrListOfPolicies: readonly P[] | P, strategy: new (policies: readonly P[]) => S, options?: AbilityResolverOptions<TTags>);
     /**
      * Resolve policy for the resource and permission key
      *
@@ -378,14 +442,19 @@ declare class AbilityResolver<Resources extends ResourcesMap, Environment = unkn
      * @param resource - Resource
      * @param environment
      */
-    resolve<Permission extends keyof Resources>(permission: Permission, resource: Resources[Permission], environment?: Environment): AbilityResult<Resources[Permission]>;
-    enforce<Permission extends keyof Resources>(permission: Permission, resource: Resources[Permission], environment?: Environment): void | never;
+    resolve<Permission extends keyof ExtractResources<P> & string>(permission: Permission, resource: ExtractResourceByPermission<P, Permission>, environment?: ExtractEnvironmentByPermission<P, Permission>): AbilityResult<ExtractResourceByPermission<P, Permission>, ExtractEnvironment<P>>;
+    enforce<Permission extends keyof ExtractResources<P> & string>(permission: Permission, resource: ExtractResourceByPermission<P, Permission>, environment?: ExtractEnvironmentByPermission<P, Permission>): void | never;
     /**
+     * @deprecated - will be removed
+     *
      * 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 toArray;
+    static normalizePermission(permission: string): string;
+    static matchPermissions(policySegments: string[], inputSegments: string[]): boolean;
 }
 
 declare class AbilityJSONParser {
@@ -394,13 +463,13 @@ declare class AbilityJSONParser {
      * @param configs - Array of policy configurations
      * @returns Array of AbilityPolicy instances
      */
-    static parse<Resource extends ResourceObject, Environment = unknown>(configs: readonly AbilityPolicyConfig[]): AbilityPolicy<Resource, Environment>[];
-    static parsePolicy<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(config: AbilityPolicyConfig): AbilityPolicy<Resource, Environment>;
-    static parseRule<Resources extends object, Environment = unknown>(config: AbilityRuleConfig): AbilityRule<Resources, Environment>;
+    static parse<R extends ResourceObject, E extends EnvironmentObject, T extends string = string>(configs: readonly AbilityPolicyConfig[]): AbilityPolicy<R, E, T>[];
+    static parsePolicy<R extends ResourceObject, E extends EnvironmentObject, T extends string = string>(config: AbilityPolicyConfig): AbilityPolicy<R, E, T>;
+    static parseRule<R extends ResourceObject, E extends EnvironmentObject>(config: AbilityRuleConfig): AbilityRule<R, E>;
     /**
      * Parse the config JSON format to Group class instance
      */
-    static parseRuleSet<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(config: AbilityRuleSetConfig): AbilityRuleSet<Resource, Environment>;
+    static parseRuleSet<R extends ResourceObject, E extends EnvironmentObject>(config: AbilityRuleSetConfig): AbilityRuleSet<R, E>;
     static ruleToJSON(rule: AbilityRule): AbilityRuleConfig;
     static ruleSetToJSON(ruleSet: AbilityRuleSet): AbilityRuleSetConfig;
     static policyToJSON(policy: AbilityPolicy): AbilityPolicyConfig;
@@ -423,17 +492,17 @@ declare class AbilityJSONParser {
  * Operators can be simple (equals, contains, in) or
  * composed (is null, is not null, greater than, less than or equal, etc.).
  */
-declare class AbilityDSLParser<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown> {
-    private dsl;
-    private tokens;
-    private pos;
-    private annotationBuffer;
+declare class AbilityDSLParser<R extends ResourceObject = Record<string, unknown>, E extends EnvironmentObject = Record<string, unknown>, T extends string = string> {
+    private readonly dsl;
+    private stream;
+    private annBuffer;
+    private aliasBuffer;
     constructor(dsl: string);
     /**
      * Main entry point: tokenize the input and parse all policies.
      * @returns Array of AbilityPolicy instances.
      */
-    parse(): readonly AbilityPolicy<Resource, Environment>[];
+    parse(): readonly AbilityPolicy<R, E, T>[];
     /**
      * Parses a single policy from the current token position.
      *
@@ -449,6 +518,7 @@ declare class AbilityDSLParser<Resource extends ResourceObject = Record<string,
      * Parses a single group, e.g. "all of:" or "any of:", and returns a RuleSet.
      */
     private parseGroup;
+    private parseExceptGroup;
     /**
      * Parses a single rule: subject operator value
      */
@@ -476,76 +546,69 @@ declare class AbilityDSLParser<Resource extends ResourceObject = Record<string,
      */
     private parseArray;
     private consumeLeadingComments;
-    private processCommentToken;
+    private consumeLeadingAliases;
+    private consumeLeadingAnnotations;
     private takeAnnotations;
-    private syntaxError;
-    private suggest;
-    private levenshteinDistance;
-    private consumeOneOf;
-    private consume;
-    private check;
     private isStartOfPolicy;
     private isStartOfGroup;
-    private advance;
-    private peek;
-    private isAtEnd;
+    private isStartOfExcept;
+    private isStartOfAlias;
 }
 
-type TokenType = 'EFFECT' | 'IF' | 'PERMISSION' | 'IDENTIFIER' | 'COLON' | 'COMMA' | 'DOT' | 'LBRACKET' | 'RBRACKET' | 'ALL' | 'ANY' | 'OF' | 'EOF' | 'COMMENT' | 'EQ' | 'CONTAINS' | 'IN' | 'NOT_IN' | 'NOT_CONTAINS' | 'GT' | 'GTE' | 'LT' | 'LTE' | 'NULL' | 'EQ_NULL' | 'NOT_EQ_NULL' | 'NOT_EQ' | 'LEN_GT' | 'LEN_LT' | 'LEN_EQ' | 'ALWAYS' | 'NEVER' | 'STRING' | 'NUMBER' | 'BOOLEAN' | 'SYMBOL' | 'KEYWORD' | 'UNKNOWN';
-/**
- * Represents a single token produced by the Ability DSL lexer.
- * Each token carries a type (e.g., EFFECT, IDENTIFIER, STRING) and its raw string value.
- */
-declare class AbilityDSLToken<Code extends TokenType = TokenType> extends AbilityCode<Code> {
-    /** The literal text of the token as it appeared in the input (e.g., "permit", "user.roles", "admin"). */
+type TokenTypeCode = 'EFFECT' | 'IF' | 'PERMISSION' | 'IDENTIFIER' | 'COLON' | 'COMMA' | 'DOT' | 'LBRACKET' | 'RBRACKET' | 'ALL' | 'ANY' | 'OF' | 'EOF' | 'COMMENT' | 'EQ' | 'CONTAINS' | 'IN' | 'NOT_IN' | 'NOT_CONTAINS' | 'GT' | 'GTE' | 'LT' | 'LTE' | 'NULL' | 'EQ_NULL' | 'NOT_EQ_NULL' | 'NOT_EQ' | 'LEN_GT' | 'LEN_LT' | 'LEN_EQ' | 'ALWAYS' | 'NEVER' | 'EXCEPT' | 'ANNOTATION' | 'STRING' | 'NUMBER' | 'BOOLEAN' | 'SYMBOL' | 'KEYWORD' | 'ALIAS' | 'UNKNOWN';
+type TokenType = TokenTypeCode & {
+    __brand: 'TokenType';
+};
+declare const TokenTypes: {
+    readonly EFFECT: TokenType;
+    readonly IF: TokenType;
+    readonly PERMISSION: TokenType;
+    readonly IDENTIFIER: TokenType;
+    readonly COLON: TokenType;
+    readonly COMMA: TokenType;
+    readonly DOT: TokenType;
+    readonly LBRACKET: TokenType;
+    readonly RBRACKET: TokenType;
+    readonly ALL: TokenType;
+    readonly ANY: TokenType;
+    readonly OF: TokenType;
+    readonly EOF: TokenType;
+    readonly COMMENT: TokenType;
+    readonly EQ: TokenType;
+    readonly CONTAINS: TokenType;
+    readonly IN: TokenType;
+    readonly NOT_IN: TokenType;
+    readonly NOT_CONTAINS: TokenType;
+    readonly GT: TokenType;
+    readonly GTE: TokenType;
+    readonly LT: TokenType;
+    readonly LTE: TokenType;
+    readonly NULL: TokenType;
+    readonly EQ_NULL: TokenType;
+    readonly NOT_EQ_NULL: TokenType;
+    readonly NOT_EQ: TokenType;
+    readonly LEN_GT: TokenType;
+    readonly LEN_LT: TokenType;
+    readonly LEN_EQ: TokenType;
+    readonly ALWAYS: TokenType;
+    readonly NEVER: TokenType;
+    readonly EXCEPT: TokenType;
+    readonly ANNOTATION: TokenType;
+    readonly STRING: TokenType;
+    readonly NUMBER: TokenType;
+    readonly BOOLEAN: TokenType;
+    readonly SYMBOL: TokenType;
+    readonly KEYWORD: TokenType;
+    readonly ALIAS: TokenType;
+    readonly UNKNOWN: TokenType;
+};
+declare class AbilityDSLToken {
+    readonly type: TokenType;
     readonly value: string;
-    /** The line number in DSL */
     readonly line: number;
-    /** The column in dsl */
     readonly column: number;
-    constructor(type: Code, value: string, line: number, column: number);
-    /**
-     * Returns a human-readable representation of the token, useful for debugging.
-     * Example output: "AbilityDSLToken([EFFECT] permit"
-     */
+    constructor(type: TokenType, value: string, line: number, column: number);
     toString(): string;
-    static readonly EFFECT: TokenType;
-    static readonly IF: TokenType;
-    static readonly PERMISSION: TokenType;
-    static readonly IDENTIFIER: TokenType;
-    static readonly COLON: TokenType;
-    static readonly COMMA: TokenType;
-    static readonly DOT: TokenType;
-    static readonly LBRACKET: TokenType;
-    static readonly RBRACKET: TokenType;
-    static readonly ALL: TokenType;
-    static readonly ANY: TokenType;
-    static readonly OF: TokenType;
-    static readonly EOF: TokenType;
-    static readonly COMMENT: TokenType;
-    static readonly EQ: TokenType;
-    static readonly CONTAINS: TokenType;
-    static readonly IN: TokenType;
-    static readonly NOT_IN: TokenType;
-    static readonly NOT_CONTAINS: TokenType;
-    static readonly GT: TokenType;
-    static readonly GTE: TokenType;
-    static readonly LT: TokenType;
-    static readonly LTE: TokenType;
-    static readonly NULL: TokenType;
-    static readonly EQ_NULL: TokenType;
-    static readonly NOT_EQ_NULL: TokenType;
-    static readonly LEN_GT: TokenType;
-    static readonly LEN_LT: TokenType;
-    static readonly LEN_EQ: TokenType;
-    static readonly NOT_EQ: TokenType;
-    static readonly ALWAYS: TokenType;
-    static readonly NEVER: TokenType;
-    static readonly STRING: TokenType;
-    static readonly NUMBER: TokenType;
-    static readonly BOOLEAN: TokenType;
-    static readonly SYMBOL: TokenType;
-    static readonly KEYWORD: TokenType;
 }
 
 declare class AbilityDSLLexer {
@@ -558,6 +621,7 @@ declare class AbilityDSLLexer {
     constructor(input: string);
     tokenize(): AbilityDSLToken[];
     private readComment;
+    private readAnnotation;
     private readString;
     private readNumber;
     private readSymbol;
@@ -572,5 +636,175 @@ declare class AbilityDSLLexer {
     private isAtEnd;
 }
 
-export { AbilityCode, AbilityCompare, AbilityCondition, AbilityDSLLexer, AbilityDSLParser, AbilityDSLToken, AbilityError, AbilityExplain, AbilityExplainPolicy, AbilityExplainRule, AbilityExplainRuleSet, AbilityJSONParser, AbilityMatch, AbilityParserError, AbilityPolicy, AbilityPolicyEffect, AbilityResolver, AbilityResult, AbilityResultState, AbilityRule, AbilityRuleSet, AbilityTypeGenerator };
-export type { AbilityCompareCodeType, AbilityConditionCodeType, AbilityConditionLiteralType, AbilityExplainConfig, AbilityExplainType, AbilityMatchCodeType, AbilityPolicyConfig, AbilityPolicyConstructorProps, AbilityPolicyEffectCodeType, AbilityResultStateCodeType, AbilityRuleConfig, AbilityRuleConstructorProps, AbilityRuleSetConfig, AbilityRuleSetConstructorProps, NestedDict, Primitive, ResourceObject, ResourcesMap, TokenType };
+declare function ability<R extends ResourceObject = Record<string, unknown>, E extends EnvironmentObject = Record<string, unknown>, T extends string = string>(strings: TemplateStringsArray, ...expr: any[]): readonly AbilityPolicy<R, E, T>[];
+
+/**
+ * AllMustPermitStrategy
+ *
+ * This strategy requires *every applicable policy* to return "permit".
+ * If at least one policy returns "deny" or "not applicable", the final result is "deny".
+ *
+ * Use this strategy when:
+ * - You want strict, conservative access control.
+ * - All rules must explicitly allow the action.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → permit
+ *     P2 → permit
+ *     P3 → deny
+ *   Result: deny (because not all policies permitted)
+ */
+declare class AllMustPermitStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    evaluate(): AbilityPolicyEffectType;
+}
+
+/**
+ * AnyPermitStrategy
+ *
+ * This strategy returns "permit" as soon as *any* applicable policy permits the action.
+ * If no policy permits, the result is "deny".
+ *
+ * Use this strategy when:
+ * - You want optimistic access control.
+ * - A single positive rule should be enough to grant access.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → deny
+ *     P2 → permit
+ *     P3 → deny
+ *   Result: permit (because at least one policy permitted)
+ */
+declare class AnyPermitStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    evaluate(): AbilityPolicyEffectType;
+}
+
+/**
+ * DenyOverridesStrategy
+ *
+ * This strategy gives absolute priority to "deny".
+ * If any applicable policy returns "deny", the final result is "deny".
+ * Otherwise, if at least one policy permits, the result is "permit".
+ *
+ * Use this strategy when:
+ * - Security is critical.
+ * - A single denial must block access.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → permit
+ *     P2 → deny
+ *     P3 → permit
+ *   Result: deny (because deny overrides everything)
+ */
+declare class DenyOverridesStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    evaluate(): AbilityPolicyEffectType;
+}
+
+/**
+ * FirstMatchStrategy
+ *
+ * This strategy evaluates policies in order and returns the result of the *first applicable* policy.
+ * Remaining policies are ignored.
+ *
+ * Use this strategy when:
+ * - Policy order matters.
+ * - You want predictable, sequential rule evaluation.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → not applicable
+ *     P2 → permit
+ *     P3 → deny
+ *   Result: permit (P2 is the first applicable)
+ */
+declare class FirstMatchStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    evaluate(): AbilityPolicyEffectType;
+}
+
+/**
+ * OnlyOneApplicableStrategy
+ *
+ * This strategy requires that *exactly one* policy is applicable.
+ * If zero or more than one policy applies, the result is "deny".
+ *
+ * Use this strategy when:
+ * - Policies must be mutually exclusive.
+ * - You want to detect ambiguous or conflicting rules.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → applicable
+ *     P2 → applicable
+ *   Result: deny (more than one applicable policy)
+ */
+declare class OnlyOneApplicableStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    evaluate(): AbilityPolicyEffectType;
+}
+
+/**
+ * PermitOverridesStrategy
+ *
+ * This strategy gives priority to "permit".
+ * If any applicable policy permits, the final result is "permit".
+ * Deny is returned only if no policy permits.
+ *
+ * Use this strategy when:
+ * - You want permissive behavior.
+ * - A single positive rule should override denials.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → deny
+ *     P2 → permit
+ *     P3 → deny
+ *   Result: permit (permit overrides deny)
+ */
+declare class PermitOverridesStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    evaluate(): AbilityPolicyEffectType;
+}
+
+/**
+ * SequentialLastMatchStrategy
+ *
+ * This strategy evaluates all applicable policies in order and returns the result of the *last* applicable one.
+ *
+ * Use this strategy when:
+ * - Later policies should override earlier ones.
+ * - You want a "last rule wins" behavior.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → permit
+ *     P2 → deny
+ *     P3 → permit
+ *   Result: permit (P3 is the last applicable)
+ */
+declare class SequentialLastMatchStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    evaluate(): AbilityPolicyEffectType;
+}
+
+/**
+ * PriorityStrategy
+ *
+ * This strategy evaluates policies based on their numeric priority.
+ * The policy with the highest priority (lowest number or highest number depending on implementation)
+ * determines the final result.
+ *
+ * Use this strategy when:
+ * - Policies have explicit priority levels.
+ * - You want deterministic resolution based on ranking.
+ *
+ * Example:
+ *   Policies:
+ *     P1 (priority 10) → deny
+ *     P2 (priority 1)  → permit
+ *   Result: permit (P2 has higher priority)
+ */
+declare class PriorityStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    evaluate(): AbilityPolicyEffectType;
+}
+
+export { AbilityCompare, AbilityCondition, AbilityDSLLexer, AbilityDSLParser, AbilityDSLToken, AbilityError, AbilityExplain, AbilityExplainPolicy, AbilityExplainRule, AbilityExplainRuleSet, AbilityJSONParser, AbilityMatch, AbilityParserError, AbilityPolicy, AbilityPolicyEffect, AbilityResolver, AbilityResult, AbilityRule, AbilityRuleSet, AbilityStrategy, AbilityTypeGenerator, AllMustPermitStrategy, AnyPermitStrategy, DenyOverridesStrategy, FirstMatchStrategy, OnlyOneApplicableStrategy, PermitOverridesStrategy, PriorityStrategy, SequentialLastMatchStrategy, TokenTypes, ability, fromLiteral, isConditionEqual, isConditionNotEqual, toLiteral };
+export type { AbilityCompareType, AbilityConditionCode, AbilityConditionLiteral, AbilityConditionType, AbilityExplainConfig, AbilityExplainType, AbilityMatchType, AbilityPolicyConfig, AbilityPolicyConstructorProps, AbilityPolicyEffectType, AbilityResolverOptions, AbilityRuleConfig, AbilityRuleConstructorProps, AbilityRuleSetConfig, AbilityRuleSetConstructorProps, EnvironmentObject, ExtractEnvironment, ExtractEnvironmentByPermission, ExtractPermission, ExtractResourceByPermission, ExtractResources, NestedDict, Primitive, ResourceObject, ResourcesMap, TokenType, TokenTypeCode };