src/index.ts - gitverse - tm-project/rbac-react-system

src/index.ts
222 строки10 KB
Artem
chore: release v1.0.4
30 ноя 2025, 22:51
30 ноя 2025, 22:51f6f509c
/**
 * rbac-react-system v1.0.4
 * Copyright (c) 2025 TM Project
 * Licensed under the MIT License
 */

/**
 * rbac-react-system
 * Система управления доступом на основе ролей (RBAC) для React с архитектурой "чистой архитектуры".
 * Предоставляет готовые к использованию компоненты, хуки и сервисы для реализации сложной системы прав доступа в React-приложениях.
 *
 * @packageDocumentation
 */

// ==================== Presentation Layer ====================
// Контекст и провайдер

/**
 * Провайдер контекста RBAC, который оборачивает приложение и предоставляет доступ к данным авторизации.
 * Должен использоваться на верхнем уровне дерева компонентов.
 * @see RbacConfig — конфигурация провайдера.
 * @see RbacContextValue — значения, доступные через контекст.
 */
export { RbacProvider, useRbacContext } from './presentation/context'

/**
 * Интерфейс конфигурации провайдера RBAC.
 * Определяет зависимости (репозитории) и начальный идентификатор пользователя.
 */
export type { RbacConfig, RbacContextValue, RbacProviderProps } from './presentation/context'

// Хуки

/**
 * Хук для получения полного контекста RBAC.
 * Возвращает данные пользователя, методы проверки прав и состояние загрузки.
 * @returns {RbacContextValue} Объект с данными авторизации.
 */
export { useRbac } from './presentation/hooks'

/**
 * Хук для проверки наличия у пользователя прямого разрешения.
 * @param {string} permission - Строка разрешения в формате "ресурс:действие" (например, "users:read").
 * @returns {boolean} `true`, если разрешение есть, иначе — `false`.
 */
export { usePermission } from './presentation/hooks'

/**
 * Хук для асинхронной проверки доступа к ресурсу с определённым действием.
 * Учитывает роли, разрешения и контекстные условия.
 * @param {string} resource - Название ресурса (например, "posts").
 * @param {string} action - Действие (например, "delete").
 * @returns {boolean} `true`, если доступ разрешён, иначе — `false`.
 */
export { useAccess } from './presentation/hooks'

/**
 * Хук для проверки, имеет ли пользователь указанную роль.
 * @param {string} role - Идентификатор или название роли.
 * @returns {boolean} `true`, если роль есть, иначе — `false`.
 */
export { useRole } from './presentation/hooks'

// Высокоуровневые компоненты (HOC)

/**
 * Обёртка компонента, которая отображает его только при наличии указанного разрешения.
 * @param {WithPermissionOptions} options - Настройки: ресурс, действие, fallback-компонент.
 * @returns {React.ComponentType} Компонент, защищённый по разрешению.
 */
export { withPermission } from './presentation/hoc'
export type { WithPermissionOptions } from './presentation/hoc'

/**
 * Обёртка компонента, которая отображает его только при наличии указанной роли.
 * @param {WithRoleOptions} options - Настройки: роль, fallback-компонент.
 * @returns {React.ComponentType} Компонент, защищённый по роли.
 */
export { withRole } from './presentation/hoc'
export type { WithRoleOptions } from './presentation/hoc'

// Компоненты

/**
 * Компонент, который отображает дочерние элементы только при наличии определённого доступа.
 * Альтернатива HOC, удобна для использования в JSX.
 * @example
 * <Protected resource="users" action="read">
 *   <UserProfile />
 * </Protected>
 */
export { Protected } from './presentation/components'
export type { ProtectedProps } from './presentation/components'

// ==================== Domain Layer ====================
// Сущности

/**
 * Представляет пользователя в системе RBAC.
 * Содержит роли, прямые разрешения, атрибуты и метаданные.
 */
export type { User } from './domain/entities'

/**
 * Представляет роль, группирующую разрешения.
 * Поддерживает наследование от других ролей.
 */
export type { Role } from './domain/entities'

/**
 * Представляет разрешение на выполнение действия над ресурсом.
 * Может включать контекстные условия.
 */
export type { Permission } from './domain/entities'

/**
 * Определяет условие, которое должно быть выполнено для активации разрешения.
 * Например: время суток, атрибуты пользователя и т.д.
 */
export type { Condition } from './domain/entities'

// Интерфейсы

/**
 * Интерфейс для работы с данными пользователей.
 * Определяет методы для поиска, получения ролей и обновления пользователя.
 */
export type { IUserRepository } from './domain/interfaces'

/**
 * Интерфейс для работы с данными разрешений.
 * Определяет методы для получения разрешений по пользователям и ролям.
 */
export type { IPermissionRepository } from './domain/interfaces'

/**
 * Интерфейс для работы с данными ролей.
 * Поддерживает получение ролей по пользователю и наследованию.
 */
export type { IRoleRepository } from './domain/interfaces'

/**
 * Интерфейс сервиса авторизации.
 * Определяет основные операции проверки доступа, ролей и разрешений.
 */
export type { IAuthorizationService } from './domain/interfaces'

// Исключения

/**
 * Базовый класс для всех исключений в системе RBAC.
 */
export { RbacException } from './domain/exceptions'

/**
 * Исключение, выбрасываемое при попытке доступа к несуществующему пользователю.
 */
export { UserNotFoundException } from './domain/exceptions'

/**
 * Исключение, выбрасываемое при явном отказе в доступе к ресурсу.
 */
export { PermissionDeniedException } from './domain/exceptions'

/**
 * Исключение, выбрасываемое при обнаружении некорректной конфигурации системы.
 */
export { InvalidConfigurationException } from './domain/exceptions'

/**
 * Исключение, выбрасываемое при попытке доступа к несуществующей роли.
 */
export { RoleNotFoundException } from './domain/exceptions'

/**
 * Исключение, выбрасываемое при обнаружении циклического наследования ролей.
 */
export { CircularRoleInheritanceException } from './domain/exceptions'

// ==================== Application Layer ====================
// Сервисы

/**
 * Основной сервис авторизации.
 * Оркестрирует use case'ы для проверки доступа, ролей и разрешений.
 */
export { AuthorizationService } from './application/services'

// Use Cases

/**
 * Use case для проверки, имеет ли пользователь доступ к ресурсу с определённым действием.
 * Учитывает прямые разрешения, роли и контекстные условия.
 */
export { CheckPermissionUseCase } from './application/use-cases'

/**
 * Use case для проверки, имеет ли пользователь указанную роль.
 * Поддерживает иерархию ролей и обнаруживает циклы.
 */
export { CheckRoleUseCase } from './application/use-cases'

// ==================== Infrastructure Layer ====================
// Мок-репозитории (для тестирования и примеров)

/**
 * Мок-репозиторий пользователей.
 * Хранит данные в памяти, используется для тестов и демонстрации.
 */
export { MockUserRepository } from './infrastructure/repositories'

/**
 * Мок-репозиторий разрешений.
 * Имитирует хранилище разрешений в памяти.
 */
export { MockPermissionRepository } from './infrastructure/repositories'

/**
 * Мок-репозиторий ролей.
 * Поддерживает иерархию ролей и назначение их пользователям.
 */
export { MockRoleRepository } from './infrastructure/repositories'