@via-profit/ability 3.0.1 → 3.1.0

package/README.md

@@ -2,1177 +2,1173 @@
 
 > Набор сервисов, частично реализующих
 > принцип [Attribute Based Access Control](https://en.wikipedia.org/wiki/Attribute-based_access_control)
+> Пакет позволяет описывать правила, объединять их в группы, формировать политики и применять их к данным для определения разрешений.
 
-Этот сервис позволяет создавать правила и политики, применять их к данным и проверять доступ на их основе.
+## Для чего
+
+Пакет задуман как **лёгкая и предельно простая альтернатива** тяжёлым системам управления доступом.  
+Без сложных конфигураций, без зависимостей — только минимальный набор инструментов, который позволяет описывать правила и политики в максимально простом DSL.
 
 ## Содержание
 
-- [Обзор](#обзор)
-  - [Состав пакета](#состав-пакета)
-  - [Основные принципы](#основные-принципы)
-- [Правила](#правила)
-  - [Создание правила](#создание-правила)
-  - [Проверка правила](#проверка-правила)
-- [Группы правил](#группы-правил)
-  - [Создание группы правил](#создание-группы-правил)
-  - [Проверка группы правил](#проверка-группы-правил)
-- [Политики](#политики)
-  - [Создание политики](#создание-политики)
-  - [Проверка политики](#проверка-политики)
-- [Управление политиками](#управление-политиками)
-  - [Зачем нужен 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)
-  - [Классы ошибок](#классы-ошибок)
-- [Рекомендации по использованию](#рекомендации-по-использованию)
-  - [Именование экшенов](#именование-экшенов)
-  - [Структура данных](#структура-данных)
-  - [Проектирование политик](#проектирование-политик)
+- [Быстрый старт](#быстрый-старт)
+- [Основные положения](#основные-положения)
+- [DSL](#dsl)
+- [Объединение политик](#объединение-политик)
+- [Environment политик](#environment-политик)
+- [Генератор типов для TypeScript](#генератор-типов-для-typescript)
 - [Отладка политик](#отладка-политик)
-- [Лицензия](#лицензия)
+- [Решение проблем](#решение-проблем)
+- [Рекомендации по проектированию](#рекомендации-по-проектированию)
+- [Примеры](#примеры)
+- [Производительность](#производительность)
+- [Api-Reference](./docs/ru/api.md)
 
----
 
-## Обзор
-
-### Состав пакета
-
-- **`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"
-        }
-      ]
-    }
-  ]
-}
+## Быстрый старт
+
+Установить пакет, написать DSL, вызвать парсер, запустить резолвер.
+
+### Установка
+
+```bash
+npm install @via-profit/ability
+```
+
+```bash
+yarn add @via-profit/ability
 ```
 
-Применение политики:
+```bash
+pnpm add @via-profit/ability
+```
+
+
+### Пример: запретить доступ к `passwordHash` всем, кроме владельца
+
+Допустим, у нас есть пользовательские данные:
 
 ```ts
-const jsonConfig = { ... };
-AbilityPolicy.parse(jsonConfig).check({
-  user: {
-    department: 'managers',
-    roles: ['manager', 'coach'],
-  }
-});
+const user = {
+  id: '1',
+  login: 'user-001',
+  passwordHash: '...',
+};
 ```
 
----
+Нужно запретить чтение `passwordHash` всем, кроме самого пользователя.
+
+#### DSL‑политика
 
-## Правила
+На языке политик это выглядит так:
 
-**Правила** выполняют условие проверки и возвращают результат. **Основная цель** - выполнить сравнение переданных
-значений субъекта и ресурса, а затем вернуть результат такого сравнения.
+```
+deny permission.user.passwordHash if any:
+  viewer.id is not equals owner.id
+```
 
-### Создание правила
+**Пояснение:**
 
-Создать правило можно двумя способами: создание через конструктор класса и парсинг JSON-конфига правила.
+- `deny` — эффект политики (запретить доступ)
+- `permission.user.passwordHash` — ключ разрешения.
+- `if any:` — начало блока условий
+- `viewer.id is not equals owner.id` — правило: если идентификатор запрашивающего не равен идентификатору владельца
 
-При создании необходимо указать следующие параметры:
 
-- **id** - `string` Уникальный идентификатор.
-- **name** - `string` Название правила.
-- **condition** - `AbilityCondition` Определяет условия сравнения переданных данных
-- **subject** - `string` Dot notation путь в проверяемом субъекте, например: `user.name`.
-- **resource** - `string | number | boolean | (string | number)[]` Dot notation путь в проверяемом ресурсе, например:
-  `user.name` или значение, которое может быть строкой, числом, булеан значением или массивом строк, или чисел.
+Если `viewer.id` не равен `owner.id`, правило считается выполненным, и политика возвращает `deny` — доступ запрещён. Если же идентификаторы совпадают (т.е. пользователь запрашивает свои собственные данные), правило не срабатывает, и доступ разрешается.
 
-_Создание правила через конструктор класса:_
+_Замечание: Ключ разрешения формируется по принципу: `permission.` + ваш кастомный ключ в формате **dot notation**, например, ключ `foo.bar.baz` в DSL будет иметь вид `permission.foo.bar.baz`_
+
+#### Проверка в коде
 
 ```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(); // получение политик
+const resolver = new AbilityResolver(policies); // создание резолвера
+
+resolver.enforce('user.passwordHash', {
+  viewer: { id: '1' },
+  owner: { id: '2' },
+}); // выбросит ошибку — доступ запрещён
 ```
+В `enforce` передаётся ключ без префикса `permission.` — он автоматически удаляется парсером.
 
-_Создание правила через парсинг JSON-конфигурации:_
+## Основные положения
 
-```ts
-import { AbilityRule } from '@via-profit/ability';
-
-const rule = AbilityRule.parse({
-  "id": "<rule-id>",
-  "name": "Пользователь из отдела managers",
-  "subject": "user.department",
-  "resource": "managers",
-  "condition": "="
-});
+Тезисно перечислим основные положения, которые необходимо знать перед тем как начать пользоваться пакетом:
+
+1. Резолвер (`AbilityResolver`) настроен по принципу `Default Deny`. Это значит, что если ни одна политика не сработала, то результат будет `deny` ([подробнее здесь](#решение-проблем)). Чтобы избежать неожиданного `deny`, убедитесь, что существует хотя бы одна `permit`‑политика, которая может совпасть. Только после этого добавляйте `deny`‑политики.
+2. Политики применяются последовательно. Если несколько политик совпали, результат определяется последней совпавшей политикой.
+3. Правила выполняются последовательно.
+4. В группе правил (`RuleSet`) с оператором сравнения `all` дальнейшее выполнение правил прекращается как только первое же правило вернёт `mismatch`.
+5. Для составления политик используйте [DSL](#dsl) — это проще и удобнее
+6. Для хранения политик на сервере используйте JSON. Политики возможно экспортировать в JSON и импортировать из JSON
+7. Чаще всего следует опираться на утверждение если разрешение не выдано явно → доступ запрещён.
+8. Используйте встроенный кэш только в случаях, если ваши политики неимоверно сложны и содержат большое количество правил
+
+---
+
+## DSL
+
+> DSL - Domain-Specific Language
+
+Ability DSL — это декларативный язык для описания политик доступа.  
+Он позволяет определять правила в человекочитаемой форме, используя простые конструкции: *политики*, *группы*, *правила* и *аннотации*.
+
+### Структура политики
+
+Политика состоит из:
 
 ```
+<effect> <permission> if <all|any>:
+  <group>...
+```
 
-### Проверка правила
+Где:
 
-Для проверки правила следует вызвать метод `check` класса `AbilityRule` передав объект проверяемого ресурса. Этот метод
-вернёт экземпляр класса
-`AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение правила и переданных значений.
+- **effect** — `permit` или `deny`
+- **permission** — строка вида `permission.foo.bar`, где суффикс `permission.` обязателен.
+- **if all:** — все группы должны быть истинны
+- **if any:** — хотя бы одна группа должна быть истинна
 
-```ts
-import { AbilityRule } from '@via-profit/ability';
-
-const rule = AbilityRule.parse({
-  "id": "<rule-id>",
-  "name": "Пользователь из отдела managers",
-  "subject": "user.department",
-  "resource": "managers",
-  "condition": "="
-});
+Политика может содержать одну или несколько групп правил.
 
-const match = rule.check({
-  user: {
-    department: 'managers',
-  },
-});
+Пример:
 
-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)
+> Префикс `permission.` обязателен в DSL, но автоматически удаляется парсером. Внутри системы разрешение хранится как `order.update`.
+
+Пример политики выше гласит - разрешение `permission.order.update` будет разрешено при выполнении одного из двух условий:
+1. user.roles содержит 'admin' **и** user.token не null
+2. user.roles содержит 'developer' **или** user.login равен 'dev'
+
+### Ключ разрешения (permission key)
 
-Для отладки или аудита может быть полезно понять, *почему* было вынесено то или иное суждение о правах доступа. Метод `resolveWithExplain()` политики возвращает детальную информацию о проверке.
+Ключ разрешения записываются в `dot notation` виде, но поддерживают возможность использования wildcard шаблонов при
+помощи символа `*`. Это позволяет группировать ключи, а так же переопределять политики с похожими ключами.
 
-### Использование
+Если под ключ подходит несколько политик, **выполняются все**. Итог определяется **последней совпавшей политикой**:
 
+
+**Пример использования шаблонов**
+
+| Политика (permission) | ключ                   | Совпадает |
+|-------------------|------------------------|-----------|
+| `order.*`         | `order.create`         | да |
+| `order.*`         | `order.update`         | да |
+| `order.*`         | `user.create`          | нет |
+| `*.create`        | `order.create`         | да |
+| `*.create`        | `user.create`          | да |
+| `*.create`        | `order.update`         | нет |
+| `user.profile.*`  | `user.profile.update`  | да |
+| `user.profile.*`  | `user.settings.update` | нет |
+
+**Пример политики с 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 не полный и показан только ради примера
+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); // выбросит AbilityError
 
 ```
 
-Результат `console.debug`
+**Пояснение**
+
+В DSL порядок политик имеет значение:
+последняя совпавшая политика выигрывает.
+
+Поэтому:
+
+1. `permit` `permission.order.*` разрешает всё, что начинается с `order.`
+2. `deny` `permission.order.update` перекрывает это разрешение.
+
+Итог выполнения:
 
 ```
-✓ policy «Запрещает менять статус заявки...» is match
-✓ ruleSet «Не администратор» is match
-✓ rule «Нет роли администраторов» is match
-✓ ruleSet «Проверка статуса...» is match
-✓ rule «Текущий статус "не обработан"» is match
-✓ rule «Будущий статус "завершен"» is match
+order.update → deny
+order.create → permit
+order.delete → permit
+order.view   → permit
 ```
 
----
 
-## Группы правил
+### Комментарии
 
-**Группы правил** необходимы для объединения нескольких правил в группу. **Основная цель** - выполнить проверку каждого
-правила в группе и вернуть лишь один результат.
+Строки, начинающиеся с символа `#` считаются комментариями и не влияют на результат работы правил и политик.
 
-Создавая группу следует указывать метод сравнения (`compareMethod`), который необходим для вычисления значения всей
-группы при проверке правил.
+---
 
-При создании необходимо указать следующие параметры:
+### Аннотации
 
-- **id** - `string` Уникальный идентификатор.
-- **name** - `string` Название группы.
-- **compareMethod** - `AbilityCompare` Способ сравнения правил в группе (`or` или `and`).
+В настоящий момент поддерживается только одна аннотация ’name’, которая будет использована в качестве имени для политики, либо группы правил, либо правила.
 
-_Влияние **compareMethod** на результат вычисления группы:_
+Аннотации задаются через комментарии:
 
-- **`or`** - Результат всей группы примет значение `match`, если хотя бы одно из правил вернуло `match`.
-- **`and`** - Результат всей группы примет значение `match`, если все правила вернули `match`.
+```
+# @name <имя>
+```
 
-### Создание группы правил
+Аннотации применяются к **следующей сущности**:
 
-Создать группу правил можно двумя способами: создание через конструктор класса и парсинг JSON-конфига группы.
+- политике
+- группе
+- правилу
 
-_Создание группы через конструктор класса_:
+Пример:
 
-```ts
-import { AbilityRuleSet, AbilityCompare } from '@via-profit/ability';
+```dsl
+# @name can order update
+permit permission.order.update if any:
+  # @name authorized admin
+  all of:
+    # @name contains role admin
+    user.roles contains 'admin'
+```
 
-const ruleSet = new AbilityRuleSet({
-  id: '<set-id>',
-  name: 'Название группы',
-  compareMethod: AbilityCompare.and,
-});
+---
 
-// Добавление правил в группу
-ruleSet.addRules([
-  new AbilityRule(...),
-  new AbilityRule(...),
-]);
+### Группы правил
 
+Группа определяет, как объединяются правила внутри неё:
 
-// Сокращённая запись
-const ruleSet2 = AbilityRuleSet.and([
-  new AbilityRule(...),
-  new AbilityRule(...),
-]);
+```
+all of:
+  <rule>
+  <rule>
 
+any of:
+  <rule>
+  <rule>
 ```
 
-_Создание группы через парсинг JSON-конфига группы_:
+- `all of:` — логическое AND
+- `any of:` — логическое OR
 
-```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': '=',
-    },
-  ],
-});
+`all of` - значит, что группа считается выполненной, если все правила внутри группы сработали.
+
+`any of` - значит, что группа считается выполненной, если хотя бы одно правило внутри группы сработало.
 
+Каждая группа внутри политики будет вычисляться независимо от других групп. Итоговая оценка результата будет определена путем сравнения результата вычисления всех групп в политике.
+
+
+Группы могут иметь аннотации:
+
+```dsl
+# @name developer group
+any of:
+  user.roles contains 'developer'
 ```
 
-### Проверка группы правил
+---
 
-Для проверки группы правил следует вызвать метод `check` класса `AbilityRuleSet` передав объект проверяемого ресурса.
-Этот метод вернёт экземпляр класса `AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение
-для группы и переданных значений.
+### Правила
 
-```ts
-import { AbilityRuleSet, AbilityCompare } from '@via-profit/ability';
+Правило — это атомарное условие внутри политики. Оно определяет, при каких данных политика будет считаться совпавшей. С помощью правил задаются условия по которым определяется эффективность политики (`permit` или `deny`)
 
-const ruleSet = new AbilityRuleSet({
-  id: '<set-id>',
-  name: 'Название группы',
-  compareMethod: AbilityCompare.and,
-}).addRules([
-  new AbilityRule(...),
-  new AbilityRule(...),
-]);
+Правило имеет форму:
 
-const match = rule.check({ ... });
+```
+<subject> <operator> <value?> — значение указывается не для всех операторов (например, is null не требует значения).
+```
+
+#### Subject (субъект)
 
-const is = match.isEqual(AbilityMatch.match);
+Идентификатор в dot‑нотации:
+
+```
+user.roles
+env.time.hour
+order.total
 ```
 
-___
+#### Operators (операторы)
 
-## Политики
+_Синонимы — это альтернативные формы записи, которые также поддерживаются парсером._
 
-**Политики** включают в себя группы правил. Основная цель - выполнить проверку всех вложенных групп, сравнить результат
-выполнения групп и вернуть один единственный результат.
+**Базовые операторы сравнения**
 
-### Создание политики
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **is equals** | `=`, `==`, `equals` | `age is equals 18` | Строгое равенство | number, string, boolean |
+| **is not equals** | `!=`, `<>`, `not equals` | `role is not equals 'admin'` | Строгое неравенство | number, string, boolean |
+| **greater than** | `>`, `gt` | `age greater than 18` | Больше | number, date |
+| **greater than or equal** | `>=`, `gte` | `age greater than or equal 18` | Больше или равно | number, date |
+| **less than** | `<`, `lt` | `age less than 18` | Меньше | number, date |
+| **less than or equal** | `<=`, `lte` | `age less than or equal 18` | Меньше или равно | number, date |
 
-Создать политику можно двумя способами: создание через конструктор класса и парсинг JSON-конфига политики.
 
-При создании политики необходимо указать следующие параметры:
+**Null‑операторы**
 
-- **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[]` Массив групп (см. [Группы правил](#группы-правил))
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **is null** | `== null`, `= null` | `middleName is null` | Значение отсутствует | any |
+| **is not null** | `!= null` | `middleName is not null` | Значение присутствует | any |
 
-**Замечание** - Политика может быть запрещающей (`effect` = `deny`) и разрешающей (`effect` = `permit`). Если вам
-необходимо ограничить какой-либо доступ, например, пользователю с недостаточными правами, то следует создавать политику
-с эффектом `deny`.
+**Операторы для списков (массивов)**
 
-_Создание политики через конструктор класса_:
+| Оператор DSL | Синонимы                  | Пример | Описание | Типы |
+|--------------|---------------------------|--------|----------|------|
+| **in [...]** | -                         | `role in ['admin', 'manager']` | Значение входит в список | number, string |
+| **not in [...]** | -                         | `role not in ['banned']` | Значение не входит | number, string |
+| **contains** | `includes`, `has`         | `tags contains 'vip'` | Массив содержит элемент | array |
+| **not contains** | `not includes`, `not has` | `tags not contains 'vip'` | Массив не содержит элемент | array |
 
-```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
-    })
-  ]
-});
 
-```
+**Строковые операторы**
 
-_Создание политики через парсинг JSON-конфига_:
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **starts with** | `begins with` | `email starts with 'admin@'` | Строка начинается с | string |
+| **not starts with** | — | `email not starts with 'test'` | Строка не начинается с | string |
+| **ends with** | — | `email ends with '.ru'` | Строка заканчивается на | string |
+| **not ends with** | — | `email not ends with '.com'` | Строка не заканчивается на | string |
+| **includes** | `contains substring` | `name includes 'lex'` | Строка содержит подстроку | string |
+| **not includes** | — | `name not includes 'test'` | Строка не содержит подстроку | string |
 
-```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": "<>"
-        }
-      ]
-    }
-  ]
-});
+**Булевые операторы**
+
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **is true** | `= true` | `isActive is true` | Значение истинно | boolean |
+| **is false** | `= false` | `isActive is false` | Значение ложно | boolean |
+
+**Операторы длины**
+
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **length equals** | `len =` | `tags length equals 3` | Длина равна | array, string |
+| **length greater than** | `len >` | `tags length greater than 2` | Длина больше | array, string |
+| **length less than** | `len <` | `tags length less than 5` | Длина меньше | array, string |
+
+#### Value (значение)
 
+Поддерживаются:
+
+- строки `'text'`
+- числа `42`
+- булевы `true` / `false`
+- `null`
+- массивы `[1, 2, 3]` / `['foo', false, null, 1, 2, '999']`
+
+Примеры:
+
+```dsl
+# возраст пользователя больше 18
+user.age greater than 18
+
+# массив ролей содержит роль 'admin'
+user.roles contains 'admin'
+
+# тэг заказа либо 'vip', либо 'priority'
+order.tag in ['vip', 'priority']
+
+# токен пользователя не null
+user.token is not null
+
+# логин пользователя длиннее 12 символов
+user.login length greater than 12
 ```
 
-### Проверка политики
 
-Для проверки политики правил следует вызвать метод `check` класса `AbilityPolicy` передав объект проверяемого ресурса.
-Этот метод вернёт экземпляр класса `AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение
-для группы и переданных значений.
 
-```ts
-import { AbilityPolicy } from '@via-profit/ability';
+---
 
-const policy = AbilityPolicy.parse({ ... });
+### Неявная группа (implicit group)
 
-const match = policy.check({ ... });
+Если правила идут без `all of:` или `any of:`, они объединяются оператором политики:
 
-const is = match.isEqual(AbilityMatch.match);
+```dsl
+permit permission.order.update if all:
+  user.roles contains 'admin'
+  user.token is not null
 ```
 
-___
+Эквивалентно:
 
-## Управление политиками
+```dsl
+permit permission.order.update if all:
+  all of:
+    user.roles contains 'admin'
+    user.token is not null
+```
 
-Класс `AbilityResolver` — это основной инструмент для применения политик в рантайме. Он решает две ключевые задачи:
+Неявная группа всегда соответствует оператору политики (`if all` или `if any`).
 
-1. **Фильтрация политик по действию** — выбирает только те политики, которые применимы к выполняемой операции
-2. **Оценка разрешений** — последовательно проверяет отобранные политики и возвращает итоговый результат (разрешено/запрещено)
+---
 
-### Зачем нужен AbilityResolver?
+### Полный пример
 
-Представим, что в системе есть десятки политик, каждая на своё действие:
-- `order.create` — правила создания заказа
-- `order.update` — правила обновления заказа
-- `order.delete` — правила удаления заказа
-- `user.profile.update` — правила обновления профиля
-- и так далее...
+```dsl
+# @name разрешено обновление заказа
+permit permission.order.update if any:
 
-Когда пользователь пытается создать заказ, нам нужно проверить только политики, связанные с действием `order.create`, игнорируя все остальные. Именно это и делает `AbilityResolver`.
+  # @name если это администратор
+  all of:
+    user.roles contains 'admin'
+    user.token is not null
 
-### Использование wildcard (*) в действиях
+  # @name если это разработчик
+  any of:
+    user.roles contains 'developer'
+    user.login is equals 'dev'
+```
 
-`AbilityResolver` поддерживает использование символа звездочки (`*`) в названиях действий. Это позволяет создавать политики, которые применяются к целым группам операций.
 
-#### Правила сопоставления с wildcard:
 
-| Политика (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` | ❌ Не совпадает |
+## Объединение политик
 
-#### Примеры использования wildcard:
+В реальном проекте следует использовать несколько политик сразу
 
-```ts
-// Политика, применяемая ко всем действиям с заказами
-{
-  id: 'orders-audit',
-  name: 'Audit all order operations',
-  action: 'order.*',  // Применится к order.create, order.update, order.delete и т.д.
-  effect: 'permit',
-  // ... правила
-}
+TODO: использование нескольких политик
 
-// Политика, применяемая ко всем операциям создания
-{
-  id: 'create-audit',
-  name: 'Audit all create operations',
-  action: '*.create',  // Применится к order.create, user.create, product.create и т.д.
-  effect: 'permit',
-  // ... правила
-}
+## Environment политик
 
-// Политика для всех операций в модуле пользователей
-{
-  id: 'user-module',
-  name: 'User module base policy',
-  action: 'user.*.*',  // Применится к user.profile.update, user.settings.delete и т.д.
-  effect: 'deny',
-  // ... правила
-}
-```
+**Environment** — это объект, содержащий данные окружения, которые не принадлежат ни пользователю, ни ресурсу.
+Содержимое объекта определяется разработчиком и может быть любым объектом состоящим из примитивов.
 
-#### Приоритет и множественное совпадение
+- время запроса,
+- IP‑адрес,
+- параметры устройства,
+- заголовки запроса,
+- контекст сессии,
+- любые другие внешние условия.
 
-Если несколько политик подходят под проверяемое действие, будут применены **все** подходящие политики. Результат определяется последней сработавшей политикой:
+**Примеры:**
 
 ```ts
-const policies = [
-  AbilityPolicy.parse({
-    action: 'order.*',
-    effect: 'permit',
-    // ... правила
-  }),
-  AbilityPolicy.parse({
-    action: 'order.update',
-    effect: 'deny',
-    // ... правила
-  })
-];
+type Environment = {
+  time: {
+    hour: number;
+  };
+  ip: string;
+  geo: {
+    country: string;
+  };
+};
+```
 
-const resolver = new AbilityResolver(policies);
+Environment передаётся в `resolve()` и `enforce()` как третий аргумент:
 
-// При проверке order.update сработают ОБЕ политики
-// Результат будет deny, так как это эффект последней сработавшей политики,
-// таким образом, каждая последующая политика считается важнее предыдущей.
-// Это применительно для ситуаций, когда необходимо, что называется, наложить вето
-// на принятые ранее решения вышестоящих политик
-resolver.enforce('order.update', data);
+```ts
+await resolver.resolve('order.update', resource, environment);
+await resolver.enforce('order.update', resource, environment);
 ```
 
-**Каждая последующая политика считается важнее предыдущей.
-Это применительно для ситуаций, когда необходимо, что называется, наложить вето
-на принятые ранее решения вышестоящих политик**
+### Использование environment в правилах
 
-#### Комбинирование точных действий и wildcard
+В политике можно ссылаться на environment через путь `env.*`.
 
-Вы можете комбинировать точные действия и wildcard для создания гибкой системы прав:
+Пример политики, которая запрещает обновление заказов ночью (22:00–06:00).:
 
-```ts
-const policies = [
-  // Общее правило для всех заказов
-  {
-    action: 'order.*',
-    effect: 'deny',  // По умолчанию запрещено
-    // ...
-  },
-  // Исключение для создания заказа
-  {
-    action: 'order.create',
-    effect: 'permit',  // Создавать можно
-    // ...
-  },
-  // Дополнительная проверка для обновления
-  {
-    action: 'order.update',
-    effect: 'deny',  // Обновление требует особых условий
-    ruleSet: [
-      // ... сложные правила для обновления
-    ]
-  }
-];
+```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
 ```
 
-### Как это работает
+**Извлечение значений из environment**
 
-```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 policies = AbilityPolicy.parseAll(configs);
+- `env.*` → значение берётся из environment
+- `user.*`, `order.*`, `profile.*` → из resource
+- литерал (`18`, `"admin"`, `true`) → используется как есть
 
-// Создаем резолвер со всеми политиками
-const resolver = new AbilityResolver(policies);
+Пример:
 
-// При выполнении действия указываем только нужный action
-// AbilityResolver автоматически отфильтрует политики и проверит их
-resolver.enforce('order.create', {
-  user: {
-    department: 'managers',
-    roles: ['manager']
-  },
-  order: {
-    amount: 5000
-  }
-});
+```ts
+subject: "env.geo.country"
+resource: "user.country"
+condition: "equal"
 ```
 
-### Проверка соответствия действия
+### Environment в TypeScript
 
-Метод `isInActionContain` позволяет проверить, соответствует ли действие шаблону с wildcard:
+Тип Environment задаётся на уровне `AbilityResolver`:
 
 ```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 resolver = new AbilityResolver<Resources, Environment>(policies);
 ```
 
-Этот метод используется внутри `AbilityResolver` для фильтрации политик, но может быть полезен и в пользовательском коде.
+Это позволяет:
 
-### Методы AbilityResolver
+- получать автодополнение в IDE,
+- проверять корректность путей `env.*`,
+- избегать ошибок при передаче environment.
 
-#### `enforce()` — строгая проверка
+> Если правило использует `env.*`, но environment не передан, то значение `env.*` будет `undefined`, и сравнение будет выполнено так, как если бы environment не было вовсе
 
-```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;
-}
-```
 
-**Важно**: `enforce()` выбрасывает исключение, если хотя бы одна подходящая политика вернула `deny`. Если ни одна политика не сработала или все вернули `permit` — исключения не будет.
 
-#### `resolve()` — мягкая проверка
+## Генератор типов для TypeScript
 
-```typescript
-const result = resolver
-  .resolve('order.update', data)
-  .isDeny(); // true если доступ запрещен
+`AbilityParser.generateTypeDefs()` генерирует типы для TypeScript на основе политик, что позволяет не беспокоиться о расхождении между типами и данными в политиках.
 
-if (result) {
-  // Самостоятельно обрабатываем запрет
-  return { error: 'Access denied' };
-}
+**Пример использования**
 
-// Продолжаем выполнение
-await updateOrder(data);
-```
+Сначала необходимо подготовить массив политик. Политики можно хранить в DSL или в JSON и парсить их в массив готовых политик. В данном примере, для наглядности, политики хранятся в DSL.
 
-#### `resolveWithExplain()` — проверка с объяснением
+```ts
+// scripts/policies.ts
 
-```typescript
-const explanations = resolver.resolveWithExplain('order.update', data);
+import { AbilityDSLParser } from './AbilityDSLParser';
 
-explanations.forEach(explain => {
-  console.log(explain.toString());
-  // ✓ policy «Политика обновления заказа» is match
-  //   ✗ ruleSet «Проверка владельца» is mismatch
-  //   ✓ ruleSet «Проверка статуса» is match
-});
+const dsl = `
+# @name Update order
+permit permission.order.update if all:
 
-if (resolver.isDeny()) {
-  console.log('Доступ запрещен по причине:');
-  explanations.forEach(e => console.log(e.toString()));
-}
+  # @name Owner check
+  all of:
+    # @name User is owner
+    user.id = order.ownerId
+`;
+
+const policies = new AbilityDSLParser(dsl).parse();
+
+export default policies;
 ```
 
-### Интеграция с TypeScript
+```ts
+// scripts/generate-types.ts
+import { writeFileSync } from 'node:fs';
+import { AbilityParser } from '@via-profit/ability';
+import policies from './policies.json';
 
-Для полной типобезопасности определите интерфейс `Resources`, где ключи — это возможные действия, а значения — структура данных, требуемая для проверки:
+const typedefs = AbilityParser.generateTypeDefs(policies);
 
-```typescript
-// Определяем типы данных для каждого действия
-type Resources = {
-  'order.create': {
-    readonly user: {
-      readonly department: string;
-      readonly roles: readonly string[];
-    };
-    readonly order: {
-      readonly amount: number;
-    };
-  };
-  
+writeFileSync('./src/ability/types.generated.ts', typedefs, 'utf8');
+```
+
+**Сгенерированный файл (пример)**
+
+```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 id: string;
-      readonly status: string;
       readonly ownerId: string;
     };
   };
-  
-  'user.profile.update': {
-    readonly user: {
-      readonly id: string;
-    };
-    readonly profile: {
-      readonly userId: string;
-    };
-  };
 };
+```
 
-// Теперь TypeScript будет проверять корректность передаваемых данных
-resolver.enforce('order.create', {
-  user: {
-    department: 'managers',
-    roles: ['manager']
-  },
-  order: {
-    amount: 5000  // ✅ все поля на месте
-  }
+**Использование в коде**
+
+```ts
+import { AbilityResolver, AbilityPolicy } from '@via-profit/ability';
+import type { Resources } from './ability/types.generated';
+
+const resolver = new AbilityResolver<Resources>(
+  AbilityPolicy.parseAll(policies),
+);
+
+await resolver.enforce('order.update', {
+  user: { id: 'u1' },
+  order: { ownerId: 'u1' },
 });
+```
 
-// ❌ Ошибка компиляции - не хватает required полей
-resolver.enforce('order.create', {
-  user: {
-    department: 'managers'
-    // missing roles
-  }
+## Отладка политик
+
+### Объяснения
+
+Для упрощения отладки политик применяется специальный класс `AbilityResult`, который уже включён в итоговый результат вычислений. `AbilityResult` инкапсулирует итог применения всех подходящих политик к ключу разрешений и ресурсу.
+
+`AbilityResult` содержит:
+
+- список проверенных политик,
+- методы для определения итогового эффекта,
+- методы для получения объяснений в текстовом представлении.
+
+Пример:
+
+```ts
+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` и связанные классы (`AbilityExplainPolicy`, `AbilityExplainRuleSet`, `AbilityExplainRule`) позволяют получить человекочитаемое объяснение:
+
+- какая политика сработала,
+- какие группы правил совпали,
+- какие правила не прошли,
+- какой эффект был применён.
+
+Пример использования:
+
+```ts
+const result = await resolver.resolve('order.update', resource);
+const explanations = result.explain();
+
+console.log(explanations.toString());
+```
+
+Пример вывода:
+
+```
+✓ policy «Запрет обновления заказа для менеджеров» is match
+  ✓ ruleSet «Менеджеры» is match
+    ✓ rule «Отдел managers» is match
+    ✗ rule «Роль manager» is mismatch
+  ✓ ruleSet «Не администраторы» is match
+    ✓ rule «Нет роли administrator» is match
+```
+
+### Формат вывода
+
+В настоящий момент поддерживается только один формат вывода - текстовый.
+
+Вывод строится по принципу: <policy | ruleSet | rule > <название> <is match | is mismatch>
+
+
+## Решение проблем
+
+### Модель принятия решений (Default Deny)
+
+> Почему политика `deny` не превращается в `permit`, если её условия не выполнены?
+
+Рассмотрим политику, которая **запрещает** доступ пользователю с возрастом 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);
+
+const result = await resolver.resolve('test', {
+  user: { age: 16 },
 });
+
+console.log(result.isDenied());  // true  ✔
+console.log(result.isAllowed()); // false ✔
 ```
 
-### Как формируется итоговое решение?
+В этом случае всё очевидно:  
+условие выполнено → политика совпала → эффект `deny` → доступ запрещён.
 
-1. Resolver собирает все политики, у которых `action` соответствует запрошенному (поддерживается wildcard `*`)
-2. Последовательно проверяет каждую политику методом `check()`
-3. Если политика вернула `match`, запоминает её `effect` (permit/deny)
-4. Возвращается `effect` **последней сработавшей политики**
+**Что происходит, если условия `не выполнены`?**
 
-```typescript
-// Пример с несколькими политиками на одно действие
-const policies = [
-  permitPolicy, // permit, но не match
-  denyPolicy,   // deny и match
-  permitPolicy2 // permit, но не match
-];
+```ts
+const result = await resolver.resolve('test', {
+  user: { age: 12 },
+});
 
-resolver.enforce('some.action', data);
-// Результат: deny (от последней сработавшей политики)
+console.log(result.isDenied());  // true  ✔
+console.log(result.isAllowed()); // false ✔
 ```
 
-### Когда использовать Resolver?
+На первый взгляд может показаться, что если условие не выполнено, то политика должна «разрешить» доступ.  
+Но это **не так**.
 
-- **В API endpoints** — проверка прав перед выполнением операции
-- **В middleware** — централизованная проверка доступа
-- **В сервисах** — защита бизнес-логики
-- **В клиентском коде** — условный рендеринг UI на основе прав
+**Модель принятия решений: `Default Deny`**
 
-Resolver делает систему прав предсказуемой, типобезопасной и легко расширяемой.
+`AbilityResolver` использует классическую модель безопасности:
 
-## API Reference
+> **Если нет ни одной совпавшей permit‑политики → доступ запрещён.**
 
-### Класс AbilityCode
+**Что происходит в данном примере:**
 
-Базовый абстрактный класс для всех кодовых значений в системе.
+1. Политика `deny` существует, но её условие **не выполнено**  
+   → политика получает статус `mismatch`.
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `isEqual()` | `compareWith: AbilityCode<T> \| null` | `boolean` | Сравнивает текущий код с другим экземпляром |
-| `isNotEqual()` | `compareWith: AbilityCode<T> \| null` | `boolean` | Проверяет неравенство с другим экземпляром |
+2. Политика `deny` **не применяется**, потому что условия не совпали.
 
-**Геттеры:**
-- `code: T` - возвращает сырое значение кода (строку или число)
+3. Политики `permit` **нет**.
 
----
+4. Раз нет ни одной разрешающей политики → итоговое решение:  
+   **deny (по умолчанию)**.
 
-### Класс AbilityMatch
 
-Представляет возможные состояния результата проверки правил.
+**Итог**
 
-**Статические свойства:**
-- `AbilityMatch.pending` - ожидание проверки
-- `AbilityMatch.match` - совпадение найдено
-- `AbilityMatch.mismatch` - совпадение не найдено
+- `deny` с совпавшими условиями → **deny**
+- `deny` с несовпавшими условиями → **deny (default deny)**
+- `permit` с совпавшими условиями → **allow**
+- `permit` с несовпавшими условиями → **deny (default deny)**
 
-Каждое свойство является экземпляром класса `AbilityMatch` и наследует все его методы.
+**Заключение**
 
----
+**Доступ разрешается только при наличии явного permit.**
 
-### Класс AbilityCondition
+## Рекомендации по проектированию
 
-Определяет операторы сравнения для правил доступа.
+### Именование ключей доступа
 
-**Статические свойства:**
-- `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`)
+- Используйте иерархические ключи: `permission.order.create`, `permission.order.update.status`, `permission.user.profile.update`.
+- Группируйте по доменам: `permission.user.*`, `permission.order.*`, `permission.product.*`.
+- Не смешивайте разные домены в одном ключе.
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `fromLiteral()` | `literal: AbilityConditionLiteralType` | `AbilityCondition` | Создает экземпляр условия из литерального имени (например, 'equal' → '=') |
+### Структура данных
 
-**Геттеры:**
-- `literal: AbilityConditionLiteralType` - возвращает литеральное имя оператора ('equal', 'not_equal' и т.д.)
+- Явно описывайте `Resources` в TypeScript.
+- Не передавайте «лишние» поля — это усложняет понимание.
+- Старайтесь, чтобы структура данных для одного `permission` была стабильной.
 
----
+### Проектирование политик
 
-### Класс AbilityCompare
+- Общие правила — через wildcard (`permission.order.*`).
+- Специфичные ограничения — через точные действия (`permission.order.update`).
+- Для запретов используйте `effect: deny`.
+- Для разрешений — `effect: permit`.
 
-Определяет методы логического сравнения для групп правил.
+### Типичные ошибки
 
-**Статические свойства:**
-- `AbilityCompare.and` - логическое И (все правила должны совпасть)
-- `AbilityCompare.or` - логическое ИЛИ (достаточно одного совпадения)
+- Ожидание, что отсутствие совпавших политик означает deny.
+- Смешивание бизнес-логики и политик доступа.
+- Слишком крупные политики с десятками правил — лучше разбивать.
 
----
+### Пример использования на фронтенде (React)
 
-### Класс AbilityPolicyEffect
+**Хук для проверки политик**
 
-Определяет эффект применения политики.
+```tsx
+// hooks/use-ability.ts
+import { useEffect, useState } from 'react';
+import { AbilityResolver } from '@via-profit/ability';
+import { Resources } from './generated-types';
 
-**Статические свойства:**
-- `AbilityPolicyEffect.deny` - запрет доступа
-- `AbilityPolicyEffect.permit` - разрешение доступа
+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;
 
-### Класс 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` | Создает правило с условием "больше или равно" |
+    async function check() {
+      try {
+        const result = await resolver.resolve(permission, resource);
+        if (!cancelled) {
+          setAllowed(result.isAllowed());
+        }
+      } catch {
+        if (!cancelled) {
+          setAllowed(false);
+        }
+      }
+    }
 
----
+    check();
 
-### Класс AbilityRuleSet
+    return () => {
+      cancelled = true;
+    };
+  }, [resolver, permission, resource]);
 
-Группирует несколько правил для совместной проверки.
+  return allowed;
+}
+```
 
-**Свойства:**
-- `state: AbilityMatch` - текущее состояние группы после вызова `check()`
-- `rules: AbilityRule[]` - массив правил в группе
-- `compareMethod: AbilityCompare` - метод сравнения (AND/OR)
-- `name: string` - название группы
-- `id: string` - уникальный идентификатор
+**Использование в компоненте**
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `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` | Статический метод. Создает группу с логическим ИЛИ |
+```tsx
+function OrderUpdateButton({ order, user }) {
+  const allowed = useAbility(resolver, 'order.update', {
+    user,
+    order,
+  });
 
----
+  if (allowed === null) {
+    return null; // или бейдж загрузки
+  }
 
-### Класс AbilityPolicy
+  if (!allowed) {
+    return null;
+  }
 
-Объединяет группы правил в полноценную политику доступа.
+  return <button>Update order</button>;
+}
+```
 
-**Свойства:**
-- `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. Удобен для загрузки нескольких политик одновременно. |
+## Примеры
 
----
 
-### Класс AbilityResolver
+### Пример сложной многоступенчатой политики
 
-Управляет множеством политик и их выполнением.
+Ниже - многоступенчатый набор политик, на примере использования в кинотеатре (выдуманный пример).
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `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` | Статический метод. Проверяет, соответствует ли действие шаблону (поддерживает `*`) |
+**Пример демонстрирует:**
+ - работу с ролями (admin, seller, manager, VIP, banned),
+ - временн́ые ограничения (`env.time.hour`),
+ - wildcard‑права (`permission.*`),
+ - ограничения по количеству билетов,
+ - запрет на продажу уже проданных билетов,
+ - комбинацию `permit`/`deny`‑политик,
+ - приоритет политик и модель Default Deny.
 
----
 
-### Класс AbilityExplain
+**Краткое описание правил**
+- **Администратор**  
+  Имеет wildcard‑права (`permission.*`) и может выполнять любые действия.  
+  Может редактировать стоимость билетов.
 
-Представляет человекочитаемое объяснение результата проверки.
+- **Продавец**  
+  Может продавать билеты только в рабочие часы (09:00–23:00).  
+  Не может продавать билеты, если:
+   - кинотеатр закрыт,
+   - билет уже продан.
 
-**Свойства:**
-- `type: AbilityExplainType` - тип элемента ('policy' \| 'rule' \| 'ruleSet')
-- `children: AbilityExplain[]` - дочерние элементы объяснения
-- `name: string` - название элемента
-- `match: AbilityMatch` - результат проверки
+- **Менеджер**  
+  Имеет те же права, что и продавец.
 
-| Метод | Аргументы | Возвращаемое значение | Описание |
-|-------|-----------|----------------------|----------|
-| `toString()` | `indent: number = 0` | `string` | Форматирует объяснение в читаемый текст с отступами |
+- **Покупатели**
+   - Пользователь старше 21 года может покупать билеты.
+   - VIP‑пользователь может покупать билеты в любое время.
+   - Заблокированный пользователь (`status = banned`) не может покупать билеты.
+   - Любой пользователь не может купить более 6 билетов.
 
-**Наследники:**
-- `AbilityExplainRule` - объяснение для правила
-- `AbilityExplainRuleSet` - объяснение для группы правил
-- `AbilityExplainPolicy` - объяснение для политики
 
----
+**Общая диаграмма политик**
+
+```mermaid
+flowchart LR
+
+%% ==== ROLES ====
+
+   subgraph Roles[Роли]
+      A[Администратор]
+      B[Продавец]
+      C[Менеджер]
+   end
+
+   subgraph Buyers[Покупатели]
+      U1[Пользователь > 21]
+      U2[VIP пользователь]
+      U3[Заблокированный пользователь]
+   end
+
+%% ==== ADMIN ====
+
+   A --> A1[Wildcard: permission.*]
+   A --> A2[Редактировать цену билетов]
+
+   A1 --> FINAL[Итоговое решение]
+   A2 --> FINAL
+
+%% ==== SELLER ====
+
+   B --> B1[Продавать билеты]
+
+   B1 -->|09:00–23:00| B2[Разрешено]
+   B1 -->|Вне времени| D2[Запрещено]
+   B1 -->|ticket.status = sold| D3[Запрещено]
+
+   B2 --> FINAL
+   D2 --> FINAL
+   D3 --> FINAL
+
+%% ==== MANAGER ====
+
+   C --> C1[Продавать билеты как продавец]
+   C1 --> FINAL
+
+%% ==== BUYERS ====
+
+   U1 --> U1A[Покупать билеты]
+   U1A -->|ticketsCount < 6| U1OK[Разрешено]
+   U1A -->|ticketsCount ≥ 6| U1DENY[Запрещено]
+
+   U2 --> U2A[Покупать билеты в любое время]
+   U2A -->|ticketsCount < 6| U2OK[Разрешено]
+   U2A -->|ticketsCount ≥ 6| U2DENY[Запрещено]
+
+   U3 --> U3A[Запрещено покупать билеты]
+
+   U1OK --> FINAL
+   U1DENY --> FINAL
+   U2OK --> FINAL
+   U2DENY --> FINAL
+   U3A --> FINAL
+
+%% ==== DENY RULES ====
+
+   D1[Запрещено покупать билеты, если user.status = banned] --> FINAL
 
-### Класс 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[];
-//     };
-//   };
-// }
 ```
 
----
+**DSL политик**
 
-### Классы ошибок
+```dsl
+############################################################
+# @name Admin can edit ticket price
+permit permission.ticket.price.edit if all:
+  user.role is equals 'admin'
 
-| Класс | Назначение |
-|-------|------------|
-| `AbilityError` | Общая ошибка доступа, выбрасывается при запрете в `enforce()` |
-| `AbilityParserError` | Ошибка парсинга конфигурации или генерации типов |
 
-## Рекомендации по использованию
+############################################################
+# @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
 
-### Именование экшенов
 
-Используйте точечную нотацию для иерархии действий:
+############################################################
+# @name Users older than 21 can buy tickets
+permit permission.ticket.buy if all:
+  user.age greater than 21
 
-- `order.create` - создание заказа
-- `order.update` - обновление заказа
-- `order.status.update` - обновление статуса заказа
 
-### Структура данных
+############################################################
+# @name VIP users can buy tickets anytime
+permit permission.ticket.buy if all:
+  user.isVIP is true
+
+
+############################################################
+# @name Deny buying tickets if user is banned
+deny permission.ticket.buy if all:
+  user.status is equals 'banned'
 
-Старайтесь группировать связанные данные под общими ключами:
+
+############################################################
+# @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
+
+
+############################################################
+# @name Manager can do everything seller can
+permit permission.ticket.sell if all:
+  user.role is equals 'manager'
+
+
+############################################################
+# @name Admin wildcard permissions
+permit permission.* if all:
+  user.role is equals 'admin'
+
+
+############################################################
+# @name Limit tickets per user (max 6)
+deny permission.ticket.buy if all:
+  user.ticketsCount greater than or equal 6
+
+
+############################################################
+# @name Cannot sell already sold tickets
+deny permission.ticket.sell if all:
+  ticket.status is equals 'sold'
+
+```
+
+
+Ниже показано, как использовать приведённые выше политики в Node.js + TypeScript.
+
+**Подготовка политик**
 
 ```ts
-// Хорошо
-{
-  user: { id: '123', roles: ['admin'] },
-  order: { status: 'new', amount: 1000 }
-}
+import { AbilityDSLParser } from '@via-profit/ability';
+import cinemaDSL from './policies/cinema.dsl';
+
+export const policies = new AbilityDSLParser(cinemaDSL).parse();
+```
 
-// Плохо
-{
-  userId: '123',
-  userRoles: ['admin'],
-  orderStatus: 'new',
-  orderAmount: 1000
+**Создание резолвера**
+
+```ts
+import { AbilityResolver } from '@via-profit/ability';
+import { policies } from './policies';
+
+const resolver = new AbilityResolver(policies);
+```
+
+**Проверка разрешений (enforce)**
+
+Пример: покупка билета.
+
+Метод enforce выбрасывает исключение `AbilityError`, если доступ запрещён.
+
+```ts
+await resolver.enforce('ticket.buy', {
+  user: { age: 25, ticketsCount: 1 },
+  env: { time: { hour: 18 } },
+});
+
+```
+Если разрешено — код продолжит выполнение.
+Если запрещено — будет выброшено исключение `AbilityError`.
+
+
+
+**Проверка разрешений без исключений (resolve)**
+
+`resolve` возвращает объект результата:
+
+```ts
+const result = await resolver.resolve('ticket.buy', {
+  user: { age: 25, ticketsCount: 1 },
+  env: { time: { hour: 18 } },
+});
+
+if (result.isAllowed()) {
+  console.log('Покупка разрешена');
+} else {
+  console.log('Покупка запрещена');
 }
+
 ```
 
-### Проектирование политик
+**Продавец может продавать только в рабочие часы***
 
-- Используйте `deny` для запрещающих политик, `permit` для разрешающих
-- Комбинируйте простые правила для сложной логики
-- Давайте понятные имена правилам и политикам для упрощения отладки
+```ts
+await resolver.enforce('ticket.sell', {
+  user: { role: 'seller' },
+  env: { time: { hour: 15 } },
+  ticket: { status: 'available' },
+});
 
-## Отладка политик
+```
+
+**Подготовка данных для резолвера**
+
+В примерах выше в резолвер передаются простые константные объекты:
+
+```ts
+resolver.enforce('ticket.buy', {
+  user: { age: 25 },
+  env: { time: { hour: 18 } },
+});
+```
+
+Это сделано для наглядности. В реальном приложении данные для резолвера должны формироваться динамически — из тех источников, которые доступны вашему серверу.
+
+**Пользователь** (`user`) обычно берётся из:
+
+
+- JWT‑токена
+- сессии
+- базы данных
+- middleware авторизации
+
+Пример:
+
+```ts
+const user = await db.users.findById(session.userId);
+```
+
+**Окружение (Environment)** (`env`)
+
+Это любые внешние параметры, которые могут влиять на доступ:
+
+- текущее время сервера
+- часовой пояс
+- IP‑адрес
+- заголовки запроса
+- конфигурация системы
+
+Пример:
+
+```ts
+const env = {
+  time: {
+    hour: new Date().getHours(),
+  },
+  ip: req.ip,
+};
+```
 
-Используйте `resolveWithExplain()` для получения детальной информации о процессе проверки:
+**Ресурс** (например, `ticket`)
+
+Если действие связано с конкретным объектом — его тоже нужно загрузить:
 
 ```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);
+```
+
+**Контекст**
+
+Контекст — это объект, который вы передаёте в `resolve` или `enforce`.  
+Он содержит **все данные**, которые могут понадобиться политикам:
+
+- `user` — данные о текущем пользователе
+- `env` — данные окружения (время, IP, география, настройки системы)
+- `resource` или `ticket` — данные о сущности, над которой выполняется действие
+- любые другие объекты, которые вы используете в DSL
+
+**Важно понимать:**
+
+> Контекст формируется под конкретное действие и конкретные политики. Его не нужно хранить заранее — вы собираете его динамически перед вызовом резолвера.
+
+
+## Производительность
+
+В тестах задействовались политики на 10 условий, вложенные поля, 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
+
 ```