why-render-react 0.1.0

package/dist/utils/Config.js

@@ -0,0 +1,401 @@
+/**
+ * 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 class WhyRenderConfig {
+    /**
+     * The current global Why Render configuration instance.
+     *
+     * This instance is created by {@link WhyRenderConfig.setup}.
+     */
+    static instance;
+    /**
+     * Whether Why Render is enabled.
+     *
+     * @defaultValue false
+     */
+    enabled;
+    /**
+     * 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.
+     */
+    constructor(value) {
+        this.enabled = WhyRenderConfig.parseBoolean(value);
+    }
+    /**
+     * 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) {
+        WhyRenderConfig.instance = new WhyRenderConfig(value);
+        return WhyRenderConfig.instance;
+    }
+    /**
+     * 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() {
+        return WhyRenderConfig.instance !== undefined;
+    }
+    /**
+     * 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() {
+        if (!WhyRenderConfig.instance) {
+            throw new Error([
+                "WhyRenderConfig has not been configured.",
+                "",
+                "Call WhyRenderConfig.setup() before accessing the configuration.",
+                "",
+                "Example:",
+                "WhyRenderConfig.setup(process.env.USE_WHY_RENDER);",
+            ].join("\n"));
+        }
+        return WhyRenderConfig.instance;
+    }
+    /**
+     * 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() {
+        return WhyRenderConfig.getConfig().enabled;
+    }
+    /**
+     * 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
+     * ```
+     */
+    static parseBoolean(value) {
+        if (typeof value === "boolean") {
+            return value;
+        }
+        if (typeof value === "string") {
+            return value.trim().toLowerCase() === "true";
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=Config.js.map

package/dist/utils/Config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Config.js","sourceRoot":"","sources":["../../src/utils/Config.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,MAAM,OAAO,eAAe;IACxB;;;;OAIG;IACK,MAAM,CAAC,QAAQ,CAA8B;IAErD;;;;OAIG;IACa,OAAO,CAAU;IAEjC;;;;;;;;OAQG;IACH,YAAoB,KAA2B;QAC3C,IAAI,CAAC,OAAO,GAAG,eAAe,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8GG;IACI,MAAM,CAAC,KAAK,CAAC,KAA2B;QAC3C,eAAe,CAAC,QAAQ,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;QACtD,OAAO,eAAe,CAAC,QAAQ,CAAC;IACpC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACI,MAAM,CAAC,YAAY;QACtB,OAAO,eAAe,CAAC,QAAQ,KAAK,SAAS,CAAC;IAClD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,MAAM,CAAC,SAAS;QACnB,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACX;gBACI,0CAA0C;gBAC1C,EAAE;gBACF,kEAAkE;gBAClE,EAAE;gBACF,UAAU;gBACV,oDAAoD;aACvD,CAAC,IAAI,CAAC,IAAI,CAAC,CACf,CAAC;QACN,CAAC;QAED,OAAO,eAAe,CAAC,QAAQ,CAAC;IACpC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,MAAM,CAAC,SAAS;QACnB,OAAO,eAAe,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACK,MAAM,CAAC,YAAY,CAAC,KAA2B;QACnD,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,KAAK,CAAC;QACjB,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;QACjD,CAAC;QAED,OAAO,KAAK,CAAC;IACjB,CAAC;CAIJ"}

package/dist/utils/utils.d.ts

@@ -0,0 +1,28 @@
+import type { PropChangeType, LabelOptions } from "../global/index.t.js";
+/**
+ * `console.log` `%c` style string used for the `[why-rerender]` header
+ * label.
+*/
+export declare const LABEL_STYLE: string;
+/** Number of characters each change-type label (e.g. `CHANGED`) is padded to. */
+export declare const PAD_SIZE: number;
+/**
+ * Builds the `%c`-formatted console log header for a render, e.g.
+ * `%c[why-rerender] <CarCard> render #3`.
+ *
+ * Must be logged together with `LABEL_STYLE` as the corresponding
+ * `%c` style argument.
+ *
+ * @param options - The component name and current render count.
+ * @returns A format string containing a single `%c` placeholder.
+*/
+export declare const setHeader: ({ name, count }: LabelOptions) => string;
+/**
+ * Returns the `%c` style string used to color a logged prop line
+ * according to its change type (changed / added / removed).
+ *
+ * @param type - The kind of prop change being logged.
+ * @returns A CSS style string for use as a `console.log` `%c` argument.
+*/
+export declare const setBodyText: (type: PropChangeType) => string;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AASxE;;;EAGE;AACF,eAAO,MAAM,WAAW,EAAE,MAA8D,CAAA;AAGxF,iFAAiF;AACjF,eAAO,MAAM,QAAQ,EAAE,MAAU,CAAA;AAEjC;;;;;;;;;EASE;AACF,eAAO,MAAM,SAAS,GAAI,iBAAc,YAAY,KAAE,MAErD,CAAA;AAID;;;;;;EAME;AACF,eAAO,MAAM,WAAW,GAAI,MAAK,cAAc,WAE9C,CAAA"}

package/dist/utils/utils.js

@@ -0,0 +1,38 @@
+/** Console text color (hex) used for each type of prop change. */
+const COLOR = {
+    changed: '#854F0B', // amber
+    added: '#0F6E56', // teal
+    removed: '#993C1D', // coral
+};
+/**
+ * `console.log` `%c` style string used for the `[why-rerender]` header
+ * label.
+*/
+export const LABEL_STYLE = 'color:#534AB7;font-weight:600;font-family:monospace';
+const PREFIX = '[why-rerender]';
+/** Number of characters each change-type label (e.g. `CHANGED`) is padded to. */
+export const PAD_SIZE = 8;
+/**
+ * Builds the `%c`-formatted console log header for a render, e.g.
+ * `%c[why-rerender] <CarCard> render #3`.
+ *
+ * Must be logged together with `LABEL_STYLE` as the corresponding
+ * `%c` style argument.
+ *
+ * @param options - The component name and current render count.
+ * @returns A format string containing a single `%c` placeholder.
+*/
+export const setHeader = ({ name, count }) => {
+    return `%c${PREFIX} <${name}> render #${count}`;
+};
+/**
+ * Returns the `%c` style string used to color a logged prop line
+ * according to its change type (changed / added / removed).
+ *
+ * @param type - The kind of prop change being logged.
+ * @returns A CSS style string for use as a `console.log` `%c` argument.
+*/
+export const setBodyText = (type) => {
+    return `color:${COLOR[type]};font-weight:600;font-family:monospace`;
+};
+//# sourceMappingURL=utils.js.map

package/dist/utils/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils/utils.ts"],"names":[],"mappings":"AAEA,kEAAkE;AAClE,MAAM,KAAK,GAAmC;IAC5C,OAAO,EAAE,SAAS,EAAG,QAAQ;IAC7B,KAAK,EAAI,SAAS,EAAG,OAAO;IAC5B,OAAO,EAAE,SAAS,EAAG,QAAQ;CAC9B,CAAA;AAED;;;EAGE;AACF,MAAM,CAAC,MAAM,WAAW,GAAW,qDAAqD,CAAA;AACxF,MAAM,MAAM,GAAW,gBAAgB,CAAA;AAEvC,iFAAiF;AACjF,MAAM,CAAC,MAAM,QAAQ,GAAW,CAAC,CAAA;AAEjC;;;;;;;;;EASE;AACF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EAAC,IAAI,EAAE,KAAK,EAAc,EAAS,EAAE;IAC3D,OAAO,KAAK,MAAM,KAAK,IAAI,aAAa,KAAK,EAAE,CAAA;AACnD,CAAC,CAAA;AAID;;;;;;EAME;AACF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAmB,EAAE,EAAE;IAC/C,OAAO,SAAS,KAAK,CAAC,IAAI,CAAC,wCAAwC,CAAA;AACvE,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "why-render-react",
+  "version": "0.1.0",
+  "description": "A React hook that helps you understand why a component re-rendered.",
+  "types": "module",
+  "main": "dist/index.js",
+  "license":"MIT",
+  "exports":{
+    ".":{
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:file": "vitest run",
+    "check": "npm run typecheck && npm run lint && npm run build",
+    "coverage": "vitest run --coverage",
+    "release": "npm run build && npm run test && npm publish --access public",
+    "pre:deploy": "npm run check && npm whoami &&  npm link",
+    "pre:test": "npm run check && npm link",
+    "local:test": "npm run reset:old && npm run pre:test"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+
+  "engines": {
+    "node":">=20"
+  },
+
+  "keywords": [],
+  "type": "module",
+  "peerDependencies": {
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.4.0",
+    "@types/react": "^19.2.18",
+    "@vitejs/plugin-react": "^6.1.1",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^9.0.0",
+    "jsdom": "^30.0.1",
+    "typescript": "^6.0.0",
+    "typescript-eslint": "^8.69.0",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
+  }
+}