@vobs/devtools 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,399 @@
+import { RuntimeHydrationMismatch } from '@vobs/runtime';
+import { VobsPlugin } from '@vobs/vobs';
+import { HTTPDebugRequest } from '@vobs/http';
+
+type DependencyEdgeType = 'state-to-effect' | 'state-to-memo' | 'memo-to-effect' | 'memo-to-memo';
+interface ComponentDebugNode {
+    readonly id: string;
+    readonly name: string;
+    readonly ownerId: string;
+    readonly signals: readonly string[];
+    readonly effects: readonly string[];
+    readonly recentUpdates: readonly string[];
+    readonly domUpdates: number;
+    readonly children: readonly ComponentDebugNode[];
+    readonly mounted: boolean;
+}
+interface SignalDebugInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly value: unknown;
+    readonly component: string;
+    readonly subscribers: number;
+    readonly createdAt: number;
+    readonly kind?: 'state' | 'memo';
+}
+interface DebugErrorInfo {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly phase?: string;
+    readonly source?: string;
+    readonly code?: string;
+    readonly hint?: string;
+    readonly cause?: string;
+    readonly fix?: string;
+    readonly location?: {
+        readonly file: string;
+        readonly line: number;
+        readonly column: number;
+    };
+    readonly hydration?: RuntimeHydrationMismatch;
+}
+interface EffectDebugInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly component: string;
+    readonly dependencies: readonly string[];
+    readonly status: 'idle' | 'dirty' | 'running' | 'success' | 'error';
+    readonly executionCount: number;
+    readonly lastExecutionTime: number;
+    readonly lastRunStatus?: 'success' | 'error' | 'cancelled';
+    readonly lastDuration?: number;
+    readonly lastUpdateId?: string;
+    readonly lastError?: DebugErrorInfo;
+    readonly lastDomUpdates?: number;
+}
+interface DependencyEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly type: DependencyEdgeType;
+}
+interface EffectExecutionInfo {
+    readonly effectId: string;
+    readonly component: string;
+    readonly duration: number;
+    readonly domUpdates: number;
+    readonly status?: 'success' | 'error' | 'cancelled';
+    readonly error?: DebugErrorInfo;
+}
+interface DomUpdateInfo {
+    readonly operation: 'text' | 'property' | 'attribute' | 'insert' | 'remove';
+    readonly target: string;
+    readonly parent?: string;
+    readonly key?: string;
+    readonly previousValue?: unknown;
+    readonly nextValue?: unknown;
+    readonly effectId?: string;
+    readonly route?: string;
+    readonly navigationId?: number;
+    readonly requestId?: number;
+}
+interface UpdateTrace {
+    readonly id: string;
+    readonly signalId: string;
+    readonly signalName: string;
+    readonly previousValue: unknown;
+    readonly nextValue: unknown;
+    readonly timestamp: number;
+    readonly effects: readonly EffectExecutionInfo[];
+    readonly affectedSignals: readonly string[];
+    readonly affectedEffects: readonly string[];
+    readonly domUpdates: readonly DomUpdateInfo[];
+    readonly status: 'completed' | 'error' | 'cancelled';
+    readonly error?: DebugErrorInfo;
+    readonly duration: number;
+    readonly route?: string;
+    readonly navigationId?: number;
+    readonly requestIds?: readonly number[];
+}
+type LifecycleEventType = 'owner-created' | 'owner-named' | 'owner-disposed' | 'signal-created' | 'signal-named' | 'signal-changed' | 'signal-disposed' | 'memo-created' | 'memo-invalidated' | 'effect-created' | 'effect-invalidated' | 'effect-run-start' | 'effect-run' | 'effect-disposed';
+interface LifecycleEvent {
+    readonly id: string;
+    readonly type: LifecycleEventType;
+    readonly timestamp: number;
+    readonly targetId: string;
+    readonly name?: string;
+    readonly ownerId?: string;
+    readonly status?: 'success' | 'error' | 'cancelled';
+}
+interface NetworkRequestTrace {
+    readonly id: number;
+    readonly url: string;
+    readonly method: string;
+    readonly status: 'loading' | 'retrying' | 'success' | 'error' | 'cancelled';
+    readonly headers: Readonly<Record<string, string>>;
+    readonly requestBody?: unknown;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly duration?: number;
+    readonly attempt: number;
+    readonly retries: number;
+    readonly responseStatus?: number;
+    readonly responseBody?: unknown;
+    readonly error?: {
+        readonly name: string;
+        readonly message: string;
+    };
+    readonly source?: 'http' | 'router' | 'ssr';
+    readonly test?: boolean;
+    readonly route?: string;
+    readonly navigationId?: number;
+    readonly dataRequestId?: number;
+    readonly environment?: 'client' | 'server';
+}
+type DevToolsErrorPhase = 'effect' | 'network' | 'global' | 'unhandledrejection' | 'route' | 'hydration' | 'render' | 'boundary' | 'application' | 'event';
+type DevToolsErrorOrigin = 'framework' | 'usage' | 'application' | 'unknown';
+type DevToolsErrorRecovery = 'propagated' | 'handled' | 'fallback' | 'retrying' | 'recovered';
+interface DevToolsErrorContext {
+    readonly updateId?: string;
+    readonly effectId?: string;
+    readonly requestId?: number;
+    readonly navigationId?: number;
+    readonly route?: string;
+    readonly source?: string;
+    readonly ownerId?: string;
+    readonly component?: string;
+    readonly origin?: DevToolsErrorOrigin;
+    readonly code?: string;
+    readonly hint?: string;
+    readonly handled?: boolean;
+    readonly recovery?: DevToolsErrorRecovery;
+}
+interface DevToolsErrorTrace extends DebugErrorInfo {
+    readonly id: number;
+    readonly phase: DevToolsErrorPhase;
+    readonly firstOccurredAt: number;
+    readonly lastOccurredAt: number;
+    readonly count: number;
+    readonly phases: readonly DevToolsErrorPhase[];
+    readonly origin: DevToolsErrorOrigin;
+    readonly handled: boolean;
+    readonly recovery: DevToolsErrorRecovery;
+    readonly updateId?: string;
+    readonly effectId?: string;
+    readonly requestId?: number;
+    readonly navigationId?: number;
+    readonly route?: string;
+    readonly ownerId?: string;
+    readonly component?: string;
+}
+interface DevToolsCollectionState {
+    readonly paused: boolean;
+}
+interface DevToolsPrivacyOptions {
+    /** Additional case-insensitive header names or fragments to omit. */
+    readonly redactedHeaders?: readonly string[];
+    /** Object keys whose values are replaced in captured/exported values. */
+    readonly redactedFields?: readonly string[];
+    /** Replace DOM values in diagnostics with the configured replacement. */
+    readonly redactDomValues?: boolean;
+    readonly replacement?: string;
+}
+interface DevToolsPerformanceEntry {
+    readonly kind: 'update' | 'effect' | 'request';
+    readonly id: string | number;
+    readonly label: string;
+    readonly duration: number;
+    readonly timestamp: number;
+    readonly status: string;
+}
+interface DevToolsInspector {
+    readonly label?: string;
+    inspect(value: unknown): unknown;
+}
+interface DevToolsTimeline {
+    readonly label?: string;
+    readonly getEvents?: () => readonly DevToolsTimelineEvent[];
+}
+interface DevToolsTimelineEvent {
+    readonly id: string;
+    readonly timestamp: number;
+    readonly title: string;
+    readonly data?: unknown;
+}
+interface DevToolsMetric {
+    readonly label?: string;
+    read(): number | string;
+}
+interface DevToolsExtensionSnapshot {
+    readonly inspectors: readonly string[];
+    readonly timelines: readonly string[];
+    readonly timelineEvents: Readonly<Record<string, readonly DevToolsTimelineEvent[]>>;
+    readonly metrics: Readonly<Record<string, number | string>>;
+}
+interface DevToolsDiagnosticSnapshot {
+    readonly version: 1;
+    readonly exportedAt: number;
+    readonly updates: readonly UpdateTrace[];
+    readonly lifecycle: readonly LifecycleEvent[];
+    readonly network: readonly NetworkRequestTrace[];
+    readonly errors: readonly DevToolsErrorTrace[];
+    readonly performance: PerformanceMetrics;
+    readonly memory: MemorySnapshot;
+    readonly extensions: DevToolsExtensionSnapshot;
+}
+interface DevToolsSSRRequestSnapshot {
+    readonly version: 1;
+    readonly environment: 'server';
+    readonly requests: readonly HTTPDebugRequest[];
+}
+type DevToolsSelection = {
+    readonly type: 'component';
+    readonly id: string;
+} | {
+    readonly type: 'signal';
+    readonly id: string;
+} | {
+    readonly type: 'effect';
+    readonly id: string;
+} | {
+    readonly type: 'update';
+    readonly id: string;
+} | {
+    readonly type: 'request';
+    readonly id: number;
+} | {
+    readonly type: 'error';
+    readonly id: number;
+};
+declare const DEVTOOLS_REACTIVITY_EVENTS: readonly ["owner-created", "owner-named", "owner-disposed", "signal-created", "signal-named", "signal-update", "signal-disposed", "effect-created", "effect-invalidated", "effect-run-start", "effect-run", "effect-disposed", "memo-created", "memo-update", "update"];
+declare const DEVTOOLS_EVENTS: readonly ["owner-created", "owner-named", "owner-disposed", "signal-created", "signal-named", "signal-update", "signal-disposed", "effect-created", "effect-invalidated", "effect-run-start", "effect-run", "effect-disposed", "memo-created", "memo-update", "update", "lifecycle", "dom-update", "network-request", "router", "error", "collection", "collection-cleared", "extension"];
+interface PerformanceMetrics {
+    readonly updateCount: number;
+    readonly averageUpdateDuration: number;
+    readonly slowUpdateCount: number;
+    readonly effectExecutionCount: number;
+    readonly slowEffectCount: number;
+    readonly slowRequestCount: number;
+    readonly maxUpdateDuration: number;
+    readonly maxEffectDuration: number;
+    readonly maxRequestDuration: number;
+}
+interface MemorySnapshot {
+    readonly signalCount: number;
+    readonly effectCount: number;
+    readonly ownerCount: number;
+    readonly dependencyEdgeCount: number;
+    readonly leakedOwners: number;
+}
+interface DevToolsTarget {
+    __VOBS_DEVTOOLS__?: DevToolsAPI;
+    addEventListener?: (type: string, listener: (...args: any[]) => void) => void;
+    removeEventListener?: (type: string, listener: (...args: any[]) => void) => void;
+}
+interface DevToolsOptions {
+    readonly expose?: boolean;
+    readonly target?: DevToolsTarget;
+    readonly maxUpdates?: number;
+    readonly slowUpdateThreshold?: number;
+    readonly privacy?: DevToolsPrivacyOptions;
+    /** Explicit opt-in for state-changing debug actions. Disabled by default. */
+    readonly allowMutations?: boolean;
+    /** Optional Router-like source for associating navigation/data events. */
+    readonly router?: DevToolsRouterSource;
+}
+interface DevToolsRouterSource {
+    readonly devtools: {
+        subscribe(event: string, callback: (payload: unknown) => void): () => void;
+    };
+}
+interface DevToolsAPI {
+    getComponentTree(): readonly ComponentDebugNode[];
+    getComponent(ownerId: string): ComponentDebugNode | null;
+    getSignals(): readonly SignalDebugInfo[];
+    getSignal(signalId: string): SignalDebugInfo | null;
+    canMutate(): boolean;
+    setSignalValue(signalId: string, value: unknown): boolean;
+    getDependencies(signalId: string): readonly DependencyEdge[];
+    getDependents(subscriberId: string): readonly DependencyEdge[];
+    getEffects(): readonly EffectDebugInfo[];
+    getUpdates(): readonly UpdateTrace[];
+    getLifecycleEvents(): readonly LifecycleEvent[];
+    getNetworkRequests(): readonly NetworkRequestTrace[];
+    importSSRRequests(snapshot: unknown): void;
+    getRouterContext(): DevToolsRouterContext | null;
+    attachRouter(router: DevToolsRouterSource): () => void;
+    getErrors(): readonly DevToolsErrorTrace[];
+    getPerformanceEntries(): readonly DevToolsPerformanceEntry[];
+    getCollectionState(): DevToolsCollectionState;
+    setCollectionPaused(paused: boolean): void;
+    clearUpdates(): void;
+    clearNetworkRequests(): void;
+    clearErrors(): void;
+    clearLifecycleEvents(): void;
+    reportError(phase: DevToolsErrorPhase, error: unknown, context?: DevToolsErrorContext): void;
+    getPerformanceMetrics(): PerformanceMetrics;
+    takeMemorySnapshot(): MemorySnapshot;
+    exportDiagnostics(): DevToolsDiagnosticSnapshot;
+    importDiagnostics(snapshot: unknown): void;
+    registerInspector(id: string, inspector: DevToolsInspector): () => void;
+    registerTimeline(id: string, timeline?: DevToolsTimeline): () => void;
+    registerMetric(id: string, metric: DevToolsMetric): () => void;
+    getExtensionSnapshot(): DevToolsExtensionSnapshot;
+    inspectExtension(id: string, value: unknown): unknown;
+    onUpdate(callback: (trace: UpdateTrace) => void): () => void;
+    subscribe(event: string, callback: (...args: any[]) => void): () => void;
+    dispose(): void;
+}
+interface DevToolsRouterContext {
+    readonly route?: string;
+    readonly navigationId?: number;
+    readonly navigationStatus?: string;
+    readonly dataRequests: readonly {
+        readonly id: number;
+        readonly kind: string;
+        readonly key: string;
+        readonly route?: string;
+        readonly status: string;
+        readonly startedAt?: number;
+        readonly endedAt?: number;
+        readonly duration?: number;
+        readonly navigationId?: number;
+        readonly trigger?: string;
+        readonly result?: unknown;
+        readonly error?: string;
+        readonly environment?: 'client' | 'server';
+    }[];
+}
+interface DevToolsWireRequest {
+    readonly source: 'vobs-devtools';
+    readonly type: 'request';
+    readonly id: string;
+    readonly method: string;
+    readonly args?: readonly unknown[];
+}
+interface DevToolsWireResponse {
+    readonly source: 'vobs-devtools';
+    readonly type: 'response';
+    readonly id: string;
+    readonly ok: boolean;
+    readonly result?: unknown;
+    readonly error?: string;
+}
+interface DevToolsWireEvent {
+    readonly source: 'vobs-devtools';
+    readonly type: 'event';
+    readonly event: string;
+    readonly payload: unknown;
+}
+interface DevToolsMessageTarget {
+    addEventListener(type: string, listener: (event: DevToolsMessageEvent) => void): void;
+    removeEventListener(type: string, listener: (event: DevToolsMessageEvent) => void): void;
+    postMessage(message: unknown, targetOrigin: string): void;
+}
+interface DevToolsMessageEvent {
+    readonly data?: unknown;
+    readonly source?: unknown;
+}
+interface DevToolsBridgeOptions {
+    readonly target?: DevToolsMessageTarget;
+    readonly api?: DevToolsAPI | null;
+}
+interface DevToolsPluginOptions extends DevToolsOptions {
+    readonly enabled?: boolean;
+}
+declare function createDevTools(options?: DevToolsOptions): DevToolsAPI;
+declare function enableDevTools(options?: DevToolsOptions): DevToolsAPI;
+declare function disableDevTools(): void;
+declare function getDevTools(): DevToolsAPI | null;
+/** Connects a browser panel through a small postMessage protocol. */
+declare function connectDevTools(options?: DevToolsBridgeOptions): () => void;
+declare function devtoolsPlugin(options?: DevToolsPluginOptions): VobsPlugin;
+declare global {
+    interface Window {
+        __VOBS_DEVTOOLS__?: DevToolsAPI;
+    }
+}
+
+export { type ComponentDebugNode, DEVTOOLS_EVENTS, DEVTOOLS_REACTIVITY_EVENTS, type DebugErrorInfo, type DependencyEdge, type DependencyEdgeType, type DevToolsAPI, type DevToolsBridgeOptions, type DevToolsCollectionState, type DevToolsDiagnosticSnapshot, type DevToolsErrorContext, type DevToolsErrorOrigin, type DevToolsErrorPhase, type DevToolsErrorRecovery, type DevToolsErrorTrace, type DevToolsExtensionSnapshot, type DevToolsInspector, type DevToolsMessageEvent, type DevToolsMessageTarget, type DevToolsMetric, type DevToolsOptions, type DevToolsPerformanceEntry, type DevToolsPluginOptions, type DevToolsPrivacyOptions, type DevToolsRouterContext, type DevToolsRouterSource, type DevToolsSSRRequestSnapshot, type DevToolsSelection, type DevToolsTarget, type DevToolsTimeline, type DevToolsTimelineEvent, type DevToolsWireEvent, type DevToolsWireRequest, type DevToolsWireResponse, type DomUpdateInfo, type EffectDebugInfo, type EffectExecutionInfo, type LifecycleEvent, type LifecycleEventType, type MemorySnapshot, type NetworkRequestTrace, type PerformanceMetrics, type SignalDebugInfo, type UpdateTrace, connectDevTools, createDevTools, devtoolsPlugin, disableDevTools, enableDevTools, getDevTools };