nanoid 3.1.30 → 3.3.8

package/async/index.browser.js

@@ -1,28 +1,61 @@
-let random = bytes =>
-  Promise.resolve(crypto.getRandomValues(new Uint8Array(bytes)))
-let customAlphabet = (alphabet, size) => {
+let random = async bytes => crypto.getRandomValues(new Uint8Array(bytes))
+
+let customAlphabet = (alphabet, defaultSize = 21) => {
+  // First, a bitmask is necessary to generate the ID. The bitmask makes bytes
+  // values closer to the alphabet size. The bitmask calculates the closest
+  // `2^31 - 1` number, which exceeds the alphabet size.
+  // For example, the bitmask for the alphabet size 30 is 31 (00011111).
+  // `Math.clz32` is not used, because it is not available in browsers.
   let mask = (2 << (Math.log(alphabet.length - 1) / Math.LN2)) - 1
-  let step = -~((1.6 * mask * size) / alphabet.length)
-  return () => {
+  // Though, the bitmask solution is not perfect since the bytes exceeding
+  // the alphabet size are refused. Therefore, to reliably generate the ID,
+  // the random bytes redundancy has to be satisfied.
+
+  // Note: every hardware random generator call is performance expensive,
+  // because the system call for entropy collection takes a lot of time.
+  // So, to avoid additional system calls, extra bytes are requested in advance.
+
+  // Next, a step determines how many random bytes to generate.
+  // The number of random bytes gets decided upon the ID size, mask,
+  // alphabet size, and magic number 1.6 (using 1.6 peaks at performance
+  // according to benchmarks).
+
+  // `-~f => Math.ceil(f)` if f is a float
+  // `-~i => i + 1` if i is an integer
+  let step = -~((1.6 * mask * defaultSize) / alphabet.length)
+
+  return async (size = defaultSize) => {
     let id = ''
     while (true) {
       let bytes = crypto.getRandomValues(new Uint8Array(step))
-      let i = step
+      // A compact alternative for `for (var i = 0; i < step; i++)`.
+      let i = step | 0
       while (i--) {
+        // Adding `|| ''` refuses a random byte that exceeds the alphabet size.
         id += alphabet[bytes[i] & mask] || ''
-        if (id.length === size) return Promise.resolve(id)
+        if (id.length === size) return id
       }
     }
   }
 }
-let nanoid = (size = 21) => {
+
+let nanoid = async (size = 21) => {
   let id = ''
-  let bytes = crypto.getRandomValues(new Uint8Array(size))
+  let bytes = crypto.getRandomValues(new Uint8Array((size |= 0)))
+
+  // A compact alternative for `for (var i = 0; i < step; i++)`.
   while (size--) {
+    // It is incorrect to use bytes exceeding the alphabet size.
+    // The following mask reduces the random byte in the 0-255 value
+    // range to the 0-63 value range. Therefore, adding hacks, such
+    // as empty string fallback or magic numbers, is unneccessary because
+    // the bitmask trims bytes down to the alphabet size.
     let byte = bytes[size] & 63
     if (byte < 36) {
+      // `0-9a-z`
       id += byte.toString(36)
     } else if (byte < 62) {
+      // `A-Z`
       id += (byte - 26).toString(36).toUpperCase()
     } else if (byte < 63) {
       id += '_'
@@ -30,6 +63,7 @@ let nanoid = (size = 21) => {
       id += '-'
     }
   }
-  return Promise.resolve(id)
+  return id
 }
+
 export { nanoid, customAlphabet, random }

package/async/index.cjs

@@ -1,7 +1,14 @@
 let crypto = require('crypto')
+
 let { urlAlphabet } = require('../url-alphabet/index.cjs')
+
+// `crypto.randomFill()` is a little faster than `crypto.randomBytes()`,
+// because it is possible to use in combination with `Buffer.allocUnsafe()`.
 let random = bytes =>
   new Promise((resolve, reject) => {
+    // `Buffer.allocUnsafe()` is faster because it doesn’t flush the memory.
+    // Memory flushing is unnecessary since the buffer allocation itself resets
+    // the memory with the new bytes.
     crypto.randomFill(Buffer.allocUnsafe(bytes), (err, buf) => {
       if (err) {
         reject(err)
@@ -10,26 +17,55 @@ let random = bytes =>
       }
     })
   })
-let customAlphabet = (alphabet, size) => {
+
+let customAlphabet = (alphabet, defaultSize = 21) => {
+  // First, a bitmask is necessary to generate the ID. The bitmask makes bytes
+  // values closer to the alphabet size. The bitmask calculates the closest
+  // `2^31 - 1` number, which exceeds the alphabet size.
+  // For example, the bitmask for the alphabet size 30 is 31 (00011111).
   let mask = (2 << (31 - Math.clz32((alphabet.length - 1) | 1))) - 1
-  let step = Math.ceil((1.6 * mask * size) / alphabet.length)
-  let tick = id =>
+  // Though, the bitmask solution is not perfect since the bytes exceeding
+  // the alphabet size are refused. Therefore, to reliably generate the ID,
+  // the random bytes redundancy has to be satisfied.
+
+  // Note: every hardware random generator call is performance expensive,
+  // because the system call for entropy collection takes a lot of time.
+  // So, to avoid additional system calls, extra bytes are requested in advance.
+
+  // Next, a step determines how many random bytes to generate.
+  // The number of random bytes gets decided upon the ID size, mask,
+  // alphabet size, and magic number 1.6 (using 1.6 peaks at performance
+  // according to benchmarks).
+  let step = Math.ceil((1.6 * mask * defaultSize) / alphabet.length)
+
+  let tick = (id, size = defaultSize) =>
     random(step).then(bytes => {
+      // A compact alternative for `for (var i = 0; i < step; i++)`.
       let i = step
       while (i--) {
+        // Adding `|| ''` refuses a random byte that exceeds the alphabet size.
         id += alphabet[bytes[i] & mask] || ''
-        if (id.length === size) return id
+        if (id.length >= size) return id
       }
-      return tick(id)
+      return tick(id, size)
     })
-  return () => tick('')
+
+  return size => tick('', size)
 }
+
 let nanoid = (size = 21) =>
-  random(size).then(bytes => {
+  random((size |= 0)).then(bytes => {
     let id = ''
+    // A compact alternative for `for (var i = 0; i < step; i++)`.
     while (size--) {
+      // It is incorrect to use bytes exceeding the alphabet size.
+      // The following mask reduces the random byte in the 0-255 value
+      // range to the 0-63 value range. Therefore, adding hacks, such
+      // as empty string fallback or magic numbers, is unneccessary because
+      // the bitmask trims bytes down to the alphabet size.
       id += urlAlphabet[bytes[size] & 63]
     }
     return id
   })
+
 module.exports = { nanoid, customAlphabet, random }

package/async/index.d.ts

@@ -24,8 +24,8 @@ export function nanoid(size?: number): Promise<string>
  * will not be secure.
  *
  * @param alphabet Alphabet used to generate the ID.
- * @param size Size of the ID.
- * @returns A promise with a random string.
+ * @param defaultSize Size of the ID. The default size is 21.
+ * @returns A function that returns a promise with a random string.
  *
  * ```js
  * import { customAlphabet } from 'nanoid/async'
@@ -37,8 +37,8 @@ export function nanoid(size?: number): Promise<string>
  */
 export function customAlphabet(
   alphabet: string,
-  size: number
-): () => Promise<string>
+  defaultSize?: number
+): (size?: number) => Promise<string>
 
 /**
  * Generate an array of random bytes collected from hardware noise.

package/async/index.js

@@ -1,7 +1,14 @@
 import crypto from 'crypto'
+
 import { urlAlphabet } from '../url-alphabet/index.js'
+
+// `crypto.randomFill()` is a little faster than `crypto.randomBytes()`,
+// because it is possible to use in combination with `Buffer.allocUnsafe()`.
 let random = bytes =>
   new Promise((resolve, reject) => {
+    // `Buffer.allocUnsafe()` is faster because it doesn’t flush the memory.
+    // Memory flushing is unnecessary since the buffer allocation itself resets
+    // the memory with the new bytes.
     crypto.randomFill(Buffer.allocUnsafe(bytes), (err, buf) => {
       if (err) {
         reject(err)
@@ -10,26 +17,55 @@ let random = bytes =>
       }
     })
   })
-let customAlphabet = (alphabet, size) => {
+
+let customAlphabet = (alphabet, defaultSize = 21) => {
+  // First, a bitmask is necessary to generate the ID. The bitmask makes bytes
+  // values closer to the alphabet size. The bitmask calculates the closest
+  // `2^31 - 1` number, which exceeds the alphabet size.
+  // For example, the bitmask for the alphabet size 30 is 31 (00011111).
   let mask = (2 << (31 - Math.clz32((alphabet.length - 1) | 1))) - 1
-  let step = Math.ceil((1.6 * mask * size) / alphabet.length)
-  let tick = id =>
+  // Though, the bitmask solution is not perfect since the bytes exceeding
+  // the alphabet size are refused. Therefore, to reliably generate the ID,
+  // the random bytes redundancy has to be satisfied.
+
+  // Note: every hardware random generator call is performance expensive,
+  // because the system call for entropy collection takes a lot of time.
+  // So, to avoid additional system calls, extra bytes are requested in advance.
+
+  // Next, a step determines how many random bytes to generate.
+  // The number of random bytes gets decided upon the ID size, mask,
+  // alphabet size, and magic number 1.6 (using 1.6 peaks at performance
+  // according to benchmarks).
+  let step = Math.ceil((1.6 * mask * defaultSize) / alphabet.length)
+
+  let tick = (id, size = defaultSize) =>
     random(step).then(bytes => {
+      // A compact alternative for `for (var i = 0; i < step; i++)`.
       let i = step
       while (i--) {
+        // Adding `|| ''` refuses a random byte that exceeds the alphabet size.
         id += alphabet[bytes[i] & mask] || ''
-        if (id.length === size) return id
+        if (id.length >= size) return id
       }
-      return tick(id)
+      return tick(id, size)
     })
-  return () => tick('')
+
+  return size => tick('', size)
 }
+
 let nanoid = (size = 21) =>
-  random(size).then(bytes => {
+  random((size |= 0)).then(bytes => {
     let id = ''
+    // A compact alternative for `for (var i = 0; i < step; i++)`.
     while (size--) {
+      // It is incorrect to use bytes exceeding the alphabet size.
+      // The following mask reduces the random byte in the 0-255 value
+      // range to the 0-63 value range. Therefore, adding hacks, such
+      // as empty string fallback or magic numbers, is unneccessary because
+      // the bitmask trims bytes down to the alphabet size.
       id += urlAlphabet[bytes[size] & 63]
     }
     return id
   })
+
 export { nanoid, customAlphabet, random }

package/async/index.native.js

@@ -1,26 +1,57 @@
 import { getRandomBytesAsync } from 'expo-random'
+
 import { urlAlphabet } from '../url-alphabet/index.js'
+
 let random = getRandomBytesAsync
-let customAlphabet = (alphabet, size) => {
+
+let customAlphabet = (alphabet, defaultSize = 21) => {
+  // First, a bitmask is necessary to generate the ID. The bitmask makes bytes
+  // values closer to the alphabet size. The bitmask calculates the closest
+  // `2^31 - 1` number, which exceeds the alphabet size.
+  // For example, the bitmask for the alphabet size 30 is 31 (00011111).
   let mask = (2 << (31 - Math.clz32((alphabet.length - 1) | 1))) - 1
-  let step = Math.ceil((1.6 * mask * size) / alphabet.length)
-  let tick = id =>
+  // Though, the bitmask solution is not perfect since the bytes exceeding
+  // the alphabet size are refused. Therefore, to reliably generate the ID,
+  // the random bytes redundancy has to be satisfied.
+
+  // Note: every hardware random generator call is performance expensive,
+  // because the system call for entropy collection takes a lot of time.
+  // So, to avoid additional system calls, extra bytes are requested in advance.
+
+  // Next, a step determines how many random bytes to generate.
+  // The number of random bytes gets decided upon the ID size, mask,
+  // alphabet size, and magic number 1.6 (using 1.6 peaks at performance
+  // according to benchmarks).
+  let step = Math.ceil((1.6 * mask * defaultSize) / alphabet.length)
+
+  let tick = (id, size = defaultSize) =>
     random(step).then(bytes => {
+      // A compact alternative for `for (var i = 0; i < step; i++)`.
       let i = step
       while (i--) {
+        // Adding `|| ''` refuses a random byte that exceeds the alphabet size.
         id += alphabet[bytes[i] & mask] || ''
-        if (id.length === size) return id
+        if (id.length >= size) return id
       }
-      return tick(id)
+      return tick(id, size)
     })
-  return () => tick('')
+
+  return size => tick('', size)
 }
+
 let nanoid = (size = 21) =>
-  random(size).then(bytes => {
+  random((size |= 0)).then(bytes => {
     let id = ''
+    // A compact alternative for `for (var i = 0; i < step; i++)`.
     while (size--) {
+      // It is incorrect to use bytes exceeding the alphabet size.
+      // The following mask reduces the random byte in the 0-255 value
+      // range to the 0-63 value range. Therefore, adding hacks, such
+      // as empty string fallback or magic numbers, is unneccessary because
+      // the bitmask trims bytes down to the alphabet size.
       id += urlAlphabet[bytes[size] & 63]
     }
     return id
   })
+
 export { nanoid, customAlphabet, random }

package/bin/nanoid.cjs

@@ -1,5 +1,55 @@
 #!/usr/bin/env node
 
-let { nanoid } = require('..')
+let { nanoid, customAlphabet } = require('..')
 
-process.stdout.write(nanoid() + '\n')
+function print(msg) {
+  process.stdout.write(msg + '\n')
+}
+
+function error(msg) {
+  process.stderr.write(msg + '\n')
+  process.exit(1)
+}
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  print(`
+  Usage
+    $ nanoid [options]
+
+  Options
+    -s, --size       Generated ID size
+    -a, --alphabet   Alphabet to use
+    -h, --help       Show this help
+
+  Examples
+    $ nanoid --s 15
+    S9sBF77U6sDB8Yg
+
+    $ nanoid --size 10 --alphabet abc
+    bcabababca`)
+  process.exit()
+}
+
+let alphabet, size
+for (let i = 2; i < process.argv.length; i++) {
+  let arg = process.argv[i]
+  if (arg === '--size' || arg === '-s') {
+    size = Number(process.argv[i + 1])
+    i += 1
+    if (Number.isNaN(size) || size <= 0) {
+      error('Size must be positive integer')
+    }
+  } else if (arg === '--alphabet' || arg === '-a') {
+    alphabet = process.argv[i + 1]
+    i += 1
+  } else {
+    error('Unknown argument ' + arg)
+  }
+}
+
+if (alphabet) {
+  let customNanoid = customAlphabet(alphabet, size)
+  print(customNanoid())
+} else {
+  print(nanoid(size))
+}

package/index.browser.cjs

@@ -1,62 +1,72 @@
+// This file replaces `index.js` in bundlers like webpack or Rollup,
+// according to `browser` config in `package.json`.
+
 let { urlAlphabet } = require('./url-alphabet/index.cjs')
-if (process.env.NODE_ENV !== 'production') {
-  if (
-    typeof navigator !== 'undefined' &&
-    navigator.product === 'ReactNative' &&
-    typeof crypto === 'undefined'
-  ) {
-    throw new Error(
-      'React Native does not have a built-in secure random generator. ' +
-        'If you don’t need unpredictable IDs use `nanoid/non-secure`. ' +
-        'For secure IDs, import `react-native-get-random-values` ' +
-        'before Nano ID.'
-    )
-  }
-  if (typeof msCrypto !== 'undefined' && typeof crypto === 'undefined') {
-    throw new Error(
-      'Import file with `if (!window.crypto) window.crypto = window.msCrypto`' +
-        ' before importing Nano ID to fix IE 11 support'
-    )
-  }
-  if (typeof crypto === 'undefined') {
-    throw new Error(
-      'Your browser does not have secure random generator. ' +
-        'If you don’t need unpredictable IDs, you can use nanoid/non-secure.'
-    )
-  }
-}
+
 let random = bytes => crypto.getRandomValues(new Uint8Array(bytes))
-let customRandom = (alphabet, size, getRandom) => {
+
+let customRandom = (alphabet, defaultSize, getRandom) => {
+  // First, a bitmask is necessary to generate the ID. The bitmask makes bytes
+  // values closer to the alphabet size. The bitmask calculates the closest
+  // `2^31 - 1` number, which exceeds the alphabet size.
+  // For example, the bitmask for the alphabet size 30 is 31 (00011111).
+  // `Math.clz32` is not used, because it is not available in browsers.
   let mask = (2 << (Math.log(alphabet.length - 1) / Math.LN2)) - 1
-  let step = -~((1.6 * mask * size) / alphabet.length)
-  return () => {
+  // Though, the bitmask solution is not perfect since the bytes exceeding
+  // the alphabet size are refused. Therefore, to reliably generate the ID,
+  // the random bytes redundancy has to be satisfied.
+
+  // Note: every hardware random generator call is performance expensive,
+  // because the system call for entropy collection takes a lot of time.
+  // So, to avoid additional system calls, extra bytes are requested in advance.
+
+  // Next, a step determines how many random bytes to generate.
+  // The number of random bytes gets decided upon the ID size, mask,
+  // alphabet size, and magic number 1.6 (using 1.6 peaks at performance
+  // according to benchmarks).
+
+  // `-~f => Math.ceil(f)` if f is a float
+  // `-~i => i + 1` if i is an integer
+  let step = -~((1.6 * mask * defaultSize) / alphabet.length)
+
+  return (size = defaultSize) => {
     let id = ''
     while (true) {
       let bytes = getRandom(step)
-      let j = step
+      // A compact alternative for `for (var i = 0; i < step; i++)`.
+      let j = step | 0
       while (j--) {
+        // Adding `|| ''` refuses a random byte that exceeds the alphabet size.
         id += alphabet[bytes[j] & mask] || ''
         if (id.length === size) return id
       }
     }
   }
 }
-let customAlphabet = (alphabet, size) => customRandom(alphabet, size, random)
-let nanoid = (size = 21) => {
-  let id = ''
-  let bytes = crypto.getRandomValues(new Uint8Array(size))
-  while (size--) {
-    let byte = bytes[size] & 63
+
+let customAlphabet = (alphabet, size = 21) =>
+  customRandom(alphabet, size, random)
+
+let nanoid = (size = 21) =>
+  crypto.getRandomValues(new Uint8Array(size)).reduce((id, byte) => {
+    // It is incorrect to use bytes exceeding the alphabet size.
+    // The following mask reduces the random byte in the 0-255 value
+    // range to the 0-63 value range. Therefore, adding hacks, such
+    // as empty string fallback or magic numbers, is unneccessary because
+    // the bitmask trims bytes down to the alphabet size.
+    byte &= 63
     if (byte < 36) {
+      // `0-9a-z`
       id += byte.toString(36)
     } else if (byte < 62) {
+      // `A-Z`
       id += (byte - 26).toString(36).toUpperCase()
-    } else if (byte < 63) {
-      id += '_'
-    } else {
+    } else if (byte > 62) {
       id += '-'
+    } else {
+      id += '_'
     }
-  }
-  return id
-}
+    return id
+  }, '')
+
 module.exports = { nanoid, customAlphabet, customRandom, urlAlphabet, random }

package/index.browser.js

@@ -1,62 +1,72 @@
+// This file replaces `index.js` in bundlers like webpack or Rollup,
+// according to `browser` config in `package.json`.
+
 import { urlAlphabet } from './url-alphabet/index.js'
-if (process.env.NODE_ENV !== 'production') {
-  if (
-    typeof navigator !== 'undefined' &&
-    navigator.product === 'ReactNative' &&
-    typeof crypto === 'undefined'
-  ) {
-    throw new Error(
-      'React Native does not have a built-in secure random generator. ' +
-        'If you don’t need unpredictable IDs use `nanoid/non-secure`. ' +
-        'For secure IDs, import `react-native-get-random-values` ' +
-        'before Nano ID.'
-    )
-  }
-  if (typeof msCrypto !== 'undefined' && typeof crypto === 'undefined') {
-    throw new Error(
-      'Import file with `if (!window.crypto) window.crypto = window.msCrypto`' +
-        ' before importing Nano ID to fix IE 11 support'
-    )
-  }
-  if (typeof crypto === 'undefined') {
-    throw new Error(
-      'Your browser does not have secure random generator. ' +
-        'If you don’t need unpredictable IDs, you can use nanoid/non-secure.'
-    )
-  }
-}
+
 let random = bytes => crypto.getRandomValues(new Uint8Array(bytes))
-let customRandom = (alphabet, size, getRandom) => {
+
+let customRandom = (alphabet, defaultSize, getRandom) => {
+  // First, a bitmask is necessary to generate the ID. The bitmask makes bytes
+  // values closer to the alphabet size. The bitmask calculates the closest
+  // `2^31 - 1` number, which exceeds the alphabet size.
+  // For example, the bitmask for the alphabet size 30 is 31 (00011111).
+  // `Math.clz32` is not used, because it is not available in browsers.
   let mask = (2 << (Math.log(alphabet.length - 1) / Math.LN2)) - 1
-  let step = -~((1.6 * mask * size) / alphabet.length)
-  return () => {
+  // Though, the bitmask solution is not perfect since the bytes exceeding
+  // the alphabet size are refused. Therefore, to reliably generate the ID,
+  // the random bytes redundancy has to be satisfied.
+
+  // Note: every hardware random generator call is performance expensive,
+  // because the system call for entropy collection takes a lot of time.
+  // So, to avoid additional system calls, extra bytes are requested in advance.
+
+  // Next, a step determines how many random bytes to generate.
+  // The number of random bytes gets decided upon the ID size, mask,
+  // alphabet size, and magic number 1.6 (using 1.6 peaks at performance
+  // according to benchmarks).
+
+  // `-~f => Math.ceil(f)` if f is a float
+  // `-~i => i + 1` if i is an integer
+  let step = -~((1.6 * mask * defaultSize) / alphabet.length)
+
+  return (size = defaultSize) => {
     let id = ''
     while (true) {
       let bytes = getRandom(step)
-      let j = step
+      // A compact alternative for `for (var i = 0; i < step; i++)`.
+      let j = step | 0
       while (j--) {
+        // Adding `|| ''` refuses a random byte that exceeds the alphabet size.
         id += alphabet[bytes[j] & mask] || ''
         if (id.length === size) return id
       }
     }
   }
 }
-let customAlphabet = (alphabet, size) => customRandom(alphabet, size, random)
-let nanoid = (size = 21) => {
-  let id = ''
-  let bytes = crypto.getRandomValues(new Uint8Array(size))
-  while (size--) {
-    let byte = bytes[size] & 63
+
+let customAlphabet = (alphabet, size = 21) =>
+  customRandom(alphabet, size, random)
+
+let nanoid = (size = 21) =>
+  crypto.getRandomValues(new Uint8Array(size)).reduce((id, byte) => {
+    // It is incorrect to use bytes exceeding the alphabet size.
+    // The following mask reduces the random byte in the 0-255 value
+    // range to the 0-63 value range. Therefore, adding hacks, such
+    // as empty string fallback or magic numbers, is unneccessary because
+    // the bitmask trims bytes down to the alphabet size.
+    byte &= 63
     if (byte < 36) {
+      // `0-9a-z`
       id += byte.toString(36)
     } else if (byte < 62) {
+      // `A-Z`
       id += (byte - 26).toString(36).toUpperCase()
-    } else if (byte < 63) {
-      id += '_'
-    } else {
+    } else if (byte > 62) {
       id += '-'
+    } else {
+      id += '_'
     }
-  }
-  return id
-}
+    return id
+  }, '')
+
 export { nanoid, customAlphabet, customRandom, urlAlphabet, random }