Support asynchronous generation (#27)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

Author: Richienb

index.d.ts

@@ -60,19 +60,36 @@ declare namespace cryptoRandomString {
 	type Options = BaseOptions & MergeExclusive<TypeOption, CharactersOption>;
 }
 
-/**
-Generate a [cryptographically strong](https://en.wikipedia.org/wiki/Strong_cryptography) random string.
+declare const cryptoRandomString: {
+	/**
+	Generate a [cryptographically strong](https://en.wikipedia.org/wiki/Strong_cryptography) random string.
+
+	@returns A randomized string.
+
+	@example
+	```
+	import cryptoRandomString = require('crypto-random-string');
+
+	cryptoRandomString({length: 10});
+	//=> '2cf05d94db'
+	```
+	*/
+	(options?: cryptoRandomString.Options): string;
+
+	/**
+	Asynchronously generate a [cryptographically strong](https://en.wikipedia.org/wiki/Strong_cryptography) random string.
 
-@returns A randomized string.
+	@returns A promise which resolves to a randomized string.
 
-@example
-```
-import cryptoRandomString = require('crypto-random-string');
+	@example
+	```
+	import cryptoRandomString = require('crypto-random-string');
 
-cryptoRandomString({length: 10});
-//=> '2cf05d94db'
-```
-*/
-declare function cryptoRandomString(options?: cryptoRandomString.Options): string;
+	await cryptoRandomString.async({length: 10});
+	//=> '2cf05d94db'
+	```
+	*/
+	async(options?: cryptoRandomString.Options): Promise<string>;
+}
 
 export = cryptoRandomString;

index.js

@@ -1,6 +1,9 @@
 'use strict';
+const {promisify} = require('util');
 const crypto = require('crypto');
 
+const randomBytesAsync = promisify(crypto.randomBytes);
+
 const urlSafeCharacters = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~'.split('');
 const numericCharacters = '0123456789'.split('');
 const distinguishableCharacters = 'CDEHKMPRTUWXY012458'.split('');
@@ -32,6 +35,40 @@ const generateForCustomCharacters = (length, characters) => {
 	return string;
 };
 
+const generateForCustomCharactersAsync = async (length, characters) => {
+	// Generating entropy is faster than complex math operations, so we use the simplest way
+	const characterCount = characters.length;
+	const maxValidSelector = (Math.floor(0x10000 / characterCount) * characterCount) - 1; // Using values above this will ruin distribution when using modular division
+	const entropyLength = 2 * Math.ceil(1.1 * length); // Generating a bit more than required so chances we need more than one pass will be really low
+	let string = '';
+	let stringLength = 0;
+
+	while (stringLength < length) { // In case we had many bad values, which may happen for character sets of size above 0x8000 but close to it
+		const entropy = await randomBytesAsync(entropyLength); // eslint-disable-line no-await-in-loop
+		let entropyPosition = 0;
+
+		while (entropyPosition < entropyLength && stringLength < length) {
+			const entropyValue = entropy.readUInt16LE(entropyPosition);
+			entropyPosition += 2;
+			if (entropyValue > maxValidSelector) { // Skip values which will ruin distribution when using modular division
+				continue;
+			}
+
+			string += characters[entropyValue % characterCount];
+			stringLength++;
+		}
+	}
+
+	return string;
+};
+
+const generateRandomBytes = (byteLength, type, length) => crypto.randomBytes(byteLength).toString(type).slice(0, length);
+
+const generateRandomBytesAsync = async (byteLength, type, length) => {
+	const buffer = await randomBytesAsync(byteLength);
+	return buffer.toString(type).slice(0, length);
+};
+
 const allowedTypes = [
 	undefined,
 	'hex',
@@ -41,7 +78,7 @@ const allowedTypes = [
 	'distinguishable'
 ];
 
-module.exports = ({length, type, characters}) => {
+const createGenerator = (generateForCustomCharacters, generateRandomBytes) => ({length, type, characters}) => {
 	if (!(length >= 0 && Number.isFinite(length))) {
 		throw new TypeError('Expected a `length` to be a non-negative finite number');
 	}
@@ -63,11 +100,11 @@ module.exports = ({length, type, characters}) => {
 	}
 
 	if (type === 'hex' || (type === undefined && characters === undefined)) {
-		return crypto.randomBytes(Math.ceil(length * 0.5)).toString('hex').slice(0, length); // Need 0.5 byte entropy per character
+		return generateRandomBytes(Math.ceil(length * 0.5), 'hex', length); // Need 0.5 byte entropy per character
 	}
 
 	if (type === 'base64') {
-		return crypto.randomBytes(Math.ceil(length * 0.75)).toString('base64').slice(0, length); // Need 0.75 byte of entropy per character
+		return generateRandomBytes(Math.ceil(length * 0.75), 'base64', length); // Need 0.75 byte of entropy per character
 	}
 
 	if (type === 'url-safe') {
@@ -92,3 +129,6 @@ module.exports = ({length, type, characters}) => {
 
 	return generateForCustomCharacters(length, characters.split(''));
 };
+
+module.exports = createGenerator(generateForCustomCharacters, generateRandomBytes);
+module.exports.async = createGenerator(generateForCustomCharactersAsync, generateRandomBytesAsync);

index.test-d.ts

@@ -5,6 +5,7 @@ expectType<string>(cryptoRandomString({length: 10}));
 expectType<string>(cryptoRandomString({length: 10, type: 'url-safe'}));
 expectType<string>(cryptoRandomString({length: 10, type: 'numeric'}));
 expectType<string>(cryptoRandomString({length: 10, characters: '1234'}));
+expectType<Promise<string>>(cryptoRandomString.async({length: 10}));
 
 expectError(cryptoRandomString({type: 'url-safe'}));
 expectError(cryptoRandomString({length: 10, type: 'url-safe', characters: '1234'}));

readme.md

@@ -40,6 +40,10 @@ cryptoRandomString({length: 10, characters: 'abc'});
 
 Returns a randomized string. [Hex](https://en.wikipedia.org/wiki/Hexadecimal) by default.
 
+### cryptoRandomString.async(options)
+
+Returns a promise which resolves to a randomized string. [Hex](https://en.wikipedia.org/wiki/Hexadecimal) by default.
+
 #### options
 
 Type: `object`

test.js

@@ -22,6 +22,13 @@ test('main', t => {
 	t.is(generatedCharacterSetSize({}, 16), 16);
 });
 
+test('async', async t => {
+	t.is((await cryptoRandomString.async({length: 0})).length, 0);
+	t.is((await cryptoRandomString.async({length: 10})).length, 10);
+	t.is((await cryptoRandomString.async({length: 100})).length, 100);
+	t.regex(await cryptoRandomString.async({length: 100}), /^[a-f\d]*$/); // Sanity check, probabilistic
+});
+
 test('hex', t => {
 	t.is(cryptoRandomString({length: 0, type: 'hex'}).length, 0);
 	t.is(cryptoRandomString({length: 10, type: 'hex'}).length, 10);