Add TypeScript submodule support for SpacetimeDB modules (#5486)

Add TypeScript submodule support for SpacetimeDB modules

# Description of Changes

- TypeScript server SDK: runtime API for module mounting (submodules),
including namespaced dispatch, ctx.as helpers for cross-namespace calls,
and HTTP handler delegation
- TypeScript client codegen: namespace-aware table/reducer/procedure
exports and query builder for submodule tables and views
- Migrations: auto-migrate support for submodule tables, views, and
indexes; AddConstraint step added alongside NamespacedIdentifier-based
migration steps
- CLI: namespace support for `spacetime call` and `spacetime sql`
- C++/C# bindings: autogenerated RawSubmoduleV10 types
- module-test-ts: submodule integration test (lib_submodule)

# API and ABI breaking changes

Adds a submodule field to ModuleDef. Older modules will be publishable
to new servers, but new modules that have submodules will not be
publishable to old servers.

# Expected complexity level and risk

5

# Testing
Beyond the rust tests defined in this PR, the following tests were done
on the full PR sequence once the entire namespace feature was
implemented for typescript:
 Feature Test Checklist

Module:
- [x] root module can import another module and mount it with a
namespace under its schema
- [x] root module and submodule can have the same function and table
names without conflicting
- [x] ctx.db.lib.lib_table is readable/writable inside root module
reducer
- [x] ctx.db.lib.lib_table is readable/writable inside root module
procedure withTx block
- [x] library_reducer(ctx.as.lib) is callable inside root module reducer

Client
- [x] Client can subscribe to lib.library_table
- [x] Client can subscribe to lib.library_view
- [x] Client can call lib/library_reducer
- [x] Client can call lib/library_procedure
- [x] Client can subscribe to lib.sublib.sublib_table
- [x] Client can subscribe to lib.sublib.sublib_view
- [x] Client can call lib/sublib/sublib_reducer
- [x] Client can call lib/sublib/sublib_procedure

CLI
- [x] CLI can subscribe to lib.library_table
- [x] CLI can subscribe to lib.library_view
- [x] CLI can call lib/library_reducer
- [x] CLI can call lib/library_procedure
- [x] CLI can subscribe to lib.sublib.sublib_table
- [x] CLI can subscribe to lib.sublib.sublib_view
- [x] CLI can call lib/sublib/sublib_reducer
- [x] CLI can call lib/sublib/sublib_procedure

Migration
- [x] Module migrates without issue from having a submodule to not
having a submodule
- [x] Module migrates without issue from not having a submodule to
having a submodule
- [x] Module migrates without issue when having a submodule and root
module change occurs (change reducer signature, add table, add column
with default, change reducer function body, change index)
- [x] Module migrates without issue when having a submodule and a
submodule change occurs (change reducer signature, add table, add column
with default, change reducer function body, change index)

Commit Log
- [x] Module loads fine from commit log
- [x] Module snapshot is created without issue
- [x] Module loads fine from snapshot

---------

Co-authored-by: Tyler Cloutier <cloutiertyler@aol.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

Author: 4 people

.github/workflows/ci.yml

@@ -528,6 +528,13 @@ jobs:
           save-if: false
           prefix-key: v1
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - uses: ./.github/actions/setup-pnpm
+
       - name: Run bindgen tests
         run: cargo ci wasm-bindings
 

crates/bench/src/spacetime_raw.rs

@@ -69,7 +69,7 @@ impl BenchDatabase for SpacetimeRaw {
                             IndexSchema {
                                 index_id: IndexId::SENTINEL,
                                 table_id,
-                                index_name: column.name.clone().unwrap(),
+                                index_name: column.name.clone().unwrap().into(),
                                 index_algorithm: IndexAlgorithm::BTree(BTreeAlgorithm {
                                     columns: ColId(i as _).into(),
                                 }),

crates/bindings-cpp/include/spacetimedb/internal/autogen/RawModuleDefV10Section.g.h

@@ -12,22 +12,23 @@
 #include <memory>
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
-#include "RawViewPrimaryKeyDefV10.g.h"
 #include "RawTableDefV10.g.h"
-#include "RawViewDefV10.g.h"
-#include "RawScheduleDefV10.g.h"
-#include "CaseConversionPolicy.g.h"
-#include "RawRowLevelSecurityDefV9.g.h"
-#include "RawHttpRouteDefV10.g.h"
-#include "RawReducerDefV10.g.h"
 #include "Typespace.g.h"
 #include "RawLifeCycleReducerDefV10.g.h"
-#include "ExplicitNames.g.h"
-#include "RawHttpHandlerDefV10.g.h"
+#include "RawReducerDefV10.g.h"
 #include "RawTypeDefV10.g.h"
+#include "RawRowLevelSecurityDefV9.g.h"
+#include "RawHttpRouteDefV10.g.h"
+#include "RawSubmoduleV10.g.h"
+#include "RawViewDefV10.g.h"
+#include "ExplicitNames.g.h"
 #include "RawProcedureDefV10.g.h"
+#include "CaseConversionPolicy.g.h"
+#include "RawScheduleDefV10.g.h"
+#include "RawViewPrimaryKeyDefV10.g.h"
+#include "RawHttpHandlerDefV10.g.h"
 
 namespace SpacetimeDB::Internal {
 
-SPACETIMEDB_INTERNAL_TAGGED_ENUM(RawModuleDefV10Section, SpacetimeDB::Internal::Typespace, std::vector<SpacetimeDB::Internal::RawTypeDefV10>, std::vector<SpacetimeDB::Internal::RawTableDefV10>, std::vector<SpacetimeDB::Internal::RawReducerDefV10>, std::vector<SpacetimeDB::Internal::RawProcedureDefV10>, std::vector<SpacetimeDB::Internal::RawViewDefV10>, std::vector<SpacetimeDB::Internal::RawScheduleDefV10>, std::vector<SpacetimeDB::Internal::RawLifeCycleReducerDefV10>, std::vector<SpacetimeDB::Internal::RawRowLevelSecurityDefV9>, SpacetimeDB::Internal::CaseConversionPolicy, SpacetimeDB::Internal::ExplicitNames, std::vector<SpacetimeDB::Internal::RawHttpHandlerDefV10>, std::vector<SpacetimeDB::Internal::RawHttpRouteDefV10>, std::vector<SpacetimeDB::Internal::RawViewPrimaryKeyDefV10>)
+SPACETIMEDB_INTERNAL_TAGGED_ENUM(RawModuleDefV10Section, SpacetimeDB::Internal::Typespace, std::vector<SpacetimeDB::Internal::RawTypeDefV10>, std::vector<SpacetimeDB::Internal::RawTableDefV10>, std::vector<SpacetimeDB::Internal::RawReducerDefV10>, std::vector<SpacetimeDB::Internal::RawProcedureDefV10>, std::vector<SpacetimeDB::Internal::RawViewDefV10>, std::vector<SpacetimeDB::Internal::RawScheduleDefV10>, std::vector<SpacetimeDB::Internal::RawLifeCycleReducerDefV10>, std::vector<SpacetimeDB::Internal::RawRowLevelSecurityDefV9>, SpacetimeDB::Internal::CaseConversionPolicy, SpacetimeDB::Internal::ExplicitNames, std::vector<SpacetimeDB::Internal::RawHttpHandlerDefV10>, std::vector<SpacetimeDB::Internal::RawHttpRouteDefV10>, std::vector<SpacetimeDB::Internal::RawViewPrimaryKeyDefV10>, std::vector<SpacetimeDB::Internal::RawSubmoduleV10>)
 } // namespace SpacetimeDB::Internal

crates/bindings-cpp/include/spacetimedb/internal/autogen/RawSubmoduleV10.g.h

@@ -0,0 +1,32 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+// This was generated using spacetimedb codegen.
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+#include <optional>
+#include <memory>
+#include "../autogen_base.h"
+#include "spacetimedb/bsatn/bsatn.h"
+
+namespace SpacetimeDB::Internal {
+struct RawModuleDefV10;
+} // namespace SpacetimeDB::Internal
+
+namespace SpacetimeDB::Internal {
+
+SPACETIMEDB_INTERNAL_PRODUCT_TYPE(RawSubmoduleV10) {
+    std::string namespace_;
+    std::shared_ptr<SpacetimeDB::Internal::RawModuleDefV10> module;
+
+    void bsatn_serialize(::SpacetimeDB::bsatn::Writer& writer) const {
+        ::SpacetimeDB::bsatn::serialize(writer, namespace_);
+        ::SpacetimeDB::bsatn::serialize(writer, *module);
+    }
+    SPACETIMEDB_PRODUCT_TYPE_EQUALITY(namespace_, module)
+};
+} // namespace SpacetimeDB::Internal

crates/bindings-csharp/Runtime/Internal/Autogen/RawModuleDefV10Section.g.cs

@@ -2,6 +2,7 @@ import { ConnectionId } from './connection_id';
 import { Identity } from './identity';
 import type { ColumnIndex, IndexColumns, IndexOpts } from './indexes';
 import type { UntypedSchemaDef } from './schema';
+import type { UntypedTableDef } from './table';
 import type { UntypedTableSchema } from './table_schema';
 import { Timestamp } from './timestamp';
 import type {
@@ -223,6 +224,26 @@ export type QueryBuilder<SchemaDef extends UntypedSchemaDef> = {
   > as Tbl['accessorName']]: TableRef<Tbl> & From<Tbl>;
 } & {};
 
+/**
+ * Like `QueryBuilder`, but with declared namespaces also exposed as sub-objects.
+ * This is the type of the `tables` argument in a `subscribe` query-builder callback.
+ *
+ * Root-level tables appear as direct properties (same as `QueryBuilder`).
+ * Declared namespaces appear as sub-objects — each is itself a `QueryBuilder` for that
+ * namespace's schema, so `tables.<namespace>.<table>` is fully typed.
+ *
+ * When `SchemaDef['namespaces']` is absent or `{}`, no namespace properties appear —
+ * accessing an undeclared namespace is a compile error.
+ */
+export type NamespacedQueryBuilder<SchemaDef extends UntypedSchemaDef> =
+  QueryBuilder<SchemaDef> & {
+    readonly [NS in keyof NonNullable<SchemaDef['namespaces']>]: NonNullable<
+      SchemaDef['namespaces']
+    >[NS] extends UntypedSchemaDef
+      ? QueryBuilder<NonNullable<SchemaDef['namespaces']>[NS]>
+      : never;
+  };
+
 /**
  * A runtime reference to a table. This materializes the RowExpr for us.
  * TODO: Maybe add the full SchemaDef to the type signature depending on how joins will work.
@@ -335,6 +356,42 @@ export function makeQueryBuilder<SchemaDef extends UntypedSchemaDef>(
   return Object.freeze(qb) as QueryBuilder<SchemaDef>;
 }
 
+/**
+ * Builds the namespace-aware `tables` object passed to `subscribe`'s query-builder callback.
+ *
+ * Tables whose `sourceName` contains no `.` are placed at the root.
+ * Tables with a dotted `sourceName` (e.g. `"namespace.table"`) are grouped under a
+ * sub-object keyed by the namespace alias, with the part after the dot as the
+ * property key within that namespace.
+ */
+export function makeFromBuilder<SchemaDef extends UntypedSchemaDef>(
+  tables: SchemaDef['tables']
+): NamespacedQueryBuilder<SchemaDef> {
+  const result: Record<string, unknown> = Object.create(null);
+  const namespaces: Record<string, Record<string, unknown>> = Object.create(
+    null
+  );
+
+  for (const table of Object.values(tables) as UntypedTableDef[]) {
+    const dotIdx = table.sourceName.indexOf('.');
+    if (dotIdx === -1) {
+      result[table.accessorName] = createTableRefFromDef(table as any);
+    } else {
+      const ns = table.sourceName.slice(0, dotIdx);
+      const key = table.sourceName.slice(dotIdx + 1);
+      (namespaces[ns] ??= Object.create(null))[key] = createTableRefFromDef(
+        table as any
+      );
+    }
+  }
+
+  for (const [ns, nsTables] of Object.entries(namespaces)) {
+    result[ns] = Object.freeze(nsTables);
+  }
+
+  return Object.freeze(result) as unknown as NamespacedQueryBuilder<SchemaDef>;
+}
+
 function createRowExpr<TableDef extends TypedTableDef>(
   tableDef: TableDef
 ): RowExpr<TableDef> {
@@ -879,7 +936,10 @@ function literalValueToSql(value: unknown): string {
 }
 
 function quoteIdentifier(name: string): string {
-  return `"${name.replace(/"/g, '""')}"`;
+  return name
+    .split('.')
+    .map(part => `"${part.replace(/"/g, '""')}"`)
+    .join('.');
 }
 
 function isLiteralExpr<Value>(

crates/bindings-csharp/Runtime/Internal/Autogen/RawSubmoduleV10.g.cs

@@ -98,6 +98,12 @@ export interface JwtClaims {
   readonly fullPayload: JsonObject;
 }
 
+export type AliasViews<SchemaDef extends UntypedSchemaDef> = SchemaDef extends {
+  namespaces: infer NS extends Record<string, UntypedSchemaDef>;
+}
+  ? { readonly [K in keyof NS]: ReducerCtx<NS[K]> }
+  : {};
+
 /**
  * Reducer context parametrized by the inferred Schema
  */
@@ -113,4 +119,5 @@ export type ReducerCtx<SchemaDef extends UntypedSchemaDef> = Readonly<{
   newUuidV4(): Uuid;
   newUuidV7(): Uuid;
   random: Random;
+  as: AliasViews<SchemaDef>;
 }>;

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

@@ -7,6 +7,7 @@ import {
 } from './algebraic_type';
 import type {
   CaseConversionPolicy,
+  RawSubmoduleV10,
   RawModuleDefV10,
   RawModuleDefV10Section,
   RawScopedTypeNameV10,
@@ -42,6 +43,7 @@ export type TableNamesOf<S extends UntypedSchemaDef> = Values<
  */
 export type UntypedSchemaDef = {
   tables: Record<string, UntypedTableDef>;
+  namespaces?: Record<string, UntypedSchemaDef>;
 };
 
 /**
@@ -202,6 +204,7 @@ export class ModuleContext {
     explicitNames: {
       entries: [],
     },
+    submodules: [],
   };
 
   get moduleDef(): ModuleDef {
@@ -266,9 +269,19 @@ export class ModuleContext {
         value: module.caseConversionPolicy,
       }
     );
+    push(
+      module.submodules && {
+        tag: 'Submodules',
+        value: module.submodules,
+      }
+    );
     return { sections };
   }
 
+  addSubmodule(submodule: RawSubmoduleV10) {
+    this.#moduleDef.submodules.push(submodule);
+  }
+
   /**
    * Set the case conversion policy for this module.
    * Called by the settings mechanism.