@randomorg/core
Version:
The official library to access the RANDOM.ORG JSON-RPC API
1,031 lines (956 loc) • 405 kB
JavaScript
var RandomOrgCore = (function (exports) {
'use strict';
function getDefaultExportFromCjs (x) {
return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
}
var RandomOrgErrors = {};
/**
* Error thrown by the RandomOrgClient class when the connection doesn't return
* a HTTP 200 OK response.
*/
RandomOrgErrors.RandomOrgBadHTTPResponseError = class RandomOrgBadHTTPResponseError extends Error
{
/**
* Constructs a new exception with the specified detail message.
* @param {string} message The detail message.
*/
constructor(message) {
super(message);
}
};
/**
* Error thrown by the RandomOrgClient class when its API key's request has
* exceeded its remaining server bits allowance.
*
* If the client is currently issuing large requests it may be possible succeed
* with smaller requests. Use the getBitsLeft() call in this class to help
* determine if an alternative request size is appropriate.
*/
RandomOrgErrors.RandomOrgInsufficientBitsError = class RandomOrgInsufficientBitsError extends Error
{
// Stores the number of bits remaining
#bits = -1;
/**
* Constructs a new exception with the specified detail message.
* @constructor
* @param {string} message The detail message.
* @param {number} bits Bits remaining just before the error was thrown.
*/
constructor(message, bits) {
super(message);
this.#bits = bits;
}
/**
* Gets the number of bits remaining.
* @returns {number} The number of bits left.
*/
getBitsLeft() {
return this.#bits;
}
};
/**
* Error thrown by the RandomOrgClient class when its API key's server requests
* allowance has been exceeded.
*
* This indicates that a back-off until midnight UTC is in effect, before which
* no requests will be sent by the client as no meaningful server responses will
* be returned.
*/
RandomOrgErrors.RandomOrgInsufficientRequestsError = class RandomOrgInsufficientRequestsError extends Error
{
/**
* Constructs a new exception with the specified detail message.
* @constructor
* @param {string} message The detail message.
*/
constructor(message) {
super(message);
}
};
/**
* Error thrown by the RandomOrgClient class when the server returns a JSON-RPC
* Error. See https://api.random.org/json-rpc/4/error-codes
*/
RandomOrgErrors.RandomOrgJSONRPCError = class RandomOrgJSONRPCError extends Error
{
/**
* Constructs a new exception with the specified detail message.
* @constructor
* @param {string} message The detail message.
*/
constructor(message) {
super(message);
}
};
/**
* Error thrown by the RandomOrgClient class when its API key has been stopped.
* Requests will not complete while API key is in the stopped state.
*/
RandomOrgErrors.RandomOrgKeyNotRunningError = class RandomOrgKeyNotRunningError extends Error
{
/**
* Error thrown by the RandomOrgClient class when its API key has been stopped.
* Requests will not complete while API key is in the stopped state.
* @constructor
* @param {string} message The detail message.
*/
constructor(message) {
super(message);
}
};
/**
* Error thrown by the RandomOrgClient class when the server returns a
* RANDOM.ORG Error. See https://api.random.org/json-rpc/4/error-codes
*/
RandomOrgErrors.RandomOrgRANDOMORGError = class RandomOrgRANDOMORGError extends Error
{
// Stores the code of the RANDOM.ORG error
#code = -1;
/**
* Error thrown by the RandomOrgClient class when the server returns a
* RANDOM.ORG Error. See https://api.random.org/json-rpc/4/error-codes
* @constructor
* @param {string} message The detail message.
* @param {number=} [code=-1] The error code.
*/
constructor(message, code = -1) {
super(message);
this.#code = code;
}
/**
* Gets the RANDOM.ORG error code, see
* https://api.random.org/json-rpc/4/error-codes
* @returns {number} The error code.
*/
getCode() {
return this.#code;
}
};
/**
* Error thrown by the RandomOrgClient class when its set blocking timeout is
* exceeded before the request can be sent.
*/
RandomOrgErrors.RandomOrgSendTimeoutError = class RandomOrgSendTimeoutError extends Error
{
/**
* Error thrown by the RandomOrgClient class when its set blocking timeout is
* exceeded before the request can be sent.
* @constructor
* @param {string} message The detail message.
*/
constructor(message) {
super(message);
}
};
/**
* Error thrown when data retrieval from an emtpy RandomOrgCache is attempted.
*/
RandomOrgErrors.RandomOrgCacheEmptyError = class RandomOrgCacheEmptyError extends Error
{
#paused = false;
/**
* Error thrown when data retrieval from an emtpy RandomOrgCache is attempted.
* @constructor
* @param {string} message The detail message.
* @param {boolean} paused Reflects whether the RandomOrgCache instance was
* paused when this error was thrown.
*/
constructor(message, paused = false) {
super(message);
this.#paused = paused;
}
/**
* Returns whether the cache was paused at the time when the
* error was thrown.
* @returns {boolean} True if paused, false otherwise.
*/
wasPaused() {
return this.#paused;
}
};
const {
RandomOrgInsufficientBitsError: RandomOrgInsufficientBitsError$2,
RandomOrgCacheEmptyError: RandomOrgCacheEmptyError$1
} = RandomOrgErrors;
/**
* Precache class for frequently used requests.
*/
var RandomOrgCache_1 = class RandomOrgCache {
// function used to send a request
#requestFunction = null;
// request to be sent
#request = null;
// n for bulk requests
#bulkRequestNumber = 0;
// n for a single request
#requestNumber = 0;
// size of a single request in bits
#requestSize = -1;
// stores cached arrays of values
#stack = [];
// number of arrays to try to maintain in #stack
#cacheSize = 10;
// status of the cache
#paused = false;
// bits used by this cache
#bitsUsed = 0;
// requests used by this cache
#requestsUsed = 0;
// ensures #populate() does not issue parallel requests
#currentlyPopulating = false;
// an error which will be thrown on the next call to get() or getOrWait()
#error = null;
/**
* Initialize class and start stack population
*
* ** WARNING** Should only be called by RandomOrgClient's createCache()
* methods.
* @param {function(Object) : Object} requestFunction Function used to send
* supplied request to server.
* @param {Object} request Request to send to server via requestFunction.
* @param {number} cacheSize Number of request responses to try maintain.
* @param {number} bulkRequestNumber If request is set to be issued in bulk,
* number of result sets in a bulk request, else 0.
* @param {number} requestNumber If request is set to be issued in bulk,
* number of results in a single request, else 0.
* @param {number} singleRequestSize Size of a single request in bits for
* adjusting bulk requests if bits are in short supply on the server.
*/
constructor(requestFunction, request, cacheSize, bulkRequestNumber, requestNumber, singleRequestSize) {
this.#requestFunction = requestFunction;
this.#request = request;
this.#cacheSize = cacheSize;
this.#bulkRequestNumber = bulkRequestNumber;
this.#requestNumber = requestNumber;
this.#requestSize = singleRequestSize;
this.#populate();
}
/**
* Function to continue issuing requests until the stack is full.
*
* Keep issuing requests to server until stack is full. When stack is full
* if requests are being issued in bulk, wait until stack has enough space
* to accommodate all of a bulk request before issuing a new request, otherwise
* issue a new request every time an item in the stack has been consumed. Note
* that requests are blocking ('await' is used when calling the requestFunction),
* i.e., only one request will be issued by the cache at any given time.
*/
#populate = async () => {
if (!this.#currentlyPopulating && !this.#paused) {
this.#currentlyPopulating = true;
let response = null;
while (true) {
if (this.#error != null) {
break;
}
if (this.#bulkRequestNumber > 0) {
// Is there space for a bulk response in the stack?
if (this.#stack.length <= (this.#cacheSize - this.#bulkRequestNumber)) {
try {
response = await this.#requestFunction(this.#request);
this.#addResponse(response, true);
} catch (e) {
// not enough bits remaining for a bulk request
if (e instanceof RandomOrgInsufficientBitsError$2) {
let bitsLeft = e.getBitsLeft();
if (bitsLeft > this.#requestSize) {
// if possible, adjust request for the largest possible size
let adjustedBulk = Math.floor(bitsLeft/this.#requestSize);
this.#request.params.n = adjustedBulk * this.#requestNumber;
response = await this.#requestFunction(this.#request);
this.#addResponse(response, true);
// reset to original bulk request size
this.#request.params.n = this.#bulkRequestNumber * this.#requestNumber;
} else {
// request size cannot be adjusted
this.#error = e;
}
} else {
// Any other error thrown during in the request function
this.#error = e;
}
}
} else {
// no space for a bulk request
break;
}
} else if (this.#stack.length < this.#cacheSize) {
// individual requests
try {
response = await this.#requestFunction(this.#request);
this.#addResponse(response, false);
} catch(e) {
this.#error = e;
}
} else {
// the stack is full
break;
}
}
this.#currentlyPopulating = false;
}
}
/**
* The cache will no longer continue to populate itself.
*/
stop() {
this.#paused = true;
}
/**
* The cache will resume populating itself if stopped.
*/
resume() {
this.#paused = false;
// check if it needs to be repopulated
this.#refresh();
}
/**
* Checks if the cache is currently not re-populating itself.
*
* Values currently cached may still be retrieved with get() but no new
* values are being fetched from the server. This state can be changed with
* stop() and resume().
* @returns {boolean} True if cache is currently not re-populating itself,
* false otherwise.
*/
isPaused() {
return this.#paused;
}
/**
* Gets the next response.
* Note that if the cache is empty, if was constructed with unsuitable parameter
* values or if the daily allowance of bits/requests has been reached, the appropriate
* error will be thrown.
* @returns {any[]} The next appropriate response for the request this RandomOrgCache
* represents or, if stack is empty throws an error.
* @throws RandomOrgCacheEmptyError if the cache is empty.
*/
get() {
if (this.#error != null) {
throw this.#error;
}
if (this.#stack && this.#stack.length == 0) {
if (this.#paused) {
throw new RandomOrgCacheEmptyError$1('The RandomOrgCache stack '
+ 'is empty and the cache is paused. Please call resume() to '
+ 'restart populating the cache.', true);
} else {
throw new RandomOrgCacheEmptyError$1('The RandomOrgCache stack '
+ 'is empty, please wait for it to repopulate itself.');
}
} else {
let data = this.#stack.pop();
// check if it needs to be repopulated
this.#refresh();
return data;
}
}
/**
* Get next response or wait until the next value is available. This method
* will block until a value is available. Note: this method will throw an error
* if the cache is empty and has been paused, i.e. is not being populated. If
* the cache was constructed with unsuitable parameter values or the daily allowance
* of bits/requests has been reached, the appropriate error will also be thrown.
* @returns {Promise<any[]>} The next appropriate response for the request this
* RandomOrgCache represents.
* @throws RandomOrgCacheEmptyError if the cache is empty and is paused.
*/
async getOrWait() {
try {
let values = this.get();
return values;
} catch (e) {
if (e instanceof RandomOrgCacheEmptyError$1) {
if (this.#paused) {
// The cache is paused and will not return any values
throw e;
}
let cachedValues = await this.#populate();
if (cachedValues == 0) {
// The cache has not yet repopulated.
await new Promise(r => setTimeout(r, 50));
}
return this.getOrWait();
}
}
}
/**
* Gets the number of result sets remaining in the cache.
*
* This essentially returns how often get() may be called without
* a cache refill.
* @returns {number} Current number of cached results.
*/
getCachedValues() {
return this.#stack.length;
}
/**
* Gets the number of bits used by this cache.
* @returns {number} Number of bits used.
*/
getBitsUsed() {
return this.#bitsUsed;
}
/**
* Gets number of requests used by this cache.
* @returns {number} Number of requests used.
*/
getRequestsUsed() {
return this.#requestsUsed;
}
/**
* Helper function to check if the cache needs to be repopulated.
*/
#refresh = () => {
if (this.#bulkRequestNumber > 0 && this.#stack.length <= (this.#cacheSize - this.#bulkRequestNumber)) {
// bulk requests
this.#populate();
}
else if (this.#bulkRequestNumber <= 0 && this.#stack.length < this.#cacheSize) {
// individual requests
this.#populate();
}
}
/**
* Helper function to add a response to the stack.
* @param {any[]} response The response received from the server.
* @param {boolean} bulk True if the cache issues bulk requests, false otherwise.
*/
#addResponse = (response, bulk) => {
this.#requestsUsed++;
this.#bitsUsed += response.result.bitsUsed;
if (bulk) {
let data = response.result.random.data;
for (let i = 0; i < data.length; i += this.#requestNumber) {
this.#stack.push(data.slice(i, i + this.#requestNumber));
}
} else {
this.#stack.push(response.result.random.data);
}
}
};
var RandomOrgCache$1 = /*@__PURE__*/getDefaultExportFromCjs(RandomOrgCache_1);
const {
RandomOrgBadHTTPResponseError: RandomOrgBadHTTPResponseError$1,
RandomOrgInsufficientBitsError: RandomOrgInsufficientBitsError$1,
RandomOrgInsufficientRequestsError: RandomOrgInsufficientRequestsError$1,
RandomOrgJSONRPCError: RandomOrgJSONRPCError$1,
RandomOrgKeyNotRunningError: RandomOrgKeyNotRunningError$1,
RandomOrgRANDOMORGError: RandomOrgRANDOMORGError$1,
RandomOrgSendTimeoutError: RandomOrgSendTimeoutError$1
} = RandomOrgErrors;
const RandomOrgCache = RandomOrgCache_1;
/**
* RandomOrgClient main class through which API functions are accessed.
*
* This class provides access to both the signed and unsigned methods of the
* RANDOM.ORG API.
*
* The class also provides access to the creation of a convenience class, RandomOrgCache,
* for precaching API responses when the request is known in advance.
*
* This class will only allow the creation of one instance per API key. If an
* instance of this class already exists for a given key, that instance will be
* returned instead of a new instance.
*
* This class obeys most of the guidelines set forth in https://api.random.org/json-rpc/4
* All requests respect the server's advisoryDelay returned in any responses, or use
* DEFAULT_DELAY if no advisoryDelay is returned. If the supplied API key is paused, i.e.,
* has exceeded its daily bit/request allowance, this implementation will back off until
* midnight UTC.
*/
var RandomOrgClient_1 = class RandomOrgClient {
// Basic API
static #INTEGER_METHOD = 'generateIntegers';
static #INTEGER_SEQUENCE_METHOD = 'generateIntegerSequences';
static #DECIMAL_FRACTION_METHOD = 'generateDecimalFractions';
static #GAUSSIAN_METHOD = 'generateGaussians';
static #STRING_METHOD = 'generateStrings';
static #UUID_METHOD = 'generateUUIDs';
static #BLOB_METHOD = 'generateBlobs';
static #GET_USAGE_METHOD = 'getUsage';
// Signed API
static #SIGNED_INTEGER_METHOD = 'generateSignedIntegers';
static #SIGNED_INTEGER_SEQUENCE_METHOD = 'generateSignedIntegerSequences';
static #SIGNED_DECIMAL_FRACTION_METHOD = 'generateSignedDecimalFractions';
static #SIGNED_GAUSSIAN_METHOD = 'generateSignedGaussians';
static #SIGNED_STRING_METHOD = 'generateSignedStrings';
static #SIGNED_UUID_METHOD = 'generateSignedUUIDs';
static #SIGNED_BLOB_METHOD = 'generateSignedBlobs';
static #GET_RESULT_METHOD = 'getResult';
static #CREATE_TICKET_METHOD = 'createTickets';
static #LIST_TICKET_METHOD = 'listTickets';
static #REVEAL_TICKET_METHOD = 'revealTickets';
static #GET_TICKET_METHOD = 'getTicket';
static #VERIFY_SIGNATURE_METHOD = 'verifySignature';
// Blob format literals
/** Blob format literal, base64 encoding (default). */
static BLOB_FORMAT_BASE64 = 'base64';
/** Blob format literal, hex encoding. */
static BLOB_FORMAT_HEX = 'hex';
// Default values
/** Default value for the replacement parameter (true). */
static DEFAULT_REPLACEMENT = true;
/** Default value for the base parameter (10). */
static DEFAULT_BASE = 10;
/** Default value for the userData parameter (null). */
static DEFAULT_USER_DATA = null;
/** Default value for the ticketId parameter (null). */
static DEFAULT_TICKET_ID = null;
/** Default value for the pregeneratedRandomization parameter (null). */
static DEFAULT_PREGENERATED_RANDOMIZATION = null;
/** Default value for the licenseData parameter (null). */
static DEFAULT_LICENSE_DATA = null;
/** Size of a single UUID in bits. */
static UUID_SIZE = 122;
/** Default value for the blockingTimeout parameter (1 day). */
static DEFAULT_BLOCKING_TIMEOUT = 24 * 60 * 60 * 1000;
/** Default value for the httpTimeout parameter (2 minutes). */
static DEFAULT_HTTP_TIMEOUT = 120 * 1000;
/** Maximum number of characters allowed in a signature verficiation URL. */
static MAX_URL_LENGTH = 2046;
// Default back-off to use if no advisoryDelay back-off supplied by server (1 second)
static #DEFAULT_DELAY = 1*1000;
// On request fetch fresh allowance state if current state data is older than
// this value (1 hour).
static #ALLOWANCE_STATE_REFRESH_SECONDS = 3600 * 1000;
// Maintains usage statistics from server.
#bitsLeft = -1;
#requestsLeft = -1;
// Back-off info for when the API key is detected as not running, probably
// because the key has exceeded its daily usage limit. Back-off runs until
// midnight UTC.
#backoff = -1;
#backoffError = '';
#apiKey = '';
#blockingTimeout = RandomOrgClient.DEFAULT_BLOCKING_TIMEOUT;
#httpTimeout = RandomOrgClient.DEFAULT_HTTP_TIMEOUT;
// Maintain info to obey server advisory delay
#advisoryDelay = 0;
#lastResponseReceivedTime = 0;
// Maintains a dictionary of API keys and their instances.
static #keyIndexedInstances = {};
static #ERROR_CODES = [ 100, 101, 200, 201, 202, 203, 204, 300,
301, 302, 303, 304, 305, 306, 307, 400, 401, 402, 403, 404,
405, 420, 421, 422, 423, 424, 425, 426, 500, 32000 ];
/**
* Constructor. Ensures only one instance of RandomOrgClient exists per API
* key. Creates a new instance if the supplied key isn't already known,
* otherwise returns the previously instantiated one.
* @constructor
* @param {string} apiKey API key of instance to create/find, obtained from
* RANDOM.ORG, see https://api.random.org/api-keys
* @param {{blockingTimeout?: number, httpTimeout?: number}} options An object
* which may contains any of the following optional parameters:
* @param {number} [options.blockingTimeout = 24 * 60 * 60 * 1000] Maximum
* time in milliseconds to wait before being allowed to send a request.
* Note this is a hint not a guarantee. The advisory delay from server
* must always be obeyed. Supply a value of -1 to allow blocking forever
* (default 24 * 60 * 60 * 1000, i.e., 1 day).
* @param {number} [options.httpTimeout = 120 * 1000] Maximum time in
* milliseconds to wait for the server response to a request (default
* 120*1000).
*/
constructor(apiKey, options = {}) {
if (RandomOrgClient.#keyIndexedInstances && RandomOrgClient.#keyIndexedInstances[apiKey]) {
return RandomOrgClient.#keyIndexedInstances[apiKey];
} else {
this.#apiKey = apiKey;
this.#blockingTimeout = options.blockingTimeout || 24 * 60 * 60 * 1000;
this.#httpTimeout = options.httpTimeout || 120 * 1000;
RandomOrgClient.#keyIndexedInstances[apiKey] = this;
}
}
// Basic API
/**
* Requests and returns an array of true random integers within a user-defined
* range from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateIntegers
* @param {number} n The number of random integers you need. Must be within
* the [1,1e4] range.
* @param {number} min The lower boundary for the range from which the random
* numbers will be picked. Must be within the [-1e9,1e9] range.
* @param {number} max The upper boundary for the range from which the random
* numbers will be picked. Must be within the [-1e9,1e9] range.
* @param {{replacement?: boolean, base?: number, pregeneratedRandomization?:
* Object}} options An object which may contains any of the following
* optional parameters:
* @param {boolean} [options.replacement=true] Specifies whether the random
* numbers should be picked with replacement. If true, the resulting numbers
* may contain duplicate values, otherwise the numbers will all be unique
* (default true).
* @param {number} [options.base=10] The base that will be used to display
* the numbers. Values allowed are 2, 8, 10 and 16 (default 10).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {(Promise<number[]>|Promise<string[]>)} A Promise which, if
* resolved successfully, represents an array of true random integers.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
* */
async generateIntegers(n, min, max, options = {}) {
let request = this.#integerRequest(n, min, max, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns an array of true random integer sequences within a
* user-defined range from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences
* @param {number} n How many arrays of random integers you need. Must be
* within the [1,1e3] range.
* @param {(number|number[])} length The length of each array of random
* integers requested. For uniform sequences, length must be an integer
* in the [1, 1e4] range. For multiform sequences, length can be an array
* with n integers, each specifying the length of the sequence identified
* by its index. In this case, each value in length must be within the
* [1, 1e4] range and the total sum of all the lengths must be in the
* [1, 1e4] range.
* @param {(number|number[])} min The lower boundary for the range from which
* the random numbers will be picked. For uniform sequences, min must be
* an integer in the [-1e9, 1e9] range. For multiform sequences, min can
* be an array with n integers, each specifying the lower boundary of the
* sequence identified by its index. In this case, each value in min must
* be within the [-1e9, 1e9] range.
* @param {(number|number[])} max The upper boundary for the range from which
* the random numbers will be picked. For uniform sequences, max must be
* an integer in the [-1e9, 1e9] range. For multiform sequences, max can
* be an array with n integers, each specifying the upper boundary of the
* sequence identified by its index. In this case, each value in max must
* be within the [-1e9, 1e9] range.
* @param {{replacement?: boolean|boolean[], base?: number|number[],
* pregeneratedRandomization?: Object}} options An object which may contains
* any of the following optional parameters:
* @param {(boolean|boolean[])} [options.replacement=true] Specifies whether
* the random numbers should be picked with replacement. If true, the
* resulting numbers may contain duplicate values, otherwise the numbers
* will all be unique. For multiform sequences, replacement can be an array
* with n boolean values, each specifying whether the sequence identified
* by its index will be created with (true) or without (false) replacement
* (default true).
* @param {(number|number[])} [options.base=10] The base that will be used
* to display the numbers. Values allowed are 2, 8, 10 and 16. For multiform
* sequences, base can be an array with n integer values taken from the
* same set, each specifying the base that will be used to display the
* sequence identified by its index (default 10).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {(Promise<number[][]>|Promise<string[][]>)} A Promise which, if
* resolved successfully, represents an array of true random integer
* sequences.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateIntegerSequences(n, length, min, max, options = {}) {
let request = this.#integerSequenceRequest(n, length, min, max, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of true random decimal fractions,
* from a uniform distribution across the [0,1] interval with a user-defined
* number of decimal places from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateDecimalFractions
* @param {number} n How many random decimal fractions you need. Must be
* within the [1,1e4] range.
* @param {number} decimalPlaces The number of decimal places to use. Must be
* within the [1,20] range.
* @param {{replacement?: boolean, pregeneratedRandomization?: Object}} options
* An object which may contains any of the following optional parameters:
* @param {boolean} [options.replacement=true] Specifies whether the random
* numbers should be picked with replacement. If true, the resulting numbers
* may contain duplicate values, otherwise the numbers will all be unique
* (default true).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<number[]>} A Promise which, if resolved successfully,
* represents an array of true random decimal fractions.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateDecimalFractions(n, decimalPlaces, options = {}) {
let request = this.#decimalFractionRequest(n, decimalPlaces, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of true random numbers from a
* Gaussian distribution (also known as a normal distribution).
*
* The form uses a Box-Muller Transform to generate the Gaussian distribution
* from uniformly distributed numbers.
* See: https://api.random.org/json-rpc/4/basic#generateGaussians
* @param {number} n How many random numbers you need. Must be within the
* [1,1e4] range.
* @param {number} mean The distribution's mean. Must be within the
* [-1e6,1e6] range.
* @param {number} standardDeviation The distribution's standard deviation.
* Must be within the [-1e6,1e6] range.
* @param {number} significantDigits The number of significant digits to use.
* Must be within the [2,20] range.
* @param {{pregeneratedRandomization?: Object}} options An object which may
* contains any of the following optional parameters:
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<number[]>} A Promise which, if resolved successfully,
* represents an array of true random numbers from a Gaussian distribution.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateGaussians(n, mean, standardDeviation, significantDigits, options = {}) {
let request = this.#gaussianRequest(n, mean, standardDeviation,
significantDigits, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of true random unicode strings from
* the server. See: https://api.random.org/json-rpc/4/basic#generateStrings
* @param {number} n How many random strings you need. Must be within the
* [1,1e4] range.
* @param {number} length The length of each string. Must be within the
* [1,20] range. All strings will be of the same length.
* @param {string} characters A string that contains the set of characters
* that are allowed to occur in the random strings. The maximum number
* of characters is 80.
* @param {{replacement?: boolean, pregeneratedRandomization?: Object}} options
* An object which may contains any of the following optional parameters:
* @param {boolean} [options.replacement=true] Specifies whether the random
* strings should be picked with replacement. If true, the resulting list
* of strings may contain duplicates, otherwise the strings will all be
* unique (default true).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<string[]>} A Promise which, if resolved successfully,
* represents an array of true random strings.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateStrings(n, length, characters, options = {}) {
let request = this.#stringRequest(n, length, characters, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of version 4 true random Universally
* Unique IDentifiers (UUIDs) in accordance with section 4.4 of RFC 4122,
* from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateUUIDs
* @param {number} n How many random UUIDs you need. Must be within the
* [1,1e3] range.
* @param {{pregeneratedRandomization?: Object}} options An object which may
* contains any of the following optional parameters:
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<string[]>} A Promise which, if resolved successfully,
* represents an array of true random UUIDs.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateUUIDs(n, options = {}) {
let request = this.#UUIDRequest(n, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of Binary Large OBjects (BLOBs)
* as unicode strings containing true random data from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateBlobs
* @param {number} n How many random blobs you need. Must be within the
* [1,100] range.
* @param {number} size The size of each blob, measured in bits. Must be
* within the [1,1048576] range and must be divisible by 8.
* @param {{format?: string, pregeneratedRandomization?: Object}} options
* An object which may contains any of the following optional parameters:
* @param {string} [options.format='base64'] Specifies the format in which
* the blobs will be returned. Values allowed are 'base64' and 'hex'
* (default 'base64').
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<number[]>} A Promise which, if resolved successfully,
* represents an array of true random blobs as strings.
* @see {@link RandomOrgClient#BLOB_FORMAT_BASE64} for 'base64' (default).
* @see {@link RandomOrgClient#BLOB_FORMAT_HEX} for 'hex'.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateBlobs(n, size, options = {}) {
let request = this.#blobRequest(n, size, options);
return this.#extractBasic(this.#sendRequest(request));
}
// SIGNED API
/**
* Requests a list (size n) of true random integers within a user-defined
* range from the server.
*
* Returns a Promise which, if resolved successfully, respresents an object
* with the parsed integer list mapped to 'data', the original response mapped
* to 'random', and the response's signature mapped to 'signature'.
* See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers
* @param {number} n How many random integers you need. Must be within the
* [1,1e4] range.
* @param {number} min The lower boundary for the range from which the
* random numbers will be picked. Must be within the [-1e9,1e9] range.
* @param {number} max The upper boundary for the range from which the
* random numbers will be picked. Must be within the [-1e9,1e9] range.
* @param {{replacement?: boolean, base?: number, pregeneratedRandomization?:
* Object, licenseData?: Object, userData?: Object|number|string, ticketId?:
* string}} options An object which may contains any of the following
* optional parameters:
* @param {boolean} [options.replacement=true] Specifies whether the random
* numbers should be picked with replacement. If true, the resulting numbers
* may contain duplicate values, otherwise the numbers will all be unique
* (default true).
* @param {number} [options.base=10] The base that will be used to display
* the numbers. Values allowed are 2, 8, 10 and 16 (default 10).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for rand