Add a typescript query builder for views (#3812)

# 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](https://github.com/clockworklabs/SpacetimeDB/compare/jsdt/ts-query-builder?expand=1#diff-4fd25c191f1207085a491cf84996c601f805f5e8280d1cf2a812ebad6aa6e75a).

To play around with the syntax, you might find it easier to look in
[crates/bindings-typescript/src/server/view.test-d.ts](https://github.com/clockworklabs/SpacetimeDB/compare/jsdt/ts-query-builder?expand=1#diff-4fd25c191f1207085a491cf84996c601f805f5e8280d1cf2a812ebad6aa6e75a).

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.
4. A table with fields of a different spacetimetype that map to the same
typescript type (like `u16` and `u32`).

I can also add back functions for things like inequality once we are ok
with the rest of it.

# API and ABI breaking changes

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

# Expected complexity level and risk

2.

# 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.

Author: jsdt

crates/bindings-typescript/src/lib/autogen/view_result_header_type.ts

@@ -59,6 +59,15 @@ export type UntypedSchemaDef = {
   tables: readonly UntypedTableDef[];
 };
 
+let REGISTERED_SCHEMA: UntypedSchemaDef | null = null;
+
+export function getRegisteredSchema(): UntypedSchemaDef {
+  if (REGISTERED_SCHEMA == null) {
+    throw new Error('Schema has not been registered yet. Call schema() first.');
+  }
+  return REGISTERED_SCHEMA;
+}
+
 /**
  * Helper type to convert an array of TableSchema into a schema definition
  */
@@ -636,6 +645,16 @@ export function schema<const H extends readonly TableSchema<any, any, any>[]>(
   // Modify the `MODULE_DEF` which will be read by
   // __describe_module__
   MODULE_DEF.tables.push(...tableDefs);
+  REGISTERED_SCHEMA = {
+    tables: handles.map(handle => ({
+      name: handle.tableName,
+      accessorName: handle.tableName,
+      columns: handle.rowType.row,
+      rowType: handle.rowSpacetimeType,
+      indexes: handle.idxs,
+      constraints: handle.constraints,
+    })),
+  };
   // MODULE_DEF.typespace = typespace;
   // throw new Error(
   //   MODULE_DEF.tables

crates/bindings-typescript/src/lib/schema.ts

@@ -34,9 +34,8 @@ type ColList = ColId[];
 /**
  * A helper type to extract the row type from a TableDef
  */
-export type RowType<TableDef extends UntypedTableDef> = InferTypeOfRow<
-  TableDef['columns']
->;
+export type RowType<TableDef extends Pick<UntypedTableDef, 'columns'>> =
+  InferTypeOfRow<TableDef['columns']>;
 
 /**
  * Coerces a column which may be a TypeBuilder or ColumnBuilder into a ColumnBuilder

crates/bindings-typescript/src/lib/table.ts

@@ -41,6 +41,15 @@ export type InferTypeOfRow<T extends RowObj> = {
   [K in keyof T & string]: InferTypeOfTypeBuilder<CollapseColumn<T[K]>>;
 };
 
+/**
+ * Helper type to extract the type of a row from an object.
+ */
+export type InferSpacetimeTypeOfRow<T extends RowObj> = {
+  [K in keyof T & string]: InferSpacetimeTypeOfTypeBuilder<
+    CollapseColumn<T[K]>
+  >;
+};
+
 /**
  * Helper type to extract the Spacetime type from a row object.
  */

crates/bindings-typescript/src/lib/type_builders.ts

@@ -20,14 +20,17 @@ import {
   type TypeBuilder,
 } from './type_builders';
 import { bsatnBaseSize, toPascalCase } from './util';
+import { type QueryBuilder, type RowTypedQuery } from '../server/query';
 
 export type ViewCtx<S extends UntypedSchemaDef> = Readonly<{
   sender: Identity;
   db: ReadonlyDbView<S>;
+  from: QueryBuilder<S>;
 }>;
 
 export type AnonymousViewCtx<S extends UntypedSchemaDef> = Readonly<{
   db: ReadonlyDbView<S>;
+  from: QueryBuilder<S>;
 }>;
 
 export type ReadonlyDbView<SchemaDef extends UntypedSchemaDef> = {
@@ -39,17 +42,34 @@ export type ViewOpts = {
   public: true;
 };
 
+type FlattenedArray<T> = T extends readonly (infer E)[] ? E : never;
+
+// // If we allowed functions to return either.
+// type ViewReturn<Ret extends ViewReturnTypeBuilder> =
+//   | Infer<Ret>
+//   | RowTypedQuery<FlattenedArray<Infer<Ret>>>;
+
 export type ViewFn<
   S extends UntypedSchemaDef,
   Params extends ParamsObj,
   Ret extends ViewReturnTypeBuilder,
-> = (ctx: ViewCtx<S>, params: InferTypeOfRow<Params>) => Infer<Ret>;
+> =
+  | ((ctx: ViewCtx<S>, params: InferTypeOfRow<Params>) => Infer<Ret>)
+  | ((
+      ctx: ViewCtx<S>,
+      params: InferTypeOfRow<Params>
+    ) => RowTypedQuery<FlattenedArray<Infer<Ret>>>);
 
 export type AnonymousViewFn<
   S extends UntypedSchemaDef,
   Params extends ParamsObj,
   Ret extends ViewReturnTypeBuilder,
-> = (ctx: AnonymousViewCtx<S>, params: InferTypeOfRow<Params>) => Infer<Ret>;
+> =
+  | ((ctx: AnonymousViewCtx<S>, params: InferTypeOfRow<Params>) => Infer<Ret>)
+  | ((
+      ctx: AnonymousViewCtx<S>,
+      params: InferTypeOfRow<Params>
+    ) => RowTypedQuery<FlattenedArray<Infer<Ret>>>);
 
 export type ViewReturnTypeBuilder =
   | TypeBuilder<
@@ -97,6 +117,7 @@ export function defineView<
     },
   });
 
+  // If it is an option, we wrap the function to make the return look like an array.
   if (returnType.tag == 'Sum') {
     const originalFn = fn;
     fn = ((ctx: ViewCtx<S>, args: InferTypeOfRow<Params>) => {

crates/bindings-typescript/src/lib/views.ts

@@ -5,6 +5,7 @@ export { reducers } from '../lib/reducers';
 export { SenderError, SpacetimeHostError, errors } from './errors';
 export { type Reducer, type ReducerCtx } from '../lib/reducers';
 export { type DbView } from './db_view';
+export { and, or, not } from './query';
 export type { ProcedureCtx, TransactionCtx } from '../lib/procedures';
 
 import './polyfills'; // Ensure polyfills are loaded