tessl/npm-intlify--shared

Shared utility package for intlify project providing performance tools, string formatting, event emitters, and type checking utilities.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Environment & Performance

Name: tessl/npm-intlify--shared
Author: tessl

Environment detection and performance measurement utilities for cross-platform development and debugging.

Capabilities

Environment Detection

Detect the runtime environment and access global objects safely.

/**
 * Boolean indicating if code is running in a browser environment
 */
const inBrowser: boolean;

/**
 * Get the global this object safely across environments
 * @returns Global object (globalThis/window/global/self)
 */
function getGlobalThis(): any;

Usage Examples:

import { inBrowser, getGlobalThis } from "@intlify/shared";

// Environment-specific code
if (inBrowser) {
  // Browser-only code
  console.log("Running in browser");
  const userAgent = navigator.userAgent;
} else {
  // Node.js or other environment
  console.log("Running in non-browser environment");
}

// Access global object safely
const globalObj = getGlobalThis();
if (inBrowser) {
  // globalObj is window in browser
  console.log(globalObj.location?.href);
} else {
  // globalObj is global in Node.js
  console.log(globalObj.process?.version);
}

Performance Measurement

Performance marking and measurement utilities for development debugging.

/**
 * Performance marking function (development mode only)
 * Undefined in production builds
 */
let mark: (tag: string) => void | undefined;

/**
 * Performance measurement function (development mode only)
 * Undefined in production builds
 * @param name - Measurement name
 * @param startTag - Start mark tag
 * @param endTag - End mark tag
 */
let measure: (
  name: string,
  startTag: string,
  endTag: string
) => void | undefined;

Usage Examples:

import { mark, measure } from "@intlify/shared";

// Performance measurement in development
function performHeavyOperation() {
  // Mark start of operation
  mark?.("heavy-operation-start");
  
  // Perform the operation
  doSomeHeavyWork();
  
  // Mark end of operation
  mark?.("heavy-operation-end");
  
  // Measure the duration
  measure?.("heavy-operation", "heavy-operation-start", "heavy-operation-end");
}

// Conditional usage with type safety
if (mark && measure) {
  mark("initialization-start");
  initializeApp();
  mark("initialization-end");
  measure("app-initialization", "initialization-start", "initialization-end");
}

Development Environment

The performance utilities are only available in development mode (__DEV__ is true) and when running in a browser environment with performance API support.

Behavior:

In development: Functions use browser Performance API if available
In production: Functions are undefined (tree-shaken out)
In non-browser environments: Functions are undefined

Performance API Requirements:

Browser must support window.performance
Must have mark, measure, clearMarks, and clearMeasures methods

Environment Detection Details

Browser Detection

The inBrowser constant is determined at module load time:

// Simplified implementation
const inBrowser = typeof window !== 'undefined';

This provides a reliable way to detect browser environments for:

Conditional imports
Platform-specific functionality
Feature detection

Global Object Access

The getGlobalThis function provides a unified way to access the global object across different JavaScript environments:

Resolution Order:

globalThis (modern standard)
self (Web Workers, Service Workers)
window (browsers)
global (Node.js)
Empty object fallback

Usage Scenarios:

import { getGlobalThis, inBrowser } from "@intlify/shared";

const globalObj = getGlobalThis();

// Safe global variable access
function setGlobalVariable(key: string, value: any) {
  globalObj[key] = value;
}

function getGlobalVariable(key: string) {
  return globalObj[key];
}

// Environment-specific global access
if (inBrowser) {
  // Access browser-specific globals
  const location = globalObj.location;
  const document = globalObj.document;
} else {
  // Access Node.js-specific globals
  const process = globalObj.process;
  const buffer = globalObj.Buffer;
}

Performance Monitoring Best Practices

Development Usage

import { mark, measure } from "@intlify/shared";

// Mark important application lifecycle events
function trackLifecycle() {
  mark?.("app-mount-start");
  mountApplication();
  mark?.("app-mount-end");
  
  mark?.("data-load-start");
  loadInitialData();
  mark?.("data-load-end");
  
  // Measure durations
  measure?.("app-mount-duration", "app-mount-start", "app-mount-end");
  measure?.("data-load-duration", "data-load-start", "data-load-end");
}

Production Considerations

In production builds, performance utilities are undefined to:

Reduce bundle size
Eliminate runtime overhead
Remove development-only code

Always use optional chaining or conditional checks:

// Recommended: Optional chaining
mark?.("operation-start");

// Alternative: Conditional check
if (mark) {
  mark("operation-start");
}

docs

environment-performance.md

tessl/npm-intlify--shared