@krakenjs/cross-domain-utils

Cross Domain Utils

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

Changelog

3.1.0 (2023-06-12)

Features

• grumbler-scripts@8 (#38) (5197ff3)

Bug Fixes

• type: domain matcher (5b6724d)

• add badges to readme (#27) (c61aa24)

• add coverage with codecov (#31) (a71904e)

• commit dist folder when releasing (#34) (7e7bf54)

• deps: use grumbler-scripts v5 (#29) (c1038b8)

• docs: update github actions badge url (6b8d5a7)

• fix build badge (d66a149)

• move devDependencies to @krakenjs scope (a5e9c68)

• move devDependencies to @krakenjs scope (f00a02d)

• remove quotes from publish (58c55aa)

• remove token from publish action (3c51659)

• update changelog generation to include all types (97c0ab6)

• update package description (1ccd651)

• use 'npm prepare' for husky (#32) (d5d9cbe)

• use prettier for code formatting (77561d8)