feat: adds handling of null container value

Author: thedanchez

README.md

@@ -28,19 +28,17 @@ await loadScript("https://example.com/library.js", {
 
 ## 🧠 API
 
-### `loadScript(src, options?, target?)`
+### `loadScript(src, options?, container?)`
 
 Loads an external script dynamically and returns a `Promise<HTMLScriptElement>`.
 
 #### Parameters:
 
-| Name      | Type                | Description                                   |
-| --------- | ------------------- | --------------------------------------------- |
-| `src`     | `string`            | Script URL (required)                         |
-| `options` | `LoadScriptOptions` | `loadScript` options (e.g. `async`, `type`)   |
-| `target`  | `HTMLElement`       | Target element to append to (default: `head`) |
-
----
+| Name        | Type                | Description                                                       |
+| ----------- | ------------------- | ----------------------------------------------------------------- |
+| `src`       | `string`            | Script URL (required)                                             |
+| `options`   | `LoadScriptOptions` | `loadScript` options (e.g. `async`, `type`)                       |
+| `container` | `HTMLElement`       | HTML element to append `<script />` to (default: `document.head`) |
 
 ## ✅ Features
 
@@ -72,11 +70,10 @@ const WidgetLoader = () => {
 };
 ```
 
----
-
 ## 📝 Notes
 
 - Scripts are cached by `src` unless `innerHTML` or `textContent` is used
+- A nil (`undefined`/`null`) container value will append the script to `document.head`.
 - Cleanup is not automatic — script elements remain in the DOM
 
 ---

src/__tests__/loadScript.test.tsx

@@ -14,6 +14,54 @@ describe("loadScript", () => {
     await expect(loadScript("")).rejects.toThrow('No "src" provided to loadScript');
   });
 
+  test("assigns all direct script properties correctly", async () => {
+    const props = {
+      async: false,
+      defer: true,
+      fetchPriority: "low",
+      noModule: true,
+      id: "test-script",
+      type: "text/javascript",
+      crossOrigin: "anonymous",
+      referrerPolicy: "origin",
+      integrity: "sha384-abc123",
+      nonce: "xyz123",
+      textContent: "Hello, world!",
+    } as LoadScriptOptions;
+
+    const promise = loadScript(SCRIPT_SRC, props);
+
+    const [script] = document.querySelectorAll(`script[src="${SCRIPT_SRC}"]`);
+    expect(script).toBeDefined();
+
+    script?.dispatchEvent(new Event("load"));
+    const resolved = await promise;
+
+    expect(resolved.async).toBe(false);
+    expect(resolved.id).toBe("test-script");
+    expect(resolved.defer).toBe(true);
+    expect(resolved.fetchPriority).toBe("low");
+    expect(resolved.noModule).toBe(true);
+    expect(resolved.type).toBe("text/javascript");
+    expect(resolved.crossOrigin).toBe("anonymous");
+    expect(resolved.referrerPolicy).toBe("origin");
+    expect(resolved.integrity).toBe("sha384-abc123");
+    expect(resolved.nonce).toBe("xyz123");
+    expect(resolved.textContent).toBe("Hello, world!");
+  });
+
+  test("applies additional script attributes via setAttribute", async () => {
+    const promise = loadScript(SCRIPT_SRC, { "data-id": "custom-script-id" });
+
+    const [script] = document.querySelectorAll(`script[src="${SCRIPT_SRC}"]`);
+    expect(script).toBeDefined();
+
+    script?.dispatchEvent(new Event("load"));
+    const resolved = await promise;
+
+    expect(resolved.getAttribute("data-id")).toBe("custom-script-id");
+  });
+
   test("resolves immediately if script already exists in DOM", async () => {
     const script = document.createElement("script");
     script.src = SCRIPT_SRC;
@@ -80,52 +128,16 @@ describe("loadScript", () => {
     expect(resolved2).not.toBe(resolved1);
   });
 
-  test("assigns all direct script properties correctly", async () => {
-    const props = {
-      async: false,
-      defer: true,
-      fetchPriority: "low",
-      noModule: true,
-      id: "test-script",
-      type: "text/javascript",
-      crossOrigin: "anonymous",
-      referrerPolicy: "origin",
-      integrity: "sha384-abc123",
-      nonce: "xyz123",
-      textContent: "Hello, world!",
-    } as LoadScriptOptions;
-
-    const promise = loadScript(SCRIPT_SRC, props);
-
-    const [script] = document.querySelectorAll(`script[src="${SCRIPT_SRC}"]`);
-    expect(script).toBeDefined();
-
-    script?.dispatchEvent(new Event("load"));
-    const resolved = await promise;
-
-    expect(resolved.async).toBe(false);
-    expect(resolved.id).toBe("test-script");
-    expect(resolved.defer).toBe(true);
-    expect(resolved.fetchPriority).toBe("low");
-    expect(resolved.noModule).toBe(true);
-    expect(resolved.type).toBe("text/javascript");
-    expect(resolved.crossOrigin).toBe("anonymous");
-    expect(resolved.referrerPolicy).toBe("origin");
-    expect(resolved.integrity).toBe("sha384-abc123");
-    expect(resolved.nonce).toBe("xyz123");
-    expect(resolved.textContent).toBe("Hello, world!");
-  });
-
-  test("applies additional script attributes via setAttribute", async () => {
-    const promise = loadScript(SCRIPT_SRC, { "data-id": "custom-script-id" });
+  test("falls back to document.head when container is null", async () => {
+    const promise = loadScript(SCRIPT_SRC, { async: true }, null);
 
-    const [script] = document.querySelectorAll(`script[src="${SCRIPT_SRC}"]`);
+    const script = document.querySelector(`head script[src="${SCRIPT_SRC}"]`);
     expect(script).toBeDefined();
 
     script?.dispatchEvent(new Event("load"));
     const resolved = await promise;
 
-    expect(resolved.getAttribute("data-id")).toBe("custom-script-id");
+    expect(document.head.contains(resolved)).toBe(true);
   });
 
   test("resolves when script loads", async () => {

src/loadScript.ts

@@ -76,19 +76,18 @@ export const __resetScriptCache = () => {
  * @example
  * ```ts
  * const script = await loadScript("https://example.com/library.js", { type: "module" }, document.head);
- * console.log("Script loaded:", script.src);
  * ```
  *
  * @param src - The script URL to load.
  * @param options - additional options for the script (e.g. async, type, textContent).
- * @param target - Optional DOM element to append the script to (defaults to `document.head`).
+ * @param container - Optional DOM element to append the script to (defaults to `document.head`).
  * @returns A Promise that resolves to the script element.
  */
 
 export const loadScript = async (
   src: string,
   options: LoadScriptOptions = {},
-  target: HTMLElement = document.head,
+  container: HTMLElement | null = document.head,
 ): Promise<HTMLScriptElement> => {
   const {
     id,
@@ -139,7 +138,8 @@ export const loadScript = async (
   const promise = new Promise<HTMLScriptElement>((resolve, reject) => {
     const script = document.createElement("script");
 
-    target.appendChild(script);
+    const _container = container ?? document.head;
+    _container.appendChild(script);
 
     script.src = src;
     script.type = type;