feat(sea): wire named query parameters (:name) through the napi binding

Completes SEA param parity: SeaSessionBackend now forwards `namedParameters`
to the kernel via `ExecuteOptions.namedParams` (kernel `param_named` /
`NamedTypedValueInput {name, sqlType, value?}`), alongside positional. New
`buildSeaNamedParams` reuses the same `toTypedValueInput` mapping (DECIMAL →
DECIMAL(p,s), NULL → VOID). Positional and named are mutually exclusive
(ParameterError, matching the Thrift backend).

Requires kernel napi `namedParams` (extends the positional codec, #84 line).

Validated live: named INT/STRING/DECIMAL/multi-param bind; both-forms rejected.
205 sea unit tests pass.

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

Author: msrathore-db

lib/sea/SeaNativeLoader.ts

@@ -84,6 +84,17 @@ export interface SeaNativeTypedValueInput {
   value?: string;
 }
 
+/**
+ * A single named bound parameter — a `SeaNativeTypedValueInput` plus its
+ * `:name`. Maps to the kernel's `param_named`. Built by
+ * `SeaPositionalParams.buildSeaNamedParams`.
+ */
+export interface SeaNativeNamedTypedValueInput {
+  name: string;
+  sqlType: string;
+  value?: string;
+}
+
 /**
  * Per-statement options accepted by the napi `executeStatement`. Matches
  * the kernel `ExecuteOptions`. All fields optional; an omitted/empty
@@ -95,6 +106,7 @@ export interface SeaNativeExecuteOptions {
   rowLimit?: number;
   queryTimeoutSecs?: number;
   positionalParams?: Array<SeaNativeTypedValueInput>;
+  namedParams?: Array<SeaNativeNamedTypedValueInput>;
 }
 
 export interface SeaNativeConnection {

lib/sea/SeaPositionalParams.ts

@@ -13,8 +13,7 @@
 // limitations under the License.
 
 import { DBSQLParameter, DBSQLParameterValue } from '../DBSQLParameter';
-import ParameterError from '../errors/ParameterError';
-import { SeaNativeTypedValueInput } from './SeaNativeLoader';
+import { SeaNativeTypedValueInput, SeaNativeNamedTypedValueInput } from './SeaNativeLoader';
 
 /**
  * Derive `(precision,scale)` from a decimal value string for the SEA
@@ -64,13 +63,9 @@ function toTypedValueInput(value: DBSQLParameter | DBSQLParameterValue): SeaNati
 
 /**
  * Convert the public `ordinalParameters` option into the napi
- * `positionalParams` array. Returns `undefined` when no positional params
- * were supplied (so the caller can keep the minimal no-options call shape).
- *
- * Named parameters are not yet bindable on the SEA path — the kernel napi
- * surface (`ExecuteOptions.positionalParams`) exposes positional only — so a
- * caller passing `namedParameters` is rejected with a clear `ParameterError`
- * rather than silently ignored.
+ * `positionalParams` array (1-based `?` placeholders). Returns `undefined`
+ * when none were supplied, so the caller can keep the minimal no-options
+ * call shape.
  */
 export function buildSeaPositionalParams(
   ordinalParameters?: Array<DBSQLParameter | DBSQLParameterValue>,
@@ -80,3 +75,21 @@ export function buildSeaPositionalParams(
   }
   return ordinalParameters.map(toTypedValueInput);
 }
+
+/**
+ * Convert the public `namedParameters` option (`Record<name, value>`) into
+ * the napi `namedParams` array (`:name` placeholders). Each value reuses the
+ * same `toTypedValueInput` mapping (DECIMAL → DECIMAL(p,s), NULL → VOID, …),
+ * then carries its name. Returns `undefined` when none were supplied.
+ */
+export function buildSeaNamedParams(
+  namedParameters?: Record<string, DBSQLParameter | DBSQLParameterValue>,
+): Array<SeaNativeNamedTypedValueInput> | undefined {
+  if (namedParameters === undefined || Object.keys(namedParameters).length === 0) {
+    return undefined;
+  }
+  return Object.keys(namedParameters).map((name) => ({
+    name,
+    ...toTypedValueInput(namedParameters[name]),
+  }));
+}

lib/sea/SeaSessionBackend.ts

@@ -36,7 +36,8 @@ import { decodeNapiKernelError } from './SeaErrorMapping';
 import SeaOperationBackend from './SeaOperationBackend';
 import SeaTableTypeFilter from './SeaTableTypeFilter';
 import { seaServerInfoValue } from './SeaServerInfo';
-import { buildSeaPositionalParams } from './SeaPositionalParams';
+import { buildSeaPositionalParams, buildSeaNamedParams } from './SeaPositionalParams';
+import ParameterError from '../errors/ParameterError';
 
 export interface SeaSessionBackendOptions {
   /** The opaque napi `Connection` handle returned by `openSession`. */
@@ -131,24 +132,23 @@ export default class SeaSessionBackend implements ISessionBackend {
   public async executeStatement(statement: string, options: ExecuteStatementOptions): Promise<IOperationBackend> {
     this.failIfClosed();
 
-    // Named params aren't bindable on the SEA path yet — the kernel napi
-    // surface (ExecuteOptions.positionalParams) exposes positional only.
-    // Reject rather than silently ignore.
-    if (options.namedParameters !== undefined && Object.keys(options.namedParameters).length > 0) {
-      throw new HiveDriverError(
-        'SEA executeStatement: named parameters are not supported yet (use positional `?` parameters).',
-      );
-    }
-
-    // Reduce positional `?` bindings to the napi `{ sqlType, value? }` inputs
-    // the kernel param codec accepts (DECIMAL → DECIMAL(p,s), NULL →
-    // value-less), reusing DBSQLParameter's stringification.
+    // Reduce `?` / `:name` bindings to the napi inputs the kernel param codec
+    // accepts (DECIMAL → DECIMAL(p,s), NULL → value-less), reusing
+    // DBSQLParameter's stringification. Positional and named are mutually
+    // exclusive at the SQL level (matches the Thrift backend).
     const positionalParams = buildSeaPositionalParams(options.ordinalParameters);
+    const namedParams = buildSeaNamedParams(options.namedParameters);
+    if (positionalParams !== undefined && namedParams !== undefined) {
+      throw new ParameterError('Driver does not support both ordinal and named parameters.');
+    }
 
     const nativeOptions: SeaNativeExecuteOptions = {};
     if (positionalParams !== undefined) {
       nativeOptions.positionalParams = positionalParams;
     }
+    if (namedParams !== undefined) {
+      nativeOptions.namedParams = namedParams;
+    }
     // JDBC `setQueryTimeout` is whole seconds; the kernel's
     // `query_timeout_secs` (SEA wait timeout, on_wait_timeout = CANCEL) is
     // the native equivalent. The SEA wire caps it at 50s server-side.

tests/unit/sea/execution.test.ts

@@ -376,17 +376,25 @@ describe('SeaSessionBackend', () => {
     expect(connection.lastOptions?.queryTimeoutSecs).to.equal(30);
   });
 
-  it('executeStatement still rejects namedParameters (positional only on SEA)', async () => {
+  it('executeStatement forwards namedParameters as napi namedParams ({name,sqlType,value})', async () => {
+    const connection = new FakeNativeConnection();
+    const session = makeSession(connection);
+    await session.executeStatement('SELECT :x', { namedParameters: { x: 'hello' } });
+    expect(connection.lastOptions?.namedParams).to.deep.equal([{ name: 'x', sqlType: 'STRING', value: 'hello' }]);
+    expect(connection.lastOptions?.positionalParams).to.equal(undefined);
+  });
+
+  it('executeStatement rejects mixing ordinal and named parameters', async () => {
     const connection = new FakeNativeConnection();
     const session = makeSession(connection);
     let thrown: unknown;
     try {
-      await session.executeStatement('SELECT :x', { namedParameters: { x: 1 } });
+      await session.executeStatement('SELECT ? AND :x', { ordinalParameters: [1], namedParameters: { x: 2 } });
     } catch (err) {
       thrown = err;
     }
-    expect(thrown).to.be.instanceOf(HiveDriverError);
-    expect((thrown as Error).message).to.match(/named parameters/);
+    expect(thrown).to.be.instanceOf(Error);
+    expect((thrown as Error).message).to.match(/both ordinal and named/);
   });
 
   it('executeStatement uses the no-options fast path when nothing is bound', async () => {

tests/unit/sea/positionalParams.test.ts

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 import { expect } from 'chai';
-import { buildSeaPositionalParams } from '../../../lib/sea/SeaPositionalParams';
+import { buildSeaPositionalParams, buildSeaNamedParams } from '../../../lib/sea/SeaPositionalParams';
 import { DBSQLParameter, DBSQLParameterType } from '../../../lib/DBSQLParameter';
 
 describe('SeaPositionalParams.buildSeaPositionalParams', () => {
@@ -55,3 +55,28 @@ describe('SeaPositionalParams.buildSeaPositionalParams', () => {
     ]);
   });
 });
+
+describe('SeaPositionalParams.buildSeaNamedParams', () => {
+  it('returns undefined for no named params', () => {
+    expect(buildSeaNamedParams(undefined)).to.equal(undefined);
+    expect(buildSeaNamedParams({})).to.equal(undefined);
+  });
+
+  it('emits {name, sqlType, value} triples, reusing the same type mapping', () => {
+    expect(
+      buildSeaNamedParams({
+        n: 42,
+        s: 'hello',
+        d: new DBSQLParameter({ type: DBSQLParameterType.DECIMAL, value: '99.99' }),
+      }),
+    ).to.deep.include.members([
+      { name: 'n', sqlType: 'INTEGER', value: '42' },
+      { name: 's', sqlType: 'STRING', value: 'hello' },
+      { name: 'd', sqlType: 'DECIMAL(4,2)', value: '99.99' },
+    ]);
+  });
+
+  it('maps a named NULL to a value-less VOID input (with the name)', () => {
+    expect(buildSeaNamedParams({ x: null })).to.deep.equal([{ name: 'x', sqlType: 'VOID' }]);
+  });
+});