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>

Author: jamesbroadhead

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

@@ -105,7 +105,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,15 +2,25 @@
 
 ```ts
 const sql: {
-  bigint: SQLNumberMarker;
+  bigint: SQLNumberMarker & {
+     __sql_type: "BIGINT";
+  };
   binary: SQLBinaryMarker;
   boolean: SQLBooleanMarker;
   date: SQLDateMarker;
-  decimal: SQLNumberMarker;
-  double: SQLNumberMarker;
-  float: SQLNumberMarker;
-  int: SQLNumberMarker;
+  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;
 };
@@ -23,12 +33,17 @@ SQL helper namespace
 ### bigint()
 
 ```ts
-bigint(value: string | number | bigint): SQLNumberMarker;
+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.
+without precision loss; for `number` inputs, requires
+`Number.isSafeInteger(value)`.
+
+Rejects values outside the signed 64-bit range `[-2^63, 2^63 - 1]`.
 
 #### Parameters
 
@@ -38,7 +53,19 @@ without precision loss.
 
 #### Returns
 
-`SQLNumberMarker`
+`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()
 
@@ -159,52 +186,48 @@ const params = { startDate: sql.date("2024-01-01") };
 params = { startDate: "2024-01-01" }
 ```
 
-### decimal()
+### double()
 
 ```ts
-decimal(value: string | number): SQLNumberMarker;
+double(value: string | number): SQLNumberMarker & {
+  __sql_type: "DOUBLE";
+};
 ```
 
-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.
+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 (strings preferred for precision) |
+| `value` | `string` \| `number` | Number or numeric string |
 
 #### Returns
 
-`SQLNumberMarker`
-
-### double()
-
-```ts
-double(value: string | number): SQLNumberMarker;
-```
-
-Creates a `DOUBLE` (double-precision) parameter. Same precision as a JS
-`number`, so `sql.double(value)` is exact for any JS number.
-
-#### Parameters
+`SQLNumberMarker` & \{
+  `__sql_type`: `"DOUBLE"`;
+\}
 
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `value` | `string` \| `number` | Number or numeric string |
+Marker pinned to `DOUBLE`
 
-#### Returns
+#### Example
 
-`SQLNumberMarker`
+```typescript
+sql.double(3.14);   // { __sql_type: "DOUBLE", value: "3.14" }
+```
 
 ### float()
 
 ```ts
-float(value: string | number): SQLNumberMarker;
+float(value: string | number): SQLNumberMarker & {
+  __sql_type: "FLOAT";
+};
 ```
 
-Creates a `FLOAT` (single-precision) parameter.
+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
 
@@ -214,18 +237,34 @@ Creates a `FLOAT` (single-precision) parameter.
 
 #### Returns
 
-`SQLNumberMarker`
+`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;
+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 |
@@ -234,7 +273,18 @@ the wire type explicit).
 
 #### Returns
 
-`SQLNumberMarker`
+`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()
 
@@ -248,10 +298,14 @@ and `OFFSET` (which require integer types):
 
 - JS integer (`10`) → `BIGINT`
 - JS non-integer (`3.14`) → `DOUBLE`
-- numeric string (`"123.45"`) → `NUMERIC` (preserves caller's precision intent)
+- integer-shaped string (`"10"`) → `BIGINT` (common HTTP-input case;
+  works with `LIMIT :n` / `OFFSET :m`)
+- decimal-shaped string (`"123.45"`) → `NUMERIC` (preserves precision)
 
-Reach for `sql.int()`, `sql.bigint()`, `sql.float()`, `sql.double()`, or
-`sql.decimal()` if you need to override the inferred type.
+Throws on `NaN`, `Infinity`, JS integers outside `Number.MAX_SAFE_INTEGER`,
+or non-numeric strings. Reach for `sql.int()`, `sql.bigint()`,
+`sql.float()`, `sql.double()`, or `sql.numeric()` if you need to override
+the inferred type.
 
 #### Parameters
 
@@ -268,9 +322,45 @@ Marker for a numeric SQL parameter
 #### Example
 
 ```typescript
-const params = { userId: sql.number(123) };       // BIGINT, value "123"
-const params = { ratio: sql.number(0.5) };        // DOUBLE, value "0.5"
-const params = { amount: sql.number("123.45") };  // NUMERIC, value "123.45"
+sql.number(123);        // { __sql_type: "BIGINT", value: "123" }
+sql.number(0.5);        // { __sql_type: "DOUBLE", value: "0.5" }
+sql.number("10");       // { __sql_type: "BIGINT", 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
+sql.numeric("12345.6789");   // { __sql_type: "NUMERIC", value: "12345.6789" }
 ```
 
 ### string()

docs/docs/plugins/analytics.md

@@ -43,14 +43,21 @@ Use `:paramName` placeholders and optionally annotate parameter types using SQL
 ```sql
 -- @param startDate DATE
 -- @param endDate DATE
--- @param limit NUMERIC
+-- @param limit BIGINT
 SELECT ...
 WHERE usage_date BETWEEN :startDate AND :endDate
 LIMIT :limit
 ```
 
+`LIMIT` / `OFFSET` require an integer-typed binding (`INT` or `BIGINT`).
+Annotate accordingly, or use `sql.number()` (auto-infers `BIGINT` for integer
+inputs) / `sql.bigint()` / `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
 

packages/appkit/src/plugins/analytics/tests/query.test.ts

@@ -171,13 +171,59 @@ describe("QueryProcessor", () => {
 
       const result = await processor.processQueryParams(query, parameters);
 
+      // Integer-shaped strings infer BIGINT (matches LIMIT/OFFSET pattern)
       expect(result.workspaceId).toEqual({
-        __sql_type: "NUMERIC",
+        __sql_type: "BIGINT",
         value: "9876543210",
       });
     });
   });
 
+  describe("LIMIT / OFFSET bindings (regression for #323)", () => {
+    test("sql.number(integer) binds as BIGINT for LIMIT/OFFSET", () => {
+      const query = "SELECT * FROM events LIMIT :n OFFSET :m";
+      const parameters = {
+        n: sql.number(10),
+        m: sql.number(20),
+      };
+
+      const result = processor.convertToSQLParameters(query, parameters);
+
+      expect(result.parameters).toEqual([
+        { name: "n", value: "10", type: "BIGINT" },
+        { name: "m", value: "20", type: "BIGINT" },
+      ]);
+    });
+
+    test("sql.number(integer-shaped string) binds as BIGINT for LIMIT/OFFSET", () => {
+      // Express/URLSearchParams return strings — this is the common
+      // handler pattern: sql.number(req.query.n).
+      const query = "SELECT * FROM events LIMIT :n OFFSET :m";
+      const parameters = {
+        n: sql.number("10"),
+        m: sql.number("20"),
+      };
+
+      const result = processor.convertToSQLParameters(query, parameters);
+
+      expect(result.parameters).toEqual([
+        { name: "n", value: "10", type: "BIGINT" },
+        { name: "m", value: "20", type: "BIGINT" },
+      ]);
+    });
+
+    test("sql.bigint(string) binds as BIGINT for LIMIT/OFFSET", () => {
+      const query = "SELECT * FROM events LIMIT :n";
+      const parameters = { n: sql.bigint("10") };
+
+      const result = processor.convertToSQLParameters(query, parameters);
+
+      expect(result.parameters).toEqual([
+        { name: "n", value: "10", type: "BIGINT" },
+      ]);
+    });
+  });
+
   describe("_createParameter - Type Handling", () => {
     test("should handle date parameters with sql.date()", () => {
       const query = "SELECT * FROM events WHERE event_date = :startDate";

packages/appkit/src/type-generator/query-registry.ts

@@ -194,7 +194,7 @@ function generateUnknownResultQuery(sql: string, queryName: string): string {
 export function extractParameterTypes(sql: string): Record<string, string> {
   const paramTypes: Record<string, string> = {};
   const regex =
-    /--\s*@param\s+(\w+)\s+(STRING|NUMERIC|BOOLEAN|DATE|TIMESTAMP|BINARY)/gi;
+    /--\s*@param\s+(\w+)\s+(STRING|NUMERIC|DECIMAL|BIGINT|TINYINT|SMALLINT|INT|FLOAT|DOUBLE|BOOLEAN|DATE|TIMESTAMP|BINARY)/gi;
   const matches = sql.matchAll(regex);
   for (const match of matches) {
     const [, paramName, paramType] = match;
@@ -207,7 +207,15 @@ export function extractParameterTypes(sql: string): Record<string, string> {
 export function defaultForType(sqlType: string | undefined): string {
   switch (sqlType?.toUpperCase()) {
     case "NUMERIC":
+    case "DECIMAL":
+    case "BIGINT":
+    case "TINYINT":
+    case "SMALLINT":
+    case "INT":
       return "0";
+    case "FLOAT":
+    case "DOUBLE":
+      return "0.0";
     case "STRING":
       return "''";
     case "BOOLEAN":