Move JSDoc typedefs to types.ts

Author: jcbrand

src/headless/plugins/adhoc/api.js

@@ -1,7 +1,3 @@
-/**
- * @typedef {import('./utils').AdHocCommand} AdHocCommand
- * @typedef {import('./utils').AdHocCommandResult} AdHocCommandResult
- */
 import log from '../../log.js';
 import _converse from '../../shared/_converse.js';
 import api from '../../shared/api/index.js';
@@ -10,11 +6,12 @@ import { parseCommandResult, parseForCommands } from './utils.js';
 
 const { Strophe, $iq, u, stx } = converse.env;
 
-/**
- * @typedef {'execute'| 'cancel' |'prev'|'next'|'complete'} AdHocCommandAction
- */
 
 export default {
+    /**
+     * @typedef {import('./types').AdHocCommandResult} AdHocCommandResult
+     */
+
     /**
      * The XEP-0050 Ad-Hoc Commands API
      *
@@ -64,7 +61,7 @@ export default {
          * @method api.adhoc.runCommand
          * @param {String} jid
          * @param {String} sessionid
-         * @param {AdHocCommandAction} action
+         * @param {import('./types').AdHocCommandAction} action
          * @param {String} node
          * @param {Array<{ [k:string]: string }>} inputs
          */

src/headless/plugins/adhoc/types.ts

@@ -0,0 +1,23 @@
+import { XForm } from '../../shared/types';
+
+export type AdHocCommand = {
+    action: string;
+    node: string;
+    sessionid: string;
+    status: string;
+}
+
+type AdHocCommandResultNote = {
+    text: string;
+    type: 'info'|'warn'|'error';
+}
+
+export type AdHocCommandAttrs = {
+    sessionid: string;
+    actions?: string[];
+    note?: AdHocCommandResultNote;
+}
+
+export type AdHocCommandResult = XForm & AdHocCommandAttrs;
+
+export type AdHocCommandAction = 'execute'| 'cancel' |'prev'|'next'|'complete';

src/headless/plugins/adhoc/utils.js

@@ -1,50 +1,25 @@
-/**
- * @typedef {import('lit').TemplateResult} TemplateResult
- * @typedef {import('../../shared/parsers').XForm} XForm
- */
 import sizzle from 'sizzle';
 import converse from '../../shared/api/public.js';
 import { parseXForm } from '../../shared/parsers.js';
 
 const { Strophe, u } = converse.env;
 
-/**
- * @typedef {Object} AdHocCommand
- * @property {string} action
- * @property {string} node
- * @property {string} sessionid
- * @property {string} status
- */
-
 /**
  * Given a "result" IQ stanza that contains a list of ad-hoc commands, parse it
  * and return the list of commands as JSON objects.
  * @param {Element} stanza
- * @returns {AdHocCommand[]}
+ * @returns {import('./types').AdHocCommand[]}
  */
 export function parseForCommands(stanza) {
     const items = sizzle(`query[xmlns="${Strophe.NS.DISCO_ITEMS}"][node="${Strophe.NS.ADHOC}"] item`, stanza);
     return items.map(u.getAttributes);
 }
 
-/**
- * @typedef {Object} AdHocCommandResultNote
- * @property {string} text
- * @property {'info'|'warn'|'error'} type
- *
- * @typedef {Object} AdHocCommandAttrs
- * @property {string} sessionid
- * @property {string[]} [actions]
- * @property {AdHocCommandResultNote} [note]
- *
- * @typedef {XForm & AdHocCommandAttrs} AdHocCommandResult
- */
-
 /**
  * Given a "result" IQ stanza containing the outcome of an Ad-hoc command that
  * was executed, parse it and return the values as a JSON object.
  * @param {Element} iq
- * @returns {AdHocCommandResult}
+ * @returns {import('./types').AdHocCommandResult}
  */
 export function parseCommandResult(iq) {
     const cmd_el = sizzle(`command[xmlns="${Strophe.NS.ADHOC}"]`, iq).pop();

src/headless/plugins/mam/api.js

@@ -1,6 +1,3 @@
-/**
- * @typedef {module:converse-rsm.RSMQueryParameters} RSMQueryParameters
- */
 import _converse from '../../shared/_converse.js';
 import api from '../../shared/api/index.js';
 import converse from '../../shared/api/public.js';
@@ -29,33 +26,16 @@ export default {
      * @memberOf _converse.api
      */
     archive: {
-         /**
-          * @typedef {RSMQueryParameters} MAMFilterParameters
-          * Filter parmeters which can be used to filter a MAM XEP-0313 archive
-          * @property String} [end] - A date string in ISO-8601 format, before which messages should be returned. Implies backward paging.
-          * @property {String} [start] - A date string in ISO-8601 format, after which messages should be returned. Implies forward paging.
-          * @property {String} [with] - A JID against which to match messages, according to either their `to` or `from` attributes.
-          *     An item in a MUC archive matches if the publisher of the item matches the JID.
-          *     If `with` is omitted, all messages that match the rest of the query will be returned, regardless of to/from
-          *     addresses of each message.
-          */
-
-         /**
-          * The options that can be passed in to the {@link _converse.api.archive.query } method
-          * @typedef {MAMFilterParameters} ArchiveQueryOptions
-          * @property {boolean} [groupchat=false] - Whether the MAM archive is for a groupchat.
-          */
-
          /**
           * Query for archived messages.
           *
           * The options parameter can also be an instance of
           * RSM to enable easy querying between results pages.
           *
           * @method _converse.api.archive.query
-          * @param {ArchiveQueryOptions} options - An object containing query parameters
+          * @param {import('./types').ArchiveQueryOptions} options - An object containing query parameters
           * @throws {Error} An error is thrown if the XMPP server responds with an error.
-          * @returns {Promise<MAMQueryResult>} A promise which resolves to a {@link MAMQueryResult} object.
+          * @returns {Promise<import('./types').MAMQueryResult>}
           *
           * @example
           * // Requesting all archived messages
@@ -299,16 +279,6 @@ export default {
             if (set) {
                 rsm = new RSM({...options, 'xml': set});
             }
-            /**
-             * @typedef {Object} MAMQueryResult
-             * @property {Array} messages
-             * @property {RSM} [rsm] - An instance of {@link RSM}.
-             *  You can call `next()` or `previous()` on this instance,
-             *  to get the RSM query parameters for the next or previous
-             *  page in the result set.
-             * @property {boolean} [complete]
-             * @property {Error} [error]
-             */
             return { messages, rsm, complete };
         }
     }

src/headless/plugins/mam/types.ts

@@ -0,0 +1,42 @@
+import { RSM } from '../../shared/rsm';
+
+export type MAMOptions = {
+    max?: number; // The maximum number of items to return. Defaults to "archived_messages_page_size"
+    after?: string; // The XEP-0359 stanza ID of a message after which messages should be returned. Implies forward paging.
+    before?: string; // The XEP-0359 stanza ID of a message before which messages should be returned. Implies backward paging.
+    end?: string; // A date string in ISO-8601 format, before which messages should be returned. Implies backward paging.
+    start?: string; // A date string in ISO-8601 format, after which messages should be returned. Implies forward paging.
+    with?: string; // The JID of the entity with which messages were exchanged.
+    groupchat?: boolean; // True if archive in groupchat.
+};
+
+// XEP-0059 RSM Attributes that can be used to filter query results
+type RSMQueryParameters = {
+    after?: string; // The XEP-0359 stanza ID of a message after which messages should be returned. Implies forward paging.
+    before?: string; // The XEP-0359 stanza ID of a message before which messages should be returned. Implies backward paging.
+    index?: number; // The index of the results page to return.
+    max?: number; // The maximum number of items to return.
+};
+
+// Filter parmeters which can be used to filter a MAM XEP-0313 archive
+export type MAMFilterParameters = RSMQueryParameters & {
+    end?: string; // A date string in ISO-8601 format, before which messages should be returned. Implies backward paging.
+    start?: string; // A date string in ISO-8601 format, after which messages should be returned. Implies forward paging.
+    with?: string; // A JID against which to match messages, according to either their `to` or `from` attributes.
+    // An item in a MUC archive matches if the publisher of the item matches the JID.
+    // If `with` is omitted, all messages that match the rest of the query will be returned, regardless of to/from
+    // addresses of each message.
+};
+
+// The options that can be passed in to the api.archive.query method
+export type ArchiveQueryOptions = MAMFilterParameters & {
+    groupchat?: boolean; // Whether the MAM archive is for a groupchat.
+};
+
+export type MAMQueryResult = {
+    messages: any[];
+    rsm?: RSM; // You can call `next()` or `previous()` on this,
+    // to get the RSM query parameters for the next or previous page in the result set.
+    complete?: boolean;
+    error?: Error;
+};

src/headless/plugins/mam/utils.js

@@ -138,28 +138,10 @@ export async function handleMAMResult(model, result, query, options, should_page
     }
 }
 
-/**
- * @typedef {Object} MAMOptions
- * A map of MAM related options that may be passed to fetchArchivedMessages
- * @param {number} [options.max] - The maximum number of items to return.
- *  Defaults to "archived_messages_page_size"
- * @param {string} [options.after] - The XEP-0359 stanza ID of a message
- *  after which messages should be returned. Implies forward paging.
- * @param {string} [options.before] - The XEP-0359 stanza ID of a message
- *  before which messages should be returned. Implies backward paging.
- * @param {string} [options.end] - A date string in ISO-8601 format,
- *  before which messages should be returned. Implies backward paging.
- * @param {string} [options.start] - A date string in ISO-8601 format,
- *  after which messages should be returned. Implies forward paging.
- * @param {string} [options.with] - The JID of the entity with
- *  which messages were exchanged.
- * @param {boolean} [options.groupchat] - True if archive in groupchat.
- */
-
 /**
  * Fetch XEP-0313 archived messages based on the passed in criteria.
  * @param {ChatBox|MUC} model
- * @param {MAMOptions} [options]
+ * @param {import('./types').MAMOptions} [options]
  * @param {('forwards'|'backwards'|null)} [should_page=null] - Determines whether
  *  this function should recursively page through the entire result set if a limited
  *  number of results were returned.
@@ -205,7 +187,7 @@ export async function fetchArchivedMessages(model, options = {}, should_page = n
 /**
  * Create a placeholder message which is used to indicate gaps in the history.
  * @param {ChatBox|MUC} model
- * @param {MAMOptions} options
+ * @param {import('./types').MAMOptions} options
  * @param {object} result - The RSM result object
  */
 async function createPlaceholder(model, options, result) {

src/headless/plugins/muc/message.js

@@ -6,7 +6,7 @@ import api from '../../shared/api/index.js';
 
 class MUCMessage extends Message {
     /**
-     * @typedef {import('plugins/vcard/utils.js').MUCOccupant} MUCOccupant
+     * @typedef {import('./occupant').default} MUCOccupant
      */
     async initialize () { // eslint-disable-line require-await
         if (!this.checkValidity()) return;
@@ -85,7 +85,7 @@ class MUCMessage extends Message {
     }
 
     /**
-     * @param {import('plugins/vcard/utils.js').MUCOccupant} [occupant]
+     * @param {MUCOccupant} [occupant]
      * @return {MUCOccupant}
      */
     setOccupant (occupant) {

src/headless/plugins/muc/muc.js

@@ -47,9 +47,9 @@ class MUC extends ModelWithMessages(ColorAwareModel(ChatBoxBase)) {
      * @typedef {import('./message.js').default} MUCMessage
      * @typedef {import('./occupant.js').default} MUCOccupant
      * @typedef {import('./affiliations/utils.js').NonOutcastAffiliation} NonOutcastAffiliation
-     * @typedef {import('./parsers').MemberListItem} MemberListItem
-     * @typedef {import('../chat/types.ts').MessageAttributes} MessageAttributes
-     * @typedef {import('./types.ts').MUCMessageAttributes} MUCMessageAttributes
+     * @typedef {import('./types').MemberListItem} MemberListItem
+     * @typedef {import('../chat/types').MessageAttributes} MessageAttributes
+     * @typedef {import('./types').MUCMessageAttributes} MUCMessageAttributes
      * @typedef {module:shared.converse.UserMessage} UserMessage
      * @typedef {import('strophe.js').Builder} Builder
      * @typedef {import('../../shared/parsers').StanzaParseError} StanzaParseError

src/headless/plugins/muc/occupants.js

@@ -126,10 +126,10 @@ class MUCOccupants extends Collection {
     }
 
     /**
-     * @typedef { Object} OccupantData
-     * @property { String } [jid]
-     * @property { String } [nick]
-     * @property { String } [occupant_id] - The XEP-0421 unique occupant id
+     * @typedef {Object} OccupantData
+     * @property {String} [jid]
+     * @property {String} [nick]
+     * @property {String} [occupant_id] - The XEP-0421 unique occupant id
      */
     /**
      * Try to find an existing occupant based on the provided

src/headless/plugins/muc/parsers.js

@@ -1,7 +1,7 @@
 /**
  * @module:plugin-muc-parsers
  * @typedef {import('../muc/muc.js').default} MUC
- * @typedef {import('./types.ts').MUCMessageAttributes} MUCMessageAttributes
+ * @typedef {import('./types').MUCMessageAttributes} MUCMessageAttributes
  */
 import dayjs from 'dayjs';
 import _converse from '../../shared/_converse.js';
@@ -250,15 +250,8 @@ export async function parseMUCMessage (stanza, chatbox) {
  * Given an IQ stanza with a member list, create an array of objects containing
  * known member data (e.g. jid, nick, role, affiliation).
  *
- * @typedef {Object} MemberListItem
- * Either the JID or the nickname (or both) will be available.
- * @property {string} affiliation
- * @property {string} [role]
- * @property {string} [jid]
- * @property {string} [nick]
- *
  * @param {Element} iq
- * @returns {MemberListItem[]}
+ * @returns {import('./types').MemberListItem[]}
  */
 export function parseMemberListIQ (iq) {
     return sizzle(`query[xmlns="${Strophe.NS.MUC_ADMIN}"] item`, iq).map(
@@ -289,30 +282,11 @@ export function parseMemberListIQ (iq) {
 
 /**
  * Parses a passed in MUC presence stanza and returns an object of attributes.
- * @method parseMUCPresence
  * @param {Element} stanza - The presence stanza
  * @param {MUC} chatbox
- * @returns {MUCPresenceAttributes}
+ * @returns {import('./types').MUCPresenceAttributes}
  */
 export function parseMUCPresence (stanza, chatbox) {
-    /**
-     * Object representing a XEP-0371 Hat
-     * @typedef {Object} MUCHat
-     * @property {string} title
-     * @property {string} uri
-     *
-     * The object which {@link parseMUCPresence} returns
-     * @typedef {Object} MUCPresenceAttributes
-     * @property {string} show
-     * @property {Array<MUCHat>} hats - An array of XEP-0317 hats
-     * @property {Array<string>} states
-     * @property {String} from - The sender JID (${muc_jid}/${nick})
-     * @property {String} nick - The nickname of the sender
-     * @property {String} occupant_id - The XEP-0421 occupant ID
-     * @property {String} type - The type of presence
-     * @property {String} [jid]
-     * @property {boolean} [is_me]
-     */
     const from = stanza.getAttribute('from');
     const type = stanza.getAttribute('type');
     const data = {