Add API methods prependFragmentRule and appendFragmentRule

Author: hirasso

src/SwupFragmentPlugin.ts

@@ -25,16 +25,6 @@ export default class SwupFragmentPlugin extends PluginBase {
 	_rawRules: Rule[] = [];
 	_parsedRules: ParsedRule[] = [];
 
-	setRules(rules: Rule[]) {
-		this._rawRules = structuredClone(rules);
-		this._parsedRules = rules.map((rule) => this.parseRule(rule));
-		if (__DEV__) this.logger?.log('Updated fragment rules', this.getRules());
-	}
-
-	getRules() {
-		return structuredClone(this._rawRules);
-	}
-
 	options: Options;
 
 	defaults: Options = {
@@ -75,6 +65,8 @@ export default class SwupFragmentPlugin extends PluginBase {
 		swup.getFragmentVisit = this.getFragmentVisit.bind(this);
 		swup.getFragmentRules = this.getRules.bind(this);
 		swup.setFragmentRules = this.setRules.bind(this);
+		swup.prependFragmentRule = this.prependRule.bind(this);
+		swup.appendFragmentRule = this.appendRule.bind(this);
 
 		if (__DEV__) {
 			this.logger?.warnIf(
@@ -95,9 +87,29 @@ export default class SwupFragmentPlugin extends PluginBase {
 		swup.getFragmentVisit = undefined;
 		swup.getFragmentRules = undefined;
 		swup.setFragmentRules = undefined;
+		swup.prependFragmentRule = undefined;
+		swup.appendFragmentRule = undefined;
 		cleanupFragmentElements();
 	}
 
+	setRules(rules: Rule[]) {
+		this._rawRules = structuredClone(rules);
+		this._parsedRules = rules.map((rule) => this.parseRule(rule));
+		if (__DEV__) this.logger?.log('Updated fragment rules', this.getRules());
+	}
+
+	getRules() {
+		return structuredClone(this._rawRules);
+	}
+
+	prependRule(rule: Rule) {
+		this.setRules([rule, ...this.getRules()]);
+	}
+
+	appendRule(rule: Rule) {
+		this.setRules([...this.getRules(), rule]);
+	}
+
 	/**
 	 * Add a fragment rule
 	 * @param {Rule} rule 			The rule options

src/index.ts

@@ -8,6 +8,8 @@ declare module 'swup' {
 		getFragmentVisit?: FragmentPlugin['getFragmentVisit'];
 		getFragmentRules?: FragmentPlugin['getRules'];
 		setFragmentRules?: FragmentPlugin['setRules'];
+		prependFragmentRule?: FragmentPlugin['prependRule'];
+		appendFragmentRule?: FragmentPlugin['appendRule'];
 	}
 	export interface Visit {
 		fragmentVisit?: FragmentVisit;

tests/vitest/modifyRules.test.ts

@@ -1,81 +1,74 @@
-import { describe, expect, it, vi, afterEach } from 'vitest';
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 import { getMountedPluginInstance, spyOnConsole } from './inc/helpers.js';
 
+const defaultRule = {
+	from: '/page-1/',
+	to: '/page-2/',
+	containers: ['#default']
+};
 const fragmentPlugin = getMountedPluginInstance({
-	rules: [
-		{
-			from: '/page-1/',
-			to: '/page-2/',
-			containers: ['#fragment-1']
-		}
-	]
+	rules: [defaultRule]
 });
+const { swup } = fragmentPlugin;
 
-describe('get and set fragment rules', () => {
+describe('modify fragment rules', () => {
+	beforeEach(() => {
+		spyOnConsole();
+		/** Reset the rules */
+		fragmentPlugin.setRules([defaultRule]);
+	})
 	afterEach(() => {
 		vi.restoreAllMocks();
 	});
 
-	it('should return raw rules', () => {
-		expect(fragmentPlugin.getRules()).toEqual([
-			{
-				from: '/page-1/',
-				to: '/page-2/',
-				containers: ['#fragment-1']
-			}
-		]);
+	it('should return unparsed raw rules', () => {
+		expect(fragmentPlugin.getRules()).toEqual([defaultRule]);
 	});
 
-	it('should be possible to modify rules at runtime', () => {
-		const console = spyOnConsole();
-		const { swup } = fragmentPlugin;
+	it('should provide API methods on the swup instance', () => {
+		expect(swup.getFragmentRules).toBeTypeOf('function');
+		expect(swup.setFragmentRules).toBeTypeOf('function');
+		expect(swup.prependFragmentRule).toBeTypeOf('function');
+		expect(swup.appendFragmentRule).toBeTypeOf('function');
+	});
 
-		/** Add a rule using the plugin's API, *after* the existing rules */
-		fragmentPlugin.setRules([
-			...fragmentPlugin.getRules(),
-			{
-				from: '/foo/',
-				to: '/bar/',
-				containers: ['#fragment-1'],
-				name: 'from-plugin'
-			}
-		]);
+	it('should provide access to prependRule() and appendRule()', () => {
+		const prependRule = {
+			from: '/corge/',
+			to: '/grault/',
+			containers: ['#corgegrault']
+		};
+		const appendRule = {
+			from: '/garply/',
+			to: '/waldo/',
+			containers: ['#garplywaldo']
+		};
 
-		/** Add a rule using swup's API, *before* the existing rules */
-		swup.setFragmentRules?.([
-			{
-				from: '/foo/',
-				to: '/bar/',
-				containers: ['#fragment-1'],
-				name: 'from-swup'
-			},
-			...swup.getFragmentRules?.() || [],
-		]);
+		swup.prependFragmentRule?.(prependRule);
+		swup.appendFragmentRule?.(appendRule);
 
-		const fromPlugin = fragmentPlugin.getRules();
-		const fromSwup = swup.getFragmentRules?.();
+		expect(swup.getFragmentRules?.()).toEqual([prependRule, defaultRule, appendRule]);
+	});
 
-		/** make sure the method exists on swup as well */
-		expect(fromPlugin).toEqual(fromSwup);
+	it('should provide access to getRules() and setRules()', () => {
+		/** Add a rule using the plugin's API, *after* the existing rules */
+		const appendRule = {
+			from: '/foo/',
+			to: '/bar/',
+			containers: ['#foobar'],
+			name: 'from-plugin'
+		};
+		fragmentPlugin.setRules([...fragmentPlugin.getRules(), appendRule]);
+
+		/** Add a rule using swup's API, *before* the existing rules */
+		const prependRule = {
+			from: '/baz/',
+			to: '/bat/',
+			containers: ['#bazbat'],
+			name: 'from-swup'
+		};
+		swup.setFragmentRules?.([prependRule, ...(swup.getFragmentRules?.() || [])]);
 
-		expect(fromPlugin).toEqual([
-			{
-				from: '/foo/',
-				to: '/bar/',
-				containers: ['#fragment-1'],
-				name: 'from-swup'
-			},
-			{
-				from: '/page-1/',
-				to: '/page-2/',
-				containers: ['#fragment-1']
-			},
-			{
-				from: '/foo/',
-				to: '/bar/',
-				containers: ['#fragment-1'],
-				name: 'from-plugin'
-			}
-		]);
+		expect(swup.getFragmentRules?.()).toEqual([prependRule, defaultRule, appendRule]);
 	});
 });