toParamValue function

ParamValue toParamValue(Object? value)

Converts a single object to a ParamValue instance.

Supported implicit input types:

• null → ParamValueNull
• ParamValue → returned as-is
• int → ParamValueInt32 or ParamValueInt64 (based on range)
• String → ParamValueString
• List<int> or Uint8List → ParamValueBinary
• bool → ParamValueInt32(1|0) (canonical mapping)
• double → ParamValueDecimal(value.toStringAsFixed(6)) (canonical mapping; NaN/Infinity rejected)
• DateTime → ParamValueString(value.toUtc().toIso8601String()) (canonical mapping; year must be in [1, 9999])

Throws ArgumentError for unsupported types with actionable message.

Example:

final pv = toParamValue(42); // ParamValueInt32(42)
final pvNull = toParamValue(null); // ParamValueNull
final pvBool = toParamValue(true); // ParamValueInt32(1)

Implementation

ParamValue toParamValue(Object? value) {
  if (value == null) return const ParamValueNull();
  if (value is ParamValue) return value;
  if (value is SqlTypedValue) return _toTypedParamValue(value);

  // Fast path for int - most common case
  if (value is int) {
    if (value >= -0x80000000 && value <= 0x7FFFFFFF) {
      return ParamValueInt32(value);
    }
    return ParamValueInt64(value);
  }

  // String - common case
  if (value is String) return ParamValueString(value);

  // Binary data
  if (value is List<int>) return ParamValueBinary(value);

  // Canonical mappings - explicit conversions with clear semantics
  if (value is bool) {
    return ParamValueInt32(value ? 1 : 0);
  }
  if (value is double) {
    if (value.isNaN) {
      throw ArgumentError(
        'Double value is NaN. Cannot convert to decimal. '
        'Use explicit ParamValue with desired representation.',
      );
    }
    if (value.isInfinite) {
      final label = value.isNegative ? '-Infinity' : 'Infinity';
      throw ArgumentError(
        'Double value is $label. Cannot convert to decimal. '
        'Use explicit ParamValue with desired representation.',
      );
    }
    return ParamValueDecimal(value.toStringAsFixed(_defaultDecimalScale));
  }
  if (value is DateTime) {
    return ParamValueString(_toValidatedUtcIso8601(value));
  }

  // Unsupported type - explicit error instead of silent toString() fallback
  throw ArgumentError(_unsupportedParameterTypeMessage(value));
}