How should we organize API type definitions in TypeScript?

[seancolsen]

Problem

Type definitions for the API are currently spread across the front end code base with inconsistent names and incomplete representation of the API behavior.

A fex examples to demonstrate the inconsistency I'm talking about:

File	TS Interface
mathesar_ui/src/stores/table-data/records.ts	TableRecordInResponse
mathesar_ui/src/stores/fileImports.ts	PreviewColumn
mathesar_ui/src/App.d.ts	Database
mathesar_ui/src/stores/table-data/constraints.ts	Constraint

Design goals and rationale

• I'd like to decide on a more consistent scheme to use so that all our API types are in one place and it's easy to find the type for a given endpoint.

• In additional to some obvious front-end benefits, better documenting the API types would also facilitate clearer communication about breaking API changes between the front end and back end teams. When discussing an API change, we begin with a diff on the type definition.

Example

(I'll use this example throughout the various options below.)

• Endpoint: /tables/{id}/constraints/

• Method: GET

• Direction: Response

• Sample:

  {
    "count": 2,
    "results": [
      {
        "id": 70,
        "name": "trees_latin_name_key",
        "type": "unique",
        "columns": [
          "latin_name"
        ]
      },
      {
        "id": 69,
        "name": "trees_pkey",
        "type": "primary",
        "columns": [
          "id"
        ]
      }
    ]
  }

• The TypeScript I'd like to see (roughly)

  export type Type = 'foreignkey' | 'primary' | 'unique' | 'check' | 'exclude';
  
  interface Constraint {
    id: number,
    name: string,
    type: Type,
    columns: string[],
  }
  
  export interface GetResponse {
    count: number,
    results: Constraint[],
  }

My question is: how do we organize that TS code so that it's easy to add more code for other endpoints, methods, and directions?

Discussion format

I'll post separate top-level threads for different options I see, and we can comment on each of them.

[seancolsen]

Auto-generated types

Use a tool like DRF Typescript generator or similar to generate TypeScript code based on our Python code.

I've never done this before. It seems like it could be awesome. But also make a dead end or waste of time if it doesn't pan out as we expect.

[silentninja]

I had a conversation on API handoff a few weeks back with @pavish. I suggested using OpenApi codegen to generate a sdk based on the swagger file generated from the backend using tools like DRF Spectacular. Here is an example sdk for typescript

[silentninja]

On the backend I am waiting until views milestone to decide on how to generate swagger. If this is a pressing issue, I would be happy to work on it once the data type milestone is complete

[seancolsen]

Thanks @silentninja I'm glad you're thinking about this too! Definitely not pressing. If we can figure out automatic code generation for the API typing, that would be well worth waiting for!

[pavish]

Eventually, we would want to use auto-generated types. I've previously discussed this with @silentninja and we can evaluate the options available. I wouldn't want to prioritize this though, we can do that after our alpha when our APIs are more stable.

[seancolsen]

Nested namespaces

• mathesar_ui/src/api.d.ts

  export default namespace API {
    export namespace Tables {
      export namespace Constraints {
        export interface GetResponse {
          // ...
        }
      }
    }
  }

• In a consuming file

  import type { API } from '@mathesar/api';
  
  function foo(): API.Tables.Constraints.GetResponse {
    // ...
  }

Benefits

• Intellisense after each dot makes it easy to navigate through all the types.

Drawbacks

• TS Namespaces are somewhat of a vestigial feature now that ESM has supplanted basically all previous code-splitting patterns. The code above does work, but it's hard to split it up into separate files using ES Modules. Perhaps there's a clean way, but I wasn't able to find it. If we use a namespace like this, it seems to me like we're best off if we just keep all the API type defs in one file, as terrible as that sounds. I'd predict it would easily grow over 1k lines.

[seancolsen]

PascalCase_PascalCase types

• mathesar_ui/src/api/tables/constraints.d.ts

  export interface GetResponse {
    // ...
  }

• mathesar_ui/src/api/index.ts

  export type {
    GetResponse as Tables_Constraints_GetResponse,
  } from './tables/constraints';

• In a consuming file

  import type { Tables_Constraints_GetResponse } from '@mathesar/api';
  
  function foo(): Tables_Constraints_GetResponse {
    // ...
  }

[seancolsen]

This is the option I'm most interested in adopting

[seancolsen]

PascalCasePascalCase types

• mathesar_ui/src/api/tables/constraints.d.ts

  export interface GetResponse {
    // ...
  }

• mathesar_ui/src/api/index.ts

  export type {
    GetResponse as APITablesConstraintsGetResponse,
  } from './tables/constraints';

• In a consuming file

  import type { APITablesConstraintsGetResponse } from '@mathesar/api';
  
  function foo(): APITablesConstraintsGetResponse {
    // ...
  }

Benefits

• All names are still in PascalCase

Drawbacks

• Potential for naming collisions with /endpoint/foo/ and /endpoint-foo/

[seancolsen]

Pavish and I chatted about this today and decided on this approach because it's what the types look like that come out of the openapi-generator (example) and we hope to use that tool someday.

[silentninja]

The templates can be modified if needed and some templates support different naming conventions using command line parameters, but the default templates follow best practices most of the time