feat(appkit): infer numeric SQL type for sql.number(), add typed variants (#323)

* feat(appkit): infer numeric SQL type for sql.number(), add typed variants

Currently sql.number() unconditionally produces __sql_type: "NUMERIC",
which Databricks SQL binds as DECIMAL(10,0). That breaks LIMIT and
OFFSET — Spark requires an integer-typed expression and rejects the
parameter with INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE — and silently
truncates non-integer JS numbers (sql.number(3.14) sent value="3.14"
into a DECIMAL(10,0) slot).

Two changes:

1. sql.number() now infers the wire type from the value:
   - integer JS number -> BIGINT
   - non-integer JS number -> DOUBLE
   - numeric string -> NUMERIC (preserves caller's precision intent;
     a string is an explicit choice to skip JS-number coercion)

   Picks the most-precise type the value can losslessly represent.
   Spark coerces numeric types implicitly so existing queries against
   BIGINT/DECIMAL/DOUBLE columns keep working, plus LIMIT now accepts
   sql.number(10) directly.

2. Typed variants for callers who need to override the inference:
   - sql.int(value)     -> INT
   - sql.bigint(value)  -> BIGINT (also accepts JS bigint for values
                          beyond Number.MAX_SAFE_INTEGER)
   - sql.float(value)   -> FLOAT
   - sql.double(value)  -> DOUBLE
   - sql.decimal(value) -> NUMERIC (decimal precision preserved)

   sql.int() and sql.bigint() reject non-integer inputs at the
   helper boundary so the failure surfaces early, before the wire.

SQLNumberMarker.__sql_type widens from "NUMERIC" to a union of the
numeric SQL types. Non-breaking for callers: any code that previously
held an SQLNumberMarker still type-checks (the union is wider in
return position). The two unit tests that pinned `type: "NUMERIC"`
for sql.number(integer) are updated to expect BIGINT.

Discovered while building a parameterized analytics query against
LIMIT — the bare `LIMIT :limit` case is the most visible failure but
the underlying issue affects any query where the column type matters.

Signed-off-by: James Broadhead <jamesbroadhead@gmail.com>

* docs: regenerate sql.* API reference for typed numeric variants

Co-authored-by: Isaac

* fix(shared): address review feedback on typed numeric SQL variants

P1 fixes
- Reject JS integers outside Number.MAX_SAFE_INTEGER in sql.number(),
  sql.int(), and sql.bigint(number). The marker would otherwise advertise
  BIGINT for a value already lost to JS-double precision.
- Widen sql.number("10") to BIGINT for integer-shaped strings so handler
  code that passes req.query strings works with LIMIT/OFFSET. Decimal-
  shaped strings still emit NUMERIC.
- Type-generator: extract INT/BIGINT/TINYINT/SMALLINT/FLOAT/DOUBLE/DECIMAL
  -- @param annotations, give them sensible defaults, and route each SQL
  type to its closest typed helper in sqlTypeToHelper.

P2 fixes
- Reject Infinity / -Infinity / NaN, hex / scientific-only / whitespace
  strings via a strict NUMERIC_LITERAL_RE.
- Emit BIGINT wire values via BigInt(value).toString() so 1e15 -> "1000000000000000"
  rather than exponent text.
- Bound-check sql.int (32-bit signed) and sql.bigint (64-bit signed)
  inputs; surface a descriptive error pointing to the wider helper.
- Narrow each typed helper's return type to the exact __sql_type literal.
- Add bound, boundary, error, and precision-loss tests for the typed
  helpers, plus an integration test for LIMIT :n OFFSET :m bindings.
- Add @returns and @example for every new helper; regenerate
  docs/docs/api/appkit/Variable.sql.md.
- Rename sql.decimal -> sql.numeric so name matches the wire literal
  (existing typed helpers all match name -> wire). Update analytics.md
  to mention the new helpers and refresh the LIMIT example.

Co-authored-by: Isaac
Signed-off-by: James Broadhead <jamesbroadhead@gmail.com>

* fix(shared): address ACE multi-model review findings

Two confirmed issues from a follow-up multi-model review of the
prior commit's typed numeric variants:

- sql.number(integer-shaped string) widened to BIGINT without
  bounds-checking. "9223372036854775808" overflowed the 64-bit
  wire type silently. Now runs the same BIGINT range check as
  sql.bigint() and throws with a hint to sql.numeric() for
  arbitrary-precision integers.

- The @param extraction regex matched TIMESTAMP_NTZ as TIMESTAMP,
  losing the NTZ specificity. Reordered the alternation so
  TIMESTAMP_NTZ wins, added a \b boundary, and gave it a default
  literal in defaultForType.

Plus drive-bys:
- Remove stale sql.interval() reference in SQLTypeMarker JSDoc.
- Pin behaviour with boundary tests at +/- 2^63 and a regression
  test that TIMESTAMP_NTZ is not partially matched.

Co-authored-by: Isaac
Signed-off-by: James Broadhead <jamesbroadhead@gmail.com>

* fix(shared): sql.number infers INT (not BIGINT) for LIMIT/OFFSET compatibility

Empirical testing against e2-dogfood.staging (from @calvarjorge) showed
that Spark's LIMIT/OFFSET operators require IntegerType specifically —
LongType/BIGINT is rejected with INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE:

  The offset expression must be integer type, but got "BIGINT".

So the original PR's "LIMIT now Just Works" claim was false: BIGINT
fails for the exact motivating case. Catalyst auto-widens INT to
BIGINT/DECIMAL/DOUBLE for wider columns, so defaulting to INT is
strictly better than defaulting to BIGINT.

Change sql.number inference:
- JS integer in [-2^31, 2^31 - 1] → INT (was BIGINT)
- JS integer outside INT but within MAX_SAFE_INTEGER → BIGINT
- integer-shaped string in INT range → INT (was BIGINT)
- integer-shaped string outside INT, within BIGINT → BIGINT
- everything else unchanged (DOUBLE for non-integer, NUMERIC for
  decimal strings, throw for out-of-BIGINT and non-numeric)

Update analytics.md to recommend `-- @param limit INT` and explain
the Spark IntegerType requirement. Update unit + integration tests
to pin INT bindings for in-range values, with explicit boundary
coverage at +/- 2^31. Regenerate the API reference page.

Co-authored-by: Isaac
Signed-off-by: James Broadhead <jamesbroadhead@gmail.com>

* docs(shared): document how to re-validate LIMIT/OFFSET mocked tests against prod

The LIMIT/OFFSET integration tests assert wire-type strings produced
by sql.number — they don't round-trip against a real warehouse. The
original PR claimed BIGINT worked for LIMIT and tests passed, but
production Spark rejected the binding.

Add a comment in the test block with a copy-pasteable
/api/2.0/sql/statements payload, the expected success and failure
states, and the exact error string. If Spark's LIMIT type contract
ever changes, this comment is the smoke test to catch it before the
mocked assertions silently drift away from production behaviour.

Verified empirically against two independent SQL Warehouses on
e2-dogfood.staging (including dd43ee29fedd958d, the warehouse the
original PR cited as evidence): INT succeeds with 2 rows, BIGINT
fails with [INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE] ... SQLSTATE: 42K0E.

Co-authored-by: Isaac
Signed-off-by: James Broadhead <jamesbroadhead@gmail.com>

---------

Signed-off-by: James Broadhead <jamesbroadhead@gmail.com>

Author: jamesbroadhead

apps/dev-playground/shared/appkit-types/analytics.d.ts

@@ -270,7 +270,7 @@ declare module "@databricks/appkit-ui/react" {
         parameters: {
           /** STRING - use sql.string() */
           stringParam: SQLStringMarker;
-          /** NUMERIC - use sql.number() */
+          /** NUMERIC - use sql.numeric() */
           numberParam: SQLNumberMarker;
           /** BOOLEAN - use sql.boolean() */
           booleanParam: SQLBooleanMarker;

docs/docs/api/appkit/Variable.sql.md

@@ -2,10 +2,25 @@
 
 ```ts
 const sql: {
+  bigint: SQLNumberMarker & {
+     __sql_type: "BIGINT";
+  };
   binary: SQLBinaryMarker;
   boolean: SQLBooleanMarker;
   date: SQLDateMarker;
+  double: SQLNumberMarker & {
+     __sql_type: "DOUBLE";
+  };
+  float: SQLNumberMarker & {
+     __sql_type: "FLOAT";
+  };
+  int: SQLNumberMarker & {
+     __sql_type: "INT";
+  };
   number: SQLNumberMarker;
+  numeric: SQLNumberMarker & {
+     __sql_type: "NUMERIC";
+  };
   string: SQLStringMarker;
   timestamp: SQLTimestampMarker;
 };
@@ -15,6 +30,43 @@ SQL helper namespace
 
 ## Type Declaration
 
+### bigint()
+
+```ts
+bigint(value: string | number | bigint): SQLNumberMarker & {
+  __sql_type: "BIGINT";
+};
+```
+
+Creates a `BIGINT` (64-bit signed integer) parameter. Accepts JS
+`bigint` so callers can round-trip values outside `Number.MAX_SAFE_INTEGER`
+without precision loss; for `number` inputs, requires
+`Number.isSafeInteger(value)`.
+
+Rejects values outside the signed 64-bit range `[-2^63, 2^63 - 1]`.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `string` \| `number` \| `bigint` | Integer number, bigint, or integer-shaped string |
+
+#### Returns
+
+`SQLNumberMarker` & \{
+  `__sql_type`: `"BIGINT"`;
+\}
+
+Marker pinned to `BIGINT`
+
+#### Example
+
+```typescript
+sql.bigint(42);                     // { __sql_type: "BIGINT", value: "42" }
+sql.bigint(9007199254740993n);      // { __sql_type: "BIGINT", value: "9007199254740993" }
+sql.bigint("9007199254740993");     // { __sql_type: "BIGINT", value: "9007199254740993" }
+```
+
 ### binary()
 
 ```ts
@@ -134,14 +186,133 @@ const params = { startDate: sql.date("2024-01-01") };
 params = { startDate: "2024-01-01" }
 ```
 
+### double()
+
+```ts
+double(value: string | number): SQLNumberMarker & {
+  __sql_type: "DOUBLE";
+};
+```
+
+Creates a `DOUBLE` (double-precision, 64-bit) parameter. Same precision
+as a JS `number`, so `sql.double(value)` is exact for any JS number.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `string` \| `number` | Number or numeric string |
+
+#### Returns
+
+`SQLNumberMarker` & \{
+  `__sql_type`: `"DOUBLE"`;
+\}
+
+Marker pinned to `DOUBLE`
+
+#### Example
+
+```typescript
+sql.double(3.14);   // { __sql_type: "DOUBLE", value: "3.14" }
+```
+
+### float()
+
+```ts
+float(value: string | number): SQLNumberMarker & {
+  __sql_type: "FLOAT";
+};
+```
+
+Creates a `FLOAT` (single-precision, 32-bit) parameter. Note that JS
+numbers are 64-bit doubles, so values may be rounded to fit FLOAT
+precision at bind time.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `string` \| `number` | Number or numeric string |
+
+#### Returns
+
+`SQLNumberMarker` & \{
+  `__sql_type`: `"FLOAT"`;
+\}
+
+Marker pinned to `FLOAT`
+
+#### Example
+
+```typescript
+sql.float(3.14);   // { __sql_type: "FLOAT", value: "3.14" }
+```
+
+### int()
+
+```ts
+int(value: string | number): SQLNumberMarker & {
+  __sql_type: "INT";
+};
+```
+
+Creates an `INT` (32-bit signed integer) parameter. Use when the column
+or context requires `INT` specifically (e.g. legacy schemas, or to make
+the wire type explicit).
+
+Rejects non-integers, values outside `Number.MAX_SAFE_INTEGER` (for
+number inputs), and values outside the signed 32-bit range
+`[-2^31, 2^31 - 1]`.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `string` \| `number` | Integer number or integer-shaped string |
+
+#### Returns
+
+`SQLNumberMarker` & \{
+  `__sql_type`: `"INT"`;
+\}
+
+Marker pinned to `INT`
+
+#### Example
+
+```typescript
+sql.int(42);     // { __sql_type: "INT", value: "42" }
+sql.int("42");   // { __sql_type: "INT", value: "42" }
+```
+
 ### number()
 
 ```ts
 number(value: string | number): SQLNumberMarker;
 ```
 
-Creates a NUMERIC type parameter
-Accepts numbers or numeric strings
+Creates a numeric type parameter. The wire SQL type is inferred from the
+value so the parameter binds correctly in any context, including `LIMIT`
+and `OFFSET`:
+
+- JS integer in `[-2^31, 2^31 - 1]` → `INT`
+- JS integer outside `INT` but within `Number.MAX_SAFE_INTEGER` → `BIGINT`
+- JS non-integer (`3.14`) → `DOUBLE`
+- integer-shaped string in `INT` range → `INT` (common HTTP-input case)
+- integer-shaped string outside `INT` but within `BIGINT` → `BIGINT`
+- decimal-shaped string (`"123.45"`) → `NUMERIC` (preserves precision)
+
+Why default to `INT`? Spark's `LIMIT` and `OFFSET` operators require
+`IntegerType` specifically — `BIGINT` (`LongType`) is rejected with
+`INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE`. Catalyst auto-widens `INT`
+to `BIGINT` / `DECIMAL` / `DOUBLE` for wider columns, so `INT` is a
+strictly better default than `BIGINT`.
+
+Throws on `NaN`, `Infinity`, JS integers outside `Number.MAX_SAFE_INTEGER`,
+integer-shaped strings outside the `BIGINT` range, or non-numeric strings.
+Reach for `sql.int()`, `sql.bigint()`, `sql.float()`, `sql.double()`, or
+`sql.numeric()` to override the inferred type.
 
 #### Parameters
 
@@ -153,18 +324,51 @@ Accepts numbers or numeric strings
 
 `SQLNumberMarker`
 
-Marker object for NUMERIC type parameter
+Marker for a numeric SQL parameter
 
-#### Examples
+#### Example
 
 ```typescript
-const params = { userId: sql.number(123) };
-params = { userId: "123" }
+sql.number(123);              // { __sql_type: "INT",    value: "123" }
+sql.number(3_000_000_000);    // { __sql_type: "BIGINT", value: "3000000000" }
+sql.number(0.5);              // { __sql_type: "DOUBLE", value: "0.5" }
+sql.number("10");             // { __sql_type: "INT",    value: "10" }
+sql.number("123.45");         // { __sql_type: "NUMERIC", value: "123.45" }
+```
+
+### numeric()
+
+```ts
+numeric(value: string | number): SQLNumberMarker & {
+  __sql_type: "NUMERIC";
+};
 ```
 
+Creates a `NUMERIC` (fixed-point DECIMAL) parameter. Use when you need
+exact decimal arithmetic (currency, percentages) — pass values as
+strings to avoid JS-number precision loss.
+
+Note: passing a JS `number` is accepted but lossy for many values
+(e.g. `0.1 + 0.2` → `"0.30000000000000004"`). Prefer strings.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `string` \| `number` | Number or numeric string (strings preferred for precision) |
+
+#### Returns
+
+`SQLNumberMarker` & \{
+  `__sql_type`: `"NUMERIC"`;
+\}
+
+Marker pinned to `NUMERIC`
+
+#### Example
+
 ```typescript
-const params = { userId: sql.number("123") };
-params = { userId: "123" }
+sql.numeric("12345.6789");   // { __sql_type: "NUMERIC", value: "12345.6789" }
 ```
 
 ### string()

docs/docs/plugins/analytics.md

@@ -43,14 +43,23 @@ Use `:paramName` placeholders and optionally annotate parameter types using SQL
 ```sql
 -- @param startDate DATE
 -- @param endDate DATE
--- @param limit NUMERIC
+-- @param limit INT
 SELECT ...
 WHERE usage_date BETWEEN :startDate AND :endDate
 LIMIT :limit
 ```
 
+`LIMIT` / `OFFSET` require Spark `IntegerType` specifically — `BIGINT`
+(`LongType`) is rejected with `INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE`.
+Annotate with `INT`, or use `sql.number()` (auto-infers `INT` for values in
+`[-2^31, 2^31-1]`, falling back to `BIGINT` for wider values) / `sql.int()`
+at the call site.
+
 **Supported `-- @param` types** (case-insensitive):
-- `STRING`, `NUMERIC`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `BINARY`
+- `STRING`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `BINARY`
+- `INT`, `BIGINT`, `TINYINT`, `SMALLINT` — bind via `sql.int()` / `sql.bigint()`
+- `FLOAT`, `DOUBLE` — bind via `sql.float()` / `sql.double()`
+- `NUMERIC`, `DECIMAL` — bind via `sql.numeric()` (pass strings for precision)
 
 ## Server-injected parameters