clockworklabs · cloutiertyler · Jan 3, 2025 · Dec 31, 2024 · Dec 31, 2024 · Dec 31, 2024
diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml
@@ -0,0 +1,26 @@
+name: Check Link Validity in Documentation
+
+on:
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16' # or the version of Node.js you're using
+
+      - name: Install dependencies
+        run: |
+          npm install
+
+      - name: Run link check
+        run: |
+          npm run check-links
diff --git a/.github/workflows/validate-nav-build.yml b/.github/workflows/validate-nav-build.yml
@@ -0,0 +1,40 @@
+name: Validate nav.ts Matches nav.js
+
+on:
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  validate-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      - name: Install dependencies
+        run: |
+          npm install
+
+      - name: Backup existing nav.js
+        run: |
+          mv docs/nav.js docs/nav.js.original
+
+      - name: Build nav.ts
+        run: |
+          npm run build
+
+      - name: Compare generated nav.js with original nav.js
+        run: |
+          diff -q docs/nav.js docs/nav.js.original || (echo "Generated nav.js differs from committed version. Run 'npm run build' and commit the updated file." && exit 1)
+
+      - name: Restore original nav.js
+        if: success() || failure()
+        run: |
+          mv docs/nav.js.original docs/nav.js
diff --git a/README.md b/README.md
@@ -32,6 +32,10 @@ git push -u origin a-branch-name-that-describes-my-change
 
 > NOTE! If you make a change to `nav.ts` you will have to run `npm run build` to generate a new `docs/nav.js` file.
 
+### Checking Links
+
+We have a CI job which validates internal links. You can run it locally with `npm run check-links`. This will print any internal links (i.e. links to other docs pages) whose targets do not exist, including fragment links (i.e. `#`-ey links to anchors).
+
 ## License
 
 This documentation repository is licensed under Apache 2.0. See LICENSE.txt for more details.
diff --git a/docs/bsatn.md b/docs/bsatn.md
@@ -24,12 +24,12 @@ To do this, we use inductive definitions, and define the following notation:
 
 ### At a glance
 
-| Type             | Description                                                      |
-| ---------------- | ---------------------------------------------------------------- |
-| `AlgebraicValue` | A value whose type may be any [`AlgebraicType`](#algebraictype). |
-| `SumValue`       | A value whose type is a [`SumType`](#sumtype).                   |
-| `ProductValue`   | A value whose type is a [`ProductType`](#producttype).           |
-| `BuiltinValue`   | A value whose type is a [`BuiltinType`](#builtintype).           |
+| Type                                | Description                                                           |
+|-------------------------------------|-----------------------------------------------------------------------|
+| [`AlgebraicValue`](#algebraicvalue) | A value of any type.                                                  |
+| [`SumValue`](#sumvalue)             | A value of a sum type, i.e. an enum or tagged union.                  |
+| [`ProductValue`](#productvalue)     | A value of a product type, i.e. a struct or tuple.                    |
+| [`BuiltinValue`](#builtinvalue)     | A value of a builtin type, including numbers, booleans and sequences. |
 
 ### `AlgebraicValue`
 
@@ -41,17 +41,17 @@ bsatn(AlgebraicValue) = bsatn(SumValue) | bsatn(ProductValue) | bsatn(BuiltinVal
 
 ### `SumValue`
 
-An instance of a [`SumType`](#sumtype).
+An instance of a sum type, i.e. an enum or tagged union.
 `SumValue`s are binary-encoded as `bsatn(tag) ++ bsatn(variant_data)`
-where `tag: u8` is an index into the [`SumType.variants`](#sumtype)
-array of the value's [`SumType`](#sumtype),
+where `tag: u8` is an index into the `SumType.variants`
+array of the value's `SumType`,
 and where `variant_data` is the data of the variant.
 For variants holding no data, i.e., of some zero sized type,
 `bsatn(variant_data) = []`.
 
 ### `ProductValue`
 
-An instance of a [`ProductType`](#producttype).
+An instance of a product type, i.e. a struct or tuple.
 `ProductValue`s are binary encoded as:
 
 ```fsharp
@@ -62,7 +62,8 @@ Field names are not encoded.
 
 ### `BuiltinValue`
 
-An instance of a [`BuiltinType`](#builtintype).
+An instance of a buil-in type.
+Built-in types include booleans, integers, floats, strings and arrays.
 The BSATN encoding of `BuiltinValue`s defers to the encoding of each variant:
 
 ```fsharp
@@ -73,7 +74,6 @@ bsatn(BuiltinValue)
     | bsatn(F32) | bsatn(F64)
     | bsatn(String)
     | bsatn(Array)
-    | bsatn(Map)
 
 bsatn(Bool(b)) = bsatn(b as u8)
 bsatn(U8(x)) = [x]
@@ -91,25 +91,19 @@ bsatn(F64(x: f64)) = bsatn(f64_to_raw_bits(x)) // lossless conversion
 bsatn(String(s)) = bsatn(len(s) as u32) ++ bsatn(bytes(s))
 bsatn(Array(a)) = bsatn(len(a) as u32)
                ++ bsatn(normalize(a)_0) ++ .. ++ bsatn(normalize(a)_n)
-bsatn(Map(map)) = bsatn(len(m) as u32)
-               ++ bsatn(key(map_0)) ++ bsatn(value(map_0))
-               ..
-               ++ bsatn(key(map_n)) ++ bsatn(value(map_n))
 ```
 
 Where
 
 - `f32_to_raw_bits(x)` is the raw transmute of `x: f32` to `u32`
 - `f64_to_raw_bits(x)` is the raw transmute of `x: f64` to `u64`
 - `normalize(a)` for `a: ArrayValue` converts `a` to a list of `AlgebraicValue`s
-- `key(map_i)` extracts the key of the `i`th entry of `map`
-- `value(map_i)` extracts the value of the `i`th entry of `map`
 
 ## Types
 
 All SATS types are BSATN-encoded by converting them to an `AlgebraicValue`,
 then BSATN-encoding that meta-value.
 
-See [the SATN JSON Format](/docs/satn-reference-json-format)
+See [the SATN JSON Format](/docs/satn)
 for more details of the conversion to meta values.
 Note that these meta values are converted to BSATN and _not JSON_.
diff --git a/docs/http/database.md b/docs/http/database.md
@@ -11,8 +11,6 @@ The HTTP endpoints in `/database` allow clients to interact with Spacetime datab
 | [`/database/set_name GET`](#databaseset_name-get)                                                                   | Set a database's name, given its address.                         |
 | [`/database/ping GET`](#databaseping-get)                                                                           | No-op. Used to determine whether a client can connect.            |
 | [`/database/register_tld GET`](#databaseregister_tld-get)                                                           | Register a top-level domain.                                      |
-| [`/database/request_recovery_code GET`](#databaserequest_recovery_code-get)                                         | Request a recovery code to the email associated with an identity. |
-| [`/database/confirm_recovery_code GET`](#databaseconfirm_recovery_code-get)                                         | Recover a login token from a recovery code.                       |
 | [`/database/publish POST`](#databasepublish-post)                                                                   | Publish a database given its module code.                         |
 | [`/database/delete/:address POST`](#databasedeleteaddress-post)                                                     | Delete a database.                                                |
 | [`/database/subscribe/:name_or_address GET`](#databasesubscribename_or_address-get)                                 | Begin a [WebSocket connection](/docs/ws).                         |
@@ -175,43 +173,6 @@ If the domain is already registered to another identity, returns JSON in the for
 } }
 ```
 
-## `/database/request_recovery_code GET`
-
-Request a recovery code or link via email, in order to recover the token associated with an identity.
-
-Accessible through the CLI as `spacetime identity recover <email> <identity>`.
-
-#### Query Parameters
-
-| Name       | Value                                                                                                                                                                                                                                                                                 |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `identity` | The identity whose token should be recovered.                                                                                                                                                                                                                                         |
-| `email`    | The email to send the recovery code or link to. This email must be associated with the identity, either during creation via [`/identity`](/docs/http/identity#identity-post) or afterwards via [`/identity/:identity/set-email`](/docs/http/identity#identityidentityset_email-post). |
-| `link`     | A boolean; whether to send a clickable link rather than a recovery code.                                                                                                                                                                                                              |
-
-## `/database/confirm_recovery_code GET`
-
-Confirm a recovery code received via email following a [`/database/request_recovery_code GET`](#-database-request_recovery_code-get) request, and retrieve the identity's token.
-
-Accessible through the CLI as `spacetime identity recover <email> <identity>`.
-
-#### Query Parameters
-
-| Name       | Value                                         |
-| ---------- | --------------------------------------------- |
-| `identity` | The identity whose token should be recovered. |
-| `email`    | The email which received the recovery code.   |
-| `code`     | The recovery code received via email.         |
-
-On success, returns JSON in the form:
-
-```typescript
-{
-    "identity": string,
-    "token": string
-}
-```
-
 ## `/database/publish POST`
 
 Publish a database.

diff --git a/docs/modules/c-sharp/quickstart.md b/docs/modules/c-sharp/quickstart.md
@@ -312,6 +312,6 @@ spacetime sql <module-name> "SELECT * FROM Message"
 
 ## What's next?
 
-You've just set up your first database in SpacetimeDB! The next step would be to create a client module that interacts with this module. You can use any of SpacetimDB's supported client languages to do this. Take a look at the quick start guide for your client language of choice: [Rust](/docs/languages/rust/rust-sdk-quickstart-guide), [C#](/docs/languages/csharp/csharp-sdk-quickstart-guide), or [TypeScript](/docs/languages/typescript/typescript-sdk-quickstart-guide).
+You've just set up your first database in SpacetimeDB! The next step would be to create a client module that interacts with this module. You can use any of SpacetimDB's supported client languages to do this. Take a look at the quick start guide for your client language of choice: [Rust](/docs/sdks/rust/quickstart), [C#](/docs/sdks/c-sharp/quickstart), or [TypeScript](/docs/sdks/typescript/quickstart).
 
 If you are planning to use SpacetimeDB with the Unity game engine, you can skip right to the [Unity Comprehensive Tutorial](/docs/unity/part-1) or check out our example game, [BitcraftMini](/docs/unity/part-3).
diff --git a/docs/nav.js b/docs/nav.js
@@ -1,12 +1,23 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 function page(title, slug, path, props) {
-    return { type: 'page', path, slug, title, ...props };
+    return __assign({ type: 'page', path: path, slug: slug, title: title }, props);
 }
 function section(title) {
-    return { type: 'section', title };
+    return { type: 'section', title: title };
 }
-const nav = {
+var nav = {
     items: [
         section('Intro'),
         page('Overview', 'index', 'index.md'), // TODO(BREAKING): For consistency & clarity, 'index' slug should be renamed 'intro'?

diff --git a/docs/satn.md b/docs/satn.md
@@ -34,7 +34,7 @@ The tag is an index into the [`SumType.variants`](#sumtype) array of the value's
 
 ### `ProductValue`
 
-An instance of a [`ProductType`](#producttype). `ProductValue`s are encoded as JSON arrays. Each element of the `ProductValue` array is of the type of the corresponding index in the [`ProductType.elements`](#productype) array of the value's [`ProductType`](#producttype).
+An instance of a [`ProductType`](#producttype). `ProductValue`s are encoded as JSON arrays. Each element of the `ProductValue` array is of the type of the corresponding index in the [`ProductType.elements`](#producttype) array of the value's [`ProductType`](#producttype).
 
 ```json
 array<AlgebraicValue>
@@ -69,7 +69,7 @@ All SATS types are JSON-encoded by converting them to an `AlgebraicValue`, then
 | --------------------------------------- | ------------------------------------------------------------------------------------ |
 | [`AlgebraicType`](#algebraictype)       | Any SATS type.                                                                       |
 | [`SumType`](#sumtype)                   | Sum types, i.e. tagged unions.                                                       |
-| [`ProductType`](#productype)            | Product types, i.e. structures.                                                      |
+| [`ProductType`](#producttype)            | Product types, i.e. structures.                                                      |
 | [`BuiltinType`](#builtintype)           | Built-in and primitive types, including booleans, numbers, strings, arrays and maps. |
 | [`AlgebraicTypeRef`](#algebraictyperef) | An indirect reference to a type, used to implement recursive types.                  |
 

diff --git a/docs/sdks/c-sharp/index.md b/docs/sdks/c-sharp/index.md
@@ -16,10 +16,10 @@ The SpacetimeDB client C# for Rust contains all the tools you need to build nati
     - [Method `SpacetimeDBClient.Connect`](#method-spacetimedbclientconnect)
     - [Event `SpacetimeDBClient.onIdentityReceived`](#event-spacetimedbclientonidentityreceived)
     - [Event `SpacetimeDBClient.onConnect`](#event-spacetimedbclientonconnect)
-  - [Query subscriptions & one-time actions](#subscribe-to-queries)
+  - [Subscribe to queries](#subscribe-to-queries)
     - [Method `SpacetimeDBClient.Subscribe`](#method-spacetimedbclientsubscribe)
     - [Event `SpacetimeDBClient.onSubscriptionApplied`](#event-spacetimedbclientonsubscriptionapplied)
-    - [Method `SpacetimeDBClient.OneOffQuery`](#method-spacetimedbclientoneoffquery)
+    - [Method \[`SpacetimeDBClient.OneOffQuery`\]](#method-spacetimedbclientoneoffquery)
   - [View rows of subscribed tables](#view-rows-of-subscribed-tables)
     - [Class `{TABLE}`](#class-table)
       - [Static Method `{TABLE}.Iter`](#static-method-tableiter)
@@ -45,7 +45,6 @@ The SpacetimeDB client C# for Rust contains all the tools you need to build nati
       - [Static Property `AuthToken.Token`](#static-property-authtokentoken)
       - [Static Method `AuthToken.SaveToken`](#static-method-authtokensavetoken)
     - [Class `Identity`](#class-identity)
-    - [Class `Identity`](#class-identity-1)
   - [Customizing logging](#customizing-logging)
     - [Interface `ISpacetimeDBLogger`](#interface-ispacetimedblogger)
     - [Class `ConsoleLogger`](#class-consolelogger)
@@ -104,7 +103,7 @@ The Unity SpacetimeDB SDK relies on there being a `NetworkManager` somewhere in
 
 ![Unity-AddNetworkManager](/images/unity-tutorial/Unity-AddNetworkManager.JPG)
 
-This component will handle updating and closing the [`SpacetimeDBClient.instance`](#property-spacetimedbclientinstance) for you, but will not call [`SpacetimeDBClient.Connect`](#method-spacetimedbclientconnect), you still need to handle that yourself. See the [Unity Quickstart](./UnityQuickStart) and [Unity Tutorial](./UnityTutorialPart1) for more information.
+This component will handle updating and closing the [`SpacetimeDBClient.instance`](#property-spacetimedbclientinstance) for you, but will not call [`SpacetimeDBClient.Connect`](#method-spacetimedbclientconnect), you still need to handle that yourself. See the [Unity Tutorial](/docs/unity-tutorial) for more information.
 
 ### Method `SpacetimeDBClient.Connect`
 
@@ -172,7 +171,7 @@ class SpacetimeDBClient {
 }
 ```
 
-Called when we receive an auth token, [`Identity`](#class-identity) and [`Address`](#class-address) from the server. The [`Identity`](#class-identity) serves as a unique public identifier for a user of the database. It can be for several purposes, such as filtering rows in a database for the rows created by a particular user. The auth token is a private access token that allows us to assume an identity. The [`Address`](#class-address) is opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#class-identity).
+Called when we receive an auth token, [`Identity`](#class-identity) and `Address` from the server. The [`Identity`](#class-identity) serves as a unique public identifier for a user of the database. It can be for several purposes, such as filtering rows in a database for the rows created by a particular user. The auth token is a private access token that allows us to assume an identity. The `Address` is opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#class-identity).
 
 To store the auth token to the filesystem, use the static method [`AuthToken.SaveToken`](#static-method-authtokensavetoken). You may also want to store the returned [`Identity`](#class-identity) in a local variable.
 

diff --git a/docs/sdks/rust/index.md b/docs/sdks/rust/index.md
@@ -149,7 +149,7 @@ impl DbConnection {
 
 `frame_tick` will advance the connection until no work remains, then return rather than blocking or `await`-ing. Games might arrange for this message to be called every frame. `frame_tick` returns `Ok` if the connection remains active afterwards, or `Err` if the connection disconnected before or during the call.
 
-## Trait `spacetimedb_sdk::DbContext`
+## Trait `DbContext`
 
 [`DbConnection`](#type-dbconnection) and [`EventContext`](#type-eventcontext) both implement `DbContext`, which allows 
 
@@ -185,7 +185,7 @@ impl SubscriptionBuilder {
 }
 ```
 
-Register a callback to run when the subscription is applied and the matching rows are inserted into the client cache. The [`EventContext`](#type-module_bindings-eventcontext) passed to the callback will have `Event::SubscribeApplied` as its `event`.
+Register a callback to run when the subscription is applied and the matching rows are inserted into the client cache. The [`EventContext`](#type-eventcontext) passed to the callback will have `Event::SubscribeApplied` as its `event`.
 
 #### Method `subscribe`