or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-globalthis

ECMAScript spec-compliant polyfill/shim for `globalThis`

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/globalthis@1.0.x

To install, run

npx @tessl/cli install tessl/npm-globalthis@1.0.0

index.mddocs/

globalthis

An ECMAScript spec-compliant polyfill/shim for globalThis that provides consistent access to the global object across different JavaScript environments including Node.js, browsers, and Web Workers. It implements the es-shim API interface and works in ES3-supported environments while complying with the TC39 proposal specification.

Package Information

  • Package Name: globalthis
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install globalthis

Core Imports

var globalThis = require('globalthis')();

ES6 modules:

import getGlobal from 'globalthis';
const globalThis = getGlobal();

Basic Usage

var globalThis = require('globalthis')();

// Access global properties consistently across environments
console.log(globalThis.Math === Math); // true
console.log(globalThis.Array === Array); // true

// Set global variables
globalThis.myGlobalVar = 'Hello World';

// In browsers, globalThis === window
// In Node.js, globalThis === global  
// In Web Workers, globalThis === self

Architecture

The globalthis package follows the standard es-shim API pattern:

  • Main Function: Returns the polyfilled global object with utility methods attached
  • Polyfill Function: Returns native global object if available and compliant, otherwise returns implementation
  • Shim Function: Modifies the global object to add/fix the globalThis property
  • Implementation: Direct access to the platform-specific global object
  • Auto-shim: Side-effect module that automatically applies the shim when imported

The package provides both Node.js and browser implementations, automatically selecting the appropriate one based on the environment.

Capabilities

Main Export Function

Returns the global object, with utility methods attached as properties.

/**
 * Returns the global object (native globalThis if compliant, otherwise polyfill)
 * @returns {Object} The global object
 */
function getGlobal(): Object;

// Attached properties:
getGlobal.getPolyfill: function getPolyfill(): Object;
getGlobal.implementation: Object;
getGlobal.shim: function shimGlobal(): Object;

Usage Examples:

// Standard usage - returns global object
var globalThis = require('globalthis')();

// Access attached utility methods
var globalThis = require('globalthis');
var polyfill = globalThis.getPolyfill();
var shim = globalThis.shim();

Polyfill Function

Returns native global object if available and compliant (in Node.js: global, in browsers: varies), otherwise returns the implementation.

/**
 * Returns native global object if compliant, otherwise returns implementation  
 * @returns {Object} The global object (global in Node.js, window/self in browsers)
 */
function getPolyfill(): Object;

Usage Examples:

// Direct polyfill usage
var globalThis = require('globalthis/polyfill')();

// Check if native global object is being used
var polyfill = require('globalthis/polyfill');
var global = polyfill();
// Will be native global object if available and compliant

Shim Function

Applies the globalThis property to the global object if not present or non-compliant, then returns the global object.

/**
 * Applies globalThis property to global object and returns it
 * @returns {Object} The shimmed global object
 */
function shimGlobal(): Object;

Usage Examples:

// Apply shim and get global object
var globalThis = require('globalthis/shim')();

// Verify globalThis property is now available
console.log(globalThis.globalThis === globalThis); // true

Auto-shim Module

Side-effect module that automatically applies the shim when required. Does not export anything.

// No exports - side-effect only
// Automatically calls shim() when imported

Usage Examples:

// Simply require to apply shim automatically
require('globalthis/auto');

// globalThis is now available globally
console.log(typeof globalThis); // 'object'

Direct Implementation

Direct access to the platform-specific global object implementation.

/**
 * Direct reference to the global object implementation
 * - Node.js: global object
 * - Browser: self, window, or Function('return this')() fallback
 */
const implementation: Object;

Usage Examples:

// Direct access to implementation
var globalThis = require('globalthis/implementation');

// This is the raw global object for the current environment
console.log(globalThis === global); // true in Node.js

Types

/**
 * Global object type - standard ECMAScript global object
 * Contains all built-in properties: Math, JSON, String, Array, etc.
 */
interface GlobalObject {
  Math: Math;
  JSON: JSON; 
  String: StringConstructor;
  Array: ArrayConstructor;
  Number: NumberConstructor;
  Boolean: BooleanConstructor;
  Object: ObjectConstructor;
  Function: FunctionConstructor;
  Date: DateConstructor;
  RegExp: RegExpConstructor;
  Symbol?: SymbolConstructor;
  globalThis?: GlobalObject;
  // Plus all other global properties and user-defined globals
  [key: string]: any;
}

Environment Compatibility

  • Node.js: Uses the global object
  • Browsers: Uses self, window, or Function('return this')() fallback
  • Web Workers: Uses self object
  • Universal: Works in all ES3+ supported environments
  • CSP Compliant: Browser implementation uses CSP-safe global object detection where possible

Error Handling

The package is designed to be robust and should not throw errors under normal usage. All functions return the global object, and the shim gracefully handles cases where property descriptors are not supported or globalThis already exists.