@tempots/dom/std/value.d.ts

Fully-typed frontend framework alternative to React and Angular

import { GetValueTypes } from '../types/domain';
import { ListenerOptions, Prop, Signal } from './signal';
/**
 * Represents a value that can either be a `Signal<T>` or a generic type `T`.
 *
 * @public
 */
export type Value<T> = Signal<T> | T;
export declare const Value: {
    /**
     * Maps a value or a Signal to a new value.
     * If the value is a Signal, it returns a new Signal with the mapped value.
     * If the value is not a Signal, it returns the mapped value.
     *
     * @typeParam T - The type of the value.
     * @typeParam U - The type of the new value.
     * @param value - The value or Signal to map.
     * @param fn - The function to map the value.
     * @returns The mapped value.
     */
    map: <T, U>(value: Value<T>, fn: (value: T) => U) => Value<U>;
    /**
     * Wraps a value or a Signal instance into a Signal.
     * If the value is already a Signal, it returns the value itself.
     * If the value is not a Signal, it creates a new Signal instance with the given value.
     *
     * @typeParam O - The type of the value.
     * @param value - The value or Signal instance to wrap.
     * @param equals - A function that determines if two values are equal. Defaults to strict equality (===).
     * @returns A Signal instance.
     */
    toSignal: <T>(value: Value<T>, equals?: (a: T, b: T) => boolean) => Signal<T>;
    /**
     * Wraps a value in a `Signal` if it is not already a `Signal`.
     * If the value is `null` or `undefined`, it returns `null` or `undefined` respectively.
     * @param value - The value to wrap or check.
     * @returns The wrapped value if it is not `null` or `undefined`, otherwise `null` or `undefined`.
     */
    maybeToSignal: <T>(value: Value<T> | undefined | null, equals?: (a: T, b: T) => boolean) => Signal<T> | undefined;
    /**
     * Gets the value from a `Signal` or the value itself if it is not a `Signal`.
     * @param value - The value or Signal instance to get the value from.
     * @returns The value.
     */
    get: <T>(value: Value<T>) => T;
    /**
     * Adds a listener to a `Signal` or calls the listener immediately if it is not a `Signal`.
     * @param value - The value or Signal instance to add the listener to.
     * @param listener - The listener to call when the value changes.
     * @returns A function to remove the listener.
     */
    on: <T>(value: Value<T>, listener: (value: T) => void) => (() => void);
    /**
     * Disposes of a value or a Signal.
     * If the value is a Signal, it disposes of the Signal.
     * If the value is not a Signal, it does nothing.
     * @param value - The value or Signal instance to dispose of.
     */
    dispose: <T>(value: Value<T>) => void;
    /**
     * Derives a Prop from a Signal.
     * If the value is a Signal, it returns a new Prop with the derived value.
     * If the value is not a Signal, it returns a new Prop with the value.
     * @param value - The value or Signal instance to derive the Prop from.
     * @param options - The options for the derived Prop.
     * @param options.autoDisposeProp - Determines whether the derived Prop should be automatically disposed.
     * @param options.equals - A function that determines if two values are equal.
     * @returns A Prop instance.
     */
    deriveProp: <T>(value: Value<T>, { autoDisposeProp, equals, }?: {
        autoDisposeProp?: boolean;
        equals?: (a: T, b: T) => boolean;
    }) => Prop<T>;
};
/**
 * Creates a computed signal that depends on other signals or literal values and updates when any of the dependencies change.
 *
 * @typeParam T - The type of the argument values.
 * @param fn - The function that computes the value.
 * @param equals - The equality function used to compare the previous and current computed values.
 * @returns - The computed signal.
 * @public
 */
export declare const makeComputedOf: <T extends Value<unknown>[]>(...args: T) => <O>(fn: (...args: GetValueTypes<T>) => O, equals?: (a: O, b: O) => boolean) => import('./signal').Computed<O>;
/**
 * Creates an effect that depends on other signals or literal values and updates when any of the dependencies change.
 *
 * @param args - The array of signals or literal values that the effect depends on.
 * @returns A disposable object that can be used to stop the effect.
 * @public
 */
export declare const makeEffectOf: <T extends Value<unknown>[]>(...args: T) => (fn: (...args: GetValueTypes<T>) => void, options?: ListenerOptions) => () => void;