feat(router): plain head exports merging order

reverses head merging for plain objects but retains order for functions

Author: wmertens

.changeset/some-emus-fly.md

@@ -0,0 +1,5 @@
+---
+'@qwik.dev/router': major
+---
+
+Breaking: The order of head export merging has been slightly. Plain objects now override outer ones. Functions still are run inner-first.

packages/qwik-router/src/runtime/src/head.ts

@@ -11,6 +11,7 @@ import type {
   Editable,
   ResolveSyncValue,
   ActionInternal,
+  ContentModuleHead,
 } from './types';
 import { isPromise } from './utils';
 
@@ -37,28 +38,36 @@ export const resolveHead = (
     }
     return data;
   }) as any as ResolveSyncValue;
-  const headProps: DocumentHeadProps = {
-    head,
-    withLocale: (fn) => withLocale(locale, fn),
-    resolveValue: getData,
-    ...routeLocation,
-  };
 
-  for (let i = contentModules.length - 1; i >= 0; i--) {
-    const contentModuleHead = contentModules[i] && contentModules[i].head;
+  const fns: Extract<ContentModuleHead, Function>[] = [];
+  for (const contentModule of contentModules) {
+    const contentModuleHead = contentModule?.head;
     if (contentModuleHead) {
       if (typeof contentModuleHead === 'function') {
-        resolveDocumentHead(
-          head,
-          withLocale(locale, () => contentModuleHead(headProps))
-        );
+        // Functions are executed inner before outer
+        fns.unshift(contentModuleHead);
       } else if (typeof contentModuleHead === 'object') {
+        // Objects are merged inner over outer
         resolveDocumentHead(head, contentModuleHead);
       }
     }
   }
+  if (fns.length) {
+    const headProps: DocumentHeadProps = {
+      head,
+      withLocale: (fn) => withLocale(locale, fn),
+      resolveValue: getData,
+      ...routeLocation,
+    };
+
+    withLocale(locale, () => {
+      for (const fn of fns) {
+        resolveDocumentHead(head, fn(headProps));
+      }
+    });
+  }
 
-  return headProps.head;
+  return head;
 };
 
 const resolveDocumentHead = (

packages/qwik-router/src/runtime/src/head.unit.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from 'vitest';
+import { resolveHead } from './head';
+import type { ContentModuleHead } from './types';
+
+const endpoint = {} as any;
+const routeLocation = {} as any;
+const locale = 'en';
+const defaults = {
+  title: 'Default Title',
+  meta: [{ key: 'desc', name: 'description', content: 'Default description' }],
+  link: [{ key: 'css', rel: 'stylesheet', href: 'default.css' }],
+};
+const mergeHeads = (...modules: any[]) =>
+  resolveHead(endpoint, routeLocation, modules.map((m) => ({ head: m })) as any, locale, defaults);
+
+describe('resolveHead', () => {
+  it('should merge contentModule properties correctly', () => {
+    const baseModule: ContentModuleHead = {
+      title: 'Base Title',
+      meta: [{ key: 'desc', name: 'description', content: 'Base description' }],
+      links: [{ key: 'css', rel: 'stylesheet', href: 'base.css' }],
+    };
+
+    const overrideModule: ContentModuleHead = {
+      title: 'Override Title',
+      meta: [{ key: 'keywords', content: 'override, test' }],
+      links: [{ key: 'icon', rel: 'icon', href: 'favicon.ico' }],
+    };
+
+    const result = mergeHeads(baseModule, overrideModule);
+
+    expect(result.title).toBe('Override Title');
+    expect(result.meta).toEqual([
+      { key: 'desc', name: 'description', content: 'Base description' },
+      { key: 'keywords', content: 'override, test' },
+    ]);
+    expect(result.links).toEqual([
+      { key: 'css', rel: 'stylesheet', href: 'base.css' },
+      { key: 'icon', rel: 'icon', href: 'favicon.ico' },
+    ]);
+  });
+
+  it('should handle missing override properties', () => {
+    const baseModule: ContentModuleHead = {
+      title: 'Base Title',
+      meta: [{ key: 'desc', content: 'Base description' }],
+    };
+
+    const overrideModule: ContentModuleHead = {};
+
+    const result = mergeHeads(baseModule, overrideModule);
+
+    expect(result.title).toBe('Base Title');
+    expect(result.meta).toEqual([{ key: 'desc', content: 'Base description' }]);
+  });
+
+  it('should handle missing base properties', () => {
+    const baseModule: ContentModuleHead = {};
+
+    const overrideModule: ContentModuleHead = {
+      title: 'Override Title',
+      meta: [{ key: 'keywords', content: 'override, test' }],
+    };
+
+    const result = mergeHeads(baseModule, overrideModule);
+
+    expect(result.title).toBe('Override Title');
+    expect(result.meta).toEqual([
+      { key: 'desc', name: 'description', content: 'Default description' },
+      { key: 'keywords', content: 'override, test' },
+    ]);
+  });
+
+  it('should not mutate input objects', () => {
+    const baseModule: ContentModuleHead = {
+      title: 'Base Title',
+      meta: [{ name: 'description', content: 'Base description' }],
+    };
+
+    const overrideModule: ContentModuleHead = {
+      title: 'Override Title',
+      meta: [{ name: 'keywords', content: 'override, test' }],
+    };
+
+    const baseCopy = JSON.parse(JSON.stringify(baseModule));
+    const overrideCopy = JSON.parse(JSON.stringify(overrideModule));
+
+    mergeHeads(baseModule, overrideModule);
+
+    expect(baseModule).toEqual(baseCopy);
+    expect(overrideModule).toEqual(overrideCopy);
+  });
+});
+
+describe('resolveHead with functions', () => {
+  it('should execute head functions in correct order and merge results', () => {
+    const baseModule: ContentModuleHead = (props) => ({
+      title: props.head.title + ' - My Site',
+      meta: [{ key: 'desc', name: 'description', content: 'Base description' }],
+    });
+
+    const overrideModule: ContentModuleHead = (props) => ({
+      title: 'Override Title',
+      meta: [{ key: 'desc', name: 'description', content: 'will be overridden' }],
+    });
+
+    const result = mergeHeads(baseModule, overrideModule);
+
+    expect(result.title).toBe('Override Title - My Site');
+    expect(result.meta).toEqual([
+      { key: 'desc', name: 'description', content: 'Base description' },
+    ]);
+  });
+
+  it('should handle mix of object and function heads', () => {
+    const objectModule: ContentModuleHead = {
+      title: 'Object Title',
+      meta: [{ key: 'desc', name: 'description', content: 'Object description' }],
+    };
+
+    const functionModule: ContentModuleHead = (props) => ({
+      title: props.head.title + ' - My Site',
+      meta: [{ key: 'keywords', content: 'function, test' }],
+    });
+
+    const result = mergeHeads(objectModule, functionModule);
+
+    expect(result.title).toBe('Object Title - My Site');
+    expect(result.meta).toEqual([
+      { key: 'desc', name: 'description', content: 'Object description' },
+      { key: 'keywords', content: 'function, test' },
+    ]);
+  });
+});