Standardize query builder syntax across Rust, TypeScript, and C# (Server/Client) (#4261)

# Description of Changes

Standardizes the query builder API across all three language SDKs (Rust,
TypeScript, C#) for consistency.

**Rust:**
- Rename `Query` struct to `RawQuery`, make `Query` a trait with `fn
into_sql(self) -> String`
- All builder types (`Table`, `FromWhere`, `LeftSemiJoin`,
`RightSemiJoin`) implement `Query<T>` trait
- Views can return `-> impl Query<T>` instead of specifying exact
builder types
- The `#[view]` macro auto-detects `impl Query<T>` and rewrites to
`RawQuery<T>`
- Add `Not` variant to `BoolExpr` with `.not()` method

**TypeScript:**
- Add `ne()` to `ColumnExpression`
- Refactor `BooleanExpr` to `BoolExpr` class with chainable `.and()`,
`.or()`, `.not()` methods
- Make builders valid queries directly (`.build()` deprecated but still
works)
- Deprecate `from()` wrapper — use `tables.person.where(...)` directly
- Merge `query` export into `tables` so table refs are also query
builders
- Add subscription callback form: `subscribe(ctx =>
ctx.from.person.where(...))`
- Unify `useTable` with query builder syntax; deprecate `filter.ts`

**C#:**
- Add `Not()` method to `BoolExpr<TRow>`
- Add `IQuery<TRow>` interface implemented by all builder types
(`Table`, `FromWhere`, `LeftSemiJoin`, `RightSemiJoin`, `Query`)
- Add `ToSql()` to all builder types so `.Build()` is no longer required
- Update `AddQuery` to accept `IQuery<TRow>` instead of `Query<TRow>`

# API and ABI breaking changes

- Rust: `Query<T>` is now a trait (was a struct). The struct is renamed
to `RawQuery<T>`. This is a breaking change for any code that used
`Query<T>` as a type directly.
- TypeScript: `BooleanExpr` is now a `BoolExpr` class (was a
discriminated union type). The `query` export is deprecated in favor of
`tables`.
- C#: `AddQuery` now accepts `Func<QueryBuilder, IQuery<TRow>>` instead
of `Func<QueryBuilder, Query<TRow>>`. Existing `.Build()` calls still
work since `Query<TRow>` implements `IQuery<TRow>`.

# Expected complexity level and risk

3 — Changes touch multiple language SDKs and codegen, but each
individual change is straightforward. The Rust macro rewrite for `impl
Query<T>` detection is the most complex piece. All existing
`.build()`/`.Build()` calls continue to work.

# Testing

- [x] `cargo test -p spacetimedb-query-builder` — 16/16 tests pass
- [x] `cargo check -p spacetimedb` — clean, no warnings
- [x] `cargo check` on views-query, views-sql, views-basic,
views-trapped smoketest modules — all clean
- [x] `cargo test -p spacetimedb-codegen codegen_csharp` — snapshot
updated, passes
- [x] `npm test` (TypeScript) — 101/101 tests pass
- [x] C# QueryBuilder tests — new tests for `Not()`, `IQuery<T>`
interface
- [ ] CI passes

Author: cloutiertyler

crates/bindings-csharp/BSATN.Runtime/QueryBuilder.cs

@@ -60,7 +60,12 @@ public static SqlLiteral<Uuid> Uuid(Uuid value) =>
         new(SqlFormat.FormatHexLiteral(value.ToString()));
 }
 
-public readonly struct Query<TRow>
+public interface IQuery<TRow>
+{
+    string ToSql();
+}
+
+public readonly struct Query<TRow> : IQuery<TRow>
 {
     public string Sql { get; }
 
@@ -87,6 +92,8 @@ public BoolExpr(string sql)
 
     public BoolExpr<TRow> Or(BoolExpr<TRow> other) => new($"({Sql} OR {other.Sql})");
 
+    public BoolExpr<TRow> Not() => new($"(NOT {Sql})");
+
     public override string ToString() => Sql;
 }
 
@@ -247,7 +254,7 @@ public IxJoinEq<TRow, TOtherRow> Eq<TOtherRow>(NullableIxCol<TOtherRow, TValue>
     public override string ToString() => RefSql;
 }
 
-public sealed class Table<TRow, TCols, TIxCols>
+public sealed class Table<TRow, TCols, TIxCols> : IQuery<TRow>
 {
     private readonly string tableName;
     private readonly TCols cols;
@@ -301,7 +308,7 @@ Func<TIxCols, TRightIxCols, IxJoinEq<TRow, TRightRow>> on
     ) => new(this, right, on(ixCols, right.ixCols), leftWhereExpr: null);
 }
 
-public sealed class FromWhere<TRow, TCols, TIxCols>
+public sealed class FromWhere<TRow, TCols, TIxCols> : IQuery<TRow>
 {
     private readonly Table<TRow, TCols, TIxCols> table;
     private readonly BoolExpr<TRow> expr;
@@ -324,7 +331,9 @@ public FromWhere<TRow, TCols, TIxCols> Filter(Func<TCols, BoolExpr<TRow>> predic
     public FromWhere<TRow, TCols, TIxCols> Filter(Func<TCols, TIxCols, BoolExpr<TRow>> predicate) =>
         Where(predicate);
 
-    public Query<TRow> Build() => new($"{table.ToSql()} WHERE {expr.Sql}");
+    public string ToSql() => $"{table.ToSql()} WHERE {expr.Sql}";
+
+    public Query<TRow> Build() => new(ToSql());
 
     public LeftSemiJoin<TRow, TCols, TIxCols, TRightRow, TRightCols, TRightIxCols> LeftSemijoin<
         TRightRow,
@@ -352,7 +361,7 @@ public sealed class LeftSemiJoin<
     TRightRow,
     TRightCols,
     TRightIxCols
->
+> : IQuery<TLeftRow>
 {
     private readonly Table<TLeftRow, TLeftCols, TLeftIxCols> left;
     private readonly Table<TRightRow, TRightCols, TRightIxCols> right;
@@ -430,13 +439,13 @@ public LeftSemiJoin<
         TRightIxCols
     > Filter(Func<TLeftCols, TLeftIxCols, BoolExpr<TLeftRow>> predicate) => Where(predicate);
 
-    public Query<TLeftRow> Build()
+    public string ToSql()
     {
         var whereClause = whereExpr.HasValue ? $" WHERE {whereExpr.Value.Sql}" : string.Empty;
-        return new(
-            $"SELECT {left.TableRefSql}.* FROM {left.TableRefSql} JOIN {right.TableRefSql} ON {leftJoinRefSql} = {rightJoinRefSql}{whereClause}"
-        );
+        return $"SELECT {left.TableRefSql}.* FROM {left.TableRefSql} JOIN {right.TableRefSql} ON {leftJoinRefSql} = {rightJoinRefSql}{whereClause}";
     }
+
+    public Query<TLeftRow> Build() => new(ToSql());
 }
 
 public sealed class RightSemiJoin<
@@ -446,7 +455,7 @@ public sealed class RightSemiJoin<
     TRightRow,
     TRightCols,
     TRightIxCols
->
+> : IQuery<TRightRow>
 {
     private readonly Table<TLeftRow, TLeftCols, TLeftIxCols> left;
     private readonly Table<TRightRow, TRightCols, TRightIxCols> right;
@@ -541,7 +550,7 @@ public RightSemiJoin<
         TRightIxCols
     > Filter(Func<TRightCols, TRightIxCols, BoolExpr<TRightRow>> predicate) => Where(predicate);
 
-    public Query<TRightRow> Build()
+    public string ToSql()
     {
         var whereClause = string.Empty;
 
@@ -558,10 +567,10 @@ public Query<TRightRow> Build()
             whereClause = $" WHERE {rightWhereExpr.Value.Sql}";
         }
 
-        return new(
-            $"SELECT {right.TableRefSql}.* FROM {left.TableRefSql} JOIN {right.TableRefSql} ON {leftJoinRefSql} = {rightJoinRefSql}{whereClause}"
-        );
+        return $"SELECT {right.TableRefSql}.* FROM {left.TableRefSql} JOIN {right.TableRefSql} ON {leftJoinRefSql} = {rightJoinRefSql}{whereClause}";
     }
+
+    public Query<TRightRow> Build() => new(ToSql());
 }
 
 public static class QueryBuilderExtensions

crates/bindings-macro/src/lib.rs

@@ -125,10 +125,19 @@ pub fn reducer(args: StdTokenStream, item: StdTokenStream) -> StdTokenStream {
 
 #[proc_macro_attribute]
 pub fn view(args: StdTokenStream, item: StdTokenStream) -> StdTokenStream {
-    cvt_attr::<ItemFn>(args, item, quote!(), |args, original_function| {
-        let args = view::ViewArgs::parse(args, &original_function.sig.ident)?;
-        view::view_impl(args, original_function)
-    })
+    let item_ts: TokenStream = item.into();
+    let original_function = match syn::parse2::<ItemFn>(item_ts.clone()) {
+        Ok(f) => f,
+        Err(e) => return TokenStream::from_iter([item_ts, e.into_compile_error()]).into(),
+    };
+    let args = match view::ViewArgs::parse(args.into(), &original_function.sig.ident) {
+        Ok(a) => a,
+        Err(e) => return TokenStream::from_iter([item_ts, e.into_compile_error()]).into(),
+    };
+    match view::view_impl(args, &original_function) {
+        Ok(ts) => ts.into(),
+        Err(e) => TokenStream::from_iter([item_ts, e.into_compile_error()]).into(),
+    }
 }
 
 /// It turns out to be shockingly difficult to construct an [`Attribute`].

crates/bindings-macro/src/view.rs

@@ -46,6 +46,26 @@ impl ViewArgs {
     }
 }
 
+/// If `ty` is `impl Query<T>`, returns `Some(T)`. Otherwise `None`.
+fn extract_impl_query_inner(ty: &syn::Type) -> Option<&syn::Type> {
+    if let syn::Type::ImplTrait(impl_trait) = ty {
+        for bound in &impl_trait.bounds {
+            if let syn::TypeParamBound::Trait(trait_bound) = bound {
+                if let Some(seg) = trait_bound.path.segments.last() {
+                    if seg.ident == "Query" {
+                        if let syn::PathArguments::AngleBracketed(args) = &seg.arguments {
+                            if let Some(syn::GenericArgument::Type(inner)) = args.args.first() {
+                                return Some(inner);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    None
+}
+
 pub(crate) fn view_impl(args: ViewArgs, original_function: &ItemFn) -> syn::Result<TokenStream> {
     let vis = &original_function.vis;
     let func_name = &original_function.sig.ident;
@@ -137,7 +157,61 @@ pub(crate) fn view_impl(args: ViewArgs, original_function: &ItemFn) -> syn::Resu
         }
     };
 
+    let original_attrs = &original_function.attrs;
+    let original_body = &original_function.block;
+
+    // Detect `impl Query<T>` return type and extract `T`.
+    let impl_query_inner = extract_impl_query_inner(ret_ty);
+
+    // When the return type is `impl Query<T>`:
+    //   - Rewrite the function to return `RawQuery<T>`
+    //   - Wrap the body: `RawQuery::new(Query::into_sql({ body }))`
+    //   - Use `RawQuery<T>` for SpacetimeType/ViewReturn assertions
+    // When the return type is `RawQuery<T>` (concrete query struct):
+    //   - Wrap with `.into()` so builder types auto-convert
+    // Otherwise (Vec<T>, Option<T>):
+    //   - Emit unchanged to preserve type inference
+    let (emitted_fn, effective_ret_ty) = if let Some(inner_ty) = impl_query_inner {
+        let original_sig = &original_function.sig;
+        // Build a new signature with the return type replaced
+        let mut new_sig = original_sig.clone();
+        new_sig.output = syn::parse_quote!(-> spacetimedb::RawQuery<#inner_ty>);
+        let effective_ty: syn::Type = syn::parse_quote!(spacetimedb::RawQuery<#inner_ty>);
+        (
+            quote! {
+                #(#original_attrs)*
+                #new_sig {
+                    spacetimedb::RawQuery::new(
+                        Query::into_sql(#original_body)
+                    )
+                }
+            },
+            effective_ty,
+        )
+    } else {
+        let original_sig = &original_function.sig;
+        let returns_raw_query =
+            matches!(ret_ty, syn::Type::Path(p) if p.path.segments.last().is_some_and(|s| s.ident == "RawQuery"));
+        let emitted_body = if returns_raw_query {
+            quote! { { ::core::convert::Into::into(#original_body) } }
+        } else {
+            quote! { #original_body }
+        };
+        (
+            quote! {
+                #(#original_attrs)*
+                #original_sig
+                    #emitted_body
+            },
+            ret_ty.clone(),
+        )
+    };
+
+    let eff_ret_ty = &effective_ret_ty;
+
     Ok(quote! {
+        #emitted_fn
+
         const _: () = { #generated_describe_function };
 
         #[allow(non_camel_case_types)]
@@ -146,7 +220,7 @@ pub(crate) fn view_impl(args: ViewArgs, original_function: &ItemFn) -> syn::Resu
         const _: () = {
             fn _assert_args #lt_params () #lt_where_clause {
                 let _ = <#ctx_ty as spacetimedb::rt::ViewContextArg>::_ITEM;
-                let _ = <#ret_ty as spacetimedb::rt::ViewReturn>::_ITEM;
+                let _ = <#eff_ret_ty as spacetimedb::rt::ViewReturn>::_ITEM;
             }
         };
 
@@ -183,7 +257,7 @@ pub(crate) fn view_impl(args: ViewArgs, original_function: &ItemFn) -> syn::Resu
             fn return_type(
                 ts: &mut impl spacetimedb::sats::typespace::TypespaceBuilder
             ) -> Option<spacetimedb::sats::AlgebraicType> {
-                Some(<#ret_ty as spacetimedb::SpacetimeType>::make_type(ts))
+                Some(<#eff_ret_ty as spacetimedb::SpacetimeType>::make_type(ts))
             }
         }
     })

crates/bindings-typescript/package.json

@@ -29,6 +29,7 @@
     "format": "prettier . --write --ignore-path ../../.prettierignore",
     "lint": "eslint . && prettier . --check --ignore-path ../../.prettierignore",
     "test": "vitest run",
+    "test:typecheck": "vitest typecheck --run",
     "coverage": "vitest run --coverage",
     "brotli-size": "brotli-size dist/index.js",
     "size": "pnpm -s build && size-limit",