[SEA-NodeJS] SEA query parameters, metadata & getInfo

[msrathore-db]

What

Consolidates three SEA session-backend capabilities into one focused PR, each a thin adapter over the merged kernel (which does the heavy lifting):

1. Bound parameters

• Forwards ordinalParameters / namedParameters to the kernel's ExecuteOptions.positionalParams / namedParams.
• Reuses the existing DBSQLParameter.toSparkParameter codec (the same type-inference the Thrift path uses), then adapts the type name to the kernel codec: DECIMAL → DECIMAL(p,s), INTERVAL * → INTERVAL, missing value → VOID/NULL.
• Positional (?) and named (:name) parameters are mutually exclusive — rejected up-front.

2. Metadata

• getCatalogs / getSchemas / getTables / getColumns / getFunctions / getTableTypes / getTypeInfo / getPrimaryKeys / getCrossReference forward to the kernel Connection.list* / get* methods and wrap the returned Statement.
• The kernel owns SQL synthesis, column projection, and the client-side TABLE_TYPE filter — the driver only maps request fields to positional arguments. (The previously-proposed driver-side SeaTableTypeFilter is therefore not needed and was dropped.)

3. getInfo

• Synthesized client-side (the SEA REST protocol / kernel have no getInfo endpoint), mirroring the three TGetInfoType values the Databricks Thrift server answers (server name / DBMS name / DBMS version) and rejecting every other value — byte-identical to the Thrift path.

Notes

• SeaInputValidation is slimmed to the single bind-time gate the driver genuinely needs (assertBindableValue); parameter-marker counting is the kernel's job, so the JS SQL-walk was removed to avoid drift.
• SeaNativeLoader re-exports the kernel's ExecuteOptions / TypedValueInput / NamedTypedValueInput types rather than re-declaring them, so driver param shapes can't drift from the kernel contract.
• Regenerates the committed napi .d.ts snapshot against the merged kernel (matches how prior SEA PRs [SEA-NodeJS] (2/8) napi-rs binding consumer — TS loader + build script #380 / [SEA-NodeJS] (1/3) SEA connect + auth (PAT + OAuth M2M/U2M) #409 landed binding updates).

Testing

• Full unit suite green (1112 passing); lib/ lints clean.
• Validated against a live warehouse via the SEA path: positional + named params return bound values, mutual-exclusion is rejected, all 9 metadata calls return rows (incl. kernel-side tableTypes=[VIEW] filter), and getInfo(CLI_DBMS_NAME) returns Spark SQL.

This pull request and its description were written by Isaac.

[gopalldb]

🟠 P1 (Important — should fix)

1. Decimal (p,s) derived by digit-counting misrepresents values; >38-digit clamp is silent data loss — SeaPositionalParams.ts:115-121. Precision/scale are inferred by counting digit characters in the string,
   which doesn't equal true significant digits: "0.00001" → DECIMAL(6,5) (leading 0 counted), and critically a 40-digit value → DECIMAL(38,0) while the full 40-digit value is still sent (I confirmed this
   output). Clamping the type to 38 while sending an unrepresentable value is internally inconsistent — the kernel will reject or silently truncate/round. The test positionalParams.test.ts:1408 blesses the
   40-digit clamp as correct, which is the wrong contract. → error at bind time on >38-digit overflow (clear ParameterError) rather than clamp-and-send; compute precision excluding insignificant leading zeros;
   consider accepting explicit precision/scale when the caller passes DBSQLParameterType.DECIMAL.
2. assertBindableValue lets values through to stringification with format surprises — SeaInputValidation.ts:39-52. Validation gates shape only; a number like 1e21 stringifies to "1e+21", which combined with
   the digit-counting decimal logic mis-derives (p,s). This is shared toSparkParameter behavior (parity-neutral, not a SEA regression), but the decimal fix above should also reject non-[+-]?digits[.digits]?
   strings when the explicit type is DECIMAL. No test covers exponential/NaN/Infinity/bigint-edge stringification.

🟡 P2 (Minor)

• Empty/non-numeric DECIMAL values ("", "abc") → DECIMAL(1,0) + raw value; type string is safe but the kernel rejects with an opaque error. → optional numeric-regex validation at bind for a clearer message.
• getInfo hardcodes 3.1.1/Spark SQL (SeaServerInfo.ts:238-249) — can drift from the live server vs. Thrift; documented Thrift-parity rationale + comparator suite. Unsupported InfoType correctly throws.
  Acceptable.
• native/sea/index.js loader — the [SEA-NodeJS] (1/3) SEA connect + auth (PAT + OAuth M2M/U2M) #409 garbled-name P0 is NOT present here. I checked: this loader uses clean @databricks/sql-kernel- names (one correct triple per branch), not the cross-triple
  garble. The only delta vs. base is adding AsyncStatement/AsyncResultHandle exports (matches index.d.ts). (package.json/optionalDependencies coverage is out of scope here — verify separately, but not
  introduced/regressed.)

[msrathore-db]

@gopalldb thanks — the DECIMAL P1 was a real bug; fixed in the latest commit and validated live.

P1.1 — digit-counting precision + >38 clamp-and-send. Confirmed both: 0.00001 → DECIMAL(6,5) (leading 0 counted), and a 40-digit value → DECIMAL(38,0) while still sending the 40-digit value (internally inconsistent — kernel rejects/truncates). Fixed in decimalPrecisionScale:

• Precision is now significant integer digits (insignificant leading zeros stripped, matching Spark's decimal-literal rule) + fractional scale: 0.00001 → DECIMAL(5,5), 007.50 → DECIMAL(3,2), 0 → DECIMAL(1,0).
• A value needing precision > 38 throws ParameterError at bind time instead of clamp-and-send.
• The test that blessed the 40-digit clamp now asserts the reject contract.

P1.2 / P2 — format surprises (1e+21, abc, ``) mis-derive (p,s). Fixed: when the explicit type is DECIMAL, the value must match `[+-]?digits[.digits]` — exponential / non-numeric / empty values now throw a clear `ParameterError` rather than emitting a bogus type the kernel rejects opaquely. (As you noted, the underlying `toSparkParameter` stringification is shared/parity-neutral, so I gated this at the DECIMAL-derivation step rather than changing shared behavior.)

Validated live: 0.00001 binds as DECIMAL(5,5) and round-trips; a 40-digit value is rejected client-side with ParameterError (no server round-trip). Unit tests cover leading-zero handling, >38 overflow, and non-numeric/exponential rejection.

P2 — getInfo 3.1.1/Spark SQL hardcode: acknowledged acceptable; I separately re-verified these against the live server (server returns the same three values, errors on every other InfoType). loader names: agreed — clean @databricks/sql-kernel-<triple> names, only the AsyncStatement/AsyncResultHandle exports added (matches index.d.ts); optionalDependencies coverage is tracked separately (#414 / the unpublished-packages note in native/sea/README.md).

This reply was written by Isaac.