Skip to content

Conversation

@jsdt
Copy link
Contributor

@jsdt jsdt commented Dec 3, 2025

Description of Changes

This adds a way to build queries with typescript views, and it allows views to return queries (if the return type of the query is an array).

For examples and syntax, you can look at the tests in crates/bindings-typescript/tests/query.test.ts.

To play around with the syntax, you might find it easier to look in crates/bindings-typescript/src/server/view.test-d.ts.

This could still use some cleanup, and there are some places where the type safety is imperfect. I'll try to list the known limitations here:

  1. This will allow the use of eq for columns that are product types, even though the query engine doesn't support it. This can be fixed later, and it would only be a breaking change for modules that have invalid queries.
  2. When we check if a view is returning a query of the correct type, we are checking with the typescript row type. We should be checking with the spacetime type, since this type checking will allow a couple incorrect things to be returned:
    1. A different table with any superset of the fields (for example, a different table that has one extra field). That will fail when executing, but will be allowed by the typescript compiler.
    2. A table with the same fields, but with those fields in a different order would also fail at runtime, but be allowed by the typescript compiler.
    3. A table with fields of a different spacetimetype that map to the same typescript type (like u16 and u32).

API and ABI breaking changes

This adds some new API surface, but does not break existing code.

Expected complexity level and risk

Testing

For automated tests, there are unit tests to see what sql gets emitted in tests/query.test.ts, and some tests of the types in view.test-d.ts.

I've also run some manual tests with a typescript module with views.

@jsdt jsdt requested a review from joshua-spacetime December 4, 2025 17:38
@jsdt jsdt marked this pull request as ready for review December 4, 2025 18:41
Copy link
Collaborator

@joshua-spacetime joshua-spacetime left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mainly reviewed the api. Improving compile-time safety will be addressed in follow up patches.

@jsdt jsdt enabled auto-merge December 4, 2025 22:05
@jsdt jsdt added this pull request to the merge queue Dec 4, 2025
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Dec 4, 2025
@jsdt jsdt added this pull request to the merge queue Dec 4, 2025
Merged via the queue into master with commit 3e7ab2c Dec 4, 2025
26 checks passed
@joshua-spacetime joshua-spacetime linked an issue Dec 4, 2025 that may be closed by this pull request
@jsdt jsdt mentioned this pull request Dec 10, 2025
github-merge-queue bot pushed a commit that referenced this pull request Dec 16, 2025
# Description of Changes

This improves the type safety a bit from
#3812.

The core change is that the previous version typed queries based on the
typescript type, not the spacetime type. This meant that we allowed
queries for incorrect tables, like a table that had the same column
names and types, but had a u32 instead of a u64 somewhere.

This still has an issue with allowing results from tables where the rows
are reordered, which would actually be a problem, but hopefully that is
not too common.

# API and ABI breaking changes

This is technically a breaking change, because it changes some type
parameters. I don't think people should be relying on these though, so I
don't think we should be worried about breaking them.

This would only cause new type errors for apps that are likely to error
at runtime anyway.

# Expected complexity level and risk

1.5. This should be low risk, since it is just a typing change.

# Testing

This has some type checks in `view.test-d.ts`, and I've done some manual
e2e testing.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[TS] Module bindings for query builder

3 participants