mirror of https://github.com/clockworklabs/SpacetimeDB.git synced 2026-05-13 11:17:50 -04:00

Files

T

History

Ryan 8a0cd87c4f Adds datastore_index_scan_point_bsatn to C# Runtime (#3909 )

# Description of Changes

To resolve #3875, we added exact-match unique index point lookup support
to the C# bindings by introducing and using
`datastore_index_scan_point_bsatn`.

Previously, generated unique index `Find()` was (in at least one
codepath) implemented as:

* A range scan (`datastore_index_scan_range_bsatn`) over a BTree bound,
then
* `SingleOrDefault()` to collapse the results into a single row.
When the scan is empty, `SingleOrDefault()` returns `default(T)`. For
value-type rows this can manifest as a default-initialized row instead
of “missing”, which is what surfaced as “default-ish row” behavior in
views.

Using `datastore_index_scan_point_bsatn` makes the C# implementation
match Rust semantics more closely by performing an exact point lookup
and returning:

* `null` when no rows are found
* the row when exactly one row is found
* (defensively) an error if >1 row is returned (unique index invariant
violation)
Similarly, `datastore_delete_by_index_scan_point_bsatn` was added and
used so deletes-by-unique-key are also exact-match point operations
rather than range deletes.

Runtime updates were made to utilize point scan in `FindSingle(key)` and
in both mutable/read-only unique-index paths.

To keep this non-breaking for existing modules, codegen now detects
whether the table row is a struct or a class and chooses the appropriate
base type:
* Struct rows: `Find()` returns `Row?` (`Nullable<Row>`).
* Class rows: `Find()` returns `Row?` (nullable reference, `null` on
miss).

# API and ABI breaking changes

This change is non-breaking with respect to row type kinds, because
class/record table rows continue to work via
RefUniqueIndex/ReadOnlyRefUniqueIndex while struct rows use
UniqueIndex/ReadOnlyUniqueIndex.

API surface changes:
* Generated `Find()` return type is now nullable (`Row?`) to correctly
represent “missing”.

ABI/runtime:
* Requires the point-scan hostcall import
(`datastore_index_scan_point_bsatn`) to be available; the runtime uses
point-scan for unique lookup (and point delete for unique delete).

# Expected complexity level and risk

Low 2

# Testing

- [X] Local testing: repro module + client validate view and direct
Find() behavior

---------

Signed-off-by: rekhoff <r.ekhoff@clockworklabs.io>

2025-12-20 00:32:37 +00:00

Codegen.csproj

C# implementation of Transactions for Procedures (#3809 )

2025-12-18 18:41:47 +00:00

Diag.cs

C# module bindings for Procedures (#3732 )

2025-11-25 16:50:54 +00:00

Module.cs

Adds datastore_index_scan_point_bsatn to C# Runtime (#3909 )

2025-12-20 00:32:37 +00:00

README.md

SATS: Flatten AlgebraicType, getting rid of BuiltinType (#1559 )

2024-08-06 18:15:19 +00:00

README.md

SpacetimeDB.Codegen

This project contains Roslyn incremental source generators that augment types and tables with static methods for self-describing and registration. They look for different attributes to know which types to augment:

[SpacetimeDB.Type] - generates a GetSatsTypeInfo() static method that registers this type with the runtime and returns a TypeInfo object. It supports only structs for now to explicitly forbid infinitely recursive types and to make the implementation simpler, as it doesn't need to deal with type references - each table is registered as an entirely self-contained type together with its nested structs if any. This is unlikely to be a problem in common scenarios, but it will be optimised in the future.

All the nested fields will be added to the product type. Because it's not possible to implement static extension methods on 3rd-party types (including built-ins) in C#, the codegen is responsible for manually routing different types to their TypeInfo descriptors. See various static TypeInfo properties and helper methods on SpacetimeDB.BSATN.AlgebraicType (Runtime/AlgebraicType.cs) and routing logic in Utils.GetTypeInfo (Codegen/Utils.cs) for more details.

Also, for the same reason - absence of static extension methods in C# - the codegen expects that your struct, as well as any of its parents, is partial so methods can be added from extra source files generated by the codegen.
[SpacetimeDB.Type] - also supports emulation of tagged enums in C#. For that, the struct needs to inherit a marker interface SpacetimeDB.TaggedEnum<Variants> where Variants is a named tuple of all possible variants, e.g.:
```
[SpacetimeDB.Type]
partial record Option<T> : SpacetimeDB.TaggedEnum<(T Some, Unit None)>;
```
will generate inherited records Option.Some(T Some_) and Option.None(Unit None_). It allows you to use tagged enums in C# in a similar way to Rust enums by leveraging C# pattern-matching on any instance of Option<T>.
[SpacetimeDB.Table] - generates code to register this table in the FFI upon startup so that they can be enumerated by the __describe_module__ FFI API. It implies [SpacetimeDB.Type], so you must not specify both attributes on the same struct.

The fields can be marked with [SpacetimeDB.ColumnAttrs] and those will be detected by the codegen and passed on to the runtime as well. Example:
```
[SpacetimeDB.Table]
public partial struct Person
{
    [SpacetimeDB.Column(ColumnAttrs.Identity)]
    public int Id;
    public string Name;
}
```
[SpacetimeDB.Reducer] - generates code to register a static function as a SpacetimeDB reducer in the FFI upon startup and creates a wrapper that will parse SATS binary blob into individual arguments and invoke the underlying function for the __call_reducer__ FFI API.