Awesome
uid
![codecov](https://badgen.now.sh/codecov/c/github/lukeed/uid)
A tiny (130B to 205B) and fast utility to randomize unique IDs of fixed length
Fast object IDs. Available for Node.js and the browser.<br>Generate randomized output strings of fixed length using lowercase alphanumeric characters (a-z0-9
). To produce IDs in UUID.V4 format, please see @lukeed/uuid
.
This module offers multiple modes for your needs:
uid
<br>The default is "non-secure", which usesMath.random
to produce UUIDs.uid/secure
<br>The "secure" mode produces cryptographically secure (CSPRNG) UUIDs using the current environment'scrypto
module.uid/single
<br>The "single" mode does not maintain an internal cache, which makes it ideal for short-lived environments.
Additionally, this module is preconfigured for native ESM support in Node.js with fallback to CommonJS. It will also work with any Rollup and webpack configuration, regardless of the "mode" selected.
Install
$ npm install --save uid
Modes
There are three "versions" of uid
available:
uid
Size (gzip): 174 bytes<br> Availability: CommonJS, ES Module, UMD
Relies on Math.random
, which means that, while faster, this mode is not cryptographically secure. <br>Works in Node.js and all browsers. <br>Alphabet: Hexadecimal
uid/secure
Size (gzip): 205 bytes<br> Availability: CommonJS, ES Module, UMD
Relies on the environment's crypto
module in order to produce cryptographically secure (CSPRNG) values. <br>Works in all versions of Node.js. Works in all browsers with crypto.getRandomValues()
support. <br>Alphabet: Hexadecimal
uid/single
Size (gzip): 131 bytes<br> Availability: CommonJS, ES Module, UMD
Relies on Math.random
, which means that this mode is not cryptographically secure. <br>Does not maintain an internal buffer, which makes this mode ideal for single-use and/or short-lived environments. <br>Works in Node.js and all browsers. <br>Alphabet: Alphanumeric
Usage
import { uid } from 'uid';
// or: import { uid } from 'uid/secure';
// or: import { uid } from 'uid/single';
// length = 11 (default)
uid(); //=> 'c92054d1dd6'
uid(); //=> 'ac84bbb3728'
// customize length
uid(16); //=> '8234dbf9a7dcec3b'
uid(25); //=> '4bbb3728b7a00a12209ec5ff5'
uid(32); //=> 'dcbc3e65506a7e6f15d30a357e884432'
API
uid(length?)
Returns: String
Creates a new random identifer of fixed length.
length
Type: Number
<br>
Default: 11
Then length of the output string.
Important: Your risk of collisions decreases with longer strings!
Benchmarks
You can run the benchmark(s) yourself via the /bench
directory.
All items listed pass a validation step for length and uniqueness. <br>
Items marked with a †
are cryptographically secure (via CSPRNG).
Running on Node.js v12.18.4
Benchmark (length = 11):
hashids/fixed x 387,306 ops/sec ±1.03% (92 runs sampled)
nanoid/non-secure x 5,338,433 ops/sec ±0.20% (95 runs sampled)
† nanoid x 2,705,158 ops/sec ±0.31% (95 runs sampled)
† uid/secure x 9,648,755 ops/sec ±0.18% (96 runs sampled)
uid/single x 4,843,529 ops/sec ±0.19% (96 runs sampled)
uid x 21,276,788 ops/sec ±0.37% (94 runs sampled)
Benchmark (length = 16):
hashids/fixed x 409,228 ops/sec ±0.36% (98 runs sampled)
nanoid/non-secure x 3,643,896 ops/sec ±1.27% (96 runs sampled)
† nanoid x 2,273,555 ops/sec ±0.15% (95 runs sampled)
† uid/secure x 9,167,545 ops/sec ±0.32% (95 runs sampled)
uid/single x 3,624,579 ops/sec ±0.29% (95 runs sampled)
uid x 24,770,463 ops/sec ±0.41% (97 runs sampled)
Benchmark (length = 25):
cuid x 177,241 ops/sec ±1.38% (91 runs sampled)
hashids/fixed x 396,013 ops/sec ±0.21% (98 runs sampled)
nanoid/non-secure x 2,477,463 ops/sec ±0.37% (96 runs sampled)
† nanoid x 1,794,062 ops/sec ±0.18% (97 runs sampled)
† uid/secure x 3,778,663 ops/sec ±0.16% (95 runs sampled)
uid/single x 2,428,167 ops/sec ±0.27% (96 runs sampled)
uid x 24,580,091 ops/sec ±0.31% (96 runs sampled)
Benchmark (length = 36):
uuid/v1 x 1,738,574 ops/sec ±0.36% (97 runs sampled)
uuid/v4 x 1,276,888 ops/sec ±0.26% (94 runs sampled)
hashids/fixed x 374,294 ops/sec ±0.14% (98 runs sampled)
nanoid/non-secure x 1,816,630 ops/sec ±0.31% (97 runs sampled)
† nanoid x 1,364,928 ops/sec ±0.18% (95 runs sampled)
† @lukeed/uuid/secure x 5,144,752 ops/sec ±0.28% (93 runs sampled)
@lukeed/uuid x 5,950,932 ops/sec ±0.53% (95 runs sampled)
† uid/secure x 5,163,209 ops/sec ±0.32% (96 runs sampled)
uid/single x 1,755,748 ops/sec ±0.24% (99 runs sampled)
uid x 20,166,119 ops/sec ±0.66% (94 runs sampled)
Running on Chrome 85.0.4183.121
Benchmark (length = 11):
hashids/fixed x 369,393 ops/sec ±1.04% (67 runs sampled)
nanoid/non-secure x 4,741,795 ops/sec ±0.67% (68 runs sampled)
† nanoid x 176,138 ops/sec ±7.17% (57 runs sampled)
† uid/secure x 2,061,703 ops/sec ±3.95% (65 runs sampled)
uid/single x 4,547,527 ops/sec ±0.29% (67 runs sampled)
uid x 21,073,518 ops/sec ±0.60% (67 runs sampled)
Benchmark (length = 16):
hashids/fixed x 362,882 ops/sec ±0.25% (67 runs sampled)
nanoid/non-secure x 3,245,036 ops/sec ±1.05% (67 runs sampled)
† nanoid x 165,535 ops/sec ±5.21% (59 runs sampled)
† uid/secure x 1,676,705 ops/sec ±0.25% (68 runs sampled)
uid/single x 3,322,695 ops/sec ±0.49% (67 runs sampled)
uid x 24,074,441 ops/sec ±0.35% (67 runs sampled)
Benchmark (length = 25):
cuid x 99,011 ops/sec ±6.09% (57 runs sampled)
hashids/fixed x 349,187 ops/sec ±0.21% (68 runs sampled)
nanoid/non-secure x 2,245,251 ops/sec ±1.21% (61 runs sampled)
† nanoid x 143,529 ops/sec ±4.53% (62 runs sampled)
† uid/secure x 936,133 ops/sec ±2.14% (67 runs sampled)
uid/single x 2,276,265 ops/sec ±1.17% (66 runs sampled)
uid x 23,409,912 ops/sec ±1.81% (67 runs sampled)
Benchmark (length = 36):
uuid/v1 x 1,695,352 ops/sec ±0.26% (67 runs sampled)
uuid/v4 x 294,032 ops/sec ±1.75% (63 runs sampled)
hashids/fixed x 340,402 ops/sec ±0.37% (50 runs sampled)
nanoid/non-secure x 1,611,905 ops/sec ±0.45% (66 runs sampled)
† nanoid x 118,006 ops/sec ±6.31% (52 runs sampled)
† @lukeed/uuid/secure x 859,592 ops/sec ±0.54% (67 runs sampled)
@lukeed/uuid x 6,041,873 ops/sec ±0.33% (66 runs sampled)
† uid/secure x 776,658 ops/sec ±0.31% (56 runs sampled)
uid/single x 1,646,199 ops/sec ±1.17% (66 runs sampled)
uid x 22,779,817 ops/sec ±0.66% (67 runs sampled)
Performance
The reason uid
and uid/secure
are so much faster than its alternatives is two-fold:
- It composes an output with hexadecimal pairs (from a cached dictionary) instead of single characters.
- It allocates a larger Buffer/ArrayBuffer up front (expensive) and slices off chunks as needed (cheap).
The uid/secure
module maintains an internal ArrayBuffer of 4096 bytes, which supplies 256 uid()
invocations. However, the default module (uid
) preallocates 512 invocations using less memory upfront. Both implementations will regenerate its internal allocation as needed.
Larger buffers would result in higher performance over time, but I found these to be a good balance of performance and memory space.
Note: If you want to don't want to preallocate memory, and do not need a CSPRNG, check out the
uid/single
mode.
Related
- hexoid - A slightly larger (190B) but extremely fast variant of this module with a different API
- @lukeed/uuid - A tiny (230B), fast, and cryptographically secure UUID (V4) generator for Node and the browser
Credits
Thank you Matthew Mueller for gifting the uid
name on npm.<br>
This module was previously known as foid
(fast object IDs).
License
MIT © Luke Edwards