Skip to content

fix: Invalid slot type and templated parameters #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Derugon wants to merge 3 commits into
base: main
Choose a base branch
from
Open

fix: Invalid slot type and templated parameters #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
388e6c1
Update types
Derugon Jul 1, 2026
7485dc4
feat: Add templated parameters
Derugon Jul 1, 2026
6aa26b3
fix: Slot variables only allowing `main`
Derugon Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 86 additions & 20 deletions index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -719,7 +719,23 @@ export interface ApiComparePagesParams extends ApiParams {
*
* This parameter specifies the slots that are to be modified. Use `fromtext-{slot}`, `fromcontentmodel-{slot}`, and `fromcontentformat-{slot}` to specify content for each slot.
*/
fromslots?: OneOrMore<"main">;
fromslots?: string | string[];
/**
* Text of the specified slot. If omitted, the slot is removed from the revision.
*/
[k: `fromtext-${string}`]: string;
/**
* When `fromtext-{slot}` is the content of a single section, this is the section identifier. It will be merged into the revision specified by `fromtitle`, `fromid` or `fromrev` as if for a section edit.
*/
[k: `fromsection-${string}`]: string;
/**
* Content serialization format of `fromtext-{slot}`.
*/
[k: `fromcontentformat-${string}`]: string;
/**
* Content model of `fromtext-{slot}`. If not supplied, it will be guessed based on the other parameters.
*/
[k: `fromcontentmodel-${string}`]: string;
/**
* Do a pre-save transform on `fromtext-{slot}`.
*/
Expand Down Expand Up @@ -769,7 +785,23 @@ export interface ApiComparePagesParams extends ApiParams {
*
* This parameter specifies the slots that are to be modified. Use `totext-{slot}`, `tocontentmodel-{slot}`, and `tocontentformat-{slot}` to specify content for each slot.
*/
toslots?: OneOrMore<"main">;
toslots?: string | string[];
/**
* Text of the specified slot. If omitted, the slot is removed from the revision.
*/
[k: `totext-${string}`]: string;
/**
* When `totext-{slot}` is the content of a single section, this is the section identifier. It will be merged into the revision specified by `totitle`, `toid` or `torev` as if for a section edit.
*/
[k: `tosection-${string}`]: string;
/**
* Content serialization format of `totext-{slot}`.
*/
[k: `tocontentformat-${string}`]: string;
/**
* Content model of `totext-{slot}`. If not supplied, it will be guessed based on the other parameters.
*/
[k: `tocontentmodel-${string}`]: string;
/**
* Do a pre-save transform on `totext`.
*/
Expand Down Expand Up @@ -1313,12 +1345,6 @@ export interface DiscussionToolsApiDiscussionToolsEditParams extends ApiParams {
* - **addtopic**: Add a new discussion section and the first comment in it.
*/
paction?: "addcomment" | "addtopic";
/**
* Automatically subscribe the user to the talk page thread?
*
* Defaults to `default`.
*/
autosubscribe?: "default" | "no" | "yes";
/**
* The page to perform actions on.
*/
Expand Down Expand Up @@ -3703,7 +3729,7 @@ export interface PageTriageApiPageTriageStatsParams extends ApiParams {
*/
show_predicted_issues_copyvio?: boolean;
/**
* Whether to include only pages created by bots.
* Whether to include only pages created by bots.
*/
showbots?: boolean;
/**
Expand Down Expand Up @@ -3739,31 +3765,31 @@ export interface PageTriageApiPageTriageStatsParams extends ApiParams {
*/
afc_state?: number;
/**
* Whether to include only pages with no category.
* Whether to include only pages with no category.
*/
no_category?: boolean;
/**
* Whether to include only pages with no references.
* Whether to include only pages with no references.
*/
unreferenced?: boolean;
/**
* Whether to include only pages with no inbound links.
* Whether to include only pages with no inbound links.
*/
no_inbound_links?: boolean;
/**
* Whether to include only pages that were previously deleted.
* Whether to include only pages that were previously deleted.
*/
recreated?: boolean;
/**
* Whether to include only pages created by non-autoconfirmed users.
* Whether to include only pages created by non-autoconfirmed users.
*/
non_autoconfirmed_users?: boolean;
/**
* Whether to include only pages created by newly autoconfirmed users.
* Whether to include only pages created by newly autoconfirmed users.
*/
learners?: boolean;
/**
* Whether to include only pages created by blocked users.
* Whether to include only pages created by blocked users.
*/
blocked_users?: boolean;
/**
Expand Down Expand Up @@ -4091,6 +4117,7 @@ export interface ApiParseParams extends ApiParams {
* - **properties**: Gives various properties defined in the parsed wikitext.
* - **limitreportdata**: Gives the limit report in a structured way. Gives no data, when `disablelimitreport` is set.
* - **limitreporthtml**: Gives the HTML version of the limit report. Gives no data, when `disablelimitreport` is set.
* - **parseroutput**: Internal. Gives the JSON-serialized `ParserOutput` object for the parsed content. The format of this property may change at any time; {@link https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility mw:Manual:Parser cache/Serialization compatibility} does not provide any guarantee of API stability.
* - **parsetree**: The XML parse tree of revision content (requires content model `wikitext`)
* - **parsewarnings**: Gives the warnings that occurred while parsing content (as wikitext).
* - **parsewarningshtml**: Gives the warnings that occurred while parsing content (as HTML).
Expand All @@ -4114,6 +4141,7 @@ export interface ApiParseParams extends ApiParams {
| "limitreporthtml"
| "links"
| "modules"
| "parseroutput"
| "parsetree"
| "parsewarnings"
| "parsewarningshtml"
Expand Down Expand Up @@ -6562,6 +6590,18 @@ export interface VisualEditorApiVisualEditorEditParams extends ApiParams {
* - **ge-task-revise-tone**: Use when saving a GrowthExperiments "{@link https://www.mediawiki.org/wiki/Growth/Revise_Tone Revise Tone}" structured edit.
*/
plugins?: string | string[];
/**
* Arbitrary data sent by a plugin with the API request.
*
* - **For the `ge-task-link-recommendation` plugin**: A JSON string of an object with these keys:
*
* - `acceptedTargets`: (optional) Array with the titles of pages, the recommended link to which was accepted by the user.
* - `rejectedTargets`: (optional) Array with the titles of pages, the recommended link to which was rejected by the user.
* - `skippedTargets`: (optional) Array with the titles of pages, the recommended link to which was skipped (ignored) by the user.
*
* - **For the `ge-task-revise-tone` plugin**: No data should be included for this plugin.
*/
[k: `data-${string}`]: string;
/**
* Whether the shown hCaptcha CAPTCHA was force shown, such as by an AbuseFilter extension consequence (and so used a more restrictive sitekey). Set this if the JS configuration variable with the same name is true or if the first attempt to use this API returned a 'forcecaptcha' error with a specified sitekey.
*/
Expand Down Expand Up @@ -7086,7 +7126,11 @@ export interface ApiQueryAllDeletedRevisionsParams extends ApiQueryParams {
/**
* Which revision slots to return data for, when slot-related properties are included in `adrprops`. If omitted, data from the `main` slot will be returned in a backwards-compatible format.
*/
adrslots?: OneOrMore<"main">;
adrslots?: string | string[];
/**
* Content serialization format used for output of content.
*/
[k: `adrcontentformat-${string}`]: string;
/**
* Limit how many revisions will be returned. If `adrprop=content`, `adrprop=parsetree`, `adrdiffto` or `adrdifftotext` is used, the limit is 50. If `adrparse` is used, the limit is 1.
*/
Expand Down Expand Up @@ -7298,6 +7342,7 @@ export interface ApiQueryAllImagesParams extends ApiQueryParams {
* - **dimensions**: Alias for size.
* - **sha1**: Adds SHA-1 hash for the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **mime**: Adds MIME type of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **thumburls**: Adds thumbnail URLs of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **mediatype**: Adds the media type of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **metadata**: Lists Exif metadata for the version of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **commonmetadata**: Lists file format generic metadata for the version of the file. If the file has been revision deleted, a `filehidden` property will be returned.
Expand All @@ -7323,6 +7368,7 @@ export interface ApiQueryAllImagesParams extends ApiQueryParams {
| "parsedcomment"
| "sha1"
| "size"
| "thumburls"
| "timestamp"
| "url"
| "user"
Expand Down Expand Up @@ -7690,7 +7736,11 @@ export interface ApiQueryAllRevisionsParams extends ApiQueryParams {
/**
* Which revision slots to return data for, when slot-related properties are included in `arvprops`. If omitted, data from the `main` slot will be returned in a backwards-compatible format.
*/
arvslots?: OneOrMore<"main">;
arvslots?: string | string[];
/**
* Content serialization format used for output of content.
*/
[k: `arvcontentformat-${string}`]: string;
/**
* Limit how many revisions will be returned. If `arvprop=content`, `arvprop=parsetree`, `arvdiffto` or `arvdifftotext` is used, the limit is 50. If `arvparse` is used, the limit is 1.
*/
Expand Down Expand Up @@ -8804,7 +8854,11 @@ export interface ApiQueryDeletedRevisionsParams extends ApiQueryParams {
/**
* Which revision slots to return data for, when slot-related properties are included in `drvprops`. If omitted, data from the `main` slot will be returned in a backwards-compatible format.
*/
drvslots?: OneOrMore<"main">;
drvslots?: string | string[];
/**
* Content serialization format used for output of content.
*/
[k: `drvcontentformat-${string}`]: string;
/**
* Limit how many revisions will be returned. If `drvprop=content`, `drvprop=parsetree`, `drvdiffto` or `drvdifftotext` is used, the limit is 50. If `drvparse` is used, the limit is 1.
*/
Expand Down Expand Up @@ -10097,6 +10151,7 @@ export interface ApiQueryImageInfoParams extends ApiQueryParams {
* - **sha1**: Adds SHA-1 hash for the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **mime**: Adds MIME type of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **thumbmime**: Adds MIME type of the image thumbnail (requires url and param iiurlwidth). If the file has been revision deleted, a `filehidden` property will be returned.
* - **thumburls**: Adds thumbnail URLs of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **mediatype**: Adds the media type of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **metadata**: Lists Exif metadata for the version of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **commonmetadata**: Lists file format generic metadata for the version of the file. If the file has been revision deleted, a `filehidden` property will be returned.
Expand Down Expand Up @@ -10126,6 +10181,7 @@ export interface ApiQueryImageInfoParams extends ApiQueryParams {
| "sha1"
| "size"
| "thumbmime"
| "thumburls"
| "timestamp"
| "uploadwarning"
| "url"
Expand Down Expand Up @@ -12049,7 +12105,11 @@ export interface ApiQueryRevisionsParams extends ApiQueryParams {
/**
* Which revision slots to return data for, when slot-related properties are included in `rvprops`. If omitted, data from the `main` slot will be returned in a backwards-compatible format.
*/
rvslots?: OneOrMore<"main">;
rvslots?: string | string[];
/**
* Content serialization format used for output of content.
*/
[k: `rvcontentformat-${string}`]: string;
/**
* Limit how many revisions will be returned. If `rvprop=content`, `rvprop=parsetree`, `rvdiffto` or `rvdifftotext` is used, the limit is 50. If `rvparse` is used, the limit is 1.
*/
Expand Down Expand Up @@ -12331,6 +12391,7 @@ export interface ApiQuerySiteinfoParams extends ApiQueryParams {
* - **autopromote**: Returns the automatic promotion configuration.
* - **autopromoteonce**: Returns the automatic promotion configuration that are only done once.
* - **copyuploaddomains**: Returns the list of allowed copy upload domains
* - **crosssiteajaxdomains**: Returns the list of allowed CORS domains
* - **sbom**: Returns a Software Bill of Materials (SBOM) for the MediaWiki installation in the CycloneDX 1.6 format.
*
* Defaults to `general`.
Expand All @@ -12341,6 +12402,7 @@ export interface ApiQuerySiteinfoParams extends ApiQueryParams {
| "autopromoteonce"
| "clientlibraries"
| "copyuploaddomains"
| "crosssiteajaxdomains"
| "dbrepllag"
| "defaultoptions"
| "doubleunderscores"
Expand Down Expand Up @@ -12438,6 +12500,7 @@ export interface ApiQueryStashImageInfoParams extends ApiQueryParams {
* - **sha1**: Adds SHA-1 hash for the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **mime**: Adds MIME type of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **thumbmime**: Adds MIME type of the image thumbnail (requires url and param siiurlwidth). If the file has been revision deleted, a `filehidden` property will be returned.
* - **thumburls**: Adds thumbnail URLs of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **metadata**: Lists Exif metadata for the version of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **commonmetadata**: Lists file format generic metadata for the version of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **extmetadata**: Lists formatted metadata combined from multiple sources. Results are HTML formatted. If the file has been revision deleted, a `filehidden` property will be returned.
Expand All @@ -12460,6 +12523,7 @@ export interface ApiQueryStashImageInfoParams extends ApiQueryParams {
| "sha1"
| "size"
| "thumbmime"
| "thumburls"
| "timestamp"
| "url"
>;
Expand Down Expand Up @@ -12925,6 +12989,7 @@ export interface TimedMediaHandlerApiQueryVideoInfoParams extends ApiQueryParams
* - **sha1**: Adds SHA-1 hash for the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **mime**: Adds MIME type of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **thumbmime**: Adds MIME type of the image thumbnail (requires url and param viurlwidth). If the file has been revision deleted, a `filehidden` property will be returned.
* - **thumburls**: Adds thumbnail URLs of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **mediatype**: Adds the media type of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **metadata**: Lists Exif metadata for the version of the file. If the file has been revision deleted, a `filehidden` property will be returned.
* - **commonmetadata**: Lists file format generic metadata for the version of the file. If the file has been revision deleted, a `filehidden` property will be returned.
Expand Down Expand Up @@ -12957,6 +13022,7 @@ export interface TimedMediaHandlerApiQueryVideoInfoParams extends ApiQueryParams
| "sha1"
| "size"
| "thumbmime"
| "thumburls"
| "timedtext"
| "timestamp"
| "uploadwarning"
Expand Down
72 changes: 64 additions & 8 deletions scripts/api-types-generator.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,14 +175,36 @@ const literalToJSdoc = (lit, multi) => {
}
};

function processParamInfo(prefix, param) {
/**
* Replace template variables in a module parameter name.
*
* @param {string} name Parameter name.
* @param {string[]} templateVars Template variables that *may* appear in the name.
*/
function replaceTemplateVars(name, templateVars) {
const varPattern = new RegExp(`\\{(${templateVars.join("|")})\\}`, "g");
return name.replaceAll(varPattern, "${string}");
}

/**
* Format an API module parameter as a TS property.
*
* @param {string} prefix Prefix to prepend to all parameter names.
* @param {any} param API module parameter data.
* @param {Set<string>} allTemplateVars Template variables used by parameters from this module.
*/
function processParamInfo(prefix, param, allTemplateVars) {
let type = param.type;

// Convert the API type to a TypeScript type
// Avoid being over-specific
// Convert the API type to a TS type
if (Array.isArray(type)) {
const enumSet = new Set(type);
if (GENERALIZE_ENUM_TYPE_CONTAINING.some((s) => s.isSubsetOf(enumSet))) {
if (
// is its value used as a template variable for another parameter?
allTemplateVars.has(param.name) ||
// is it extensible?
GENERALIZE_ENUM_TYPE_CONTAINING.some((s) => s.isSubsetOf(enumSet))
) {
type = "string";
}
} else if (type === "text" || type === "title" || type === "user" || type === "raw") {
Expand All @@ -203,7 +225,12 @@ function processParamInfo(prefix, param) {
}

let name = prefix + param.name;
if (name.includes("-")) {
let isOptional = true;
if (param.templatevars !== undefined) {
name = replaceTemplateVars(name, Object.keys(param.templatevars));
name = `[k: \`${name}\`]`;
isOptional = false;
} else if (name.includes("-")) {
name = `"${name}"`;
}

Expand All @@ -220,7 +247,7 @@ function processParamInfo(prefix, param) {
jsdoc.deprecated = true;
}

return `${jsdoc.toString()}\n${name}?: ${type};`;
return `${jsdoc.toString()}\n${name}${isOptional ? "?:" : ":"} ${type};`;
}

function getInterfaceName(module) {
Expand All @@ -230,6 +257,29 @@ function getInterfaceName(module) {
.replace(/ApiApi/g, "Api");
}

/**
* Merge 2 parameter arrays into a new array, ordered by index.
*
* @param {any[]} params1 1st parameter array, ordered by index.
* @param {any[]} params2 2nd parameter array, ordered by index.
*/
function mergeParameterArrays(params1, params2) {
const params = [];
let i1 = 0,
i2 = 0;
while (i1 < params1.length && i2 < params2.length) {
params.push(params1[i1].index < params2[i2].index ? params1[i1++] : params2[i2++]);
}
params.push(...params1.slice(i1), ...params2.slice(i2));
return params;
}

/**
* Format an API module as a TS interface.
*
* @param {string} parent Parent interface name.
* @param {any} module API module data.
*/
function processModuleInfo(parent, module) {
const jsdoc = new JSdoc();
jsdoc.description = htmlToJSdoc(module.description);
Expand All @@ -240,11 +290,17 @@ function processModuleInfo(parent, module) {
if (module.deprecated) {
jsdoc.deprecated = true;
}

const parameters = mergeParameterArrays(module.parameters, module.templatedparameters);
const allTemplateVars = new Set(
module.templatedparameters.flatMap((p) => Object.values(p.templatevars)),
);

return [
jsdoc.toString(),
`export interface ${getInterfaceName(module)}Params extends ${parent}Params {`,
...module.parameters.map((param) =>
processParamInfo(module.prefix, param).replace(/^/gm, "\t"),
...parameters.map((param) =>
processParamInfo(module.prefix, param, allTemplateVars).replace(/^/gm, "\t"),
),
"}",
].join("\n");
Expand Down
Loading