⚡ @zappzarapp/browser-utils

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

Highlights

• All-in-one — 35 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 — 3950+ tests, strict ESLint, full 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	WebSocket with auto-reconnect
request	RequestInterceptor	Fetch middleware and auth
url	UrlBuilder	URL building, query params
broadcast	BroadcastManager	Cross-tab messaging

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

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
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 >= 20
• 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 } from '@zappzarapp/browser-utils/keyboard';

const shortcuts = ShortcutManager.create();

shortcuts.register({
  key: 's',
  ctrlKey: true,
  handler: () => saveDocument(),
});

shortcuts.destroy();

Network Retry Queue

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

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

const result = await queue.add({
  operation: () => fetch('/api/data').then((r) => r.json()),
});

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	keyboard
broadcast	logging
cache	media
clipboard	network
cookie	notification
core	observe
csp	offline
device	performance
download	request
encryption	sanitize
events	scroll
features	session
focus	storage
form	url
fullscreen	visibility
geolocation	websocket
idle	glossary

Guides: Browser Support · Error Handling · Security Guide

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