bippy 0.1.0 → 0.1.1

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2024 Aiden Bai
+Copyright 2024 Aiden Bai, Million Software, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -9,26 +9,46 @@
 [![version](https://img.shields.io/npm/v/bippy?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/bippy)
 [![downloads](https://img.shields.io/npm/dt/bippy.svg?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/bippy)
 
-a hacky way to get fibers from react. <small>used internally by [`react-scan`](https://github.com/aidenybai/react-scan)</small>
+bippy is a toolkit to **hack into react internals**
 
-bippy _attempts\*_ to solve two problems:
+by default, you cannot access react internals. bippy bypasses this by "pretending" to be react devtools, giving you access to the fiber tree and other internals.
 
-1. it's not possible to write instrumentation for React without the end user changing code
-2. doing anything useful with fibers requires you to know react source code very well
+- works outside of react – no react code modification needed
+- utility functions that work across modern react (v17-19)
+- no prior react source code knowledge required
 
-bippy allows you to access fiber information from outside of react and provides friendly low-level utils for interacting with fibers.
+```jsx
+import { instrument, traverseFiber } from 'bippy';
 
-<sub><sup>\*disclaimer: "attempt" used loosely, i highly recommend not relying on this in production</sub></sup>
+instrument({
+  onCommitFiberRoot(_, root) {
+    traverseFiber(root.current, (fiber) => {
+      // will print every fiber in the current React tree
+      console.log('fiber:', fiber);
+    });
+  },
+});
+```
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="https://bippy.dev"><b>open live demo ↗</b></a>
+      </td>
+    </tr>
+  </tbody>
+</table>
 
-## how it works
+## how it works & motivation
 
-bippy allows you to **access** and **use** fibers from outside of react.
+bippy allows you to **access** and **use** react fibers **outside** of react components.
 
 a react fiber is a "unit of execution." this means react will do something based on the data in a fiber. each fiber either represents a composite (function/class component) or a host (dom element).
 
 > here is a [live visualization](https://jser.pro/ddir/rie?reactVersion=18.3.1&snippetKey=hq8jm2ylzb9u8eh468) of what the fiber tree looks like, and here is a [deep dive article](https://jser.dev/2023-07-18-how-react-rerenders/).
 
-fibers are useful because they contain information about the React app (component props, state, contexts, etc.). a simplified version of a fiber looks roughly like this:
+fibers are useful because they contain information about the react app (component props, state, contexts, etc.). a simplified version of a fiber looks roughly like this:
 
 ```typescript
 interface Fiber {
@@ -44,6 +64,9 @@ interface Fiber {
   // parent fiber
   return: Fiber | null;
 
+  // the previous or current version of the fiber
+  alternate: Fiber | null;
+
   // saved props input
   memoizedProps: any;
 
@@ -71,16 +94,16 @@ while all of the information is there, it's not super easy to work with, and cha
 
 however, fibers aren't directly accessible by the user. so, we have to hack our way around to accessing it.
 
-luckily, react [reads from a property](https://github.com/facebook/react/blob/6a4b46cd70d2672bc4be59dcb5b8dede22ed0cef/packages/react-reconciler/src/ReactFiberDevToolsHook.js#L48) in the window object: `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` and runs handlers on it when certain events happen. this property must exist before react's bundle is executed. this is intended for react devtools, but we can use it to our advantage.
+luckily, react [reads from a property](https://github.com/facebook/react/blob/6a4b46cd70d2672bc4be59dcb5b8dede22ed0cef/packages/react-reconciler/src/reactFiberDevToolsHook.js#L48) in the window object: `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` and runs handlers on it when certain events happen. this property must exist before react's bundle is executed. this is intended for react devtools, but we can use it to our advantage.
 
 here's what it roughly looks like:
 
 ```typescript
 interface __REACT_DEVTOOLS_GLOBAL_HOOK__ {
   // list of renderers (react-dom, react-native, etc.)
-  renderers: Map<RendererID, ReactRenderer>;
+  renderers: Map<RendererID, reactRenderer>;
 
-  // called when react has rendered everything for an update and is ready to
+  // called when react has rendered everything for an update and the fiber tree is fully built and ready to
   // apply changes to the host tree (e.g. DOM mutations)
   onCommitFiberRoot: (
     rendererID: RendererID,
@@ -92,7 +115,7 @@ interface __REACT_DEVTOOLS_GLOBAL_HOOK__ {
   onPostCommitFiberRoot: (rendererID: RendererID, root: FiberRoot) => void;
 
   // called when a specific fiber unmounts
-  onCommitFiberUnmount: (rendererID: RendererID, Fiber: Fiber) => void;
+  onCommitFiberUnmount: (rendererID: RendererID, fiber: Fiber) => void;
 }
 ```
 
@@ -102,6 +125,282 @@ bippy works by monkey-patching `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` with our
   - _(instead of directly mutating `onCommitFiberRoot`, ...)_
 - `secure` to wrap your handlers in a try/catch and determine if handlers are safe to run
   - _(instead of rawdogging `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` handlers, which may crash your app)_
+- `createFiberVisitor` to traverse the fiber tree and determine which fibers have actually rendered
+  - _(instead of `child`, `sibling`, and `return` pointers)_
+- `traverseFiber` to traverse the fiber tree, regardless of whether it has rendered
+  - _(instead of `child`, `sibling`, and `return` pointers)_
+- `setFiberId` / `getFiberId` to set and get a fiber's id
+  - _(instead of anonymous fibers with no identity)_
+
+## how to use
+
+you can either install via a npm (recommended) or a script tag.
+
+this package should be imported before a React app runs. this will add a special object to the global which is used by React for providing its internals to the tool for analysis (React Devtools does the same). as soon as React library is loaded and attached to the tool, bippy starts collecting data about what is going on in React's internals.
+
+```shell
+npm install bippy
+```
+
+or, use via script tag. must be added before any other scripts run:
+
+```html
+<script src="https://unpkg.com/bippy"></script>
+```
+
+> this will cause bippy to be accessible under a `window.Bippy` global.
+
+next, you can use the api to get data about the fiber tree. below is a (useful) subset of the api. for the full api, read the [source code](https://github.com/aidenybai/bippy/blob/main/src/core.ts).
+
+### instrument
+
+patches `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` with your handlers. must be imported before react, and must be initialized to properly run any other methods.
+
+> use with the `secure` function to prevent uncaught errors from crashing your app.
+
+```typescript
+import { instrument, secure } from 'bippy'; // must be imported BEFORE react
+import * as React from 'react';
+
+instrument(
+  secure({
+    onCommitFiberRoot(rendererID, root) {
+      console.log('root ready to commit', root);
+    },
+    onPostCommitFiberRoot(rendererID, root) {
+      console.log('root with effects committed', root);
+    },
+    onCommitFiberUnmount(rendererID, fiber) {
+      console.log('fiber unmounted', fiber);
+    },
+  })
+);
+```
+
+### createFiberVisitor
+
+not every fiber in the fiber tree renders. `createFiberVisitor` allows you to traverse the fiber tree and determine which fibers have actually rendered.
+
+```typescript
+import { instrument, secure, createFiberVisitor } from 'bippy'; // must be imported BEFORE react
+import * as React from 'react';
+
+const visit = createFiberVisitor({
+  onRender(fiber) {
+    console.log('fiber rendered', fiber);
+  },
+});
+
+instrument(
+  secure({
+    onCommitFiberRoot(rendererID, root) {
+      visit(rendererID, root);
+    },
+  })
+);
+```
+
+### traverseFiber
+
+calls a callback on every fiber in the fiber tree.
+
+```typescript
+import { instrument, secure, traverseFiber } from 'bippy'; // must be imported BEFORE react
+import * as React from 'react';
+
+instrument(
+  secure({
+    onCommitFiberRoot(rendererID, root) {
+      traverseFiber(root.current, (fiber) => {
+        console.log(fiber);
+      });
+    },
+  })
+);
+```
+
+### traverseProps
+
+traverses the props of a fiber.
+
+```typescript
+import { traverseProps } from 'bippy';
+
+// ...
+
+traverseProps(fiber, (propName, next, prev) => {
+  console.log(propName, next, prev);
+});
+```
+
+### traverseState
+
+traverses the state (useState, useReducer, etc.) and effects that set state of a fiber.
+
+```typescript
+import { traverseState } from 'bippy';
+
+// ...
+
+traverseState(fiber, (next, prev) => {
+  console.log(next, prev);
+});
+```
+
+### traverseEffects
+
+traverses the effects (useEffect, useLayoutEffect, etc.) of a fiber.
+
+```typescript
+import { traverseEffects } from 'bippy';
+
+// ...
+
+traverseEffects(fiber, (effect) => {
+  console.log(effect);
+});
+```
+
+### traverseContexts
+
+traverses the contexts (useContext) of a fiber.
+
+```typescript
+import { traverseContexts } from 'bippy';
+
+// ...
+
+traverseContexts(fiber, (next, prev) => {
+  console.log(next, prev);
+});
+```
+
+### setFiberId / getFiberId
+
+set and get a persistent identity for a fiber. by default, fibers are anonymous and have no identity.
+
+```typescript
+import { setFiberId, getFiberId } from 'bippy';
+
+// ...
+
+setFiberId(fiber);
+console.log('unique id for fiber:', getFiberId(fiber));
+```
+
+### isHostFiber
+
+returns `true` if the fiber is a host fiber (e.g., a DOM node in react-dom).
+
+```typescript
+import { isHostFiber } from 'bippy';
+
+if (isHostFiber(fiber)) {
+  console.log('fiber is a host fiber');
+}
+```
+
+### isCompositeFiber
+
+returns `true` if the fiber is a composite fiber. composite fibers represent class components, function components, memoized components, and so on (anything that can actually render output).
+
+```typescript
+import { isCompositeFiber } from 'bippy';
+
+if (isCompositeFiber(fiber)) {
+  console.log('fiber is a composite fiber');
+}
+```
+
+### getDisplayName
+
+returns the display name of the fiber's component, falling back to the component's function or class name if available.
+
+```typescript
+import { getDisplayName } from 'bippy';
+
+console.log(getDisplayName(fiber));
+```
+
+### getType
+
+returns the underlying type (the component definition) for a given fiber. for example, this could be a function component or class component.
+
+```jsx
+import { getType } from 'bippy';
+import { memo } from 'react';
+
+const RealComponent = () => {
+  return <div>hello</div>;
+};
+const MemoizedComponent = memo(() => {
+  return <div>hello</div>;
+});
+
+console.log(getType(fiberForMemoizedComponent) === RealComponent);
+```
+
+### getNearestHostFiber / getNearestHostFibers
+
+getNearestHostFiber returns the closest host fiber above or below a given fiber. getNearestHostFibers(fiber) returns all host fibers associated with the provided fiber and its subtree.
+
+```jsx
+import { getNearestHostFiber, getNearestHostFibers } from 'bippy';
+
+// ...
+
+function Component() {
+  return (
+    <>
+      <div>hello</div>
+      <div>world</div>
+    </>
+  );
+}
+
+console.log(getNearestHostFiber(fiberForComponent)); // <div>hello</div>
+console.log(getNearestHostFibers(fiberForComponent)); // [<div>hello</div>, <div>world</div>]
+```
+
+### getTimings
+
+returns the self and total render times for the fiber.
+
+```typescript
+// timings don't exist in react production builds
+if (fiber.actualDuration !== undefined) {
+  const { selfTime, totalTime } = getTimings(fiber);
+  console.log(selfTime, totalTime);
+}
+```
+
+### getFiberStack
+
+returns an array representing the stack of fibers from the current fiber up to the root.
+
+```typescript
+[fiber, fiber.return, fiber.return.return, ...]
+```
+
+### getMutatedHostFibers
+
+returns an array of all host fibers that have committed and rendered in the provided fiber's subtree.
+
+```typescript
+import { getMutatedHostFibers } from 'bippy';
+
+console.log(getMutatedHostFibers(fiber));
+```
+
+### isValidFiber
+
+returns `true` if the given object is a valid React Fiber (i.e., has a tag, stateNode, return, child, sibling, etc.).
+
+```typescript
+import { isValidFiber } from 'bippy';
+
+console.log(isValidFiber(fiber));
+```
 
 ## examples
 
@@ -161,22 +460,22 @@ const visit = createFiberVisitor({
 });
 
 /**
- * `instrument` is a function that installs the React DevTools global
- * hook and allows you to set up custom handlers for React fiber events.
+ * `instrument` is a function that installs the react DevTools global
+ * hook and allows you to set up custom handlers for react fiber events.
  */
 instrument(
   /**
    * `secure` is a function that wraps your handlers in a try/catch
    * and prevents it from crashing the app. it also prevents it from
-   * running on unsupported React versions and during production.
+   * running on unsupported react versions and during production.
    *
    * this is not required but highly recommended to provide "safeguards"
    * in case something breaks.
    */
   secure({
     /**
-     * `onCommitFiberRoot` is a handler that is called when React is
-     * ready to commit a fiber root. this means that React is has
+     * `onCommitFiberRoot` is a handler that is called when react is
+     * ready to commit a fiber root. this means that react is has
      * rendered your entire app and is ready to apply changes to
      * the host tree (e.g. via DOM mutations).
      */
@@ -286,6 +585,44 @@ instrument(
 );
 ```
 
+## glossary
+
+- fiber: a "unit of execution" in react, representing a component or dom element
+- commit: the process of applying changes to the host tree (e.g. DOM mutations)
+- render: the process of building the fiber tree by executing component function/classes
+- host tree: the tree of UI elements that react mutates (e.g. DOM elements)
+- reconciler (or "renderer"): custom bindings for react, e.g. react-dom, react-native, react-three-fiber, etc to mutate the host tree
+- `rendererID`: the id of the reconciler, starting at 1 (can be from multiple reconciler instances)
+- `root`: a special `FiberRoot` type that contains the container fiber (the one you pass to `ReactDOM.createRoot`) in the `current` property
+- `onCommitFiberRoot`: called when react is ready to commit a fiber root
+- `onPostCommitFiberRoot`: called when react has committed a fiber root and effects have run
+- `onCommitFiberUnmount`: called when a fiber unmounts
+
+## development
+
+we use a pnpm monorepo, get started by running:
+
+```shell
+pnpm install
+# create dev builds
+pnpm run dev
+# run unit tests
+pnpm run test
+```
+
+you can ad-hoc test by running `pnpm run dev` in the `/kitchen-sink` directory.
+
+```shell
+cd kitchen-sink
+pnpm run dev
+```
+
 ## misc
 
+we use this project internally in [react-scan](https://github.com/aidenybai/react-scan), which is deployed with proper safeguards to ensure it's only used in development or error-guarded in production.
+
+while i maintain this specifically for react-scan, those seeking more robust solutions might consider [its-fine](https://github.com/pmndrs/its-fine) for accessing fibers within react using hooks, or [react-devtools-inline](https://www.npmjs.com/package/react-devtools-inline) for a headful interface.
+
+if you plan to use this project beyond experimentation, please review [react-scan's source code](https://github.com/aidenybai/react-scan) to understand our safeguarding practices.
+
 the original bippy character is owned and created by [@dairyfreerice](https://www.instagram.com/dairyfreerice). this project is not related to the bippy brand, i just think the character is cute.