npm package: @krakenjs/cross-domain-utils
Description: Utilities for dealing with cross-domain windows.
Latest version: 3.1.0

## Cross Domain Utils

[![build status][build-badge]][build]
[![code coverage][coverage-badge]][coverage]
[![npm version][version-badge]][package]
[![apache license][license-badge]][license]

[build-badge]: https://img.shields.io/github/actions/workflow/status/krakenjs/cross-domain-utils/main.yml?branch=main&logo=github&style=flat-square
[build]: https://github.com/krakenjs/cross-domain-utils/actions/workflows/main.yml?query=workflow:build
[coverage-badge]: https://img.shields.io/codecov/c/github/krakenjs/cross-domain-utils.svg?style=flat-square
[coverage]: https://codecov.io/github/krakenjs/cross-domain-utils
[version-badge]: https://img.shields.io/npm/v/@krakenjs/cross-domain-utils.svg?style=flat-square
[package]: https://www.npmjs.com/package/@krakenjs/cross-domain-utils
[license-badge]: https://img.shields.io/npm/l/@krakenjs/cross-domain-utils.svg?style=flat-square
[license]: https://github.com/krakenjs/cross-domain-utils/blob/main/LICENSE

A set of utilities for dealing with cross-domain windows

## Installation

As of version 3 this package will be published under the `@krakenjs` scope.

```
npm install @krakenjs/cross-domain-utils
```

## Public methods

### `getDomain(win : Window) => string`

Get the full domain of the specified window, as a string.

- `win` must be a window on the same domain as the current window, or an exception will be raised
- This can be overridden / mocked by setting `win.mockDomain = 'mock://some-domain.com';`. `mock://` is required to ensure the window can not spoof actual `http://` or `https://` domains

### `getDomainFromUrl(url : string) => string`

Get the full domain from the specified url, as a string.

- it will try to extract the domain from the url string if it starts with well known protocols (`http://`, `https://`, `file://`, and additionally `mock://` urls)
- if url string does not contain a known protocol, it will try to extract the domain calling `getDomain` using the current window as input

### `getActualDomain(win : Window) => string`

Same as `getDomain` but overriding / mocking is disabled. it will return the real full domain of the specified window.

### `isBlankDomain(win : Window) => boolean`

Returns if the domain for the specified window is blank, or `about:blank`

- `win` must be a window on the same domain as the current window, or an exception will be raised
- `win` may be a window or iframe that has been newly opened by the current window

### `isSameDomain(win : Window) => boolean`

Returns if the specified window is on the same domain as the current window.

- Does so without raising any errors or console warnings, even in Safari where wrapping the check `try/catch` still raises a console warning.

### `getParent(win : Window) => ?Window`

Gets the parent of the specified window, if the window has a parent.

- Only returns the parent of iframes
- Returns void if the window is the top-level window

### `getOpener(win : Window) => ?Window`

Gets the opener of the specified window, if the window has an opener.

- Only returns the opener of windows opened with `window.open`
- Returns void if the window is the top-level window

### `getParents(win : Window) => Array<Window>`

Gets all of the hierarchical parents of the specified window.

- Only returns the parents of iframes
- Returns a blank array if the window is the top-level window

### `isAncestorParent(ancestor : Window, win : Window) => boolean`

Returns true if the `ancestor` is a direct or non-direct parent of the specified window.

### `getFrames(win : Window) => Array<Window>`

Returns an array of all direct child frames found in a given window.

- Only returns direct children

### `getAllChildFrames(win : Window) => Array<Window>`

Returns an array of all recursive child frames found in a given window, and in the child-frames of that window.

- Recursively searches for all direct and indirect children

### `getTop(win : Window) => Window`

Gets the top-level parent of the specified window.

### `getAllFramesInWindow(win : Window) => Array<Window>`

Returns an array of all recursive child frames found in a given window, and in the child-frames of that window, including the specified window.

- Recursively searches for all direct and indirect children

### `isTop(win : Window) => boolean`

Returns true if the specified window is the top level window, without any parents.

### `isFrameWindowClosed(frame : HTMLIFrameElement) => boolean`

Returns true if the window attached to an iframe element is closed, by checking if the frame is still attached to an open document.

- Prefer `isWindowClosed` when possible

### `isWindowClosed(win : Window) => boolean`

Returns true if a window has been closed

- In IE/Edge, this check is not 100% reliable for frame windows where the frame has been removed from the DOM. Such window objects give no indication that they are closed.

### `getUserAgent(win : Window) => string`

Gets the user agent for the specified window

- Window must be on the same domain as the current window
- Uses `win.navigator.mockUserAgent` if specified, to allow for mocking / tests.

### `getFrameByName(win : Window, name : string) => ?Window`

Gets a frame window with the given name, if it exists as a child of the specified window.

### `findChildFrameByName(win : Window, name : string) => ?Window`

Recursively searches for a given frame window inside the children specified window.

### `findFrameByName(win : Window, name : string) => ?Window`

Recursively searches for a given frame window inside the entire frame hierarchy of the specified window.

- Searches both the children and the parent windows recursively for the frame.

### `isParent(parent : Window, child : Window) => boolean`

Returns true if the specified parent window is the parent of the specified child window.

### `isOpener(opener : Window, child : Window) => boolean`

Returns true if the specified opener window is the opener of the specified child window.

### `getAncestor(win : Window) => ?Window`

Gets either the parent or the opener of the specified window, if either is present.

### `getAncestors(win : Window) => Array<Window>`

Recursively gets either the parent or the opener of the specified window, if either is present, and returns an array of the entire ancestor hierarchy.

### `isAncestor(ancestor : Window, child : Window) => boolean`

Returns true if the specified ancestor window is the parent or the opener of the specified child window.

### `isPopup(win : Window) => boolean`

Returns true if the specified window has been opened with `window.open` (i.e. if it is a popup window)

### `isIframe(win : Window) => boolean`

Returns true if the specified window has been opened as an iframe.

### `getDistanceFromTop(win : Window) => number`

Gets the numerical distance from the specified window to the top level window in that window's hierarchy.

- If the specified window is at the top, this will return 0.

### `getNthParent(win : Window, n : number) => ?Window`

Gets the window `n` levels up from the specified window, if it exists.

### `isSameTopWindow(win1 : window, win2 : Window) => boolean`

Returns true if the windows are in the same hierarchy, with the same top level window

- Will return false if one of the windows is a popup and the other window is not a frame inside that popup.

### `isWindow(obj : Window) => boolean`

Returns true if the specified object is a window instance

### `onCloseWindow(win : Window, callback : Function, interval : number) => { cancel : Function }`

Calls the callback when the specified window closes, with checks running on the specified interval.

- Returns a listener object with a `.cancel()` method, to stop the loop

### `matchDomain(pattern : (string | RegExp | Array<string>), domain : string) => boolean`

Returns true if the specified domain matches the pattern. The pattern can be one of:

- A literal string
- A regular expression
- An array of possible domains as strings

# Tasks

All of the tasks are listed in the package.json file under the scripts section

| Command       |               Description                |
| ------------- | :--------------------------------------: |
| npm run build |          Builds the dist files           |
| npm test      | Runs the test suite. Lint + Type + Karma |

# Debugging

Run the debug task and pass the next tasks as argument.

```
npm run debug -- npm run build
npm run debug -- npm test
npm run debug -- npm run karma -- --browsers=Chrome
```