CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-vue--shared

Internal utility functions shared across Vue.js packages for DOM manipulation, type checking, and general utilities

Pending
Overview
Eval results
Files

environment-utilities.mddocs/

Environment and Global Access

Cross-environment utilities for accessing global objects, handling platform differences, and managing allowed global variables in Vue templates.

Capabilities

Global Object Access

Functions for safely accessing the global object across different JavaScript environments.

/**
 * Get the global object in a cross-environment way
 * Handles globalThis, self, window, global, and fallback cases
 * @returns The global object for the current environment
 */
function getGlobalThis(): any;

Global Variable Allowlist

Functions for controlling which global variables can be accessed in Vue templates for security.

/**
 * Check if a global variable name is allowed in Vue templates
 * Prevents access to potentially dangerous globals
 * @param key - Global variable name to check
 * @returns True if the global is safe to access
 */
function isGloballyAllowed(key: string): boolean;

/**
 * @deprecated Use isGloballyAllowed instead
 * Legacy name for isGloballyAllowed function
 */
function isGloballyWhitelisted(key: string): boolean;

Utility Functions

Additional environment-related utilities.

/**
 * Create a map-based lookup function from comma-separated string
 * Used internally for creating fast lookup functions
 * @param str - Comma-separated string of keys
 * @returns Function that checks if key exists in the map
 */
function makeMap(str: string): (key: string) => boolean;

Usage Examples:

import { 
  getGlobalThis, 
  isGloballyAllowed, 
  isGloballyWhitelisted,
  makeMap 
} from "@vue/shared";

// Global object access across environments
const globalObj = getGlobalThis();

// In browser environment
if (typeof window !== 'undefined') {
  console.log(globalObj === window); // true
}

// In Node.js environment  
if (typeof global !== 'undefined') {
  console.log(globalObj === global); // true
}

// In Web Worker environment
if (typeof self !== 'undefined') {
  console.log(globalObj === self); // true
}

// Modern environments with globalThis
if (typeof globalThis !== 'undefined') {
  console.log(globalObj === globalThis); // true
}

// Global variable allowlist checking
console.log(isGloballyAllowed("Math")); // true - Math is allowed
console.log(isGloballyAllowed("console")); // true - console is allowed  
console.log(isGloballyAllowed("Date")); // true - Date is allowed
console.log(isGloballyAllowed("Array")); // true - Array is allowed
console.log(isGloballyAllowed("Object")); // true - Object is allowed

// Security - potentially dangerous globals are blocked
console.log(isGloballyAllowed("eval")); // false - eval is not allowed
console.log(isGloballyAllowed("Function")); // false - Function constructor blocked
console.log(isGloballyAllowed("window")); // false - direct window access blocked
console.log(isGloballyAllowed("document")); // false - document access blocked
console.log(isGloballyAllowed("localStorage")); // false - localStorage blocked

// Template usage simulation
function evaluateTemplateExpression(expr: string, globals: Record<string, any>) {
  // Check if global variables in expression are allowed
  const globalRefs = extractGlobalReferences(expr); // hypothetical function
  
  for (const ref of globalRefs) {
    if (!isGloballyAllowed(ref)) {
      throw new Error(`Global '${ref}' is not allowed in templates`);
    }
  }
  
  // Safe to evaluate expression
  return evaluateExpression(expr, globals);
}

// Legacy function (deprecated)
console.log(isGloballyWhitelisted("Math")); // true - same as isGloballyAllowed
// Note: This function is deprecated, use isGloballyAllowed instead

// Creating custom lookup maps
const allowedProps = makeMap("id,class,style,title,alt");
console.log(allowedProps("class")); // true
console.log(allowedProps("onclick")); // false

const htmlTags = makeMap("div,span,p,h1,h2,h3,button,input");
console.log(htmlTags("div")); // true
console.log(htmlTags("custom-element")); // false

Allowed Global Variables

The following global variables are permitted in Vue templates:

JavaScript Built-ins:

  • Infinity, undefined, NaN
  • isFinite, isNaN, parseFloat, parseInt
  • decodeURI, decodeURIComponent, encodeURI, encodeURIComponent

Standard Objects:

  • Math, Number, Date, Array, Object, Boolean, String, RegExp
  • Map, Set, JSON, Intl, BigInt

Debugging:

  • console, Error

Symbols:

  • Symbol

Security Rationale

The allowlist prevents template injection attacks by blocking access to:

  • Code Execution: eval, Function, setTimeout, setInterval
  • DOM Access: window, document, location
  • Storage: localStorage, sessionStorage, indexedDB
  • Network: fetch, XMLHttpRequest, WebSocket
  • Node.js Globals: process, require, module, exports

Environment Detection Patterns

// Safe global access pattern
const global = getGlobalThis();

// Feature detection
if ('fetch' in global) {
  // Fetch API available
}

if ('process' in global && global.process?.env) {
  // Node.js environment
}

// Environment-specific setup
function setupEnvironment() {
  const global = getGlobalThis();
  
  if (typeof window !== 'undefined') {
    // Browser environment
    setupBrowser(global);
  } else if (typeof global.process !== 'undefined') {
    // Node.js environment  
    setupNode(global);
  } else {
    // Other environment (Web Worker, etc.)
    setupGeneric(global);
  }
}

Performance Characteristics

  • getGlobalThis: Cached after first call - subsequent calls return cached value
  • isGloballyAllowed: O(1) lookup using internal map created by makeMap
  • makeMap: Creates optimized lookup with Object.create(null) for fast property access

Integration with Vue

These utilities enable Vue's secure template system:

  • Template Compilation: Global references are validated against the allowlist
  • Expression Evaluation: Only safe globals can be accessed in template expressions
  • SSR Compatibility: Works across server and client environments
  • Development Tools: Global access provides platform-specific debugging capabilities

Install with Tessl CLI

npx tessl i tessl/npm-vue--shared

docs

display-utilities.md

dom-configuration.md

environment-utilities.md

equality-utilities.md

html-security.md

index.md

normalization.md

object-utilities.md

reactive-flags.md

string-transformations.md

type-checking.md

tile.json