initial commit

.vscode/settings.json

···
+{
+	"editor.defaultFormatter": "denoland.vscode-deno",
+	"deno.enable": true
+}

.zed/settings.json

···
+{
+	"lsp": {
+		"deno": {
+			"settings": {
+				"deno": {
+					"enable": true
+				}
+			}
+		}
+	},
+	"languages": {
+		"JavaScript": {
+			"language_servers": [
+				"deno",
+				"!typescript-language-server",
+				"!vtsls",
+				"!eslint"
+			],
+			"formatter": "language_server"
+		},
+		"TypeScript": {
+			"language_servers": [
+				"deno",
+				"!typescript-language-server",
+				"!vtsls",
+				"!eslint"
+			],
+			"formatter": "language_server"
+		},
+		"TSX": {
+			"language_servers": [
+				"deno",
+				"!typescript-language-server",
+				"!vtsls",
+				"!eslint"
+			],
+			"formatter": "language_server"
+		}
+	}
+}

LICENSE

···
+BSD Zero Clause License
+
+Copyright (c) 2025 Mary
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

README.md

···
+# history
+
+Manages browsing session history
+
+```ts
+const history = createBrowserHistory();
+
+history.listen(({ action, location }) => {
+	console.log(action, location.pathname);
+});
+
+history.navigate('/dashboard?tab=stats#top');
+// action: "push", location.pathname: "/dashboard"
+
+history.update({ theme: 'dark' });
+// action: "update"
+
+history.back();
+```

deno.json

···
+{
+	"name": "@mary/history",
+	"version": "0.1.0",
+	"license": "0BSD",
+	"exports": "./lib/mod.ts",
+	"fmt": {
+		"useTabs": true,
+		"indentWidth": 2,
+		"lineWidth": 110,
+		"semiColons": true,
+		"singleQuote": true
+	},
+	"publish": {
+		"include": ["lib/", "LICENSE", "README.md", "deno.json"]
+	},
+	"imports": {
+		"@mary/events": "jsr:@mary/events@^0.2.0",
+		"esm-env": "npm:esm-env@^1.2.2",
+		"nanoid": "npm:nanoid@^5.1.5"
+	},
+	"compilerOptions": {
+		"lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]
+	}
+}

deno.lock

···
+{
+  "version": "5",
+  "specifiers": {
+    "jsr:@mary/events@0.2": "0.2.0",
+    "npm:esm-env@^1.2.2": "1.2.2",
+    "npm:nanoid@^5.1.5": "5.1.5"
+  },
+  "jsr": {
+    "@mary/events@0.2.0": {
+      "integrity": "39fd9f4022bfb3bda038655de1d95c7e4b3eee0f99128e822ab42afefb12c4f1"
+    }
+  },
+  "npm": {
+    "esm-env@1.2.2": {
+      "integrity": "sha512-Epxrv+Nr/CaL4ZcFGPJIYLWFom+YeV1DqMLHJoEd9SYRxNbaFruBwfEX/kkHUJf55j2+TUbmDcmuilbP1TmXHA=="
+    },
+    "nanoid@5.1.5": {
+      "integrity": "sha512-Ir/+ZpE9fDsNH0hQ3C68uyThDXzYcim2EqcZ8zn8Chtt1iylPT9xXJB0kPCnqzgcEGikO9RxSrh63MsmVCU7Fw==",
+      "bin": true
+    }
+  },
+  "workspace": {
+    "dependencies": [
+      "jsr:@mary/events@0.2",
+      "npm:esm-env@^1.2.2",
+      "npm:nanoid@^5.1.5"
+    ]
+  }
+}

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 { nanoid } from 'nanoid/non-secure';
+
+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 string associated with this location */
+	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>;
+
+/**
+ * public interface for interacting with browser-like history.
+ */
+export interface History {
+	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;
+}
+
+/**
+ * A browser history stores the current location in regular URLs in a web
+ * browser environment. This is the standard for most web apps and provides the
+ * cleanest URLs the browser's address bar.
+ */
+export interface BrowserHistory extends History {}
+
+const warning = (cond: unknown, message: string) => {
+	if (DEV && !cond) {
+		console.warn(message);
+	}
+};
+
+interface HistoryState {
+	usr: unknown;
+	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,
+			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) }, '');
+	}
+
+	// state defaults to `null` because `window.history.state` does
+	const getNextLocation = (to: To, index: number, state: unknown = null): Location => {
+		return {
+			pathname: location.pathname,
+			hash: '',
+			search: '',
+			...(typeof to === 'string' ? parsePath(to) : to),
+			index,
+			state,
+			key: createKey(),
+		};
+	};
+
+	const getHistoryStateAndUrl = (nextLocation: Location): [HistoryState, string] => {
+		return [
+			{
+				usr: nextLocation.state,
+				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, state }: NavigateOptions = {}): void => {
+		const nextAction: Action = !replace ? 'push' : 'replace';
+		const nextIndex = location.index + (!replace ? 1 : 0);
+		const nextLocation = getNextLocation(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 createKey = () => {
+	return nanoid();
+};
+
+/**
+ * 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;
+};