⏱ react-runtime-hooks-z

LIVE EXAMPLE

react-runtime-hooks-z is a small, focused library of runtime-level React hooks for managing effects, lifecycles, scheduling, and reactive side-effects — without abusing useEffect.

React renders. Effects live in a runtime.

---

✨ Why react-runtime-hooks-z?

• Precise effect lifecycles (mount / update / unmount)

• Abortable & async-safe effects

• Fine-grained dependency tracking (no deps array hell)

• Zero unnecessary re-renders

• Effect logic that is explicit, testable, and composable

---

🧠 Mental Model

• Effect instance — created per dependency change

• EffectContext — lifetime of one effect instance

• watch() — reactive source instead of deps array

• compare() — custom equality for updates

• Scheduler — control when effects run

• Transaction — batch effect updates

• Dependency change = old effect aborted, new effect created.

---

📦 Installation

npm install react-runtime-hooks-z

🔹 Basic Usage

useEffectFlow
useEffectFlow(flow => {
  flow.onMount(() => connect())

  flow.onUpdate(({ prev, next }) => {
    if (prev.id !== next.id) {
      fetchData(next.id)
    }
  })

  flow.onUnmount(() => cleanup())
}, () => user)

🔹 Abortable / Async-safe Effects

useEffectFlow(flow => {
  flow.onUpdate(async ({ next, effect }) => {
    const res = await fetch(`/api/user/${next.id}`, {
      signal: effect.signal
    })

    const data = await res.json()
    console.log(data)
  })
}, () => user)

• Dependency changes automatically abort the previous request

• No stale updates, no race conditions

🔹 Multi-watch (Composed Source)

useEffectFlow(flow => {
  flow.onUpdate(({ next }) => {
    const [userId, token, locale] = next
    loadUser(userId, token, locale)
  })
},
() => [user.id, token, locale],
shallowArrayEqual
)

🔹 Effect Cleanup & Scope

useEffectFlow(flow => {
  flow.onUpdate(({ effect }) => {
    const id = setInterval(tick, 1000)

    effect.onCleanup(() => {
      clearInterval(id)
    })
  })
}, () => enabled)

• Cleanup is tied to the effect instance, not the component.

🔹 useLifecycleEffect (Lower-level)

useLifecycleEffect(
  {
    mount() {
      console.log("mounted")
    },
    update({ prev, next }) {
      console.log("changed", prev, next)
    },
    unmount() {
      console.log("unmounted")
    }
  },
  () => value
)

🔹 useReactiveEffect

useReactiveEffect(
  () => user.id,
  (id) => {
    console.log("User id changed:", id)
  }
)

🔹 usePhaseEffect

usePhaseEffect("mount", () => {
  console.log("mounted")
})

Supported phases: mount | update | unmount

🔹 useVisibleEffect

useVisibleEffect(() => {
  console.log("element is visible")
})

Runs when the component enters the viewport.

🔹 useIdleEffect

useIdleEffect(() => {
  preloadHeavyStuff()
})

Runs during browser idle time.

🔹 Transactions

import { transaction } from "react-runtime-hooks-z"

transaction(() => {
  updateA()
  updateB()
})

Ensures effects run only once after the batch.

---

📊 Comparison with useEffect

Feature	react-runtime-hooks-z	useEffect
Abortable async	✅	❌
Instance-based cleanup	✅	⚠️
Custom dependency compare	✅	❌
Multi-source watch	✅	❌
Scheduler support	✅	❌
Accidental re-renders	❌	⚠️

---

🚫 Anti-patterns

• Using useEffect for complex async flows

• Encoding orchestration logic into deps arrays

• Letting stale effects mutate newer state

• Tying side-effects directly to render cycles

---

🧠 Philosophy

• Effects are runtime constructs, not render side-effects

• Dependencies should be explicit

• Cleanup should be automatic and scoped

• React should focus on rendering, not orchestration

---

📜 License

MIT