Merge branch 'release/v0.2.0'

Author: addon-owner

README.md

@@ -10,9 +10,9 @@ Automatically detects Chrome Extension Manifest V2 and V3 and delegates to the a
 
 - [Installation](#installation)
 - [Usage](#usage)
-  - [Executing Functions](#executing-functions)
-  - [Injecting Script Files](#injecting-script-files)
-  - [Updating Options](#updating-options)
+    - [Executing Functions](#executing-functions)
+    - [Injecting Script Files](#injecting-script-files)
+    - [Updating Options](#updating-options)
 - [API](#api)
 - [Options](#options)
 - [Examples](#examples)
@@ -41,23 +41,26 @@ import injectScript, {InjectScriptOptions} from "@adnbn/inject-script";
 
 // Initialize an injector for a specific tab (Manifest V2 or V3)
 const injector = injectScript({
-  tabId: 123,
-  frameId: false,           // inject into the top frame only
-  matchAboutBlank: true,    // include about:blank frames
-  injectImmediately: false, // inject at `document_idle`
-  // V2 only: timeFallback: 5000,   // ms before timing out (default: 4000)
-  // V3 only: world: 'ISOLATED', documentId: 'abc123'
+    tabId: 123,
+    frameId: false, // inject into the top frame only
+    matchAboutBlank: true, // include about:blank frames
+    runAt: "document_idle", // inject at `document_idle`
+    // V2 only: timeFallback: 5000,   // ms before timing out (default: 4000)
+    // V3 only: world: 'ISOLATED', documentId: 'abc123'
 });
 
 // Execute a function in the page context
-await injector.run((msg: string) => {
-  console.log(msg);
-  return 'Done';
-}, ['Hello from extension!']);
+await injector.run(
+    (msg: string) => {
+        console.log(msg);
+        return "Done";
+    },
+    ["Hello from extension!"]
+);
 
 // Inject one or more external script files
-await injector.file('scripts/content.js');
-await injector.file(['scripts/lib.js', 'scripts/util.js']);
+await injector.file("scripts/content.js");
+await injector.file(["scripts/lib.js", "scripts/util.js"]);
 ```
 
 ### Executing Functions
@@ -74,7 +77,7 @@ Use the `options(opts: Partial<InjectScriptOptions>)` method to merge or overrid
 
 ## API
 
-### `injectScript(options: InjectScriptUnionOptions): InjectScriptContract`
+### `injectScript(options: InjectScriptOptions): InjectScriptContract`
 
 Creates and returns a new script injector. Detects your manifest version via `@adnbn/browser` and delegates to the appropriate implementation.
 
@@ -86,40 +89,41 @@ Creates and returns a new script injector. Detects your manifest version via `@a
 
 ## Options
 
-| Option             | Type                                    | Description                                                                                     |
-| ------------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `tabId`            | `number` (required)                     | Target browser tab ID.                                                                          |
-| `frameId`          | `boolean \| number \| number[]`        | `true` for all frames, number or list for specific frame IDs.                                   |
-| `matchAboutBlank`  | `boolean`                               | Include `about:blank` and similar frames (V2 and V3). Default: `true`.                          |
-| `injectImmediately` | `boolean`                               | Inject at `document_start` (`true`) or `document_idle` (`false`).                                |
-| `timeFallback`     | `number`                                | (V2 only) ms before timing out. Default: `4000`.                                                |
-| `world`            | `'MAIN' \| 'ISOLATED'`                 | (V3 only) Execution world for script injection.                                                 |
-| `documentId`       | `string \| string[]`                    | (V3 only) Document IDs for injection target.                                                    |
+| Option            | Type                                                    | Description                                                                                                  |
+| ----------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `tabId`           | `number` (required)                                     | Target browser tab ID.                                                                                       |
+| `frameId`         | `boolean \| number \| number[]`                         | `true` for all frames, number or list for specific frame IDs.                                                |
+| `matchAboutBlank` | `boolean`                                               | Include `about:blank` and similar frames (V2 and V3). Default: `true`.                                       |
+| `runAt`           | `'document_start' \| 'document_end' \| 'document_idle'` | Script injection timing. Use `document_start`, `document_end`, or `document_idle`. Default: `document_idle`. |
+| `timeFallback`    | `number`                                                | (V2 only) ms before timing out. Default: `4000`.                                                             |
+| `world`           | `'MAIN' \| 'ISOLATED'`                                  | (V3 only) Execution world for script injection.                                                              |
+| `documentId`      | `string \| string[]`                                    | (V3 only) Document IDs for injection target.                                                                 |
 
 ## Examples
 
 ```ts
 import injectScript from "@adnbn/inject-script";
 
 const injector = injectScript({
-  tabId: 123,
-  frameId: [0, 1],
-  injectImmediately: true,
-  world: 'MAIN',
-  documentId: ['doc1', 'doc2']
+    tabId: 123,
+    frameId: [0, 1],
+    runAt: "document_start",
+    world: "MAIN",
+    documentId: ["doc1", "doc2"],
 });
 
 // Execute code and handle results
 const results = await injector.run(() => location.href);
 console.log(results);
 
 // Inject scripts
-await injector.file(['content.js', 'helper.js']);
+await injector.file(["content.js", "helper.js"]);
 ```
 
 ## Development
 
 Build files
+
 ```bash
 npm run build
 ```
@@ -142,4 +146,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.
 
 ## License
 
-MIT © Addon Bone
+MIT © Addon Bone

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adnbn/inject-script",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A lightweight, TypeScript-ready library for injecting JavaScript functions or external scripts into Chrome extension tabs and frames (Manifest V2 & V3).",
   "keywords": [
     "browser",

src/AbstractInjectScript.ts

@@ -1,4 +1,4 @@
-import {InjectScriptOptions, InjectScriptContract} from "./types";
+import {InjectScriptContract, InjectScriptOptions} from "./types";
 
 type Awaited<T> = chrome.scripting.Awaited<T>;
 type InjectionResult<T> = chrome.scripting.InjectionResult<T>;

src/InjectScriptV2.ts

@@ -6,29 +6,22 @@ import AbstractInjectScript from "./AbstractInjectScript";
 
 import {InjectScriptOptions} from "./types";
 
-type RunAt = chrome.extensionTypes.RunAt;
-type InjectDetails = chrome.extensionTypes.InjectDetails;
-
-type MessageSender = chrome.runtime.MessageSender;
-
 type Awaited<T> = chrome.scripting.Awaited<T>;
+type MessageSender = chrome.runtime.MessageSender;
+type InjectDetails = chrome.extensionTypes.InjectDetails;
 type InjectionResult<T> = chrome.scripting.InjectionResult<T>;
 
-export interface InjectScriptV2Options extends InjectScriptOptions {
-    timeFallback?: number;
-}
-
 export default class extends AbstractInjectScript {
-    public constructor(protected _options: InjectScriptV2Options) {
-        super(_options);
+    public constructor(options: InjectScriptOptions) {
+        super(options);
     }
 
     public async run<A extends any[], R extends any>(
         func: (...args: A) => R,
         args?: A
     ): Promise<InjectionResult<Awaited<R>>[]> {
         return new Promise<InjectionResult<Awaited<R>>[]>(async (resolve, reject) => {
-            const {tabId} = this._options;
+            const {tabId, runAt} = this._options;
 
             const type = `inject-script-${nanoid()}`;
             const injectResults: InjectionResult<Awaited<R>>[] = [];
@@ -71,8 +64,8 @@ export default class extends AbstractInjectScript {
             }, this._options.timeFallback || 4000);
 
             const details: InjectDetails = {
+                runAt,
                 code: this.getCode(type, func, args),
-                runAt: this.runAt,
                 matchAboutBlank: this.matchAboutBlank,
             };
 
@@ -93,18 +86,14 @@ export default class extends AbstractInjectScript {
     }
 
     public async file(files: string | string[]): Promise<void> {
-        const {tabId} = this._options;
+        const {tabId, runAt} = this._options;
 
         const fileList = typeof files === "string" ? [files] : files;
 
         const injectTasks: Promise<any>[] = [];
 
         for (const file of fileList) {
-            const details: InjectDetails = {
-                file,
-                runAt: this.runAt,
-                matchAboutBlank: this.matchAboutBlank,
-            };
+            const details: InjectDetails = {file, runAt, matchAboutBlank: this.matchAboutBlank};
 
             if (this.allFrames) {
                 injectTasks.push(executeScriptTab(tabId, {...details, allFrames: true}));
@@ -148,8 +137,4 @@ export default class extends AbstractInjectScript {
                 });
         };
     }
-
-    protected get runAt(): RunAt {
-        return this._options.injectImmediately ? "document_start" : "document_idle";
-    }
 }

src/InjectScriptV3.ts

@@ -7,39 +7,37 @@ import {InjectScriptOptions} from "./types";
 type Awaited<T> = chrome.scripting.Awaited<T>;
 type InjectionTarget = chrome.scripting.InjectionTarget;
 type InjectionResult<T> = chrome.scripting.InjectionResult<T>;
-type ExecutionWorld = chrome.scripting.ExecutionWorld;
-
-export interface InjectScriptV3Options extends InjectScriptOptions {
-    world?: ExecutionWorld;
-    documentId?: string | string[];
-}
 
 export default class extends AbstractInjectScript {
-    constructor(protected _options: InjectScriptV3Options) {
-        super(_options);
+    constructor(options: InjectScriptOptions) {
+        super(options);
     }
 
     public async run<A extends any[], R extends any>(
         func: (...args: A) => R,
         args?: A
     ): Promise<InjectionResult<Awaited<R>>[]> {
-        const {world, injectImmediately} = this._options;
-
-        return executeScript({target: this.target, func, args, world, injectImmediately});
+        return executeScript({
+            target: this.target,
+            world: this._options.world,
+            injectImmediately: this.injectImmediately,
+            func,
+            args,
+        });
     }
 
     public async file(fileList: string | string[]): Promise<void> {
-        const {world, injectImmediately} = this._options;
-        const files = typeof fileList === "string" ? [fileList] : fileList;
-
-        await executeScript({target: this.target, files, world, injectImmediately});
+        await executeScript({
+            target: this.target,
+            world: this._options.world,
+            injectImmediately: this.injectImmediately,
+            files: typeof fileList === "string" ? [fileList] : fileList,
+        });
     }
 
     protected get target(): InjectionTarget {
-        const {tabId} = this._options;
-
         return {
-            tabId,
+            tabId: this._options.tabId,
             allFrames: this.allFrames,
             frameIds: this.frameIds,
             documentIds: this.documentIds,
@@ -51,4 +49,8 @@ export default class extends AbstractInjectScript {
 
         return typeof documentId === "string" ? [documentId] : documentId;
     }
+
+    protected get injectImmediately(): boolean {
+        return this._options.runAt === "document_start";
+    }
 }

src/index.ts

@@ -1,17 +1,12 @@
 import {isManifestVersion3} from "@adnbn/browser";
 
-import InjectScriptV2, {InjectScriptV2Options} from "./InjectScriptV2";
-import InjectScriptV3, {InjectScriptV3Options} from "./InjectScriptV3";
+import InjectScriptV2 from "./InjectScriptV2";
+import InjectScriptV3 from "./InjectScriptV3";
 
 import {InjectScriptOptions, InjectScriptContract} from "./types";
 
 export {type InjectScriptContract, type InjectScriptOptions};
 
-export type InjectScriptUnionOptions = InjectScriptV2Options & InjectScriptV3Options;
-
-export default (options: InjectScriptUnionOptions): InjectScriptContract => {
-    const {timeFallback, ...optionsV3} = options;
-    const {documentId, world, ...optionsV2} = options;
-
-    return isManifestVersion3() ? new InjectScriptV3(optionsV3) : new InjectScriptV2(optionsV2);
+export default (options: InjectScriptOptions): InjectScriptContract => {
+    return isManifestVersion3() ? new InjectScriptV3(options) : new InjectScriptV2(options);
 };

src/types.ts

@@ -1,4 +1,6 @@
+type RunAt = chrome.extensionTypes.RunAt;
 type Awaited<T> = chrome.scripting.Awaited<T>;
+type ExecutionWorld = chrome.scripting.ExecutionWorld;
 type InjectionResult<T> = chrome.scripting.InjectionResult<T>;
 
 export interface InjectScriptContract {
@@ -13,5 +15,12 @@ export interface InjectScriptOptions {
     tabId: number;
     frameId?: boolean | number | number[];
     matchAboutBlank?: boolean;
-    injectImmediately?: boolean;
+
+    // Options for MV2
+    runAt?: RunAt;
+    timeFallback?: number;
+
+    // Options for MV3
+    world?: ExecutionWorld;
+    documentId?: string | string[];
 }