pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/expressions.py

@@ -0,0 +1,1200 @@
+"""Typed immutable scalar expressions and predicates."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from typing import TYPE_CHECKING, Generic, TypeAlias, TypeVar, cast, overload
+
+from pyoq.errors import ExpressionTypeError
+from pyoq.query.nodes import (
+    ArrayDimensionsNode,
+    ArrayElementNode,
+    ArrayLengthNode,
+    ArrayNode,
+    ArrayOperation,
+    BinaryNode,
+    BinaryOperator,
+    BoundValueNode,
+    DatePart,
+    ExpressionNode,
+    ExtractNode,
+    FunctionName,
+    FunctionNode,
+    JsonContainsNode,
+    JsonKeysNode,
+    JsonNode,
+    JsonOperation,
+    JsonWrite,
+    JsonWriteNode,
+    NodeProvider,
+    ScalarFamily,
+    UnaryNode,
+    UnaryOperator,
+    VariadicNode,
+    VariadicOperator,
+)
+from pyoq.query.results import expression_family
+from pyoq.schema.models import JsonValue
+
+if TYPE_CHECKING:
+    from pyoq.query.projections import OrderTerm, Projection
+    from pyoq.query.results import ResultDescriptor
+
+Value = TypeVar("Value")
+Operand = TypeVar("Operand")
+OrderedValue = TypeVar(
+    "OrderedValue",
+    bound=int | float | Decimal | str | date | datetime | time | timedelta | None,
+)
+TemporalValue = TypeVar("TemporalValue", bound=date | datetime | time | None)
+HelperValue = TypeVar("HelperValue")
+Element = TypeVar("Element")
+
+
+_WHOLE_DOCUMENT_WRITES = frozenset({JsonWrite.MERGE, JsonWrite.CONCAT})
+"""Writes that take one document into another rather than reaching a member."""
+
+
+class Expression(Generic[Value]):
+    __slots__ = ("_expression_family", "_expression_node")
+    _expression_family: ScalarFamily
+    _expression_node: ExpressionNode
+
+    def __init__(self, node: ExpressionNode, family: ScalarFamily) -> None:
+        self._initialize_expression(node, family)
+
+    def _initialize_expression(
+        self,
+        node: ExpressionNode,
+        family: ScalarFamily,
+    ) -> None:
+        object.__setattr__(self, "_expression_node", node)
+        object.__setattr__(self, "_expression_family", family)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = "expressions are immutable"
+        raise AttributeError(message)
+
+    @property
+    def node(self) -> ExpressionNode:
+        return self._expression_node
+
+    @property
+    def family(self) -> ScalarFamily:
+        return self._expression_family
+
+    @property
+    def result(self) -> ResultDescriptor:
+        """What this answers with: its kind, its Python type, its nullability.
+
+        Derived from the tree rather than stored, so an expression built out
+        of others cannot disagree with what it was built from.
+        """
+        from pyoq.query.results import result_descriptor
+
+        return result_descriptor(self.node)
+
+    def as_(self, name: str, /) -> Projection[Value]:
+        from pyoq.query.projections import alias
+
+        return alias(self, name)
+
+    def asc(self) -> OrderTerm:
+        from pyoq.query.projections import ascending
+
+        return ascending(self)
+
+    def desc(self) -> OrderTerm:
+        from pyoq.query.projections import descending
+
+        return descending(self)
+
+    def eq(
+        self: Expression[Operand],
+        other: Operand | Expression[Operand],
+        /,
+    ) -> Condition:
+        if other is None:
+            return self.is_null()
+        return _comparison(BinaryOperator.EQUAL, self, other)
+
+    def ne(
+        self: Expression[Operand],
+        other: Operand | Expression[Operand],
+        /,
+    ) -> Condition:
+        if other is None:
+            return self.is_not_null()
+        return _comparison(BinaryOperator.NOT_EQUAL, self, other)
+
+    def is_distinct_from(
+        self: Expression[Operand],
+        other: Operand | Expression[Operand],
+        /,
+    ) -> Condition:
+        return _comparison(BinaryOperator.IS_DISTINCT_FROM, self, other)
+
+    def is_not_distinct_from(
+        self: Expression[Operand],
+        other: Operand | Expression[Operand],
+        /,
+    ) -> Condition:
+        return _comparison(BinaryOperator.IS_NOT_DISTINCT_FROM, self, other)
+
+    def has(
+        self: Expression[tuple[Element, ...]],
+        value: Element,
+        /,
+    ) -> Condition:
+        """Whether this array holds that value."""
+        return Condition(self._array_node(ArrayOperation.HAS, (value,)))
+
+    def lacks(
+        self: Expression[tuple[Element, ...]],
+        value: Element,
+        /,
+    ) -> Condition:
+        """Whether this array holds that value nowhere."""
+        return Condition(self._array_node(ArrayOperation.LACKS, (value,)))
+
+    def contains_all(
+        self: Expression[tuple[Element, ...]],
+        values: tuple[Element, ...],
+        /,
+    ) -> Condition:
+        """Whether this array holds every one of those values."""
+        return Condition(self._array_node(ArrayOperation.CONTAINS, values))
+
+    def contained_by(
+        self: Expression[tuple[Element, ...]],
+        values: tuple[Element, ...],
+        /,
+    ) -> Condition:
+        """Whether every value of this array is among those."""
+        return Condition(self._array_node(ArrayOperation.CONTAINED_BY, values))
+
+    def overlaps(
+        self: Expression[tuple[Element, ...]],
+        values: tuple[Element, ...],
+        /,
+    ) -> Condition:
+        """Whether this array and those values share anything at all."""
+        return Condition(self._array_node(ArrayOperation.OVERLAPS, values))
+
+    def append(
+        self: Expression[tuple[Element, ...]],
+        value: Element,
+        /,
+    ) -> ComputedExpression[tuple[Element, ...]]:
+        """This array with that value on the end."""
+        return self._array_result(ArrayOperation.APPEND, (value,))
+
+    def prepend(
+        self: Expression[tuple[Element, ...]],
+        value: Element,
+        /,
+    ) -> ComputedExpression[tuple[Element, ...]]:
+        """This array with that value on the front."""
+        return self._array_result(ArrayOperation.PREPEND, (value,))
+
+    def concat_array(
+        self: Expression[tuple[Element, ...]],
+        values: tuple[Element, ...],
+        /,
+    ) -> ComputedExpression[tuple[Element, ...]]:
+        """This array with those values after it."""
+        return self._array_result(ArrayOperation.CONCAT, values)
+
+    def without(
+        self: Expression[tuple[Element, ...]],
+        value: Element,
+        /,
+    ) -> ComputedExpression[tuple[Element, ...]]:
+        """This array with every copy of that value gone."""
+        return self._array_result(ArrayOperation.REMOVE, (value,))
+
+    def _array_result(
+        self: Expression[tuple[Element, ...]],
+        operation: ArrayOperation,
+        values: tuple[object, ...],
+    ) -> ComputedExpression[tuple[Element, ...]]:
+        return ComputedExpression[tuple[Element, ...]](
+            self._array_node(operation, values), ScalarFamily.OTHER
+        )
+
+    def replacing(
+        self: Expression[tuple[Element, ...]],
+        value: Element,
+        replacement: Element,
+        /,
+    ) -> ComputedExpression[tuple[Element, ...]]:
+        """This array with every copy of that value replaced by another."""
+        return ComputedExpression[tuple[Element, ...]](
+            ArrayNode(
+                ArrayOperation.REPLACE,
+                self.node,
+                (
+                    operand(value, ScalarFamily.OTHER),
+                    operand(replacement, ScalarFamily.OTHER),
+                ),
+            ),
+            ScalarFamily.OTHER,
+        )
+
+    def element(
+        self: Expression[tuple[Element, ...]],
+        *position: int,
+    ) -> ComputedExpression[Element | None]:
+        """The element at this position, counted from zero.
+
+        A column of an array is read back as a tuple and a tuple counts from
+        zero, so this counts from zero too and the dialect is told what it
+        counts from. Past the end there is no element, so the answer is null.
+
+        An array of arrays is read at one position per dimension, together,
+        because a dialect that stores one does not hand back a row of it.
+        """
+        for index in position:
+            if index < 0:
+                message = "an array is counted from zero, forwards"
+                raise ValueError(message)
+        return ComputedExpression[Element | None](
+            ArrayElementNode(
+                self.node,
+                tuple(operand(index, ScalarFamily.NUMERIC) for index in position),
+            ),
+            ScalarFamily.OTHER,
+        )
+
+    def length_along(
+        self: Expression[tuple[Element, ...]],
+        dimension: int,
+        /,
+    ) -> ComputedExpression[int | None]:
+        """How many elements this array holds along one of its dimensions.
+
+        Counted from one, the way a dialect numbers dimensions. The whole
+        count across every dimension is what length answers with.
+        """
+        if dimension < 1:
+            message = "the dimensions of an array are counted from one"
+            raise ValueError(message)
+        return ComputedExpression[int | None](
+            ArrayLengthNode(self.node, dimension), ScalarFamily.NUMERIC
+        )
+
+    def dimensions(
+        self: Expression[tuple[Element, ...]],
+    ) -> ComputedExpression[int | None]:
+        """How many dimensions this array has, which an empty array does not say."""
+        return ComputedExpression[int | None](
+            ArrayDimensionsNode(self.node), ScalarFamily.NUMERIC
+        )
+
+    def _array_node(
+        self,
+        operation: ArrayOperation,
+        values: tuple[object, ...],
+    ) -> ArrayNode:
+        one = operation in _ONE_VALUE
+        value = values[0] if one else values
+        return ArrayNode(operation, self.node, (operand(value, ScalarFamily.OTHER),))
+
+    def json_get(
+        self: Expression[HelperValue],
+        *path: str | int,
+    ) -> ComputedExpression[JsonValue]:
+        """The JSON value at this path, as JSON.
+
+        A path is steps rather than text because the dialects do not agree on
+        how one is written, and PostgreSQL reads another's spelling as a
+        member that is simply absent. A string step is a member and an
+        integer step is an element.
+        """
+        return ComputedExpression[JsonValue](
+            self._json_node(JsonOperation.VALUE, path), ScalarFamily.JSON
+        )
+
+    def json_keys(
+        self: Expression[HelperValue],
+    ) -> ComputedExpression[JsonValue]:
+        """The members this object has, as a JSON array of their names.
+
+        The dialects do not agree on the order the names come back in, because
+        each one stores an object the way it stores an object.
+        """
+        return ComputedExpression[JsonValue](JsonKeysNode(self.node), ScalarFamily.JSON)
+
+    def json_text(
+        self: Expression[HelperValue],
+        *path: str | int,
+    ) -> ComputedExpression[str | None]:
+        """The JSON value at this path, as text rather than as JSON."""
+        return ComputedExpression[str | None](
+            self._json_node(JsonOperation.TEXT, path), ScalarFamily.STRING
+        )
+
+    def json_length(
+        self: Expression[HelperValue],
+        *path: str | int,
+    ) -> ComputedExpression[int | None]:
+        """How many elements the array at this path holds."""
+        return ComputedExpression[int | None](
+            self._json_node(JsonOperation.LENGTH, path), ScalarFamily.NUMERIC
+        )
+
+    def json_has(self: Expression[HelperValue], *path: str | int) -> Condition:
+        """Whether anything is at this path at all."""
+        if not path:
+            message = "asking whether a path is there needs a path"
+            raise ValueError(message)
+        return Condition(self._json_node(JsonOperation.EXISTS, path))
+
+    def json_set(
+        self: Expression[HelperValue],
+        *path: str | int,
+        to: JsonValue | NodeProvider,
+    ) -> ComputedExpression[JsonValue]:
+        """The document with this path set, whether or not it was there."""
+        return self._json_written(JsonWrite.SET, path, to)
+
+    def json_insert(
+        self: Expression[HelperValue],
+        *path: str | int,
+        to: JsonValue | NodeProvider,
+    ) -> ComputedExpression[JsonValue]:
+        """The document with this path set, only where it was not there."""
+        return self._json_written(JsonWrite.INSERT, path, to)
+
+    def json_replace(
+        self: Expression[HelperValue],
+        *path: str | int,
+        to: JsonValue | NodeProvider,
+    ) -> ComputedExpression[JsonValue]:
+        """The document with this path set, only where it was there already."""
+        return self._json_written(JsonWrite.REPLACE, path, to)
+
+    def json_merge(
+        self: Expression[HelperValue],
+        value: JsonValue | NodeProvider,
+        /,
+    ) -> ComputedExpression[JsonValue]:
+        """The document with that one merged into it, all the way down.
+
+        This is merge-patch: a member given as null is removed rather than set
+        to null, and two objects at the same member are merged rather than one
+        replacing the other. PostgreSQL has no merge-patch of its own and its
+        concatenation is a different operation, so it is refused there and
+        ``json_concat`` says the other thing plainly.
+        """
+        return self._json_written(JsonWrite.MERGE, (), value)
+
+    def json_concat(
+        self: Expression[HelperValue],
+        value: JsonValue | NodeProvider,
+        /,
+    ) -> ComputedExpression[JsonValue]:
+        """The document with that one written over its members, one level deep.
+
+        A member of the second document replaces the first whole, an object is
+        not merged into an object, and a null is stored as a null rather than
+        removing anything.
+        """
+        return self._json_written(JsonWrite.CONCAT, (), value)
+
+    def json_remove(
+        self: Expression[HelperValue],
+        *path: str | int,
+    ) -> ComputedExpression[JsonValue]:
+        """The document without whatever was at this path."""
+        if not path:
+            message = "removing something from a document needs a path"
+            raise ValueError(message)
+        return ComputedExpression[JsonValue](
+            self._json_node(JsonOperation.REMOVE, path), ScalarFamily.JSON
+        )
+
+    def _json_written(
+        self,
+        operation: JsonWrite,
+        path: tuple[str | int, ...],
+        value: JsonValue | NodeProvider,
+    ) -> ComputedExpression[JsonValue]:
+        """A value or an expression, because a member can be set from a column."""
+        _require_family(self.family, ScalarFamily.JSON)
+        if operation not in _WHOLE_DOCUMENT_WRITES and not path:
+            message = "writing into a document needs a path"
+            raise ValueError(message)
+        written = (
+            value.node
+            if isinstance(value, NodeProvider)
+            else operand(value, ScalarFamily.JSON)
+        )
+        return ComputedExpression[JsonValue](
+            JsonWriteNode(operation, self.node, written, path), ScalarFamily.JSON
+        )
+
+    def json_contains(
+        self: Expression[HelperValue],
+        value: JsonValue,
+        /,
+    ) -> Condition:
+        """Whether this JSON value holds that one."""
+        _require_family(self.family, ScalarFamily.JSON)
+        return Condition(JsonContainsNode(self.node, operand(value, ScalarFamily.JSON)))
+
+    def _json_node(
+        self,
+        operation: JsonOperation,
+        path: tuple[str | int, ...],
+    ) -> JsonNode:
+        _require_family(self.family, ScalarFamily.JSON)
+        return JsonNode(operation, self.node, path)
+
+    def is_null(self) -> Condition:
+        return Condition(UnaryNode(UnaryOperator.IS_NULL, self.node))
+
+    def is_not_null(self) -> Condition:
+        return Condition(UnaryNode(UnaryOperator.IS_NOT_NULL, self.node))
+
+    def in_(
+        self: Expression[Operand],
+        *values: Operand | Expression[Operand],
+    ) -> Condition:
+        return _membership(VariadicOperator.IN, self, values)
+
+    def not_in(
+        self: Expression[Operand],
+        *values: Operand | Expression[Operand],
+    ) -> Condition:
+        return _membership(VariadicOperator.NOT_IN, self, values)
+
+    def between(
+        self: Expression[OrderedValue],
+        lower: OrderedValue | Expression[OrderedValue],
+        upper: OrderedValue | Expression[OrderedValue],
+        /,
+    ) -> Condition:
+        _require_ordered(self.family)
+        return _range_condition(VariadicOperator.BETWEEN, self, lower, upper)
+
+    def not_between(
+        self: Expression[OrderedValue],
+        lower: OrderedValue | Expression[OrderedValue],
+        upper: OrderedValue | Expression[OrderedValue],
+        /,
+    ) -> Condition:
+        _require_ordered(self.family)
+        return _range_condition(VariadicOperator.NOT_BETWEEN, self, lower, upper)
+
+    def lt(
+        self: Expression[OrderedValue],
+        other: OrderedValue | Expression[OrderedValue],
+        /,
+    ) -> Condition:
+        _require_ordered(self.family)
+        return _comparison(BinaryOperator.LESS_THAN, self, other)
+
+    def le(
+        self: Expression[OrderedValue],
+        other: OrderedValue | Expression[OrderedValue],
+        /,
+    ) -> Condition:
+        _require_ordered(self.family)
+        return _comparison(BinaryOperator.LESS_OR_EQUAL, self, other)
+
+    def gt(
+        self: Expression[OrderedValue],
+        other: OrderedValue | Expression[OrderedValue],
+        /,
+    ) -> Condition:
+        _require_ordered(self.family)
+        return _comparison(BinaryOperator.GREATER_THAN, self, other)
+
+    def ge(
+        self: Expression[OrderedValue],
+        other: OrderedValue | Expression[OrderedValue],
+        /,
+    ) -> Condition:
+        _require_ordered(self.family)
+        return _comparison(BinaryOperator.GREATER_OR_EQUAL, self, other)
+
+    @overload
+    def add(
+        self: Expression[int], other: int | Expression[int], /
+    ) -> ComputedExpression[int]: ...
+
+    @overload
+    def add(
+        self: Expression[float], other: float | Expression[float], /
+    ) -> ComputedExpression[float]: ...
+
+    @overload
+    def add(
+        self: Expression[Decimal], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal]: ...
+
+    @overload
+    def add(
+        self: Expression[int | None], other: int | Expression[int], /
+    ) -> ComputedExpression[int | None]: ...
+
+    @overload
+    def add(
+        self: Expression[float | None], other: float | Expression[float], /
+    ) -> NullableFloatResult: ...
+
+    @overload
+    def add(
+        self: Expression[Decimal | None], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal | None]: ...
+
+    def add(self, other: object, /) -> NumericResult:
+        return cast(NumericResult, _numeric(BinaryOperator.ADD, self, other))
+
+    @overload
+    def subtract(
+        self: Expression[int], other: int | Expression[int], /
+    ) -> ComputedExpression[int]: ...
+
+    @overload
+    def subtract(
+        self: Expression[float], other: float | Expression[float], /
+    ) -> ComputedExpression[float]: ...
+
+    @overload
+    def subtract(
+        self: Expression[Decimal], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal]: ...
+
+    @overload
+    def subtract(
+        self: Expression[int | None], other: int | Expression[int], /
+    ) -> ComputedExpression[int | None]: ...
+
+    @overload
+    def subtract(
+        self: Expression[float | None], other: float | Expression[float], /
+    ) -> NullableFloatResult: ...
+
+    @overload
+    def subtract(
+        self: Expression[Decimal | None], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal | None]: ...
+
+    def subtract(self, other: object, /) -> NumericResult:
+        return cast(NumericResult, _numeric(BinaryOperator.SUBTRACT, self, other))
+
+    @overload
+    def multiply(
+        self: Expression[int], other: int | Expression[int], /
+    ) -> ComputedExpression[int]: ...
+
+    @overload
+    def multiply(
+        self: Expression[float], other: float | Expression[float], /
+    ) -> ComputedExpression[float]: ...
+
+    @overload
+    def multiply(
+        self: Expression[Decimal], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal]: ...
+
+    @overload
+    def multiply(
+        self: Expression[int | None], other: int | Expression[int], /
+    ) -> ComputedExpression[int | None]: ...
+
+    @overload
+    def multiply(
+        self: Expression[float | None], other: float | Expression[float], /
+    ) -> NullableFloatResult: ...
+
+    @overload
+    def multiply(
+        self: Expression[Decimal | None], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal | None]: ...
+
+    def multiply(self, other: object, /) -> NumericResult:
+        return cast(NumericResult, _numeric(BinaryOperator.MULTIPLY, self, other))
+
+    @overload
+    def divide(
+        self: Expression[int], other: int | Expression[int], /
+    ) -> ComputedExpression[int]: ...
+
+    @overload
+    def divide(
+        self: Expression[float], other: float | Expression[float], /
+    ) -> ComputedExpression[float]: ...
+
+    @overload
+    def divide(
+        self: Expression[Decimal], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal]: ...
+
+    @overload
+    def divide(
+        self: Expression[int | None], other: int | Expression[int], /
+    ) -> ComputedExpression[int | None]: ...
+
+    @overload
+    def divide(
+        self: Expression[float | None], other: float | Expression[float], /
+    ) -> NullableFloatResult: ...
+
+    @overload
+    def divide(
+        self: Expression[Decimal | None], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal | None]: ...
+
+    def divide(self, other: object, /) -> NumericResult:
+        return cast(NumericResult, _numeric(BinaryOperator.DIVIDE, self, other))
+
+    @overload
+    def modulo(
+        self: Expression[int], other: int | Expression[int], /
+    ) -> ComputedExpression[int]: ...
+
+    @overload
+    def modulo(
+        self: Expression[float], other: float | Expression[float], /
+    ) -> ComputedExpression[float]: ...
+
+    @overload
+    def modulo(
+        self: Expression[Decimal], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal]: ...
+
+    @overload
+    def modulo(
+        self: Expression[int | None], other: int | Expression[int], /
+    ) -> ComputedExpression[int | None]: ...
+
+    @overload
+    def modulo(
+        self: Expression[float | None], other: float | Expression[float], /
+    ) -> NullableFloatResult: ...
+
+    @overload
+    def modulo(
+        self: Expression[Decimal | None], other: Decimal | Expression[Decimal], /
+    ) -> ComputedExpression[Decimal | None]: ...
+
+    def modulo(self, other: object, /) -> NumericResult:
+        return cast(NumericResult, _numeric(BinaryOperator.MODULO, self, other))
+
+    def negate(self: Expression[Operand]) -> ComputedExpression[Operand]:
+        _require_family(self.family, ScalarFamily.NUMERIC)
+        return ComputedExpression(
+            UnaryNode(UnaryOperator.NEGATE, self.node), self.family
+        )
+
+    @overload
+    def concat(
+        self: Expression[str], other: str | Expression[str], /
+    ) -> ComputedExpression[str]: ...
+
+    @overload
+    def concat(
+        self: Expression[str | None], other: str | Expression[str], /
+    ) -> ComputedExpression[str | None]: ...
+
+    def concat(self, other: object, /) -> StringResult:
+        return cast(StringResult, _string_binary(BinaryOperator.CONCAT, self, other))
+
+    @overload
+    def like(self: Expression[str], pattern: str | Expression[str], /) -> Condition: ...
+
+    @overload
+    def like(
+        self: Expression[str | None], pattern: str | Expression[str], /
+    ) -> Condition: ...
+
+    def like(self, pattern: str | Expression[str], /) -> Condition:
+        return _string_condition(BinaryOperator.LIKE, self, pattern)
+
+    @overload
+    def not_like(
+        self: Expression[str], pattern: str | Expression[str], /
+    ) -> Condition: ...
+
+    @overload
+    def not_like(
+        self: Expression[str | None], pattern: str | Expression[str], /
+    ) -> Condition: ...
+
+    def not_like(self, pattern: str | Expression[str], /) -> Condition:
+        return _string_condition(BinaryOperator.NOT_LIKE, self, pattern)
+
+    @overload
+    def contains(
+        self: Expression[str], value: str | Expression[str], /
+    ) -> Condition: ...
+
+    @overload
+    def contains(
+        self: Expression[str | None], value: str | Expression[str], /
+    ) -> Condition: ...
+
+    def contains(self, value: str | Expression[str], /) -> Condition:
+        return _string_function(FunctionName.CONTAINS, self, value)
+
+    @overload
+    def starts_with(
+        self: Expression[str], value: str | Expression[str], /
+    ) -> Condition: ...
+
+    @overload
+    def starts_with(
+        self: Expression[str | None], value: str | Expression[str], /
+    ) -> Condition: ...
+
+    def starts_with(self, value: str | Expression[str], /) -> Condition:
+        return _string_function(FunctionName.STARTS_WITH, self, value)
+
+    @overload
+    def ends_with(
+        self: Expression[str], value: str | Expression[str], /
+    ) -> Condition: ...
+
+    @overload
+    def ends_with(
+        self: Expression[str | None], value: str | Expression[str], /
+    ) -> Condition: ...
+
+    def ends_with(self, value: str | Expression[str], /) -> Condition:
+        return _string_function(FunctionName.ENDS_WITH, self, value)
+
+    @overload
+    def is_true(self: Expression[bool]) -> Condition: ...
+
+    @overload
+    def is_true(self: Expression[bool | None]) -> Condition: ...
+
+    def is_true(self) -> Condition:
+        _require_family(self.family, ScalarFamily.BOOLEAN)
+        return Condition(UnaryNode(UnaryOperator.IS_TRUE, self.node))
+
+    @overload
+    def is_false(self: Expression[bool]) -> Condition: ...
+
+    @overload
+    def is_false(self: Expression[bool | None]) -> Condition: ...
+
+    def is_false(self) -> Condition:
+        _require_family(self.family, ScalarFamily.BOOLEAN)
+        return Condition(UnaryNode(UnaryOperator.IS_FALSE, self.node))
+
+    @overload
+    def lower(self: Expression[str]) -> ComputedExpression[str]: ...
+
+    @overload
+    def lower(self: Expression[str | None]) -> ComputedExpression[str | None]: ...
+
+    def lower(self) -> StringResult:
+        return cast(StringResult, _string_transform(FunctionName.LOWER, self))
+
+    @overload
+    def upper(self: Expression[str]) -> ComputedExpression[str]: ...
+
+    @overload
+    def upper(self: Expression[str | None]) -> ComputedExpression[str | None]: ...
+
+    def upper(self) -> StringResult:
+        return cast(StringResult, _string_transform(FunctionName.UPPER, self))
+
+    @overload
+    def length(self: Expression[str]) -> ComputedExpression[int]: ...
+
+    @overload
+    def length(self: Expression[str | None]) -> ComputedExpression[int | None]: ...
+
+    @overload
+    def length(
+        self: Expression[tuple[Element, ...]],
+    ) -> ComputedExpression[int | None]: ...
+
+    def length(self) -> LengthResult:
+        """How long this is: characters of text, or elements of an array."""
+        if self.family is ScalarFamily.OTHER:
+            return cast(
+                LengthResult,
+                ComputedExpression[int | None](
+                    ArrayLengthNode(self.node), ScalarFamily.NUMERIC
+                ),
+            )
+        _require_family(self.family, ScalarFamily.STRING)
+        return cast(
+            LengthResult,
+            ComputedExpression[int](
+                FunctionNode(FunctionName.LENGTH, (self.node,)),
+                ScalarFamily.NUMERIC,
+            ),
+        )
+
+    @overload
+    def extract(
+        self: Expression[date], part: DatePart, /
+    ) -> ComputedExpression[int]: ...
+
+    @overload
+    def extract(
+        self: Expression[date | None], part: DatePart, /
+    ) -> ComputedExpression[int | None]: ...
+
+    @overload
+    def extract(
+        self: Expression[datetime], part: DatePart, /
+    ) -> ComputedExpression[int]: ...
+
+    @overload
+    def extract(
+        self: Expression[datetime | None], part: DatePart, /
+    ) -> ComputedExpression[int | None]: ...
+
+    @overload
+    def extract(
+        self: Expression[time], part: DatePart, /
+    ) -> ComputedExpression[int]: ...
+
+    @overload
+    def extract(
+        self: Expression[time | None], part: DatePart, /
+    ) -> ComputedExpression[int | None]: ...
+
+    def extract(self, part: DatePart, /) -> ExtractResult:
+        _require_family(self.family, ScalarFamily.TEMPORAL)
+        return cast(
+            ExtractResult,
+            ComputedExpression[int](ExtractNode(part, self.node), ScalarFamily.NUMERIC),
+        )
+
+    def add_duration(
+        self: Expression[TemporalValue],
+        duration: timedelta | Expression[timedelta],
+        /,
+    ) -> ComputedExpression[TemporalValue]:
+        return _temporal(BinaryOperator.ADD, self, duration)
+
+    def subtract_duration(
+        self: Expression[TemporalValue],
+        duration: timedelta | Expression[timedelta],
+        /,
+    ) -> ComputedExpression[TemporalValue]:
+        return _temporal(BinaryOperator.SUBTRACT, self, duration)
+
+    @overload
+    def difference(
+        self: Expression[date],
+        other: date | Expression[date],
+        /,
+    ) -> ComputedExpression[timedelta]: ...
+
+    @overload
+    def difference(
+        self: Expression[date | None],
+        other: date | Expression[date],
+        /,
+    ) -> ComputedExpression[timedelta | None]: ...
+
+    @overload
+    def difference(
+        self: Expression[datetime],
+        other: datetime | Expression[datetime],
+        /,
+    ) -> ComputedExpression[timedelta]: ...
+
+    @overload
+    def difference(
+        self: Expression[datetime | None],
+        other: datetime | Expression[datetime],
+        /,
+    ) -> ComputedExpression[timedelta | None]: ...
+
+    @overload
+    def difference(
+        self: Expression[time],
+        other: time | Expression[time],
+        /,
+    ) -> ComputedExpression[timedelta]: ...
+
+    @overload
+    def difference(
+        self: Expression[time | None],
+        other: time | Expression[time],
+        /,
+    ) -> ComputedExpression[timedelta | None]: ...
+
+    def difference(self, other: object, /) -> DifferenceResult:
+        _require_family(self.family, ScalarFamily.TEMPORAL)
+        return cast(
+            DifferenceResult,
+            ComputedExpression[timedelta](
+                BinaryNode(
+                    BinaryOperator.SUBTRACT,
+                    self.node,
+                    operand(other, ScalarFamily.TEMPORAL),
+                ),
+                ScalarFamily.TEMPORAL,
+            ),
+        )
+
+
+class ComputedExpression(Expression[Value], Generic[Value]):
+    __slots__ = ()
+
+
+LengthResult: TypeAlias = ComputedExpression[int] | ComputedExpression[int | None]
+ExtractResult: TypeAlias = ComputedExpression[int] | ComputedExpression[int | None]
+NumericResult: TypeAlias = (
+    ComputedExpression[int]
+    | ComputedExpression[float]
+    | ComputedExpression[Decimal]
+    | ComputedExpression[int | None]
+    | ComputedExpression[float | None]
+    | ComputedExpression[Decimal | None]
+)
+NullableFloatResult: TypeAlias = (
+    ComputedExpression[int | None] | ComputedExpression[float | None]
+)
+StringResult: TypeAlias = ComputedExpression[str] | ComputedExpression[str | None]
+DifferenceResult: TypeAlias = (
+    ComputedExpression[timedelta] | ComputedExpression[timedelta | None]
+)
+
+
+class Condition(Expression[bool]):
+    __slots__ = ()
+
+    def __init__(self, node: ExpressionNode) -> None:
+        super().__init__(node, ScalarFamily.BOOLEAN)
+
+    def and_(self, other: Expression[bool], /) -> Condition:
+        return Condition(_combine(VariadicOperator.AND, self.node, other.node))
+
+    def or_(self, other: Expression[bool], /) -> Condition:
+        return Condition(_combine(VariadicOperator.OR, self.node, other.node))
+
+    def not_(self) -> Condition:
+        return Condition(UnaryNode(UnaryOperator.NOT, self.node))
+
+    def __and__(self, other: Expression[bool], /) -> Condition:
+        return self.and_(other)
+
+    def __or__(self, other: Expression[bool], /) -> Condition:
+        return self.or_(other)
+
+    def __invert__(self) -> Condition:
+        return self.not_()
+
+
+_ONE_VALUE = frozenset(
+    {
+        ArrayOperation.HAS,
+        ArrayOperation.LACKS,
+        ArrayOperation.APPEND,
+        ArrayOperation.PREPEND,
+        ArrayOperation.REMOVE,
+    }
+)
+"""The ways of asking about an array that take one value, not a set of them."""
+
+
+def require_boolean(value: object, clause: str) -> None:
+    if not isinstance(value, Expression) or value.family is not ScalarFamily.BOOLEAN:
+        message = f"{clause} requires a boolean expression"
+        raise TypeError(message)
+
+
+def _comparison(
+    operator: BinaryOperator,
+    left: Expression[HelperValue],
+    right: object,
+) -> Condition:
+    right_node = operand(right, left.family)
+    return Condition(BinaryNode(operator, left.node, right_node))
+
+
+def _membership(
+    operator: VariadicOperator,
+    expression: Expression[HelperValue],
+    values: tuple[object, ...],
+) -> Condition:
+    operands = (
+        expression.node,
+        *(operand(value, expression.family) for value in values),
+    )
+    return Condition(VariadicNode(operator, operands))
+
+
+def _range_condition(
+    operator: VariadicOperator,
+    expression: Expression[HelperValue],
+    lower: object,
+    upper: object,
+) -> Condition:
+    operands = (
+        expression.node,
+        operand(lower, expression.family),
+        operand(upper, expression.family),
+    )
+    return Condition(VariadicNode(operator, operands))
+
+
+def _numeric(
+    operator: BinaryOperator,
+    left: Expression[HelperValue],
+    right: object,
+) -> ComputedExpression[HelperValue]:
+    _require_family(left.family, ScalarFamily.NUMERIC)
+    return ComputedExpression[HelperValue](
+        BinaryNode(operator, left.node, operand(right, ScalarFamily.NUMERIC)),
+        ScalarFamily.NUMERIC,
+    )
+
+
+def _string_binary(
+    operator: BinaryOperator,
+    left: Expression[HelperValue],
+    right: object,
+) -> ComputedExpression[HelperValue]:
+    _require_family(left.family, ScalarFamily.STRING)
+    return ComputedExpression[HelperValue](
+        BinaryNode(operator, left.node, operand(right, ScalarFamily.STRING)),
+        ScalarFamily.STRING,
+    )
+
+
+def _temporal(
+    operator: BinaryOperator,
+    left: Expression[TemporalValue],
+    right: timedelta | Expression[timedelta],
+) -> ComputedExpression[TemporalValue]:
+    _require_family(left.family, ScalarFamily.TEMPORAL)
+    return ComputedExpression(
+        BinaryNode(operator, left.node, operand(right, ScalarFamily.TEMPORAL)),
+        ScalarFamily.TEMPORAL,
+    )
+
+
+def _string_condition(
+    operator: BinaryOperator,
+    left: Expression[HelperValue],
+    right: object,
+) -> Condition:
+    _require_family(left.family, ScalarFamily.STRING)
+    return Condition(
+        BinaryNode(operator, left.node, operand(right, ScalarFamily.STRING))
+    )
+
+
+def _string_function(
+    name: FunctionName,
+    expression: Expression[HelperValue],
+    value: object,
+) -> Condition:
+    _require_family(expression.family, ScalarFamily.STRING)
+    arguments = (expression.node, operand(value, ScalarFamily.STRING))
+    return Condition(FunctionNode(name, arguments))
+
+
+def _string_transform(
+    name: FunctionName,
+    expression: Expression[HelperValue],
+) -> ComputedExpression[HelperValue]:
+    _require_family(expression.family, ScalarFamily.STRING)
+    return ComputedExpression[HelperValue](
+        FunctionNode(name, (expression.node,)), ScalarFamily.STRING
+    )
+
+
+def operand(value: object, expected: ScalarFamily) -> ExpressionNode:
+    """Turn a value or expression into a node, refusing an incompatible one.
+
+    What an expression is judged by is what its own node answers with, so an
+    expression built out of others is bound as the thing it became rather
+    than as the thing it was constructed with.
+    """
+    if isinstance(value, Expression):
+        _require_compatible(expected, expression_family(value.node))
+        return value.node
+    family = family_for_value(value)
+    _require_compatible(expected, family)
+    return BoundValueNode(value, family)
+
+
+def family_for_value(value: object) -> ScalarFamily:
+    if value is None:
+        return ScalarFamily.NULL
+    if isinstance(value, bool):
+        return ScalarFamily.BOOLEAN
+    if isinstance(value, (int, float, Decimal)):
+        return ScalarFamily.NUMERIC
+    if isinstance(value, str):
+        return ScalarFamily.STRING
+    if isinstance(value, bytes):
+        return ScalarFamily.BINARY
+    if isinstance(value, (date, time, timedelta)):
+        return ScalarFamily.TEMPORAL
+    if isinstance(value, (list, dict)):
+        return ScalarFamily.JSON
+    return ScalarFamily.OTHER
+
+
+def _require_compatible(expected: ScalarFamily, actual: ScalarFamily) -> None:
+    if actual is ScalarFamily.NULL or expected is ScalarFamily.OTHER:
+        return
+    json_families = {
+        ScalarFamily.BOOLEAN,
+        ScalarFamily.JSON,
+        ScalarFamily.NUMERIC,
+        ScalarFamily.STRING,
+    }
+    if expected is ScalarFamily.JSON and actual in json_families:
+        return
+    if actual is expected:
+        return
+    message = f"incompatible expression families: {expected.value} and {actual.value}"
+    raise ExpressionTypeError(message)
+
+
+def _require_family(actual: ScalarFamily, expected: ScalarFamily) -> None:
+    if actual is not expected:
+        message = f"operation requires {expected.value}, received {actual.value}"
+        raise ExpressionTypeError(message)
+
+
+def _require_ordered(family: ScalarFamily) -> None:
+    if family not in {ScalarFamily.NUMERIC, ScalarFamily.STRING, ScalarFamily.TEMPORAL}:
+        message = f"operation requires an ordered expression, received {family.value}"
+        raise ExpressionTypeError(message)
+
+
+def _combine(
+    operator: VariadicOperator,
+    left: ExpressionNode,
+    right: ExpressionNode,
+) -> VariadicNode:
+    left_operands = (
+        left.operands
+        if isinstance(left, VariadicNode) and left.operator is operator
+        else (left,)
+    )
+    right_operands = (
+        right.operands
+        if isinstance(right, VariadicNode) and right.operator is operator
+        else (right,)
+    )
+    return VariadicNode(operator, (*left_operands, *right_operands))
+
+
+__all__ = (
+    "ComputedExpression",
+    "Condition",
+    "Expression",
+    "family_for_value",
+    "operand",
+    "require_boolean",
+)