feat: add jsdoc documentation generation generation for ts-rest contracts

[tefkah]

Issue(s) Resolved

#2869

Test Plan

Run tests

Notes/Context/Gotchas

This PR adds the ability to autogenerate JSDoc comments for the API routes defined by the ts-rest schemas.

Roughly, this here file
https://github.com/pubpub/pubpub/blob/61a53d5063009a1226de48dce445fc407997d0bf/tools/generateJSDoc.ts#L1-L115

defines a script that uses the typescript compiler API + ts-morph (a library that makes working with said compiler a bit easier) to look for the description, path, method, and metadata fields of a route, and generates a JSDoc comment that describes the route.

This JSDoc comment will then show up in the SDK as intellisense hints, and, by using typedoc, will be shown in the documentation for the SDK.

An example

This route
https://github.com/pubpub/pubpub/blob/84f83d2e16c6ded36206e6d5ec54d5516d090a8c/utils/api/contracts/customScript.ts#L32-L54

will receive such a comment

https://github.com/pubpub/pubpub/blob/84f83d2e16c6ded36206e6d5ec54d5516d090a8c/utils/api/contracts/customScript.ts#L10-L31

Metadata

For now there are three pieces of metadata you can specify.
This information can also be used by the OpenAPI docs, which I intend to add, but haven't yet. For instance you can mark whether a route needs cookie authentication this way, which currently is very vague.

loggedIn

This can be true (default), false or "admin".

• true: you need to be logged in and have access to this resource in order to use this route. Most routes are like this.
• false: you do not need to be logged in in order to use this route.
• "admin": you need to be logged in as an admin of this community to use this route. These routes are the newer ones, such as upload, import, and most of the GET routes.

since

This is to mark since when this route has been available in the SDK. Not using this atm.

example

Here you can write an example in Markdown of how this code should be used. We are using tsdoc specification here, so @example tags are interpreted as Markdown, not code. If you want code, you need to manually specify a code block, see the example above.

Weird reordering

As you may have noticed, I shuffled around the contracts a bit.

They went from

// contracts/example.ts

import { initContract } from '@ts-rest/core'

const c = initContract()

export const exampleContract = c.router({
      get: {
          // route info
      }
})

to

// contracts/example.ts
import type { AppRouter } from '@ts-rest/core'

export const exampleRouter = {
      get: {
        // route info
     }
} as const satisfies AppRouter

type ExampleRouterType = typeof exampleRouter

export interface ExampleRouter extends ExampleRouterType {}

You may be wondering: why????

Well, dear reader, it's because typescript is an evil language designed to make me suffer. And because of implementation details in ts-rest

Basically, unless we do this AND fork ts-rest to export some key types, typescript will inline every single type in the output d.ts files of the client, i.e. dereference every single type and just print the finalized object type. So no ProxyClient<ApplyAppRouter<typeof exampleRouter>>, but { get: (input: { body: /* ... */ }) => { /*...*/}) }.

That alone would not be a big problem, sure the output file is a bit big but it's just types, who cares.

The problem is that typescript gets rid of the JSDoc comments when it does this. Which sucks as a user of the API client, as you miss a lot of context.

I can go into why this works a bit more elsewhere, but tl;dr: to prevent typescript from dereferencing/inlining types we force two important types to be exported by ts-rest (otherwise, in the output d.ts, typescript is forced to inline it as it cannot reference them obviously), and force these interfaces to be used as the type by doing this as nonsense here

https://github.com/pubpub/pubpub/blob/ed5bbcfcfc4d1e7119ec9ecb72b231c25b594ea7/utils/api/contract.ts#L27-L45

Typescript doesn't like to dereference interfaces nearly as much as types.

Because of all this, typescript keeps references to the original route in the d.ts, which has the JSDoc annotations, which means that consumers of the sdk will have annotations, woohoo!

Shifting around things for documentation purposes

The other goal of the JSDoc comments was to use typedoc to generate docs for the client.

This was easier said then done, as typedoc REALLY didn't want to properly show certain types, but after some (a lot) of coercing i managed to find some things that work, see the documentation about the documentation at https://github.com/pubpub/sdk.

But tl;dr, I could only manage typedoc to generate correct documentation for nested contracts.

E.g. this lead to correct documentation

export const contract = c.router({
      pub: {
         get: {
           // route
        }
     }
})

while this did not

export const contract = c.router({
      getPub: {
          // route
     }
})

Why? I don't know. I'm sure it has something to do with how I mangle the types for the client, but this is the only way I managed to get it to work. Seeing how much time I already wasted trying to generate the docs nicely, I found reorganizing some floating routes to be a worthwhile sacrifice.

These groupings only affect the API of the SDK and how certain routes are written, not any implementation or path changes. This will also change how the OpenAPI spec is displayed, as these grouping represent these tabs on the left side.

Reorganization details

I grouped

• logout: GET /api/logout
• login: POST /api/login

into

• auth
  • logout: GET /api/logout
  • login: POST /api/login

I grouped

• workerTask
  • get: GET /api/workerTasks
• import: POST /api/import
• export: POST /api/export

into

• workerTask
  • get: GET /api/workerTasks
  • createImport: POST /api/import
  • createExport: POST /api/export

I grouped

• upload: POST /api/upload
• uploadPolicy: POST /api/uploadPolicy

into

• upload
  • file: POST /api/upload
  • uploadPolicy: POST /api/uploadPolicy

That's it!

Ideas for further grouping

Doing this made me realize: I could have done this all along!

I have not implemented this yet, but I would like to propose the following groupings

• collection
  • some routes
• collectionAttribution
  • get
  • getMany
  • create
  • remove
• collectionPub
  • get
  • create
  • remove

to

• collection
  • attribution
    • get
    • getMany
    • create
    • remove
  • pub
    • get
    • add <-- i think this is clearer, you are adding a pub to a collection
    • remove

I want to do a similar thing with pubAttributions for pubs.

I think this is much clearer.

The only downside is that we lose the http path significance, but I tihnk it's worth it.

Prettier...

As you may have seen from the gigantic amount of files changed, something happened.
That something was that I wanted to use a certain prettier plugin, prettier-plugin-jsdoc, to make sure the JSDocs were formatted correctly.

Unfortunately, this meant upgrading to prettier v3, which meant upgrading the eslint-plugin-prettier extension, which meant that a whole lot of files were throwing errors during npm run lint.
I fixed these errors, but that came with the downside that now a lot of files have been changed.

This is super cringe, but I think an okay sacrifice. I think we would have to upgrade prettier anyway, might as well be now!

The PR is very messy bc of this though, apologies! I can revert it if you find it important, and upgrade prettier in a separate PR.

[tefkah]

eslint seems to have changed this. (i ran eslint --fix to fix all the prettier changes, this may have been caught in that)

I think this shouldn't do anything, unless you were somehow relying on some evil react thingy

[tefkah]

same here

[tefkah]

fragment removed

[tefkah]

fragment removed

[tefkah]

fragment removed

[tefkah]

fragment removed
ill stop marking these now

[tefkah]

this is kind of a significant change, and is related to something i changed in our fork of ts-rest, which i'll explain here.

ts-rest does not do arrays well. if it encounters an array in a field in an object that gets converted to formdata, it just appends the whole array, which often leads you with "['object Object', 'object Object']" as the field, which is silly.

before, I would allow users to pass either a File (which is not available in node 18), or [Blob, string]. I would then manually, in the sdk, create methods that merge these things and do something like

upload({ files }) {
  const form = new FormData()
  if(Array.isArray(files)){
       files.forEach(([blob, filename]) => {
          form.append('files', blob, filename)
       })
  }
// ...
}

which makes formdata sort of manually create a file. Kind of weird but whatever.

I decided to get rid of those manual methods in the sdk, because, as we were forking ts-rest anyway, might as well have it do what we want it to do.

See this diff for what i changed

pubpub/ts-rest@b533bdd...fe7c011#diff-aa23f3f5a1b6dab4c323411e117b8624de01d63a532d78e5138363cde570eba3

Long story short, allowing for both File and a Blob/filename pair, and arrays of those, is way cleaner if the Blob/filename pair is an object.

so to upload files, you can now do

await pubpub.upload.file({
     files: [{ blob: new Blob(['hey'], 'text/plain'), filename: 'hey.txt' }]
})

Neat!

[tefkah]

to create the filter query param schema, i filter out all optional() fields, which are normally associations and I don't want to allow filtering by association (e.g. show me all collections with a Pub with name 'My Pub', too complex).
However, due to annoying reasons, I needed to make the createdAt and updatedAt optional as well, so I allow an exception for them.

[tefkah]

i wasn't using this client for anything, kind of weird to have it here

[3mcd]

LGTM, other than the failing tests. Know what's causing that?

[tefkah]

Sorry, totally missed that you had approved this @3mcd !
Made some tiny adjustments that fix some small issues on the SDK, and merged this with master.

The only significant change is a type change, namely making the update params for facets all partial.

I.e., before the types looked like

{
  facets?: {
	PubHeaderTheme?: {
		backgroundImage: string
		backgroundColor: string
		theme: string
    }
    ....
}

and now the look like

{
  facets?: {
	PubHeaderTheme?: {
		backgroundImage?: string
		backgroundColor?: string
		theme?: string
    }
    ....
}

This reflect more closely what the api actually accepts, and allows you to update facets without having to specifiy every single part of that facet, just the one you need.

i.e. i can now change the background color by doing

pubpub.facets.update({
   PubHeaderTheme: {
		backgroundColor: '#000000'
	}
})

instead of also having to specify the background image and theme.

This was already how the API worked, the types now more accurately reflect this.