dbkit-core 0.3.0

use bitflags::bitflags;

use crate::compile::CompiledSql;
use crate::expr::{AggregateExpr, Expr, ExprNode, ExprOperand, IntoExpr, NumericExprType, TrimDirection, Value, VectorBinaryOp};
use crate::query::Select;
use crate::PgVector;

pub trait StringUnaryExpr {
    type Output;
}

impl StringUnaryExpr for String {
    type Output = String;
}

impl StringUnaryExpr for Option<String> {
    type Output = Option<String>;
}

pub trait StringLengthExpr {
    type Output;
}

impl StringLengthExpr for String {
    type Output = i32;
}

impl StringLengthExpr for Option<String> {
    type Output = Option<i32>;
}

pub trait StringSplitExpr {
    type Output;
}

impl StringSplitExpr for String {
    type Output = Vec<String>;
}

impl StringSplitExpr for Option<String> {
    type Output = Option<Vec<String>>;
}

pub trait StringBinaryExpr<Rhs, Result> {
    type Output;
}

impl<Result> StringBinaryExpr<String, Result> for String {
    type Output = Result;
}

impl<Result> StringBinaryExpr<Option<String>, Result> for String {
    type Output = Option<Result>;
}

impl<Result> StringBinaryExpr<String, Result> for Option<String> {
    type Output = Option<Result>;
}

impl<Result> StringBinaryExpr<Option<String>, Result> for Option<String> {
    type Output = Option<Result>;
}

#[doc(hidden)]
pub struct ConcatExpr {
    node: ExprNode,
}

pub trait IntoConcatExpr {
    fn into_concat_expr(self) -> ConcatExpr;
}

impl<T> IntoConcatExpr for T
where
    T: ExprOperand,
    T::Value: StringUnaryExpr,
{
    fn into_concat_expr(self) -> ConcatExpr {
        ConcatExpr {
            node: self.into_operand_expr().node,
        }
    }
}

impl IntoConcatExpr for ConcatExpr {
    fn into_concat_expr(self) -> ConcatExpr {
        self
    }
}

bitflags! {
    /// Composable options for [`regex_replace`]; use [`empty`](Self::empty) for default behavior.
    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
    pub struct RegexReplaceFlags: u8 {
        /// Uses case-insensitive matching. Maps to PostgreSQL's `i` flag.
        const CASE_INSENSITIVE = 1 << 0;
        /// Replaces every match instead of only the first. Maps to PostgreSQL's `g` flag.
        const GLOBAL = 1 << 1;
    }

    /// Composable options for [`regex_split`]; use [`empty`](Self::empty) for default behavior.
    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
    pub struct RegexSplitFlags: u8 {
        /// Uses case-insensitive matching. Maps to PostgreSQL's `i` flag.
        const CASE_INSENSITIVE = 1 << 0;
    }
}

/// A PostgreSQL Unicode normalization form for [`normalize`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NormalizationForm {
    /// PostgreSQL `NFC` normalization.
    Nfc,
    /// PostgreSQL `NFD` normalization.
    Nfd,
    /// PostgreSQL `NFKC` normalization.
    Nfkc,
    /// PostgreSQL `NFKD` normalization.
    Nfkd,
}

/// Output type for boolean string functions.
pub trait StringBoolExpr {
    /// Result type preserving input nullability.
    type Output;
}

impl StringBoolExpr for String {
    type Output = bool;
}

impl StringBoolExpr for Option<String> {
    type Output = Option<bool>;
}

/// Output type for integer-to-character functions.
pub trait CodepointExpr {
    /// Result type preserving input nullability.
    type Output;
}

impl CodepointExpr for i32 {
    type Output = String;
}

impl CodepointExpr for Option<i32> {
    type Output = Option<String>;
}

impl RegexReplaceFlags {
    fn as_postgres_str(self) -> &'static str {
        match (self.contains(Self::GLOBAL), self.contains(Self::CASE_INSENSITIVE)) {
            (false, false) => "",
            (false, true) => "i",
            (true, false) => "g",
            (true, true) => "gi",
        }
    }
}

impl RegexSplitFlags {
    fn as_postgres_str(self) -> &'static str {
        if self.contains(Self::CASE_INSENSITIVE) {
            "i"
        } else {
            ""
        }
    }
}

fn unary_string_fn<T>(name: &'static str, arg: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    let expr = arg.into_expr();
    Expr::new(ExprNode::Func {
        name,
        args: vec![expr.node],
    })
}

fn string_length_fn<T>(name: &'static str, arg: impl IntoExpr<T>) -> Expr<<T as StringLengthExpr>::Output>
where
    T: StringLengthExpr,
{
    let expr = arg.into_expr();
    Expr::new(ExprNode::Func {
        name,
        args: vec![expr.node],
    })
}

fn string_fn<T>(name: &'static str, arg: impl IntoExpr<T>, extra_args: Vec<ExprNode>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    let mut args = vec![arg.into_expr().node];
    args.extend(extra_args);
    Expr::new(ExprNode::Func { name, args })
}

fn binary_string_fn<L, R, O>(name: &'static str, left: impl IntoExpr<L>, right: impl IntoExpr<R>) -> Expr<O> {
    let left = left.into_expr();
    let right = right.into_expr();
    Expr::new(ExprNode::Func {
        name,
        args: vec![left.node, right.node],
    })
}

fn ternary_string_fn<A, B, C, O>(
    name: &'static str,
    first: impl IntoExpr<A>,
    second: impl IntoExpr<B>,
    third: impl IntoExpr<C>,
) -> Expr<O> {
    Expr::new(ExprNode::Func {
        name,
        args: vec![first.into_expr().node, second.into_expr().node, third.into_expr().node],
    })
}

fn string_expr_nodes<I, A>(args: I) -> Vec<ExprNode>
where
    I: IntoIterator<Item = A>,
    A: IntoConcatExpr,
{
    args.into_iter().map(|arg| arg.into_concat_expr().node).collect()
}

fn directed_trim_fn<T>(
    arg: impl IntoExpr<T>,
    direction: TrimDirection,
    characters: Option<Expr<String>>,
) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    Expr::new(ExprNode::Trim {
        direction,
        expr: Box::new(arg.into_expr().node),
        characters: characters.map(|characters| Box::new(characters.node)),
    })
}

/// Converts text to uppercase according to the database locale, preserving input nullability.
/// Maps to PostgreSQL `UPPER`.
pub fn upper<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    unary_string_fn("UPPER", arg)
}

/// Converts text to lowercase according to the database locale, preserving input nullability.
/// Maps to PostgreSQL `LOWER`.
pub fn lower<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    unary_string_fn("LOWER", arg)
}

/// Converts the first letter of each alphanumeric word to upper case and the rest to lower case.
/// Maps to PostgreSQL `INITCAP`.
pub fn title_case<T>(expression: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    unary_string_fn("INITCAP", expression)
}

/// Replaces every exact occurrence of `from` with `to`.
/// Returns NULL if any argument is NULL.
/// Maps to PostgreSQL `REPLACE`.
pub fn replace<S, F, T>(
    expression: impl IntoExpr<S>,
    from: impl IntoExpr<F>,
    to: impl IntoExpr<T>,
) -> Expr<<<S as StringBinaryExpr<F, String>>::Output as StringBinaryExpr<T, String>>::Output>
where
    S: StringBinaryExpr<F, String>,
    <S as StringBinaryExpr<F, String>>::Output: StringBinaryExpr<T, String>,
{
    ternary_string_fn("REPLACE", expression, from, to)
}

/// Replaces `count` characters from the 1-based `start` with `replacement`.
/// Returns NULL if either string argument is NULL.
/// Maps to PostgreSQL's callable `OVERLAY` form.
pub fn replace_range<S, R>(
    expression: impl IntoExpr<S>,
    replacement: impl IntoExpr<R>,
    start: impl IntoExpr<i32>,
    count: impl IntoExpr<i32>,
) -> Expr<<S as StringBinaryExpr<R, String>>::Output>
where
    S: StringBinaryExpr<R, String>,
{
    Expr::new(ExprNode::Func {
        name: "OVERLAY",
        args: vec![
            expression.into_expr().node,
            replacement.into_expr().node,
            start.into_expr().node,
            count.into_expr().node,
        ],
    })
}

/// Replaces characters positionally, deleting `from` characters without a corresponding `to` character.
/// Returns NULL if any argument is NULL.
/// Maps to PostgreSQL `TRANSLATE`.
pub fn translate_chars<S, F, T>(
    expression: impl IntoExpr<S>,
    from: impl IntoExpr<F>,
    to: impl IntoExpr<T>,
) -> Expr<<<S as StringBinaryExpr<F, String>>::Output as StringBinaryExpr<T, String>>::Output>
where
    S: StringBinaryExpr<F, String>,
    <S as StringBinaryExpr<F, String>>::Output: StringBinaryExpr<T, String>,
{
    ternary_string_fn("TRANSLATE", expression, from, to)
}

/// Reverses the characters in a string.
/// Maps to PostgreSQL `REVERSE`.
pub fn reverse<T>(expression: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    unary_string_fn("REVERSE", expression)
}

/// Removes spaces from both ends of a text expression, preserving input nullability.
/// Maps to PostgreSQL `TRIM(expression)`.
pub fn trim<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    unary_string_fn("TRIM", arg)
}

/// Removes the longest span made only of characters in the `characters` set from both ends.
/// For example, trimming `"xyxtrimyyx"` with `"xyz"` yields `"trim"`.
/// Maps to PostgreSQL `TRIM(BOTH characters FROM expression)`.
pub fn trim_chars<T>(arg: impl IntoExpr<T>, characters: impl IntoExpr<String>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    directed_trim_fn(arg, TrimDirection::Both, Some(characters.into_expr()))
}

/// Removes leading spaces from a text expression.
/// Maps to PostgreSQL `TRIM(LEADING FROM expression)`.
pub fn trim_start<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    directed_trim_fn(arg, TrimDirection::Leading, None)
}

/// Removes the longest leading span made only of characters in the `characters` set.
/// Maps to PostgreSQL `TRIM(LEADING characters FROM expression)`.
pub fn trim_start_chars<T>(arg: impl IntoExpr<T>, characters: impl IntoExpr<String>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    directed_trim_fn(arg, TrimDirection::Leading, Some(characters.into_expr()))
}

/// Removes trailing spaces from a text expression.
/// Maps to PostgreSQL `TRIM(TRAILING FROM expression)`.
pub fn trim_end<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    directed_trim_fn(arg, TrimDirection::Trailing, None)
}

/// Removes the longest trailing span made only of characters in the `characters` set.
/// Maps to PostgreSQL `TRIM(TRAILING characters FROM expression)`.
pub fn trim_end_chars<T>(arg: impl IntoExpr<T>, characters: impl IntoExpr<String>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    directed_trim_fn(arg, TrimDirection::Trailing, Some(characters.into_expr()))
}

/// Returns the number of characters in a text expression, preserving input nullability.
/// Maps to PostgreSQL `CHAR_LENGTH`.
pub fn char_length<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringLengthExpr>::Output>
where
    T: StringLengthExpr,
{
    string_length_fn("CHAR_LENGTH", arg)
}

/// Returns the encoded byte length of a text expression, preserving input nullability.
/// Maps to PostgreSQL `OCTET_LENGTH`.
pub fn byte_length<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringLengthExpr>::Output>
where
    T: StringLengthExpr,
{
    string_length_fn("OCTET_LENGTH", arg)
}

/// Returns eight times the encoded byte length, preserving input nullability.
/// Maps to PostgreSQL `BIT_LENGTH`.
pub fn bit_length<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringLengthExpr>::Output>
where
    T: StringLengthExpr,
{
    string_length_fn("BIT_LENGTH", arg)
}

/// Returns the 1-based position of `substring` in `expression`, or zero when absent.
/// Returns NULL if either argument is NULL; `position("banana", "ana")` evaluates to `2`.
/// Maps to PostgreSQL `STRPOS`.
pub fn position<L, R>(expression: impl IntoExpr<L>, substring: impl IntoExpr<R>) -> Expr<<L as StringBinaryExpr<R, i32>>::Output>
where
    L: StringBinaryExpr<R, i32>,
{
    binary_string_fn("STRPOS", expression, substring)
}

/// Tests whether `expression` begins with the exact, case-sensitive `prefix`.
/// Returns NULL if either argument is NULL; `starts_with("PostgreSQL", "Post")` evaluates to `true`.
/// Requires PostgreSQL 11 or newer.
/// Maps to PostgreSQL `STARTS_WITH`.
pub fn starts_with<L, R>(expression: impl IntoExpr<L>, prefix: impl IntoExpr<R>) -> Expr<<L as StringBinaryExpr<R, bool>>::Output>
where
    L: StringBinaryExpr<R, bool>,
{
    binary_string_fn("STARTS_WITH", expression, prefix)
}

/// Concatenates string expressions in order, ignoring NULL values.
/// Maps to PostgreSQL `CONCAT`.
pub fn concat<I, A>(values: I) -> Expr<String>
where
    I: IntoIterator<Item = A>,
    A: IntoConcatExpr,
{
    let args = string_expr_nodes(values);
    Expr::new(ExprNode::Func { name: "CONCAT", args })
}

/// Concatenates string expressions with `separator`, ignoring NULL values.
/// Returns NULL when `separator` is NULL.
/// Maps to PostgreSQL `CONCAT_WS`.
pub fn concat_with_separator<S, I, A>(separator: impl IntoExpr<S>, values: I) -> Expr<<S as StringUnaryExpr>::Output>
where
    S: StringUnaryExpr,
    I: IntoIterator<Item = A>,
    A: IntoConcatExpr,
{
    let mut args = vec![separator.into_expr().node];
    args.extend(string_expr_nodes(values));
    Expr::new(ExprNode::Func { name: "CONCAT_WS", args })
}

/// Splits a string into a text array using a delimiter.
/// A NULL delimiter splits the source into individual characters.
/// Maps to PostgreSQL `STRING_TO_ARRAY`.
pub fn split<S, D>(expression: impl IntoExpr<S>, delimiter: impl IntoExpr<D>) -> Expr<<S as StringSplitExpr>::Output>
where
    S: StringSplitExpr,
    D: StringUnaryExpr,
{
    binary_string_fn("STRING_TO_ARRAY", expression, delimiter)
}

/// Returns the 1-based field from a delimited string.
/// Negative indexes count from the end on PostgreSQL 14 or newer.
/// PostgreSQL rejects an index of zero and returns an empty string for an out-of-range index.
/// Maps to PostgreSQL `SPLIT_PART`.
pub fn split_part<S, D>(
    expression: impl IntoExpr<S>,
    delimiter: impl IntoExpr<D>,
    index: impl IntoExpr<i32>,
) -> Expr<<S as StringBinaryExpr<D, String>>::Output>
where
    S: StringBinaryExpr<D, String>,
{
    let expression = expression.into_expr();
    let delimiter = delimiter.into_expr();
    let index = index.into_expr();
    Expr::new(ExprNode::Func {
        name: "SPLIT_PART",
        args: vec![expression.node, delimiter.node, index.node],
    })
}

/// Tests whether a POSIX regular expression matches anywhere in the text.
/// Requires PostgreSQL 15 or newer.
/// Maps to PostgreSQL `REGEXP_LIKE`.
pub fn regex_is_match<L, R>(expression: impl IntoExpr<L>, pattern: impl IntoExpr<R>) -> Expr<<L as StringBinaryExpr<R, bool>>::Output>
where
    L: StringBinaryExpr<R, bool>,
{
    binary_string_fn("REGEXP_LIKE", expression, pattern)
}

/// Counts non-overlapping POSIX regular-expression matches.
/// Requires PostgreSQL 15 or newer.
/// Maps to PostgreSQL `REGEXP_COUNT`.
pub fn regex_count<L, R>(expression: impl IntoExpr<L>, pattern: impl IntoExpr<R>) -> Expr<<L as StringBinaryExpr<R, i32>>::Output>
where
    L: StringBinaryExpr<R, i32>,
{
    binary_string_fn("REGEXP_COUNT", expression, pattern)
}

/// Returns the 1-based position of the first match, or zero when absent.
/// Requires PostgreSQL 15 or newer.
/// Maps to PostgreSQL `REGEXP_INSTR`.
pub fn regex_position<L, R>(expression: impl IntoExpr<L>, pattern: impl IntoExpr<R>) -> Expr<<L as StringBinaryExpr<R, i32>>::Output>
where
    L: StringBinaryExpr<R, i32>,
{
    binary_string_fn("REGEXP_INSTR", expression, pattern)
}

/// Returns captures from the first match, or NULL when there is no match. Requires PostgreSQL 10 or newer.
/// Capture elements are nullable because optional groups can be unmatched.
/// Maps to PostgreSQL `REGEXP_MATCH`.
pub fn regex_captures<L, R>(expression: impl IntoExpr<L>, pattern: impl IntoExpr<R>) -> Expr<Option<Vec<Option<String>>>>
where
    L: StringUnaryExpr,
    R: StringUnaryExpr,
{
    binary_string_fn("REGEXP_MATCH", expression, pattern)
}

/// Returns the first matching substring, or NULL when there is no match.
/// Requires PostgreSQL 15 or newer.
/// Maps to PostgreSQL `REGEXP_SUBSTR`.
pub fn regex_extract<L, R>(expression: impl IntoExpr<L>, pattern: impl IntoExpr<R>) -> Expr<Option<String>>
where
    L: StringUnaryExpr,
    R: StringUnaryExpr,
{
    binary_string_fn("REGEXP_SUBSTR", expression, pattern)
}

/// Returns the first `count` characters, or all but the last `|count|` when negative.
/// Maps to PostgreSQL `LEFT`.
pub fn left<T>(arg: impl IntoExpr<T>, count: impl IntoExpr<i32>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    string_fn("LEFT", arg, vec![count.into_expr().node])
}

/// Returns the last `count` characters, or all but the first `|count|` when negative.
/// Maps to PostgreSQL `RIGHT`.
pub fn right<T>(arg: impl IntoExpr<T>, count: impl IntoExpr<i32>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    string_fn("RIGHT", arg, vec![count.into_expr().node])
}

/// Returns up to `count` characters from the 1-based `start`.
/// From `"abcdef"`, `(2, 3)` yields `"bcd"` and `(0, 3)` yields `"ab"`; negative counts are rejected.
/// Maps to PostgreSQL `SUBSTRING`.
pub fn substring<T>(arg: impl IntoExpr<T>, start: impl IntoExpr<i32>, count: impl IntoExpr<i32>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    string_fn("SUBSTRING", arg, vec![start.into_expr().node, count.into_expr().node])
}

/// Repeats the text `count` times.
/// Repeating `"ab"` three times yields `"ababab"`; non-positive counts yield an empty string.
/// Maps to PostgreSQL `REPEAT`.
pub fn repeat<T>(arg: impl IntoExpr<T>, count: impl IntoExpr<i32>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    string_fn("REPEAT", arg, vec![count.into_expr().node])
}

/// Pads on the left to `length` by cycling `fill`, truncating the source on the right if needed.
/// Padding `"ab"` to 5 with `"xy"` yields `"xyxab"`; empty fill adds nothing and non-positive length yields `""`.
/// Maps to PostgreSQL `LPAD`.
pub fn pad_start<T>(arg: impl IntoExpr<T>, length: impl IntoExpr<i32>, fill: impl IntoExpr<String>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    string_fn("LPAD", arg, vec![length.into_expr().node, fill.into_expr().node])
}

/// Pads on the right to `length` by cycling `fill`, truncating the source on the right if needed.
/// Padding `"ab"` to 5 with `"xy"` yields `"abxyx"`; empty fill adds nothing and non-positive length yields `""`.
/// Maps to PostgreSQL `RPAD`.
pub fn pad_end<T>(arg: impl IntoExpr<T>, length: impl IntoExpr<i32>, fill: impl IntoExpr<String>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    string_fn("RPAD", arg, vec![length.into_expr().node, fill.into_expr().node])
}

/// Replaces the first POSIX regular-expression match in `source`, or returns `source` unchanged when none exists.
/// [`RegexReplaceFlags::GLOBAL`] replaces every match; [`RegexReplaceFlags::CASE_INSENSITIVE`] ignores case.
/// `replacement` supports PostgreSQL backreferences (`\1` through `\9`, `\&`, and `\\` for a literal backslash).
/// Returns NULL if `source`, `pattern`, or `replacement` is NULL.
/// Maps to PostgreSQL `REGEXP_REPLACE`.
pub fn regex_replace<S, P, R, SP, O>(
    source: impl IntoExpr<S>,
    pattern: impl IntoExpr<P>,
    replacement: impl IntoExpr<R>,
    flags: RegexReplaceFlags,
) -> Expr<O>
where
    S: StringBinaryExpr<P, String, Output = SP>,
    SP: StringBinaryExpr<R, String, Output = O>,
{
    Expr::new(ExprNode::Func {
        name: "REGEXP_REPLACE",
        args: vec![
            source.into_expr().node,
            pattern.into_expr().node,
            replacement.into_expr().node,
            ExprNode::Value(Value::String(flags.as_postgres_str().to_string())),
        ],
    })
}

/// Splits `source` around POSIX regular-expression matches into a text array.
/// Returns `source` as the only element when no match exists.
/// Zero-length matches at the start or end, or immediately after a previous match, are ignored.
/// [`RegexSplitFlags::CASE_INSENSITIVE`] enables case-insensitive matching.
/// Returns NULL if `source` or `pattern` is NULL.
/// Maps to PostgreSQL `REGEXP_SPLIT_TO_ARRAY`.
pub fn regex_split<S, P, O>(source: impl IntoExpr<S>, pattern: impl IntoExpr<P>, flags: RegexSplitFlags) -> Expr<O>
where
    S: StringBinaryExpr<P, Vec<String>, Output = O>,
{
    Expr::new(ExprNode::Func {
        name: "REGEXP_SPLIT_TO_ARRAY",
        args: vec![
            source.into_expr().node,
            pattern.into_expr().node,
            ExprNode::Value(Value::String(flags.as_postgres_str().to_string())),
        ],
    })
}

/// Normalizes text using the selected Unicode form. Requires PostgreSQL 13 or newer and `UTF8`.
/// Maps to PostgreSQL `NORMALIZE(expression, form)`.
pub fn normalize<T>(arg: impl IntoExpr<T>, form: NormalizationForm) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    Expr::new(ExprNode::Normalize {
        expr: Box::new(arg.into_expr().node),
        form,
    })
}

/// Returns the numeric code of the first character, or zero for empty text.
/// Other multibyte encodings accept only ASCII characters.
/// Maps to PostgreSQL `ASCII`, which returns Unicode code points with `UTF8`.
pub fn first_codepoint<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringLengthExpr>::Output>
where
    T: StringLengthExpr,
{
    string_length_fn("ASCII", arg)
}

/// Returns the character for an integer code point. PostgreSQL rejects zero and invalid code points.
/// Other multibyte encodings accept only ASCII characters.
/// Maps to PostgreSQL `CHR`, which interprets Unicode code points with `UTF8`.
pub fn from_codepoint<T>(arg: impl IntoExpr<T>) -> Expr<<T as CodepointExpr>::Output>
where
    T: CodepointExpr,
{
    let expr = arg.into_expr();
    Expr::new(ExprNode::Func {
        name: "CHR",
        args: vec![expr.node],
    })
}

/// Converts text to ASCII, primarily by removing accents.
/// Supports only `LATIN1`, `LATIN2`, `LATIN9`, and `WIN1250` database encodings, not `UTF8`.
/// Maps to PostgreSQL `TO_ASCII(expression)`.
pub fn to_ascii<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    unary_string_fn("TO_ASCII", arg)
}

/// Performs collation-dependent Unicode case folding. Requires PostgreSQL 18 or newer and `UTF8`.
/// Maps to PostgreSQL `CASEFOLD`.
pub fn case_fold<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringUnaryExpr>::Output>
where
    T: StringUnaryExpr,
{
    unary_string_fn("CASEFOLD", arg)
}

/// Tests whether every character has an assigned Unicode code point. Requires PostgreSQL 18 or newer and `UTF8`.
/// Maps to PostgreSQL `UNICODE_ASSIGNED`.
pub fn is_unicode_assigned<T>(arg: impl IntoExpr<T>) -> Expr<<T as StringBoolExpr>::Output>
where
    T: StringBoolExpr,
{
    let expr = arg.into_expr();
    Expr::new(ExprNode::Func {
        name: "UNICODE_ASSIGNED",
        args: vec![expr.node],
    })
}

pub fn count<T>(arg: impl IntoExpr<T>) -> AggregateExpr<i64> {
    let expr = arg.into_expr();
    Expr::new(ExprNode::Func {
        name: "COUNT",
        args: vec![expr.node],
    })
}

pub fn sum<T>(arg: impl IntoExpr<T>) -> AggregateExpr<T> {
    let expr = arg.into_expr();
    Expr::new(ExprNode::Func {
        name: "SUM",
        args: vec![expr.node],
    })
}

pub trait NullableAggregateOutput {
    type Output;
}

macro_rules! impl_nullable_aggregate_output {
    ($($ty:ty),+ $(,)?) => {
        $(
            impl NullableAggregateOutput for $ty {
                type Output = Option<$ty>;
            }

            impl NullableAggregateOutput for Option<$ty> {
                type Output = Option<$ty>;
            }
        )+
    };
}

impl_nullable_aggregate_output!(
    String,
    i16,
    i32,
    i64,
    f32,
    f64,
    uuid::Uuid,
    chrono::NaiveDateTime,
    chrono::DateTime<chrono::Utc>,
    chrono::NaiveDate,
    chrono::NaiveTime,
    crate::PgInterval,
);

pub fn min<T>(arg: impl IntoExpr<T>) -> AggregateExpr<<T as NullableAggregateOutput>::Output>
where
    T: NullableAggregateOutput,
{
    let expr = arg.into_expr();
    Expr::new(ExprNode::Func {
        name: "MIN",
        args: vec![expr.node],
    })
}

pub fn max<T>(arg: impl IntoExpr<T>) -> AggregateExpr<<T as NullableAggregateOutput>::Output>
where
    T: NullableAggregateOutput,
{
    let expr = arg.into_expr();
    Expr::new(ExprNode::Func {
        name: "MAX",
        args: vec![expr.node],
    })
}

pub fn coalesce<T>(a: impl IntoExpr<T>, b: impl IntoExpr<T>) -> Expr<T> {
    let left = a.into_expr();
    let right = b.into_expr();
    Expr::new(ExprNode::Func {
        name: "COALESCE",
        args: vec![left.node, right.node],
    })
}

pub fn least<T>(a: impl IntoExpr<T>, b: impl IntoExpr<T>) -> Expr<T> {
    let left = a.into_expr();
    let right = b.into_expr();
    Expr::new(ExprNode::Func {
        name: "LEAST",
        args: vec![left.node, right.node],
    })
}

pub fn greatest<T>(a: impl IntoExpr<T>, b: impl IntoExpr<T>) -> Expr<T> {
    let left = a.into_expr();
    let right = b.into_expr();
    Expr::new(ExprNode::Func {
        name: "GREATEST",
        args: vec![left.node, right.node],
    })
}

pub fn power<B, E>(base: impl IntoExpr<B>, exponent: impl IntoExpr<E>) -> Expr<f64>
where
    B: NumericExprType,
    E: NumericExprType,
{
    let base = base.into_expr();
    let exponent = exponent.into_expr();
    Expr::new(ExprNode::Func {
        name: "POWER",
        args: vec![base.node, exponent.node],
    })
}

pub fn date_trunc<T>(part: impl IntoExpr<String>, value: impl IntoExpr<T>) -> Expr<T> {
    let part = part.into_expr();
    let value = value.into_expr();
    Expr::new(ExprNode::Func {
        name: "DATE_TRUNC",
        args: vec![part.node, value.node],
    })
}

fn exists_expr(subquery: CompiledSql) -> Expr<bool> {
    Expr::new(ExprNode::Exists { subquery })
}

pub fn exists<Out, Loads, Lock, DistinctState, GroupState>(subquery: Select<Out, Loads, Lock, DistinctState, GroupState>) -> Expr<bool> {
    exists_expr(subquery.compile_for_exists())
}

/// Marker trait for values that can participate in vector distance/similarity expressions.
pub trait VectorExpr<const N: usize> {}

impl<const N: usize> VectorExpr<N> for PgVector<N> {}
impl<const N: usize> VectorExpr<N> for Option<PgVector<N>> {}

fn vector_binary_fn<const N: usize, L, R>(name: &'static str, left: impl IntoExpr<L>, right: impl IntoExpr<R>) -> Expr<f32>
where
    L: VectorExpr<N>,
    R: VectorExpr<N>,
{
    let left = left.into_expr();
    let right = right.into_expr();
    Expr::new(ExprNode::Func {
        name,
        args: vec![left.node, right.node],
    })
}

fn vector_binary_operator<const N: usize, L, R>(op: VectorBinaryOp, left: impl IntoExpr<L>, right: impl IntoExpr<R>) -> Expr<f32>
where
    L: VectorExpr<N>,
    R: VectorExpr<N>,
{
    let left = left.into_expr();
    let right = right.into_expr();
    Expr::new(ExprNode::VectorBinary {
        left: Box::new(left.node),
        op,
        right: Box::new(right.node),
    })
}

/// Euclidean (L2) distance using pgvector's `<->` operator.
///
/// Lower is more similar.
///
/// ANN note:
/// - This form is operator-based and can use pgvector ivfflat/hnsw indexes for
///   `ORDER BY ... LIMIT` nearest-neighbor queries.
pub fn l2_distance<const N: usize, L, R>(left: impl IntoExpr<L>, right: impl IntoExpr<R>) -> Expr<f32>
where
    L: VectorExpr<N>,
    R: VectorExpr<N>,
{
    vector_binary_operator::<N, L, R>(VectorBinaryOp::L2Distance, left, right)
}

/// Cosine distance using pgvector's `<=>` operator.
///
/// Lower is more similar.
///
/// ANN note:
/// - This form is operator-based and can use pgvector ivfflat/hnsw indexes for
///   `ORDER BY ... LIMIT` nearest-neighbor queries.
pub fn cosine_distance<const N: usize, L, R>(left: impl IntoExpr<L>, right: impl IntoExpr<R>) -> Expr<f32>
where
    L: VectorExpr<N>,
    R: VectorExpr<N>,
{
    vector_binary_operator::<N, L, R>(VectorBinaryOp::CosineDistance, left, right)
}

/// True inner product as a function expression (`INNER_PRODUCT(a, b)`).
///
/// Higher is more similar (for normalized embeddings, identical vectors are `1.0`).
///
/// ANN warning:
/// - This is intentionally a function call to preserve true inner-product semantics,
///   but function expressions are generally not pgvector ANN index-compatible for
///   `ORDER BY ... LIMIT`.
/// - For ANN-indexed retrieval, use [`inner_product_distance`] with `ORDER BY ASC`.
pub fn inner_product<const N: usize, L, R>(left: impl IntoExpr<L>, right: impl IntoExpr<R>) -> Expr<f32>
where
    L: VectorExpr<N>,
    R: VectorExpr<N>,
{
    vector_binary_fn::<N, L, R>("INNER_PRODUCT", left, right)
}

/// L1 (Manhattan) distance using pgvector's `<+>` operator.
///
/// Lower is more similar.
///
/// ANN note:
/// - This form is operator-based and can use pgvector ivfflat/hnsw indexes for
///   `ORDER BY ... LIMIT` nearest-neighbor queries.
pub fn l1_distance<const N: usize, L, R>(left: impl IntoExpr<L>, right: impl IntoExpr<R>) -> Expr<f32>
where
    L: VectorExpr<N>,
    R: VectorExpr<N>,
{
    vector_binary_operator::<N, L, R>(VectorBinaryOp::L1Distance, left, right)
}

/// Negative inner-product distance using pgvector's `<#>` operator.
///
/// Lower is more similar, so nearest-neighbor queries should use `ORDER BY ASC`.
///
/// ANN note:
/// - This form is operator-based and can use pgvector ivfflat/hnsw indexes for
///   `ORDER BY ... LIMIT` nearest-neighbor queries.
/// - Thresholds are inverted relative to true inner product
///   (for example `inner_product > 0.9` corresponds to
///   `inner_product_distance < -0.9`).
pub fn inner_product_distance<const N: usize, L, R>(left: impl IntoExpr<L>, right: impl IntoExpr<R>) -> Expr<f32>
where
    L: VectorExpr<N>,
    R: VectorExpr<N>,
{
    vector_binary_operator::<N, L, R>(VectorBinaryOp::InnerProductDistance, left, right)
}