Navigation Actions

/**
 * Navigate to a new location, adding entry to history stack
 * @param path - URL path string
 * @param state - Optional state object to associate with location
 * @returns Redux action for router middleware to process
 */
function push<S = LocationState>(path: Path, state?: S): CallHistoryMethodAction<[Path, S?]>;

/**
 * Navigate to a new location using location descriptor object
 * @param location - Location descriptor with pathname, search, hash, state
 * @returns Redux action for router middleware to process
 */
function push<S = LocationState>(location: LocationDescriptorObject<S>): CallHistoryMethodAction<[LocationDescriptorObject<S>]>;

interface LocationDescriptorObject<S = LocationState> {
  /** URL pathname */
  pathname?: string;
  /** URL search string */
  search?: string;
  /** URL hash */
  hash?: string;
  /** State object to associate with location */
  state?: S;
}

type Path = string;

import { push } from 'connected-react-router';

// Basic path navigation
dispatch(push('/users'));
dispatch(push('/users/123'));

// Navigation with state
dispatch(push('/profile', { fromDashboard: true }));

// Navigation with location object
dispatch(push({
  pathname: '/search',
  search: '?q=react',
  hash: '#results',
  state: { query: 'react' }
}));

// In redux-thunk action creator
const navigateToUser = (userId) => (dispatch) => {
  dispatch(push(`/users/${userId}`));
};

// In redux-saga
import { put } from 'redux-saga/effects';

function* navigateAfterSave() {
  yield put(push('/success'));
}

/**
 * Navigate to a new location, replacing current entry in history stack
 * @param path - URL path string
 * @param state - Optional state object to associate with location
 * @returns Redux action for router middleware to process
 */
function replace<S = LocationState>(path: Path, state?: S): CallHistoryMethodAction<[Path, S?]>;

/**
 * Navigate to a new location using location descriptor object
 * @param location - Location descriptor with pathname, search, hash, state
 * @returns Redux action for router middleware to process
 */
function replace<S = LocationState>(location: LocationDescriptorObject<S>): CallHistoryMethodAction<[LocationDescriptorObject<S>]>;

import { replace } from 'connected-react-router';

// Replace current location
dispatch(replace('/login'));

// Replace with state (useful for redirects)
dispatch(replace('/dashboard', { redirected: true }));

// Replace with location object
dispatch(replace({
  pathname: '/error',
  state: { errorCode: 404 }
}));

// Common pattern: redirect after authentication
const authenticateUser = (credentials) => (dispatch) => {
  return api.login(credentials)
    .then(() => {
      // Replace login page so user can't go back to it
      dispatch(replace('/dashboard'));
    });
};

/**
 * Move through history by relative position
 * @param n - Number of steps to move (negative for backward, positive for forward)
 * @returns Redux action for router middleware to process
 */
function go(n: number): CallHistoryMethodAction<[number]>;

/**
 * Navigate backward one step in history (equivalent to browser back button)
 * @returns Redux action for router middleware to process
 */
function goBack(): CallHistoryMethodAction<[]>;

/**
 * Navigate forward one step in history (equivalent to browser forward button)
 * @returns Redux action for router middleware to process
 */
function goForward(): CallHistoryMethodAction<[]>;

import { go, goBack, goForward } from 'connected-react-router';

// Go back one step (like browser back button)
dispatch(goBack());

// Go forward one step (like browser forward button)
dispatch(goForward());

// Go back 2 steps
dispatch(go(-2));

// Go forward 3 steps
dispatch(go(3));

// Common pattern: back navigation with fallback
const handleBackNavigation = () => (dispatch, getState) => {
  const canGoBack = window.history.length > 1;
  if (canGoBack) {
    dispatch(goBack());
  } else {
    dispatch(push('/'));
  }
};

/**
 * Object containing all router action creators
 */
const routerActions: {
  push: typeof push;
  replace: typeof replace;
  go: typeof go;
  goBack: typeof goBack;
  goForward: typeof goForward;
};

import { routerActions } from 'connected-react-router';

// Use action creators from the collection
dispatch(routerActions.push('/home'));
dispatch(routerActions.goBack());

// Useful for passing all actions to components
const mapDispatchToProps = {
  ...routerActions,
  // other action creators...
};

/**
 * Action interface for history method calls
 */
interface CallHistoryMethodAction<A = any[]> {
  type: typeof CALL_HISTORY_METHOD;
  payload: LocationActionPayload<A>;
}

interface LocationActionPayload<A = any[]> {
  /** Name of history method to call */
  method: string;
  /** Arguments to pass to history method */
  args?: A;
}

/** Union type of all router actions */
type RouterAction<S = LocationState> = LocationChangeAction<S> | CallHistoryMethodAction;

/** Action type constant for history method calls */
const CALL_HISTORY_METHOD: '@@router/CALL_HISTORY_METHOD';

type Push = typeof push;
type Replace = typeof replace;  
type Go = typeof go;
type GoBack = typeof goBack;
type GoForward = typeof goForward;