Members
(constant) DEFAULT_OPTIONS :Options
Default options for requests across all sessions.
Packages extending m3api’s capabilities (“extension packages”) may add their own options here, conventionally prefixed with the package name and a slash. For example, a package named 'abc' may add options 'abc/x' and 'abc/y', while a package named '@abc/def' may add '@abc/def/x' and '@abc/def/y'. Extension packages are encouraged to use a single options object for their own options as well as ones that are passed through to m3api, rather than e.g. separate options or individual parameters; both kinds of options can then have per-session and global defaults.
Changing or removing any default options here is strongly discouraged, and may result in unpredictable behavior.
Type:
Methods
makeWarnDroppingTruncatedResultWarning(warn) → {function}
Decorate the given warn handler so that warnings about truncated results are dropped.
Most of the time, you should use the dropTruncatedResultWarning request option instead of using this function directly.
Parameters:
| Name | Type | Description |
|---|---|---|
warn |
function | The original warn function. |
Returns:
A new function that, when called, will call the original warn functions, but with all truncated result warnings dropped; when there are no other warnings, the original function is not called.
- Type
- function
responseBoolean(value) → {boolean}
Convenience function to get a boolean from an API response value.
Works for formatversion=1 booleans (absent means false, empty string means true) as well as formatversion=2 booleans (absent or false means false, true means true). Mostly useful in library code, when you don’t know the formatversion of the response. (If you control the request parameters, just use formatversion=2.)
Parameters:
| Name | Type | Description |
|---|---|---|
value |
boolean | '' | undefined | A value from an API response (e.g. response.query.general.rtl). |
Returns:
- Type
- boolean
set(…elements) → {Set}
Convenience function to create a Set.
The two invocations
new Set( [ 'a', 'b' ] )
set( 'a', 'b' )
are equivalent, but the second one is shorter and easier to type.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
elements |
* |
<repeatable> |
Returns:
- Type
- Set
Type Definitions
ErrorHandler(session, params, options, internalResponse, error) → {Object|null|Promise.<(Object|null)>}
An error handler callback, which can be registered in the errorHandlers option.
The callback is called if an API request results in an error and the callback has been registered for that error code. It may retry the request or perform any other action.
Parameters:
| Name | Type | Description |
|---|---|---|
session |
Session | The session to which the request belongs. |
params |
Params | The request parameters. |
options |
Options | The request options. The retryUntil option is always set here, and the error handler should not retry the request if this timestamp has already passed. |
internalResponse |
InternalResponse | The full response sent by the server. |
error |
Object | The specific error returned to the API that matched this handler. |
Returns:
A synchronous or asynchronous result. If the handler returns an object (or a promise resolving to an object), that object is used as the result of the API request; this can be used to retry the request (the handler makes another request to the session with the same params and options, and returns its result). If the handler returns null (or a promise resolving to null), the error could not be handled; m3api will call error handlers for the remaining errors (if any) and eventually throw ApiErrors if none of them returned an object either.
- Type
- Object | null | Promise.<(Object|null)>
InternalResponse
The internal representation of a full server response, returned by Session#internalGet and Session#internalPost.
Type:
- Object
Properties:
| Name | Type | Description |
|---|---|---|
status |
number | The HTTP status code (e.g. 200 OK). |
headers |
Object | The response headers. Header names must be all-lowercase. (Set-Cookie is not expected to be included.) |
body |
Object | JSON-decoded response body. |
ListParam
A request parameter value that is a list of values (several titles, namespace numbers, etc.), which may potentially be combined with other lists in a single request (if specified as a set) or not (if specified as an array).
Type:
- Array.<ListableParam> | Set.<ListableParam>
ListableParam
A request parameter value that can potentially be put in a list: a title, user name, namespace number, etc.
Type:
- string | number
Options
Request options for Session#request and related methods. The actual effective options are merged from the builtin DEFAULT_OPTIONS, the default options passed into the Session constructor, and the options given with a particular request call.
Type:
- Object
Properties:
| Name | Type | Attributes | Description |
|---|---|---|---|
method |
string |
<optional> |
The method, either GET (default) or POST. |
tokenType |
string | null |
<optional> |
Include a token parameter of this type, automatically getting it from the API if necessary. The most common token type is 'csrf' (some actions use a different type); you will also want to set the method option to POST. |
tokenName |
string |
<optional> |
The name of the token parameter. Only used if the tokenType option is not null. Defaults to 'token', but some modules need a different name (e.g. action=login needs 'lgtoken'). |
userAgent |
string |
<optional> |
The User-Agent header to send. (Usually specified as a default option in the constructor.) |
maxRetriesSeconds |
number |
<optional> |
The maximum duration for automatic retries, i.e. a time interval (in seconds) during which the request will be automatically repeated according to the Retry-After response header if it is present. Defaults to 65 seconds; set to 0 to disable automatic retries. (Can also be a fractional number for sub-second precision.) |
retryAfterMaxlagSeconds |
number |
<optional> |
Default Retry-After header value in case of a maxlag error. Only used when the response is missing the header. Since MediaWiki usually sends this header for maxlag errors, this option is rarely used. Defaults to five seconds, which is the recommended maxlag value for bots. |
retryAfterReadonlySeconds |
number |
<optional> |
Default Retry-After header value in case of a readonly error. Only used when the response is missing the header. MediaWiki does not usually send this header for readonly errors, so this option is more important than the retryAfterMaxlagSeconds option. The default of 30 seconds is thought to be appropriate for Wikimedia wikis; for third-party wikis, higher values may be useful (remember to also increase the maxRetriesSeconds option accordingly). |
warn |
function |
<optional> |
A handler for warnings from this API request. Called with a single instance of a subclass of Error, such as ApiWarnings. The default is console.warn (interactive CLI applications may wish to change this). |
dropTruncatedResultWarning |
boolean |
<optional> |
Whether to drop warnings about truncated results instead of passing them to the warn handler. Occasionally, an API result may not fit into a single network response; in such cases, the API will add a warning about the result being truncated, as well as continuation parameters that will result in the remaining information being included in the next request, if continuation is followed. If you follow continuation and are prepared to merge truncated responses back together, you don’t need to see this warning and can use this option to suppress it. This option defaults to false in Session#request (i.e. treat the warning like any other), but to true in Session#requestAndContinueReducingBatch. |
authorization |
string |
<optional> |
Value for the Authorization request header.
This option can be used to authenticate requests using OAuth 2.0.
For an owner-only client / consumer, where you have an access token,
you can set this option to |
errorHandlers |
Object.<string, ErrorHandler> |
<optional> |
Internal option. Define handlers for API errors, which can retry the request if appropriate. This option is only part of the internal interface, not of the stable, public interface. |
retryUntil |
number |
<optional> |
Internal option. Retry until the given timestamp (in terms of the performance.now() clock). Takes precedence over the maxRetriesSeconds option. This option is only part of the internal interface, not of the stable, public interface. |
Param
A request parameter value of any kind.
Type:
Params
Request parameters for Session#request and related methods. Each parameter may be a string, number, boolean, null, or undefined, or an array or set of strings or numbers. Parameters with values false, null, or undefined are completely removed when the request is sent out. In POST requests, a parameter may also be a Blob or File.
Type:
- Object.<string, Param>
SingleParam
A single request parameter value.
Type:
UnlistableParam
A request parameter value that cannot be put in a list: a boolean toggle, a Blob or File (POST requests only), or null or undefined as a default fallback for not sending a parameter at all.
Type:
- boolean | Blob | File | null | undefined