docs: add scheduler docs

Author: crimx

README.md

@@ -123,6 +123,37 @@ trace(count$);
 
 </details>
 
+<details>
+<summary>⏳ Scheduler mechanism for controlled updates.</summary>
+
+`@embra/reactivity` includes a scheduler mechanism and built-in schedulers that lets you control when reactive updates are processed.
+This is useful for batching updates and deferring computations.
+
+```ts
+import { writable, MicrotaskScheduler } from "@embra/reactivity";
+
+const rapidChangeCount$ = writable(0);
+
+rapidChangeCount$.reaction(console.log, MicrotaskScheduler);
+
+count$.set(1);
+count$.set(2);
+
+await Promise.resolve();
+// Logs "2" once after a microtask tick, reducing unnecessary computations.
+```
+
+You can also provide your owned custom scheduler function easily.
+
+```ts
+import { writable, asyncScheduler } from "@embra/reactivity";
+
+const MicrotaskScheduler = asyncScheduler(flush => Promise.resolve().then(flush));
+const AnimationFrameScheduler = asyncScheduler(requestAnimationFrame);
+```
+
+</details>
+
 <details>
 <summary>🏗️ Framework agnostic. First-class support for React.</summary>
 

cspell.json

@@ -9,6 +9,7 @@
     "endregion",
     "hyrious",
     "lcov",
+    "microtask",
     "Parens",
     "pnpm",
     "preinstall",

src/react/useValue.ts

@@ -41,6 +41,7 @@ const defaultArgs = [returnsNoop, returnsNoop as () => any] as const;
  * It only triggers re-rendering when new value emitted from $ (base on {@link Readable.version} instead of React's `Object.is` comparison).
  *
  * @param $ A {@link ReadableLike}.
+ * @param scheduler - An optional {@link Scheduler} to control the update frequency. If not provided, updates are applied synchronously.
  * @returns the value of the {@link ReadableLike}, or $ itself if $ is not a {@link ReadableLike}
  *
  * @example
@@ -52,6 +53,16 @@ const defaultArgs = [returnsNoop, returnsNoop as () => any] as const;
  *   return <div>{count}</div>;
  * }
  * ```
+ *
+ * @example
+ * ```tsx
+ * import { useValue, MicrotaskScheduler } from "@embra/reactivity/react";
+ *
+ * function App({ rapidChangeCount$ }) {
+ *   const count = useValue(rapidChangeCount$, MicrotaskScheduler); // update at most once per microtask
+ *   return <div>{count}</div>;
+ * }
+ * ```
  */
 export const useValue: UseValue = <T, U>($: ReadableLike<T> | U, scheduler?: Scheduler): Unwrap<T> | U => {
   const args = useMemo(() => {

src/schedulers/MicrotaskScheduler.ts

@@ -2,7 +2,7 @@ import { asyncScheduler } from "./AsyncScheduler";
 import { type Scheduler, type SchedulerFlush } from "./interface";
 
 /**
- * A {@link Scheduler} that runs updates in microtasks (Promise).
+ * A {@link Scheduler} that runs updates at most once per microtask (Promise).
  */
 export const MicrotaskScheduler: Scheduler = /* @__PURE__ */ asyncScheduler(
   /* @__PURE__ */ ((tick: Promise<void>, flush: SchedulerFlush): Promise<void> => tick.then(flush)).bind(