@tempots/dom 18.0.0 → 19.0.0

package/std/signal-utils.d.ts

@@ -1,50 +1,226 @@
 import { RemoveSignals, Value } from '../types/domain';
 import { AnySignal, Computed, Prop, Signal } from './signal';
 
+/**
+ * Represents a memory store that stores key-value pairs.
+ *
+ * @public
+ */
 export declare class MemoryStore {
     private readonly _store;
-    getItem: (key: string) => string | null;
-    setItem: (key: string, value: string) => void;
+    /**
+     * Retrieves the value associated with the specified key from the memory store.
+     * @param key - The key to retrieve the value for.
+     * @returns The value associated with the key, or `null` if the key is not found.
+     */
+    readonly getItem: (key: string) => string | null;
+    /**
+     * Sets the value associated with the specified key in the memory store.
+     * @param key - The key to set the value for.
+     * @param value - The value to set.
+     */
+    readonly setItem: (key: string, value: string) => void;
 }
-export declare function storedProp<T>({ key, defaultValue, store, serialize, deserialize, equals, onLoad, }: {
+/**
+ * Represents the properties required for storing and retrieving a value of type `T`.
+ *
+ * @typeParam T - The type of the value to be stored.
+ * @public
+ */
+export type StoredPropOptions<T> = {
+    /**
+     * The key to use for storing and retrieving the value.
+     */
     key: string;
+    /**
+     * The default value to use if the value is not found in the store.
+     * This can be a value of type `T` or a function that returns a value of type `T`.
+     * If a function is provided, it will be called to get the default value.
+     */
     defaultValue: T | (() => T);
+    /**
+     * The store to use for storing and retrieving the value.
+     */
     store: {
+        /**
+         * Retrieves the value associated with the specified key from the store.
+         * @param key - The key to retrieve the value for.
+         * @returns The value associated with the key, or `null` if the key is not found.
+         */
         getItem: (key: string) => string | null;
+        /**
+         * Sets the value associated with the specified key in the store.
+         * @param key - The key to set the value for.
+         * @param value - The value to set.
+         */
         setItem: (key: string, value: string) => void;
     };
+    /**
+     * A function that serializes a value of type `T` to a string.
+     * The default implementation uses `JSON.stringify`.
+     */
     serialize?: (v: T) => string;
+    /**
+     * A function that deserializes a string to a value of type `T`.
+     * The default implementation uses `JSON.parse`.
+     */
     deserialize?: (v: string) => T;
+    /**
+     * A function that compares two values of type `T` for equality.
+     * The default implementation uses strict equality (`===`).
+     */
     equals?: (a: T, b: T) => boolean;
+    /**
+     * A function that is called when a value is loaded from the store.
+     * The default implementation returns the value as is.
+     */
     onLoad?: (value: T) => T;
-}): Prop<T>;
-export declare function localStorageProp<T>(options: {
+};
+/**
+ * Creates a stored property that persists its value in a storage mechanism.
+ *
+ * @typeParam T - The type of the property value.
+ * @param options - The options for creating the stored property.
+ * @returns - The created stored property.
+ * @public
+ */
+export declare const storedProp: <T>({ key, defaultValue, store, serialize, deserialize, equals, onLoad, }: StoredPropOptions<T>) => Prop<T>;
+/**
+ * Represents the properties required for storing and retrieving a value of type `T`.
+ *
+ * @typeParam T - The type of the value to be stored.
+ * @public
+ */
+export type StorageOptions<T> = {
+    /**
+     * The key to use for storing and retrieving the value.
+     */
     key: string;
+    /**
+     * The default value to use if the value is not found in the store.
+     * This can be a value of type `T` or a function that returns a value of type `T`.
+     * If a function is provided, it will be called to get the default value.
+     */
     defaultValue: T | (() => T);
+    /**
+     * A function that serializes a value of type `T` to a string.
+     * The default implementation uses `JSON.stringify`.
+     */
     serialize?: (v: T) => string;
+    /**
+     * A function that deserializes a string to a value of type `T`.
+     * The default implementation uses `JSON.parse`.
+     */
     deserialize?: (v: string) => T;
+    /**
+     * A function that compares two values of type `T` for equality.
+     * The default implementation uses strict equality (`===`).
+     */
     equals?: (a: T, b: T) => boolean;
+    /**
+     * A function that is called when a value is loaded from the store.
+     * The default implementation returns the value as is.
+     */
     onLoad?: (value: T) => T;
-}): Prop<T>;
-export declare function sessionStorageProp<T>(options: {
-    key: string;
-    defaultValue: T | (() => T);
-    serialize?: (v: T) => string;
-    deserialize?: (v: string) => T;
-    equals?: (a: T, b: T) => boolean;
-    onLoad?: (value: T) => T;
-}): Prop<T>;
-export declare function animateSignals<T>(initialValue: T, fn: () => T, dependencies: Array<AnySignal>, options?: {
+};
+/**
+ * Creates a prop that is backed by the localStorage or a MemoryStore.
+ *
+ * @param options - The options for creating the prop.
+ * @returns The created prop.
+ * @public
+ */
+export declare const localStorageProp: <T>(options: StorageOptions<T>) => Prop<T>;
+/**
+ * Creates a prop that stores its value in the session storage.
+ *
+ * @param options - The options for the storage prop.
+ * @returns A prop that stores its value in the session storage.
+ * @public
+ */
+export declare const sessionStorageProp: <T>(options: StorageOptions<T>) => Prop<T>;
+/**
+ * Options for animating signals.
+ *
+ * @typeParam T - The type of the signal values.
+ * @public
+ */
+export type AnimateSignalsOptions<T> = {
+    /**
+     * The function that interpolates between two values.
+     */
     interpolate?: (start: T, end: T, delta: number) => T;
+    /**
+     * The duration of the animation in milliseconds.
+     */
     duration?: Value<number>;
+    /**
+     * The easing function for the animation.
+     */
     easing?: (t: number) => number;
+    /**
+     * The function that compares two values for equality.
+     */
     equals?: (a: T, b: T) => boolean;
-}): Prop<T>;
-export declare function animateSignal<T>(signal: Signal<T>, options?: {
+};
+/**
+ * Animates signals based on the provided options.
+ *
+ * @typeParam T - The type of the animated value.
+ * @param initialValue - The initial value of the animation.
+ * @param fn - A function that returns the end value of the animation.
+ * @param dependencies - An array of signals that the animation depends on.
+ * @param options - Optional options for the animation.
+ * @returns - The animated value as Prop<T>
+ * @public
+ */
+export declare const animateSignals: <T>(initialValue: T, fn: () => T, dependencies: Array<AnySignal>, options?: AnimateSignalsOptions<T>) => Prop<T>;
+/**
+ * Represents the configuration options for animating a signal.
+ *
+ * @typeParam T - The type of the signal value.
+ * @public
+ */
+export type AnimateSignal<T> = {
+    /**
+     * The initial value for the animation. If not provided, the current value of the input signal will be used.
+     */
     initialValue?: T;
+    /**
+     * The interpolation function to use for calculating intermediate values during the animation.
+     */
     interpolate?: (start: T, end: T, delta: number) => T;
+    /**
+     * The duration of the animation in milliseconds.
+     */
     duration?: number;
+    /**
+     * The easing function to use for controlling the animation progress.
+     */
     easing?: (t: number) => number;
+    /**
+     * The equality function to use for comparing signal values.
+     */
     equals?: (a: T, b: T) => boolean;
-}): Prop<T>;
-export declare function computedRecord<T extends Record<string, Value<unknown>>, U>(record: T, fn: (value: RemoveSignals<T>) => U): Computed<U>;
+};
+/**
+ * Animates a signal by creating a new signal that transitions from an initial value to the current value of the input signal.
+ *
+ * @typeParam T - The type of the signal value.
+ * @param signal - The input signal to animate.
+ * @param options - The animation options.
+ * @returns - The animated signal.
+ * @public
+ */
+export declare const animateSignal: <T>(signal: Signal<T>, options?: AnimateSignal<T>) => Prop<T>;
+/**
+ * Computes a value based on a record of signals and literals.
+ *
+ * @typeParam T - The type of the record containing signals and literals.
+ * @typeParam O - The type of the computed value.
+ * @param record - The record containing signals and literals.
+ * @param fn - The function to compute the value based on the literals.
+ * @returns - The computed value as a signal.
+ * @public
+ */
+export declare const makeComputedRecord: <T extends Record<string, Value<unknown>>, O>(record: T, fn: (value: RemoveSignals<T>) => O) => Computed<O>;