@hyacine/helper 0.0.1

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hyacine/helper",
+  "version": "0.0.1",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./runtime": {
+      "types": "./src/runtime.d.ts",
+      "default": "./src/runtime.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "lint": "bunx --bun oxlint --type-aware --type-check . --fix",
+    "format": "bunx oxfmt ."
+  },
+  "dependencies": {
+    "@hyacine/core": "workspace:*",
+    "es-toolkit": "^1.44.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/src/dom-inject.test.ts

@@ -0,0 +1,218 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+/**
+ * 模拟浏览器环境
+ */
+function setupDOM() {
+  // 模拟 document 和基本的 DOM 方法
+  const elements = new Map<string, HTMLElement>();
+
+  const mockDocument = {
+    createElement: (tagName: string) => {
+      const element = {
+        tagName: tagName.toUpperCase(),
+        textContent: "",
+        src: "",
+        href: "",
+        type: "",
+        async: false,
+        defer: false,
+        crossOrigin: "",
+        integrity: "",
+        rel: "",
+        media: "",
+        attributes: {} as Record<string, string>,
+        setAttribute: (name: string, value: string) => {
+          element.attributes[name] = value;
+        },
+        getAttribute: (name: string) => element.attributes[name],
+      };
+      return element;
+    },
+    head: {
+      appendChild: (element: unknown) => {
+        elements.set("head-child", element as HTMLElement);
+        return element;
+      },
+    },
+    body: {
+      appendChild: (element: unknown) => {
+        elements.set("body-child", element as HTMLElement);
+        return element;
+      },
+    },
+  };
+
+  // 将模拟的 document 设置到 global 作用域
+  // @ts-expect-error: 模拟 DOM 环境
+  global.document = mockDocument;
+
+  return { mockDocument, elements };
+}
+
+function teardownDOM() {
+  // @ts-expect-error: 清理模拟的 DOM
+  delete global.document;
+}
+
+// 导入需要测试的函数（必须在 DOM 模拟之后）
+import { injectLinkCSS, injectScript } from "./dom-inject";
+
+describe("injectScript", () => {
+  beforeEach(() => {
+    setupDOM();
+  });
+
+  afterEach(() => {
+    teardownDOM();
+  });
+
+  test("应该注入外部脚本到 head", () => {
+    const script = injectScript({
+      src: "https://example.com/script.js",
+    });
+
+    expect(script.tagName).toBe("SCRIPT");
+    expect(script.src).toBe("https://example.com/script.js");
+  });
+
+  test("应该注入内联脚本到 head", () => {
+    const script = injectScript({
+      content: 'console.log("test");',
+    });
+
+    expect(script.tagName).toBe("SCRIPT");
+    expect(script.textContent).toBe('console.log("test");');
+  });
+
+  test("应该注入脚本到 body", () => {
+    const script = injectScript(
+      {
+        src: "https://example.com/script.js",
+      },
+      "body",
+    );
+
+    expect(script.tagName).toBe("SCRIPT");
+    expect(script.src).toBe("https://example.com/script.js");
+  });
+
+  test("应该设置 async 属性", () => {
+    const script = injectScript({
+      src: "https://example.com/script.js",
+      async: true,
+    });
+
+    expect(script.async).toBe(true);
+  });
+
+  test("应该设置 defer 属性", () => {
+    const script = injectScript({
+      src: "https://example.com/script.js",
+      defer: true,
+    });
+
+    expect(script.defer).toBe(true);
+  });
+
+  test("应该设置 type 属性", () => {
+    const script = injectScript({
+      src: "https://example.com/script.js",
+      type: "module",
+    });
+
+    expect(script.type).toBe("module");
+  });
+
+  test("应该设置 crossOrigin 和 integrity", () => {
+    const script = injectScript({
+      src: "https://example.com/script.js",
+      crossOrigin: "anonymous",
+      integrity: "sha384-xxx",
+    });
+
+    expect(script.crossOrigin).toBe("anonymous");
+    expect(script.integrity).toBe("sha384-xxx");
+  });
+
+  test("应该设置自定义属性", () => {
+    const script = injectScript({
+      src: "https://example.com/script.js",
+      attributes: {
+        "data-custom": "value",
+        id: "my-script",
+      },
+    });
+
+    expect(script.getAttribute("data-custom")).toBe("value");
+    expect(script.getAttribute("id")).toBe("my-script");
+  });
+
+  test("当既没有 src 也没有 content 时应该抛出错误", () => {
+    expect(() => {
+      injectScript({});
+    }).toThrow(/必须提供 src 或 content 之一/);
+  });
+
+  test("当同时提供 src 和 content 时应该抛出错误", () => {
+    expect(() => {
+      injectScript({
+        src: "https://example.com/script.js",
+        content: 'console.log("test");',
+      });
+    }).toThrow(/src 和 content 不能同时提供/);
+  });
+});
+
+describe("injectLinkCSS", () => {
+  beforeEach(() => {
+    setupDOM();
+  });
+
+  afterEach(() => {
+    teardownDOM();
+  });
+
+  test("应该注入 CSS 链接到 head", () => {
+    const link = injectLinkCSS({
+      href: "https://example.com/style.css",
+    });
+
+    expect(link.tagName).toBe("LINK");
+    expect(link.rel).toBe("stylesheet");
+    expect(link.href).toBe("https://example.com/style.css");
+  });
+
+  test("应该设置 media 属性", () => {
+    const link = injectLinkCSS({
+      href: "/mobile.css",
+      media: "(max-width: 768px)",
+    });
+
+    expect(link.media).toBe("(max-width: 768px)");
+  });
+
+  test("应该设置 crossOrigin 和 integrity", () => {
+    const link = injectLinkCSS({
+      href: "https://cdn.example.com/library.css",
+      crossOrigin: "anonymous",
+      integrity: "sha384-xxx",
+    });
+
+    expect(link.crossOrigin).toBe("anonymous");
+    expect(link.integrity).toBe("sha384-xxx");
+  });
+
+  test("应该设置自定义属性", () => {
+    const link = injectLinkCSS({
+      href: "/style.css",
+      attributes: {
+        "data-theme": "dark",
+        id: "theme-css",
+      },
+    });
+
+    expect(link.getAttribute("data-theme")).toBe("dark");
+    expect(link.getAttribute("id")).toBe("theme-css");
+  });
+});

package/src/dom-inject.ts

@@ -0,0 +1,223 @@
+/**
+ * DOM Injection API
+ *
+ * This module provides utilities for injecting scripts and CSS into the DOM.
+ */
+
+/**
+ * Script 标签配置选项
+ */
+export interface ScriptOptions {
+  /**
+   * script 标签的 src 属性（外部脚本）
+   */
+  src?: string;
+  /**
+   * script 标签的内联内容（内联脚本）
+   */
+  content?: string;
+  /**
+   * script 标签的类型，默认为 "text/javascript"
+   */
+  type?: string;
+  /**
+   * 是否异步加载脚本
+   */
+  async?: boolean;
+  /**
+   * 是否延迟加载脚本
+   */
+  defer?: boolean;
+  /**
+   * 跨域设置
+   */
+  crossOrigin?: "anonymous" | "use-credentials";
+  /**
+   * 脚本的完整性校验值（Subresource Integrity）
+   */
+  integrity?: string;
+  /**
+   * 其他自定义属性
+   */
+  attributes?: Record<string, string>;
+}
+
+/**
+ * Link CSS 标签配置选项
+ */
+export interface LinkCSSOptions {
+  /**
+   * link 标签的 href 属性（CSS 文件路径）
+   */
+  href: string;
+  /**
+   * 跨域设置
+   */
+  crossOrigin?: "anonymous" | "use-credentials";
+  /**
+   * 资源的完整性校验值（Subresource Integrity）
+   */
+  integrity?: string;
+  /**
+   * 媒体查询条件
+   */
+  media?: string;
+  /**
+   * 其他自定义属性
+   */
+  attributes?: Record<string, string>;
+}
+
+/**
+ * 向 head 或 body 注入 script 标签
+ *
+ * @param options - Script 标签配置选项
+ * @param target - 注入目标，默认为 'head'
+ * @returns 创建的 script 元素
+ * @throws {Error} 如果既没有提供 src 也没有提供 content
+ *
+ * @example
+ * ```typescript
+ * // 注入外部脚本到 head
+ * injectScript({
+ *   src: 'https://example.com/script.js',
+ *   async: true
+ * });
+ *
+ * // 注入内联脚本到 body
+ * injectScript({
+ *   content: 'console.log("Hello from inline script");'
+ * }, 'body');
+ *
+ * // 注入带有完整性校验的外部脚本
+ * injectScript({
+ *   src: 'https://cdn.example.com/library.js',
+ *   integrity: 'sha384-xxx',
+ *   crossOrigin: 'anonymous'
+ * });
+ * ```
+ */
+export function injectScript(
+  options: ScriptOptions,
+  target: "head" | "body" = "head",
+): HTMLScriptElement {
+  if (!options.src && !options.content) {
+    throw new Error("[hyacine-plugin] injectScript: 必须提供 src 或 content 之一");
+  }
+
+  if (options.src && options.content) {
+    throw new Error("[hyacine-plugin] injectScript: src 和 content 不能同时提供");
+  }
+
+  const script = document.createElement("script");
+
+  // 设置基本属性
+  if (options.src) {
+    script.src = options.src;
+  }
+
+  if (options.content) {
+    script.textContent = options.content;
+  }
+
+  if (options.type) {
+    script.type = options.type;
+  }
+
+  if (options.async) {
+    script.async = true;
+  }
+
+  if (options.defer) {
+    script.defer = true;
+  }
+
+  if (options.crossOrigin) {
+    script.crossOrigin = options.crossOrigin;
+  }
+
+  if (options.integrity) {
+    script.integrity = options.integrity;
+  }
+
+  // 设置自定义属性
+  if (options.attributes) {
+    for (const [key, value] of Object.entries(options.attributes)) {
+      script.setAttribute(key, value);
+    }
+  }
+
+  // 注入到目标位置
+  const targetElement = document[target];
+  if (!targetElement) {
+    throw new Error(`[hyacine-plugin] injectScript: 找不到目标元素 <${target}>`);
+  }
+
+  targetElement.appendChild(script);
+
+  return script;
+}
+
+/**
+ * 向 head 注入 link CSS 标签
+ *
+ * @param options - Link CSS 标签配置选项
+ * @returns 创建的 link 元素
+ *
+ * @example
+ * ```typescript
+ * // 注入外部 CSS
+ * injectLinkCSS({
+ *   href: 'https://example.com/style.css'
+ * });
+ *
+ * // 注入带有媒体查询的 CSS
+ * injectLinkCSS({
+ *   href: '/mobile.css',
+ *   media: '(max-width: 768px)'
+ * });
+ *
+ * // 注入带有完整性校验的 CSS
+ * injectLinkCSS({
+ *   href: 'https://cdn.example.com/library.css',
+ *   integrity: 'sha384-xxx',
+ *   crossOrigin: 'anonymous'
+ * });
+ * ```
+ */
+export function injectLinkCSS(options: LinkCSSOptions): HTMLLinkElement {
+  const link = document.createElement("link");
+
+  // 设置固定属性
+  link.rel = "stylesheet";
+  link.href = options.href;
+
+  if (options.crossOrigin) {
+    link.crossOrigin = options.crossOrigin;
+  }
+
+  if (options.integrity) {
+    link.integrity = options.integrity;
+  }
+
+  if (options.media) {
+    link.media = options.media;
+  }
+
+  // 设置自定义属性
+  if (options.attributes) {
+    for (const [key, value] of Object.entries(options.attributes)) {
+      link.setAttribute(key, value);
+    }
+  }
+
+  // 注入到 head
+  const head = document.head;
+  if (!head) {
+    throw new Error("[hyacine-plugin] injectLinkCSS: 找不到 <head> 元素");
+  }
+
+  head.appendChild(link);
+
+  return link;
+}