@via-profit/ability 3.4.1 → 3.5.0

package/README.md

@@ -385,7 +385,7 @@ deny permission.order.update
 const policies = new AbilityDSLParser(dsl).parse();
 const resolver = new AbilityResolver(policies);
 
-await resolver.enforce('order.update', resource); // will throw AbilityError
+resolver.enforce('order.update', resource); // will throw AbilityError
 ```
 
 **Explanation**
@@ -669,7 +669,7 @@ const environment = {
   ip: req.ip,
 }
 
-await resolver.enforce('order.update', resource, environment);
+resolver.enforce('order.update', resource, environment);
 ```
 
 ### Using environment in rules
@@ -797,7 +797,7 @@ export type Resources = {
 ```ts
 import { policyResolver } from './policies';
 
-await resolver.enforce('order.update', {
+resolver.enforce('order.update', {
   user: { id: 'u1' },
   order: { ownerId: 'u1' },
 });
@@ -818,7 +818,7 @@ To simplify policy debugging, a special `AbilityResult` class is used, which is
 Example:
 
 ```ts
-const result = await resolver.resolve('order.update', resource);
+const result = resolver.resolve('order.update', resource);
 
 if (result.isDenied()) {
   console.log('Access denied');
@@ -841,7 +841,7 @@ const explanations = result.explain(); // AbilityExplain
 Usage example:
 
 ```ts
-const result = await resolver.resolve('order.update', resource);
+const result = resolver.resolve('order.update', resource);
 const explanations = result.explain();
 
 console.log(explanations.toString());
@@ -881,7 +881,7 @@ deny permission.test if all:
 const policies = new AbilityDSLParser(dsl).parse();
 const resolver = new AbilityResolver(policies);
 
-const result = await resolver.resolve('test', {
+const result = resolver.resolve('test', {
   user: { age: 16 },
 });
 
@@ -895,7 +895,7 @@ the condition is met → the policy matches → effect `deny` → access denied.
 **What happens if the conditions are *not met*?**
 
 ```ts
-const result = await resolver.resolve('test', {
+const result = resolver.resolve('test', {
   user: { age: 12 },
 });
 
@@ -984,7 +984,7 @@ export function useAbility<Permission extends keyof Resources>(
 
     async function check() {
       try {
-        const result = await resolver.resolve(permission, resource);
+        const result = resolver.resolve(permission, resource);
         if (!cancelled) {
           setAllowed(result.isAllowed());
         }
@@ -1224,7 +1224,7 @@ Example: buying a ticket.
 The `enforce` method throws an `AbilityError` if access is denied.
 
 ```ts
-await resolver.enforce('ticket.buy', {
+resolver.enforce('ticket.buy', {
   user: { age: 25, ticketsCount: 1 },
   env: { time: { hour: 18 } },
 });
@@ -1237,7 +1237,7 @@ If denied — an `AbilityError` exception is thrown.
 `resolve` returns a result object:
 
 ```ts
-const result = await resolver.resolve('ticket.buy', {
+const result = resolver.resolve('ticket.buy', {
   user: { age: 25, ticketsCount: 1 },
   env: { time: { hour: 18 } },
 });
@@ -1252,7 +1252,7 @@ if (result.isAllowed()) {
 **Seller can only sell during working hours**
 
 ```ts
-await resolver.enforce('ticket.sell', {
+resolver.enforce('ticket.sell', {
   user: { role: 'seller' },
   env: { time: { hour: 15 } },
   ticket: { status: 'available' },

package/dist/index.d.ts

@@ -1,19 +1,574 @@
-export * from './core/AbilityCode';
-export * from './core/AbilityCompare';
-export * from './core/AbilityCondition';
-export * from './core/AbilityError';
-export * from './core/AbilityMatch';
-export * from './core/AbilityTypeGenerator';
-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';
+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 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;
+}
+
+declare class AbilityError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+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 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;
+};
+type AbilityRuleConstructorProps = Omit<AbilityRuleConfig, 'condition'> & {
+    readonly condition: AbilityCondition;
+};
+/**
+ * Represents a rule that defines a condition to be checked against a subject and resource.
+ */
+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);
+    private isPrimitive;
+    private isNumber;
+    private isString;
+    private valueLen;
+    private operatorHandlers;
+    /**
+     * Check if the rule is matched
+     * @param resource - The resource to check
+     * @param environment
+     */
+    check(resource: Resources | null, environment?: Environment): 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;
+    copyWith(props: Partial<{
+        id: string | null;
+        name: string | null;
+        subject: string;
+        resource: AbilityRuleConfig['resource'];
+        condition: AbilityCondition;
+    }>): 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>;
+}
+
+type AbilityRuleSetConfig = {
+    readonly id?: string | null;
+    readonly name?: string | null;
+    readonly compareMethod: AbilityCompareCodeType;
+    readonly rules: readonly AbilityRuleConfig[];
+};
+type AbilityRuleSetConstructorProps = {
+    readonly id?: string | null;
+    readonly name?: string | null;
+    readonly compareMethod: AbilityCompare;
+};
+declare class AbilityRuleSet<Resources extends ResourceObject = Record<string, unknown>, Environment = unknown> {
+    state: AbilityMatch;
+    /**
+     * List of rules
+     */
+    rules: AbilityRule<Resources, Environment>[];
+    /**
+     * 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;
+    /**
+     * Group name
+     */
+    name: string;
+    /**
+     * Group ID
+     */
+    id: string;
+    constructor(params: AbilityRuleSetConstructorProps);
+    addRule(rule: AbilityRule<Resources, Environment>): this;
+    addRules(rules: AbilityRule<Resources, Environment>[]): this;
+    check(resources: Resources | null, environment?: Environment): AbilityMatch;
+    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>;
+}
+
+type AbilityPolicyEffectCodeType = 'deny' | 'permit';
+declare class AbilityPolicyEffect extends AbilityCode<AbilityPolicyEffectCodeType> {
+    static deny: AbilityPolicyEffect;
+    static permit: AbilityPolicyEffect;
+}
+
+type AbilityExplainConfig = {
+    readonly type: AbilityExplainType;
+    readonly name: string;
+    readonly match: AbilityMatch;
+};
+declare class AbilityExplain {
+    readonly type: AbilityExplainType;
+    readonly children: AbilityExplain[];
+    readonly name: string;
+    readonly match: AbilityMatch;
+    constructor(config: AbilityExplainConfig, children?: AbilityExplain[]);
+    toString(indent?: number): string;
+}
+declare class AbilityExplainRule extends AbilityExplain {
+    constructor(rule: AbilityRule);
+}
+declare class AbilityExplainRuleSet extends AbilityExplain {
+    constructor(ruleSet: AbilityRuleSet);
+}
+declare class AbilityExplainPolicy extends AbilityExplain {
+    constructor(policy: AbilityPolicy);
+}
+type AbilityExplainType = 'policy' | 'rule' | 'ruleSet';
+
+type AbilityPolicyConfig = {
+    readonly permission: string;
+    readonly effect: AbilityPolicyEffectCodeType;
+    readonly compareMethod: AbilityCompareCodeType;
+    readonly ruleSet: readonly AbilityRuleSetConfig[];
+    readonly id: string;
+    readonly name: string;
+};
+type AbilityPolicyConstructorProps = {
+    id: string;
+    name: string;
+    permission: string;
+    effect: AbilityPolicyEffect;
+    compareMethod?: AbilityCompare;
+};
+declare class AbilityPolicy<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown> {
+    matchState: AbilityMatch;
+    /**
+     * List of rules
+     */
+    ruleSet: AbilityRuleSet<Resource, Environment>[];
+    /**
+     * Policy effect
+     */
+    effect: AbilityPolicyEffect;
+    /**
+     * 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;
+    /**
+     * Policy ID
+     */
+    id: string;
+    /**
+     * Running the `enforce` or `resolve` method
+     * will select only those from all passed policies that fall under the specified permission key.
+     */
+    permission: string;
+    constructor(params: AbilityPolicyConstructorProps);
+    /**
+     * Add rule set to the policy
+     * @param ruleSet - The rule set to add
+     */
+    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 resource - The resource to check
+     * @param environment - The user environment object
+     */
+    check(resource: Resource, environment?: Environment): AbilityMatch;
+    explain(): AbilityExplain;
+    copyWith(props: Partial<{
+        id: string;
+        name: string;
+        permission: string;
+        effect: AbilityPolicyEffect;
+        compareMethod: AbilityCompare;
+        ruleSet: AbilityRuleSet<Resource, Environment>[];
+    }>): AbilityPolicy<Resource, Environment>;
+}
+
+type Primitive = string | number | boolean | null | undefined;
+type NestedDict<T = Primitive> = {
+    [key: string]: NestedDict<T> | T;
+};
+type ResourceObject = Record<string, unknown>;
+type ResourcesMap = Record<string, ResourceObject>;
+declare class AbilityTypeGenerator {
+    readonly policies: readonly AbilityPolicy[];
+    constructor(policies: readonly AbilityPolicy[]);
+    /**
+     * Generates TypeScript type definitions based on the provided policies.
+     * @returns A generated type definitions.
+     */
+    generateTypeDefs(): string;
+    /**
+     * Determines TypeScript type based on the rule
+     * @param rule - The rule to analyze
+     * @returns TypeScript type as string
+     */
+    private determineTypeFromRule;
+    /**
+     * Gets TypeScript type for array values
+     * @param resource - The resource value to analyze
+     * @returns TypeScript array type as string
+     */
+    private getArrayType;
+    /**
+     * Gets primitive TypeScript type for a value
+     * @param value - The value to analyze
+     * @returns TypeScript primitive type as string
+     */
+    private 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 buildNestedStructure;
+    /**
+     * Formats type structure into a string
+     * @param structure - Nested type structure
+     * @returns Formatted TypeScript type definition string
+     */
+    private formatTypeDefinitions;
+    /**
+     * Recursively formats nested object
+     * @param obj - Object to format
+     * @param indent - Current indentation level
+     * @returns Formatted string
+     */
+    private formatNestedObject;
+}
+
+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;
+}
+
+declare class AbilityResolver<Resources extends ResourcesMap, Environment = unknown> {
+    private policies;
+    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>);
+    /**
+     * 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): AbilityResult<Resources[Permission]>;
+    enforce<Permission extends keyof Resources>(permission: Permission, resource: Resources[Permission], environment?: Environment): 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;
+}
+
+declare class AbilityJSONParser {
+    /**
+     * Parses an array of policy configurations into an array of AbilityPolicy instances.
+     * @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>;
+    /**
+     * 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 ruleToJSON(rule: AbilityRule): AbilityRuleConfig;
+    static ruleSetToJSON(ruleSet: AbilityRuleSet): AbilityRuleSetConfig;
+    static policyToJSON(policy: AbilityPolicy): AbilityPolicyConfig;
+    static toJSON(policies: readonly AbilityPolicy[]): AbilityPolicyConfig[];
+}
+
+/**
+ * Parser for the Ability DSL.
+ *
+ * Converts a DSL string into one or more AbilityPolicy instances.
+ * The grammar follows the structure:
+ *
+ *   <effect> <permission> if <group> [ <group> ... ]
+ *
+ * where <group> is either "all of:" or "any of:", followed by a colon,
+ * and then a list of rules (one per line).
+ *
+ * Each rule is: <identifier> <operator> <value>
+ *
+ * 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;
+    constructor(dsl: string);
+    /**
+     * Main entry point: tokenize the input and parse all policies.
+     * @returns Array of AbilityPolicy instances.
+     */
+    parse(): readonly AbilityPolicy<Resource, Environment>[];
+    /**
+     * Parses a single policy from the current token position.
+     *
+     * Grammar:
+     *   policy = EFFECT PERMISSION IF (ALL | ANY) COLON ruleSets
+     */
+    private parsePolicy;
+    /**
+     * Parses a sequence of rule sets (groups) until a new policy starts or EOF.
+     */
+    private parseRuleSets;
+    /**
+     * Parses a single group, e.g. "all of:" or "any of:", and returns a RuleSet.
+     */
+    private parseGroup;
+    /**
+     * Parses a single rule: subject operator value
+     */
+    private parseRule;
+    /**
+     * Parses the comparison operator part of a rule.
+     * Returns both the resulting AbilityCondition and the token type that was consumed.
+     */
+    private parseConditionOperator;
+    /**
+     * Helper to match and consume a specific word token (KEYWORD or IDENTIFIER).
+     * @param word The exact string to look for.
+     * @returns True if the next token has that value.
+     */
+    private matchWord;
+    private matchSymbol;
+    /**
+     * Parses a resource value. Can be a string literal, number, boolean,
+     * null, a path (identifier), or an array.
+     */
+    private parseValue;
+    /**
+     * Parses an array literal: [ <value>, <value>, ... ]
+     * The opening bracket has already been consumed.
+     */
+    private parseArray;
+    private consumeLeadingComments;
+    private processCommentToken;
+    private takeAnnotations;
+    private syntaxError;
+    private suggest;
+    private levenshteinDistance;
+    private consumeOneOf;
+    private consume;
+    private check;
+    private isStartOfPolicy;
+    private isStartOfGroup;
+    private advance;
+    private peek;
+    private isAtEnd;
+}
+
+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"). */
+    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"
+     */
+    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 {
+    private readonly input;
+    private pos;
+    private tokens;
+    private line;
+    private column;
+    private readonly keywords;
+    constructor(input: string);
+    tokenize(): AbilityDSLToken[];
+    private readComment;
+    private readString;
+    private readNumber;
+    private readSymbol;
+    private readWord;
+    private skipWhitespace;
+    private isDigit;
+    private isAlpha;
+    private isSymbol;
+    private isNewline;
+    private peek;
+    private advance;
+    private isAtEnd;
+}
+
+export { AbilityCode, AbilityCompare, AbilityCondition, AbilityDSLLexer, AbilityDSLParser, AbilityDSLToken, AbilityError, AbilityExplain, AbilityExplainPolicy, AbilityExplainRule, AbilityExplainRuleSet, AbilityJSONParser, AbilityMatch, AbilityParserError, AbilityPolicy, AbilityPolicyEffect, AbilityResolver, AbilityResult, AbilityRule, AbilityRuleSet, AbilityTypeGenerator };
+export type { AbilityCompareCodeType, AbilityConditionCodeType, AbilityConditionLiteralType, AbilityExplainConfig, AbilityExplainType, AbilityMatchCodeType, AbilityPolicyConfig, AbilityPolicyConstructorProps, AbilityPolicyEffectCodeType, AbilityRuleConfig, AbilityRuleConstructorProps, AbilityRuleSetConfig, AbilityRuleSetConstructorProps, NestedDict, Primitive, ResourceObject, ResourcesMap, TokenType };