zeck 0.2.0 → 2.0.0

package/README.md

@@ -6,6 +6,8 @@ A Rust library for compressing and decompressing data using the Zeckendorf repre
 
 The Zeckendorf algorithm represents numbers as a sum of non-consecutive Fibonacci numbers. This library interprets input data as a big integer (either big-endian or little-endian), converts it to its Zeckendorf representation, and sometimes achieves compression. However, compression is not guaranteed; the algorithm may result in a larger representation depending on the input data. The library can automatically try both endian interpretations and select the one that produces the best compression.
 
+**⚠️ 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.
+
 **Command-line tools** (`zeck-compress` and `zeck-decompress`) are available and can be installed via `cargo install zeck`. See the [Binaries](#binaries) section for usage details.
 
 ## Features
@@ -192,6 +194,8 @@ After installation, you can use `zeck-compress` and `zeck-decompress` directly f
 
 ### Compression/Decompression Tools
 
+**⚠️ 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.
+
 #### zeck-compress
 
 Compresses data using the Zeckendorf representation algorithm. Automatically adds `.zbe` extension for big-endian compression and `.zle` extension for little-endian compression.
@@ -301,20 +305,20 @@ A playground/scratchpad for testing library functions.
 ### Generate Test Data
 
 ```bash
-cargo run --release --bin generate_data <size_in_bytes> [filename]
+cargo run --release --bin zeck-generate-data --features development_tools -- <size_in_bytes> [filename]
 ```
 
 Generates random test data files in the `generated_data/` directory.
 
 Example:
 ```bash
-cargo run --release --bin generate_data 1024 my_file.bin
+cargo run --release --bin zeck-generate-data --features development_tools -- 1024 my_file.bin
 ```
 
 ### Generate Statistics
 
 ```bash
-cargo run --release --bin generate_statistics --features plotting
+cargo run --release --bin zeck-generate-statistics --features plotting,development_tools
 ```
 
 Generates comprehensive compression statistics and plots:
@@ -327,7 +331,7 @@ Generates comprehensive compression statistics and plots:
 ### Plot Compression Ratios
 
 ```bash
-cargo run --release --bin plot --features plotting
+cargo run --release --bin zeck-plot --features plotting,development_tools
 ```
 
 Generates visualization plots of:
@@ -402,7 +406,29 @@ This avoids redundant Fibonacci numbers (F(0)=0 and F(1)=F(2)=1).
 - Compression is not guaranteed—some inputs may result in larger output
 - 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
-- Compression of large amounts of data causes memory issues. It is currently not recommended to compress files larger than 100,000 bytes.
+- **⚠️ 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.
+
+## 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.
+
+Here is a snippet of the `time` object from the npm registry JSON (https://registry.npmjs.org/zeck):
+
+```json
+  "time": {
+    "created": "2026-01-02T20:19:14.018Z",
+    "modified": "2026-01-03T17:25:15.940Z",
+    "1.0.0": "2024-02-21T14:36:36.292Z",
+    "1.0.1": "2024-02-21T15:26:38.621Z",
+    "1.0.2": "2024-02-21T15:36:30.258Z",
+    "1.0.3": "2024-02-21T15:48:07.853Z",
+    "1.0.4": "2024-02-21T15:48:38.804Z",
+    "1.0.5": "2024-02-21T16:02:36.339Z",
+    "1.0.6": "2024-02-21T16:36:36.643Z",
+    "0.1.0": "2026-01-02T20:19:14.175Z",
+    "0.2.0": "2026-01-03T17:25:15.702Z"
+  },
+```
 
 ## License
 

package/package.json

@@ -5,18 +5,17 @@
     "Peter Ryszkiewicz"
   ],
   "description": "A Rust library for compressing and decompressing data using the Zeckendorf representation algorithm",
-  "version": "0.2.0",
+  "version": "2.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pRizz/zeckendorf"
+    "url": "https://github.com/pRizz/zeckendorf.git"
   },
   "files": [
     "zeck_bg.wasm",
     "zeck.js",
     "zeck_bg.js",
-    "zeck.d.ts",
-    "LICENSE.txt"
+    "zeck.d.ts"
   ],
   "main": "zeck.js",
   "types": "zeck.d.ts",

package/zeck.d.ts

@@ -236,95 +236,153 @@ export function memoized_zeckendorf_list_descending_for_integer(n: bigint): BigU
 export function pack_ezba_bits_to_bytes(ezba: Uint8Array): Uint8Array;
 
 /**
- * Unpacks a vector of bytes into a vector of bits (0s and 1s) from an ezba (Effective Zeckendorf Bits Ascending).
+ * Compresses a slice of bytes using the Padless Zeckendorf Compression algorithm.
+ *
+ * Assumes the input data is interpreted as a big endian integer. The output data is in little endian order, so the first bit and byte is the least significant bit and byte and the last bit and byte is the most significant bit and byte.
+ *
+ * # ⚠️ Important: Original Size Preservation
+ *
+ * **This function strips leading zero bytes from the input data during compression.**
+ * It is the caller's responsibility to retain the original size information (e.g., `data.len()`)
+ * before calling this function. When decompressing, the original size must be used to pad the
+ * decompressed data with leading zeros to restore the exact original data. Without the original
+ * size, information will be lost during decompression.
+ *
+ * For a format that automatically handles size preservation, use [`crate::zeck_file_format::compress::compress_zeck_be`]
+ * instead, which includes a header with the original size information.
+ *
+ * # ⚠️ 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.
+ *
+ * TODO: Technically, the way the input data is interpreted is arbitrary; we could interpret it as little endian which could result in a more compact representation. We could go even further and interpret the data at different byte or word boundaries to see if it results in a more compact representation, and signify to the caller which interpretation was used. We probably need a better understanding of random distributions of data to determine what is the optimal interpretation. More investigation is needed here.
  *
  * # Examples
  *
  * ```
- * # use zeck::unpack_bytes_to_ezba_bits;
- * assert_eq!(unpack_bytes_to_ezba_bits(&[0]), vec![0, 0, 0, 0, 0, 0, 0, 0]);
- * assert_eq!(unpack_bytes_to_ezba_bits(&[1]), vec![1, 0, 0, 0, 0, 0, 0, 0]);
- * assert_eq!(unpack_bytes_to_ezba_bits(&[0b111]), vec![1, 1, 1, 0, 0, 0, 0, 0]);
- * assert_eq!(unpack_bytes_to_ezba_bits(&[1, 1]), vec![1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0]);
+ * # use zeck::padless_zeckendorf_compress_be_dangerous;
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[0]), vec![0]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[1]), vec![1]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[12]), vec![0b111]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[54]), vec![30]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[55]), vec![0, 1]); // 55 is the 10 indexed Fibonacci number, which is the 8 indexed effective Fibonacci number, and therefore is the first number needing two bytes to contain these 8 bits, because there is 1 "use bit" and 7 "skip bits" in the effective zeckendorf bits ascending.
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[255]), vec![33, 2]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[1, 0]), vec![34, 2]);
  * ```
  */
-export function unpack_bytes_to_ezba_bits(bytes: Uint8Array): Uint8Array;
+export function padless_zeckendorf_compress_be_dangerous(data: Uint8Array): Uint8Array;
 
 /**
- * Compresses a slice of bytes using the Zeckendorf algorithm.
+ * Compresses a slice of bytes using the Padless Zeckendorf Compression algorithm.
  *
- * Assumes the input data is interpreted as a big endian integer. The output data is in little endian order, so the first bit and byte is the least significant bit and byte and the last bit and byte is the most significant bit and byte.
+ * Assumes the input data is interpreted as a little endian integer. The output data is in little endian order, so the first bit and byte is the least significant bit and byte and the last bit and byte is the most significant bit and byte.
  *
- * TODO: Technically, the way the input data is interpreted is arbitrary; we could interpret it as little endian which could result in a more compact representation. We could go even further and interpret the data at different byte or word boundaries to see if it results in a more compact representation, and signify to the caller which interpretation was used. We probably need a better understanding of random distributions of data to determine what is the optimal interpretation. More investigation is needed here.
+ * # ⚠️ Important: Original Size Preservation
+ *
+ * **This function strips leading zero bytes from the input data during compression.**
+ * It is the caller's responsibility to retain the original size information (e.g., `data.len()`)
+ * before calling this function. When decompressing, the original size must be used to pad the
+ * decompressed data with leading zeros to restore the exact original data. Without the original
+ * size, information will be lost during decompression.
+ *
+ * For a format that automatically handles size preservation, use [`crate::zeck_file_format::compress::compress_zeck_le`]
+ * instead, which includes a header with the original size information.
+ *
+ * # ⚠️ 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::zeckendorf_compress_be;
- * assert_eq!(zeckendorf_compress_be(&[0]), vec![0]);
- * assert_eq!(zeckendorf_compress_be(&[1]), vec![1]);
- * assert_eq!(zeckendorf_compress_be(&[12]), vec![0b111]);
- * assert_eq!(zeckendorf_compress_be(&[54]), vec![30]);
- * assert_eq!(zeckendorf_compress_be(&[55]), vec![0, 1]); // 55 is the 10 indexed Fibonacci number, which is the 8 indexed effective Fibonacci number, and therefore is the first number needing two bytes to contain these 8 bits, because there is 1 "use bit" and 7 "skip bits" in the effective zeckendorf bits ascending.
- * assert_eq!(zeckendorf_compress_be(&[255]), vec![33, 2]);
- * assert_eq!(zeckendorf_compress_be(&[1, 0]), vec![34, 2]);
+ * # use zeck::padless_zeckendorf_compress_le_dangerous;
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[0]), vec![0]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[1]), vec![1]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[12]), vec![0b111]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[54]), vec![30]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[55]), vec![0, 1]); // 55 is the 10 indexed Fibonacci number, which is the 8 indexed effective Fibonacci number, and therefore is the first number needing two bytes to contain these 8 bits, because there is 1 "use bit" and 7 "skip bits" in the effective zeckendorf bits ascending.
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[255]), vec![33, 2]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[0, 1]), vec![34, 2]);
  * ```
  */
-export function zeckendorf_compress_be(data: Uint8Array): Uint8Array;
+export function padless_zeckendorf_compress_le_dangerous(data: Uint8Array): Uint8Array;
 
 /**
- * Compresses a slice of bytes using the Zeckendorf algorithm.
+ * Decompresses a slice of bytes compressed using the Zeckendorf algorithm, assuming the original data was compressed using the big endian bytes interpretation.
  *
- * Assumes the input data is interpreted as a little endian integer. The output data is in little endian order, so the first bit and byte is the least significant bit and byte and the last bit and byte is the most significant bit and byte.
+ * Assume the original input data was interpreted as a big endian integer, for now. See the TODO in the [`padless_zeckendorf_compress_be_dangerous`] function for more information.
+ *
+ * # ⚠️ Important: Leading Zero Padding
+ *
+ * **This function does not pad leading zero bytes.** If the original data had leading zeros, they will not be restored.
+ * The decompressed output will be the minimal representation of the number (without leading zeros).
+ *
+ * For a format that automatically handles size preservation and padding, use [`crate::zeck_file_format::file::deserialize_zeck_file`]
+ * and [`crate::zeck_file_format::decompress::decompress_zeck_file`] instead, which includes a header with the original size information and restores leading zeros.
+ *
+ * # ⚠️ 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::zeckendorf_compress_le;
- * assert_eq!(zeckendorf_compress_le(&[0]), vec![0]);
- * assert_eq!(zeckendorf_compress_le(&[1]), vec![1]);
- * assert_eq!(zeckendorf_compress_le(&[12]), vec![0b111]);
- * assert_eq!(zeckendorf_compress_le(&[54]), vec![30]);
- * assert_eq!(zeckendorf_compress_le(&[55]), vec![0, 1]); // 55 is the 10 indexed Fibonacci number, which is the 8 indexed effective Fibonacci number, and therefore is the first number needing two bytes to contain these 8 bits, because there is 1 "use bit" and 7 "skip bits" in the effective zeckendorf bits ascending.
- * assert_eq!(zeckendorf_compress_le(&[255]), vec![33, 2]);
- * assert_eq!(zeckendorf_compress_le(&[0, 1]), vec![34, 2]);
+ * # use zeck::padless_zeckendorf_decompress_be_dangerous;
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[0]), vec![0]);
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[1]), vec![1]);
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[0b111]), vec![12]);
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[33, 2]), vec![255]);
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[34, 2]), vec![1, 0]);
  * ```
  */
-export function zeckendorf_compress_le(data: Uint8Array): Uint8Array;
+export function padless_zeckendorf_decompress_be_dangerous(compressed_data: Uint8Array): Uint8Array;
 
 /**
- * Decompresses a slice of bytes compressed using the Zeckendorf algorithm, assuming the original data was compressed using the big endian bytes interpretation.
+ * Decompresses a slice of bytes compressed using the Zeckendorf algorithm, assuming the original data was compressed using the little endian bytes interpretation.
+ *
+ * # ⚠️ Important: Leading Zero Padding
  *
- * Assume the original input data was interpreted as a big endian integer, for now. See the TODO in the [`zeckendorf_compress_be`] function for more information.
+ * **This function does not pad leading zero bytes.** If the original data had leading zeros, they will not be restored.
+ * The decompressed output will be the minimal representation of the number (without leading zeros).
+ *
+ * For a format that automatically handles size preservation and padding, use [`crate::zeck_file_format::file::deserialize_zeck_file`]
+ * and [`crate::zeck_file_format::decompress::decompress_zeck_file`] instead, which includes a header with the original size information and restores leading zeros.
+ *
+ * # ⚠️ 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::zeckendorf_decompress_be;
- * assert_eq!(zeckendorf_decompress_be(&[0]), vec![0]);
- * assert_eq!(zeckendorf_decompress_be(&[1]), vec![1]);
- * assert_eq!(zeckendorf_decompress_be(&[0b111]), vec![12]);
- * assert_eq!(zeckendorf_decompress_be(&[33, 2]), vec![255]);
- * assert_eq!(zeckendorf_decompress_be(&[34, 2]), vec![1, 0]);
+ * # use zeck::padless_zeckendorf_decompress_le_dangerous;
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[0]), vec![0]);
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[1]), vec![1]);
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[0b111]), vec![12]);
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[33, 2]), vec![255]);
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[34, 2]), vec![0, 1]);
  * ```
  */
-export function zeckendorf_decompress_be(compressed_data: Uint8Array): Uint8Array;
+export function padless_zeckendorf_decompress_le_dangerous(compressed_data: Uint8Array): Uint8Array;
 
 /**
- * Decompresses a slice of bytes compressed using the Zeckendorf algorithm, assuming the original data was compressed using the little endian bytes interpretation.
+ * Unpacks a vector of bytes into a vector of bits (0s and 1s) from an ezba (Effective Zeckendorf Bits Ascending).
  *
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_decompress_le;
- * assert_eq!(zeckendorf_decompress_le(&[0]), vec![0]);
- * assert_eq!(zeckendorf_decompress_le(&[1]), vec![1]);
- * assert_eq!(zeckendorf_decompress_le(&[0b111]), vec![12]);
- * assert_eq!(zeckendorf_decompress_le(&[33, 2]), vec![255]);
- * assert_eq!(zeckendorf_decompress_le(&[34, 2]), vec![0, 1]);
+ * # use zeck::unpack_bytes_to_ezba_bits;
+ * assert_eq!(unpack_bytes_to_ezba_bits(&[0]), vec![0, 0, 0, 0, 0, 0, 0, 0]);
+ * assert_eq!(unpack_bytes_to_ezba_bits(&[1]), vec![1, 0, 0, 0, 0, 0, 0, 0]);
+ * assert_eq!(unpack_bytes_to_ezba_bits(&[0b111]), vec![1, 1, 1, 0, 0, 0, 0, 0]);
+ * assert_eq!(unpack_bytes_to_ezba_bits(&[1, 1]), vec![1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0]);
  * ```
  */
-export function zeckendorf_decompress_le(compressed_data: Uint8Array): Uint8Array;
+export function unpack_bytes_to_ezba_bits(bytes: Uint8Array): Uint8Array;
 
 /**
  * An Effective Zeckendorf List (EZL) has a lowest EFI of 0, which is an FI of 2.

package/zeck_bg.js

@@ -353,136 +353,194 @@ export function pack_ezba_bits_to_bytes(ezba) {
 }
 
 /**
- * Unpacks a vector of bytes into a vector of bits (0s and 1s) from an ezba (Effective Zeckendorf Bits Ascending).
+ * Compresses a slice of bytes using the Padless Zeckendorf Compression algorithm.
+ *
+ * Assumes the input data is interpreted as a big endian integer. The output data is in little endian order, so the first bit and byte is the least significant bit and byte and the last bit and byte is the most significant bit and byte.
+ *
+ * # ⚠️ Important: Original Size Preservation
+ *
+ * **This function strips leading zero bytes from the input data during compression.**
+ * It is the caller's responsibility to retain the original size information (e.g., `data.len()`)
+ * before calling this function. When decompressing, the original size must be used to pad the
+ * decompressed data with leading zeros to restore the exact original data. Without the original
+ * size, information will be lost during decompression.
+ *
+ * For a format that automatically handles size preservation, use [`crate::zeck_file_format::compress::compress_zeck_be`]
+ * instead, which includes a header with the original size information.
+ *
+ * # ⚠️ 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.
+ *
+ * TODO: Technically, the way the input data is interpreted is arbitrary; we could interpret it as little endian which could result in a more compact representation. We could go even further and interpret the data at different byte or word boundaries to see if it results in a more compact representation, and signify to the caller which interpretation was used. We probably need a better understanding of random distributions of data to determine what is the optimal interpretation. More investigation is needed here.
  *
  * # Examples
  *
  * ```
- * # use zeck::unpack_bytes_to_ezba_bits;
- * assert_eq!(unpack_bytes_to_ezba_bits(&[0]), vec![0, 0, 0, 0, 0, 0, 0, 0]);
- * assert_eq!(unpack_bytes_to_ezba_bits(&[1]), vec![1, 0, 0, 0, 0, 0, 0, 0]);
- * assert_eq!(unpack_bytes_to_ezba_bits(&[0b111]), vec![1, 1, 1, 0, 0, 0, 0, 0]);
- * assert_eq!(unpack_bytes_to_ezba_bits(&[1, 1]), vec![1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0]);
+ * # use zeck::padless_zeckendorf_compress_be_dangerous;
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[0]), vec![0]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[1]), vec![1]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[12]), vec![0b111]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[54]), vec![30]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[55]), vec![0, 1]); // 55 is the 10 indexed Fibonacci number, which is the 8 indexed effective Fibonacci number, and therefore is the first number needing two bytes to contain these 8 bits, because there is 1 "use bit" and 7 "skip bits" in the effective zeckendorf bits ascending.
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[255]), vec![33, 2]);
+ * assert_eq!(padless_zeckendorf_compress_be_dangerous(&[1, 0]), vec![34, 2]);
  * ```
- * @param {Uint8Array} bytes
+ * @param {Uint8Array} data
  * @returns {Uint8Array}
  */
-export function unpack_bytes_to_ezba_bits(bytes) {
-    const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+export function padless_zeckendorf_compress_be_dangerous(data) {
+    const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.unpack_bytes_to_ezba_bits(ptr0, len0);
+    const ret = wasm.padless_zeckendorf_compress_be_dangerous(ptr0, len0);
     var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
     wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
     return v2;
 }
 
 /**
- * Compresses a slice of bytes using the Zeckendorf algorithm.
+ * Compresses a slice of bytes using the Padless Zeckendorf Compression algorithm.
  *
- * Assumes the input data is interpreted as a big endian integer. The output data is in little endian order, so the first bit and byte is the least significant bit and byte and the last bit and byte is the most significant bit and byte.
+ * Assumes the input data is interpreted as a little endian integer. The output data is in little endian order, so the first bit and byte is the least significant bit and byte and the last bit and byte is the most significant bit and byte.
  *
- * TODO: Technically, the way the input data is interpreted is arbitrary; we could interpret it as little endian which could result in a more compact representation. We could go even further and interpret the data at different byte or word boundaries to see if it results in a more compact representation, and signify to the caller which interpretation was used. We probably need a better understanding of random distributions of data to determine what is the optimal interpretation. More investigation is needed here.
+ * # ⚠️ Important: Original Size Preservation
+ *
+ * **This function strips leading zero bytes from the input data during compression.**
+ * It is the caller's responsibility to retain the original size information (e.g., `data.len()`)
+ * before calling this function. When decompressing, the original size must be used to pad the
+ * decompressed data with leading zeros to restore the exact original data. Without the original
+ * size, information will be lost during decompression.
+ *
+ * For a format that automatically handles size preservation, use [`crate::zeck_file_format::compress::compress_zeck_le`]
+ * instead, which includes a header with the original size information.
+ *
+ * # ⚠️ 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::zeckendorf_compress_be;
- * assert_eq!(zeckendorf_compress_be(&[0]), vec![0]);
- * assert_eq!(zeckendorf_compress_be(&[1]), vec![1]);
- * assert_eq!(zeckendorf_compress_be(&[12]), vec![0b111]);
- * assert_eq!(zeckendorf_compress_be(&[54]), vec![30]);
- * assert_eq!(zeckendorf_compress_be(&[55]), vec![0, 1]); // 55 is the 10 indexed Fibonacci number, which is the 8 indexed effective Fibonacci number, and therefore is the first number needing two bytes to contain these 8 bits, because there is 1 "use bit" and 7 "skip bits" in the effective zeckendorf bits ascending.
- * assert_eq!(zeckendorf_compress_be(&[255]), vec![33, 2]);
- * assert_eq!(zeckendorf_compress_be(&[1, 0]), vec![34, 2]);
+ * # use zeck::padless_zeckendorf_compress_le_dangerous;
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[0]), vec![0]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[1]), vec![1]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[12]), vec![0b111]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[54]), vec![30]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[55]), vec![0, 1]); // 55 is the 10 indexed Fibonacci number, which is the 8 indexed effective Fibonacci number, and therefore is the first number needing two bytes to contain these 8 bits, because there is 1 "use bit" and 7 "skip bits" in the effective zeckendorf bits ascending.
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[255]), vec![33, 2]);
+ * assert_eq!(padless_zeckendorf_compress_le_dangerous(&[0, 1]), vec![34, 2]);
  * ```
  * @param {Uint8Array} data
  * @returns {Uint8Array}
  */
-export function zeckendorf_compress_be(data) {
+export function padless_zeckendorf_compress_le_dangerous(data) {
     const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.zeckendorf_compress_be(ptr0, len0);
+    const ret = wasm.padless_zeckendorf_compress_le_dangerous(ptr0, len0);
     var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
     wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
     return v2;
 }
 
 /**
- * Compresses a slice of bytes using the Zeckendorf algorithm.
+ * Decompresses a slice of bytes compressed using the Zeckendorf algorithm, assuming the original data was compressed using the big endian bytes interpretation.
  *
- * Assumes the input data is interpreted as a little endian integer. The output data is in little endian order, so the first bit and byte is the least significant bit and byte and the last bit and byte is the most significant bit and byte.
+ * Assume the original input data was interpreted as a big endian integer, for now. See the TODO in the [`padless_zeckendorf_compress_be_dangerous`] function for more information.
+ *
+ * # ⚠️ Important: Leading Zero Padding
+ *
+ * **This function does not pad leading zero bytes.** If the original data had leading zeros, they will not be restored.
+ * The decompressed output will be the minimal representation of the number (without leading zeros).
+ *
+ * For a format that automatically handles size preservation and padding, use [`crate::zeck_file_format::file::deserialize_zeck_file`]
+ * and [`crate::zeck_file_format::decompress::decompress_zeck_file`] instead, which includes a header with the original size information and restores leading zeros.
+ *
+ * # ⚠️ 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::zeckendorf_compress_le;
- * assert_eq!(zeckendorf_compress_le(&[0]), vec![0]);
- * assert_eq!(zeckendorf_compress_le(&[1]), vec![1]);
- * assert_eq!(zeckendorf_compress_le(&[12]), vec![0b111]);
- * assert_eq!(zeckendorf_compress_le(&[54]), vec![30]);
- * assert_eq!(zeckendorf_compress_le(&[55]), vec![0, 1]); // 55 is the 10 indexed Fibonacci number, which is the 8 indexed effective Fibonacci number, and therefore is the first number needing two bytes to contain these 8 bits, because there is 1 "use bit" and 7 "skip bits" in the effective zeckendorf bits ascending.
- * assert_eq!(zeckendorf_compress_le(&[255]), vec![33, 2]);
- * assert_eq!(zeckendorf_compress_le(&[0, 1]), vec![34, 2]);
+ * # use zeck::padless_zeckendorf_decompress_be_dangerous;
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[0]), vec![0]);
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[1]), vec![1]);
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[0b111]), vec![12]);
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[33, 2]), vec![255]);
+ * assert_eq!(padless_zeckendorf_decompress_be_dangerous(&[34, 2]), vec![1, 0]);
  * ```
- * @param {Uint8Array} data
+ * @param {Uint8Array} compressed_data
  * @returns {Uint8Array}
  */
-export function zeckendorf_compress_le(data) {
-    const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+export function padless_zeckendorf_decompress_be_dangerous(compressed_data) {
+    const ptr0 = passArray8ToWasm0(compressed_data, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.zeckendorf_compress_le(ptr0, len0);
+    const ret = wasm.padless_zeckendorf_decompress_be_dangerous(ptr0, len0);
     var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
     wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
     return v2;
 }
 
 /**
- * Decompresses a slice of bytes compressed using the Zeckendorf algorithm, assuming the original data was compressed using the big endian bytes interpretation.
+ * Decompresses a slice of bytes compressed using the Zeckendorf algorithm, assuming the original data was compressed using the little endian bytes interpretation.
+ *
+ * # ⚠️ Important: Leading Zero Padding
+ *
+ * **This function does not pad leading zero bytes.** If the original data had leading zeros, they will not be restored.
+ * The decompressed output will be the minimal representation of the number (without leading zeros).
+ *
+ * For a format that automatically handles size preservation and padding, use [`crate::zeck_file_format::file::deserialize_zeck_file`]
+ * and [`crate::zeck_file_format::decompress::decompress_zeck_file`] instead, which includes a header with the original size information and restores leading zeros.
  *
- * Assume the original input data was interpreted as a big endian integer, for now. See the TODO in the [`zeckendorf_compress_be`] function for more information.
+ * # ⚠️ 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::zeckendorf_decompress_be;
- * assert_eq!(zeckendorf_decompress_be(&[0]), vec![0]);
- * assert_eq!(zeckendorf_decompress_be(&[1]), vec![1]);
- * assert_eq!(zeckendorf_decompress_be(&[0b111]), vec![12]);
- * assert_eq!(zeckendorf_decompress_be(&[33, 2]), vec![255]);
- * assert_eq!(zeckendorf_decompress_be(&[34, 2]), vec![1, 0]);
+ * # use zeck::padless_zeckendorf_decompress_le_dangerous;
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[0]), vec![0]);
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[1]), vec![1]);
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[0b111]), vec![12]);
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[33, 2]), vec![255]);
+ * assert_eq!(padless_zeckendorf_decompress_le_dangerous(&[34, 2]), vec![0, 1]);
  * ```
  * @param {Uint8Array} compressed_data
  * @returns {Uint8Array}
  */
-export function zeckendorf_decompress_be(compressed_data) {
+export function padless_zeckendorf_decompress_le_dangerous(compressed_data) {
     const ptr0 = passArray8ToWasm0(compressed_data, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.zeckendorf_decompress_be(ptr0, len0);
+    const ret = wasm.padless_zeckendorf_decompress_le_dangerous(ptr0, len0);
     var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
     wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
     return v2;
 }
 
 /**
- * Decompresses a slice of bytes compressed using the Zeckendorf algorithm, assuming the original data was compressed using the little endian bytes interpretation.
+ * Unpacks a vector of bytes into a vector of bits (0s and 1s) from an ezba (Effective Zeckendorf Bits Ascending).
  *
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_decompress_le;
- * assert_eq!(zeckendorf_decompress_le(&[0]), vec![0]);
- * assert_eq!(zeckendorf_decompress_le(&[1]), vec![1]);
- * assert_eq!(zeckendorf_decompress_le(&[0b111]), vec![12]);
- * assert_eq!(zeckendorf_decompress_le(&[33, 2]), vec![255]);
- * assert_eq!(zeckendorf_decompress_le(&[34, 2]), vec![0, 1]);
+ * # use zeck::unpack_bytes_to_ezba_bits;
+ * assert_eq!(unpack_bytes_to_ezba_bits(&[0]), vec![0, 0, 0, 0, 0, 0, 0, 0]);
+ * assert_eq!(unpack_bytes_to_ezba_bits(&[1]), vec![1, 0, 0, 0, 0, 0, 0, 0]);
+ * assert_eq!(unpack_bytes_to_ezba_bits(&[0b111]), vec![1, 1, 1, 0, 0, 0, 0, 0]);
+ * assert_eq!(unpack_bytes_to_ezba_bits(&[1, 1]), vec![1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0]);
  * ```
- * @param {Uint8Array} compressed_data
+ * @param {Uint8Array} bytes
  * @returns {Uint8Array}
  */
-export function zeckendorf_decompress_le(compressed_data) {
-    const ptr0 = passArray8ToWasm0(compressed_data, wasm.__wbindgen_malloc);
+export function unpack_bytes_to_ezba_bits(bytes) {
+    const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.zeckendorf_decompress_le(ptr0, len0);
+    const ret = wasm.unpack_bytes_to_ezba_bits(ptr0, len0);
     var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
     wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
     return v2;