zeroshot-sql-decorators 0.1.5__tar.gz

zeroshot_sql_decorators-0.1.5/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: zeroshot-sql-decorators
+Version: 0.1.5
+Summary: SQL-focused decorators and helpers for Zeroshot Python packages.
+License-Expression: MIT
+Requires-Dist: zeroshot-commons==0.1.5
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: asyncpg>=0.30
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# zeroshot-sql-decorators
+
+SQL-focused decorators and helpers for Zeroshot Python packages.

zeroshot_sql_decorators-0.1.5/README.md

@@ -0,0 +1,3 @@
+# zeroshot-sql-decorators
+
+SQL-focused decorators and helpers for Zeroshot Python packages.

zeroshot_sql_decorators-0.1.5/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "zeroshot-sql-decorators"
+version = "0.1.5"
+description = "SQL-focused decorators and helpers for Zeroshot Python packages."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = [
+  "zeroshot-commons==0.1.5",
+  "sqlalchemy[asyncio]>=2.0",
+  "asyncpg>=0.30",
+]
+
+[tool.uv.sources]
+zeroshot-commons = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12"]
+build-backend = "uv_build"

zeroshot_sql_decorators-0.1.5/src/zeroshot_sql_decorators/__init__.py

@@ -0,0 +1,39 @@
+"""SQL-focused decorators and helpers for Zeroshot Python packages."""
+
+from .decorators import (
+    DaoBase,
+    TransactionalityBase,
+    dao,
+    sql_query,
+    sql_transaction,
+    stream_select,
+    with_transactionality,
+)
+from .stream_iterator import StreamIterator
+from .types import (
+    ArrayResult,
+    BooleanResult,
+    NumberResult,
+    QueryOptions,
+    QueryType,
+    StreamSelectOptions,
+    StringResult,
+)
+
+__all__ = [
+    "ArrayResult",
+    "BooleanResult",
+    "DaoBase",
+    "NumberResult",
+    "QueryOptions",
+    "QueryType",
+    "StreamIterator",
+    "StreamSelectOptions",
+    "StringResult",
+    "TransactionalityBase",
+    "dao",
+    "sql_query",
+    "sql_transaction",
+    "stream_select",
+    "with_transactionality",
+]

zeroshot_sql_decorators-0.1.5/src/zeroshot_sql_decorators/decorators.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
+
+from .param_mapper import build_replacements, expand_in_clauses, extract_param_names
+from .query import load_query
+from .result_mapper import map_result
+from .stream_iterator import StreamIterator
+from .types import QueryOptions, StreamSelectOptions
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Base classes
+# ---------------------------------------------------------------------------
+
+
+class DaoBase:
+    """Base class for Data Access Objects.
+
+    Holds a reference to the SQLAlchemy ``AsyncEngine``.
+    """
+
+    def __init__(self, engine: AsyncEngine) -> None:
+        self._engine = engine
+
+
+class TransactionalityBase:
+    """Base class for repositories that coordinate transactions across DAOs."""
+
+    def __init__(self, engine: AsyncEngine) -> None:
+        self._engine = engine
+
+
+# ---------------------------------------------------------------------------
+# Class decorators
+# ---------------------------------------------------------------------------
+
+
+def dao(*, query_directory: Path | str | None = None) -> Any:
+    """Mark a class as a DAO with an optional query file directory."""
+
+    def decorator(cls: type) -> type:
+        cls._query_directory = Path(query_directory) if query_directory else None  # type: ignore[attr-defined]
+        return cls
+
+    return decorator
+
+
+def with_transactionality() -> Any:
+    """Mark a class as transaction-aware (mirrors TS ``@WithTransactionality()``)."""
+
+    def decorator(cls: type) -> type:
+        return cls
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# @sql_query
+# ---------------------------------------------------------------------------
+
+
+def sql_query(options: QueryOptions) -> Any:
+    """Method decorator that executes a SQL query and maps the result.
+
+    The decorated method becomes a stub — its body is never called.
+    Parameters are extracted from the function signature and bound to the query.
+    An optional ``session: AsyncSession | None = None`` parameter enables
+    transaction participation.
+    """
+
+    def decorator(fn: Any) -> Any:
+        param_names = extract_param_names(fn)
+
+        @functools.wraps(fn)
+        async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            engine: AsyncEngine = self._engine
+
+            # Resolve query directory
+            query_dir: Path | None = getattr(self.__class__, "_query_directory", None)
+
+            sql = load_query(
+                inline_query=options.query,
+                file_path=options.file,
+                query_directory=query_dir,
+                class_name=self.__class__.__name__,
+                method_name=fn.__name__,
+            )
+
+            # Build all args (positional + keyword), excluding self
+            all_args = _merge_args(fn, args, kwargs)
+            replacements = build_replacements(param_names, all_args)
+
+            # Expand IN clauses for list parameters
+            expanded_sql, expanded_params = expand_in_clauses(sql, replacements)
+
+            # Check for an explicit session argument
+            session = _extract_session(fn, args, kwargs)
+
+            if session is not None:
+                result = await session.execute(text(expanded_sql), expanded_params)
+                try:
+                    rows: list[Any] = [dict(r) for r in result.mappings().all()]
+                except Exception:
+                    rows = []
+            else:
+                async with engine.connect() as conn:
+                    result = await conn.execute(text(expanded_sql), expanded_params)
+                    try:
+                        rows = [dict(r) for r in result.mappings().all()]
+                    except Exception:
+                        rows = []
+                    await conn.commit()
+
+            return map_result(rows, options.query_type, options.clazz, options.return_list)
+
+        return wrapper
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# @stream_select
+# ---------------------------------------------------------------------------
+
+
+def stream_select(options: StreamSelectOptions) -> Any:
+    """Method decorator that returns a ``StreamIterator`` for lazy batch iteration."""
+
+    def decorator(fn: Any) -> Any:
+        param_names = extract_param_names(fn)
+
+        @functools.wraps(fn)
+        def wrapper(self: Any, *args: Any, **kwargs: Any) -> StreamIterator[Any]:
+            engine: AsyncEngine = self._engine
+            query_dir: Path | None = getattr(self.__class__, "_query_directory", None)
+
+            sql = load_query(
+                inline_query=options.query,
+                file_path=options.file,
+                query_directory=query_dir,
+                class_name=self.__class__.__name__,
+                method_name=fn.__name__,
+            )
+
+            all_args = _merge_args(fn, args, kwargs)
+            replacements = build_replacements(param_names, all_args)
+
+            return StreamIterator(
+                engine=engine,
+                sql=sql,
+                replacements=replacements,
+                clazz=options.clazz,
+                batch_size=options.batch_size,
+            )
+
+        return wrapper
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# @sql_transaction
+# ---------------------------------------------------------------------------
+
+
+def sql_transaction(
+    *,
+    isolation_level: str | None = None,
+) -> Any:
+    """Method decorator that wraps the call in a database transaction.
+
+    If a ``session`` kwarg/arg is already provided and has an active
+    transaction, the method participates in that transaction.
+    Otherwise a new transaction is created, committed on success,
+    and rolled back on error.
+    """
+
+    def decorator(fn: Any) -> Any:
+        @functools.wraps(fn)
+        async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            engine: AsyncEngine = self._engine
+
+            existing_session = _extract_session(fn, args, kwargs)
+
+            if existing_session is not None and existing_session.in_transaction():
+                # Already in a transaction — just call through
+                return await fn(self, *args, **kwargs)
+
+            if existing_session is not None:
+                raise ValueError(
+                    "A session was provided but has no active transaction. "
+                    "Do not pass a session unless it is already transactional."
+                )
+
+            # Create a new session + transaction
+            exec_opts: dict[str, Any] = {}
+            if isolation_level:
+                exec_opts["isolation_level"] = isolation_level
+
+            session_factory = async_sessionmaker(
+                engine,
+                expire_on_commit=False,
+            )
+            async with session_factory.begin() as session:
+                if exec_opts:
+                    await session.connection(execution_options=exec_opts)
+                new_kwargs = dict(kwargs)
+                new_kwargs["session"] = session
+                return await fn(self, *args, **new_kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _merge_args(fn: Any, args: tuple[Any, ...], kwargs: dict[str, Any]) -> tuple[Any, ...]:
+    """Merge positional and keyword args into a positional tuple,
+    respecting the original function signature order (excluding ``self``)."""
+    sig = inspect.signature(fn)
+    params = [p for p in sig.parameters.values() if p.name != "self"]
+
+    merged: list[Any] = list(args)
+
+    # Fill in remaining params from kwargs
+    for i in range(len(args), len(params)):
+        p = params[i]
+        if p.name in kwargs:
+            merged.append(kwargs[p.name])
+        elif p.default is not inspect.Parameter.empty:
+            merged.append(p.default)
+
+    return tuple(merged)
+
+
+def _extract_session(
+    fn: Any,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> AsyncSession | None:
+    """Pull out the ``session`` argument if present."""
+    if "session" in kwargs:
+        return kwargs["session"]
+
+    sig = inspect.signature(fn)
+    params = [p for p in sig.parameters.values() if p.name != "self"]
+
+    for i, p in enumerate(params):
+        if p.name == "session" and i < len(args):
+            val = args[i]
+            if isinstance(val, AsyncSession):
+                return val
+
+    return None

zeroshot_sql_decorators-0.1.5/src/zeroshot_sql_decorators/param_mapper.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import dataclasses
+import inspect
+import re
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+def extract_param_names(func: Any) -> list[str]:
+    """Get parameter names from a function, excluding ``self`` and ``session``."""
+    sig = inspect.signature(func)
+    return [
+        name
+        for name, param in sig.parameters.items()
+        if (name not in ("self", "session") and param.default is not inspect.Parameter.empty)
+        or (
+            param.kind
+            in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.POSITIONAL_ONLY)
+            and name not in ("self", "session")
+        )
+    ]
+
+
+def _is_complex(value: Any) -> bool:
+    """Return True if *value* is a dataclass instance or has a ``__dict__``
+    that is not a basic built-in type."""
+    if value is None or isinstance(value, (str, int, float, bool, bytes, list, tuple)):
+        return False
+    return dataclasses.is_dataclass(value) and not isinstance(value, type)
+
+
+def _extract_fields(obj: Any) -> dict[str, Any]:
+    """Pull fields from a dataclass instance, including property getters."""
+    result: dict[str, Any] = {}
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        for f in dataclasses.fields(obj):
+            result[f.name] = getattr(obj, f.name)
+        # Also pick up @property descriptors on the class
+        for name in dir(type(obj)):
+            if name.startswith("_"):
+                continue
+            attr = getattr(type(obj), name, None)
+            if isinstance(attr, property):
+                result[name] = attr.fget(obj)  # type: ignore[arg-type]
+    return result
+
+
+def build_replacements(
+    param_names: list[str],
+    args: tuple[Any, ...],
+) -> dict[str, Any]:
+    """Map function arguments to SQL ``:param`` replacements.
+
+    Rules (mirroring the TS implementation):
+    * Filter out any ``AsyncSession`` values (transaction arg).
+    * Single complex arg → spread its fields as parameters.
+    * Multiple args → map each name to its value.
+    * ``None`` values stay as ``None`` (SQL ``NULL``).
+    """
+    # Pair up names with values, skip sessions
+    pairs: list[tuple[str, Any]] = []
+    for name, value in zip(param_names, args, strict=False):
+        if isinstance(value, AsyncSession):
+            continue
+        pairs.append((name, value))
+
+    if len(pairs) == 1 and _is_complex(pairs[0][1]):
+        return _replace_none(_extract_fields(pairs[0][1]))
+
+    replacements: dict[str, Any] = {}
+    for name, value in pairs:
+        if _is_complex(value):
+            replacements.update(_extract_fields(value))
+        else:
+            replacements[name] = value
+
+    return _replace_none(replacements)
+
+
+def _replace_none(d: dict[str, Any]) -> dict[str, Any]:
+    """Ensure ``None`` values remain as-is (SQLAlchemy handles NULL binding)."""
+    return d
+
+
+# ---------------------------------------------------------------------------
+# IN-clause expansion
+# ---------------------------------------------------------------------------
+
+_IN_PARAM_RE = re.compile(r":(\w+)")
+
+
+def _param_is_in_clause(sql: str, key: str) -> bool:
+    """Check if ``:key`` appears inside an ``IN (...)`` context in the SQL."""
+    pattern = re.compile(rf"IN\s*\([^)]*:{re.escape(key)}(?!\w)[^)]*\)", re.IGNORECASE)
+    return pattern.search(sql) is not None
+
+
+def _param_is_null_check(sql: str, key: str) -> bool:
+    """Check if ``:key IS NULL`` appears in the SQL."""
+    pattern = re.compile(rf":{re.escape(key)}\s+IS\s+NULL", re.IGNORECASE)
+    return pattern.search(sql) is not None
+
+
+def expand_in_clauses(sql: str, replacements: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    """Expand list-valued parameters for ``IN (:param)`` clauses.
+
+    Given ``IN (:ids)`` and ``ids=[1, 2, 3]``, rewrites to
+    ``IN (:ids_0, :ids_1, :ids_2)`` with individual entries in replacements.
+
+    List parameters that appear outside of IN clauses (e.g. PostgreSQL array
+    values) are left as-is.
+
+    Also handles the ``(:param IS NULL OR ... IN (:param))`` pattern.
+    """
+    expanded: dict[str, Any] = {}
+    new_sql = sql
+
+    for key, value in list(replacements.items()):
+        has_in = _param_is_in_clause(new_sql, key)
+        has_is_null = _param_is_null_check(new_sql, key)
+
+        if value is None and has_is_null:
+            # None means "skip this filter"
+            _is_null_pat = re.compile(rf":{re.escape(key)}\s+IS\s+NULL", re.IGNORECASE)
+            new_sql = _is_null_pat.sub("TRUE", new_sql)
+            if has_in:
+                _in_pat = re.compile(rf"IN\s*\(\s*:{re.escape(key)}\s*\)", re.IGNORECASE)
+                new_sql = _in_pat.sub("IN (NULL)", new_sql)
+            continue
+
+        if not isinstance(value, (list, tuple)):
+            expanded[key] = value
+            continue
+
+        # List value but NOT used in an IN clause — it's a PostgreSQL array param
+        if not has_in:
+            expanded[key] = value
+            continue
+
+        # --- list/tuple in an IN clause ---
+
+        # Handle ":key IS NULL" patterns
+        if has_is_null:
+            _is_null_pat = re.compile(rf":{re.escape(key)}\s+IS\s+NULL", re.IGNORECASE)
+            new_sql = _is_null_pat.sub("FALSE", new_sql)
+
+        if len(value) == 0:
+            _in_pat = re.compile(rf"IN\s*\(\s*:{re.escape(key)}\s*\)", re.IGNORECASE)
+            new_sql = _in_pat.sub("IN (NULL)", new_sql)
+            continue
+
+        # Build individual param names
+        param_names = [f"{key}_{i}" for i in range(len(value))]
+        placeholders = ", ".join(f":{name}" for name in param_names)
+
+        # Only replace :key references inside IN clauses
+        _in_content_pat = re.compile(
+            rf"(IN\s*\([^)]*):{re.escape(key)}(?!\w)([^)]*\))", re.IGNORECASE
+        )
+        new_sql = _in_content_pat.sub(rf"\g<1>{placeholders}\g<2>", new_sql)
+
+        for pname, val in zip(param_names, value, strict=False):
+            expanded[pname] = val
+
+    return new_sql, expanded

zeroshot_sql_decorators-0.1.5/src/zeroshot_sql_decorators/py.typed

@@ -0,0 +1 @@
+

zeroshot_sql_decorators-0.1.5/src/zeroshot_sql_decorators/query.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+_query_cache: dict[str, str] = {}
+
+
+@dataclass(frozen=True, slots=True)
+class BatchingOptions:
+    limit: int
+    offset: int
+
+
+def load_query(
+    *,
+    inline_query: str | None,
+    file_path: str | None,
+    query_directory: Path | None,
+    class_name: str,
+    method_name: str,
+) -> str:
+    cache_key = f"{class_name}.{method_name}"
+    cached = _query_cache.get(cache_key)
+    if cached is not None:
+        return cached
+
+    if inline_query is not None:
+        _query_cache[cache_key] = inline_query
+        return inline_query
+
+    if file_path is not None:
+        resolved = Path(file_path)
+        if not resolved.is_absolute() and query_directory is not None:
+            resolved = query_directory / file_path
+    elif query_directory is not None:
+        resolved = query_directory / f"{method_name}.sql"
+    else:
+        raise ValueError(
+            f"{class_name}.{method_name}: no query, file, or query_directory specified"
+        )
+
+    if not resolved.exists():
+        raise FileNotFoundError(f"{class_name}.{method_name}: SQL file not found: {resolved}")
+
+    sql = resolved.read_text()
+    _query_cache[cache_key] = sql
+    return sql
+
+
+def apply_batching(sql: str, batching: BatchingOptions | None) -> str:
+    if batching is None:
+        return sql
+    return f"{sql.rstrip().rstrip(';')}\nLIMIT {batching.limit} OFFSET {batching.offset}"

zeroshot_sql_decorators-0.1.5/src/zeroshot_sql_decorators/result_mapper.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import dataclasses
+import json
+from collections.abc import Mapping, Sequence
+from decimal import Decimal
+from typing import Any
+
+from .types import QueryType
+
+
+def map_result(
+    rows: Sequence[Mapping[str, Any]],
+    query_type: QueryType,
+    clazz: type[Any] | None,
+    return_list: bool,
+) -> Any:
+    """Map raw database rows to the appropriate return shape."""
+    if query_type in (
+        QueryType.UPSERT,
+        QueryType.DELETE,
+        QueryType.BULK_UPDATE,
+        QueryType.BULK_DELETE,
+        QueryType.RAW,
+    ):
+        return None
+
+    if query_type == QueryType.SELECT:
+        return _map_select(rows, clazz, return_list)
+
+    if query_type in (QueryType.INSERT, QueryType.UPDATE):
+        return _map_returning(rows, clazz, return_list)
+
+    return None
+
+
+def _map_select(
+    rows: Sequence[Mapping[str, Any]],
+    clazz: type[Any] | None,
+    return_list: bool,
+) -> Any:
+    if return_list:
+        return [to_instance(dict(r), clazz) for r in rows]
+
+    if len(rows) == 0:
+        return None
+
+    if len(rows) > 1:
+        raise ValueError(
+            f"Expected 0 or 1 rows but got {len(rows)}. "
+            "Set return_list=True in QueryOptions to allow multiple rows."
+        )
+
+    return to_instance(dict(rows[0]), clazz)
+
+
+def _map_returning(
+    rows: Sequence[Mapping[str, Any]],
+    clazz: type[Any] | None,
+    return_list: bool,
+) -> Any:
+    if len(rows) == 0:
+        return None
+
+    if return_list:
+        return [to_instance(dict(r), clazz) for r in rows]
+
+    return to_instance(dict(rows[0]), clazz)
+
+
+def to_instance(row: dict[str, Any], clazz: type[Any] | None) -> Any:
+    """Convert a row dict to a class instance or cleaned dict."""
+    cleaned = _clean_row(row)
+
+    if clazz is None:
+        return cleaned
+
+    if dataclasses.is_dataclass(clazz):
+        field_names = {f.name for f in dataclasses.fields(clazz)}
+        filtered = {k: v for k, v in cleaned.items() if k in field_names}
+
+        # Handle nested dataclass fields (e.g. from json_agg)
+        for f in dataclasses.fields(clazz):
+            if f.name in filtered and filtered[f.name] is not None:
+                val = filtered[f.name]
+                # Check if the field type annotation hints at a list of dataclasses
+                origin = getattr(f.type, "__origin__", None)
+                if origin is list and isinstance(val, list):
+                    args = getattr(f.type, "__args__", ())
+                    if args and dataclasses.is_dataclass(args[0]):
+                        inner_cls = args[0]
+                        filtered[f.name] = [
+                            to_instance(item, inner_cls) if isinstance(item, dict) else item
+                            for item in val
+                        ]
+
+        return clazz(**filtered)
+
+    # Fallback: try to construct the class directly
+    return clazz(**cleaned)
+
+
+def _clean_row(row: dict[str, Any]) -> dict[str, Any]:
+    """Normalise database values: Decimal→float/int, JSON strings→objects."""
+    cleaned: dict[str, Any] = {}
+    for key, value in row.items():
+        if value is None:
+            cleaned[key] = None
+        elif isinstance(value, Decimal):
+            # Match TS behaviour: NUMERIC → float, BIGINT → int
+            if value == int(value):
+                cleaned[key] = int(value)
+            else:
+                cleaned[key] = float(value)
+        elif isinstance(value, str) and value.startswith("["):
+            try:
+                cleaned[key] = json.loads(value)
+            except (json.JSONDecodeError, ValueError):
+                cleaned[key] = value
+        else:
+            cleaned[key] = value
+    return cleaned

zeroshot_sql_decorators-0.1.5/src/zeroshot_sql_decorators/stream_iterator.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from .param_mapper import expand_in_clauses
+from .query import BatchingOptions, apply_batching
+from .result_mapper import to_instance
+
+
+class StreamIterator[T]:
+    """Lazily streams query results in batches, yielding one row at a time."""
+
+    def __init__(
+        self,
+        engine: AsyncEngine,
+        sql: str,
+        replacements: dict[str, Any],
+        clazz: type[T] | None = None,
+        batch_size: int = 1000,
+    ) -> None:
+        self._engine = engine
+        self._sql = sql
+        self._replacements = replacements
+        self._clazz = clazz
+        self._batch_size = batch_size
+
+    async def _generate(self) -> AsyncIterator[T]:
+        offset = 0
+        while True:
+            batching = BatchingOptions(limit=self._batch_size, offset=offset)
+            batch_sql = apply_batching(self._sql, batching)
+            expanded_sql, expanded_params = expand_in_clauses(batch_sql, self._replacements)
+
+            async with self._engine.connect() as conn:
+                result = await conn.execute(text(expanded_sql), expanded_params)
+                rows = result.mappings().all()
+
+            for row in rows:
+                instance = to_instance(dict(row), self._clazz)
+                yield instance
+
+            if len(rows) < self._batch_size:
+                break
+
+            offset += self._batch_size
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self._generate()

zeroshot_sql_decorators-0.1.5/src/zeroshot_sql_decorators/types.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from typing import Any
+
+
+class QueryType(enum.Enum):
+    SELECT = "SELECT"
+    INSERT = "INSERT"
+    UPDATE = "UPDATE"
+    DELETE = "DELETE"
+    UPSERT = "UPSERT"
+    BULK_UPDATE = "BULK_UPDATE"
+    BULK_DELETE = "BULK_DELETE"
+    RAW = "RAW"
+
+
+@dataclass(frozen=True, slots=True)
+class BooleanResult:
+    result: bool
+
+
+@dataclass(frozen=True, slots=True)
+class StringResult:
+    result: str
+
+
+@dataclass(frozen=True, slots=True)
+class NumberResult:
+    result: int | float
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayResult:
+    result: list[str]
+
+
+type Clazz[T] = type[T]
+
+
+@dataclass(frozen=True)
+class QueryOptions:
+    query_type: QueryType
+    clazz: type[Any] | None = None
+    return_list: bool = False
+    query: str | None = None
+    file: str | None = None
+
+
+@dataclass(frozen=True)
+class StreamSelectOptions:
+    clazz: type[Any] | None = None
+    batch_size: int = 1000
+    query: str | None = None
+    file: str | None = None