refactor: 💡 API refactor

Author: tianyingchun

README.md

@@ -52,28 +52,73 @@ import { TemplateParser } from '@hyperse/html-webpack-plugin-loader';
 // Create a new parser instance
 const parser = new TemplateParser(htmlSource);
 
-// Chain methods to modify the template
+// Define template options
+const templateOptions: TemplateOptions = {
+  // Set page title
+  title: 'My Page Title',
+
+  // Set website favicon
+  favicon: '/favicon.ico',
+
+  // Set meta tags in head
+  headMetaTags: ['<meta name="description" content="My page description">'],
+
+  // Set styles in head
+  headStyles: ['<style>body { margin: 0; }</style>'],
+
+  // Set scripts in head
+  headScripts: [
+    {
+      id: 'main-js', // Required: Unique script identifier
+      src: '/main.js', // Required: Script source path
+      position: 'end', // Required: Script position in head
+      type: 'text/javascript', // Optional: Script type
+      async: true, // Optional: Load script asynchronously
+      defer: false, // Optional: Defer script loading
+      order: 1, // Optional: Loading order
+    },
+  ],
+
+  // Set inline scripts in head
+  headInlineScripts: [
+    {
+      id: 'inline-script', // Required: Unique script identifier
+      position: 'end', // Required: Script position in head
+      content: 'console.log("Hello");', // Required: Script content
+      order: 2, // Optional: Loading order
+    },
+  ],
+
+  // Set scripts in body
+  bodyScripts: [
+    {
+      id: 'app-js', // Required: Unique script identifier
+      src: '/app.js', // Required: Script source path
+      position: 'end', // Required: Script position in body
+      type: 'text/javascript', // Optional: Script type
+      async: true, // Optional: Load script asynchronously
+      defer: false, // Optional: Defer script loading
+      order: 1, // Optional: Loading order
+    },
+  ],
+};
+
+// Use template options to modify HTML
 const modifiedHtml = parser
-  .upsertTitleTag('My Page Title')
-  .upsertFaviconTag('/favicon.ico')
-  .upsertViewportTag(
-    '<meta name="viewport" content="width=device-width, initial-scale=1">'
-  )
-  .upsertHeadMetaTags([
-    '<meta name="description" content="My page description">',
-  ])
-  .upsertHeadStyles(['<style>body { margin: 0; }</style>'])
-  .upsertHeadScripts([{ src: '/main.js' }])
-  .upsertHeadInlineScripts(['<script>console.log("Hello");</script>'])
-  .upsertBodyScripts([{ src: '/app.js' }])
+  .upsertTitleTag(templateOptions.title)
+  .upsertFaviconTag(templateOptions.favicon)
+  .upsertHeadMetaTags(templateOptions.headMetaTags)
+  .upsertHeadStyles(templateOptions.headStyles)
+  .upsertHeadScripts(templateOptions.headScripts)
+  .upsertHeadInlineScripts(templateOptions.headInlineScripts)
+  .upsertBodyScripts(templateOptions.bodyScripts)
   .serialize();
 ```
 
 #### Available Methods
 
 - `upsertTitleTag(title: string)`: Updates or inserts the page title
 - `upsertFaviconTag(favicon: string)`: Updates or inserts the favicon link
-- `upsertViewportTag(viewport: string)`: Updates or inserts the viewport meta tag
 - `upsertHeadMetaTags(tags: string[])`: Updates or inserts meta tags in the head
 - `upsertHeadStyles(styles: string[])`: Updates or inserts style tags in the head
 - `upsertHeadScripts(scripts: ScriptItem[])`: Updates or inserts script tags in the head

src/parser/TemplateParser.ts

@@ -1,6 +1,6 @@
 import type { DefaultTreeAdapterTypes } from 'parse5';
 import { serialize } from 'parse5';
-import type { ScriptItem } from '../types.js';
+import type { ScriptionInlineItem, ScriptItem } from '../types.js';
 import { parseDocument } from '../utils/parseDocument.js';
 import { upsertFavicon } from './upsertFavicon.js';
 import { upsertHeadInlineScripts } from './upsertHeadInlineScripts.js';
@@ -41,16 +41,6 @@ export class TemplateParser {
     return this;
   }
 
-  /**
-   * Upsert the viewport tag
-   * @param viewport - The viewport to upsert
-   * @returns The TemplateParser instance
-   */
-  public upsertViewportTag(viewport: string): TemplateParser {
-    upsertHeadInlineScripts(this.head, [viewport]);
-    return this;
-  }
-
   /**
    * Upsert the head before html tags
    * @param tags - The tags to upsert
@@ -86,7 +76,9 @@ export class TemplateParser {
    * @param scripts - The scripts to upsert
    * @returns The TemplateParser instance
    */
-  public upsertHeadInlineScripts(scripts: string[]): TemplateParser {
+  public upsertHeadInlineScripts(
+    scripts: ScriptionInlineItem[]
+  ): TemplateParser {
     upsertHeadInlineScripts(this.body, scripts);
     return this;
   }

src/parser/parseTemplate.ts

@@ -21,10 +21,6 @@ export const parseTemplate = (
     parser.upsertFaviconTag(options.favicon);
   }
 
-  if (options.viewport) {
-    parser.upsertViewportTag(options.viewport);
-  }
-
   if (options.headMetaTags?.length) {
     parser.upsertHeadMetaTags(options.headMetaTags);
   }

src/parser/upsertHeadInlineScripts.ts

@@ -1,4 +1,5 @@
 import { type DefaultTreeAdapterTypes, parseFragment } from 'parse5';
+import type { ScriptionInlineItem } from '../types.js';
 
 /**
  * Upsert the inline scripts
@@ -7,17 +8,16 @@ import { type DefaultTreeAdapterTypes, parseFragment } from 'parse5';
  */
 export const upsertHeadInlineScripts = (
   head: DefaultTreeAdapterTypes.Element,
-  scripts: string[]
+  scripts: ScriptionInlineItem[]
 ) => {
   // Remove existing inline scripts with matching content
   scripts.forEach((script) => {
     const existingScriptIndex = head.childNodes.findIndex(
       (node) =>
         node.nodeName === 'script' &&
-        (
-          (node as DefaultTreeAdapterTypes.Element)
-            .childNodes?.[0] as DefaultTreeAdapterTypes.TextNode
-        )?.value === script
+        (node as DefaultTreeAdapterTypes.Element).attrs?.find(
+          (attr) => attr.name === 'id' && attr.value === script.id
+        )
     );
 
     if (existingScriptIndex > -1) {
@@ -26,10 +26,46 @@ export const upsertHeadInlineScripts = (
   });
 
   // Add new inline scripts
-  scripts.forEach((script) => {
-    const scriptNode = parseFragment(`<script>${script}</script>`)
-      .childNodes[0] as DefaultTreeAdapterTypes.Element;
+  // Sort scripts by order (smaller numbers first)
+  const sortedScripts = [...scripts].sort(
+    (a, b) => (a.order ?? 0) - (b.order ?? 0)
+  );
+
+  // Create script nodes
+  const scriptTags = sortedScripts.map((script) => {
+    const scriptNode = parseFragment(
+      `<script id="${script.id}">${script.content}</script>`
+    ).childNodes[0] as DefaultTreeAdapterTypes.Element;
+    return scriptNode;
+  });
+
+  // Split scripts by position
+  const beginningScripts = sortedScripts.reduce<
+    DefaultTreeAdapterTypes.Element[]
+  >((acc, script, index) => {
+    if (script.position === 'beginning') {
+      acc.push(scriptTags[index]);
+    }
+    return acc;
+  }, []);
+
+  const endScripts = sortedScripts.reduce<DefaultTreeAdapterTypes.Element[]>(
+    (acc, script, index) => {
+      if (script.position === 'end') {
+        acc.push(scriptTags[index]);
+      }
+      return acc;
+    },
+    []
+  );
+
+  // Add beginning scripts
+  beginningScripts.reverse().forEach((scriptNode) => {
+    head.childNodes.unshift(scriptNode);
+  });
 
+  // Add end scripts
+  endScripts.forEach((scriptNode) => {
     head.childNodes.push(scriptNode);
   });
 };

src/parser/upsertScripts.ts

@@ -21,7 +21,7 @@ export const upsertScripts = (
       (node) =>
         node.nodeName === 'script' &&
         (node as DefaultTreeAdapterTypes.Element).attrs?.find(
-          (attr) => attr.name === 'src' && attr.value === script.src
+          (attr) => attr.name === 'id' && attr.value === script.id
         )
     );
 
@@ -32,8 +32,9 @@ export const upsertScripts = (
 
   // Create new script nodes
   const scriptTags = sortedScripts.map((script) => {
-    const scriptNode = parseFragment(`<script src="${script.src}"></script>`)
-      .childNodes[0] as DefaultTreeAdapterTypes.Element;
+    const scriptNode = parseFragment(
+      `<script id="${script.id}" src="${script.src}"></script>`
+    ).childNodes[0] as DefaultTreeAdapterTypes.Element;
 
     if (script.type) {
       scriptNode.attrs?.push({ name: 'type', value: script.type });

src/types.ts

@@ -1,17 +1,41 @@
-export type ScriptItem = {
+/**
+ * The position of the script
+ */
+export type Position = 'beginning' | 'end';
+
+/**
+ * The base script item
+ */
+export type ScriptItemBase = {
   /**
-   * The src of the script
+   * The id of the script
    */
-  src: string;
+  id: string;
   /**
    * The position of the script, 'beginning' for beginning of head, 'end' for end of head
    * The position of the script, 'beginning' for beginning of body, 'end' for end of body
    */
-  position: 'beginning' | 'end';
+  position: Position;
   /**
    * The order of the script, smaller numbers are loaded first
    */
   order?: number;
+};
+/**
+ * The inline script item
+ */
+export type ScriptionInlineItem = ScriptItemBase & {
+  /**
+   * The content of the script
+   */
+  content: string;
+};
+
+export type ScriptItem = ScriptItemBase & {
+  /**
+   * The src of the script, the id
+   */
+  src: string;
   /**
    * The type of the script
    */
@@ -50,14 +74,7 @@ export interface TemplateOptions {
    * The favicon of the page
    */
   favicon?: string;
-  /**
-   * The viewport of the page
-   */
-  viewport?: string;
-  /**
-   * The head inline scripts
-   */
-  headInlineScripts?: string[];
+
   /**
    * The head html meta tags of the page
    */
@@ -74,4 +91,8 @@ export interface TemplateOptions {
    * The body scripts of the page
    */
   bodyScripts?: ScriptItem[];
+  /**
+   * The head inline scripts
+   */
+  headInlineScripts?: ScriptionInlineItem[];
 }