spacetimedb 2.0.4 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spacetimedb",
-  "version": "2.0.4",
+  "version": "2.2.0",
   "description": "API and ABI bindings for the SpacetimeDB TypeScript module library",
   "homepage": "https://github.com/clockworklabs/SpacetimeDB#readme",
   "bugs": {
@@ -94,7 +94,7 @@
       "name": "esm (gzip)",
       "path": "dist/index.mjs",
       "gzip": true,
-      "limit": "40 kB"
+      "limit": "48 kB"
     },
     {
       "name": "esm (uncompressed)",

package/src/lib/algebraic_type.ts

@@ -535,7 +535,11 @@ const view = reader.view;
 ${ty.elements
   .map(({ name, algebraicType: { tag } }) =>
     tag in primitiveJSName
-      ? `\
+      ? tag === 'Bool'
+        ? `\
+result.${name} = view.getUint8(reader.offset) !== 0;
+reader.offset += 1;`
+        : `\
 result.${name} = view.get${primitiveJSName[tag as JSPrimitives]}(reader.offset, ${primitiveSizes[tag] > 1 ? 'true' : ''});
 reader.offset += ${primitiveSizes[tag]};`
       : `result.${name} = reader.read${tag}();`

package/src/lib/binary_reader.ts

@@ -25,8 +25,11 @@ export default class BinaryReader {
     this.offset = 0;
   }
 
-  reset(view: DataView) {
-    this.view = view;
+  reset(input: Uint8Array | DataView) {
+    this.view =
+      input instanceof DataView
+        ? input
+        : new DataView(input.buffer, input.byteOffset, input.byteLength);
     this.offset = 0;
   }
 

package/src/lib/binary_writer.ts

@@ -63,7 +63,7 @@ export default class BinaryWriter {
     return fromByteArray(this.getBuffer());
   }
 
-  getBuffer(): Uint8Array {
+  getBuffer(): Uint8Array<ArrayBuffer> {
     return new Uint8Array(this.buffer.buffer, 0, this.offset);
   }
 
@@ -93,6 +93,12 @@ export default class BinaryWriter {
     this.offset += 1;
   }
 
+  writeBytes(value: Uint8Array): void {
+    this.expandBuffer(value.length);
+    new Uint8Array(this.buffer.buffer, this.offset, value.length).set(value);
+    this.offset += value.length;
+  }
+
   writeI8(value: number): void {
     this.expandBuffer(1);
     this.view.setInt8(this.offset, value);

package/src/lib/filter.ts

@@ -1,7 +1,8 @@
 import type { RowType, UntypedTableDef } from './table';
+import { Timestamp } from './timestamp';
 import { Uuid } from './uuid';
 
-export type Value = string | number | boolean | Uuid;
+export type Value = string | number | boolean | Uuid | Timestamp;
 
 export type Expr<Column extends string> =
   | { type: 'eq'; key: Column; value: Value }
@@ -77,6 +78,13 @@ export function evaluate<Column extends string>(
         if (v instanceof Uuid && typeof expr.value === 'string') {
           return v.toString() === expr.value;
         }
+
+        if (v instanceof Timestamp) {
+          // Value of the Column and passed Value are both Timestamps so compare microseconds.
+          if (expr.value instanceof Timestamp) {
+            return v.microsSinceUnixEpoch === expr.value.microsSinceUnixEpoch;
+          }
+        }
       }
       return false;
     }
@@ -103,6 +111,9 @@ function formatValue(v: Value): string {
       if (v instanceof Uuid) {
         return `'${v.toString()}'`;
       }
+      if (v instanceof Timestamp) {
+        return `'${v.toISOString()}'`;
+      }
 
       return '';
     }

package/src/lib/query.ts

@@ -348,7 +348,8 @@ function createRowExpr<TableDef extends TypedTableDef>(
       columnBuilder.typeBuilder.algebraicType as InferSpacetimeTypeOfColumn<
         TableDef,
         typeof columnName
-      >
+      >,
+      columnBuilder.columnMetadata.name
     );
     row[columnName] = Object.freeze(column);
   }
@@ -438,7 +439,10 @@ export class ColumnExpression<
   ColumnName extends ColumnNames<TableDef>,
 > {
   readonly type = 'column' as const;
+  // This is the column accessor
   readonly column: ColumnName;
+  // The name of the column in the database.
+  readonly columnName: string;
   readonly table: TableDef['sourceName'];
   // phantom: actual runtime value is undefined
   readonly tsValueType?: RowType<TableDef>[ColumnName];
@@ -447,10 +451,12 @@ export class ColumnExpression<
   constructor(
     table: TableDef['sourceName'],
     column: ColumnName,
-    spacetimeType: InferSpacetimeTypeOfColumn<TableDef, ColumnName>
+    spacetimeType: InferSpacetimeTypeOfColumn<TableDef, ColumnName>,
+    columnName?: string
   ) {
     this.table = table;
     this.column = column;
+    this.columnName = columnName || column;
     this.spacetimeType = spacetimeType;
   }
 
@@ -710,15 +716,38 @@ type BooleanExprData<Table extends TypedTableDef> = (
   _tableType?: Table;
 };
 
+type AndOrMixedTableScopeError = {
+  readonly 'Cannot combine predicates from different table scopes with and/or. In semijoin on(...), keep only the join equality and move extra predicates to .where(...).': never;
+};
+
+type RequireSameAndOrTable<
+  Expected extends TypedTableDef,
+  Actual extends TypedTableDef,
+> = [Expected] extends [Actual]
+  ? [Actual] extends [Expected]
+    ? unknown
+    : AndOrMixedTableScopeError
+  : AndOrMixedTableScopeError;
+
 export class BooleanExpr<Table extends TypedTableDef> {
   constructor(readonly data: BooleanExprData<Table>) {}
 
-  and(other: BooleanExpr<Table>): BooleanExpr<Table> {
-    return new BooleanExpr({ type: 'and', clauses: [this.data, other.data] });
+  and<OtherTable extends TypedTableDef>(
+    other: BooleanExpr<OtherTable> & RequireSameAndOrTable<Table, OtherTable>
+  ): BooleanExpr<Table> {
+    return new BooleanExpr({
+      type: 'and',
+      clauses: [this.data, other.data as BooleanExprData<Table>],
+    });
   }
 
-  or(other: BooleanExpr<Table>): BooleanExpr<Table> {
-    return new BooleanExpr({ type: 'or', clauses: [this.data, other.data] });
+  or<OtherTable extends TypedTableDef>(
+    other: BooleanExpr<OtherTable> & RequireSameAndOrTable<Table, OtherTable>
+  ): BooleanExpr<Table> {
+    return new BooleanExpr({
+      type: 'or',
+      clauses: [this.data, other.data as BooleanExprData<Table>],
+    });
   }
 
   not(): BooleanExpr<Table> {
@@ -732,28 +761,40 @@ export function not<T extends TypedTableDef>(
   return new BooleanExpr({ type: 'not', clause: clause.data });
 }
 
-export function and<T extends TypedTableDef>(
-  ...clauses: readonly [BooleanExpr<T>, BooleanExpr<T>, ...BooleanExpr<T>[]]
-): BooleanExpr<T> {
+export function and<
+  Table extends TypedTableDef,
+  OtherTable extends TypedTableDef,
+>(
+  first: BooleanExpr<Table>,
+  second: BooleanExpr<OtherTable> & RequireSameAndOrTable<Table, OtherTable>,
+  ...rest: readonly BooleanExpr<Table>[]
+): BooleanExpr<Table> {
+  const clauses = [first, second, ...rest];
   return new BooleanExpr({
     type: 'and',
     clauses: clauses.map(c => c.data) as [
-      BooleanExprData<T>,
-      BooleanExprData<T>,
-      ...BooleanExprData<T>[],
+      BooleanExprData<Table>,
+      BooleanExprData<Table>,
+      ...BooleanExprData<Table>[],
     ],
   });
 }
 
-export function or<T extends TypedTableDef>(
-  ...clauses: readonly [BooleanExpr<T>, BooleanExpr<T>, ...BooleanExpr<T>[]]
-): BooleanExpr<T> {
+export function or<
+  Table extends TypedTableDef,
+  OtherTable extends TypedTableDef,
+>(
+  first: BooleanExpr<Table>,
+  second: BooleanExpr<OtherTable> & RequireSameAndOrTable<Table, OtherTable>,
+  ...rest: readonly BooleanExpr<Table>[]
+): BooleanExpr<Table> {
+  const clauses = [first, second, ...rest];
   return new BooleanExpr({
     type: 'or',
     clauses: clauses.map(c => c.data) as [
-      BooleanExprData<T>,
-      BooleanExprData<T>,
-      ...BooleanExprData<T>[],
+      BooleanExprData<Table>,
+      BooleanExprData<Table>,
+      ...BooleanExprData<Table>[],
     ],
   });
 }
@@ -803,7 +844,7 @@ function valueExprToSql<Table extends TypedTableDef>(
     return literalValueToSql(expr.value);
   }
   const table = tableAlias ?? expr.table;
-  return `${quoteIdentifier(table)}.${quoteIdentifier(expr.column)}`;
+  return `${quoteIdentifier(table)}.${quoteIdentifier(expr.columnName)}`;
 }
 
 function literalValueToSql(value: unknown): string {

package/src/lib/table.ts

@@ -239,7 +239,12 @@ export type ReadonlyTable<TableDef extends UntypedTableDef> = Prettify<
 >;
 
 export interface ReadonlyTableMethods<TableDef extends UntypedTableDef> {
-  /** Returns the number of rows in the TX state. */
+  /**
+   * Returns the number of rows in this table.
+   *
+   * This reads datastore metadata, so it runs in constant time.
+   * It also takes into account modifications by the current transaction.
+   */
   count(): bigint;
 
   /** Iterate over all rows in the TX state. Rust Iterator<Item=Row> → TS IterableIterator<Row>. */
@@ -263,6 +268,13 @@ export interface TableMethods<TableDef extends UntypedTableDef>
 
   /** Delete a row equal to `row`. Returns true if something was deleted. */
   delete(row: Prettify<RowType<TableDef>>): boolean;
+
+  /**
+   * Clears the table of all rows.
+   * Returns the number of rows deleted,
+   * i.e., the return value of `this.count()` before this call.
+   */
+  clear(): bigint;
 }
 
 /**
@@ -399,7 +411,8 @@ export function table<Row extends RowObj, const Opts extends TableOpts<Row>>(
       });
     }
 
-    if (meta.defaultValue) {
+    // Check for defaultValue on the property to allow for 0, false, '', and undefined as defaults
+    if (Object.prototype.hasOwnProperty.call(meta, 'defaultValue')) {
       const writer = new BinaryWriter(16);
       builder.serialize(writer, meta.defaultValue);
       defaultValues.push({

package/src/react/index.ts

@@ -2,3 +2,4 @@ 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/react/useProcedure.ts

@@ -0,0 +1,60 @@
+import { useCallback, useEffect, useRef } from 'react';
+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 queueRef = useRef<
+    {
+      params: ProcedureParamsType<ProcedureDef>;
+      resolve: (val: any) => void;
+      reject: (err: unknown) => void;
+    }[]
+  >([]);
+
+  // Flush when we finally have a connection
+  useEffect(() => {
+    const conn = getConnection();
+    if (!conn) {
+      return;
+    }
+    const fn = (conn.procedures as any)[procedureName] as (
+      ...p: ProcedureParamsType<ProcedureDef>
+    ) => Promise<ProcedureReturnType<ProcedureDef>>;
+    if (queueRef.current.length) {
+      const pending = queueRef.current.splice(0);
+      for (const item of pending) {
+        fn(...item.params).then(item.resolve, item.reject);
+      }
+    }
+  }, [getConnection, procedureName, isActive]);
+
+  return useCallback(
+    (...params: ProcedureParamsType<ProcedureDef>) => {
+      const conn = getConnection();
+      if (!conn) {
+        return new Promise<ProcedureReturnType<ProcedureDef>>(
+          (resolve, reject) => {
+            queueRef.current.push({ params, resolve, reject });
+          }
+        );
+      }
+      const fn = (conn.procedures as any)[procedureName] as (
+        ...p: ProcedureParamsType<ProcedureDef>
+      ) => Promise<ProcedureReturnType<ProcedureDef>>;
+      return fn(...params);
+    },
+    [getConnection, procedureName]
+  );
+}

package/src/react/useTable.ts

@@ -24,6 +24,8 @@ 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';
@@ -67,6 +69,7 @@ export function useTable<TableDef extends UntypedTableDef>(
   callbacks?: UseTableCallbacks<Prettify<RowType<TableDef>>>
 ): [readonly Prettify<RowType<TableDef>>[], boolean] {
   type UseTableRowType = RowType<TableDef>;
+  const enabled = callbacks?.enabled ?? true;
   const accessorName = getQueryAccessorName(query);
   const whereExpr = getQueryWhereClause(query);
 
@@ -93,6 +96,9 @@ export function useTable<TableDef extends UntypedTableDef>(
     readonly Prettify<UseTableRowType>[],
     boolean,
   ] => {
+    if (!enabled) {
+      return [[], true];
+    }
     const connection = connectionState.getConnection();
     if (!connection) {
       return [[], false];
@@ -104,8 +110,10 @@ export function useTable<TableDef extends UntypedTableDef>(
         ) as Prettify<UseTableRowType>[])
       : (Array.from(table.iter()) as Prettify<UseTableRowType>[]);
     return [result, subscribeApplied];
+    // TODO: investigating refactoring so that this is no longer necessary, as we have had genuine bugs with missed deps.
+    // See https://github.com/clockworklabs/SpacetimeDB/pull/4580.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [connectionState, accessorName, querySql, subscribeApplied]);
+  }, [connectionState, accessorName, querySql, subscribeApplied, enabled]);
 
   // Invalidate the cached snapshot when computeSnapshot changes (e.g. when
   // subscribeApplied flips to true) so getSnapshot() recomputes on the next
@@ -115,6 +123,10 @@ export function useTable<TableDef extends UntypedTableDef>(
   }, [computeSnapshot]);
 
   useEffect(() => {
+    if (!enabled) {
+      setSubscribeApplied(false);
+      return;
+    }
     const connection = connectionState.getConnection()!;
     if (connectionState.isActive && connection) {
       const cancel = connection
@@ -127,10 +139,14 @@ export function useTable<TableDef extends UntypedTableDef>(
         cancel.unsubscribe();
       };
     }
-  }, [querySql, connectionState.isActive, connectionState]);
+  }, [querySql, connectionState.isActive, connectionState, enabled]);
 
   const subscribe = useCallback(
     (onStoreChange: () => void) => {
+      if (!enabled) {
+        return () => {};
+      }
+
       const onInsert = (
         ctx: EventContextInterface<UntypedRemoteModule>,
         row: any
@@ -205,14 +221,18 @@ export function useTable<TableDef extends UntypedTableDef>(
         table.removeOnUpdate?.(onUpdate);
       };
     },
+    // TODO: investigating refactoring so that this is no longer necessary, as we have had genuine bugs with missed deps.
+    // See https://github.com/clockworklabs/SpacetimeDB/pull/4580.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
       connectionState,
       accessorName,
       querySql,
+      computeSnapshot,
       callbacks?.onDelete,
       callbacks?.onInsert,
       callbacks?.onUpdate,
+      enabled,
     ]
   );
 

package/src/sdk/db_connection_builder.ts

@@ -8,6 +8,7 @@ import type {
 } from '../';
 import { ensureMinimumVersionOrThrow } from './version';
 import { WebsocketDecompressAdapter } from './websocket_decompress_adapter';
+import type { WebSocketFactory } from './ws';
 
 /**
  * The database client connection to a SpacetimeDB server.
@@ -23,10 +24,10 @@ export class DbConnectionBuilder<DbConnection extends DbConnectionImpl<any>> {
   #identity?: Identity;
   #token?: string;
   #emitter: EventEmitter<ConnectionEvent> = new EventEmitter();
-  #compression: 'gzip' | 'none' = 'gzip';
+  #compression: 'gzip' | 'brotli' | 'none' = 'gzip';
   #lightMode: boolean = false;
   #confirmedReads?: boolean;
-  #createWSFn: typeof WebsocketDecompressAdapter.createWebSocketFn;
+  #createWSFn: WebSocketFactory;
 
   /**
    * Creates a new `DbConnectionBuilder` database client and set the initial parameters.
@@ -42,7 +43,7 @@ export class DbConnectionBuilder<DbConnection extends DbConnectionImpl<any>> {
       config: DbConnectionConfig<RemoteModuleOf<DbConnection>>
     ) => DbConnection
   ) {
-    this.#createWSFn = WebsocketDecompressAdapter.createWebSocketFn;
+    this.#createWSFn = WebsocketDecompressAdapter.openWebSocket;
   }
 
   /**
@@ -82,9 +83,7 @@ export class DbConnectionBuilder<DbConnection extends DbConnectionImpl<any>> {
     return this;
   }
 
-  withWSFn(
-    createWSFn: typeof WebsocketDecompressAdapter.createWebSocketFn
-  ): this {
+  withWSFn(createWSFn: WebSocketFactory): this {
     this.#createWSFn = createWSFn;
     return this;
   }
@@ -94,7 +93,17 @@ export class DbConnectionBuilder<DbConnection extends DbConnectionImpl<any>> {
    *
    * @param compression The compression algorithm to use for the connection.
    */
-  withCompression(compression: 'gzip' | 'none'): this {
+  withCompression(compression: 'gzip' | 'brotli' | 'none'): this {
+    if (compression === 'brotli') {
+      try {
+        new DecompressionStream('brotli' as CompressionFormat);
+      } catch (e) {
+        throw new TypeError(
+          `Brotli compression is not supported by the runtime. Please choose a different compression method.`,
+          { cause: e }
+        );
+      }
+    }
     this.#compression = compression;
     return this;
   }