Class: NSRequest

nationscript/requests/base~NSRequest()

The mother of superclasses, inherited by all specialised request classes.

Holds static properties configurable by the user to en/disable the built-in rate-limiter of NationScript and, most importantly, set the user agent for identifying the user to NS admins.

The raw function is invoked by every single execution of a request subclass, returning the API's raw response in the form of an IncomingMessage.

The send function calls the raw function, and then parses the body using the node-xml-stream-parser package, sending emitted events to the NSFactory created by the set factoryConfigurer.

Constructor

new NSRequest()

Members

(protected) body :Object.<string, string>

Data registered to be sent as this request's body. If it is empty upon request execution, the request will be sent as a GET request, without a request body. Subclasses offer methods for altering this data.

Type:
  • Object.<string, string>

(package, nullable) useragent :string

The text that sent as the User-Agent header in requests to the NS API.

Type:
  • string

(package) useRateLimit :boolean

Whether to use the in-built rate-limiter for requests to the NS API.

Type:
  • boolean
Default Value:
  • true

Methods

getData() → {string}

Formats the body into a query string, as required by the NationStates API for the request body.

Returns:

A string of the format key1=value1&key2=value2&...

Type
string

(async, protected) getStream() → {Promise.<Stream>}

Gets the data stream containing the XML to parse within the send function.

Note: This "middleman" function between the send and raw functions is needed so the DumpRequest can cleanly override the getting of the XML stream. Since it can either use a ReadStream or an IncomingMessage, depending on the DumpMode, but the former is missing properties of the latter, the type-checker will complain if raw is overridden with the possibility of returning a ReadStream.

Returns:

Stream with the XML data

Type
Promise.<Stream>

(async) raw() → {Promise.<http.IncomingMessage>}

Checks whether the useragent is set, then calls the executeHTTP function and returns its response. If useRateLimit is true, the request is ensured to respect the API's rate-limit.

Returns:

The raw response to the request

Type
Promise.<http.IncomingMessage>

removeHeader(name) → {this}

Removes any prepared header with the given name.

Parameters:
Name Type Description
name string

Header name
Returns:

The request, for chaining

Type
this

(async) send() → {Promise.<?any>}

Calls the raw function and passes the returned response stream through the node-xml-stream-parser. The emitted events are in turn handled by a factory created using the defined factoryConfigurer, or, if none is set, the factory determined by the matchFactory function.

Returns:

The chosen factory's finished product

Type
Promise.<?any>

setHeader(name, value) → {this}

Registers the given value to be sent under the given header name when this request is executed.

Parameters:
Name Type Description
name string

Header name
value string

Header value
Returns:

The request, for chaining

Type
this

(protected) setTargetURL(url) → {this}

Configures this request to be sent to the given URL.

Parameters:
Name Type Description
url string

URL to target
Returns:

The request, for chaining

Type
this

(protected) useFactory(factory) → {this}

Configures this request use the given function for creating the root factory during XML parsing.

Parameters:
Name Type Description
factory factory.FactoryConstructor.<any>

Creation function to use
Returns:

The request, for chaining

Type
this