feat: add parameterized query output support

[h22rana]

Summary

• Add a fully isolated, non-breaking parameterized query pipeline that returns SQL with bind placeholders (@p1, $1) plus a separate parameter list, instead of inlined literals
• Dialect-aware placeholder styles: named (@p1) for BigQuery/Spanner/ClickHouse, positional ($1) for PostgreSQL/DuckDB
• Schema coercion applied before parameter binding (e.g., string "50000" -> int64(50000) for integer fields)
• New E350 ErrUnreferencedPlaceholder error code catches custom operators that drop arguments
• Full API symmetry: 6 Transpiler methods + 6 package-level convenience functions mirroring existing inline API
• REPL: :params toggle command switches between inline and parameterized output
• WASM: transpileParameterized, transpileConditionParameterized, quickTranspileParameterized JS functions + playground UI checkbox
• Large integer precision: JSON decoding uses json.Decoder.UseNumber() to preserve exact integer values. Unquoted integers like 9223372036854775808 now produce exact SQL instead of lossy float64 representations.

What gets parameterized

Value	Parameterized?	Reason
Strings, numbers	Yes	User-supplied data
NULL, TRUE, FALSE	No	Structural SQL tokens
Column names (var)	No	Identifiers, not data

Example

sql, params, _ := jsonlogic2sql.TranspileParameterized(
    jsonlogic2sql.DialectBigQuery,
    `{"and": [{"==": [{"var": "status"}, "active"]}, {">": [{"var": "amount"}, 1000]}]}`,
)
// sql    = "WHERE (status = @p1 AND amount > @p2)"
// params = [{Name: "p1", Value: "active"}, {Name: "p2", Value: 1000}]

REPL

[BigQuery] jsonlogic> :params
Parameterized mode: ON (output uses bind placeholders)

[BigQuery] jsonlogic> {"==": [{"var": "status"}, "active"]}
SQL:    WHERE status = @p1
Params: [{p1: "active"}]

Architecture

All existing functions remain untouched. New parallel *Param methods are created throughout the stack:

• internal/params/ — ParamCollector, PlaceholderStyle, ValidatePlaceholderRefs, FindQuotedPlaceholderRef, ValueForPlaceholder
• internal/operators/*.go — ToSQLParam() / valueToSQLParam() for all operator types
• internal/parser/parser.go — ParseParameterized pipeline with ParamExpressionParser callback + quoted-placeholder guard for custom operators
• parameterized.go — public QueryParam type and all 12 public functions
• internal/errors/errors.go — E350 ErrUnreferencedPlaceholder
• cmd/repl/main.go — :params toggle, printParams helper, parameterized-aware custom operators
• demo/wasm/main.go — 3 new JS bridge functions
• demo/wasm/index.html — Parameterized checkbox with bind params display

Post-review fixes

The following issues were identified during code review and fixed in follow-up commits:

Large integer precision (json.Decoder.UseNumber)

• Root cause: json.Unmarshal coerces all JSON numbers to float64, losing precision for integers exceeding 2^53. For example, 9223372036854775808 and 9223372036854775809 produced identical SQL.
• Fix: Switched to json.Decoder.UseNumber() which preserves numbers as json.Number (string-backed). Added json.Number handling to all operator paths (isPrimitive, isNumber, valueToSQL, valueToSQLParam, getNumber, coerceValueForComparison, handleIn/handleInParam, primitiveToSQLParam).
• Parameterized behavior: JS-safe integers (within ±2^53−1) bind as float64 for backward compatibility; overflow integers bind as string.

Out-of-range float preservation

• Root cause: jsonNumberParamValue errored on float64 overflow (e.g., 1e309) and silently bound underflow values (e.g., 1e-400) as 0, while inline transpilation preserved these literals verbatim.
• Fix: Changed jsonNumberParamValue to fall back to the original numeric string when ParseFloat produces infinity or underflow-to-zero. Added the same underflow guard to parser.primitiveToSQLParam (separate conversion path used by custom operators). Both paths now match inline behavior.

Quoted-placeholder guard for custom operators

• Root cause: Custom operators in parameterized mode receive placeholders (e.g., @p1) as plain string arguments. A naive operator could wrap them in SQL string literals (e.g., '@p1'), which passes validation but silently breaks bind semantics at runtime.
• Fix: Added FindQuotedPlaceholderRef in internal/params/ that scans SQL string literals for placeholder tokens with proper boundary checking (avoids false positives like 'name@p1.example'). The parser now runs this guard after custom operator SQL generation in parameterized mode, failing with E102 ErrCustomOperatorFailed if a placeholder is found inside quotes. Valid expressions like CONCAT(@p1, '%') continue to work.

Parameterized in operator

• String containment with custom-op SQL literals: ProcessedValue{IsSQL:true} from custom operators (e.g., 'foo') was misrouted to array membership (IN UNNEST) instead of string containment (STRPOS). Fixed by mirroring the non-param quoting heuristic.
• String containment with custom-op placeholders: Custom operators returning bare placeholders (e.g., @p1) lost type information. Added ParamCollector.ValueForPlaceholder() to look up the Go type of the stored parameter and route string values to containment.
• Dialect-aware strposFunc routing: Both handleIn and handleInParam now use dialect-aware strposFunc for literal string/number containment (e.g., STRPOS on BigQuery, POSITION(x IN y) on PostgreSQL).
• Schema coercion: handleInParam now defers placeholder generation until after schema-based coercion is applied.

REPL custom LIKE operators

• Placeholder embedding: Custom LIKE operators (startsWith, endsWith, contains and negations) were embedding placeholders inside SQL string literals ('@p1%'). Refactored with buildLikeSQL helper to use CONCAT(@p1, '%').
• Wildcard escaping: Parameterized LIKE patterns now escape %, _, \ at runtime via SQL REPLACE functions.
• CAST for numeric patterns: Numeric bind values are cast to string (CAST(@p1 AS STRING) / CAST($1 AS TEXT)) before REPLACE to prevent type errors.
• Reversed contains args: Added isBoundValue() helper for robust column-vs-pattern detection in parameterized mode.
• Array-pattern contains: Single-element array patterns (["x"]) in parameterized mode are now formatted as strings in primitiveToSQLParam so custom operators can detect and unwrap them consistently.

BigQuery regexpContains

• Raw string prefix: BigQuery's r'...' prefix is only valid for inline SQL literals. In parameterized mode, the pattern is now emitted without the r prefix to avoid invalid SQL and E350 errors.

Security

• WASM XSS prevention: Replaced innerHTML with textContent + DOM element creation for rendering SQL output in the WASM playground.
• json.Number SQL injection via map/interface APIs: TranspileFromMap/TranspileFromInterface accepted crafted json.Number values (e.g., json.Number("1 OR 1=1")) and inlined them verbatim, enabling SQL injection. Defense-in-depth at two layers: (1) validJSONNumberLiteral regex in data.valueToSQL, numeric.valueToSQL, and their parameterized counterparts rejects invalid literals at the operator level; (2) the validator's isNumber() now validates json.Number against the JSON number grammar, catching invalid values at the earliest point before any operator (built-in or custom) sees them. The Transpile(string) path was not affected since json.Decoder only produces valid numeric tokens.

Typed-nil schema fix

• SetSchema(nil) and NewTranspilerWithConfig with a nil *Schema pointer now correctly return a true nil interface, ensuring no-schema identifier validation (regex whitelist) is not bypassed.

Code quality and optimizations

• JSON decoding allocation: Switched bytes.NewBufferString to strings.NewReader in decodeJSONLogic to avoid unnecessary byte slice copy.
• In-place array mutation: handleIn and handleInParam now copy arrays before schema coercion to prevent mutating caller-provided slices.
• Placeholder validation perf: Replaced per-parameter regexp.Compile in ValidatePlaceholderRefs with boundary-aware strings.Index scanning.
• WASM error handling: All json.Marshal calls in demo/wasm/main.go now handle errors instead of swallowing them.

Documentation

• Updated QueryParam.Value type documentation to cover unquoted large JSON integers, quoted string inputs, and out-of-range floats, with UseNumber explanation.
• Clarified parameterized LIKE placeholder patterns (valid vs invalid forms).
• Documented quoted-placeholder rejection rule for custom operators.

Test plan

• All existing tests pass (no regressions)
• Unit tests for internal/params package (collector, styles, validator, ValueForPlaceholder, FindQuotedPlaceholderRef)
• Unit tests for all operator ToSQLParam methods (data, comparison, numeric, logical, string, array)
• Parser ParseParameterized tests across BigQuery and PostgreSQL dialects
• Integration tests in parameterized_test.go covering all operators, all 5 dialects, schema coercion, custom operators, nested expressions
• Large integer precision tests: distinct values produce distinct SQL and exact parameterized strings
• Out-of-range float tests: 1e309 overflow and 1e-400 underflow preserve original string in both operator and custom operator paths
• Quoted-placeholder guard: rejection of '@p1' patterns and acceptance of CONCAT(@p1, '%') expressions
• json.Number injection rejection: TranspileFromMap/TranspileFromInterface reject crafted non-numeric json.Number values in both built-in and custom operator paths
• Error parity tests ensuring identical error codes between inline and parameterized pipelines
• E350 detection test for custom operators that drop arguments
• REPL tests: printParams formatting, params mode toggle, parameterized transpile, custom LIKE operators, reversed args, regexpContains BigQuery, array-pattern contains
• Typed-nil schema tests (NewTranspilerWithConfig nil pointer, SetSchema(nil) restore)
• Dialect compliance test for in string containment and numeric boundaries across all 5 dialects
• make lint — 0 issues
• make test — all 8 packages pass
• make bench — benchmarks pass
• make build / make build/wasm — successful