@endge/core 5.0.0 → 7.0.0

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

@@ -0,0 +1,108 @@
+import { AnyEndgeModule, EndgeFederationContextOf, EndgeFederationModuleAccessors, EndgeModuleDefinition, EndgeModuleDefinitions, EndgeModuleDescriptor } from './types/endge-modules.types';
+import { AnyEndgeFederation, EndgeChildFederationDefinition, EndgeChildFederationDefinitions, EndgeFederationContext, EndgeFederationDefinition, EndgeFederationDiagnosticsSnapshot, EndgeFederationDiagnosticsSnapshotOptions, EndgeFederationHost, EndgeFederationState, EndgeLifecycleNodeDescriptor, EndgePlugin } from './types/federation.types';
+type EndgeFederationPhase = 'setup' | 'load' | 'build' | 'start';
+declare const ENDGE_FEDERATION_CONTROL_KEY: unique symbol;
+type UnionToIntersection<TValue> = (TValue extends unknown ? (value: TValue) => void : never) extends ((value: infer TResult) => void) ? TResult : never;
+type EndgeChildFederationContext<TFederation> = TFederation extends {
+    boot: (ctx: infer TContext) => Promise<void>;
+} ? TContext : EndgeFederationContext;
+type EndgeChildFederationsContext<TDefinitions extends EndgeChildFederationDefinitions> = [TDefinitions[number]] extends [never] ? EndgeFederationContext : UnionToIntersection<EndgeChildFederationContext<TDefinitions[number]['federation']>> extends infer TContext extends EndgeFederationContext ? TContext : EndgeFederationContext;
+type EndgeFederationConstructor = abstract new (...args: any[]) => EndgeFederation;
+type EndgeFederationStatics = Omit<typeof EndgeFederation, 'prototype' | 'boot' | 'build'>;
+type EndgeFederationAccessors<TDefinitions extends EndgeChildFederationDefinitions> = {
+    readonly [TDefinition in TDefinitions[number] as TDefinition['key']]: TDefinition['federation'];
+};
+export type DefinedEndgeFederation<TDefinitions extends EndgeModuleDefinitions, TFederations extends EndgeChildFederationDefinitions = readonly [], TContext extends EndgeFederationContext = EndgeFederationContextOf<TDefinitions> & EndgeChildFederationsContext<TFederations>> = EndgeFederationConstructor & EndgeFederationStatics & EndgeFederationModuleAccessors<TDefinitions> & EndgeFederationAccessors<TFederations> & {
+    readonly prototype: EndgeFederation;
+    boot: (ctx: TContext) => Promise<void>;
+    build: (ctx?: TContext) => Promise<void>;
+};
+interface EndgeFederationControl {
+    readonly id: string;
+    attach: (parentFederationId: string) => void;
+    createDiagnosticsSnapshot: (path: string[], options: EndgeFederationDiagnosticsSnapshotOptions) => EndgeFederationDiagnosticsSnapshot;
+    configure: () => void;
+    runPhase: (phase: EndgeFederationPhase, ctx: EndgeFederationContext) => Promise<void>;
+    reset: () => Promise<void>;
+}
+/**
+ * Общая статическая федерация lifecycle-узлов.
+ * Хост федерации живёт в `globalThis`, поэтому один и тот же id
+ * остаётся singleton даже при загрузке из разных пакетов/бандлов.
+ */
+export declare abstract class EndgeFederation {
+    protected static readonly federationId: string;
+    protected static readonly federationDefinitionSignature: string | null;
+    /** Стабильная runtime identity Federation. */
+    static get id(): string;
+    /** Создаёт Federation с ленивыми Modules и дочерними Federations. */
+    static define<const TDefinitions extends EndgeModuleDefinitions, const TFederations extends EndgeChildFederationDefinitions = readonly []>(definition: EndgeFederationDefinition<TDefinitions, TFederations>): DefinedEndgeFederation<TDefinitions, TFederations>;
+    static get isInitialized(): boolean;
+    static get isConfigured(): boolean;
+    static get state(): EndgeFederationState;
+    static get lastError(): unknown | null;
+    /** Рекурсивно снимает диагностическое состояние явного Federation graph. */
+    static createDiagnosticsSnapshot(options?: EndgeFederationDiagnosticsSnapshotOptions): EndgeFederationDiagnosticsSnapshot;
+    /** Хук одноразовой декларации собственных lifecycle-узлов Federation. */
+    protected static configureFederation(): void;
+    /** Запускает всё дерево Federation по pipeline `setup -> load -> build -> start`. */
+    static boot(ctx: EndgeFederationContext): Promise<void>;
+    private static _runBoot;
+    /** Регистрирует декларативное расширение до configuration Federation. */
+    static use(plugin: EndgePlugin): void;
+    /** Декларирует уже созданный Module во время custom configuration. */
+    static defineModule<T extends AnyEndgeModule>(descriptor: EndgeModuleDescriptor<T>): T;
+    static defineModules(descriptors: readonly EndgeModuleDescriptor[]): void;
+    /** Декларирует лениво создаваемые Modules во время configuration. */
+    protected static defineModuleDefinitions(definitions: readonly EndgeModuleDefinition[]): void;
+    /** Декларирует дочернюю Federation как composite lifecycle-узел. */
+    static defineFederation(definition: EndgeChildFederationDefinition): void;
+    static defineFederations(definitions: readonly EndgeChildFederationDefinition[]): void;
+    protected static setup(ctx?: EndgeFederationContext, touchedNodes?: Set<EndgeLifecycleNodeDescriptor>): Promise<void>;
+    protected static load(ctx?: EndgeFederationContext, touchedNodes?: Set<EndgeLifecycleNodeDescriptor>): Promise<void>;
+    static build(ctx?: EndgeFederationContext): Promise<void>;
+    protected static start(ctx?: EndgeFederationContext, touchedNodes?: Set<EndgeLifecycleNodeDescriptor>): Promise<void>;
+    /** Сбрасывает всё дерево в обратном dependency order. */
+    static reset(): Promise<void>;
+    private static _runReset;
+    private static _buildPhase;
+    private static _runPhase;
+    private static _resetNodes;
+    private static _finishBuild;
+    private static _finishReset;
+    static getModule<T extends AnyEndgeModule = AnyEndgeModule>(key: string): T;
+    static tryGetModule<T extends AnyEndgeModule = AnyEndgeModule>(key: string): T | null;
+    static hasModule(key: string): boolean;
+    static getFederation<T extends AnyEndgeFederation = AnyEndgeFederation>(key: string): T;
+    static tryGetFederation<T extends AnyEndgeFederation = AnyEndgeFederation>(key: string): T | null;
+    static hasFederation(key: string): boolean;
+    protected static get host(): EndgeFederationHost;
+    private static _ensureConfigured;
+    private static _getFederationId;
+    private static _createHost;
+    private static _getOrCreateHost;
+    private static _normalizeHost;
+    private static _normalizeModuleDefinitions;
+    private static _normalizeFederationDefinitions;
+    private static _normalizeNodeKey;
+    private static _requireBootContext;
+    private static _requireConfiguringHost;
+    private static _assertNodeKeyAvailable;
+    private static _validatePluginKeys;
+    private static _installPlugins;
+    private static _finalizeNodes;
+    private static _defineAccessors;
+    private static _defineHostAccessors;
+    private static _assertAccessorAvailable;
+    private static _defineAccessor;
+    private static _createDefinitionSignature;
+    private static _createPluginSignature;
+    private static _getFederationControl;
+    protected static [ENDGE_FEDERATION_CONTROL_KEY](): EndgeFederationControl;
+    private static _createDiagnosticsSnapshot;
+    private static _attachToParent;
+    private static _runAttachedPhase;
+    private static _resetAttached;
+    private static _registry;
+}
+export {};

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

@@ -0,0 +1,59 @@
+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>;
+    /**
+     * Возвращает состояние Module для общего диагностического snapshot.
+     * По умолчанию используется persistence-проекция `serialize()`; Module может
+     * переопределить метод более подробным или безопасным диагностическим представлением.
+     * Снимки принадлежащих Module submodules явно включает их родитель.
+     */
+    createDiagnosticsSnapshot(): unknown;
+    /**
+     * Возвращает сериализуемый 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,9 @@
+import { EndgeModuleDescriptor } from '../types/endge-modules.types';
+interface EndgeOrderedDescriptor {
+    readonly key: string;
+    readonly before?: string | readonly string[];
+    readonly after?: string | readonly string[];
+}
+export declare function sortEndgeOrderedDescriptors<TDescriptor extends EndgeOrderedDescriptor>(descriptors: readonly TDescriptor[]): TDescriptor[];
+export declare function sortEndgeModuleDescriptors(descriptors: EndgeModuleDescriptor[]): EndgeModuleDescriptor[];
+export {};

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

@@ -0,0 +1,33 @@
+import { EndgeModule } from '../EndgeModule';
+import { EndgeFederationContext, EndgeFederationDiagnosticsSnapshot, EndgeFederationDiagnosticsSnapshotOptions } 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;
+    createDiagnosticsSnapshot: (options?: EndgeFederationDiagnosticsSnapshotOptions) => EndgeFederationDiagnosticsSnapshot;
+}
+/** Декларативное описание лениво создаваемого модуля федерации. */
+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 {};

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

@@ -0,0 +1,119 @@
+import { EndgeModule } from '../EndgeModule';
+import { AnyEndgeModule, EndgeModuleDefinitions, EndgeModuleDescriptor, EndgeModuleOrder } from './endge-modules.types';
+/** Минимальный context, общий для lifecycle любой федерации. */
+export interface EndgeFederationContext {
+    signal?: AbortSignal;
+}
+export type EndgeFederationState = 'idle' | 'booting' | 'ready' | 'building' | 'resetting' | 'failed';
+export type EndgeModuleDiagnosticsSnapshotStatus = 'captured' | 'empty' | 'skipped' | 'failed' | 'referenced';
+/** Стабильная ссылка на Module внутри декларативного дерева Federation. */
+export interface EndgeModuleDiagnosticsSnapshotReference {
+    federationId: string;
+    key: string;
+    path: string[];
+    moduleName: string;
+}
+/** Настройки рекурсивного сбора диагностического дерева Federation. */
+export interface EndgeFederationDiagnosticsSnapshotOptions {
+    shouldCaptureModule?: (module: EndgeModuleDiagnosticsSnapshotReference) => boolean;
+}
+/** Диагностический узел зарегистрированного Module. */
+export interface EndgeModuleDiagnosticsSnapshotNode extends EndgeModuleDiagnosticsSnapshotReference {
+    kind: 'module';
+    status: EndgeModuleDiagnosticsSnapshotStatus;
+    snapshot?: unknown;
+    snapshotRef?: string;
+    error?: string;
+}
+/** Диагностический узел дочерней Federation. */
+export interface EndgeChildFederationDiagnosticsSnapshotNode {
+    kind: 'federation';
+    key: string;
+    path: string[];
+    status: 'captured' | 'failed';
+    federation?: EndgeFederationDiagnosticsSnapshot;
+    error?: string;
+}
+export type EndgeFederationDiagnosticsSnapshotNode = EndgeModuleDiagnosticsSnapshotNode | EndgeChildFederationDiagnosticsSnapshotNode;
+/** Рекурсивная диагностическая проекция одного декларативного Federation graph. */
+export interface EndgeFederationDiagnosticsSnapshot {
+    id: string;
+    name: string;
+    path: string[];
+    state: EndgeFederationState;
+    plugins: string[];
+    nodes: EndgeFederationDiagnosticsSnapshotNode[];
+}
+/** Публичный lifecycle-контракт статического facade Federation. */
+export interface EndgeFederationFacade<in TContext extends EndgeFederationContext = EndgeFederationContext> {
+    readonly id: string;
+    readonly isConfigured: boolean;
+    readonly isInitialized: boolean;
+    readonly lastError: unknown | null;
+    readonly state: EndgeFederationState;
+    createDiagnosticsSnapshot: (options?: EndgeFederationDiagnosticsSnapshotOptions) => EndgeFederationDiagnosticsSnapshot;
+    boot: (ctx: TContext) => Promise<void>;
+    build: (ctx?: TContext) => Promise<void>;
+    reset: () => Promise<void>;
+}
+export type AnyEndgeFederation = EndgeFederationFacade<any>;
+/** Дочерняя Federation как один composite lifecycle-узел родительского graph. */
+export interface EndgeChildFederationDefinition<TKey extends string = string, TFederation extends AnyEndgeFederation = AnyEndgeFederation> {
+    readonly key: TKey;
+    readonly federation: TFederation;
+    readonly before?: EndgeModuleOrder;
+    readonly after?: EndgeModuleOrder;
+}
+export type EndgeChildFederationDefinitions = readonly EndgeChildFederationDefinition[];
+/** Plugin декларативно расширяет одну Federation до её configuration/boot. */
+export interface EndgePlugin<TModules extends EndgeModuleDefinitions = EndgeModuleDefinitions, TFederations extends EndgeChildFederationDefinitions = EndgeChildFederationDefinitions> {
+    readonly id: string;
+    readonly modules?: TModules;
+    readonly federations?: TFederations;
+}
+/** Полное декларативное описание автоматически собираемой федерации. */
+export interface EndgeFederationDefinition<TDefinitions extends EndgeModuleDefinitions, TFederations extends EndgeChildFederationDefinitions = readonly []> {
+    readonly id: string;
+    readonly name?: string;
+    readonly modules: TDefinitions;
+    readonly federations?: TFederations;
+}
+export type EndgeLifecycleNodeDescriptor = {
+    readonly kind: 'module';
+    readonly key: string;
+    readonly module: AnyEndgeModule;
+    readonly before?: EndgeModuleOrder;
+    readonly after?: EndgeModuleOrder;
+} | {
+    readonly kind: 'federation';
+    readonly key: string;
+    readonly federation: AnyEndgeFederation;
+    readonly before?: EndgeModuleOrder;
+    readonly after?: EndgeModuleOrder;
+};
+export interface EndgeFederationHost {
+    definitionSignature: string | null;
+    parentFederationId: string | null;
+    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;
+    moduleDefinitions: EndgeModuleDefinitions[number][];
+    federationDefinitions: EndgeChildFederationDefinition[];
+    moduleDescriptors: EndgeModuleDescriptor[];
+    nodes: EndgeLifecycleNodeDescriptor[];
+    modules: Map<string, EndgeModule<any>>;
+    federations: Map<string, AnyEndgeFederation>;
+    facades: Set<AnyEndgeFederation>;
+    plugins: EndgePlugin[];
+    pluginSignatures: Map<string, string>;
+    installedPluginIds: Set<string>;
+    attachedTouchedNodes: Set<EndgeLifecycleNodeDescriptor>;
+}

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;
+}