useWhenever

Shorthand for watching a source and running an effect only when the value is truthy. Built on watch — lazy by default (immediate: false).

Usage

Hook

import { useObservable, useWhenever } from "@usels/web";

function Component() {
  const isReady$ = useObservable(false);

  // ✅ Effect only runs when isReady$ is truthy
  useWhenever(isReady$, (value) => {
    console.log("ready:", value);
  });
}

Scope

import { observable, whenever } from "@usels/web";

function Component() {
  "use scope"
  const isReady$ = observable(false);

  // ✅ Effect only runs when isReady$ is truthy
  whenever(isReady$, (value) => {
    console.log("ready:", value);
  });
}

Eager mode (immediate: true)

Pass immediate: true to also fire on setup if the value is already truthy.

Hook

import { useObservable, useWhenever } from "@usels/web";

function Component() {
  const isReady$ = useObservable(true);

  useWhenever(
    isReady$,
    (value) => {
      console.log("value:", value);
    },
    { immediate: true } // fires immediately since isReady$ is truthy
  );
}

Scope

import { observable, whenever } from "@usels/web";

function Component() {
  "use scope"
  const isReady$ = observable(true);

  whenever(
    isReady$,
    (value) => {
      console.log("value:", value);
    },
    { immediate: true } // fires immediately since isReady$ is truthy
  );
}

Once (once: true)

Dispose the watcher automatically after the first truthy invocation.

Hook

import { useObservable, useWhenever } from "@usels/web";

function Component() {
  const token$ = useObservable<string | null>(null);

  // ✅ Only fires the first time token$ becomes truthy
  useWhenever(
    () => token$.get(),
    (token) => {
      console.log("got token:", token);
    },
    { once: true }
  );
}

Scope

import { observable, whenever } from "@usels/web";

function Component() {
  "use scope"
  const token$ = observable<string | null>(null);

  // ✅ Only fires the first time token$ becomes truthy
  whenever(
    () => token$.get(),
    (token) => {
      console.log("got token:", token);
    },
    { once: true }
  );
}

Reactive function selector

Use a function to derive a truthy/falsy value from one or more observables.

Hook

import { useObservable, useWhenever } from "@usels/web";

function Component() {
  const user$ = useObservable<{ name: string } | null>(null);

  useWhenever(
    () => user$.get(),
    (user) => {
      console.log("user logged in:", user.name);
    }
  );
}

Scope

import { observable, whenever } from "@usels/web";

function Component() {
  "use scope"
  const user$ = observable<{ name: string } | null>(null);

  whenever(
    () => user$.get(),
    (user) => {
      console.log("user logged in:", user.name);
    }
  );
}

Batch scheduling (schedule)

The schedule option controls when the effect runs relative to Legend-State’s batch cycle.

• schedule: 'sync' — runs synchronously inside the batch
• schedule: 'deferred' — runs after the batch ends
• omitted — uses Legend-State’s default batching

useWhenever(flag$, (v) => console.log(v), { schedule: "sync" });

Type

export { whenever, type WheneverOptions, type Truthy } from "./core";
export type UseWhenever = typeof whenever;
/**
 * Shorthand for watching a source and running an effect only when the value is truthy.
 * Built on `watch` — lazy by default (`immediate: false`).
 *
 * @param selector - Observable or reactive function returning `T`.
 * @param effect   - Callback invoked with the truthy value.
 * @param options  - `immediate`, `schedule`, `once`.
 *
 * @example
 * ```tsx twoslash
 * // @noErrors
 * import { useWhenever } from "@usels/core";
 * import { observable } from "@legendapp/state";
 *
 * const isReady$ = observable(false);
 *
 * useWhenever(isReady$, (value) => {
 *   console.log("ready:", value); // only called when truthy
 * });
 * ```
 */
export declare const useWhenever: UseWhenever;

Source

View on GitHub