@woosh/meep-engine 3.26.0 → 3.27.0

package/src/core/binary/lz4/lz4_compress_block_at_level.js

@@ -0,0 +1,47 @@
+import { assert } from "../../assert.js";
+import { LZ4_LEVEL } from "./LZ4_LEVEL.js";
+import { lz4_compress_block } from "./lz4_compress_block.js";
+import { lz4_compress_block_hc } from "./lz4_compress_block_hc.js";
+
+/**
+ * Encode one LZ4 block, at whichever level the caller asks for.
+ *
+ * This is what a caller with a knob calls. The two encoders behind it are not variants of one
+ * another — {@link lz4_compress_block} makes a single greedy pass over a table that holds one
+ * position per hash, and {@link lz4_compress_block_hc} walks a chain of every position carrying the
+ * same hash and parses the matches against each other — so they are two functions, and this is the
+ * one line that chooses between them.
+ *
+ * **Every level writes the same format.** A block is a block: the level changes how long the encoder
+ * spent looking for matches, not what a match is coded as. So the level is a build-time decision
+ * with no reader consequence at all, and one that can be changed on an existing pipeline without
+ * anything downstream knowing.
+ *
+ * `destination` and `source` must not overlap.
+ *
+ * @param {Uint8Array} destination
+ * @param {number} destination_offset where this block's output starts
+ * @param {number} destination_end one past the last byte the block may write; give it
+ *                                 {@link lz4_compress_bound} bytes and it cannot run out
+ * @param {Uint8Array} source
+ * @param {number} source_offset the first byte of input, and the floor a match may reach back to
+ * @param {number} source_end one past the last byte of input
+ * @param {number} level {@link LZ4_LEVEL.FAST}, or one of 3 to {@link LZ4_LEVEL.HC_MAX} — there is
+ *                       no level 2, and {@link LZ4_LEVEL} says why
+ * @returns {number} the offset just past the last byte written
+ * @throws {Error} if the block does not fit the space given for it
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function lz4_compress_block_at_level(destination, destination_offset, destination_end, source, source_offset, source_end, level) {
+    assert.isInteger(level, 'level');
+
+    if (level === LZ4_LEVEL.FAST) {
+        return lz4_compress_block(destination, destination_offset, destination_end, source, source_offset, source_end);
+    }
+
+    return lz4_compress_block_hc(
+        destination, destination_offset, destination_end, source, source_offset, source_end, level
+    );
+}

package/src/core/binary/lz4/lz4_compress_block_hc.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Encode one LZ4 block at a compression level.
+ *
+ * A port of the reference implementation's `lz4hc`, without its dictionary and streaming support:
+ * meep compresses one self-contained block with no history, so the external dictionary, the
+ * dictionary context, the pattern rotation across a dictionary boundary, `favorDecSpeed` and
+ * `fillOutput` all drop, and with them about half the reference file. What is left is byte for byte
+ * what `LZ4_compress_HC` writes at the same level.
+ *
+ * **The format does not change.** This emits ordinary LZ4 blocks — the same tokens, the same
+ * sixteen-bit offsets, the same restrictions on where a match may start — so a block written here
+ * at any level decodes under {@link lz4_decompress_block} and under every other reader that exists.
+ * What changes is only how hard the encoder looked: where {@link lz4_compress_block} takes the
+ * first match a hash slot offers, this walks a chain of every position carrying the same hash and
+ * parses the matches it finds against each other.
+ *
+ * What that is worth depends entirely on the payload. On text it is 20% or more; on quantised,
+ * densely packed bytes — geometry pages, say — it is about 2.5%, and almost all of that is already
+ * there at level 3. What it costs is an order of magnitude of throughput: 400 MB/s becomes 50.
+ *
+ * `destination` and `source` must not overlap.
+ *
+ * @see https://github.com/lz4/lz4/blob/dev/lib/lz4hc.c — `LZ4HC_compress_hashChain` and `LZ4HC_compress_optimal`
+ *
+ * @param {Uint8Array} p_destination
+ * @param {number} destination_offset where this block's output starts
+ * @param {number} destination_end one past the last byte the block may write; give it
+ *                                 {@link lz4_compress_bound} bytes and it cannot run out
+ * @param {Uint8Array} p_source
+ * @param {number} source_offset the first byte of input, and the floor a match may reach back to
+ * @param {number} source_end one past the last byte of input
+ * @param {number} level one of {@link LZ4_LEVEL}'s high-compression levels
+ * @returns {number} the offset just past the last byte written
+ * @throws {Error} if the block does not fit the space given for it
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function lz4_compress_block_hc(p_destination: Uint8Array, destination_offset: number, destination_end: number, p_source: Uint8Array, source_offset: number, source_end: number, level: number): number;
+//# sourceMappingURL=lz4_compress_block_hc.d.ts.map

package/src/core/binary/lz4/lz4_compress_block_hc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lz4_compress_block_hc.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/lz4/lz4_compress_block_hc.js"],"names":[],"mappings":"AAovCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qDAdW,UAAU,sBACV,MAAM,mBACN,MAAM,YAEN,UAAU,iBACV,MAAM,cACN,MAAM,SACN,MAAM,GACJ,MAAM,CAiFlB"}