@foxford/den 1.0.0

package/index.d.cts

@@ -0,0 +1,386 @@
+import { C as Core, a as ContainerManager, R as RequestContext, G as GuardRunner, b as Guard, c as GuardResult, N as NavigationManager, d as NavigationEntry, e as NavigationInterceptor, D as Disposable, L as LeaveGuardResult, S as StateSerializer } from './types-B4Arep3V.cjs';
+export { A as Activatable, f as ActivatableToken, g as ContainerManagerToken, h as GuardRunnerToken, i as NavigationManagerToken, j as RequestContextToken, k as SlotEntry, l as SlotRegistry, m as SlotRegistryToken, n as StateCache, o as StateParticipant, p as StateRegistry, q as StateRegistryToken, r as StateSerializerToken } from './types-B4Arep3V.cjs';
+import { Container, Token } from '@foxford/ioc';
+import { DefinitionResolver } from './adapter.cjs';
+import { D as DefineGuardOptions, G as GuardDefinition, A as AppConfig, a as DefineAppOptions, b as AppDefinition, E as ExtensionConfig, c as DefineExtensionOptions, d as ExtensionDefinition, e as ActionGuard, f as DefineActionGuardOptions, g as ActionGuardDefinition, L as LayoutConfig, h as DefineLayoutOptions, i as LayoutDefinition, j as LayerConfig, k as DefineLayerOptions, l as LayerDefinition } from './define-slot-es1K6_-L.cjs';
+export { m as DefineRepositoryOptions, n as DefineServiceOptions, o as DefineSlotOptions, p as DefineViewModelOptions, q as Definition, R as RepositoryDefinition, S as ServiceDefinition, r as SlotDefinition, V as ViewModelDefinition, s as defineRepository, t as defineService, u as defineSlot, v as defineViewModel } from './define-slot-es1K6_-L.cjs';
+
+/**
+ * Опции для создания Core Runtime.
+ */
+interface CreateCoreOptions {
+    /**
+     * Внешний app-контейнер (опционально).
+     * Если не передан, создаётся новый Container.
+     */
+    container?: Container;
+}
+/**
+ * Создаёт экземпляр Core Runtime.
+ * Инициализирует app-контейнер, все менеджеры и регистрирует их в IoC.
+ * @param options - Опции создания
+ * @returns Объект Core со всеми менеджерами
+ *
+ * @example
+ * const core = createCore()
+ * core.navigationManager.recordNavigation(null, '/home', {})
+ * const pageContainer = core.containerManager.createPageContainer('/home')
+ */
+declare function createCore(options?: CreateCoreOptions): Core;
+
+/**
+ * Реализация ContainerManager.
+ * Управляет иерархией контейнеров: одним app-контейнером, дочерними контейнерами страниц
+ * и per-request контейнерами для SSR.
+ */
+declare class ContainerManagerImpl implements ContainerManager {
+    /** App-контейнер (корневой синглтон) */
+    private readonly appContainer;
+    /** Map дочерних контейнеров страниц: routeId → Container */
+    private readonly pageContainers;
+    /** Map контейнеров запросов: requestId → Container */
+    private readonly requestContainers;
+    /** Map SSR page контейнеров: requestId → Container (child от request container) */
+    private readonly ssrPageContainers;
+    /**
+     * @param appContainer - Корневой app-контейнер
+     */
+    constructor(appContainer: Container);
+    /**
+     * Возвращает app-контейнер (синглтон).
+     */
+    getAppContainer(): Container;
+    /**
+     * Возвращает существующий дочерний контейнер страницы или undefined.
+     * @param routeId - Идентификатор маршрута
+     */
+    getPageContainer(routeId: string): Container | undefined;
+    /**
+     * Создаёт дочерний контейнер для страницы.
+     * Если контейнер для данного routeId уже существует, возвращает существующий.
+     * @param routeId - Идентификатор маршрута
+     */
+    createPageContainer(routeId: string): Container;
+    /**
+     * Уничтожает дочерний контейнер страницы и освобождает его ресурсы.
+     * Если контейнер не найден — no-op.
+     * @param routeId - Идентификатор маршрута
+     */
+    destroyPageContainer(routeId: string): Promise<void>;
+    /**
+     * Создаёт дочерний контейнер для HTTP-запроса с забинженным RequestContext.
+     * Если контейнер для данного requestId уже существует, возвращает существующий.
+     * @param requestId - Уникальный идентификатор запроса
+     * @param context - Контекст запроса (заголовки и cookies)
+     */
+    createRequestContainer(requestId: string, context: RequestContext): Container;
+    /**
+     * Возвращает существующий контейнер запроса или undefined.
+     * @param requestId - Уникальный идентификатор запроса
+     */
+    getRequestContainer(requestId: string): Container | undefined;
+    /**
+     * Уничтожает контейнер запроса и освобождает ресурсы.
+     * Если контейнер не найден — no-op.
+     * @param requestId - Уникальный идентификатор запроса
+     */
+    destroyRequestContainer(requestId: string): Promise<void>;
+    /**
+     * Создаёт page container для SSR как дочерний от заданного родителя.
+     * Отслеживается менеджером — может быть уничтожен через destroySsrPageContainer.
+     * Если контейнер для данного requestId уже существует, возвращает существующий.
+     * @param requestId - Уникальный идентификатор запроса
+     * @param parent - Родительский контейнер (обычно request container)
+     */
+    createSsrPageContainer(requestId: string, parent: Container): Container;
+    /**
+     * Уничтожает SSR page container и освобождает ресурсы (Disposable VM, сервисы).
+     * Вызывается в onAfterRenderHtml после завершения SSR-рендера.
+     * Если контейнер не найден — no-op.
+     * @param requestId - Уникальный идентификатор запроса
+     */
+    destroySsrPageContainer(requestId: string): Promise<void>;
+}
+
+/**
+ * Реализация GuardRunner.
+ * Параллельно выполняет guards из app-контейнера и возвращает их результаты.
+ */
+declare class GuardRunnerImpl implements GuardRunner {
+    /** App-контейнер для резолвинга guards */
+    private readonly container;
+    /**
+     * @param container - App-контейнер, из которого резолвятся guards
+     */
+    constructor(container: Container);
+    /**
+     * Параллельно выполняет все guards и возвращает их результаты.
+     * Если передан container — guards резолвятся из него (например, request-scope container).
+     * Без container — guards резолвятся из app-контейнера.
+     * @param tokens - Токены guards
+     * @param params - Параметры маршрута
+     * @param container - Опциональный контейнер для резолвинга guards
+     */
+    runGuards(tokens: Token<Guard>[], params: Record<string, string>, container?: Container): Promise<GuardResult[]>;
+}
+
+/**
+ * Реализация NavigationManager.
+ * Хранит историю переходов, оповещает подписчиков, управляет leave guards
+ * и инициализирует браузерные listeners.
+ */
+declare class NavigationManagerImpl implements NavigationManager {
+    /** Стек истории навигации */
+    private readonly _history;
+    /** Текущая запись навигации */
+    current: NavigationEntry | null;
+    /** Список обработчиков навигации */
+    private readonly handlers;
+    /** Список зарегистрированных interceptors (leave guards) */
+    private readonly interceptors;
+    /** Функция очистки popstate listener (только на клиенте) */
+    private removePopstateListener;
+    /** Функция очистки beforeunload listener (только на клиенте) */
+    private removeBeforeunloadListener;
+    /** Функция очистки click listener (только на клиенте) */
+    private removeClickListener;
+    /**
+     * История переходов (только для чтения снаружи).
+     */
+    get history(): NavigationEntry[];
+    /**
+     * Подписывается на событие навигации.
+     * @param handler - Обработчик события
+     * @returns Функция отписки
+     */
+    onNavigate(handler: (entry: NavigationEntry) => void): () => void;
+    /**
+     * Записывает переход в историю и оповещает подписчиков.
+     * @param from - Маршрут отправления (null — начало сессии)
+     * @param to - Маршрут назначения
+     * @param params - Параметры маршрута
+     */
+    recordNavigation(from: string | null, to: string, params: Record<string, string>): void;
+    /**
+     * Проверяет актуальность текущего состояния.
+     * Состояние считается актуальным если история и текущий элемент согласованы.
+     */
+    checkFreshness(): Promise<boolean>;
+    /**
+     * Регистрирует interceptor для перехвата навигации (leave guard).
+     * @param handler - Перехватчик навигации
+     * @returns Disposable для отмены регистрации
+     */
+    intercept(handler: NavigationInterceptor): Disposable;
+    /**
+     * Запускает все зарегистрированные leave guards последовательно.
+     * При первом заблокированном возвращает `{ allow: false, reason? }`.
+     * @param from - Маршрут отправления
+     * @param to - Маршрут назначения
+     * @returns Результат проверки
+     */
+    runLeaveGuards(from: string | null, to: string): Promise<LeaveGuardResult>;
+    /**
+     * Инициализирует обработчики браузерных событий навигации.
+     * Обрабатывает: popstate (с rollback при blocked), beforeunload,
+     * делегирование кликов по <a>-элементам.
+     * SSR-safe: все browser API за проверкой typeof window.
+     * Вызывать только на клиенте.
+     */
+    initClientListeners(): void;
+}
+
+/**
+ * Реализация StateSerializer.
+ * Не хранит состояние — читает участников из StateRegistry конкретного контейнера.
+ * Протокол: plain objects.
+ */
+declare class StateSerializerImpl implements StateSerializer {
+    /**
+     * Достаёт StateRegistry из контейнера, если он там забинжен.
+     * Реестр биндится как toValue (Singleton), поэтому resolve синхронен; на всякий
+     * случай отсекаем Promise-ветку, чтобы контракт serialize/hydrate оставался синхронным.
+     *
+     * Не использует this: сериализатор stateless (состояние живёт в контейнере), но
+     * остаётся классом ради биндинга по StateSerializerToken в IoC.
+     * @param container - Контейнер, из которого берётся реестр
+     */
+    private getRegistry;
+    /**
+     * Сериализует состояние участников контейнера в plain object.
+     * Включает только тех, кто объявил serialize (участник имеет toJSON).
+     * @param container - Контейнер, из реестра которого извлекаются данные
+     */
+    serialize(container: Container): Record<string, unknown>;
+    /**
+     * Восстанавливает состояние участников контейнера из plain object.
+     * Вызывает fromJSON только у тех, чей ключ присутствует в state и кто объявил deserialize.
+     * @param container - Целевой контейнер
+     * @param state - Сериализованное состояние
+     */
+    hydrate(container: Container, state: Record<string, unknown>): void;
+    /**
+     * Вызывает activate(params) на всех участниках реестра контейнера параллельно.
+     * @param container - Контейнер, участники которого активируются
+     * @param params - Параметры маршрута
+     */
+    activateAll(container: Container, params: Record<string, string>): Promise<void>;
+}
+
+/**
+ * Дефолтная стратегия резолва `define*` — async/global (режим Vike).
+ *
+ * Это «дефолтный резолвер-адаптер»: `den` ставит его сайд-эффектом при загрузке
+ * (см. `index.ts`), поэтому Vike-консьюмеры получают рабочий `.use()` без явной
+ * инициализации. Next-адаптер переопределяет стратегию через `installResolver()`.
+ *
+ * Резолвит из глобального IoC-контейнера с подъёмом по parent-chain
+ * (page-container → app-container). Если токен не найден нигде (page-scope VM
+ * при навигации до создания нового контейнера) — возвращает pending `Promise`,
+ * и view рендерит `null`, пока контейнер не появится.
+ */
+declare const defaultGlobalResolver: DefinitionResolver;
+
+/**
+ * Определяет Guard с IoC-биндингом.
+ * Поддерживает два режима:
+ * - С create + requires: создаёт Guard-класс с инъецированными зависимостями (IoC-паттерн).
+ * - Только check: регистрирует инлайн Guard как value (без зависимостей).
+ *
+ * @template Deps - Кортеж токенов зависимостей (по умолчанию пустой)
+ * @param token - Токен для регистрации Guard в IoC
+ * @param options - Опции: requires, create, check
+ * @returns GuardDefinition с методом register(container)
+ *
+ * @example
+ * // С инъекцией зависимостей через класс
+ * const authGuard = defineGuard(AuthGuardToken, {
+ *   requires: [AuthServiceToken] as const,
+ *   create: ([authService]) => new AuthGuard(authService),
+ * })
+ * authGuard.register(appContainer)
+ *
+ * @example
+ * // Инлайн-реализация без зависимостей
+ * const devGuard = defineGuard(DevGuardToken, {
+ *   check: (_params) => ({ allowed: process.env.NODE_ENV !== 'production' }),
+ * })
+ * devGuard.register(appContainer)
+ */
+declare function defineGuard<Deps extends readonly Token<unknown>[] = readonly []>(token: Token<Guard>, options: DefineGuardOptions<Deps>): GuardDefinition;
+
+/**
+ * Определяет конфигурацию приложения с декларативным списком сервисов и guards.
+ * Заменяет ручной вызов setupContainer() — декларирует, какие сервисы запускаются
+ * при старте (eager), какие — лениво (lazy), и какие guards применяются глобально.
+ * Регистрирует AppConfig-значение в IoC-контейнере.
+ *
+ * @param token - Токен для регистрации AppConfig в IoC
+ * @param options - Опции: eager, lazy, guards
+ * @returns AppDefinition с методом register(container)
+ *
+ * @example
+ * // app/app.ts
+ * export const app = defineApp(AppToken, {
+ *   eager: [AuthServiceToken, NotificationServiceToken],
+ *   lazy: [CartServiceToken],
+ *   guards: [GlobalAuthGuardToken],
+ * })
+ * app.register(appContainer)
+ */
+declare function defineApp(token: Token<AppConfig>, options?: DefineAppOptions): AppDefinition;
+
+/**
+ * Определяет app-scope расширение с lifecycle-хуками activate/deactivate.
+ * Extension — модуль с собственным lifecycle, живущий в скоупе приложения
+ * (модалки, онбординг, системы очередей, cookie consent и т.д.).
+ * Регистрирует Activatable-обёртку в IoC-контейнере.
+ *
+ * @template Deps - Кортеж токенов зависимостей (по умолчанию пустой кортеж)
+ * @param token - Токен для регистрации ExtensionConfig в IoC
+ * @param options - Опции: requires, activate, deactivate
+ * @returns ExtensionDefinition с методом register(container)
+ *
+ * @example
+ * // extensions/onboarding/extension.ts
+ * export const onboardingExtension = defineExtension(OnboardingExtensionToken, {
+ *   requires: [OnboardingServiceToken] as const,
+ *   activate: ([service]) => service.checkAndStart(),
+ *   deactivate: ([service]) => service.reset(),
+ * })
+ * onboardingExtension.register(appContainer)
+ */
+declare function defineExtension<Deps extends readonly Token<unknown>[] = readonly []>(token: Token<ExtensionConfig>, options?: DefineExtensionOptions<Deps>): ExtensionDefinition<Deps>;
+
+/**
+ * Определяет перехватчик вызова метода Service с IoC-биндингом.
+ * Используется для вставки проверки перед выполнением операции:
+ * 2FA, подтверждение действия, rate-limiting и т.д.
+ * Резолвит зависимости через IoC и регистрирует ActionGuard как Singleton.
+ *
+ * @template Deps - Кортеж токенов зависимостей (по умолчанию пустой кортеж)
+ * @param token - Токен для регистрации ActionGuard в IoC
+ * @param options - Опции: requires, intercept
+ * @returns ActionGuardDefinition с методом register(container)
+ *
+ * @example
+ * // domains/auth/2fa.action-guard.ts
+ * export const twoFaGuard = defineActionGuard(TwoFaGuardToken, {
+ *   requires: [TwoFaServiceToken] as const,
+ *   intercept: async ([twoFaService], next) => {
+ *     await twoFaService.verify()
+ *     return next()
+ *   },
+ * })
+ * twoFaGuard.register(appContainer)
+ *
+ * // Использование в сервисе:
+ * const paymentService = defineService(PaymentToken, {
+ *   requires: [TwoFaGuardToken] as const,
+ *   create: ([twoFaGuard]) => ({
+ *     processPayment: () => twoFaGuard.intercept(() => doPayment()),
+ *   }),
+ * })
+ */
+declare function defineActionGuard<Deps extends readonly Token<unknown>[] = readonly []>(token: Token<ActionGuard>, options: DefineActionGuardOptions<Deps>): ActionGuardDefinition<Deps>;
+
+/**
+ * Определяет layout с декларативной привязкой ViewModel и slots.
+ * Регистрирует LayoutConfig-значение в IoC-контейнере.
+ * Layout является персистентной оболочкой приложения (header, sidebar, footer),
+ * которая не пересоздаётся при навигации между страницами.
+ *
+ * @param token - Токен для регистрации LayoutConfig в IoC
+ * @param options - Опции: viewModels, slots
+ * @returns LayoutDefinition с методом register(container)
+ *
+ * @example
+ * // layouts/default/layout.ts
+ * export const defaultLayout = defineLayout(DefaultLayoutToken, {
+ *   viewModels: [HeaderVmToken, FooterVmToken],
+ *   slots: { sidebar: SidebarToken },
+ * })
+ * defaultLayout.register(appContainer)
+ */
+declare function defineLayout(token: Token<LayoutConfig>, options?: DefineLayoutOptions): LayoutDefinition;
+
+/**
+ * Определяет конфигурационный слой view-фреймворка.
+ * Позволяет сменить view-адаптер (React, Vue, Qwik) без изменения бизнес-логики.
+ * Регистрирует LayerConfig-значение в IoC-контейнере.
+ *
+ * @param token - Токен для регистрации LayerConfig в IoC
+ * @param options - Опции: name (имя слоя), adapter (адаптер фреймворка)
+ * @returns LayerDefinition с методом register(container)
+ *
+ * @example
+ * // app/layers/view.layer.ts
+ * export const viewLayer = defineLayer(ViewLayerToken, {
+ *   name: 'view',
+ *   adapter: reactAdapter(),
+ * })
+ * viewLayer.register(appContainer)
+ */
+declare function defineLayer(token: Token<LayerConfig>, options: DefineLayerOptions): LayerDefinition;
+
+export { ActionGuard, ActionGuardDefinition, AppConfig, AppDefinition, ContainerManager, ContainerManagerImpl, Core, type CreateCoreOptions, DefineActionGuardOptions, DefineAppOptions, DefineExtensionOptions, DefineGuardOptions, DefineLayerOptions, DefineLayoutOptions, Disposable, ExtensionConfig, ExtensionDefinition, Guard, GuardDefinition, GuardResult, GuardRunner, GuardRunnerImpl, LayerConfig, LayerDefinition, LayoutConfig, LayoutDefinition, LeaveGuardResult, NavigationEntry, NavigationInterceptor, NavigationManager, NavigationManagerImpl, RequestContext, StateSerializer, StateSerializerImpl, createCore, defaultGlobalResolver, defineActionGuard, defineApp, defineExtension, defineGuard, defineLayer, defineLayout };