zeck 1.0.7 → 2.1.0

package/README.md

@@ -408,6 +408,28 @@ This avoids redundant Fibonacci numbers (F(0)=0 and F(1)=F(2)=1).
 - 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.
 
+## 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
 
 This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.

package/package.json

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

package/zeck.d.ts

@@ -1,5 +1,41 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * 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.
+ */
+export interface ZeckFile {
+    /**
+     * File format version
+     */
+    version: number;
+    /**
+     * Original uncompressed file size in bytes
+     */
+    original_size: number;
+    /**
+     * Flags byte (bit 0 = big endian, bits 1-7 reserved)
+     */
+    flags: number;
+    /**
+     * Compressed data (without header)
+     */
+    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.
@@ -17,6 +53,129 @@
  */
 export function bit_count_for_number(n: number): number;
 
+/**
+ * Compresses data using the Zeckendorf algorithm with big endian interpretation,
+ * and stores the result in 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_be;
+ * let data = vec![1, 0];
+ * match compress_zeck_be(&data) {
+ *     Ok(zeck_file) => {
+ *         // Access file information
+ *         println!("Original size: {} bytes", zeck_file.original_size);
+ *         println!("Is big endian: {}", zeck_file.is_big_endian());
+ *         // Serialize to bytes for writing to file
+ *         let bytes = zeck_file.to_bytes();
+ *     }
+ *     Err(e) => {
+ *         // Handle error (e.g., data size too large)
+ *     }
+ * }
+ * ```
+ */
+export function compress_zeck_be(data: Uint8Array): ZeckFile;
+
+/**
+ * Compresses data using the Zeckendorf algorithm with automatic endianness selection,
+ * and stores the result in a [`BestCompressionResult`] struct.
+ *
+ * This function attempts compression with both big endian and little endian interpretations,
+ * and returns the best result, or if neither produced compression (both were larger than the original).
+ *
+ * # ⚠️ 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_best;
+ * # use zeck::zeck_file_format::compress::BestCompressionResult;
+ * # use zeck::zeck_file_format::decompress::decompress_zeck_file;
+ * let data = vec![0, 1]; // Compresses best interpreted as a big endian integer
+ * match compress_zeck_best(&data) {
+ *     Ok(best_compression_result) => {
+ *         match best_compression_result {
+ *             BestCompressionResult::BigEndianBest { zeck_file, le_size } => {
+ *                 let decompressed = decompress_zeck_file(&zeck_file).unwrap();
+ *                 assert_eq!(decompressed, data);
+ *             }
+ *             BestCompressionResult::LittleEndianBest { zeck_file, be_size } => {
+ *                 assert!(false);
+ *             }
+ *             BestCompressionResult::Neither { be_size, le_size } => {
+ *                 assert!(false);
+ *             }
+ *         }
+ *     }
+ *     Err(e) => {
+ *         assert!(false);
+ *     }
+ * }
+ *
+ * let data = vec![1, 0]; // Compresses best interpreted as a little endian integer
+ * match compress_zeck_best(&data) {
+ *     Ok(best_compression_result) => {
+ *         match best_compression_result {
+ *             BestCompressionResult::BigEndianBest { zeck_file, le_size } => {
+ *                 assert!(false);
+ *             }
+ *             BestCompressionResult::LittleEndianBest { zeck_file, be_size } => {
+ *                 let decompressed = decompress_zeck_file(&zeck_file).unwrap();
+ *                 assert_eq!(decompressed, data);
+ *             }
+ *             BestCompressionResult::Neither { be_size, le_size } => {
+ *                 assert!(false);
+ *             }
+ *         }
+ *     }
+ *     Err(e) => {
+ *         assert!(false);
+ *     }
+ * }
+ * ```
+ */
+export function compress_zeck_best(data: Uint8Array): BestCompressionResult;
+
+/**
+ * Compresses data using the Zeckendorf algorithm with little endian interpretation,
+ * and stores the result in 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;
+ * let data = vec![1, 0];
+ * match compress_zeck_le(&data) {
+ *     Ok(zeck_file) => {
+ *         // Access file information
+ *         println!("Original size: {} bytes", zeck_file.original_size);
+ *         println!("Compressed size: {} bytes", zeck_file.compressed_data.len());
+ *         // Serialize to bytes for writing to file
+ *         let bytes = zeck_file.to_bytes();
+ *     }
+ *     Err(e) => {
+ *         // Handle error (e.g., data size too large)
+ *     }
+ * }
+ * ```
+ */
+export function compress_zeck_le(data: Uint8Array): ZeckFile;
+
 /**
  * Effective Fibonacci Index to Fibonacci Index: FI(efi) === efi + 2, where efi is the Effective Fibonacci Index
  *
@@ -64,9 +223,9 @@ export function ezba_from_ezld(effective_zeckendorf_list_descending: BigUint64Ar
  *
  * ```
  * # use zeck::ezba_to_ezla;
- * assert_eq!(ezba_to_ezla(&[0, 0, 0, 0, 0, 0, 0, 0]), vec![]);
- * assert_eq!(ezba_to_ezla(&[1, 0, 0, 0, 0, 0, 0, 0]), vec![0]);
- * assert_eq!(ezba_to_ezla(&[1, 1, 1, 0, 0, 0, 0, 0]), vec![0, 2, 4]);
+ * assert_eq!(ezba_to_ezla(&[0, 0, 0, 0, 0, 0, 0, 0]), vec![] as Vec<u64>);
+ * assert_eq!(ezba_to_ezla(&[1, 0, 0, 0, 0, 0, 0, 0]), vec![0u64]);
+ * assert_eq!(ezba_to_ezla(&[1, 1, 1, 0, 0, 0, 0, 0]), vec![0u64, 2u64, 4u64]);
  * ```
  */
 export function ezba_to_ezla(ezba_bits: Uint8Array): BigUint64Array;
@@ -194,21 +353,21 @@ export function memoized_slow_fibonacci_recursive(fi: bigint): bigint;
  * ```
  * # use zeck::memoized_zeckendorf_list_descending_for_integer;
  * // Base cases
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(0), vec![]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(1), vec![2]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(2), vec![3]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(0), vec![] as Vec<u64>);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(1), vec![2u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(2), vec![3u64]);
  *
  * // Small Zeckendorf numbers
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(3), vec![4]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(4), vec![4, 2]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(5), vec![5]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(6), vec![5, 2]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(7), vec![5, 3]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(8), vec![6]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(9), vec![6, 2]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(10), vec![6, 3]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(11), vec![6, 4]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(12), vec![6, 4, 2]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(3), vec![4u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(4), vec![4u64, 2u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(5), vec![5u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(6), vec![5u64, 2u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(7), vec![5u64, 3u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(8), vec![6u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(9), vec![6u64, 2u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(10), vec![6u64, 3u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(11), vec![6u64, 4u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(12), vec![6u64, 4u64, 2u64]);
  * ```
  */
 export function memoized_zeckendorf_list_descending_for_integer(n: bigint): BigUint64Array;
@@ -236,24 +395,20 @@ 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.
  *
- * # Examples
+ * 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.
  *
- * ```
- * # 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 unpack_bytes_to_ezba_bits(bytes: Uint8Array): Uint8Array;
-
-/**
- * Compresses a slice of bytes using the Zeckendorf algorithm.
+ * # ⚠️ Important: Original Size Preservation
  *
- * 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.
+ * **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
  *
@@ -265,23 +420,34 @@ export function unpack_bytes_to_ezba_bits(bytes: Uint8Array): Uint8Array;
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_compress_be_broken_do_not_use;
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[0]), vec![0]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[1]), vec![1]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[12]), vec![0b111]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[54]), vec![30]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[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_broken_do_not_use(&[255]), vec![33, 2]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[1, 0]), vec![34, 2]);
+ * # 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 zeckendorf_compress_be_broken_do_not_use(data: 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 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.
  *
+ * # ⚠️ 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.**
@@ -290,22 +456,30 @@ export function zeckendorf_compress_be_broken_do_not_use(data: Uint8Array): Uint
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_compress_le_broken_do_not_use;
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[0]), vec![0]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[1]), vec![1]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[12]), vec![0b111]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[54]), vec![30]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[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_broken_do_not_use(&[255]), vec![33, 2]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[0, 1]), 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_le_broken_do_not_use(data: Uint8Array): Uint8Array;
+export function padless_zeckendorf_compress_le_dangerous(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.
  *
- * 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.
+ * 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
  *
@@ -315,19 +489,27 @@ export function zeckendorf_compress_le_broken_do_not_use(data: Uint8Array): Uint
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_decompress_be_broken_do_not_use;
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[0]), vec![0]);
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[1]), vec![1]);
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[0b111]), vec![12]);
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[33, 2]), vec![255]);
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[34, 2]), vec![1, 0]);
+ * # 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_decompress_be_broken_do_not_use(compressed_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 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.
+ *
  * # ⚠️ Warning
  *
  * **Compressing or decompressing data larger than 10KB (10,000 bytes) is unstable due to time and memory pressure.**
@@ -336,15 +518,30 @@ export function zeckendorf_decompress_be_broken_do_not_use(compressed_data: Uint
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_decompress_le_broken_do_not_use;
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[0]), vec![0]);
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[1]), vec![1]);
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[0b111]), vec![12]);
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[33, 2]), vec![255]);
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[34, 2]), vec![0, 1]);
+ * # 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 padless_zeckendorf_decompress_le_dangerous(compressed_data: Uint8Array): Uint8Array;
+
+/**
+ * Unpacks a vector of bytes into a vector of bits (0s and 1s) from an ezba (Effective Zeckendorf Bits Ascending).
+ *
+ * # 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]);
  * ```
  */
-export function zeckendorf_decompress_le_broken_do_not_use(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

@@ -3,6 +3,12 @@ export function __wbg_set_wasm(val) {
     wasm = val;
 }
 
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
 function getArrayU64FromWasm0(ptr, len) {
     ptr = ptr >>> 0;
     return getBigUint64ArrayMemory0().subarray(ptr / 8, ptr / 8 + len);
@@ -21,6 +27,11 @@ function getBigUint64ArrayMemory0() {
     return cachedBigUint64ArrayMemory0;
 }
 
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
 let cachedUint8ArrayMemory0 = null;
 function getUint8ArrayMemory0() {
     if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
@@ -29,6 +40,15 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
 function passArray64ToWasm0(arg, malloc) {
     const ptr = malloc(arg.length * 8, 8) >>> 0;
     getBigUint64ArrayMemory0().set(arg, ptr / 8);
@@ -43,6 +63,26 @@ function passArray8ToWasm0(arg, malloc) {
     return ptr;
 }
 
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
 let WASM_VECTOR_LEN = 0;
 
 /**
@@ -66,6 +106,159 @@ export function bit_count_for_number(n) {
     return ret >>> 0;
 }
 
+/**
+ * Compresses data using the Zeckendorf algorithm with big endian interpretation,
+ * and stores the result in 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_be;
+ * let data = vec![1, 0];
+ * match compress_zeck_be(&data) {
+ *     Ok(zeck_file) => {
+ *         // Access file information
+ *         println!("Original size: {} bytes", zeck_file.original_size);
+ *         println!("Is big endian: {}", zeck_file.is_big_endian());
+ *         // Serialize to bytes for writing to file
+ *         let bytes = zeck_file.to_bytes();
+ *     }
+ *     Err(e) => {
+ *         // Handle error (e.g., data size too large)
+ *     }
+ * }
+ * ```
+ * @param {Uint8Array} data
+ * @returns {ZeckFile}
+ */
+export function compress_zeck_be(data) {
+    const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.compress_zeck_be(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Compresses data using the Zeckendorf algorithm with automatic endianness selection,
+ * and stores the result in a [`BestCompressionResult`] struct.
+ *
+ * This function attempts compression with both big endian and little endian interpretations,
+ * and returns the best result, or if neither produced compression (both were larger than the original).
+ *
+ * # ⚠️ 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_best;
+ * # use zeck::zeck_file_format::compress::BestCompressionResult;
+ * # use zeck::zeck_file_format::decompress::decompress_zeck_file;
+ * let data = vec![0, 1]; // Compresses best interpreted as a big endian integer
+ * match compress_zeck_best(&data) {
+ *     Ok(best_compression_result) => {
+ *         match best_compression_result {
+ *             BestCompressionResult::BigEndianBest { zeck_file, le_size } => {
+ *                 let decompressed = decompress_zeck_file(&zeck_file).unwrap();
+ *                 assert_eq!(decompressed, data);
+ *             }
+ *             BestCompressionResult::LittleEndianBest { zeck_file, be_size } => {
+ *                 assert!(false);
+ *             }
+ *             BestCompressionResult::Neither { be_size, le_size } => {
+ *                 assert!(false);
+ *             }
+ *         }
+ *     }
+ *     Err(e) => {
+ *         assert!(false);
+ *     }
+ * }
+ *
+ * let data = vec![1, 0]; // Compresses best interpreted as a little endian integer
+ * match compress_zeck_best(&data) {
+ *     Ok(best_compression_result) => {
+ *         match best_compression_result {
+ *             BestCompressionResult::BigEndianBest { zeck_file, le_size } => {
+ *                 assert!(false);
+ *             }
+ *             BestCompressionResult::LittleEndianBest { zeck_file, be_size } => {
+ *                 let decompressed = decompress_zeck_file(&zeck_file).unwrap();
+ *                 assert_eq!(decompressed, data);
+ *             }
+ *             BestCompressionResult::Neither { be_size, le_size } => {
+ *                 assert!(false);
+ *             }
+ *         }
+ *     }
+ *     Err(e) => {
+ *         assert!(false);
+ *     }
+ * }
+ * ```
+ * @param {Uint8Array} data
+ * @returns {BestCompressionResult}
+ */
+export function compress_zeck_best(data) {
+    const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.compress_zeck_best(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Compresses data using the Zeckendorf algorithm with little endian interpretation,
+ * and stores the result in 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;
+ * let data = vec![1, 0];
+ * match compress_zeck_le(&data) {
+ *     Ok(zeck_file) => {
+ *         // Access file information
+ *         println!("Original size: {} bytes", zeck_file.original_size);
+ *         println!("Compressed size: {} bytes", zeck_file.compressed_data.len());
+ *         // Serialize to bytes for writing to file
+ *         let bytes = zeck_file.to_bytes();
+ *     }
+ *     Err(e) => {
+ *         // Handle error (e.g., data size too large)
+ *     }
+ * }
+ * ```
+ * @param {Uint8Array} data
+ * @returns {ZeckFile}
+ */
+export function compress_zeck_le(data) {
+    const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.compress_zeck_le(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
  *
@@ -127,9 +320,9 @@ export function ezba_from_ezld(effective_zeckendorf_list_descending) {
  *
  * ```
  * # use zeck::ezba_to_ezla;
- * assert_eq!(ezba_to_ezla(&[0, 0, 0, 0, 0, 0, 0, 0]), vec![]);
- * assert_eq!(ezba_to_ezla(&[1, 0, 0, 0, 0, 0, 0, 0]), vec![0]);
- * assert_eq!(ezba_to_ezla(&[1, 1, 1, 0, 0, 0, 0, 0]), vec![0, 2, 4]);
+ * assert_eq!(ezba_to_ezla(&[0, 0, 0, 0, 0, 0, 0, 0]), vec![] as Vec<u64>);
+ * assert_eq!(ezba_to_ezla(&[1, 0, 0, 0, 0, 0, 0, 0]), vec![0u64]);
+ * assert_eq!(ezba_to_ezla(&[1, 1, 1, 0, 0, 0, 0, 0]), vec![0u64, 2u64, 4u64]);
  * ```
  * @param {Uint8Array} ezba_bits
  * @returns {BigUint64Array}
@@ -295,21 +488,21 @@ export function memoized_slow_fibonacci_recursive(fi) {
  * ```
  * # use zeck::memoized_zeckendorf_list_descending_for_integer;
  * // Base cases
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(0), vec![]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(1), vec![2]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(2), vec![3]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(0), vec![] as Vec<u64>);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(1), vec![2u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(2), vec![3u64]);
  *
  * // Small Zeckendorf numbers
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(3), vec![4]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(4), vec![4, 2]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(5), vec![5]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(6), vec![5, 2]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(7), vec![5, 3]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(8), vec![6]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(9), vec![6, 2]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(10), vec![6, 3]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(11), vec![6, 4]);
- * assert_eq!(memoized_zeckendorf_list_descending_for_integer(12), vec![6, 4, 2]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(3), vec![4u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(4), vec![4u64, 2u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(5), vec![5u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(6), vec![5u64, 2u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(7), vec![5u64, 3u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(8), vec![6u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(9), vec![6u64, 2u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(10), vec![6u64, 3u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(11), vec![6u64, 4u64]);
+ * assert_eq!(memoized_zeckendorf_list_descending_for_integer(12), vec![6u64, 4u64, 2u64]);
  * ```
  * @param {bigint} n
  * @returns {BigUint64Array}
@@ -353,33 +546,20 @@ 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.
  *
- * # Examples
+ * 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.
  *
- * ```
- * # 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} bytes
- * @returns {Uint8Array}
- */
-export function unpack_bytes_to_ezba_bits(bytes) {
-    const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
-    const len0 = WASM_VECTOR_LEN;
-    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;
-}
-
-/**
- * Compresses a slice of bytes using the Zeckendorf algorithm.
+ * # ⚠️ Important: Original Size Preservation
  *
- * 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.
+ * **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
  *
@@ -391,32 +571,43 @@ export function unpack_bytes_to_ezba_bits(bytes) {
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_compress_be_broken_do_not_use;
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[0]), vec![0]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[1]), vec![1]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[12]), vec![0b111]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[54]), vec![30]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[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_broken_do_not_use(&[255]), vec![33, 2]);
- * assert_eq!(zeckendorf_compress_be_broken_do_not_use(&[1, 0]), vec![34, 2]);
+ * # 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} data
  * @returns {Uint8Array}
  */
-export function zeckendorf_compress_be_broken_do_not_use(data) {
+export function padless_zeckendorf_compress_be_dangerous(data) {
     const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.zeckendorf_compress_be_broken_do_not_use(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 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.
  *
+ * # ⚠️ 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.**
@@ -425,22 +616,22 @@ export function zeckendorf_compress_be_broken_do_not_use(data) {
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_compress_le_broken_do_not_use;
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[0]), vec![0]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[1]), vec![1]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[12]), vec![0b111]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[54]), vec![30]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[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_broken_do_not_use(&[255]), vec![33, 2]);
- * assert_eq!(zeckendorf_compress_le_broken_do_not_use(&[0, 1]), 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_le_broken_do_not_use(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_le_broken_do_not_use(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;
@@ -449,7 +640,15 @@ export function zeckendorf_compress_le_broken_do_not_use(data) {
 /**
  * Decompresses a slice of bytes compressed using the Zeckendorf algorithm, assuming the original data was compressed using the big endian bytes interpretation.
  *
- * 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.
+ * 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
  *
@@ -459,20 +658,20 @@ export function zeckendorf_compress_le_broken_do_not_use(data) {
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_decompress_be_broken_do_not_use;
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[0]), vec![0]);
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[1]), vec![1]);
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[0b111]), vec![12]);
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[33, 2]), vec![255]);
- * assert_eq!(zeckendorf_decompress_be_broken_do_not_use(&[34, 2]), vec![1, 0]);
+ * # 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} compressed_data
  * @returns {Uint8Array}
  */
-export function zeckendorf_decompress_be_broken_do_not_use(compressed_data) {
+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_decompress_be_broken_do_not_use(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;
@@ -481,6 +680,14 @@ export function zeckendorf_decompress_be_broken_do_not_use(compressed_data) {
 /**
  * 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.
+ *
  * # ⚠️ Warning
  *
  * **Compressing or decompressing data larger than 10KB (10,000 bytes) is unstable due to time and memory pressure.**
@@ -489,20 +696,44 @@ export function zeckendorf_decompress_be_broken_do_not_use(compressed_data) {
  * # Examples
  *
  * ```
- * # use zeck::zeckendorf_decompress_le_broken_do_not_use;
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[0]), vec![0]);
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[1]), vec![1]);
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[0b111]), vec![12]);
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[33, 2]), vec![255]);
- * assert_eq!(zeckendorf_decompress_le_broken_do_not_use(&[34, 2]), vec![0, 1]);
+ * # 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_le_broken_do_not_use(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_le_broken_do_not_use(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;
+}
+
+/**
+ * Unpacks a vector of bytes into a vector of bits (0s and 1s) from an ezba (Effective Zeckendorf Bits Ascending).
+ *
+ * # 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]);
+ * ```
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array}
+ */
+export function unpack_bytes_to_ezba_bits(bytes) {
+    const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    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;
@@ -536,6 +767,15 @@ export function zl_to_ezl(zl) {
     return v2;
 }
 
+export function __wbg___wbindgen_throw_dd24417ed36fc46e(arg0, arg1) {
+    throw new Error(getStringFromWasm0(arg0, arg1));
+};
+
+export function __wbg_parse_a09a54cf72639456() { return handleError(function (arg0, arg1) {
+    const ret = JSON.parse(getStringFromWasm0(arg0, arg1));
+    return ret;
+}, arguments) };
+
 export function __wbindgen_init_externref_table() {
     const table = wasm.__wbindgen_externrefs;
     const offset = table.grow(4);