spacetimedb 2.4.0 → 2.5.0

package/src/server/schema.ts

@@ -50,6 +50,7 @@ import {
   type ViewFn,
   type ViewOpts,
   type ViewReturnTypeBuilder,
+  type ValidateViewPrimaryKey,
   type Views,
 } from './views';
 import type { UntypedTableDef } from '../lib/table';
@@ -395,7 +396,11 @@ export class Schema<S extends UntypedSchemaDef> implements ModuleDefaultExport {
   view<Ret extends ViewReturnTypeBuilder, F extends ViewFn<S, {}, Ret>>(
     opts: ViewOpts,
     ret: Ret,
-    fn: F
+    fn: F,
+    // Compile-time-only guard: this rest parameter is `[]` for valid return
+    // builders, but becomes a required error tuple when a returned row builder
+    // marks more than one column with `.primaryKey()`.
+    ..._: ValidateViewPrimaryKey<Ret>
   ): ViewExport<F> {
     return makeViewExport<S, {}, Ret, F>(this.#ctx, opts, {}, ret, fn);
   }
@@ -428,7 +433,15 @@ export class Schema<S extends UntypedSchemaDef> implements ModuleDefaultExport {
   anonymousView<
     Ret extends ViewReturnTypeBuilder,
     F extends AnonymousViewFn<S, {}, Ret>,
-  >(opts: ViewOpts, ret: Ret, fn: F): ViewExport<F> {
+  >(
+    opts: ViewOpts,
+    ret: Ret,
+    fn: F,
+    // Compile-time-only guard: this rest parameter is `[]` for valid return
+    // builders, but becomes a required error tuple when a returned row builder
+    // marks more than one column with `.primaryKey()`.
+    ..._: ValidateViewPrimaryKey<Ret>
+  ): ViewExport<F> {
     return makeAnonViewExport<S, {}, Ret, F>(this.#ctx, opts, {}, ret, fn);
   }
 

package/src/server/view.test-d.ts

@@ -73,11 +73,33 @@ const spacetime = schema({
 
 const arrayRetValue = t.array(person.rowType);
 const optionalPerson = t.option(person.rowType);
+const multiplePrimaryKeyRows = t.array(
+  t.row('MultiplePrimaryKeyRows', {
+    id: t.u32().primaryKey(),
+    name: t.string().primaryKey(),
+  })
+);
 
 spacetime.anonymousView({ name: 'v1', public: true }, arrayRetValue, ctx => {
   return ctx.from.person.build();
 });
 
+// @ts-expect-error views can have at most one primaryKey column on the returned row type.
+spacetime.anonymousView(
+  { name: 'multiplePrimaryRows', public: true },
+  multiplePrimaryKeyRows,
+  () => []
+);
+
+// @ts-expect-error the same multiple-primary-key check also applies to query-builder views.
+spacetime.anonymousView(
+  { name: 'multiplePrimaryRowsQuery', public: true },
+  multiplePrimaryKeyRows,
+  ctx => {
+    return ctx.from.person;
+  }
+);
+
 spacetime.anonymousView(
   { name: 'optionalPerson', public: true },
   optionalPerson,

package/src/server/views.ts

@@ -10,10 +10,15 @@ import type { OptionAlgebraicType } from '../lib/option';
 import type { ParamsObj } from '../lib/reducers';
 import { type UntypedSchemaDef } from '../lib/schema';
 import {
+  ArrayBuilder,
+  OptionBuilder,
   RowBuilder,
+  type ColumnBuilder,
+  type ColumnMetadata,
   type Infer,
   type InferSpacetimeTypeOfTypeBuilder,
   type InferTypeOfRow,
+  type RowObj,
   type TypeBuilder,
 } from '../lib/type_builders';
 import { bsatnBaseSize, toPascalCase } from '../lib/util';
@@ -90,6 +95,77 @@ export type ViewOpts = {
 
 type FlattenedArray<T> = T extends readonly (infer E)[] ? E : never;
 
+// Compile-time mirror of `viewReturnRow` below. Views currently return either
+// `array(row(...))` or `option(row(...))`; this extracts the row object type
+// from those builders so we can inspect column metadata at the type level.
+// Non-row returns collapse to `never`, which makes the primary-key validation
+// below a no-op for unsupported shapes.
+type ViewReturnRow<Ret extends ViewReturnTypeBuilder> =
+  Ret extends ArrayBuilder<infer Element>
+    ? Element extends RowBuilder<infer Row>
+      ? Row
+      : never
+    : Ret extends OptionBuilder<infer Value>
+      ? Value extends RowBuilder<infer Row>
+        ? Row
+        : never
+      : never;
+
+// Produces a union of the returned row's column names marked with
+// `.primaryKey()`. For example, `{ id: t.u32().primaryKey(), name: t.string() }`
+// becomes `"id"`, while two marked columns becomes `"id" | "name"`.
+type PrimaryKeyColumnNames<Row extends RowObj> = {
+  [K in keyof Row & string]: Row[K] extends ColumnBuilder<any, any, infer M>
+    ? M extends { isPrimaryKey: true }
+      ? K
+      : never
+    : never;
+}[keyof Row & string];
+
+// Standard conditional-type trick for distinguishing a single type from a
+// union. We use it because zero or one primary-key column is valid, but a union
+// of two or more column names means the row builder marked multiple primary
+// keys.
+type IsUnion<T, U = T> = [T] extends [never]
+  ? false
+  : T extends any
+    ? [U] extends [T]
+      ? false
+      : true
+    : false;
+
+// In generic code, row keys may widen from literal names like "id" | "name"
+// to plain `string`. That means "unknown column name", not "multiple primary
+// keys", so avoid a false-positive type error and rely on the runtime check.
+type HasMultiplePrimaryKeys<Row extends RowObj> =
+  string extends PrimaryKeyColumnNames<Row>
+    ? false
+    : IsUnion<PrimaryKeyColumnNames<Row>>;
+
+type MultiplePrimaryKeyColumns<Ret extends ViewReturnTypeBuilder> =
+  PrimaryKeyColumnNames<ViewReturnRow<Ret>>;
+
+type ERROR_view_return_type_can_have_at_most_one_primaryKey<
+  Columns extends string,
+> = {
+  _primaryKeyColumns: Columns;
+  _fix: 'Remove primaryKey() from all but one column on the returned row type';
+};
+
+// Used as a rest parameter type on `Schema.view` and `Schema.anonymousView`.
+// Valid return builders produce `[]`, so callers pass no extra arguments. If
+// the returned row has multiple `.primaryKey()` columns, this becomes a
+// one-element tuple containing an explanatory error type, which makes the
+// normal three-argument call fail to type-check.
+export type ValidateViewPrimaryKey<Ret extends ViewReturnTypeBuilder> =
+  HasMultiplePrimaryKeys<ViewReturnRow<Ret>> extends true
+    ? [
+        error: ERROR_view_return_type_can_have_at_most_one_primaryKey<
+          MultiplePrimaryKeyColumns<Ret>
+        >,
+      ]
+    : [];
+
 // // If we allowed functions to return either.
 // type ViewReturn<Ret extends ViewReturnTypeBuilder> =
 //   | Infer<Ret>
@@ -164,6 +240,22 @@ export function registerView<
     returnType,
   });
 
+  // Runtime counterpart to `ValidateViewPrimaryKey`: the type-level check gives
+  // users an early diagnostic in normal code, but this still protects dynamic
+  // or widened builders and is the source of the raw module-def metadata.
+  const primaryKeyColumns = viewPrimaryKeyColumns(ret);
+  if (primaryKeyColumns.length > 1) {
+    throw new TypeError(
+      `View '${exportName}' can have at most one primaryKey() column on its returned row type; found ${primaryKeyColumns.join(', ')}`
+    );
+  }
+  if (primaryKeyColumns.length === 1) {
+    ctx.moduleDef.viewPrimaryKeys.push({
+      viewSourceName: exportName,
+      columns: primaryKeyColumns,
+    });
+  }
+
   if (opts.name != null) {
     ctx.moduleDef.explicitNames.entries.push({
       tag: 'Function',
@@ -194,6 +286,40 @@ export function registerView<
   });
 }
 
+// Inspect the returned row builder and collect the column property names marked
+// with `.primaryKey()`. These names are the TypeScript row-builder keys, which
+// are also the raw column names in the module definition emitted by the TS SDK.
+function viewPrimaryKeyColumns(ret: ViewReturnTypeBuilder): string[] {
+  const row = viewReturnRow(ret);
+  if (row == null) {
+    return [];
+  }
+
+  return Object.entries(row.row)
+    .filter(
+      (
+        entry
+      ): entry is [string, ColumnBuilder<any, any, ColumnMetadata<any>>] =>
+        entry[1].columnMetadata.isPrimaryKey === true
+    )
+    .map(([name]) => name);
+}
+
+// Views can return either `array(row(...))` or `option(row(...))`. The primary
+// key marker lives on the inner `RowBuilder`, so unwrap those two supported
+// shapes and ignore anything else.
+function viewReturnRow(
+  ret: ViewReturnTypeBuilder
+): RowBuilder<any> | undefined {
+  if (ret instanceof ArrayBuilder && ret.element instanceof RowBuilder) {
+    return ret.element;
+  }
+  if (ret instanceof OptionBuilder && ret.value instanceof RowBuilder) {
+    return ret.value;
+  }
+  return undefined;
+}
+
 type ViewInfo<F> = {
   fn: F;
   deserializeParams: Deserializer<any>;

package/src/solid/SpacetimeDBProvider.ts

@@ -0,0 +1,97 @@
+import {
+  DbConnectionBuilder,
+  type DbConnectionImpl,
+} from '../sdk/db_connection_impl';
+import { onCleanup, createMemo, createComputed } from 'solid-js';
+import { createStore } from 'solid-js/store';
+import { SpacetimeDBContext } from './useSpacetimeDB';
+import type { ConnectionState } from './connection_state';
+import { ConnectionId } from '../lib/connection_id';
+import {
+  ConnectionManager,
+  type ConnectionState as ManagerConnectionState,
+} from '../sdk/connection_manager';
+
+export interface SpacetimeDBProviderProps<
+  DbConnection extends DbConnectionImpl<any>,
+> {
+  connectionBuilder: DbConnectionBuilder<DbConnection>;
+  children?: any;
+}
+
+export function SpacetimeDBProvider<DbConnection extends DbConnectionImpl<any>>(
+  props: SpacetimeDBProviderProps<DbConnection>
+) {
+  const uri = () => props.connectionBuilder.getUri();
+  const moduleName = () => props.connectionBuilder.getModuleName();
+
+  const key = createMemo(() => ConnectionManager.getKey(uri(), moduleName()));
+
+  const fallbackState: ManagerConnectionState = {
+    isActive: false,
+    identity: undefined,
+    token: undefined,
+    connectionId: ConnectionId.random(),
+    connectionError: undefined,
+  };
+
+  const [state, setState] = createStore<ManagerConnectionState>(fallbackState);
+
+  // Subscribe to ConnectionManager state changes
+  createComputed(() => {
+    const currentKey = key();
+
+    const unsubscribe = ConnectionManager.subscribe(currentKey, () => {
+      const snapshot =
+        ConnectionManager.getSnapshot(currentKey) ?? fallbackState;
+      setState(snapshot);
+    });
+
+    // Load initial snapshot
+    const snapshot = ConnectionManager.getSnapshot(currentKey) ?? fallbackState;
+    setState(snapshot);
+
+    onCleanup(() => {
+      unsubscribe();
+    });
+  });
+
+  const getConnection = () =>
+    ConnectionManager.getConnection<DbConnection>(key());
+
+  const contextValue: ConnectionState = {
+    get isActive() {
+      return state.isActive;
+    },
+    get identity() {
+      return state.identity;
+    },
+    get token() {
+      return state.token;
+    },
+    get connectionId() {
+      return state.connectionId;
+    },
+    get connectionError() {
+      return state.connectionError;
+    },
+    getConnection,
+  };
+
+  // Retain / release lifecycle
+  createComputed(() => {
+    const currentKey = key();
+    ConnectionManager.retain(currentKey, props.connectionBuilder);
+
+    onCleanup(() => {
+      ConnectionManager.release(currentKey);
+    });
+  });
+
+  return SpacetimeDBContext.Provider({
+    value: contextValue,
+    get children() {
+      return props.children;
+    },
+  });
+}

package/src/solid/connection_state.ts

@@ -0,0 +1,6 @@
+import type { DbConnectionImpl } from '../sdk/db_connection_impl';
+import type { ConnectionState as ManagerConnectionState } from '../sdk/connection_manager';
+
+export type ConnectionState = ManagerConnectionState & {
+  getConnection(): DbConnectionImpl<any> | null;
+};

package/src/solid/index.ts

@@ -0,0 +1,5 @@
+export * from './SpacetimeDBProvider.ts';
+export { useSpacetimeDB } from './useSpacetimeDB.ts';
+export { useTable } from './useTable.ts';
+export { useReducer } from './useReducer.ts';
+export { useProcedure } from './useProcedure.ts';

package/src/solid/useProcedure.ts

@@ -0,0 +1,57 @@
+import { createEffect } from 'solid-js';
+import type { UntypedProcedureDef } from '../sdk/procedures';
+import { useSpacetimeDB } from './useSpacetimeDB';
+import type {
+  ProcedureParamsType,
+  ProcedureReturnType,
+} from '../sdk/type_utils';
+
+export function useProcedure<ProcedureDef extends UntypedProcedureDef>(
+  procedureDef: ProcedureDef
+): (
+  ...params: ProcedureParamsType<ProcedureDef>
+) => Promise<ProcedureReturnType<ProcedureDef>> {
+  const { getConnection, isActive } = useSpacetimeDB();
+  const procedureName = procedureDef.accessorName;
+
+  // Holds calls made before the connection exists
+  const queue: {
+    params: ProcedureParamsType<ProcedureDef>;
+    resolve: (val: any) => void;
+    reject: (err: unknown) => void;
+  }[] = [];
+
+  // Flush when we finally have a connection
+  createEffect(() => {
+    if (!isActive) return;
+
+    const conn = getConnection();
+    if (!conn) return;
+
+    const fn = (conn.procedures as any)[procedureName] as (
+      ...p: ProcedureParamsType<ProcedureDef>
+    ) => Promise<ProcedureReturnType<ProcedureDef>>;
+
+    if (queue.length) {
+      const pending = queue.splice(0);
+      for (const item of pending) {
+        fn(...item.params).then(item.resolve, item.reject);
+      }
+    }
+  });
+
+  return (...params: ProcedureParamsType<ProcedureDef>) => {
+    const conn = getConnection();
+    if (!conn) {
+      return new Promise<ProcedureReturnType<ProcedureDef>>(
+        (resolve, reject) => {
+          queue.push({ params, resolve, reject });
+        }
+      );
+    }
+    const fn = (conn.procedures as any)[procedureName] as (
+      ...p: ProcedureParamsType<ProcedureDef>
+    ) => Promise<ProcedureReturnType<ProcedureDef>>;
+    return fn(...params);
+  };
+}

package/src/solid/useReducer.ts

@@ -0,0 +1,50 @@
+import { createEffect } from 'solid-js';
+import type { UntypedReducerDef } from '../sdk/reducers';
+import { useSpacetimeDB } from './useSpacetimeDB';
+import type { ParamsType } from '../sdk';
+
+export function useReducer<ReducerDef extends UntypedReducerDef>(
+  reducerDef: ReducerDef
+): (...params: ParamsType<ReducerDef>) => Promise<void> {
+  const { getConnection, isActive } = useSpacetimeDB();
+  const reducerName = reducerDef.accessorName;
+
+  // Holds calls made before the connection exists
+  const queue: {
+    params: ParamsType<ReducerDef>;
+    resolve: () => void;
+    reject: (err: unknown) => void;
+  }[] = [];
+
+  // Flush when we finally have a connection
+  createEffect(() => {
+    if (!isActive) return;
+
+    const conn = getConnection();
+    if (!conn) return;
+
+    const fn = (conn.reducers as any)[reducerName] as (
+      ...p: ParamsType<ReducerDef>
+    ) => Promise<void>;
+
+    if (queue.length) {
+      const pending = queue.splice(0);
+      for (const item of pending) {
+        fn(...item.params).then(item.resolve, item.reject);
+      }
+    }
+  });
+
+  return (...params: ParamsType<ReducerDef>) => {
+    const conn = getConnection();
+    if (!conn) {
+      return new Promise<void>((resolve, reject) => {
+        queue.push({ params, resolve, reject });
+      });
+    }
+    const fn = (conn.reducers as any)[reducerName] as (
+      ...p: ParamsType<ReducerDef>
+    ) => Promise<void>;
+    return fn(...params);
+  };
+}

package/src/solid/useSpacetimeDB.ts

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'solid-js';
+import type { ConnectionState } from './connection_state';
+
+export const SpacetimeDBContext = createContext<ConnectionState | undefined>(
+  undefined
+);
+
+// Throws an error if used outside of a SpacetimeDBProvider
+// Error is caught by other hooks like useTable so they can provide better error messages
+export function useSpacetimeDB(): ConnectionState {
+  const context = useContext(SpacetimeDBContext) as ConnectionState | undefined;
+  if (!context) {
+    throw new Error(
+      'useSpacetimeDB must be used within a SpacetimeDBProvider component. Did you forget to add a `SpacetimeDBProvider` to your component tree?'
+    );
+  }
+  return context;
+}

package/src/solid/useTable.ts

@@ -0,0 +1,203 @@
+import { createSignal, onCleanup, createMemo, createComputed } from 'solid-js';
+import { useSpacetimeDB } from './useSpacetimeDB';
+import { type EventContextInterface } from '../sdk/db_connection_impl';
+import type { UntypedRemoteModule } from '../sdk/spacetime_module';
+import type { RowType, UntypedTableDef } from '../lib/table';
+import type { Prettify } from '../lib/type_util';
+import {
+  type Query,
+  type BooleanExpr,
+  toSql,
+  evaluateBooleanExpr,
+  getQueryAccessorName,
+  getQueryWhereClause,
+} from '../lib/query';
+import { createStore, reconcile } from 'solid-js/store';
+
+export interface UseTableCallbacks<RowType> {
+  onInsert?: (row: RowType) => void;
+  onDelete?: (row: RowType) => void;
+  onUpdate?: (oldRow: RowType, newRow: RowType) => void;
+  /** Whether the subscription is active. Defaults to `true`. */
+  enabled?: () => boolean;
+}
+
+type MembershipChange = 'enter' | 'leave' | 'stayIn' | 'stayOut';
+
+function classifyMembership(
+  whereExpr: BooleanExpr<any> | undefined,
+  oldRow: Record<string, any>,
+  newRow: Record<string, any>
+): MembershipChange {
+  if (!whereExpr) return 'stayIn';
+  const oldIn = evaluateBooleanExpr(whereExpr, oldRow);
+  const newIn = evaluateBooleanExpr(whereExpr, newRow);
+  if (oldIn && !newIn) return 'leave';
+  if (!oldIn && newIn) return 'enter';
+  if (oldIn && newIn) return 'stayIn';
+  return 'stayOut';
+}
+
+/**
+ * SolidJS primitive to subscribe to a table in SpacetimeDB and receive live updates.
+ *
+ * Accepts a query builder expression as the first argument:
+ * - `tables.user` — subscribe to all rows
+ * - `tables.user.where(r => r.online.eq(true))` — subscribe with a filter
+ *
+ * @param query - A query builder expression (table reference or filtered query).
+ * @param callbacks - Optional callbacks for row insert, delete, and update events.
+ * @returns A tuple of [rows, isReady].
+ *
+ * @example
+ * ```tsx
+ * const [rows, isReady] = useTable(tables.user);
+ * const [onlineUsers, isReady] = useTable(
+ *   tables.user.where(r => r.online.eq(true)),
+ *   { onInsert: (row) => console.log('New user:', row) }
+ * );
+ * ```
+ */
+export function useTable<TableDef extends UntypedTableDef>(
+  query: () => Query<TableDef>,
+  callbacks?: UseTableCallbacks<Prettify<RowType<TableDef>>>
+): [readonly Prettify<RowType<TableDef>>[], () => boolean] {
+  type UseTableRowType = RowType<TableDef>;
+  const enabled = callbacks?.enabled ?? (() => true);
+  const q = createMemo(query);
+  const accessorName = createMemo(() => getQueryAccessorName(q()));
+  const whereExpr = createMemo(() => getQueryWhereClause(q()));
+  const querySql = createMemo(() => toSql(q()));
+
+  let connectionState: import('./connection_state').ConnectionState;
+  try {
+    connectionState = useSpacetimeDB();
+  } catch {
+    throw new Error(
+      'Could not find SpacetimeDB client! Did you forget to add a ' +
+        '`SpacetimeDBProvider`? `useTable` must be used in the SolidJS component tree ' +
+        'under a `SpacetimeDBProvider` component.'
+    );
+  }
+
+  const [rows, setRows] = createStore<readonly Prettify<UseTableRowType>[]>([]);
+
+  let latestTransactionEventId: string | null = null;
+
+  const computeSnapshot = (): readonly Prettify<UseTableRowType>[] => {
+    if (!enabled()) {
+      return [];
+    }
+
+    const connection = connectionState.getConnection();
+    if (!connection) {
+      return [];
+    }
+    const table = connection.db[accessorName()];
+    const result: readonly Prettify<UseTableRowType>[] = whereExpr()
+      ? (Array.from(table.iter()).filter(row =>
+          evaluateBooleanExpr(whereExpr()!, row as Record<string, any>)
+        ) as Prettify<UseTableRowType>[])
+      : (Array.from(table.iter()) as Prettify<UseTableRowType>[]);
+    return result;
+  };
+
+  const [isReady, setIsReady] = createSignal(false);
+
+  createComputed(() => {
+    if (!enabled()) {
+      setIsReady(false);
+      return;
+    }
+
+    const connection = connectionState.getConnection();
+    if (!connectionState.isActive || !connection) {
+      setIsReady(false);
+      return;
+    }
+
+    const cancel = connection
+      .subscriptionBuilder()
+      .onApplied(() => {
+        setIsReady(true);
+      })
+      .subscribe(querySql());
+
+    onCleanup(() => {
+      cancel.unsubscribe();
+    });
+
+    // Bind to table events
+    const table = connection.db[accessorName()];
+
+    const onInsert = (
+      ctx: EventContextInterface<UntypedRemoteModule>,
+      row: any
+    ) => {
+      if (whereExpr() && !evaluateBooleanExpr(whereExpr()!, row)) {
+        return;
+      }
+      callbacks?.onInsert?.(row);
+      if (ctx.event.id !== latestTransactionEventId) {
+        latestTransactionEventId = ctx.event.id;
+        setRows(reconcile(computeSnapshot()));
+      }
+    };
+
+    const onDelete = (
+      ctx: EventContextInterface<UntypedRemoteModule>,
+      row: any
+    ) => {
+      if (whereExpr() && !evaluateBooleanExpr(whereExpr()!, row)) {
+        return;
+      }
+      callbacks?.onDelete?.(row);
+      if (ctx.event.id !== latestTransactionEventId) {
+        latestTransactionEventId = ctx.event.id;
+        setRows(reconcile(computeSnapshot()));
+      }
+    };
+
+    const onUpdate = (
+      ctx: EventContextInterface<UntypedRemoteModule>,
+      oldRow: any,
+      newRow: any
+    ) => {
+      const change = classifyMembership(whereExpr(), oldRow, newRow);
+
+      switch (change) {
+        case 'leave':
+          callbacks?.onDelete?.(oldRow);
+          break;
+        case 'enter':
+          callbacks?.onInsert?.(newRow);
+          break;
+        case 'stayIn':
+          callbacks?.onUpdate?.(oldRow, newRow);
+          break;
+        case 'stayOut':
+          return; // no-op
+      }
+
+      if (ctx.event.id !== latestTransactionEventId) {
+        latestTransactionEventId = ctx.event.id;
+        setRows(reconcile(computeSnapshot()));
+      }
+    };
+
+    table.onInsert(onInsert);
+    table.onDelete(onDelete);
+    table.onUpdate?.(onUpdate);
+
+    // Load initial snapshot
+    setRows(reconcile(computeSnapshot()));
+
+    onCleanup(() => {
+      table.removeOnInsert(onInsert);
+      table.removeOnDelete(onDelete);
+      table.removeOnUpdate?.(onUpdate);
+    });
+  });
+
+  return [rows, isReady];
+}