zeck 2.1.0 → 2.1.2

package/README.md

@@ -13,17 +13,20 @@ The Zeckendorf algorithm represents numbers as a sum of non-consecutive Fibonacc
 ## Features
 
 - **Compression & Decompression**: Convert data to/from Zeckendorf representation
+- **File Format with Headers**: `.zeck` file format that automatically preserves original file size and endianness information
 - **Multiple Endian Interpretations**: Support for both big-endian and little-endian input interpretations
 - **Automatic Best Compression**: Try both endian interpretations and automatically select the best result
 - **Multiple Fibonacci Algorithms**: 
   - Slow recursive (memoized, for small numbers)
   - Slow iterative (memoized, for large numbers)
   - Fast Doubling (optimized, ~160x faster for large indices)
+  - Memoized Fast Doubling (with sparse HashMap caching for large, non-contiguous indices)
 - **BigInt Support**: Handle arbitrarily large numbers using `num-bigint`
 - **Memoization**: Thread-safe caching for improved performance
 - **Statistics & Visualization**: Generate compression statistics and plots
 - **Benchmarking**: Comprehensive performance benchmarks
 - **WebAssembly Support**: Available as a WebAssembly module for use in web browsers
+- **Error Handling**: Comprehensive error types for file format operations
 
 ## WebAssembly
 
@@ -44,14 +47,14 @@ Or add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-zeck = "0.1.0"
+zeck = "2.1.0"
 ```
 
 For plotting features:
 
 ```toml
 [dependencies]
-zeck = { version = "0.1.0", features = ["plotting"] }
+zeck = { version = "2.1.0", features = ["plotting"] }
 ```
 
 ### Install from GitHub (development version)
@@ -87,70 +90,130 @@ Or add this to your `package.json`:
 ```json
 {
   "dependencies": {
-    "zeck": "^0.1.0"
+    "zeck": "^2.1.0"
   }
 }
 ```
 
 ## Usage
 
-### Basic Compression/Decompression
+### File Format Compression (Recommended)
 
-#### Big-Endian Interpretation
+The `.zeck` file format automatically handles size preservation and endianness information. This is the recommended approach for most use cases.
+
+#### Big-Endian File Format
 
 ```rust
-use zeck::{zeckendorf_compress_be, zeckendorf_decompress_be};
+use zeck::zeck_file_format::{compress::compress_zeck_be, decompress::decompress_zeck_file};
 
 // Compress data (interpreted as big-endian integer)
 let data = vec![12u8];
-let compressed = zeckendorf_compress_be(&data);
+let zeck_file = compress_zeck_be(&data)?;
 
-// Decompress data
-let decompressed = zeckendorf_decompress_be(&compressed);
+// Serialize to bytes for storage
+let bytes = zeck_file.to_bytes();
+
+// Later, deserialize and decompress
+use zeck::zeck_file_format::file::deserialize_zeck_file;
+let zeck_file = deserialize_zeck_file(&bytes)?;
+let decompressed = decompress_zeck_file(&zeck_file)?;
 assert_eq!(data, decompressed);
 ```
 
-#### Little-Endian Interpretation
+#### Little-Endian File Format
 
 ```rust
-use zeck::{zeckendorf_compress_le, zeckendorf_decompress_le};
+use zeck::zeck_file_format::{compress::compress_zeck_le, decompress::decompress_zeck_file};
 
 // Compress data (interpreted as little-endian integer)
 let data = vec![12u8];
-let compressed = zeckendorf_compress_le(&data);
+let zeck_file = compress_zeck_le(&data)?;
 
 // Decompress data
-let decompressed = zeckendorf_decompress_le(&compressed);
+let decompressed = decompress_zeck_file(&zeck_file)?;
 assert_eq!(data, decompressed);
 ```
 
-#### Automatic Best Compression
+#### Automatic Best Compression (File Format)
 
 ```rust
-use zeck::{zeckendorf_compress_best, zeckendorf_decompress_be, zeckendorf_decompress_le, CompressionResult};
+use zeck::zeck_file_format::{
+    compress::{compress_zeck_best, BestCompressionResult},
+    decompress::decompress_zeck_file,
+};
 
 // Try both endian interpretations and get the best result
 let data = vec![1, 0];
-let result = zeckendorf_compress_best(&data);
-
-match result {
-    CompressionResult::BigEndianBest { compressed_data, le_size } => {
+match compress_zeck_best(&data)? {
+    BestCompressionResult::BigEndianBest { zeck_file, le_size } => {
         // Big-endian produced the best compression
-        let decompressed = zeckendorf_decompress_be(&compressed_data);
+        let decompressed = decompress_zeck_file(&zeck_file)?;
         assert_eq!(data, decompressed);
     }
-    CompressionResult::LittleEndianBest { compressed_data, be_size } => {
+    BestCompressionResult::LittleEndianBest { zeck_file, be_size } => {
         // Little-endian produced the best compression
-        let decompressed = zeckendorf_decompress_le(&compressed_data);
+        let decompressed = decompress_zeck_file(&zeck_file)?;
         assert_eq!(data, decompressed);
     }
-    CompressionResult::Neither { be_size, le_size } => {
+    BestCompressionResult::Neither { be_size, le_size } => {
         // Neither method compressed the data (both were larger than original)
         println!("Neither method compressed: BE size = {}, LE size = {}", be_size, le_size);
     }
 }
 ```
 
+### Padless Compression (Advanced)
+
+The padless compression functions strip leading zero bytes and do not preserve original size information. **You must manually track the original size** if you need to restore leading zeros. These functions are marked as `_dangerous` to indicate they require careful handling.
+
+**⚠️ Important:** The padless functions are lower-level and do not preserve leading zero bytes. Use the file format functions above for most use cases.
+
+#### Big-Endian Padless
+
+```rust
+use zeck::{padless_zeckendorf_compress_be_dangerous, padless_zeckendorf_decompress_be_dangerous};
+
+// Compress data (interpreted as big-endian integer)
+let data = vec![12u8];
+let compressed = padless_zeckendorf_compress_be_dangerous(&data);
+
+// Decompress data (leading zeros may be lost)
+let decompressed = padless_zeckendorf_decompress_be_dangerous(&compressed);
+// Note: decompressed may not equal data if data had leading zeros
+```
+
+#### Little-Endian Padless
+
+```rust
+use zeck::{padless_zeckendorf_compress_le_dangerous, padless_zeckendorf_decompress_le_dangerous};
+
+// Compress data (interpreted as little-endian integer)
+let data = vec![12u8];
+let compressed = padless_zeckendorf_compress_le_dangerous(&data);
+
+// Decompress data (trailing zeros may be lost)
+let decompressed = padless_zeckendorf_decompress_le_dangerous(&compressed);
+```
+
+#### Automatic Best Padless Compression
+
+```rust
+use zeck::{padless_zeckendorf_compress_best_dangerous, PadlessCompressionResult};
+
+let data = vec![1, 0];
+match padless_zeckendorf_compress_best_dangerous(&data) {
+    PadlessCompressionResult::BigEndianBest { compressed_data, le_size } => {
+        // Use padless_zeckendorf_decompress_be_dangerous for decompression
+    }
+    PadlessCompressionResult::LittleEndianBest { compressed_data, be_size } => {
+        // Use padless_zeckendorf_decompress_le_dangerous for decompression
+    }
+    PadlessCompressionResult::Neither { be_size, le_size } => {
+        // Neither method compressed the data
+    }
+}
+```
+
 ### Fibonacci Numbers
 
 ```rust
@@ -160,8 +223,12 @@ use zeck::memoized_slow_fibonacci_recursive;
 let fib_10 = memoized_slow_fibonacci_recursive(10); // Returns 55
 
 // For larger numbers, use BigInt versions
-use zeck::fast_doubling_fibonacci_bigint;
-let fib_100 = fast_doubling_fibonacci_bigint(100);
+use zeck::fast_doubling_fibonacci_biguint;
+let fib_100 = fast_doubling_fibonacci_biguint(100);
+
+// For even better performance with caching, use memoized fast doubling
+use zeck::memoized_fast_doubling_fibonacci_biguint;
+let fib_1000 = memoized_fast_doubling_fibonacci_biguint(1000);
 ```
 
 ### Zeckendorf Representation
@@ -172,8 +239,58 @@ use zeck::memoized_zeckendorf_list_descending_for_integer;
 // Get Zeckendorf representation as a list of Fibonacci indices
 let zld = memoized_zeckendorf_list_descending_for_integer(12);
 // Returns [6, 4, 2] meaning F(6) + F(4) + F(2) = 8 + 3 + 1 = 12
+
+// For BigInt numbers
+use zeck::memoized_zeckendorf_list_descending_for_biguint;
+use num_bigint::BigUint;
+let zld = memoized_zeckendorf_list_descending_for_biguint(&BigUint::from(12u64));
+```
+
+### Utility Functions
+
+The library provides various utility functions for working with Fibonacci numbers and Zeckendorf representations:
+
+```rust
+use zeck::{
+    bit_count_for_number,           // Count bits needed to represent a number
+    highest_one_bit,                 // Get the highest set bit
+    efi_to_fi, fi_to_efi,            // Convert between Effective Fibonacci Index and Fibonacci Index
+    memoized_effective_fibonacci,     // Get Fibonacci number from Effective Fibonacci Index
+    zl_to_ezl, ezl_to_zl,            // Convert between Zeckendorf List and Effective Zeckendorf List
+    all_ones_zeckendorf_to_biguint,   // Create "all ones" Zeckendorf numbers
+    PHI, PHI_SQUARED,                 // Golden ratio constants
+};
+```
+
+### Error Handling
+
+The file format functions return `Result` types with comprehensive error handling:
+
+```rust
+use zeck::zeck_file_format::{compress::compress_zeck_be, error::ZeckFormatError};
+
+match compress_zeck_be(&data) {
+    Ok(zeck_file) => {
+        // Compression succeeded
+    }
+    Err(ZeckFormatError::DataSizeTooLarge { size }) => {
+        // Data size exceeds u64::MAX
+    }
+    Err(e) => {
+        // Handle other errors
+        eprintln!("Compression error: {}", e);
+    }
+}
 ```
 
+Common error types include:
+- `HeaderTooShort`: Input data is too short to contain a valid header
+- `UnsupportedVersion`: File format version is not supported
+- `ReservedFlagsSet`: Reserved flags are set (indicating a newer format)
+- `CompressionFailed`: Compression did not reduce the data size
+- `DecompressedTooLarge`: Decompressed data is larger than expected
+- `DataSizeTooLarge`: Data size exceeds the maximum representable size
+
 ## Binaries
 
 The project includes several utility binaries. The command-line compression tools (`zeck-compress` and `zeck-decompress`) can be installed globally via:
@@ -198,7 +315,7 @@ After installation, you can use `zeck-compress` and `zeck-decompress` directly f
 
 #### zeck-compress
 
-Compresses data using the Zeckendorf representation algorithm. Automatically adds `.zbe` extension for big-endian compression and `.zle` extension for little-endian compression.
+Compresses data using the Zeckendorf representation algorithm. Automatically adds `.zeck` extension for compressed files.
 
 ```bash
 zeck-compress [INPUT] [-o OUTPUT] [--endian ENDIAN] [-v]
@@ -208,13 +325,13 @@ zeck-compress [INPUT] [-o OUTPUT] [--endian ENDIAN] [-v]
 - `INPUT`: Input file path (optional, reads from stdin if not specified)
   - Shows a warning if reading from stdin and no data was piped in
 - `-o, --output FILE`: Output file path (optional)
-  - If not specified and input is a file, uses the input filename with the appropriate extension (`.zbe` or `.zle`) appended
+  - If not specified and input is a file, uses the input filename with the `.zeck` extension appended
   - If not specified and reading from stdin, writes to stdout
-  - The appropriate extension (`.zbe` for big-endian, `.zle` for little-endian) is automatically added unless the file already ends with `.zbe` or `.zle`
+  - The `.zeck` extension is automatically added unless the file already ends with `.zeck`
 - `--endian ENDIAN`: Endianness to use (`big`, `little`, or `best`). Default: `best`
-  - `big`: Use big-endian interpretation (output will have `.zbe` extension)
-  - `little`: Use little-endian interpretation (output will have `.zle` extension)
-  - `best`: Try both and use the best result (default, extension added based on which was used)
+  - `big`: Use big-endian interpretation
+  - `little`: Use little-endian interpretation
+  - `best`: Try both and use the best result (default)
   - **Note:** When using `best`, if neither method produces compression (both result in larger or equal output), the tool will exit with an error showing compression statistics
 - `-v, --verbose`: Show compression statistics (default: true, use `--no-verbose` to disable)
 
@@ -222,74 +339,61 @@ zeck-compress [INPUT] [-o OUTPUT] [--endian ENDIAN] [-v]
 ```bash
 # Compress a file (output filename automatically created from input with extension)
 zeck-compress input.bin
-# Creates input.bin.zbe or input.bin.zle depending on which endianness was used
+# Creates input.bin.zeck
 
 # Compress with best endianness (statistics shown by default)
 zeck-compress input.bin --endian best
 
-# Compress with specific endianness (creates input.bin.zbe)
+# Compress with specific endianness
 zeck-compress input.bin --endian big
 
 # Compress to a specific output file
 zeck-compress input.bin -o output
-# Creates output.zbe or output.zle depending on which endianness was used
+# Creates output.zeck
 
 # Compress from stdin to stdout
 cat input.bin | zeck-compress
 ```
 
-**Note:** When writing to a file, the output filename is printed to stdout (e.g., "Compressed to: input.bin.zbe"). Verbose statistics are shown by default and include descriptive messages about compression ratios (e.g., "File was compressed by X.XX% (Y bytes -> Z bytes)"). A warning is shown when reading from stdin if no data was piped in.
+**Note:** When writing to a file, the output filename is printed to stdout (e.g., "Compressed to: input.bin.zeck"). Verbose statistics are shown by default and include descriptive messages about compression ratios (e.g., "File was compressed by X.XX% (Y bytes -> Z bytes)"). A warning is shown when reading from stdin if no data was piped in.
 
 #### zeck-decompress
 
-Decompresses data that was compressed using the Zeckendorf representation algorithm. Automatically detects endianness from file extension (`.zbe` for big-endian, `.zle` for little-endian).
+Decompresses data that was compressed using the Zeckendorf representation algorithm. Automatically detects endianness from the file header.
 
 ```bash
-zeck-decompress [INPUT] [-o OUTPUT] [--endian ENDIAN] [-v]
+zeck-decompress [INPUT] [-o OUTPUT] [-v]
 ```
 
 **Options:**
 - `INPUT`: Input file path (optional, reads from stdin if not specified)
-  - When reading from a file, endianness is automatically detected from file extension (`.zbe` for big-endian, `.zle` for little-endian)
-  - **If extension is not recognized, `--endian` is REQUIRED** (exits with error if not specified)
-  - **When reading from stdin, `--endian` is REQUIRED**
+  - When reading from a file, endianness is automatically detected from the file header
+  - When reading from stdin, endianness is automatically detected from the file header
   - Shows a warning if reading from stdin and no data was piped in
 - `-o, --output FILE`: Output file path (optional)
-  - If not specified and input is a file, uses the input filename with `.zbe` or `.zle` extension removed
+  - If not specified and input is a file, uses the input filename with `.zeck` extension removed
   - If not specified and reading from stdin, writes to stdout
-- `--endian ENDIAN`: Endianness used during compression (`big` or `little`)
-  - `big`: Decompress as big-endian
-  - `little`: Decompress as little-endian
-  - **REQUIRED when reading from stdin** (no input file specified)
-  - When reading from a file, this option overrides automatic detection from file extension
 - `-v, --verbose`: Show decompression statistics (default: true, use `--no-verbose` to disable)
 
 **Examples:**
 ```bash
-# Decompress a file (endianness detected from .zbe extension, output filename automatically created)
-zeck-decompress input.zbe
-# Automatically uses big-endian decompression, creates output file "input"
-
-# Decompress with little-endian file
-zeck-decompress input.zle
-# Automatically uses little-endian decompression, creates output file "input"
+# Decompress a file (endianness detected from file header, output filename automatically created)
+zeck-decompress input.zeck
+# Automatically detects endianness from header, creates output file "input"
 
 # Decompress to a specific output file
-zeck-decompress input.zbe -o output.bin
-# Automatically uses big-endian decompression
-
-# Override automatic detection
-zeck-decompress input.zbe --endian little -o output.bin
-# Overrides the .zbe extension and uses little-endian
+zeck-decompress input.zeck -o output.bin
+# Automatically detects endianness from header
 
-# Decompress from stdin to stdout (--endian is required)
-cat input.zbe | zeck-decompress --endian big
+# Decompress from stdin to stdout
+cat input.zeck | zeck-decompress
+# Automatically detects endianness from header
 ```
 
-**Note:** The endianness used for decompression must match the endianness used during compression. The file extension (`.zbe` or `.zle`) indicates which endianness was used, so decompression will automatically use the correct endianness when reading from a file. **If the input file doesn't have a recognized extension, `--endian` must be explicitly specified** (the tool will exit with an error if not provided). You can override automatic detection with the `--endian` flag if needed. **When reading from stdin, `--endian` must be explicitly specified** since there's no file extension to detect from.
+**Note:** The endianness used for decompression must match the endianness used during compression. The file header stores which endianness was used, so decompression will automatically use the correct endianness when reading from a file or from stdin.
 
 **Additional features:**
-- When writing to a file, the output filename is printed to stdout (e.g., "Compressed to: input.bin.zbe" or "Decompressed to: output.bin")
+- When writing to a file, the output filename is printed to stdout (e.g., "Compressed to: input.bin.zeck" or "Decompressed to: output.bin")
 - Verbose statistics are shown by default (use `--no-verbose` to disable) and include descriptive messages about compression/decompression ratios
 - Compression will exit with an error if the data cannot be compressed (when using `--endian best` and neither method produces compression)
 - A warning is shown when reading from stdin if no data was piped in
@@ -297,7 +401,7 @@ cat input.zbe | zeck-decompress --endian big
 ### Main Playground
 
 ```bash
-cargo run --release --bin zeck
+cargo run --release --bin zeck-playground --features development_tools
 ```
 
 A playground/scratchpad for testing library functions.
@@ -373,6 +477,7 @@ cargo bench --bench zeckendorf_bench -- --baseline <name>
 ## Performance Characteristics
 
 - **Fast Doubling Fibonacci**: ~160x faster than iterative method for the 100,000th Fibonacci number
+- **Memoized Fast Doubling**: Uses sparse HashMap caching for efficient memory usage with large, non-contiguous Fibonacci indices
 - **Memoization**: Thread-safe caching significantly improves repeated calculations. The trade-off is that the cache takes up memory.
 - **Compression Effectiveness**: Varies by input; compression ratios oscillate and become less favorable as input size increases
 
@@ -385,12 +490,23 @@ Every positive integer can be uniquely represented as a sum of non-consecutive F
 
 ### Compression Process
 
-1. Input data is interpreted as either a big-endian or little-endian integer (you can choose, or use `zeckendorf_compress_best` to try both)
+1. Input data is interpreted as either a big-endian or little-endian integer (you can choose, or use `compress_zeck_best` to try both)
 2. The integer is converted to its Zeckendorf representation (list of Fibonacci indices)
 3. The representation is encoded as bits (use/skip bits)
 4. Bits are packed into bytes (little-endian output)
 
-The library provides functions to compress with either interpretation, or you can use `zeckendorf_compress_best` to automatically try both and select the one that produces the smallest output.
+The library provides functions to compress with either interpretation, or you can use `compress_zeck_best` to automatically try both and select the one that produces the smallest output.
+
+### File Format
+
+The `.zeck` file format includes a 10-byte header:
+- **Version** (1 byte): File format version (currently 1)
+- **Original Size** (8 bytes): Original uncompressed file size in bytes (little-endian)
+- **Flags** (1 byte): Endianness and reserved flags
+  - Bit 0: Big endian flag (1 = big endian, 0 = little endian)
+  - Bits 1-7: Reserved for future use
+
+The header is followed by the compressed data. This format automatically preserves the original file size, allowing proper restoration of leading or trailing zero bytes during decompression.
 
 ### Effective Fibonacci Indices
 
@@ -407,10 +523,11 @@ This avoids redundant Fibonacci numbers (F(0)=0 and F(1)=F(2)=1).
 - Compression effectiveness decreases as input size increases
 - The library supports both big-endian and little-endian interpretations, but other byte orderings or word boundaries are not currently explored
 - **⚠️ Warning:** Compressing or decompressing files larger than 10KB (10,000 bytes) is unstable due to time and memory pressure. The library may experience performance issues, excessive memory usage, or failures when processing files exceeding this size.
+- Padless compression functions (`*_dangerous`) do not preserve leading/trailing zero bytes—use the file format functions for automatic size preservation
 
 ## NPM Versioning Quirk
 
-For some reason, NPM was showing there were versions of zeck published between `1.0.0` and `1.0.6` from 2024, even though I never published them to npm. I don't know how this happened. So I bumped the version to `1.0.7` and was able to successfully publish it to npm. Maybe there was an old package with the same name that was deleted, and NPM is still showing the old versions.
+For some reason, NPM was showing there were versions of zeck published between `1.0.0` and `1.0.6` from 2024 (we are in 2026), even though I never published them to npm. I don't know how this happened. So I bumped the version to `1.0.7` and was able to successfully publish it to npm. Maybe there was an old package with the same name that was deleted, and NPM is still showing the old versions.
 
 Here is a snippet of the `time` object from the npm registry JSON (https://registry.npmjs.org/zeck):
 
@@ -442,3 +559,4 @@ Contributions are welcome! Please feel free to submit a Pull Request. For major
 
 - [Fast Fibonacci Algorithms](https://www.nayuki.io/page/fast-fibonacci-algorithms) - Fast doubling algorithm reference
 - [Zeckendorf's Theorem](https://en.wikipedia.org/wiki/Zeckendorf%27s_theorem) - Every positive integer has a unique representation as a sum of non-consecutive Fibonacci numbers
+- [Exploring Fibonacci Based Compression](https://medium.com/@peterryszkiewicz/exploring-fibonacci-based-compression-8713770f5598) - My blog post about the Zeckendorf representation algorithm and this library

package/package.json

@@ -5,7 +5,7 @@
     "Peter Ryszkiewicz"
   ],
   "description": "A Rust library for compressing and decompressing data using the Zeckendorf representation algorithm",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "license": "MIT",
   "repository": {
     "type": "git",

package/zeck.d.ts

@@ -1,11 +1,25 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * Result of best compression attempt, containing the best compressed zeck file and the size for the other endianness attempt, or if neither produced compression (both were larger than the original).
+ */
+export type BestCompressionResult = { BigEndianBest: { zeck_file: ZeckFile; le_size: number } } | { LittleEndianBest: { zeck_file: ZeckFile; be_size: number } } | { Neither: { be_size: number; le_size: number } };
+
+/**
+ * Errors that can occur when parsing or processing .zeck files.
+ */
+export type ZeckFormatError = { HeaderTooShort: { actual_length: number; required_length: number } } | { UnsupportedVersion: { found_version: number; supported_version: number } } | { ReservedFlagsSet: { flags: number } } | { CompressionFailed: { original_size: number; be_size: number; le_size: number } } | { DecompressedTooLarge: { expected_size: number; actual_size: number } } | { DataSizeTooLarge: { size: number } };
+
 /**
  * Represents a .zeck file with its header information and compressed data.
  *
  * This struct holds all the information needed to reconstruct a .zeck file,
  * including the format version, original file size, endianness flags, and
  * the compressed data itself.
+ *
+ * Using `derive(Serialize, Deserialize, Tsify)` and `tsify(into_wasm_abi, from_wasm_abi)` on the struct is necessary
+ * to allow the struct to be used in the WebAssembly module, namely because the `compressed_data` field is
+ * a [`Vec<u8>`], which needed [`Copy`], and the [`wasm_bindgen`] attribute was insufficient to achieve this.
  */
 export interface ZeckFile {
     /**
@@ -26,16 +40,6 @@ export interface ZeckFile {
     compressed_data: number[];
 }
 
-/**
- * Result of best compression attempt, containing the best compressed zeck file and the size for the other endianness attempt, or if neither produced compression (both were larger than the original).
- */
-export type BestCompressionResult = { BigEndianBest: { zeck_file: ZeckFile; le_size: number } } | { LittleEndianBest: { zeck_file: ZeckFile; be_size: number } } | { Neither: { be_size: number; le_size: number } };
-
-/**
- * Errors that can occur when parsing or processing .zeck files.
- */
-export type ZeckFormatError = { HeaderTooShort: { actual_length: number; required_length: number } } | { UnsupportedVersion: { found_version: number; supported_version: number } } | { ReservedFlagsSet: { flags: number } } | { CompressionFailed: { original_size: number; be_size: number; le_size: number } } | { DecompressedTooLarge: { expected_size: number; actual_size: number } } | { DataSizeTooLarge: { size: number } };
-
 
 /**
  * Returns the number of bits required to represent the given number. Returns 0 if the number is less than or equal to 0.
@@ -176,6 +180,64 @@ export function compress_zeck_best(data: Uint8Array): BestCompressionResult;
  */
 export function compress_zeck_le(data: Uint8Array): ZeckFile;
 
+/**
+ * Decompresses data from a [`ZeckFile`] struct.
+ *
+ * This function takes a [`ZeckFile`] directly and uses its header information to decompress
+ * the data. This is a convenience function that avoids the need to serialize and parse the
+ * file format when you already have a [`ZeckFile`] struct.
+ *
+ * # ⚠️ Warning
+ *
+ * **Compressing or decompressing data larger than 10KB (10,000 bytes) is unstable due to time and memory pressure.**
+ * The library may experience performance issues, excessive memory usage, or failures when processing data exceeding this size.
+ *
+ * # Examples
+ *
+ * ```
+ * # use zeck::zeck_file_format::{compress::compress_zeck_le, decompress::decompress_zeck_file};
+ * let original = vec![0, 1];
+ * let zeck_file = compress_zeck_le(&original).unwrap();
+ * match decompress_zeck_file(&zeck_file) {
+ *     Ok(decompressed) => {
+ *         assert_eq!(decompressed, original);
+ *     }
+ *     Err(e) => {
+ *         // Handle error
+ *         assert!(false);
+ *     }
+ * }
+ * ```
+ */
+export function decompress_zeck_file(zeck_file: ZeckFile): Uint8Array;
+
+/**
+ * Deserializes a .zeck file from raw bytes into a [`ZeckFile`] struct.
+ *
+ * This function reads the header to determine the file format version, original size, and endianness,
+ * and constructs a [`ZeckFile`] struct. To decompress the data, call [`crate::zeck_file_format::decompress::decompress_zeck_file`] on the result.
+ *
+ * # Examples
+ *
+ * ```
+ * # use zeck::zeck_file_format::{compress::compress_zeck_le, file::deserialize_zeck_file, decompress::decompress_zeck_file};
+ * let original = vec![0, 1];
+ * let zeck_file = compress_zeck_le(&original).unwrap();
+ * let zeck_file_bytes = zeck_file.to_bytes();
+ * match deserialize_zeck_file(&zeck_file_bytes) {
+ *     Ok(zeck_file) => {
+ *         let decompressed = decompress_zeck_file(&zeck_file).unwrap();
+ *         assert_eq!(decompressed, original);
+ *     }
+ *     Err(e) => {
+ *         // Handle error
+ *         assert!(false);
+ *     }
+ * }
+ * ```
+ */
+export function deserialize_zeck_file(zeck_file_data: Uint8Array): ZeckFile;
+
 /**
  * Effective Fibonacci Index to Fibonacci Index: FI(efi) === efi + 2, where efi is the Effective Fibonacci Index
  *
@@ -543,6 +605,16 @@ export function padless_zeckendorf_decompress_le_dangerous(compressed_data: Uint
  */
 export function unpack_bytes_to_ezba_bits(bytes: Uint8Array): Uint8Array;
 
+/**
+ * We need to make public standalone functions on ZeckFile because for some reason, the #[wasm_bindgen] attribute doesn't seem to work on the struct methods. Maybe using Tsify on ZeckFile is causing the issue.
+ * This is a workaround to allow the functions to be used in the WebAssembly module.
+ */
+export function zeck_file_is_big_endian(zeck_file: ZeckFile): boolean;
+
+export function zeck_file_to_bytes(zeck_file: ZeckFile): Uint8Array;
+
+export function zeck_file_total_size(zeck_file: ZeckFile): number;
+
 /**
  * An Effective Zeckendorf List (EZL) has a lowest EFI of 0, which is an FI of 2.
  * This is because it doesn't make sense for the lists to contain FIs 0 or 1 because

package/zeck_bg.js

@@ -27,6 +27,14 @@ function getBigUint64ArrayMemory0() {
     return cachedBigUint64ArrayMemory0;
 }
 
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
 function getStringFromWasm0(ptr, len) {
     ptr = ptr >>> 0;
     return decodeText(ptr, len);
@@ -49,6 +57,10 @@ function handleError(f, args) {
     }
 }
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
 function passArray64ToWasm0(arg, malloc) {
     const ptr = malloc(arg.length * 8, 8) >>> 0;
     getBigUint64ArrayMemory0().set(arg, ptr / 8);
@@ -63,6 +75,43 @@ function passArray8ToWasm0(arg, malloc) {
     return ptr;
 }
 
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
 function takeFromExternrefTable0(idx) {
     const value = wasm.__wbindgen_externrefs.get(idx);
     wasm.__externref_table_dealloc(idx);
@@ -83,6 +132,19 @@ function decodeText(ptr, len) {
     return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
 }
 
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    }
+}
+
 let WASM_VECTOR_LEN = 0;
 
 /**
@@ -259,6 +321,84 @@ export function compress_zeck_le(data) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Decompresses data from a [`ZeckFile`] struct.
+ *
+ * This function takes a [`ZeckFile`] directly and uses its header information to decompress
+ * the data. This is a convenience function that avoids the need to serialize and parse the
+ * file format when you already have a [`ZeckFile`] struct.
+ *
+ * # ⚠️ Warning
+ *
+ * **Compressing or decompressing data larger than 10KB (10,000 bytes) is unstable due to time and memory pressure.**
+ * The library may experience performance issues, excessive memory usage, or failures when processing data exceeding this size.
+ *
+ * # Examples
+ *
+ * ```
+ * # use zeck::zeck_file_format::{compress::compress_zeck_le, decompress::decompress_zeck_file};
+ * let original = vec![0, 1];
+ * let zeck_file = compress_zeck_le(&original).unwrap();
+ * match decompress_zeck_file(&zeck_file) {
+ *     Ok(decompressed) => {
+ *         assert_eq!(decompressed, original);
+ *     }
+ *     Err(e) => {
+ *         // Handle error
+ *         assert!(false);
+ *     }
+ * }
+ * ```
+ * @param {ZeckFile} zeck_file
+ * @returns {Uint8Array}
+ */
+export function decompress_zeck_file(zeck_file) {
+    const ret = wasm.decompress_zeck_file(zeck_file);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v1 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v1;
+}
+
+/**
+ * Deserializes a .zeck file from raw bytes into a [`ZeckFile`] struct.
+ *
+ * This function reads the header to determine the file format version, original size, and endianness,
+ * and constructs a [`ZeckFile`] struct. To decompress the data, call [`crate::zeck_file_format::decompress::decompress_zeck_file`] on the result.
+ *
+ * # Examples
+ *
+ * ```
+ * # use zeck::zeck_file_format::{compress::compress_zeck_le, file::deserialize_zeck_file, decompress::decompress_zeck_file};
+ * let original = vec![0, 1];
+ * let zeck_file = compress_zeck_le(&original).unwrap();
+ * let zeck_file_bytes = zeck_file.to_bytes();
+ * match deserialize_zeck_file(&zeck_file_bytes) {
+ *     Ok(zeck_file) => {
+ *         let decompressed = decompress_zeck_file(&zeck_file).unwrap();
+ *         assert_eq!(decompressed, original);
+ *     }
+ *     Err(e) => {
+ *         // Handle error
+ *         assert!(false);
+ *     }
+ * }
+ * ```
+ * @param {Uint8Array} zeck_file_data
+ * @returns {ZeckFile}
+ */
+export function deserialize_zeck_file(zeck_file_data) {
+    const ptr0 = passArray8ToWasm0(zeck_file_data, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.deserialize_zeck_file(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Effective Fibonacci Index to Fibonacci Index: FI(efi) === efi + 2, where efi is the Effective Fibonacci Index
  *
@@ -739,6 +879,37 @@ export function unpack_bytes_to_ezba_bits(bytes) {
     return v2;
 }
 
+/**
+ * We need to make public standalone functions on ZeckFile because for some reason, the #[wasm_bindgen] attribute doesn't seem to work on the struct methods. Maybe using Tsify on ZeckFile is causing the issue.
+ * This is a workaround to allow the functions to be used in the WebAssembly module.
+ * @param {ZeckFile} zeck_file
+ * @returns {boolean}
+ */
+export function zeck_file_is_big_endian(zeck_file) {
+    const ret = wasm.zeck_file_is_big_endian(zeck_file);
+    return ret !== 0;
+}
+
+/**
+ * @param {ZeckFile} zeck_file
+ * @returns {Uint8Array}
+ */
+export function zeck_file_to_bytes(zeck_file) {
+    const ret = wasm.zeck_file_to_bytes(zeck_file);
+    var v1 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v1;
+}
+
+/**
+ * @param {ZeckFile} zeck_file
+ * @returns {number}
+ */
+export function zeck_file_total_size(zeck_file) {
+    const ret = wasm.zeck_file_total_size(zeck_file);
+    return ret >>> 0;
+}
+
 /**
  * An Effective Zeckendorf List (EZL) has a lowest EFI of 0, which is an FI of 2.
  * This is because it doesn't make sense for the lists to contain FIs 0 or 1 because
@@ -767,6 +938,20 @@ export function zl_to_ezl(zl) {
     return v2;
 }
 
+export function __wbg___wbindgen_is_undefined_f6b95eab589e0269(arg0) {
+    const ret = arg0 === undefined;
+    return ret;
+};
+
+export function __wbg___wbindgen_string_get_a2a31e16edf96e42(arg0, arg1) {
+    const obj = arg1;
+    const ret = typeof(obj) === 'string' ? obj : undefined;
+    var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+};
+
 export function __wbg___wbindgen_throw_dd24417ed36fc46e(arg0, arg1) {
     throw new Error(getStringFromWasm0(arg0, arg1));
 };
@@ -776,6 +961,11 @@ export function __wbg_parse_a09a54cf72639456() { return handleError(function (ar
     return ret;
 }, arguments) };
 
+export function __wbg_stringify_655a6390e1f5eb6b() { return handleError(function (arg0) {
+    const ret = JSON.stringify(arg0);
+    return ret;
+}, arguments) };
+
 export function __wbindgen_init_externref_table() {
     const table = wasm.__wbindgen_externrefs;
     const offset = table.grow(4);