lucaswerkmeister/m3api-query

m3api extension package to use the MediaWiki “query” API

m3api-query's Issues

Let `queryFullPages()` and `queryFullRevisions()` sort objects

This idea came up in #3 for queryFullRevisions(), but also makes sense for queryFullPages(), so let’s have a separate issue for it: we should let the caller sort the objects that these functions are about to yield. Since callers can’t know when a new request is about to be made during iteration, this can’t be easily emulated “externally”.

Hide truncatedresult warnings

Part of the purpose of this module is to automatically handle truncated responses, so we should hide this warning if it happens.

Move option parameters into options object

As outlined in #4 and supported by lucaswerkmeister/m3api#21 and related commits.

Account for converted titles

getResponsePageByTitle() currently doesn’t look at converted in the API response (compare MediaWikiPageNameNormalizer::extractPageRecord()).

Add function to get revision by revid from response

As of 6aefcf7, we have two functions in this module: get a page by its title, or by its page ID. The third function to complete the set (by analogy with the parameters titles, pageids, revids) should be one to get a revision by its ID.

However, I’m not sure what the return value of this function should be if the revision doesn’t exist. The API actually returns a specially-formed object for missing revisions, for example:

{
    "batchcomplete": "",
    "query": {
        "badrevids": {
            "12345678901": {
                "revid": 12345678901
            }
        },
        "pages": {
            "1443": {
                "pageid": 1443,
                "ns": 0,
                "title": "Q1094",
                "revisions": [
                    {
                        "revid": 12345,
                        "parentid": 12343,
                        "user": "Soulkeeper",
                        "timestamp": "2012-10-30T21:54:07Z",
                        "comment": "/* wbsetsitelink-set:1|enwiki */ Indium"
                    }
                ]
            }
        }
    }
}

This is not unlike the objects with "missing": true or "invalid": true that can be returned for bad titles or page IDs; however, here the object doesn’t have anything inside to mark it as a bad revision ID, once you take it out of the "badrevids" context. So I’m not sure what the function should return in this case:

• The "badrevids" entry, since it’s part of the response?
  • Maybe with an additional, non-enumerable m3api-specific Symbol key to mark it as a bad revid, so people can look for that if they want to? But that seems fairly opaque.
• null, ignoring this part of the response completely? But that’s inconsistent with the other two functions, which usually return an object, even if its an object for a missing/invalid page.
• Throw a custom exception? But that seems very inconsistent with the other two functions.

Add function to get full revisions

I thought a queryFullRevisions() function, analogous to queryFullPages() (yield all the revisions in a continued response, e.g. from a generator), would make sense:

async function * queryFullRevisions(
    session,
    params,
    options = {},
) {
    params = makeParamsWithString( 'prop', params, 'revisions' );
    options = {
        dropTruncatedResultWarning: true,
        ...options,
    };
    for await ( const response of session.requestAndContinue( params, options ) ) {
        const query = response.query || {};
        let pages = query.pages || [];
        if ( !Array.isArray( pages ) ) {
            pages = Object.values( pages );
        }
        for ( const page of pages ) {
            const revisions = page.revisions || [];
            for ( const revision of revisions ) {
                yield revision;
            }
        }
    }
}

But I just realized that this leaves the caller with no way to know which page the revision belongs to. With the default rvprop, a revision looks like this:

{
    "revid": 1089180047,
    "parentid": 1089175962,
    "minor": false,
    "user": "50.107.154.111",
    "anon": true,
    "timestamp": "2022-05-22T10:10:46Z",
    "comment": "His Interpretation(s)"
}

There’s no indication here of the surrounding page, nor in any of the other available props (which makes sense in the context of a full API response).

This needs some more thinking about what the interface should look like. The session, params, options parameters should probably be the same, and it should return a generator, but I’m not sure what kind of objects the generator should yield.