@foxford/den 1.0.0

package/types-B4Arep3V.d.ts

@@ -0,0 +1,415 @@
+import { Token, Container } from '@foxford/ioc';
+
+/**
+ * Интерфейс для объектов с жизненным циклом страницы.
+ * Реализуется сервисами и ViewModel, чтобы Core мог управлять их lifecycle.
+ */
+interface Activatable {
+    /**
+     * Вызывается при активации страницы (SSR и клиент).
+     * @param params - Параметры маршрута (например, { id: '42' })
+     */
+    activate(params: Record<string, string>): void | Promise<void>;
+    /**
+     * Вызывается только на клиенте после hydration (опционально).
+     * @param params - Параметры маршрута
+     */
+    activateClient?(params: Record<string, string>): void | Promise<void>;
+    /**
+     * Вызывается при уходе со страницы (опционально).
+     */
+    deactivate?(): void | Promise<void>;
+}
+
+/**
+ * Запись слота в реестре: имя + непрозрачная ссылка на view.
+ *
+ * `view` намеренно `unknown` — ядро не знает, что это компонент React/Vue/…: рендерит
+ * его view-адаптер (например `Slot` из `@foxford/den-react`). Так слот host-агностичен.
+ */
+interface SlotEntry {
+    /** Имя слота — по нему оркестратор решает, чем его заполнить. */
+    name: string;
+    /** Непрозрачная ссылка на view слота (компонент view-фреймворка). */
+    view: unknown;
+}
+/**
+ * Per-container реестр слотов.
+ *
+ * `defineSlot(...).register(container)` кладёт слот сюда; оркестратор (например
+ * федерация core-app) резолвит реестр из контейнера и перечисляет все зарегистрированные
+ * слоты — без сканирования исходников, чистый DI. Живёт столько же, сколько контейнер.
+ */
+declare class SlotRegistry {
+    /** Слоты по имени. Повторная регистрация с тем же именем перезаписывает. */
+    private readonly slots;
+    /**
+     * Регистрирует слот.
+     * @param entry - Запись слота (имя + непрозрачный view)
+     */
+    add(entry: SlotEntry): void;
+    /**
+     * Возвращает слот по имени.
+     * @param name - Имя слота
+     */
+    get(name: string): SlotEntry | undefined;
+    /**
+     * Возвращает все зарегистрированные слоты.
+     */
+    all(): readonly SlotEntry[];
+}
+
+/**
+ * Кэш сериализованных стейтов страниц.
+ * Используется для восстановления состояния при возврате на ранее посещённую страницу.
+ * Реализует LRU-стратегию с ограничением по количеству записей.
+ */
+declare class StateCache {
+    private cache;
+    private readonly maxSize;
+    /**
+     * @param maxSize - Максимальное количество кэшированных страниц (по умолчанию 10)
+     */
+    constructor(maxSize?: number);
+    /**
+     * Сохраняет сериализованный стейт страницы.
+     * @param routeId - Идентификатор маршрута
+     * @param state - Сериализованный стейт (результат toJSON() от VM)
+     */
+    set(routeId: string, state: Record<string, unknown>): void;
+    /**
+     * Возвращает закэшированный стейт страницы или undefined.
+     * @param routeId - Идентификатор маршрута
+     */
+    get(routeId: string): Record<string, unknown> | undefined;
+    /**
+     * Удаляет кэш для страницы.
+     * @param routeId - Идентификатор маршрута
+     */
+    delete(routeId: string): void;
+    /** Очищает весь кэш. */
+    clear(): void;
+}
+
+/**
+ * Участник сериализации состояния — сервис, объявивший serialize/deserialize.
+ * Методы замкнуты на разрешённые зависимости сервиса и на его экземпляр,
+ * поэтому сериализатору не нужно повторно резолвить токены.
+ */
+interface StateParticipant {
+    /** Возвращает сериализуемое состояние (если сервис объявил serialize). */
+    toJSON?(): unknown;
+    /** Восстанавливает состояние из данных (если сервис объявил deserialize). */
+    fromJSON?(data: unknown): void;
+    /** Активирует сервис при входе на страницу (lifecycle-хук activate). */
+    activate?(params: Record<string, string>): void | Promise<void>;
+}
+/**
+ * Реестр участников сериализации в рамках одного контейнера.
+ *
+ * Живёт ровно столько, сколько контейнер (page/request), в который он забинжен
+ * контейнер-менеджером. Уничтожается вместе с контейнером через dispose — поэтому
+ * ссылки на страничные сервисы не утекают в app-scope, в отличие от прежнего
+ * app-scope Map в StateSerializerImpl.
+ */
+declare class StateRegistry {
+    /** Участники: стабильный ключ (token.description) → участник. */
+    private readonly participants;
+    /**
+     * Регистрирует участника сериализации.
+     * Повторная регистрация с тем же ключом перезаписывает предыдущего.
+     * @param key - Стабильный ключ (обычно token.description)
+     * @param participant - Участник с хуками toJSON/fromJSON/activate
+     */
+    add(key: string, participant: StateParticipant): void;
+    /**
+     * Возвращает всех зарегистрированных участников (ключ → участник).
+     */
+    all(): ReadonlyMap<string, StateParticipant>;
+}
+
+/**
+ * Контекст HTTP-запроса — заголовки и cookies, переданные сервером.
+ * На клиенте содержит пустые объекты.
+ */
+interface RequestContext {
+    /** HTTP-заголовки запроса (в нижнем регистре) */
+    headers: Record<string, string>;
+    /** Распарсенные cookies из заголовка Cookie */
+    cookies: Record<string, string>;
+}
+/**
+ * Результат проверки guard.
+ * - `{ allowed: true }` — переход разрешён
+ * - `{ allowed: false, redirect: string }` — переход запрещён, перенаправить по redirect
+ */
+type GuardResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    redirect: string;
+};
+/**
+ * Guard — функция проверки доступа к странице.
+ * Вызывается до активации страницы.
+ */
+interface Guard {
+    /**
+     * Проверяет доступ к маршруту.
+     * @param params - Параметры маршрута
+     * @returns Результат проверки
+     */
+    check(params: Record<string, string>): GuardResult | Promise<GuardResult>;
+}
+/**
+ * Запись в истории навигации.
+ */
+interface NavigationEntry {
+    /** Маршрут, с которого произошёл переход */
+    from: string | null;
+    /** Маршрут, на который произошёл переход */
+    to: string;
+    /** Параметры маршрута назначения */
+    params: Record<string, string>;
+    /** Временная метка перехода (ms) */
+    timestamp: number;
+}
+/**
+ * Менеджер дочерних контейнеров для страниц и запросов.
+ */
+interface ContainerManager {
+    /**
+     * Возвращает app-контейнер (синглтон).
+     */
+    getAppContainer(): Container;
+    /**
+     * Возвращает существующий дочерний контейнер страницы или undefined.
+     * @param routeId - Идентификатор маршрута
+     */
+    getPageContainer(routeId: string): Container | undefined;
+    /**
+     * Создаёт дочерний контейнер для страницы.
+     * Если контейнер для данного routeId уже существует, возвращает его.
+     * @param routeId - Идентификатор маршрута
+     */
+    createPageContainer(routeId: string): Container;
+    /**
+     * Уничтожает дочерний контейнер страницы и освобождает ресурсы.
+     * @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 как дочерний от заданного родителя (обычно request container).
+     * Отслеживается менеджером — может быть уничтожен через destroySsrPageContainer после рендера.
+     * Если контейнер для данного requestId уже существует, возвращает существующий.
+     * @param requestId - Уникальный идентификатор запроса
+     * @param parent - Родительский контейнер
+     */
+    createSsrPageContainer(requestId: string, parent: Container): Container;
+    /**
+     * Уничтожает SSR page container и освобождает ресурсы (Disposable VM, сервисы).
+     * Вызывается в onAfterRenderHtml после завершения SSR-рендера.
+     * Если контейнер не найден — no-op.
+     * @param requestId - Уникальный идентификатор запроса
+     */
+    destroySsrPageContainer(requestId: string): Promise<void>;
+}
+/**
+ * Запускатель guards для страниц.
+ */
+interface GuardRunner {
+    /**
+     * Параллельно выполняет все guards и возвращает их результаты.
+     * Если передан container — guards резолвятся из него (request-scope).
+     * Без container — guards резолвятся из app-контейнера (поведение по умолчанию).
+     * @param tokens - Токены guards
+     * @param params - Параметры маршрута
+     * @param container - Опциональный контейнер для резолвинга guards (например, request container)
+     */
+    runGuards(tokens: Token<Guard>[], params: Record<string, string>, container?: Container): Promise<GuardResult[]>;
+}
+/**
+ * Объект, поддерживающий освобождение ресурсов.
+ * Возвращается методами регистрации для отмены подписки.
+ */
+interface Disposable {
+    /** Освобождает ресурсы и отменяет регистрацию. */
+    dispose(): void;
+}
+/**
+ * Перехватчик навигации — вызывается перед каждым переходом (leave guard).
+ */
+interface NavigationInterceptor {
+    /**
+     * Проверяет, разрешён ли переход.
+     * @param from - Текущий маршрут (откуда), null при первом переходе
+     * @param to - Целевой маршрут (куда)
+     * @returns Объект с результатом проверки
+     */
+    beforeNavigate(from: string | null, to: string): Promise<{
+        allow: boolean;
+        reason?: string;
+    }>;
+}
+/**
+ * Результат проверки leave guards.
+ * - `{ allow: true }` — переход разрешён
+ * - `{ allow: false, reason? }` — переход заблокирован
+ */
+type LeaveGuardResult = {
+    allow: true;
+} | {
+    allow: false;
+    reason?: string;
+};
+/**
+ * Менеджер навигации — хранит историю переходов и оповещает подписчиков.
+ */
+interface NavigationManager {
+    /** История переходов (не изменяется снаружи) */
+    readonly history: NavigationEntry[];
+    /** Текущая запись навигации */
+    current: NavigationEntry | null;
+    /**
+     * Подписывается на событие навигации.
+     * @param handler - Обработчик события
+     * @returns Функция отписки
+     */
+    onNavigate(handler: (entry: NavigationEntry) => void): () => void;
+    /**
+     * Записывает переход и оповещает подписчиков.
+     * @param from - Маршрут отправления
+     * @param to - Маршрут назначения
+     * @param params - Параметры маршрута
+     */
+    recordNavigation(from: string | null, to: string, params: Record<string, string>): void;
+    /**
+     * Проверяет актуальность текущего состояния (stub: всегда true).
+     */
+    checkFreshness(): Promise<boolean>;
+    /**
+     * Инициализирует обработчики браузерных событий навигации (только на клиенте).
+     */
+    initClientListeners(): void;
+    /**
+     * Регистрирует 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>;
+}
+/**
+ * Сериализатор состояния для SSR.
+ * Протокол: plain objects.
+ *
+ * Не хранит состояние сам — работает поверх StateRegistry конкретного контейнера
+ * (page/request). Участники сериализации регистрируются в реестр контейнера через
+ * defineService({ serialize, deserialize }) при создании экземпляра сервиса, поэтому
+ * их время жизни ограничено контейнером и утечки в app-scope не происходит.
+ */
+interface StateSerializer {
+    /**
+     * Сериализует состояние участников из StateRegistry контейнера в plain object.
+     * Ключ записи — token.description сервиса.
+     * @param container - Контейнер, из реестра которого извлекаются данные
+     */
+    serialize(container: Container): Record<string, unknown>;
+    /**
+     * Восстанавливает состояние участников из plain object в контейнер.
+     * Вызывает deserialize только у тех участников, чей ключ есть в state.
+     * @param container - Целевой контейнер
+     * @param state - Сериализованное состояние
+     */
+    hydrate(container: Container, state: Record<string, unknown>): void;
+    /**
+     * Вызывает activate(params) на всех участниках реестра контейнера параллельно.
+     * Используется в Vike-хуках для активации страничных сервисов при входе на страницу.
+     * @param container - Контейнер, участники которого активируются
+     * @param params - Параметры маршрута (например, { id: '42' })
+     */
+    activateAll(container: Container, params: Record<string, string>): Promise<void>;
+}
+/**
+ * Основной объект Core Runtime.
+ * Создаётся фабрикой createCore и предоставляет доступ ко всем менеджерам.
+ */
+interface Core {
+    /** App-контейнер (IoC) */
+    container: Container;
+    /** Менеджер контейнеров страниц */
+    containerManager: ContainerManager;
+    /** Запускатель guards */
+    guardRunner: GuardRunner;
+    /** Менеджер навигации */
+    navigationManager: NavigationManager;
+    /** Кэш стейтов страниц для state persistence при back-навигации */
+    stateCache: StateCache;
+    /** Сериализатор состояния */
+    stateSerializer: StateSerializer;
+}
+/**
+ * Токен для регистрации ContainerManager в IoC-контейнере.
+ */
+declare const ContainerManagerToken: Token<ContainerManager>;
+/**
+ * Токен для регистрации GuardRunner в IoC-контейнере.
+ */
+declare const GuardRunnerToken: Token<GuardRunner>;
+/**
+ * Токен для регистрации NavigationManager в IoC-контейнере.
+ */
+declare const NavigationManagerToken: Token<NavigationManager>;
+/**
+ * Токен для регистрации StateSerializer в IoC-контейнере.
+ */
+declare const StateSerializerToken: Token<StateSerializer>;
+/**
+ * Токен per-container реестра участников сериализации.
+ * Свежий StateRegistry биндится контейнер-менеджером в каждый page/request-контейнер
+ * и уничтожается вместе с ним.
+ */
+declare const StateRegistryToken: Token<StateRegistry>;
+/**
+ * Токен per-container реестра слотов.
+ * `defineSlot(...).register(container)` кладёт слот сюда (get-or-create), оркестратор
+ * резолвит реестр и перечисляет зарегистрированные слоты.
+ */
+declare const SlotRegistryToken: Token<SlotRegistry>;
+/**
+ * Токен для регистрации Activatable-объектов в контейнере.
+ */
+declare const ActivatableToken: Token<Activatable>;
+/**
+ * Токен для доступа к RequestContext из IoC-контейнера.
+ * На сервере содержит headers/cookies текущего HTTP-запроса.
+ * На клиенте — пустые объекты.
+ */
+declare const RequestContextToken: Token<RequestContext>;
+
+export { type Activatable as A, type Core as C, type Disposable as D, type GuardRunner as G, type LeaveGuardResult as L, type NavigationManager as N, type RequestContext as R, type StateSerializer as S, type ContainerManager as a, type Guard as b, type GuardResult as c, type NavigationEntry as d, type NavigationInterceptor as e, ActivatableToken as f, ContainerManagerToken as g, GuardRunnerToken as h, NavigationManagerToken as i, RequestContextToken as j, type SlotEntry as k, SlotRegistry as l, SlotRegistryToken as m, StateCache as n, type StateParticipant as o, StateRegistry as p, StateRegistryToken as q, StateSerializerToken as r };