Wavesurfer.js: plugin type definition

[lee-zion]

Wavesurfer.js version(s)

v4.0.1

Browser and operating system version(s)

Chrome 84.0.4147.125, Windows 10 Pro

Code needed to reproduce the issue

Plugin example from (here)[https://wavesurfer-js.org/example/spectrogram/index.html] seems not working in typescript.

import Wavesurfer from 'wavesurfer.js'
let wavesurefer: Wavesurfer;
wavesurfer = Wavesurfer.create({
  ...
  plugins: [
    Wavesurfer.spectrogram.create({
      fftSamples: 2048,
      ...
    })
  ]
});

I saw PluginDefinitions are well described in index.d.ts as below:

interface PluginDefinition {
  name: String;
  staticProps?: object;
  deferInit?: boolean;
  params: object;
  instance: { new (params: object, ws: WaveSurfer): WaveSurferPlugin };
}

I saw documents and issues, but there are no available informations about name, staticProps and so on.

My question is how to use plugin in typescript, and any example about typescript and plugin would be appreciated.

[peterj35]

Having a similar issue, when importing the RegionPlugin as such:

import RegionPlugin from 'wavesurfer.js/dist/plugin/wavesurfer.regions.min.js'

Seeing typescript error:

Could not find a declaration file for module 'wavesurfer.js/dist/plugin/wavesurfer.regions.min.js'. '/workspace/node_modules/wavesurfer.js/dist/plugin/wavesurfer.regions.min.js' implicitly has an 'any' type.
  If the 'wavesurfer.js' package actually exposes this module, consider sending a pull request to amend 'https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/wavesurfer.js` 

[lee-zion]

Some progress to share.

plugins: [
  {
    name: "spectrogram",
    params: {
      container: "#wave-spectrogram",
      fftSamples: 2048,
    },
    instance: WavesurferPlugin
  }
]

Above matches all the types, but instance is undefined so it fails.
I'm looking index.d.ts and there seems no other interfaces than WavesurferPlugin, but is empty.

Since I'm a begineer in typescript and not familiar with OOP, I cannot understand what kind of code matches to below:

instance: { new (params: object, ws: WaveSurfer): WaveSurferPlugin };

[sundayz]

Plugins recently got moved around in folders so maybe that’s an issue.

Although I don’t think the definitelytyped types have been updated in a long while. Someone needs to add typings for all the plugins.

@thijstriemstra maybe it would be better to move the type definitions inside the project? it would be simpler to keep the types in sync with the current version. The DefinitelyTyped repo says the type definition file is for version 3.3. None of the plugins have types either. I could add them.

[thijstriemstra]

maybe it would be better to move the type definitions inside the project?

I did not know there were typings.

Someone needs to add typings for all the plugins.

Right. Not me though ;)

I could add them.

Nice!

[thijstriemstra]

4.1.0 will move more plugins to a separate directory, anyone updating the typings might want to wait until that's released.

[sundayz]

What do you think about moving the types into this project? In a folder called “types”

https://stackoverflow.com/questions/56834190/why-publish-the-typescript-declaration-file-on-definitelytyped-for-a-javascript

It would be easier to maintain and they would still be optional. Maybe someone else knows better than me the advantages vs disadvantages

[thijstriemstra]

I'm fine with that.

[thijstriemstra]

What do you think about moving the types into this project?

How does this start?

[sundayz]

What do you think about moving the types into this project?

How does this start?

Making a new folder called "types". I started a prototype, but I thought about it some more. Which is the higher cost: maintaining typescript types, or rewriting the project to (partially) use typescript. And I am not sure which is the answer. If we keep the project javascript and create type definitions, we have to make sure every single change we make is also reflected in the types.

[dtilchin]

Does anyone have at least a prototype definition file for plugins? I'm reluctantly about to give this a shot myself, but I've never created one of these before and I just started using WaveSurfer yesterday 🤔
@sundayz do you have a public fork/branch/blob of what you've started on?

For the overall project, I think having more complete typescript defs would help adoption. Personally I've spent about 75% of my time with WaveSurfer so far trying to figure out how to make plugins work (which does say something very positive about how easy to initially grasp WS is in general!)

[sundayz]

@dtilchin https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/wavesurfer.js/index.d.ts

You can use this as a starting point. You could commit directly to definitelytyped. The alternative is configuring typescript inside the project and adding a "types" folder. In my opinion best case would be to simply convert the whole project to typescript and over time add type annotations to the functions.

Typescript can also automatically generate type defintions for the whole project, I've done it, I'll see if I still have the branch... but it would be easier and better to do a gradual conversion to typescript.

[dtilchin]

I'm throwing in the towel, for now. I just spent far too long trying to figure out how to get a type declaration for a plugin working to no avail. The fact that there are no imports of plugins seems to make this less clear-cut; but I've never dealt with this stuff before so I'm also underinformed.

To enable the plugin, add the script plugin/wavesurfer.regions.js to your page.

I _think_ because of this, what people are doing is importing plugins from eg wavesurfer.js/dist/plugin/cursor/cursor.js. This seems to make the resolution of the module declarations, or whatever the heck I'm supposed to do here, not work in an obvious way.

For now I'm probably going to just use the plugins in JS files, maybe with a tiny wrapper to do what I need.

Perhaps I'll open a ticket on DefinitelyTyped and ping the contributors to the basic type declaration that exists.

[thijstriemstra]

If we keep the project javascript and create type definitions, we have to make sure every single change we make is also reflected in the types.

This doesn't sound like it's worth the effort and a lot of maintenance headaches.

[this-username-is-taken]

I was able to get the plugins to work with Typescript by doing the following:

1. Import the plugin directly from the dist folder:
   import SpectrogramPlugin from 'wavesurfer.js/dist/plugin/wavesurfer.spectrogram';
2. Use the plugin as described in the docs:
   var wavesurfer = WaveSurfer.create({ // wavesurfer options ... plugins: [ SpectrogramPlugin.create({ // plugin options ... }) ] });
3. Turn off TS7016 by adding "noImplicitAny": false to tsconfig.json.

Definitely not as ideal as having a proper Typescript definition, but at least I am now able to use the plugins.

[dtilchin]

If we keep the project javascript and create type definitions, we have to make sure every single change we make is also reflected in the types.

This doesn't sound like it's worth the effort and a lot of maintenance headaches.

Just to be clear, this is already the situation - it's just other contributors doing the work in another repo (https://www.npmjs.com/package/@types/wavesurfer.js). To a user of WS, the current issue is basically that @types/wavesurfer.js is incomplete (or out of date), specifically the plugins.

Aside: I did end up kludging up some typedefs for a few plugins I needed. It's definitely not the right way to do this - I'm fairly new to TS - but this is an illustration of how one could make it work in a pinch if you don't have better options ;)
https://gist.github.com/dtilchin/b2f4c676eda4c597cafbefa5b96ae5b5
(Note: this is just a stub / illustration of how to do this. I think I generated the mappings with tsc. If anyone wants the whole shazam I could make a working example)

BTW, nice initiative on the TS migration. That would be very nice.