Native Node.js bindings for Google's Snappy compression library with precompiled binaries
npm install @thisames/snappy-js

Fast, native Node.js bindings for Google's Snappy compression library
High-performance compression/decompression with pre-compiled binaries for major platforms. Written in TypeScript with full type definitions.
- ā” Blazing Fast: Native C++ implementation, significantly faster than pure JavaScript alternatives
- š¦ Pre-compiled Binaries: Zero build time on supported platforms (Linux, macOS, Windows)
- š§ TypeScript Support: Full type definitions included
- šÆ Simple API: Compress and decompress in a single function call
- š Cross-platform: Works on Linux, macOS, and Windows (x64, ARM64)
- š Compatible: Drop-in replacement for other Snappy libraries
``bash`
npm install snappy-js
No compilation required! Pre-built binaries are automatically downloaded for your platform.
- Node.js >= 14.0.0
If a pre-built binary is not available for your platform:
`bash`
npm install snappy-js
Build tools will be automatically invoked. You'll need:
- Python 3
- C++ compiler (gcc, clang, or MSVC)
- make
`javascript
const snappy = require('snappy-js');
// Compress a Buffer
const data = Buffer.from('Hello, World!');
const compressed = snappy.compress(data);
console.log('Compressed:', compressed.length, 'bytes');
// Decompress
const decompressed = snappy.uncompress(compressed);
console.log('Decompressed:', decompressed.toString());
`
`typescript
import { compress, uncompress } from 'snappy-js';
const data = Buffer.from('Hello, TypeScript!');
const compressed = compress(data);
const decompressed = uncompress(compressed);
`
`javascript
const snappy = require('snappy-js');
// Compress a string directly
const text = 'Lorem ipsum dolor sit amet...';
const compressed = snappy.compressSync(text);
// Decompress to string
const decompressed = snappy.uncompressSync(compressed);
console.log(decompressed); // 'Lorem ipsum dolor sit amet...'
`
`javascript
const snappy = require('snappy-js');
// Compress JSON
const data = { users: [...], posts: [...] };
const json = JSON.stringify(data);
const compressed = snappy.compressSync(json);
// Save to file or send over network
fs.writeFileSync('data.snappy', compressed);
// Decompress JSON
const decompressed = snappy.uncompressSync(compressed);
const restored = JSON.parse(decompressed);
`
`javascript
const snappy = require('snappy-js');
const compressed = snappy.compress(data);
// Check if data is valid Snappy-compressed
if (snappy.isValidCompressed(compressed)) {
// Get uncompressed size without decompressing
const size = snappy.uncompressedLength(compressed);
console.log('Original size:', size, 'bytes');
// Decompress
const decompressed = snappy.uncompress(compressed);
}
`
Compress a Buffer using Snappy compression.
Parameters:
- input - Buffer to compress
Returns: Compressed Buffer
Throws: TypeError if input is not a Buffer
---
Decompress Snappy-compressed data.
Parameters:
- compressed - Compressed Buffer
Returns: Decompressed Buffer
Throws:
- TypeError if input is not a Buffer
- Error if data is not valid Snappy-compressed data
---
Compress a string using Snappy.
Parameters:
- str - String to compressencoding
- - String encoding (default: 'utf8')
Returns: Compressed Buffer
---
Decompress to a string.
Parameters:
- compressed - Compressed Bufferencoding
- - String encoding (default: 'utf8')
Returns: Decompressed string
---
Get the uncompressed length without decompressing.
Parameters:
- compressed - Compressed Buffer
Returns: Original uncompressed size in bytes
---
Check if a buffer contains valid Snappy-compressed data.
Parameters:
- data - Buffer to validate
Returns: true if valid, false otherwise
---
- decompress = uncompressdecompressSync
- = uncompressSync
Benchmarks comparing snappy-js (native) vs SnappyJS (pure JavaScript):
`
Dataset: JSON Data (10KB)
========================
snappy-js (Native): 0.015ms/op (66,666 ops/sec)
SnappyJS (JavaScript): 0.180ms/op (5,555 ops/sec)
š snappy-js is 12x faster
`
Run benchmarks yourself:
`bash`
npm run benchmark:compare
`javascript
const redis = require('redis');
const snappy = require('snappy-js');
async function setCache(key, value) {
const json = JSON.stringify(value);
const compressed = snappy.compressSync(json);
await redis.set(key, compressed);
}
async function getCache(key) {
const compressed = await redis.getBuffer(key);
if (!compressed) return null;
const json = snappy.uncompressSync(compressed);
return JSON.parse(json);
}
`
`javascript
const fs = require('fs');
const snappy = require('snappy-js');
// Save compressed file
const data = fs.readFileSync('data.json');
const compressed = snappy.compress(data);
fs.writeFileSync('data.json.snappy', compressed);
// Read compressed file
const compressedFile = fs.readFileSync('data.json.snappy');
const decompressed = snappy.uncompress(compressedFile);
`
`javascript
const express = require('express');
const snappy = require('snappy-js');
app.get('/api/data', (req, res) => {
const data = { / large dataset / };
const json = JSON.stringify(data);
const compressed = snappy.compressSync(json);
res.set('Content-Encoding', 'snappy');
res.send(compressed);
});
`
The package includes:
``
snappy-js/
āāā dist/ # Compiled TypeScript
ā āāā index.js
ā āāā index.d.ts
ā āāā *.map
āāā deps/ # Native dependencies
ā āāā binding.cc # C++ bindings
ā āāā snappy/ # Snappy C++ source
āāā prebuilds/ # Pre-compiled binaries (if available)
ā āāā darwin-arm64/
ā āāā darwin-x64/
ā āāā linux-arm64/
ā āāā linux-x64/
ā āāā win32-ia32/
ā āāā win32-x64/
āāā binding.gyp # Build configuration
āāā package.json
Yes, the Snappy C++ source code (~500KB) is included in the package. This is normal and necessary because:
1. ā
Fallback compilation: If no pre-built binary exists for your platform
2. ā
No external dependencies: Everything needed to build is self-contained
3. ā
Licensing: BSD-3-Clause allows redistribution
4. ā
Industry standard: This is how most native Node.js modules work (sharp, better-sqlite3, etc.)
`bashInstall dependencies
npm install
$3
`bash
npm test
`$3
`bash
Run comparison benchmark
npm run benchmark:compareRun internal benchmarks
npm run benchmark
`$3
`bash
Build for all platforms (requires Docker or VMs)
npm run prebuild
`š License
BSD-3-Clause
- This library: BSD-3-Clause
- Snappy library: BSD-3-Clause (included in
deps/snappy/`)Contributions are welcome! Please feel free to submit a Pull Request.
- Snappy - Original Google Snappy library
- SnappyJS - Pure JavaScript implementation
- node-snappy - Alternative native bindings
| Feature | snappy-js | SnappyJS | node-snappy |
|---------|-----------|----------|-------------|
| Performance | ā” Native C++ | š JavaScript | ā” Native C++ |
| TypeScript | ā
Full support | ā No types | ā ļø Community types |
| Pre-built binaries | ā
Yes | N/A | ā No |
| Installation time | š < 5 seconds | Instant | š ~30 seconds |
| Maintenance | ā
Active | ā ļø Inactive | ā ļø Sporadic |
| Modern Node.js | ā
14+ | ā
10+ | ā ļø Old API |
- š Issues: GitHub Issues
- š Documentation: GitHub Wiki
---
Made with ā¤ļø by Thiago Santos