Add support for publishing in definitely-typed repository

[tato123]

Enhancement request

Overview

For projects that utilize typescript and npm, types can be associated to a project by downloading the library via npm and exposeing a typings key. The request is to create the necessary values and expose the library on npm as a published package

Changes required within repository

• Create a package.json
• Add "typings": "./types/index.d.ts" key/value

Additional owner / contributor changes

• publish changes to npm
• stretch goal: use a build system to publish changes upon merge to master

[tato123]

Included a pull request with the proposed changes #29

[pklaschka]

Alright – let's now discuss how we can go about publishing to npm here. @kerrishotts Any thoughts (the problem if I just publish it myself is that it would be difficult to get access rights for Adobe staff (since I don't have any paid npm account and therefore very limited "contributor management" features)?

[ashryanbeats]

Thanks for bringing this up. I've also added @dkstevekwak to the discussion here. We can learn from how Kerri is handling things for xdpm today.

To sum up what I've seen here and elsewhere, the issues we're trying to solve for are:

• Avoid having a single point of failure in the publishing workflow
• To the extent possible, automate the process

Is this accurate?

[tato123]

@ashryanbeats yes, your summary is accurate. It was a stretch goal, however it would simplify maintaining this project as a community lead library.

I should however have renamed this request. One thing I realized after I created this issue was that using definitelytyped would require the type definitions of this project to be moved over to the definitelytyped repository.

However, I do not think that is not necessary since major libraries like firebase and redux maintain their typings outside the definitelytyped repository.

[pklaschka]

@ashryanbeats Another thing is that since I'm currently basically the sole maintainer of the repo, we need to have some way of publishing it to npm with

1. me not being the only one able to publish it (which would happen if I just published it myself)
2. me being able to publish it (since – at least from what it looks like right now – I will for the near future be the person to make changes and always having to wait for someone on your side to review and publish it would only make things more complicated and increase work for both sides 😉 )

[pklaschka]

@ashryanbeats @kerrishotts Is there any update on this? I don't mean to pressure you, but "We can learn from how Kerri is handling things for xdpm today." was five days ago 😉

[pklaschka]

@kerrishotts @ashryanbeats @dkstevekwak Sorry to be tagging you all here, but is there any news about this? The today in

Thanks for bringing this up. I've also added @dkstevekwak to the discussion here. We can learn from how Kerri is handling things for xdpm today.

is more than a month ago 😉

[ericdrobinson]

I've some comments that I hope will be helpful to this discussion.

Communicating the Purpose of Typings

First, I would strongly suggest that you be careful as to how you message the purpose of these typings. I bring this up because the first sentence of this issue starts with:

For projects that utilize typescript and npm

Type Declaration Files (aka "typings") are not just for TypeScript. They power immensely powerful features for pure JavaScript when used in compatible editors. With the very typings you guys have in these documents you can help your pure-JavaScript developers as well! To that end, I would suggest that you simplify that statement to simply read:

For projects that utilize npm

I'm not trying to suggest that you guys update this Issue specifically, but rather that you take a broader view of the importance and impact that these files may have for your XD (and, eventually, the greater UXP) developers.

Case in point: I am not an XD developer; I've never touched the program. However, by simply downloading this repository and creating a test.js file, I'm able to begin writing pure JavaScript in Visual Studio Code with IntelliSense-powered autocomplete and inline documentation. See:

Versioning the Typings

Second, as I've not seen any [public] conversation on how to structure these typings with respect to host application version changes, I would like to suggest that you take a page out of the NodeJS type declaration versioning. Perhaps this was the plan all along, as it's the approach suggested by DefinitelyTyped, but I think it's worth bringing up for the avoidance of doubt.

This means that you would end up supporting multiple "versions" of typings. It also means that you could guarantee that users with, say, scripts targeting XD 14 specifically could set their type dependencies to something like @types/adobe-xd-uxp@14 and guarantee that an npm update wouldn't suddenly poison their ambient type declarations with APIs that don't actually exist for their target platform yet.

Currently, APIs in this repository are documented with notes reading something like:

Since: XD 14

This is excellent information, but it isn't functional. Properly versioning the types allows users to code in an environment that only suggests APIs available to their specified target.

Separating UXP from XD

My understanding is that UXP is the eventual successor to CEP and will be adopted by other host applications over time. To support this paradigm, I would strongly suggest that you treat the uxp typings as their own package that the "adobe-xd-uxp" typings reference. With the versioning support outlined above, you could ensure that your @types/adobe-xd-uxp@15 has a dependency on @types/adobe-uxp@1 while, say, @types/adobe-xd-uxp@20 has a dependency on @types/adobe-uxp@4.

Other host applications could then also benefit from the core uxp type declarations by referencing them as needed.

---

Perhaps everything I've typed in this comment matches the implicit approach that was already planned... if so, cool! If not, I only hope that this comment starts a constructive discussion on the topics raised.

[pklaschka]

@ericdrobinson

I've some comments that I hope will be helpful to this discussion.

Communicating the Purpose of Typings

First, I would strongly suggest that you be careful as to how you message the purpose of these typings. I bring this up because the first sentence of this issue starts with:

For projects that utilize typescript and npm

Type Declaration Files (aka "typings") are not just for TypeScript. They power immensely powerful features for pure JavaScript when used in compatible editors. With the very typings you guys have in these documents you can help your pure-JavaScript developers as well! To that end, I would suggest that you simplify that statement to simply read:

For projects that utilize npm

I'm not trying to suggest that you guys update this Issue specifically, but rather that you take a broader view of the importance and impact that these files may have for your XD (and, eventually, the greater UXP) developers.

Case in point: I am not an XD developer; I've never touched the program. However, by simply downloading this repository and creating a test.js file, I'm able to begin writing pure JavaScript in Visual Studio Code with IntelliSense-powered autocomplete and inline documentation. See:

Sounds great. In fact, I had initially developed the typings to only get used for autocompletion – the fact that they work for TypeScript as well were an added bonus where we had basically only afterwards discovered how they can get used for TypeScript 😉

Versioning the Typings

Second, as I've not seen any [public] conversation on how to structure these typings with respect to host application version changes, I would like to suggest that you take a page out of the NodeJS type declaration versioning. Perhaps this was the plan all along, as it's the approach suggested by DefinitelyTyped, but I think it's worth bringing up for the avoidance of doubt.

This means that you would end up supporting multiple "versions" of typings. It also means that you could guarantee that users with, say, scripts targeting XD 14 specifically could set their type dependencies to something like @types/adobe-xd-uxp@14 and guarantee that an npm update wouldn't suddenly poison their ambient type declarations with APIs that don't actually exist for their target platform yet.

I agree. Since this is also the versioning system I've used for tags or releases here on GitHub (v14.0 for XD 14, v15.0 and v15.1 as "revisions" of XD 15, cf. https://github.com/AdobeXD/typings/releases), we can just continue to use that system.

Currently, APIs in this repository are documented with notes reading something like:

Since: XD 14

This is excellent information, but it isn't functional. Properly versioning the types allows users to code in an environment that only suggests APIs available to their specified target.

Since I want to reflect the API info in the docs comments, this is something which – as long as I basically maintain the repo – will probably remain. It is, however, not meant as a replacement to using the typings at a specific version, but used to note any changes. With API-changes on XD's side, this info isn't meant as a functional "warning", but just as a reflection of the API docs. I may, for example, check the lowest compatible version without having to look up the API docs website for every function that way.

Separating UXP from XD

My understanding is that UXP is the eventual successor to CEP and will be adopted by other host applications over time. To support this paradigm, I would strongly suggest that you treat the uxp typings as their own package that the "adobe-xd-uxp" typings reference. With the versioning support outlined above, you could ensure that your @types/adobe-xd-uxp@15 has a dependency on @types/adobe-uxp@1 while, say, @types/adobe-xd-uxp@20 has a dependency on @types/adobe-uxp@4.

Other host applications could then also benefit from the core uxp type declarations by referencing them as needed.

I think that that's a great idea. However, I think that this will only become relevant when other host applications use uxp. As long as there aren't any other host apps accessible to me (I'm saying it that way since I can – of course – not exclude the possibility that some other app already has a prerelease program regarding UXP extensibility which I'm unaware of), I think it's easier to keep this managed in here.

Perhaps everything I've typed in this comment matches the implicit approach that was already planned... if so, cool! If not, I only hope that this comment starts a constructive discussion on the topics raised.

From the looks of it, I mostly agree with you (and while I'm not working at Adobe, I'm basically currently maintaining this repo, so chances are good things we agree on might get done that way, unless anyone from Adobe says something against it 🙂 ). Besides that, constructive ideas, criticism and discussions are always welcome here, so thank you for your suggestions 👍