SnappyJS

https://github.com/zhipeng-jia/snappyjs
Admin
SnappyJS is a pure JavaScript implementation of Google's Snappy compression library that works in...
Tokens:3,567
Snippets:29
Trust Score:6.7
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install SnappyJS with npm

Source: https://github.com/zhipeng-jia/snappyjs/blob/master/README.md

Use this command to install SnappyJS for Node.js projects.

```bash
npm install snappyjs
```

--------------------------------

### Node.js Usage Example

Source: https://github.com/zhipeng-jia/snappyjs/blob/master/README.md

Demonstrates basic compression and decompression in a Node.js environment. Ensure SnappyJS is required and input is an ArrayBuffer.

```javascript
var SnappyJS = require('snappyjs')
var buffer = new ArrayBuffer(100)
// fill data in buffer
var compressed = SnappyJS.compress(buffer)
var uncompressed = SnappyJS.uncompress(compressed)
```

--------------------------------

### Install SnappyJS with Bower

Source: https://github.com/zhipeng-jia/snappyjs/blob/master/README.md

Use this command to install SnappyJS for projects managed with Bower.

```bash
bower install snappyjs
```

--------------------------------

### Benchmark Results Overview

Source: https://github.com/zhipeng-jia/snappyjs/blob/master/README.md

Provides performance comparison data between SnappyJS and node-snappy for various data types and sizes. Note that SnappyJS may outperform native implementations for small input sizes due to lower function call overhead.

```text
Real text #1 (length 618425, byte length 618425), repeated 100 times:
node-snappy#compress x 2.31 ops/sec ±1.47% (10 runs sampled)
snappyjs#compress x 0.91 ops/sec ±0.92% (7 runs sampled)
node-snappy#uncompress x 7.22 ops/sec ±4.07% (22 runs sampled)
snappyjs#uncompress x 2.45 ops/sec ±1.53% (11 runs sampled)

Real text #2 (length 3844590, byte length 3844591), repeated 10 times:
node-snappy#compress x 7.68 ops/sec ±2.78% (23 runs sampled)
snappyjs#compress x 3.56 ops/sec ±1.44% (13 runs sampled)
node-snappy#uncompress x 17.94 ops/sec ±4.71% (33 runs sampled)
snappyjs#uncompress x 7.24 ops/sec ±2.57% (22 runs sampled)

Random string (length 1000000, byte length 1500098), repeated 50 times:
node-snappy#compress x 6.69 ops/sec ±5.23% (21 runs sampled)
snappyjs#compress x 2.39 ops/sec ±2.54% (10 runs sampled)
node-snappy#uncompress x 14.94 ops/sec ±6.90% (40 runs sampled)
snappyjs#uncompress x 5.92 ops/sec ±4.28% (19 runs sampled)

Random string (length 100, byte length 147), repeated 100000 times:
node-snappy#compress x 4.17 ops/sec ±2.96% (15 runs sampled)
snappyjs#compress x 5.45 ops/sec ±1.51% (18 runs sampled)
node-snappy#uncompress x 4.39 ops/sec ±3.83% (15 runs sampled)
snappyjs#uncompress x 14.01 ops/sec ±2.06% (38 runs sampled)
```

--------------------------------

### SnappyJS Compression API

Source: https://github.com/zhipeng-jia/snappyjs/blob/master/README.md

Compresses input data using the Snappy algorithm. Supports ArrayBuffer, Buffer, and Uint8Array inputs and returns the compressed data in the same format.

```APIDOC
## SnappyJS.compress(input)

### Description
Compresses `input`, which must be of type `ArrayBuffer`, `Buffer`, or `Uint8Array`. The compressed byte stream is returned in the same type as the input.

### Method
`SnappyJS.compress`

### Parameters
#### Input
- **input** (ArrayBuffer | Buffer | Uint8Array) - Required - The data to be compressed.
```

--------------------------------

### Webpack Configuration for SnappyJS

Source: https://context7.com/zhipeng-jia/snappyjs/llms.txt

Configures webpack to exclude Buffer polyfills when only using ArrayBuffer or Uint8Array, reducing bundle size. Demonstrates importing and using SnappyJS in a module.

```javascript
// webpack.config.js
module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist'
  },
  // Prevent webpack from bundling Buffer polyfill
  node: {
    Buffer: false
  }
};

// src/index.js - Using SnappyJS without Buffer
import SnappyJS from 'snappyjs';

function compressData(data) {
  // Works with Uint8Array or ArrayBuffer
  if (data instanceof ArrayBuffer || data instanceof Uint8Array) {
    return SnappyJS.compress(data);
  }
  throw new TypeError('Input must be ArrayBuffer or Uint8Array');
}

function decompressData(compressed, maxLength = undefined) {
  return SnappyJS.uncompress(compressed, maxLength);
}

export { compressData, decompressData };
```

--------------------------------

### SnappyJS Error Handling

Source: https://context7.com/zhipeng-jia/snappyjs/llms.txt

Demonstrates how SnappyJS throws errors for invalid input types and corrupted data. Includes a safe decompression wrapper function to handle potential errors gracefully.

```javascript
const SnappyJS = require('snappyjs');

// TypeError for invalid input types
try {
  SnappyJS.compress('string input'); // Strings are not supported
} catch (err) {
  console.error('Type Error:', err.message);
  // Output: Type Error: Argument compressed must be type of ArrayBuffer, Buffer, or Uint8Array
}

try {
  SnappyJS.compress(12345); // Numbers are not supported
} catch (err) {
  console.error('Type Error:', err.message);
  // Output: Type Error: Argument compressed must be type of ArrayBuffer, Buffer, or Uint8Array
}

// Error for invalid/corrupted compressed data
try {
  const invalidData = Buffer.from([0xff, 0xff, 0xff, 0xff]);
  SnappyJS.uncompress(invalidData);
} catch (err) {
  console.error('Decompression Error:', err.message);
  // Output: Decompression Error: Invalid Snappy bitstream
}

// Safe decompression wrapper function
function safeUncompress(compressed, maxLength = 10 * 1024 * 1024) {
  try {
    return {
      success: true,
      data: SnappyJS.uncompress(compressed, maxLength)
    };
  } catch (err) {
    return {
      success: false,
      error: err.message
    };
  }
}

// Usage
const validCompressed = SnappyJS.compress(Buffer.from('Valid data'));
console.log(safeUncompress(validCompressed));
// Output: { success: true, data: <Buffer 56 61 6c 69 64 20 64 61 74 61> }

const invalidCompressed = Buffer.from([0x00, 0x01, 0x02]);
console.log(safeUncompress(invalidCompressed));
// Output: { success: false, error: 'Invalid Snappy bitstream' }
```

--------------------------------

### Compress Data with SnappyJS

Source: https://context7.com/zhipeng-jia/snappyjs/llms.txt

Compresses Buffer, Uint8Array, or ArrayBuffer inputs synchronously. The output format matches the input format.

```javascript
const SnappyJS = require('snappyjs');

// Compress using Buffer (Node.js)
const inputBuffer = Buffer.from('Hello, World! This is a test string that will be compressed.');
const compressedBuffer = SnappyJS.compress(inputBuffer);
console.log('Original size:', inputBuffer.length);
console.log('Compressed size:', compressedBuffer.length);
// Output:
// Original size: 60
// Compressed size: 62

// Compress using Uint8Array
const encoder = new TextEncoder();
const inputUint8 = encoder.encode('Repeated text repeated text repeated text repeated text');
const compressedUint8 = SnappyJS.compress(inputUint8);
console.log('Original size:', inputUint8.length);
console.log('Compressed size:', compressedUint8.length);
// Output:
// Original size: 55
// Compressed size: 29

// Compress using ArrayBuffer
const arrayBuffer = new ArrayBuffer(100);
const view = new Uint8Array(arrayBuffer);
for (let i = 0; i < 100; i++) {
  view[i] = i % 10; // Repeating pattern for better compression
}
const compressedArrayBuffer = SnappyJS.compress(arrayBuffer);
console.log('Type is ArrayBuffer:', compressedArrayBuffer instanceof ArrayBuffer);
// Output: Type is ArrayBuffer: true
```

--------------------------------

### Browser Usage of SnappyJS

Source: https://context7.com/zhipeng-jia/snappyjs/llms.txt

Includes SnappyJS directly in the browser via a script tag. Works with ArrayBuffer and typed arrays. Provides helper functions for string to Uint8Array conversion.

```html
<!DOCTYPE html>
<html>
<head>
  <title>SnappyJS Browser Example</title>
  <script src="dist/snappyjs.min.js"></script>
</head>
<body>
  <script>
    // Convert string to Uint8Array for compression
    function stringToUint8Array(str) {
      const encoder = new TextEncoder();
      return encoder.encode(str);
    }

    // Convert Uint8Array back to string
    function uint8ArrayToString(arr) {
      const decoder = new TextDecoder();
      return decoder.decode(arr);
    }

    // Compress and decompress example
    const originalText = 'Hello from the browser! This text will be compressed.';
    const inputArray = stringToUint8Array(originalText);

    // Compress
    const compressed = SnappyJS.compress(inputArray);
    console.log('Original size:', inputArray.length);
    console.log('Compressed size:', compressed.length);

    // Decompress
    const decompressed = SnappyJS.uncompress(compressed);
    const resultText = uint8ArrayToString(decompressed);
    console.log('Decompressed text:', resultText);

    // Working with ArrayBuffer (e.g., from FileReader)
    const buffer = new ArrayBuffer(50);
    const view = new Uint8Array(buffer);
    for (let i = 0; i < 50; i++) view[i] = 65; // Fill with 'A'

    const compressedBuffer = SnappyJS.compress(buffer);
    const uncompressedBuffer = SnappyJS.uncompress(compressedBuffer);
    console.log('ArrayBuffer round-trip successful:',
      uncompressedBuffer instanceof ArrayBuffer);
  </script>
</body>
</html>
```

--------------------------------

### Decompress Data with SnappyJS

Source: https://context7.com/zhipeng-jia/snappyjs/llms.txt

Decompresses data and supports an optional maxLength parameter to prevent memory issues with malicious input.

```javascript
const SnappyJS = require('snappyjs');

// Basic decompression
const original = Buffer.from('This message will be compressed and then decompressed back.');
const compressed = SnappyJS.compress(original);
const decompressed = SnappyJS.uncompress(compressed);
console.log('Decompressed:', decompressed.toString());
// Output: Decompressed: This message will be compressed and then decompressed back.

// Round-trip with Uint8Array
const encoder = new TextEncoder();
const decoder = new TextDecoder();
const inputData = encoder.encode('SnappyJS compression test data');
const compressedData = SnappyJS.compress(inputData);
const uncompressedData = SnappyJS.uncompress(compressedData);
console.log('Result:', decoder.decode(uncompressedData));
// Output: Result: SnappyJS compression test data

// Using maxLength for protection against malicious data
const safeData = Buffer.from('Safe content');
const compressedSafe = SnappyJS.compress(safeData);
try {
  // This will succeed - maxLength is larger than actual size
  const result = SnappyJS.uncompress(compressedSafe, 1000);
  console.log('Decompressed successfully');
} catch (err) {
  console.error('Error:', err.message);
}

try {
  // This will throw - maxLength is smaller than uncompressed size
  const result = SnappyJS.uncompress(compressedSafe, 5);
} catch (err) {
  console.error('Error:', err.message);
  // Output: Error: The uncompressed length of 12 is too big, expect at most 5
}
```

--------------------------------

### SnappyJS Uncompression API

Source: https://github.com/zhipeng-jia/snappyjs/blob/master/README.md

Decompresses Snappy-compressed data. Supports ArrayBuffer, Buffer, and Uint8Array inputs and returns the uncompressed data in the same format. Includes an optional maxLength parameter for security.

```APIDOC
## SnappyJS.uncompress(compressed, [maxLength])

### Description
Uncompresses `compressed` data, which must be of type `ArrayBuffer`, `Buffer`, or `Uint8Array`. The uncompressed byte stream is returned in the same type as the input.
If `maxLength` is provided, the uncompress function will throw an exception if the data length encoded in the header exceeds `maxLength`. This is a protection mechanism for malicious data streams.

### Method
`SnappyJS.uncompress`

### Parameters
#### Compressed Input
- **compressed** (ArrayBuffer | Buffer | Uint8Array) - Required - The Snappy-compressed data to be uncompressed.
#### Maximum Length
- **maxLength** (number) - Optional - The maximum allowed length for the uncompressed data. If the encoded length exceeds this value, an exception is thrown.
```

--------------------------------

### Webpack Configuration for ArrayBuffer/Uint8Array Input

Source: https://github.com/zhipeng-jia/snappyjs/blob/master/README.md

Configure webpack to prevent bundling a Buffer polyfill when only ArrayBuffer or Uint8Array are used as input. This is crucial for browser builds.

```javascript
  node: {
    Buffer: false,
  }
```
Tokens:
Raw