Add union type parameters

[cycraig]

Description of change

This adds the UMethodQuery and UDID (naming convention open to change) Typescript union types. This pattern allows us to create analogues for generic types in function parameters, such as MethodQuery which takes either an IotaDIDUrl or String. This is to enhance the developer-friendliness of our Wasm API by removing unnecessary toString invocations and allowing pseudo-generic, polymorphic function parameters.

export type UMethodQuery = DIDUrl | string;
export type UDID = DID | string;

Edit: this PR no longer exports the union types to Typescript, instead it injects the union into the function parameter definitions directly.

E.g.

signSelf(key_pair: KeyPair, method_query: DIDUrl | string): void;

With this change, all of the following work:

doc.signSelf("did:iota:example#sign-0");                // CURRENT
doc.signSelf(doc.defaultSigningMethod().id.toString()); // CURRENT
doc.signSelf(doc.defaultSigningMethod().id);            // NEW

doc.resolveMethod("did:iota:example#sign-0");                // CURRENT
doc.resolveMethod(doc.defaultSigningMethod().id.toString()); // CURRENT
doc.resolveMethod(doc.defaultSigningMethod().id);            // NEW

let resolved = await client.resolve("did:iota:example"); // CURRENT
let resolved = await client.resolve(doc.id.toString());  // CURRENT
let resolved = await client.resolve(doc.id);             // NEW

let history = await client.resolveHistory("did:iota:example"); // CURRENT
let history = await client.resolveHistory(doc.id.toString());  // CURRENT
let history = await client.resolveHistory(doc.id);             // NEW

The alternative for Client::resolve and Client::resolveHistory would be to enforce taking in a WasmDID only, but error handling is more unwieldy than in Rust and users may extract DIDs as strings from JSON objects like credentials. The proposed pattern would still be useful for UMethodQuery which matches the behaviour in Rust. Note this is only possible when all types in the union serialise to the same representation, since we use serde to handle the conversion. Different union types are possible but would require an intermediary untagged enum to handle deserialisation with this method.

Added

• UDID union type to take either DID or a string as a parameter.
• UMethodQuery union type to take either DIDUrl or a string as a parameter.
• WasmNetwork::name getter.

Changed

• Document::resolveMethod parameter changed from string to UMethodQuery.
• Document::revokeMerkleKey parameter changed from string to UMethodQuery.
• Document::signSelf parameter changed from string to UMethodQuery.
• Document::diff parameter changed from string to UMethodQuery.
• Client::resolve parameter changed from string to UDID.
• Client::resolveHistory parameter changed from string to UDID.
• WasmDID::network is no longer a getter, just a regular function.
• WasmDID JSON representation changed to match IotaDID.
• WasmDIDUrl JSON representation changed to match IotaDID.

Type of change

• Bug fix (a non-breaking change which fixes an issue)
• Enhancement (a non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Fix

How the change has been tested

Wasm tests and examples pass locally.

Change checklist

• I have followed the contribution guidelines for this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[olivereanderson]

Looks good to me!

[abdulmth]

The only problem I see with this change is that the type in the method signature became harder to understand.
for example:

signSelf(key_pair: KeyPair, method_query: UMethodQuery): void

Developers must go to the method declaration to see what UMethodQuery actually includes, and that's a string can be passed as an argument.
In a perfect world, the method should look like:

signSelf(key_pair: KeyPair, method_query: DIDUrl | string): void

I'm not sure removing toString() is worth the complexity the new method signature has. But also having polymorphic arguments is an improvement.

[cycraig]

In a perfect world, the method should look like:

signSelf(key_pair: KeyPair, method_query: DIDUrl | string): void

Turns out wasm-bindgen does actually support generating such a function signature via typescript_type! rustwasm/wasm-bindgen#2155

I forgot about the above since I was just looking at their guide: https://rustwasm.github.io/docs/wasm-bindgen/reference/attributes/on-rust-exports/typescript_type.html

/// Duck-typed union to pass either a string or WasmDID as a parameter.
#[wasm_bindgen]
extern "C" {
  #[wasm_bindgen(typescript_type = "DID | string")]
  pub type UWasmDID;
}

/// Duck-typed union to pass either a string or WasmDIDUrl as a parameter.
#[wasm_bindgen]
extern "C" {
  #[wasm_bindgen(typescript_type = "DIDUrl | string")]
  pub type UWasmMethodQuery;
}

With the revised code the Typescript function signature is as-desired:

* @param {KeyPair} key_pair
* @param {DIDUrl | string} method_query
*/
  signSelf(key_pair: KeyPair, method_query: DIDUrl | string): void;

Thanks for the catch!

[eike-hass]

big improvement in my opinion