bippy 0.3.34 → 0.5.0

package/README.md

@@ -20,11 +20,13 @@ by default, you cannot access react internals. bippy bypasses this by "pretendin
 ```jsx
 import { onCommitFiberRoot, traverseFiber } from 'bippy'; // must be imported BEFORE react
 
-onCommitFiberRoot((root) => {
-  traverseFiber(root.current, (fiber) => {
-    // prints every fiber in the current React tree
-    console.log('fiber:', fiber);
-  });
+instrument({
+  onCommitFiberRoot: (root) => {
+    traverseFiber(root.current, (fiber) => {
+      // prints every fiber in the current React tree
+      console.log('fiber:', fiber);
+    });
+  },
 });
 ```
 
@@ -244,7 +246,7 @@ traverseProps(fiber, (propName, next, prev) => {
 
 ### traverseState
 
-traverses the state (useState, useReducer, etc.) and effects that set state of a fiber.
+traverses the state (`useState`, `useReducer`, etc.) and effects that set state of a fiber.
 
 ```typescript
 import { traverseState } from 'bippy';
@@ -258,7 +260,7 @@ traverseState(fiber, (next, prev) => {
 
 ### traverseContexts
 
-traverses the contexts (useContext) of a fiber.
+traverses the contexts (`useContext`) of a fiber.
 
 ```typescript
 import { traverseContexts } from 'bippy';
@@ -464,7 +466,7 @@ the function accepts a fiber and a partial object containing the props to overri
 
 ### overrideHookState
 
-overrides hook state (usestate, usereducer, etc.) at runtime by hook id.
+overrides hook state (`useState`, `useReducer`, etc.) at runtime by hook id.
 
 ```typescript
 import { overrideHookState } from 'bippy';
@@ -505,6 +507,35 @@ overrideContext(fiber, ThemeContext, 'dark');
 
 the function traverses up the fiber tree to find the context provider matching the provided context type and overrides its value.
 
+### getSource
+
+gets the source code location of a composite fiber.
+
+```typescript
+import { getSource } from 'bippy/source';
+
+// random fiber on the DOM
+const hostFiber = getFiberFromHostInstance(document.querySelector('div'));
+
+// get nearest composite fiber up the tree
+const compositeFiber = traverseFiber(
+  hostFiber,
+  (fiber) => {
+    if (isCompositeFiber(fiber)) {
+      return fiber;
+    }
+  },
+  true,
+);
+
+const source = await getSource(compositeFiber);
+// {
+//   columnNumber: 12,
+//   fileName: 'path/to/file.tsx',
+//   lineNumber: 12,
+// }
+```
+
 ## examples
 
 the best way to understand bippy is to [read the source code](https://github.com/aidenybai/bippy/blob/main/src/core.ts). here are some examples of how you can use it:

package/dist/index-BWzt7MZs.d.cts

@@ -0,0 +1,331 @@
+import * as React$1 from "react";
+import { BundleType, ComponentSelector, DevToolsConfig, Fiber, FiberRoot, Flags, HasPseudoClassSelector, HookType, HostConfig, LanePriority, Lanes, MutableSource, OpaqueHandle, OpaqueRoot, React$AbstractComponent, ReactConsumer, ReactContext, ReactPortal, ReactProvider, ReactProviderType, RefObject, RoleSelector, RootTag, Selector, Source, SuspenseHydrationCallbacks, TestNameSelector, TextSelector, Thenable, TransitionTracingCallbacks, TypeOfMode, WorkTag } from "react-reconciler";
+
+//#region src/types.d.ts
+interface ContextDependency<T> {
+  context: ReactContext<T>;
+  memoizedValue: T;
+  next: ContextDependency<unknown> | null;
+  observedBits: number;
+}
+interface Dependencies {
+  firstContext: ContextDependency<unknown> | null;
+  lanes: Lanes;
+}
+interface Effect {
+  [key: string]: unknown;
+  create: (...args: unknown[]) => unknown;
+  deps: null | unknown[];
+  destroy: ((...args: unknown[]) => unknown) | null;
+  next: Effect | null;
+  tag: number;
+}
+interface Family {
+  current: unknown;
+}
+/**
+ * Represents a react-internal Fiber node.
+ */
+type Fiber$1<T = any> = Omit<Fiber, 'alternate' | 'child' | 'dependencies' | 'memoizedProps' | 'memoizedState' | 'pendingProps' | 'return' | 'sibling' | 'stateNode' | 'updateQueue'> & {
+  _debugInfo?: Array<{
+    debugLocation?: unknown;
+    env?: string;
+    name?: string;
+  }>;
+  _debugOwner?: Fiber$1;
+  _debugSource?: {
+    columnNumber?: number;
+    fileName: string;
+    lineNumber: number;
+  };
+  _debugStack?: Error & {
+    stack: string;
+  };
+  alternate: Fiber$1 | null;
+  child: Fiber$1 | null;
+  dependencies: Dependencies | null;
+  memoizedProps: Props;
+  memoizedState: MemoizedState;
+  pendingProps: Props;
+  return: Fiber$1 | null;
+  sibling: Fiber$1 | null;
+  stateNode: T;
+  updateQueue: {
+    [key: string]: unknown;
+    lastEffect: Effect | null;
+  };
+};
+interface MemoizedState {
+  [key: string]: unknown;
+  memoizedState: unknown;
+  next: MemoizedState | null;
+}
+interface Props {
+  [key: string]: unknown;
+}
+interface ReactDevToolsGlobalHook {
+  _instrumentationIsActive?: boolean;
+  _instrumentationSource?: string;
+  checkDCE: (fn: unknown) => void;
+  hasUnsupportedRendererAttached: boolean;
+  inject: (renderer: ReactRenderer) => number;
+  on: () => void;
+  onCommitFiberRoot: (rendererID: number, root: FiberRoot, priority: number | void) => void;
+  onCommitFiberUnmount: (rendererID: number, fiber: Fiber$1) => void;
+  onPostCommitFiberRoot: (rendererID: number, root: FiberRoot) => void;
+  renderers: Map<number, ReactRenderer>;
+  supportsFiber: boolean;
+  supportsFlight: boolean;
+}
+interface ReactRenderer {
+  bundleType: 0 | 1;
+  currentDispatcherRef: any;
+  findFiberByHostInstance?: (hostInstance: unknown) => Fiber$1 | null;
+  getCurrentFiber?: (fiber: Fiber$1) => Fiber$1 | null;
+  overrideContext?: (fiber: Fiber$1, contextType: unknown, path: string[], value: unknown) => void;
+  overrideHookState?: (fiber: Fiber$1, id: string, path: string[], value: unknown) => void;
+  overrideHookStateDeletePath?: (fiber: Fiber$1, id: number, path: Array<number | string>) => void;
+  overrideHookStateRenamePath?: (fiber: Fiber$1, id: number, oldPath: Array<number | string>, newPath: Array<number | string>) => void;
+  overrideProps?: (fiber: Fiber$1, path: string[], value: unknown) => void;
+  overridePropsDeletePath?: (fiber: Fiber$1, path: Array<number | string>) => void;
+  overridePropsRenamePath?: (fiber: Fiber$1, oldPath: Array<number | string>, newPath: Array<number | string>) => void;
+  reconcilerVersion: string;
+  rendererPackageName: string;
+  scheduleRefresh?: (root: FiberRoot, update: {
+    staleFamilies: Set<Family>;
+    updatedFamilies: Set<Family>;
+  }) => void;
+  scheduleRoot?: (root: FiberRoot, element: React.ReactNode) => void;
+  scheduleUpdate?: (fiber: Fiber$1) => void;
+  setErrorHandler?: (newShouldErrorImpl: (fiber: Fiber$1) => boolean) => void;
+  setRefreshHandler?: (handler: ((fiber: Fiber$1) => Family | null) | null) => void;
+  setSuspenseHandler?: (newShouldSuspendImpl: (suspenseInstance: unknown) => void) => void;
+  version: string;
+}
+declare global {
+  var __REACT_DEVTOOLS_GLOBAL_HOOK__: ReactDevToolsGlobalHook | undefined;
+} //#endregion
+//#region src/rdt-hook.d.ts
+declare const version: string | undefined;
+declare const BIPPY_INSTRUMENTATION_STRING: string;
+declare const isRealReactDevtools: (rdtHook?: ReactDevToolsGlobalHook) => boolean;
+declare const isReactRefresh: (rdtHook?: ReactDevToolsGlobalHook) => boolean;
+declare const _renderers: Set<ReactRenderer>;
+declare const installRDTHook: (onActive?: () => unknown) => ReactDevToolsGlobalHook;
+declare const patchRDTHook: (onActive?: () => unknown) => void;
+declare const hasRDTHook: () => boolean;
+/**
+ * Returns the current React DevTools global hook.
+ */
+declare const getRDTHook: (onActive?: () => unknown) => ReactDevToolsGlobalHook;
+declare const isClientEnvironment: () => boolean;
+/**
+ * Usually used purely for side effect
+ */
+declare const safelyInstallRDTHook: () => void;
+
+//#endregion
+//#region src/core.d.ts
+declare const FunctionComponentTag = 0;
+declare const ClassComponentTag = 1;
+declare const HostRootTag = 3;
+declare const HostComponentTag = 5;
+declare const HostTextTag = 6;
+declare const FragmentTag = 7;
+declare const ContextConsumerTag = 9;
+declare const ForwardRefTag = 11;
+declare const SuspenseComponentTag = 13;
+declare const MemoComponentTag = 14;
+declare const SimpleMemoComponentTag = 15;
+declare const LazyComponentTag = 16;
+declare const DehydratedSuspenseComponentTag = 18;
+declare const SuspenseListComponentTag = 19;
+declare const OffscreenComponentTag = 22;
+declare const LegacyHiddenComponentTag = 23;
+declare const HostHoistableTag = 26;
+declare const HostSingletonTag = 27;
+declare const ActivityComponentTag = 28;
+declare const ViewTransitionComponentTag = 30;
+declare const CONCURRENT_MODE_NUMBER = 60111;
+declare const ELEMENT_TYPE_SYMBOL_STRING = "Symbol(react.element)";
+declare const TRANSITIONAL_ELEMENT_TYPE_SYMBOL_STRING = "Symbol(react.transitional.element)";
+declare const CONCURRENT_MODE_SYMBOL_STRING = "Symbol(react.concurrent_mode)";
+declare const DEPRECATED_ASYNC_MODE_SYMBOL_STRING = "Symbol(react.async_mode)";
+/**
+ * Returns `true` if object is a React Element.
+ *
+ * @see https://react.dev/reference/react/isValidElement
+ */
+declare const isValidElement: (element: unknown) => element is React$1.ReactElement;
+/**
+ * Returns `true` if object is a React Fiber.
+ */
+declare const isValidFiber: (fiber: unknown) => fiber is Fiber$1;
+/**
+ * Returns `true` if fiber is a host fiber. Host fibers are DOM nodes in react-dom, `View` in react-native, etc.
+ *
+ * @see https://reactnative.dev/architecture/glossary#host-view-tree-and-host-view
+ */
+declare const isHostFiber: (fiber: Fiber$1) => boolean;
+/**
+ * Returns `true` if fiber is a composite fiber. Composite fibers are fibers that can render (like functional components, class components, etc.)
+ *
+ * @see https://reactnative.dev/architecture/glossary#react-composite-components
+ */
+declare const isCompositeFiber: (fiber: Fiber$1) => boolean;
+/**
+ * Returns `true` if the object is a {@link Fiber}
+ */
+declare const isFiber: (maybeFiber: unknown) => maybeFiber is Fiber$1;
+/**
+ * Returns `true` if the two {@link Fiber}s are the same reference
+ */
+declare const areFiberEqual: (fiberA: Fiber$1, fiberB: Fiber$1) => boolean;
+/**
+ * Traverses up or down a {@link Fiber}'s contexts, return `true` to stop and select the current and previous context value.
+ */
+declare const traverseContexts: (fiber: Fiber$1, selector: (nextValue: ContextDependency<unknown> | null | undefined, prevValue: ContextDependency<unknown> | null | undefined) => boolean | void) => boolean;
+/**
+ * Traverses up or down a {@link Fiber}'s states, return `true` to stop and select the current and previous state value. This stores both state values and effects.
+ */
+declare const traverseState: (fiber: Fiber$1, selector: (nextValue: MemoizedState | null | undefined, prevValue: MemoizedState | null | undefined) => boolean | void) => boolean;
+/**
+ * Traverses up or down a {@link Fiber}'s props, return `true` to stop and select the current and previous props value.
+ */
+declare const traverseProps: (fiber: Fiber$1, selector: (propName: string, nextValue: unknown, prevValue: unknown) => boolean | void) => boolean;
+/**
+ * Returns `true` if the {@link Fiber} has rendered. Note that this does not mean the fiber has rendered in the current commit, just that it has rendered in the past.
+ */
+declare const didFiberRender: (fiber: Fiber$1) => boolean;
+/**
+ * Returns `true` if the {@link Fiber} has committed. Note that this does not mean the fiber has committed in the current commit, just that it has committed in the past.
+ */
+declare const didFiberCommit: (fiber: Fiber$1) => boolean;
+/**
+ * Returns all host {@link Fiber}s that have committed and rendered.
+ */
+declare const getMutatedHostFibers: (fiber: Fiber$1) => Fiber$1[];
+/**
+ * Returns the stack of {@link Fiber}s from the current fiber to the root fiber.
+ *
+ * @example
+ * ```ts
+ * [fiber, fiber.return, fiber.return.return, ...]
+ * ```
+ */
+declare const getFiberStack: (fiber: Fiber$1) => Fiber$1[];
+/**
+ * Returns `true` if the {@link Fiber} should be filtered out during reconciliation.
+ */
+declare const shouldFilterFiber: (fiber: Fiber$1) => boolean;
+/**
+ * Returns the nearest host {@link Fiber} to the current {@link Fiber}.
+ */
+declare const getNearestHostFiber: (fiber: Fiber$1, ascending?: boolean) => Fiber$1 | null;
+/**
+ * Returns all host {@link Fiber}s in the tree that are associated with the current {@link Fiber}.
+ */
+declare const getNearestHostFibers: (fiber: Fiber$1) => Fiber$1[];
+/**
+ * Traverses up or down a {@link Fiber}, return `true` to stop and select a node.
+ */
+declare function traverseFiber(fiber: Fiber$1 | null, selector: (node: Fiber$1) => boolean | void, ascending?: boolean): Fiber$1 | null;
+declare function traverseFiber(fiber: Fiber$1 | null, selector: (node: Fiber$1) => Promise<boolean | void>, ascending?: boolean): Promise<Fiber$1 | null>;
+declare const traverseFiberSync: (fiber: Fiber$1 | null, selector: (node: Fiber$1) => boolean | void, ascending?: boolean) => Fiber$1 | null;
+declare const traverseFiberAsync: (fiber: Fiber$1 | null, selector: (node: Fiber$1) => Promise<boolean | void>, ascending?: boolean) => Promise<Fiber$1 | null>;
+/**
+ * Returns the timings of the {@link Fiber}.
+ *
+ * @example
+ * ```ts
+ * const { selfTime, totalTime } = getTimings(fiber);
+ * console.log(selfTime, totalTime);
+ * ```
+ */
+declare const getTimings: (fiber?: Fiber$1 | null) => {
+  selfTime: number;
+  totalTime: number;
+};
+/**
+ * Returns `true` if the {@link Fiber} uses React Compiler's memo cache.
+ */
+declare const hasMemoCache: (fiber: Fiber$1) => boolean;
+/**
+ * Returns the type (e.g. component definition) of the {@link Fiber}
+ */
+declare const getType: (type: unknown) => null | React$1.ComponentType<unknown>;
+/**
+ * Returns the display name of the {@link Fiber} type.
+ */
+declare const getDisplayName: (type: unknown) => null | string;
+/**
+ * Returns the build type of the React renderer.
+ */
+declare const detectReactBuildType: (renderer: ReactRenderer) => "development" | "production";
+/**
+ * Returns `true` if bippy's instrumentation is active.
+ */
+declare const isInstrumentationActive: () => boolean;
+/**
+ * Returns the latest fiber (since it may be double-buffered).
+ */
+declare const getLatestFiber: (fiber: Fiber$1) => Fiber$1;
+type RenderHandler = <S>(fiber: Fiber$1, phase: RenderPhase, state?: S) => unknown;
+type RenderPhase = 'mount' | 'unmount' | 'update';
+declare const fiberIdMap: WeakMap<Fiber$1, number>;
+declare const setFiberId: (fiber: Fiber$1, id?: number) => void;
+declare const getFiberId: (fiber: Fiber$1) => number;
+declare const mountFiberRecursively: (onRender: RenderHandler, firstChild: Fiber$1, traverseSiblings: boolean) => void;
+declare const updateFiberRecursively: (onRender: RenderHandler, nextFiber: Fiber$1, prevFiber: Fiber$1, parentFiber: Fiber$1 | null) => void;
+declare const unmountFiber: (onRender: RenderHandler, fiber: Fiber$1) => void;
+declare const unmountFiberChildrenRecursively: (onRender: RenderHandler, fiber: Fiber$1) => void;
+/**
+ * Creates a fiber visitor function. Must pass a fiber root and a render handler.
+ * @example
+ * traverseRenderedFibers(root, (fiber, phase) => {
+ *   console.log(phase)
+ * })
+ */
+declare const traverseRenderedFibers: (root: FiberRoot, onRender: RenderHandler) => void;
+declare const injectOverrideMethods: () => {
+  overrideContext: ((fiber: Fiber$1, contextType: unknown, path: string[], value: unknown) => void) | null | undefined;
+  overrideHookState: ((fiber: Fiber$1, id: string, path: string[], value: unknown) => void) | null | undefined;
+  overrideProps: ((fiber: Fiber$1, path: string[], value: unknown) => void) | null | undefined;
+} | null | undefined;
+declare const overrideProps: (fiber: Fiber$1, partialValue: Record<string, unknown>) => void;
+declare const overrideHookState: (fiber: Fiber$1, id: number, partialValue: Record<string, unknown>) => void;
+declare const overrideContext: (fiber: Fiber$1, contextType: unknown, partialValue: Record<string, unknown>) => void;
+interface InstrumentationOptions {
+  name?: string;
+  onActive?: () => unknown;
+  onCommitFiberRoot?: (rendererID: number, root: FiberRoot, priority: number | void) => unknown;
+  onCommitFiberUnmount?: (rendererID: number, fiber: Fiber$1) => unknown;
+  onPostCommitFiberRoot?: (rendererID: number, root: FiberRoot) => unknown;
+  onScheduleFiberRoot?: (rendererID: number, root: FiberRoot, children: React$1.ReactNode) => unknown;
+}
+/**
+ * Instruments the DevTools hook.
+ * @example
+ * const hook = instrument({
+ *   onActive() {
+ *     console.log('initialized');
+ *   },
+ *   onCommitFiberRoot(rendererID, root) {
+ *     console.log('fiberRoot', root.current)
+ *   },
+ * });
+ */
+declare const instrument: (options: InstrumentationOptions) => ReactDevToolsGlobalHook;
+declare const getFiberFromHostInstance: <T>(hostInstance: T) => Fiber$1 | null;
+declare const INSTALL_ERROR: Error;
+declare const _fiberRoots: Set<any>;
+declare const secure: (options: InstrumentationOptions, secureOptions?: {
+  dangerouslyRunInProduction?: boolean;
+  installCheckTimeout?: number;
+  isProduction?: boolean;
+  minReactMajorVersion?: number;
+  onError?: (error?: unknown) => unknown;
+}) => InstrumentationOptions;
+
+//#endregion
+export { ActivityComponentTag, BIPPY_INSTRUMENTATION_STRING, BundleType, CONCURRENT_MODE_NUMBER, CONCURRENT_MODE_SYMBOL_STRING, ClassComponentTag, ComponentSelector, ContextConsumerTag, ContextDependency, DEPRECATED_ASYNC_MODE_SYMBOL_STRING, DehydratedSuspenseComponentTag, Dependencies, DevToolsConfig, ELEMENT_TYPE_SYMBOL_STRING, Effect, Family, Fiber$1 as Fiber, FiberRoot, Flags, ForwardRefTag, FragmentTag, FunctionComponentTag, HasPseudoClassSelector, HookType, HostComponentTag, HostConfig, HostHoistableTag, HostRootTag, HostSingletonTag, HostTextTag, INSTALL_ERROR, InstrumentationOptions, LanePriority, Lanes, LazyComponentTag, LegacyHiddenComponentTag, MemoComponentTag, MemoizedState, MutableSource, OffscreenComponentTag, OpaqueHandle, OpaqueRoot, Props, React$AbstractComponent, ReactConsumer, ReactContext, ReactDevToolsGlobalHook, ReactPortal, ReactProvider, ReactProviderType, ReactRenderer, RefObject, RenderHandler, RenderPhase, RoleSelector, RootTag, Selector, SimpleMemoComponentTag, Source, SuspenseComponentTag, SuspenseHydrationCallbacks, SuspenseListComponentTag, TRANSITIONAL_ELEMENT_TYPE_SYMBOL_STRING, TestNameSelector, TextSelector, Thenable, TransitionTracingCallbacks, TypeOfMode, ViewTransitionComponentTag, WorkTag, _fiberRoots, _renderers, areFiberEqual, detectReactBuildType, didFiberCommit, didFiberRender, fiberIdMap, getDisplayName, getFiberFromHostInstance, getFiberId, getFiberStack, getLatestFiber, getMutatedHostFibers, getNearestHostFiber, getNearestHostFibers, getRDTHook, getTimings, getType, hasMemoCache, hasRDTHook, injectOverrideMethods, installRDTHook, instrument, isClientEnvironment, isCompositeFiber, isFiber, isHostFiber, isInstrumentationActive, isReactRefresh, isRealReactDevtools, isValidElement, isValidFiber, mountFiberRecursively, overrideContext, overrideHookState, overrideProps, patchRDTHook, safelyInstallRDTHook, secure, setFiberId, shouldFilterFiber, traverseContexts, traverseFiber, traverseFiberAsync, traverseFiberSync, traverseProps, traverseRenderedFibers, traverseState, unmountFiber, unmountFiberChildrenRecursively, updateFiberRecursively, version };