@addmaple/lz4 0.1.2 → 0.2.0

package/README.md

@@ -4,6 +4,24 @@ Fast LZ4 compression in the browser and Node.js using Rust + WASM.
 
 **2.5x-3.5x faster** than `lz4js`.
 
+## Implementation (Rust)
+
+This package is backed by these Rust crates in the `wasm-fast-compress` repo:
+
+- `codec-lz4` (this repo): high-level codec wrapper
+- `lz4_flex` (Git fork, branch `wasm-simd`): core LZ4 implementation with WASM SIMD128 hot paths
+
+## SIMD acceleration (how it works)
+
+- We build **two WASM binaries**:
+  - `lz4.base.wasm`: compiled without `+simd128`
+  - `lz4.simd.wasm`: compiled with `-C target-feature=+simd128`
+- At runtime, the JS loader detects SIMD support and loads the best binary automatically.
+
+On wasm32, the SIMD build benefits from:
+- `lz4_flex` explicit `wasm32 + simd128` intrinsics for match finding / copying hot paths
+- additional LLVM autovectorization where applicable
+
 ## Installation
 
 ```bash
@@ -15,12 +33,81 @@ npm install @addmaple/lz4
 ```javascript
 import { init, compress } from '@addmaple/lz4';
 
+// Optional: call init() to avoid first-call latency.
+// If you skip init(), the first compress/decompress call will lazy-initialize.
 await init();
 
 const input = new TextEncoder().encode('hello world');
 const compressed = await compress(input);
 ```
 
+### Lazy init (init() optional)
+
+```javascript
+import { compress } from '@addmaple/lz4';
+
+const input = new TextEncoder().encode('hello world');
+const compressed = await compress(input); // triggers lazy init on first call
+```
+
+### Streaming compression + decompression
+
+For chunked input (e.g. streaming over the network), use the handle-based streaming helpers:
+
+```javascript
+import { init, StreamingCompressor, StreamingDecompressor } from '@addmaple/lz4';
+
+// Optional: init() is not required; streaming helpers also lazy-init.
+await init();
+
+// Compress
+const enc = new StreamingCompressor();
+const c1 = await enc.compressChunk(chunk1, false);
+const c2 = await enc.compressChunk(chunk2, false);
+const c3 = await enc.compressChunk(chunk3, true); // finish
+
+// Decompress (finish must be true to produce output for frame format)
+const dec = new StreamingDecompressor();
+await dec.decompressChunk(c1, false);
+await dec.decompressChunk(c2, false);
+const plain = await dec.decompressChunk(c3, true);
+```
+
+### Streaming to `fetch()` (ergonomic)
+
+If you want to upload a `File`/`Blob` with LZ4 compression, you can pipe it through the built-in stream helper:
+
+```javascript
+import { createCompressionStream } from '@addmaple/lz4';
+
+const body = file.stream().pipeThrough(createCompressionStream());
+
+await fetch('/upload', {
+  method: 'POST',
+  headers: {
+    // Not a standard encoding token like gzip; your server must explicitly support this.
+    'Content-Encoding': 'lz4',
+  },
+  body,
+  // Needed for streaming request bodies in some runtimes (notably Node fetch).
+  duplex: 'half',
+});
+```
+
+### Streaming decompression from `fetch()` (ergonomic)
+
+```javascript
+import { createDecompressionStream } from '@addmaple/lz4';
+
+const res = await fetch('/download');
+if (!res.body) throw new Error('No response body');
+
+const decompressed = res.body.pipeThrough(createDecompressionStream());
+
+// Example: read it all (or pipe somewhere else)
+const buf = await new Response(decompressed).arrayBuffer();
+```
+
 ### Inline (Zero-latency)
 
 WASM bytes embedded directly in JS — no separate file fetching:

package/dist/core.js

@@ -42,7 +42,8 @@ function toBytes(input) {
   if (input instanceof Uint8Array) return input;
   if (ArrayBuffer.isView(input)) return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
   if (input instanceof ArrayBuffer) return new Uint8Array(input);
-  throw new TypeError("Expected a TypedArray or ArrayBuffer");
+  if (typeof input === 'string') return new TextEncoder().encode(input);
+  throw new TypeError("Expected a TypedArray, ArrayBuffer, or string");
 }
 
 function scalarSize(type) {

package/dist/custom.js

@@ -14,7 +14,8 @@ function toBytes(input) {
   if (input instanceof Uint8Array) return input;
   if (ArrayBuffer.isView(input)) return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
   if (input instanceof ArrayBuffer) return new Uint8Array(input);
-  throw new TypeError("Expected a TypedArray or ArrayBuffer");
+  if (typeof input === 'string') return new TextEncoder().encode(input);
+  throw new TypeError("Expected a TypedArray, ArrayBuffer, or string");
 }
 
 // ============================================================================
@@ -335,5 +336,80 @@ export async function decompress(input) {
   }
 }
 
+// ============================================================================
+// Ergonomic streaming helpers (Web Streams)
+// ============================================================================
+
+function requireTransformStream() {
+  if (typeof TransformStream === 'undefined') {
+    throw new Error('TransformStream is not available in this runtime');
+  }
+}
+
+/**
+ * Create a TransformStream that LZ4-compresses a byte stream.
+ *
+ * This uses the LZ4 *frame* streaming API so the output can be decoded without
+ * knowing the original size ahead of time (good for fetch request bodies).
+ *
+ * @returns {TransformStream<Uint8Array, Uint8Array>}
+ */
+export function createCompressionStream() {
+  requireTransformStream();
+  const enc = new StreamingCompressor();
+
+  return new TransformStream({
+    async transform(chunk, controller) {
+      const out = await enc.compressChunk(toBytes(chunk), false);
+      if (out.length) controller.enqueue(out);
+    },
+    async flush(controller) {
+      // Finish the stream (flush footer / close handle)
+      const out = await enc.compressChunk(new Uint8Array(0), true);
+      if (out.length) controller.enqueue(out);
+    },
+  });
+}
+
+/**
+ * Create a TransformStream that LZ4-decompresses a byte stream.
+ *
+ * Note: current LZ4 frame streaming decompression buffers until finish=true,
+ * so output is typically produced during `flush()`.
+ *
+ * @returns {TransformStream<Uint8Array, Uint8Array>}
+ */
+export function createDecompressionStream() {
+  requireTransformStream();
+  const dec = new StreamingDecompressor();
+
+  return new TransformStream({
+    async transform(chunk, controller) {
+      const out = await dec.decompressChunk(toBytes(chunk), false);
+      if (out.length) controller.enqueue(out);
+    },
+    async flush(controller) {
+      const out = await dec.decompressChunk(new Uint8Array(0), true);
+      if (out.length) controller.enqueue(out);
+    },
+  });
+}
+
+/**
+ * Convenience helper: readable.pipeThrough(createCompressionStream()).
+ * @param {ReadableStream<Uint8Array>} readable
+ */
+export function compressStream(readable) {
+  return readable.pipeThrough(createCompressionStream());
+}
+
+/**
+ * Convenience helper: readable.pipeThrough(createDecompressionStream()).
+ * @param {ReadableStream<Uint8Array>} readable
+ */
+export function decompressStream(readable) {
+  return readable.pipeThrough(createDecompressionStream());
+}
+
 export { wasmExports };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@addmaple/lz4",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/node.js",
   "browser": "./dist/browser.js",