Add api.disco.entities.find API function

This lets us search for a disco entity that implements a particular
disco feature.

The entity must be either our own JID, our domain's JID or one of the
(top-level) items advertised by our domain JID.

Author: jcbrand

src/headless/plugins/disco/api.js

@@ -2,7 +2,7 @@ import { getOpenPromise } from '@converse/openpromise';
 import _converse from '../../shared/_converse.js';
 import api from '../../shared/api/index.js';
 import converse from '../../shared/api/public.js';
-import log from "@converse/log";
+import log from '@converse/log';
 
 const { Strophe, $iq } = converse.env;
 
@@ -197,6 +197,36 @@ export default {
          * @memberOf api.disco
          */
         entities: {
+            /**
+             * Finds the first entity advertising a given feature.
+             *
+             * @method api.disco.entities.find
+             * @param {string} feature The feature var to search for.
+             * @returns {Promise<DiscoEntity|null>} The matching DiscoEntity instance or null if not found.
+             */
+            async find(feature) {
+                const bare = _converse.session.get('bare_jid');
+                const bare_entity = await api.disco.entities.get(bare);
+                if (bare_entity && (await bare_entity.getFeature(feature))) {
+                    return bare_entity;
+                }
+
+                const domain = Strophe.getDomainFromJid(bare);
+                const domain_entity = await api.disco.entities.get(domain);
+                if (domain_entity && (await domain_entity.getFeature(feature))) {
+                    return domain_entity;
+                }
+
+                const items = await api.disco.entities.items(domain);
+                for (const entity of items) {
+                    const jid = entity.get('jid');
+                    if (await api.disco.features.has(feature, jid)) {
+                        return api.disco.entities.get(jid);
+                    }
+                }
+                return null;
+            },
+
             /**
              * Get the corresponding `DiscoEntity` instance.
              *
@@ -302,10 +332,7 @@ export default {
 
                 const items = await api.disco.entities.items(jid);
 
-                const promises = [
-                    entity.getFeature(feature),
-                    ...items.map((i) => i.getFeature(feature)),
-                ];
+                const promises = [entity.getFeature(feature), ...items.map((i) => i.getFeature(feature))];
                 const result = await Promise.all(promises);
                 return result.filter((f) => f instanceof Object);
             },

src/headless/plugins/disco/tests/disco.js

@@ -1,7 +1,7 @@
 /*global converse */
 import mock from "../../../tests/mock.js";
 
-const { u, stx } = converse.env;
+const { u, stx, Strophe } = converse.env;
 
 describe("Service Discovery", function () {
 
@@ -108,7 +108,6 @@ describe("Service Discovery", function () {
                 ['discoInitialized'], {},
                 function (_converse) {
 
-            const { Strophe } = converse.env;
             spyOn(_converse.api, "trigger").and.callThrough();
             _converse.disco_entities.get(_converse.domain).features.create({'var': Strophe.NS.MAM});
             expect(_converse.api.trigger).toHaveBeenCalled();
@@ -117,4 +116,66 @@ describe("Service Discovery", function () {
             expect(last_call.args[1].get('var')).toBe(Strophe.NS.MAM);
         }));
     });
+
+    describe('api.disco.entities.find', function () {
+        it(
+            "returns our own JID's entity if the bare JID advertises the desired feature",
+            mock.initConverse([], {}, async function (_converse) {
+                const bare = _converse.session.get('bare_jid');
+                await mock.waitUntilDiscoConfirmed(_converse, bare, [], ['feature1']);
+                const result = await _converse.api.disco.entities.find('feature1');
+                expect(result.get('jid')).toBe(bare);
+            })
+        );
+
+        it(
+            'returns the domain entity if bare JID does not advertise but domain does',
+            mock.initConverse([], {}, async function (_converse) {
+                const bare = _converse.session.get('bare_jid');
+                const domain = Strophe.getDomainFromJid(bare);
+                await mock.waitUntilDiscoConfirmed(_converse, bare, [], []);
+                await mock.waitUntilDiscoConfirmed(_converse, domain, [], ['feature2']);
+                const result = await _converse.api.disco.entities.find('feature2');
+                expect(result.get('jid')).toBe(domain);
+            })
+        );
+
+        it(
+            'returns first matching item entity if neither bare nor domain advertises but an item does',
+            mock.initConverse([], {}, async function (_converse) {
+                const bare = _converse.session.get('bare_jid');
+                const domain = Strophe.getDomainFromJid(bare);
+                await mock.waitUntilDiscoConfirmed(_converse, bare, [], []);
+                await mock.waitUntilDiscoConfirmed(
+                    _converse,
+                    domain,
+                    [{ 'category': 'server', 'type': 'IM' }],
+                    ['http://jabber.org/protocol/disco#items']
+                );
+                await mock.waitUntilDiscoConfirmed(_converse, domain, [], [], ['a@b', 'c@d'], 'items');
+                await mock.waitUntilDiscoConfirmed(_converse, 'a@b', [], []);
+                await mock.waitUntilDiscoConfirmed(_converse, 'c@d', [], ['feature3']);
+                const result = await _converse.api.disco.entities.find('feature3');
+                expect(result.get('jid')).toBe('c@d');
+            })
+        );
+
+        it(
+            'returns null if no entity matches',
+            mock.initConverse([], {}, async function (_converse) {
+                const bare = _converse.session.get('bare_jid');
+                const domain = Strophe.getDomainFromJid(bare);
+                await mock.waitUntilDiscoConfirmed(_converse, bare, [], []);
+                await mock.waitUntilDiscoConfirmed(
+                    _converse,
+                    domain,
+                    [{ 'category': 'server', 'type': 'IM' }],
+                    ['http://jabber.org/protocol/disco#items']
+                );
+                await mock.waitUntilDiscoConfirmed(_converse, domain, [], [], [], 'items');
+                const result = await _converse.api.disco.entities.find('feature4');
+                expect(result).toBeNull();
+            })
+        );
+    });
 });

src/headless/types/plugins/disco/api.d.ts

@@ -79,6 +79,14 @@ declare namespace _default {
          */
         export function items(jid: string, node?: string): Promise<any>;
         export namespace entities {
+            /**
+             * Finds the first entity advertising a given feature.
+             *
+             * @method api.disco.entities.find
+             * @param {string} feature The feature var to search for.
+             * @returns {Promise<DiscoEntity|null>} The matching DiscoEntity instance or null if not found.
+             */
+            function find(feature: string): Promise<import("./entity").default | null>;
             /**
              * Get the corresponding `DiscoEntity` instance.
              *