A tiny NodeJS client for generating random users using the RandomUser.me API. Perfect for testing, prototyping, and generating placeholder user data for your applications.
npm install randomuseror with yarn:
yarn add randomuserconst RandomUser = require('randomuser');
const client = new RandomUser();
// Get a single random user
client.getUsersAsync().then(data => {
console.log(data[0]); // User object with name, email, address, etc.
});
// Get multiple users with options
client.getUsersAsync({ results: 3, gender: 'female' }).then(data => {
console.log(data); // Array of 3 female user objects
});{
gender: 'female',
name: { title: 'Ms', first: 'Jennie', last: 'Nichols' },
location: {
street: '8929 Valwood Pkwy',
city: 'Billings',
state: 'Michigan',
postcode: '63104',
coordinates: { latitude: '-69.8246', longitude: '134.8719' },
timezone: { offset: '+9:30', description: 'Adelaide, Darwin' }
},
email: 'jennie.nichols@example.com',
phone: '(272) 790-0888',
cell: '(489) 330-2385',
id: { name: 'SSN', value: '405-88-3636' },
picture: {
large: 'https://randomuser.me/api/portraits/women/75.jpg',
medium: 'https://randomuser.me/api/portraits/med/women/75.jpg',
thumbnail: 'https://randomuser.me/api/portraits/thumb/women/75.jpg'
},
nat: 'US'
}// CommonJS
const RandomUser = require('randomuser');
const client = new RandomUser();
// ES Modules (TypeScript)
import * as RandomUser from 'randomuser';
const client = new RandomUser();
// Async/await with options
async function getRandomUsers() {
const data = await client.getUsersAsync({ seed: "foxie", results: 5, gender: "male" });
console.log(data);
}
// Promise-based without options
client.getUsersAsync()
.then(data => {
console.log(data);
});
// With request cancellation
async function getRandomUsersWithTimeout() {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000); // 5 second timeout
try {
const data = await client.getUsersAsync(
{ results: 10 },
{ signal: controller.signal }
);
clearTimeout(timeoutId);
console.log(data);
} catch (error) {
if (error.code === 'ABORT_ERROR') {
console.log('Request was cancelled due to timeout');
} else {
console.error('Error:', error);
}
}
}
// With explicit timeout option
async function getRandomUsersWithTimeoutOption() {
try {
const data = await client.getUsersAsync(
{ results: 10 },
{ timeout: 5000 } // 5 second timeout
);
console.log(data);
} catch (error) {
console.error('Request failed or timed out:', error);
}
}const RandomUser = require('randomuser');
const client = new RandomUser();
// With options
client.getUsers({ seed: "foxie", results: 5, gender: "male" }, data => {
console.log(data);
});
// Without options
client.getUsers(data => {
console.log(data);
});| Parameter | Type | Description |
|---|---|---|
results |
number or string |
Number of results to return (default: 1) |
gender |
string |
Filter by gender ("male" or "female") |
seed |
string |
Generate consistent results for the same seed value |
page |
number or string |
Page number for pagination |
nat |
string or string[] |
Nationality filter (e.g., "us", "gb", "fr") |
inc |
string or string[] |
Include only these fields |
exc |
string or string[] |
Exclude these fields |
| Option | Type | Description |
|---|---|---|
signal |
AbortSignal |
Signal for request cancellation via AbortController |
timeout |
number |
Timeout in milliseconds after which the request will be cancelled |
For full API documentation, see the RandomUser.me API docs.
We welcome contributions! Here's how you can help:
- Fork the repository and create your feature branch
- Install dependencies:
yarn install - Build the project:
yarn build - Run tests:
yarn test - Make your changes and ensure tests pass
- Submit a pull request with a clear description of your changes
- Clone your fork:
git clone https://github.com/your-username/randomuser.git - Install dependencies:
yarn install - Build the project:
yarn build - Run tests:
yarn test
Please make sure your code follows the existing style and includes appropriate tests.