@raphy-js/raph 1.0.0-dev.2 → 1.0.1-dev.25

package/dist/api/Raph.d.ts

@@ -1,228 +1,97 @@
-import { DataPathDef, PathEvents, PathOptions } from '../path/path.types';
-import { DerivedOptions, RaphDerivedHandle } from '../path/RaphDerivedHandle';
-import { RaphKernelOptions, RaphKernelRoot, RaphKernel } from '../path/RaphKernel';
-import { RaphMeta } from '../path/RaphMeta';
+import { DerivedOptions, RaphDerivedHandle } from '../path/derived/RaphDerivedHandle';
+import { DataPathDef, PathOptions } from '../path/path.types';
+import { RaphKernel, RaphKernelOptions, RaphKernelRoot } from '../path/RaphKernel';
 import { ScopeNode } from '../reactivity/scope';
 import { Disposer, ReadonlySignal, Signal, WatchOptions, WatchSource, WatchValue, WritableComputedOptions } from '../reactivity/types';
-import { PathHandle } from '../runtime/PathHandle';
-import { FrameLoopLease, RaphEffectOptions, RaphPhase } from '../runtime/phase.types';
-import { RaphRuntimeDebug } from '../runtime/RaphDebug';
-import { NodeOptions, RaphNode } from '../runtime/RaphNode';
-import { RaphRuntimeOptions, RaphRuntime } from '../runtime/RaphRuntime';
-import { RaphScope } from '../runtime/RaphScope';
-import { RaphConfigureOptions, RaphMode } from './types';
-import { collectionByKey, filterByKey, full } from '../path/derived-strategies';
-interface RaphComputed {
-    <T>(getter: () => T): ReadonlySignal<T>;
-    <T>(options: WritableComputedOptions<T>): Signal<T>;
-}
-interface RaphEffect {
-    (callback: () => void | Disposer): Disposer;
-    (phase: string, callback: () => void | Disposer, options?: RaphEffectOptions): Disposer;
-}
-interface RaphWatch {
-    (masks: DataPathDef | readonly DataPathDef[], callback: (payload: PathEvents) => void | Disposer, options?: WatchOptions): Disposer;
-    <S extends WatchSource | readonly WatchSource[]>(source: S, callback: (value: WatchValue<S>, previous: WatchValue<S> | undefined) => void | Disposer, options?: WatchOptions): Disposer;
-}
-interface RaphScopeFactory {
-    (): ScopeNode;
-    (id: string): RaphScope;
-}
+import { RaphRuntimeDebug } from '../runtime/diagnostics/RaphDebug';
+import { NodeOptions, RaphNode } from '../runtime/ownership/RaphNode';
+import { RaphScope } from '../runtime/ownership/RaphScope';
+import { FrameLoopLease, RaphAggregateSource, RaphEffectOptions, RaphPhase, RaphPhaseEffect, RaphWatchOptions, RaphWatchSource } from '../runtime/phases/phase.types';
+import { RaphRuntimeMeta, RaphRuntimeOptions, RaphRuntime } from '../runtime/RaphRuntime';
+import { PathHandle } from '../runtime/reactivity/PathHandle';
+import { RaphAggregate } from '../runtime/reactivity/RaphWorkGraph';
+import { ConfiguredRaph, RaphFlatConfigureOptions, RaphInstance, RaphInstanceDefinitions, RaphInstancesConfigureOptions, RaphReactivityInstanceOptions, StrictRaphConfigureOptions } from './types';
+import { collectionByKey, filterByKey, full } from '../path/derived/derived-strategy.utils';
+import { RaphReactivityInstance } from './RaphReactivityInstance';
+type WithoutRuntimePathHandle<Source> = Source extends PathHandle<unknown> ? never : Source extends readonly unknown[] ? {
+    [Key in keyof Source]: Source[Key] extends PathHandle<unknown> ? never : Source[Key];
+} : Source;
 /**
- * Плоский фасад над одним явно выбранным backend текущей сессии.
+ * Process-level convenience facade над одной явно configured heterogeneous session.
  */
 export declare class Raph {
-    private static _state;
-    private static _mode;
-    private static _defaultRuntime;
-    private static _reactivity;
-    private static _runtimes;
-    private static _runtimeOrder;
-    private static _runtimeCounter;
-    private static _runtimeDefaults;
-    static signal: <T>(value: T) => Signal<T>;
-    static computed: RaphComputed;
-    static effect: RaphEffect;
-    static watch: RaphWatch;
-    static batch: <T>(operation: () => T) => T;
-    static untracked: <T>(operation: () => T) => T;
-    static scope: RaphScopeFactory;
-    /**
-     * Показывает, завершена ли явная конфигурация facade.
-     */
+    private static _handle;
+    private constructor();
     static get configured(): boolean;
-    /**
-     * Возвращает выбранный режим либо `undefined` до конфигурации.
-     */
-    static get mode(): RaphMode | undefined;
-    /**
-     * Однократно выбирает backend и устанавливает публичные операции facade.
-     */
-    static configure(options: RaphConfigureOptions): void;
-    /**
-     * Освобождает принадлежащие facade runtimes и возвращает его в исходное состояние.
-     */
-    static reset(): void;
-    /**
-     * Возвращает default runtime текущей runtime-сессии.
-     */
-    static get runtime(): RaphRuntime;
-    /**
-     * Возвращает metadata facade default runtime.
-     */
-    static get meta(): RaphMeta;
-    /**
-     * Возвращает диагностический facade default runtime.
-     */
+    static get defaultInstanceId(): string | undefined;
+    static get kernel(): RaphKernel;
+    static get meta(): RaphRuntimeMeta;
     static get debug(): RaphRuntimeDebug;
-    /**
-     * Возвращает корневой node default runtime.
-     */
     static get root(): RaphNode;
-    /**
-     * Формирует снимок materialized derived default runtime.
-     */
-    static getDerivedSnapshot(): ReturnType<RaphKernel['getDerivedSnapshot']>;
-    /**
-     * Создаёт независимый path/kernel owner в runtime-режиме.
-     */
-    static createKernel(options?: RaphKernelOptions): RaphKernel;
-    /**
-     * Создаёт и регистрирует принадлежащий facade runtime.
-     */
+    static get rootScope(): RaphScope;
+    static get frameTick(): ReadonlySignal<number>;
+    static get frame(): RaphRuntime['frame'];
+    static get phases(): readonly RaphPhase[];
+    static get loopEnabled(): boolean;
+    static configure<const Definitions extends RaphInstanceDefinitions>(options: StrictRaphConfigureOptions<RaphInstancesConfigureOptions<Definitions>>): ConfiguredRaph<RaphInstancesConfigureOptions<Definitions>>;
+    static configure<const Options extends RaphFlatConfigureOptions>(options: StrictRaphConfigureOptions<Options>): ConfiguredRaph<Options>;
+    static reset(): void;
+    static instance(id?: string): RaphInstance;
+    static getInstance(id: string): RaphInstance | undefined;
+    static hasInstance(id: string): boolean;
+    static disposeInstance(id: string): boolean;
+    static runtime(id?: string): RaphRuntime;
+    static reactivity(id?: string): RaphReactivityInstance;
     static createRuntime(options?: RaphRuntimeOptions): RaphRuntime;
-    /**
-     * Возвращает зарегистрированный runtime без ошибки при его отсутствии.
-     */
-    static getRuntime(id: string): RaphRuntime | undefined;
-    /**
-     * Возвращает зарегистрированный runtime либо отклоняет неизвестный id.
-     */
-    static requireRuntime(id: string): RaphRuntime;
-    /**
-     * Проверяет наличие runtime в registry текущей сессии.
-     */
-    static hasRuntime(id: string): boolean;
-    /**
-     * Освобождает зарегистрированный runtime с указанным id.
-     */
-    static disposeRuntime(id: string): boolean;
-    /**
-     * Заменяет phases default runtime до первого выполнения pipeline.
-     */
+    static createReactivity(options?: RaphReactivityInstanceOptions): RaphReactivityInstance;
+    static createKernel(options?: RaphKernelOptions): RaphKernel;
+    static signal<T>(value: T): Signal<T>;
+    static reactive<T extends object>(value: T): T;
+    static computed<T>(getter: () => T): ReadonlySignal<T>;
+    static computed<T>(options: WritableComputedOptions<T>): Signal<T>;
+    static effect(callback: () => void | Disposer): Disposer;
+    static effect(phase: string, callback: RaphPhaseEffect, options?: RaphEffectOptions): Disposer;
+    static watch<Source extends WatchSource | readonly WatchSource[]>(source: Source & WithoutRuntimePathHandle<Source>, callback: (value: WatchValue<Source>, previous: WatchValue<Source> | undefined) => void | Disposer, options?: WatchOptions): Disposer;
+    static watch(source: RaphWatchSource, phase: string, callback: RaphPhaseEffect, options?: RaphWatchOptions): Disposer;
+    static batch<T>(operation: () => T): T;
+    static untracked<T>(operation: () => T): T;
+    static scope(): ScopeNode;
+    static scope(id: string): RaphScope;
+    static action<Args extends unknown[], Result>(operation: (...args: Args) => Result): (...args: Args) => Result;
+    static action<Args extends unknown[], Result>(name: string, operation: (...args: Args) => Result): (...args: Args) => Result;
     static definePhases(phases: readonly RaphPhase[]): void;
-    /**
-     * Добавляет phase в default runtime до первого выполнения pipeline.
-     */
     static addPhase(phase: RaphPhase): void;
-    /**
-     * Удаляет phases default runtime до первого выполнения pipeline.
-     */
     static clearPhases(): void;
-    /**
-     * Синхронно выполняет накопленную работу default runtime.
-     */
+    static requestExecution(): void;
     static flush(): void;
-    /**
-     * Удерживает frame loop активным от имени указанного owner.
-     */
+    static afterFlush(): Promise<void>;
     static acquireLoop(owner: string): FrameLoopLease;
-    /**
-     * Явно запускает frame loop default runtime.
-     */
     static startLoop(): void;
-    /**
-     * Снимает явный запуск frame loop default runtime.
-     */
     static stopLoop(): void;
-    /**
-     * Создаёт принадлежащий default runtime node и выполняет его setup.
-     */
-    static node<TApi>(options: NodeOptions, setup: (node: RaphNode) => TApi): RaphNode<TApi>;
-    /**
-     * Регистрирует materialized path dependency в default runtime.
-     */
+    static aggregate(sources: readonly RaphAggregateSource[]): RaphAggregate;
+    static node<TApi = void>(options: NodeOptions, setup?: (node: RaphNode) => TApi): RaphNode<TApi>;
+    static getNode(id: string): RaphNode | undefined;
     static derive<TSource, TTarget>(options: DerivedOptions<TSource, TTarget>): RaphDerivedHandle<TSource, TTarget>;
-    /**
-     * Создаёт lifecycle-aware handle указанного data path.
-     */
+    static getDerivedSnapshot(): ReturnType<RaphKernel['getDerivedSnapshot']>;
     static path<T>(path: DataPathDef, options?: PathOptions): PathHandle<T>;
-    /**
-     * Читает весь path-root Kernel default runtime с реактивным tracking.
-     */
     static get<T = RaphKernelRoot>(): T | undefined;
-    /**
-     * Читает значение path с реактивным tracking текущего owner.
-     */
     static get<T = unknown>(path: DataPathDef, options?: PathOptions): T | undefined;
-    /**
-     * Читает весь path-root Kernel default runtime без tracking.
-     */
     static peek<T = RaphKernelRoot>(): T | undefined;
-    /**
-     * Читает значение path без регистрации реактивной зависимости.
-     */
     static peek<T = unknown>(path: DataPathDef, options?: PathOptions): T | undefined;
-    /**
-     * Проверяет наличие значения по указанному path.
-     */
     static has(path: DataPathDef, options?: PathOptions): boolean;
-    /**
-     * Заменяет значение по указанному path.
-     */
     static set<T>(path: DataPathDef, value: T, options?: PathOptions): void;
-    /**
-     * Объединяет значение с существующим объектом по указанному path.
-     */
     static merge(path: DataPathDef, value: unknown, options?: PathOptions): void;
-    /**
-     * Удаляет значение по указанному path.
-     */
     static delete(path: DataPathDef, options?: PathOptions): void;
-    /**
-     * Выполняет несколько mutations как одну реактивную транзакцию.
-     */
-    static transaction<T>(operation: () => T): T;
-    /**
-     * Оборачивает операцию в именованную action текущего runtime.
-     */
-    static action<Args extends unknown[], Result>(name: string, operation: (...args: Args) => Result): (...args: Args) => Result;
-    /**
-     * Немедленно выполняет именованную action текущего runtime.
-     */
-    static runInAction<T>(name: string, operation: () => T): T;
-    private static _configureReactivity;
-    private static _configureRuntime;
-    private static _bindRuntime;
-    private static _registerRuntime;
-    private static _requireDefault;
-    private static _requireMode;
-    private static _resolveRuntimeId;
-    private static _validateRuntimeId;
-    private static _validateConfigureOptions;
-    private static _assertKnownOptions;
-    private static _installMissingDefaultBindings;
-    private static _clearBindings;
-    private static _clearSession;
-    /**
-     * Запрещает создание экземпляров статического facade.
-     */
-    private constructor();
-    /**
-     * Предоставляет режимы scheduler без отдельного импорта константы.
-     */
     static readonly Scheduler: Readonly<{
         readonly AnimationFrame: "animationFrame";
         readonly Microtask: "microtask";
         readonly Sync: "sync";
     }>;
-    /**
-     * Предоставляет стратегии materialized derived рядом с facade API.
-     */
     static readonly DerivedStrategy: Readonly<{
         full: typeof full;
         collectionByKey: typeof collectionByKey;
         filterByKey: typeof filterByKey;
     }>;
+    private static _require;
 }
 export {};

package/dist/api/RaphFacadeSession.d.ts

@@ -0,0 +1,90 @@
+import { RaphRuntimeOptions, RaphRuntime } from '../runtime/RaphRuntime';
+import { RaphConfigureOptions, RaphInstance, RaphReactivityInstanceOptions } from './types';
+import { RaphKernel } from '../path/RaphKernel';
+import { RaphReactivityInstance } from './RaphReactivityInstance';
+/**
+ * Владеет registry, default pointer и lifecycle одной facade generation.
+ */
+export declare class RaphFacadeSession {
+    private static _runtimeCounter;
+    private static _reactivityCounter;
+    private readonly _instances;
+    private readonly _instanceOrder;
+    private _defaultInstance;
+    private _disposed;
+    private constructor();
+    /**
+     * Валидирует всю конфигурацию до construction и атомарно создаёт session.
+     */
+    static create(options: RaphConfigureOptions): RaphFacadeSession;
+    /**
+     * Показывает, завершен ли lifecycle session.
+     */
+    get disposed(): boolean;
+    /**
+     * Возвращает ID default instance без создания fallback.
+     */
+    get defaultInstanceId(): string | undefined;
+    /**
+     * Возвращает default либо явно адресованный instance.
+     */
+    instance(id?: string): RaphInstance;
+    /**
+     * Читает registry без ошибки для неизвестного ID.
+     */
+    getInstance(id: string): RaphInstance | undefined;
+    /**
+     * Проверяет наличие managed instance.
+     */
+    hasInstance(id: string): boolean;
+    /**
+     * Возвращает Runtime или сообщает о capability mismatch.
+     */
+    runtime(id?: string): RaphRuntime;
+    /**
+     * Возвращает pure-reactivity instance или сообщает о capability mismatch.
+     */
+    reactivity(id?: string): RaphReactivityInstance;
+    /**
+     * Создаёт managed Runtime без неявного изменения default pointer.
+     */
+    createRuntime(options?: RaphRuntimeOptions): RaphRuntime;
+    /**
+     * Создаёт managed pure-reactivity instance без изменения default pointer.
+     */
+    createReactivity(options?: RaphReactivityInstanceOptions): RaphReactivityInstance;
+    /** Создаёт unmanaged Kernel, сохраняя generation-bound lifecycle check. */
+    createKernel(options?: ConstructorParameters<typeof RaphKernel>[0]): RaphKernel;
+    /**
+     * Освобождает managed instance и сразу удаляет его из registry.
+     */
+    disposeInstance(id: string): boolean;
+    /**
+     * Освобождает managed instances в обратном порядке construction.
+     */
+    dispose(): void;
+    /**
+     * Создаёт instance из заранее проверенного definition.
+     */
+    private _construct;
+    /**
+     * Регистрирует единственный managed owner и его terminal cleanup.
+     */
+    private _register;
+    /**
+     * Удаляет точную identity после её terminal disposal.
+     */
+    private _forget;
+    /**
+     * Формирует свободный ID для dynamic factory.
+     */
+    private _generateId;
+    /**
+     * Отклоняет duplicate resolved ID до registration.
+     */
+    private _assertFreeId;
+    /**
+     * Запрещает stale typed/global handle после reset.
+     */
+    private _assertActive;
+}

package/dist/api/RaphReactivityInstance.d.ts

@@ -0,0 +1,72 @@
+import { Disposer, ReadonlySignal, Signal, WatchCallback, WatchOptions, WatchSource, WritableComputedOptions } from '../reactivity/types';
+import { RaphReactivityInstanceOptions } from './types';
+import { RaphReactivity } from '../reactivity/engine';
+import { ScopeNode } from '../reactivity/scope';
+/**
+ * Управляемый pure-reactivity instance одной facade session.
+ */
+export declare class RaphReactivityInstance {
+    readonly id: string;
+    readonly mode: "reactivity";
+    readonly engine: RaphReactivity;
+    readonly rootScope: ScopeNode;
+    private _disposed;
+    private readonly _disposedListeners;
+    /**
+     * Создаёт изолированный graph с общим lifecycle owner.
+     */
+    constructor(id: string, options?: Omit<RaphReactivityInstanceOptions, 'id'>);
+    /**
+     * Показывает, завершён ли lifecycle instance.
+     */
+    get disposed(): boolean;
+    /**
+     * Создаёт signal, принадлежащий root scope instance.
+     */
+    signal<T>(value: T): Signal<T>;
+    /**
+     * Создаёт deep reactive Proxy в изолированном graph instance.
+     */
+    reactive<T extends object>(value: T): T;
+    /**
+     * Создаёт root-owned computed только для чтения.
+     */
+    computed<T>(getter: () => T): ReadonlySignal<T>;
+    /**
+     * Создаёт root-owned writable computed.
+     */
+    computed<T>(options: WritableComputedOptions<T>): Signal<T>;
+    /**
+     * Создаёт синхронный effect в root scope instance.
+     */
+    effect(callback: () => void | Disposer): Disposer;
+    /**
+     * Создаёт value watch в root scope instance.
+     */
+    watch<S extends WatchSource | readonly WatchSource[]>(source: S, callback: WatchCallback<S>, options?: WatchOptions): Disposer;
+    /**
+     * Группирует propagation одного reactive graph.
+     */
+    batch<T>(operation: () => T): T;
+    /**
+     * Выполняет операцию без dependency tracking.
+     */
+    untracked<T>(operation: () => T): T;
+    /**
+     * Создаёт дочерний resource scope, освобождаемый вместе с instance.
+     */
+    scope(): ScopeNode;
+    /**
+     * Освобождает owned resources и делает retained reactive proxies терминальными.
+     */
+    dispose(): void;
+    /**
+     * Привязывает registry cleanup к lifecycle managed instance.
+     * @internal
+     */
+    _onDisposed(listener: () => void): Disposer;
+    /**
+     * Запрещает операции после завершения lifecycle.
+     */
+    private _assertAlive;
+}

package/dist/api/errors.d.ts

@@ -9,12 +9,17 @@ export declare class RaphError extends Error {
 export declare class RaphConfigurationError extends RaphError {
 }
 /**
- * Сообщает, что операция недоступна в выбранном режиме facade.
+ * Сообщает, что выбранный instance не поддерживает запрошенную capability.
  */
-export declare class RaphModeError extends RaphConfigurationError {
+export declare class RaphCapabilityError extends RaphConfigurationError {
 }
 /**
- * Сообщает об отсутствии default runtime у runtime-сессии.
+ * Сообщает об отсутствии default instance у facade session.
  */
-export declare class RaphDefaultRuntimeError extends RaphConfigurationError {
+export declare class RaphDefaultInstanceError extends RaphConfigurationError {
+}
+/**
+ * Сообщает, что generation-bound handle относится к уже освобождённой session.
+ */
+export declare class RaphFacadeDisposedError extends RaphConfigurationError {
 }