diff --git a/content/docs/00-introduction/00-overview.md b/content/docs/00-introduction/00-overview.md index d57d9f7..61eaa86 100644 --- a/content/docs/00-introduction/00-overview.md +++ b/content/docs/00-introduction/00-overview.md @@ -12,7 +12,7 @@ You can find the instructions to install the CLI tool for your platform [here](/ To get started running your own standalone instance of SpacetimeDB check out our [Getting Started Guide](/docs/introduction/getting-started). - + ## What is SpacetimeDB? @@ -54,7 +54,7 @@ Each identity has a corresponding authentication token. The authentication token Additionally, each database has an owner `Identity`. Many database maintenance operations, like publishing a new version or evaluating arbitrary SQL queries, are restricted to only authenticated connections by the owner. -SpacetimeDB provides tools in the CLI and the [client SDKs](/docs/sdks) for managing credentials. +SpacetimeDB provides tools in the CLI and the [client SDKs](/docs/sdk/overview) for managing credentials. ## Addresses @@ -70,8 +70,8 @@ Each client connection has an `Address`. These addresses are opaque, and do not Currently, Rust is the best-supported language for writing SpacetimeDB modules. Support for lots of other languages is in the works! -- [Rust](/docs/modules/rust) - [(Quickstart)](/docs/modules/rust/quickstart) -- [C#](/docs/modules/c-sharp) - [(Quickstart)](/docs/modules/c-sharp/quickstart) +- [Rust](/docs/module/rust-reference) - [(Quickstart)](/docs/module/rust-quickstart) +- [C#](/docs/module/c-sharp-reference) - [(Quickstart)](/docs/module/c-sharp-quickstart) - Python (Coming soon) - Typescript (Coming soon) - C++ (Planned) @@ -79,16 +79,16 @@ Currently, Rust is the best-supported language for writing SpacetimeDB modules. ### Client-side SDKs -- [Rust](/docs/sdks/rust) - [(Quickstart)](/docs/sdks/rust/quickstart) -- [C#](/docs/sdks/c-sharp) - [(Quickstart)](/docs/sdks/c-sharp/quickstart) -- [TypeScript](/docs/sdks/typescript) - [(Quickstart)](/docs/sdks/typescript/quickstart) +- [Rust](/docs/sdk/rust-reference) - [(Quickstart)](/docs/sdk/rust-quickstart) +- [C#](/docs/sdk/c-sharp-reference) - [(Quickstart)](/docs/sdk/c-sharp-quickstart) +- [TypeScript](/docs/sdk/typescript-reference) - [(Quickstart)](/docs/sdk/typescript-quickstart) - Python (Planned) - C++ (Planned) - Lua (Planned) ### Unity -SpacetimeDB was designed first and foremost as the backend for multiplayer Unity games. To learn more about using SpacetimeDB with Unity, jump on over to the [SpacetimeDB Unity Tutorial](/docs/unity/part-1). +SpacetimeDB was designed first and foremost as the backend for multiplayer Unity games. To learn more about using SpacetimeDB with Unity, jump on over to the [SpacetimeDB Unity Tutorial](/docs/unity-tutorial/part-1). ## FAQ @@ -102,7 +102,7 @@ SpacetimeDB was designed first and foremost as the backend for multiplayer Unity Just install our command line tool and then upload your application to the cloud. 1. How do I create a new database with SpacetimeDB? - Follow our [Quick Start](/docs/getting-started) guide! + Follow our [Quick Start](/docs/introduction/getting-started) guide! TL;DR in an empty directory: @@ -112,7 +112,7 @@ spacetime publish ``` 5. How do I create a Unity game with SpacetimeDB? - Follow our [Unity Project](/docs/unity-tutorial) guide! + Follow our [Unity Project](/docs/unity-tutorial/overview) guide! TL;DR in an empty directory: diff --git a/content/docs/00-introduction/10-getting-started.md b/content/docs/00-introduction/10-getting-started.md index ad5578c..38028b1 100644 --- a/content/docs/00-introduction/10-getting-started.md +++ b/content/docs/00-introduction/10-getting-started.md @@ -22,14 +22,14 @@ You are ready to start developing SpacetimeDB modules. See below for a quickstar ### Server (Module) -- [Rust](/docs/modules/rust/quickstart) -- [C#](/docs/modules/c-sharp/quickstart) +- [Rust](/docs/module/rust-quickstart) +- [C#](/docs/module/c-sharp-quickstart) ⚡**Note:** Rust is [roughly 2x faster](https://faun.dev/c/links/faun/c-vs-rust-vs-go-a-performance-benchmarking-in-kubernetes/) than C# ### Client -- [Rust](/docs/sdks/rust/quickstart) -- [C# (Standalone)](/docs/sdks/c-sharp/quickstart) -- [C# (Unity)](/docs/unity/part-1) -- [Typescript](/docs/sdks/typescript/quickstart) +- [Rust](/docs/sdk/rust-quickstart) +- [C# (Standalone)](/docs/sdk/c-sharp-quickstart) +- [C# (Unity)](/docs/unity-tutorial/part-1) +- [Typescript](/docs/sdk/typescript-quickstart) diff --git a/content/docs/02-unity-tutorial/00-overview.md b/content/docs/02-unity-tutorial/00-overview.md index 40d0d32..86d678f 100644 --- a/content/docs/02-unity-tutorial/00-overview.md +++ b/content/docs/02-unity-tutorial/00-overview.md @@ -13,16 +13,16 @@ Tested with UnityEngine `2022.3.20f1 LTS` (and may also work on newer versions). ## Unity Tutorial - Basic Multiplayer -Get started with the core client-server setup. For part 2, you may choose your server module preference of [Rust](/docs/modules/rust) or [C#](/docs/modules/c-sharp): +Get started with the core client-server setup. For part 2, you may choose your server module preference of [Rust](/docs/module/rust-reference) or [C#](/docs/module/c-sharp-reference). -- [Part 1 - Setup](/docs/unity/part-1) -- [Part 2a - Server (Rust)](/docs/unity/part-2a-rust) -- [Part 2b - Server (C#)](/docs/unity/part-2b-c-sharp) -- [Part 3 - Client](/docs/unity/part-3) +- [Part 1 - Setup](/docs/unity-tutorial/part-1) +- [Part 2a - Server (Rust)](/docs/unity-tutorial/part-2a-rust) +- [Part 2b - Server (C#)](/docs/unity-tutorial/part-2b-c-sharp) +- [Part 3 - Client](/docs/unity-tutorial/part-3) ## Unity Tutorial - Advanced By this point, you should already have a basic understanding of SpacetimeDB client, server and CLI: -- [Part 4 - Resources & Scheduling](/docs/unity/part-4) -- [Part 5 - BitCraft Mini](/docs/unity/part-5) +- [Part 4 - Resources & Scheduling](/docs/unity-advanced/part-4) +- [Part 5 - BitCraft Mini](/docs/unity-advanced/part-5) diff --git a/content/docs/02-unity-tutorial/20-part-2a-rust.md b/content/docs/02-unity-tutorial/20-part-2a-rust.md index 3557566..2e46131 100644 --- a/content/docs/02-unity-tutorial/20-part-2a-rust.md +++ b/content/docs/02-unity-tutorial/20-part-2a-rust.md @@ -5,7 +5,7 @@ navTitle: 2a - Server (Rust) Need help with the tutorial? [Join our Discord server](https://discord.gg/spacetimedb)! -This progressive tutorial is continued from the [Part 1 Tutorial](/docs/unity/part-1) +This progressive tutorial is continued from the [Part 1 Tutorial](/docs/unity-tutorial/part-1) ## Create a Server Module @@ -32,7 +32,7 @@ use spacetimedb::{spacetimedb, Identity, SpacetimeType, ReducerContext}; use log; ``` -Then we are going to start by adding the global `Config` table. Right now it only contains the "message of the day" but it can be extended to store other configuration variables. This also uses a couple of macros, like `#[spacetimedb(table)]` which you can learn more about in our [Rust module reference](/docs/modules/rust) (including making your tables `private`!). Simply put, this just tells SpacetimeDB to create a table which uses this struct as the schema for the table. +Then we are going to start by adding the global `Config` table. Right now it only contains the "message of the day" but it can be extended to store other configuration variables. This also uses a couple of macros, like `#[spacetimedb(table)]` which you can learn more about in our [Rust module reference](/docs/module/rust-reference) (including making your tables `private`!). Simply put, this just tells SpacetimeDB to create a table which uses this struct as the schema for the table. **Append to the bottom of lib.rs:** @@ -314,4 +314,4 @@ Now that we added chat support, let's publish the latest module version to Space spacetime publish -c unity-tutorial ``` -From here, the [next tutorial](/docs/unity/part-3) continues with a Client (Unity) focus. +From here, the [next tutorial](/docs/unity-tutorial/part-3) continues with a Client (Unity) focus. diff --git a/content/docs/02-unity-tutorial/21-part-2b-c-sharp.md b/content/docs/02-unity-tutorial/21-part-2b-c-sharp.md index 2ecfe2c..b73a14b 100644 --- a/content/docs/02-unity-tutorial/21-part-2b-c-sharp.md +++ b/content/docs/02-unity-tutorial/21-part-2b-c-sharp.md @@ -5,7 +5,7 @@ navTitle: 2b - Server (C#) Need help with the tutorial? [Join our Discord server](https://discord.gg/spacetimedb)! -This progressive tutorial is continued from the [Part 1 Tutorial](/docs/unity/part-1) +This progressive tutorial is continued from the [Part 1 Tutorial](/docs/unity-tutorial/part-1) ## Create a Server Module @@ -33,7 +33,7 @@ using SpacetimeDB.Module; using static SpacetimeDB.Runtime; ``` -Then we are going to start by adding the global `Config` table. Right now it only contains the "message of the day" but it can be extended to store other configuration variables. This also uses a couple of attributes, like `[SpacetimeDB.Table]` which you can learn more about in our [C# module reference](/docs/modules/c-sharp). Simply put, this just tells SpacetimeDB to create a table which uses this struct as the schema for the table. +Then we are going to start by adding the global `Config` table. Right now it only contains the "message of the day" but it can be extended to store other configuration variables. This also uses a couple of attributes, like `[SpacetimeDB.Table]` which you can learn more about in our [C# module reference](/docs/module/c-sharp-reference). Simply put, this just tells SpacetimeDB to create a table which uses this struct as the schema for the table. **Append to the bottom of lib.cs:** @@ -340,4 +340,4 @@ cd server spacetime publish -c unity-tutorial ``` -From here, the [next tutorial](/docs/unity/part-3) continues with a Client (Unity) focus. +From here, the [next tutorial](/docs/unity-tutorial/part-3) continues with a Client (Unity) focus. diff --git a/content/docs/02-unity-tutorial/30-part-3.md b/content/docs/02-unity-tutorial/30-part-3.md index 39ffde8..d02b9cc 100644 --- a/content/docs/02-unity-tutorial/30-part-3.md +++ b/content/docs/02-unity-tutorial/30-part-3.md @@ -7,8 +7,8 @@ Need help with the tutorial? [Join our Discord server](https://discord.gg/spacet This progressive tutorial is continued from one of the Part 2 tutorials: -- [Rust Server Module](/docs/unity/part-2a-rust) -- [C# Server Module](/docs/unity/part-2b-c-sharp) +- [Rust Server Module](/docs/unity-tutorial/part-2a-rust) +- [C# Server Module](/docs/unity-tutorial/part-2b-c-sharp) ## Updating our Unity Project Client to use SpacetimeDB @@ -467,7 +467,7 @@ Now when you run the game you should be able to send chat messages to other play This concludes the SpacetimeDB basic multiplayer tutorial, where we learned how to create a multiplayer game. In the next Unity tutorial, we will add resource nodes to the game and learn about _scheduled_ reducers: -From here, the tutorial continues with more-advanced topics: The [next tutorial](/docs/unity/part-4) introduces Resources & Scheduling. +From here, the tutorial continues with more-advanced topics: The [next tutorial](/docs/unity-advanced/part-4) introduces Resources & Scheduling. --- diff --git a/content/docs/03-unity-advanced/00-part-4.md b/content/docs/03-unity-advanced/00-part-4.md index b5899f8..e4ed58f 100644 --- a/content/docs/03-unity-advanced/00-part-4.md +++ b/content/docs/03-unity-advanced/00-part-4.md @@ -5,7 +5,7 @@ navTitle: 4 - Resources & Scheduling Need help with the tutorial? [Join our Discord server](https://discord.gg/spacetimedb)! -This progressive tutorial is continued from the [Part 3](/docs/unity/part-3) Tutorial. +This progressive tutorial is continued from the [Part 3](/docs/unity-tutorial/part-3) Tutorial. **Oct 14th, 2023: This tutorial has not yet been updated for the recent 0.7.0 release, it will be updated asap!** diff --git a/content/docs/03-unity-advanced/10-part-5.md b/content/docs/03-unity-advanced/10-part-5.md index b1524b5..ac4d7f4 100644 --- a/content/docs/03-unity-advanced/10-part-5.md +++ b/content/docs/03-unity-advanced/10-part-5.md @@ -5,7 +5,7 @@ navTitle: 5 - BitCraft Mini Need help with the tutorial? [Join our Discord server](https://discord.gg/spacetimedb)! -This progressive tutorial is continued from the [Part 4](/docs/unity/part-3) Tutorial. +This progressive tutorial is continued from the [Part 4](/docs/unity-tutorial/part-3) Tutorial. **Oct 14th, 2023: This tutorial has not yet been updated for the recent 0.7.0 release, it will be updated asap!** diff --git a/content/docs/04-module/00-overview.md b/content/docs/04-module/00-overview.md index 000367f..2ffee0c 100644 --- a/content/docs/04-module/00-overview.md +++ b/content/docs/04-module/00-overview.md @@ -13,15 +13,15 @@ In the following sections, we'll cover the basics of server modules and how to c As of SpacetimeDB 0.6, Rust is the only fully supported language for server modules. Rust is a great option for server modules because it is fast, safe, and has a small runtime. -- [Rust Module Reference](/docs/modules/rust) -- [Rust Module Quickstart Guide](/docs/modules/rust/quickstart) +- [Rust Module Reference](/docs/module/rust-reference) +- [Rust Module Quickstart Guide](/docs/module/rust-quickstart) ### C# We have C# support available in experimental status. C# can be a good choice for developers who are already using Unity or .net for their client applications. -- [C# Module Reference](/docs/modules/c-sharp) -- [C# Module Quickstart Guide](/docs/modules/c-sharp/quickstart) +- [C# Module Reference](/docs/module/c-sharp-reference) +- [C# Module Quickstart Guide](/docs/module/c-sharp-quickstart) ### Coming Soon diff --git a/content/docs/04-module/10-rust-quickstart.md b/content/docs/04-module/10-rust-quickstart.md index 7f7c4f0..56d0758 100644 --- a/content/docs/04-module/10-rust-quickstart.md +++ b/content/docs/04-module/10-rust-quickstart.md @@ -274,6 +274,6 @@ spacetime sql "SELECT * FROM Message" You can find the full code for this module [in the SpacetimeDB module examples](https://github.com/clockworklabs/SpacetimeDB/tree/master/modules/quickstart-chat). -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 quickstart guide for your client language of choice: [Rust](/docs/sdks/rust/quickstart), [C#](/docs/sdks/c-sharp/quickstart), or [TypeScript](/docs/sdks/typescript/quickstart). +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 quickstart guide for your client language of choice: [Rust](/docs/sdk/rust-quickstart), [C#](/docs/sdk/c-sharp-quickstart), or [TypeScript](/docs/sdk/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). +If you are planning to use SpacetimeDB with the Unity game engine, you can skip right to the [Unity Comprehensive Tutorial](/docs/unity-tutorial/part-1) or check out our example game, [BitcraftMini](/docs/unity-advanced/part-5). diff --git a/content/docs/04-module/20-c-sharp-quickstart.md b/content/docs/04-module/20-c-sharp-quickstart.md index 2b3cba4..608c41d 100644 --- a/content/docs/04-module/20-c-sharp-quickstart.md +++ b/content/docs/04-module/20-c-sharp-quickstart.md @@ -315,6 +315,6 @@ spacetime sql "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/sdk/rust-quickstart), [C#](/docs/sdk/c-sharp-quickstart), or [TypeScript](/docs/sdk/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). +If you are planning to use SpacetimeDB with the Unity game engine, you can skip right to the [Unity Comprehensive Tutorial](/docs/unity-tutorial/part-1) or check out our example game, [BitcraftMini](/docs/unity-advanced/part-5). diff --git a/content/docs/05-sdk/00-overview.md b/content/docs/05-sdk/00-overview.md index 3b23096..902bec7 100644 --- a/content/docs/05-sdk/00-overview.md +++ b/content/docs/05-sdk/00-overview.md @@ -5,9 +5,9 @@ navTitle: Overview The SpacetimeDB Client SDKs provide a comprehensive interface to interact with the SpacetimeDB server engine from various programming languages. Currently, SDKs are available for -- [Rust](/docs/sdks/rust) - [(Quickstart)](/docs/sdks/rust/quickstart) -- [C#](/docs/sdks/c-sharp) - [(Quickstart)](/docs/sdks/c-sharp/quickstart) -- [TypeScript](/docs/sdks/typescript) - [(Quickstart)](/docs/sdks/typescript/quickstart) +- [Rust](/docs/sdk/rust-reference) - [(Quickstart)](/docs/sdk/rust-quickstart) +- [C#](/docs/sdk/c-sharp-reference) - [(Quickstart)](/docs/sdk/c-sharp-quickstart) +- [TypeScript](/docs/sdk/typescript-reference) - [(Quickstart)](/docs/sdk/typescript-quickstart) ## Key Features diff --git a/content/docs/05-sdk/10-typescript-quickstart.md b/content/docs/05-sdk/10-typescript-quickstart.md index 00ac483..8b2ed11 100644 --- a/content/docs/05-sdk/10-typescript-quickstart.md +++ b/content/docs/05-sdk/10-typescript-quickstart.md @@ -9,7 +9,7 @@ We'll implement a basic single page web app for the module created in our Rust o ## Project structure -Enter the directory `quickstart-chat` you created in the [Rust Module Quickstart](/docs/modules/rust/quickstart) or [C# Module Quickstart](/docs/modules/c-sharp/quickstart) guides: +Enter the directory `quickstart-chat` you created in the [Rust Module Quickstart](/docs/module/rust-quickstart) or [C# Module Quickstart](/docs/module/c-sharp-quickstart) guides: ```bash cd quickstart-chat diff --git a/content/docs/05-sdk/11-typescript-reference.md b/content/docs/05-sdk/11-typescript-reference.md index db4b09a..26acd2c 100644 --- a/content/docs/05-sdk/11-typescript-reference.md +++ b/content/docs/05-sdk/11-typescript-reference.md @@ -94,13 +94,13 @@ console.log(Person, AddReducer, SayHelloReducer); ### Classes -| Class | Description | -| ----------------------------------------------- | ---------------------------------------------------------------------------- | -| [`SpacetimeDBClient`](#class-spacetimedbclient) | The database client connection to a SpacetimeDB server. | -| [`Identity`](#class-identity) | The user's public identity. | -| [`Address`](#class-address) | An opaque identifier for differentiating connections by the same `Identity`. | -| [`{Table}`](#class-table) | `{Table}` is a placeholder for each of the generated tables. | -| [`{Reducer}`](#class-reducer) | `{Reducer}` is a placeholder for each of the generated reducers. | +| Class | Description | +| --------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| [`SpacetimeDBClient`](#api-at-a-glance-class-spacetimedbclient) | The database client connection to a SpacetimeDB server. | +| [`Identity`](#events-class-identity) | The user's public identity. | +| [`Address`](#methods-class-address) | An opaque identifier for differentiating connections by the same `Identity`. | +| [`{Table}`](#methods-class-table) | `{Table}` is a placeholder for each of the generated tables. | +| [`{Reducer}`](#methods-class-reducer) | `{Reducer}` is a placeholder for each of the generated reducers. | ### Class `SpacetimeDBClient` @@ -108,20 +108,20 @@ The database client connection to a SpacetimeDB server. Defined in [spacetimedb-sdk.spacetimedb](https://github.com/clockworklabs/spacetimedb-typescript-sdk/blob/main/src/spacetimedb.ts): -| Constructors | Description | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------ | -| [`SpacetimeDBClient.constructor`](#spacetimedbclient-constructor) | Creates a new `SpacetimeDBClient` database client. | -| Properties | -| [`SpacetimeDBClient.identity`](#spacetimedbclient-identity) | The user's public identity. | -| [`SpacetimeDBClient.live`](#spacetimedbclient-live) | Whether the client is connected. | -| [`SpacetimeDBClient.token`](#spacetimedbclient-token) | The user's private authentication token. | -| Methods | | -| [`SpacetimeDBClient.connect`](#spacetimedbclient-connect) | Connect to a SpacetimeDB module. | -| [`SpacetimeDBClient.disconnect`](#spacetimedbclient-disconnect) | Close the current connection. | -| [`SpacetimeDBClient.subscribe`](#spacetimedbclient-subscribe) | Subscribe to a set of queries. | -| Events | | -| [`SpacetimeDBClient.onConnect`](#spacetimedbclient-onconnect) | Register a callback to be invoked upon authentication with the database. | -| [`SpacetimeDBClient.onError`](#spacetimedbclient-onerror) | Register a callback to be invoked upon a error. | +| Constructors | Description | +| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | +| [`SpacetimeDBClient.constructor`](#constructors-spacetimedbclient-constructor) | Creates a new `SpacetimeDBClient` database client. | +| Properties | +| [`SpacetimeDBClient.identity`](#properties-spacetimedbclient-identity) | The user's public identity. | +| [`SpacetimeDBClient.live`](#properties-spacetimedbclient-live) | Whether the client is connected. | +| [`SpacetimeDBClient.token`](#properties-spacetimedbclient-token) | The user's private authentication token. | +| Methods | | +| [`SpacetimeDBClient.connect`](#properties-spacetimedbclient-connect) | Connect to a SpacetimeDB module. | +| [`SpacetimeDBClient.disconnect`](#properties-spacetimedbclient-disconnect) | Close the current connection. | +| [`SpacetimeDBClient.subscribe`](#properties-spacetimedbclient-subscribe) | Subscribe to a set of queries. | +| Events | | +| [`SpacetimeDBClient.onConnect`](#events-spacetimedbclient-onconnect) | Register a callback to be invoked upon authentication with the database. | +| [`SpacetimeDBClient.onError`](#events-spacetimedbclient-onerror) | Register a callback to be invoked upon a error. | ## Constructors @@ -214,7 +214,7 @@ SpacetimeDBClient.registerTables(User, Player); ### `SpacetimeDBClient` identity -The user's public [Identity](#class-identity). +The user's public [Identity](#events-class-identity). ``` identity: Identity | undefined @@ -259,11 +259,11 @@ connect(host: string?, name_or_address: string?, auth_token: string?): Promise A new call to `subscribe` will remove all previous subscriptions and replace them with the new `queries`. > If any rows matched the previous subscribed queries but do not match the new queries, -> those rows will be removed from the client cache, and [`{Table}.on_delete`](#table-ondelete) callbacks will be invoked for them. +> those rows will be removed from the client cache, and [`{Table}.on_delete`](#methods-table-ondelete) callbacks will be invoked for them. ```ts subscribe(queryOrQueries: string | string[]): void @@ -344,15 +344,15 @@ Register a callback to be invoked upon authentication with the database. onConnect(callback: (token: string, identity: Identity) => void): void ``` -The callback will be invoked with the public user [Identity](#class-identity), private authentication token and connection [`Address`](#class-address) provided by the database. If credentials were supplied to [connect](#spacetimedbclient-connect), those passed to the callback will be equivalent to the ones used to connect. If the initial connection was anonymous, a new set of credentials will be generated by the database to identify this user. +The callback will be invoked with the public user [Identity](#events-class-identity), private authentication token and connection [`Address`](#methods-class-address) provided by the database. If credentials were supplied to [connect](#properties-spacetimedbclient-connect), those passed to the callback will be equivalent to the ones used to connect. If the initial connection was anonymous, a new set of credentials will be generated by the database to identify this user. The credentials passed to the callback can be saved and used to authenticate the same user in future connections. #### Parameters -| Name | Type | -| :--------- | :--------------------------------------------------------------------------------------------------------------- | -| `callback` | (`token`: `string`, `identity`: [`Identity`](#class-identity), `address`: [`Address`](#class-address)) => `void` | +| Name | Type | +| :--------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `callback` | (`token`: `string`, `identity`: [`Identity`](#events-class-identity), `address`: [`Address`](#methods-class-address)) => `void` | #### Example @@ -395,14 +395,14 @@ A unique public identifier for a user of a database. Defined in [spacetimedb-sdk.identity](https://github.com/clockworklabs/spacetimedb-typescript-sdk/blob/main/src/identity.ts): -| Constructors | Description | -| ----------------------------------------------- | -------------------------------------------- | -| [`Identity.constructor`](#identity-constructor) | Creates a new `Identity`. | -| Methods | | -| [`Identity.isEqual`](#identity-isequal) | Compare two identities for equality. | -| [`Identity.toHexString`](#identity-tohexstring) | Print the identity as a hexadecimal string. | -| Static methods | | -| [`Identity.fromString`](#identity-fromstring) | Parse an Identity from a hexadecimal string. | +| Constructors | Description | +| ------------------------------------------------------------ | -------------------------------------------- | +| [`Identity.constructor`](#constructors-identity-constructor) | Creates a new `Identity`. | +| Methods | | +| [`Identity.isEqual`](#methods-identity-isequal) | Compare two identities for equality. | +| [`Identity.toHexString`](#methods-identity-tohexstring) | Print the identity as a hexadecimal string. | +| Static methods | | +| [`Identity.fromString`](#methods-identity-fromstring) | Parse an Identity from a hexadecimal string. | ## Constructors @@ -430,9 +430,9 @@ isEqual(other: Identity): boolean #### Parameters -| Name | Type | -| :------ | :---------------------------- | -| `other` | [`Identity`](#class-identity) | +| Name | Type | +| :------ | :----------------------------------- | +| `other` | [`Identity`](#events-class-identity) | #### Returns @@ -470,22 +470,22 @@ Identity.fromString(str: string): Identity #### Returns -[`Identity`](#class-identity) +[`Identity`](#events-class-identity) ### Class `Address` -An opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#type-identity). +An opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#events-class-identity). Defined in [spacetimedb-sdk.address](https://github.com/clockworklabs/spacetimedb-typescript-sdk/blob/main/src/address.ts): -| Constructors | Description | -| --------------------------------------------- | ------------------------------------------- | -| [`Address.constructor`](#address-constructor) | Creates a new `Address`. | -| Methods | | -| [`Address.isEqual`](#address-isequal) | Compare two identities for equality. | -| [`Address.toHexString`](#address-tohexstring) | Print the address as a hexadecimal string. | -| Static methods | | -| [`Address.fromString`](#address-fromstring) | Parse an Address from a hexadecimal string. | +| Constructors | Description | +| ---------------------------------------------------------- | ------------------------------------------- | +| [`Address.constructor`](#constructors-address-constructor) | Creates a new `Address`. | +| Methods | | +| [`Address.isEqual`](#methods-address-isequal) | Compare two identities for equality. | +| [`Address.toHexString`](#methods-address-tohexstring) | Print the address as a hexadecimal string. | +| Static methods | | +| [`Address.fromString`](#methods-address-fromstring) | Parse an Address from a hexadecimal string. | ## Constructors @@ -513,9 +513,9 @@ isEqual(other: Address): boolean #### Parameters -| Name | Type | -| :------ | :-------------------------- | -| `other` | [`Address`](#class-address) | +| Name | Type | +| :------ | :---------------------------------- | +| `other` | [`Address`](#methods-class-address) | #### Returns @@ -553,7 +553,7 @@ Address.fromString(str: string): Address #### Returns -[`Address`](#class-address) +[`Address`](#methods-class-address) ### Class `{Table}` @@ -561,22 +561,21 @@ For each table defined by a module, `spacetime generate` generates a `class` in The generated class has a field for each of the table's columns, whose names are the column names converted to `snake_case`. -| Properties | Description | -| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| [`Table.name`](#table-name) | The name of the class. | -| [`Table.tableName`](#table-tableName) | The name of the table in the database. | -| Methods | | -| [`Table.isEqual`](#table-isequal) | Method to compare two identities. | -| [`Table.all`](#table-all) | Return all the subscribed rows in the table. | -| [`Table.filterBy{COLUMN}`](#table-filterbycolumn) | Autogenerated; return subscribed rows with a given value in a particular column. `{COLUMN}` is a placeholder for a column name. | -| [`Table.findBy{COLUMN}`](#table-findbycolumn) | Autogenerated; return a subscribed row with a given value in a particular unique column. `{COLUMN}` is a placeholder for a column name. | -| Events | | -| [`Table.onInsert`](#table-oninsert) | Register an `onInsert` callback for when a subscribed row is newly inserted into the database. | -| [`Table.removeOnInsert`](#table-removeoninsert) | Unregister a previously-registered [`onInsert`](#table-oninsert) callback. | -| [`Table.onUpdate`](#table-onupdate) | Register an `onUpdate` callback for when an existing row is modified. | -| [`Table.removeOnUpdate`](#table-removeonupdate) | Unregister a previously-registered [`onUpdate`](#table-onupdate) callback. | -| [`Table.onDelete`](#table-ondelete) | Register an `onDelete` callback for when a subscribed row is removed from the database. | -| [`Table.removeOnDelete`](#table-removeondelete) | Unregister a previously-registered [`onDelete`](#table-removeondelete) callback. | +| Properties | Description | +| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| [`Table.name`](#properties-table-name) | The name of the class. | +| [`Table.tableName`](#properties-table-tablename) | The name of the table in the database. | +| Methods | | +| [`Table.all`](#methods-table-all) | Return all the subscribed rows in the table. | +| [`Table.filterBy{COLUMN}`](#methods-table-filterby-column) | Autogenerated; return subscribed rows with a given value in a particular column. `{COLUMN}` is a placeholder for a column name. | +| [`Table.findBy{COLUMN}`](#methods-table-findby-column) | Autogenerated; return a subscribed row with a given value in a particular unique column. `{COLUMN}` is a placeholder for a column name. | +| Events | | +| [`Table.onInsert`](#methods-table-oninsert) | Register an `onInsert` callback for when a subscribed row is newly inserted into the database. | +| [`Table.removeOnInsert`](#methods-table-removeoninsert) | Unregister a previously-registered [`onInsert`](#methods-table-oninsert) callback. | +| [`Table.onUpdate`](#methods-table-onupdate) | Register an `onUpdate` callback for when an existing row is modified. | +| [`Table.removeOnUpdate`](#methods-table-removeonupdate) | Unregister a previously-registered [`onUpdate`](#methods-table-onupdate) callback. | +| [`Table.onDelete`](#methods-table-ondelete) | Register an `onDelete` callback for when a subscribed row is removed from the database. | +| [`Table.removeOnDelete`](#methods-table-removeondelete) | Unregister a previously-registered [`onDelete`](#methods-table-removeondelete) callback. | ## Properties @@ -810,7 +809,7 @@ Person.onInsert((person, reducerEvent) => { ### {Table} removeOnInsert -Unregister a previously-registered [`onInsert`](#table-oninsert) callback. +Unregister a previously-registered [`onInsert`](#methods-table-oninsert) callback. ```ts {Table}.removeOnInsert(callback: (value: Person, reducerEvent: ReducerEvent | undefined) => void): void @@ -860,7 +859,7 @@ Person.onUpdate((oldPerson, newPerson, reducerEvent) => { ### {Table} removeOnUpdate -Unregister a previously-registered [`onUpdate`](#table-onUpdate) callback. +Unregister a previously-registered [`onUpdate`](#methods-table-onupdate) callback. ```ts {Table}.removeOnUpdate(callback: (oldValue: {Table}, newValue: {Table}, reducerEvent: ReducerEvent | undefined) => void): void @@ -915,7 +914,7 @@ Person.onDelete((person, reducerEvent) => { ### {Table} removeOnDelete -Unregister a previously-registered [`onDelete`](#table-onDelete) callback. +Unregister a previously-registered [`onDelete`](#methods-table-ondelete) callback. ```ts {Table}.removeOnDelete(callback: (value: {Table}, reducerEvent: ReducerEvent | undefined) => void): void @@ -933,11 +932,11 @@ Unregister a previously-registered [`onDelete`](#table-onDelete) callback. The class's name will be the reducer's name converted to `PascalCase`. -| Static methods | Description | -| ------------------------------- | ------------------------------------------------------------ | -| [`Reducer.call`](#reducer-call) | Executes the reducer. | -| Events | | -| [`Reducer.on`](#reducer-on) | Register a callback to run each time the reducer is invoked. | +| Static methods | Description | +| ---------------------------------------------- | ------------------------------------------------------------ | +| [`Reducer.call`](#static-methods-reducer-call) | Executes the reducer. | +| Events | | +| [`Reducer.on`](#events-reducer-on) | Register a callback to run each time the reducer is invoked. | ## Static methods diff --git a/content/docs/05-sdk/20-rust-quickstart.md b/content/docs/05-sdk/20-rust-quickstart.md index 422b7ac..aab9a88 100644 --- a/content/docs/05-sdk/20-rust-quickstart.md +++ b/content/docs/05-sdk/20-rust-quickstart.md @@ -9,7 +9,7 @@ We'll implement a command-line client for the module created in our Rust or C# M ## Project structure -Enter the directory `quickstart-chat` you created in the [Rust Module Quickstart](/docs/modules/rust/quickstart) or [C# Module Quickstart](/docs/modules/c-sharp/quickstart) guides: +Enter the directory `quickstart-chat` you created in the [Rust Module Quickstart](/docs/module/rust-quickstart) or [C# Module Quickstart](/docs/module/c-sharp-quickstart) guides: ```bash cd quickstart-chat @@ -474,7 +474,7 @@ User connected. You can find the full code for this client [in the Rust SDK's examples](https://github.com/clockworklabs/SpacetimeDB/tree/master/crates/sdk/examples/quickstart-chat). -Check out the [Rust SDK Reference](/docs/sdks/rust) for a more comprehensive view of the SpacetimeDB Rust SDK. +Check out the [Rust SDK Reference](/docs/sdk/rust-reference) for a more comprehensive view of the SpacetimeDB Rust SDK. Our bare-bones terminal interface has some quirks. Incoming messages can appear while the user is typing and be spliced into the middle of user input, which is less than ideal. Also, the user's input is interspersed with the program's output, so messages the user sends will seem to appear twice. Why not try building a better interface using [Rustyline](https://crates.io/crates/rustyline), [Cursive](https://crates.io/crates/cursive), or even a full-fledged GUI? We went for the Cursive route, and you can check out what we came up with [in the Rust SDK's examples](https://github.com/clockworklabs/SpacetimeDB/tree/master/crates/sdk/examples/cursive-chat). diff --git a/content/docs/05-sdk/21-rust-reference.md b/content/docs/05-sdk/21-rust-reference.md index c4a999b..99c6378 100644 --- a/content/docs/05-sdk/21-rust-reference.md +++ b/content/docs/05-sdk/21-rust-reference.md @@ -34,53 +34,53 @@ mod module_bindings; ## API at a glance -| Definition | Description | -| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -| Function [`module_bindings::connect`](#function-connect) | Autogenerated function to connect to a database. | -| Function [`spacetimedb_sdk::disconnect`](#function-disconnect) | Close the active connection. | -| Function [`spacetimedb_sdk::on_disconnect`](#function-on_disconnect) | Register a `FnMut` callback to run when a connection ends. | -| Function [`spacetimedb_sdk::once_on_disconnect`](#function-once_on_disconnect) | Register a `FnOnce` callback to run the next time a connection ends. | -| Function [`spacetimedb_sdk::remove_on_disconnect`](#function-remove_on_disconnect) | Cancel an `on_disconnect` or `once_on_disconnect` callback. | -| Function [`spacetimedb_sdk::subscribe`](#function-subscribe) | Subscribe to queries with a `&[&str]`. | -| Function [`spacetimedb_sdk::subscribe_owned`](#function-subscribe_owned) | Subscribe to queries with a `Vec`. | -| Function [`spacetimedb_sdk::on_subscription_applied`](#function-on_subscription_applied) | Register a `FnMut` callback to run when a subscription's initial rows become available. | -| Function [`spacetimedb_sdk::once_on_subscription_applied`](#function-once_on_subscription_applied) | Register a `FnOnce` callback to run the next time a subscription's initial rows become available. | -| Function [`spacetimedb_sdk::remove_on_subscription_applied`](#function-remove_on_subscription_applied) | Cancel an `on_subscription_applied` or `once_on_subscription_applied` callback. | -| Type [`spacetimedb_sdk::identity::Identity`](#type-identity) | A unique public identifier for a client. | -| Type [`spacetimedb_sdk::identity::Token`](#type-token) | A private authentication token corresponding to an `Identity`. | -| Type [`spacetimedb_sdk::identity::Credentials`](#type-credentials) | An `Identity` paired with its `Token`. | -| Type [`spacetimedb_sdk::Address`](#type-address) | An opaque identifier for differentiating connections by the same `Identity`. | -| Function [`spacetimedb_sdk::identity::identity`](#function-identity) | Return the current connection's `Identity`. | -| Function [`spacetimedb_sdk::identity::token`](#function-token) | Return the current connection's `Token`. | -| Function [`spacetimedb_sdk::identity::credentials`](#function-credentials) | Return the current connection's [`Credentials`](#type-credentials). | -| Function [`spacetimedb_sdk::identity::address`](#function-address) | Return the current connection's [`Address`](#type-address). | -| Function [`spacetimedb_sdk::identity::on_connect`](#function-on_connect) | Register a `FnMut` callback to run when the connection's [`Credentials`](#type-credentials) are verified with the database. | -| Function [`spacetimedb_sdk::identity::once_on_connect`](#function-once_on_connect) | Register a `FnOnce` callback to run when the connection's [`Credentials`](#type-credentials) are verified with the database. | -| Function [`spacetimedb_sdk::identity::remove_on_connect`](#function-remove_on_connect) | Cancel an `on_connect` or `once_on_connect` callback. | -| Function [`spacetimedb_sdk::identity::load_credentials`](#function-load_credentials) | Load a saved [`Credentials`](#type-credentials) from a file. | -| Function [`spacetimedb_sdk::identity::save_credentials`](#function-save_credentials) | Save a [`Credentials`](#type-credentials) to a file. | -| Type [`module_bindings::{TABLE}`](#type-table) | Autogenerated `struct` type for a table, holding one row. | -| Method [`module_bindings::{TABLE}::filter_by_{COLUMN}`](#method-filter_by_column) | Autogenerated method to iterate over subscribed rows where a column matches a value. | -| Method [`module_bindings::{TABLE}::find_by_{COLUMN}`](#method-find_by_column) | Autogenerated method to seek a subscribed row where a unique column matches a value. | -| Trait [`spacetimedb_sdk::table::TableType`](#trait-tabletype) | Automatically implemented for all tables defined by a module. | -| Method [`spacetimedb_sdk::table::TableType::count`](#method-count) | Count the number of subscribed rows in a table. | -| Method [`spacetimedb_sdk::table::TableType::iter`](#method-iter) | Iterate over all subscribed rows. | -| Method [`spacetimedb_sdk::table::TableType::filter`](#method-filter) | Iterate over a subset of subscribed rows matching a predicate. | -| Method [`spacetimedb_sdk::table::TableType::find`](#method-find) | Return one subscribed row matching a predicate. | -| Method [`spacetimedb_sdk::table::TableType::on_insert`](#method-on_insert) | Register a `FnMut` callback to run whenever a new subscribed row is inserted. | -| Method [`spacetimedb_sdk::table::TableType::remove_on_insert`](#method-remove_on_insert) | Cancel an `on_insert` callback. | -| Method [`spacetimedb_sdk::table::TableType::on_delete`](#method-on_delete) | Register a `FnMut` callback to run whenever a subscribed row is deleted. | -| Method [`spacetimedb_sdk::table::TableType::remove_on_delete`](#method-remove_on_delete) | Cancel an `on_delete` callback. | -| Trait [`spacetimedb_sdk::table::TableWithPrimaryKey`](#trait-tablewithprimarykey) | Automatically implemented for tables with a column designated `#[primarykey]`. | -| Method [`spacetimedb_sdk::table::TableWithPrimaryKey::on_update`](#method-on_update) | Register a `FnMut` callback to run whenever an existing subscribed row is updated. | -| Method [`spacetimedb_sdk::table::TableWithPrimaryKey::remove_on_update`](#method-remove_on_update) | Cancel an `on_update` callback. | -| Type [`module_bindings::ReducerEvent`](#type-reducerevent) | Autogenerated enum with a variant for each reducer defined by the module. | -| Type [`module_bindings::{REDUCER}Args`](#type-reducerargs) | Autogenerated `struct` type for a reducer, holding its arguments. | -| Function [`module_bindings::{REDUCER}`](#function-reducer) | Autogenerated function to invoke a reducer. | -| Function [`module_bindings::on_{REDUCER}`](#function-on_reducer) | Autogenerated function to register a `FnMut` callback to run whenever the reducer is invoked. | -| Function [`module_bindings::once_on_{REDUCER}`](#function-once_on_reducer) | Autogenerated function to register a `FnOnce` callback to run the next time the reducer is invoked. | -| Function [`module_bindings::remove_on_{REDUCER}`](#function-remove_on_reducer) | Autogenerated function to cancel an `on_{REDUCER}` or `once_on_{REDUCER}` callback. | -| Type [`spacetimedb_sdk::reducer::Status`](#type-status) | Enum representing reducer completion statuses. | +| Definition | Description | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| Function [`module_bindings::connect`](#connect-to-a-database-function-connect) | Autogenerated function to connect to a database. | +| Function [`spacetimedb_sdk::disconnect`](#connect-to-a-database-function-disconnect) | Close the active connection. | +| Function [`spacetimedb_sdk::on_disconnect`](#connect-to-a-database-function-on-disconnect) | Register a `FnMut` callback to run when a connection ends. | +| Function [`spacetimedb_sdk::once_on_disconnect`](#connect-to-a-database-function-once-on-disconnect) | Register a `FnOnce` callback to run the next time a connection ends. | +| Function [`spacetimedb_sdk::remove_on_disconnect`](#connect-to-a-database-function-remove-on-disconnect) | Cancel an `on_disconnect` or `once_on_disconnect` callback. | +| Function [`spacetimedb_sdk::subscribe`](#subscribe-to-queries-function-subscribe) | Subscribe to queries with a `&[&str]`. | +| Function [`spacetimedb_sdk::subscribe_owned`](#subscribe-to-queries-function-subscribe-owned) | Subscribe to queries with a `Vec`. | +| Function [`spacetimedb_sdk::on_subscription_applied`](#subscribe-to-queries-function-on-subscription-applied) | Register a `FnMut` callback to run when a subscription's initial rows become available. | +| Function [`spacetimedb_sdk::once_on_subscription_applied`](#subscribe-to-queries-function-once-on-subscription-applied) | Register a `FnOnce` callback to run the next time a subscription's initial rows become available. | +| Function [`spacetimedb_sdk::remove_on_subscription_applied`](#subscribe-to-queries-function-remove-on-subscription-applied) | Cancel an `on_subscription_applied` or `once_on_subscription_applied` callback. | +| Type [`spacetimedb_sdk::identity::Identity`](#identify-a-client-type-identity) | A unique public identifier for a client. | +| Type [`spacetimedb_sdk::identity::Token`](#identify-a-client-type-token) | A private authentication token corresponding to an `Identity`. | +| Type [`spacetimedb_sdk::identity::Credentials`](#identify-a-client-type-credentials) | An `Identity` paired with its `Token`. | +| Type [`spacetimedb_sdk::Address`](#identify-a-client-type-address) | An opaque identifier for differentiating connections by the same `Identity`. | +| Function [`spacetimedb_sdk::identity::identity`](#identify-a-client-function-identity) | Return the current connection's `Identity`. | +| Function [`spacetimedb_sdk::identity::token`](#identify-a-client-function-token) | Return the current connection's `Token`. | +| Function [`spacetimedb_sdk::identity::credentials`](#identify-a-client-function-credentials) | Return the current connection's [`Credentials`](#identify-a-client-type-credentials). | +| Function [`spacetimedb_sdk::identity::address`](#identify-a-client-function-address) | Return the current connection's [`Address`](#identify-a-client-type-address). | +| Function [`spacetimedb_sdk::identity::on_connect`](#identify-a-client-function-on-connect) | Register a `FnMut` callback to run when the connection's [`Credentials`](#identify-a-client-type-credentials) are verified with the database. | +| Function [`spacetimedb_sdk::identity::once_on_connect`](#identify-a-client-function-once-on-connect) | Register a `FnOnce` callback to run when the connection's [`Credentials`](#identify-a-client-type-credentials) are verified with the database. | +| Function [`spacetimedb_sdk::identity::remove_on_connect`](#identify-a-client-function-remove-on-connect) | Cancel an `on_connect` or `once_on_connect` callback. | +| Function [`spacetimedb_sdk::identity::load_credentials`](#identify-a-client-function-load-credentials) | Load a saved [`Credentials`](#identify-a-client-type-credentials) from a file. | +| Function [`spacetimedb_sdk::identity::save_credentials`](#identify-a-client-function-save-credentials) | Save a [`Credentials`](#identify-a-client-type-credentials) to a file. | +| Type [`module_bindings::{TABLE}`](#view-subscribed-rows-of-tables-type-table) | Autogenerated `struct` type for a table, holding one row. | +| Method [`module_bindings::{TABLE}::filter_by_{COLUMN}`](#view-subscribed-rows-of-tables-method-filter-by-column) | Autogenerated method to iterate over subscribed rows where a column matches a value. | +| Method [`module_bindings::{TABLE}::find_by_{COLUMN}`](#view-subscribed-rows-of-tables-method-find-by-column) | Autogenerated method to seek a subscribed row where a unique column matches a value. | +| Trait [`spacetimedb_sdk::table::TableType`](#view-subscribed-rows-of-tables-trait-tabletype) | Automatically implemented for all tables defined by a module. | +| Method [`spacetimedb_sdk::table::TableType::count`](#view-subscribed-rows-of-tables-trait-tabletype-method-count) | Count the number of subscribed rows in a table. | +| Method [`spacetimedb_sdk::table::TableType::iter`](#view-subscribed-rows-of-tables-trait-tabletype-method-iter) | Iterate over all subscribed rows. | +| Method [`spacetimedb_sdk::table::TableType::filter`](#view-subscribed-rows-of-tables-trait-tabletype-method-filter) | Iterate over a subset of subscribed rows matching a predicate. | +| Method [`spacetimedb_sdk::table::TableType::find`](#view-subscribed-rows-of-tables-trait-tabletype-method-find) | Return one subscribed row matching a predicate. | +| Method [`spacetimedb_sdk::table::TableType::on_insert`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-insert) | Register a `FnMut` callback to run whenever a new subscribed row is inserted. | +| Method [`spacetimedb_sdk::table::TableType::remove_on_insert`](#view-subscribed-rows-of-tables-trait-tabletype-method-remove-on-insert) | Cancel an `on_insert` callback. | +| Method [`spacetimedb_sdk::table::TableType::on_delete`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-delete) | Register a `FnMut` callback to run whenever a subscribed row is deleted. | +| Method [`spacetimedb_sdk::table::TableType::remove_on_delete`](#view-subscribed-rows-of-tables-trait-tabletype-method-remove-on-delete) | Cancel an `on_delete` callback. | +| Trait [`spacetimedb_sdk::table::TableWithPrimaryKey`](#view-subscribed-rows-of-tables-trait-tablewithprimarykey) | Automatically implemented for tables with a column designated `#[primarykey]`. | +| Method [`spacetimedb_sdk::table::TableWithPrimaryKey::on_update`](#view-subscribed-rows-of-tables-trait-tablewithprimarykey-method-on-update) | Register a `FnMut` callback to run whenever an existing subscribed row is updated. | +| Method [`spacetimedb_sdk::table::TableWithPrimaryKey::remove_on_update`](#view-subscribed-rows-of-tables-trait-tablewithprimarykey-method-remove-on-update) | Cancel an `on_update` callback. | +| Type [`module_bindings::ReducerEvent`](#observe-and-request-reducer-invocations-type-reducerevent) | Autogenerated enum with a variant for each reducer defined by the module. | +| Type [`module_bindings::{REDUCER}Args`](#observe-and-request-reducer-invocations-type-reducer-args) | Autogenerated `struct` type for a reducer, holding its arguments. | +| Function [`module_bindings::{REDUCER}`](#observe-and-request-reducer-invocations-function-reducer) | Autogenerated function to invoke a reducer. | +| Function [`module_bindings::on_{REDUCER}`](#observe-and-request-reducer-invocations-function-on-reducer) | Autogenerated function to register a `FnMut` callback to run whenever the reducer is invoked. | +| Function [`module_bindings::once_on_{REDUCER}`](#observe-and-request-reducer-invocations-function-once-on-reducer) | Autogenerated function to register a `FnOnce` callback to run the next time the reducer is invoked. | +| Function [`module_bindings::remove_on_{REDUCER}`](#observe-and-request-reducer-invocations-function-remove-on-reducer) | Autogenerated function to cancel an `on_{REDUCER}` or `once_on_{REDUCER}` callback. | +| Type [`spacetimedb_sdk::reducer::Status`](#observe-and-request-reducer-invocations-type-status) | Enum representing reducer completion statuses. | ## Connect to a database @@ -96,13 +96,13 @@ module_bindings::connect( Connect to a database named `db_name` accessible over the internet at the URI `spacetimedb_uri`. -| Argument | Type | Meaning | -| ----------------- | --------------------- | ------------------------------------------------------------ | -| `spacetimedb_uri` | `impl TryInto` | URI of the SpacetimeDB instance running the module. | -| `db_name` | `&str` | Name of the module. | -| `credentials` | `Option` | [`Credentials`](#type-credentials) to authenticate the user. | +| Argument | Type | Meaning | +| ----------------- | --------------------- | ------------------------------------------------------------------------------ | +| `spacetimedb_uri` | `impl TryInto` | URI of the SpacetimeDB instance running the module. | +| `db_name` | `&str` | Name of the module. | +| `credentials` | `Option` | [`Credentials`](#identify-a-client-type-credentials) to authenticate the user. | -If `credentials` are supplied, they will be passed to the new connection to identify and authenticate the user. Otherwise, a set of [`Credentials`](#type-credentials) will be generated by the server. +If `credentials` are supplied, they will be passed to the new connection to identify and authenticate the user. Otherwise, a set of [`Credentials`](#identify-a-client-type-credentials) will be generated by the server. ```rust const MODULE_NAME: &str = "my-module-name"; @@ -158,9 +158,9 @@ Register a callback to be invoked when a connection ends. | ---------- | ------------------------------- | ------------------------------------------------------ | | `callback` | `impl FnMut() + Send + 'static` | Callback to be invoked when subscriptions are applied. | -The callback will be invoked after calling [`disconnect`](#function-disconnect), or when a connection is closed by the server. +The callback will be invoked after calling [`disconnect`](#connect-to-a-database-function-disconnect), or when a connection is closed by the server. -The returned `DisconnectCallbackId` can be passed to [`remove_on_disconnect`](#function-remove_on_disconnect) to unregister the callback. +The returned `DisconnectCallbackId` can be passed to [`remove_on_disconnect`](#connect-to-a-database-function-remove-on-disconnect) to unregister the callback. ```rust on_disconnect(|| println!("Disconnected!")); @@ -187,11 +187,11 @@ Register a callback to be invoked the next time a connection ends. | ---------- | ------------------------------- | ------------------------------------------------------ | | `callback` | `impl FnMut() + Send + 'static` | Callback to be invoked when subscriptions are applied. | -The callback will be invoked after calling [`disconnect`](#function-disconnect), or when a connection is closed by the server. +The callback will be invoked after calling [`disconnect`](#connect-to-a-database-function-disconnect), or when a connection is closed by the server. The callback will be unregistered after running. -The returned `DisconnectCallbackId` can be passed to [`remove_on_disconnect`](#function-remove_on_disconnect) to unregister the callback. +The returned `DisconnectCallbackId` can be passed to [`remove_on_disconnect`](#connect-to-a-database-function-remove-on-disconnect) to unregister the callback. ```rust once_on_disconnect(|| println!("Disconnected!")); @@ -219,7 +219,7 @@ spacetimedb_sdk::remove_on_disconnect( ) ``` -Unregister a previously-registered [`on_disconnect`](#function-on_disconnect) callback. +Unregister a previously-registered [`on_disconnect`](#connect-to-a-database-function-on-disconnect) callback. | Argument | Type | Meaning | | -------- | ---------------------- | ------------------------------------------ | @@ -253,11 +253,11 @@ Subscribe to a set of queries, to be notified when rows which match those querie The `queries` should be a slice of strings representing SQL queries. -`subscribe` will return an error if called before establishing a connection with the autogenerated [`connect`](#function-connect) function. In that case, the queries are not registered. +`subscribe` will return an error if called before establishing a connection with the autogenerated [`connect`](#connect-to-a-database-function-connect) function. In that case, the queries are not registered. -`subscribe` does not return data directly. The SDK will generate types [`module_bindings::{TABLE}`](#type-table) corresponding to each of the tables in your module. These types implement the trait [`spacetimedb_sdk::table_type::TableType`](#trait-tabletype), which contains methods such as [`TableType::on_insert`](#method-on_insert). Use these methods to receive data from the queries you subscribe to. +`subscribe` does not return data directly. The SDK will generate types [`module_bindings::{TABLE}`](#view-subscribed-rows-of-tables-type-table) corresponding to each of the tables in your module. These types implement the trait [`spacetimedb_sdk::table_type::TableType`](#view-subscribed-rows-of-tables-trait-tabletype), which contains methods such as [`TableType::on_insert`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-insert). Use these methods to receive data from the queries you subscribe to. -A new call to `subscribe` (or [`subscribe_owned`](#function-subscribe_owned)) will remove all previous subscriptions and replace them with the new `queries`. If any rows matched the previous subscribed queries but do not match the new queries, those rows will be removed from the client cache, and [`TableType::on_delete`](#method-on_delete) callbacks will be invoked for them. +A new call to `subscribe` (or [`subscribe_owned`](#subscribe-to-queries-function-subscribe-owned)) will remove all previous subscriptions and replace them with the new `queries`. If any rows matched the previous subscribed queries but do not match the new queries, those rows will be removed from the client cache, and [`TableType::on_delete`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-delete) callbacks will be invoked for them. ```rust subscribe(&["SELECT * FROM User;", "SELECT * FROM Message;"]) @@ -278,10 +278,10 @@ Subscribe to a set of queries, to be notified when rows which match those querie The `queries` should be a `Vec` of `String`s representing SQL queries. -A new call to `subscribe_owned` (or [`subscribe`](#function-subscribe)) will remove all previous subscriptions and replace them with the new `queries`. -If any rows matched the previous subscribed queries but do not match the new queries, those rows will be removed from the client cache, and [`TableType::on_delete`](#method-on_delete) callbacks will be invoked for them. +A new call to `subscribe_owned` (or [`subscribe`](#subscribe-to-queries-function-subscribe)) will remove all previous subscriptions and replace them with the new `queries`. +If any rows matched the previous subscribed queries but do not match the new queries, those rows will be removed from the client cache, and [`TableType::on_delete`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-delete) callbacks will be invoked for them. -`subscribe_owned` will return an error if called before establishing a connection with the autogenerated [`connect`](#function-connect) function. In that case, the queries are not registered. +`subscribe_owned` will return an error if called before establishing a connection with the autogenerated [`connect`](#connect-to-a-database-function-connect) function. In that case, the queries are not registered. ```rust let query = format!("SELECT * FROM User WHERE name = '{}';", compute_my_name()); @@ -304,9 +304,9 @@ Register a callback to be invoked the first time a subscription's matching rows | ---------- | ------------------------------- | ------------------------------------------------------ | | `callback` | `impl FnMut() + Send + 'static` | Callback to be invoked when subscriptions are applied. | -The callback will be invoked after a successful [`subscribe`](#function-subscribe) or [`subscribe_owned`](#function-subscribe_owned) call when the initial set of matching rows becomes available. +The callback will be invoked after a successful [`subscribe`](#subscribe-to-queries-function-subscribe) or [`subscribe_owned`](#subscribe-to-queries-function-subscribe-owned) call when the initial set of matching rows becomes available. -The returned `SubscriptionCallbackId` can be passed to [`remove_on_subscription_applied`](#function-remove_on_subscription_applied) to unregister the callback. +The returned `SubscriptionCallbackId` can be passed to [`remove_on_subscription_applied`](#subscribe-to-queries-function-remove-on-subscription-applied) to unregister the callback. ```rust on_subscription_applied(|| println!("Subscription applied!")); @@ -338,11 +338,11 @@ Register a callback to be invoked the next time a subscription's matching rows b | ---------- | ------------------------------- | ------------------------------------------------------ | | `callback` | `impl FnMut() + Send + 'static` | Callback to be invoked when subscriptions are applied. | -The callback will be invoked after a successful [`subscribe`](#function-subscribe) or [`subscribe_owned`](#function-subscribe_owned) call when the initial set of matching rows becomes available. +The callback will be invoked after a successful [`subscribe`](#subscribe-to-queries-function-subscribe) or [`subscribe_owned`](#subscribe-to-queries-function-subscribe-owned) call when the initial set of matching rows becomes available. The callback will be unregistered after running. -The returned `SubscriptionCallbackId` can be passed to [`remove_on_subscription_applied`](#function-remove_on_subscription_applied) to unregister the callback. +The returned `SubscriptionCallbackId` can be passed to [`remove_on_subscription_applied`](#subscribe-to-queries-function-remove-on-subscription-applied) to unregister the callback. ```rust once_on_subscription_applied(|| println!("Subscription applied!")); @@ -368,7 +368,7 @@ spacetimedb_sdk::remove_on_subscription_applied( ) ``` -Unregister a previously-registered [`on_subscription_applied`](#function-on_subscription_applied) callback. +Unregister a previously-registered [`on_subscription_applied`](#subscribe-to-queries-function-on-subscription-applied) callback. | Argument | Type | Meaning | | -------- | ------------------------ | ------------------------------------------ | @@ -420,10 +420,10 @@ spacetimedb_sdk::identity::Credentials Credentials, including a private access token, sufficient to authenticate a client connected to a database. -| Field | Type | -| ---------- | ---------------------------- | -| `identity` | [`Identity`](#type-identity) | -| `token` | [`Token`](#type-token) | +| Field | Type | +| ---------- | ---------------------------------------------- | +| `identity` | [`Identity`](#identify-a-client-type-identity) | +| `token` | [`Token`](#identify-a-client-type-token) | ### Type `Address` @@ -431,7 +431,7 @@ Credentials, including a private access token, sufficient to authenticate a clie spacetimedb_sdk::Address ``` -An opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#type-identity). +An opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#identify-a-client-type-identity). ### Function `identity` @@ -439,11 +439,11 @@ An opaque identifier for a client connection to a database, intended to differen spacetimedb_sdk::identity::identity() -> Result ``` -Read the current connection's public [`Identity`](#type-identity). +Read the current connection's public [`Identity`](#identify-a-client-type-identity). Returns an error if: -- [`connect`](#function-connect) has not yet been called. +- [`connect`](#connect-to-a-database-function-connect) has not yet been called. - We connected anonymously, and we have not yet received our credentials. ```rust @@ -463,11 +463,11 @@ println!("My identity is {:?}", identity()); spacetimedb_sdk::identity::token() -> Result ``` -Read the current connection's private [`Token`](#type-token). +Read the current connection's private [`Token`](#identify-a-client-type-token). Returns an error if: -- [`connect`](#function-connect) has not yet been called. +- [`connect`](#connect-to-a-database-function-connect) has not yet been called. - We connected anonymously, and we have not yet received our credentials. ```rust @@ -487,11 +487,11 @@ println!("My token is {:?}", token()); spacetimedb_sdk::identity::credentials() -> Result ``` -Read the current connection's [`Credentials`](#type-credentials), including a public [`Identity`](#type-identity) and a private [`Token`](#type-token). +Read the current connection's [`Credentials`](#identify-a-client-type-credentials), including a public [`Identity`](#identify-a-client-type-identity) and a private [`Token`](#identify-a-client-type-token). Returns an error if: -- [`connect`](#function-connect) has not yet been called. +- [`connect`](#connect-to-a-database-function-connect) has not yet been called. - We connected anonymously, and we have not yet received our credentials. ```rust @@ -514,9 +514,9 @@ println!("My credentials are {:?}", credentials()); spacetimedb_sdk::identity::address() -> Result
``` -Read the current connection's [`Address`](#type-address). +Read the current connection's [`Address`](#identify-a-client-type-address). -Returns an error if [`connect`](#function-connect) has not yet been called. +Returns an error if [`connect`](#connect-to-a-database-function-connect) has not yet been called. ```rust connect(SPACETIMEDB_URI, DB_NAME, None) @@ -541,11 +541,11 @@ Register a callback to be invoked upon authentication with the database. | ---------- | -------------------------------------------------- | ------------------------------------------------------ | | `callback` | `impl FnMut(&Credentials, Address) + Send + 'sync` | Callback to be invoked upon successful authentication. | -The callback will be invoked with the [`Credentials`](#type-credentials) and [`Address`](#type-address) provided by the database to identify this connection. If [`Credentials`](#type-credentials) were supplied to [`connect`](#function-connect), those passed to the callback will be equivalent to the ones used to connect. If the initial connection was anonymous, a new set of [`Credentials`](#type-credentials) will be generated by the database to identify this user. +The callback will be invoked with the [`Credentials`](#identify-a-client-type-credentials) and [`Address`](#identify-a-client-type-address) provided by the database to identify this connection. If [`Credentials`](#identify-a-client-type-credentials) were supplied to [`connect`](#connect-to-a-database-function-connect), those passed to the callback will be equivalent to the ones used to connect. If the initial connection was anonymous, a new set of [`Credentials`](#identify-a-client-type-credentials) will be generated by the database to identify this user. -The [`Credentials`](#type-credentials) passed to the callback can be saved and used to authenticate the same user in future connections. +The [`Credentials`](#identify-a-client-type-credentials) passed to the callback can be saved and used to authenticate the same user in future connections. -The returned `ConnectCallbackId` can be passed to [`remove_on_connect`](#function-remove_on_connect) to unregister the callback. +The returned `ConnectCallbackId` can be passed to [`remove_on_connect`](#identify-a-client-function-remove-on-connect) to unregister the callback. ```rust on_connect( @@ -576,13 +576,13 @@ Register a callback to be invoked once upon authentication with the database. | ---------- | --------------------------------------------------- | ---------------------------------------------------------------- | | `callback` | `impl FnOnce(&Credentials, Address) + Send + 'sync` | Callback to be invoked once upon next successful authentication. | -The callback will be invoked with the [`Credentials`](#type-credentials) and [`Address`](#type-address) provided by the database to identify this connection. If [`Credentials`](#type-credentials) were supplied to [`connect`](#function-connect), those passed to the callback will be equivalent to the ones used to connect. If the initial connection was anonymous, a new set of [`Credentials`](#type-credentials) will be generated by the database to identify this user. +The callback will be invoked with the [`Credentials`](#identify-a-client-type-credentials) and [`Address`](#identify-a-client-type-address) provided by the database to identify this connection. If [`Credentials`](#identify-a-client-type-credentials) were supplied to [`connect`](#connect-to-a-database-function-connect), those passed to the callback will be equivalent to the ones used to connect. If the initial connection was anonymous, a new set of [`Credentials`](#identify-a-client-type-credentials) will be generated by the database to identify this user. -The [`Credentials`](#type-credentials) passed to the callback can be saved and used to authenticate the same user in future connections. +The [`Credentials`](#identify-a-client-type-credentials) passed to the callback can be saved and used to authenticate the same user in future connections. The callback will be unregistered after running. -The returned `ConnectCallbackId` can be passed to [`remove_on_connect`](#function-remove_on_connect) to unregister the callback. +The returned `ConnectCallbackId` can be passed to [`remove_on_connect`](#identify-a-client-function-remove-on-connect) to unregister the callback. ### Function `remove_on_connect` @@ -590,7 +590,7 @@ The returned `ConnectCallbackId` can be passed to [`remove_on_connect`](#functio spacetimedb_sdk::identity::remove_on_connect(id: ConnectCallbackId) ``` -Unregister a previously-registered [`on_connect`](#function-on_connect) or [`once_on_connect`](#function-once_on_connect) callback. +Unregister a previously-registered [`on_connect`](#identify-a-client-function-on-connect) or [`once_on_connect`](#identify-a-client-function-once-on-connect) callback. | Argument | Type | Meaning | | -------- | ------------------- | ------------------------------------------ | @@ -619,15 +619,15 @@ spacetimedb_sdk::identity::load_credentials( ) -> Result> ``` -Load a saved [`Credentials`](#type-credentials) from a file within `~/dirname`, if one exists. +Load a saved [`Credentials`](#identify-a-client-type-credentials) from a file within `~/dirname`, if one exists. | Argument | Type | Meaning | | --------- | ------ | ----------------------------------------------------- | | `dirname` | `&str` | Name of a sub-directory in the user's home directory. | -`dirname` is treated as a directory in the user's home directory. If it contains a file named `credentials`, that file is treated as a BSATN-encoded [`Credentials`](#type-credentials), deserialized and returned. These files are created by [`save_credentials`](#function-save_credentials) with the same `dirname` argument. +`dirname` is treated as a directory in the user's home directory. If it contains a file named `credentials`, that file is treated as a BSATN-encoded [`Credentials`](#identify-a-client-type-credentials), deserialized and returned. These files are created by [`save_credentials`](#identify-a-client-function-save-credentials) with the same `dirname` argument. -Returns `Ok(None)` if the directory or the credentials file does not exist. Returns `Err` when IO or deserialization fails. The returned `Result` may be unwrapped, and the contained `Option` passed to [`connect`](#function-connect). +Returns `Ok(None)` if the directory or the credentials file does not exist. Returns `Err` when IO or deserialization fails. The returned `Result` may be unwrapped, and the contained `Option` passed to [`connect`](#connect-to-a-database-function-connect). ```rust const CREDENTIALS_DIR = ".my-module"; @@ -648,14 +648,14 @@ spacetimedb_sdk::identity::save_credentials( ) -> Result<()> ``` -Store a [`Credentials`](#type-credentials) to a file within `~/dirname`, to be later loaded with [`load_credentials`](#function-load_credentials). +Store a [`Credentials`](#identify-a-client-type-credentials) to a file within `~/dirname`, to be later loaded with [`load_credentials`](#identify-a-client-function-load-credentials). -| Argument | Type | Meaning | -| ------------- | -------------- | ----------------------------------------------------- | -| `dirname` | `&str` | Name of a sub-directory in the user's home directory. | -| `credentials` | `&Credentials` | [`Credentials`](#type-credentials) to store. | +| Argument | Type | Meaning | +| ------------- | -------------- | -------------------------------------------------------------- | +| `dirname` | `&str` | Name of a sub-directory in the user's home directory. | +| `credentials` | `&Credentials` | [`Credentials`](#identify-a-client-type-credentials) to store. | -`dirname` is treated as a directory in the user's home directory. The directory is created if it does not already exists. A file within it named `credentials` is created or replaced, containing `creds` encoded as BSATN. The saved credentials can be retrieved by [`load_credentials`](#function-load_credentials) with the same `dirname` argument. +`dirname` is treated as a directory in the user's home directory. The directory is created if it does not already exists. A file within it named `credentials` is created or replaced, containing `creds` encoded as BSATN. The saved credentials can be retrieved by [`load_credentials`](#identify-a-client-function-load-credentials) with the same `dirname` argument. Returns `Err` when IO or serialization fails. @@ -693,7 +693,7 @@ module_bindings::{TABLE}::filter_by_{COLUMN}( ) -> impl Iterator ``` -For each column of a table, `spacetime generate` generates a static method on the [table struct](#type-table) to filter subscribed rows where that column matches a requested value. +For each column of a table, `spacetime generate` generates a static method on the [table struct](#view-subscribed-rows-of-tables-type-table) to filter subscribed rows where that column matches a requested value. These methods are named `filter_by_{COLUMN}`, where `{COLUMN}` is the column name converted to `snake_case`. The method's return type is an `Iterator` over the `{TABLE}` rows which match the requested value. @@ -705,11 +705,11 @@ module_bindings::{TABLE}::find_by_{COLUMN}( ) -> {FILTER_RESULT}<{TABLE}> ``` -For each unique column of a table (those annotated `#[unique]` and `#[primarykey]`), `spacetime generate` generates a static method on the [table struct](#type-table) to seek a subscribed row where that column matches a requested value. +For each unique column of a table (those annotated `#[unique]` and `#[primarykey]`), `spacetime generate` generates a static method on the [table struct](#view-subscribed-rows-of-tables-type-table) to seek a subscribed row where that column matches a requested value. The method's return type depends on the column's attributes: -- For unique columns, including those annotated `#[unique]` and `#[primarykey]`, the `filter_by` method returns an `Option<{TABLE}>`, where `{TABLE}` is the [table struct](#type-table). +- For unique columns, including those annotated `#[unique]` and `#[primarykey]`, the `filter_by` method returns an `Option<{TABLE}>`, where `{TABLE}` is the [table struct](#view-subscribed-rows-of-tables-type-table). - For non-unique columns, the `filter_by` method returns an `impl Iterator`. These methods are named `find_by_{COLUMN}`, where `{COLUMN}` is the column name converted to `snake_case`. The method's return type is `Option<{TABLE}>`. @@ -719,7 +719,7 @@ The method's return type depends on the column's attributes: spacetimedb_sdk::table::TableType ``` -Every [generated table struct](#type-table) implements the trait `TableType`. +Every [generated table struct](#view-subscribed-rows-of-tables-type-table) implements the trait `TableType`. #### Method `count` @@ -755,7 +755,7 @@ Iterate over all the subscribed rows in the table. This method acquires a global lock, but the iterator does not hold it. -This method must heap-allocate enough memory to hold all of the rows being iterated over. [`TableType::filter`](#method-filter) allocates significantly less, so prefer it when possible. +This method must heap-allocate enough memory to hold all of the rows being iterated over. [`TableType::filter`](#view-subscribed-rows-of-tables-method-filter-by-column) allocates significantly less, so prefer it when possible. ```rust connect(SPACETIMEDB_URI, DB_NAME, None) @@ -793,7 +793,7 @@ The `predicate` is called eagerly for each subscribed row in the table, even if This method must heap-allocate enough memory to hold all of the matching rows, but does not allocate space for subscribed rows which do not match the `predicate`. -Client authors should prefer calling [tables' generated `filter_by_{COLUMN}` methods](#method-filter_by_column) when possible rather than calling `TableType::filter`. +Client authors should prefer calling [tables' generated `filter_by_{COLUMN}` methods](#view-subscribed-rows-of-tables-method-filter-by-column) when possible rather than calling `TableType::filter`. ```rust connect(SPACETIMEDB_URI, DB_NAME, None) @@ -833,7 +833,7 @@ This method acquires a global lock. If multiple subscribed rows match `predicate`, one is chosen arbitrarily. The choice may not be stable across different calls to `find` with the same `predicate`. -Client authors should prefer calling [tables' generated `find_by_{COLUMN}` methods](#method-find_by_column) when possible rather than calling `TableType::find`. +Client authors should prefer calling [tables' generated `find_by_{COLUMN}` methods](#view-subscribed-rows-of-tables-method-find-by-column) when possible rather than calling `TableType::find`. ```rust connect(SPACETIMEDB_URI, DB_NAME, None) @@ -873,9 +873,9 @@ Register an `on_insert` callback for when a subscribed row is newly inserted int The callback takes two arguments: - `row: &Self`, the newly-inserted row value. -- `reducer_event: Option<&ReducerEvent>`, the [`ReducerEvent`](#type-reducerevent) which caused this row to be inserted, or `None` if this row is being inserted while initializing a subscription. +- `reducer_event: Option<&ReducerEvent>`, the [`ReducerEvent`](#observe-and-request-reducer-invocations-type-reducerevent) which caused this row to be inserted, or `None` if this row is being inserted while initializing a subscription. -The returned `InsertCallbackId` can be passed to [`remove_on_insert`](#method-remove_on_insert) to remove the callback. +The returned `InsertCallbackId` can be passed to [`remove_on_insert`](#view-subscribed-rows-of-tables-trait-tabletype-method-remove-on-insert) to remove the callback. ```rust connect(SPACETIMEDB_URI, DB_NAME, None) @@ -903,11 +903,11 @@ sleep(Duration::from_secs(1)); TableType::remove_on_insert(id: InsertCallbackId) ``` -Unregister a previously-registered [`on_insert`](#method-on_insert) callback. +Unregister a previously-registered [`on_insert`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-insert) callback. -| Argument | Type | Meaning | -| -------- | ------------------------ | ----------------------------------------------------------------------- | -| `id` | `InsertCallbackId` | Identifier for the [`on_insert`](#method-on_insert) callback to remove. | +| Argument | Type | Meaning | +| -------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| `id` | `InsertCallbackId` | Identifier for the [`on_insert`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-insert) callback to remove. | If `id` does not refer to a currently-registered callback, this operation does nothing. @@ -944,9 +944,9 @@ Register an `on_delete` callback for when a subscribed row is removed from the d The callback takes two arguments: - `row: &Self`, the previously-present row which is no longer resident in the database. -- `reducer_event: Option<&ReducerEvent>`, the [`ReducerEvent`](#type-reducerevent) which caused this row to be deleted, or `None` if this row was previously subscribed but no longer matches the new queries while initializing a subscription. +- `reducer_event: Option<&ReducerEvent>`, the [`ReducerEvent`](#observe-and-request-reducer-invocations-type-reducerevent) which caused this row to be deleted, or `None` if this row was previously subscribed but no longer matches the new queries while initializing a subscription. -The returned `DeleteCallbackId` can be passed to [`remove_on_delete`](#method-remove_on_delete) to remove the callback. +The returned `DeleteCallbackId` can be passed to [`remove_on_delete`](#view-subscribed-rows-of-tables-trait-tabletype-method-remove-on-delete) to remove the callback. ```rust connect(SPACETIMEDB_URI, DB_NAME, None) @@ -980,11 +980,11 @@ sleep(Duration::from_secs(1)); TableType::remove_on_delete(id: DeleteCallbackId) ``` -Unregister a previously-registered [`on_delete`](#method-on_delete) callback. +Unregister a previously-registered [`on_delete`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-delete) callback. -| Argument | Type | Meaning | -| -------- | ------------------------ | ----------------------------------------------------------------------- | -| `id` | `DeleteCallbackId` | Identifier for the [`on_delete`](#method-on_delete) callback to remove. | +| Argument | Type | Meaning | +| -------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| `id` | `DeleteCallbackId` | Identifier for the [`on_delete`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-delete) callback to remove. | If `id` does not refer to a currently-registered callback, this operation does nothing. @@ -1013,7 +1013,7 @@ sleep(Duration::from_secs(1)); spacetimedb_sdk::table::TableWithPrimaryKey ``` -[Generated table structs](#type-table) with a column designated `#[primarykey]` implement the trait `TableWithPrimaryKey`. +[Generated table structs](#view-subscribed-rows-of-tables-type-table) with a column designated `#[primarykey]` implement the trait `TableWithPrimaryKey`. #### Method `on_update` @@ -1033,9 +1033,9 @@ The callback takes three arguments: - `old: &Self`, the previous row value which has been replaced in the database. - `new: &Self`, the updated row value which is now resident in the database. -- `reducer_event: Option<&ReducerEvent>`, the [`ReducerEvent`](#type-reducerevent) which caused this row to be inserted. +- `reducer_event: Option<&ReducerEvent>`, the [`ReducerEvent`](#observe-and-request-reducer-invocations-type-reducerevent) which caused this row to be inserted. -The returned `UpdateCallbackId` can be passed to [`remove_on_update`](#method-remove_on_update) to remove the callback. +The returned `UpdateCallbackId` can be passed to [`remove_on_update`](#view-subscribed-rows-of-tables-trait-tablewithprimarykey-method-remove-on-update) to remove the callback. ```rust connect(SPACETIMEDB_URI, DB_NAME, None) @@ -1057,11 +1057,11 @@ subscribe(&["SELECT * FROM User;"]) TableWithPrimaryKey::remove_on_update(id: UpdateCallbackId) ``` -| Argument | Type | Meaning | -| -------- | ------------------------ | ----------------------------------------------------------------------- | -| `id` | `UpdateCallbackId` | Identifier for the [`on_update`](#method-on_update) callback to remove. | +| Argument | Type | Meaning | +| -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `UpdateCallbackId` | Identifier for the [`on_update`](#view-subscribed-rows-of-tables-trait-tablewithprimarykey-method-on-update) callback to remove. | -Unregister a previously-registered [`on_update`](#method-on_update) callback. +Unregister a previously-registered [`on_update`](#view-subscribed-rows-of-tables-trait-tablewithprimarykey-method-on-update) callback. If `id` does not refer to a currently-registered callback, this operation does nothing. @@ -1087,9 +1087,9 @@ subscribe(&["SELECT * FROM User;"]) module_bindings::ReducerEvent ``` -`spacetime generate` defines an enum `ReducerEvent` with a variant for each reducer defined by a module. The variant's name will be the reducer's name converted to `PascalCase`, and the variant will hold an instance of [the autogenerated reducer arguments struct for that reducer](#type-reducerargs). +`spacetime generate` defines an enum `ReducerEvent` with a variant for each reducer defined by a module. The variant's name will be the reducer's name converted to `PascalCase`, and the variant will hold an instance of [the autogenerated reducer arguments struct for that reducer](#observe-and-request-reducer-invocations-type-reducer-args). -[`on_insert`](#method-on_insert), [`on_delete`](#method-on_delete) and [`on_update`](#method-on_update) callbacks accept an `Option<&ReducerEvent>` which identifies the reducer which caused the row to be inserted, deleted or updated. +[`on_insert`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-insert), [`on_delete`](#view-subscribed-rows-of-tables-trait-tabletype-method-on-delete) and [`on_update`](#view-subscribed-rows-of-tables-trait-tablewithprimarykey-method-on-update) callbacks accept an `Option<&ReducerEvent>` which identifies the reducer which caused the row to be inserted, deleted or updated. ### Type `{REDUCER}Args` @@ -1127,8 +1127,8 @@ For each reducer defined by a module, `spacetime generate` generates a function The callback always accepts three arguments: -- `caller_id: &Identity`, the [`Identity`](#type-identity) of the client which invoked the reducer. -- `caller_address: Option
`, the [`Address`](#type-address) of the client which invoked the reducer. This may be `None` for scheduled reducers. +- `caller_id: &Identity`, the [`Identity`](#identify-a-client-type-identity) of the client which invoked the reducer. +- `caller_address: Option
`, the [`Address`](#identify-a-client-type-address) of the client which invoked the reducer. This may be `None` for scheduled reducers. In addition, the callback accepts a reference to each of the reducer's arguments. @@ -1137,7 +1137,7 @@ Clients will only be notified of reducer runs if either of two criteria is met: - The reducer inserted, deleted or updated at least one row to which the client is subscribed. - The reducer invocation was requested by this client, and the run failed. -The `on_{REDUCER}` function returns a `ReducerCallbackId<{REDUCER}Args>`, where `{REDUCER}Args` is the [generated reducer arguments struct](#type-reducerargs). This `ReducerCallbackId` can be passed to the [generated `remove_on_{REDUCER}` function](#function-remove_on_reducer) to cancel the callback. +The `on_{REDUCER}` function returns a `ReducerCallbackId<{REDUCER}Args>`, where `{REDUCER}Args` is the [generated reducer arguments struct](#observe-and-request-reducer-invocations-type-reducer-args). This `ReducerCallbackId` can be passed to the [generated `remove_on_{REDUCER}` function](#observe-and-request-reducer-invocations-function-remove-on-reducer) to cancel the callback. ### Function `once_on_{REDUCER}` @@ -1153,11 +1153,11 @@ For each reducer defined by a module, `spacetime generate` generates a function | ---------- | ------------------------------------------------------------------------------- | ----------------------------------------------------- | | `callback` | `impl FnOnce(&Identity, Option
, &Status, {&ARGS...}) + Send + 'static` | Callback to run the next time the reducer is invoked. | -The callback accepts the same arguments as an [on-reducer callback](#function-on_reducer), but may be a `FnOnce` rather than a `FnMut`. +The callback accepts the same arguments as an [on-reducer callback](#observe-and-request-reducer-invocations-function-on-reducer), but may be a `FnOnce` rather than a `FnMut`. The callback will be invoked in the same circumstances as an on-reducer callback. -The `once_on_{REDUCER}` function returns a `ReducerCallbackId<{REDUCER}Args>`, where `{REDUCER}Args` is the [generated reducer arguments struct](#type-reducerargs). This `ReducerCallbackId` can be passed to the [generated `remove_on_{REDUCER}` function](#function-remove_on_reducer) to cancel the callback. +The `once_on_{REDUCER}` function returns a `ReducerCallbackId<{REDUCER}Args>`, where `{REDUCER}Args` is the [generated reducer arguments struct](#observe-and-request-reducer-invocations-type-reducer-args). This `ReducerCallbackId` can be passed to the [generated `remove_on_{REDUCER}` function](#observe-and-request-reducer-invocations-function-remove-on-reducer) to cancel the callback. ### Function `remove_on_{REDUCER}` @@ -1165,11 +1165,11 @@ The `once_on_{REDUCER}` function returns a `ReducerCallbackId<{REDUCER}Args>`, w module_bindings::remove_on_{REDUCER}(id: ReducerCallbackId<{REDUCER}Args>) ``` -For each reducer defined by a module, `spacetime generate` generates a function which unregisters a previously-registered [on-reducer](#function-on_reducer) or [once-on-reducer](#function-once_on_reducer) callback. +For each reducer defined by a module, `spacetime generate` generates a function which unregisters a previously-registered [on-reducer](#observe-and-request-reducer-invocations-function-on-reducer) or [once-on-reducer](#observe-and-request-reducer-invocations-function-once-on-reducer) callback. -| Argument | Type | Meaning | -| -------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -| `id` | `UpdateCallbackId` | Identifier for the [`on_{REDUCER}`](#function-on_reducer) or [`once_on_{REDUCER}`](#function-once_on_reducer) callback to remove. | +| Argument | Type | Meaning | +| -------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `UpdateCallbackId` | Identifier for the [`on_{REDUCER}`](#observe-and-request-reducer-invocations-function-on-reducer) or [`once_on_{REDUCER}`](#observe-and-request-reducer-invocations-function-once-on-reducer) callback to remove. | If `id` does not refer to a currently-registered callback, this operation does nothing. @@ -1181,7 +1181,7 @@ spacetimedb_sdk::reducer::Status An enum whose variants represent possible reducer completion statuses. -A `Status` is passed as the second argument to [`on_{REDUCER}`](#function-on_reducer) and [`once_on_{REDUCER}`](#function-once_on_reducer) callbacks. +A `Status` is passed as the second argument to [`on_{REDUCER}`](#observe-and-request-reducer-invocations-function-on-reducer) and [`once_on_{REDUCER}`](#observe-and-request-reducer-invocations-function-once-on-reducer) callbacks. #### Variant `Status::Committed` diff --git a/content/docs/05-sdk/40-c-sharp-quickstart.md b/content/docs/05-sdk/40-c-sharp-quickstart.md index de0ece5..7c24496 100644 --- a/content/docs/05-sdk/40-c-sharp-quickstart.md +++ b/content/docs/05-sdk/40-c-sharp-quickstart.md @@ -5,11 +5,11 @@ navTitle: C# Quickstart In this guide we'll show you how to get up and running with a simple SpacetimeDB app with a client written in C#. -We'll implement a command-line client for the module created in our [Rust](../../modules/rust/quickstart) or [C# Module](../../modules/c-sharp/quickstart) Quickstart guides. Ensure you followed one of these guides before continuing. +We'll implement a command-line client for the module created in our [Rust](/docs/module/rust-quickstart) or [C# Module](/docs/module/c-sharp-quickstart) Quickstart guides. Ensure you followed one of these guides before continuing. ## Project structure -Enter the directory `quickstart-chat` you created in the [Rust Module Quickstart](/docs/modules/rust/quickstart) or [C# Module Quickstart](/docs/modules/c-sharp/quickstart) guides: +Enter the directory `quickstart-chat` you created in the [Rust Module Quickstart](/docs/module/rust-quickstart) or [C# Module Quickstart](/docs/module/c-sharp-quickstart) guides: ```bash cd quickstart-chat diff --git a/content/docs/05-sdk/41-c-sharp-reference.md b/content/docs/05-sdk/41-c-sharp-reference.md index c384c33..b83bd4e 100644 --- a/content/docs/05-sdk/41-c-sharp-reference.md +++ b/content/docs/05-sdk/41-c-sharp-reference.md @@ -5,55 +5,6 @@ navTitle: C# The SpacetimeDB client C# for Rust contains all the tools you need to build native clients for SpacetimeDB modules using C#. -## Table of Contents - -- [The SpacetimeDB C# client SDK](#the-spacetimedb-c-client-sdk) - - [Table of Contents](#table-of-contents) - - [Install the SDK](#install-the-sdk) - - [Using the `dotnet` CLI tool](#using-the-dotnet-cli-tool) - - [Using Unity](#using-unity) - - [Generate module bindings](#generate-module-bindings) - - [Initialization](#initialization) - - [Property `SpacetimeDBClient.instance`](#property-spacetimedbclientinstance) - - [Class `NetworkManager`](#class-networkmanager) - - [Method `SpacetimeDBClient.Connect`](#method-spacetimedbclientconnect) - - [Event `SpacetimeDBClient.onIdentityReceived`](#event-spacetimedbclientonidentityreceived) - - [Event `SpacetimeDBClient.onConnect`](#event-spacetimedbclientonconnect) - - [Query subscriptions & one-time actions](#subscribe-to-queries) - - [Method `SpacetimeDBClient.Subscribe`](#method-spacetimedbclientsubscribe) - - [Event `SpacetimeDBClient.onSubscriptionApplied`](#event-spacetimedbclientonsubscriptionapplied) - - [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) - - [Static Method `{TABLE}.FilterBy{COLUMN}`](#static-method-tablefilterbycolumn) - - [Static Method `{TABLE}.FindBy{COLUMN}`](#static-method-tablefindbycolumn) - - [Static Method `{TABLE}.Count`](#static-method-tablecount) - - [Static Event `{TABLE}.OnInsert`](#static-event-tableoninsert) - - [Static Event `{TABLE}.OnBeforeDelete`](#static-event-tableonbeforedelete) - - [Static Event `{TABLE}.OnDelete`](#static-event-tableondelete) - - [Static Event `{TABLE}.OnUpdate`](#static-event-tableonupdate) - - [Observe and invoke reducers](#observe-and-invoke-reducers) - - [Class `Reducer`](#class-reducer) - - [Static Method `Reducer.{REDUCER}`](#static-method-reducerreducer) - - [Static Event `Reducer.On{REDUCER}`](#static-event-reduceronreducer) - - [Class `ReducerEvent`](#class-reducerevent) - - [Enum `Status`](#enum-status) - - [Variant `Status.Committed`](#variant-statuscommitted) - - [Variant `Status.Failed`](#variant-statusfailed) - - [Variant `Status.OutOfEnergy`](#variant-statusoutofenergy) - - [Identity management](#identity-management) - - [Class `AuthToken`](#class-authtoken) - - [Static Method `AuthToken.Init`](#static-method-authtokeninit) - - [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) - - [Class `UnityDebugLogger`](#class-unitydebuglogger) - ## Install the SDK ### Using the `dotnet` CLI tool @@ -64,7 +15,7 @@ If you would like to create a console application using .NET, you can create a n dotnet add package spacetimedbsdk ``` -(See also the [CSharp Quickstart](/docs/modules/c-sharp/quickstart) for an in-depth example of such a console application.) +(See also the [CSharp Quickstart](/docs/module/c-sharp-quickstart) for an in-depth example of such a console application.) ### Using Unity @@ -72,7 +23,7 @@ To install the SpacetimeDB SDK into a Unity project, [download the SpacetimeDB S In Unity navigate to the `Assets > Import Package > Custom Package` menu in the menu bar. Select your `SpacetimeDB.Unity.Comprehensive.Tutorial.unitypackage` file and leave all folders checked. -(See also the [Unity Tutorial](/docs/unity/part-1)) +(See also the [Unity Tutorial](/docs/unity-tutorial/part-1)) ## Generate module bindings @@ -107,7 +58,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`](#initialization-property-spacetimedbclient-instance) for you, but will not call [`SpacetimeDBClient.Connect`](#initialization-method-spacetimedbclient-connect), you still need to handle that yourself. See the [Unity Tutorial](/docs/unity-tutorial/overview) for more information. ### Method `SpacetimeDBClient.Connect` @@ -137,7 +88,7 @@ Connect to a database named `addressOrName` accessible over the internet at the | `addressOrName` | `string` | Address or name of the module. | | `sslEnabled` | `bool` | Whether or not to use SSL when connecting to SpacetimeDB. Default: `true`. | -If a `token` is supplied, it will be passed to the new connection to identify and authenticate the user. Otherwise, a new token and [`Identity`](#class-identity) will be generated by the server and returned in [`onConnect`](#event-spacetimedbclientonconnect). +If a `token` is supplied, it will be passed to the new connection to identify and authenticate the user. Otherwise, a new token and [`Identity`](#identity-management-class-identity) will be generated by the server and returned in [`onConnect`](#initialization-event-spacetimedbclient-onconnect). ```cs using SpacetimeDB; @@ -161,7 +112,7 @@ SpacetimeDBClient.instance.onIdentityReceived += (string authToken, Identity ide } ``` -(You should probably also store the returned `Identity` somewhere; see the [`onIdentityReceived`](#event-spacetimedbclientonidentityreceived) event.) +(You should probably also store the returned `Identity` somewhere; see the [`onIdentityReceived`](#initialization-event-spacetimedbclient-onidentityreceived) event.) ### Event `SpacetimeDBClient.onIdentityReceived` @@ -175,9 +126,9 @@ 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`](#identity-management-class-identity) and `Address` from the server. The [`Identity`](#identity-management-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`](#identity-management-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. +To store the auth token to the filesystem, use the static method [`AuthToken.SaveToken`](#identity-management-class-authtoken-static-method-authtoken-savetoken). You may also want to store the returned [`Identity`](#identity-management-class-identity) in a local variable. If an existing auth token is used to connect to the database, the same auth token and the identity it came with will be returned verbatim in `onIdentityReceived`. @@ -206,7 +157,7 @@ class SpacetimeDBClient { Allows registering delegates to be invoked upon authentication with the database. -Once this occurs, the SDK is prepared for calls to [`SpacetimeDBClient.Subscribe`](#method-spacetimedbclientsubscribe). +Once this occurs, the SDK is prepared for calls to [`SpacetimeDBClient.Subscribe`](#subscribe-to-queries-method-spacetimedbclient-subscribe). ## Subscribe to queries @@ -228,11 +179,11 @@ class SpacetimeDBClient { Subscribe to a set of queries, to be notified when rows which match those queries are altered. -`Subscribe` will return an error if called before establishing a connection with the [`SpacetimeDBClient.Connect`](#method-spacetimedbclientconnect) function. In that case, the queries are not registered. +`Subscribe` will return an error if called before establishing a connection with the [`SpacetimeDBClient.Connect`](#initialization-method-spacetimedbclient-connect) function. In that case, the queries are not registered. -The `Subscribe` method does not return data directly. `spacetime generate` will generate classes [`SpacetimeDB.Types.{TABLE}`](#class-table) for each table in your module. These classes are used to reecive information from the database. See the section [View Rows of Subscribed Tables](#view-rows-of-subscribed-tables) for more information. +The `Subscribe` method does not return data directly. `spacetime generate` will generate classes [`SpacetimeDB.Types.{TABLE}`](#view-rows-of-subscribed-tables-class-table) for each table in your module. These classes are used to reecive information from the database. See the section [View Rows of Subscribed Tables](#view-rows-of-subscribed-tables) for more information. -A new call to `Subscribe` will remove all previous subscriptions and replace them with the new `queries`. If any rows matched the previous subscribed queries but do not match the new queries, those rows will be removed from the client cache, and [`{TABLE}.OnDelete`](#static-event-tableoninsert) callbacks will be invoked for them. +A new call to `Subscribe` will remove all previous subscriptions and replace them with the new `queries`. If any rows matched the previous subscribed queries but do not match the new queries, those rows will be removed from the client cache, and [`{TABLE}.OnDelete`](#view-rows-of-subscribed-tables-class-table-static-event-table-oninsert) callbacks will be invoked for them. ```cs using SpacetimeDB; @@ -305,31 +256,31 @@ SpacetimeDBClient.instance.OneOffQuery("WHERE sender = \"bob\""); ## View rows of subscribed tables -The SDK maintains a local view of the database called the "client cache". This cache contains whatever rows are selected via a call to [`SpacetimeDBClient.Subscribe`](#method-spacetimedbclientsubscribe). These rows are represented in the SpacetimeDB .Net SDK as instances of [`SpacetimeDB.Types.{TABLE}`](#class-table). +The SDK maintains a local view of the database called the "client cache". This cache contains whatever rows are selected via a call to [`SpacetimeDBClient.Subscribe`](#subscribe-to-queries-method-spacetimedbclient-subscribe). These rows are represented in the SpacetimeDB .Net SDK as instances of [`SpacetimeDB.Types.{TABLE}`](#view-rows-of-subscribed-tables-class-table). -ONLY the rows selected in a [`SpacetimeDBClient.Subscribe`](#method-spacetimedbclientsubscribe) call will be available in the client cache. All operations in the client sdk operate on these rows exclusively, and have no information about the state of the rest of the database. +ONLY the rows selected in a [`SpacetimeDBClient.Subscribe`](#subscribe-to-queries-method-spacetimedbclient-subscribe) call will be available in the client cache. All operations in the client sdk operate on these rows exclusively, and have no information about the state of the rest of the database. In particular, SpacetimeDB does not support foreign key constraints. This means that if you are using a column as a foreign key, SpacetimeDB will not automatically bring in all of the rows that key might reference. You will need to manually subscribe to all tables you need information from. -To optimize network performance, prefer selecting as few rows as possible in your [`Subscribe`](#method-spacetimedbclientsubscribe) query. Processes that need to view the entire state of the database are better run inside the database -- that is, inside modules. +To optimize network performance, prefer selecting as few rows as possible in your [`Subscribe`](#subscribe-to-queries-method-spacetimedbclient-subscribe) query. Processes that need to view the entire state of the database are better run inside the database -- that is, inside modules. ### Class `{TABLE}` -For each table defined by a module, `spacetime generate` will generate a class [`SpacetimeDB.Types.{TABLE}`](#class-table) whose name is that table's name converted to `PascalCase`. The generated class contains a property for each of the table's columns, whose names are the column names converted to `camelCase`. It also contains various static events and methods. +For each table defined by a module, `spacetime generate` will generate a class [`SpacetimeDB.Types.{TABLE}`](#view-rows-of-subscribed-tables-class-table) whose name is that table's name converted to `PascalCase`. The generated class contains a property for each of the table's columns, whose names are the column names converted to `camelCase`. It also contains various static events and methods. Static Methods: -- [`{TABLE}.Iter()`](#static-method-tableiter) iterates all subscribed rows in the client cache. -- [`{TABLE}.FilterBy{COLUMN}(value)`](#static-method-tablefilterbycolumn) filters subscribed rows in the client cache by a column value. -- [`{TABLE}.FindBy{COLUMN}(value)`](#static-method-tablefindbycolumn) finds a subscribed row in the client cache by a unique column value. -- [`{TABLE}.Count()`](#static-method-tablecount) counts the number of subscribed rows in the client cache. +- [`{TABLE}.Iter()`](#view-rows-of-subscribed-tables-class-table-static-method-table-iter) iterates all subscribed rows in the client cache. +- [`{TABLE}.FilterBy{COLUMN}(value)`](#view-rows-of-subscribed-tables-class-table-static-method-table-filterby-column) filters subscribed rows in the client cache by a column value. +- [`{TABLE}.FindBy{COLUMN}(value)`](#view-rows-of-subscribed-tables-class-table-static-method-table-findby-column) finds a subscribed row in the client cache by a unique column value. +- [`{TABLE}.Count()`](#view-rows-of-subscribed-tables-class-table-static-method-table-count) counts the number of subscribed rows in the client cache. Static Events: -- [`{TABLE}.OnInsert`](#static-event-tableoninsert) is called when a row is inserted into the client cache. -- [`{TABLE}.OnBeforeDelete`](#static-event-tableonbeforedelete) is called when a row is about to be removed from the client cache. -- If the table has a primary key attribute, [`{TABLE}.OnUpdate`](#static-event-tableonupdate) is called when a row is updated. -- [`{TABLE}.OnDelete`](#static-event-tableondelete) is called while a row is being removed from the client cache. You should almost always use [`{TABLE}.OnBeforeDelete`](#static-event-tableonbeforedelete) instead. +- [`{TABLE}.OnInsert`](#view-rows-of-subscribed-tables-class-table-static-event-table-oninsert) is called when a row is inserted into the client cache. +- [`{TABLE}.OnBeforeDelete`](#view-rows-of-subscribed-tables-class-table-static-event-table-onbeforedelete) is called when a row is about to be removed from the client cache. +- If the table has a primary key attribute, [`{TABLE}.OnUpdate`](#view-rows-of-subscribed-tables-class-table-static-event-table-onupdate) is called when a row is updated. +- [`{TABLE}.OnDelete`](#view-rows-of-subscribed-tables-class-table-static-event-table-ondelete) is called while a row is being removed from the client cache. You should almost always use [`{TABLE}.OnBeforeDelete`](#view-rows-of-subscribed-tables-class-table-static-event-table-onbeforedelete) instead. Note that it is not possible to directly insert into the database from the client SDK! All insertion validation should be performed inside serverside modules for security reasons. You can instead [invoke reducers](#observe-and-invoke-reducers), which run code inside the database that can insert rows for you. @@ -345,9 +296,9 @@ class TABLE { } ``` -Iterate over all the subscribed rows in the table. This method is only available after [`SpacetimeDBClient.onSubscriptionApplied`](#event-spacetimedbclientonsubscriptionapplied) has occurred. +Iterate over all the subscribed rows in the table. This method is only available after [`SpacetimeDBClient.onSubscriptionApplied`](#subscribe-to-queries-event-spacetimedbclient-onsubscriptionapplied) has occurred. -When iterating over rows and filtering for those containing a particular column, [`{TABLE}.FilterBy{COLUMN}`](#static-method-tablefilterbycolumn) and [`{TABLE}.FindBy{COLUMN}`](#static-method-tablefindbycolumn) will be more efficient, so prefer those when possible. +When iterating over rows and filtering for those containing a particular column, [`{TABLE}.FilterBy{COLUMN}`](#view-rows-of-subscribed-tables-class-table-static-method-table-filterby-column) and [`{TABLE}.FindBy{COLUMN}`](#view-rows-of-subscribed-tables-class-table-static-method-table-findby-column) will be more efficient, so prefer those when possible. ```cs using SpacetimeDB; @@ -377,9 +328,9 @@ class TABLE { } ``` -For each column of a table, `spacetime generate` generates a static method on the [table class](#class-table) to filter subscribed rows where that column matches a requested value. +For each column of a table, `spacetime generate` generates a static method on the [table class](#view-rows-of-subscribed-tables-class-table) to filter subscribed rows where that column matches a requested value. -These methods are named `filterBy{COLUMN}`, where `{COLUMN}` is the column name converted to `PascalCase`. The method's return type is an `IEnumerable` over the [table class](#class-table). +These methods are named `filterBy{COLUMN}`, where `{COLUMN}` is the column name converted to `PascalCase`. The method's return type is an `IEnumerable` over the [table class](#view-rows-of-subscribed-tables-class-table). #### Static Method `{TABLE}.FindBy{COLUMN}` @@ -394,9 +345,9 @@ class TABLE { } ``` -For each unique column of a table (those annotated `#[unique]` or `#[primarykey]`), `spacetime generate` generates a static method on the [table class](#class-table) to seek a subscribed row where that column matches a requested value. +For each unique column of a table (those annotated `#[unique]` or `#[primarykey]`), `spacetime generate` generates a static method on the [table class](#view-rows-of-subscribed-tables-class-table) to seek a subscribed row where that column matches a requested value. -These methods are named `findBy{COLUMN}`, where `{COLUMN}` is the column name converted to `PascalCase`. Those methods return a single instance of the [table class](#class-table) if a row is found, or `null` if no row matches the query. +These methods are named `findBy{COLUMN}`, where `{COLUMN}` is the column name converted to `PascalCase`. Those methods return a single instance of the [table class](#view-rows-of-subscribed-tables-class-table) if a row is found, or `null` if no row matches the query. #### Static Method `{TABLE}.Count` @@ -445,7 +396,7 @@ Register a delegate for when a subscribed row is newly inserted into the databas The delegate takes two arguments: -- A [`{TABLE}`](#class-table) instance with the data of the inserted row +- A [`{TABLE}`](#view-rows-of-subscribed-tables-class-table) instance with the data of the inserted row - A [`ReducerEvent?`], which contains the data of the reducer that inserted the row, or `null` if the row is being inserted while initializing a subscription. ```cs @@ -483,10 +434,10 @@ Register a delegate for when a subscribed row is about to be deleted from the da The delegate takes two arguments: -- A [`{TABLE}`](#class-table) instance with the data of the deleted row -- A [`ReducerEvent`](#class-reducerevent), which contains the data of the reducer that deleted the row. +- A [`{TABLE}`](#view-rows-of-subscribed-tables-class-table) instance with the data of the deleted row +- A [`ReducerEvent`](#observe-and-invoke-reducers-class-reducerevent), which contains the data of the reducer that deleted the row. -This event should almost always be used instead of [`OnDelete`](#static-event-tableondelete). This is because often, many rows will be deleted at once, and `OnDelete` can be invoked in an arbitrary order on these rows. This means that data related to a row may already be missing when `OnDelete` is called. `OnBeforeDelete` does not have this problem. +This event should almost always be used instead of [`OnDelete`](#view-rows-of-subscribed-tables-class-table-static-event-table-ondelete). This is because often, many rows will be deleted at once, and `OnDelete` can be invoked in an arbitrary order on these rows. This means that data related to a row may already be missing when `OnDelete` is called. `OnBeforeDelete` does not have this problem. ```cs using SpacetimeDB; @@ -515,12 +466,12 @@ class TABLE { } ``` -Register a delegate for when a subscribed row is being deleted from the database. If a reducer deletes many rows at once, this delegate will be invoked on those rows in arbitrary order, and data for some rows may already be missing when it is invoked. For this reason, prefer the event [`{TABLE}.OnBeforeDelete`](#static-event-tableonbeforedelete). +Register a delegate for when a subscribed row is being deleted from the database. If a reducer deletes many rows at once, this delegate will be invoked on those rows in arbitrary order, and data for some rows may already be missing when it is invoked. For this reason, prefer the event [`{TABLE}.OnBeforeDelete`](#view-rows-of-subscribed-tables-class-table-static-event-table-onbeforedelete). The delegate takes two arguments: -- A [`{TABLE}`](#class-table) instance with the data of the deleted row -- A [`ReducerEvent`](#class-reducerevent), which contains the data of the reducer that deleted the row. +- A [`{TABLE}`](#view-rows-of-subscribed-tables-class-table) instance with the data of the deleted row +- A [`ReducerEvent`](#observe-and-invoke-reducers-class-reducerevent), which contains the data of the reducer that deleted the row. ```cs using SpacetimeDB; @@ -554,9 +505,9 @@ Register a delegate for when a subscribed row is being updated. This event is on The delegate takes three arguments: -- A [`{TABLE}`](#class-table) instance with the old data of the updated row -- A [`{TABLE}`](#class-table) instance with the new data of the updated row -- A [`ReducerEvent`](#class-reducerevent), which contains the data of the reducer that updated the row. +- A [`{TABLE}`](#view-rows-of-subscribed-tables-class-table) instance with the old data of the updated row +- A [`{TABLE}`](#view-rows-of-subscribed-tables-class-table) instance with the new data of the updated row +- A [`ReducerEvent`](#observe-and-invoke-reducers-class-reducerevent), which contains the data of the reducer that updated the row. ```cs using SpacetimeDB; @@ -576,7 +527,7 @@ User.OnUpdate += (User oldUser, User newUser, ReducerEvent reducerEvent) => { "Reducer" is SpacetimeDB's name for the stored procedures that run in modules inside the database. You can invoke reducers from a connected client SDK, and also receive information about which reducers are running. -`spacetime generate` generates a class [`SpacetimeDB.Types.Reducer`](#class-reducer) that contains methods and events for each reducer defined in a module. To invoke a reducer, use the method [`Reducer.{REDUCER}`](#static-method-reducerreducer) generated for it. To receive a callback each time a reducer is invoked, use the static event [`Reducer.On{REDUCER}`](#static-event-reduceronreducer). +`spacetime generate` generates a class [`SpacetimeDB.Types.Reducer`](#observe-and-invoke-reducers-class-reducer) that contains methods and events for each reducer defined in a module. To invoke a reducer, use the method [`Reducer.{REDUCER}`](#observe-and-invoke-reducers-class-reducer-static-method-reducer-reducer) generated for it. To receive a callback each time a reducer is invoked, use the static event [`Reducer.On{REDUCER}`](#observe-and-invoke-reducers-class-reducer-static-event-reducer-on-reducer). ### Class `Reducer` @@ -647,7 +598,7 @@ public static event /*{REDUCER}*/Handler On/*{REDUCER}*/Event; For each reducer defined by a module, `spacetime generate` generates an event to run each time the reducer is invoked. The generated functions are named `on{REDUCER}Event`, where `{REDUCER}` is the reducer's name converted to `PascalCase`. -The first argument to the event handler is an instance of [`SpacetimeDB.Types.ReducerEvent`](#class-reducerevent) describing the invocation -- its timestamp, arguments, and whether it succeeded or failed. The remaining arguments are the arguments passed to the reducer. Reducers cannot have return values, so no return value information is included. +The first argument to the event handler is an instance of [`SpacetimeDB.Types.ReducerEvent`](#observe-and-invoke-reducers-class-reducerevent) describing the invocation -- its timestamp, arguments, and whether it succeeded or failed. The remaining arguments are the arguments passed to the reducer. Reducers cannot have return values, so no return value information is included. For example, if we define a reducer in Rust as follows: @@ -885,15 +836,15 @@ namespace SpacetimeDB } ``` -An opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#class-identity). +An opaque identifier for a client connection to a database, intended to differentiate between connections from the same [`Identity`](#identity-management-class-identity). ## Customizing logging The SpacetimeDB C# SDK performs internal logging. -A default logger is set up automatically for you - a [`ConsoleLogger`](#class-consolelogger) for C# projects and [`UnityDebugLogger`](#class-unitydebuglogger) for Unity projects. +A default logger is set up automatically for you - a [`ConsoleLogger`](#customizing-logging-class-consolelogger) for C# projects and [`UnityDebugLogger`](#customizing-logging-class-unitydebuglogger) for Unity projects. -If you want to redirect SDK logs elsewhere, you can inherit from the [`ISpacetimeDBLogger`](#interface-ispacetimedblogger) and assign an instance of your class to the `SpacetimeDB.Logger.Current` static property. +If you want to redirect SDK logs elsewhere, you can inherit from the [`ISpacetimeDBLogger`](#customizing-logging-interface-ispacetimedblogger) and assign an instance of your class to the `SpacetimeDB.Logger.Current` static property. ### Interface `ISpacetimeDBLogger` diff --git a/content/docs/06-webassembly-abi/00-overview.md b/content/docs/06-webassembly-abi/00-overview.md index c012c95..9a24481 100644 --- a/content/docs/06-webassembly-abi/00-overview.md +++ b/content/docs/06-webassembly-abi/00-overview.md @@ -3,9 +3,9 @@ title: Module ABI Reference navTitle: Module ABI --- -This document specifies the _low level details_ of module-host interactions (_"Module ABI"_). _**Most users**_ looking to interact with the host will want to use derived and higher level functionality like [`bindings`], `#[spacetimedb(table)]`, and `#[derive(SpacetimeType)]` rather than this low level ABI. For more on those, read the [Rust module quick start][module_quick_start] guide and the [Rust module reference][module_ref]. +This document specifies the _low level details_ of module-host interactions (_"Module ABI"_). _**Most users**_ looking to interact with the host will want to use derived and higher level functionality like [`bindings`](https://github.com/clockworklabs/SpacetimeDB/blob/master/crates/bindings/src/lib.rs), `#[spacetimedb(table)]`, and `#[derive(SpacetimeType)]` rather than this low level ABI. For more on those, read the [Rust module quick start](/docs/module/rust-quickstart) guide and the [Rust module reference](/docs/module/rust-reference). -The Module ABI is defined in [`bindings_sys::raw`] and is used by modules to interact with their host and perform various operations like: +The Module ABI is defined in [`bindings_sys::raw`](https://github.com/clockworklabs/SpacetimeDB/blob/master/crates/bindings-sys/src/lib.rs#L44-L215) and is used by modules to interact with their host and perform various operations like: - logging, - transporting data, @@ -18,7 +18,7 @@ In the next few sections, we'll define the functions that make up the ABI and wh ## General notes -The functions in this ABI all use the [`C` ABI on the `wasm32` platform][wasm_c_abi]. They are specified in a Rust `extern "C" { .. }` block. For those more familiar with the `C` notation, an [appendix][c_header] is provided with equivalent definitions as would occur in a `.h` file. +The functions in this ABI all use the [`C` ABI on the `wasm32` platform](https://github.com/WebAssembly/tool-conventions/blob/main/BasicCABI.md). They are specified in a Rust `extern "C" { .. }` block. For those more familiar with the `C` notation, an [appendix](#appendix-bindings-h) is provided with equivalent definitions as would occur in a `.h` file. Many functions in the ABI take in- or out-pointers, e.g. `*const u8` and `*mut u8`. The WASM host itself does not have undefined behavior. However, what WASM does not consider a memory access violation could be one according to some other language's abstract machine. For example, running the following on a WASM host would violate Rust's rules around writing across allocations: @@ -493,10 +493,3 @@ uint16_t _iter_start_filtered( BufferIter *out ); ``` - -[`bindings_sys::raw`]: https://github.com/clockworklabs/SpacetimeDB/blob/master/crates/bindings-sys/src/lib.rs#L44-L215 -[`bindings`]: https://github.com/clockworklabs/SpacetimeDB/blob/master/crates/bindings/src/lib.rs -[module_ref]: /docs/languages/rust/rust-module-reference -[module_quick_start]: /docs/languages/rust/rust-module-quick-start -[wasm_c_abi]: https://github.com/WebAssembly/tool-conventions/blob/main/BasicCABI.md -[c_header]: #appendix-bindingsh diff --git a/content/docs/07-http/00-overview.md b/content/docs/07-http/00-overview.md index 5e5e131..16e5f4a 100644 --- a/content/docs/07-http/00-overview.md +++ b/content/docs/07-http/00-overview.md @@ -11,7 +11,7 @@ Rather than a password, each Spacetime identity is associated with a private tok Clients can request a new identity and token via [the `/identity POST` HTTP endpoint](/docs/http/identity#identity-post). -Alternately, a new identity and token will be generated during an anonymous connection via the [WebSocket API](/docs/ws), and passed to the client as [an `IdentityToken` message](/docs/ws#identitytoken). +Alternately, a new identity and token will be generated during an anonymous connection via the [WebSocket API](/docs/ws/overview), and passed to the client as [an `IdentityToken` message](/docs/ws/overview#messages-server-to-client-identitytoken). ## Encoding `Authorization` headers diff --git a/content/docs/07-http/01-identity.md b/content/docs/07-http/01-identity.md index 0775a23..1b2cbb6 100644 --- a/content/docs/07-http/01-identity.md +++ b/content/docs/07-http/01-identity.md @@ -7,14 +7,14 @@ The HTTP endpoints in `/identity` allow clients to generate and manage Spacetime ## At a glance -| Route | Description | -| ----------------------------------------------------------------------- | ------------------------------------------------------------------ | -| [`/identity GET`](#identity-get) | Look up an identity by email. | -| [`/identity POST`](#identity-post) | Generate a new identity and token. | -| [`/identity/websocket_token POST`](#identitywebsocket_token-post) | Generate a short-lived access token for use in untrusted contexts. | -| [`/identity/:identity/set-email POST`](#identityidentityset-email-post) | Set the email for an identity. | -| [`/identity/:identity/databases GET`](#identityidentitydatabases-get) | List databases owned by an identity. | -| [`/identity/:identity/verify GET`](#identityidentityverify-get) | Verify an identity and token. | +| Route | Description | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| [`/identity GET`](#identity-get) | Look up an identity by email. | +| [`/identity POST`](#identity-post) | Generate a new identity and token. | +| [`/identity/websocket_token POST`](#identity-websocket-token-post) | Generate a short-lived access token for use in untrusted contexts. | +| [`/identity/:identity/set-email POST`](#identity-identity-set-email-post) | Set the email for an identity. | +| [`/identity/:identity/databases GET`](#identity-identity-databases-get) | List databases owned by an identity. | +| [`/identity/:identity/verify GET`](#identity-identity-verify-get) | Verify an identity and token. | ## `/identity GET` @@ -74,9 +74,9 @@ Generate a short-lived access token which can be used in untrusted contexts, e.g ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ### Returns @@ -110,9 +110,9 @@ Accessible through the CLI as `spacetime identity set-email `. ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ## `/identity/:identity/databases GET` @@ -148,9 +148,9 @@ Verify the validity of an identity/token pair. ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ### Returns diff --git a/content/docs/07-http/02-database.md b/content/docs/07-http/02-database.md index 6c5d7af..5725041 100644 --- a/content/docs/07-http/02-database.md +++ b/content/docs/07-http/02-database.md @@ -7,24 +7,24 @@ The HTTP endpoints in `/database` allow clients to interact with Spacetime datab ## At a glance -| Route | Description | -| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -| [`/database/dns/:name GET`](#databasednsname-get) | Look up a database's address by its name. | -| [`/database/reverse_dns/:address GET`](#databasereverse_dnsaddress-get) | Look up a database's name by its address. | -| [`/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). | -| [`/database/call/:name_or_address/:reducer POST`](#databasecallname_or_addressreducer-post) | Invoke a reducer in a database. | -| [`/database/schema/:name_or_address GET`](#databaseschemaname_or_address-get) | Get the schema for a database. | -| [`/database/schema/:name_or_address/:entity_type/:entity GET`](#databaseschemaname_or_addressentity_typeentity-get) | Get a schema for a particular table or reducer. | -| [`/database/info/:name_or_address GET`](#databaseinfoname_or_address-get) | Get a JSON description of a database. | -| [`/database/logs/:name_or_address GET`](#databaselogsname_or_address-get) | Retrieve logs from a database. | -| [`/database/sql/:name_or_address POST`](#databasesqlname_or_address-post) | Run a SQL query against a database. | +| Route | Description | +| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| [`/database/dns/:name GET`](#database-dns-name-get) | Look up a database's address by its name. | +| [`/database/reverse_dns/:address GET`](#database-reverse-dns-address-get) | Look up a database's name by its address. | +| [`/database/set_name GET`](#database-set-name-get) | Set a database's name, given its address. | +| [`/database/ping GET`](#database-ping-get) | No-op. Used to determine whether a client can connect. | +| [`/database/register_tld GET`](#database-register-tld-get) | Register a top-level domain. | +| [`/database/request_recovery_code GET`](#database-request-recovery-code-get) | Request a recovery code to the email associated with an identity. | +| [`/database/confirm_recovery_code GET`](#database-confirm-recovery-code-get) | Recover a login token from a recovery code. | +| [`/database/publish POST`](#database-publish-post) | Publish a database given its module code. | +| [`/database/delete/:address POST`](#database-delete-address-post) | Delete a database. | +| [`/database/subscribe/:name_or_address GET`](#database-subscribe-name-or-address-get) | Begin a [WebSocket connection](/docs/ws/overview). | +| [`/database/call/:name_or_address/:reducer POST`](#database-call-name-or-address-reducer-post) | Invoke a reducer in a database. | +| [`/database/schema/:name_or_address GET`](#database-schema-name-or-address-get) | Get the schema for a database. | +| [`/database/schema/:name_or_address/:entity_type/:entity GET`](#database-schema-name-or-address-entity-type-entity-get) | Get a schema for a particular table or reducer. | +| [`/database/info/:name_or_address GET`](#database-info-name-or-address-get) | Get a JSON description of a database. | +| [`/database/logs/:name_or_address GET`](#database-logs-name-or-address-get) | Retrieve logs from a database. | +| [`/database/sql/:name_or_address POST`](#database-sql-name-or-address-post) | Run a SQL query against a database. | ## `/database/dns/:name GET` @@ -95,9 +95,9 @@ Accessible through the CLI as `spacetime dns set-name
`. ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ### Returns @@ -148,9 +148,9 @@ Accessible through the CLI as `spacetime dns register-tld `. ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ### Returns @@ -186,15 +186,15 @@ Accessible through the CLI as `spacetime identity recover `. ### 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. | +| 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#identity-identity-set-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. +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 `. @@ -232,9 +232,9 @@ Accessible through the CLI as `spacetime publish`. ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ### Data @@ -284,13 +284,13 @@ Accessible through the CLI as `spacetime delete
`. ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ## `/database/subscribe/:name_or_address GET` -Begin a [WebSocket connection](/docs/ws) with a database. +Begin a [WebSocket connection](/docs/ws/overview) with a database. ### Parameters @@ -302,19 +302,19 @@ Begin a [WebSocket connection](/docs/ws) with a database. For more information about WebSocket headers, see [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455). -| Name | Value | -| ------------------------ | ---------------------------------------------------------------------------------------------------- | -| `Sec-WebSocket-Protocol` | [`v1.bin.spacetimedb`](/docs/ws#binary-protocol) or [`v1.text.spacetimedb`](/docs/ws#text-protocol). | -| `Connection` | `Updgrade` | -| `Upgrade` | `websocket` | -| `Sec-WebSocket-Version` | `13` | -| `Sec-WebSocket-Key` | A 16-byte value, generated randomly by the client, encoded as Base64. | +| Name | Value | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `Sec-WebSocket-Protocol` | [`v1.bin.spacetimedb`](/docs/ws/overview#protocols-binary-protocol) or [`v1.text.spacetimedb`](/docs/ws/overview#protocols-text-protocol). | +| `Connection` | `Updgrade` | +| `Upgrade` | `websocket` | +| `Sec-WebSocket-Version` | `13` | +| `Sec-WebSocket-Key` | A 16-byte value, generated randomly by the client, encoded as Base64. | ### Optional Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ## `/database/call/:name_or_address/:reducer POST` @@ -329,9 +329,9 @@ Invoke a reducer in a database. ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ### Data @@ -447,13 +447,13 @@ The `"entities"` will be an object whose keys are table and reducer names, and w } ``` -| Entity field | Value | -| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `arity` | For tables, the number of colums; for reducers, the number of arguments. | -| `type` | For tables, `"table"`; for reducers, `"reducer"`. | -| `schema` | A [JSON-encoded `ProductType`](/docs/satn); for tables, the table schema; for reducers, the argument schema. Only present if `expand` is supplied and true. | +| Entity field | Value | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `arity` | For tables, the number of colums; for reducers, the number of arguments. | +| `type` | For tables, `"table"`; for reducers, `"reducer"`. | +| `schema` | A [JSON-encoded `ProductType`](/docs/data-format/satn); for tables, the table schema; for reducers, the argument schema. Only present if `expand` is supplied and true. | -The `"typespace"` will be a JSON array of [`AlgebraicType`s](/docs/satn) referenced by the module. This can be used to resolve `Ref` types within the schema; the type `{ "Ref": n }` refers to `response["typespace"][n]`. +The `"typespace"` will be a JSON array of [`AlgebraicType`s](/docs/data-format/satn) referenced by the module. This can be used to resolve `Ref` types within the schema; the type `{ "Ref": n }` refers to `response["typespace"][n]`. ## `/database/schema/:name_or_address/:entity_type/:entity GET` @@ -477,7 +477,7 @@ Accessible through the CLI as `spacetime describe `. ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ### Returns @@ -566,9 +566,9 @@ Accessible through the CLI as `spacetime sql `. ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ### Data @@ -585,6 +585,6 @@ Returns a JSON array of statement results, each of which takes the form: } ``` -The `schema` will be a [JSON-encoded `ProductType`](/docs/satn) describing the type of the returned rows. +The `schema` will be a [JSON-encoded `ProductType`](/docs/data-format/satn) describing the type of the returned rows. -The `rows` will be an array of [JSON-encoded `ProductValue`s](/docs/satn), each of which conforms to the `schema`. +The `rows` will be an array of [JSON-encoded `ProductValue`s](/docs/data-format/satn), each of which conforms to the `schema`. diff --git a/content/docs/07-http/03-energy.md b/content/docs/07-http/03-energy.md index 7c2cf7c..a2c07a5 100644 --- a/content/docs/07-http/03-energy.md +++ b/content/docs/07-http/03-energy.md @@ -7,10 +7,10 @@ The HTTP endpoints in `/energy` allow clients to query identities' energy balanc ## At a glance -| Route | Description | -| ------------------------------------------------ | --------------------------------------------------------- | -| [`/energy/:identity GET`](#energyidentity-get) | Get the remaining energy balance for the user `identity`. | -| [`/energy/:identity POST`](#energyidentity-post) | Set the energy balance for the user `identity`. | +| Route | Description | +| ------------------------------------------------- | --------------------------------------------------------- | +| [`/energy/:identity GET`](#energy-identity-get) | Get the remaining energy balance for the user `identity`. | +| [`/energy/:identity POST`](#energy-identity-post) | Set the energy balance for the user `identity`. | ## `/energy/:identity GET` @@ -60,9 +60,9 @@ Accessible through the CLI as `spacetime energy set-balance ### Required Headers -| Name | Value | -| --------------- | --------------------------------------------------------------- | -| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http). | +| Name | Value | +| --------------- | ------------------------------------------------------------------------ | +| `Authorization` | A Spacetime token [encoded as Basic authorization](/docs/http/overview). | ### Returns diff --git a/content/docs/08-ws/00-overview.md b/content/docs/08-ws/00-overview.md index f584ad2..1e54995 100644 --- a/content/docs/08-ws/00-overview.md +++ b/content/docs/08-ws/00-overview.md @@ -3,43 +3,43 @@ title: WebSocket API navTitle: WebSocket --- -As an extension of the [HTTP API](/doc/http-api-reference), SpacetimeDB offers a WebSocket API. Clients can subscribe to a database via a WebSocket connection to receive streaming updates as the database changes, and send requests to invoke reducers. Messages received from the server over a WebSocket will follow the same total ordering of transactions as are committed to the database. +As an extension of the [HTTP API](/docs/http/overview), SpacetimeDB offers a WebSocket API. Clients can subscribe to a database via a WebSocket connection to receive streaming updates as the database changes, and send requests to invoke reducers. Messages received from the server over a WebSocket will follow the same total ordering of transactions as are committed to the database. The SpacetimeDB SDKs comminicate with their corresponding database using the WebSocket API. ## Connecting -To initiate a WebSocket connection, send a `GET` request to the [`/database/subscribe/:name_or_address` endpoint](/docs/http/database#databasesubscribename_or_address-get) with headers appropriate to upgrade to a WebSocket connection as per [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455). +To initiate a WebSocket connection, send a `GET` request to the [`/database/subscribe/:name_or_address` endpoint](/docs/http/database#database-subscribe-name-or-address-get) with headers appropriate to upgrade to a WebSocket connection as per [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455). -To re-connect with an existing identity, include its token in a [SpacetimeDB Authorization header](/docs/http). Otherwise, a new identity and token will be generated for the client. +To re-connect with an existing identity, include its token in a [SpacetimeDB Authorization header](/docs/http/overview#encoding-authorization-headers). Otherwise, a new identity and token will be generated for the client. ## Protocols -Clients connecting via WebSocket can choose between two protocols, [`v1.bin.spacetimedb`](#binary-protocol) and [`v1.text.spacetimedb`](#text-protocol). Clients should include one of these protocols in the `Sec-WebSocket-Protocol` header of their request. +Clients connecting via WebSocket can choose between two protocols, [`v1.bin.spacetimedb`](#protocols-binary-protocol) and [`v1.text.spacetimedb`](#protocols-text-protocol). Clients should include one of these protocols in the `Sec-WebSocket-Protocol` header of their request. -| `Sec-WebSocket-Protocol` header value | Selected protocol | -| ------------------------------------- | -------------------------- | -| `v1.bin.spacetimedb` | [Binary](#binary-protocol) | -| `v1.text.spacetimedb` | [Text](#text-protocol) | +| `Sec-WebSocket-Protocol` header value | Selected protocol | +| ------------------------------------- | ------------------------------------ | +| `v1.bin.spacetimedb` | [Binary](#protocols-binary-protocol) | +| `v1.text.spacetimedb` | [Text](#protocols-text-protocol) | ### Binary Protocol -The SpacetimeDB binary WebSocket protocol, `v1.bin.spacetimedb`, encodes messages using [ProtoBuf 3](https://protobuf.dev), and reducer and row data using [BSATN](/docs/bsatn). +The SpacetimeDB binary WebSocket protocol, `v1.bin.spacetimedb`, encodes messages using [ProtoBuf 3](https://protobuf.dev), and reducer and row data using [BSATN](/docs/data-format/bsatn). The binary protocol's messages are defined in [`client_api.proto`](https://github.com/clockworklabs/SpacetimeDB/blob/master/crates/client-api-messages/protobuf/client_api.proto). ### Text Protocol -The SpacetimeDB text WebSocket protocol, `v1.text.spacetimedb`, encodes messages, reducer and row data as JSON. Reducer arguments and table rows are JSON-encoded according to the [SATN JSON format](/docs/satn). +The SpacetimeDB text WebSocket protocol, `v1.text.spacetimedb`, encodes messages, reducer and row data as JSON. Reducer arguments and table rows are JSON-encoded according to the [SATN JSON format](/docs/data-format/satn). ## Messages ### Client to server -| Message | Description | -| ------------------------------- | --------------------------------------------------------------------------- | -| [`FunctionCall`](#functioncall) | Invoke a reducer. | -| [`Subscribe`](#subscribe) | Register queries to receive streaming updates for a subset of the database. | +| Message | Description | +| --------------------------------------------------------- | --------------------------------------------------------------------------- | +| [`FunctionCall`](#messages-client-to-server-functioncall) | Invoke a reducer. | +| [`Subscribe`](#messages-client-to-server-subscribe) | Register queries to receive streaming updates for a subset of the database. | #### `FunctionCall` @@ -79,13 +79,13 @@ message FunctionCall { Clients send a `Subscribe` message to register SQL queries in order to receive streaming updates. -The client will only receive [`TransactionUpdate`s](#transactionupdate) for rows to which it is subscribed, and for reducer runs which alter at least one subscribed row. As a special exception, the client is always notified when a reducer run it requests via a [`FunctionCall` message](#functioncall) fails. +The client will only receive [`TransactionUpdate`s](#messages-server-to-client-transactionupdate) for rows to which it is subscribed, and for reducer runs which alter at least one subscribed row. As a special exception, the client is always notified when a reducer run it requests via a [`FunctionCall` message](#messages-client-to-server-functioncall) fails. -SpacetimeDB responds to each `Subscribe` message with a [`SubscriptionUpdate` message](#subscriptionupdate) containing all matching rows at the time the subscription is applied. +SpacetimeDB responds to each `Subscribe` message with a [`SubscriptionUpdate` message](#messages-server-to-client-subscriptionupdate) containing all matching rows at the time the subscription is applied. -Each `Subscribe` message establishes a new set of subscriptions, replacing all previous subscriptions. Clients which want to add a query to an existing subscription must send a `Subscribe` message containing all the previous queries in addition to the new query. In this case, the returned [`SubscriptionUpdate`](#subscriptionupdate) will contain all previously-subscribed rows in addition to the newly-subscribed rows. +Each `Subscribe` message establishes a new set of subscriptions, replacing all previous subscriptions. Clients which want to add a query to an existing subscription must send a `Subscribe` message containing all the previous queries in addition to the new query. In this case, the returned [`SubscriptionUpdate`](#messages-server-to-client-subscriptionupdate) will contain all previously-subscribed rows in addition to the newly-subscribed rows. -Each query must be a SQL `SELECT * FROM` statement on a single table with an optional `WHERE` clause. See the [SQL Reference](/docs/sql) for the subset of SQL supported by SpacetimeDB. +Each query must be a SQL `SELECT * FROM` statement on a single table with an optional `WHERE` clause. See the [SQL Reference](/docs/sql/overview) for the subset of SQL supported by SpacetimeDB. ##### Binary: ProtoBuf definition @@ -115,15 +115,15 @@ message Subscribe { ### Server to client -| Message | Description | -| ------------------------------------------- | -------------------------------------------------------------------------- | -| [`IdentityToken`](#identitytoken) | Sent once upon successful connection with the client's identity and token. | -| [`SubscriptionUpdate`](#subscriptionupdate) | Initial message in response to a [`Subscribe` message](#subscribe). | -| [`TransactionUpdate`](#transactionupdate) | Streaming update after a reducer runs containing altered rows. | +| Message | Description | +| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| [`IdentityToken`](#messages-server-to-client-identitytoken) | Sent once upon successful connection with the client's identity and token. | +| [`SubscriptionUpdate`](#messages-server-to-client-subscriptionupdate) | Initial message in response to a [`Subscribe` message](#messages-client-to-server-subscribe). | +| [`TransactionUpdate`](#messages-server-to-client-transactionupdate) | Streaming update after a reducer runs containing altered rows. | #### `IdentityToken` -Upon establishing a WebSocket connection, the server will send an `IdentityToken` message containing the client's identity and token. If the client included a [SpacetimeDB Authorization header](/docs/http) in their connection request, the `IdentityToken` message will contain the same token used to connect, and its corresponding identity. If the client connected anonymously, SpacetimeDB will generate a new identity and token for the client. +Upon establishing a WebSocket connection, the server will send an `IdentityToken` message containing the client's identity and token. If the client included a [SpacetimeDB Authorization header](/docs/http/overview) in their connection request, the `IdentityToken` message will contain the same token used to connect, and its corresponding identity. If the client connected anonymously, SpacetimeDB will generate a new identity and token for the client. ##### Binary: ProtoBuf definition @@ -157,7 +157,7 @@ message IdentityToken { #### `SubscriptionUpdate` -In response to a [`Subscribe` message](#subscribe), the database sends a `SubscriptionUpdate` containing all of the matching rows which are resident in the database at the time the `Subscribe` was received. +In response to a [`Subscribe` message](#messages-client-to-server-subscribe), the database sends a `SubscriptionUpdate` containing all of the matching rows which are resident in the database at the time the `Subscribe` was received. ##### Binary: ProtoBuf definition @@ -182,7 +182,7 @@ message TableRowOperation { } ``` -Each `SubscriptionUpdate` contains a `TableUpdate` for each table with subscribed rows. Each `TableUpdate` contains a `TableRowOperation` for each subscribed row. `SubscriptionUpdate`, `TableUpdate` and `TableRowOperation` are also used by the [`TransactionUpdate` message](#transactionupdate) to encode rows altered by a reducer, so `TableRowOperation` includes an `OperationType` which identifies the row alteration as either an insert or a delete. When a client receives a `SubscriptionUpdate` message in response to a [`Subscribe` message](#subscribe), all of the `TableRowOperation`s will have `op` of `INSERT`. +Each `SubscriptionUpdate` contains a `TableUpdate` for each table with subscribed rows. Each `TableUpdate` contains a `TableRowOperation` for each subscribed row. `SubscriptionUpdate`, `TableUpdate` and `TableRowOperation` are also used by the [`TransactionUpdate` message](#messages-server-to-client-transactionupdate) to encode rows altered by a reducer, so `TableRowOperation` includes an `OperationType` which identifies the row alteration as either an insert or a delete. When a client receives a `SubscriptionUpdate` message in response to a [`Subscribe` message](#messages-client-to-server-subscribe), all of the `TableRowOperation`s will have `op` of `INSERT`. | `TableUpdate` field | Value | | -------------------- | ------------------------------------------------------------------------------------------------------------- | @@ -190,10 +190,10 @@ Each `SubscriptionUpdate` contains a `TableUpdate` for each table with subscribe | `tableName` | The string name of the table. Clients should use this field to identify the table, rather than the `tableId`. | | `tableRowOperations` | A `TableRowOperation` for each inserted or deleted row. | -| `TableRowOperation` field | Value | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `op` | `INSERT` for inserted rows during a [`TransactionUpdate`](#transactionupdate) or rows resident upon applying a subscription; `DELETE` for deleted rows during a [`TransactionUpdate`](#transactionupdate). | -| `row` | The altered row, encoded as a BSATN `ProductValue`. | +| `TableRowOperation` field | Value | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `op` | `INSERT` for inserted rows during a [`TransactionUpdate`](#messages-server-to-client-transactionupdate) or rows resident upon applying a subscription; `DELETE` for deleted rows during a [`TransactionUpdate`](#messages-server-to-client-transactionupdate). | +| `row` | The altered row, encoded as a BSATN `ProductValue`. | ##### Text: JSON encoding @@ -219,7 +219,7 @@ Each `SubscriptionUpdate` contains a `TableUpdate` for each table with subscribe } ``` -Each `SubscriptionUpdate` contains a `TableUpdate` for each table with subscribed rows. Each `TableUpdate` contains a `TableRowOperation` for each subscribed row. `SubscriptionUpdate`, `TableUpdate` and `TableRowOperation` are also used by the [`TransactionUpdate` message](#transactionupdate) to encode rows altered by a reducer, so `TableRowOperation` includes an `"op"` field which identifies the row alteration as either an insert or a delete. When a client receives a `SubscriptionUpdate` message in response to a [`Subscribe` message](#subscribe), all of the `TableRowOperation`s will have `"op"` of `"insert"`. +Each `SubscriptionUpdate` contains a `TableUpdate` for each table with subscribed rows. Each `TableUpdate` contains a `TableRowOperation` for each subscribed row. `SubscriptionUpdate`, `TableUpdate` and `TableRowOperation` are also used by the [`TransactionUpdate` message](#messages-server-to-client-transactionupdate) to encode rows altered by a reducer, so `TableRowOperation` includes an `"op"` field which identifies the row alteration as either an insert or a delete. When a client receives a `SubscriptionUpdate` message in response to a [`Subscribe` message](#messages-client-to-server-subscribe), all of the `TableRowOperation`s will have `"op"` of `"insert"`. | `TableUpdate` field | Value | | ---------------------- | -------------------------------------------------------------------------------------------------------------- | @@ -227,10 +227,10 @@ Each `SubscriptionUpdate` contains a `TableUpdate` for each table with subscribe | `table_name` | The string name of the table. Clients should use this field to identify the table, rather than the `table_id`. | | `table_row_operations` | A `TableRowOperation` for each inserted or deleted row. | -| `TableRowOperation` field | Value | -| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `op` | `"insert"` for inserted rows during a [`TransactionUpdate`](#transactionupdate) or rows resident upon applying a subscription; `"delete"` for deleted rows during a [`TransactionUpdate`](#transactionupdate). | -| `row` | The altered row, encoded as a JSON array. | +| `TableRowOperation` field | Value | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `op` | `"insert"` for inserted rows during a [`TransactionUpdate`](#messages-server-to-client-transactionupdate) or rows resident upon applying a subscription; `"delete"` for deleted rows during a [`TransactionUpdate`](#messages-server-to-client-transactionupdate). | +| `row` | The altered row, encoded as a JSON array. | #### `TransactionUpdate` @@ -239,7 +239,7 @@ Upon a reducer run, a client will receive a `TransactionUpdate` containing infor 1. The reducer ran successfully and altered at least one row to which the client subscribes. 2. The reducer was invoked by the client, and either failed or was terminated due to insufficient energy. -Each `TransactionUpdate` contains a [`SubscriptionUpdate`](#subscriptionupdate) with all rows altered by the reducer, including inserts and deletes; and an `Event` with information about the reducer itself, including a [`FunctionCall`](#functioncall) containing the reducer's name and arguments. +Each `TransactionUpdate` contains a [`SubscriptionUpdate`](#messages-server-to-client-subscriptionupdate) with all rows altered by the reducer, including inserts and deletes; and an `Event` with information about the reducer itself, including a [`FunctionCall`](#messages-client-to-server-functioncall) containing the reducer's name and arguments. ##### Binary: ProtoBuf definition @@ -265,16 +265,16 @@ message Event { } ``` -| Field | Value | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `event` | An `Event` containing information about the reducer run. | -| `subscriptionUpdate` | A [`SubscriptionUpdate`](#subscriptionupdate) containing all the row insertions and deletions committed by the transaction. | +| Field | Value | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `event` | An `Event` containing information about the reducer run. | +| `subscriptionUpdate` | A [`SubscriptionUpdate`](#messages-server-to-client-subscriptionupdate) containing all the row insertions and deletions committed by the transaction. | | `Event` field | Value | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timestamp` | The time when the reducer started, as microseconds since the Unix epoch. | | `callerIdentity` | The identity of the client which requested the reducer invocation. For event-driven and scheduled reducers, this is the identity of the database owner. | -| `functionCall` | A [`FunctionCall`](#functioncall) containing the name of the reducer and the arguments passed to it. | +| `functionCall` | A [`FunctionCall`](#messages-client-to-server-functioncall) containing the name of the reducer and the arguments passed to it. | | `status` | `committed` if the reducer ran successfully and its changes were committed to the database; `failed` if the reducer signaled an error; `out_of_energy` if the reducer was canceled due to insufficient energy. | | `message` | The error message with which the reducer failed if `status` is `failed`, or the empty string otherwise. | | `energy_quanta_used` | The amount of energy consumed by running the reducer. | @@ -305,10 +305,10 @@ message Event { } ``` -| Field | Value | -| --------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `event` | An `Event` containing information about the reducer run. | -| `subscription_update` | A [`SubscriptionUpdate`](#subscriptionupdate) containing all the row insertions and deletions committed by the transaction. | +| Field | Value | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `event` | An `Event` containing information about the reducer run. | +| `subscription_update` | A [`SubscriptionUpdate`](#messages-server-to-client-subscriptionupdate) containing all the row insertions and deletions committed by the transaction. | | `Event` field | Value | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/content/docs/09-data-format/00-satn.md b/content/docs/09-data-format/00-satn.md index d9bd80a..352343c 100644 --- a/content/docs/09-data-format/00-satn.md +++ b/content/docs/09-data-format/00-satn.md @@ -3,19 +3,19 @@ title: SATN JSON Format navTitle: SATN --- -The Spacetime Algebraic Type Notation JSON format defines how Spacetime `AlgebraicType`s and `AlgebraicValue`s are encoded as JSON. Algebraic types and values are JSON-encoded for transport via the [HTTP Databases API](/docs/http/database) and the [WebSocket text protocol](/docs/ws#text-protocol). +The Spacetime Algebraic Type Notation JSON format defines how Spacetime `AlgebraicType`s and `AlgebraicValue`s are encoded as JSON. Algebraic types and values are JSON-encoded for transport via the [HTTP Databases API](/docs/http/database) and the [WebSocket text protocol](/docs/ws/overview#protocols-text-protocol). ## Values ### 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` | A value whose type may be any [`AlgebraicType`](#types-algebraictype). | +| `SumValue` | A value whose type is a [`SumType`](#types-sumtype). | +| `ProductValue` | A value whose type is a [`ProductType`](#types-producttype). | +| `BuiltinValue` | A value whose type is a [`BuiltinType`](#types-builtintype). | +| | | ### `AlgebraicValue` @@ -25,9 +25,9 @@ SumValue | ProductValue | BuiltinValue ### `SumValue` -An instance of a [`SumType`](#sumtype). `SumValue`s are encoded as a JSON object with a single key, a non-negative integer tag which identifies the variant. The value associated with this key is the variant data. Variants which hold no data will have an empty array as their value. +An instance of a [`SumType`](#types-sumtype). `SumValue`s are encoded as a JSON object with a single key, a non-negative integer tag which identifies the variant. The value associated with this key is the variant data. Variants which hold no data will have an empty array as their value. -The tag is an index into the [`SumType.variants`](#sumtype) array of the value's [`SumType`](#sumtype). +The tag is an index into the [`SumType.variants`](#types-sumtype) array of the value's [`SumType`](#types-sumtype). ```json { @@ -37,7 +37,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`](#types-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`](#types-producttype) array of the value's [`ProductType`](#types-producttype). ```json array @@ -45,20 +45,20 @@ array ### `BuiltinValue` -An instance of a [`BuiltinType`](#builtintype). `BuiltinValue`s are encoded as JSON values of corresponding types. +An instance of a [`BuiltinType`](#types-builtintype). `BuiltinValue`s are encoded as JSON values of corresponding types. ```json boolean | number | string | array | map ``` -| [`BuiltinType`](#builtintype) | JSON type | -| ----------------------------- | ------------------------------------- | -| `Bool` | `boolean` | -| Integer types | `number` | -| Float types | `number` | -| `String` | `string` | -| Array types | `array` | -| Map types | `map` | +| [`BuiltinType`](#types-builtintype) | JSON type | +| ----------------------------------- | ------------------------------------- | +| `Bool` | `boolean` | +| Integer types | `number` | +| Float types | `number` | +| `String` | `string` | +| Array types | `array` | +| Map types | `map` | All SATS integer types are encoded as JSON `number`s, so values of 64-bit and 128-bit integer types may lose precision when encoding values larger than 2⁵². @@ -68,17 +68,17 @@ All SATS types are JSON-encoded by converting them to an `AlgebraicValue`, then ### At a glance -| Type | Description | -| --------------------------------------- | ------------------------------------------------------------------------------------ | -| [`AlgebraicType`](#algebraictype) | Any SATS type. | -| [`SumType`](#sumtype) | Sum types, i.e. tagged unions. | -| [`ProductType`](#productype) | 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. | +| Type | Description | +| --------------------------------------------- | ------------------------------------------------------------------------------------ | +| [`AlgebraicType`](#types-algebraictype) | Any SATS type. | +| [`SumType`](#types-sumtype) | Sum types, i.e. tagged unions. | +| [`ProductType`](#types-producttype) | Product types, i.e. structures. | +| [`BuiltinType`](#types-builtintype) | Built-in and primitive types, including booleans, numbers, strings, arrays and maps. | +| [`AlgebraicTypeRef`](#types-algebraictyperef) | An indirect reference to a type, used to implement recursive types. | -#### `AlgebraicType` +### `AlgebraicType` -`AlgebraicType` is the most general meta-type in the Spacetime Algebraic Type System. Any SATS type can be represented as an `AlgebraicType`. `AlgebraicType` is encoded as a tagged union, with variants for [`SumType`](#sumtype), [`ProductType`](#producttype), [`BuiltinType`](#builtintype) and [`AlgebraicTypeRef`](#algebraictyperef). +`AlgebraicType` is the most general meta-type in the Spacetime Algebraic Type System. Any SATS type can be represented as an `AlgebraicType`. `AlgebraicType` is encoded as a tagged union, with variants for [`SumType`](#types-sumtype), [`ProductType`](#types-producttype), [`BuiltinType`](#types-builtintype) and [`AlgebraicTypeRef`](#types-algebraictyperef). ```json { "Sum": SumType } @@ -87,13 +87,13 @@ All SATS types are JSON-encoded by converting them to an `AlgebraicValue`, then | { "Ref": AlgebraicTypeRef } ``` -#### `SumType` +### `SumType` The meta-type `SumType` represents sum types, also called tagged unions or Rust `enum`s. A sum type has some number of variants, each of which has an `AlgebraicType` of variant data, and an optional string discriminant. For each instance, exactly one variant will be active. The instance will contain only that variant's data. A `SumType` with zero variants is called an empty type or never type because it is impossible to construct an instance. -Instances of `SumType`s are [`SumValue`s](#sumvalue), and store a tag which identifies the active variant. +Instances of `SumType`s are [`SumValue`s](#values-sumvalue), and store a tag which identifies the active variant. ```json // SumType: @@ -114,7 +114,7 @@ The meta-type `ProductType` represents product types, also called structs or tup A `ProductType` with zero fields is called a unit type because it has a single instance, the unit, which is empty. -Instances of `ProductType`s are [`ProductValue`s](#productvalue), and store an array of field data. +Instances of `ProductType`s are [`ProductValue`s](#values-productvalue), and store an array of field data. ```json // ProductType: @@ -163,4 +163,4 @@ SATS array and map types are homogeneous, meaning that each array has a single e ### `AlgebraicTypeRef` -`AlgebraicTypeRef`s are JSON-encoded as non-negative integers. These are indices into a typespace, like the one returned by the [`/database/schema/:name_or_address GET` HTTP endpoint](/docs/http/database#databaseschemaname_or_address-get). +`AlgebraicTypeRef`s are JSON-encoded as non-negative integers. These are indices into a typespace, like the one returned by the [`/database/schema/:name_or_address GET` HTTP endpoint](/docs/http/database#database-schema-name-or-address-get). diff --git a/content/docs/09-data-format/01-bsatn.md b/content/docs/09-data-format/01-bsatn.md index b499a84..4cd07ac 100644 --- a/content/docs/09-data-format/01-bsatn.md +++ b/content/docs/09-data-format/01-bsatn.md @@ -27,12 +27,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` | A value whose type may be any [`AlgebraicType`](/docs/data-format/satn#types-algebraictype). | +| `SumValue` | A value whose type is a [`SumType`](/docs/data-format/satn#types-sumtype). | +| `ProductValue` | A value whose type is a [`ProductType`](/docs/data-format/satn#types-producttype). | +| `BuiltinValue` | A value whose type is a [`BuiltinType`](/docs/data-format/satn#types-builtintype). | ### `AlgebraicValue` @@ -44,17 +44,17 @@ bsatn(AlgebraicValue) = bsatn(SumValue) | bsatn(ProductValue) | bsatn(BuiltinVal ### `SumValue` -An instance of a [`SumType`](#sumtype). +An instance of a [`SumType`](/docs/data-format/satn#types-sumtype). `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`](/docs/data-format/satn#types-sumtype) +array of the value's [`SumType`](/docs/data-format/satn#types-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 [`ProductType`](/docs/data-format/satn#types-producttype). `ProductValue`s are binary encoded as: ```fsharp @@ -65,7 +65,7 @@ Field names are not encoded. ### `BuiltinValue` -An instance of a [`BuiltinType`](#builtintype). +An instance of a [`BuiltinType`](/docs/data-format/satn#types-builtintype). The BSATN encoding of `BuiltinValue`s defers to the encoding of each variant: ```fsharp @@ -113,6 +113,6 @@ Where 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/data-format/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/content/docs/10-sql/00-overview.md b/content/docs/10-sql/00-overview.md index d892ef3..4dfedfe 100644 --- a/content/docs/10-sql/00-overview.md +++ b/content/docs/10-sql/00-overview.md @@ -2,7 +2,7 @@ title: SQL Reference --- -SpacetimeDB supports a subset of SQL as a query language. Developers can evaluate SQL queries against a Spacetime database via the `spacetime sql` command-line tool and the [`/database/sql/:name_or_address POST` HTTP endpoint](/docs/http/database#databasesqlname_or_address-post). Client developers also write SQL queries when subscribing to events in the [WebSocket API](/docs/ws#subscribe) or via an SDK `subscribe` function. +SpacetimeDB supports a subset of SQL as a query language. Developers can evaluate SQL queries against a Spacetime database via the `spacetime sql` command-line tool and the [`/database/sql/:name_or_address POST` HTTP endpoint](/docs/http/database#database-sql-name-or-address-post). Client developers also write SQL queries when subscribing to events in the [WebSocket API](/docs/ws/overview#messages-client-to-server-subscribe) or via an SDK `subscribe` function. SpacetimeDB aims to support much of the [SQL 2016 standard](https://www.iso.org/standard/63555.html), and in particular aims to be compatible with [PostgreSQL](https://www.postgresql.org/). @@ -10,31 +10,31 @@ SpacetimeDB 0.6 implements a relatively small subset of SQL. Future SpacetimeDB ## Types -| Type | Description | -| --------------------------------------------- | -------------------------------------- | -| [Nullable types](#nullable-types) | Types which may not hold a value. | -| [Logic types](#logic-types) | Booleans, i.e. `true` and `false`. | -| [Integer types](#integer-types) | Numbers without fractional components. | -| [Floating-point types](#floating-point-types) | Numbers with fractional components. | -| [Text types](#text-types) | UTF-8 encoded text. | +| Type | Description | +| ---------------------------------------------------------------------- | -------------------------------------- | +| [Nullable types](#data-types-nullable-types) | Types which may not hold a value. | +| [Logic types](#data-types-logic-types) | Booleans, i.e. `true` and `false`. | +| [Integer types](#data-types-numeric-types-integer-types) | Numbers without fractional components. | +| [Floating-point types](#data-types-numeric-types-floating-point-types) | Numbers with fractional components. | +| [Text types](#data-types-text-types) | UTF-8 encoded text. | ### Definition statements -| Statement | Description | -| ----------------------------- | ------------------------------------ | -| [CREATE TABLE](#create-table) | Create a new table. | -| [DROP TABLE](#drop-table) | Remove a table, discarding all rows. | +| Statement | Description | +| ------------------------------------ | ------------------------------------ | +| [CREATE TABLE](#syntax-create-table) | Create a new table. | +| [DROP TABLE](#syntax-drop-table) | Remove a table, discarding all rows. | ### Query statements -| Statement | Description | -| ----------------- | -------------------------------------------------------------------------------------------- | -| [FROM](#from) | A source of data, like a table or a value. | -| [JOIN](#join) | Combine several data sources. | -| [SELECT](#select) | Select specific rows and columns from a data source, and optionally compute a derived value. | -| [DELETE](#delete) | Delete specific rows from a table. | -| [INSERT](#insert) | Insert rows into a table. | -| [UPDATE](#update) | Update specific rows in a table. | +| Statement | Description | +| ------------------------- | -------------------------------------------------------------------------------------------- | +| [FROM](#queries-from) | A source of data, like a table or a value. | +| [JOIN](#queries-join) | Combine several data sources. | +| [SELECT](#queries-select) | Select specific rows and columns from a data source, and optionally compute a derived value. | +| [DELETE](#queries-delete) | Delete specific rows from a table. | +| [INSERT](#queries-insert) | Insert rows into a table. | +| [UPDATE](#queries-update) | Update specific rows in a table. | ## Data types @@ -209,7 +209,7 @@ CREATE TABLE location (entity_id INTEGER, x REAL, z REAL); A `DROP TABLE` statement removes a table from the database, deleting all its associated rows, indexes, constraints and sequences. -To empty a table of rows without destroying the table, use [`DELETE`](#delete). +To empty a table of rows without destroying the table, use [`DELETE`](#queries-delete). The syntax of the `DROP TABLE` statement is: @@ -302,7 +302,7 @@ SELECT inventory_id FROM inventory; SELECT inventory.inventory_id FROM inventory; ``` -An optional `WHERE` clause can be added to filter the data source using a [logical expression](#logical-expressions). The `SELECT` will return only the rows from the data source for which the expression returns `true`. +An optional `WHERE` clause can be added to filter the data source using a [logical expression](#syntax-expressions-logical-expressions). The `SELECT` will return only the rows from the data source for which the expression returns `true`. #### Examples diff --git a/scripts/checks.ts b/scripts/checks.ts index 1f0e7c0..916361a 100644 --- a/scripts/checks.ts +++ b/scripts/checks.ts @@ -9,7 +9,11 @@ import { } from 'marked'; import { readdir, readFile } from 'node:fs/promises'; -const CHECK_EXTERNAL_LINKS = true; +//////////////////////////////////////////////// !FLAGS //////////////////////////////////////////////// +// If you want to disable any of these, set them to false +const CHECK_EXTERNAL_LINKS = false; +const PRINT_ERRORS = true; +/////////////////////////////////////////////////////////////////////////////////////////////////// const data = await gatherData(); @@ -42,35 +46,38 @@ const totalErrors = Array.from(errors.values()).reduce( 0 ); -if (errors.size !== 0) { - console.log(kleur.red().bold(`${totalErrors} ERRORS`)); - for (const [slug, slugErrors] of errors) { - console.log(kleur.dim().bold(slug.padStart(40, '-').padEnd(60, '-'))); - for (const error of slugErrors) { - console.log( - kleur - .yellow() - .bold( - ` ${new URL(`../content/docs/${error.file}`, import.meta.url).pathname}:${error.line}` - ) - ); - console.log(kleur.red().bold(` ${error.message}`)); - if (error.suggestion) { +if (PRINT_ERRORS) + if (errors.size !== 0) { + console.log(kleur.red().bold(`${totalErrors} ERRORS`)); + for (const [slug, slugErrors] of errors) { + console.log(kleur.dim().bold(slug.padStart(40, '-').padEnd(60, '-'))); + for (const error of slugErrors) { console.log( - kleur.green().bold(` Did you mean: ${error.suggestion}`) + kleur + .yellow() + .bold( + ` ${new URL(`../content/docs/${error.file}`, import.meta.url).pathname}:${error.line}` + ) ); + console.log(kleur.red().bold(` ${error.message}`)); + if (error.suggestion) { + console.log( + kleur.green().bold(` Did you mean: ${error.suggestion}`) + ); + } + console.log(); } - console.log(); } + console.log(kleur.red().bold(`${totalErrors} ERRORS`)); + + throw new Error(''); + } else { + console.log( + kleur + .green() + .bold('✅✅✅✅✅✅✅✅✅ No errors found! ✅✅✅✅✅✅✅✅✅') + ); } - console.log(kleur.red().bold(`${totalErrors} ERRORS`)); - - throw new Error(''); -} else { - console.log( - kleur.green().bold('✅✅✅✅✅✅✅✅✅ No errors found! ✅✅✅✅✅✅✅✅✅') - ); -} async function gatherData() { const dirs = await readdir(new URL('../content/docs', import.meta.url)); @@ -273,12 +280,17 @@ async function checkLinks() { } else if (href.startsWith('/docs')) { // Should start with /docs. Then compare, including any hash it might have. Examples: /docs/data-format/bsatn or /docs/introduction/getting-started#some-heading const link = href.slice(1); - const slug = link.slice(5); - const hashIfThere = slug.includes('#') - ? slug.slice(slug.indexOf('#')) + const slug = link.slice(5).split('#')[0]; + const hashIfThere = link.includes('#') + ? link.slice(link.indexOf('#') + 1) : null; - if (!headingsOnPages.has(slug)) { + if ( + !headingsOnPages.has(slug) || + (headingsOnPages.has(slug) && + hashIfThere && + !headingsOnPages.get(slug)!.has(hashIfThere)) + ) { const results = await search(db, { term: slug.split(/[^a-zA-Z0-9]+/).join(' ') +