@via-profit/ability 3.1.1 → 3.3.0

package/CHANGELOG.md

@@ -1,129 +1,2 @@
 # Changelog
 
-## [3.2.0] - 2026-x3-xx
-
-### Изменено
-
-- Метод `AbilityPolicy.parseAll()` переименован в `AbilityPolicy.fromJSONAll()`
-- Метод `AbilityPolicy.parse()` переименован в `AbilityPolicy.toJSON()`
-- Метод `AbilityRule.parse()` переименован в `AbilityRule.toJSON()`
-- Метод `AbilityRuleSet.parse()` переименован в `.toJSON()`
-
-## [3.1.0] - 2026-03-20
-
-### Добавлено
-
-- Реализован кэш
-  - Добавлен кэш-провайдер `AbilityCacheProvider` для реализации кастомного кэша
-  - Реализован и включён по умолчанию `AbilityInMemoryCache` (кэш в памяти)
-- Добавлена полноценная поддержка `environment` как третьего аргумента в:
-  - `resolver.resolve(action, resource, environment)`
-  - `resolver.enforce(action, resource, environment)`
-- Введена возможность использовать пути вида `env.*` в правилах политик.
-  - Пример: `"subject": "env.time.hour"`
-- Добавлена поддержка смешанных сравнений:
-  - `resource.*` ↔ `env.*`
-  - литерал ↔ `env.*`
-  - `env.*` ↔ литерал
-
-### Breaking changes
-
-Асинхронизация механизма проверки политик.
-Все методы, участвующие в цепочке вычисления разрешений, теперь возвращают `Promise`.
-
-#### Изменено
-
-- `AbilityRule.check(resource): Promise<AbilityMatch>`  
-  Ранее возвращал `AbilityMatch` синхронно.
-
-- `AbilityRuleSet.check(resource): Promise<AbilityMatch>`  
-  Теперь выполняет правила последовательно и асинхронно.
-
-- `AbilityPolicy.check(resource): Promise<AbilityMatch>`  
-  Асинхронно проверяет ruleSet в строгом порядке.
-
-- `AbilityResolver.resolve(action, resource): Promise<AbilityResult>`  
-  Теперь асинхронный метод, который дожидается выполнения всех политик.
-
-- `AbilityResolver.enforce(action, resource): Promise<void | never>`  
-  Теперь работает асинхронно.
-
-### Миграция
-
-1. Все вызовы `check()` должны быть обновлены:
-
-```ts
-await rule.check(resource);
-await ruleSet.check(resource);
-await policy.check(resource);
-```
-
-2. Все вызовы `resolver.resolve()` и `resolver.enforce()` теперь требуют `await`:
-
-```ts
-await resolver.resolve('order.update', resource);
-await resolver.enforce('order.update', resource);
-```
-
-## [3.0.1] - 2026-03-19
-
-## Добавлено
-
-### 1. **Лицензия MIT** (`LICENSE`)
-
-- Добавлен официальный файл лицензии MIT от Via Profit
-
-### 2. **Класс `AbilityExplain.ts`**
-
-- Новый класс для получения человекочитаемых объяснений результатов проверки
-- Классы-наследники:
-    - `AbilityExplainRule` - объяснение для правила
-    - `AbilityExplainRuleSet` - объяснение для группы правил
-    - `AbilityExplainPolicy` - объяснение для политики
-- Метод `toString()` форматирует вывод с отступами и символами ✓/✗
-
----
-
-## Обновлено
-
-### **AbilityParser.ts** (полная переработка)
-
-- **Было**: Базовая генерация типов
-- **Стало**: Расширенная система генерации TypeScript типов
-- Новые методы:
-    - `determineTypeFromRule()` - определение типа на основе правила
-    - `getArrayType()` - обработка массивов
-    - `getPrimitiveType()` - определение примитивных типов
-    - `buildNestedStructure()` - трансформация плоской структуры во вложенную
-    - `formatTypeDefinitions()` - форматирование финального вывода
-    - `formatNestedObject()` - рекурсивное форматирование объектов
-
-### **AbilityRule.ts**
-
-- `id` и `name` теперь опциональные (`?`)
-- Автогенерация `id` и `name` если не предоставлены
-- **Новые статические методы** (фабричные методы):
-    - `equal()`, `notEqual()`, `in()`, `notIn()`
-    - `lessThan()`, `lessOrEqual()`, `moreThan()`, `moreOrEqual()`
-
-### **AbilityRuleSet.ts**
-
-- `id` и `name` теперь опциональные
-- Добавлены статические методы:
-    - `and()` - создание группы с логическим И
-    - `or()` - создание группы с логическим ИЛИ
-
-### **AbilityPolicy.ts**
-
-- Новый метод `explain()` - получение объяснения проверки
-- Новый статический метод `parseAll()` - парсинг массива конфигураций
-- Улучшены комментарии к полю `action`
-
-### **AbilityResolver.ts**
-
-- Новый метод `resolveWithExplain()` - проверка с детальным объяснением
-- Возвращает массив `AbilityExplain[]` для анализа результатов
-
----
-
-## Обновлена документация и примеры

package/README.md

@@ -3,6 +3,15 @@
 > 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.
 
+![npm version](https://img.shields.io/npm/v/%40via-profit/ability)
+![npm downloads](https://img.shields.io/npm/dm/%40via-profit/ability)
+![license](https://img.shields.io/github/license/via-profit/ability)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+![status](https://img.shields.io/badge/status-active-success)
+![issues](https://img.shields.io/github/issues/via-profit/ability)
+![stars](https://img.shields.io/github/stars/via-profit/ability?style=social)
+
+
 ## Language / Язык
 
 - [🇬🇧 English](/docs/en/README.md)
@@ -113,6 +122,191 @@ Let’s briefly list the key points you need to know before starting to use the
 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.
 
+### Interaction Model
+
+First, you define "raw" policies (using DSL, JSON, or classes). Then, you transform the raw data into ready-to-use policies (an array of policies). This is done once and provides a single source of truth. After that, you can perform permission checks in any part of your code using the prepared policies and the resolver.
+
+Policies, rule sets, and rules can be created using:
+
+- DSL (Domain-Specific Language)
+- Classes (classic approach)
+- JSON
+
+**Creating policies with DSL**
+
+```ts
+import { AbilityDSLParser } from '@via-profit/ability';
+
+// Describe policies using Ability-DSL
+const dsl = `
+  # @name Order creation is only available to persons over 18 years old
+  permit permission.order.action.create if all:
+    all of:
+      user.age gte 18
+
+  # @name Price editing is only available to administrators
+  permit permission.order.data.price if all:
+    all of:
+      user.roles contains 'administrator'
+`;
+
+// Define resource types for TypeScript
+// Types can be generated automatically (more on this later) or defined manually
+// In this example, for simplicity, types are defined manually
+type Resources = {
+  ['order.action.create']: {
+    user: {
+      age: number;
+    }
+  }
+  ['order.data.price']: {
+    user: {
+      roles: string[];
+    }
+  }
+}
+
+// Use the parser to create policies
+// Pass the resource type as a generic parameter
+const policies = new AbilityDSLParser<Resources>(dsl).parse(); // AbilityPolicy[]
+
+// The parser returns an array of policies even
+// if only one policy is described in the DSL
+console.log(policies); // [AbilityPolicy, AbilityPolicy, ...]
+
+// Export the ready-to-use policies
+export default policies;
+```
+
+For more details about DSL, see the [DSL](#dsl) section.
+
+**Creating policies using classes (classic approach)**
+
+This approach is quite verbose but gives you full control over the policies.
+
+```ts
+import { AbilityPolicy, AbilityRuleSet, AbilityRule, AbilityCompare, AbilityPolicyEffect } from '@via-profit/ability';
+
+// Define resource types for TypeScript
+// Types can be generated automatically (more on this later) or defined manually
+// In this example, for simplicity, types are defined manually
+type Resources = {
+  ['order.action.create']: {
+    user: {
+      age: number;
+    }
+  }
+  ['order.data.price']: {
+    user: {
+      roles: string[];
+    }
+  }
+}
+
+const policies = [
+  // first policy
+  new AbilityPolicy<Resources>({
+    id: '1',
+    name: 'Order creation is only available to persons over 18 years old',
+    compareMethod: AbilityCompare.and,
+    effect: AbilityPolicyEffect.permit,
+    permission: 'order.action.create',
+  }).addRuleSet(
+    AbilityRuleSet.and([
+      // rule
+      AbilityRule.moreOrEqual('user.age', 18),
+    ]),
+  ),
+
+  // second policy
+  new AbilityPolicy<Resources>({
+    id: '2',
+    name: 'Price editing is only available to administrators',
+    compareMethod: AbilityCompare.and,
+    effect: AbilityPolicyEffect.permit,
+    permission: 'order.data.price',
+  }).addRuleSet(
+    AbilityRuleSet.and([
+      // rule
+      AbilityRule.contains('user.roles', 'administrator'),
+    ])
+  ),
+];
+
+// Export the ready-to-use policies
+export default policies;
+```
+
+**Creating policies with JSON**
+
+JSON allows you to store policies in a file or database, for example, in PostgreSQL, which supports working with JSON data.
+
+Policy, rule set, and rule classes have JSON export methods, so you can create policies in any way and export them to JSON whenever needed.
+
+```ts
+import { AbilityJSONParser } from '@via-profit/ability';
+
+// Define resource types for TypeScript
+// Types can be generated automatically (more on this later) or defined manually
+// In this example, for simplicity, types are defined manually
+type Resources = {
+  ['order.action.create']: {
+    user: {
+      age: number;
+    }
+  }
+  ['order.data.price']: {
+    user: {
+      roles: string[];
+    }
+  }
+}
+
+// Parse JSON using AbilityJSONParser
+// Pass the resource types as a generic parameter
+const policies = AbilityJSONParser.parse<Resources>([
+  {
+    id: '1',
+    name: 'Order creation is only available to persons over 18 years old',
+    effect: 'permit',
+    permission: 'order.action.create',
+    compareMethod: 'and',
+    ruleSet: [
+      {
+        compareMethod: 'and',
+        rules: [
+          {
+            subject: 'user.age',
+            resource: 18,
+            condition: '>',
+          }
+        ]
+      }
+    ],
+  },
+  {
+    id: '2',
+    name: 'Price editing is only available to administrators',
+    effect: 'permit',
+    permission: 'order.data.price',
+    compareMethod: 'and',
+    ruleSet: [
+      {
+        compareMethod: 'and',
+        rules: [
+          {
+            subject: 'user.roles',
+            resource: 'administrator',
+            condition: 'contains',
+          }
+        ]
+      }
+    ]
+  }
+]);
+
+export default policies;
+```
 ---
 
 ## DSL
@@ -447,24 +641,17 @@ The content of the object is defined by the developer and can be any object cons
 - session context,
 - any other external conditions.
 
-**Examples:**
-
-```ts
-type Environment = {
-  time: {
-    hour: number;
-  };
-  ip: string;
-  geo: {
-    country: string;
-  };
-};
-```
 
 Environment is passed to `resolve()` and `enforce()` as the third argument:
 
 ```ts
-await resolver.resolve('order.update', resource, environment);
+const environment = {
+  time: {
+    hour: new Date().getHours(),
+  },
+  ip: req.ip,
+}
+
 await resolver.enforce('order.update', resource, environment);
 ```
 
@@ -515,18 +702,14 @@ This allows:
 
 ## TypeScript Type Generator
 
-`AbilityParser.generateTypeDefs()` generates TypeScript types based on policies, allowing you to avoid discrepancies between types and data in policies.
-
-**Usage Example**
+`AbilityTypeGenerator.generateTypeDefs(policies)` generates TypeScript types based on policies, allowing you to avoid inconsistencies between types and the data in the policies.
 
-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.
+**Example usage**
 
-```ts
-// scripts/policies.ts
-
-import { AbilityDSLParser } from './AbilityDSLParser';
+Policies can be stored in DSL or JSON. This example uses a DSL file.
 
-const dsl = `
+_policies/policies.dsl_
+```
 # @name Update order
 permit permission.order.update if all:
 
@@ -534,25 +717,46 @@ permit permission.order.update if all:
   all of:
     # @name User is owner
     user.id = order.ownerId
-`;
+```
+
+_scripts/policies.js_
+```js
+const fs = require('node:fs');
+const path = require('node:path');
+const { AbilityTypeGenerator, AbilityDSLParser } = require('@via-profit/ability');
+
+// Prepare paths
+const dslPath = path.resolve(__dirname, '../src/policies/policies.dsl');
+const typeDefsPath = path.join(path.dirname(dslPath), 'policies.types.ts');
 
+// Read DSL as a string
+const dsl = fs.readFileSync(dslPath, {encoding: 'utf-8'});
+
+// Create policies
 const policies = new AbilityDSLParser(dsl).parse();
 
-export default policies;
+// Generate TypeScript types
+const typeDefs = new AbilityTypeGenerator(policies).generateTypeDefs();
+
+// Save TypeScript types to file
+fs.writeFileSync(typeDefsPath, typeDefs, {encoding: 'utf-8'});
 ```
 
+_policies/index.ts_
 ```ts
-// scripts/generate-types.ts
-import { writeFileSync } from 'node:fs';
-import { AbilityParser } from '@via-profit/ability';
-import policies from './policies.json';
+import { AbilityDSLParser, AbilityResolver } from '@via-profit/ability';
+import type { Resources } from './policies.types';
+import dsl from './policies.dsl';
+
+const policies = new AbilityDSLParser<Resources>(dsl).parse();
 
-const typedefs = AbilityParser.generateTypeDefs(policies);
+export const policyResolver = new AbilityResolver(new AbilityDSLParser<Resources>(dsl).parse());
+
+export default policyResolver;
 
-writeFileSync('./src/ability/types.generated.ts', typedefs, 'utf8');
 ```
 
-**Generated File (example)**
+**Generated file (example)**
 
 ```ts
 // src/ability/types.generated.ts
@@ -574,12 +778,7 @@ export type Resources = {
 **Usage in code**
 
 ```ts
-import { AbilityResolver, AbilityPolicy } from '@via-profit/ability';
-import type { Resources } from './ability/types.generated';
-
-const resolver = new AbilityResolver<Resources>(
-  AbilityPolicy.parseAll(policies),
-);
+import { policyResolver } from './policies';
 
 await resolver.enforce('order.update', {
   user: { id: 'u1' },
@@ -1144,4 +1343,4 @@ Throughput (ops/s)
 
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See the [LICENSE](/LICENSE) file for details.

package/dist/core/AbilityPolicy.d.ts

@@ -3,7 +3,7 @@ import AbilityMatch from './AbilityMatch';
 import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
 import AbilityPolicyEffect, { AbilityPolicyEffectCodeType } from './AbilityPolicyEffect';
 import { AbilityExplain } from './AbilityExplain';
-import { ResourceObject } from './AbilityParser';
+import { ResourceObject } from './AbilityTypeGenerator';
 export type AbilityPolicyConfig = {
     readonly permission: string;
     readonly effect: AbilityPolicyEffectCodeType;
@@ -67,18 +67,13 @@ export declare class AbilityPolicy<Resource extends ResourceObject = Record<stri
      */
     check(resource: Resource, environment?: Environment): Promise<AbilityMatch>;
     explain(): AbilityExplain;
-    /**
-     * Parses an array of policy configurations into an array of AbilityPolicy instances.
-     * @param configs - Array of policy configurations
-     * @returns Array of AbilityPolicy instances
-     */
-    static fromJSONAll<Resource extends ResourceObject, Environment = unknown>(configs: readonly AbilityPolicyConfig[]): AbilityPolicy<Resource, Environment>[];
-    /**
-     * Parse the config JSON format to Policy class instance
-     */
-    static fromJSON<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(config: AbilityPolicyConfig): AbilityPolicy<Resource, Environment>;
-    static fromDSL<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(dsl: string): AbilityPolicy<Resource, Environment>;
-    toJSON(): AbilityPolicyConfig;
-    toString(): string;
+    copyWith(props: Partial<{
+        id: string;
+        name: string;
+        permission: string;
+        effect: AbilityPolicyEffect;
+        compareMethod: AbilityCompare;
+        ruleSet: AbilityRuleSet<Resource, Environment>[];
+    }>): AbilityPolicy<Resource, Environment>;
 }
 export default AbilityPolicy;

package/dist/core/AbilityResolver.d.ts

@@ -1,6 +1,6 @@
 import AbilityPolicy from './AbilityPolicy';
 import { AbilityResult } from './AbilityResult';
-import { ResourcesMap } from './AbilityParser';
+import { ResourcesMap } from './AbilityTypeGenerator';
 import { AbilityCacheAdapter } from '../cache/AbilityCacheAdapter';
 export type AbilityResolverOptions = {
     readonly cache?: AbilityCacheAdapter | null;

package/dist/core/AbilityResult.d.ts

@@ -1,5 +1,5 @@
 import { AbilityExplain } from './AbilityExplain';
-import { ResourceObject } from './AbilityParser';
+import { ResourceObject } from './AbilityTypeGenerator';
 import AbilityPolicy from './AbilityPolicy';
 import AbilityPolicyEffect from './AbilityPolicyEffect';
 export declare class AbilityResult<Resource extends ResourceObject = Record<string, unknown>> {

package/dist/core/AbilityRule.d.ts

@@ -61,7 +61,13 @@ export declare class AbilityRule<Resources extends object = object, Environment
      */
     getDotNotationValue<T = unknown>(resource: unknown, desc: string): T | undefined;
     toString(): string;
-    static fromJSON<Resources extends object, Environment = unknown>(config: AbilityRuleConfig): AbilityRule<Resources, Environment>;
+    copyWith(props: Partial<{
+        id: string | null;
+        name: string | null;
+        subject: string;
+        resource: AbilityRuleConfig['resource'];
+        condition: AbilityCondition;
+    }>): AbilityRule<Resources, Environment>;
     static equals<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
     static notEquals<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
     static contains<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;

package/dist/core/AbilityRuleSet.d.ts

@@ -1,7 +1,7 @@
 import AbilityRule, { AbilityRuleConfig } from './AbilityRule';
 import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
 import AbilityMatch from './AbilityMatch';
-import { ResourceObject } from './AbilityParser';
+import { ResourceObject } from './AbilityTypeGenerator';
 export type AbilityRuleSetConfig = {
     readonly id?: string | null;
     readonly name?: string | null;
@@ -39,10 +39,12 @@ export declare class AbilityRuleSet<Resources extends ResourceObject = Record<st
     addRules(rules: AbilityRule<Resources, Environment>[]): this;
     check(resources: Resources | null, environment?: Environment): Promise<AbilityMatch>;
     toString(): string;
-    /**
-     * Parse the config JSON format to Group class instance
-     */
-    static fromJSON<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(config: AbilityRuleSetConfig): AbilityRuleSet<Resource, Environment>;
+    copyWith(props: Partial<{
+        id: string | null;
+        name: string | null;
+        compareMethod: AbilityCompare;
+        rules: AbilityRule<Resources, Environment>[];
+    }>): AbilityRuleSet<Resources, Environment>;
     static and(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, unknown>;
     static or(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, unknown>;
 }

package/dist/core/AbilityTypeGenerator.d.ts

@@ -0,0 +1,55 @@
+import AbilityPolicy from './AbilityPolicy';
+export type Primitive = string | number | boolean | null | undefined;
+export type NestedDict<T = Primitive> = {
+    [key: string]: NestedDict<T> | T;
+};
+export type ResourceObject = Record<string, unknown>;
+export type ResourcesMap = Record<string, ResourceObject>;
+export declare class AbilityTypeGenerator {
+    readonly policies: readonly AbilityPolicy[];
+    constructor(policies: readonly AbilityPolicy[]);
+    /**
+     * Generates TypeScript type definitions based on the provided policies.
+     * @returns A generated type definitions.
+     */
+    generateTypeDefs(): string;
+    /**
+     * Determines TypeScript type based on the rule
+     * @param rule - The rule to analyze
+     * @returns TypeScript type as string
+     */
+    private determineTypeFromRule;
+    /**
+     * Gets TypeScript type for array values
+     * @param resource - The resource value to analyze
+     * @returns TypeScript array type as string
+     */
+    private getArrayType;
+    /**
+     * Gets primitive TypeScript type for a value
+     * @param value - The value to analyze
+     * @returns TypeScript primitive type as string
+     */
+    private getPrimitiveType;
+    /**
+     * Builds nested structure from flat paths
+     * Example: 'user.profile.name' -> { user: { profile: { name: 'string' } } }
+     * @param flatStructure - Flat structure with dot notation paths
+     * @returns Nested object structure
+     */
+    private buildNestedStructure;
+    /**
+     * Formats type structure into a string
+     * @param structure - Nested type structure
+     * @returns Formatted TypeScript type definition string
+     */
+    private formatTypeDefinitions;
+    /**
+     * Recursively formats nested object
+     * @param obj - Object to format
+     * @param indent - Current indentation level
+     * @returns Formatted string
+     */
+    private formatNestedObject;
+}
+export default AbilityTypeGenerator;

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export * from './core/AbilityCompare';
 export * from './core/AbilityCondition';
 export * from './core/AbilityError';
 export * from './core/AbilityMatch';
-export * from './core/AbilityParser';
+export * from './core/AbilityTypeGenerator';
 export * from './core/AbilityPolicy';
 export * from './core/AbilityPolicyEffect';
 export * from './core/AbilityResolver';