@bernierllc/validators-utils

Shared utilities for the BernierLLC validators ecosystem. This package provides parsing, DOM manipulation, color analysis, URL handling, file operations, and HTTP utilities used across all validators.

Installation

npm install @bernierllc/validators-utils

Usage

DOM Utilities

import { parseHtml } from '@bernierllc/validators-utils';

const doc = parseHtml('<div class="content">Hello World</div>');
if (doc) {
  const element = doc.querySelector('.content');
  const text = element?.textContent;
  console.log(text); // "Hello World"
}

Color Analysis

import { parseColor, getContrastRatio, meetsWCAGContrastRequirement } from '@bernierllc/validators-utils';

const foreground = parseColor('#ffffff');
const background = parseColor('#000000');
const ratio = getContrastRatio('#ffffff', '#000000');
const wcagAA = meetsWCAGContrastRequirement(ratio, 'AA', 'normal');

console.log(ratio); // 21
console.log(wcagAA); // true

URL Validation

import { isValidUrl, resolveUrl, isDangerousProtocol } from '@bernierllc/validators-utils';

console.log(isValidUrl('https://example.com')); // true
console.log(isDangerousProtocol('javascript:alert(1)')); // true
console.log(resolveUrl('https://example.com/', './page.html')); // "https://example.com/page.html"

File Operations

import { matchesPattern, isImageFile, formatFileSize } from '@bernierllc/validators-utils';

console.log(matchesPattern('*.js', 'app.js')); // true
console.log(isImageFile('photo.jpg')); // true
console.log(formatFileSize(1024).readable); // "1.0 KB"

HTTP Utilities

import { fetchWithTimeout, checkUrlAccessibility } from '@bernierllc/validators-utils';

const result = await checkUrlAccessibility('https://example.com');
console.log(result.ok); // true/false

API Reference

Color Utilities

• parseColor(color: string): RGBColor | null - Parse color strings into RGB values
• getContrastRatio(color1: string, color2: string): number - Calculate WCAG contrast ratio
• isLightColor(color: string): boolean - Check if color is considered light
• isDarkColor(color: string): boolean - Check if color is considered dark
• meetsWCAGContrastRequirement(ratio: number, level: 'AA' | 'AAA', size?: 'normal' | 'large'): boolean - Check WCAG compliance
• getRelativeLuminance(rgb: RGBColor): number - Calculate relative luminance
• rgbToHsl(rgb: RGBColor): HSLColor - Convert RGB to HSL

DOM Utilities

• parseHtml(html: string): Document | null - Parse HTML string into DOM Document

HTTP Utilities

• fetchWithTimeout(url: string, options?: FetchOptions): Promise<FetchResult> - Fetch with timeout and rate limiting
• checkUrlAccessibility(url: string): Promise<FetchResult> - Check if URL is accessible
• isSuccessStatus(status: number): boolean - Check if status is 2xx
• isRedirectStatus(status: number): boolean - Check if status is 3xx
• isClientErrorStatus(status: number): boolean - Check if status is 4xx
• isServerErrorStatus(status: number): boolean - Check if status is 5xx
• getHttpStatusMessage(status: number): string - Get human-readable status message

URL Utilities

• isValidUrl(url: string): boolean - Validate URL format
• resolveUrl(base: string, relative: string): string - Resolve relative URLs
• isDangerousProtocol(url: string): boolean - Check for dangerous protocols
• isHttpsUrl(url: string): boolean - Check if URL uses HTTPS
• isHttpUrl(url: string): boolean - Check if URL uses HTTP
• getUrlDomain(url: string): string | null - Extract domain from URL
• hasTrackingParameters(url: string): boolean - Check for tracking parameters
• removeTrackingParameters(url: string): string - Remove tracking parameters
• isEmailAddress(email: string): boolean - Validate email format
• isMailtoUrl(url: string): boolean - Check if URL is mailto

File Utilities

• matchesPattern(path: string, pattern: string): boolean - Check if path matches glob pattern
• isValidFileName(fileName: string): boolean - Validate file name
• getFileExtension(fileName: string): string - Get file extension
• sanitizeFileName(fileName: string): string - Sanitize file name for filesystem
• isImageFile(fileName: string): boolean - Check if file is an image
• isDocumentFile(fileName: string): boolean - Check if file is a document
• normalizeFilePath(filePath: string): string - Normalize file path
• formatFileSize(bytes: number): { bytes: number; readable: string } - Format file size

CSS Utilities

• parseCss(css: string): ParsedCSS - Parse CSS string into AST

Integration Status

• Logger integration: not-applicable - Utility functions with no user-facing operations requiring logging. No @bernierllc/logger dependency needed.
• Docs-Suite: ready - All functions documented with TypeScript definitions and comprehensive API reference
• NeverHub integration: not-applicable - Foundation utility package with no service discovery requirements. No @bernierllc/neverhub-adapter needed as this package provides core utilities only.

See Also

• @bernierllc/validators-core - Core types and interfaces
• @bernierllc/validators-runner - Orchestration and execution

License

Copyright (c) 2025 Bernier LLC. All rights reserved.