use-travel/dist/index.d.ts

A React hook for state time travel with undo, redo, reset, rebase and archive functionalities.

import type { TravelPatches, TravelsOptions, RebasableManualTravelsControls, RebasableTravelsControls, Value, Updater, PatchesOption } from 'travels';
import { Travels } from 'travels';
export type { TravelPatches };
/** Adds `canUndo` and `canRedo` flags to a controls type. */
export type WithUndoRedoFlags<C> = C & {
    /** Whether undo is currently possible. */
    readonly canUndo: boolean;
    /** Whether redo is currently possible. */
    readonly canRedo: boolean;
};
/** Controls returned by `useTravelStore`, including `canUndo` and `canRedo`. */
export type StoreControlsWithFlags<S, F extends boolean, A extends boolean, P extends PatchesOption = {}> = WithUndoRedoFlags<A extends true ? RebasableTravelsControls<S, F, P> : RebasableManualTravelsControls<S, F, P>>;
/**
 * Creates a component-scoped Travels instance with undo/redo support and returns its reactive API.
 *
 * The hook memoises the underlying `Travels` instance per component, wires it to React's lifecycle, and forces
 * re-renders whenever the managed state changes. Consumers receive a tuple containing the current state, a `setState`
 * updater that accepts either a mutative draft function or partial state, and the history controls exposed by
 * Travels.
 *
 * @typeParam S - Shape of the state managed by the travel store.
 * @typeParam F - Whether draft freezing is enabled.
 * @typeParam A - Whether the instance auto-archives changes; determines the controls contract.
 * @typeParam P - Additional patches configuration forwarded to Mutative.
 * @param initialState - Value used to initialise the travel store.
 * @returns A tuple with the current state, typed updater, and history controls.
 * @throws {Error} When `setState` is invoked multiple times within the same render cycle (development-only guard).
 */
export declare function useTravel<S, F extends boolean>(initialState: S): [
    Value<S, F>,
    (updater: Updater<S>) => void,
    WithUndoRedoFlags<RebasableTravelsControls<S, F>>
];
export declare function useTravel<S, F extends boolean, A extends boolean, P extends PatchesOption = {}>(initialState: S, options: Omit<TravelsOptions<F, true, P>, 'autoArchive' | 'mutable'> & {
    autoArchive?: true;
}): [
    Value<S, F>,
    (updater: Updater<S>) => void,
    WithUndoRedoFlags<RebasableTravelsControls<S, F, P>>
];
export declare function useTravel<S, F extends boolean, A extends boolean, P extends PatchesOption = {}>(initialState: S, options: Omit<TravelsOptions<F, false, P>, 'autoArchive' | 'mutable'> & {
    autoArchive: false;
}): [
    Value<S, F>,
    (updater: Updater<S>) => void,
    WithUndoRedoFlags<RebasableManualTravelsControls<S, F, P>>
];
/**
 * Subscribes to an existing Travels store and bridges it into React via `useSyncExternalStore`.
 *
 * The hook keeps React in sync with the store's state and exposes the same tuple shape as {@link useTravel}, but it
 * does not create or manage the store lifecycle. Mutable Travels instances are rejected because they reuse the same
 * state reference, which prevents React from observing updates.
 *
 * @typeParam S - Shape of the state managed by the travel store.
 * @typeParam F - Whether draft freezing is enabled.
 * @typeParam A - Whether the instance auto-archives changes; determines the controls contract.
 * @typeParam P - Additional patches configuration forwarded to Mutative.
 * @param travels - Existing Travels instance to bind to React.
 * @returns A tuple containing the current state, typed updater, and history controls.
 * @throws {Error} If the provided `Travels` instance was created with `mutable: true`.
 */
export declare function useTravelStore<S, F extends boolean, A extends boolean, P extends PatchesOption = {}>(travels: Travels<S, F, A, P>): [
    Value<S, F>,
    (updater: Updater<S>) => void,
    StoreControlsWithFlags<S, F, A, P>
];
//# sourceMappingURL=index.d.ts.map