recursal/MDN huggingface dataset:
history.addUrl()
================

Adds a record to the browser's history of a visit to the given URL. The visit's time is recorded as the time of the call, and the `TransitionType` is recorded as "link".

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let addingUrl = browser.history.addUrl(
  details         // object
)
```

### Parameters

`details`

`object`. Object containing the URL to add.

`url`

`string`. The URL to add.

`title` Optional

string: The title of the page. If this is not supplied, the title will be recorded as `null`.

`transition` Optional

`history.TransitionType`. Describes how the browser navigated to the page on this occasion. If this is not supplied, a transition type of "link" will be recorded.

`visitTime` Optional

`number` or `string` or `object`. A value indicating a date and time. This can be represented as: a `Date` object, an ISO 8601 date string, or the number of milliseconds since the epoch. Sets the visit time to this value. If this is not supplied, the current time will be recorded.


### Return value

A `Promise` will be fulfilled with no parameters when the item has been added.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Add a record of a visit to "https://example.org/", then check that the new visit was recorded by searching history for the most recent item and logging it:


```js
function onGot(results) {
  if (results.length) {
    console.log(results[0].url);
    console.log(new Date(results[0].lastVisitTime));
  }
}

browser.history
  .addUrl({ url: "https://example.org/" })
  .then(() =>
    browser.history.search({
      text: "https://example.org/",
      startTime: 0,
      maxResults: 1,
    }),
  )
  .then(onGot);
```


Add a record of a visit to "https://example.org", but give it a `visitTime` 24 hours in the past, and a `transition` of "typed":


```js
const DAY = 24 \* 60 \* 60 \* 1000;

function oneDayAgo() {
  return Date.now() - DAY;
}

function onGot(visits) {
  for (const visit of visits) {
    console.log(new Date(visit.visitTime));
    console.log(visit.transition);
  }
}

browser.history
  .addUrl({
    url: "https://example.org/",
    visitTime: oneDayAgo(),
    transition: "typed",
  })
  .then(() =>
    browser.history.getVisits({
      url: "https://example.org/",
    }),
  )
  .then(onGot);
```


**Note:** This API is based on Chromium's `chrome.history` API. This documentation is derived from `history.json` in the Chromium code.
history.onVisited
=================

Fired each time the user visits a page. A `history.HistoryItem` object is passed to the listener. This event fires before the page has loaded.

Syntax
------


```js
browser.history.onVisited.addListener(listener)
browser.history.onVisited.removeListener(listener)
browser.history.onVisited.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`result`

`history.HistoryItem`. An object representing the item in the browser's history.

At the time that this event is sent, the browser doesn't yet know the title of the page. If the browser has visited this page before and has remembered its old title, then the `HistoryItem.title` object will contain the old title of the page. If the browser doesn't have a record of the page's old title, then `HistoryItem.title` will be empty. To get the titles of pages as soon as they are known, listen for `history.onTitleChanged`.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Listen for visits, and log the URL and visit time.


```js
function onVisited(historyItem) {
  console.log(historyItem.url);
  console.log(new Date(historyItem.lastVisitTime));
}

browser.history.onVisited.addListener(onVisited);
```


**Note:** This API is based on Chromium's `chrome.history` API. This documentation is derived from `history.json` in the Chromium code.
history.onTitleChanged
======================

Fired when the title of a page visited by the user is recorded. To listen for visits to a page you use `history.onVisited`. However, the `history.HistoryItem` that this event passes to its listener does not include the page title, because the page title is typically not known at the time `history.onVisited` is sent. Instead, the stored `history.HistoryItem` is updated with the page title after the page has loaded, once the title is known. The `history.onTitleChanged` event is fired at that time. So if you need to know the titles of pages as they are visited, listen for `history.onTitleChanged`.

Syntax
------


```js
browser.history.onTitleChanged.addListener(listener)
browser.history.onTitleChanged.removeListener(listener)
browser.history.onTitleChanged.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed an object with these properties:

`id`

`String`. The unique identifier for the `history.HistoryItem` associated with this visit.

`url`

`String`. URL of the page visited.

`title`

`String`. Title of the page visited.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Listen for title change events, and log the ID, URL, and title of the visited pages.


```js
function handleTitleChanged(item) {
  console.log(item.id);
  console.log(item.title);
  console.log(item.url);
}

browser.history.onTitleChanged.addListener(handleTitleChanged);
```


**Note:** This API is based on Chromium's `chrome.history` API. This documentation is derived from `history.json` in the Chromium code.
history.deleteRange()
=====================

Removes all visits to pages that the user made during the given time range. If this removes all visits made to a given page, then the page will be no longer appear in the browser history and `history.onVisitRemoved` will fire for it.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let deletingRange = browser.history.deleteRange(
  range           // object
)
```

### Parameters

`range`

`object`. Specification of the time range for which to delete visits.

`startTime`

`number` or `string` or `object`. A value indicating a date and time. This can be represented as: a `Date` object, an ISO 8601 date string, or the number of milliseconds since the epoch. Specifies the start time for the range.

`endTime`

`number` or `string` or `object`. A value indicating a date and time. This can be represented as: a `Date` object, an ISO 8601 date string, or the number of milliseconds since the epoch. Specifies the end time for the range.


### Return value

A `Promise` will be fulfilled with no parameters when the range has been deleted.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Delete all visits made in the last minute:


```js
const MINUTE = 60 \* 1000;

function oneMinuteAgo() {
  return Date.now() - MINUTE;
}

browser.history.deleteRange({
  startTime: oneMinuteAgo(),
  endTime: Date.now(),
});
```


**Note:** This API is based on Chromium's `chrome.history` API. This documentation is derived from `history.json` in the Chromium code.
history.getVisits()
===================

Retrieves information about all visits to the given URL.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let getting = browser.history.getVisits(
  details                // object
)
```

### Parameters

`details`

An object with the following properties:

`url`

`string`. The URL for which to retrieve visit information.


### Return value

A `Promise` will be fulfilled with an array of ``history.VisitItem`` objects each representing a visit to the given URL. Visits are sorted in reverse chronological order.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

List all visits to the most recently-visited page:


```js
function gotVisits(visits) {
  console.log(`Visit count: ${visits.length}`);
  for (const visit of visits) {
    console.log(visit.visitTime);
  }
}

function listVisits(historyItems) {
  if (historyItems.length) {
    console.log(`URL ${historyItems[0].url}`);
    const gettingVisits = browser.history.getVisits({
      url: historyItems[0].url,
    });
    gettingVisits.then(gotVisits);
  }
}

let searching = browser.history.search({
  text: "",
  startTime: 0,
  maxResults: 1,
});

searching.then(listVisits);
```


**Note:** This API is based on Chromium's `chrome.history` API. This documentation is derived from `history.json` in the Chromium code.
history.HistoryItem
===================

A `HistoryItem` object provides information about a page in the browser history.

Type
----

This is an object with the following properties:

`id`

`string`. Unique identifier for the item.

`url` Optional

`string`. The URL of the page.

`title` Optional

`string`. The title of the page.

`lastVisitTime` Optional

`number`. The date and time the page was last loaded, represented in milliseconds since the epoch.

`visitCount` Optional

`number`. The number of times the user has visited the page.

`typedCount` Optional

`number`. The number of times the user has navigated to this page by typing in the address.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.history` API. This documentation is derived from `history.json` in the Chromium code.
history.onVisitRemoved
======================

Fired when a page is removed completely from the browser history.

* If all visits to a single page are removed (for example, using `history.deleteUrl`), then this event is fired once.
* If a range of visits is removed (for example, using `history.deleteRange` or a browser feature like "Clear Recent History"), then it is fired once for each page *whose visits all fall within the cleared range*.
* If the browser's entire history is cleared (for example, using `history.deleteAll`), then it is fired only once.
Syntax
------


```js
browser.history.onVisitRemoved.addListener(listener)
browser.history.onVisitRemoved.removeListener(listener)
browser.history.onVisitRemoved.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`removed`

`object`. Details of the removal. This is an object containing two properties: a boolean `allHistory` and an array `urls`.

* If this event is firing because all history was cleared, `allHistory` will be `true` and `urls` will be an empty array.
* Otherwise, `allHistory` will be `false` and `urls` will contain one item, which is the URL of the removed page.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function onRemoved(removed) {
  if (removed.allHistory) {
    console.log("All history removed");
  } else if (removed.urls.length) {
    console.log(`URL removed: ${removed.urls[0]}`);
  }
}

browser.history.onVisitRemoved.addListener(onRemoved);
```


**Note:** This API is based on Chromium's `chrome.history` API. This documentation is derived from `history.json` in the Chromium code.
windows.getAll()
================

Gets information about all open windows, passing them into a callback.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingAll = browser.windows.getAll(
  getInfo                // optional object
)
```

### Parameters

`getInfo` Optional

`object`. This controls what `windows.Window` objects are retrieved.

`populate` Optional

`boolean`. Defaults to `false`. If set to `true`, each `windows.Window` object will have a `tabs` property that contains a list of `tabs.Tab` objects representing the tabs in that window. The `Tab` objects will contain the `url`, `title` and `favIconUrl` properties only if the extension's manifest file includes the `"tabs"` permission or host permissions that match the tab's URL.

`windowTypes` Optional

An `array` of `windows.WindowType` objects. If set, the `windows.Window` objects returned will be filtered based on their type. If unset the default filter is set to `['normal', 'panel', 'popup']`, with `'panel'` window types limited to the extension's own windows.


### Return value

A `Promise` that will be fulfilled with an array of `windows.Window` objects, representing all windows that match the given criteria. If any error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the URLs for the tabs across all "normal" browser windows. Note that you'll need the "tabs" permission or matching host permissions to access tab URLs.


```js
function logTabsForWindows(windowInfoArray) {
  for (const windowInfo of windowInfoArray) {
    console.log(`Window: ${windowInfo.id}`);
    console.log(windowInfo.tabs.map((tab) => tab.url));
  }
}

function onError(error) {
  console.error(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener((tab) => {
  browser.windows
    .getAll({
      populate: true,
      windowTypes: ["normal"],
    })
    .then(logTabsForWindows, onError);
});
```

### Example extensions

* private-browsing-theme
* window-manipulator

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.onCreated
=================

Fired when a window is created.

Syntax
------


```js
browser.windows.onCreated.addListener(listener)
browser.windows.onCreated.removeListener(listener)
browser.windows.onCreated.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`window`

A `windows.Window` object containing details of the window that was created.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the IDs of new windows as they are created:


```js
browser.windows.onCreated.addListener((window) => {
  console.log(`New window: ${window.id}`);
});
```

### Example extensions

* private-browsing-theme

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.WINDOW\_ID\_NONE
========================

The `windowId` value that represents the absence of a browser window.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.WindowState
===================

The state of this browser window.

Type
----

Values of this type are `strings`. Possible values are:

`"normal"`

The window is at the default size or user-selected size.

`"minimized"`

The window is only visible as an icon in the taskbar or .

`"maximized"`

The window fills the screen on which it is displayed not including any screen areas reserved by the operating system.

`"fullscreen"`

The window is running as a full screen application or content in a tab is using the Fullscreen API

`"docked"`

A docked window occupies a fixed position relative to other windows owned by the same application.

macOS compatibility: Beginning in macOS 10.10, the default maximizing behavior for windows changed to run applications as full screen applications instead of "zoomed" windows. `fullscreen` refers to both the browser running as a full screen application and when content in a tab uses the Fullscreen API.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.CreateType
==================

Specifies the type of browser window to create.

Type
----

Values of this type are `strings`. Possible values are:

* `"normal"`
* `"popup"`
* `"panel"`
* `"detached_panel"`
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.onRemoved
=================

Fired when a window is closed.

Syntax
------


```js
browser.windows.onRemoved.addListener(listener)
browser.windows.onRemoved.removeListener(listener)
browser.windows.onRemoved.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`windowId`

`integer`. ID of the window that was closed.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the IDs of windows as they are removed.


```js
browser.windows.onRemoved.addListener((windowId) => {
  console.log(`Closed window: ${windowId}`);
});
```


**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.WindowType
==================

The type of browser window this is.

Type
----

Values of this type are `strings`. Possible values are:

* `"normal"`
* `"popup"`
* `"panel"`
* `"devtools"`
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.
windows.getCurrent()
====================

Gets the current browser window, passing its details into a callback.

The "current" window is not necessarily the same as the currently focused window. If this function is called from a background script, then it returns the currently focused window. But if it is called from a script whose document is associated with a particular browser window, then it returns that browser window. For example, if the browser is displaying a sidebar, then every browser window has its own instance of the sidebar document. If a script running in the sidebar document calls `getCurrent()`, then it will return that sidebar document's window.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingCurrent = browser.windows.getCurrent(
  getInfo               // optional object
)
```

### Parameters

`getInfo` Optional

`object`.

`populate` Optional

`boolean`. If true, the `windows.Window` object will have a `tabs` property that contains a list of `tabs.Tab` objects representing the tabs in the window. The `Tab` objects only contain the `url`, `title` and `favIconUrl` properties if the extension's manifest file includes the `"tabs"` permission or host permissions that match the tab's URL.

`windowTypes` 
Deprecated
 Optional

An `array` of ``windows.WindowType`` objects. If set, the `windows.Window` returned will be filtered based on its type. If unset the default filter is set to `['normal', 'panel', 'popup']`, with `'panel'` window types limited to the extension's own windows.


**Note:** If supplied, the `windowTypes` component of `getInfo` is ignored. The use of `windowTypes` has been deprecated as of Firefox 62.

### Return value

A `Promise` that will be fulfilled with a `windows.Window` object containing the details of the window. If any error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

When the user clicks a browser action's icon, this example gets the current window and logs the URLs of the tabs it contains. Note that you'll need the "tabs" permission or matching host permissions to access tab URLs.


```js
function logTabs(windowInfo) {
  for (const tabInfo of windowInfo.tabs) {
    console.log(tabInfo.url);
  }
}

function onError(error) {
  console.error(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener((tab) => {
  browser.windows.getCurrent({ populate: true }).then(logTabs, onError);
});
```

### Example extensions

* annotate-page
* theme-integrated-sidebar
* window-manipulator

**Note:** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.json` in the Chromium code.