roxify 1.2.7 → 1.2.9

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+## [1.2.10] - 2026-01-09
+
+### Performance 🚀🚀
+
+- **MASSIVE file packing speedup**: 18,750 files (660MB) now in **7 seconds** (was 18s)
+- Parallelized file reading with `fs.promises.readFile()` and `Promise.all()` batching
+- Batch size optimized to 1000 files per parallel read
+- Improved buffer concatenation strategy (array accumulation + single concat)
+- Added error handling for unreadable files during parallel reads
+
+### Benchmarks
+
+- Single file 1GB: 389ms (2.63 GB/s)
+- Directory 18,750 files (660MB): **6.8s** (97 MB/s including I/O overhead)
+
+## [1.2.9] - 2026-01-09
+
+### Performance 🚀
+
+- **EXTREME SPEED**: 1GB encode in 0.39s (**2.6 GB/s throughput**)
+- Optimized PNG pixel copying from byte-by-byte loops to bulk Buffer.copy() operations
+- Reduced PNG deflate overhead by using zlib level 0 (data already compressed with Zstd)
+- Lowered large image threshold from 50M to 10M pixels for faster manual PNG generation
+- Default Zstd compression level changed from 15 to 3 (much faster, still excellent ratio)
+
+### Changed
+
+- Added `compressionLevel` option to `EncodeOptions` (default: 3)
+- Added `skipOptimization` option to disable zopfli PNG optimization
+- CLI now disables PNG optimization by default for maximum speed
+
+### Benchmarks
+
+- 1KB: 14.77ms
+- 100MB: 63.74ms (1.57 GB/s)
+- 500MB: 203ms (2.46 GB/s)
+- 1GB: 389ms (2.63 GB/s)
+
+## [1.2.8] - 2026-01-09
+
+### Added
+
+- 🦀 **Native Rust acceleration** via N-API for extreme performance
+  - Delta encoding/decoding with Rayon parallelization
+  - Multi-threaded Zstd compression (level 19) with `zstdmt` feature
+  - Fast CRC32 and Adler32 checksums
+  - Parallel pixel scanning for ROX1 magic and markers
+- ⚡ **Performance improvements**: Up to 1GB/s throughput on modern hardware
+  - 1GB encode: ~1.2s (863 MB/s)
+  - 1GB decode: ~1.0s (1031 MB/s)
+- 🔄 **Automatic fallback**: Pure TypeScript implementation when native module unavailable
+- 📦 **Unified repository**: Rust and TypeScript code in single npm package
+
+### Changed
+
+- Switched from `@mongodb-js/zstd` to native Rust zstd for better performance
+- Updated package description to highlight native acceleration
+- Compression ratio improved to 0.01-0.05% with Zstd level 19
+
+### Technical
+
+- Added `build:native` and `build:all` npm scripts
+- Native module compiled to `libroxify_native.node` (1.8MB)
+- Cargo workspace configured with `native/` directory
+- Updated dependencies: Rust crates (napi, rayon, zstd, crc32fast, adler)
+
+## [1.0.4] - Previous release
+
+- Initial TypeScript implementation
+- Brotli compression
+- Multiple encoding modes (compact, chunk, pixel, screenshot)
+- AES-256-GCM encryption support

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Yohan SANNIER
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to use,
-modify, merge, publish, distribute, sublicense, and/or sell tools or applications
-that make use of the Software, provided that the Software itself is not copied,
-rebranded, or redistributed as a standalone package under a different name or
-ownership.
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 RoxCompressor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,117 +1,370 @@
-# roxify
-
-[![npm version](https://img.shields.io/npm/v/roxify.svg)](https://www.npmjs.com/package/roxify)
-
-Encode binary data into PNG images and decode them back. Supports CLI and programmatic API (Node.js ESM).
-
-Roxify is a compact, color-based alternative to QR codes, designed specifically for digital-only use (not for printing). It encodes data using color channels (rather than monochrome patterns) for higher density, and is optimized for decoding from approximate screenshots — including nearest-neighbour resize/stretch and solid or gradient backgrounds. It is not intended for printed media and is not resilient to lossy compression or heavy image filtering.
-
-Roxify creates PNGs that are often more space-efficient than ZIP or 7z archives for similar payloads without loss. Roxify provides superior compression ratios, making it ideal for embedding images, GIFs, audio, video, code, and other files without any quality loss — the original file is perfectly recovered upon decoding.
-
-Key benefits:
-
-- **Superior Compression**: Roxify outperforms traditional ZIP and 7z (LZMA) in speed and ratio, enabling smaller PNG outputs.
-- **Lossless Embedding**: Compress and embed any file type (images, videos, code) with full fidelity restoration.
-- **Code Efficiency**: Hyper-efficient for compressing source code, reducing file sizes dramatically.
-- **Obfuscation & Security**: Obfuscate code or lock files with AES-256-GCM encryption, more compact than password-protected ZIPs.
-- **Visual Data Indicator**: PNG size visually represents embedded data size, providing an intuitive overview.
-- **Archive Support**: Pack directories into archives, list contents without decoding, and extract individual files selectively.
-- **Central Directory**: Access file lists without passphrase, even for encrypted archives.
-
-## Installation
-
-```bash
-npm install roxify
-```
-
-## CLI Usage
-
-```bash
-npx rox encode <inputName>.ext (<outputName>.png)
-npx rox decode <inputName>.png (<outputName>.ext)
-npx rox list <inputName>.png
-```
-
-If no output name is provided:
-
-- Encoding: output defaults to `<inputName>.png`.
-- Decoding: if the image contains the original filename it will be restored; otherwise the output will be `decoded.bin`.
-
-**Options:**
-
-- `-p, --passphrase <pass>` — Encrypt with AES-256-GCM
-- `-v, --verbose` — Show detailed errors
-
-Run `npx rox help` for full options.
-
-## API Usage
-
-### Basic Encoding and Decoding
-
-```js
-import { readFileSync, writeFileSync } from 'fs';
-import { encodeBinaryToPng } from 'roxify';
-
-const fileName = 'input.bin';
-const inputBuffer = readFileSync(fileName);
-const pngBuffer = await encodeBinaryToPng(inputBuffer, {
-  name: fileName,
-});
-writeFileSync('output.png', pngBuffer);
-```
-
-```js
-import { readFileSync, writeFileSync } from 'fs';
-import { decodePngToBinary } from 'roxify';
-
-const pngFromDisk = readFileSync('output.png');
-const { buf, meta } = await decodePngToBinary(pngFromDisk);
-writeFileSync(meta?.name ?? 'decoded.txt', buf);
-```
-
-### With Passphrase
-
-```js
-const pngBuffer = await encodeBinaryToPng(inputBuffer, {
-  name: fileName,
-  passphrase: 'mysecret',
-});
-```
-
-```js
-const { buf, meta } = await decodePngToBinary(pngFromDisk, {
-  passphrase: 'mysecret',
-});
-```
-
-### With Progress Logging
-
-```js
-const pngBuffer = await encodeBinaryToPng(inputBuffer, {
-  name: fileName,
-  onProgress: (info) => {
-    console.log(`Phase: ${info.phase}, Loaded: ${info.loaded}/${info.total}`);
-  },
-});
-```
-
-## Requirements
-
-- Node.js 18+ (ESM)
-- Native dependencies: `sharp` (auto-installed)
-
-## License
-
-This package is proprietary (UNLICENSED). The repository remains private; the package is published to npm for distribution. If there is significant community interest, it may be open-sourced in the future.
-
-## Minimal PNG container (minpng) 🔧
-
-This library includes a compact encoder/decoder that targets the smallest possible PNG container while guaranteeing pixel-perfect recovery from screenshots when no lossy filtering is applied.
-
-- Inputs must be raw RGB 8-bit buffers (no alpha).
-- Transformations used: Paeth 2D predictor (left/top), RGB decorrelation (G, R−G, B−G), zigzag traversal.
-- Compression: Zstd at maximum compression level.
-- Output: neutral PNG (no ICC/gamma/alpha), all data mapped to RGB bytes only.
-- The decoder searches for start/end markers and a compact header embedded in pixels to perform a reliable, deterministic roundtrip.
-
-Use `encodeMinPng(rgbBuf, width, height)` and `decodeMinPng(pngBuf)` from the public API (`roxify`).
+# RoxCompressor Transform
+
+> Encode binary data into PNG images and decode them back. Fast, efficient, with optional encryption and native Rust acceleration.
+
+[![npm version](https://img.shields.io/npm/v/roxify.svg)](https://www.npmjs.com/package/roxify)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Features
+
+- ⚡ **Blazing Fast**: Native Rust acceleration via N-API — **1GB/s** throughput on modern hardware
+- 🚀 **Optimized Compression**: Multi-threaded Zstd compression (level 19) with parallel processing
+- 🔒 **Secure**: AES-256-GCM encryption support with PBKDF2 key derivation
+- 🎨 **Multiple modes**: Compact, chunk, pixel, and screenshot modes
+- 📦 **CLI & API**: Use as command-line tool or JavaScript library
+- 🔄 **Lossless**: Perfect roundtrip encoding/decoding
+- 📊 **Efficient**: Typically 0.01-0.05% of original size with Zstd compression
+- 📖 **Full TSDoc**: Complete TypeScript documentation
+- 🦀 **Rust Powered**: Optional native module for extreme performance (falls back to pure JS)
+
+## Documentation
+
+- 📘 **[CLI Documentation](./CLI.md)** - Complete command-line usage guide
+- 📗 **[JavaScript SDK](./JAVASCRIPT_SDK.md)** - Programmatic API reference with examples
+- 📙 **[Quick Start](#quick-start)** - Get started in 2 minutes
+
+## Installation
+
+### As CLI tool (npx)
+
+No installation needed! Use directly with npx:
+
+```bash
+  npx rox encode input.zip output.png
+  npx rox decode output.png original.zip
+```
+
+### As library
+
+```bash
+npm install roxify
+```
+
+## CLI Usage
+
+### Quick Start
+
+```bash
+# Encode a file
+  npx rox encode document.pdf document.png
+
+# Decode it back
+  npx rox decode document.png document.pdf
+
+# With encryption
+  npx rox encode secret.zip secret.png -p mypassword
+  npx rox decode secret.png secret.zip -p mypassword
+```
+
+### CLI Commands
+
+#### `encode` - Encode file to PNG
+
+```bash
+  npx rox encode <input> [output] [options]
+```
+
+**Options:**
+
+- `-p, --passphrase <pass>` - Encrypt with passphrase (AES-256-GCM)
+- `-m, --mode <mode>` - Encoding mode: `compact|chunk|pixel|screenshot` (default: `screenshot`)
+- `-q, --quality <0-11>` - Brotli compression quality (default: `1`)
+  - `0` = fastest, largest
+  - `11` = slowest, smallest
+- `-e, --encrypt <type>` - Encryption: `auto|aes|xor|none` (default: `aes` if passphrase)
+- `--no-compress` - Disable compression
+- `-o, --output <path>` - Output file path
+
+**Examples:**
+
+```bash
+# Basic encoding
+  npx rox encode data.bin output.png
+
+# Fast compression for large files
+  npx rox encode large-video.mp4 output.png -q 0
+
+# High compression for small files
+  npx rox encode config.json output.png -q 11
+
+# With encryption
+  npx rox encode secret.pdf secure.png -p "my secure password"
+
+# Compact mode (smallest PNG)
+  npx rox encode data.bin tiny.png -m compact
+
+# Screenshot mode (recommended, looks like a real image)
+  npx rox encode archive.tar.gz screenshot.png -m screenshot
+```
+
+#### `decode` - Decode PNG to file
+
+```bash
+  npx rox decode <input> [output] [options]
+```
+
+**Options:**
+
+- `-p, --passphrase <pass>` - Decryption passphrase
+- `-o, --output <path>` - Output file path (auto-detected from metadata if not provided)
+
+**Examples:**
+
+```bash
+# Basic decoding
+  npx rox decode encoded.png output.bin
+
+# Auto-detect filename from metadata
+  npx rox decode encoded.png
+
+# With decryption
+  npx rox decode encrypted.png output.pdf -p "my secure password"
+```
+
+## JavaScript API
+
+### Basic Usage
+
+```typescript
+import { encodeBinaryToPng, decodePngToBinary } from 'roxify';
+import { readFileSync, writeFileSync } from 'fs';
+
+// Encode
+const input = readFileSync('input.zip');
+const png = await encodeBinaryToPng(input, {
+  mode: 'screenshot',
+  name: 'input.zip',
+});
+writeFileSync('output.png', png);
+
+// Decode
+const encoded = readFileSync('output.png');
+const result = await decodePngToBinary(encoded);
+writeFileSync(result.meta?.name || 'output.bin', result.buf);
+```
+
+### With Encryption
+
+```typescript
+// Encode with AES-256-GCM
+const png = await encodeBinaryToPng(input, {
+  mode: 'screenshot',
+  passphrase: 'my-secret-password',
+  encrypt: 'aes',
+  name: 'secret.zip',
+});
+
+// Decode with passphrase
+const result = await decodePngToBinary(encoded, {
+  passphrase: 'my-secret-password',
+});
+```
+
+### Fast Compression
+
+```typescript
+// Optimize for speed (recommended for large files)
+const png = await encodeBinaryToPng(largeBuffer, {
+  mode: 'screenshot',
+  brQuality: 0, // Fastest
+  name: 'large-file.bin',
+});
+
+// Optimize for size (recommended for small files)
+const png = await encodeBinaryToPng(smallBuffer, {
+  mode: 'compact',
+  brQuality: 11, // Best compression
+  name: 'config.json',
+});
+```
+
+### Encoding Modes
+
+#### `screenshot` (Recommended)
+
+Encodes data as RGB pixel values, optimized for screenshot-like appearance. Best balance of size and compatibility.
+
+```typescript
+const png = await encodeBinaryToPng(data, { mode: 'screenshot' });
+```
+
+#### `compact` (Smallest)
+
+Minimal 1x1 PNG with data in custom chunk. Fastest and smallest.
+
+```typescript
+const png = await encodeBinaryToPng(data, { mode: 'compact' });
+```
+
+#### `pixel`
+
+Encodes data as RGB pixel values without screenshot optimization.
+
+```typescript
+const png = await encodeBinaryToPng(data, { mode: 'pixel' });
+```
+
+#### `chunk`
+
+Standard PNG with data in custom rXDT chunk.
+
+```typescript
+const png = await encodeBinaryToPng(data, { mode: 'chunk' });
+```
+
+## API Reference
+
+### `encodeBinaryToPng(input, options)`
+
+Encodes binary data into a PNG image.
+
+**Parameters:**
+
+- `input: Buffer` - The binary data to encode
+- `options?: EncodeOptions` - Encoding options
+
+**Returns:** `Promise<Buffer>` - The encoded PNG
+
+**Options:**
+
+```typescript
+interface EncodeOptions {
+  // Compression algorithm ('br' = Brotli, 'none' = no compression)
+  compression?: 'br' | 'none';
+
+  // Passphrase for encryption
+  passphrase?: string;
+
+  // Original filename to embed
+  name?: string;
+
+  // Encoding mode
+  mode?: 'compact' | 'chunk' | 'pixel' | 'screenshot';
+
+  // Encryption method
+  encrypt?: 'auto' | 'aes' | 'xor' | 'none';
+
+  // Output format
+  output?: 'auto' | 'png' | 'rox';
+
+  // Include filename in metadata (default: true)
+  includeName?: boolean;
+
+  // Brotli quality 0-11 (default: 1)
+  brQuality?: number;
+}
+```
+
+### `decodePngToBinary(pngBuf, options)`
+
+Decodes a PNG image back to binary data.
+
+**Parameters:**
+
+- `pngBuf: Buffer` - The PNG image to decode
+- `options?: DecodeOptions` - Decoding options
+
+**Returns:** `Promise<DecodeResult>` - The decoded data and metadata
+
+**Options:**
+
+```typescript
+interface DecodeOptions {
+  // Passphrase for decryption
+  passphrase?: string;
+}
+```
+
+**Result:**
+
+```typescript
+interface DecodeResult {
+  // Decoded binary data
+  buf: Buffer;
+
+  // Extracted metadata
+  meta?: {
+    // Original filename
+    name?: string;
+  };
+}
+```
+
+## Performance Tips
+
+### For Large Files (>10 MB)
+
+```bash
+# Use quality 0 for fastest encoding
+npx rox encode large.bin output.png -q 0
+```
+
+```typescript
+const png = await encodeBinaryToPng(largeFile, {
+  mode: 'screenshot',
+  brQuality: 0, // 10-20x faster than default
+});
+```
+
+### For Small Files (<1 MB)
+
+```bash
+# Use quality 11 for best compression
+npx rox encode small.json output.png -q 11 -m compact
+```
+
+```typescript
+const png = await encodeBinaryToPng(smallFile, {
+  mode: 'compact',
+  brQuality: 11, // Best compression ratio
+});
+```
+
+### Benchmark Results
+
+File: 3.8 MB binary
+
+- **Quality 0**: ~500-800ms, output ~1.2 MB
+- **Quality 1** (default): ~1-2s, output ~800 KB
+- **Quality 5**: ~8-12s, output ~750 KB
+- **Quality 11**: ~20-30s, output ~720 KB
+
+## Error Handling
+
+```typescript
+try {
+  const result = await decodePngToBinary(encoded, {
+    passphrase: 'wrong-password',
+  });
+} catch (err) {
+  if (err.message.includes('Incorrect passphrase')) {
+    console.error('Wrong password!');
+  } else if (err.message.includes('Invalid ROX format')) {
+    console.error('Not a valid RoxCompressor PNG');
+  } else {
+    console.error('Decode failed:', err.message);
+  }
+}
+```
+
+## Security
+
+- **AES-256-GCM**: Authenticated encryption with 100,000 PBKDF2 iterations
+- **XOR cipher**: Simple obfuscation (not cryptographically secure)
+- **No encryption**: Data is compressed but not encrypted
+
+⚠️ **Warning**: Use strong passphrases for sensitive data. The `xor` encryption mode is not secure and should only be used for obfuscation.
+
+## License
+
+MIT © RoxCompressor
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR on GitHub.
+
+## Links
+
+- [GitHub Repository](https://github.com/RoxasYTB/RoxCompressor)
+- [npm Package](https://www.npmjs.com/package/roxify)
+- [Report Issues](https://github.com/RoxasYTB/RoxCompressor/issues)

package/dist/cli.d.ts

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
-export {};
+#!/usr/bin/env node
+export {};