spacetimedb 2.4.1 → 2.5.0

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];
+}