@raphy-js/raph 1.0.0-dev.2

package/dist/reactivity/scope.d.ts

@@ -0,0 +1,146 @@
+import { RaphReactivity } from './engine';
+import { Disposer, EffectCallback, OwnedResource, OwnedSource, ReadonlySignal, ScopeChildren, ScopeLink, Signal, SourceFinalizer, WatchCallback, WatchOptions, WatchSource, WritableComputedOptions } from './types';
+/**
+ * Универсальный владелец ресурсов без фаз, путей и зависимости от Runtime.
+ * Хранит ресурсы в двусвязном списке и освобождает их в обратном порядке.
+ * Проверки lifetime выполняют только owned handles; свободные signal() не проходят
+ * через владельца. Класс не является узлом графа зависимостей.
+ */
+export declare class ScopeNode {
+    readonly reactivity: RaphReactivity;
+    /**
+     * Первый зарегистрированный ресурс; не является ребёнком execution-дерева.
+     * @internal
+     */
+    scopeFirstChild: OwnedResource | undefined;
+    /**
+     * Последний ресурс, с которого начинается освобождение владельца.
+     * @internal
+     */
+    scopeLastChild: OwnedResource | undefined;
+    private _resourceCount;
+    private _sourceFinalizers;
+    protected _disposed: boolean;
+    protected _disposing: boolean;
+    /**
+     * Связывает владельца с реактивным экземпляром без создания нового графа.
+     * @param reactivity Экземпляр, в котором создаются owned-ресурсы.
+     */
+    constructor(reactivity: RaphReactivity);
+    /**
+     * Показывает, началось ли окончательное освобождение владельца.
+     */
+    get disposed(): boolean;
+    /**
+     * Разрешает регистрацию и доступ только до начала освобождения.
+     */
+    get active(): boolean;
+    /**
+     * Создаёт owned signal и регистрирует его финализатор.
+     * Все методы возвращённого handle проверяют, что владелец ещё активен.
+     */
+    signal<T>(value: T): Signal<T>;
+    /**
+     * Создаёт owned computed только для чтения.
+     */
+    computed<T>(getter: () => T): ReadonlySignal<T>;
+    /**
+     * Создаёт owned writable computed с очисткой getter и setter.
+     */
+    computed<T>(options: WritableComputedOptions<T>): Signal<T>;
+    /**
+     * Создаёт эффект и принимает его disposer во владение.
+     * Если владелец уничтожен во время синхронного запуска, немедленно останавливает эффект.
+     */
+    effect(callback: EffectCallback): Disposer;
+    /**
+     * Создаёт watch и регистрирует окончательную остановку у владельца.
+     */
+    watch<S extends WatchSource | readonly WatchSource[]>(source: S, callback: WatchCallback<S>, options?: WatchOptions): Disposer;
+    /**
+     * Принимает произвольный cleanup и возвращает однократный disposer.
+     * Если владелец уже неактивен, выполняет cleanup сразу и возвращает пустой disposer.
+     */
+    own(disposer: Disposer): Disposer;
+    /**
+     * Возвращает число ещё не освобождённых записей ресурсов.
+     * @internal
+     */
+    _debugResourceCount(): number;
+    /**
+     * Возвращает число зарегистрированных финализаторов источников.
+     * @internal
+     */
+    _debugSourceCount(): number;
+    /**
+     * Освобождает ресурсы в обратном порядке, затем финализирует источники.
+     * Повторный вызов безопасен. Ошибки cleanup и завершающего hook собираются
+     * и передаются только после завершения остальных стадий.
+     */
+    dispose(): void;
+    /**
+     * Регистрирует ресурс только у активного владельца.
+     * Дочерняя запись отсоединяется до вызова cleanup, включая ошибочный и вложенный stop.
+     * В отличие от own(), не принимает регистрацию после dispose.
+     * @internal
+     */
+    _own(disposer: Disposer): Disposer;
+    /**
+     * Принимает уже созданный ресурс и не оставляет его без владельца при ошибке регистрации.
+     * При неудачной очистке сохраняет и ошибку регистрации, и ошибку освобождения.
+     * @internal
+     */
+    _adoptResource(disposer: Disposer): Disposer;
+    /**
+     * Регистрирует финализатор owned-источника и возвращает его handle.
+     * Если владелец уже недоступен, освобождает источник до передачи ошибки.
+     * @internal
+     */
+    _adoptSource<T>(owned: OwnedSource<T>): T;
+    /**
+     * Добавляет финализатор источника. Возвращённый им false означает повторную попытку
+     * после прогресса других финализаторов, а не успешное освобождение.
+     * @internal
+     */
+    _ownSource(finalizer: SourceFinalizer): void;
+    /**
+     * Запрещает операции после начала освобождения владельца.
+     * Текст существующей ошибки сохранён для совместимости вызывающих слоёв.
+     * @internal
+     */
+    _assertAlive(): void;
+    /**
+     * Завершающий hook для наследников после ресурсов и источников.
+     * Базовая реализация ничего не делает; исключение наследника попадёт в общий результат.
+     */
+    protected _afterDispose(): void;
+    /**
+     * Возвращает сообщение для AggregateError при нескольких ошибках освобождения.
+     */
+    protected _disposalMessage(): string;
+    /**
+     * Освобождает источники в обратном порядке регистрации с повторными попытками.
+     * Если в проходе не было прогресса, прекращает обход, сохраняя существующий контракт.
+     * Исключение одного финализатора не блокирует остальные.
+     */
+    private _finalizeSources;
+}
+/**
+ * Добавляет дочерний ресурс в конец списка владельца без отдельной обёртки связей.
+ * Предусловие: ребёнок ещё не находится в другом списке. Переиспользуется
+ * ресурсами ScopeNode и записями вложенных эффектов.
+ * @internal
+ */
+export declare function appendScopeChild<T extends ScopeLink<T>>(parent: ScopeChildren<T>, child: T): void;
+/**
+ * Отсоединяет ребёнка от владельца и обнуляет его связи со списком.
+ * Повторное отсоединение безопасно; пользовательский cleanup здесь не вызывается.
+ * @internal
+ */
+export declare function detachScopeChild<T extends ScopeLink<T>>(node: T): void;
+/**
+ * Передаёт единственную ошибку без обёртки либо несколько причин в AggregateError.
+ * Пустой набор не вызывает исключения.
+ * @internal
+ */
+export declare function throwScopeErrors(errors: readonly unknown[], message: string): void;

package/dist/reactivity/types.d.ts

@@ -0,0 +1,150 @@
+export type Disposer = () => void;
+export interface ReadonlySignal<T> {
+    get: (this: ReadonlySignal<unknown>) => T;
+    peek: (this: ReadonlySignal<unknown>) => T;
+}
+export interface Signal<T> extends ReadonlySignal<T> {
+    set: (value: T) => void;
+}
+export interface WritableComputedOptions<T> {
+    readonly get: () => T;
+    readonly set: (value: T) => void;
+}
+export type EffectCallback = () => void | Disposer;
+export interface EffectTask {
+    schedule: () => void;
+    dispose: Disposer;
+}
+export interface EffectScheduler {
+    bind: (run: () => void) => EffectTask;
+}
+export interface ReactivityOptions {
+    readonly effectScheduler?: EffectScheduler;
+}
+export type WatchSource<T = unknown> = ReadonlySignal<T> | (() => T);
+export interface WatchOptions {
+    readonly immediate?: boolean;
+}
+export type WatchValue<S> = S extends readonly unknown[] ? {
+    [K in keyof S]: S[K] extends WatchSource<infer V> ? V : never;
+} : S extends WatchSource<infer V> ? V : never;
+export type WatchCallback<S> = (value: WatchValue<S>, previous: WatchValue<S> | undefined) => void | Disposer;
+export type EffectFactory = (callback: EffectCallback, onStop?: Disposer) => Disposer;
+export type TrackedOperation = <T>(operation: () => T) => T;
+/**
+ * Финализатор источника: true означает завершение, false — необходимость повторной
+ * попытки после освобождения зависимостей. Не является дублем Disposer.
+ * @internal
+ */
+export type SourceFinalizer = () => boolean;
+/**
+ * Запись произвольного ресурса в списке владельца.
+ * Функция dispose отсоединяет запись перед вызовом пользовательской очистки.
+ * @internal
+ */
+export interface OwnedResource extends ScopeLink<OwnedResource> {
+    dispose: Disposer;
+}
+/**
+ * Границы списка принадлежащих ресурсов. Не описывают граф зависимостей
+ * или дерево исполнения RaphNode.
+ * @internal
+ */
+export interface ScopeChildren<T> {
+    scopeFirstChild?: T;
+    scopeLastChild?: T;
+}
+/**
+ * Встроенные связи ресурса с владельцем и соседями списка.
+ * Не требуют отдельного ScopeNode для каждого эффекта.
+ * @internal
+ */
+export interface ScopeLink<T> {
+    scopeParent?: ScopeChildren<T>;
+    scopePrevious?: T;
+    scopeNext?: T;
+}
+/**
+ * Одна зависимость производителя и потребителя, одновременно включённая
+ * в список потребителей производителя и список зависимостей потребителя.
+ * @internal
+ */
+export interface ReactiveEdge {
+    dep: ReactiveNode;
+    sub: ReactiveNode;
+    prevSub: ReactiveEdge | null;
+    nextSub: ReactiveEdge | null;
+    prevDep: ReactiveEdge | null;
+    nextDep: ReactiveEdge | null;
+}
+/**
+ * Материализованная запись графа: signal, computed либо effect.
+ * Не наследует ScopeNode/RaphNode; поля scope используются только для вложенных эффектов.
+ * Гетерогенные значения графа намеренно имеют внутренний параметр any.
+ * @internal
+ */
+export interface ReactiveNode<T = any> extends ScopeChildren<ReactiveNode>, ScopeLink<ReactiveNode> {
+    flags: number;
+    firstSub: ReactiveEdge | null;
+    lastSub: ReactiveEdge | null;
+    firstDep: ReactiveEdge | null;
+    tailDep: ReactiveEdge | null;
+    depCount: number;
+    subSearchCursor?: ReactiveEdge;
+    evaluate: (() => any) | undefined;
+    cachedValue: T;
+    pendingValue?: T;
+    pendingAuthor?: ReactiveNode | null;
+    effectTask?: EffectTask;
+    onStop?: Disposer;
+}
+/**
+ * Низкоуровневые read/write для raw-дорожки Bench Lab.
+ * Публичный объектный API намеренно не использует этот контракт.
+ * @internal
+ */
+export interface SignalAccess<T> {
+    read: () => T;
+    write: (value: T) => void;
+}
+/**
+ * Низкоуровневый computed с требованием сохранить receiver первого чтения.
+ * @internal
+ */
+export interface ComputedAccess<T> {
+    read: (this: ComputedAccess<unknown>) => T;
+}
+/**
+ * Ленивый raw handle: до первого чтения поля ReactiveNode отсутствуют.
+ * Partial описывает стадию материализации, а не ослабляет контракт готового узла.
+ * @internal
+ */
+export interface ComputedAccessHandle<T> extends Partial<ReactiveNode<T>>, ComputedAccess<T> {
+    evaluate: (() => T) | undefined;
+}
+/**
+ * Ленивый объектный computed: графовые поля становятся обязательными
+ * только после initializeComputedHandle(). Отдельной записи графа не выделяет.
+ * @internal
+ */
+export interface ComputedSourceAccessHandle<T> extends Partial<ReactiveNode<T>>, ReadonlySignal<T> {
+    evaluate: (() => T) | undefined;
+}
+/**
+ * Handle источника вместе с независимым финализатором для владельца.
+ * @internal
+ */
+export interface OwnedSource<T> {
+    source: T;
+    dispose: SourceFinalizer;
+}
+/**
+ * Общие для одного графа адаптеры receiver его handles.
+ * Не хранят состояние алгоритмов: передают исходный handle методам движка.
+ * @internal
+ */
+export interface HandleReaders {
+    initializeComputed: <T>(this: ReadonlySignal<unknown>) => T;
+    initializeRaw: <T>(this: ComputedAccess<unknown>) => T;
+    peek: <T>(this: ReadonlySignal<unknown>) => T;
+}

package/dist/reactivity/watch.d.ts

@@ -0,0 +1,15 @@
+import { Disposer, EffectFactory, TrackedOperation, WatchCallback, WatchOptions, WatchSource } from './types';
+/**
+ * Создаёт watch поверх переданной фабрики эффектов и политики чтения.
+ * Фабрика обязана поддерживать второй аргумент onStop: он связывает окончательную
+ * очистку watch с остановкой эффекта родителем, scope или внешним disposer.
+ * Повторный запуск с равным результатом не вызывает cleanup callback.
+ * @param effect Фабрика с независимым финализатором окончательной остановки.
+ * @param untracked Выполняет callback и cleanup без сбора зависимостей.
+ * @param source Один источник либо список источников.
+ * @param callback Обрабатывает новое и предыдущее значения.
+ * @param options Настройки первоначального вызова.
+ * @param runTracked Оборачивает только чтение selector; используется Runtime.
+ * @internal
+ */
+export declare function watchWithReactivity<S extends WatchSource | readonly WatchSource[]>(effect: EffectFactory, untracked: TrackedOperation, source: S, callback: WatchCallback<S>, options?: WatchOptions, runTracked?: TrackedOperation): Disposer;

package/dist/reactivity.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("./debug/reactivity/scope.cjs");require("./debug/reactivity/watch.cjs");const e=require("./debug/reactivity/engine.cjs");exports.ScopeNode=t.ScopeNode;exports.RaphReactivity=e.RaphReactivity;exports.batch=e.batch;exports.computed=e.computed;exports.effect=e.effect;exports.scope=e.scope;exports.signal=e.signal;exports.untracked=e.untracked;exports.watch=e.watch;

package/dist/reactivity.js

@@ -0,0 +1,14 @@
+import { ScopeNode as c } from "./debug/reactivity/scope.js";
+import "./debug/reactivity/watch.js";
+import { RaphReactivity as a, batch as r, computed as f, effect as i, scope as m, signal as d, untracked as h, watch as n } from "./debug/reactivity/engine.js";
+export {
+  a as RaphReactivity,
+  c as ScopeNode,
+  r as batch,
+  f as computed,
+  i as effect,
+  m as scope,
+  d as signal,
+  h as untracked,
+  n as watch
+};

package/dist/runtime/PathHandle.d.ts

@@ -0,0 +1,72 @@
+import { ParsedDataPath } from '../path/data-path';
+import { PathOptions } from '../path/path.types';
+import { RaphKernel } from '../path/RaphKernel';
+import { RaphReactivity } from '../reactivity/engine';
+import { ReadonlySignal } from '../reactivity/types';
+type PathSignalEngine = Pick<RaphReactivity, '_isTracking' | '_ownedSignal'>;
+/**
+ * Реактивный handle одного canonical path в default E2 data-plane.
+ */
+export declare class PathHandle<T> implements ReadonlySignal<T | undefined> {
+    readonly path: string;
+    readonly options: PathOptions;
+    private _revision;
+    private _disposeRevision;
+    private _isTracking;
+    private _store;
+    private _release;
+    private readonly _masks;
+    private _assertOwnerAlive;
+    private _assertTrackedRead;
+    private _assertWriteAllowed;
+    private _runWrite;
+    private _stop;
+    private _disposed;
+    /**
+     * Создаёт internal path handle и связывает его с runtime lifecycle.
+     * @internal
+     */
+    constructor(store: RaphKernel, parsed: ParsedDataPath, options: PathOptions, release: (handle: PathHandle<unknown>) => void, signals: PathSignalEngine, assertOwnerAlive?: () => void, assertTrackedRead?: () => void, assertWriteAllowed?: () => void, runWrite?: <Result>(operation: () => Result) => Result);
+    /**
+     * Показывает, освобождён ли path handle.
+     */
+    get disposed(): boolean;
+    /**
+     * Читает path с регистрацией реактивной зависимости.
+     */
+    get(): T | undefined;
+    /**
+     * Читает path без регистрации реактивной зависимости.
+     */
+    peek(): T | undefined;
+    /**
+     * Записывает значение path через runtime write policy.
+     */
+    set(value: T): void;
+    /**
+     * Объединяет значение path через runtime write policy.
+     */
+    merge(value: Partial<T>): void;
+    /**
+     * Удаляет значение path через runtime write policy.
+     */
+    delete(): void;
+    /**
+     * Проверяет наличие значения path.
+     */
+    has(): boolean;
+    /**
+     * Отсоединяет Kernel subscription и освобождает reactive revision handle.
+     */
+    dispose(): void;
+    /**
+     * Читает path с регистрацией runtime reactive dependency.
+     * @internal
+     */
+    _getTracked(): T | undefined;
+    private _readTracked;
+    private _observe;
+    private _write;
+    private _assertAlive;
+}
+export {};

package/dist/runtime/RaphDebug.d.ts

@@ -0,0 +1,32 @@
+import { RaphScope } from './RaphScope';
+export interface RaphDebugOwnerSnapshot {
+    readonly id: string;
+    readonly kind: 'scope' | 'node';
+    readonly disposed: boolean;
+    readonly resources: number;
+    readonly sources: number;
+    readonly children: readonly RaphDebugOwnerSnapshot[];
+}
+export interface RaphDebugFrameLoopSnapshot {
+    readonly running: boolean;
+    readonly manual: boolean;
+    readonly leases: number;
+}
+export interface RaphDebugSnapshot {
+    readonly id: string;
+    readonly disposed: boolean;
+    readonly pending: boolean;
+    readonly transactionDepth: number;
+    readonly kernelTransactionDepth: number;
+    readonly owners: number;
+    readonly pathHandles: number;
+    readonly rootScope: RaphDebugOwnerSnapshot;
+    readonly scopes: readonly RaphDebugOwnerSnapshot[];
+    readonly root: RaphDebugOwnerSnapshot;
+    readonly frameLoop: RaphDebugFrameLoopSnapshot;
+}
+export interface RaphRuntimeDebug {
+    snapshot: () => RaphDebugSnapshot;
+    getTree: () => RaphDebugOwnerSnapshot;
+}
+export declare function createOwnerSnapshot(owner: RaphScope): RaphDebugOwnerSnapshot;

package/dist/runtime/RaphFrameLoop.d.ts

@@ -0,0 +1,51 @@
+import { FrameLoopLease } from './phase.types';
+/**
+ * Ленивые frame callbacks не запускаются обычной реактивной работой.
+ */
+export declare class RaphFrameLoop {
+    private readonly _tick;
+    private readonly _leases;
+    private _frameHandle;
+    private _frameHandleKind;
+    private _scheduleToken;
+    private _running;
+    private _manual;
+    /**
+     * Создаёт frame-loop, который запрашивает выполнение runtime pipeline.
+     */
+    constructor(_tick: () => void);
+    /**
+     * Показывает, выполняется ли автоматический frame-loop.
+     */
+    get running(): boolean;
+    /**
+     * Получает lease, удерживающий автоматический frame-loop активным.
+     */
+    acquire(owner: string): FrameLoopLease;
+    /**
+     * Запускает manual lease frame-loop.
+     */
+    start(): void;
+    /**
+     * Останавливает manual lease, не затрагивая внешние leases.
+     */
+    stop(): void;
+    /**
+     * Снимает все leases и отменяет запланированный frame callback.
+     */
+    dispose(): void;
+    /**
+     * Возвращает внутреннее состояние frame-loop для диагностики.
+     * @internal
+     */
+    _debugState(): {
+        running: boolean;
+        manual: boolean;
+        leases: number;
+    };
+    private _onFrame;
+    private _ensureRunning;
+    private _schedule;
+    private _reconcile;
+    private _stop;
+}

package/dist/runtime/RaphNode.d.ts

@@ -0,0 +1,68 @@
+import { DataPathDef } from '../path/path.types';
+import { Disposer } from '../reactivity/types';
+import { RaphObserveDataOptions, RaphTrackOptions } from './phase.types';
+import { RaphRuntime } from './RaphRuntime';
+import { RaphScope } from './RaphScope';
+export interface NodeOptions {
+    readonly id?: string;
+    readonly priority?: number;
+    readonly parent?: RaphNode;
+    readonly meta?: Readonly<Record<string, unknown>>;
+    readonly type?: string;
+}
+/**
+ * Scope с явным parent/children lifecycle.
+ */
+export declare class RaphNode<TApi = unknown> extends RaphScope {
+    priority: number;
+    private _parent;
+    private readonly _children;
+    readonly api: Readonly<TApi>;
+    meta: Record<string, unknown>;
+    type: string;
+    /**
+     * Создаёт node внутри ownership tree указанного runtime.
+     */
+    constructor(parent: RaphNode | RaphRuntime | null, options?: Omit<NodeOptions, 'parent'>, runtime?: RaphRuntime);
+    /**
+     * Возвращает текущего родителя node либо null для root.
+     */
+    get parent(): RaphNode | null;
+    /**
+     * Возвращает снимок непосредственных дочерних nodes.
+     */
+    get children(): readonly RaphNode[];
+    /**
+     * Перемещает node внутри ownership tree одного Runtime.
+     */
+    addChild(node: RaphNode): boolean;
+    /**
+     * Обновляет изменяемые priority, meta и type node.
+     */
+    options(options: Pick<NodeOptions, 'meta' | 'priority' | 'type'>): void;
+    /**
+     * Показывает, ожидает ли node выполнения.
+     */
+    dirty(phase: string): void;
+    /**
+     * Отсоединяет node от ownership tree с заданной lifecycle-семантикой.
+     */
+    remove(): void;
+    /**
+     * Освобождает node вместе с дочерними owners и registrations.
+     */
+    dispose(): void;
+    /**
+     * Регистрирует path observer в phase pipeline.
+     */
+    observeData(masks: DataPathDef | readonly DataPathDef[], options: RaphObserveDataOptions): Disposer;
+    /**
+     * Регистрирует tracked executor указанной phase.
+     */
+    track(masks: DataPathDef | readonly DataPathDef[], options?: RaphTrackOptions): Disposer;
+    /**
+     * Однократно устанавливает immutable API, принадлежащий node.
+     * @internal
+     */
+    _setApi(api: TApi): void;
+}