Make apache-arrow an optional dependency

docs/release-notes/index.md

@@ -20,6 +20,13 @@ To check for security updates, go to [Security announcements for the Elastic sta
 % ### Fixes [elasticsearch-javascript-client-next-fixes]
 % \*
 
+## 9.4.0 [elasticsearch-javascript-client-9.4.0-release-notes]
+
+### Features and enhancements [elasticsearch-javascript-client-9.4.0-features-enhancements]
+
+- **Compatibility with Elasticsearch 9.4:** All changes and additions to Elasticsearch APIs for its 9.4 release are reflected in this release.
+- **Apache Arrow is optional:** The `apache-arrow` package was added to support some useful ES|QL helpers, but is not needed unless those functions are used. It's a large package, so making it an optional peer dependency helps make the dependency tree smaller.
+
 ## 9.3.4 [elasticsearch-javascript-client-9.3.4-release-notes]
 
 ### Fixes [elasticsearch-javascript-client-9.3.4-fixes]

package.json

@@ -25,7 +25,7 @@
     }
   },
   "scripts": {
-    "test": "npm run build && npm run lint && c8 --exclude='**/api/**' --exclude='**/test/**' --check-coverage --statements=96 --branches=90 --lines=96 --functions=88 tap --disable-coverage",
+    "test": "npm run build && npm run lint && c8 --exclude='**/api/**' --exclude='**/test/**' --check-coverage --statements=96 --branches=90 --lines=96 --functions=91 tap --disable-coverage",
     "test:unit": "npm run build && tap",
     "test:unit-bun": "bun run build && bunx tap",
     "test:bundler": "npm run build && cd test/bundlers/repro && npm install file:../../.. && npx esbuild@0.24 --bundle --platform=node repro.mjs --outfile=bundled.js && node bundled.js",
@@ -109,11 +109,19 @@
     "typescript": "5.9.3",
     "workq": "3.0.0",
     "xmlbuilder2": "4.0.3",
-    "zx": "8.8.5"
+    "zx": "8.8.5",
+    "apache-arrow": "18.x - 21.x"
   },
   "dependencies": {
     "@elastic/transport": "^9.3.5",
-    "apache-arrow": "18.x - 21.x",
     "tslib": "^2.4.0"
+  },
+  "peerDependencies": {
+    "apache-arrow": "18.x - 21.x"
+  },
+  "peerDependenciesMeta": {
+    "apache-arrow": {
+      "optional": true
+    }
   }
 }

src/helpers.ts

@@ -11,11 +11,25 @@ import assert from 'node:assert'
 import * as timersPromises from 'node:timers/promises'
 import { Readable } from 'node:stream'
 import { errors, TransportResult, TransportRequestOptions, TransportRequestOptionsWithMeta } from '@elastic/transport'
-import { Table, TypeMap, tableFromIPC, AsyncRecordBatchStreamReader } from 'apache-arrow/Arrow.node'
+import type { Table, TypeMap, AsyncRecordBatchStreamReader } from 'apache-arrow/Arrow.node'
 import Client from './client'
 import * as T from './api/types'
 import { Id } from './api/types'
 
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+function loadArrow (): typeof import('apache-arrow/Arrow.node') {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require('apache-arrow/Arrow.node') as typeof import('apache-arrow/Arrow.node')
+  } catch /* c8 ignore next */ {
+    /* c8 ignore next 4 */
+    throw new Error(
+      'Package "apache-arrow" is required for Arrow functionality. ' +
+      'Install it with: npm install apache-arrow'
+    )
+  }
+}
+
 export interface HelpersOptions {
   client: Client
   metaHeader: string | null
@@ -988,6 +1002,7 @@ export default class Helpers {
       },
 
       async toArrowTable (): Promise<Table<TypeMap>> {
+        const { tableFromIPC } = loadArrow()
         if (metaHeader !== null) {
           reqOptions.headers = reqOptions.headers ?? {}
           reqOptions.headers['x-elastic-client-meta'] = `${metaHeader as string},h=qa`
@@ -1001,6 +1016,7 @@ export default class Helpers {
       },
 
       async toArrowReader (): Promise<AsyncRecordBatchStreamReader> {
+        const { AsyncRecordBatchStreamReader } = loadArrow()
         if (metaHeader !== null) {
           reqOptions.headers = reqOptions.headers ?? {}
           reqOptions.headers['x-elastic-client-meta'] = `${metaHeader as string},h=qa`

test/unit/helpers/esql.test.ts

@@ -314,5 +314,7 @@ test('ES|QL helper', t => {
 
     t.end()
   })
+
+  // note: the loadArrow catch block (when apache-arrow is not installed) is excluded
   t.end()
 })