@via-profit/ability 3.0.1 → 3.1.1

package/README.md

@@ -1,1181 +1,1147 @@
 # @via-profit/Ability
 
-> Набор сервисов, частично реализующих
-> принцип [Attribute Based Access Control](https://en.wikipedia.org/wiki/Attribute-based_access_control)
-
-Этот сервис позволяет создавать правила и политики, применять их к данным и проверять доступ на их основе.
-
-## Содержание
-
-- [Обзор](#обзор)
-  - [Состав пакета](#состав-пакета)
-  - [Основные принципы](#основные-принципы)
-- [Правила](#правила)
-  - [Создание правила](#создание-правила)
-  - [Проверка правила](#проверка-правила)
-- [Группы правил](#группы-правил)
-  - [Создание группы правил](#создание-группы-правил)
-  - [Проверка группы правил](#проверка-группы-правил)
-- [Политики](#политики)
-  - [Создание политики](#создание-политики)
-  - [Проверка политики](#проверка-политики)
-- [Управление политиками](#управление-политиками)
-  - [Зачем нужен AbilityResolver?](#зачем-нужен-abilityresolver)
-  - [Использование wildcard (*) в действиях](#использование-wildcard--в-действиях)
-  - [Как это работает](#как-это-работает)
-  - [Проверка соответствия действия](#проверка-соответствия-действия)
-  - [Методы AbilityResolver](#методы-abilityresolver)
-  - [Интеграция с TypeScript](#интеграция-с-typescript)
-  - [Как формируется итоговое решение?](#как-формируется-итоговое-решение)
-  - [Когда использовать Resolver?](#когда-использовать-resolver)
-- [API Reference](#api-reference)
-  - [Класс AbilityCode](#класс-abilitycode)
-  - [Класс AbilityMatch](#класс-abilitymatch)
-  - [Класс AbilityCondition](#класс-abilitycondition)
-  - [Класс AbilityCompare](#класс-abilitycompare)
-  - [Класс AbilityPolicyEffect](#класс-abilitypolicyeffect)
-  - [Класс AbilityRule](#класс-abilityrule)
-  - [Класс AbilityRuleSet](#класс-abilityruleset)
-  - [Класс AbilityPolicy](#класс-abilitypolicy)
-  - [Класс AbilityResolver](#класс-abilityresolver)
-  - [Класс AbilityExplain](#класс-abilityexplain)
-  - [Класс AbilityParser](#класс-abilityparser)
-  - [Классы ошибок](#классы-ошибок)
-- [Рекомендации по использованию](#рекомендации-по-использованию)
-  - [Именование экшенов](#именование-экшенов)
-  - [Структура данных](#структура-данных)
-  - [Проектирование политик](#проектирование-политик)
-- [Отладка политик](#отладка-политик)
-- [Лицензия](#лицензия)
+> A set of services that partially implement the [Attribute Based Access Control](https://en.wikipedia.org/wiki/Attribute-based_access_control) principle.
+> The package allows you to describe rules, combine them into groups, form policies, and apply them to data to determine permissions.
 
----
+## Language / Язык
 
-## Обзор
-
-### Состав пакета
-
-- **`AbilityRule`** — класс отдельного правила
-- **`AbilityRuleSet`** — класс группы правил
-- **`AbilityPolicy`** — класс политики
-- **`AbilityResolver`** — управление политиками
-- **`AbilityMatch`** — константы состояния правил (`pending`, `match`, `mismatch`)
-- **`AbilityCompare`** — способы сравнения (`or`, `and`)
-- **`AbilityCondition`** — методы вычисления (`equal`, `not_equal`, `more_than`, `less_than`, `in`, `not_in` и др.)
-- **`AbilityPolicyEffect`** — эффекты политики (`deny`, `permit`)
-- **`AbilityParser`** — парсер конфигурационных правил (JSON) и генератор `Typescript` типов
-- **`AbilityError`** — инстанс ошибок
-- **`AbilityExplain`** — вспомогательный инструмент, который позволяет получить человекочитаемое объяснение того, почему конкретное действие разрешено или запрещено текущей конфигурацией Ability
-
-### Основные принципы
-
-Работа сервиса основана на формировании **правил**, объединении их в **политики** и проверке доступа с их помощью.
-
-Пример: необходимо **запретить доступ** пользователям, связанным с отделом менеджеров, **за исключением администраторов**.
-
-- Менеджеры — если их отдел `managers` или есть роль `manager`
-- Администраторы — пользователи с ролью `administrator`
-
-Структура политики:
-
-![ability-01.png](./assets/ability-01.drawio.png)
-
-JSON-конфигурация:
-
-```json
-{
-  "name": "Запрет доступа для менеджеров (исключение: администраторы)",
-  "compareMethod": "and",
-  "action": "order.update",
-  "effect": "deny",
-  "ruleSet": [
-    {
-      "name": "Менеджеры",
-      "compareMethod": "or",
-      "rules": [
-        {
-          "name": "Отдел managers",
-          "subject": "user.department",
-          "resource": "managers",
-          "condition": "in"
-        },
-        {
-          "name": "Роль manager",
-          "subject": "user.roles",
-          "resource": "manager",
-          "condition": "in"
-        }
-      ]
-    },
-    {
-      "name": "Не администраторы",
-      "compareMethod": "and",
-      "rules": [
-        {
-          "name": "Нет роли administrator",
-          "subject": "user.roles",
-          "resource": "administrator",
-          "condition": "not in"
-        }
-      ]
-    }
-  ]
-}
+- [🇬🇧 English](/docs/en/README.md)
+- [🇷🇺 Русский](/docs/ru/README.md)
+
+## Purpose
+
+The package is intended as a **lightweight and extremely simple alternative** to heavy access control systems.  
+Without complex configurations, without dependencies — just a minimal set of tools that allows you to describe rules and policies in a maximally simple DSL.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Fundamentals](#fundamentals)
+- [DSL](#dsl)
+- [Combining Policies](#combining-policies)
+- [Policy Environment](#policy-environment)
+- [TypeScript Type Generator](#typescript-type-generator)
+- [Policy Debugging](#policy-debugging)
+- [Troubleshooting](#troubleshooting)
+- [Design Recommendations](#design-recommendations)
+- [Examples](#examples)
+- [Performance](#performance)
+- [API Reference](./api.md)
+
+## Quick Start
+
+Install the package, write DSL, call the parser, and run the resolver.
+
+### Installation
+
+```bash
+npm install @via-profit/ability
+```
+
+```bash
+yarn add @via-profit/ability
 ```
 
-Применение политики:
+```bash
+pnpm add @via-profit/ability
+```
+
+### Example: Deny access to `passwordHash` for everyone except the owner
+
+Suppose we have user data:
 
 ```ts
-const jsonConfig = { ... };
-AbilityPolicy.parse(jsonConfig).check({
-  user: {
-    department: 'managers',
-    roles: ['manager', 'coach'],
-  }
-});
+const user = {
+  id: '1',
+  login: 'user-001',
+  passwordHash: '...',
+};
 ```
 
----
+We need to deny reading `passwordHash` to everyone except the user themselves.
+
+#### DSL Policy
 
-## Правила
+In the policy language, this looks like:
 
-**Правила** выполняют условие проверки и возвращают результат. **Основная цель** - выполнить сравнение переданных
-значений субъекта и ресурса, а затем вернуть результат такого сравнения.
+```
+deny permission.user.passwordHash if any:
+  viewer.id is not equals owner.id
+```
 
-### Создание правила
+**Explanation:**
 
-Создать правило можно двумя способами: создание через конструктор класса и парсинг JSON-конфига правила.
+- `deny` — policy effect (deny access)
+- `permission.user.passwordHash` — permission key.
+- `if any:` — start of the condition block
+- `viewer.id is not equals owner.id` — rule: if the requester's ID is not equal to the owner's ID
 
-При создании необходимо указать следующие параметры:
+If `viewer.id` is not equal to `owner.id`, the rule is satisfied and the policy returns `deny` — access denied. If the IDs match (i.e., the user requests their own data), the rule does not trigger, and access is allowed.
 
-- **id** - `string` Уникальный идентификатор.
-- **name** - `string` Название правила.
-- **condition** - `AbilityCondition` Определяет условия сравнения переданных данных
-- **subject** - `string` Dot notation путь в проверяемом субъекте, например: `user.name`.
-- **resource** - `string | number | boolean | (string | number)[]` Dot notation путь в проверяемом ресурсе, например:
-  `user.name` или значение, которое может быть строкой, числом, булеан значением или массивом строк, или чисел.
+*Note: The permission key is formed according to the principle: `permission.` + your custom key in dot notation. For example, the key `foo.bar.baz` in DSL would be `permission.foo.bar.baz`.*
 
-_Создание правила через конструктор класса:_
+#### Check in Code
 
 ```ts
-import { AbilityRule, AbilityCondition } from '@via-profit/ability';
-
-const rule = new AbilityRule({
-  id: '<rule-id>',
-  name: 'Пользователь из отдела managers',
-  subject: 'user.department',
-  resource: 'managers',
-  condition: AbilityCondition.equal
-});
+import { AbilityDSLParser, AbilityResolver } from '@via-profit/ability';
 
-// сокращённая запись
-const rule2 = AbilityRule.equal(
-  'user.department', // subject
-  'managers' // resource
-);
+const dsl = `
+deny permission.user.passwordHash if any:
+  viewer.id is not equals owner.id
+`;
+
+const policies = new AbilityDSLParser(dsl).parse(); // obtain policies
+const resolver = new AbilityResolver(policies); // create resolver
 
+resolver.enforce('user.passwordHash', {
+  viewer: { id: '1' },
+  owner: { id: '2' },
+}); // will throw an error — access denied
 ```
+In `enforce`, the key is passed without the `permission.` prefix — it is automatically removed by the parser.
 
-_Создание правила через парсинг JSON-конфигурации:_
+## Fundamentals
 
-```ts
-import { AbilityRule } from '@via-profit/ability';
-
-const rule = AbilityRule.parse({
-  "id": "<rule-id>",
-  "name": "Пользователь из отдела managers",
-  "subject": "user.department",
-  "resource": "managers",
-  "condition": "="
-});
+Let’s briefly list the key points you need to know before starting to use the package:
 
+1. The resolver (`AbilityResolver`) follows the **Default Deny** principle. This means that if no policy matches, the result is `deny` ([more details here](#troubleshooting)). To avoid unexpected `deny`, ensure there is at least one `permit` policy that can match. Only then add `deny` policies.
+2. Policies are applied sequentially. If multiple policies match, the result is determined by the last matching policy.
+3. Rules are executed sequentially.
+4. In a rule set (`RuleSet`) with the `all` comparison operator, further rule execution stops as soon as the first rule returns `mismatch`.
+5. Use [DSL](#dsl) to compose policies — it's simpler and more convenient.
+6. For storing policies on the server, use JSON. Policies can be exported to JSON and imported from JSON.
+7. Generally, rely on the principle: if permission is not explicitly granted → access is denied.
+8. Use the built-in cache only if your policies are incredibly complex and contain a large number of rules.
+
+---
+
+## DSL
+
+> DSL - Domain-Specific Language
+
+Ability DSL is a declarative language for describing access policies.  
+It allows you to define rules in a human-readable form using simple constructs: *policies*, *groups*, *rules*, and *annotations*.
+
+### Policy Structure
+
+A policy consists of:
+
+```
+<effect> <permission> if <all|any>:
+  <group>...
 ```
 
-### Проверка правила
+Where:
 
-Для проверки правила следует вызвать метод `check` класса `AbilityRule` передав объект проверяемого ресурса. Этот метод
-вернёт экземпляр класса
-`AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение правила и переданных значений.
+- **effect** — `permit` or `deny`
+- **permission** — a string of the form `permission.foo.bar`, where the `permission.` prefix is mandatory.
+- **if all:** — all groups must be true
+- **if any:** — at least one group must be true
 
-```ts
-import { AbilityRule } from '@via-profit/ability';
-
-const rule = AbilityRule.parse({
-  "id": "<rule-id>",
-  "name": "Пользователь из отдела managers",
-  "subject": "user.department",
-  "resource": "managers",
-  "condition": "="
-});
+A policy can contain one or more rule groups.
 
-const match = rule.check({
-  user: {
-    department: 'managers',
-  },
-});
+Example:
 
-const is = match.isEqual(AbilityMatch.match); // true
+```dsl
+permit permission.order.update if any:
+  all of:
+    user.roles contains 'admin'
+    user.token is not null
 
+  any of:
+    user.roles contains 'developer'
+    user.login is equals 'dev'
 ```
 
-## Получение пояснений (AbilityExplain)
+> The `permission.` prefix is mandatory in DSL but is automatically removed by the parser. Internally, the permission is stored as `order.update`.
+
+The example policy above says: permission `order.update` will be allowed if one of two conditions is met:
+1. `user.roles` contains 'admin' **and** `user.token` is not null
+2. `user.roles` contains 'developer' **or** `user.login` equals 'dev'
 
-Для отладки или аудита может быть полезно понять, *почему* было вынесено то или иное суждение о правах доступа. Метод `resolveWithExplain()` политики возвращает детальную информацию о проверке.
+### Permission Key
 
-### Использование
+Permission keys are written in dot notation but support the use of wildcard patterns with the `*` character. This allows grouping of keys and overriding policies with similar keys.
 
+If multiple policies match a key, **all of them are executed**. The final result is determined by the **last matching policy**:
+
+**Example of using wildcards**
+
+| Policy (permission) | Key                   | Matches |
+|---------------------|-----------------------|---------|
+| `order.*`           | `order.create`        | yes     |
+| `order.*`           | `order.update`        | yes     |
+| `order.*`           | `user.create`         | no      |
+| `*.create`          | `order.create`        | yes     |
+| `*.create`          | `user.create`         | yes     |
+| `*.create`          | `order.update`        | no      |
+| `user.profile.*`    | `user.profile.update` | yes     |
+| `user.profile.*`    | `user.settings.update`| no      |
+
+**Example of a policy with wildcard**
 ```ts
-const config: AbilityPolicyConfig = {
-  id: 'bb758c1b-1015-4894-ba25-d23156e063cf',
-  name: 'Запрещает менять статус заявки с `не обработан` на `завершен` всем, кроме администраторам',
-  action: 'order.status',
-  effect: 'deny',
-  compareMethod: 'and',
-  ruleSet: [
-    {
-      id: '9cc009e5-0aa9-453a-a668-cb3f418ced92',
-      name: 'Не администратор',
-      compareMethod: 'and',
-      rules: [
-        {
-          id: '4093cd50-e54f-4062-8053-2d3b5966fad3',
-          name: 'Нет роли администраторов',
-          subject: 'user.roles',
-          resource: 'administrator',
-          condition: 'not in',
-        },
-      ],
-    },
-    {
-      id: '2f8f9d71-860b-4fa6-b395-9331f1f0848e',
-      name: 'Проверка статуса `не обработан` -> `завершен`',
-      compareMethod: 'and',
-      rules: [
-        {
-          id: 'a3c7d66f-5c2d-4a24-83bc-03b0a2d9c32b',
-          name: 'Текущий статус `не обработан`',
-          subject: 'order.status',
-          resource: 'не обработан',
-          condition: '=',
-        },
-        {
-          id: 'a3c7d66f-5c2d-4a24-83bc-03b0a2d9c32b',
-          name: 'Будущий статус `завершен`',
-          subject: 'feature.status',
-          resource: 'завершен',
-          condition: '=',
-        },
-      ],
-    },
-  ],
-};
+import { AbilityDSLParser, AbilityResolver } from '@via-profit/ability';
 
-const policy = AbilityPolicy.parse<Resources>(config);
-const resolver = new AbilityResolver(policy);
-const explain = resolver.resolveWithExplain('order.status', {
-  user: {
-    roles: ['user', 'couch'],
-  },
-  order: {
-    status: 'не обработан',
-  },
-  feature: {
-    status: 'завершен',
-  },
-});
+// DSL is not complete, shown for illustration only
+const dsl = `
+permit permission.order.*
+deny permission.order.update
+`;
 
-explain.forEach((e) => {
-  console.debug(e.toString());
-});
+const policies = new AbilityDSLParser(dsl).parse();
+const resolver = new AbilityResolver(policies);
 
-type Resources = {
-  ['order.status']: {
-    readonly user: {
-      readonly roles: readonly string[];
-    };
-    readonly order: {
-      readonly status: string;
-    };
-    readonly feature: {
-      readonly status: string;
-    };
-  };
-};
+await resolver.enforce('order.update', resource); // will throw AbilityError
+```
+
+**Explanation**
+
+In DSL, the order of policies matters:
+the last matching policy wins.
+
+Therefore:
+
+1. `permit` `permission.order.*` allows everything that starts with `order.`
+2. `deny` `permission.order.update` overrides this permission.
+
+Execution result:
 
 ```
+order.update → deny
+order.create → permit
+order.delete → permit
+order.view   → permit
+```
+
+### Comments
 
-Результат `console.debug`
+Lines starting with the `#` symbol are considered comments and do not affect the evaluation of rules and policies.
+
+---
+
+### Annotations
+
+Currently, only one annotation is supported: `name`, which will be used as the name for a policy, rule group, or rule.
+
+Annotations are specified via comments:
 
 ```
-✓ policy «Запрещает менять статус заявки...» is match
-✓ ruleSet «Не администратор» is match
-✓ rule «Нет роли администраторов» is match
-✓ ruleSet «Проверка статуса...» is match
-✓ rule «Текущий статус "не обработан"» is match
-✓ rule «Будущий статус "завершен"» is match
+# @name <name>
+```
+
+Annotations apply to the **following entity**:
+
+- policy
+- group
+- rule
+
+Example:
+
+```dsl
+# @name can order update
+permit permission.order.update if any:
+  # @name authorized admin
+  all of:
+    # @name contains role admin
+    user.roles contains 'admin'
 ```
 
 ---
 
-## Группы правил
+### Rule Groups
 
-**Группы правил** необходимы для объединения нескольких правил в группу. **Основная цель** - выполнить проверку каждого
-правила в группе и вернуть лишь один результат.
+A group defines how the rules within it are combined:
 
-Создавая группу следует указывать метод сравнения (`compareMethod`), который необходим для вычисления значения всей
-группы при проверке правил.
+```
+all of:
+  <rule>
+  <rule>
 
-При создании необходимо указать следующие параметры:
+any of:
+  <rule>
+  <rule>
+```
 
-- **id** - `string` Уникальный идентификатор.
-- **name** - `string` Название группы.
-- **compareMethod** - `AbilityCompare` Способ сравнения правил в группе (`or` или `and`).
+- `all of:` — logical AND
+- `any of:` — logical OR
 
-_Влияние **compareMethod** на результат вычисления группы:_
+`all of` means that the group is considered satisfied if all rules within the group match.
 
-- **`or`** - Результат всей группы примет значение `match`, если хотя бы одно из правил вернуло `match`.
-- **`and`** - Результат всей группы примет значение `match`, если все правила вернули `match`.
+`any of` means that the group is considered satisfied if at least one rule within the group matches.
 
-### Создание группы правил
+Each group within a policy will be evaluated independently of other groups. The final result is determined by comparing the results of all groups in the policy.
 
-Создать группу правил можно двумя способами: создание через конструктор класса и парсинг JSON-конфига группы.
+Groups can have annotations:
 
-_Создание группы через конструктор класса_:
+```dsl
+# @name developer group
+any of:
+  user.roles contains 'developer'
+```
 
-```ts
-import { AbilityRuleSet, AbilityCompare } from '@via-profit/ability';
+---
 
-const ruleSet = new AbilityRuleSet({
-  id: '<set-id>',
-  name: 'Название группы',
-  compareMethod: AbilityCompare.and,
-});
+### Rules
+
+A rule is an atomic condition inside a policy. It defines under what data the policy is considered matched. Rules set the conditions that determine the effectiveness of a policy (`permit` or `deny`).
 
-// Добавление правил в группу
-ruleSet.addRules([
-  new AbilityRule(...),
-  new AbilityRule(...),
-]);
+A rule has the form:
+
+```
+<subject> <operator> <value?> — the value is not required for some operators (e.g., `is null` does not require a value).
+```
 
+#### Subject
 
-// Сокращённая запись
-const ruleSet2 = AbilityRuleSet.and([
-  new AbilityRule(...),
-  new AbilityRule(...),
-]);
+Identifier in dot notation:
 
+```
+user.roles
+env.time.hour
+order.total
 ```
 
-_Создание группы через парсинг JSON-конфига группы_:
+#### Operators
 
-```ts
-import { AbilityRuleSet } from '@via-profit/ability';
-
-const ruleSet = AbilityRuleSet.parse({
-  'id': '<set-id>',
-  'name': 'Название группы',
-  'compareMethod': 'and',
-  'rules': [
-    {
-      'id': '<rule-id>',
-      'name': 'Пользователь из отдела managers',
-      'subject': 'user.department',
-      'resource': 'managers',
-      'condition': '=',
-    },
-  ],
-});
+*Synonyms are alternative forms of writing that are also supported by the parser.*
+
+**Basic Comparison Operators**
+
+| DSL Operator | Synonyms | Example | Description | Types |
+|--------------|----------|---------|-------------|-------|
+| **is equals** | `=`, `==`, `equals` | `age is equals 18` | Strict equality | number, string, boolean |
+| **is not equals** | `!=`, `<>`, `not equals` | `role is not equals 'admin'` | Strict inequality | number, string, boolean |
+| **greater than** | `>`, `gt` | `age greater than 18` | Greater than | number, date |
+| **greater than or equal** | `>=`, `gte` | `age greater than or equal 18` | Greater than or equal | number, date |
+| **less than** | `<`, `lt` | `age less than 18` | Less than | number, date |
+| **less than or equal** | `<=`, `lte` | `age less than or equal 18` | Less than or equal | number, date |
+
+**Null Operators**
+
+| DSL Operator | Synonyms | Example | Description | Types |
+|--------------|----------|---------|-------------|-------|
+| **is null** | `== null`, `= null` | `middleName is null` | Value is absent | any |
+| **is not null** | `!= null` | `middleName is not null` | Value is present | any |
+
+**Operators for Lists (Arrays)**
+
+| DSL Operator | Synonyms                  | Example | Description | Types |
+|--------------|---------------------------|---------|-------------|-------|
+| **in [...]** | -                         | `role in ['admin', 'manager']` | Value is in the list | number, string |
+| **not in [...]** | -                         | `role not in ['banned']` | Value is not in the list | number, string |
+| **contains** | `includes`, `has`         | `tags contains 'vip'` | Array contains the element | array |
+| **not contains** | `not includes`, `not has` | `tags not contains 'vip'` | Array does not contain the element | array |
 
+**String Operators**
+
+| DSL Operator | Synonyms | Example | Description | Types |
+|--------------|----------|---------|-------------|-------|
+| **starts with** | `begins with` | `email starts with 'admin@'` | String starts with | string |
+| **not starts with** | — | `email not starts with 'test'` | String does not start with | string |
+| **ends with** | — | `email ends with '.ru'` | String ends with | string |
+| **not ends with** | — | `email not ends with '.com'` | String does not end with | string |
+| **includes** | `contains substring` | `name includes 'lex'` | String contains substring | string |
+| **not includes** | — | `name not includes 'test'` | String does not contain substring | string |
+
+**Boolean Operators**
+
+| DSL Operator | Synonyms | Example | Description | Types |
+|--------------|----------|---------|-------------|-------|
+| **is true** | `= true` | `isActive is true` | Value is true | boolean |
+| **is false** | `= false` | `isActive is false` | Value is false | boolean |
+
+**Length Operators**
+
+| DSL Operator | Synonyms | Example | Description | Types |
+|--------------|----------|---------|-------------|-------|
+| **length equals** | `len =` | `tags length equals 3` | Length equals | array, string |
+| **length greater than** | `len >` | `tags length greater than 2` | Length greater than | array, string |
+| **length less than** | `len <` | `tags length less than 5` | Length less than | array, string |
+
+#### Value
+
+Supported values:
+
+- strings `'text'`
+- numbers `42`
+- booleans `true` / `false`
+- `null`
+- arrays `[1, 2, 3]` / `['foo', false, null, 1, 2, '999']`
+
+Examples:
+
+```dsl
+# user age greater than 18
+user.age greater than 18
+
+# array of roles contains the role 'admin'
+user.roles contains 'admin'
+
+# order tag is either 'vip' or 'priority'
+order.tag in ['vip', 'priority']
+
+# user token is not null
+user.token is not null
+
+# user login is longer than 12 characters
+user.login length greater than 12
 ```
 
-### Проверка группы правил
+---
 
-Для проверки группы правил следует вызвать метод `check` класса `AbilityRuleSet` передав объект проверяемого ресурса.
-Этот метод вернёт экземпляр класса `AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение
-для группы и переданных значений.
+### Implicit Group
 
-```ts
-import { AbilityRuleSet, AbilityCompare } from '@via-profit/ability';
+If rules are written without `all of:` or `any of:`, they are combined using the policy operator:
 
-const ruleSet = new AbilityRuleSet({
-  id: '<set-id>',
-  name: 'Название группы',
-  compareMethod: AbilityCompare.and,
-}).addRules([
-  new AbilityRule(...),
-  new AbilityRule(...),
-]);
+```dsl
+permit permission.order.update if all:
+  user.roles contains 'admin'
+  user.token is not null
+```
 
-const match = rule.check({ ... });
+Equivalent to:
 
-const is = match.isEqual(AbilityMatch.match);
+```dsl
+permit permission.order.update if all:
+  all of:
+    user.roles contains 'admin'
+    user.token is not null
 ```
 
-___
+The implicit group always matches the policy operator (`if all` or `if any`).
+
+---
+
+### Complete Example
 
-## Политики
+```dsl
+# @name order update allowed
+permit permission.order.update if any:
 
-**Политики** включают в себя группы правил. Основная цель - выполнить проверку всех вложенных групп, сравнить результат
-выполнения групп и вернуть один единственный результат.
+  # @name if admin
+  all of:
+    user.roles contains 'admin'
+    user.token is not null
 
-### Создание политики
+  # @name if developer
+  any of:
+    user.roles contains 'developer'
+    user.login is equals 'dev'
+```
 
-Создать политику можно двумя способами: создание через конструктор класса и парсинг JSON-конфига политики.
+## Combining Policies
 
-При создании политики необходимо указать следующие параметры:
+In a real project, you should use multiple policies at once.
 
-- **id** - `string` Уникальный идентификатор.
-- **name** - `string` Название политики.
-- **action** - `string` Ключ политики, в формате Dot notation, определяющий схожесть политик. В названии может
-  применяться символ звездочки (`*`). Политики с одинаковым экшеном обрабатываются вместе как группа политик. Экшен
-  `users.account` не считается похожим с экшеном `users.account.login`, но в это же время `users.account.*` равен экшену
-  `users.account.login` (из-за использования звездочки).
-- **compareMethod** - `AbilityCompare` Метод сравнения групп правил, входящих в политику (`or` или `and`)
-- **effect** - `AbilityPolicyEffect` Определяет итоговый результат всех вычислений (`permit` или `deny`). В слчае
-  использования класса `AbilityResolver` (метод `enforce`) последний выкинет исключение `AbilityError`, если политика
-  вернёт `deny`. Текст сообщения `AbilityError` будет соответствовать названию сработавшей политики. В остальных случаях
-  ничего не произойдет.
-- **ruleSet** - `AbilityRuleSet[]` Массив групп (см. [Группы правил](#группы-правил))
+TODO: using multiple policies
 
-**Замечание** - Политика может быть запрещающей (`effect` = `deny`) и разрешающей (`effect` = `permit`). Если вам
-необходимо ограничить какой-либо доступ, например, пользователю с недостаточными правами, то следует создавать политику
-с эффектом `deny`.
+## Policy Environment
 
-_Создание политики через конструктор класса_:
+**Environment** is an object containing context data that does not belong to either the user or the resource.  
+The content of the object is defined by the developer and can be any object consisting of primitives.
 
-```ts
-import { AbilityPolicy, AbilityCondition } from '@via-profit/ability';
-
-const policy = new AbilityPolicy({
-  id: '<policy-id>',
-  name: 'Пример политики',
-  effect: 'deny',
-  action: 'users.update',
-  compareMethod: 'and',
-  ruleSet: [
-    new AbilityRule({
-      id: '<rule-id>',
-      name: 'Пользователь является владельцем заказа',
-      subject: 'user.id',
-      resource: 'order.owner',
-      condition: AbilityCondition.equal
-    })
-  ]
-});
+- request time,
+- IP address,
+- device parameters,
+- request headers,
+- session context,
+- any other external conditions.
+
+**Examples:**
 
+```ts
+type Environment = {
+  time: {
+    hour: number;
+  };
+  ip: string;
+  geo: {
+    country: string;
+  };
+};
 ```
 
-_Создание политики через парсинг JSON-конфига_:
+Environment is passed to `resolve()` and `enforce()` as the third argument:
 
 ```ts
-import { AbilityPolicy } from '@via-profit/ability';
-
-const policy = AbilityPolicy.parse({
-  "id": "bb758c1b-1015-4894-ba25-d23156e063cf",
-  "name": "Status hui",
-  "action": "order.status",
-  "effect": "deny",
-  "compareMethod": "and",
-  "ruleSet": [
-    {
-      "id": "9cc009e5-0aa9-453a-a668-cb3f418ced92",
-      "name": "Не администратор",
-      "compareMethod": "and",
-      "rules": [
-        {
-          "id": "4093cd50-e54f-4062-8053-2d3b5966fad3",
-          "name": "Нет роли администраторв",
-          "subject": "account.roles",
-          "resource": "administrator",
-          "condition": "<>"
-        }
-      ]
-    }
-  ]
-});
+await resolver.resolve('order.update', resource, environment);
+await resolver.enforce('order.update', resource, environment);
+```
+
+### Using environment in rules
+
+In a policy, you can refer to environment via the `env.*` path.
 
+Example policy that denies order updates at night (10 PM – 6 AM):
+
+```dsl
+# @name Deny updates at night
+deny permission.order.update if all:
+  env.time.hour less than 6 
+  env.time.hour greater or equal than 22
 ```
 
-### Проверка политики
+**Retrieving values from environment**
+
+If a path is specified in a rule:
+
+- `env.*` → value is taken from environment
+- `user.*`, `order.*`, `profile.*` → from resource
+- literal (`18`, `"admin"`, `true`) → used as is
 
-Для проверки политики правил следует вызвать метод `check` класса `AbilityPolicy` передав объект проверяемого ресурса.
-Этот метод вернёт экземпляр класса `AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение
-для группы и переданных значений.
+Example:
 
 ```ts
-import { AbilityPolicy } from '@via-profit/ability';
+subject: "env.geo.country"
+resource: "user.country"
+condition: "equal"
+```
 
-const policy = AbilityPolicy.parse({ ... });
+### Environment in TypeScript
 
-const match = policy.check({ ... });
+The Environment type is set at the `AbilityResolver` level:
 
-const is = match.isEqual(AbilityMatch.match);
+```ts
+const resolver = new AbilityResolver<Resources, Environment>(policies);
 ```
 
-___
+This allows:
 
-## Управление политиками
+- getting autocompletion in IDE,
+- checking the correctness of `env.*` paths,
+- avoiding errors when passing environment.
 
-Класс `AbilityResolver` — это основной инструмент для применения политик в рантайме. Он решает две ключевые задачи:
+> If a rule uses `env.*` but environment is not passed, then the value of `env.*` will be `undefined`, and the comparison will be performed as if the environment were absent.
 
-1. **Фильтрация политик по действию** — выбирает только те политики, которые применимы к выполняемой операции
-2. **Оценка разрешений** — последовательно проверяет отобранные политики и возвращает итоговый результат (разрешено/запрещено)
+## TypeScript Type Generator
 
-### Зачем нужен AbilityResolver?
+`AbilityParser.generateTypeDefs()` generates TypeScript types based on policies, allowing you to avoid discrepancies between types and data in policies.
 
-Представим, что в системе есть десятки политик, каждая на своё действие:
-- `order.create` — правила создания заказа
-- `order.update` — правила обновления заказа
-- `order.delete` — правила удаления заказа
-- `user.profile.update` — правила обновления профиля
-- и так далее...
+**Usage Example**
 
-Когда пользователь пытается создать заказ, нам нужно проверить только политики, связанные с действием `order.create`, игнорируя все остальные. Именно это и делает `AbilityResolver`.
+First, you need to prepare an array of policies. Policies can be stored in DSL or JSON and parsed into an array of ready-made policies. In this example, for clarity, policies are stored in DSL.
 
-### Использование wildcard (*) в действиях
+```ts
+// scripts/policies.ts
+
+import { AbilityDSLParser } from './AbilityDSLParser';
 
-`AbilityResolver` поддерживает использование символа звездочки (`*`) в названиях действий. Это позволяет создавать политики, которые применяются к целым группам операций.
+const dsl = `
+# @name Update order
+permit permission.order.update if all:
 
-#### Правила сопоставления с wildcard:
+  # @name Owner check
+  all of:
+    # @name User is owner
+    user.id = order.ownerId
+`;
 
-| Политика (action) | Проверяемое действие | Результат |
-|-------------------|---------------------|-----------|
-| `order.*` | `order.create` | ✅ Совпадает |
-| `order.*` | `order.update` | ✅ Совпадает |
-| `order.*` | `order.delete` | ✅ Совпадает |
-| `order.*` | `user.create` | ❌ Не совпадает |
-| `*.create` | `order.create` | ✅ Совпадает |
-| `*.create` | `user.create` | ✅ Совпадает |
-| `*.create` | `order.update` | ❌ Не совпадает |
-| `user.profile.*` | `user.profile.update` | ✅ Совпадает |
-| `user.profile.*` | `user.profile.delete` | ✅ Совпадает |
-| `user.profile.*` | `user.settings.update` | ❌ Не совпадает |
+const policies = new AbilityDSLParser(dsl).parse();
 
-#### Примеры использования wildcard:
+export default policies;
+```
 
 ```ts
-// Политика, применяемая ко всем действиям с заказами
-{
-  id: 'orders-audit',
-  name: 'Audit all order operations',
-  action: 'order.*',  // Применится к order.create, order.update, order.delete и т.д.
-  effect: 'permit',
-  // ... правила
-}
+// scripts/generate-types.ts
+import { writeFileSync } from 'node:fs';
+import { AbilityParser } from '@via-profit/ability';
+import policies from './policies.json';
 
-// Политика, применяемая ко всем операциям создания
-{
-  id: 'create-audit',
-  name: 'Audit all create operations',
-  action: '*.create',  // Применится к order.create, user.create, product.create и т.д.
-  effect: 'permit',
-  // ... правила
-}
+const typedefs = AbilityParser.generateTypeDefs(policies);
 
-// Политика для всех операций в модуле пользователей
-{
-  id: 'user-module',
-  name: 'User module base policy',
-  action: 'user.*.*',  // Применится к user.profile.update, user.settings.delete и т.д.
-  effect: 'deny',
-  // ... правила
-}
+writeFileSync('./src/ability/types.generated.ts', typedefs, 'utf8');
 ```
 
-#### Приоритет и множественное совпадение
+**Generated File (example)**
+
+```ts
+// src/ability/types.generated.ts
+
+// Automatically generated by via-profit/ability
+// Do not edit manually
+export type Resources = {
+  'order.update': {
+    readonly user: {
+      readonly id: string;
+    };
+    readonly order: {
+      readonly ownerId: string;
+    };
+  };
+};
+```
 
-Если несколько политик подходят под проверяемое действие, будут применены **все** подходящие политики. Результат определяется последней сработавшей политикой:
+**Usage in code**
 
 ```ts
-const policies = [
-  AbilityPolicy.parse({
-    action: 'order.*',
-    effect: 'permit',
-    // ... правила
-  }),
-  AbilityPolicy.parse({
-    action: 'order.update',
-    effect: 'deny',
-    // ... правила
-  })
-];
+import { AbilityResolver, AbilityPolicy } from '@via-profit/ability';
+import type { Resources } from './ability/types.generated';
 
-const resolver = new AbilityResolver(policies);
+const resolver = new AbilityResolver<Resources>(
+  AbilityPolicy.parseAll(policies),
+);
 
-// При проверке order.update сработают ОБЕ политики
-// Результат будет deny, так как это эффект последней сработавшей политики,
-// таким образом, каждая последующая политика считается важнее предыдущей.
-// Это применительно для ситуаций, когда необходимо, что называется, наложить вето
-// на принятые ранее решения вышестоящих политик
-resolver.enforce('order.update', data);
+await resolver.enforce('order.update', {
+  user: { id: 'u1' },
+  order: { ownerId: 'u1' },
+});
 ```
 
-**Каждая последующая политика считается важнее предыдущей.
-Это применительно для ситуаций, когда необходимо, что называется, наложить вето
-на принятые ранее решения вышестоящих политик**
+## Policy Debugging
+
+### Explanations
+
+To simplify policy debugging, a special `AbilityResult` class is used, which is already included in the final evaluation result. `AbilityResult` encapsulates the outcome of applying all matching policies to a permission key and resource.
 
-#### Комбинирование точных действий и wildcard
+`AbilityResult` contains:
 
-Вы можете комбинировать точные действия и wildcard для создания гибкой системы прав:
+- a list of evaluated policies,
+- methods to determine the final effect,
+- methods to get explanations in textual representation.
+
+Example:
 
 ```ts
-const policies = [
-  // Общее правило для всех заказов
-  {
-    action: 'order.*',
-    effect: 'deny',  // По умолчанию запрещено
-    // ...
-  },
-  // Исключение для создания заказа
-  {
-    action: 'order.create',
-    effect: 'permit',  // Создавать можно
-    // ...
-  },
-  // Дополнительная проверка для обновления
-  {
-    action: 'order.update',
-    effect: 'deny',  // Обновление требует особых условий
-    ruleSet: [
-      // ... сложные правила для обновления
-    ]
-  }
-];
+const result = await resolver.resolve('order.update', resource);
+
+if (result.isDenied()) {
+  console.log('Access denied');
+}
+
+const explanations = result.explain(); // AbilityExplain
+
+// console.log(explanations.toString());
 ```
 
-### Как это работает
+### AbilityExplain
+
+`AbilityExplain` and related classes (`AbilityExplainPolicy`, `AbilityExplainRuleSet`, `AbilityExplainRule`) allow you to get a human-readable explanation:
+
+- which policy matched,
+- which rule groups matched,
+- which rules did not pass,
+- which effect was applied.
+
+Usage example:
 
 ```ts
-import { AbilityPolicy, AbilityResolver } from '@via-profit/ability';
-import type { AbilityPolicyConfig } from '@via-profit/ability';
-
-// Загружаем все политики системы (например, из JSON-файлов)
-const configs: AbilityPolicyConfig[] = [
-  {
-    id: 'order-create-policy',
-    name: 'Политика создания заказа',
-    action: 'order.create',
-    effect: 'permit',
-    compareMethod: 'and',
-    ruleSet: [
-      // ... правила для создания заказа
-    ]
-  },
-  {
-    id: 'order-update-policy',
-    name: 'Политика обновления заказа',
-    action: 'order.update',
-    effect: 'deny',
-    compareMethod: 'and',
-    ruleSet: [
-      // ... правила для обновления заказа
-    ]
-  },
-  {
-    id: 'orders-base-policy',
-    name: 'Базовая политика для всех операций с заказами',
-    action: 'order.*',
-    effect: 'deny',
-    compareMethod: 'and',
-    ruleSet: [
-      // ... общие правила для всех заказов
-    ]
-  }
-];
+const result = await resolver.resolve('order.update', resource);
+const explanations = result.explain();
 
-// Создаем экземпляры политик
-const policies = AbilityPolicy.parseAll(configs);
+console.log(explanations.toString());
+```
 
-// Создаем резолвер со всеми политиками
+Example output:
+
+```
+✓ policy «Deny order update for managers» is match
+  ✓ ruleSet «Managers» is match
+    ✓ rule «Department managers» is match
+    ✗ rule «Role manager» is mismatch
+  ✓ ruleSet «Not administrators» is match
+    ✓ rule «No role administrator» is match
+```
+
+### Output Format
+
+Currently, only one output format is supported — textual.
+
+The output follows the principle: `<policy | ruleSet | rule> <name> <is match | is mismatch>`
+
+## Troubleshooting
+
+### Decision‑Making Model (Default Deny)
+
+> Why does a `deny` policy not turn into `permit` if its conditions are not met?
+
+Consider a policy that **denies** access to a user aged 16:
+
+```ts
+const dsl = `
+deny permission.test if all:
+  user.age is equals 16
+`;
+
+const policies = new AbilityDSLParser(dsl).parse();
 const resolver = new AbilityResolver(policies);
 
-// При выполнении действия указываем только нужный action
-// AbilityResolver автоматически отфильтрует политики и проверит их
-resolver.enforce('order.create', {
-  user: {
-    department: 'managers',
-    roles: ['manager']
-  },
-  order: {
-    amount: 5000
-  }
+const result = await resolver.resolve('test', {
+  user: { age: 16 },
 });
+
+console.log(result.isDenied());  // true  ✔
+console.log(result.isAllowed()); // false ✔
 ```
 
-### Проверка соответствия действия
+In this case, everything is obvious:  
+the condition is met → the policy matches → effect `deny` → access denied.
 
-Метод `isInActionContain` позволяет проверить, соответствует ли действие шаблону с wildcard:
+**What happens if the conditions are *not met*?**
 
 ```ts
-// Статический метод класса AbilityResolver
-AbilityResolver.isInActionContain('order.*', 'order.create'); // true
-AbilityResolver.isInActionContain('order.*', 'user.create');  // false
-AbilityResolver.isInActionContain('*.update', 'order.update'); // true
-AbilityResolver.isInActionContain('*.update', 'order.create'); // false
+const result = await resolver.resolve('test', {
+  user: { age: 12 },
+});
+
+console.log(result.isDenied());  // true  ✔
+console.log(result.isAllowed()); // false ✔
 ```
 
-Этот метод используется внутри `AbilityResolver` для фильтрации политик, но может быть полезен и в пользовательском коде.
+At first glance, it might seem that if the condition is not met, the policy should “allow” access.  
+But that is **not the case**.
 
-### Методы AbilityResolver
+**Decision‑Making Model: `Default Deny`**
 
-#### `enforce()` — строгая проверка
+`AbilityResolver` uses the classic security model:
 
-```typescript
-try {
-  resolver.enforce('order.update', data);
-  // Доступ разрешен - продолжаем выполнение
-  await updateOrder(data);
-} catch (error) {
-  if (error instanceof AbilityError) {
-    // Доступ запрещен - error.message содержит название сработавшей политики
-    console.error(`Доступ запрещен политикой: ${error.message}`);
-    return;
-  }
-  throw error;
-}
-```
+> **If there is no matching permit‑policy → access is denied.**
 
-**Важно**: `enforce()` выбрасывает исключение, если хотя бы одна подходящая политика вернула `deny`. Если ни одна политика не сработала или все вернули `permit` — исключения не будет.
+**What happens in this example:**
 
-#### `resolve()` — мягкая проверка
+1. The `deny` policy exists, but its condition is **not met**  
+   → the policy gets status `mismatch`.
 
-```typescript
-const result = resolver
-  .resolve('order.update', data)
-  .isDeny(); // true если доступ запрещен
+2. The `deny` policy **is not applied** because the conditions did not match.
 
-if (result) {
-  // Самостоятельно обрабатываем запрет
-  return { error: 'Access denied' };
-}
+3. There is no `permit` policy.
 
-// Продолжаем выполнение
-await updateOrder(data);
-```
+4. Since there is no permit policy → the final decision:  
+   **deny (by default)**.
 
-#### `resolveWithExplain()` — проверка с объяснением
+**Summary**
 
-```typescript
-const explanations = resolver.resolveWithExplain('order.update', data);
+- `deny` with matching conditions → **deny**
+- `deny` with non‑matching conditions → **deny (default deny)**
+- `permit` with matching conditions → **allow**
+- `permit` with non‑matching conditions → **deny (default deny)**
 
-explanations.forEach(explain => {
-  console.log(explain.toString());
-  // ✓ policy «Политика обновления заказа» is match
-  //   ✗ ruleSet «Проверка владельца» is mismatch
-  //   ✓ ruleSet «Проверка статуса» is match
-});
+**Conclusion**
 
-if (resolver.isDeny()) {
-  console.log('Доступ запрещен по причине:');
-  explanations.forEach(e => console.log(e.toString()));
-}
-```
+**Access is allowed only if there is an explicit permit.**
 
-### Интеграция с TypeScript
+## Design Recommendations
 
-Для полной типобезопасности определите интерфейс `Resources`, где ключи — это возможные действия, а значения — структура данных, требуемая для проверки:
+### Naming Access Keys
 
-```typescript
-// Определяем типы данных для каждого действия
-type Resources = {
-  'order.create': {
-    readonly user: {
-      readonly department: string;
-      readonly roles: readonly string[];
-    };
-    readonly order: {
-      readonly amount: number;
-    };
-  };
-  
-  'order.update': {
-    readonly user: {
-      readonly id: string;
-    };
-    readonly order: {
-      readonly id: string;
-      readonly status: string;
-      readonly ownerId: string;
-    };
-  };
-  
-  'user.profile.update': {
-    readonly user: {
-      readonly id: string;
-    };
-    readonly profile: {
-      readonly userId: string;
+- Use hierarchical keys: `permission.order.create`, `permission.order.update.status`, `permission.user.profile.update`.
+- Group by domains: `permission.user.*`, `permission.order.*`, `permission.product.*`.
+- Do not mix different domains in one key.
+
+### Data Structure
+
+- Explicitly describe `Resources` in TypeScript.
+- Do not pass “extra” fields — this complicates understanding.
+- Strive to keep the data structure for a given `permission` stable.
+
+### Policy Design
+
+- General rules — via wildcard (`permission.order.*`).
+- Specific restrictions — via exact actions (`permission.order.update`).
+- Use `effect: deny` for prohibitions.
+- Use `effect: permit` for permissions.
+
+### Common Mistakes
+
+- Expecting that absence of matching policies means allow.
+- Mixing business logic and access policies.
+- Too large policies with dozens of rules — better to break them down.
+
+### Example of Use on the Frontend (React)
+
+**Hook for checking policies**
+
+```tsx
+// hooks/use-ability.ts
+import { useEffect, useState } from 'react';
+import { AbilityResolver } from '@via-profit/ability';
+import { Resources } from './generated-types';
+
+export function useAbility<Permission extends keyof Resources>(
+  resolver: AbilityResolver<Resources>,
+  permission: Permission,
+  resource: Resources[Permission],
+) {
+  const [allowed, setAllowed] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function check() {
+      try {
+        const result = await resolver.resolve(permission, resource);
+        if (!cancelled) {
+          setAllowed(result.isAllowed());
+        }
+      } catch {
+        if (!cancelled) {
+          setAllowed(false);
+        }
+      }
+    }
+
+    check();
+
+    return () => {
+      cancelled = true;
     };
-  };
-};
+  }, [resolver, permission, resource]);
 
-// Теперь TypeScript будет проверять корректность передаваемых данных
-resolver.enforce('order.create', {
-  user: {
-    department: 'managers',
-    roles: ['manager']
-  },
-  order: {
-    amount: 5000  // ✅ все поля на месте
+  return allowed;
+}
+```
+
+**Usage in a component**
+
+```tsx
+function OrderUpdateButton({ order, user }) {
+  const allowed = useAbility(resolver, 'order.update', {
+    user,
+    order,
+  });
+
+  if (allowed === null) {
+    return null; // or loading spinner
   }
-});
 
-// ❌ Ошибка компиляции - не хватает required полей
-resolver.enforce('order.create', {
-  user: {
-    department: 'managers'
-    // missing roles
+  if (!allowed) {
+    return null;
   }
-});
+
+  return <button>Update order</button>;
+}
 ```
 
-### Как формируется итоговое решение?
+## Examples
 
-1. Resolver собирает все политики, у которых `action` соответствует запрошенному (поддерживается wildcard `*`)
-2. Последовательно проверяет каждую политику методом `check()`
-3. Если политика вернула `match`, запоминает её `effect` (permit/deny)
-4. Возвращается `effect` **последней сработавшей политики**
+### Example of a Complex Multi‑Level Policy
 
-```typescript
-// Пример с несколькими политиками на одно действие
-const policies = [
-  permitPolicy, // permit, но не match
-  denyPolicy,   // deny и match
-  permitPolicy2 // permit, но не match
-];
+Below is a multi‑level set of policies, using a cinema example (fictional).
 
-resolver.enforce('some.action', data);
-// Результат: deny (от последней сработавшей политики)
-```
+**The example demonstrates:**
+- working with roles (admin, seller, manager, VIP, banned),
+- time constraints (`env.time.hour`),
+- wildcard permissions (`permission.*`),
+- ticket quantity limits,
+- prohibition on selling already sold tickets,
+- combination of `permit`/`deny` policies,
+- policy priority and Default Deny model.
 
-### Когда использовать Resolver?
+**Brief description of rules**
+- **Administrator**  
+  Has wildcard permissions (`permission.*`) and can perform any action.  
+  Can edit ticket prices.
 
-- **В API endpoints** — проверка прав перед выполнением операции
-- **В middleware** — централизованная проверка доступа
-- **В сервисах** — защита бизнес-логики
-- **В клиентском коде** — условный рендеринг UI на основе прав
+- **Seller**  
+  Can sell tickets only during working hours (09:00–23:00).  
+  Cannot sell tickets if:
+    - the cinema is closed,
+    - the ticket is already sold.
 
-Resolver делает систему прав предсказуемой, типобезопасной и легко расширяемой.
+- **Manager**  
+  Has the same rights as a seller.
 
-## API Reference
+- **Buyers**
+    - A user older than 21 can buy tickets.
+    - A VIP user can buy tickets at any time.
+    - A banned user (`status = banned`) cannot buy tickets.
+    - Any user cannot buy more than 6 tickets.
 
-### Класс AbilityCode
+**Policy Diagram**
 
-Базовый абстрактный класс для всех кодовых значений в системе.
+```mermaid
+flowchart LR
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `isEqual()` | `compareWith: AbilityCode<T> \| null` | `boolean` | Сравнивает текущий код с другим экземпляром |
-| `isNotEqual()` | `compareWith: AbilityCode<T> \| null` | `boolean` | Проверяет неравенство с другим экземпляром |
+%% ==== ROLES ====
 
-**Геттеры:**
-- `code: T` - возвращает сырое значение кода (строку или число)
+   subgraph Roles[Roles]
+      A[Administrator]
+      B[Seller]
+      C[Manager]
+   end
 
----
+   subgraph Buyers[Buyers]
+      U1[User > 21]
+      U2[VIP user]
+      U3[Banned user]
+   end
 
-### Класс AbilityMatch
+%% ==== ADMIN ====
 
-Представляет возможные состояния результата проверки правил.
+   A --> A1[Wildcard: permission.*]
+   A --> A2[Edit ticket price]
 
-**Статические свойства:**
-- `AbilityMatch.pending` - ожидание проверки
-- `AbilityMatch.match` - совпадение найдено
-- `AbilityMatch.mismatch` - совпадение не найдено
+   A1 --> FINAL[Final decision]
+   A2 --> FINAL
 
-Каждое свойство является экземпляром класса `AbilityMatch` и наследует все его методы.
+%% ==== SELLER ====
 
----
+   B --> B1[Sell tickets]
 
-### Класс AbilityCondition
+   B1 -->|09:00–23:00| B2[Allowed]
+   B1 -->|Outside hours| D2[Denied]
+   B1 -->|ticket.status = sold| D3[Denied]
 
-Определяет операторы сравнения для правил доступа.
+   B2 --> FINAL
+   D2 --> FINAL
+   D3 --> FINAL
 
-**Статические свойства:**
-- `AbilityCondition.equal` - равно (`=`)
-- `AbilityCondition.not_equal` - не равно (`<>`)
-- `AbilityCondition.more_than` - больше (`>`)
-- `AbilityCondition.less_than` - меньше (`<`)
-- `AbilityCondition.less_or_equal` - меньше или равно (`<=`)
-- `AbilityCondition.more_or_equal` - больше или равно (`>=`)
-- `AbilityCondition.in` - входит в массив (`in`)
-- `AbilityCondition.not_in` - не входит в массив (`not in`)
+%% ==== MANAGER ====
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `fromLiteral()` | `literal: AbilityConditionLiteralType` | `AbilityCondition` | Создает экземпляр условия из литерального имени (например, 'equal' → '=') |
+   C --> C1[Sell tickets as seller]
+   C1 --> FINAL
 
-**Геттеры:**
-- `literal: AbilityConditionLiteralType` - возвращает литеральное имя оператора ('equal', 'not_equal' и т.д.)
+%% ==== BUYERS ====
 
----
+   U1 --> U1A[Buy tickets]
+   U1A -->|ticketsCount < 6| U1OK[Allowed]
+   U1A -->|ticketsCount ≥ 6| U1DENY[Denied]
 
-### Класс AbilityCompare
+   U2 --> U2A[Buy tickets anytime]
+   U2A -->|ticketsCount < 6| U2OK[Allowed]
+   U2A -->|ticketsCount ≥ 6| U2DENY[Denied]
 
-Определяет методы логического сравнения для групп правил.
+   U3 --> U3A[Denied to buy tickets]
 
-**Статические свойства:**
-- `AbilityCompare.and` - логическое И (все правила должны совпасть)
-- `AbilityCompare.or` - логическое ИЛИ (достаточно одного совпадения)
+   U1OK --> FINAL
+   U1DENY --> FINAL
+   U2OK --> FINAL
+   U2DENY --> FINAL
+   U3A --> FINAL
 
----
+%% ==== DENY RULES ====
 
-### Класс AbilityPolicyEffect
+   D1[Denied to buy tickets if user.status = banned] --> FINAL
+```
 
-Определяет эффект применения политики.
+**DSL Policies**
 
-**Статические свойства:**
-- `AbilityPolicyEffect.deny` - запрет доступа
-- `AbilityPolicyEffect.permit` - разрешение доступа
+```dsl
+############################################################
+# @name Admin can edit ticket price
+permit permission.ticket.price.edit if all:
+  user.role is equals 'admin'
 
----
 
-### Класс AbilityRule
-
-Представляет отдельное правило проверки доступа.
-
-**Свойства:**
-- `subject: string` - путь к значению субъекта в dot-нотации
-- `resource: string | number | boolean | (string | number)[]` - значение или путь для сравнения
-- `condition: AbilityCondition` - условие сравнения
-- `name: string` - название правила
-- `id: string` - уникальный идентификатор
-- `state: AbilityMatch` - текущее состояние после вызова `check()`
-
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `check()` | `resource: Resources \| null` | `AbilityMatch` | Проверяет правило на переданных данных, обновляет `state` и возвращает результат |
-| `extractValues()` | `resourceData: Resources \| null` | `[any, any]` | Извлекает значения для сравнения из субъекта и ресурса по указанным путям |
-| `getDotNotationValue()` | `resource: unknown, desc: string` | `T \| undefined` | Извлекает значение из объекта по dot-нотации (поддерживает массивы: `users[0].name`) |
-| `export()` | — | `AbilityRuleConfig` | Экспортирует правило в конфигурационный объект для сериализации |
-| `parse()` | `config: AbilityRuleConfig` | `AbilityRule` | Статический метод. Создает экземпляр правила из конфигурационного объекта |
-
-**Статические фабричные методы (все возвращают `AbilityRule`):**
-
-| Метод | Аргументы | Описание |
-|-------|-----------|----------|
-| `equal()` | `subject: string, resource: any` | Создает правило с условием "равно" |
-| `notEqual()` | `subject: string, resource: any` | Создает правило с условием "не равно" |
-| `in()` | `subject: string, resource: any` | Создает правило с условием "входит в массив" |
-| `notIn()` | `subject: string, resource: any` | Создает правило с условием "не входит в массив" |
-| `lessThan()` | `subject: string, resource: any` | Создает правило с условием "меньше" |
-| `lessOrEqual()` | `subject: string, resource: any` | Создает правило с условием "меньше или равно" |
-| `moreThan()` | `subject: string, resource: any` | Создает правило с условием "больше" |
-| `moreOrEqual()` | `subject: string, resource: any` | Создает правило с условием "больше или равно" |
+############################################################
+# @name Seller can sell tickets during working hours
+permit permission.ticket.sell if all:
+  user.role is equals 'seller'
+  all of:
+    env.time.hour greater than or equal 9
+    env.time.hour less than or equal 23
 
----
 
-### Класс AbilityRuleSet
+############################################################
+# @name Users older than 21 can buy tickets
+permit permission.ticket.buy if all:
+  user.age greater than 21
 
-Группирует несколько правил для совместной проверки.
 
-**Свойства:**
-- `state: AbilityMatch` - текущее состояние группы после вызова `check()`
-- `rules: AbilityRule[]` - массив правил в группе
-- `compareMethod: AbilityCompare` - метод сравнения (AND/OR)
-- `name: string` - название группы
-- `id: string` - уникальный идентификатор
+############################################################
+# @name VIP users can buy tickets anytime
+permit permission.ticket.buy if all:
+  user.isVIP is true
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `addRule()` | `rule: AbilityRule` | `this` | Добавляет одно правило в группу (поддерживает цепочку вызовов) |
-| `addRules()` | `rules: AbilityRule[]` | `this` | Добавляет массив правил в группу |
-| `check()` | `resources: Resources \| null` | `AbilityMatch` | Проверяет все правила группы, применяет метод сравнения и возвращает результат |
-| `export()` | — | `AbilityRuleSetConfig` | Экспортирует группу в конфигурационный объект |
-| `parse()` | `config: AbilityRuleSetConfig` | `AbilityRuleSet` | Статический метод. Создает экземпляр группы из конфигурации |
-| `and()` | `rules: AbilityRule[]` | `AbilityRuleSet` | Статический метод. Создает группу с логическим И |
-| `or()` | `rules: AbilityRule[]` | `AbilityRuleSet` | Статический метод. Создает группу с логическим ИЛИ |
 
----
+############################################################
+# @name Deny buying tickets if user is banned
+deny permission.ticket.buy if all:
+  user.status is equals 'banned'
 
-### Класс AbilityPolicy
 
-Объединяет группы правил в полноценную политику доступа.
+############################################################
+# @name Deny selling tickets if cinema is closed
+deny permission.ticket.sell if all:
+  any of:
+    env.time.hour less than 9
+    env.time.hour greater than 23
 
-**Свойства:**
-- `matchState: AbilityMatch` - состояние политики после проверки
-- `ruleSet: AbilityRuleSet[]` - массив групп правил
-- `effect: AbilityPolicyEffect` - эффект политики (permit/deny)
-- `compareMethod: AbilityCompare` - метод сравнения групп
-- `name: string` - название политики
-- `id: string` - уникальный идентификатор
-- `action: string` - действие, к которому применяется политика
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `addRuleSet()` | `ruleSet: AbilityRuleSet` | `this` | Добавляет группу правил в политику |
-| `check()` | `resources: Resources` | `AbilityMatch` | Проверяет все группы правил и возвращает результат |
-| `explain()` | — | `AbilityExplain` | Возвращает объяснение результата проверки (должен быть вызван после `check()`) |
-| `export()` | — | `AbilityPolicyConfig` | Экспортирует политику в конфигурационный объект |
-| `parse()` | `config: AbilityPolicyConfig` | `AbilityPolicy` | Статический метод. Создает экземпляр политики из конфигурации |
-| `parseAll()` | `configs: readonly AbilityPolicyConfig[]` | `AbilityPolicy[]` | Статический метод. Парсит массив конфигураций политик и возвращает массив экземпляров AbilityPolicy. Удобен для загрузки нескольких политик одновременно. |
+############################################################
+# @name Manager can do everything seller can
+permit permission.ticket.sell if all:
+  user.role is equals 'manager'
 
----
 
-### Класс AbilityResolver
+############################################################
+# @name Admin wildcard permissions
+permit permission.* if all:
+  user.role is equals 'admin'
 
-Управляет множеством политик и их выполнением.
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `constructor()` | `policies: AbilityPolicy[] \| AbilityPolicy` | `AbilityResolver` | Создает экземпляр с одной или несколькими политиками |
-| `resolve()` | `action: keyof Resources, resource: Resources[Action]` | `this` | Фильтрует политики по действию и проверяет их, возвращает себя для цепочки вызовов |
-| `resolveWithExplain()` | `action: keyof Resources, resource: Resources[Action]` | `readonly AbilityExplain[]` | Выполняет проверку и возвращает массив объяснений для каждой политики |
-| `enforce()` | `action: keyof Resources, resource: Resources[Action]` | `void \| never` | Выполняет проверку и выбрасывает `AbilityError` если результат Deny |
-| `getEffect()` | — | `AbilityPolicyEffect \| null` | Возвращает эффект последней сработавшей политики |
-| `isPermit()` | — | `boolean` | Проверяет, разрешен ли доступ |
-| `isDeny()` | — | `boolean` | Проверяет, запрещен ли доступ |
-| `getMatchedPolicy()` | — | `AbilityPolicy \| null` | Возвращает последнюю сработавшую политику |
-| `isInActionContain()` | `actionA: string, actionB: string` | `boolean` | Статический метод. Проверяет, соответствует ли действие шаблону (поддерживает `*`) |
+############################################################
+# @name Limit tickets per user (max 6)
+deny permission.ticket.buy if all:
+  user.ticketsCount greater than or equal 6
 
----
 
-### Класс AbilityExplain
+############################################################
+# @name Cannot sell already sold tickets
+deny permission.ticket.sell if all:
+  ticket.status is equals 'sold'
+```
 
-Представляет человекочитаемое объяснение результата проверки.
+Below is how to use the policies above in Node.js + TypeScript.
 
-**Свойства:**
-- `type: AbilityExplainType` - тип элемента ('policy' \| 'rule' \| 'ruleSet')
-- `children: AbilityExplain[]` - дочерние элементы объяснения
-- `name: string` - название элемента
-- `match: AbilityMatch` - результат проверки
+**Preparing Policies**
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `toString()` | `indent: number = 0` | `string` | Форматирует объяснение в читаемый текст с отступами |
+```ts
+import { AbilityDSLParser } from '@via-profit/ability';
+import cinemaDSL from './policies/cinema.dsl';
 
-**Наследники:**
-- `AbilityExplainRule` - объяснение для правила
-- `AbilityExplainRuleSet` - объяснение для группы правил
-- `AbilityExplainPolicy` - объяснение для политики
+export const policies = new AbilityDSLParser(cinemaDSL).parse();
+```
 
----
+**Creating the Resolver**
 
-### Класс AbilityParser
-
-Предназначен для парсинга и генерации типов из конфигураций.
-
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `generateTypeDefs()` | `policies: readonly AbilityPolicy[]` | `string` | Статический метод. Генерирует TypeScript тип `Resources` на основе правил во всех политиках. Анализирует условия правил и определяет соответствующие типы (string, number, boolean, массивы). Возвращает строку с готовым TypeScript определением типа. |
-
-#### Пример использования:
-
-```typescript
-import { AbilityParser, AbilityPolicy } from '@via-profit/ability';
-import fs from 'node:fs';
-
-// Массив политик
-const policies: AbilityPolicy[] = AbilityPolicy.parseAll([
-  {
-    id: 'policy-1',
-    name: 'Example policy',
-    action: 'order.status',
-    effect: 'deny',
-    compareMethod: 'and',
-    ruleSet: [
-      {
-        id: 'rule-set-1',
-        name: 'Example rule set',
-        compareMethod: 'and',
-        rules: [
-          {
-            subject: 'user.roles',
-            resource: ['admin'],
-            condition: 'in',
-          },
-          {
-            subject: 'order.amount',
-            resource: 1000,
-            condition: '<=',
-          },
-        ],
-      },
-    ],
-  },
-]);
-
-// Генерация TypeScript типа
-const typeDefinitions = AbilityParser.generateTypeDefs(policies);
-
-// Запись в файл
-fs.writeFileSync('./src/types/ability.ts', typeDefinitions);
-
-// Результат в файле:
-// // Automatically generated by via-profit/ability
-// // Do not edit manually
-//
-// export type Resources = {
-//   ['order.status']: {
-//     readonly order: {
-//       readonly amount: number;
-//     };
-//     readonly user: {
-//       readonly roles: string[];
-//     };
-//   };
-// }
+```ts
+import { AbilityResolver } from '@via-profit/ability';
+import { policies } from './policies';
+
+const resolver = new AbilityResolver(policies);
 ```
 
----
+**Checking Permissions (enforce)**
 
-### Классы ошибок
+Example: buying a ticket.
 
-| Класс | Назначение |
-|-------|------------|
-| `AbilityError` | Общая ошибка доступа, выбрасывается при запрете в `enforce()` |
-| `AbilityParserError` | Ошибка парсинга конфигурации или генерации типов |
+The `enforce` method throws an `AbilityError` if access is denied.
 
-## Рекомендации по использованию
+```ts
+await resolver.enforce('ticket.buy', {
+  user: { age: 25, ticketsCount: 1 },
+  env: { time: { hour: 18 } },
+});
+```
+If allowed — the code continues execution.  
+If denied — an `AbilityError` exception is thrown.
 
-### Именование экшенов
+**Checking Permissions Without Exceptions (resolve)**
 
-Используйте точечную нотацию для иерархии действий:
+`resolve` returns a result object:
 
-- `order.create` - создание заказа
-- `order.update` - обновление заказа
-- `order.status.update` - обновление статуса заказа
+```ts
+const result = await resolver.resolve('ticket.buy', {
+  user: { age: 25, ticketsCount: 1 },
+  env: { time: { hour: 18 } },
+});
 
-### Структура данных
+if (result.isAllowed()) {
+  console.log('Purchase allowed');
+} else {
+  console.log('Purchase denied');
+}
+```
 
-Старайтесь группировать связанные данные под общими ключами:
+**Seller can only sell during working hours**
 
 ```ts
-// Хорошо
-{
-  user: { id: '123', roles: ['admin'] },
-  order: { status: 'new', amount: 1000 }
-}
+await resolver.enforce('ticket.sell', {
+  user: { role: 'seller' },
+  env: { time: { hour: 15 } },
+  ticket: { status: 'available' },
+});
+```
 
-// Плохо
-{
-  userId: '123',
-  userRoles: ['admin'],
-  orderStatus: 'new',
-  orderAmount: 1000
-}
+**Preparing Data for the Resolver**
+
+In the examples above, constant objects are passed to the resolver:
+
+```ts
+resolver.enforce('ticket.buy', {
+  user: { age: 25 },
+  env: { time: { hour: 18 } },
+});
 ```
 
-### Проектирование политик
+This is done for clarity. In a real application, the data for the resolver should be built dynamically — from the sources available to your server.
+
+**User** (`user`) is usually taken from:
+
+- JWT token
+- session
+- database
+- authorization middleware
+
+Example:
+
+```ts
+const user = await db.users.findById(session.userId);
+```
+
+**Environment** (`env`)
+
+These are any external parameters that can affect access:
+
+- current server time
+- time zone
+- IP address
+- request headers
+- system configuration
 
-- Используйте `deny` для запрещающих политик, `permit` для разрешающих
-- Комбинируйте простые правила для сложной логики
-- Давайте понятные имена правилам и политикам для упрощения отладки
+Example:
 
-## Отладка политик
+```ts
+const env = {
+  time: {
+    hour: new Date().getHours(),
+  },
+  ip: req.ip,
+};
+```
+
+**Resource** (e.g., `ticket`)
 
-Используйте `resolveWithExplain()` для получения детальной информации о процессе проверки:
+If the action is associated with a specific object, it also needs to be loaded:
 
 ```ts
-const explanations = resolver.resolveWithExplain('order.update', data);
-explanations.forEach(exp => console.log(exp.toString()));
-// ✓ policy «Запрет доступа для менеджеров» is match
-//   ✓ ruleSet «Менеджеры» is match
-//     ✓ rule «Отдел managers» is match
-//     ✗ rule «Роль manager» is mismatch
-//   ✓ ruleSet «Не администраторы» is match
-//     ✓ rule «Нет роли administrator» is match
+const ticket = await db.tickets.findById(req.params.ticketId);
 ```
 
+**Context**
+
+Context is the object that you pass to `resolve` or `enforce`.  
+It contains **all the data** that policies might need:
+
+- `user` — data about the current user
+- `env` — environment data (time, IP, geography, system settings)
+- `resource` or `ticket` — data about the entity on which the action is performed
+- any other objects that you use in DSL
+
+**It is important to understand:**
+
+> Context is formed for a specific action and specific policies. It does not need to be stored in advance — you gather it dynamically before calling the resolver.
+
+## Performance
+
+The tests used policies with 10 conditions, nested fields, and environment.
+
+**Tinybench** ([https://github.com/tinylibs/tinybench](https://github.com/tinylibs/tinybench))
+
+| # | Task name                              | Latency avg (ns)      | Latency med (ns)      | Throughput avg (ops/s) | Throughput med (ops/s) | Samples |
+|---|-----------------------------------------|------------------------|------------------------|--------------------------|--------------------------|---------|
+| 0 | resolve() — no cache (heavy rules)      | 646317 ± 0.32%         | 632319 ± 8446.0        | 1555 ± 0.21%             | 1581 ± 21                | 3095    |
+| 1 | resolve() — cold cache (heavy rules)    | 636363 ± 0.38%         | 623092 ± 7885.0        | 1581 ± 0.21%             | 1605 ± 20                | 3143    |
+| 2 | resolve() — warm cache (heavy rules)    | 631328 ± 0.26%         | 621152 ± 6562.5        | 1590 ± 0.17%             | 1610 ± 17                | 3168    |
+
+```
+Latency (ns)
+650k | ███████████████████████████████████████ resolve() — no cache
+640k | █████████████████████████████████████ resolve() — cold cache
+630k | ████████████████████████████████████ resolve() — warm cache
+      --------------------------------------------------------------
+        no cache            cold cache            warm cache
+```
+
+```
+Throughput (ops/s)
+1600 | ███████████████████████████████████████ resolve() — warm cache
+1590 | ██████████████████████████████████████ resolve() — cold cache
+1580 | █████████████████████████████████████ resolve() — no cache
+      --------------------------------------------------------------
+        no cache            cold cache            warm cache
+```
 
-## Лицензия
+## License
 
-Этот проект лицензирован под лицензией MIT. Подробности в файле [LICENSE](LICENSE).
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.