@trkyshorty/node-lzf 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,32 @@
+BSD 2-Clause License
+
+Copyright (c) 2011 Ian Babrou <ibobrik@gmail.com>
+Copyright (c) 2025 Türkay Tanrikulu <trky.shorty@gmail.com>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+----------------------------------------------------------------------------
+
+This package bundles liblzf by Marc Alexander Lehmann (src/lzf/), which is
+distributed under the BSD 2-Clause license (or alternatively the GPL v2 or
+later). See the license headers in src/lzf/*.h and src/lzf/*.cc for details.

package/README.md

@@ -4,81 +4,146 @@
 
 LZF advantages:
 
-* Small code size (less then 500 lines including header files and docs).
-* Very fast compression speeds, rivaling a straight copy loop, especially for decompression which is basically at (unoptimized) memcpy-speed. Compression speed can be increased by 20% by sacrificing a few percent of compression ratio.
-* Mediocre compression ratios - you can usually expect about 40-50% compression for typical binary data
-* Easy to use (just two functions, no state attached)
-* Highly portable (written in C)
-* Tunable, see the file lzfP.h in the distribution, to tailor liblzf to your needs. The generated compressed blocks can be decompressed by any liblzf version regardless of the options used to compress.
-* Freely usable (BSD-type-license)
+- Small code size (less then 500 lines including header files and docs).
+- Very fast compression speeds, rivaling a straight copy loop, especially for decompression which is basically at (unoptimized) memcpy-speed. Compression speed can be increased by 20% by sacrificing a few percent of compression ratio.
+- Mediocre compression ratios - you can usually expect about 40-50% compression for typical binary data
+- Easy to use (just two functions, no state attached)
+- Highly portable (written in C)
+- Tunable, see the file lzfP.h in the distribution, to tailor liblzf to your needs. The generated compressed blocks can be decompressed by any liblzf version regardless of the options used to compress.
+- Freely usable (BSD-type-license)
+
+### Install
+
+```bash
+npm install @trkyshorty/node-lzf
+```
+
+The module is N-API based and ships prebuilt binaries (`prebuilds/`) for
+linux-x64, linux-arm64, win32-x64 and darwin-arm64 — no compiler toolchain
+is needed on those platforms. On other platforms it falls back to compiling
+from source via `node-gyp-build` (requires a C++ toolchain).
+
+Prebuilds are produced by the `prebuild` GitHub Actions workflow
+(`npm run prebuild` runs `prebuildify --napi --strip` for the current
+platform). Before `npm publish`, download the merged `prebuilds` artifact
+from the workflow run and place it in the package root as `prebuilds/`.
 
 ### Usage
 
 ```javascript
-var lzf = require("lzf");
+const lzf = require('@trkyshorty/node-lzf');
 
+const data = Buffer.from('some data to compress');
 
-var lorem = "Lorem ipsum dolor sit amet, consectetur adipiscing elit." +
-    "Curabitur volutpat, nulla nec egestas semper," +
-    "ante dui tristique nibh, quis feugiat.";
+// sync — runs on the calling thread
+const compressed = lzf.compress(data);
+const restored = lzf.decompress(compressed, data.length);
 
-// create buffer of your data
-var loremBuffer = new Buffer(lorem);
+// async — runs on the libuv thread pool, never blocks the event loop
+const compressed2 = await lzf.compressAsync(data);
+const restored2 = await lzf.decompressAsync(compressed2, data.length);
+```
 
-// compress your buffer and get another buffer
-var loremCompressed = lzf.compress(loremBuffer);
+#### TypeScript
 
-// decompress compressed buffer
-var loremDecompressed = lzf.decompress(loremCompressed);
+Type definitions are bundled, no `@types` package is needed. The module is
+CommonJS (`export =`), so import it as a namespace — or as a default import
+when `esModuleInterop` is enabled:
 
-```
+```typescript
+import * as lzf from '@trkyshorty/node-lzf';
+// with "esModuleInterop": true you can also write:
+// import lzf from '@trkyshorty/node-lzf';
 
-### Benchmarks
+const data: Buffer = Buffer.from('some data to compress');
 
-Benchmarks against [compress-buffer](https://github.com/egorFiNE/node-compress-buffer) library. Just to be short: it's faster.
+// sync
+const compressed: Buffer = lzf.compress(data);
+const restored: Buffer = lzf.decompress(compressed, data.length);
 
+// async
+async function roundtrip(input: Buffer): Promise<Buffer> {
+    const packed = await lzf.compressAsync(input);
+    return lzf.decompressAsync(packed, input.length);
+}
 ```
-Testing compression at 100 bytes
-lzf-compress x 139,495 ops/sec ±11.88% (58 runs sampled)
-zlib-compress x 29,879 ops/sec ±6.88% (88 runs sampled)
-Fastest is lzf-compress
-
-Testing decompression at 100 bytes
-lzf-decompress x 36,574 ops/sec ±7.74% (87 runs sampled)
-zlib-decompress x 26,153 ops/sec ±6.92% (89 runs sampled)
-Fastest is lzf-decompress
-
-Testing compression at 1000 bytes
-lzf-compress x 57,345 ops/sec ±9.49% (81 runs sampled)
-zlib-compress x 11,828 ops/sec ±3.93% (60 runs sampled)
-Fastest is lzf-compress
-
-Testing decompression at 1000 bytes
-lzf-decompress x 29,221 ops/sec ±7.06% (89 runs sampled)
-zlib-decompress x 19,351 ops/sec ±4.77% (92 runs sampled)
-Fastest is lzf-decompress
-
-Testing compression at 10000 bytes
-lzf-compress x 10,512 ops/sec ±3.26% (92 runs sampled)
-zlib-compress x 1,850 ops/sec ±0.20% (73 runs sampled)
-Fastest is lzf-compress
-
-Testing decompression at 10000 bytes
-lzf-decompress x 12,487 ops/sec ±3.85% (91 runs sampled)
-zlib-decompress x 6,939 ops/sec ±3.14% (93 runs sampled)
-Fastest is lzf-decompress
-
-Testing compression at 100000 bytes
-lzf-compress x 1,628 ops/sec ±1.50% (96 runs sampled)
-zlib-compress x 132 ops/sec ±0.13% (93 runs sampled)
-Fastest is lzf-compress
-
-Testing decompression at 100000 bytes
-lzf-decompress x 2,472 ops/sec ±1.09% (91 runs sampled)
-zlib-decompress x 1,430 ops/sec ±0.73% (95 runs sampled)
-Fastest is lzf-decompress
+
+### API
+
+TypeScript definitions are bundled (`index.d.ts`).
+
+#### `compress(data: Buffer): Buffer`
+
+Returns an LZF-compressed Buffer sized exactly to the result. Throws
+`TypeError` if `data` is not a Buffer, is empty, or exceeds 1 GiB.
+Note: incompressible input can grow slightly (up to ~104%).
+
+#### `decompress(data: Buffer, expectedLength: number): Buffer`
+
+Returns the decompressed Buffer. `expectedLength` is **required** — pass the
+exact decompressed size (or an upper bound); the result is shrunk to the
+actual size. Throws `TypeError`/`RangeError` for invalid arguments
+(`expectedLength` must be an integer between 1 and 1 GiB) and `Error` with
+a descriptive message when the input is corrupted (`corrupted input`) or
+`expectedLength` is too small (`expected length too small`). The
+decompressor is safe on untrusted input: corrupt streams throw instead of
+reading or writing out of bounds.
+
+> **v1.1.0 note:** older versions allowed omitting `expectedLength` and
+> silently allocated a 999 MB scratch buffer per call — that default has
+> been removed.
+
+#### `compressAsync(data: Buffer): Promise<Buffer>` / `decompressAsync(data: Buffer, expectedLength: number): Promise<Buffer>`
+
+Same semantics as the sync variants, but the (de)compression runs on the
+libuv thread pool and the returned promise rejects with the errors the sync
+variants would throw. Prefer these for payloads larger than a few hundred
+KB on latency-sensitive servers.
+
+Compressed output is a valid LZF stream decodable by any liblzf build.
+The exact compressed bytes are not guaranteed to be identical across calls
+(liblzf's hash table is intentionally left uninitialized for speed) — only
+the roundtrip contract holds.
+
+### Benchmarks
+
+`npm run bench` compares against node's built-in zlib (`deflateRaw`,
+levels 1 and 6) on deterministic datasets. Numbers below from a Windows
+x64 machine, Node 24 (`ratio` = compressed/original; lower is better):
+
+```text
+dataset      codec      ratio   comp ms  comp MB/s  decomp ms  decomp MB/s
+text 100KB   lzf          40%     0.158        433      0.094          726
+text 100KB   zlib-1       30%     0.354        194      0.122          562
+text 100KB   zlib-6       27%     1.421         48      0.120          570
+json 64KB    lzf          37%     0.039        917      0.037          963
+json 64KB    zlib-1       24%     0.122        291      0.054          658
+json 64KB    zlib-6       19%     0.486         73      0.049          722
+json 2MB     lzf          36%     1.837        617      1.156          980
+json 2MB     zlib-1       24%     4.383        259      1.511          750
+json 2MB     zlib-6       18%    17.541         65      1.311          865
+binary 4KB   lzf          79%     0.008        509      0.004          904
+binary 4KB   zlib-1       72%     0.039        100      0.011          346
+binary 64KB  lzf          76%     0.127        493      0.049         1286
+binary 64KB  zlib-1       71%     0.660         95      0.127          492
+random 1MB   lzf         103%     2.816        355      0.415         2410
+random 1MB   zlib-1      100%    15.080         66      0.385         2598
+zeros 1MB    lzf           1%     0.273       3660      1.531          653
+zeros 1MB    zlib-1        0%     0.350       2861      0.473         2115
 ```
 
+In short: LZF compresses 2–10× faster than zlib at its fastest level, at
+the cost of a worse ratio. Pick LZF when compression latency matters more
+than size (hot network paths); pick zlib/brotli for cold storage.
+
 ---
+
 ### Authors
-- Ian Babrou (ibobrik@gmail.com)
+
+- Ian Babrou (`ibobrik@gmail.com`) — original author
+- Türkay Tanrikulu (`trky.shorty@gmail.com`) — fork maintainer
+
+### License
+
+BSD-2-Clause, see [LICENSE](LICENSE). Bundles [liblzf](http://oldhome.schmorp.de/marc/liblzf.html)
+by Marc Alexander Lehmann (BSD-2-Clause / GPL dual-licensed).

package/binding.gyp

@@ -8,14 +8,21 @@
         "src/lzf/lzf_d.cc"
       ],
       "include_dirs": [
-        "<!(node -e \"require('nan')\")",
+        "<!(node -p \"require('node-addon-api').include_dir\")",
         "src/lzf"
       ],
+      "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ],
+      # -Wno-implicit-fallthrough: upstream liblzf (src/lzf/lzf_d.cc) deliberately unrolls its
+      # copy loops with "case" fallthrough (Duff's device); the warning gcc enables with -Wextra
+      # is not a bug here. The vendored code and our own code (src/lzf.cc) build as a single
+      # target, so the suppression is target-wide; we do not rewrite the algorithm. MSVC does
+      # not emit this warning, so no flag is added on Windows.
       "conditions": [
         [
           'OS=="linux" or OS=="freebsd" or OS=="openbsd" or OS=="solaris"',
           {
-            "cflags": [ "-O3" ],
+            "cflags": [ "-O3", "-Wno-implicit-fallthrough" ],
+            "cflags_cc": [ "-O3" ],
             "conditions": [
               ["target_arch=='x64'", { "cflags": [ "-fPIC" ] }]
             ]
@@ -25,7 +32,7 @@
           "OS=='mac'",
           {
             "xcode_settings": {
-              "OTHER_CFLAGS": [ "-O3" ]
+              "OTHER_CFLAGS": [ "-O3", "-Wno-implicit-fallthrough" ]
             }
           }
         ],

package/index.d.ts

@@ -0,0 +1,33 @@
+/// <reference types="node" />
+
+declare namespace lzf {
+    /**
+     * Compresses a Buffer with LZF. Throws TypeError on invalid input
+     * (non-Buffer, empty, or larger than 1 GiB). Runs synchronously on
+     * the calling thread.
+     */
+    function compress(data: Buffer): Buffer;
+
+    /**
+     * Compresses a Buffer with LZF on the libuv thread pool without
+     * blocking the event loop. Rejects with the same errors compress()
+     * throws.
+     */
+    function compressAsync(data: Buffer): Promise<Buffer>;
+
+    /**
+     * Decompresses an LZF-compressed Buffer. expectedLength is the exact
+     * (or an upper bound of the) decompressed size, between 1 and 1 GiB.
+     * Throws TypeError/RangeError on invalid arguments and Error when the
+     * input is corrupted or expectedLength is too small.
+     */
+    function decompress(data: Buffer, expectedLength: number): Buffer;
+
+    /**
+     * Decompresses on the libuv thread pool without blocking the event
+     * loop. Rejects with the same errors decompress() throws.
+     */
+    function decompressAsync(data: Buffer, expectedLength: number): Promise<Buffer>;
+}
+
+export = lzf;

package/index.js

@@ -1,5 +1,4 @@
-try {
-    module.exports = require('./build/default/lzf.node');
-} catch(e) {
-    module.exports = require('./build/Release/lzf.node');
-}
+// Resolves a bundled prebuild for the current platform/arch when available
+// (prebuilds/<platform>-<arch>/node.napi.node), otherwise falls back to a
+// locally compiled build/Release/lzf.node.
+module.exports = require('node-gyp-build')(__dirname);

package/package.json

@@ -1,26 +1,48 @@
 {
-    "name": "@trkyshorty/node-lzf",
-    "version": "1.0.0",
-    "description": "lzf compression module for nodejs (Topface/node-lzf fork with mem-leak fix)",
-    "keywords": ["lzf", "compression", "buffer"],
-    "author": "Ian Babrou <ibobrik@gmail.com>",
-    "engines": [
-        "node"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/trkyshorty/node-lzf.git"
-    },
-    "dependencies": {
-        "nan": "^2.18.0"
-    },
-    "directories": {
-        "lib": "./lib"
-    },
-    "main": "./index",
-    "gypfile": true,
-    "scripts": {
-        "test": "node test/test.js"
-    },
-    "license": "BSD-2-Clause"
+  "name": "@trkyshorty/node-lzf",
+  "version": "1.2.0",
+  "description": "lzf compression module for nodejs (Topface/node-lzf fork)",
+  "keywords": [
+    "lzf",
+    "compression",
+    "buffer",
+    "prebuilds",
+    "napi"
+  ],
+  "author": "Türkay TANRIKULU <trky.shorty@gmail.com>",
+  "contributors": [
+    "Ian Babrou <ibobrik@gmail.com>"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trkyshorty/node-lzf.git"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.3.0",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "prebuildify": "^6.0.1"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "gypfile": true,
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "binding.gyp",
+    "src/",
+    "prebuilds/",
+    "README.md"
+  ],
+  "scripts": {
+    "install": "node-gyp-build",
+    "prebuild": "prebuildify --napi --strip",
+    "test": "node --test test/test.js",
+    "bench": "node benchmark/benchmark.js"
+  },
+  "license": "BSD-2-Clause"
 }

package/src/lzf/lzfP.h

@@ -78,8 +78,17 @@
 /*
  * Unconditionally aligning does not cost very much, so do it if unsure
  */
+/*
+ * node-lzf: upstream used `# define STRICT_ALIGN !(defined(__i386) || defined (__amd64))`;
+ * a `defined` operator produced by macro expansion is undefined behavior in the standard
+ * (gcc/clang -Wexpansion-to-defined). We select the same value directly with #if.
+ */
 #ifndef STRICT_ALIGN
-# define STRICT_ALIGN !(defined(__i386) || defined (__amd64))
+# if defined(__i386) || defined (__amd64)
+#  define STRICT_ALIGN 0
+# else
+#  define STRICT_ALIGN 1
+# endif
 #endif
 
 /*
@@ -142,7 +151,12 @@ using namespace std;
 
 #ifndef LZF_USE_OFFSETS
 # if defined (WIN32)
-#  define LZF_USE_OFFSETS defined(_M_X64)
+   /* node-lzf: replaces upstream's macro-expanded `defined(_M_X64)`; same rationale as STRICT_ALIGN. */
+#  if defined(_M_X64)
+#   define LZF_USE_OFFSETS 1
+#  else
+#   define LZF_USE_OFFSETS 0
+#  endif
 # else
 #  if __cplusplus > 199711L
 #   include <cstdint>