feat: diffWindow accepts optional windowSize parameter

sunnylqm · claude · sunnylqm · commit 4f42a8092853 · 2026-07-08T15:15:24.000+08:00
(oldPath, newPath, outDiffPath[, windowSize][, cb]) — sliding-window
byte size over old data, default 2MB. Larger windows catch
longer-distance content moves at roughly linear additional memory.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -46,7 +46,7 @@ in-memory `diff()` for the same inputs; prefer `diff()` when memory allows.
 In sync mode returns `outDiffPath`; async callback signature is
 `(err, outDiffPath)`.
 
-### diffWindow(oldPath, newPath, outDiffPath[, cb])
+### diffWindow(oldPath, newPath, outDiffPath[, windowSize][, cb])
 
 Create a **single-format** (same wire format as `diff()`) patch using window
 mode: big covers come from streaming block matching, then residuals are
@@ -56,6 +56,9 @@ stays at the streaming tier — usually a much smaller patch than
 `diffSingleStream()` for the same inputs. The output applies with `patch()`,
 `patchSingleStream()`, and any existing single-format apply side. In sync mode
 returns `outDiffPath`; async callback signature is `(err, outDiffPath)`.
+`windowSize` is the sliding-window byte size over the old data (default 2MB);
+a larger window catches longer-distance content moves at roughly linear
+additional memory.
 
 ### patchSingleStream(oldPath, diffPath, outNewPath[, cb])
 
diff --git a/index.d.ts b/index.d.ts
@@ -38,11 +38,23 @@ export interface NativeAddon {
     outNewPath: string,
     cb: StreamCallback
   ): void;
-  diffWindow(oldPath: string, newPath: string, outDiffPath: string): string;
   diffWindow(
     oldPath: string,
     newPath: string,
     outDiffPath: string,
+    windowSize?: number
+  ): string;
+  diffWindow(
+    oldPath: string,
+    newPath: string,
+    outDiffPath: string,
+    cb: StreamCallback
+  ): void;
+  diffWindow(
+    oldPath: string,
+    newPath: string,
+    outDiffPath: string,
+    windowSize: number,
     cb: StreamCallback
   ): void;
 }
@@ -110,18 +122,28 @@ export function patchSingleStream(
 ): void;
 
 // window 模式生成 HDIFFSF20 single 格式 patch:匹配质量接近内存版
-// diff(),内存占用保持流式档;产物用 patch()/patchSingleStream() 应用
+// diff(),内存占用保持流式档;产物用 patch()/patchSingleStream() 应用。
+// windowSize 为 old 数据滑动窗口字节数(缺省 2MB),调大可捕获更长距离
+// 的内容移动,内存占用近似线性增长。
 export function diffWindow(
   oldPath: string,
   newPath: string,
-  outDiffPath: string
+  outDiffPath: string,
+  windowSize?: number
 ): string;
 export function diffWindow(
   oldPath: string,
   newPath: string,
   outDiffPath: string,
   cb: StreamCallback
 ): void;
+export function diffWindow(
+  oldPath: string,
+  newPath: string,
+  outDiffPath: string,
+  windowSize: number,
+  cb: StreamCallback
+): void;
 
 declare const hdiffpatch: {
   native: NativeAddon;
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "node-hdiffpatch",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "hdiffpatch port to node.js",
   "main": "index.js",
   "types": "index.d.ts",
diff --git a/src/hdiff.cpp b/src/hdiff.cpp
@@ -145,7 +145,8 @@ void hdiff_stream(const char* oldPath,const char* newPath,const char* outDiffPat
     streams.closeAllOrThrow();
 }
 
-void hdiff_window(const char* oldPath,const char* newPath,const char* outDiffPath){
+void hdiff_window(const char* oldPath,const char* newPath,const char* outDiffPath,
+                  size_t windowSize){
     if (!oldPath || !newPath || !outDiffPath) {
         throw std::runtime_error("Invalid file path.");
     }
@@ -158,13 +159,15 @@ void hdiff_window(const char* oldPath,const char* newPath,const char* outDiffPat
     streams.openInputs(oldPath, newPath);
     streams.openDiffOut(outDiffPath);
 
-    // window 模式:大块流式匹配拿大 cover,再在 old 数据的滑动窗口
-    // (默认 2MB)内做后缀串精修。除 patchStepMemSize/匹配分沿用本库
-    // 固定值外,其余参数取 v5 默认。
+    // window 模式:大块流式匹配拿大 cover,再在 old 数据的滑动窗口内做
+    // 后缀串精修。窗口默认 2MB,可调大以捕获更长距离的内容移动;
+    // kSegSize 传 0 由上游自动取 windowSize/64。除 patchStepMemSize/
+    // 匹配分沿用本库固定值外,其余参数取 v5 默认。
+    if (windowSize == 0) windowSize = kDefaultWindowOldSize;
     create_single_compressed_diff_window(&streams.newStream.base, &streams.oldStream.base,
                                          &streams.diffOutStream.base,
                                          &compressPlugin.base, kPatchStepMemSize,
-                                         kDefaultWindowOldSize, 0,
+                                         windowSize, 0,
                                          kDefaultBigCoverSize, kMatchWindowsBlockSize_default,
                                          kDefaultFastMatchBlockSize,
                                          kSingleMatchScore);
diff --git a/src/hdiff.h b/src/hdiff.h
@@ -16,7 +16,10 @@ void hdiff_stream(const char* oldPath,const char* newPath,const char* outDiffPat
 // 任何既有 single 应用端可直接使用)
 void hdiff_single_stream(const char* oldPath,const char* newPath,const char* outDiffPath);
 // HDIFFSF20 single 格式的 window 模式生成:大块流式匹配 + 窗口内后缀串
-// 精修,匹配质量接近内存版而内存占用保持流式档;产物与 diff() 同格式
-void hdiff_window(const char* oldPath,const char* newPath,const char* outDiffPath);
+// 精修,匹配质量接近内存版而内存占用保持流式档;产物与 diff() 同格式。
+// windowSize 为 old 数据滑动窗口字节数,0 表示用默认值(2MB);窗口越大
+// 能捕获越长距离的内容移动,内存占用近似随之线性增长。
+void hdiff_window(const char* oldPath,const char* newPath,const char* outDiffPath,
+                  size_t windowSize=0);
 
 #endif
diff --git a/src/main.cc b/src/main.cc
@@ -472,16 +472,19 @@ namespace hdiffpatchNode
         DiffWindowAsyncWorker(Napi::Function& callback,
                               std::string oldPath,
                               std::string newPath,
-                              std::string outDiffPath)
+                              std::string outDiffPath,
+                              size_t windowSize)
             : Napi::AsyncWorker(callback),
               oldPath_(std::move(oldPath)),
               newPath_(std::move(newPath)),
-              outDiffPath_(std::move(outDiffPath)) {
+              outDiffPath_(std::move(outDiffPath)),
+              windowSize_(windowSize) {
         }
 
         void Execute() override {
             try {
-                hdiff_window(oldPath_.c_str(), newPath_.c_str(), outDiffPath_.c_str());
+                hdiff_window(oldPath_.c_str(), newPath_.c_str(), outDiffPath_.c_str(),
+                             windowSize_);
             } catch (const std::exception& e) {
                 SetError(e.what());
             }
@@ -503,6 +506,7 @@ namespace hdiffpatchNode
         std::string oldPath_;
         std::string newPath_;
         std::string outDiffPath_;
+        size_t windowSize_;
     };
 
     // ============ 同步/异步 diffSingleStream ============
@@ -546,6 +550,9 @@ namespace hdiffpatchNode
     // single 格式(HDIFFSF20)的 window 模式生成:大块流式匹配 + 窗口内
     // 后缀串精修,匹配质量接近内存版 diff() 而内存占用保持流式档。
     // 产物与 diff()/diffSingleStream() 同格式,既有应用端可直接应用。
+    // 签名:(oldPath, newPath, outDiffPath[, windowSize][, cb])
+    // windowSize 为 old 数据滑动窗口字节数(缺省 2MB),调大可捕获更长
+    // 距离的内容移动,内存占用近似线性增长。
     Napi::Value diffWindow(const Napi::CallbackInfo& info) {
         Napi::Env env = info.Env();
 
@@ -556,22 +563,36 @@ namespace hdiffpatchNode
             !getStringUtf8(info[0], oldPath) ||
             !getStringUtf8(info[1], newPath) ||
             !getStringUtf8(info[2], outDiffPath)) {
-            Napi::TypeError::New(env, "Invalid arguments: expected (oldPath, newPath, outDiffPath).")
+            Napi::TypeError::New(env, "Invalid arguments: expected (oldPath, newPath, outDiffPath[, windowSize][, cb]).")
                 .ThrowAsJavaScriptException();
             return env.Undefined();
         }
 
-        if (info.Length() > 3 && info[3].IsFunction()) {
-            Napi::Function callback = info[3].As<Napi::Function>();
+        size_t windowSize = 0;  // 0 = 使用默认窗口(2MB)
+        size_t argIdx = 3;
+        if (info.Length() > argIdx && info[argIdx].IsNumber()) {
+            double raw = info[argIdx].As<Napi::Number>().DoubleValue();
+            if (!std::isfinite(raw) || raw < 0 ||
+                raw > static_cast<double>(std::numeric_limits<size_t>::max())) {
+                Napi::TypeError::New(env, "Invalid windowSize: expected a non-negative integer.")
+                    .ThrowAsJavaScriptException();
+                return env.Undefined();
+            }
+            windowSize = static_cast<size_t>(raw);
+            argIdx++;
+        }
+
+        if (info.Length() > argIdx && info[argIdx].IsFunction()) {
+            Napi::Function callback = info[argIdx].As<Napi::Function>();
             DiffWindowAsyncWorker* worker = new DiffWindowAsyncWorker(
-                callback, oldPath, newPath, outDiffPath
+                callback, oldPath, newPath, outDiffPath, windowSize
             );
             worker->Queue();
             return env.Undefined();
         }
 
         try {
-            hdiff_window(oldPath.c_str(), newPath.c_str(), outDiffPath.c_str());
+            hdiff_window(oldPath.c_str(), newPath.c_str(), outDiffPath.c_str(), windowSize);
         } catch (const std::exception& e) {
             Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
             return env.Undefined();
diff --git a/test/test.js b/test/test.js
@@ -90,6 +90,14 @@ console.log(
   "  ✓ diffWindow output (" + winDiffData.length + "B vs diff " + diffResult.length +
   "B) applies via patch() and patchSingleStream()"
 );
+// 显式 windowSize(8MB)同步调用
+var winDiff8Path = path.join(ssDir, "win8.diff");
+hdiffpatch.diffWindow(ssOldPath, ssNewPath, winDiff8Path, 8 * 1024 * 1024);
+var winDiff8Data = fs.readFileSync(winDiff8Path);
+assert.strictEqual(winDiff8Data.slice(0, 9).toString("latin1"), "HDIFFSF20");
+assert.deepStrictEqual(hdiffpatch.patch(oldData, winDiff8Data), newData);
+assert.throws(() => hdiffpatch.diffWindow(ssOldPath, ssNewPath, winDiff8Path, -1));
+console.log("  ✓ diffWindow with explicit windowSize works, invalid size throws");
 
 console.log("\nTest 6: Single-compressed patchSingleStream (file paths)...");
 var tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "hdiffpatch-"));
@@ -165,6 +173,14 @@ async function runAsyncTests() {
   var asyncWinDiffPath = path.join(tempDir, "async-win.diff");
   assert.strictEqual(await diffWindowAsync(oldPath, newPath, asyncWinDiffPath), asyncWinDiffPath);
   assert.deepStrictEqual(hdiffpatch.patch(oldData, fs.readFileSync(asyncWinDiffPath)), newData);
+  // 带 windowSize 的异步形态:(old, new, out, windowSize, cb)
+  var asyncWin8Path = path.join(tempDir, "async-win8.diff");
+  await new Promise((resolve, reject) => {
+    hdiffpatch.diffWindow(oldPath, newPath, asyncWin8Path, 4 * 1024 * 1024, (err, out) =>
+      err ? reject(err) : resolve(out)
+    );
+  });
+  assert.deepStrictEqual(hdiffpatch.patch(oldData, fs.readFileSync(asyncWin8Path)), newData);
   await assert.rejects(
     () => diffWindowAsync(path.join(tempDir, "no-such.bin"), newPath, asyncWinDiffPath)
   );

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "node-hdiffpatch",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"description": "hdiffpatch port to node.js",`
`5`	`5`	`"main": "index.js",`
`6`	`6`	`"types": "index.d.ts",`