@skbkontur/global-object

@skbkontur/global-object

Кросс-платформенный глобальный объект с безопасной типизацией и возможностью подмены window.

Полезен в коде, который может выполнятся как в браузере, так и в nodejs, вместо использования window, global или их полей как глобальных сущностей напрямую. В отличии от globalThis более безопасно типизирован. Все поля globalObject соответствуют полям globalThis, но имеют в типе undefined и требуют явной проверки перед использованием.

import { globalObject, isBrowser, isInstanceOf } from '@skbkontur/global-object';

// было
requestAnamtionFrame();
// стало
globalObject.requestAnimationFrame?.();

// было
clearTimeout();
// стало
globalObject.clearTimeout();

// было
typeof HTMLElement !== 'undefined' && node instanceof HTMLElement
// стало
isInstanceOf(node, globalObject.HTMLElement)

// было
typeof window !== 'undefined' && window.location.host
// стало
globalObject.location?.host

// было
document.addEventListener('load', () => console.log(window.clientHeight));
// стало
if (isBrowser(globalObject)) {
  globalObject.document.addEventListener('load', () => console.log(globalObject.clientHeight));
}

Хелпер isBrowser(globalObject) позволяет убедиться, что код выполняется в браузере и избавляет от необходимости проверять на существование в globalObject полей интерфейса Window.

import { globalObject, isBrowser } from '@skbkontur/global-object';

// было
globalObject.addEventListener?.('load', () => console.log((globalObject.clientHeight || 0) + 1));
// стало
if (isBrowser(globalObject)) {
  globalObject.document.addEventListener('load', () => console.log(globalObject.clientHeight));
}

Также имеется возможность переопределить window. Может быть полезно при разработке изолированных виджетов.

import { setWindow } from '@skbkontur/global-object';

setWindow(window.parent);

Подмена window должна осуществляться один раз и как можно раньше в приложении, до загрузки всех модулей, которые используют @skbkontur/global-object. Подмена в рантайме, в произвольный момент времени не подразумевается. Иначе результат может отличаться от ожидаемого.