@falkordb/text-to-cypher 0.1.17 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-06-21
+
+### Added
+- **UDF context**: surface a FalkorDB instance's user-defined functions to the model so generated
+  Cypher can call them (`RETURN library.function(...)`). New `ClientOptions` fields:
+  - `discoverUdfs?: boolean` — discover instance UDFs via `GRAPH.UDF LIST` during query generation
+    (off by default; client-level, also applies to `cypherOnly`).
+  - `udfs?: UdfLibraryInput[]` — a caller-supplied catalog (takes precedence over `discoverUdfs`)
+    to avoid an extra discovery round-trip when the UDF list is already known.
+
+### Changed
+- Bumped the `text-to-cypher` Rust dependency to `0.2.0` (UDF context + falkordb-rs `0.9.0`). The
+  binding's existing public TypeScript API is unchanged; the new options are additive and opt-in.
+
+## [0.1.18] - 2026-06-20
+
+### Changed
+- Bumped the `text-to-cypher` Rust dependency to `0.1.21` — brings falkordb-rs `0.8.9`, a
+  read-only retry policy, and gated FalkorDB tracing under the hood. The binding's public TypeScript
+  API is unchanged (patch release).
+
+### CI
+- Re-enabled the macOS **x64** and **universal-apple-darwin** release targets (previously disabled).
+
 ## [0.1.17] - 2026-06-10
 
 ### Added
@@ -96,6 +120,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Proper error handling and propagation from Rust to JavaScript
 - Zero runtime dependencies
 
+[0.2.0]: https://github.com/FalkorDB/text-to-cypher-node/releases/tag/v0.2.0
+[0.1.18]: https://github.com/FalkorDB/text-to-cypher-node/releases/tag/v0.1.18
 [0.1.17]: https://github.com/FalkorDB/text-to-cypher-node/releases/tag/v0.1.17
 [0.1.16]: https://github.com/FalkorDB/text-to-cypher-node/releases/tag/v0.1.16
 [0.1.15]: https://github.com/FalkorDB/text-to-cypher-node/releases/tag/v0.1.15

package/README.md

@@ -60,6 +60,8 @@ Creates a new text-to-cypher client.
 - `options.apiKey` (string): API key for the AI service
 - `options.falkordbConnection` (string): FalkorDB connection string (e.g., `'falkor://localhost:6379'`)
 - `options.llmEndpoint` (string, optional): Custom LLM provider endpoint/base URL for OpenAI-compatible local providers such as LM Studio (e.g., `'http://localhost:1234/v1'`)
+- `options.discoverUdfs` (boolean, optional): When `true`, discover the connected instance's user-defined functions (UDFs) via `GRAPH.UDF LIST` and surface their `library.function` call targets to the model. Off by default. Client-level — applies to `textToCypher`, `textToCypherWithMessages`, and `cypherOnly`. Ignored when `udfs` is provided.
+- `options.udfs` (`UdfLibraryInput[]`, optional): A caller-supplied UDF catalog to surface to the model. Takes precedence over `discoverUdfs` — use it when you already have the UDF list (e.g. from `GRAPH.UDF LIST`) to avoid an extra discovery round-trip.
 
 **Example:**
 ```javascript
@@ -81,6 +83,26 @@ const client = new TextToCypher({
 });
 ```
 
+To let generated Cypher call your instance's UDFs, either discover them automatically or pass a catalog you already have:
+
+```javascript
+// Auto-discover (one GRAPH.UDF LIST during generation)
+const client = new TextToCypher({
+  model: 'gpt-4o-mini',
+  apiKey: 'sk-...',
+  falkordbConnection: 'falkor://localhost:6379',
+  discoverUdfs: true
+});
+
+// Or supply a catalog you already fetched (no extra round-trip)
+const client = new TextToCypher({
+  model: 'gpt-4o-mini',
+  apiKey: 'sk-...',
+  falkordbConnection: 'falkor://localhost:6379',
+  udfs: [{ name: 'geo', functions: [{ name: 'distance' }, { name: 'within' }] }]
+});
+```
+
 ### `textToCypher(graphName, question)`
 
 Converts natural language to Cypher, executes the query, and generates a natural language answer.

package/index.d.ts

@@ -195,6 +195,19 @@ export interface ClientOptions {
   falkordbConnection: string
   /** Optional LLM provider endpoint/base URL override */
   llmEndpoint?: string
+  /**
+   * When true, discover the connected instance's user-defined functions (UDFs) and surface their
+   * `library.function` call targets to the model. Off by default. This is a client-level option,
+   * so it applies to `textToCypher`, `textToCypherWithMessages`, and `cypherOnly` (i.e. it may
+   * run `GRAPH.UDF LIST` against FalkorDB during query generation). Ignored when `udfs` is set.
+   */
+  discoverUdfs?: boolean
+  /**
+   * A caller-supplied UDF catalog to surface to the model. Takes precedence over `discoverUdfs`.
+   * Use this when you already have the UDF list (e.g. from `GRAPH.UDF LIST`) to avoid an extra
+   * discovery round-trip.
+   */
+  udfs?: Array<UdfLibraryInput>
 }
 
 /** A chat message in the conversation */
@@ -241,3 +254,21 @@ export interface TokenUsage {
   /** Total tokens consumed across all LLM calls */
   totalTokens: number
 }
+
+/** A user-defined function to surface to the model. */
+export interface UdfFunctionInput {
+  /** Function name; the right-hand side of a `library.function(...)` call */
+  name: string
+  /** Optional signature hint (e.g. "(x, y)") */
+  signatureHint?: string
+  /** Optional human-readable description */
+  description?: string
+}
+
+/** A user-defined function library (namespace) and its functions. */
+export interface UdfLibraryInput {
+  /** Library name; the left side of a `library.function(...)` call */
+  name: string
+  /** Functions registered in this library */
+  functions: Array<UdfFunctionInput>
+}

package/index.js

@@ -3,7 +3,7 @@
 // @ts-nocheck
 /* auto-generated by NAPI-RS */
 
-const { readFileSync } = require('node:fs')
+const { readFileSync } = require('fs')
 let nativeBinding = null
 const loadErrors = []
 
@@ -33,7 +33,7 @@ const isMuslFromFilesystem = () => {
 
 const isMuslFromReport = () => {
   let report = null
-  if (typeof process.report?.getReport === 'function') {
+  if (process.report && typeof process.report.getReport === 'function') {
     process.report.excludeNetwork = true
     report = process.report.getReport()
   }
@@ -77,8 +77,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-android-arm64')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-android-arm-eabi')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -105,7 +105,7 @@ function requireNative() {
     }
   } else if (process.platform === 'win32') {
     if (process.arch === 'x64') {
-      if (process.config?.variables?.shlib_suffix === 'dll.a' || process.config?.variables?.node_target_type === 'shared_library') {
+      if ((process.config && process.config.variables && process.config.variables.shlib_suffix === 'dll.a') || (process.config && process.config.variables && process.config.variables.node_target_type === 'shared_library')) {
         try {
         return require('./text-to-cypher.win32-x64-gnu.node')
       } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-win32-x64-gnu')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-win32-x64-msvc')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-win32-ia32-msvc')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-win32-arm64-msvc')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
     try {
       const binding = require('@falkordb/text-to-cypher-darwin-universal')
       const bindingPackageVersion = require('@falkordb/text-to-cypher-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-darwin-x64')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-darwin-arm64')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-freebsd-x64')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-freebsd-arm64')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-x64-musl')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-x64-gnu')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-arm64-musl')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-arm64-gnu')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-arm-musleabihf')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-loong64-musl')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-loong64-gnu')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-riscv64-musl')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
         try {
           const binding = require('@falkordb/text-to-cypher-linux-riscv64-gnu')
           const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-linux-ppc64-gnu')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-linux-s390x-gnu')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-openharmony-arm64')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-openharmony-x64')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
       try {
         const binding = require('@falkordb/text-to-cypher-openharmony-arm')
         const bindingPackageVersion = require('@falkordb/text-to-cypher-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.1.17' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.17 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -525,23 +525,33 @@ function requireNative() {
 
 nativeBinding = requireNative()
 
-if (!nativeBinding || process.env.NAPI_RS_FORCE_WASI) {
+// NAPI_RS_FORCE_WASI is a tri-state flag:
+//   unset / any other value → native binding preferred, WASI is only a fallback
+//   'true'                   → force WASI fallback even if native loaded
+//   'error'                  → force WASI and throw if no WASI binding is found
+// Treating any non-empty string as truthy (the historical behavior) meant
+// NAPI_RS_FORCE_WASI=false, NAPI_RS_FORCE_WASI=0, etc. inadvertently triggered
+// the WASI path, causing ENOENT for packages shipped without a .wasi.cjs file.
+const forceWasi =
+  process.env.NAPI_RS_FORCE_WASI === 'true' || process.env.NAPI_RS_FORCE_WASI === 'error'
+
+if (!nativeBinding || forceWasi) {
   let wasiBinding = null
   let wasiBindingError = null
   try {
     wasiBinding = require('./text-to-cypher.wasi.cjs')
     nativeBinding = wasiBinding
   } catch (err) {
-    if (process.env.NAPI_RS_FORCE_WASI) {
+    if (forceWasi) {
       wasiBindingError = err
     }
   }
-  if (!nativeBinding || process.env.NAPI_RS_FORCE_WASI) {
+  if (!nativeBinding || forceWasi) {
     try {
       wasiBinding = require('@falkordb/text-to-cypher-wasm32-wasi')
       nativeBinding = wasiBinding
     } catch (err) {
-      if (process.env.NAPI_RS_FORCE_WASI) {
+      if (forceWasi) {
         if (!wasiBindingError) {
           wasiBindingError = err
         } else {
@@ -560,17 +570,18 @@ if (!nativeBinding || process.env.NAPI_RS_FORCE_WASI) {
 
 if (!nativeBinding) {
   if (loadErrors.length > 0) {
-    throw new Error(
+    const error = new Error(
       `Cannot find native binding. ` +
         `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +
         'Please try `npm i` again after removing both package-lock.json and node_modules directory.',
-      {
-        cause: loadErrors.reduce((err, cur) => {
-          cur.cause = err
-          return cur
-        }),
-      },
     )
+    // assign instead of the `new Error(message, { cause })` options form,
+    // which Node < 16.9 silently ignores
+    error.cause = loadErrors.reduce((err, cur) => {
+      cur.cause = err
+      return cur
+    })
+    throw error
   }
   throw new Error(`Failed to load native binding`)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkordb/text-to-cypher",
-  "version": "0.1.17",
+  "version": "0.2.0",
   "description": "Node.js bindings for FalkorDB text-to-cypher library - Convert natural language to Cypher queries",
   "main": "index.js",
   "types": "index.d.ts",