Improve experience for Typescript developers

  • 25 November 2021
  • 9 replies
  • 251 views
Marijn Huizendveld
Userlevel 2
Badge +2

Hi!

Currently there exists a type definition of the Miro SDK in the form of `miro.d.ts` in the app-examples Git repository.
Unfortunately there are two issues with it:

It would be great if:

  • the enums would be published part of a module that can be used for the runtime
  • and the types would be published as a DefinitelyTyped package

Are there any plans to do so?
 

Take care,
Marijn

9 replies

Addison Schultz
Rank
Userlevel 5

Hi Marijn,

 

Great point on the TS definitions. We’re definitely working on improving this experience and the TS experience overall, but thank you for the feedback and heads up on the missing enums. 

 

If you have any other suggestions for TypeScript support, please let us know!

 

Addison

Marijn Huizendveld
Userlevel 2
Badge +2
  • miro.board.widgets.get: If that is compatible with lodash (as documented) then the typing should not be Record<string, unknown> because it also accepts a callback function.

  • miro.board.widgets.update: Does not properly typehint at allowed inputs vs. required inputs. A first improvement could be to make everything optional for the specific IWidget type T and merge that with the required id field from T. Further improvements could be to ignore the readonly fields but they don’t seem to be documented correctly in the type definitions of the individual widgets at this point.

    update<T extends IWidget>(

        widgets: OneOrMany<Omit<Partial<T>, 'id'> & Pick<T, 'id'»

    ): Promise<T[]>

  • miro.board.widgets.create: Use the specific IWidget type T in stead of WidgetToBeCreated to hint at the required fields. Unfortunately it is not clear for me which fields are required and which fields are optional for the individual widgets. That’s why I’m not suggesting code because it will certainly be wrong.

In general there is a lot that could be improved in the API of the SDK itself from the perspective of the plugin developer. But that has more to do with the SDK than with its type definitions.

 

Marijn Huizendveld
Userlevel 2
Badge +2

Introduce a dedicated type WidgetTypes which is a union of all the possible types. Use this to typehint in various places

type WidgetTypes = 'COMMENT' | 'STICKER' | 'TEXT' /* etc. */;

 

Marijn Huizendveld
Userlevel 2
Badge +2

I’m analyzing how this changed for the Web SDK 2.0. Overall it seems to be an improvement :-)

Thinks that I noticed:

  • Types are again distributed differently from what is common in typescript (You need to add "typeRoots": ["./node_modules/@types", "./node_modules/@mirohq"]  to tsconfig.json. Why not distribute via the @types repo? That would reduced the number of steps people need to make in order to get started with Typescript and Miro

  • It seems that it is no longer possible to define tags with any desired color, in 1.0 this was less restrictive. In my case I’d like to have at least as many color options as there are sticky note colors.
  • The GetFilter type is an improvement over the hard-coded Record<string, string> but the API is supposed to be compatible with lodash. That implies that a callback should also be a possible argument, it would be nice if the GetFilter type would reflect this.
  • The get(filter?: GetFilter): Promise<BoardNode[]> allows to specify by type. This means we would get back specific type of BoardNode but this cannot be typehinted. My proposal would be get<T extends BoardNode>(filter?: GetFilter): Promise<T[]>
  • It is unclear where these types are managed in a repo, I’d open a PR if there would be a public source of them somewhere...
Ahmed El Gabri
Rank

Hi @Marijn Huizendveld, 

Thanks for your feedback, I’m glad that you find the types file useful & an improvement over the v1 one. 
 

Types are again distributed differently from what is common in typescript (You need to add "typeRoots": ["./node_modules/@types", "./node_modules/@mirohq"]  to tsconfig.json. Why not distribute via the @types repo? That would reduced the number of steps people need to make in order to get started with Typescript and Miro

 

While true, we can’t do this for multiple reasons. We would like to have more control over when we update the package & do new releases, we can’t do this with the DefinitelyTyped repo. We also use the types file to generate the SDK reference & do more automation.
 

It seems that it is no longer possible to define tags with any desired color, in 1.0 this was less restrictive. In my case I’d like to have at least as many color options as there are sticky note colors.

 


What was in v1 was actually a bug, the UI supports only 12 colors for tags & this was fixed in v2, will pass this request to the product team.
 

The GetFilter type is an improvement over the hard-coded Record<string, string> but the API is supposed to be compatible with lodash. That implies that a callback should also be a possible argument, it would be nice if the GetFilter type would reflect this.

 

May I ask where is the expectation that the API is supposed to be compatible with lodash is coming from?
 

The get(filter?: GetFilter): Promise<BoardNode[]> allows to specify by type. This means we would get back specific type of BoardNode but this cannot be typehinted. My proposal would be get<T extends BoardNode>(filter?: GetFilter): Promise<T[]>


Will pass this suggestion to the team.
 

It is unclear where these types are managed in a repo, I’d open a PR if there would be a public source of them somewhere…

 

For now it’s private, we have some discussions on maybe open source it but that’s nothing more than discussions right now.

Marijn Huizendveld
Userlevel 2
Badge +2

Hi @Marijn Huizendveld, 

Thanks for your feedback, I’m glad that you find the types file useful & an improvement over the v1 one. 
 

Types are again distributed differently from what is common in typescript (You need to add "typeRoots": ["./node_modules/@types", "./node_modules/@mirohq"]  to tsconfig.json. Why not distribute via the @types repo? That would reduced the number of steps people need to make in order to get started with Typescript and Miro

 

While true, we can’t do this for multiple reasons. We would like to have more control over when we update the package & do new releases, we can’t do this with the DefinitelyTyped repo. We also use the types file to generate the SDK reference & do more automation.
 

As far as I understand the DefinitelyTyped repo get’s published every 90 minutes, is that insufficient for your needs? Or did I misunderstand how DT works? In my opinion the less special the setup the easier it will be to adopt :-)

It seems that it is no longer possible to define tags with any desired color, in 1.0 this was less restrictive. In my case I’d like to have at least as many color options as there are sticky note colors.


What was in v1 was actually a bug, the UI supports only 12 colors for tags & this was fixed in v2, will pass this request to the product team.

Interesting, I was always under the impression that I could create tags with colors that don’t seem to be supported in the Miro UI.

The GetFilter type is an improvement over the hard-coded Record<string, string> but the API is supposed to be compatible with lodash. That implies that a callback should also be a possible argument, it would be nice if the GetFilter type would reflect this.

 

May I ask where is the expectation that the API is supposed to be compatible with lodash is coming from?

The V1 SDK API documents it here: https://developers.miro.com/docs/interface-iboardwidgetscommands#get

The get(filter?: GetFilter): Promise<BoardNode[]> allows to specify by type. This means we would get back specific type of BoardNode but this cannot be typehinted. My proposal would be get<T extends BoardNode>(filter?: GetFilter): Promise<T[]>


Will pass this suggestion to the team.
 

It is unclear where these types are managed in a repo, I’d open a PR if there would be a public source of them somewhere…

 

For now it’s private, we have some discussions on maybe open source it but that’s nothing more than discussions right now.

Really too bad, it would be a perfect place to discuss improvements of the SDK API.

 

Ahmed El Gabri
Rank

As far as I understand the DefinitelyTyped repo get’s published every 90 minutes, is that insufficient for your needs? Or did I misunderstand how DT works? In my opinion the less special the setup the easier it will be to adopt :-)

 

I don’t think it will work for us, at least right now but we can definitely revisit this later :)
 

The V1 SDK API documents it here: https://developers.miro.com/docs/interface-iboardwidgetscommands#get

 

SDK v2 is a complete rewrite & not compatible with SDKv1 at all. v2 `get` is not supposed to be compatible with `lodash` API or any other library. 

Marijn Huizendveld
Userlevel 2
Badge +2

Thanks for sharing Ahmed. I understand that things change from v1 to v2. I was trying to be helpful and explain gaps in v1 and how they translate to v2 from the perspective of the plugin developer :-)

Have a nice day!

Ahmed El Gabri
Rank

Totally understand! thanks for the feedback it’s really helpful & whenever you have more feedback please feel free to share with us.

Have a nice weekend :)

Reply


Terms & Conditions