Merge pull request #1183 from danielpeintner/issue-1055-v2

refactor: favor WoT.requestThingDescription instead of general fetch

API.md

@@ -245,7 +245,7 @@ Interacting with another WoT Thing is called consuming a Thing and works by usin
 ##### Fetch a Thing Description of a Thing given its URL
 
 ```javascript
-WoTHelpers.fetch("http://localhost:8080/counter").then(async(td) => {
+WoT.requestThingDescription("http://localhost:8080/counter").then(async(td) => {
   // Do something with the TD
 }
 ```
@@ -255,13 +255,13 @@ URLs can have various schemes, including `file://` to read from the local filesy
 ##### Consume a TD of a Thing, including parsing the TD and generating the protocol bindings in order to access lower level functionality
 
 ```javascript
-WoTHelpers.fetch("http://localhost:8080/counter").then(async (td) => {
+WoT.requestThingDescription("http://localhost:8080/counter").then(async (td) => {
     let thing = WoT.consume(td);
     // Do something with the consumed Thing
 });
 ```
 
-Things can be `consume`d no matter if they were fetched with WoTHelpers or not.
+Things can be `consume`d no matter if they were fetched with `WoT.requestThingDescription()`, `WoTHelpers.fetch()` or any other mean.
 `consume` only requires a TD as an `Object`, so you could also use `fs.readFile` and `JSON.parse` or inline it into your code.
 As long at it results in a TD Object, you can receive it over Fax, Morse it or use smoke signals.
 
@@ -298,10 +298,10 @@ It is an asynchronous function that will take some time to complete.
 So you should handle it explicitly.
 Here we use the `async`/`await` functionality of NodeJS.
 
-Declare the surrounding function as `async`, e.g., the `WoTHelpers.fetch()` resolve handler:
+Declare the surrounding function as `async`, e.g., the `WoT.requestThingDescription()` resolve handler:
 
 ```javascript
-WoTHelpers.fetch(myURI).then(async(td) => { ... });
+WoT.requestThingDescription(myURI).then(async(td) => { ... });
 ```
 
 Use `await` to make Promises synchronous (blocking):

README.md

@@ -180,27 +180,21 @@ Now supposing you want to interact with the device, you have to consume its Thin
 ```JavaScript
 // client.js
 // Required steps to create a servient for a client
-const { Servient, Helpers } = require("@node-wot/core");
+const { Servient } = require("@node-wot/core");
 const { HttpClientFactory } = require('@node-wot/binding-http');
 
 const servient = new Servient();
 servient.addClientFactory(new HttpClientFactory(null));
-const WoTHelpers = new Helpers(servient);
-
-WoTHelpers.fetch("http://localhost:8080/counter").then(async (td) => {
-    try {
-        const WoT = await servient.start();
-        // Then from here on you can consume the thing
-        let thing = await WoT.consume(td);
-        thing.observeProperty("count", async (data) => { console.log("count:", await data.value()); });
-        for (let i = 0; i < 5; i++) {
-            await thing.invokeAction("increment");
-        }
-    }
-    catch (err) {
-        console.error("Script error:", err);
+
+servient.start().then(async (WoT) => {
+    const td = await WoT.requestThingDescription("http://localhost:8080/counter");
+    // Then from here on you can consume the thing
+    let thing = await WoT.consume(td);
+    thing.observeProperty("count", async (data) => { console.log("count:", await data.value()); });
+    for (let i = 0; i < 5; i++) {
+        await thing.invokeAction("increment");
     }
-}).catch((err) => { console.error("Fetch error:", err); });
+}).catch((err) => { console.error(err); });
 ```
 
 If you execute both scripts you will see `count: ${count}` printed 5 times. We host a more complex version of this example at [http://plugfest.thingweb.io/examples/counter.html](http://plugfest.thingweb.io/examples/counter.html) and you can find the source code in the [counter example](./examples/browser) folder. You can also find more examples in the [examples folder](./examples/scripts) for JavaScript and in the [examples folder](./packages/examples/) for TypeScript. Finally, for your convenience, we host a set of online Things that you can use to test your applications. You can find more information about them in the [Online Things](#online-things) section.

examples/scripts/counter-client.js

@@ -26,9 +26,8 @@ function getFormIndexForDecrementWithCoAP(thing) {
     // return formIndex: 0 if no CoAP target IRI found
     return 0;
 }
-WoTHelpers.fetch("coap://localhost:5683/counter")
+WoT.requestThingDescription("coap://localhost:5683/counter")
     .then(async (td) => {
-        // using await for serial execution (note 'async' in then() of fetch())
         try {
             const thing = await WoT.consume(td);
             console.info("=== TD ===");

examples/scripts/smart-coffee-machine-client.js

@@ -15,15 +15,14 @@
 // This is an example of Web of Things consumer ("client" mode) Thing script.
 // It considers a fictional smart coffee machine in order to demonstrate the capabilities of Web of Things.
 // An accompanying tutorial is available at http://www.thingweb.io/smart-coffee-machine.html.
-
 // Print data and an accompanying message in a distinguishable way
 function log(msg, data) {
     console.info("======================");
     console.info(msg);
     console.dir(data);
     console.info("======================");
 }
-WoTHelpers.fetch("http://127.0.0.1:8080/smart-coffee-machine").then(async (td) => {
+WoT.requestThingDescription("http://127.0.0.1:8080/smart-coffee-machine").then(async (td) => {
     try {
         const thing = await WoT.consume(td);
         log("Thing Description:", td);

examples/security/oauth/consumer.js

@@ -12,7 +12,7 @@
  *
  * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
  ********************************************************************************/
-WoTHelpers.fetch("https://localhost:8080/oauth").then((td) => {
+WoT.requestThingDescription("https://localhost:8080/oauth").then((td) => {
     WoT.consume(td).then(async (thing) => {
         try {
             const resp = await thing.invokeAction("sayOk");

examples/testthing/testclient.js

@@ -39,9 +39,8 @@ async function testPropertyWrite(thing, name, value, shouldFail) {
         else console.info("PASS " + name + " WRITE (" + displayValue + "):", JSON.stringify(err));
     }
 }
-WoTHelpers.fetch("http://localhost:8080/testthing")
+WoT.requestThingDescription("http://localhost:8080/testthing")
     .then(async (td) => {
-        // using await for serial execution (note 'async' in then() of fetch())
         try {
             const thing = await WoT.consume(td);
             console.info("=== TD ===");

packages/binding-coap/README.md

@@ -26,20 +26,18 @@ The Thing Description is located under the following CoAP URI `coap://plugfest.t
 
 ```js
 // example-client.js
-const { Servient, Helpers } = require("@node-wot/core");
+const { Servient } = require("@node-wot/core");
 const { CoapClientFactory } = require("@node-wot/binding-coap");
 
 // create Servient and add CoAP binding
 const servient = new Servient();
 servient.addClientFactory(new CoapClientFactory());
 
-const wotHelper = new Helpers(servient);
-wotHelper
-    .fetch("coap://plugfest.thingweb.io:5683/testthing")
-    .then(async (td) => {
-        // using await for serial execution (note 'async' in then() of fetch())
+servient
+    .start()
+    .then(async (WoT) => {
         try {
-            const WoT = await servient.start();
+            const td = await WoT.requestThingDescription("coap://plugfest.thingweb.io:5683/testthing");
             const thing = await WoT.consume(td);
 
             // read property
@@ -50,7 +48,7 @@ wotHelper
         }
     })
     .catch((err) => {
-        console.error("Fetch error:", err);
+        console.error("Start error:", err);
     });
 ```
 

packages/binding-http/README.md

@@ -29,19 +29,15 @@ The Thing Description is located under the following uri <http://plugfest.thingw
 Servient = require("@node-wot/core").Servient;
 HttpClientFactory = require("@node-wot/binding-http").HttpClientFactory;
 
-Helpers = require("@node-wot/core").Helpers;
-
 // create Servient and add HTTP binding
 let servient = new Servient();
 servient.addClientFactory(new HttpClientFactory(null));
 
-let wotHelper = new Helpers(servient);
-wotHelper
-    .fetch("http://plugfest.thingweb.io:8083/testthing")
-    .then(async (td) => {
-        // using await for serial execution (note 'async' in then() of fetch())
+servient
+    .start()
+    .then(async (WoT) => {
         try {
-            const WoT = await servient.start();
+            const td = await WoT.requestThingDescription("http://plugfest.thingweb.io:8083/testthing");
             const thing = await WoT.consume(td);
 
             // read property
@@ -52,7 +48,7 @@ wotHelper
         }
     })
     .catch((err) => {
-        console.error("Fetch error:", err);
+        console.error("Start error:", err);
     });
 ```
 

packages/examples/src/bindings/coap/example-client.ts

@@ -13,22 +13,18 @@
  * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
  ********************************************************************************/
 
-import { Servient, Helpers } from "@node-wot/core";
+import { Servient } from "@node-wot/core";
 import { CoapClientFactory } from "@node-wot/binding-coap";
-import { ThingDescription } from "wot-typescript-definitions";
 
 // create Servient and add CoAP binding
 const servient = new Servient();
 servient.addClientFactory(new CoapClientFactory());
 
-const wotHelper = new Helpers(servient);
-wotHelper
-    .fetch("coap://plugfest.thingweb.io:5683/testthing")
-    .then(async (fetched) => {
-        const td: ThingDescription = fetched as ThingDescription;
-        // using await for serial execution (note 'async' in then() of fetch())
+servient
+    .start()
+    .then(async (WoT) => {
         try {
-            const WoT = await servient.start();
+            const td = await WoT.requestThingDescription("coap://plugfest.thingweb.io:5683/testthing");
             const thing = await WoT.consume(td);
 
             // read property
@@ -39,5 +35,5 @@ wotHelper
         }
     })
     .catch((err) => {
-        console.error("Fetch error:", err);
+        console.error("Start error:", err);
     });

packages/examples/src/bindings/http/example-client.ts

@@ -13,22 +13,18 @@
  * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
  ********************************************************************************/
 
-import { Servient, Helpers } from "@node-wot/core";
+import { Servient } from "@node-wot/core";
 import { HttpClientFactory } from "@node-wot/binding-http";
-import { ThingDescription } from "wot-typescript-definitions";
 
 // create Servient and add HTTP  binding
 const servient = new Servient();
 servient.addClientFactory(new HttpClientFactory());
 
-const wotHelper = new Helpers(servient);
-wotHelper
-    .fetch("http://plugfest.thingweb.io:8083/testthing")
-    .then(async (fetched) => {
-        const td: ThingDescription = fetched as ThingDescription;
-        // using await for serial execution (note 'async' in then() of fetch())
+servient
+    .start()
+    .then(async (WoT) => {
         try {
-            const WoT = await servient.start();
+            const td = await WoT.requestThingDescription("http://plugfest.thingweb.io:8083/testthing");
             const thing = await WoT.consume(td);
 
             // read property
@@ -39,5 +35,5 @@ wotHelper
         }
     })
     .catch((err) => {
-        console.error("Fetch error:", err);
+        console.error("Start error:", err);
     });

packages/examples/src/scripts/counter-client.ts

@@ -13,11 +13,6 @@
  * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
  ********************************************************************************/
 
-import { Helpers } from "@node-wot/core";
-import { ThingDescription } from "wot-typescript-definitions";
-
-let WoTHelpers!: Helpers;
-
 function getFormIndexForDecrementWithCoAP(thing: WoT.ConsumedThing): number {
     const forms = thing.getThingDescription().actions?.decrement.forms;
     if (forms !== undefined) {
@@ -31,11 +26,10 @@ function getFormIndexForDecrementWithCoAP(thing: WoT.ConsumedThing): number {
     return 0;
 }
 
-WoTHelpers.fetch("coap://localhost:5683/counter")
+WoT.requestThingDescription("coap://localhost:5683/counter")
     .then(async (td) => {
-        // using await for serial execution (note 'async' in then() of fetch())
         try {
-            const thing = await WoT.consume(td as ThingDescription);
+            const thing = await WoT.consume(td);
             console.info("=== TD ===");
             console.info(td);
             console.info("==========");

packages/examples/src/scripts/smart-coffee-machine-client.ts

@@ -17,10 +17,6 @@
 // It considers a fictional smart coffee machine in order to demonstrate the capabilities of Web of Things.
 // An accompanying tutorial is available at http://www.thingweb.io/smart-coffee-machine.html.
 
-import { ThingDescription } from "wot-typescript-definitions";
-import { Helpers } from "@node-wot/core";
-let WoTHelpers!: Helpers;
-
 // Print data and an accompanying message in a distinguishable way
 function log(msg: string, data: unknown) {
     console.info("======================");
@@ -29,9 +25,9 @@ function log(msg: string, data: unknown) {
     console.info("======================");
 }
 
-WoTHelpers.fetch("http://127.0.0.1:8080/smart-coffee-machine").then(async (td) => {
+WoT.requestThingDescription("http://127.0.0.1:8080/smart-coffee-machine").then(async (td) => {
     try {
-        const thing = await WoT.consume(td as ThingDescription);
+        const thing = await WoT.consume(td);
         log("Thing Description:", td);
 
         // Read property allAvailableResources

packages/examples/src/security/oauth/consumer.ts

@@ -12,13 +12,9 @@
  *
  * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
  ********************************************************************************/
-import { Helpers } from "@node-wot/core";
-import { ThingDescription } from "wot-typescript-definitions";
 
-let WoTHelpers!: Helpers;
-
-WoTHelpers.fetch("https://localhost:8080/oauth").then((td) => {
-    WoT.consume(td as ThingDescription).then(async (thing) => {
+WoT.requestThingDescription("https://localhost:8080/oauth").then((td) => {
+    WoT.consume(td).then(async (thing) => {
         try {
             const resp = await thing.invokeAction("sayOk");
             const result = await resp?.value();

packages/examples/src/testthing/testclient.ts

@@ -13,10 +13,6 @@
  * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
  ********************************************************************************/
 
-import { Helpers } from "@node-wot/core";
-import { ThingDescription } from "wot-typescript-definitions";
-let WoTHelpers!: Helpers;
-
 console.log = () => {
     /* empty */
 };
@@ -51,11 +47,10 @@ async function testPropertyWrite(
     }
 }
 
-WoTHelpers.fetch("http://localhost:8080/testthing")
+WoT.requestThingDescription("http://localhost:8080/testthing")
     .then(async (td) => {
-        // using await for serial execution (note 'async' in then() of fetch())
         try {
-            const thing = await WoT.consume(td as ThingDescription);
+            const thing = await WoT.consume(td);
             console.info("=== TD ===");
             console.info(td);
             console.info("==========");