⚡ @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