feat!(typescript): align TypeScript definitions with Discovery API (#513)

* feat!(typescript): align TypeScript definitions with Discovery API

* fixup! feat!(typescript): align TypeScript definitions with Discovery API

* fixup! feat!(typescript): align TypeScript definitions with Discovery AP…

* fixup! feat!(typescript): align TypeScript definitions with Discovery API

Co-authored-by: danielpeintner <[email protected]>

* fixup! feat!(typescript): align TypeScript definitions with Discovery API

* fixup! feat!(typescript): align TypeScript definitions with Discovery API

* chore(typescript): bump version number

---------

Co-authored-by: danielpeintner <[email protected]>

Author: JKRhb

typescript/scripting-api/index.d.ts

@@ -6,11 +6,30 @@ type DeepPartial<T> = T extends object ? {
 declare namespace WoT {
 
     /**
-     * Starts the discovery process that will provide ConsumedThing 
-     * 
+     * Starts the discovery process that will provide {@link ThingDescription}
+     * objects for Thing Descriptions that match an optional {@link filter}
+     * argument of type {@link ThingFilter}.
+     *
+     * @param filter represents the constraints for discovering Things as key-value pairs
+     */
+    export function discover(filter?: ThingFilter): Promise<ThingDiscoveryProcess>;
+
+    /**
+     * Starts the discovery process that, given a TD Directory {@link url}, will
+     *  provide {@link ThingDescription} objects for Thing Descriptions that
+     * match an optional {@link filter} argument of type {@link ThingFilter}.
+     *
+     * @param url URL pointing to a TD Directory.
      * @param filter represents the constraints for discovering Things as key-value pairs
      */
-    export function discover(filter?: ThingFilter): ThingDiscovery;
+    export function exploreDirectory(url: string, filter?: ThingFilter): Promise<ThingDiscoveryProcess>;
+
+    /**
+     * Requests a {@link ThingDescription} from the given {@link url}.
+     *
+     * @param url The URL to request the Thing Description from.
+     */
+    export function requestThingDescription(url: string): Promise<ThingDescription>;
 
     /**
      * Accepts a ThingDescription and returns a ConsumedThing
@@ -31,47 +50,20 @@ declare namespace WoT {
      * Dictionary that represents the constraints for discovering Things as key-value pairs. 
      */
     export interface ThingFilter {
-        /**
-         * The method field represents the discovery type that should be used in the discovery process. The possible values are defined by the DiscoveryMethod enumeration that can be extended by string values defined by solutions (with no guarantee of interoperability). 
-         */
-        method?: DiscoveryMethod | string; // default value "any", DOMString
-        /**
-         * The url field represents additional information for the discovery method, such as the URL of the target entity serving the discovery request, such as a Thing Directory or a Thing.
-         */
-        url?: string;
-        /**
-         * The query field represents a query string accepted by the implementation, for instance a SPARQL query. 
-         */
-        query?: string;
         /**
          * The fragment field represents a template object used for matching against discovered Things.
          */
         fragment?: object;
     }
 
-    /** The DiscoveryMethod enumeration represents the discovery type to be used */
-    export enum DiscoveryMethod {
-        /** does not restrict */
-        "any",
-        /** for discovering Things defined in the same Servient */
-        "local",
-        /** for discovery based on a service provided by a Thing Directory */
-        "directory",
-        /** for discovering Things in the same/reachable network by using a supported multicast protocol */
-        "multicast"
-    }
-
     /**
      * The ThingDiscovery object is constructed given a filter and provides the properties and methods
      * controlling the discovery process. 
      */
-    export interface ThingDiscovery {
+    export interface ThingDiscoveryProcess extends AsyncIterable<ThingDescription> {
         filter?: ThingFilter;
-        active: boolean;
         done: boolean;
         error?: Error;
-        start(): void;
-        next(): Promise<ThingDescription>;
         stop(): void;
     }
 
@@ -300,4 +292,4 @@ declare namespace WoT {
 
 declare module "wot-typescript-definitions" {
     export = WoT;
-}
+}

typescript/scripting-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wot-typescript-definitions",
-  "version": "0.8.0-SNAPSHOT.28",
+  "version": "0.8.0-SNAPSHOT.29",
   "description": "TypeScript definitions for the W3C WoT Scripting API",
   "author": "W3C Web of Things Working Group",
   "license": "W3C-20150513",