Build typescript .d.ts files

[PaulHax]

Adds a tsc step in the npm run build script.

api.js changes:

• make most options to api.DICOMwebClient optional.
• add progressCallback arg to retrieveSeries

[pieper]

Should these be two different topics?

[hackermd]

@PaulHax thanks for your PR. Could you kindly provide some context for these changes and elaboration on why you think they would be needed?

[PaulHax]

Hi @hackermd

.d.ts files make this library easier to use with Typescript projects and enable auto-completion in some IDEs.

The Typescript build tool can use the extensive JS Docs comments to generate types. The couple changes the JS Docs I made bring the generated TS types closer to the JavaScript behavior.

[hackermd]

Thanks @PaulHax, I see how that could be helpful. This appears to be related to #42. I wonder whether we should rather focus on getting the full types into the library?

[PaulHax]

Ah, some nice work in Slim with the essential Dataset, Study, MetadataElement, etc types. Copying the Slim types in and closing this PR sounds good.

[hackermd]

Could you help us get #42 over the finish line? It appears you have experience in configuration a JavaScript library for TypeScript and I am wondering whether we may be able to reuse (parts of) the configuration file that's included in this PR.

[hackermd]

I would also like to include your improvements/fixes of the documentation.

[PaulHax]

I would like to help with this.

Would be nice to keep using the JS Docs for the source maps, doc helper pop-ups, and future maintenance. I pushed up another commit that mixes in Slim's Metadata and and MetadataElement interfaces. It add some Typescript oriented lines to api.js

/**
 * @typedef { import("../types/types").InstanceMetadata } InstanceMetadata
 */

But the docs would get better with TS folks forced to maintain them?

[PaulHax]

Hi @hackermd

Have any thoughts on keeping the JS Docs the source of type truth?

[hackermd]

Have any thoughts on keeping the JS Docs the source of type truth?

I have limited experience with mixing JavaScript and TypeScript. Based on my understanding, there are two options:

1. Declare the types in a separate .d.ts file and omit them in the JSDoc docstrings
2. Define the types in the JSDoc docstrings

The first option has the advantage that the type declarations can be specified in the package.json file via the types parameter: https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

In addition, I tend argue that it would make the transition to TypeScript (.js -> .ts) easier, because we wouldn't want the type definitions in the JSDoc docstrings anymore once type hints are used throughout the code, would we?

What would be the downsides of that approach?

[PaulHax]

This PR adds a type field to the pacakge.json file pointing to the tsc built .d.ts file. It also mixes in Slim's Metadata type via a comment in api.js

@typedef { import("../types/types").InstanceMetadata } InstanceMetadata

Keeping types in the JSDocs makes the docs appear on hover and "go to definition" go to the JavaScript.

[hackermd]

Thanks @PaulHax! Looks mostly good to me. Unfortunately, our pipelines are currently broken (#65), so we'll have to ignore the failures.

Moving forward it would be great to make the documentation available online. Do you know how to generate the HTML files with JSDoc together with the typescript type declaration files?

[PaulHax]

Great 👍

Do you know how to generate the HTML files with JSDoc

That is something I have not done before.

[hackermd]

Do you know how to generate the HTML files with JSDoc

That is something I have not done before.

Okay, we can figure that out later.