Typescript module bindings for views

Author: coolreader18

crates/bindings-typescript/src/server/indexes.ts

@@ -46,6 +46,13 @@ export type Indexes<
   [k in keyof I]: Index<TableDef, I[k]>;
 };
 
+export type ReadonlyIndexes<
+  TableDef extends UntypedTableDef,
+  I extends Record<string, UntypedIndex<keyof TableDef['columns'] & string>>,
+> = {
+  [k in keyof I]: ReadonlyIndex<TableDef, I[k]>;
+};
+
 /**
  * A type representing a database index, which can be either unique or ranged.
  */
@@ -56,32 +63,51 @@ export type Index<
   ? UniqueIndex<TableDef, I>
   : RangedIndex<TableDef, I>;
 
+export type ReadonlyIndex<
+  TableDef extends UntypedTableDef,
+  I extends UntypedIndex<keyof TableDef['columns'] & string>,
+> = I['unique'] extends true
+  ? ReadonlyUniqueIndex<TableDef, I>
+  : ReadonlyRangedIndex<TableDef, I>;
+
+export interface ReadonlyUniqueIndex<
+  TableDef extends UntypedTableDef,
+  I extends UntypedIndex<keyof TableDef['columns'] & string>,
+> {
+  find(col_val: IndexVal<TableDef, I>): RowType<TableDef> | null;
+}
+
 /**
  * A type representing a unique index on a database table.
  * Unique indexes enforce that the indexed columns contain unique values.
  */
-export type UniqueIndex<
+export interface UniqueIndex<
   TableDef extends UntypedTableDef,
   I extends UntypedIndex<keyof TableDef['columns'] & string>,
-> = {
-  find(col_val: IndexVal<TableDef, I>): RowType<TableDef> | null;
+> extends ReadonlyUniqueIndex<TableDef, I> {
   delete(col_val: IndexVal<TableDef, I>): boolean;
   update(col_val: RowType<TableDef>): RowType<TableDef>;
-};
+}
+
+export interface ReadonlyRangedIndex<
+  TableDef extends UntypedTableDef,
+  I extends UntypedIndex<keyof TableDef['columns'] & string>,
+> {
+  filter(
+    range: IndexScanRangeBounds<TableDef, I>
+  ): IterableIterator<RowType<TableDef>>;
+}
 
 /**
  * A type representing a ranged index on a database table.
  * Ranged indexes allow for range queries on the indexed columns.
  */
-export type RangedIndex<
+export interface RangedIndex<
   TableDef extends UntypedTableDef,
   I extends UntypedIndex<keyof TableDef['columns'] & string>,
-> = {
-  filter(
-    range: IndexScanRangeBounds<TableDef, I>
-  ): IterableIterator<RowType<TableDef>>;
+> extends ReadonlyRangedIndex<TableDef, I> {
   delete(range: IndexScanRangeBounds<TableDef, I>): number;
-};
+}
 
 /**
  * A helper type to extract the value type of an index based on the table definition and index definition.

crates/bindings-typescript/src/server/register_hooks.ts

@@ -1,4 +1,6 @@
 import { register_hooks } from 'spacetime:[email protected]';
-import { hooks } from './runtime';
+import { register_hooks as register_hooks_v1_1 } from 'spacetime:[email protected]';
+import { hooks, hooks_v1_1 } from './runtime';
 
 register_hooks(hooks);
+register_hooks_v1_1(hooks_v1_1);

crates/bindings-typescript/src/server/runtime.ts

@@ -29,6 +29,12 @@ import { MODULE_DEF } from './schema';
 
 import * as _syscalls from 'spacetime:[email protected]';
 import type { u16, u32, ModuleHooks } from 'spacetime:[email protected]';
+import {
+  ANON_VIEWS,
+  VIEWS,
+  type AnonymousViewCtx,
+  type ViewCtx,
+} from './views';
 
 const { freeze } = Object;
 
@@ -212,6 +218,46 @@ export const hooks: ModuleHooks = {
   },
 };
 
+export const hooks_v1_1: import('spacetime:[email protected]').ModuleHooks = {
+  __call_view__(id, sender, argsBuf) {
+    const { fn, params, returnType, returnTypeBaseSize } = VIEWS[id];
+    const ctx: ViewCtx<any> = freeze({
+      sender: new Identity(sender),
+      // this is the non-readonly DbView, but the typing for the user will be
+      // the readonly one, and if they do call mutating functions it will fail
+      // at runtime
+      db: getDbView(),
+    });
+    const args = AlgebraicType.deserializeValue(
+      new BinaryReader(argsBuf),
+      AlgebraicType.Product(params),
+      MODULE_DEF.typespace
+    );
+    const ret = fn(ctx, args);
+    const retBuf = new BinaryWriter(returnTypeBaseSize);
+    AlgebraicType.serializeValue(retBuf, returnType, ret, MODULE_DEF.typespace);
+    return retBuf.getBuffer();
+  },
+  __call_view_anon__(id, argsBuf) {
+    const { fn, params, returnType, returnTypeBaseSize } = ANON_VIEWS[id];
+    const ctx: AnonymousViewCtx<any> = freeze({
+      // this is the non-readonly DbView, but the typing for the user will be
+      // the readonly one, and if they do call mutating functions it will fail
+      // at runtime
+      db: getDbView(),
+    });
+    const args = AlgebraicType.deserializeValue(
+      new BinaryReader(argsBuf),
+      AlgebraicType.Product(params),
+      MODULE_DEF.typespace
+    );
+    const ret = fn(ctx, args);
+    const retBuf = new BinaryWriter(returnTypeBaseSize);
+    AlgebraicType.serializeValue(retBuf, returnType, ret, MODULE_DEF.typespace);
+    return retBuf.getBuffer();
+  },
+};
+
 let DB_VIEW: DbView<any> | null = null;
 function getDbView() {
   DB_VIEW ??= makeDbView(MODULE_DEF);
@@ -464,7 +510,7 @@ function makeTableView(typespace: Typespace, table: RawTableDefV9): Table<any> {
   return freeze(tableView);
 }
 
-function bsatnBaseSize(typespace: Typespace, ty: AlgebraicType): number {
+export function bsatnBaseSize(typespace: Typespace, ty: AlgebraicType): number {
   const assumedArrayLength = 4;
   while (ty.tag === 'Ref') ty = typespace.types[ty.value];
   if (ty.tag === 'Product') {

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

@@ -22,6 +22,12 @@ import {
   type AlgebraicTypeVariants,
 } from '../lib/algebraic_type';
 import type RawScopedTypeNameV9 from '../lib/autogen/raw_scoped_type_name_v_9_type';
+import {
+  defineView,
+  type AnonymousViewFn,
+  type ViewFn,
+  type ViewReturnTypeBuilder,
+} from './views';
 
 /**
  * The global module definition that gets populated by calls to `reducer()` and lifecycle hooks.
@@ -285,6 +291,54 @@ class Schema<S extends UntypedSchemaDef> {
     clientDisconnected(name, {}, fn);
   }
 
+  view<Ret extends ViewReturnTypeBuilder>(
+    name: string,
+    ret: Ret,
+    fn: ViewFn<S, {}, Ret>
+  ): void;
+  view<Params extends ParamsObj, Ret extends ViewReturnTypeBuilder>(
+    name: string,
+    params: Params,
+    ret: Ret,
+    fn: ViewFn<S, {}, Ret>
+  ): void;
+  view<Params extends ParamsObj, Ret extends ViewReturnTypeBuilder>(
+    name: string,
+    paramsOrRet: Ret | Params,
+    retOrFn: ViewFn<S, {}, Ret> | Ret,
+    maybeFn?: ViewFn<S, Params, Ret>
+  ): void {
+    if (typeof retOrFn === 'function') {
+      defineView(name, false, {}, paramsOrRet as Ret, retOrFn);
+    } else {
+      defineView(name, false, paramsOrRet as Params, retOrFn, maybeFn!);
+    }
+  }
+
+  anyonymousView<Ret extends ViewReturnTypeBuilder>(
+    name: string,
+    ret: Ret,
+    fn: AnonymousViewFn<S, {}, Ret>
+  ): void;
+  anyonymousView<Params extends ParamsObj, Ret extends ViewReturnTypeBuilder>(
+    name: string,
+    params: Params,
+    ret: Ret,
+    fn: AnonymousViewFn<S, {}, Ret>
+  ): void;
+  anyonymousView<Params extends ParamsObj, Ret extends ViewReturnTypeBuilder>(
+    name: string,
+    paramsOrRet: Ret | Params,
+    retOrFn: AnonymousViewFn<S, {}, Ret> | Ret,
+    maybeFn?: AnonymousViewFn<S, Params, Ret>
+  ): void {
+    if (typeof retOrFn === 'function') {
+      defineView(name, true, {}, paramsOrRet as Ret, retOrFn);
+    } else {
+      defineView(name, true, paramsOrRet as Params, retOrFn, maybeFn!);
+    }
+  }
+
   clientVisibilityFilter = {
     sql(filter: string): void {
       MODULE_DEF.rowLevelSecurity.push({ sql: filter });

crates/bindings-typescript/src/server/sys.d.ts

@@ -66,3 +66,12 @@ declare module 'spacetime:[email protected]' {
   export function identity(): { __identity__: u256 };
   export function get_jwt_payload(connection_id: u128): Uint8Array;
 }
+
+declare module 'spacetime:[email protected]' {
+  export type ModuleHooks = {
+    __call_view__(id: u32, sender: u256, args: Uint8Array): Uint8Array;
+    __call_view_anon__(id: u32, args: Uint8Array): Uint8Array;
+  };
+
+  export function register_hooks(hooks: ModuleHooks);
+}

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

@@ -5,7 +5,13 @@ import type RawIndexDefV9 from '../lib/autogen/raw_index_def_v_9_type';
 import type RawSequenceDefV9 from '../lib/autogen/raw_sequence_def_v_9_type';
 import type RawTableDefV9 from '../lib/autogen/raw_table_def_v_9_type';
 import type { AllUnique } from './constraints';
-import type { ColumnIndex, IndexColumns, Indexes, IndexOpts } from './indexes';
+import type {
+  ColumnIndex,
+  IndexColumns,
+  Indexes,
+  IndexOpts,
+  ReadonlyIndexes,
+} from './indexes';
 import { MODULE_DEF, splitName } from './schema';
 import {
   RowBuilder,
@@ -108,17 +114,25 @@ export type Table<TableDef extends UntypedTableDef> = Prettify<
   TableMethods<TableDef> & Indexes<TableDef, TableIndexes<TableDef>>
 >;
 
-/**
- * A type representing the methods available on a table.
- */
-export type TableMethods<TableDef extends UntypedTableDef> = {
+export type ReadonlyTable<TableDef extends UntypedTableDef> = Prettify<
+  ReadonlyTableMethods<TableDef> &
+    ReadonlyIndexes<TableDef, TableIndexes<TableDef>>
+>;
+
+export interface ReadonlyTableMethods<TableDef extends UntypedTableDef> {
   /** Returns the number of rows in the TX state. */
   count(): bigint;
 
   /** Iterate over all rows in the TX state. Rust Iterator<Item=Row> → TS IterableIterator<Row>. */
   iter(): IterableIterator<RowType<TableDef>>;
   [Symbol.iterator](): IterableIterator<RowType<TableDef>>;
+}
 
+/**
+ * A type representing the methods available on a table.
+ */
+export interface TableMethods<TableDef extends UntypedTableDef>
+  extends ReadonlyTableMethods<TableDef> {
   /**
    * Insert and return the inserted row (auto-increment fields filled).
    *
@@ -130,7 +144,7 @@ export type TableMethods<TableDef extends UntypedTableDef> = {
 
   /** Delete a row equal to `row`. Returns true if something was deleted. */
   delete(row: RowType<TableDef>): boolean;
-};
+}
 
 /**
  * Represents a handle to a database table, including its name, row type, and row spacetime type.

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

@@ -0,0 +1,92 @@
+import type {
+  AlgebraicType,
+  AlgebraicTypeVariants,
+  ProductType,
+} from '../lib/algebraic_type';
+import type { Identity } from '../lib/identity';
+import type { ParamsObj } from './reducers';
+import { bsatnBaseSize } from './runtime';
+import { MODULE_DEF, type UntypedSchemaDef } from './schema';
+import type { ReadonlyTable } from './table';
+import type { Infer, InferTypeOfRow, TypeBuilder } from './type_builders';
+
+export type ViewCtx<S extends UntypedSchemaDef> = Readonly<{
+  sender: Identity;
+  db: ReadonlyDbView<S>;
+}>;
+
+export type AnonymousViewCtx<S extends UntypedSchemaDef> = Readonly<{
+  db: ReadonlyDbView<S>;
+}>;
+
+export type ReadonlyDbView<SchemaDef extends UntypedSchemaDef> = {
+  readonly [Tbl in SchemaDef['tables'][number] as Tbl['name']]: ReadonlyTable<Tbl>;
+};
+
+export type ViewFn<
+  S extends UntypedSchemaDef,
+  Params extends ParamsObj,
+  Ret extends ViewReturnTypeBuilder,
+> = (ctx: ViewCtx<S>, params: InferTypeOfRow<Params>) => Infer<Ret>;
+
+export type AnonymousViewFn<
+  S extends UntypedSchemaDef,
+  Params extends ParamsObj,
+  Ret extends ViewReturnTypeBuilder,
+> = (ctx: AnonymousViewCtx<S>, params: InferTypeOfRow<Params>) => Infer<Ret>;
+
+export type ViewReturnTypeBuilder = TypeBuilder<
+  any,
+  | { tag: 'Array'; value: AlgebraicTypeVariants.Product }
+  | AlgebraicTypeVariants.Product
+>;
+
+export function defineView<
+  S extends UntypedSchemaDef,
+  const Anonymous extends boolean,
+  Params extends ParamsObj,
+  Ret extends ViewReturnTypeBuilder,
+>(
+  name: string,
+  anon: Anonymous,
+  params: Params,
+  ret: Ret,
+  fn: Anonymous extends true
+    ? AnonymousViewFn<S, Params, Ret>
+    : ViewFn<S, Params, Ret>
+) {
+  const paramType = {
+    elements: Object.entries(params).map(([n, c]) => ({
+      name: n,
+      algebraicType: c.algebraicType,
+    })),
+  };
+
+  MODULE_DEF.miscExports.push({
+    tag: 'View',
+    value: {
+      name,
+      isPublic: true,
+      isAnonymous: anon,
+      params: paramType,
+      returnType: ret.algebraicType,
+    },
+  });
+
+  (anon ? ANON_VIEWS : VIEWS).push({
+    fn,
+    params: paramType,
+    returnType: ret.algebraicType,
+    returnTypeBaseSize: bsatnBaseSize(MODULE_DEF.typespace, ret.algebraicType),
+  });
+}
+
+type ViewInfo<F> = {
+  fn: F;
+  params: ProductType;
+  returnType: AlgebraicType;
+  returnTypeBaseSize: number;
+};
+
+export const VIEWS: ViewInfo<ViewFn<any, any, any>>[] = [];
+export const ANON_VIEWS: ViewInfo<AnonymousViewFn<any, any, any>>[] = [];

modules/sdk-test-ts/src/index.ts

@@ -1015,3 +1015,8 @@ spacetimedb.reducer(
     }
   }
 );
+
+const X = t.object('X', { a: t.i32() });
+spacetimedb.view('a', X, () => {
+  return { a: 1 };
+});