value-enhancer/src/from.ts

Enhance value with plain and explicit reactive wrapper. Think of it as hook-style signals.

import { ValAgent } from "./agent";
import type { ReadonlyVal, ValConfig, ValDisposer } from "./typings";
import { ValImpl } from "./val";

/**
 * Creates a readonly val from a getter function and a listener function.
 *
 * @param getValue A function that returns the current value.
 * @param onChange A function that takes a notify function and returns a disposer.
 *        The notify function should be called when the value changes.
 * @param config custom config for the val.
 * @returns A readonly val.
 *
 * @example
 * ```ts
 * const prefersDark = window.matchMedia("(prefers-color-scheme: dark)");
 * const isDarkMode$ = from(
 *   () => prefersDark.matches,
 *   notify => {
 *     prefersDark.addEventListener("change", notify);
 *     return () => prefersDark.removeEventListener("change", notify);
 *   },
 * );
 * ```
 */
export const from = <TValue = any>(
  getValue: () => TValue,
  onChange: (notify: () => void) => ValDisposer | void | undefined,
  config?: ValConfig<TValue>
): ReadonlyVal<TValue> => new ValImpl(new ValAgent(getValue, config, onChange));