swup 4.2.0 → 4.3.0

package/src/Swup.ts

@@ -21,6 +21,7 @@ import { renderPage } from './modules/renderPage.js';
 import { use, unuse, findPlugin, Plugin } from './modules/plugins.js';
 import { isSameResolvedUrl, resolveUrl } from './modules/resolveUrl.js';
 import { nextTick } from './utils.js';
+import { HistoryState } from './helpers/createHistoryRecord.js';
 
 /** Options for customizing swup's behavior. */
 export type Options = {
@@ -47,7 +48,7 @@ export type Options = {
 	/** Rewrite URLs before loading them. */
 	resolveUrl: (url: string) => string;
 	/** Callback for telling swup to ignore certain popstate events.  */
-	skipPopStateHandling: (event: any) => boolean;
+	skipPopStateHandling: (event: PopStateEvent) => boolean;
 };
 
 const defaults: Options = {
@@ -56,7 +57,7 @@ const defaults: Options = {
 	animationScope: 'html',
 	cache: true,
 	containers: ['#swup'],
-	ignoreVisit: (url, { el, event } = {}) => !!el?.closest('[data-no-swup]'),
+	ignoreVisit: (url, { el } = {}) => !!el?.closest('[data-no-swup]'),
 	linkSelector: 'a[href]',
 	linkToSelf: 'scroll',
 	plugins: [],
@@ -65,7 +66,7 @@ const defaults: Options = {
 		'X-Requested-With': 'swup',
 		'Accept': 'text/html, application/xhtml+xml'
 	},
-	skipPopStateHandling: (event) => event.state?.source !== 'swup'
+	skipPopStateHandling: (event) => (event.state as HistoryState)?.source !== 'swup'
 };
 
 /** Swup page transition library. */
@@ -101,7 +102,7 @@ export default class Swup {
 	findPlugin = findPlugin;
 
 	/** Log a message. Has no effect unless debug plugin is installed */
-	log: (message: string, context?: any) => void = () => {};
+	log: (message: string, context?: unknown) => void = () => {};
 
 	/** Navigate to a new URL */
 	navigate = navigate;
@@ -296,7 +297,7 @@ export default class Swup {
 	}
 
 	protected handlePopState(event: PopStateEvent) {
-		const href = event.state?.url ?? location.href;
+		const href: string = (event.state as HistoryState)?.url ?? location.href;
 
 		// Exit early if this event should be ignored
 		if (this.options.skipPopStateHandling(event)) {
@@ -324,7 +325,7 @@ export default class Swup {
 		this.visit.history.popstate = true;
 
 		// Determine direction of history visit
-		const index = Number(event.state?.index);
+		const index = Number((event.state as HistoryState)?.index);
 		if (index) {
 			const direction = index - this.currentHistoryIndex > 0 ? 'forwards' : 'backwards';
 			this.visit.history.direction = direction;

package/src/config/version.ts

@@ -6,8 +6,7 @@
 // export { version as default } from '../../package.json';
 
 // This will work in microbundle + webpack 5, but won't treeshake in webpack 4
-// Ignore next line in TypeScript as package.json is outside of rootDir
-// @ts-ignore
+// @ts-ignore: package.json is outside of rootDir
 import pckg from '../../package.json';
 
 export default pckg.version;

package/src/helpers/createHistoryRecord.ts

@@ -1,12 +1,20 @@
 import { getCurrentUrl } from './getCurrentUrl.js';
 
+export interface HistoryState {
+	url: string;
+	source: 'swup';
+	random: number;
+	index?: number;
+	[key: string]: unknown;
+}
+
 /** Create a new history record with a custom swup identifier. */
 export const createHistoryRecord = (
 	url: string,
 	customData: Record<string, unknown> = {}
 ): void => {
 	url = url || getCurrentUrl({ hash: true });
-	const data = {
+	const data: HistoryState = {
 		url,
 		random: Math.random(),
 		source: 'swup',

package/src/helpers/matchPath.ts

@@ -18,6 +18,6 @@ export const matchPath = <P extends object = object>(
 	try {
 		return match<P>(path, options);
 	} catch (error) {
-		throw new Error(`[swup] Error parsing path "${path}":\n${error}`);
+		throw new Error(`[swup] Error parsing path "${String(path)}":\n${String(error)}`);
 	}
 };

package/src/helpers/updateHistoryRecord.ts

@@ -1,3 +1,4 @@
+import { HistoryState } from './createHistoryRecord.js';
 import { getCurrentUrl } from './getCurrentUrl.js';
 
 /** Update the current history record with a custom swup identifier. */
@@ -6,8 +7,9 @@ export const updateHistoryRecord = (
 	customData: Record<string, unknown> = {}
 ): void => {
 	url = url || getCurrentUrl({ hash: true });
-	const data = {
-		...history.state,
+	const state = (history.state as HistoryState) || {};
+	const data: HistoryState = {
+		...state,
 		url,
 		random: Math.random(),
 		source: 'swup',

package/src/modules/Cache.ts

@@ -53,7 +53,7 @@ export class Cache {
 	}
 
 	/** Update a cache record, overwriting or adding custom data. */
-	update(url: string, payload: Record<string, any>) {
+	update(url: string, payload: object) {
 		url = this.resolve(url);
 		const page = { ...this.get(url), ...payload, url } as CacheData;
 		this.pages.set(url, page);
@@ -67,7 +67,7 @@ export class Cache {
 	/** Empty the cache. */
 	clear(): void {
 		this.pages.clear();
-		this.swup.hooks.callSync('cache:clear');
+		this.swup.hooks.callSync('cache:clear', undefined);
 	}
 
 	/** Remove all cache entries that return true for a given predicate function.  */

package/src/modules/Classes.ts

@@ -23,7 +23,7 @@ export class Classes {
 
 	protected get targets(): HTMLElement[] {
 		if (!this.selector.trim()) return [];
-		return queryAll(this.selector) as HTMLElement[];
+		return queryAll(this.selector);
 	}
 
 	add(...classes: string[]): void {

package/src/modules/Hooks.ts

@@ -34,19 +34,35 @@ export interface HookDefinitions {
 	'visit:end': undefined;
 }
 
+export interface HookReturnValues {
+	'content:scroll': Promise<boolean>;
+	'fetch:request': Promise<Response>;
+	'page:load': Promise<PageData>;
+	'scroll:top': boolean;
+	'scroll:anchor': boolean;
+}
+
 export type HookArguments<T extends HookName> = HookDefinitions[T];
 
 export type HookName = keyof HookDefinitions;
 
-/** A hook handler. */
+/** A generic hook handler. */
 export type Handler<T extends HookName> = (
+	/** Context about the current visit. */
+	visit: Visit,
+	/** Local arguments passed into the handler. */
+	args: HookArguments<T>
+) => Promise<unknown> | unknown;
+
+/** A default hook handler with an expected return type. */
+export type DefaultHandler<T extends HookName> = (
 	/** Context about the current visit. */
 	visit: Visit,
 	/** Local arguments passed into the handler. */
 	args: HookArguments<T>,
 	/** Default handler to be executed. Available if replacing an internal hook handler. */
-	defaultHandler?: Handler<T>
-) => Promise<any> | any;
+	defaultHandler?: DefaultHandler<T>
+) => T extends keyof HookReturnValues ? HookReturnValues[T] : Promise<unknown> | unknown;
 
 export type Handlers = {
 	[K in HookName]: Handler<K>[];
@@ -67,11 +83,14 @@ export type HookOptions = {
 	replace?: boolean;
 };
 
-export type HookRegistration<T extends HookName> = {
+export type HookRegistration<
+	T extends HookName,
+	H extends Handler<T> | DefaultHandler<T> = Handler<T>
+> = {
 	id: number;
 	hook: T;
-	handler: Handler<T>;
-	defaultHandler?: Handler<T>;
+	handler: H;
+	defaultHandler?: DefaultHandler<T>;
 } & HookOptions;
 
 type HookLedger<T extends HookName> = Map<Handler<T>, HookRegistration<T>>;
@@ -183,12 +202,18 @@ export class Hooks {
 	 *                - `replace`: Replace the default handler with this handler
 	 * @returns A function to unregister the handler
 	 */
-	on<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
-	on<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
-	on<T extends HookName>(
+
+	// Overload: replacing default handler
+	on<T extends HookName, O extends HookOptions>(hook: T, handler: DefaultHandler<T>, options: O & { replace: true }): HookUnregister; // prettier-ignore
+	// Overload: passed in handler options
+	on<T extends HookName, O extends HookOptions>(hook: T, handler: Handler<T>, options: O): HookUnregister; // prettier-ignore
+	// Overload: no handler options
+	on<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister; // prettier-ignore
+	// Implementation
+	on<T extends HookName, O extends HookOptions>(
 		hook: T,
-		handler: Handler<T>,
-		options: HookOptions = {}
+		handler: O['replace'] extends true ? DefaultHandler<T> : Handler<T>,
+		options: Partial<O> = {}
 	): HookUnregister {
 		const ledger = this.get(hook);
 		if (!ledger) {
@@ -212,8 +237,11 @@ export class Hooks {
 	 * @returns A function to unregister the handler
 	 * @see on
 	 */
-	before<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
+	// Overload: passed in handler options
 	before<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
+	// Overload: no handler options
+	before<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
+	// Implementation
 	before<T extends HookName>(
 		hook: T,
 		handler: Handler<T>,
@@ -231,11 +259,14 @@ export class Hooks {
 	 * @returns A function to unregister the handler
 	 * @see on
 	 */
-	replace<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
-	replace<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
+	// Overload: passed in handler options
+	replace<T extends HookName>(hook: T, handler: DefaultHandler<T>, options: HookOptions): HookUnregister; // prettier-ignore
+	// Overload: no handler options
+	replace<T extends HookName>(hook: T, handler: DefaultHandler<T>): HookUnregister; // prettier-ignore
+	// Implementation
 	replace<T extends HookName>(
 		hook: T,
-		handler: Handler<T>,
+		handler: DefaultHandler<T>,
 		options: HookOptions = {}
 	): HookUnregister {
 		return this.on(hook, handler, { ...options, replace: true });
@@ -249,8 +280,11 @@ export class Hooks {
 	 * @param options Any other event options (see `hooks.on()` for details)
 	 * @see on
 	 */
-	once<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
+	// Overload: passed in handler options
 	once<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
+	// Overload: no handler options
+	once<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
+	// Implementation
 	once<T extends HookName>(
 		hook: T,
 		handler: Handler<T>,
@@ -265,9 +299,12 @@ export class Hooks {
 	 * @param handler The handler function that was registered.
 	 *                If omitted, all handlers for the hook will be removed.
 	 */
+	// Overload: unregister a specific handler
+	off<T extends HookName>(hook: T, handler: Handler<T> | DefaultHandler<T>): void;
+	// Overload: unregister all handlers
 	off<T extends HookName>(hook: T): void;
-	off<T extends HookName>(hook: T, handler: Handler<T>): void;
-	off<T extends HookName>(hook: T, handler?: Handler<T>): void {
+	// Implementation
+	off<T extends HookName>(hook: T, handler?: Handler<T> | DefaultHandler<T>): void {
 		const ledger = this.get(hook);
 		if (ledger && handler) {
 			const deleted = ledger.delete(handler);
@@ -289,9 +326,9 @@ export class Hooks {
 	 */
 	async call<T extends HookName>(
 		hook: T,
-		args?: HookArguments<T>,
-		defaultHandler?: Handler<T>
-	): Promise<any> {
+		args: HookArguments<T>,
+		defaultHandler?: DefaultHandler<T>
+	): Promise<Awaited<ReturnType<DefaultHandler<T>>>> {
 		const { before, handler, after } = this.getHandlers(hook, defaultHandler);
 		await this.run(before, args);
 		const [result] = await this.run(handler, args);
@@ -310,9 +347,9 @@ export class Hooks {
 	 */
 	callSync<T extends HookName>(
 		hook: T,
-		args?: HookArguments<T>,
-		defaultHandler?: Handler<T>
-	): any {
+		args: HookArguments<T>,
+		defaultHandler?: DefaultHandler<T>
+	): ReturnType<DefaultHandler<T>> {
 		const { before, handler, after } = this.getHandlers(hook, defaultHandler);
 		this.runSync(before, args);
 		const [result] = this.runSync(handler, args);
@@ -326,10 +363,16 @@ export class Hooks {
 	 * @param registrations The registrations (handler + options) to execute
 	 * @param args Arguments to pass to the handler
 	 */
-	protected async run<T extends HookName>(
-		registrations: HookRegistration<T>[],
-		args?: HookArguments<T>
-	): Promise<any> {
+
+	// Overload: running DefaultHandler: expect DefaultHandler return type
+	protected async run<T extends HookName>(registrations: HookRegistration<T, DefaultHandler<T>>[], args: HookArguments<T>): Promise<Awaited<ReturnType<DefaultHandler<T>>>[]>; // prettier-ignore
+	// Overload:  running user handler: expect no specific type
+	protected async run<T extends HookName>(registrations: HookRegistration<T>[], args: HookArguments<T>): Promise<unknown[]>; // prettier-ignore
+	// Implementation
+	protected async run<T extends HookName, R extends HookRegistration<T>[]>(
+		registrations: R,
+		args: HookArguments<T>
+	): Promise<Awaited<ReturnType<DefaultHandler<T>>> | unknown[]> {
 		const results = [];
 		for (const { hook, handler, defaultHandler, once } of registrations) {
 			const result = await runAsPromise(handler, [this.swup.visit, args, defaultHandler]);
@@ -346,13 +389,19 @@ export class Hooks {
 	 * @param registrations The registrations (handler + options) to execute
 	 * @param args Arguments to pass to the handler
 	 */
-	protected runSync<T extends HookName>(
-		registrations: HookRegistration<T>[],
-		args?: HookArguments<T>
-	): any[] {
+
+	// Overload: running DefaultHandler: expect DefaultHandler return type
+	protected runSync<T extends HookName>(registrations: HookRegistration<T, DefaultHandler<T>>[], args: HookArguments<T> ): ReturnType<DefaultHandler<T>>[]; // prettier-ignore
+	// Overload: running user handler: expect no specific type
+	protected runSync<T extends HookName>(registrations: HookRegistration<T>[], args: HookArguments<T>): unknown[]; // prettier-ignore
+	// Implementation
+	protected runSync<T extends HookName, R extends HookRegistration<T>[]>(
+		registrations: R,
+		args: HookArguments<T>
+	): (ReturnType<DefaultHandler<T>> | unknown)[] {
 		const results = [];
 		for (const { hook, handler, defaultHandler, once } of registrations) {
-			const result = handler(this.swup.visit, args as HookArguments<T>, defaultHandler);
+			const result = (handler as DefaultHandler<T>)(this.swup.visit, args, defaultHandler);
 			results.push(result);
 			if (isPromise(result)) {
 				console.warn(
@@ -374,30 +423,33 @@ export class Hooks {
 	 * @returns An object with the handlers sorted into `before` and `after` arrays,
 	 *          as well as a flag indicating if the original handler was replaced
 	 */
-	protected getHandlers<T extends HookName>(hook: T, defaultHandler?: Handler<T>) {
+	protected getHandlers<T extends HookName>(hook: T, defaultHandler?: DefaultHandler<T>) {
 		const ledger = this.get(hook);
 		if (!ledger) {
 			return { found: false, before: [], handler: [], after: [], replaced: false };
 		}
 
-		const sort = this.sortRegistrations;
 		const registrations = Array.from(ledger.values());
 
+		// Let TypeScript know that replaced handlers are default handlers by filtering to true
+		const def = (T: HookRegistration<T>): T is HookRegistration<T, DefaultHandler<T>> => true;
+		const sort = this.sortRegistrations;
+
 		// Filter into before, after, and replace handlers
 		const before = registrations.filter(({ before, replace }) => before && !replace).sort(sort);
-		const replace = registrations.filter(({ replace }) => replace).sort(sort);
+		const replace = registrations.filter(({ replace }) => replace).filter(def).sort(sort); // prettier-ignore
 		const after = registrations.filter(({ before, replace }) => !before && !replace).sort(sort);
 		const replaced = replace.length > 0;
 
 		// Define main handler registration
-		// This is an array to allow passing it into hooks.run() directly
-		let handler: HookRegistration<T>[] = [];
+		// Created as HookRegistration[] array to allow passing it into hooks.run() directly
+		let handler: HookRegistration<T, DefaultHandler<T>>[] = [];
 		if (defaultHandler) {
 			handler = [{ id: 0, hook, handler: defaultHandler }];
 			if (replaced) {
 				const index = replace.length - 1;
 				const replacingHandler = replace[index].handler;
-				const createDefaultHandler = (index: number): Handler<T> | undefined => {
+				const createDefaultHandler = (index: number): DefaultHandler<T> | undefined => {
 					const next = replace[index - 1];
 					if (next) {
 						return (visit, args) =>

package/src/modules/Visit.ts

@@ -13,6 +13,8 @@ export interface Visit {
 	animation: VisitAnimation;
 	/** What triggered this visit */
 	trigger: VisitTrigger;
+	/** Cache behavior for this visit */
+	cache: VisitCache;
 	/** Browser history behavior on this visit */
 	history: VisitHistory;
 	/** Scroll behavior on this visit */
@@ -60,6 +62,13 @@ export interface VisitTrigger {
 	event?: Event;
 }
 
+export interface VisitCache {
+	/** Whether this visit will try to load the requested page from cache. */
+	read: boolean;
+	/** Whether this visit will save the loaded page in cache. */
+	write: boolean;
+}
+
 export interface VisitHistory {
 	/** History action to perform: `push` for creating a new history entry, `replace` for replacing the current entry. Default: `push` */
 	action: HistoryAction;
@@ -112,6 +121,10 @@ export function createVisit(
 			el,
 			event
 		},
+		cache: {
+			read: this.options.cache,
+			write: this.options.cache
+		},
 		history: {
 			action,
 			popstate: false,

package/src/modules/__test__/cache.test.ts

@@ -90,19 +90,19 @@ describe('Cache', () => {
 
 		swup.hooks.on('cache:set', (_, { page }) => {
 			const ttl: CacheTtlData = { ttl: 1000, created: now };
-			cache.update(page.url, ttl as AugmentedCacheData);
+			cache.update(page.url, ttl);
 		});
 
 		cache.set('/page', { url: '/page', html: '' });
 
-		const page = cache.get('/page') as AugmentedCacheData;
+		const page = cache.get('/page');
 
 		expect(page).toEqual({ url: '/page', html: '', ttl: 1000, created: now });
 	});
 
 	it('should allow manual pruning', () => {
 		swup.hooks.on('cache:set', (_, { page }) => {
-			cache.update(page.url, { index: cache.size } as AugmentedCacheData);
+			cache.update(page.url, { index: cache.size });
 		});
 
 		cache.set(page1.url, page1);

package/src/modules/__test__/hooks.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import Swup from '../../Swup.js';
-import { Handler, Hooks } from '../Hooks.js';
+import { DefaultHandler, Handler, Hooks } from '../Hooks.js';
 import { Visit } from '../Visit.js';
 
 describe('Hook registry', () => {
@@ -37,14 +37,14 @@ describe('Hook registry', () => {
 		swup.hooks.on('enable', handler1);
 		swup.hooks.on('enable', handler2);
 
-		await swup.hooks.call('enable');
+		await swup.hooks.call('enable', undefined);
 
 		expect(handler1).toBeCalledTimes(1);
 		expect(handler2).toBeCalledTimes(1);
 
 		swup.hooks.off('enable', handler2);
 
-		await swup.hooks.call('enable');
+		await swup.hooks.call('enable', undefined);
 
 		expect(handler1).toBeCalledTimes(2);
 		expect(handler2).toBeCalledTimes(1);
@@ -60,14 +60,14 @@ describe('Hook registry', () => {
 
 		expect(unregister1).toBeTypeOf('function');
 
-		await swup.hooks.call('enable');
+		await swup.hooks.call('enable', undefined);
 
 		expect(handler1).toBeCalledTimes(1);
 		expect(handler2).toBeCalledTimes(1);
 
 		unregister2();
 
-		await swup.hooks.call('enable');
+		await swup.hooks.call('enable', undefined);
 
 		expect(handler1).toBeCalledTimes(2);
 		expect(handler2).toBeCalledTimes(1);
@@ -79,7 +79,7 @@ describe('Hook registry', () => {
 
 		swup.hooks.on('enable', handler);
 
-		await swup.hooks.call('enable');
+		await swup.hooks.call('enable', undefined);
 
 		expect(handler).toBeCalledTimes(1);
 	});
@@ -303,18 +303,17 @@ describe('Types', () => {
 		const swup = new Swup();
 
 		// @ts-expect-no-error
-		swup.hooks.on(
-			'history:popstate',
-			(visit: Visit, { event }: { event: PopStateEvent }) => {}
-		);
+		swup.hooks.on('history:popstate', (visit: Visit, { event }: { event: PopStateEvent }) => {});
 		// @ts-expect-no-error
 		await swup.hooks.call('history:popstate', { event: new PopStateEvent('') });
 
-		// @ts-expect-error
+		// @ts-expect-error: first arg must be Visit object
 		swup.hooks.on('history:popstate', ({ event: MouseEvent }) => {});
-		// @ts-expect-error
+		// @ts-expect-error: event arg must be PopStateEvent
 		swup.hooks.on('history:popstate', (visit: Visit, { event }: { event: MouseEvent }) => {});
-		// @ts-expect-error
+		// @ts-expect-error: event arg must be PopStateEvent
 		await swup.hooks.call('history:popstate', { event: new MouseEvent('') });
+		// @ts-expect-error: handler arg must be optional: handler?
+		swup.hooks.replace('enable', (visit: Visit, args: undefined, handler: DefaultHandler<'enable'>) => {});
 	});
 });

package/src/modules/animatePageIn.ts

@@ -27,5 +27,5 @@ export const animatePageIn = async function (this: Swup) {
 
 	await animation;
 
-	await this.hooks.call('animation:in:end');
+	await this.hooks.call('animation:in:end', undefined);
 };

package/src/modules/animatePageOut.ts

@@ -7,7 +7,7 @@ import { classify } from '../helpers.js';
  */
 export const animatePageOut = async function (this: Swup) {
 	if (!this.visit.animation.animate) {
-		await this.hooks.call('animation:skip');
+		await this.hooks.call('animation:skip', undefined);
 		return;
 	}
 
@@ -26,5 +26,5 @@ export const animatePageOut = async function (this: Swup) {
 		await this.awaitAnimations({ selector: visit.animation.selector });
 	});
 
-	await this.hooks.call('animation:out:end');
+	await this.hooks.call('animation:out:end', undefined);
 };

package/src/modules/awaitAnimations.ts

@@ -150,7 +150,7 @@ export function getTransitionInfo(element: Element, expectedType?: AnimationType
 	};
 }
 
-function isTransitionOrAnimationEvent(event: any): event is TransitionEvent | AnimationEvent {
+function isTransitionOrAnimationEvent(event: Event): event is TransitionEvent | AnimationEvent {
 	return [`${TRANSITION}end`, `${ANIMATION}end`].includes(event.type);
 }
 

package/src/modules/fetchPage.ts

@@ -10,13 +10,11 @@ export interface PageData {
 }
 
 /** Define how a page is fetched. */
-export interface FetchOptions extends RequestInit {
+export interface FetchOptions extends Omit<RequestInit, 'cache'> {
 	/** The request method. */
 	method?: 'GET' | 'POST';
 	/** The body of the request: raw string, form data object or URL params. */
 	body?: string | FormData | URLSearchParams;
-	/** The headers of the request: key/value object. */
-	headers?: Record<string, string>;
 }
 
 export class FetchError extends Error {
@@ -66,8 +64,12 @@ export async function fetchPage(
 	const { url: finalUrl } = Location.fromUrl(responseUrl);
 	const page = { url: finalUrl, html };
 
-	// Only save cache entry for non-redirects
-	if (url === finalUrl) {
+	// Write to cache for safe methods and non-redirects
+	if (
+		this.visit.cache.write &&
+		(!options.method || options.method === 'GET') &&
+		url === finalUrl
+	) {
 		this.cache.set(page.url, page);
 	}
 

package/src/modules/navigate.ts

@@ -1,11 +1,12 @@
 import Swup from '../Swup.js';
 import { createHistoryRecord, updateHistoryRecord, getCurrentUrl, Location } from '../helpers.js';
-import { FetchOptions } from './fetchPage.js';
+import { FetchOptions, PageData } from './fetchPage.js';
 import { VisitInitOptions } from './Visit.js';
 
 export type HistoryAction = 'push' | 'replace';
 export type HistoryDirection = 'forwards' | 'backwards';
 export type NavigationToSelfAction = 'scroll' | 'navigate';
+export type CacheControl = Partial<{ read: boolean; write: boolean }>;
 
 /** Define how to navigate to a page. */
 type NavigationOptions = {
@@ -15,6 +16,8 @@ type NavigationOptions = {
 	animation?: string;
 	/** History action to perform: `push` for creating a new history entry, `replace` for replacing the current entry. Default: `push` */
 	history?: HistoryAction;
+	/** Whether this visit should read from or write to the cache. */
+	cache?: CacheControl;
 };
 
 /**
@@ -83,14 +86,30 @@ export async function performNavigation(
 		this.visit.animation.name = animation;
 	}
 
+	// Sanitize cache option
+	if (typeof options.cache === 'object') {
+		this.visit.cache.read = options.cache.read ?? this.visit.cache.read;
+		this.visit.cache.write = options.cache.write ?? this.visit.cache.write;
+	} else if (options.cache !== undefined) {
+		this.visit.cache = { read: !!options.cache, write: !!options.cache };
+	}
+	// Delete this so that window.fetch doesn't mis-interpret it
+	delete options.cache;
+
 	try {
-		await this.hooks.call('visit:start');
+		await this.hooks.call('visit:start', undefined);
 
 		// Begin loading page
 		const pagePromise = this.hooks.call('page:load', { options }, async (visit, args) => {
-			const cachedPage = this.cache.get(visit.to.url!);
-			args.page = cachedPage || (await this.fetchPage(visit.to.url!, args.options));
+			// Read from cache
+			let cachedPage: PageData | undefined;
+			if (this.visit.cache.read) {
+				cachedPage = this.cache.get(visit.to.url);
+			}
+
+			args.page = cachedPage || (await this.fetchPage(visit.to.url, args.options));
 			args.cache = !!cachedPage;
+
 			return args.page;
 		});