why-render-react 0.1.0

package/dist/useWhyRerender.d.ts

@@ -0,0 +1,95 @@
+import type { Rerender } from "./global/useRerender.t.js";
+import { type WhyRenderConfigValue } from "./utils/Config.js";
+/**
+ * Initializes the shared Why Render configuration and returns whether
+ * it is enabled.
+ *
+ * This is a thin convenience wrapper around `WhyRenderConfig.setup()`
+ * for call sites that only need the resulting boolean (e.g. to gate
+ * other setup logic) rather than the full config instance.
+ *
+ * @param value - The raw configuration value, e.g. an environment
+ * variable such as `process.env.USE_WHY_RENDER`. Only the boolean
+ * `true`, or a string that trims and lower-cases to `"true"`, enables
+ * Why Render.
+ * @returns `true` if the resolved configuration is enabled, `false`
+ * otherwise.
+ *
+ * @example
+ * ```ts
+ * setup(process.env.USE_WHY_RENDER)
+ * ```
+ */
+export declare const setup: (value: WhyRenderConfigValue) => boolean;
+/**
+ * Tracks and logs why a React component rendered.
+ *
+ * On each render, `useWhyRerender` compares the component's current props
+ * with the props from the previous render and logs the result when
+ * Why Render is enabled.
+ *
+ * The first render is logged as `"initial"`. Subsequent renders are logged
+ * as either:
+ * - `"no-prop-changes"` when no props changed.
+ * - A list of changed props when one or more props changed.
+ *
+ * Logging can be disabled globally through `WhyRenderConfig` or locally
+ * for a specific component using `isActive`.
+ *
+ * @param options - Configuration describing the component and its props.
+ * @param options.name - Human-readable component name used in the log output.
+ * @param options.props - The current component props to compare with the
+ *   previous render.
+ * @param options.verbose - When `true`, includes the previous and next values
+ *   for changed props. Defaults to `false`.
+ * @param options.isActive - When `false`, disables logging for this
+ *   component while keeping the hook mounted. Defaults to `true`.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * useWhyRerender({
+ *   name: "UserProfile",
+ *   props,
+ * });
+ * ```
+ *
+ * @example
+ * Enable verbose output:
+ * ```tsx
+ * useWhyRerender({
+ *   name: "UserProfile",
+ *   props,
+ *   verbose: true,
+ * });
+ * ```
+ *
+ * @example
+ * Temporarily disable tracking:
+ * ```tsx
+ * useWhyRerender({
+ *   name: "UserProfile",
+ *   props,
+ *   isActive: false,
+ * });
+ * ```
+ *
+ * @example
+ * Use with a component's props:
+ * ```tsx
+ * function UserProfile(props: UserProfileProps) {
+ *   useWhyRerender({
+ *     name: "UserProfile",
+ *     props,
+ *   });
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @remarks
+ * Why Render must be enabled through `WhyRenderConfig` before this hook
+ * produces any logging output.
+ */
+export declare const useWhyRerender: ({ name, props, verbose, isActive }: Rerender) => void;
+//# sourceMappingURL=useWhyRerender.d.ts.map

package/dist/useWhyRerender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWhyRerender.d.ts","sourceRoot":"","sources":["../src/useWhyRerender.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAmB,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAI9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,oBAAoB,KAAG,OAGnD,CAAA;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,eAAO,MAAM,cAAc,GAAI,oCAAyC,QAAQ,KAAE,IAyBjF,CAAA"}

package/dist/useWhyRerender.js

@@ -0,0 +1,126 @@
+import { useRef, useEffect } from "react";
+import diffProps from "./diff.js";
+import log from "./logger.js";
+import { WhyRenderConfig } from "./utils/Config.js";
+/**
+ * Initializes the shared Why Render configuration and returns whether
+ * it is enabled.
+ *
+ * This is a thin convenience wrapper around `WhyRenderConfig.setup()`
+ * for call sites that only need the resulting boolean (e.g. to gate
+ * other setup logic) rather than the full config instance.
+ *
+ * @param value - The raw configuration value, e.g. an environment
+ * variable such as `process.env.USE_WHY_RENDER`. Only the boolean
+ * `true`, or a string that trims and lower-cases to `"true"`, enables
+ * Why Render.
+ * @returns `true` if the resolved configuration is enabled, `false`
+ * otherwise.
+ *
+ * @example
+ * ```ts
+ * setup(process.env.USE_WHY_RENDER)
+ * ```
+ */
+export const setup = (value) => {
+    const instance = WhyRenderConfig.setup(value);
+    return instance.enabled;
+};
+/**
+ * Tracks and logs why a React component rendered.
+ *
+ * On each render, `useWhyRerender` compares the component's current props
+ * with the props from the previous render and logs the result when
+ * Why Render is enabled.
+ *
+ * The first render is logged as `"initial"`. Subsequent renders are logged
+ * as either:
+ * - `"no-prop-changes"` when no props changed.
+ * - A list of changed props when one or more props changed.
+ *
+ * Logging can be disabled globally through `WhyRenderConfig` or locally
+ * for a specific component using `isActive`.
+ *
+ * @param options - Configuration describing the component and its props.
+ * @param options.name - Human-readable component name used in the log output.
+ * @param options.props - The current component props to compare with the
+ *   previous render.
+ * @param options.verbose - When `true`, includes the previous and next values
+ *   for changed props. Defaults to `false`.
+ * @param options.isActive - When `false`, disables logging for this
+ *   component while keeping the hook mounted. Defaults to `true`.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * useWhyRerender({
+ *   name: "UserProfile",
+ *   props,
+ * });
+ * ```
+ *
+ * @example
+ * Enable verbose output:
+ * ```tsx
+ * useWhyRerender({
+ *   name: "UserProfile",
+ *   props,
+ *   verbose: true,
+ * });
+ * ```
+ *
+ * @example
+ * Temporarily disable tracking:
+ * ```tsx
+ * useWhyRerender({
+ *   name: "UserProfile",
+ *   props,
+ *   isActive: false,
+ * });
+ * ```
+ *
+ * @example
+ * Use with a component's props:
+ * ```tsx
+ * function UserProfile(props: UserProfileProps) {
+ *   useWhyRerender({
+ *     name: "UserProfile",
+ *     props,
+ *   });
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @remarks
+ * Why Render must be enabled through `WhyRenderConfig` before this hook
+ * produces any logging output.
+ */
+export const useWhyRerender = ({ name, props, verbose, isActive = true }) => {
+    const enable = WhyRenderConfig.isEnabled();
+    const prevPropsRef = useRef(null);
+    const renderCountRef = useRef(0);
+    useEffect(() => {
+        if (!enable || !isActive)
+            return;
+        renderCountRef.current += 1;
+        const count = renderCountRef.current;
+        const changes = diffProps({ prev: prevPropsRef.current, next: props });
+        if (count === 1) {
+            log({ name, count, changes: "initial", verbose: verbose ?? false, });
+        }
+        else if (changes.length === 0) {
+            log({ name, count, changes: "no-prop-changes", verbose: verbose ?? false, });
+        }
+        else {
+            log({
+                name,
+                count,
+                changes,
+                verbose: verbose ?? false,
+            });
+        }
+        prevPropsRef.current = { ...props };
+    });
+};
+//# sourceMappingURL=useWhyRerender.js.map

package/dist/useWhyRerender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWhyRerender.js","sourceRoot":"","sources":["../src/useWhyRerender.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAG,MAAM,OAAO,CAAA;AAC1C,OAAO,SAAS,MAAM,WAAW,CAAA;AACjC,OAAO,GAAG,MAAM,aAAa,CAAA;AAE7B,OAAO,EAAE,eAAe,EAA6B,MAAM,mBAAmB,CAAA;AAI9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAA2B,EAAW,EAAE;IAC1D,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC7C,OAAO,QAAQ,CAAC,OAAO,CAAA;AAC3B,CAAC,CAAA;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAC,IAAI,EAAY,EAAO,EAAE;IACrF,MAAM,MAAM,GAAG,eAAe,CAAC,SAAS,EAAE,CAAA;IAC1C,MAAM,YAAY,GAAI,MAAM,CAAiC,IAAI,CAAC,CAAA;IAClE,MAAM,cAAc,GAAG,MAAM,CAAS,CAAC,CAAC,CAAA;IAExC,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ;YAAE,OAAO;QACjC,cAAc,CAAC,OAAO,IAAI,CAAC,CAAC;QAC5B,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC;QACrC,MAAM,OAAO,GAAG,SAAS,CAAC,EAAC,IAAI,EAAC,YAAY,CAAC,OAAO,EAAE,IAAI,EAAC,KAAK,EAAC,CAAC,CAAA;QAElE,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YACd,GAAG,CAAC,EAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAC,SAAS,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK,GAAE,CAAC,CAAA;QACrE,CAAC;aAAM,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,GAAG,CAAC,EAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAC,iBAAiB,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK,GAAE,CAAC,CAAA;QAC7E,CAAC;aAAM,CAAC;YACJ,GAAG,CAAC;gBACA,IAAI;gBACJ,KAAK;gBACL,OAAO;gBACP,OAAO,EAAE,OAAO,IAAI,KAAK;aAC5B,CAAC,CAAA;QACN,CAAC;QACD,YAAY,CAAC,OAAO,GAAG,EAAE,GAAG,KAAK,EAAE,CAAA;IACvC,CAAC,CAAC,CAAA;AACN,CAAC,CAAA"}

package/dist/utils/Config.d.ts

@@ -0,0 +1,379 @@
+/**
+ * A value that can be used to configure Why Render.
+ *
+ * Environment variables are commonly represented as strings, while custom
+ * configuration systems may provide boolean values directly.
+ */
+export type WhyRenderConfigValue = string | boolean | undefined;
+/**
+ * Configuration manager for Why Render.
+ *
+ * Why Render is disabled by default and must be explicitly enabled by passing
+ * the boolean `true` or a string equivalent to `"true"`.
+ *
+ * Only the following values enable Why Render:
+ *
+ * - `true`
+ * - `"true"` (case-insensitive)
+ * - Strings with surrounding whitespace, such as `" true "`
+ *
+ * All other values disable Why Render, including:
+ *
+ * - `false`
+ * - `undefined`
+ * - `"false"`
+ * - `"1"`
+ * - `"yes"`
+ * - An empty string
+ *
+ * ## Important
+ *
+ * This configuration receives a resolved value rather than an environment
+ * variable name.
+ *
+ * Therefore, `WhyRenderConfig` cannot determine where the value came from or
+ * verify that it originated from the intended environment variable.
+ *
+ * Any value explicitly equal to `true` or a string equivalent to `"true"`
+ * will enable Why Render, regardless of its source.
+ *
+ * Developers should ensure they pass the intended Why Render configuration
+ * value, such as `process.env.USE_WHY_RENDER`.
+ *
+ * @example Enable with a boolean
+ * ```ts
+ * WhyRenderConfig.setup(true);
+ *
+ * if (WhyRenderConfig.isEnabled()) {
+ *     // Why Render is enabled.
+ * }
+ * ```
+ *
+ * @example Node.js, Bun, or Express
+ * ```ts
+ * WhyRenderConfig.setup(
+ *     process.env.USE_WHY_RENDER
+ * );
+ * ```
+ *
+ * ```env
+ * USE_WHY_RENDER=true
+ * ```
+ *
+ * @example Vite
+ * ```ts
+ * WhyRenderConfig.setup(
+ *     import.meta.env.VITE_USE_WHY_RENDER
+ * );
+ * ```
+ *
+ * ```env
+ * VITE_USE_WHY_RENDER=true
+ * ```
+ *
+ * @example Custom environment object
+ * ```ts
+ * WhyRenderConfig.setup(
+ *     env.USE_WHY_RENDER
+ * );
+ * ```
+ *
+ * @example Disabled by default
+ * ```ts
+ * WhyRenderConfig.setup(undefined);
+ *
+ * WhyRenderConfig.isEnabled();
+ * // false
+ * ```
+ *
+ * @example Important: unrelated values can enable Why Render
+ *
+ * The following is valid, but may unintentionally enable Why Render:
+ *
+ * ```ts
+ * WhyRenderConfig.setup(
+ *     process.env.DEBUG
+ * );
+ * ```
+ *
+ * If `DEBUG` contains `"true"`, Why Render will be enabled because this class
+ * receives only the resolved value and cannot determine that it came from
+ * `DEBUG` instead of `USE_WHY_RENDER`.
+ */
+export declare class WhyRenderConfig {
+    /**
+     * The current global Why Render configuration instance.
+     *
+     * This instance is created by {@link WhyRenderConfig.setup}.
+     */
+    private static instance;
+    /**
+     * Whether Why Render is enabled.
+     *
+     * @defaultValue false
+     */
+    readonly enabled: boolean;
+    /**
+     * Creates a Why Render configuration instance.
+     *
+     * The constructor is private because the global configuration should be
+     * created through {@link WhyRenderConfig.setup}.
+     *
+     * @param value - The resolved value used to determine whether Why Render
+     * is enabled.
+     */
+    private constructor();
+    /**
+     * Configures Why Render.
+     *
+     * Calling this method creates the global configuration instance.
+     *
+     * If Why Render has already been configured, calling this method again
+     * replaces the existing configuration with a new one.
+     *
+     * Why Render is enabled only when the provided value is:
+     *
+     * - The boolean `true`
+     * - A string equivalent to `"true"` after trimming whitespace and
+     *   ignoring letter case
+     *
+     * All other values disable Why Render.
+     *
+     * ## Important
+     *
+     * This method accepts a resolved value, not an environment variable name.
+     *
+     * As a result, this class cannot verify that the value came from
+     * `USE_WHY_RENDER`.
+     *
+     * For example, the following code will enable Why Render if `DEBUG`
+     * contains `"true"`:
+     *
+     * ```ts
+     * WhyRenderConfig.setup(process.env.DEBUG);
+     * ```
+     *
+     * Developers should pass the intended Why Render environment variable:
+     *
+     * ```ts
+     * WhyRenderConfig.setup(process.env.USE_WHY_RENDER);
+     * ```
+     *
+     * @param value - The resolved configuration value used to enable or
+     * disable Why Render.
+     *
+     * @returns The newly created global {@link WhyRenderConfig} instance.
+     *
+     * @example Node.js
+     * ```ts
+     * WhyRenderConfig.setup(
+     *     process.env.USE_WHY_RENDER
+     * );
+     * ```
+     *
+     * ```env
+     * USE_WHY_RENDER=true
+     * ```
+     *
+     * @example Bun
+     * ```ts
+     * WhyRenderConfig.setup(
+     *     process.env.USE_WHY_RENDER
+     * );
+     * ```
+     *
+     * @example Express
+     * ```ts
+     * WhyRenderConfig.setup(
+     *     process.env.USE_WHY_RENDER
+     * );
+     * ```
+     *
+     * @example Vite
+     * ```ts
+     * WhyRenderConfig.setup(
+     *     import.meta.env.VITE_USE_WHY_RENDER
+     * );
+     * ```
+     *
+     * ```env
+     * VITE_USE_WHY_RENDER=true
+     * ```
+     *
+     * @example Enable directly
+     * ```ts
+     * WhyRenderConfig.setup(true);
+     * ```
+     *
+     * @example Disable directly
+     * ```ts
+     * WhyRenderConfig.setup(false);
+     * ```
+     *
+     * @example Missing environment variable
+     *
+     * Missing values safely disable Why Render.
+     *
+     * ```ts
+     * WhyRenderConfig.setup(
+     *     process.env.USE_WHY_RENDER
+     * );
+     *
+     * // If USE_WHY_RENDER is undefined:
+     * WhyRenderConfig.isEnabled();
+     * // false
+     * ```
+     *
+     * @example Warning: unrelated environment variable
+     *
+     * ```ts
+     * WhyRenderConfig.setup(
+     *     process.env.DEBUG
+     * );
+     * ```
+     *
+     * If `DEBUG` is `"true"`, Why Render will be enabled.
+     */
+    static setup(value: WhyRenderConfigValue): WhyRenderConfig;
+    /**
+     * Returns whether Why Render has been configured.
+     *
+     * This method checks only whether {@link WhyRenderConfig.setup} has been
+     * called.
+     *
+     * It does not indicate whether Why Render is enabled.
+     *
+     * @returns `true` when Why Render has been configured; otherwise `false`.
+     *
+     * @example Not configured
+     * ```ts
+     * WhyRenderConfig.isConfigured();
+     * // false
+     * ```
+     *
+     * @example Configured and enabled
+     * ```ts
+     * WhyRenderConfig.setup(true);
+ *
+     * WhyRenderConfig.isConfigured();
+     * // true
+     * ```
+     *
+     * @example Configured but disabled
+     * ```ts
+     * WhyRenderConfig.setup(false);
+     *
+     * WhyRenderConfig.isConfigured();
+     * // true
+     *
+     * WhyRenderConfig.isEnabled();
+     * // false
+     * ```
+     *
+     * @example Configure only when necessary
+     * ```ts
+     * if (!WhyRenderConfig.isConfigured()) {
+     *     WhyRenderConfig.setup(
+     *         process.env.USE_WHY_RENDER
+     *     );
+     * }
+     * ```
+     */
+    static isConfigured(): boolean;
+    /**
+     * Returns the current global Why Render configuration.
+     *
+     * @returns The current {@link WhyRenderConfig} instance.
+     *
+     * @throws {Error}
+     * Thrown when {@link WhyRenderConfig.setup} has not been called.
+     *
+     * @example
+     * ```ts
+     * WhyRenderConfig.setup(
+     *     process.env.USE_WHY_RENDER
+     * );
+     *
+     * const config =
+     *     WhyRenderConfig.getConfig();
+     *
+     * console.log(config.enabled);
+     * ```
+     *
+     * @example Error when not configured
+     * ```ts
+     * WhyRenderConfig.getConfig();
+     *
+     * // Throws an Error because setup() has not been called.
+     * ```
+     */
+    static getConfig(): WhyRenderConfig;
+    /**
+     * Returns whether Why Render is currently enabled.
+     *
+     * @returns `true` when Why Render is enabled; otherwise `false`.
+     *
+     * @throws {Error}
+     * Thrown when {@link WhyRenderConfig.setup} has not been called.
+     *
+     * @example
+     * ```ts
+     * WhyRenderConfig.setup(
+     *     process.env.USE_WHY_RENDER
+     * );
+     *
+     * if (WhyRenderConfig.isEnabled()) {
+     *     console.log("Why Render is enabled.");
+     * }
+     * ```
+     *
+     * @example Disabled
+     * ```ts
+     * WhyRenderConfig.setup(false);
+ *
+     * WhyRenderConfig.isEnabled();
+     * // false
+     * ```
+     */
+    static isEnabled(): boolean;
+    /**
+     * Converts a supported configuration value into a boolean.
+     *
+     * The value must explicitly represent `true` to enable Why Render.
+     *
+     * Only the following values enable Why Render:
+     *
+     * - `true`
+     * - A string equivalent to `"true"` after trimming whitespace and
+     *   ignoring letter case
+     *
+     * All other values return `false`.
+     *
+     * @param value - The configuration value to parse.
+     *
+     * @returns `true` only when the value explicitly enables Why Render;
+     * otherwise `false`.
+     *
+     * @example
+     * ```ts
+     * // All enable Why Render:
+     * true
+     * "true"
+     * "TRUE"
+     * " true "
+     * ```
+     *
+     * @example
+     * ```ts
+     * // All disable Why Render:
+     * false
+     * "false"
+     * "1"
+     * "yes"
+     * ""
+     * undefined
+     * ```
+     */
+    private static parseBoolean;
+}
+//# sourceMappingURL=Config.d.ts.map

package/dist/utils/Config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../src/utils/Config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAE,OAAO,GAAE,SAAS,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,qBAAa,eAAe;IACxB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA8B;IAErD;;;;OAIG;IACH,SAAgB,OAAO,EAAE,OAAO,CAAC;IAEjC;;;;;;;;OAQG;IACH,OAAO;IAIP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8GG;WACW,KAAK,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe;IAKjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;WACW,YAAY,IAAI,OAAO;IAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;WACW,SAAS,IAAI,eAAe;IAiB1C;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;WACW,SAAS,IAAI,OAAO;IAIlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAc9B"}