/**
* TypeScript type representation of the standard `setTimeout` function.
*
* This type is isolated in a separate file to avoid referencing the global
* `setTimeout` directly in the main bundle, which would automatically add a
* Node.js reference (`/// `) to the bundle.
*
* @remarks
* The separation is necessary because using `typeof setTimeout` in the same
* file where `setTimeout` is referenced as a variable in the module scope
* would cause TypeScript to add Node.js type references, potentially creating
* issues in non-Node environments.
* @example
* // How to use this type
* import { SetTimeout } from '@reatom/core'
*
* function setupTimer(customTimeout: SetTimeout) {
* return customTimeout(() => console.log('Timer fired'), 1000)
* }
*
* @public
* @see {@link https://github.com/reatom/reatom/issues/983} for the original issue and discussion
*/import { StandardSchemaV1 } from "@standard-schema/spec";
//#region src/setTimeout.d.ts
type SetTimeout = typeof setTimeout;
//#endregion
//#region src/utils.d.ts
/**
* Generic function type representing any function that takes any parameters and
* returns any value. Used throughout Reatom for typing function parameters and
* callbacks.
*/
interface Fn {
(...params: any[]): any;
}
/**
* Type alias for Record for brevity. Represents an object with
* string keys and values of type T.
*
* @template T - The type of values in the record (defaults to any)
*/
type Rec = Record;
/**
* Function interface for unsubscribing from subscriptions. Used consistently
* throughout Reatom for cleanup functions.
*/
interface Unsubscribe {
(): void;
}
/**
* Type representing different possible return values from observable
* subscription methods. Supports both function-based unsubscribers and objects
* with unsubscribe methods.
*/
type MaybeUnsubscribe = void | Exclude<{}, Fn> | Unsubscribe | {
unsubscribe: Unsubscribe;
};
/**
* Utility type that converts properties with undefined values to optional
* properties. Makes properties with object or null values required, while
* making other properties optional.
*
* @template T - The object type to transform
*/
type UndefinedToOptional = Partial & PickValues;
/**
* Union type of all JavaScript falsy values except for NaN. Includes: false, 0,
* empty string, null, and undefined.
*
* @see https://stackoverflow.com/a/51390763
*/
type Falsy = false | 0 | '' | null | undefined;
/**
* Removes named generics to produce a plain type representation. Preserves
* function signatures and object structure while eliminating generic parameter
* names.
*
* This is useful for presenting cleaner types in documentation and error
* messages.
*
* @template Intersection - The type to convert to a plain representation
*/
type Plain = Intersection extends ((...params: infer I) => infer O) ? ((...params: I) => O) & { [Key in keyof Intersection]: Intersection[Key] } : Intersection extends (new (...params: any[]) => any) ? Intersection : Intersection extends object ? { [Key in keyof Intersection]: Intersection[Key] } : Intersection;
/**
* Creates a shallow clone type of T. Useful for creating a new type that has
* the same shape but is a distinct type.
*
* @template T - The type to create a shallow clone of
*/
type Shallow = { [K in keyof T]: T[K] } & {};
/**
* Represents a constructor function that can be instantiated with the new
* operator.
*
* @template ReturnType - The type of object that will be created when
* instantiated
*/
interface Newable {
new (...params: any[]): ReturnType;
}
/**
* Extracts the union type of all values in an object type.
*
* @template T - The object type to extract values from
*/
type Values = T[keyof T];
/**
* Extracts keys from type T where the corresponding value does not extend type
* V.
*
* @template T - The object type to extract keys from
* @template V - The value type to exclude
*/
type OmitValuesKeys = Values<{ [K in keyof T]: T[K] extends V ? never : K }>;
/**
* Creates a type with all properties from T except those with values extending
* V.
*
* @template T - The object type to filter properties from
* @template V - The value type to exclude
*/
type OmitValues = { [K in OmitValuesKeys]: T[K] };
/**
* Extracts keys from type T where the corresponding value extends type V.
*
* @template T - The object type to extract keys from
* @template V - The value type to include
*/
type PickValuesKeys = Values<{ [K in keyof T]: T[K] extends V ? K : never }>;
/**
* Creates a type with only properties from T with values extending V.
*
* @template T - The object type to filter properties from
* @template V - The value type to include
*/
type PickValues = { [K in PickValuesKeys]: T[K] };
/**
* Flattens a function type with up to 5 overloads into a single function
* signature. This creates a union of the parameter types and return types.
*
* Useful for generic type handling of overloaded functions.
*
* @template T - The overloaded function type to flatten
*/
type Overloads = T extends {
(...params: infer Overload1Params): infer Return1;
(...params: infer Overload2Params): infer Return2;
(...params: infer Overload3Params): infer Return3;
(...params: infer Overload4Params): infer Return4;
(...params: infer Overload5Params): infer Return5;
} ? (...params: Overload1Params | Overload2Params | Overload3Params | Overload4Params | Overload5Params) => Return1 | Return2 | Return3 | Return4 | Return5 : never;
/**
* Extracts the parameters type from an overloaded function. Returns a union of
* all possible parameter tuples.
*
* @template T - The overloaded function type to extract parameters from
*/
type OverloadParameters = Parameters>;
/**
* Asserts that a value is truthy, throwing an error if it's falsy. This is a
* TypeScript type assertion function that helps with type narrowing.
*
* @param value - The value to check
* @param message - The error message to use if the assertion fails
* @param ErrorConstructor - Optional custom error constructor to use (defaults
* to Error)
* @throws {Error} Throws an error with the provided message if value is falsy
*/
declare function assert(value: unknown, message: string, ErrorConstructor?: Newable): asserts value;
/**
* No-operation function that accepts any parameters and returns undefined.
* Useful as a default callback or for stubbing functionality.
*/
declare const noop: (...params: any[]) => any;
/**
* Identity function that returns the first argument unchanged. Can accept
* additional parameters but ignores them.
*
* @template T - The type of value being passed through
* @param value - The value to return
* @returns The same value that was passed in
*/
declare const identity: (value: T, ...a: any[]) => T;
/**
* Creates a promise that resolves after the specified number of milliseconds.
* Useful for creating delays in async functions.
*
* @param ms - The number of milliseconds to sleep (defaults to 0)
* @returns A promise that resolves after the specified delay
*/
declare const sleep: (ms?: number) => Promise;
/**
* Type guard that checks if a value is an object (non-null and typeof
* 'object'). Provides advanced type narrowing to either the original object
* type or a generic object type.
*
* @template T - The type of value being checked
* @param thing - The value to check
* @returns True if the value is a non-null object, false otherwise
*/
declare const isObject: (thing: T) => thing is T extends Record ? T : Record;
/**
* Type guard that checks if a value is a plain object (a simple object literal
* or created with Object.create(null)). Verifies that the object either has no
* prototype or its prototype is Object.prototype.
*
* @param thing - The value to check
* @returns True if the value is a plain object, false otherwise
*/
declare const isRec: (thing: unknown) => thing is Record;
/**
* Performs a shallow equality comparison between two values. Handles
* primitives, objects, dates, regular expressions, arrays, maps, and sets.
*
* For iterables, compares each item in sequence for equality. For objects,
* compares direct property values but not nested objects deeply.
*
* @param a - First value to compare
* @param b - Second value to compare
* @param is - Optional comparison function to use for individual values
* (defaults to Object.is)
* @returns True if the values are shallowly equal, false otherwise
*/
declare const isShallowEqual: (a: any, b: any, is?: (value1: any, value2: any) => boolean) => any;
/**
* Performs a deep equality comparison between two values. Recursively compares
* nested objects and arrays while properly handling cyclic references.
*
* Handles primitives, objects, dates, regular expressions, arrays, maps, and
* sets. Uses a WeakMap to track visited objects to avoid infinite recursion
* with circular references.
*
* @param a - First value to compare
* @param b - Second value to compare
* @returns True if the values are deeply equal, false otherwise
*/
declare const isDeepEqual: (a: any, b: any) => any;
/**
* Type utility for merging up to four types with proper type safety. Properties
* from later types override properties from earlier types. Preserves function
* signatures from T1 if it's a function type.
*
* @template T1 - First type to merge
* @template T2 - Second type to merge, overrides T1 properties
* @template T3 - Optional third type to merge, overrides T1 and T2 properties
* @template T4 - Optional fourth type to merge, overrides T1, T2, and T3
* properties
*/
type Assign = Plain<(T1 extends ((...params: infer I) => infer O) ? (...params: I) => O : {}) & Omit & Omit & Omit & T4>;
/**
* Type-safe version of Object.assign that properly handles type merging. Unlike
* standard Object.assign typing, properties with the same name are replaced
* rather than becoming a union type.
*
* @template T1 - Type of the target object
* @template T2 - Type of the first source object
* @template T3 - Type of the optional second source object
* @template T4 - Type of the optional third source object
* @returns A new object with merged properties
*/
declare const assign: {
(a1: T1, a2: T2): Assign;
(a1: T1, a2: T2, a3?: T3): Assign;
(a1: T1, a2: T2, a3?: T3, a4?: T4): Assign;
};
/**
* Creates a new object with merged properties from all provided objects.
* Similar to Object.assign but always creates a new object rather than mutating
* the first argument.
*
* @example
* // Creates a new object: { a: 1, b: 2, c: 3 }
* const obj = merge({ a: 1 }, { b: 2 }, { c: 3 })
*
* @returns A new object with all properties from the provided objects
*/
declare const merge: typeof assign;
/**
* Type-safe version of Object.keys that preserves the key type information.
* Returns an array of keys with the correct type for the object.
*
* @template T - The object type
* @param thing - The object to get keys from
* @returns An array of the object's keys with proper typing
*/
declare const keys: {
(thing: T): Array;
};
/**
* Type-safe version of Object.entries that preserves key and value type
* information. Returns an array of key-value pairs with correct types.
*
* @template T - The object type
* @param thing - The object to get entries from
* @returns An array of [key, value] pairs with proper typing
*/
declare const entries: {
(thing: T): Array<[keyof T, T[keyof T]]>;
};
/**
* Type-safe version of Object.fromEntries that preserves key and value type
* information. Creates an object from an iterable of key-value pairs.
*
* @template K - The key type
* @template V - The value type
* @param entries - An iterable of [key, value] pairs
* @returns An object with the specified keys and values
*/
declare const fromEntries: {
(entries: Iterable): Record;
};
/**
* Creates a new object with only the specified keys from the original object.
*
* @example
* const user = { id: 1, name: 'Alice', email: 'alice@example.com' }
* const userInfo = pick(user, ['name', 'email'])
* // Result: { name: 'Alice', email: 'alice@example.com' }
*
* @template T - The source object type
* @template K - The keys to pick from the object
* @param target - The source object
* @param keys - Array of keys to include in the result
* @returns A new object containing only the specified keys and their values
*/
declare const pick: (target: T, keys: Array) => Plain>;
/**
* Creates a new object excluding the specified keys from the original object.
*
* @example
* const user = { id: 1, name: 'Alice', password: 'secret' }
* const safeUser = omit(user, ['password'])
* // Result: { id: 1, name: 'Alice' }
*
* @template T - The source object type
* @template K - The keys to omit from the object
* @param target - The source object
* @param keys - Array of keys to exclude from the result
* @returns A new object containing all keys except the specified ones
*/
declare const omit: (target: T, keys: Array) => Plain>;
/**
* Creates a deep clone of a value using JSON serialization/deserialization.
* This is a type-safe shortcut to `JSON.parse(JSON.stringify(value))`.
*
* Note: This has limitations with circular references, functions, symbols, and
* special objects like Date (converts to string). Consider using the native
* structuredClone when available.
*
* @template T - The type of value being cloned
* @param value - The value to clone
* @returns A deep clone of the input value
* @see https://developer.mozilla.org/en-US/docs/Web/API/structuredClone
*/
declare const jsonClone: (value: T) => T;
declare let _random: (min?: number, max?: number) => number;
/**
* Generates a random integer between min and max (inclusive).
*
* @param min - The minimum integer value (defaults to 0)
* @param max - The maximum integer value (defaults to Number.MAX_SAFE_INTEGER -
* 1)
* @returns A random integer between min and max
*/
declare const random: typeof _random;
/**
* Replaces the default random number generator with a custom implementation.
* Useful for testing to provide deterministic "random" values.
*
* @example
* // Set up deterministic random values for testing
* const restore = mockRandom(() => 42)
* console.log(random()) // Always returns 42
* restore() // Back to normal random behavior
*
* @param fn - The custom random function to use
* @returns A restore function that reverts to the original random
* implementation when called
*/
declare const mockRandom: (fn: typeof random) => () => void;
/**
* Asserts that a value is not null or undefined. Throws a TypeError if the
* value is null or undefined. Also serves as a type guard to narrow the type to
* non-nullable.
*
* @example
* const name = nonNullable(user.name) // TypeScript knows name is not null or undefined
*
* @template T - The type of value to check
* @param value - The value to check
* @param message - Optional custom error message
* @returns The input value if it's not null or undefined
* @throws {TypeError} If the value is null or undefined
*/
declare const nonNullable: (value: T, message?: string) => NonNullable;
/**
* Converts any JavaScript value to a stable string representation. Handles
* complex data structures and edge cases that JSON.stringify cannot manage.
*
* Provides special handling for:
*
* - Circular references
* - Maps and Sets
* - Symbols
* - Functions
* - Custom class instances
* - Regular objects (with sorted keys for stability)
*
* @example
* // Handles circular references
* const obj = { name: 'test' }
* obj.self = obj
* const key = toStringKey(obj) // No infinite recursion!
*
* // Stable representation of objects (key order doesn't matter)
* toStringKey({ a: 1, b: 2 }) === toStringKey({ b: 2, a: 1 }) // true
*
* @param thing - The value to convert to a string
* @param immutable - Whether to memoize results for complex objects (defaults
* to true)
* @returns A string representation of the value
*/
declare const toStringKey: (thing: any, immutable?: boolean) => string;
/**
* Interface extending DOMException for abort-specific error handling. Used to
* represent errors triggered by AbortController signal aborts.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/AbortController
*/
interface AbortError extends DOMException {
name: 'AbortError';
}
/**
* Converts any value to an AbortError. If the value is already an AbortError,
* it will be returned as is. Otherwise, creates a new AbortError with
* appropriate information.
*
* Handles different environments by using DOMException when available or
* falling back to regular Error with name set to 'AbortError'.
*
* @param reason - The value to convert to an AbortError
* @returns An AbortError instance
*/
declare const toAbortError: (reason: any) => AbortError;
/**
* Checks if an AbortController is aborted and throws an AbortError if it is.
* Useful for quick abort checks at the beginning of async operations.
*
* @param controller - The AbortController to check (can be undefined, null or
* void)
* @throws {AbortError} If the controller's signal is aborted
*/
declare const throwIfAborted: (controller?: void | AbortController | null | undefined) => void;
/**
* Type guard that checks if a value is an AbortError.
*
* @param thing - The value to check
* @returns True if the value is an AbortError, false otherwise
*/
declare const isAbort: (thing: any) => thing is AbortError;
/**
* Creates and throws an AbortError with the provided message. Optionally aborts
* the provided controller with the same error.
*
* @param message - The error message
* @param controller - Optional AbortController to abort
* @throws {AbortError} Always throws the created AbortError
*/
declare const throwAbort: (message?: string, controller?: AbortController) => never;
/**
* Enhanced version of the global setTimeout function. Ensures consistent
* behavior across different environments by handling both numeric and object
* timeout IDs. Adds a toJSON method to object timeout IDs for serialization.
*
* @param handler - The function to call after the timeout
* @param timeout - The time in milliseconds to wait before calling the handler
* @param args - Optional arguments to pass to the handler function
* @returns A timeout ID that can be used with clearTimeout
*/
declare const setTimeout$1: SetTimeout;
/**
* Maximum safe integer value for setTimeout delay. Any timeout value larger
* than this may cause overflow issues in some browsers.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/setTimeout#maximum_delay_value
*/
declare const MAX_SAFE_TIMEOUT: number;
/**
* Represents a constructor function that can be instantiated with the new
* operator.
*
* @template T - The type of object that will be created when instantiated
*/
type Constructor = new (...args: any[]) => T;
/**
* Detects whether the code is running in a browser environment. Checks for the
* existence of window and document objects.
*
* @returns True if running in a browser environment, false otherwise
*/
declare const isBrowser: () => boolean;
/**
* Creates a Promise and returns it along with its resolve and reject functions.
* This utility is similar to the upcoming `Promise.withResolvers()` static
* method. It allows for manual control over a Promise's settlement from outside
* its constructor.
*
* @example
* const { promise, resolve, reject } = withResolvers()
*
* promise
* .then((value) => console.log('Resolved:', value))
* .catch((error) => console.error('Rejected:', error))
*
* // Sometime later, or in a different part of the code:
* if (Math.random() > 0.5) {
* resolve('Success!')
* } else {
* reject(new Error('Failed!'))
* }
*
* @template T - The type of the value the promise will resolve with.
* @property {Promise} promise - The created Promise.
* @property {(value: T) => void} resolve - A function to resolve the promise
* with a value of type T.
* @property {(reason?: any) => void} reject - A function to reject the promise
* with an optional reason.
* @returns An object containing the `promise`, and its `resolve` and `reject`
* functions.
*/
declare const withResolvers: () => {
promise: Promise;
resolve: (value: T) => void;
reject: (reason?: any) => void;
};
/**
* Removes the first occurrence of an item from an array in a single iteration.
* Mutates the array in place by splicing out the found element.
*
* More efficient than using `indexOf` + `splice` as it only walks the array
* once.
*
* @example
* const items = [1, 2, 3, 4]
* removeItem(items, 3) // returns true, items is now [1, 2, 4]
* removeItem(items, 5) // returns false, items unchanged
*
* @template T - The type of elements in the array
* @param array - The array to remove the item from
* @param item - The item to remove (compared using strict equality)
* @returns True if the item was found and removed, false otherwise
*/
declare const removeItem: (array: T[], item: T) => boolean;
//#endregion
//#region src/core/action.d.ts
interface ActionCall {
params: Params;
payload: Payload;
}
/** Autoclearable array of processed events */
interface ActionState extends Array> {}
/** Logic container with atom features */
interface Action extends AtomLike, Params, Payload> {
subscribe: (cb?: (payload: Payload, params: Params) => any) => Unsubscribe;
}
/** Action type that supports all overloads of the original function */
type GAction = T & Action, ReturnType>;
/**
* Type guard to check if a value is a Reatom action.
*
* This function determines whether the given value is an action by checking if
* it's an atom with non-reactive behavior (actions are non-reactive atoms).
*
* @param target - The value to check
* @returns `true` if the value is a Reatom action, `false` otherwise
*/
declare let isAction: (target: unknown) => target is Action;
/**
* Creates an extension that adds middleware to an action, wrapping only the
* call function, not the state.
*
* Unlike `withMiddleware`, which wraps the entire middleware chain (including
* the state update), `withActionMiddleware` wraps only the call function that
* gets passed to `actionMiddleware`. This allows you to decorate the action's
* execution logic without interfering with the action's state management.
*
* @example
* // Creating a retry middleware for actions
* const withRetry = (maxAttempts: number) =>
* withActionMiddleware((target) => {
* return (next, ...params) => {
* let attempts = 0
* while (attempts < maxAttempts) {
* try {
* return next(...params)
* } catch (error) {
* attempts++
* if (attempts >= maxAttempts) throw error
* }
* }
* }
* })
*
* // Using the middleware
* const fetchData = action(async () => {
* const response = await fetch('/api/data')
* return response.json()
* }).extend(withRetry(3))
*
* @template Target - The type of action the middleware will be applied to
* @param cb - A function that receives the target action and returns a
* middleware function that wraps the call
* @returns An extension that applies the middleware when used with .extend()
*/
declare let withActionMiddleware: {
(cb: (target: Action) => (next: Fn, ...params: Params) => Payload): Ext>;
};
/**
* Creates a logic and side effect container.
*
* Actions are used to encapsulate complex logic, perform side effects (like API
* calls), and orchestrate multiple state updates. Unlike atoms, actions are
* meant to be called with parameters and can return values.
*
* Actions also have atom-like features (subscribe, extend) and track their call
* history.
*
* @example
* // Create an action that fetches data and updates state
* const fetchUserData = action(async (userId: string) => {
* const response = await wrap(fetch(`/api/users/${userId}`))
* const data = await wrap(response.json())
*
* // Update state atoms with the fetched data
* userName(data.name)
* userEmail(data.email)
*
* return data // Actions can return values
* }, 'fetchUserData')
*
* // Call the action
* fetchUserData('user123')
*
* @template Params - The parameter types the action accepts
* @template Payload - The return type of the action
* @param cb - The function containing the action's logic
* @param name - Optional name for debugging purposes
* @returns An action instance that can be called with the specified parameters
*/
declare function action any>(cb: T, name?: string): GAction;
declare function action(cb: (...params: Params) => Payload, name?: string): Action;
//#endregion
//#region src/core/actions.d.ts
/**
* Type representing a set of methods converted to Reatom actions.
*
* This type maps each method in the original record to a corresponding Reatom
* action with the same parameter and return types.
*
* @template Methods - Record of functions to be converted to actions
*/
type ActionsExt> = { [K in keyof Methods]: Methods[K] extends ((...params: infer Params) => infer Payload) ? Action : never };
/**
* Extension that binds actions to an atom or action as methods.
*
* This extension adds methods to an atom or action by converting them to Reatom
* actions. Each method is converted to an action with the same name and bound
* to the target. The name of each action will be prefixed with the target's
* name for better debugging.
*
* @example
* const counter = atom(0, 'counter').extend(
* withActions({
* increment: (amount = 1) => counter((prev) => prev + amount),
* decrement: (amount = 1) => counter((prev) => prev - amount),
* reset: () => counter(0),
* }),
* )
*
* counter.increment(5) // Can now call these methods directly
* counter.reset()
*
* @example
* const counter = atom(0, 'counter').extend(
* withActions((target) => ({
* increment: (amount = 1) => target.set((prev) => prev + amount),
* decrement: (amount = 1) => target.set((prev) => prev - amount),
* reset: () => target.set(0),
* })),
* )
*
* @template Target - The atom or action being extended
* @template Methods - Record of functions to convert to actions
* @param options - Either a record of methods or a function that creates
* methods given the target
* @returns An extension that adds the methods as actions
* @throws {ReatomError} If a method name collides with an existing property on
* the target
*/
declare function withActions>(options: Methods | ((target: Target) => Methods)): (target: Target) => ActionsExt;
//#endregion
//#region src/extensions/withAbort.d.ts
interface AbortExt {
abort: Action<[reason?: any]>;
}
/**
* Extension to add abort handling to actions and computed atoms.
*
* @example
* // last-in-win: only the last request matters
* const fetchUser = action(async (id: number) => {
* const response = await wrap(fetch(`/api/user/${id}`))
* return response.json()
* }).extend(withAbort())
*
* fetchUser(1) // will be aborted
* fetchUser(2) // will be aborted
* fetchUser(3) // this one wins
*
* @example
* // first-in-win: ignore subsequent calls until the first completes
* const fetchOnce = action(async () => {
* await wrap(fetch('/api/data'))
* }).extend(withAbort('first-in-win'))
*
* fetchOnce() // runs
* fetchOnce() // ignored, returns previous promise
* fetchOnce() // ignored, returns previous promise
*
* @example
* // manual with manual abort (useful for polling/long-running tasks)
* const poll = action(async () => {
* while (true) {
* await wrap(sleep(1000))
* doSome()
* }
* }).extend(withAbort('manual'))
*
* // start
* poll()
*
* // stop
* poll.abort()
*
* @param strategy - The abort strategy to use:
*
* - `'last-in-win'` (default): Aborts previous concurrent calls when a new one
* starts
* - `'first-in-win'`: Ignores new calls while a previous one is still running
* - `'manual'`: No automatic abort, just adds the `abort` action for manual
* control
*/
declare let withAbort: (strategy?: "last-in-win" | "first-in-win" | "finally" | "manual") => AssignerExt;
//#endregion
//#region src/extensions/withChangeHook.d.ts
/**
* Executes a callback whenever the target atom's state changes.
*
* This extension is essential for creating stable, declarative connections
* between independent modules or features. The hook fires in the "Hooks" phase
* of Reatom's lifecycle (after Updates, before Computations), making it perfect
* for triggering side effects or synchronizing state across module boundaries.
*
* **When to use:**
*
* - Creating stable connections between features that shouldn't depend on each
* other directly
* - Triggering validation when a field's value or state changes
* - Syncing derived state in response to source state changes
* - Managing side effects like DOM updates or analytics based on state changes
* - Coordinating behavior across module boundaries without coupling them
*
* **When NOT to use:**
*
* - In dynamic features, like from computed factories (use `take` or `effect` and
* `ifChanged` instead)
* - When a regular computed dependency would suffice
* - For connection/disconnection events (use `withConnectHook` instead)
*
* The callback receives the new state and previous state. It only fires when
* the state actually changes (referential inequality check via `Object.is`).
* The callback executes within the same reactive context, so you can safely
* call other atoms and actions.
*
* @example
* // Basic usage: React to atom state changes
* const theme = reatomEnum(['light', 'dark', 'system']).extend(
* withChangeHook((state, prevState) => {
* document.body.classList.remove(prevState)
* document.body.classList.add(state)
* }),
* )
*
* @example
* // Stable feature connection: Analytics tracking
* // In userModule.ts
* export const userAtom = atom({ id: null, name: '' }, 'user')
*
* // In analyticsModule.ts
* import { userAtom } from './userModule'
* userAtom.extend(
* withChangeHook((user, prevUser) => {
* if (user.id !== prevUser?.id) {
* analytics.identify(user.id, { name: user.name })
* }
* }),
* )
*
* @template Target - The atom type being extended
* @param cb - Callback fired when state changes. Receives:
*
* - `state` - The new state value
* - `prevState` - The previous state value (undefined on first change)
*
* @returns Extension function to be used with `.extend()`
* @throws {ReatomError} If callback is not a function
* @see {@link addChangeHook} For dynamically adding/removing change hooks
* @see {@link withCallHook} For reacting to action calls instead of state changes
* @see {@link withConnectHook} For reacting to connection lifecycle events
*/
declare let withChangeHook: (cb: (state: AtomState, prevState: undefined | AtomState) => void) => Ext;
/**
* Dynamically adds a change hook to an existing atom and returns a function to
* remove it.
*
* Unlike `withChangeHook` which is applied at atom definition time,
* `addChangeHook` allows you to add and remove hooks at runtime. This is useful
* for temporary subscriptions or when you need conditional hook behavior that
* can be enabled/disabled dynamically.
*
* This feature is rarely needed, you should prefer using `effect` with
* `ifChanged` or `take` instead.
*
* @template T - The atom type
* @param target - The atom to attach the hook to
* @param cb - Callback fired when state changes
* @returns Unsubscribe function to remove this specific hook
* @see {@link withChangeHook} For adding hooks at atom definition time
*/
declare let addChangeHook: (target: T, cb: (state: AtomState, prevState?: AtomState) => void) => Unsubscribe;
/**
* Executes a callback whenever the target action is called.
*
* This extension enables you to react to action invocations, making it
* invaluable for creating stable connections between independent features. The
* hook fires in the "Hooks" phase (after Updates, before Computations) and
* receives both the action's return value and its parameters.
*
* **When to use:**
*
* - Creating stable cross-module connections that react to specific actions
* - Tracking action calls for analytics, logging, or debugging
* - Triggering side effects in response to action completions
* - Coordinating behavior between independent features without coupling them
* - Implementing event-driven communication patterns
*
* **When NOT to use:**
*
* - In dynamic features, like from computed factories (`take` or `effect` and
* `getCalls` instead)
* - When you can achieve the same goal with direct action composition
*
* For actions extended with `withAsync`, you can also hook into `.onFulfill`,
* `.onReject`, or `.onSettle` to react to async completion events.
*
* @example
* // Cross-module coordination: Analytics tracking
* // In checkoutModule.ts
* export const submitOrder = action(async (order) => {
* const result = await api.submitOrder(order)
* return result
* }, 'submitOrder')
*
* // In analyticsModule.ts
* import { submitOrder } from './checkoutModule'
* submitOrder.extend(
* withCallHook((promise, params) => {
* const [order] = params
* analytics.track('new_order', {
* orderId: order.id,
* total: order.total,
* })
* }),
* )
*
* @example
* // Stable feature connection: Form submission tracking
* const fetch = action(async (param: number) => {
* const data = await api.fetch(param)
* return data
* }, 'fetch').extend(withAsync())
*
* fetch.onFulfill.extend(
* withCallHook((call) => {
* console.log('Fetch completed', call.payload)
* }),
* )
*
* @template Target - The action type being extended
* @param cb - Callback fired when action is called. Receives:
*
* - `payload` - The return value of the action
* - `params` - The parameters passed to the action as an array
*
* @returns Extension function to be used with `.extend()`
* @throws {ReatomError} If callback is not a function
* @throws {ReatomError} If applied to an atom instead of an action
* @see {@link addCallHook} For dynamically adding/removing call hooks
* @see {@link withChangeHook} For reacting to atom state changes instead
* @see {@link withAsync} For async action lifecycle hooks (onFulfill, onReject, onSettle)
*/
declare let withCallHook: (cb: (payload: ReturnType, params: OverloadParameters) => void) => Ext;
/**
* Dynamically adds a call hook to an existing action and returns a function to
* remove it.
*
* Unlike `withCallHook` which is applied at action definition time,
* `addCallHook` allows you to add and remove hooks at runtime. This is useful
* for temporary subscriptions, conditional hook behavior, or when integrating
* with external systems that need to be connected and disconnected
* dynamically.
*
* This feature is rarely needed, you should prefer using `effect` with
* `getCalls` or `take` instead.
*
* @template Target - The action type
* @param target - The action to attach the hook to
* @param cb - Callback fired when the action is called
* @returns Unsubscribe function to remove this specific hook
* @see {@link withCallHook} For adding hooks at action definition time
*/
declare let addCallHook: (target: Target, cb: (payload: ReturnType, params: OverloadParameters) => void) => Unsubscribe;
//#endregion
//#region src/extensions/withComputed.d.ts
/**
* A middleware extension that enhances an atom with computed capabilities.
*
* @template Target - The target atom or action type to be extended with
* computed functionality.
* @param {function} computed - A function that computes the new state based on
* the current state.
* @param {Object} [options={}] - Configuration options. Default is `{}`
* @param {boolean} [options.tail=true] - Determines the order of the passed
* computed calling. ATTENTION: use `false` only for computed with fixed size
* of dependencies. Default is `true`
* @returns {Ext} The extended atom or action with computed
* functionality.
*/
declare let withComputed: (computed: (state: AtomState) => AtomState, {
tail
}?: {
tail?: boolean;
}) => Ext;
//#endregion
//#region src/extensions/withConnectHook.d.ts
declare let withConnectHook: (cb: (target: Target) => MaybeUnsubscribe) => Ext;
declare let withDisconnectHook: (cb: (target: Target) => void) => Ext;
//#endregion
//#region src/extensions/withDynamicSubscription.d.ts
/**
* This interface improve `.subscribe` method behavior by relying it on
* `abortVar`. It performs unsubscribe automatically, when abort will occur.
*/
interface DynamicSubscriptionExt {}
declare let withDynamicSubscription: () => (target: Target) => Target & DynamicSubscriptionExt;
//#endregion
//#region src/extensions/withInit.d.ts
/**
* Checks if the current execution context is within the initialization of the
* current atom.
*
* @example
* const search = atom('', 'search').extend(withSearchParams('search'))
* const page = atom(1, 'page').extend(
* withSearchParams('page'),
* withComputed((state) => {
* search() // subscribe to the search changes
* // do NOT drop the persisted state on init
* return isInit() ? state : 1
* }),
* )
*
* @returns {boolean} True if currently in the initialization phase, false
* otherwise
*/
declare let isInit: () => boolean;
/**
* Define dynamically computed initial value for an atom.
*
* Typically, you can use just an init callback in `atom` first argument:
* `atom(() => new Date())`. But if you need to add initial callback after the
* atom creation, so there this extensions is useful.
*
* @example
* const something = reatomSomething().extend(
* withInit((initState) => ({ ...initState, ...additions })),
* )
*
* @example
* const myData = atom(null, 'myData')
* if (meta.env.TEST) {
* myData.extend(withInit(mockData))
* }
*
* @template Target - The atom type that extends AtomLike
* @param {AtomState
* | ((state: AtomState) => AtomState)} init
* The initial value or a function that returns the initial value based on
* current state
* @returns {Ext} An extension that can be applied to an atom
*/
declare let withInit: (init: AtomState | ((state: AtomState, ...params: any[]) => AtomState)) => Ext;
/**
* Extension that runs the passed hook when the atom is initialized.
*
* @example
* const userAtom = atom({ id: 1, name: 'John' }).extend(
* withInitHook((initState) => {
* // Perform any setup logic here
* analytics.track('user_loaded', initState)
* }),
* )
*
* @template Target - The atom type that extends AtomLike
* @param {(initState: AtomState) => any} hook A function to be called
* with the initial state during initialization
* @returns {Ext} An extension that can be applied to an atom
*/
declare let withInitHook: (hook: (initState: AtomState) => any, queue?: QueueKind) => Ext;
//#endregion
//#region src/extensions/withMemo.d.ts
declare let withMemo: (isEqual?: (prevState: AtomState, nextState: AtomState) => boolean) => Ext;
//#endregion
//#region src/extensions/withSuspense.d.ts
/**
* Internal suspense cache record tracking promise state. Do not use it
* directly, only for libraries!
*/
interface SuspenseRecord {
kind: 'pending' | 'fulfilled' | 'rejected';
value: any;
}
/**
* Internal suspense cache mapping promises to their settlement state. Do not
* use it directly, only for libraries!
*/
declare let SUSPENSE: WeakMap, SuspenseRecord>;
/**
* Checks if a promise is settled and returns its value or fallback. If the
* promise is fulfilled, returns the resolved value. If the promise is rejected,
* throws the error. If the promise is pending, returns the fallback value
* (defaults to undefined).
*
* Uses an internal WeakMap cache to track promise states across calls.
*
* @example
* const promise = Promise.resolve(42)
* await promise
* const value = settled(promise) // 42
*
* @param promise - The promise or synchronous value to check
* @param fallback - The value to return if the promise is still pending
* @returns The resolved value if fulfilled, throws if rejected, or fallback if
* pending
*/
declare let settled: (promise: Result | Promise, fallback?: Fallback) => Result | Fallback;
/**
* Extension type that adds a `suspended` computed atom to track resolved values
* from async atoms.
*/
type SuspenseExt = {
suspended: Computed>;
};
/**
* Extension that adds suspense support to async atoms. Creates a `suspended`
* computed atom that tracks the resolved value of promises and throws the
* promise when pending (for React Suspense compatibility).
*
* The `suspended` atom will:
*
* - Return the resolved value immediately if the promise is already fulfilled
* - Throw the promise if it's still pending (allowing Suspense boundaries to
* catch it)
* - Propagate errors if the promise is rejected
* - Automatically update when the promise resolves
*
* @example
* const data = computed(async () => {
* const response = await fetch('/api/data')
* return response.json()
* }, 'data').extend(withSuspense())
*
* // Subscribe to resolved values
* subscribe(data.suspended, (value) => {
* console.log('Resolved:', value)
* })
*
* // Use in React component with Suspense
* function Component() {
* const value = useAtom(data.suspended) // throws promise if pending
* return
{value}
* }
*
* @param options - Configuration options
* @param options.preserve - If true, preserves the previous state when
* suspending instead of throwing immediately. Useful for preventing
* flickering in UI.
* @returns An extension that adds the `suspended` computed atom
*/
declare let withSuspense: >>>({
preserve
}?: {
preserve?: boolean;
}) => Ext>>;
/**
* Helper function to access the suspended value of an atom. Automatically
* applies `withSuspense()` extension if the atom doesn't already have it.
*
* This function:
*
* - Returns the resolved value if the promise is fulfilled
* - Throws the promise if it's still pending (for Suspense boundaries)
* - Throws the error if the promise is rejected
*
* @remarks
* If `withSuspense` is already applied with different `preserve` options, the
* behavior may be inconsistent. Consider applying `withSuspense()` explicitly
* to control options.
* @example
* const data = computed(async () => {
* const response = await fetch('/api/data')
* return response.json()
* }, 'data')
*
* // Automatically applies withSuspense() and returns suspended value
* const result = computed(() => {
* try {
* return suspense(data) // throws promise if pending
* } catch (promise) {
* if (promise instanceof Promise) {
* // Handle pending state
* return undefined
* }
* throw promise // Re-throw errors
* }
* }, 'result')
*
* @param target - The atom to get the suspended value from
* @returns The resolved value (Awaited), or throws a promise/error
*/
declare let suspense: (target: AtomLike) => Awaited;
/**
* Extension that enables asynchronous initialization for synchronous atoms.
* This feature bridges async data loading with sync atom semantics.
*
* During initialization, if the result is a Promise, it throws the promise
* (suspense pattern) and schedules setting the atom's state when resolved.
* After initialization completes, the atom operates fully synchronously.
*
* This is perfect for local-first architectures: load data asynchronously on
* init, then work with it synchronously. Combine with `withChangeHook` to sync
* changes back to a server or database.
*
* **Without callback**: Transforms `Atom>` into `Atom`.
* The atom's async initializer is unwrapped, and consumers receive the resolved
* value.
*
* @example
* const userSettings = atom(async () => {
* const response = await fetch('/api/settings')
* return response.json()
* }).extend(withSuspenseInit())
* // Type: Atom (not Atom>)
*
* effect(() => {
* // After init completes, reads are synchronous
* const settings = userSettings()
* console.log(settings.theme)
* })
*
* @example
* // With callback: Provides an async initializer for any atom type, keeping the original state type.
* // Local-first pattern: async init + sync operations + sync-back
* const todos = atom([]).extend(
* withSuspenseInit(async () => {
* const cached = await indexedDB.get('todos')
* return cached ?? []
* }),
* withChangeHook((newState) => {
* // Sync changes back to storage
* indexedDB.set('todos', newState)
* }),
* )
*
* @example
* // Typed async init with custom default
* const profile = atom<{ username: string; age: number }>(
* throwAbort,
* ).extend(
* withSuspenseInit(async () => {
* const data = await fetchProfile()
* return data ?? { username: 'guest', age: 0 }
* }),
* )
*
* @overload
* @overload
* @param cb - Async or sync initializer function. Receives the current init
* state and returns the new state (or Promise of it).
* @returns Extension that unwraps `Atom>` to `Atom`
* @returns Extension that initializes the atom with the callback result
*/
declare let withSuspenseInit: {
(): Ext>, Atom>;
(cb: (state?: AtomState) => AtomState | Promise>): Ext;
};
//#endregion
//#region src/extensions/withSuspenseRetry.d.ts
/**
* Creates a mixin that retries an async action when it fails coz of a
* suspension
*
* This mixin wraps an async action to automatically retry it when a Promise is
* thrown, which indicates a suspension. It will keep retrying until the action
* completes successfully or throws a non-Promise error.
*
* ⚠️ Be careful with non-idempotent operations inside the action body, as they
* may be executed multiple times during retries. It's recommended to carefully
* plan the execution logic to handle potential retries safely.
*
* @example
* const fetchUserBooks = action(async () => {
* const id = user().id // `user` is a suspended atom
* const response = await fetch(`/api/users/${id}/books`)
* return response.json()
* }).extend(withSuspenseRetry())
*
* @returns The same passed action
*/
declare let withSuspenseRetry: >>() => Ext;
//#endregion
//#region src/methods/variable.d.ts
type NonUndefined = NonNullable | null;
interface AsyncVariableOptions {
name?: string;
defaultValue?: T;
create?: (...params: Params) => T;
}
/**
* Interface for context variables in Reatom
*
* Variables maintain values within the context of a computation tree, allowing
* for context-aware state similar to React's Context API but with more granular
* control and integration with Reatom's reactive system.
*
* @template T - Type of the stored value
* @see {@link https://github.com/tc39/proposal-async-context?tab=readme-ov-file#asynccontextvariable}
*/
declare class Variable {
protected _findReactiveStartIndex: number;
protected create: (...params: Params) => T;
readonly name: `var#${string}`;
constructor(options?: AsyncVariableOptions);
/**
* Gets the frame value of the variable. Traverse the whole stack to find it.
*
* @param {Frame} [frame] - Optional frame to check (defaults to current top
* frame)
* @returns {T} The current value
* @throws {Error} If the variable is not found in the frame tree
*/
get(frame?: Frame): undefined | T;
/**
* Gets the value of the variable and throws an error if it is not found in
* the frame stack.
*
* This method is a stricter version of `get()` that ensures the variable has
* been set to a value. Use this when you expect the variable to always be
* defined and want to fail fast if it is not.
*
* @param {Frame} [frame] - Optional frame to check (defaults to current top
* frame)
* @returns {T} The current value (guaranteed to be defined)
* @throws {ReatomError} If the variable is not set (undefined)
*/
require(frame?: Frame): T;
/**
* Executes a callback function with the variable set to a specific value
* within that execution context
*
* This method creates a new frame in the context tree where the variable is
* bound to the provided value. The callback function runs within this frame,
* allowing any code inside (and its descendants) to access this value via
* `get()`.
*
* @example
* const userVar = variable('user')
*
* userVar.run('Alice', () => {
* console.log(userVar.get()) // 'Alice'
* })
*
* // Passing parameters to callback
* const result = userVar.run('Bob', (x, y) => x + y, 2, 3)
* console.log(result) // 5
*
* @template Params - Types of parameters passed to the callback
* @template Payload - Return type of the callback
* @param {T} value - The value to set for this variable during callback
* execution. Cannot be undefined.
* @param {(...params: Params) => Payload} cb - The callback function to
* execute with the variable set
* @param {...Params} params - Additional parameters to pass to the callback
* @returns {Payload} The return value of the callback
* @throws {ReatomError} If value is undefined
*/
run: GAction<((value: T, cb: (...params: Params) => Payload, ...params: Params) => Payload)>;
/**
* Runs a callback with an auto-created variable value. Only available when
* the variable's create function requires no parameters.
*
* @example
* const loggerVar = variable(() => console, 'logger')
*
* loggerVar.createAndRun(() => {
* loggerVar.get()?.log('Hello!') // uses auto-created console
* })
*/
createAndRun: GAction<((cb: (...params: Params) => Payload, ...params: Params) => Payload)> & ([] extends Params ? {} : never);
/**
* This utility allow you to start a function which will NOT follow the async
* context of this variable.
*
* @example
* // If you want to start a fetch when the atom gets a subscription,
* // but don't want to abort the fetch when the subscription is lost to save the data anyway.
* const some = atom('...').extend(
* withConnectHook((target) => {
* abortVar.spawn(async () => {
* // here `wrap` doesn't follow the connection abort
* const data = await wrap(api.getSome())
* some(data)
* })
* }),
* )
*/
spawn: GAction<((cb: (...params: Params) => Payload, ...params: Params) => Payload)>;
/**
* Gets the variable value from the first frame only, without traversing the
* whole frame tree
*
* Unlike `get()` which searches through parent frames, this method only
* checks the top frame. Returns undefined if the variable is not set in the
* frame.
*
* @returns {undefined | T} The value in the frame, or undefined if not set
*/
first(frame?: Frame): undefined | T;
/**
* Checks if the variable exists in the passed frame stack
*
* @param {Frame} [frame] - Optional frame to check (defaults to current top
* frame)
* @returns {boolean} True if the variable exists in the context
*/
has(frame?: Frame): boolean;
/**
* Traverses the frame tree to find and map the variable value.
*
* @template Result - Return type of the callback
* @param {(value: undefined | T) => undefined | Result} [cb] - Optional
* transformation callback
* @param {Frame} [frame] - Optional frame to check (defaults to current top
* frame)
* @returns {undefined | Result} The transformed value or undefined if not
* found
*/
find(cb?: (payload: undefined | T) => undefined | Result, frame?: Frame): undefined | Result;
/**
* Sets a new variable value for CURRENT frame. Be aware that it is mostly for
* internal use!
*
* @param {...Params} params - Parameters passed to the setter function
* @returns {T} The new value
*/
set(...params: Params): T;
}
/**
* Creates a new context variable with getter and setter functionality
*
* This implementation provides a similar capability to the proposed TC39
* AsyncContextVariable, allowing you to maintain values that are specific to a
* particular execution context. Variables created with this function can be
* accessed and modified within their frame context.
*
* Also, it can be used as IoC/DI container replacement:
*
* | IoC/DI Concept | Variable Equivalent |
* | --------------- | ------------------------------- |
* | Token/Key | `variable('name')` |
* | Provider | `.run(impl, fn)` / `.set(impl)` |
* | Inject/Resolve | `.require()` or `.get()` |
* | Container scope | Execution context (frame stack) |
*
* @example
* // Simple variable with string values
* const currentUser = variable('currentUser')
*
* // Set the value
* currentUser.set('Alice')
*
* // Get the value
* console.log(currentUser.get()) // 'Alice'
*
* // Run code with a different value
* currentUser.run('Bob', () => {
* console.log(currentUser.get()) // 'Bob'
* })
*
* // Advanced variable with custom setter logic
* const userRole = variable((role: string, permissions: string[]) => {
* return { role, permissions }
* }, 'userRole')
*
* userRole.set('admin', ['read', 'write', 'delete'])
*
* @example
* // Using variable as IoC/DI container replacement
* // Step 1: Define service interface (DI contract)
* interface Logger {
* log: (message: string) => void
* }
*
* // Step 2: Create a variable as DI token/key
* const loggerVar = variable('logger')
*
* // Step 3: Inject dependency in atoms/actions via `require()`
* const fetchData = action(async (url: string) => {
* const logger = loggerVar.require()
* logger.log(`Fetching ${url}`)
* const response = await wrap(fetch(url))
* logger.log(`Fetched ${url}`)
* return response.json()
* }, 'fetchData')
*
* // Step 4: Provide implementation at application entry point
* loggerVar.run(console, () => {
* fetchData('/api/users') // uses console as logger
* })
*
* // In tests, createAndRun a mock implementation
* const mockLogger = { log: vi.fn() }
* loggerVar.run(mockLogger, () => {
* fetchData('/api/users') // uses mock logger
* })
*
* @example
* // Variable with creation function for lazy initialization
* // Useful when the dependency needs configuration or is expensive to create
* const dbVar = variable(
* (connectionString: string) => new Database(connectionString),
* 'db',
* )
*
* // Inside a main process function, use `.set()` instead of `.run()`
* // This is handy when you control the whole feature lifecycle
* const initApp = action(async () => {
* // `.set()` creates and binds the value to the current frame
* const db = dbVar.set(process.env.DATABASE_URL)
*
* // All subsequent calls in this frame can access the db
* await loadUsers() // uses dbVar.require() internally
* await loadPosts() // uses dbVar.require() internally
* }, 'initApp')
*
* const loadUsers = action(async () => {
* const db = dbVar.require()
* return db.query('SELECT * FROM users')
* }, 'loadUsers')
*
* @template T - The type of the simple variable (when used with just a name)
* @template Params - Types of parameters for the setter function
* @template Payload - The type of the stored value
* @see {@link https://github.com/tc39/proposal-async-context?tab=readme-ov-file#asynccontextvariable}
*/
declare let variable: {
(name?: string): Variable;
(set: (...params: Params) => Payload, name?: string): Variable;
};
//#endregion
//#region src/methods/abortVar.d.ts
/**
* Version of abort controller with explicit name for better debugging.
*
* May control variable propagation by setting the `spawned` flag (used
* internally to handle abort boundaries).
*
* @param name - The name of the abort controller
* @param spawned - Whether to traverse the frame tree beyond the current frame
* (default: `false`)
*/
declare class ReatomAbortController extends AbortController {
name: string;
spawned: boolean;
constructor(name: string, spawned?: boolean);
abort(reason?: any): void;
}
interface ControlledPromise extends Promise {
controller: AbortController;
}
interface AbortSubscription {
controller: ReatomAbortController;
unsubscribe: Unsubscribe;
[Symbol.dispose]: Unsubscribe;
[Symbol.asyncDispose]: Unsubscribe;
/**
* Controller that managed the subscribtion itself, mostly for internal usage.
*
* @private
*/
listenerController: AbortController;
}
declare class AbortVariable extends Variable {
protected _findReactiveStartIndex: number;
find(cb?: (payload: undefined | ReatomAbortController) => undefined | Result, frame?: Frame): undefined | Result;
createAndRun: GAction<((cb: (...params: Params) => Payload, ...params: Params) => Payload extends Promise ? ControlledPromise : Payload)>;
constructor();
/**
* Subscribes to abortion events from parent context tree (including current
* frame).
*
* Creates a subscription that listens for abort signals from any parent
* AbortController in the context tree. When an abort occurs, the callback is
* invoked with the abort error and the subscription automatically cleans up.
*
* It is IMPORTANT to clean up the subscription when it is no longer needed,
* otherwise a memory leak will occur. You can use the `unsubscribe` function
* returned by this method or `using` statement.
*
* @example
* const myResource = computed(async () => {
* const { controller, unsubscribe } = abortVar.subscribe()
* const { signal } = controller
*
* try {
* const response = await fetch('/api/my-resource', { signal })
* return await response.json()
* } finally {
* unsubscribe()
* }
* }).extend(withAsyncData())
*
* @example
* const myResource = computed(async () => {
* using { controller } = abortVar.subscribe()
* const { signal } = controller
*
* const response = await fetch('/api/my-resource', { signal })
* return await response.json()
* }).extend(withAsyncData())
*
* @param {(error: AbortError) => void} cb - Callback invoked when abortion
* occurs
* @returns {Object} Subscription object
* @returns {AbortController} Controller - The AbortController for the current
* context
* @returns {Function} Unsubscribe - Function to unsubscribe from abort events
*/
subscribe(cb?: (error: AbortError) => void): AbortSubscription;
/**
* NOTE: this method already used in `wrap`, that you should use in your code
* instead.
*
* Throws if any AbortController in the parent context (frame) tree, including
* the current frame, is aborted.
*
* @throws {AbortError}
*/
throwIfAborted(frame?: Frame): void;
}
/**
* Global abort variable that precess AbortController's coupled to the current
* frame stack.
*
* The abortVar is computed from all other abort atoms in the current frame
* tree, which allows for propagation of abortion signals through the
* computation hierarchy. This is a critical component for cancellation handling
* in Reatom's async operations.
*
* @example
* // Trigger abortion of the current frame
* abortVar.abortCurrent('Operation cancelled')
*
* @example
* // Trigger abortion of the current frame stack
* abortVar.get()?.abort('Operation cancelled')
*
* @example
* // Check if current operation (the whole frame stack) is aborted
* abortVar.throwIfAborted()
* // continue operation...
*
* @example
* // Get AbortController for fetch API
* const { controller, unsubscribe } = abortVar.subscribe()
* await fetch('/api/data', { signal: controller.signal })
* unsubscribe()
*
* @type {AbortVariable}
*/
declare let abortVar: AbortVariable;
/**
* Races multiple controlled promises and automatically aborts all losers when
* one settles.
*
* Unlike `Promise.race`, this function ensures proper cleanup by aborting all
* remaining promises once a winner is determined. This prevents resource leaks
* from ongoing async operations that are no longer needed.
*
* @example
* const resource = computed(async () => {
* return race(
* abortVar.createAndRun(() => fetchFromCache()),
* abortVar.createAndRun(() => fetchFromNetwork()),
* )
* })
*
* @param promises - Controlled promises to race (must have `controller`
* property)
* @returns Promise that resolves/rejects with the first settled value
*/
declare let race: (...promises: Array>) => Promise;
//#endregion
//#region src/methods/connectLogger.d.ts
/**
* A special logging action for debugging Reatom applications.
*
* `log` provides an enhanced logging experience with automatic tracing and
* production-safe output. It forwards all arguments to the native `console.log`
* while providing additional context about the call stack and dependencies.
*
* ## Key Benefits
*
* - **Short and handy name** - Easy to type and use throughout your codebase
* - **Automatic stack tracing** - Shows the relative call stack each time it's
* called
* - **Use it everywhere** - Logs are only visible when `connectLogger()` is
* active
* - **Production-safe** - Logs won't appear in production builds when logger is
* not connected
* - **Context-aware** - Integrates with Reatom's dependency tracking system
* - **Extendable** - You can extend it with other extensions to add custom
* behavior
*
* @example
* import { log } from '@reatom/core'
*
* // Make LOG available globally (recommended)
* declare global {
* var LOG: typeof log
* }
* globalThis.LOG = log
*
* @example
* const fetchSome = action(() => {
* const payload = a() + b() + c() // ...
* // Log intermediate data
* LOG('Call api with:', payload) // the log will display that it in the 'fetchSome' action
* return api(payload)
* }, 'fetchSome')
*
* @example
* // Multiple arguments like console.log
* LOG('Debug info:', { foo: 'bar' }, [1, 2, 3])
*
* @example
* export const Input = props => {
* // Use anywhere in your code
* LOG('Render Input', props)
* return
* }
*
* @example
* // Log state changes only when data changes
* // This will return the data and log it only if it has changed
* const data = LOG.state('data', useSomeData())
*
* @example
* // Extend LOG with custom behavior using withCallHook
* import { withCallHook } from '@reatom/core'
*
* LOG.extend(
* withCallHook((payload, params) => {
* // Send logs to a remote service
* sendToAnalytics({ level: 'debug', args: params })
* }),
* )
*
* @see {@link connectLogger} - Must be called to enable logging output
*/
declare let log: Action & {
state(name: string, data: T): T;
};
/**
* Sets up and connects a logger to the Reatom system for debugging and tracing.
*
* This function enhances all non-private atoms and actions with logging
* capabilities. When an atom's value changes or an action is called, it logs
* the event with relevant information to the console including:
*
* - Previous and current state for atoms
* - Parameters and return values for actions
* - Complete dependency stack traces
* - Error information when exceptions occur
*
* The logger adapts to the environment, using different formatting for browser
* and Node.js. Private atoms (those with names starting with `_` or containing
* `._`) are not logged.
*
* @example
* connectLogger()
*
* @example
* connectLogger({ match: (name) => name.startsWith('myFeature.') })
*
* @example
* // Highlight specific atoms with custom colors
* connectLogger({
* match: (name) => (name.includes('important') ? '#ff6b6b' : true),
* })
*
* @param options.match - Optional matcher to control which atoms/actions are
* logged. Return `true` to log, `false` to skip, or a color string to log
* with custom background (browser only).
*/
declare let connectLogger: ({
match
}?: {
/**
* Return `true` to log, `false` to skip, or a color string (e.g. `'#ff0000'`)
* to log with custom background (browser only)
*/
match?: (name: string, frame: Frame) => boolean | string;
}) => void;
//#endregion
//#region src/primitives/reatomLinkedList.d.ts
type State$1 = T extends Atom ? Value : T;
declare const LL_PREV: unique symbol;
type LL_PREV = typeof LL_PREV;
declare const LL_NEXT: unique symbol;
type LL_NEXT = typeof LL_NEXT;
type LLNode = T & {
[LL_PREV]: null | LLNode;
[LL_NEXT]: null | LLNode;
};
type LinkedListSymbols = {
readonly LL_PREV: LL_PREV;
readonly LL_NEXT: LL_NEXT;
};
type LLChanges = {
kind: 'create';
node: Node;
} | {
kind: 'createMany';
nodes: Node[];
} | {
kind: 'remove';
node: Node;
} | {
kind: 'removeMany';
nodes: Node[];
} | {
kind: 'swap';
a: Node;
b: Node;
} | {
kind: 'move';
node: Node;
after: null | Node;
} | {
kind: 'clear';
};
interface LinkedList extends LinkedListSymbols {
head: null | Node;
tail: null | Node;
size: number;
version: number;
changes: Array>;
}
interface LinkedListLikeAtom extends Atom, LinkedListSymbols {
array: Computed ? LLNode : never>>;
__reatomLinkedList: true;
}
interface LinkedListAtom extends LinkedListLikeAtom>> {
batch: Action<[cb: Fn]>;
create: Action>;
createMany: Action<[Array], Array>>;
remove: Action<[LLNode], boolean>;
removeMany: Action<[Array>], number>;
swap: Action<[a: LLNode, b: LLNode], void>;
move: Action<[node: LLNode, after: null | LLNode], void>;
clear: Action<[], void>;
find: (cb: (node: LLNode) => boolean) => null | LLNode;
/**
* This lazy map is useful for working with serializable identifier, but it is
* not recommended to use it for large (thousands elements) lists
*/
map: Key extends never ? never : Atom, LLNode>>;
initiateFromState: (initState: Array) => LinkedList>;
initiateFromSnapshot: (initSnapshot: Array) => LinkedList>;
reatomMap: (cb: (node: LLNode) => T, options?: string | {
name?: string;
onCreate?: (node: LLNode) => void;
onRemove?: (node: LLNode, origin: LLNode) => void;
onSwap?: (payload: {
a: LLNode;
b: LLNode;
}) => void;
onMove?: (node: LLNode) => void;
onClear?: (lastState: LinkedListDerivedState, LLNode>) => void;
}) => LinkedListDerivedAtom, LLNode>;
}
interface LinkedListDerivedState extends LinkedList {
map: WeakMap;
}
interface LinkedListDerivedAtom extends Computed>, LinkedListSymbols {
array: Computed ? LLNode : never>>;
__reatomLinkedList: true;
}
/**
* Creates a reactive linked list for collections where inserts, removals, and
* reordering are part of the main workflow.
*
* @remarks
* Each item becomes a node with hidden prev/next links, so you can `move` or
* `swap` existing items without rebuilding the whole collection. You can
* start from existing nodes, a node factory, or a config with `initState` /
* `initSnapshot`. Use `array()` when rendering with normal array helpers,
* `key` when you need lookup by a stable id, and `batch()` when importing or
* reordering many nodes at once.
* @example
* // Build a reorderable upload queue
* const uploads = reatomLinkedList(
* {
* create: (fileName: string) => ({
* fileName,
* progress: atom(0),
* }),
* key: 'fileName',
* },
* 'uploads',
* )
*
* uploads.create('cover.png')
* const hero = uploads.create('hero.png')
*
* uploads.move(hero, null)
* uploads.map().get('cover.png')?.progress.set(100)
*
* uploads.array().map((upload) => ({
* fileName: upload.fileName,
* progress: upload.progress(),
* }))
* // [
* // { fileName: 'hero.png', progress: 0 },
* // { fileName: 'cover.png', progress: 100 },
* // ]
*
* @example
* // Keep derived row state in sync with the source order
* const backlog = reatomLinkedList(
* (title: string) => ({ title }),
* 'backlog',
* )
* const rows = backlog.reatomMap(
* (task) => ({
* title: task.title,
* expanded: atom(false),
* }),
* 'backlogRows',
* )
*
* const docsTask = backlog.create('Write docs')
* backlog.create('Ship release')
*
* rows.array()[0].expanded.set(true)
* backlog.remove(docsTask)
*
* rows.array().map((row) => ({
* title: row.title,
* expanded: row.expanded(),
* }))
* // [{ title: 'Ship release', expanded: false }]
*/
declare function reatomLinkedList(initState: Array, name?: string): LinkedListAtom;
declare function reatomLinkedList(initState: (...params: Params) => Node, name?: string): LinkedListAtom;
declare function reatomLinkedList(initState: {
create: (...params: Params) => Node;
initState?: Array;
key?: Key;
}, name?: string): LinkedListAtom;
declare function reatomLinkedList(initState: {
create?: (...params: Params) => Node;
initState: Array;
key?: Key;
}, name?: string): LinkedListAtom;
declare function reatomLinkedList(initSnapshot: {
create: (...params: Params) => Node;
initSnapshot?: Array;
key?: Key;
}, name?: string): LinkedListAtom;
/**
* Checks whether a value is a linked list atom or a linked-list derivative
* created by `reatomLinkedList`.
*
* @example
* // Enable drag-and-drop only for linked lists
* const canReorder = (value: unknown) =>
* isLinkedListAtom(value) && value().size > 1
*/
declare const isLinkedListAtom: (thing: any) => thing is LinkedListLikeAtom;
//#endregion
//#region src/methods/deatomize.d.ts
type Primitive = string | number | boolean | null | undefined;
type Builtin = Date | RegExp | Function;
/**
* Type utility that recursively unwraps atom types to their state types
*
* This complex type recursively traverses a type structure, unwrapping atoms to
* their contained state types. It handles various container types like arrays,
* maps, sets, and objects.
*
* @template T - The type to unwrap
* @returns Unwrapped version of the type with atoms replaced by their state
* types
*/
type Deatomize = T extends LinkedListLikeAtom ? T extends LinkedList> ? Array> : never : T extends AtomLike ? T extends AtomLike, Params, Payload> ? T : Deatomize : T extends Map ? Map> : T extends Set ? Set> : T extends Array ? Array> : T extends Primitive | Builtin ? T : T extends Record ? { [K in keyof T]: Deatomize } : T;
/**
* Recursively unwraps atoms in a value to get their current states
*
* This function deeply traverses a value, including nested objects, arrays,
* maps, and sets, replacing atoms with their current state values. It's useful
* for serialization, debugging, or creating snapshots of state that don't
* contain reactive references.
*
* @example
* const user = {
* id: 42,
* name: atom('John', 'userName'),
* stats: {
* score: atom(100, 'userScore'),
* badges: atom(['gold', 'silver'], 'userBadges'),
* },
* }
*
* // Results in: { id: 42, name: 'John', stats: { score: 100, badges: ['gold', 'silver'] }}
* const plainUser = deatomize(user)
*
* @template Value - The type of value to parse
* @param {Value} value - The value containing atoms to unwrap
* @returns {Deatomize