import { SQLBinaryMarker, SQLBooleanMarker, SQLDateMarker, SQLNumberMarker, SQLStringMarker, SQLTimestampMarker, SQLTypeMarker } from "./types.js";

//#region ../shared/src/sql/helpers.d.ts
/**
 * SQL helper namespace
 */
declare const sql: {
  /**
   * Creates a DATE type parameter
   * Accepts Date objects or ISO date strings (YYYY-MM-DD format)
   * @param value - Date object or ISO date string
   * @returns Marker object for DATE type parameter
   * @example
   * ```typescript
   * const params = { startDate: sql.date(new Date("2024-01-01")) };
   * params = { startDate: "2024-01-01" }
   * ```
   * @example
   * ```typescript
   * const params = { startDate: sql.date("2024-01-01") };
   * params = { startDate: "2024-01-01" }
   * ```
   */
  date(value: Date | string): SQLDateMarker;
  /**
   * Creates a TIMESTAMP type parameter
   * Accepts Date objects, ISO timestamp strings, or Unix timestamp numbers
   * @param value - Date object, ISO timestamp string, or Unix timestamp number
   * @returns Marker object for TIMESTAMP type parameter
   * @example
   * ```typescript
   * const params = { createdTime: sql.timestamp(new Date("2024-01-01T12:00:00Z")) };
   * params = { createdTime: "2024-01-01T12:00:00Z" }
   * ```
   * @example
   * ```typescript
   * const params = { createdTime: sql.timestamp("2024-01-01T12:00:00Z") };
   * params = { createdTime: "2024-01-01T12:00:00Z" }
   * ```
   * @example
   * ```typescript
   * const params = { createdTime: sql.timestamp(1704110400000) };
   * params = { createdTime: "2024-01-01T12:00:00Z" }
   * ```
   */
  timestamp(value: Date | string | number): SQLTimestampMarker;
  /**
   * 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.
   *
   * @param value - Number or numeric string
   * @returns Marker for a numeric SQL parameter
   * @example
   * ```typescript
   * 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" }
   * ```
   */
  number(value: number | string): SQLNumberMarker;
  /**
   * 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]`.
   *
   * @param value - Integer number or integer-shaped string
   * @returns Marker pinned to `INT`
   * @example
   * ```typescript
   * sql.int(42);     // { __sql_type: "INT", value: "42" }
   * sql.int("42");   // { __sql_type: "INT", value: "42" }
   * ```
   */
  int(value: number | string): SQLNumberMarker & {
    __sql_type: "INT";
  };
  /**
   * 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]`.
   *
   * @param value - Integer number, bigint, or integer-shaped string
   * @returns 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" }
   * ```
   */
  bigint(value: number | bigint | string): SQLNumberMarker & {
    __sql_type: "BIGINT";
  };
  /**
   * 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.
   *
   * @param value - Number or numeric string
   * @returns Marker pinned to `FLOAT`
   * @example
   * ```typescript
   * sql.float(3.14);   // { __sql_type: "FLOAT", value: "3.14" }
   * ```
   */
  float(value: number | string): SQLNumberMarker & {
    __sql_type: "FLOAT";
  };
  /**
   * Creates a `DOUBLE` (double-precision, 64-bit) parameter. Same precision
   * as a JS `number`, so `sql.double(value)` is exact for any JS number.
   *
   * @param value - Number or numeric string
   * @returns Marker pinned to `DOUBLE`
   * @example
   * ```typescript
   * sql.double(3.14);   // { __sql_type: "DOUBLE", value: "3.14" }
   * ```
   */
  double(value: number | string): 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.
   *
   * Note: passing a JS `number` is accepted but lossy for many values
   * (e.g. `0.1 + 0.2` → `"0.30000000000000004"`). Prefer strings.
   *
   * @param value - Number or numeric string (strings preferred for precision)
   * @returns Marker pinned to `NUMERIC`
   * @example
   * ```typescript
   * sql.numeric("12345.6789");   // { __sql_type: "NUMERIC", value: "12345.6789" }
   * ```
   */
  numeric(value: number | string): SQLNumberMarker & {
    __sql_type: "NUMERIC";
  };
  /**
   * Creates a STRING type parameter
   * Accepts strings, numbers, or booleans
   * @param value - String, number, or boolean
   * @returns Marker object for STRING type parameter
   * @example
   * ```typescript
   * const params = { name: sql.string("John") };
   * params = { name: "John" }
   * ```
   * @example
   * ```typescript
   * const params = { name: sql.string(123) };
   * params = { name: "123" }
   * ```
   * @example
   * ```typescript
   * const params = { name: sql.string(true) };
   * params = { name: "true" }
   * ```
   */
  string(value: string | number | boolean): SQLStringMarker;
  /**
   * Create a BOOLEAN type parameter
   * Accepts booleans, strings, or numbers
   * @param value - Boolean, string, or number
   * @returns Marker object for BOOLEAN type parameter
   * @example
   * ```typescript
   * const params = { isActive: sql.boolean(true) };
   * params = { isActive: "true" }
   * ```
   * @example
   * ```typescript
   * const params = { isActive: sql.boolean("true") };
   * params = { isActive: "true" }
   * ```
   * @example
   * ```typescript
   * const params = { isActive: sql.boolean(1) };
   * params = { isActive: "true" }
   * ```
   * @example
   * ```typescript
   * const params = { isActive: sql.boolean("false") };
   * params = { isActive: "false" }
   * ```
   * @example
   * ```typescript
   * const params = { isActive: sql.boolean(0) };
   * params = { isActive: "false" }
   * ```
   * @returns
   */
  boolean(value: boolean | string | number): SQLBooleanMarker;
  /**
   * Creates a BINARY parameter as hex-encoded STRING
   * Accepts Uint8Array, ArrayBuffer, or hex string
   * Note: Databricks SQL Warehouse doesn't support BINARY as parameter type,
   * so this helper returns a STRING with hex encoding. Use UNHEX(:param) in your SQL.
   * @param value - Uint8Array, ArrayBuffer, or hex string
   * @returns Marker object with STRING type and hex-encoded value
   * @example
   * ```typescript
   * // From Uint8Array:
   * const params = { data: sql.binary(new Uint8Array([0x53, 0x70, 0x61, 0x72, 0x6b])) };
   * // Returns: { __sql_type: "STRING", value: "537061726B" }
   * // SQL: SELECT UNHEX(:data) as binary_value
   * ```
   * @example
   * ```typescript
   * // From hex string:
   * const params = { data: sql.binary("537061726B") };
   * // Returns: { __sql_type: "STRING", value: "537061726B" }
   * ```
   */
  binary(value: Uint8Array | ArrayBuffer | string): SQLBinaryMarker;
};
/**
 * Type guard to check if a value is a SQL type marker
 * @param value - Value to check
 * @returns True if the value is a SQL type marker, false otherwise
 * @example
 * ```typescript
 * const value = {
 *   __sql_type: "DATE",
 *   value: "2024-01-01",
 * };
 * const isSQLTypeMarker = isSQLTypeMarker(value);
 * console.log(isSQLTypeMarker); // true
 * ```
 */
declare function isSQLTypeMarker(value: any): value is SQLTypeMarker;
//#endregion
export { isSQLTypeMarker, sql };
//# sourceMappingURL=helpers.d.ts.map