@wxt-dev/browser 0.2.8 → 0.3.0

package/README.md

@@ -55,4 +55,4 @@ pnpm gen
 
 With WXT, you must import the `browser` variable to use the extension APIs. The way `@types/chrome` is implemented forces you to define a global `chrome` variable. With WXT, this isn't acceptable, we don't want to pollute the global (type) scope or introduce conflicts with auto-imports.
 
-Additionally, WXT overrides types to provide additional type safety for some APIs, like `browser.runtime.getURL` and `browser.i18n.getMessage`. With `@types/chrome`'s nested namespace approach, it's not possible to override the types for those functions.
+Additionally, WXT overrides types to provide additional type safety for some APIs, like `browser.runtime.getURL` and `browser.i18n.getMessage`. With `@types/chrome`'s `declare namespace` definition, it's not possible to override the types for those functions.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wxt-dev/browser",
   "description": "Provides a cross-browser API for using extension APIs and types based on @types/chrome",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.mjs",
   "types": "src/index.d.ts",
@@ -25,7 +25,7 @@
     "src"
   ],
   "devDependencies": {
-    "@types/chrome": "0.2.8",
+    "@types/chrome": "0.3.0",
     "@types/node": "^22",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"

package/src/gen/index.d.ts

@@ -13,8 +13,20 @@ type SetPartial<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 ////////////////////
 interface Window {
     // chrome: typeof chrome;
+
+    /**
+     * Cross-browser alias of {@link chrome}.
+     * @since Chrome 148 (Chrome 152 for extensions declaring a `devtools_page` in manifest)
+     */
+    browser: typeof chrome;
 }
 
+/**
+ * Cross-browser alias of {@link chrome}.
+ * @since Chrome 148 (Chrome 152 for extensions declaring a `devtools_page` in manifest)
+ */
+declare var browser: typeof chrome;
+
 export namespace Browser {
     ////////////////////
     // Accessibility Features
@@ -527,7 +539,7 @@ export namespace Browser {
             /** Device name */
             deviceName: string;
             /** Type of the device */
-            deviceType: DeviceType;
+            deviceType: `${DeviceType}`;
             /** The user-friendly name (e.g. "USB Microphone"). */
             displayName: string;
             /** The unique identifier of the audio device. */
@@ -539,14 +551,14 @@ export namespace Browser {
             /** The stable/persisted device id string when available. */
             stableDeviceId?: string;
             /** Stream type associated with this device. */
-            streamType: StreamType;
+            streamType: `${StreamType}`;
         }
 
         interface DeviceFilter {
             /** If set, only audio devices whose active state matches this value will satisfy the filter. */
             isActive?: boolean;
             /** If set, only audio devices whose stream type is included in this list will satisfy the filter. */
-            streamTypes?: StreamType[];
+            streamTypes?: `${StreamType}`[];
         }
 
         interface DeviceIdLists {
@@ -602,7 +614,7 @@ export namespace Browser {
             /** Whether or not the stream is now muted. */
             isMuted: boolean;
             /** The type of the stream for which the mute value changed. The updated mute value applies to all devices with this stream type. */
-            streamType: StreamType;
+            streamType: `${StreamType}`;
         }
 
         /** Type of stream an audio device provides. */
@@ -613,14 +625,17 @@ export namespace Browser {
 
         /**
          * Gets a list of audio devices filtered based on filter.
+         * @param filter Device properties by which to filter the list of returned audio devices. If the filter is not set or set to `{}`, returned device list will contain all available audio devices.
+         *
          * Can return its result via Promise in Manifest V3 or later since Chrome 116.
          */
         function getDevices(filter?: DeviceFilter): Promise<AudioDeviceInfo[]>;
-        function getDevices(filter: DeviceFilter, callback: (devices: AudioDeviceInfo[]) => void): void;
         function getDevices(callback: (devices: AudioDeviceInfo[]) => void): void;
+        function getDevices(filter: DeviceFilter | undefined, callback: (devices: AudioDeviceInfo[]) => void): void;
 
         /**
          * Gets the system-wide mute state for the specified stream type.
+         *
          * Can return its result via Promise in Manifest V3 or later since Chrome 116.
          */
         function getMute(streamType: `${StreamType}`): Promise<boolean>;
@@ -628,6 +643,7 @@ export namespace Browser {
 
         /**
          * Sets lists of active input and/or output devices.
+         *
          * Can return its result via Promise in Manifest V3 or later since Chrome 116.
          */
         function setActiveDevices(ids: DeviceIdLists): Promise<void>;
@@ -635,6 +651,7 @@ export namespace Browser {
 
         /**
          * Sets mute state for a stream type. The mute state will apply to all audio devices with the specified audio stream type.
+         *
          * Can return its result via Promise in Manifest V3 or later since Chrome 116.
          */
         function setMute(streamType: `${StreamType}`, isMuted: boolean): Promise<void>;
@@ -642,6 +659,7 @@ export namespace Browser {
 
         /**
          * Sets the properties for the input or output device.
+         *
          * Can return its result via Promise in Manifest V3 or later since Chrome 116.
          */
         function setProperties(id: string, properties: DeviceProperties): Promise<void>;
@@ -650,18 +668,18 @@ export namespace Browser {
         /**
          * Fired when audio devices change, either new devices being added, or existing devices being removed.
          */
-        const onDeviceListChanged: Browser.events.Event<(devices: AudioDeviceInfo[]) => void>;
+        const onDeviceListChanged: events.Event<(devices: AudioDeviceInfo[]) => void>;
 
         /**
          * Fired when sound level changes for an active audio device.
          */
-        const onLevelChanged: Browser.events.Event<(event: LevelChangedEvent) => void>;
+        const onLevelChanged: events.Event<(event: LevelChangedEvent) => void>;
 
         /**
          * Fired when the mute state of the audio input or output changes.
          * Note that mute state is system-wide and the new value applies to every audio device with specified stream type.
          */
-        const onMuteChanged: Browser.events.Event<(event: MuteChangedEvent) => void>;
+        const onMuteChanged: events.Event<(event: MuteChangedEvent) => void>;
     }
 
     ////////////////////
@@ -2904,20 +2922,59 @@ export namespace Browser {
             injectedScript?: string | undefined;
         }
 
-        interface EvaluationExceptionInfo {
-            /** Set if the error occurred on the DevTools side before the expression is evaluated. */
-            isError: boolean;
-            /** Set if the error occurred on the DevTools side before the expression is evaluated. */
-            code: string;
-            /** Set if the error occurred on the DevTools side before the expression is evaluated. */
-            description: string;
-            /** Set if the error occurred on the DevTools side before the expression is evaluated, contains the array of the values that may be substituted into the description string to provide more information about the cause of the error. */
-            details: any[];
-            /** Set if the evaluated code produces an unhandled exception. */
-            isException: boolean;
-            /** Set if the evaluated code produces an unhandled exception. */
-            value: string;
-        }
+        type EvaluationExceptionInfo =
+            | {
+                /**
+                 * Set if the error occurred on the DevTools side before the expression is evaluated.
+                 *
+                 * If `isError` is set to true, a DevTools-side error has occurred, and `code` is set to an error code.
+                 *
+                 * See the docs on `isException` for more details on parsing this object.
+                 */
+                isError: true;
+                /** Set if the error occurred on the DevTools side before the expression is evaluated. */
+                code: string;
+                /** Set if the error occurred on the DevTools side before the expression is evaluated. */
+                description: string;
+                /** Set if the error occurred on the DevTools side before the expression is evaluated, contains the array of the values that may be substituted into the description string to provide more information about the cause of the error. */
+                details: any[];
+                /**
+                 * Set if the evaluated code produces an unhandled exception.
+                 *
+                 * If `isException` is non-null but not true, and `isError` is true, a DevTools-side error has occurred, and `code` is set to an error code.
+                 *
+                 * If `isException` is set to true, a JavaScript error has occurred, and `value` is set to the string value of the thrown object.
+                 */
+                isException?: undefined;
+                /** Set if the evaluated code produces an unhandled exception. */
+                value?: undefined;
+            }
+            | {
+                /**
+                 * Set if the error occurred on the DevTools side before the expression is evaluated.
+                 *
+                 * If `isError` is set to true, a DevTools-side error has occurred, and `code` is set to an error code.
+                 *
+                 * See the docs on `isException` for more details on parsing this object.
+                 */
+                isError?: undefined;
+                /** Set if the error occurred on the DevTools side before the expression is evaluated. */
+                code?: undefined;
+                /** Set if the error occurred on the DevTools side before the expression is evaluated. */
+                description?: undefined;
+                /** Set if the error occurred on the DevTools side before the expression is evaluated, contains the array of the values that may be substituted into the description string to provide more information about the cause of the error. */
+                details?: undefined;
+                /**
+                 * Set if the evaluated code produces an unhandled exception.
+                 *
+                 * If `isException` is non-null but not true, and `isError` is true, a DevTools-side error has occurred, and `code` is set to an error code.
+                 *
+                 * If `isException` is set to true, a JavaScript error has occurred, and `value` is set to the string value of the thrown object.
+                 */
+                isException: true;
+                /** Set if the evaluated code produces an unhandled exception. */
+                value: string;
+            };
 
         /** The ID of the tab being inspected. This ID may be used with {@link Browser.tabs} API. */
         const tabId: number;
@@ -2937,15 +2994,23 @@ export namespace Browser {
         function eval<T = { [key: string]: unknown }>(
             expression: string,
             options?: EvalOptions,
-        ): Promise<{ result: T; exceptionInfo: EvaluationExceptionInfo }>;
+        ): Promise<T>;
         function eval<T = { [key: string]: unknown }>(
             expression: string,
-            callback?: (result: T, exceptionInfo: EvaluationExceptionInfo) => void,
+            callback: (
+                ...args:
+                    | [result: T, exceptionInfo: undefined]
+                    | [result: undefined, exceptionInfo: EvaluationExceptionInfo]
+            ) => void,
         ): void;
         function eval<T = { [key: string]: unknown }>(
             expression: string,
             options: EvalOptions | undefined,
-            callback?: (result: T, exceptionInfo: EvaluationExceptionInfo) => void,
+            callback: (
+                ...args:
+                    | [result: T, exceptionInfo: undefined]
+                    | [result: undefined, exceptionInfo: EvaluationExceptionInfo]
+            ) => void,
         ): void;
 
         /**