swup 3.1.0 → 4.0.0-rc.14

package/src/modules/Hooks.ts

@@ -0,0 +1,393 @@
+import { DelegateEvent } from 'delegate-it';
+
+import Swup, { Options } from '../Swup.js';
+import { isPromise, runAsPromise } from '../utils.js';
+import { Context } from './Context.js';
+import { FetchOptions, PageData } from './fetchPage.js';
+import { AnimationDirection } from './getAnimationPromises.js';
+
+export interface HookDefinitions {
+	animationInDone: undefined;
+	animationInStart: undefined;
+	animationOutDone: undefined;
+	animationOutStart: undefined;
+	animationSkipped: undefined;
+	awaitAnimation: { selector: Options['animationSelector']; direction: AnimationDirection };
+	cacheCleared: undefined;
+	clickLink: { el: HTMLAnchorElement; event: DelegateEvent<MouseEvent> };
+	disabled: undefined;
+	enabled: undefined;
+	fetchPage: { url: string; options: FetchOptions; response?: Response | Promise<Response> };
+	loadPage: { url: string; options: FetchOptions; page?: PageData | Promise<PageData> };
+	openPageInNewTab: { href: string };
+	pageCached: { page: PageData };
+	pageLoaded: { page: PageData; cache?: boolean };
+	pageView: { url: string; title: string };
+	popState: { event: PopStateEvent };
+	replaceContent: { page: PageData; containers: Options['containers'] };
+	samePage: undefined;
+	samePageWithHash: { hash: string; options: ScrollIntoViewOptions };
+	scrollToContent: { options: ScrollIntoViewOptions };
+	serverError: { url: string; status: number; response: Response };
+	transitionStart: undefined;
+	transitionEnd: undefined;
+}
+
+export type HookArguments<T extends HookName> = HookDefinitions[T];
+
+export type HookName = keyof HookDefinitions;
+
+export type Handler<T extends HookName> = (
+	context: Context,
+	args: HookArguments<T>
+) => Promise<any> | void;
+
+export type Handlers = {
+	[K in HookName]: Handler<K>[];
+};
+
+export type HookOptions = {
+	once?: boolean;
+	before?: boolean;
+	priority?: number;
+	replace?: boolean;
+};
+
+export type HookRegistration<T extends HookName> = {
+	id: number;
+	hook: T;
+	handler: Handler<T>;
+} & HookOptions;
+
+type HookLedger<T extends HookName> = Map<Handler<T>, HookRegistration<T>>;
+
+interface HookRegistry extends Map<HookName, HookLedger<HookName>> {
+	get<K extends HookName>(key: K): HookLedger<K> | undefined;
+	set<K extends HookName>(key: K, value: HookLedger<K>): this;
+}
+
+/**
+ * Hook registry.
+ *
+ * Create, trigger and handle hooks.
+ *
+ */
+export class Hooks {
+	protected swup: Swup;
+	protected registry: HookRegistry = new Map();
+
+	// Can we deduplicate this somehow? Or make it error when not in sync with HookDefinitions?
+	// https://stackoverflow.com/questions/53387838/how-to-ensure-an-arrays-values-the-keys-of-a-typescript-interface/53395649
+	readonly hooks: HookName[] = [
+		'animationInDone',
+		'animationInStart',
+		'animationOutDone',
+		'animationOutStart',
+		'animationSkipped',
+		'awaitAnimation',
+		'cacheCleared',
+		'clickLink',
+		'disabled',
+		'enabled',
+		'fetchPage',
+		'loadPage',
+		'openPageInNewTab',
+		'pageCached',
+		'pageLoaded',
+		'pageView',
+		'popState',
+		'replaceContent',
+		'samePage',
+		'samePageWithHash',
+		'scrollToContent',
+		'serverError',
+		'transitionStart',
+		'transitionEnd'
+	];
+
+	constructor(swup: Swup) {
+		this.swup = swup;
+		this.init();
+	}
+
+	/**
+	 * Create ledgers for all core hooks.
+	 */
+	protected init() {
+		this.hooks.forEach((hook) => this.create(hook));
+	}
+
+	/**
+	 * Register a new hook.
+	 */
+	create(hook: HookName) {
+		if (!this.registry.has(hook)) {
+			this.registry.set(hook, new Map());
+		}
+	}
+
+	/**
+	 * Check if a hook is registered.
+	 */
+	has(hook: HookName): boolean {
+		return this.registry.has(hook);
+	}
+
+	/**
+	 * Get the ledger with all registrations for a hook.
+	 */
+	protected get<T extends HookName>(hook: T): HookLedger<T> | undefined {
+		const ledger = this.registry.get(hook);
+		if (ledger) {
+			return ledger;
+		} else {
+			console.error(`Unknown hook '${hook}'`);
+		}
+	}
+
+	/**
+	 * Remove all handlers of all hooks.
+	 */
+	clear() {
+		this.registry.forEach((ledger) => ledger.clear());
+	}
+
+	/**
+	 * Register a new hook handler.
+	 * @param hook Name of the hook to listen for
+	 * @param handler The handler function to execute
+	 * @param options Object to specify how and when the handler is executed
+	 *                Available options:
+	 *                - `once`: Only execute the handler once
+	 *                - `before`: Execute the handler before the default handler
+	 *                - `priority`: Specify the order in which the handlers are executed
+	 *                - `replace`: Replace the default handler with this handler
+	 * @returns The handler function
+	 */
+	on<T extends HookName>(hook: T, handler: Handler<T>): Handler<T>;
+	on<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): Handler<T>;
+	on<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions = {}): Handler<T> {
+		const ledger = this.get(hook);
+		if (!ledger) {
+			console.warn(`Hook '${hook}' not found.`);
+			return handler;
+		}
+
+		const id = ledger.size + 1;
+		const registration: HookRegistration<T> = { ...options, id, hook, handler };
+		ledger.set(handler, registration);
+		return handler;
+	}
+
+	/**
+	 * Register a new hook handler to run before the default handler.
+	 * Shortcut for `hooks.on(hook, handler, { before: true })`.
+	 * @param hook Name of the hook to listen for
+	 * @param handler The handler function to execute
+	 * @param options Any other event options (see `hooks.on()` for details)
+	 * @returns The handler function
+	 * @see on
+	 */
+	before<T extends HookName>(hook: T, handler: Handler<T>): Handler<T>;
+	before<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): Handler<T>;
+	before<T extends HookName>(
+		hook: T,
+		handler: Handler<T>,
+		options: HookOptions = {}
+	): Handler<T> {
+		return this.on(hook, handler, { ...options, before: true });
+	}
+
+	/**
+	 * Register a new hook handler to replace the default handler.
+	 * Shortcut for `hooks.on(hook, handler, { replace: true })`.
+	 * @param hook Name of the hook to listen for
+	 * @param handler The handler function to execute instead of the default handler
+	 * @param options Any other event options (see `hooks.on()` for details)
+	 * @returns The handler function
+	 * @see on
+	 */
+	replace<T extends HookName>(hook: T, handler: Handler<T>): Handler<T>;
+	replace<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): Handler<T>;
+	replace<T extends HookName>(
+		hook: T,
+		handler: Handler<T>,
+		options: HookOptions = {}
+	): Handler<T> {
+		return this.on(hook, handler, { ...options, replace: true });
+	}
+
+	/**
+	 * Register a new hook handler to run once.
+	 * Shortcut for `hooks.on(hook, handler, { once: true })`.
+	 * @param hook Name of the hook to listen for
+	 * @param handler The handler function to execute
+	 * @param options Any other event options (see `hooks.on()` for details)
+	 * @see on
+	 */
+	once<T extends HookName>(hook: T, handler: Handler<T>): Handler<T>;
+	once<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): Handler<T>;
+	once<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions = {}): Handler<T> {
+		return this.on(hook, handler, { ...options, once: true });
+	}
+
+	/**
+	 * Unregister a hook handler.
+	 * @param hook Name of the hook the handler is registered for
+	 * @param handler The handler function that was registered.
+	 *                If omitted, all handlers for the hook will be removed.
+	 */
+	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 {
+		const ledger = this.get(hook);
+
+		if (ledger && handler) {
+			const deleted = ledger.delete(handler);
+			if (!deleted) {
+				console.warn(`Handler for hook '${hook}' not found.`);
+			}
+		} else if (ledger) {
+			ledger.clear();
+		}
+	}
+
+	/**
+	 * Trigger a hook asynchronously, executing its default handler and all registered handlers.
+	 * Will execute all handlers in order and `await` any `Promise`s they return.
+	 * @param hook Name of the hook to trigger
+	 * @param args Arguments to pass to the handler
+	 * @param defaultHandler A default implementation of this hook to execute
+	 * @returns The resolved return value of the executed default handler
+	 */
+	async trigger<T extends HookName>(
+		hook: T,
+		args?: HookArguments<T>,
+		defaultHandler?: Handler<T>
+	): Promise<any> {
+		const { before, handler, after } = this.getHandlers(hook, defaultHandler);
+		await this.execute(before, args);
+		const [result] = await this.execute(handler, args);
+		await this.execute(after, args);
+		this.dispatchDomEvent(hook);
+		return result;
+	}
+
+	/**
+	 * Trigger a hook synchronously, executing its default handler and all registered handlers.
+	 * Will execute all handlers in order, but will **not** `await` any `Promise`s they return.
+	 * @param hook Name of the hook to trigger
+	 * @param args Arguments to pass to the handler
+	 * @param defaultHandler A default implementation of this hook to execute
+	 * @returns The (possibly unresolved) return value of the executed default handler
+	 */
+	triggerSync<T extends HookName>(
+		hook: T,
+		args?: HookArguments<T>,
+		defaultHandler?: Handler<T>
+	): any {
+		const { before, after, handler } = this.getHandlers(hook, defaultHandler);
+		this.executeSync(before, args);
+		const [result] = this.executeSync(handler, args);
+		this.executeSync(after, args);
+		this.dispatchDomEvent(hook);
+		return result;
+	}
+
+	/**
+	 * Execute the handlers for a hook, in order, as `Promise`s that will be `await`ed.
+	 * @param registrations The registrations (handler + options) to execute
+	 * @param args Arguments to pass to the handler
+	 */
+	async execute<T extends HookName>(
+		registrations: HookRegistration<T>[],
+		args?: HookArguments<T>
+	): Promise<any> {
+		const results = [];
+		for (const { hook, handler, once } of registrations) {
+			const result = await runAsPromise(handler, [this.swup.context, args]);
+			results.push(result);
+			if (once) {
+				this.off(hook, handler);
+			}
+		}
+		return results;
+	}
+
+	/**
+	 * Execute the handlers for a hook, in order, without `await`ing any returned `Promise`s.
+	 * @param registrations The registrations (handler + options) to execute
+	 * @param args Arguments to pass to the handler
+	 */
+	executeSync<T extends HookName>(
+		registrations: HookRegistration<T>[],
+		args?: HookArguments<T>
+	): any[] {
+		const results = [];
+		for (const { hook, handler, once } of registrations) {
+			const result = handler(this.swup.context, args as HookArguments<T>);
+			results.push(result);
+			if (isPromise(result)) {
+				console.warn(
+					`Promise returned from handler for synchronous hook '${hook}'.` +
+						`Swup will not wait for it to resolve.`
+				);
+			}
+			if (once) {
+				this.off(hook, handler);
+			}
+		}
+		return results;
+	}
+
+	/**
+	 * Get all registered handlers for a hook, sorted by priority and registration order.
+	 * @param hook Name of the hook
+	 * @param defaultHandler The optional default handler of this hook
+	 * @returns An object with the handlers sorted into `before` and `after` arrays,
+	 *          as well as a flag indicating if the original handler was replaced
+	 */
+	getHandlers<T extends HookName>(hook: T, defaultHandler?: Handler<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());
+
+		const before = registrations.filter(({ before, replace }) => before && !replace).sort(sort);
+		const replace = registrations.filter(({ replace }) => replace).sort(sort);
+		const after = registrations.filter(({ before, replace }) => !before && !replace).sort(sort);
+		const replaced = replace.length > 0;
+
+		let handler: HookRegistration<T>[] = [];
+		if (replaced) {
+			handler = [{ id: 0, hook, handler: replace[0].handler }];
+		} else if (defaultHandler) {
+			handler = [{ id: 0, hook, handler: defaultHandler }];
+		}
+
+		return { found: true, before, handler, after, replaced };
+	}
+
+	/**
+	 * Sort two hook registrations by priority and registration order.
+	 * @param a The registration object to compare
+	 * @param b The other registration object to compare with
+	 * @returns The sort direction
+	 */
+	sortRegistrations<T extends HookName>(a: HookRegistration<T>, b: HookRegistration<T>): number {
+		const priority = (b.priority ?? 0) - (a.priority ?? 0);
+		const id = a.id - b.id;
+		return priority || id || 0;
+	}
+
+	/**
+	 * Trigger a custom event on the `document`. Prefixed with `swup:`
+	 * @param hook Name of the hook to trigger.
+	 */
+	dispatchDomEvent<T extends HookName>(hook: T): void {
+		document.dispatchEvent(new CustomEvent(`swup:${hook}`, { detail: hook }));
+	}
+}

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

@@ -0,0 +1,142 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import Swup from '../../Swup.js';
+import { Cache, CacheData } from '../Cache.js';
+import { Context } from '../Context.js';
+
+interface CacheTtlData {
+	ttl: number;
+	created: number;
+}
+
+interface CacheIndexData {
+	index: number;
+}
+
+interface AugmentedCacheData extends CacheData, CacheTtlData, CacheIndexData {}
+
+const swup = new Swup();
+const ctx = swup.context;
+const cache = new Cache(swup);
+
+const page1 = { url: '/page-1', html: '1' };
+const page2 = { url: '/page-2', html: '2' };
+const page3 = { url: '/page-3', html: '3' };
+
+describe('Cache', () => {
+	beforeEach(() => {
+		cache.clear();
+	});
+
+	it('should be empty', () => {
+		expect(cache.size).toBe(0);
+	});
+
+	it('should append pages', () => {
+		cache.set(page1.url, page1);
+		expect(cache.size).toBe(1);
+	});
+
+	it('should have pages', () => {
+		cache.set(page1.url, page1);
+		expect(cache.has(page1.url)).toBe(true);
+	});
+
+	it('should get pages', () => {
+		cache.set(page1.url, page1);
+		expect(cache.get(page1.url)).toEqual(page1);
+	});
+
+	it('should delete pages', () => {
+		cache.set(page1.url, page1);
+		expect(cache.has(page1.url)).toBe(true);
+		cache.delete(page1.url);
+		expect(cache.has(page1.url)).toBe(false);
+	});
+
+	it('should clear', () => {
+		cache.set(page1.url, page1);
+		expect(cache.size).toBe(1);
+		cache.clear();
+		expect(cache.size).toBe(0);
+	});
+
+	it('should overwrite identical pages', () => {
+		cache.set(page1.url, page1);
+		expect(cache.size).toBe(1);
+		cache.set(page1.url, page1);
+		expect(cache.size).toBe(1);
+	});
+
+	it('should not overwrite different pages', () => {
+		cache.set(page1.url, page1);
+		expect(cache.size).toBe(1);
+		cache.set(page2.url, page2);
+		expect(cache.size).toBe(2);
+	});
+
+	it('should trigger a hook on set', () => {
+		const handler = vi.fn();
+
+		swup.hooks.on('pageCached', handler);
+
+		cache.set(page1.url, page1);
+
+		expect(handler).toBeCalledTimes(1);
+		expect(handler).toBeCalledWith(ctx, { page: page1 });
+	});
+
+	it('should allow augmenting cache entries on save', () => {
+		const now = Date.now();
+
+		swup.hooks.on('pageCached', (_, { page }) => {
+			const ttl: CacheTtlData = { ttl: 1000, created: now };
+			cache.update(page.url, ttl as AugmentedCacheData);
+		});
+
+		cache.set('/page', { url: '/page', html: '' });
+
+		const page = cache.get('/page') as AugmentedCacheData;
+
+		expect(page).toEqual({ url: '/page', html: '', ttl: 1000, created: now });
+	});
+
+	it('should allow manual pruning', () => {
+		swup.hooks.on('pageCached', (_, { page }) => {
+			cache.update(page.url, { index: cache.size } as AugmentedCacheData);
+		});
+
+		cache.set(page1.url, page1);
+		cache.set(page2.url, page2);
+		cache.set(page3.url, page3);
+
+		cache.prune((url, page) => (page as AugmentedCacheData).index > 2);
+
+		expect(cache.size).toBe(2);
+		expect(cache.has(page1.url)).toBe(true);
+		expect(cache.has(page2.url)).toBe(true);
+		expect(cache.has(page3.url)).toBe(false);
+	});
+});
+
+describe('Types', () => {
+	it('error when necessary', async () => {
+		const swup = new Swup();
+		const cache = new Cache(swup);
+
+		// @ts-expect-no-error
+		swup.hooks.on('popState', (ctx: Context, { event: PopStateEvent }) => {});
+		// @ts-expect-no-error
+		await swup.hooks.trigger('popState', { event: new PopStateEvent('') });
+
+		try {
+			// @ts-expect-error
+			cache.set();
+			// @ts-expect-error
+			cache.set(url);
+			// @ts-expect-error
+			cache.set(url, {});
+			// @ts-expect-error
+			cache.set({ url: '/test' });
+		} catch (error) {}
+	});
+});