🔒 crc-check

Blazing-fast CRC checksums for TypeScript that actually make sense — no dependencies, no nonsense, just checksums that work.

✨ Features

• ✅ Triple Threat: CRC-8, CRC-16, and CRC-32 support out of the box
• ✅ Zero Dependencies: Only uses Node.js/Bun built-ins, zero bloat
• ✅ Smart Caching: Automatic lookup table generation with intelligent caching
• ✅ Type Safety: Strict TypeScript with discriminated unions and readonly types
• ✅ Universal Input: Handles strings (UTF-8) and Uint8Array natively

📦 Installation

npm install @adametherzlab/crc-check
# or
bun add @adametherzlab/crc-check

🚀 Quick Start

// REMOVED external import: import { computeCrc32, computeCrc16, computeCrc8 } from "@adametherzlab/crc-check";

// Works with strings (UTF-8 encoded automatically)
const crc32 = computeCrc32("Hello World");
console.log(crc32.checksum); // 3178483241
console.log(crc32.hex);      // "bd0f9e75"

// Works with raw bytes too
const bytes = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
const crc16 = computeCrc16(bytes);
console.log(crc16.hex); // "da70"

// Quick CRC-8 for small payloads
const crc8 = computeCrc8("sensor-data-42");
console.log(crc8.hex); // "52"

📚 API Reference

Core Computation Functions

Function	Signature	Description
computeCrc	(data: InputData, variant: CrcVariant, options?: CrcOptions): CrcResult	Generic CRC computation with full control
computeCrc8	(data: InputData, options?: CrcOptions): CrcResult	CRC-8 with standard polynomial (0x07)
computeCrc16	(data: InputData, options?: CrcOptions): CrcResult	CRC-16 with standard polynomial (0x8005)
computeCrc32	(data: InputData, options?: CrcOptions): CrcResult	CRC-32 with standard polynomial (0x04c11db7)

Example:

// REMOVED external import: import { computeCrc, CrcVariant } from "@adametherzlab/crc-check";
const result = computeCrc("payload", CrcVariant.CRC32);
// result.checksum: number, result.hex: string

Utility Functions

Function	Signature	Description
calculateCrc	(data: InputData, variant: CrcVariant, options?: CrcOptions): CrcResult	Alias for computeCrc with additional validation
verifyCrc	(data: InputData, expected: number | CrcResult, variant: CrcVariant, options?: CrcOptions): boolean	Verify data integrity against expected checksum
generateLookupTable	(polynomial: number, variant: CrcVariant): LookupTable	Generate custom lookup table for non-standard polynomials
getLookupTable	(variant: CrcVariant): LookupTable	Retrieve cached lookup table (generates if needed)
clearLookupCache	(): void	Clear internal lookup table cache
toHex	(value: number, variant: CrcVariant): string	Format checksum as zero-padded hex string
reflectByte	(byte: number): number	Reverse bits in a single byte
reflectValue	(value: number, bitWidth: number): number	Reverse bits in a value with specified width

Types & Constants

// REMOVED external import: import { CrcVariant, STANDARD_POLYNOMIALS, type CrcOptions, type CrcResult } from "@adametherzlab/crc-check";

// Variants
CrcVariant.CRC8   // 8-bit checksums
CrcVariant.CRC16  // 16-bit checksums  
CrcVariant.CRC32  // 32-bit checksums

// Standard polynomials
STANDARD_POLYNOMIALS[CrcVariant.CRC8]   // 0x07 (Standard CRC-8)
STANDARD_POLYNOMIALS[CrcVariant.CRC16]  // 0x8005 (IBM/ARC)
STANDARD_POLYNOMIALS[CrcVariant.CRC32]  // 0x04c11db7 (IEEE 802.3)

Configuration Options

The CrcOptions interface allows customization of CRC behavior:

interface CrcOptions {
  initialValue?: number;   // Starting value (default: variant-specific standard)
  finalXor?: number;       // Final XOR value applied to result (default: 0)
  reflectInput?: boolean;  // Reverse input bits (default: false, true for CRC-32)
  reflectOutput?: boolean; // Reverse output bits (default: false, true for CRC-32)
}

Standard Defaults:

• CRC-8: Initial 0x00, Final XOR 0x00, No reflection
• CRC-16: Initial 0x0000, Final XOR 0x0000, No reflection
• CRC-32: Initial 0xFFFFFFFF, Final XOR 0xFFFFFFFF, Input/Output reflected

Lookup Table Caching & Performance

This library uses lookup table acceleration for O(n) performance where n is data length. Tables are generated on-demand and cached globally:

• First call: Generates 256-entry lookup table (negligible one-time cost)
• Subsequent calls: Uses cached table for maximum speed
• Memory: ~1KB per variant (256 bytes for CRC-8, 512 for CRC-16, 1KB for CRC-32)

// REMOVED external import: import { clearLookupCache } from "@adametherzlab/crc-check";
clearLookupCache();

🧪 Advanced Usage

Data Integrity Verification

// REMOVED external import: import { computeCrc32, verifyCrc, CrcVariant } from "@adametherzlab/crc-check";

// Simulate sending data
const payload = "critical-transaction-data";
const checksum = computeCrc32(payload);
console.log(`Transmit: ${checksum.hex}`); // e.g., "9eceb24f"

// On the receiving side
const receivedData = "critical-transaction-data"; // Your actual received buffer
const isValid = verifyCrc(receivedData, checksum, CrcVariant.CRC32);

if (isValid) {
  console.log("✅ Data integrity confirmed");
} else {
  console.error("❌ Data corruption detected!");
}

Custom Polynomials

Need a non-standard CRC? Generate your own lookup table:

// REMOVED external import: import { generateLookupTable, CrcVariant, calculateCrc } from "@adametherzlab/crc-check";

// Custom CRC-16 with polynomial 0x1021 (CCITT-FALSE)
const customTable = generateLookupTable(0x1021, CrcVariant.CRC16);
const result = calculateCrc("data", CrcVariant.CRC16, {
  initialValue: 0xFFFF,
  finalXor: 0x0000
});

Working with Bytes

// REMOVED external import: import { computeCrc16 } from "@adametherzlab/crc-check";

const packet = new Uint8Array([
  0x7E, 0x00, 0x05, // Header
  0x01, 0x02, 0x03, // Payload
  0x00, 0x00        // CRC placeholder
]);

// Calculate CRC over payload only
const crc = computeCrc16(packet.subarray(0, 6));
packet[6] = (crc.checksum >> 8) & 0xFF; // High byte
packet[7] = crc.checksum & 0xFF;        // Low byte

🤝 Contributing

See CONTRIBUTING.md

📄 License

MIT (c) AdametherzLab