Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lukeed/uid
A tiny (130B to 205B) and fast utility to generate random IDs of fixed length
https://github.com/lukeed/uid
Last synced: 3 months ago
JSON representation
A tiny (130B to 205B) and fast utility to generate random IDs of fixed length
- Host: GitHub
- URL: https://github.com/lukeed/uid
- Owner: lukeed
- License: mit
- Created: 2020-03-03T07:51:36.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-20T17:55:09.000Z (about 1 year ago)
- Last Synced: 2024-04-13T19:49:10.103Z (10 months ago)
- Language: JavaScript
- Homepage:
- Size: 43.9 KB
- Stars: 634
- Watchers: 7
- Forks: 13
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Funding: .github/FUNDING.yml
- License: license
Awesome Lists containing this project
- awesome - lukeed/uid - A tiny (130B to 205B) and fast utility to generate random IDs of fixed length (JavaScript)
- awesome-tiny-js - uid - More of the same, <img align="top" height="24" src="./img/uid.svg"> (Unique ID Generation / Reactive Programming)
- awesome-list - uid
- jimsghstars - lukeed/uid - A tiny (130B to 205B) and fast utility to generate random IDs of fixed length (JavaScript)
README
# uid [](https://github.com/lukeed/uid/actions) [](https://licenses.dev/npm/uid) [](https://codecov.io/gh/lukeed/uid)
> A tiny (130B to 205B) and [fast](#benchmarks) utility to randomize unique IDs of fixed length
_**Fast object IDs.** Available for Node.js and the browser._
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`](https://github.com/lukeed/uuid).
This module offers multiple [modes](#modes) for your needs:
* [`uid`](#uid)
_The default is "non-secure", which uses `Math.random` to produce UUIDs._
* [`uid/secure`](#uidsecure)
_The "secure" mode produces cryptographically secure (CSPRNG) UUIDs using the current environment's `crypto` module._
* [`uid/single`](#uidsingle)
_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
> **Availability:** [CommonJS](https://unpkg.com/uid/dist/index.js), [ES Module](https://unpkg.com/uid/dist/index.mjs), [UMD](https://unpkg.com/uid/dist/index.min.js)
Relies on `Math.random`, which means that, while faster, this mode **is not** cryptographically secure.
Works in Node.js and all browsers.
Alphabet: ***Hexadecimal***
#### `uid/secure`
> **Size (gzip):** 205 bytes
> **Availability:** [CommonJS](https://unpkg.com/uid/secure/index.js), [ES Module](https://unpkg.com/uid/secure/index.mjs), [UMD](https://unpkg.com/uid/secure/index.min.js)
Relies on the environment's `crypto` module in order to produce cryptographically secure (CSPRNG) values.
Works in all versions of Node.js. Works in all browsers with [`crypto.getRandomValues()` support](https://caniuse.com/#feat=getrandomvalues).
Alphabet: ***Hexadecimal***
#### `uid/single`
> **Size (gzip):** 131 bytes
> **Availability:** [CommonJS](https://unpkg.com/uid/single/index.js), [ES Module](https://unpkg.com/uid/single/index.mjs), [UMD](https://unpkg.com/uid/single/index.min.js)
Relies on `Math.random`, which means that this mode **is not** cryptographically secure.
Does **not** maintain an internal buffer, which makes this mode ideal for single-use and/or short-lived environments.
Works in Node.js and all browsers.
Alphabet: ***Alphanumeric***
## Usage
```js
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`
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`](/bench) directory.
All items listed pass a validation step for length and uniqueness.
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:
1) It composes an output with hexadecimal pairs (from a cached dictionary) instead of single characters.
2) 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](https://github.com/lukeed/hexoid) - A slightly larger (190B) but extremely fast variant of this module with a different API
- [@lukeed/uuid](https://github.com/lukeed/uuid) - A tiny (230B), fast, and cryptographically secure UUID (V4) generator for Node and the browser
## Credits
Thank you [Matthew Mueller](https://github.com/matthewmueller) for gifting the `uid` name on npm.
This module was previously known as `foid` (fast object IDs).
## License
MIT © [Luke Edwards](https://lukeed.com)