pkg-history / lib / mod.ts

// fork of `history` npm package
// repository: github.com/remix-run/history
// commit: 3e9dab413f4eda8d6bce565388c5ddb7aeff9f7e

// most of the changes are just trimming it down to only include the browser
// history implementation.

import { DEV } from 'esm-env';

import { EventEmitter } from '@mary/events';

/**
 * kind of navigation action performed on the history stack.
 */
export type Action = 'traverse' | 'push' | 'replace' | 'update';

/**
 * components of a URL path.
 */
export interface Path {
	/** a URL pathname, beginning with a /. */
	pathname: string;
	/** a URL search string, beginning with a ?. */
	search: string;
	/** a URL fragment identifier, beginning with a #. */
	hash: string;
}

/**
 * location entry stored by the history, including position, state and key.
 */
export interface Location extends Path {
	/** position of this history */
	index: number;
	/** a value of arbitrary data associated with this location. */
	state: unknown;
	/** a unique identifier for the specific history entry */
	id: string;
	/** a unique identifier for the history entry's slot in the entries list */
	key: string;
}

/**
 * update dispatched to listeners when the history changes.
 */
export interface Update {
	action: Action;
	location: Location;
}

/**
 * listener callback for history updates.
 * @param update update information for the navigation
 */
export type Listener = (update: Update) => void;

/**
 * transition passed to blockers to allow retrying or inspecting the update.
 */
export interface Transition extends Update {
	retry(): void;
}

/**
 * blocker callback to intercept a transition and optionally defer it.
 * @param tx transition information and retry capability
 */
export type Blocker = (tx: Transition) => void;

/**
 * destination for navigation, either a full string path or parts of a path.
 */
export type To = string | Partial<Path>;

/**
 * interface for interacting with the browser history.
 */
export interface BrowserHistory {
	readonly location: Location;

	/**
	 * navigates to a new location.
	 * @param to destination to navigate to
	 * @param options navigation options
	 */
	navigate(to: To, options?: NavigateOptions): void;
	/**
	 * updates the state of the current location without changing the URL.
	 * @param state arbitrary state to associate with the location
	 */
	update(state: unknown): void;

	/**
	 * moves the history pointer by the given delta.
	 * @param delta positive or negative number of entries to move
	 */
	go(delta: number): void;
	/**
	 * navigates one entry back.
	 */
	back(): void;
	/**
	 * navigates one entry forward.
	 */
	forward(): void;

	/**
	 * subscribes to history updates.
	 * @param listener callback to invoke on updates
	 * @returns unsubscribe function
	 */
	listen(listener: Listener): () => void;
	/**
	 * registers a blocker to intercept transitions.
	 * @param blocker callback to invoke with transition info
	 * @returns unblock function
	 */
	block(blocker: Blocker): () => void;
}

/**
 * options for navigation.
 */
export interface NavigateOptions {
	replace?: boolean;
	state?: unknown;
}

const warning = (cond: unknown, message: string) => {
	if (DEV && !cond) {
		console.warn(message);
	}
};

interface HistoryState {
	usr: unknown;
	id?: string;
	key?: string;
	idx: number;
}

const BeforeUnloadEventType = 'beforeunload';
const PopStateEventType = 'popstate';

/**
 * options for creating a browser history instance.
 */
export interface BrowserHistoryOptions {
	window?: Window;
}

/**
 * browser history stores the location in regular URLs. this is the standard for
 * most web apps, but it requires configuration on the server to serve the same
 * app at multiple URLs.
 * @param options options for the browser history
 * @returns a browser history instance
 */
export const createBrowserHistory = (options: BrowserHistoryOptions = {}): BrowserHistory => {
	const { window = document.defaultView! } = options;
	const globalHistory = window.history;

	const getCurrentLocation = (): Location => {
		const { pathname, search, hash } = window.location;
		const state = globalHistory.state || {};
		return {
			pathname,
			search,
			hash,
			index: state.idx,
			state: state.usr || null,
			id: state.id || 'default',
			key: state.key || 'default',
		};
	};

	let blockedPopTx: Transition | null = null;
	const handlePop = () => {
		if (blockedPopTx) {
			emitter.emit('block', blockedPopTx);
			blockedPopTx = null;
		} else {
			const nextAction: Action = 'traverse';
			const nextLocation = getCurrentLocation();
			const nextIndex = nextLocation.index;

			if (emitter.has('block')) {
				if (nextIndex != null) {
					const delta = location.index - nextIndex;
					if (delta) {
						// Revert the POP
						blockedPopTx = {
							action: nextAction,
							location: nextLocation,
							retry() {
								go(delta * -1);
							},
						};

						go(delta);
					}
				} else {
					// Trying to POP to a location with no index. We did not create
					// this location, so we can't effectively block the navigation.
					warning(
						false,
						// TODO: Write up a doc that explains our blocking strategy in
						// detail and link to it here so people can understand better what
						// is going on and how to avoid it.
						`You are trying to block a POP navigation to a location that was not ` +
							`created by the history library. The block will fail silently in ` +
							`production, but in general you should do all navigation with the ` +
							`history library (instead of using window.history.pushState directly) ` +
							`to avoid this situation.`,
					);
				}
			} else {
				applyTx(nextAction);
			}
		}
	};

	const emitter = new EventEmitter<{
		update: [evt: Update];
		block: [tx: Transition];
	}>();

	let location = getCurrentLocation();

	window.addEventListener(PopStateEventType, handlePop);

	if (location.index == null) {
		globalHistory.replaceState({ ...globalHistory.state, idx: (location.index = 0) }, '');
	}

	const getNextLocation = (replace: boolean, to: To, index: number, state: unknown): Location => {
		return {
			pathname: location.pathname,
			hash: '',
			search: '',
			...(typeof to === 'string' ? parsePath(to) : to),
			index,
			state,
			id: randomId(),
			key: replace ? location.key : randomId(),
		};
	};

	const getHistoryStateAndUrl = (nextLocation: Location): [HistoryState, string] => {
		return [
			{
				usr: nextLocation.state,
				id: nextLocation.id,
				key: nextLocation.key,
				idx: nextLocation.index,
			},
			createHref(nextLocation),
		];
	};

	const allowTx = (action: Action, location: Location, retry: () => void): boolean => {
		return !emitter.emit('block', { action, location, retry });
	};

	const applyTx = (nextAction: Action): void => {
		location = getCurrentLocation();
		emitter.emit('update', { action: nextAction, location });
	};

	const navigate = (to: To, { replace = false, state = null }: NavigateOptions = {}): void => {
		const nextAction: Action = !replace ? 'push' : 'replace';
		const nextIndex = location.index + (!replace ? 1 : 0);
		const nextLocation = getNextLocation(replace, to, nextIndex, state);

		const retry = () => {
			navigate(to, { replace, state });
		};

		if (allowTx(nextAction, nextLocation, retry)) {
			const [historyState, url] = getHistoryStateAndUrl(nextLocation);

			// TODO: Support forced reloading
			if (!replace) {
				// try...catch because iOS limits us to 100 pushState calls :/
				try {
					globalHistory.pushState(historyState, '', url);
				} catch {
					// They are going to lose state here, but there is no real
					// way to warn them about it since the page will refresh...
					window.location.assign(url);
				}
			} else {
				globalHistory.replaceState(historyState, '', url);
			}

			applyTx(nextAction);
		}
	};

	const update = (state: unknown): void => {
		const nextAction: Action = 'update';
		const nextLocation = { ...location, state };

		const [historyState, url] = getHistoryStateAndUrl(nextLocation);

		// TODO: Support forced reloading
		globalHistory.replaceState(historyState, '', url);

		applyTx(nextAction);
	};

	const go = (delta: number): void => {
		globalHistory.go(delta);
	};

	const history: BrowserHistory = {
		get location() {
			return location;
		},
		navigate,
		update,
		go,
		back: () => {
			return go(-1);
		},
		forward: () => {
			return go(1);
		},
		listen: (listener) => {
			return emitter.on('update', listener);
		},
		block: (blocker) => {
			if (!emitter.has('block')) {
				window.addEventListener(BeforeUnloadEventType, promptBeforeUnload);
			}

			const unblock = emitter.on('block', blocker);

			return () => {
				unblock();

				// Remove the beforeunload listener so the document may
				// still be salvageable in the pagehide event.
				// See https://html.spec.whatwg.org/#unloading-documents
				if (!emitter.has('block')) {
					window.removeEventListener(BeforeUnloadEventType, promptBeforeUnload);
				}
			};
		},
	};

	return history;
};

const promptBeforeUnload = (event: BeforeUnloadEvent): void => {
	// Cancel the event.
	event.preventDefault();
};

const randomId = () => {
	return crypto.randomUUID();
};

/**
 * creates an href string for a destination. strings are returned as-is while
 * partial paths are composed into a string via createPath.
 * @param to destination to convert to href
 * @returns href string
 */
export const createHref = (to: To): string => {
	return typeof to === 'string' ? to : createPath(to);
};

/**
 * creates a string URL path from the given pathname, search, and hash components.
 * @param pathname path component beginning with '/'
 * @param search search component beginning with '?'
 * @param hash hash component beginning with '#'
 * @returns the composed path string
 */
export const createPath = ({ pathname = '/', search = '', hash = '' }: Partial<Path>): string => {
	if (search && search !== '?') {
		pathname += search.charAt(0) === '?' ? search : '?' + search;
	}
	if (hash && hash !== '#') {
		pathname += hash.charAt(0) === '#' ? hash : '#' + hash;
	}
	return pathname;
};

/**
 * parses a string URL path into its pathname, search, and hash components.
 * @param path input path string to parse
 * @returns the parsed path components
 */
export const parsePath = (path: string): Partial<Path> => {
	const parsedPath: Partial<Path> = {};

	if (path) {
		const hashIndex = path.indexOf('#');
		if (hashIndex >= 0) {
			parsedPath.hash = path.slice(hashIndex);
			path = path.slice(0, hashIndex);
		}

		const searchIndex = path.indexOf('?');
		if (searchIndex >= 0) {
			parsedPath.search = path.slice(searchIndex);
			path = path.slice(0, searchIndex);
		}

		if (path) {
			parsedPath.pathname = path;
		}
	}

	return parsedPath;
};