3 Commits

Author	SHA1	Message	Date
Tyler Cloutier	c83f55f65e	Refactors TypeScript into a single spacetimedb package (#3248) ... # Description of Changes This PR moves most of the contents of `@clockworklabs/spacetimedb-sdk` into the `spacetimedb` module. The `spacetimedb` module now exports `sdk` and `server` as separate subpaths where `sdk` contains the code which was previously in `@clockworklabs/spacetimedb-sdk`. In particular it makes the following moves: - `/sdks/typescript/packages/sdk` -> `/sdks/typescript` - most of the contents of `/sdks/typescript/packages/sdk` -> `crates/bindings-typescript` - `/sdks/typescript/packages/test-app` -> `crates/bindings-typescript/test-app` The following packags was NOT moved: `/sdks/typescript/examples/quickstart-chat` ## Motivation In accordance with https://github.com/clockworklabs/SpacetimeDB/issues/3250, we would like to consolidate `@clockworklabs/spacetimedb-sdk` into a single `spacetimedb` package so that users can import the different things they need from a single package. ### Pros: - allow users to install a single package with subpaths `spacetimedb`, `spacetimedb/react`, `spacetimedb/sdk`, `spacetimedb/server`, etc. - Is much simpler for bundling, etc. - Is backwards compatible with `@clockworklabs/spacetimedb-sdk` which now becomes a thin wrapper - eventually allow us to break up the `spacetimedb` package into other packages if we want to split them up (e.g. `@spacetimedb/lib`, `@spacetimedb/sdk`, etc.) and we can solve the build complexity that introduces when we get to it - eventually allow us to move `bindings-csharp` out of the crates directory where it probably doesn't belong anyway - organizes all TypeScript packages into the packages directory where you'd normally expect them, with the possible exception of `/sdks/typescript` if we wanted to leave that separate ### Cons: - The `sdk` directory is now a bit of a ruse as to where the code actually lives since it's just a thin wrapper. If it eventually becomes its own independent package, we'll also have to break up spacetimedb into `@spacetimedb/lib` and `@spacetimedb/server` so that `@clockworklabs/spacetimedb-sdk` can depend on `@spacetimedb/lib` while being a dependency of `spacetimedb`. Ideally this change would have been made later, however, it became necessary for the following **heinously disastrous chain of forcing moves**: 1. Adding `react` support necessitated shipping react as an optional peer dependency under `@clockworklabs/spacetimedb-sdk/react` 2. This required adding a new build target/export/bundle 3. Previously `@clockworklabs/spacetimedb-sdk` was configured to have `noExternal` for `spacetimedb` meaning it would collect the library into the sdk bundle. I attempted to continue this for react support but... 4. Creating a new `react` bundle which also pulled in `spacetimedb` caused their to be nominal type conflicts between classes in the duplicate `spacetimedb` bundles. 5. Changing `spacetimedb` to be included as `external` caused compile errors because `@clockworklabs/spacetimedb-sdk` is configured in `tsconfig.json` to fail on unused variables and it was now including the source of `spacetimedb` which is not configured to error on unused variables and has "unused" private variables which are actually used by us secretly, but not exposed to the clients. > SIDE NOTE: The unused variables settings cannot be turned off on a line by line basis, so it has to be turned off entirely, but in order to maintain the linting checks we had I used `eslint` to enforce the rule so that we could disable it line by line. (This caused me to discover quite a lot of things that were broken that were caught by `eslint` being applied to the entire project. `eslint` was previously only applied to the `quickstart-chat` and the `crates/bindings-typescript` library) 6. Changing the build to be external, now requires `spacetimedb` to also be published to npm as its own module which `@clockworklabs/spacetimedb-sdk` now imports, which requires that we add `tsup` config to `spacetimedb` to publish a built version of the library. 7. The only way to avoid that is to move the `sdk` and `react` code from `@clockworklabs/spacetimedb-sdk` into the existing `spacetimedb` package to avoid the duplicate import problem on step 4 and change `@clockworklabs/spacetimedb-sdk` back to again use `noExternal` for its `spacetimedb` dependency. And here we are. I chose not to move `/crates/bindings-typescript` even though that's probably not a great place long term. It would be better to have it in `/packages/spacetimedb` or `/npm-packages/spacetimedb` or `/ts-packages/spacetimedb` or something, and move all our TypeScript packages in there. But that is a different matter. The net result however is that we have a new `spacetimedb` package which exports the different parts of the API under: - `spacetimedb` - `spacetimedb/server` - `spacetimedb/sdk` - `spacetimedb/react` while still not breaking the existing deploy process, nor any users/developers who are currently using `@clockworklabs/spacetimedb-sdk`. I think long term should we ever decide to split `spacetimedb` up into multiple packages or if we have additional unrelated packages, we should publish them to the `@spacetimedb` org which I reserved for us here: https://www.npmjs.com/org/spacetimedb > NOTE: `spacetimedb` is a package and `@spacetimedb` is an org. `spacetimedb/sdk` is not a separate package, it's a subpath export of the `spacetimedb` package, whereas `@spacetimedb/sdk` would be (and would need to be) it's own separate package. You can certainly have both `spacetimedb/sdk` and `@spacetimedb/sdk`. We could for example host the code for the sdk at `@spacetimedb/sdk` and just reexport it from `spacetimedb` under the `spacetimedb/sdk` subpath. # API and ABI breaking changes This should not change or modify the API or ABI in any way. If it does so accidentally it is a bug, although I carefully went through the exports. # Expected complexity level and risk 3 because it changes how the SDK is built a bit and rearranges a lot of paths. # Testing - [x] All of the CI passes - [x] I also ran quickstart-chat to confirm that it is not broken - [x] I also ran test-app	2025-09-19 19:33:45 +00:00
Tyler Cloutier	413c8cbf3c	Unifies TypeScript packages and command names (#3195) ... # Description of Changes This PR: - standardizes the prettier config across all TypeScript projects - adds a root level package.json - standardizes all `pnpm` commands to be the same - updates documentation accordingly - adds some additional typescript testing for serialization and deserialization **IMPORTANT!** Once this PR merges we will need to change the `compile-and-test` required check to `build-and-test` # API and ABI breaking changes No breaking changes. # Expected complexity level and risk 2 - It in principle doesn't change any code, but could affect deploy processes. # Testing - [x] Just the automated testing that we had previously - [x] I added additional automated tests --------- Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>	2025-09-04 02:23:29 +00:00
Tyler Cloutier	5901fb5063	Separate out TypeScript module library from the SDK (#3182) ... # Description of Changes Please note, much of the code changed in this PR is generated code. This change updates the TypeScript SDK to use a new `spacetimedb` TypeScript library which lives under the `/crates/bindings-typescript` folder alongside `/crates/bindings-csharp`. Just like with the C# bindings library, the types for `AlgebraicType` and `RawModuleDef` are now code generated with a script in `/crates/codegen/examples`. Pulling this out into a library allows us to use the same types and serialization code on both the server and the client for TypeScript modules. In the process of making this change I also found and fixed several issues with the TypeScript code generation. Namely an issue with recursive types and an issue with the `never` type. I also removed any use of `namespace`s since those are a TypeScript only feature, and we want to have JavaScript + types so that we can use the generated code with ESBuild without TSC. I have also improved the npm/pnpm scripts to be able to generate TypeScript code for us automatically by running `pnpm generate` for any place that we have to generate typescript code. Namely: - Quickstart module bindings - AlgebraicType/ModuleDef for TypeScript module library - Client API messages for the TypeScript API - TestApp module bindings # API and ABI breaking changes IMPORTANT! This is an API breaking change for clients, as such it should be a major version change. However, I am going to see if I can shim in the old API as best as possible to make it compatible. Notably, we were previously exporting APIs that end users do not need, and I don't think it would ever occur to them to use, namely the whole `AlgebraicValue` API and also the `AlgebraicType` API. In principle, no one should have a need for these, although it was technically possible for them to use it. Indeed, we could potentially even just remove AlgebraicType completely from the API by directly code generating the serialization code. Listed below are all of the **BREAKING** changes to the API and their effect: - `AlgebraicType` is now a structural union literal type instead of a class (nominal type), this is a consequence of generating the type with our code gen. Users did not have a reason to use `AlgebraicType` directly. - The `AlgebraicValue` type has been removed entirely. This was previously a class that was exported from the SDK, but very unlikely to be used by users. - The `ProductValue` type has been removed. - The `ReducerArgsAdapter` and `ValueAdapter` types, which were used with AlgebraicValues have been removed. - Generated code has changed incompatibly so users will have to regenerate code when upgrading to this version. Technically a breaking change, but pretty easy to fix. Listed below are the non-breaking API changes: - I am now exporting generated product types as the default export in addition to how I was exporting them before - For generated sum type `T`, I am now exporting a `TVariants` namespace which has the types of all the variants for `T`. This was previously exposed on the namespace `T`, but was inaccessible in modules other than the one it was defined in because I also export a type `T` in addition to namespace `T` and in the type position `T` was being interpreted as a type rather than a namespace. It's unclear why TypeScript resolved it as the `T` namespace within the module in which is was defined previously. Anyway, since the old types were apparently unobservable to users, I've replaced them with the types in `TVariants`. (Open to other names for this namespace). - I fixed a bug where never types (sum types with no variants) were not correctly generated. # Expected complexity level and risk 3. The most complex thing about the PR are the potential impacts to the API. I am reasonably certain, but not 100% certain that I have accounted for everything above. # Testing - [x] I ran `pnpm test` which runs all the tests in the repo including an integration test which tests the connection to SpacetimeDB. I also fixed broken tests. --------- Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>	2025-09-03 21:12:14 +00:00