@ibodr/state 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,1169 @@
+/**
+ * An ArraySet operates as an array until it reaches a certain size, after which a Set is used
+ * instead. In either case, the same methods are used to get, set, remove, and visit the items.
+ * @internal
+ */
+declare class ArraySet<T> {
+    private arraySize;
+    private array;
+    private set;
+    /**
+     * Get whether this ArraySet has any elements.
+     *
+     * @returns True if this ArraySet has any elements, false otherwise.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Add an element to the ArraySet if it is not already present.
+     *
+     * @param elem - The element to add to the set
+     * @returns `true` if the element was added, `false` if it was already present
+     * @example
+     * ```ts
+     * const arraySet = new ArraySet<string>()
+     *
+     * console.log(arraySet.add('hello')) // true
+     * console.log(arraySet.add('hello')) // false (already exists)
+     * ```
+     */
+    add(elem: T): boolean;
+    /**
+     * Remove an element from the ArraySet if it is present.
+     *
+     * @param elem - The element to remove from the set
+     * @returns `true` if the element was removed, `false` if it was not present
+     * @example
+     * ```ts
+     * const arraySet = new ArraySet<string>()
+     * arraySet.add('hello')
+     *
+     * console.log(arraySet.remove('hello')) // true
+     * console.log(arraySet.remove('hello')) // false (not present)
+     * ```
+     */
+    remove(elem: T): boolean;
+    /**
+     * Execute a callback function for each element in the ArraySet.
+     *
+     * @param visitor - A function to call for each element in the set
+     * @example
+     * ```ts
+     * const arraySet = new ArraySet<string>()
+     * arraySet.add('hello')
+     * arraySet.add('world')
+     *
+     * arraySet.visit((item) => {
+     *   console.log(item) // 'hello', 'world'
+     * })
+     * ```
+     */
+    visit(visitor: (item: T) => void): void;
+    /**
+     * Make the ArraySet iterable, allowing it to be used in for...of loops and with spread syntax.
+     *
+     * @returns An iterator that yields each element in the set
+     * @example
+     * ```ts
+     * const arraySet = new ArraySet<number>()
+     * arraySet.add(1)
+     * arraySet.add(2)
+     *
+     * for (const item of arraySet) {
+     *   console.log(item) // 1, 2
+     * }
+     *
+     * const items = [...arraySet] // [1, 2]
+     * ```
+     */
+    [Symbol.iterator](): Generator<T, void, unknown>;
+    /**
+     * Check whether an element is present in the ArraySet.
+     *
+     * @param elem - The element to check for
+     * @returns `true` if the element is present, `false` otherwise
+     * @example
+     * ```ts
+     * const arraySet = new ArraySet<string>()
+     * arraySet.add('hello')
+     *
+     * console.log(arraySet.has('hello')) // true
+     * console.log(arraySet.has('world')) // false
+     * ```
+     */
+    has(elem: T): boolean;
+    /**
+     * Remove all elements from the ArraySet.
+     *
+     * @example
+     * ```ts
+     * const arraySet = new ArraySet<string>()
+     * arraySet.add('hello')
+     * arraySet.add('world')
+     *
+     * arraySet.clear()
+     * console.log(arraySet.size()) // 0
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get the number of elements in the ArraySet.
+     *
+     * @returns The number of elements in the set
+     * @example
+     * ```ts
+     * const arraySet = new ArraySet<string>()
+     * console.log(arraySet.size()) // 0
+     *
+     * arraySet.add('hello')
+     * console.log(arraySet.size()) // 1
+     * ```
+     */
+    size(): number;
+}
+
+/**
+ * A unique symbol used to indicate that a signal's value should be reset or that
+ * there is insufficient history to compute diffs between epochs.
+ *
+ * This value is returned by {@link Signal.getDiffSince} when the requested epoch
+ * is too far in the past and the diff sequence cannot be reconstructed.
+ *
+ * @example
+ * ```ts
+ * import { atom, getGlobalEpoch, RESET_VALUE } from '@ibodr/state'
+ *
+ * const count = atom('count', 0, { historyLength: 3 })
+ * const oldEpoch = getGlobalEpoch()
+ *
+ * // Make many changes that exceed history length
+ * count.set(1)
+ * count.set(2)
+ * count.set(3)
+ * count.set(4)
+ *
+ * const diffs = count.getDiffSince(oldEpoch)
+ * if (diffs === RESET_VALUE) {
+ *   console.log('Too many changes, need to reset state')
+ * }
+ * ```
+ *
+ * @public
+ */
+declare const RESET_VALUE: unique symbol;
+/**
+ * Type representing the the unique symbol RESET_VALUE symbol, used in type annotations
+ * to indicate when a signal value should be reset or when diff computation
+ * cannot proceed due to insufficient history.
+ *
+ * @public
+ */
+type RESET_VALUE = typeof RESET_VALUE;
+/**
+ * A reactive value container that can change over time and track diffs between sequential values.
+ *
+ * Signals are the foundation of the \@ibodr/state reactive system. They automatically manage
+ * dependencies and trigger updates when their values change. Any computed signal or effect
+ * that reads from this signal will be automatically recomputed when the signal's value changes.
+ *
+ * There are two types of signal:
+ * - **Atomic signals** - Created using `atom()`. These are mutable containers that can be
+ *   directly updated using `set()` or `update()` methods.
+ * - **Computed signals** - Created using `computed()`. These derive their values from other
+ *   signals and are automatically recomputed when dependencies change.
+ *
+ * @example
+ * ```ts
+ * import { atom, computed } from '@ibodr/state'
+ *
+ * // Create an atomic signal
+ * const count = atom('count', 0)
+ *
+ * // Create a computed signal that derives from the atom
+ * const doubled = computed('doubled', () => count.get() * 2)
+ *
+ * console.log(doubled.get()) // 0
+ * count.set(5)
+ * console.log(doubled.get()) // 10
+ * ```
+ *
+ * @public
+ */
+interface Signal<Value, Diff = unknown> {
+    /**
+     * A human-readable identifier for this signal, used primarily for debugging and performance profiling.
+     *
+     * The name is displayed in debug output from {@link whyAmIRunning} and other diagnostic tools.
+     * It does not need to be globally unique within your application.
+     */
+    name: string;
+    /**
+     * Gets the current value of the signal and establishes a dependency relationship.
+     *
+     * When called from within a computed signal or effect, this signal will be automatically
+     * tracked as a dependency. If this signal's value changes, any dependent computations
+     * or effects will be marked for re-execution.
+     *
+     * @returns The current value stored in the signal
+     */
+    get(): Value;
+    /**
+     * The global epoch number when this signal's value last changed.
+     *
+     * Note that this represents when the value actually changed, not when it was last computed.
+     * A computed signal may recalculate and produce the same value without changing its epoch.
+     * This is used internally for dependency tracking and history management.
+     */
+    lastChangedEpoch: number;
+    /**
+     * Gets the sequence of diffs that occurred between a specific epoch and the current state.
+     *
+     * This method enables incremental synchronization by providing a list of changes that
+     * have occurred since a specific point in time. If the requested epoch is too far in
+     * the past or the signal doesn't have enough history, it returns the unique symbol RESET_VALUE
+     * to indicate that a full state reset is required.
+     *
+     * @param epoch - The epoch timestamp to get diffs since
+     * @returns An array of diff objects representing changes since the epoch, or the unique symbol RESET_VALUE if insufficient history is available
+     */
+    getDiffSince(epoch: number): RESET_VALUE | Diff[];
+    /**
+     * Gets the current value of the signal without establishing a dependency relationship.
+     *
+     * This method bypasses the automatic dependency tracking system, making it useful for
+     * performance-critical code paths where the overhead of dependency capture would be
+     * problematic. Use with caution as it breaks the reactive guarantees of the system.
+     *
+     * **Warning**: This method should only be used when you're certain that you don't need
+     * the calling context to react to changes in this signal.
+     *
+     * @param ignoreErrors - Whether to suppress errors during value retrieval (optional)
+     * @returns The current value without establishing dependencies
+     */
+    __unsafe__getWithoutCapture(ignoreErrors?: boolean): Value;
+    /** @internal */
+    children: ArraySet<Child>;
+}
+/**
+ * Internal interface representing a child node in the signal dependency graph.
+ *
+ * This interface is used internally by the reactive system to manage dependencies
+ * between signals, computed values, and effects. Each child tracks its parent
+ * signals and maintains state needed for efficient dependency graph traversal
+ * and change propagation.
+ *
+ * @internal
+ */
+interface Child {
+    /**
+     * The epoch when this child was last traversed during dependency graph updates.
+     * Used to prevent redundant traversals during change propagation.
+     */
+    lastTraversedEpoch: number;
+    /**
+     * Set of parent signals that this child depends on.
+     * Used for efficient lookup and cleanup operations.
+     */
+    readonly parentSet: ArraySet<Signal<any, any>>;
+    /**
+     * Array of parent signals that this child depends on.
+     * Maintained in parallel with parentSet for ordered access.
+     */
+    readonly parents: Signal<any, any>[];
+    /**
+     * Array of epochs corresponding to each parent signal.
+     * Used to detect which parents have changed since last computation.
+     */
+    readonly parentEpochs: number[];
+    /**
+     * Human-readable name for this child, used in debugging output.
+     */
+    readonly name: string;
+    /**
+     * Whether this child is currently subscribed to change notifications.
+     * Used to optimize resource usage by unsubscribing inactive dependencies.
+     */
+    isActivelyListening: boolean;
+    /**
+     * Debug information tracking ancestor epochs in the dependency graph.
+     * Only populated in debug builds for diagnostic purposes.
+     */
+    __debug_ancestor_epochs__: Map<Signal<any, any>, number> | null;
+}
+/**
+ * A function type that computes the difference between two values of a signal.
+ *
+ * This function is used to generate incremental diffs that can be applied to
+ * reconstruct state changes over time. It's particularly useful for features
+ * like undo/redo, synchronization, and change tracking.
+ *
+ * The function should analyze the previous and current values and return a
+ * diff object that represents the change. If the diff cannot be computed
+ * (e.g., the values are too different or incompatible), it should return
+ * the unique symbol RESET_VALUE to indicate that a full state reset is required.
+ *
+ * @param previousValue - The previous value of the signal
+ * @param currentValue - The current value of the signal
+ * @param lastComputedEpoch - The epoch when the previous value was set
+ * @param currentEpoch - The epoch when the current value was set
+ * @returns A diff object representing the change, or the unique symbol RESET_VALUE if no diff can be computed
+ *
+ * @example
+ * ```ts
+ * import { atom, RESET_VALUE } from '@ibodr/state'
+ *
+ * // Simple numeric diff
+ * const numberDiff: ComputeDiff<number, number> = (prev, curr) => curr - prev
+ *
+ * // Array diff with reset fallback
+ * const arrayDiff: ComputeDiff<string[], { added: string[], removed: string[] }> = (prev, curr) => {
+ *   if (prev.length > 1000 || curr.length > 1000) {
+ *     return RESET_VALUE // Too complex, force reset
+ *   }
+ *   return {
+ *     added: curr.filter(item => !prev.includes(item)),
+ *     removed: prev.filter(item => !curr.includes(item))
+ *   }
+ * }
+ *
+ * const count = atom('count', 0, { computeDiff: numberDiff })
+ * ```
+ *
+ * @public
+ */
+type ComputeDiff<Value, Diff> = (previousValue: Value, currentValue: Value, lastComputedEpoch: number, currentEpoch: number) => Diff | RESET_VALUE;
+
+/**
+ * The options to configure an atom, passed into the {@link atom} function.
+ * @public
+ */
+interface AtomOptions<Value, Diff> {
+    /**
+     * The maximum number of diffs to keep in the history buffer.
+     *
+     * If you don't need to compute diffs, or if you will supply diffs manually via {@link Atom.set}, you can leave this as `undefined` and no history buffer will be created.
+     *
+     * If you expect the value to be part of an active effect subscription all the time, and to not change multiple times inside of a single transaction, you can set this to a relatively low number (e.g. 10).
+     *
+     * Otherwise, set this to a higher number based on your usage pattern and memory constraints.
+     *
+     */
+    historyLength?: number;
+    /**
+     * A method used to compute a diff between the atom's old and new values. If provided, it will not be used unless you also specify {@link AtomOptions.historyLength}.
+     */
+    computeDiff?: ComputeDiff<Value, Diff>;
+    /**
+     * If provided, this will be used to compare the old and new values of the atom to determine if the value has changed.
+     * By default, values are compared using first using strict equality (`===`), then `Object.is`, and finally any `.equals` method present in the object's prototype chain.
+     * @param a - The old value
+     * @param b - The new value
+     * @returns True if the values are equal, false otherwise.
+     */
+    isEqual?(a: any, b: any): boolean;
+}
+/**
+ * An Atom is a signal that can be updated directly by calling {@link Atom.set} or {@link Atom.update}.
+ *
+ * Atoms are created using the {@link atom} function.
+ *
+ * @example
+ * ```ts
+ * const name = atom('name', 'John')
+ *
+ * print(name.get()) // 'John'
+ * ```
+ *
+ * @public
+ */
+interface Atom<Value, Diff = unknown> extends Signal<Value, Diff> {
+    /**
+     * Sets the value of this atom to the given value. If the value is the same as the current value, this is a no-op.
+     *
+     * @param value - The new value to set.
+     * @param diff - The diff to use for the update. If not provided, the diff will be computed using {@link AtomOptions.computeDiff}.
+     */
+    set(value: Value, diff?: Diff): Value;
+    /**
+     * Updates the value of this atom using the given updater function. If the returned value is the same as the current value, this is a no-op.
+     *
+     * @param updater - A function that takes the current value and returns the new value.
+     */
+    update(updater: (value: Value) => Value): Value;
+}
+/**
+ * Creates a new {@link Atom}.
+ *
+ * An Atom is a signal that can be updated directly by calling {@link Atom.set} or {@link Atom.update}.
+ *
+ * @example
+ * ```ts
+ * const name = atom('name', 'John')
+ *
+ * name.get() // 'John'
+ *
+ * name.set('Jane')
+ *
+ * name.get() // 'Jane'
+ * ```
+ *
+ * @public
+ */
+declare function atom<Value, Diff = unknown>(
+/**
+ * A name for the signal. This is used for debugging and profiling purposes, it does not need to be unique.
+ */
+name: string, 
+/**
+ * The initial value of the signal.
+ */
+initialValue: Value, 
+/**
+ * The options to configure the atom. See {@link AtomOptions}.
+ */
+options?: AtomOptions<Value, Diff>): Atom<Value, Diff>;
+/**
+ * Returns true if the given value is an {@link Atom}.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an Atom, false otherwise
+ * @example
+ * ```ts
+ * const myAtom = atom('test', 42)
+ * const notAtom = 'hello'
+ *
+ * console.log(isAtom(myAtom)) // true
+ * console.log(isAtom(notAtom)) // false
+ * ```
+ * @public
+ */
+declare function isAtom(value: unknown): value is Atom<unknown>;
+
+/**
+ * Executes the given function without capturing any parents in the current capture context.
+ *
+ * This is mainly useful if you want to run an effect only when certain signals change while also
+ * dereferencing other signals which should not cause the effect to rerun on their own.
+ *
+ * @example
+ * ```ts
+ * const name = atom('name', 'Sam')
+ * const time = atom('time', () => new Date().getTime())
+ *
+ * setInterval(() => {
+ *   time.set(new Date().getTime())
+ * })
+ *
+ * react('log name changes', () => {
+ * 	 print(name.get(), 'was changed at', unsafe__withoutCapture(() => time.get()))
+ * })
+ *
+ * ```
+ *
+ * @public
+ */
+declare function unsafe__withoutCapture<T>(fn: () => T): T;
+/**
+ * A debugging tool that tells you why a computed signal or effect is running.
+ * Call in the body of a computed signal or effect function.
+ *
+ * @example
+ * ```ts
+ * const name = atom('name', 'Bob')
+ * react('greeting', () => {
+ * 	whyAmIRunning()
+ *	print('Hello', name.get())
+ * })
+ *
+ * name.set('Alice')
+ *
+ * // 'greeting' is running because:
+ * //     'name' changed => 'Alice'
+ * ```
+ *
+ * @public
+ */
+declare function whyAmIRunning(): void;
+
+/**
+ * A special symbol used to indicate that a computed signal has not been initialized yet.
+ * This is passed as the `previousValue` parameter to a computed signal function on its first run.
+ *
+ * @example
+ * ```ts
+ * const count = atom('count', 0)
+ * const double = computed('double', (prevValue) => {
+ *   if (isUninitialized(prevValue)) {
+ *     console.log('First computation!')
+ *   }
+ *   return count.get() * 2
+ * })
+ * ```
+ *
+ * @public
+ */
+declare const UNINITIALIZED: unique symbol;
+/**
+ * The type of the first value passed to a computed signal function as the 'prevValue' parameter.
+ * This type represents the uninitialized state of a computed signal before its first calculation.
+ *
+ * @see {@link isUninitialized}
+ * @public
+ */
+type UNINITIALIZED = typeof UNINITIALIZED;
+/**
+ * Call this inside a computed signal function to determine whether it is the first time the function is being called.
+ *
+ * Mainly useful for incremental signal computation.
+ *
+ * @example
+ * ```ts
+ * const count = atom('count', 0)
+ * const double = computed('double', (prevValue) => {
+ *   if (isUninitialized(prevValue)) {
+ *     print('First time!')
+ *   }
+ *   return count.get() * 2
+ * })
+ * ```
+ *
+ * @param value - The value to check.
+ * @public
+ */
+declare function isUninitialized(value: any): value is UNINITIALIZED;
+/**
+ * A singleton class used to wrap computed signal values along with their diffs.
+ * This class is used internally by the {@link withDiff} function to provide both
+ * the computed value and its diff to the signal system.
+ *
+ * @example
+ * ```ts
+ * const count = atom('count', 0)
+ * const double = computed('double', (prevValue) => {
+ *   const nextValue = count.get() * 2
+ *   if (isUninitialized(prevValue)) {
+ *     return nextValue
+ *   }
+ *   return withDiff(nextValue, nextValue - prevValue)
+ * })
+ * ```
+ *
+ * @public
+ */
+declare const WithDiff: {
+    new <Value, Diff>(value: Value, diff: Diff): {
+        value: Value;
+        diff: Diff;
+    };
+};
+/**
+ * Interface representing a value wrapped with its corresponding diff.
+ * Used in incremental computation to provide both the new value and the diff from the previous value.
+ *
+ * @public
+ */
+interface WithDiff<Value, Diff> {
+    /**
+     * The computed value.
+     */
+    value: Value;
+    /**
+     * The diff between the previous and current value.
+     */
+    diff: Diff;
+}
+/**
+ * When writing incrementally-computed signals it is convenient (and usually more performant) to incrementally compute the diff too.
+ *
+ * You can use this function to wrap the return value of a computed signal function to indicate that the diff should be used instead of calculating a new one with {@link AtomOptions.computeDiff}.
+ *
+ * @example
+ * ```ts
+ * const count = atom('count', 0)
+ * const double = computed('double', (prevValue) => {
+ *   const nextValue = count.get() * 2
+ *   if (isUninitialized(prevValue)) {
+ *     return nextValue
+ *   }
+ *   return withDiff(nextValue, nextValue - prevValue)
+ * }, { historyLength: 10 })
+ * ```
+ *
+ *
+ * @param value - The value.
+ * @param diff - The diff.
+ * @public
+ */
+declare function withDiff<Value, Diff>(value: Value, diff: Diff): WithDiff<Value, Diff>;
+/**
+ * Options for configuring computed signals. Used when calling `computed` or using the `@computed` decorator.
+ *
+ * @example
+ * ```ts
+ * const greeting = computed('greeting', () => `Hello ${name.get()}!`, {
+ *   historyLength: 10,
+ *   isEqual: (a, b) => a === b,
+ *   computeDiff: (oldVal, newVal) => ({ type: 'change', from: oldVal, to: newVal })
+ * })
+ * ```
+ *
+ * @public
+ */
+interface ComputedOptions<Value, Diff> {
+    /**
+     * The maximum number of diffs to keep in the history buffer.
+     *
+     * If you don't need to compute diffs, or if you will supply diffs manually via {@link Atom.set}, you can leave this as `undefined` and no history buffer will be created.
+     *
+     * If you expect the value to be part of an active effect subscription all the time, and to not change multiple times inside of a single transaction, you can set this to a relatively low number (e.g. 10).
+     *
+     * Otherwise, set this to a higher number based on your usage pattern and memory constraints.
+     *
+     */
+    historyLength?: number;
+    /**
+     * A method used to compute a diff between the computed's old and new values. If provided, it will not be used unless you also specify {@link ComputedOptions.historyLength}.
+     */
+    computeDiff?: ComputeDiff<Value, Diff>;
+    /**
+     * If provided, this will be used to compare the old and new values of the computed to determine if the value has changed.
+     * By default, values are compared using first using strict equality (`===`), then `Object.is`, and finally any `.equals` method present in the object's prototype chain.
+     * @param a - The old value
+     * @param b - The new value
+     * @returns True if the values are equal, false otherwise.
+     */
+    isEqual?(a: any, b: any): boolean;
+}
+/**
+ * A computed signal created via the `computed` function or `@computed` decorator.
+ * Computed signals derive their values from other signals and automatically update when their dependencies change.
+ * They use lazy evaluation, only recalculating when accessed and dependencies have changed.
+ *
+ * @example
+ * ```ts
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
+ * const fullName = computed('fullName', () => `${firstName.get()} ${lastName.get()}`)
+ *
+ * console.log(fullName.get()) // "John Doe"
+ * firstName.set('Jane')
+ * console.log(fullName.get()) // "Jane Doe"
+ * ```
+ *
+ * @public
+ */
+interface Computed<Value, Diff = unknown> extends Signal<Value, Diff> {
+    /**
+     * Whether this computed signal is involved in an actively-running effect graph.
+     * Returns true if there are any reactions or other computed signals depending on this one.
+     * @public
+     */
+    readonly isActivelyListening: boolean;
+    /** @internal */
+    readonly parentSet: ArraySet<Signal<any, any>>;
+    /** @internal */
+    readonly parents: Signal<any, any>[];
+    /** @internal */
+    readonly parentEpochs: number[];
+}
+/**
+ * Retrieves the underlying computed instance for a given property created with the `computed`
+ * decorator.
+ *
+ * @example
+ * ```ts
+ * class Counter {
+ *   max = 100
+ *   count = atom(0)
+ *
+ *   @computed getRemaining() {
+ *     return this.max - this.count.get()
+ *   }
+ * }
+ *
+ * const c = new Counter()
+ * const remaining = getComputedInstance(c, 'getRemaining')
+ * remaining.get() === 100 // true
+ * c.count.set(13)
+ * remaining.get() === 87 // true
+ * ```
+ *
+ * @param obj - The object
+ * @param propertyName - The property name
+ * @public
+ */
+declare function getComputedInstance<Obj extends object, Prop extends keyof Obj>(obj: Obj, propertyName: Prop): Computed<Obj[Prop]>;
+/**
+ * Creates a computed signal that derives its value from other signals.
+ * Computed signals automatically update when their dependencies change and use lazy evaluation
+ * for optimal performance.
+ *
+ * @example
+ * ```ts
+ * const name = atom('name', 'John')
+ * const greeting = computed('greeting', () => `Hello ${name.get()}!`)
+ * console.log(greeting.get()) // 'Hello John!'
+ * ```
+ *
+ * `computed` may also be used as a decorator for creating computed getter methods.
+ *
+ * @example
+ * ```ts
+ * class Counter {
+ *   max = 100
+ *   count = atom<number>(0)
+ *
+ *   @computed getRemaining() {
+ *     return this.max - this.count.get()
+ *   }
+ * }
+ * ```
+ *
+ * You may optionally pass in a {@link ComputedOptions} when used as a decorator:
+ *
+ * @example
+ * ```ts
+ * class Counter {
+ *   max = 100
+ *   count = atom<number>(0)
+ *
+ *   @computed({isEqual: (a, b) => a === b})
+ *   getRemaining() {
+ *     return this.max - this.count.get()
+ *   }
+ * }
+ * ```
+ *
+ * @param name - The name of the signal for debugging purposes
+ * @param compute - The function that computes the value of the signal. Receives the previous value and last computed epoch
+ * @param options - Optional configuration for the computed signal
+ * @returns A new computed signal
+ * @public
+ */
+declare function computed<Value, Diff = unknown>(name: string, compute: (previousValue: Value | typeof UNINITIALIZED, lastComputedEpoch: number) => Value | WithDiff<Value, Diff>, options?: ComputedOptions<Value, Diff>): Computed<Value, Diff>;
+/**
+ * TC39 decorator for creating computed methods in classes.
+ *
+ * @example
+ * ```ts
+ * class MyClass {
+ *   value = atom('value', 10)
+ *
+ *   @computed
+ *   doubled() {
+ *     return this.value.get() * 2
+ *   }
+ * }
+ * ```
+ *
+ * @param compute - The method to be decorated
+ * @param context - The decorator context provided by TypeScript
+ * @returns The decorated method
+ * @public
+ */
+declare function computed<This extends object, Value>(compute: () => Value, context: ClassMethodDecoratorContext<This, () => Value>): () => Value;
+/**
+ * Legacy TypeScript decorator for creating computed methods in classes.
+ *
+ * @example
+ * ```ts
+ * class MyClass {
+ *   value = atom('value', 10)
+ *
+ *   @computed
+ *   doubled() {
+ *     return this.value.get() * 2
+ *   }
+ * }
+ * ```
+ *
+ * @param target - The class prototype
+ * @param key - The property key
+ * @param descriptor - The property descriptor
+ * @returns The modified property descriptor
+ * @public
+ */
+declare function computed(target: any, key: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+/**
+ * Decorator factory for creating computed methods with options.
+ *
+ * @example
+ * ```ts
+ * class MyClass {
+ *   items = atom('items', [1, 2, 3])
+ *
+ *   @computed({ historyLength: 10 })
+ *   sum() {
+ *     return this.items.get().reduce((a, b) => a + b, 0)
+ *   }
+ * }
+ * ```
+ *
+ * @param options - Configuration options for the computed signal
+ * @returns A decorator function that can be applied to methods
+ * @public
+ */
+declare function computed<Value, Diff = unknown>(options?: ComputedOptions<Value, Diff>): ((target: any, key: string, descriptor: PropertyDescriptor) => PropertyDescriptor) & (<This>(compute: () => Value, context: ClassMethodDecoratorContext<This, () => Value>) => () => Value);
+
+/** @public */
+interface EffectSchedulerOptions {
+    /**
+     * scheduleEffect is a function that will be called when the effect is scheduled.
+     *
+     * It can be used to defer running effects until a later time, for example to batch them together with requestAnimationFrame.
+     *
+     *
+     * @example
+     * ```ts
+     * let isRafScheduled = false
+     * const scheduledEffects: Array<() => void> = []
+     * const scheduleEffect = (runEffect: () => void) => {
+     * 	scheduledEffects.push(runEffect)
+     * 	if (!isRafScheduled) {
+     * 		isRafScheduled = true
+     * 		requestAnimationFrame(() => {
+     * 			isRafScheduled = false
+     * 			scheduledEffects.forEach((runEffect) => runEffect())
+     * 			scheduledEffects.length = 0
+     * 		})
+     * 	}
+     * }
+     * const stop = react('set page title', () => {
+     * 	document.title = doc.title,
+     * }, scheduleEffect)
+     * ```
+     *
+     * @param execute - A function that will execute the effect.
+     * @returns void
+     */
+    scheduleEffect?: (execute: () => void) => void;
+}
+/**
+ * An EffectScheduler is responsible for executing side effects in response to changes in state.
+ *
+ * You probably don't need to use this directly unless you're integrating this library with a framework of some kind.
+ *
+ * Instead, use the {@link react} and {@link reactor} functions.
+ *
+ * @example
+ * ```ts
+ * const render = new EffectScheduler('render', drawToCanvas)
+ *
+ * render.attach()
+ * render.execute()
+ * ```
+ *
+ * @public
+ */
+declare const EffectScheduler: new <Result>(name: string, runEffect: (lastReactedEpoch: number) => Result, options?: EffectSchedulerOptions) => EffectScheduler<Result>;
+/** @public */
+interface EffectScheduler<Result> {
+    /**
+     * Whether this scheduler is attached and actively listening to its parents.
+     * @public
+     */
+    readonly isActivelyListening: boolean;
+    /** @internal */
+    readonly lastTraversedEpoch: number;
+    /** @public */
+    readonly name: string;
+    /** @internal */
+    __debug_ancestor_epochs__: Map<Signal<any, any>, number> | null;
+    /**
+     * The number of times this effect has been scheduled.
+     * @public
+     */
+    readonly scheduleCount: number;
+    /** @internal */
+    readonly parentSet: ArraySet<Signal<any, any>>;
+    /** @internal */
+    readonly parentEpochs: number[];
+    /** @internal */
+    readonly parents: Signal<any, any>[];
+    /** @internal */
+    maybeScheduleEffect(): void;
+    /** @internal */
+    scheduleEffect(): void;
+    /** @internal */
+    maybeExecute(): void;
+    /**
+     * Makes this scheduler become 'actively listening' to its parents.
+     * If it has been executed before it will immediately become eligible to receive 'maybeScheduleEffect' calls.
+     * If it has not executed before it will need to be manually executed once to become eligible for scheduling, i.e. by calling `EffectScheduler.execute`.
+     * @public
+     */
+    attach(): void;
+    /**
+     * Makes this scheduler stop 'actively listening' to its parents.
+     * It will no longer be eligible to receive 'maybeScheduleEffect' calls until `EffectScheduler.attach` is called again.
+     * @public
+     */
+    detach(): void;
+    /**
+     * Executes the effect immediately and returns the result.
+     * @returns The result of the effect.
+     * @public
+     */
+    execute(): Result;
+}
+/**
+ * Starts a new effect scheduler, scheduling the effect immediately.
+ *
+ * Returns a function that can be called to stop the scheduler.
+ *
+ * @example
+ * ```ts
+ * const color = atom('color', 'red')
+ * const stop = react('set style', () => {
+ *   divElem.style.color = color.get()
+ * })
+ * color.set('blue')
+ * // divElem.style.color === 'blue'
+ * stop()
+ * color.set('green')
+ * // divElem.style.color === 'blue'
+ * ```
+ *
+ *
+ * Also useful in React applications for running effects outside of the render cycle.
+ *
+ * @example
+ * ```ts
+ * useEffect(() => react('set style', () => {
+ *   divRef.current.style.color = color.get()
+ * }), [])
+ * ```
+ *
+ * @public
+ */
+declare function react(name: string, fn: (lastReactedEpoch: number) => any, options?: EffectSchedulerOptions): () => void;
+/**
+ * The reactor is a user-friendly interface for starting and stopping an `EffectScheduler`.
+ *
+ * Calling `.start()` will attach the scheduler and execute the effect immediately the first time it is called.
+ *
+ * If the reactor is stopped, calling `.start()` will re-attach the scheduler but will only execute the effect if any of its parents have changed since it was stopped.
+ *
+ * You can create a reactor with {@link reactor}.
+ * @public
+ */
+interface Reactor<T = unknown> {
+    /**
+     * The underlying effect scheduler.
+     * @public
+     */
+    scheduler: EffectScheduler<T>;
+    /**
+     * Start the scheduler. The first time this is called the effect will be scheduled immediately.
+     *
+     * If the reactor is stopped, calling this will start the scheduler again but will only execute the effect if any of its parents have changed since it was stopped.
+     *
+     * If you need to force re-execution of the effect, pass `{ force: true }`.
+     * @public
+     */
+    start(options?: {
+        force?: boolean;
+    }): void;
+    /**
+     * Stop the scheduler.
+     * @public
+     */
+    stop(): void;
+}
+/**
+ * Creates a {@link Reactor}, which is a thin wrapper around an `EffectScheduler`.
+ *
+ * @public
+ */
+declare function reactor<Result>(name: string, fn: (lastReactedEpoch: number) => Result, options?: EffectSchedulerOptions): Reactor<Result>;
+
+/**
+ * @public
+ */
+declare const EMPTY_ARRAY: [];
+
+/**
+ * Type guard function that determines whether a value is a signal (either an Atom or Computed).
+ *
+ * This utility function is helpful when working with mixed data types and you need to
+ * differentiate between regular values and reactive signal containers. It returns `true`
+ * if the provided value is either an atomic signal created with `atom()` or a computed
+ * signal created with `computed()`.
+ *
+ * @param value - The value to check, can be of any type
+ * @returns `true` if the value is a Signal (Atom or Computed), `false` otherwise
+ *
+ * @example
+ * ```ts
+ * import { atom, computed, isSignal } from '@ibodr/state'
+ *
+ * const count = atom('count', 5)
+ * const doubled = computed('doubled', () => count.get() * 2)
+ * const regularValue = 'hello'
+ *
+ * console.log(isSignal(count))        // true
+ * console.log(isSignal(doubled))      // true
+ * console.log(isSignal(regularValue)) // false
+ * console.log(isSignal(null))         // false
+ * ```
+ *
+ * @public
+ */
+declare function isSignal(value: any): value is Signal<any>;
+
+/**
+ * Creates a new {@link Atom} that persists its value to localStorage.
+ *
+ * The atom is automatically synced with localStorage - changes to the atom are saved to localStorage,
+ * and the initial value is read from localStorage if it exists. Returns both the atom and a cleanup
+ * function that should be called to stop syncing when the atom is no longer needed. If you need to delete
+ * the atom, you should do it manually after all cleanup functions have been called.
+ *
+ * @example
+ * ```ts
+ * const [theme, cleanup] = localStorageAtom('theme', 'light')
+ *
+ * theme.get() // 'light' or value from localStorage if it exists
+ *
+ * theme.set('dark') // updates atom and saves to localStorage
+ *
+ * // When done:
+ * cleanup() // stops syncing to localStorage
+ * ```
+ *
+ * @param name - The localStorage key and atom name. This is used for both localStorage persistence
+ *   and debugging/profiling purposes.
+ * @param initialValue - The initial value of the atom, used if no value exists in localStorage.
+ * @param options - Optional atom configuration. See {@link AtomOptions}.
+ * @returns A tuple containing the atom and a cleanup function to stop localStorage syncing.
+ * @public
+ */
+declare function localStorageAtom<Value, Diff = unknown>(name: string, initialValue: Value, options?: AtomOptions<Value, Diff>): [Atom<Value, Diff>, () => void];
+
+/**
+ * Batches state updates, deferring side effects until after the transaction completes.
+ * Unlike {@link transact}, this function always creates a new transaction, allowing for nested transactions.
+ *
+ * @example
+ * ```ts
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
+ *
+ * react('greet', () => {
+ *   console.log(`Hello, ${firstName.get()} ${lastName.get()}!`)
+ * })
+ *
+ * // Logs "Hello, John Doe!"
+ *
+ * transaction(() => {
+ *  firstName.set('Jane')
+ *  lastName.set('Smith')
+ * })
+ *
+ * // Logs "Hello, Jane Smith!"
+ * ```
+ *
+ * If the function throws, the transaction is aborted and any signals that were updated during the transaction revert to their state before the transaction began.
+ *
+ * @example
+ * ```ts
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
+ *
+ * react('greet', () => {
+ *   console.log(`Hello, ${firstName.get()} ${lastName.get()}!`)
+ * })
+ *
+ * // Logs "Hello, John Doe!"
+ *
+ * transaction(() => {
+ *  firstName.set('Jane')
+ *  throw new Error('oops')
+ * })
+ *
+ * // Does not log
+ * // firstName.get() === 'John'
+ * ```
+ *
+ * A `rollback` callback is passed into the function.
+ * Calling this will prevent the transaction from committing and will revert any signals that were updated during the transaction to their state before the transaction began.
+ *
+ * @example
+ * ```ts
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
+ *
+ * react('greet', () => {
+ *   console.log(`Hello, ${firstName.get()} ${lastName.get()}!`)
+ * })
+ *
+ * // Logs "Hello, John Doe!"
+ *
+ * transaction((rollback) => {
+ *  firstName.set('Jane')
+ *  lastName.set('Smith')
+ *  rollback()
+ * })
+ *
+ * // Does not log
+ * // firstName.get() === 'John'
+ * // lastName.get() === 'Doe'
+ * ```
+ *
+ * @param fn - The function to run in a transaction, called with a function to roll back the change.
+ * @returns The return value of the function
+ * @public
+ */
+declare function transaction<T>(fn: (rollback: () => void) => T): T;
+/**
+ * Like {@link transaction}, but does not create a new transaction if there is already one in progress.
+ * This is the preferred way to batch state updates when you don't need the rollback functionality.
+ *
+ * @example
+ * ```ts
+ * const count = atom('count', 0)
+ * const doubled = atom('doubled', 0)
+ *
+ * react('update doubled', () => {
+ *   console.log(`Count: ${count.get()}, Doubled: ${doubled.get()}`)
+ * })
+ *
+ * // This batches both updates into a single reaction
+ * transact(() => {
+ *   count.set(5)
+ *   doubled.set(count.get() * 2)
+ * })
+ * // Logs: "Count: 5, Doubled: 10"
+ * ```
+ *
+ * @param fn - The function to run in a transaction
+ * @returns The return value of the function
+ * @public
+ */
+declare function transact<T>(fn: () => T): T;
+/**
+ * Defers the execution of asynchronous effects until they can be properly handled.
+ * This function creates an asynchronous transaction context that batches state updates
+ * across async operations while preventing conflicts with synchronous transactions.
+ *
+ * @example
+ * ```ts
+ * const data = atom('data', null)
+ * const loading = atom('loading', false)
+ *
+ * await deferAsyncEffects(async () => {
+ *   loading.set(true)
+ *   const result = await fetch('/api/data')
+ *   const json = await result.json()
+ *   data.set(json)
+ *   loading.set(false)
+ * })
+ * ```
+ *
+ * @param fn - The async function to execute within the deferred context
+ * @returns A promise that resolves to the return value of the function
+ * @throws Will throw if called during a synchronous transaction
+ * @internal
+ */
+declare function deferAsyncEffects<T>(fn: () => Promise<T>): Promise<T | undefined>;
+
+export { ArraySet, type Atom, type AtomOptions, type Child, type ComputeDiff, type Computed, type ComputedOptions, EMPTY_ARRAY, EffectScheduler, type EffectSchedulerOptions, RESET_VALUE, type Reactor, type Signal, UNINITIALIZED, WithDiff, atom, computed, deferAsyncEffects, getComputedInstance, isAtom, isSignal, isUninitialized, localStorageAtom, react, reactor, transact, transaction, unsafe__withoutCapture, whyAmIRunning, withDiff };