short-unique-id
Advanced tools
The short-unique-id npm package is a utility for generating short, unique, non-sequential ids. It is useful for creating unique identifiers for various purposes such as database keys, session tokens, and more.
Generate a unique ID
This feature allows you to generate a unique ID with the default settings. The generated ID is a short, unique string.
const ShortUniqueId = require('short-unique-id');
const uid = new ShortUniqueId();
console.log(uid());Custom length of the ID
This feature allows you to specify the length of the generated ID. In this example, the ID will be 10 characters long.
const ShortUniqueId = require('short-unique-id');
const uid = new ShortUniqueId({ length: 10 });
console.log(uid());Custom dictionary for ID generation
This feature allows you to use a custom dictionary for generating the ID. In this example, the ID will be generated using only hexadecimal characters.
const ShortUniqueId = require('short-unique-id');
const uid = new ShortUniqueId({ dictionary: '0123456789ABCDEF' });
console.log(uid());Generate multiple unique IDs
This feature allows you to generate multiple unique IDs at once. In this example, an array of 5 unique IDs is generated.
const ShortUniqueId = require('short-unique-id');
const uid = new ShortUniqueId();
const ids = Array.from({ length: 5 }, () => uid());
console.log(ids);The uuid package is a popular library for generating UUIDs (Universally Unique Identifiers). Unlike short-unique-id, which generates shorter IDs, uuid generates longer, more complex IDs that are globally unique. It is commonly used for creating unique identifiers in distributed systems.
The nanoid package is a small, secure, URL-friendly unique string ID generator. It is similar to short-unique-id in that it generates short, unique IDs, but it focuses on security and URL-friendliness. Nanoid is also highly customizable in terms of ID length and character set.
The cuid package is designed for generating collision-resistant IDs optimized for horizontal scaling and performance. It generates longer IDs compared to short-unique-id and includes features like timestamp and counter to ensure uniqueness even in distributed environments.
Tiny (6.7kB minified) no-dependency library for generating random or sequential UUID of any length with exceptionally minuscule probabilies of duplicate IDs.
const uid = new ShortUniqueId({ length: 10 });
uid.rnd(); // p0ZoB1FwH6
uid.rnd(); // mSjGCTfn8w
uid.rnd(); // yt4Xx5nHMB
// ...
// or
const { randomUUID } = new ShortUniqueId({ length: 10 });
randomUUID(); // e8Civ0HoDy
randomUUID(); // iPjiGoHXAK
randomUUID(); // n528gSMwTN
// ...
For example, using the default dictionary of numbers and letters (lower and upper case):
0,1,2,3,4,5,6,7,8,9,
a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z,
A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z
To put this into perspective:
You can calculate duplicate/collision probabilities using the included functions:
NOTE: 👆 On these links you will also find explanations for the math used within the functions.
This project is part of the Open Collective project Simply Hexagonal and is open to updates by its users, we ensure that PRs are relevant to the community. In other words, if you find a bug or want a new feature, please help us by becoming one of the contributors ✌️ ! See the contributing section.
Please consider:
In order to improve security compliance we have removed the ability to use a ShortUniqueId as a
function, i.e. const uid = new ShortUniqueId(); uid(); is no longer supported.
If you plan to upgrade to v5 make sure to refactor uid(); to uid.rnd(); in your code beforehand.
For more information regarding this decision you can view issue #53.
// js/ts
const uid = new ShortUniqueId();
const uidWithTimestamp = uid.stamp(32);
console.log(uidWithTimestamp);
// GDa608f973aRCHLXQYPTbKDbjDeVsSb3
const recoveredTimestamp = uid.parseStamp(uidWithTimestamp);
console.log(recoveredTimestamp);
// 2021-05-03T06:24:58.000Z
# cli
$ suid -s -l 42
lW611f30a2ky4276g3l8N7nBHI5AQ5rCiwYzU47HP2
$ suid -p lW611f30a2ky4276g3l8N7nBHI5AQ5rCiwYzU47HP2
2021-08-20T04:33:38.000Z
new ShortUniqueId())// instantiate using one of the default dictionary strings
const uid = new ShortUniqueId({
dictionary: 'hex',
});
console.log(uid.dict.join());
// 0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f
// or change the dictionary after instantiation
uid.setDictionary('alpha_upper');
console.log(uid.dict.join());
// A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z
Where $r is random UUID, $s is sequential UUID, and $t is timestamp UUID:
const timestamp = new Date('4-01-29T03:21:21.000Z');
const result = uid.formattedUUID('Time: $t0 ID: $s2-$r4', timestamp); // timestamp is optional
console.log(result);
// Time: 63d5e631 ID: 0b-aaab
Example of using .validate() method:
// Instantiate using one of the default dictionary strings
const uid = new ShortUniqueId({
dictionary: 'hex',
});
const uuid = uid.stamp(32); // Generate a UUID
// Validate the generated UUID against the instance dictionary
const isValid = uid.validate(uuid);
console.log(`Is the UUID valid? ${isValid}`);
// ---
// Validate the generated UUID against the provided dictionary
const customDictionary = ['a', 'b', /* ... */];
const isValid = uid.validate(uuid, customDictionary);
console.log(`Is the UUID valid? ${isValid}`);
$ npm install --global short-unique-id
$ suid -h
# Usage:
# node short-unique-id [OPTION]
#
# Options:
# -l, --length=ARG character length of the uid to generate.
# -s, --stamp include timestamp in uid (must be used with --length (-l) of 10 or more).
# -t, --timestamp=ARG custom timestamp to parse (must be used along with -s, --stamp, -f, or --format).
# -f, --format=ARG string representing custom format to generate id with.
# -p, --parse=ARG extract timestamp from stamped uid (ARG).
# -d, --dictionaryJson=ARG json file with dictionary array.
# -h, --help display this help
Add to your project:
// ES6 / TypeScript Import
import ShortUniqueId from 'short-unique-id';
// Node.js require
const ShortUniqueId = require('short-unique-id');
// Deno (web module) Import
import ShortUniqueId from 'https://esm.sh/short-unique-id';
Instantiate and use:
//Instantiate
const uid = new ShortUniqueId();
// Random UUID
console.log(uid.rnd());
// Sequential UUID
console.log(uid.seq());
alternatively using destructuring assignment:
// Instantiate and destructure (long method name recommended for code readability)
const { randomUUID, sequentialUUID } = new ShortUniqueId();
// Random UUID
console.log(randomUUID());
// Sequential UUID
console.log(sequentialUUID());
NOTE: we made sure to use bind() on all ShortUniqueId methods to ensure that any options
passed when creating the instance will be respected by the destructured methods.
<!-- Add source (minified 4.6kB) -->
<script src="https://cdn.jsdelivr.net/npm/short-unique-id@latest/dist/short-unique-id.min.js"></script>
<!-- Usage -->
<script>
// Instantiate
var uid = new ShortUniqueId();
// Random UUID
document.write(uid.rnd());
// Sequential UUID
document.write(uid.seq());
</script>
Options can be passed when instantiating uid:
const options = { ... };
const uid = new ShortUniqueId(options);
For more information take a look at the docs.
You can find the docs and online generator at:
This largely depends on the given dictionary and the selected UUID length.
Out of the box this library provides a shuffled dictionary of digits from 0 to 9, as well as the alphabet from a to z both in UPPER and lower case, with a default UUID length of 6. That gives you a total of 56,800,235,584 possible UUIDs.
So, given the previous values, the probability of generating a duplicate in 1,000,000 rounds is ~0.00000002, or about 1 in 50,000,000.
If you change the dictionary and/or the UUID length then we have provided
the function collisionProbability() function to calculate the probability
of hitting a duplicate in a given number of rounds (a collision) and the
function uniqueness() which provides a score (from 0 to 1) to rate the
"quality" of the combination of given dictionary and UUID length (the closer
to 1, higher the uniqueness and thus better the quality).
To find out more about the math behind these functions please refer to the API Reference.
This repo and npm package started as a straight up manual transpilation to ES6 of the short-uid npm package by Ankit Kuwadekar.
Since this package is now reporting 200k+ npm weekly downloads and 16M+ weekly cdn hits, we've gone ahead and re-written the whole of it in TypeScript and made sure to package dist modules compatible with Deno, Node.js and all major Browsers.
Clone this repo:
# SSH
git clone git@github.com:jeanlescure/short-unique-id.git
# HTTPS
git clone https://github.com/jeanlescure/short-unique-id.git
Tests run using:
pnpm test
In order to publish the latest changes you must build the distribution files:
pnpm build
Then commit all changes and run the release script:
pnpm release
Yes, thank you! This plugin is community-driven, most of its features are from different authors.
Please update the docs and tests and add your name to the package.json file.
Thanks goes to these wonderful people (emoji key):
| 
| 
| 
| ||||
| 
| 
| 
| ||||
| 
| 
| 
| ||||
| 
| 
|
Copyright (c) 2018-2024 Short Unique ID Contributors.
Licensed under the Apache License 2.0.
FAQs
Generate random or sequential UUID of any length
We found that short-unique-id demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.