cross-domain-utils

cross-domain-utils

Window and origin helpers for code that talks across frames and popups.

npm install cross-domain-utils

import { getOpener, getParent, isSameDomain, isWindowClosed, matchDomain } from 'cross-domain-utils';

const ancestor = getOpener() ?? getParent();          // who put this window here
if (ancestor && !isWindowClosed(ancestor)) { ... }

isSameDomain(someFrame);                                // may I read it
matchDomain([ 'https://a.com', /\.b\.com$/u ], origin); // does this origin fit

ES modules, TypeScript types included, no dependencies, ES2019 syntax. For current browsers: nothing here exists to work around an old one.

What's here

Every function takes a Window, from any origin, and never throws on one it can't look inside; reads the browser allows across origins (parent, top, opener, closed, frames, length, named child frames, self) are used directly, and the ones it doesn't (location, name, document) are behind isSameDomain.

Where a window sits

Function	Gives
getParent(win?), getParents(win)	The parent frame, or every ancestor frame, none for a top
getOpener(win?)	The window that opened a popup; never set for an iframe
getAncestor(win?), getAncestors(win)	Opener for a popup, parent for a frame, and so on up
getTop(win?), isTop(win)	The top of a frame tree
getNextOpener(win?), getUltimateTop(win?)	Across popup chains: the top's opener, and the top nothing opened
isIframe(win?), isPopup(win?), isFullpage(win?), getWindowType(win?)	What kind of window it is
getDistanceFromTop(win?), getNthParent(win, n?), getNthParentFromTop(win, n?)	Position in the frame tree
isParent(win, frame), isOpener(parent, child), isAncestor(parent, child), isSameTopWindow(a, b)	Relationships

Frames

Function	Gives
getFrames(win), getAllChildFrames(win)	Direct children, or the whole subtree
getAllFramesInWindow(win), getAllWindows(win?)	Every frame in the tree, and every frame up the opener chain
getFrameByName(win, name), findChildFrameByName(win, name), findFrameByName(win, name)	By name: a direct child, anywhere below, anywhere in the tree
getFrameForWindow(win)	The <iframe> element for a window in this document

Lifetime

Function	Gives
isWindowClosed(win), isFrameWindowClosed(frame)	Closed, or removed from the page
onCloseWindow({ win, callback, delay?, maxtime? })	Poll until it closes; returns { cancel }
closeWindow(win)	Removes an iframe, closes a popup

Origins

Function	Gives
getDomain(win?)	https://host:port, file://, or a blank frame's inherited origin
isSameDomain(win), assertSameDomain(win), canReadFromWindow(win)	May this side read it
matchDomain(pattern, origin), stringifyDomainPattern(pattern)	A DomainMatcher is a string, a RegExp, a list of either, or *
getDomainFromUrl(url), isCurrentDomain(domain), isBrowser()	Odds and ends
getProtocol(win?), isFileProtocol(win?), isAboutProtocol(win?), isBlankDomain(win)	Protocol checks

Other

Function	Gives
isWindow(value)	Whether a value is a window, of any origin
submitForm({ url, target, method?, body? })	Navigate a named window by form submission, the only way to POST into one

Constants: WILDCARD, PROTOCOL, WINDOW_TYPE. Types: DomainMatcher, WindowType, and CrossDomainWindowType / SameDomainWindowType as aliases of Window for code written against earlier versions.

Changes in 4.0

Published as cross-domain-utils again (3.x lived under @krakenjs). ES modules and TypeScript only. Gone, because no supported browser needs them: the Internet Explorer error-message checks, user-agent sniffing (getUserAgent), the orphaned-iframe tracking (linkFrameWindow), the mock:// domain machinery for tests (isMockDomain, normalizeMockUrl, mockDomain, mockclosed, mockUserAgent), the window.constructor and property-descriptor tricks, and the separate getActualDomain / isActuallySameDomain (the plain functions now do what those did). isSameDomain is now simply "can this side read the window's location", which is the rule browsers enforce. getTop and isSameTopWindow no longer search child frames as a fallback. submitForm moved here from belter. The test suite runs against real same-origin, cross-origin and nested frames and real popups.

License

Apache-2.0