SnappyJS

Common errors

• TypeError: Cannot read properties of undefined (reading 'compress')

  cause The SnappyJS module was not correctly imported or required, or the 'compress' method was called on an undefined object.
  fix Ensure you are importing the default export (e.g., `import SnappyJS from "snappyjs"`) or correctly requiring the module (e.g., `const SnappyJS = require("snappyjs")`) before calling its methods.

• ReferenceError: Buffer is not defined

  cause When bundling for a browser environment with webpack, the Node.js `Buffer` global is not available, and webpack may implicitly attempt to polyfill it, failing if not configured correctly.
  fix Add `node: { Buffer: false }` to your webpack configuration object to explicitly prevent `Buffer` polyfilling, especially if you only intend to use `ArrayBuffer` or `Uint8Array`.

• Error: Input must be type of ArrayBuffer, Buffer, or Uint8Array

  cause The input provided to `SnappyJS.compress` or `SnappyJS.uncompress` is not one of the supported binary data types.
  fix Convert your data into an `ArrayBuffer`, `Buffer` (Node.js only), or `Uint8Array` before passing it to SnappyJS compression/decompression functions.

• RangeError: Offset is out of bounds

  cause This error typically occurs during decompression if the input `compressed` data stream is corrupted, malformed, or does not conform to the Snappy format. It can also be triggered if the `maxLength` parameter in `uncompress` is exceeded by the data's internal header.
  fix Verify the integrity of your compressed data. If using `uncompress(data, maxLength)`, ensure `maxLength` is set appropriately to prevent unexpected data sizes from causing an error.

Warnings

• gotcha When bundling `snappyjs` for browser environments using webpack, explicitly disable the Node.js `Buffer` polyfill to prevent unnecessary code from being included in your bundle. This is crucial if you intend to only use `ArrayBuffer` or `Uint8Array` as input parameters.
  Fix: Add `node: { Buffer: false }` to your webpack configuration object to prevent automatic `Buffer` polyfilling.
• gotcha While SnappyJS is optimized JavaScript, its performance for larger inputs (e.g., >100KB) typically reaches only 35-45% of native Snappy implementations. For extremely performance-critical Node.js applications, consider native C++ bindings if cross-platform pure JS isn't a strict requirement.
  Fix: Evaluate your application's performance needs; use native Snappy bindings (e.g., `node-snappy`) for maximum speed in Node.js, or accept the pure JavaScript performance for browser compatibility and simpler deployments.
• gotcha Since v0.7.0, the `uncompress` function accepts an optional `maxLength` parameter. It is highly recommended to provide this parameter as a protection mechanism against malicious or malformed data streams that could attempt to exhaust memory by declaring an excessively large uncompressed size.
  Fix: Always call `SnappyJS.uncompress(compressedData, expectedMaxLength)` and provide a reasonable upper bound for the uncompressed data size based on your application's expectations.

Install

• npm install snappyjs npm
• yarn add snappyjs yarn
• pnpm add snappyjs pnpm

Imports

• SnappyJS
  wrong:

  import { SnappyJS } from 'snappyjs'

  correct:

  import SnappyJS from 'snappyjs'

  For CommonJS environments, use 'const SnappyJS = require("snappyjs")'. The library primarily exports a single object containing 'compress' and 'uncompress' methods.
• compress
  wrong:

  import { compress } from 'snappyjs'

  correct:

  import SnappyJS from 'snappyjs'; const compressed = SnappyJS.compress(input);

  The 'compress' function is a method of the main SnappyJS object. Ensure you import the default SnappyJS object first.
• uncompress
  wrong:

  import { uncompress } from 'snappyjs'

  correct:

  import SnappyJS from 'snappyjs'; const uncompressed = SnappyJS.uncompress(compressed, maxLength);

  The 'uncompress' function is a method of the main SnappyJS object. It supports an optional 'maxLength' parameter for security since v0.7.0.

Quickstart

Demonstrates how to import SnappyJS, convert a string to an `ArrayBuffer`, then compress and uncompress the data, including verification and using the `maxLength` security feature.

import * as SnappyJS from 'snappyjs';

// Example data: a simple text string converted to a Uint8Array
const text = "Hello, SnappyJS! This is a test string to demonstrate compression and decompression.";
const encoder = new TextEncoder();
const originalData = encoder.encode(text);

// SnappyJS expects ArrayBuffer, Buffer, or Uint8Array. 
// Uint8Array's .buffer property provides the underlying ArrayBuffer.
const inputBuffer = originalData.buffer;

console.log(`Original text: "${text}"`);
console.log('Original size:', inputBuffer.byteLength, 'bytes');

try {
  // Compress the data
  const compressed = SnappyJS.compress(inputBuffer);
  console.log('Compressed size:', compressed.byteLength, 'bytes');

  // Uncompress the data
  // Using maxLength as a security measure, estimating twice the original size as a safe upper bound.
  const estimatedMaxLength = inputBuffer.byteLength * 2;
  const uncompressed = SnappyJS.uncompress(compressed, estimatedMaxLength);
  console.log('Uncompressed size:', uncompressed.byteLength, 'bytes');

  // Convert back to string to verify
  const decoder = new TextDecoder();
  const decompressedText = decoder.decode(uncompressed);
  console.log('Decompressed text:', decompressedText);

  if (text === decompressedText) {
    console.log("Compression and decompression successful and data integrity maintained!");
  } else {
    console.error("Error: Data mismatch after compression/decompression!");
  }
} catch (error) {
  console.error("An error occurred during SnappyJS operation:", error.message);
}