Window Open Promise Reference

🪟 Promised Window.open();.

Usage

📦 Node

Install window-open-promise as a dependency:

pnpm add window-open-promise
# or
npm install window-open-promise
# or
yarn add window-open-promise

Import it and use it:

import { windowOpenPromise } from "window-open-promise";

const windowOpen = windowOpenPromise(globalThis);

windowOpen({
	url: "https://example.com", // URL is not required, you can open a blank window
	top: 10,
	left: 10,
})
	.then(newWindow => {
		newWindow.console.log("This will log in the new window.");
		newWindow.addEventListener("beforeunload", _event => {
			console.log("This will log when the new window is closed.");
		});
	})
	.catch(_error => {
		console.error("This will log if the new window can't be opened.");
	});

🦕 Deno

Import window-open-promise using the npm: prefix, and use it directly:

import { windowOpenPromise } from "npm:window-open-promise";

const windowOpen = windowOpenPromise(globalThis);

try {
	const newWindow = await windowOpen({
		url: "https://example.com", // URL is not required, you can open a blank window
		top: 10,
		left: 10,
	});
	newWindow.console.log("This will log in the new window.");
	newWindow.addEventListener("beforeunload", _event => {
		console.log("This will log when the new window is closed.");
	});
} catch (_error) {
	console.error("This will log if the new window can't be opened.");
}

🌎 Browser

Import window-open-promise using esm.sh, and use it directly:

<script type="module">
	import { windowOpenPromise } from "https://esm.sh/window-open-promise";

	const windowOpen = windowOpenPromise(globalThis);

	try {
		const newWindow = await windowOpen({
			url: "https://example.com", // URL is not required, you can open a blank window
			top: 10,
			left: 10,
		});
		newWindow.console.log("This will log in the new window.");
		newWindow.addEventListener("beforeunload", _event => {
			console.log("This will log when the new window is closed.");
		});
	} catch (_error) {
		console.error("This will log if the new window can't be opened.");
	}
</script>

Useful links

• 📝 Documentation: TypeDoc generated documentation.
• ⏳ Changelog: List of changes between versions.
• ✅ Tests Coverage: Coveralls page with tests coverage.

Type Aliases

WindowOpenPromiseFeatures

type WindowOpenPromiseFeatures: Omit<WindowOpenPromiseOptions, "replace" | "target" | "url">;

WindowOpenPromise features.

---

WindowOpenPromiseOptions

type WindowOpenPromiseOptions: object;

WindowOpenPromise options.

Type declaration

Member	Type	Description
height	number	WindowOpenPromise height (minimum 100).
left	number	WindowOpenPromise left position.
menuBar	boolean	WindowOpenPromise renders the menu bar.
noOpener	boolean	WindowOpenPromise can’t access it’s opener.
resizable	boolean	WindowOpenPromise is resizable.
scrollbars	boolean	WindowOpenPromise has scrollbars.
target	string	WindowOpenPromise target.
titleBar	boolean	WindowOpenPromise renders the title bar.
toolBar	boolean	WindowOpenPromise renders the tool bar.
top	number	WindowOpenPromise top position.
url	string	WindowOpenPromise url.
width	number	WindowOpenPromise width (minimum 100).

Functions

featureJoin()

function featureJoin<Item>(iterable: Readonly<Iterable<Item>>): string;

Joins given array of features with the FEATURE_SEPARATOR.

Type parameters

Type parameter
Item extends Strigifiable

Parameters

Parameter	Type
iterable	Readonly<Iterable<Item>>

Returns

string

Joint string.

Example

featureJoin(["top=10", "left=10", "resizable=1"]); // "top=10,left=10,resizable=1"

---

featureMap()

function featureMap(
	iterable: Readonly<Iterable<EntryOf<WindowOpenPromiseFeatures>>>,
): Readonly<IterableIterator<string>>;

Maps array of feature entries to valid values.

Parameters

Parameter	Type
iterable	Readonly<Iterable<EntryOf<WindowOpenPromiseFeatures>>>

Returns

Readonly<IterableIterator<string>>

Array of formatted features.

Example

featureMap([
	["top", "10"],
	["left", "10"],
	["resizable", true],
]); // ["top=10", "left=10", "resizable=1"]

---

featureParser()

function featureParser(features?: WindowOpenPromiseFeatures): string;

Parses features object into features string.

Parameters

Parameter	Type	Description
features?	WindowOpenPromiseFeatures	Features object.

Returns

string

Parsed string.

Example

featureParser({
	top: 10,
	left: 10,
	resizable: true,
}); // "top=10,left=10,resizable=1"

---

featureValueMapper()

function featureValueMapper(value: unknown): number;

Takes a feature value and returns a formatted feature value.

Parameters

Parameter	Type
value	unknown

Returns

number

Feature value.

Example

featureValueMapper(true); // 1
featureValueMapper(false); // 0
featureValueMapper(13); // 13

---

windowOpenPromise()

function windowOpenPromise(
	global: Readonly<Pick<Window, "open">>,
): (options: WindowOpenPromiseOptions) => object;

Promised Window.open.

Parameters

Parameter	Type
global	Readonly<Pick<Window, "open">>

Returns

Function

Curried function with window in context.

Curried function with window set.

Parameters

Parameter	Type	Default value	Description
options	WindowOpenPromiseOptions	EMPTY_OBJECT	WindowOpenPromise options.

Returns

object

Promise with new window.

Member	Type	Description
catch	<RejectedValue_1>(this: void, onrejected?: Unary<unknown, RejectedValue_1 | PromiseLike<RejectedValue_1>>) => Promise<Window | RejectedValue_1>	See Promise#then
then	<ResolvedValue, RejectedValue>(this: void, onResolved?: Unary<Window, ResolvedValue | PromiseLike<ResolvedValue>>, onRejected?: Unary<unknown, RejectedValue | PromiseLike<RejectedValue>>) => Promise<ResolvedValue | RejectedValue>	See Promise#then

Example

const windowOpen = windowOpenPromise(window);
windowOpen({
	url: "https://example.com",
	top: 10,
	left: 10,
})
	.then(newWindow => {
		newWindow.console.log("This will log in the new window.");
		newWindow.addEventListener("beforeunload", _event => {
			console.log("This will log when the new window is closed.");
		});
	})
	.catch(_error => {
		console.error("This will log if the new window can't be opened.");
	});

Example

const windowOpen = windowOpenPromise(window);
windowOpen({
	url: "https://example.com",
	top: 10,
	left: 10,
})
	.then(newWindow => {
		newWindow.console.log("This will log in the new window.");
		newWindow.addEventListener("beforeunload", _event => {
			console.log("This will log when the new window is closed.");
		});
	})
	.catch(_error => {
		console.error("This will log if the new window can't be opened.");
	});