Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/krakenjs/cross-domain-utils

Cross Domain utilities
https://github.com/krakenjs/cross-domain-utils

hacktoberfest

Last synced: 3 days ago
JSON representation

Cross Domain utilities

Awesome Lists containing this project

README 

        
## 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`



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`



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



- Only returns direct children



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



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`



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`



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), 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

```