[typescript] Use namespace instead of interface for WoT functions

[relu91]

Currently, the wot-typescript-definition file export WoT functions as part of the WoT interface. This interface is under the namespace WoT, therefore accessible with WoT.WoT path. This works well for node.js environments, while it may not work as intended inside browsers or servient runtimes.

Following the IDL for the WoT interface, those API should be accessed from the global scope as, for example, WoT.consume(..). I assume that also runtime scripts (i.e. scripts run by servients) MAY use the same mechanism (instead of import or require). However, the typescript definition does not define a globally scoped variable.

Typescript documentation suggests using a namespace to specify a global variable. I made a refactored version of the type-definition here. With that d.ts, vscode (and tsc) correctly identify WoT global variable inside node-wot scripts as shown in this tweet

I am not sure that this is the intended behavior, therefore I am not creating a PR. However, I'd like to understand whether my suggestion could be an improvement to the current wot-typescript-definitions or not.

[zolkis]

A quick note: we could make (or could have made) the API object(s) constructible. That would go well with today's trends and solve the issue. It would also ease the separation of conformance classes.

We have played with the idea in the past, i.e. instead of WOT.consume() one could just create a new ConsumedThing(td) with a Thing Description td.

Since we would just create JS objects, the constructors won't have side effects.

All the things (bindings) that require a Promise now could be done transparently by the impl when any of the interactions are invoked.

Similarly, instead of WOT.produce() we could have new ExposedThing(td_init) based on an init dictionary. There the expose() method would re-generate the bindings from the internal slot TD representation every time it is invoked.

I made a refactored version of the type-definition here.

Looks good to me.

[egekorkan]

I like this approach as well 👍

[danielpeintner]

@relu91 the proposal is to change

export as namespace WoT;

/**
 * The WoT interface defines the API entry point exposed as a singleton and contains the API methods.
 */
export interface WoT {

to

/**
 * The WoT namespace defines the API entry point exposed as a singleton and contains the API methods.
 */
declare namespace WoT {

and also wrap all other constructs in it plus removing all export statements.

I am fine with that.

Did you try to out whether it has any consequences to existing implementations/code?

If not I like the approach!

[relu91]

I don't have a strong opinion about constructible API object(s). I think people coming from OOP background would like them more, whereas people from function background would prefer the current definition. Using functions might be safer if in the future, somehow, we came up with the idea to initialize a ConsumeThing asynchronously... but again I am quite positive about this approach.

Answering @danielpeintner, yes that is what I changed. I am not sure that I can submit a PR for a W3C repository... since I am not inside the WG. However, I am totally fine if you do the changes 👍 .

Did you try to out whether it has any consequences to existing implementations/code?

I briefly did some experiments with node-wot I remember that I changed a couple of imports and then it was fine.

[zolkis]

For historical reference (and arguments) see #3.
Constructors are idiomatic in JS now, but we have adopted this opinion and included it in the rationale, too (which may need some updating, too).

Of course we could have plain object constructors and second phase (asynchronous) initialization. We have played with that, too, and IIRC didn't receive much love.

[danielpeintner]

I think the intial issue about TypeScript is still not resolved...