@endge/core 5.0.0 → 6.0.0

package/dist/features/federation/EndgeFederation.d.ts

@@ -0,0 +1,80 @@
+import { AnyEndgeModule, EndgeFederationContextOf, EndgeFederationModuleAccessors, EndgeModuleDefinitions, EndgeModuleDescriptor, EndgePlugin } from './types/endge-modules.types';
+import { EndgeFederationContext, EndgeFederationDefinition, EndgeFederationHost, EndgeFederationState } from './types/federation.types';
+type EndgeFederationConstructor = abstract new (...args: any[]) => EndgeFederation;
+type EndgeFederationStatics = Omit<typeof EndgeFederation, 'prototype' | 'boot' | 'build'>;
+export type DefinedEndgeFederation<TDefinitions extends EndgeModuleDefinitions, TContext extends EndgeFederationContext = EndgeFederationContextOf<TDefinitions>> = EndgeFederationConstructor & EndgeFederationStatics & EndgeFederationModuleAccessors<TDefinitions> & {
+    readonly prototype: EndgeFederation;
+    boot: (ctx: TContext) => Promise<void>;
+    build: (ctx?: TContext) => Promise<void>;
+};
+/**
+ * Общая статическая федерация модулей.
+ * Хост федерации живёт в `globalThis`, поэтому один и тот же класс
+ * остаётся singleton даже при загрузке из разных пакетов/бандлов.
+ */
+export declare abstract class EndgeFederation {
+    protected static readonly federationId: string;
+    /**
+     * Создаёт статическую федерацию с ленивыми модулями и типизированными readonly accessors.
+     * Для дополнительного поведения возвращённый class-like facade можно наследовать.
+     */
+    static define<const TDefinitions extends EndgeModuleDefinitions>(definition: EndgeFederationDefinition<TDefinitions>): DefinedEndgeFederation<TDefinitions, EndgeFederationContextOf<TDefinitions>>;
+    static get isInitialized(): boolean;
+    static get isConfigured(): boolean;
+    static get state(): EndgeFederationState;
+    static get lastError(): unknown | null;
+    /**
+     * Хук для одноразовой регистрации модулей в порядке вызова.
+     */
+    protected static configureFederation(): void;
+    /**
+     * Запускает федерацию по полному lifecycle pipeline: `setup -> load -> build -> start`.
+     */
+    static boot(ctx: EndgeFederationContext): Promise<void>;
+    private static _runBoot;
+    /**
+     * Добавляет plugin в список расширений федерации.
+     * Plugin устанавливается во время конфигурации федерации, до boot.
+     */
+    static use(plugin: EndgePlugin): void;
+    /**
+     * Декларирует модуль федерации.
+     * Итоговый порядок строится после установки plugin-модулей.
+     */
+    static defineModule<T extends AnyEndgeModule>(descriptor: EndgeModuleDescriptor<T>): T;
+    /**
+     * Декларирует модули федерации.
+     * Итоговый порядок строится после установки plugin-модулей.
+     */
+    static defineModules(descriptors: EndgeModuleDescriptor[]): void;
+    /**
+     * Выполняет `setup()` для всех модулей один раз до первого `start()`.
+     */
+    protected static setup(ctx?: EndgeFederationContext, touchedModules?: Set<AnyEndgeModule>): Promise<void>;
+    protected static load(ctx?: EndgeFederationContext, touchedModules?: Set<AnyEndgeModule>): Promise<void>;
+    static build(ctx?: EndgeFederationContext): Promise<void>;
+    protected static start(ctx?: EndgeFederationContext, touchedModules?: Set<AnyEndgeModule>): Promise<void>;
+    /**
+     * Выполняет `reset()` в обратном dependency order и сбрасывает состояние федерации.
+     */
+    static reset(): Promise<void>;
+    private static _runReset;
+    private static _buildPhase;
+    private static _runPhase;
+    private static _resetModules;
+    private static _finishBuild;
+    static getModule<T extends AnyEndgeModule = AnyEndgeModule>(key: string): T;
+    static tryGetModule<T extends AnyEndgeModule = AnyEndgeModule>(key: string): T | null;
+    static hasModule(key: string): boolean;
+    protected static get host(): EndgeFederationHost;
+    private static _getFederationId;
+    private static _createHost;
+    private static _getOrCreateHost;
+    private static _normalizeHost;
+    private static _normalizeDefinitions;
+    private static _requireBootContext;
+    private static _installPlugins;
+    private static _finalizeModules;
+    private static _registry;
+}
+export {};

package/dist/features/federation/EndgeModule.d.ts

@@ -0,0 +1,52 @@
+import { EndgeFederationContext } from './types/federation.types';
+import { Subscribable } from '@endge/utils';
+/**
+ * Базовый модуль федерации.
+ * Все модули являются `Subscribable` и при необходимости могут уведомлять подписчиков через `notify()`.
+ */
+export declare abstract class EndgeModule<TContext extends EndgeFederationContext = EndgeFederationContext> extends Subscribable {
+    /** Сохраняет требуемый lifecycle context в type system без runtime state. */
+    protected readonly _contextType: TContext;
+    /**
+     * Подготавливает модуль до загрузки данных.
+     * Используется для настройки зависимостей, клиентов, registry и базовых опций.
+     * Метод можно не переопределять.
+     */
+    setup(_ctx: TContext): void | Promise<void>;
+    /**
+     * Участвует в загрузке данных движка.
+     * Модуль выполняет только свою часть загрузки или принятия данных.
+     * Метод можно не переопределять.
+     */
+    load(_ctx: TContext): void | Promise<void>;
+    /**
+     * Строит производные структуры из загруженных данных.
+     * Здесь уместны normalize, validate, index и compile.
+     * Метод можно не переопределять.
+     */
+    build(_ctx: TContext): void | Promise<void>;
+    /**
+     * Запускает живую инфраструктуру модуля после `load/build`.
+     * Здесь уместны subscriptions, runtime phases, watchers, adapters и debug hooks.
+     * Метод можно не переопределять.
+     */
+    start(_ctx: TContext): void | Promise<void>;
+    /**
+     * Сбрасывает runtime-состояние модуля.
+     * После `reset()` федерация может быть повторно инициализирована тем же набором модулей.
+     * Метод можно не переопределять.
+     */
+    reset(): void | Promise<void>;
+    /**
+     * Возвращает сериализуемый snapshot состояния модуля.
+     * Конкретный persistent Module сам определяет storage contract и момент сохранения.
+     * Если сохранять нечего, можно вернуть `undefined` или не переопределять метод.
+     */
+    serialize(): unknown;
+    /**
+     * Восстанавливает состояние модуля из snapshot, полученного его persistence owner.
+     * `undefined` означает отсутствие сохранённого состояния и должен обрабатываться как дефолтный сценарий.
+     * Метод можно не переопределять.
+     */
+    deserialize(_payload: unknown): void;
+}

package/dist/features/federation/constants/federation.constants.d.ts

@@ -0,0 +1,2 @@
+/** Глобальный ключ registry для всех экземпляров федерации Endge. */
+export declare const ENDGE_FEDERATION_REGISTRY_KEY: unique symbol;

package/dist/features/federation/tools/endge-token.d.ts

@@ -0,0 +1,3 @@
+import { EndgeEventMap, EndgeToken } from '../types/forge.types';
+/** Создаёт типизированный идентификатор federation service. */
+export declare function endgeToken<T, E extends EndgeEventMap = object>(id: string): EndgeToken<T, E>;

package/dist/features/federation/tools/sort-endge-modules.d.ts

@@ -0,0 +1,2 @@
+import { EndgeModuleDescriptor } from '../types/endge-modules.types';
+export declare function sortEndgeModuleDescriptors(descriptors: EndgeModuleDescriptor[]): EndgeModuleDescriptor[];

package/dist/features/federation/types/endge-modules.types.d.ts

@@ -0,0 +1,36 @@
+import { EndgeModule } from '../EndgeModule';
+import { EndgeFederationContext } from './federation.types';
+export type AnyEndgeModule = EndgeModule<any>;
+export type EndgeModuleOrder = string | readonly string[];
+/** Доступ к уже объявленным модулям во время создания graph dependencies. */
+export interface EndgeModuleFactoryContext {
+    getModule: <T extends AnyEndgeModule = AnyEndgeModule>(key: string) => T;
+}
+/** Декларативное описание лениво создаваемого модуля федерации. */
+export interface EndgeModuleDefinition<TKey extends string = string, TModule extends AnyEndgeModule = AnyEndgeModule> {
+    readonly key: TKey;
+    readonly create: (context: EndgeModuleFactoryContext) => TModule;
+    readonly before?: EndgeModuleOrder;
+    readonly after?: EndgeModuleOrder;
+}
+export interface EndgeModuleDescriptor<T extends AnyEndgeModule = AnyEndgeModule> {
+    key: string;
+    module: T;
+    before?: EndgeModuleOrder;
+    after?: EndgeModuleOrder;
+}
+export type EndgeModuleDefinitions = readonly EndgeModuleDefinition[];
+/** Lifecycle context, объявленный concrete Module. */
+export type EndgeModuleContext<TModule extends AnyEndgeModule> = TModule extends EndgeModule<infer TContext> ? TContext : never;
+type UnionToIntersection<TValue> = (TValue extends unknown ? (value: TValue) => void : never) extends ((value: infer TResult) => void) ? TResult : never;
+/** Наиболее строгий lifecycle context, требуемый всеми Modules федерации. */
+export type EndgeFederationContextOf<TDefinitions extends EndgeModuleDefinitions> = UnionToIntersection<EndgeModuleContext<ReturnType<TDefinitions[number]['create']>>> extends infer TContext extends EndgeFederationContext ? TContext : EndgeFederationContext;
+/** Readonly module accessors, выведенные из literal keys и factory return types. */
+export type EndgeFederationModuleAccessors<TDefinitions extends EndgeModuleDefinitions> = {
+    readonly [TDefinition in TDefinitions[number] as TDefinition['key']]: ReturnType<TDefinition['create']>;
+};
+export interface EndgePlugin {
+    id: string;
+    install: () => void;
+}
+export {};

package/dist/features/federation/types/federation.types.d.ts

@@ -0,0 +1,30 @@
+import { EndgeModule } from '../EndgeModule';
+import { EndgeModuleDefinitions, EndgeModuleDescriptor, EndgePlugin } from './endge-modules.types';
+/** Минимальный context, общий для lifecycle любой федерации. */
+export interface EndgeFederationContext {
+    signal?: AbortSignal;
+}
+export type EndgeFederationState = 'idle' | 'booting' | 'ready' | 'building' | 'resetting' | 'failed';
+/** Полное декларативное описание автоматически собираемой федерации. */
+export interface EndgeFederationDefinition<TDefinitions extends EndgeModuleDefinitions> {
+    readonly id: string;
+    readonly name?: string;
+    readonly modules: TDefinitions;
+}
+export interface EndgeFederationHost {
+    isConfigured: boolean;
+    isConfiguring: boolean;
+    isSetup: boolean;
+    isInitialized: boolean;
+    state: EndgeFederationState;
+    lastError: unknown | null;
+    bootContext: EndgeFederationContext | null;
+    bootPromise: Promise<void> | null;
+    resetPromise: Promise<void> | null;
+    buildQueue: Promise<void>;
+    pendingBuilds: number;
+    moduleDescriptors: EndgeModuleDescriptor[];
+    modules: Map<string, EndgeModule<any>>;
+    plugins: EndgePlugin[];
+    installedPluginIds: Set<string>;
+}

package/dist/features/federation/types/forge.types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Endge Модуль
+ */
+export interface EndgeModule {
+    id: string;
+    setup: () => void;
+    destroy?: () => void;
+    toPlain?: () => object;
+    fromPlain?: (data: object) => void;
+}
+export type EndgeEventMap = Record<string, any>;
+/**
+ * Токены (типизированные идентификаторы сервисов)
+ */
+export type EndgeToken<T, E extends EndgeEventMap> = string & {
+    __t?: T;
+    __ev?: E;
+};
+export type EndgeModuleCtor = new () => EndgeModule;
+export type EndgeModuleSpec = EndgeModule | EndgeModuleCtor;
+export type EndgeModuleLoader = (() => Promise<EndgeModuleSpec> | EndgeModuleSpec) | EndgeModuleSpec;
+export interface EndgeModuleInstall<T extends EndgeModule, E extends EndgeEventMap = object> {
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    token: EndgeToken<T, E>;
+    loader: EndgeModuleLoader;
+}