⚡ @zappzarapp/browser-utils

Zero-dependency browser utilities with security-first design — type-safe, tree-shakeable, and fully tested.

Highlights

• All-in-one — 39 browser modules in a single, tree-shakeable package
• Type-safe — strict TypeScript with generics throughout
• Zero dependencies — no runtime dependencies
• Secure by default — cryptographic randomness, input validation, XSS prevention
• Dual error handling — throwing and Result-based APIs
• Quality-backed — 4800+ tests, strict ESLint, 99%+ coverage

Modules

Storage & Data

Module	Key Classes	Description
storage	StorageManager	localStorage with LRU eviction
session	SessionStorageManager	sessionStorage wrapper
cookie	CookieManager	Secure cookie management
indexeddb	IndexedDBManager	IndexedDB async wrapper
cache	CacheManager	HTTP-style stale-while-revalidate
encryption	EncryptedStorage	AES-GCM with PBKDF2

DOM & UI

Module	Key Classes	Description
html	DomHelper, HtmlEscaper	DOM helpers, HTML escaping
focus	FocusTrap	Focus trapping for modals
scroll	ScrollManager	Scroll utilities and locking
fullscreen	FullscreenManager	Fullscreen API wrapper
form	FormValidator, FormSerializer	Validation and serialization

Events & Input

Module	Key Classes	Description
events	EventDelegator, debounce, throttle	Event delegation and timing
keyboard	ShortcutManager	Keyboard shortcuts
idle	IdleCallback	requestIdleCallback wrapper

Observers

Module	Key Classes	Description
observe	IntersectionObserverWrapper, ResizeObserverWrapper	Intersection, Resize, Mutation

Network & Communication

Module	Key Classes	Description
network	RetryQueue, NetworkStatus	Retry queue with backoff
offline	OfflineQueue	IndexedDB-backed offline sync
websocket	WebSocketManager	Auto-reconnect + SSE/polling fallback
request	RequestInterceptor	Fetch middleware, auth, retry, dedupe
url	UrlBuilder	URL building, query params
broadcast	BroadcastManager	Cross-tab messaging
share	ShareManager	Web Share API with clipboard fallback

Device & Environment

Module	Key Classes	Description
device	DeviceInfo	Device detection
features	FeatureDetect	Browser feature detection
media	MediaQuery	Media queries, breakpoints
visibility	VisibilityManager	Page Visibility API
geolocation	GeolocationManager	Geolocation API wrapper
performance	PerformanceMonitor	Core Web Vitals monitoring
wakelock	WakeLock	Screen Wake Lock API

Security

Module	Key Classes	Description
csp	CspDetector	CSP detection and helpers
sanitize	HtmlSanitizer	HTML sanitization
clipboard	ClipboardManager	Secure clipboard access

Utility

Module	Key Classes	Description
color	parseColor, contrastRatio, mix	Color parse/convert/contrast
intl	formatNumber, formatDate, resolveLocale	Intl formatting + locale negotiation
logging	Logger	Console logging with levels
notification	NotificationManager	Browser notifications
download	FileDownload	File download triggers
a11y	AriaUtils, LiveAnnouncer, SkipLink	Accessibility utilities
core	Result, Validator, debounce	Types, errors, validation

Requirements

• Node.js >= 22
• ESM-only — cannot be require()'d from CommonJS

Installation

npm install @zappzarapp/browser-utils
# or
pnpm add @zappzarapp/browser-utils

Quick Start

Storage Manager

import { StorageManager } from '@zappzarapp/browser-utils/storage';

interface UserData {
  id: string;
  name: string;
}

const storage = StorageManager.create<UserData>({
  prefix: 'myApp',
  maxEntries: 100,
});

storage.set('user-1', { id: '1', name: 'Alice' });
const user = storage.get('user-1');

Keyboard Shortcuts

import {
  ShortcutManager,
  KeyboardShortcut,
} from '@zappzarapp/browser-utils/keyboard';

// Single shortcut — returns a cleanup function
const cleanup = ShortcutManager.on(KeyboardShortcut.ctrlKey('s'), () =>
  saveDocument()
);

// App-wide surface: bare keys skipped while typing, one undo/redo per platform
const shortcuts = ShortcutManager.createGroup({ ignoreEditableTargets: true });
shortcuts
  .add(KeyboardShortcut.cmdOrCtrl('z'), undo)
  .add(KeyboardShortcut.key('r'), () => (hasSelection() ? rotate() : false));

cleanup();
shortcuts.cleanup();

Network Retry Queue

import { RetryQueue } from '@zappzarapp/browser-utils/network';

const queue = RetryQueue.create({
  maxRetries: 3,
  backoff: 'exponential',
  networkAware: true,
});

const result = await queue.add(() => fetch('/api/data').then((r) => r.json()));

Automatic Request Retry

import { RequestInterceptor } from '@zappzarapp/browser-utils/request';

// Opt-in retry for idempotent requests with exponential backoff;
// Retry-After response headers are honored (capped at maxDelay)
const api = RequestInterceptor.create({
  baseUrl: 'https://api.example.com',
  retry: { maxRetries: 3 },
});

Lazy Loading with Observers

import { IntersectionObserverWrapper } from '@zappzarapp/browser-utils/observe';

const cleanup = IntersectionObserverWrapper.lazyLoad(
  document.querySelectorAll('img[data-src]'),
  (img) => {
    img.src = img.dataset.src!;
  }
);

Documentation

Module	Module
a11y	intl
broadcast	keyboard
cache	logging
clipboard	media
color	network
cookie	notification
core	observe
csp	offline
device	performance
download	request
encryption	sanitize
events	scroll
features	session
focus	share
form	storage
fullscreen	url
geolocation	visibility
html	wakelock
idle	websocket
indexeddb	glossary

Recipes: Offline-First App · Secure File Upload · Accessible Form · Resilient API Client · Real-Time Data Sync · Progressive Enhancement

Guides: Browser Support · Error Handling · Security Guide · Benchmarks

Generate API docs locally with pnpm run docs.

Versioning

This project follows Semantic Versioning.

Security

See SECURITY.md for vulnerability disclosure policy and supported versions.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT