From dbc3687c7b9cfc2e5923d2c8a28a94cb6b9e56da Mon Sep 17 00:00:00 2001
From: "lancedb-gatefixer[bot]"
 <313497061+lancedb-gatefixer[bot]@users.noreply.github.com>
Date: Fri, 7 Aug 2026 17:31:53 +0800
Subject: [PATCH] fix(node): require compatible Node.js types (#3829)

## Summary

- require Node.js 18-compatible type declarations when TypeScript
consumers install them
- keep the type peer optional for JavaScript-only consumers
- add a regression test tying the Node type peer range to the supported
runtime

## Root cause

LanceDB requires Node.js 18 or newer, and its public types expose Apache
Arrow declarations that import built-ins through the node: scheme. The
package did not declare a matching @types/node peer requirement, so npm
accepted projects pinned to Node 12 declarations and TypeScript then
reported that node:stream and node:fs/promises did not exist.

## Validation

- pnpm lint
- pnpm build
- pnpm run docs
- pnpm test --runInBand (678 passed, 5 skipped)
- packed-package consumer probe rejects @types/node 12.20.55 and
installs with @types/node 18.19.130

Fixes #1713

<!-- lance-gatekeeper-fix:v1 agent=7a2b68f3daad20bed9e46cb8892d6e6c
generation=1 -->

Co-authored-by: Gatefixer <313497061+lancedb-gatefixer[bot]@users.noreply.github.com>
---
 nodejs/__test__/package.test.ts | 14 ++++++++++++++
 nodejs/package-lock.json        |  6 ++++++
 nodejs/package.json             |  6 ++++++
 3 files changed, 26 insertions(+)
 create mode 100644 nodejs/__test__/package.test.ts

diff --git a/nodejs/__test__/package.test.ts b/nodejs/__test__/package.test.ts
new file mode 100644
index 000000000..7743d73d6
--- /dev/null
+++ b/nodejs/__test__/package.test.ts
@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import packageJson = require("../package.json");
+
+describe("package metadata", () => {
+  it("requires Node.js type declarations compatible with the runtime", () => {
+    expect(packageJson.engines.node).toBe(">= 18");
+    expect(packageJson.peerDependencies["@types/node"]).toBe(">=18");
+    expect(packageJson.peerDependenciesMeta["@types/node"]).toEqual({
+      optional: true,
+    });
+  });
+});
diff --git a/nodejs/package-lock.json b/nodejs/package-lock.json
index 8e30b0fab..bdbd3cf79 100644
--- a/nodejs/package-lock.json
+++ b/nodejs/package-lock.json
@@ -55,7 +55,13 @@
         "openai": "4.29.2"
       },
       "peerDependencies": {
+        "@types/node": ">=18",
         "apache-arrow": ">=15.0.0 <=18.1.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        }
       }
     },
     "node_modules/@aws-crypto/crc32": {
diff --git a/nodejs/package.json b/nodejs/package.json
index f3f719af2..671f3f94d 100644
--- a/nodejs/package.json
+++ b/nodejs/package.json
@@ -101,6 +101,12 @@
     "openai": "4.29.2"
   },
   "peerDependencies": {
+    "@types/node": ">=18",
     "apache-arrow": ">=15.0.0 <=18.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
   }
 }