feat: callback as an option in plugin method

[jkbz64]

Hello,

It would be nice to have callback as an option in nativePromise plugin methods to handle some side effects without relying on global listeners or making the process complicated for the end-user e.g:

SomePlugin.someMethod({
  onSomething: () => {}
});

Currently there is no public api to call.getFunction inside plugin to get the callback id, build it into PluginCall and resolve it.

I know about @PluginMethod(returnType = PluginMethod.RETURN_CALLBACK) but it's not perfect - the function becomes nativeCallback which changes the return type to Promise<String> and that forces user of the plugin to detect the "progress" and "completion" of the process in the callback.

Real world example

I'm trying to implement download progress in capacitor-community/http#159 but inability to pass callback as an option forces me to either:

• use notifyListeners inside nativePromise method

  + We get the result as intended in the promise
  - Additional call to subscribe to events
  - Progress of the downloaded files is getting mixed up in one listener which can be:
  mitigated by dispatching different naming events eg: notifyListeners("progress:file_name", ...)
  worked around by "routing" the events by the file name inside global listener

• use nativeCallback

  + Non-mixed up progress of multiple instances of downloaded files
  - Promise<String> result
  - The end-user has to write the logic to detect the result (and resolve self-made promise) and handle side-effect (progress) manually in the callback

Both ways are in my opinion not perfect for such case and this feature would make all plugins better without relying on workarounds.

Workaround

One theoretical way I can think of to "workaround" the lack of callback as an option for plugins is to make a wrapper/proxy for registerPlugin<SomePlugin>(...) result and override the specific function that does nativeCallback approach there on original plugin object's method, rerouting various callbacks in the original one and returning promise to make it look like nativePromise.

Pseudo-example:

const oPlugin = createPlugin<SomePlugin>(...);

const Plugin = { 
  ...oPlugin, 
  originalMethod: (options) => { 
    return new Promise((resolve, reject) => {
      const { onSomething, onSomethingOther,  ...restOptions } = options;
      oPlugin.originalMethod(restOptions, (e) => {
        if (e.done) resolve(e.whatever);
        else {
          onSomething(e.something);
          if (e.somethingOther) onSomethingOther(e.somethingOther);
          // etc
        }
     });
    })
  }
}};

export { Plugin };

Related: #1920, #4843