Gathering detailed insights and metrics for short-unique-id
Short Unique ID (UUID) generation library. Available in NPM.
Installations
npm install short-unique-idDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS
Node Version
20.12.1
NPM Version
10.5.0
Score
99.7
Supply Chain
100
Quality
79
Maintenance
100
Vulnerability
100
License
Releases
24
Contributors
7
Unable to fetch Contributors
Languages
5
TypeScript
HTML
JavaScript
Shell
Handlebars
TypeScript (78.45%)
HTML (13.7%)
JavaScript (4.58%)
Shell (2.58%)
Handlebars (0.69%)
Developer
Download Statistics
Total Downloads
42,635,674
Last Day
153,558
Last Week
628,639
Last Month
2,871,892
Last Year
28,222,492
GitHub Statistics
406 Stars
161 Commits
20 Forks
4 Watching
1 Branches
7 Contributors
Bundle Size
7.71 kB
Minified
2.49 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
5.2.0
Package Id
short-unique-id@5.2.0
Unpacked Size
144.88 kB
Size
68.39 kB
File Count
10
NPM Version
10.5.0
Node Version
20.12.1
Publised On
30 Apr 2024
Total Downloads
Cumulative downloads
Total Downloads
42,635,674
Last day
0.1%
153,558
Compared to previous day
Last week
-16.5%
628,639
Compared to previous week
Last month
-1.3%
2,871,892
Compared to previous month
Last year
153.1%
28,222,492
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Versions
Short Unique ID (UUID) Generating Library
Tiny (6.7kB minified) no-dependency library for generating random or sequential UUID of any length with exceptionally minuscule probabilies of duplicate IDs.
1const uid = new ShortUniqueId({ length: 10 }); 2uid.rnd(); // p0ZoB1FwH6 3uid.rnd(); // mSjGCTfn8w 4uid.rnd(); // yt4Xx5nHMB 5// ... 6 7// or 8 9const { randomUUID } = new ShortUniqueId({ length: 10 }); 10randomUUID(); // e8Civ0HoDy 11randomUUID(); // iPjiGoHXAK 12randomUUID(); // n528gSMwTN 13// ...
For example, using the default dictionary of numbers and letters (lower and upper case):
1 0,1,2,3,4,5,6,7,8,9, 2 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, 3 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
- if you generate a unique ID of 16 characters (half of the standard UUID of 32 characters)
- generating 100 unique IDs per second
It would take ~10 thousand years to have a 1% probability of at least one collision!
To put this into perspective:
- 73 years is the (global) average life expectancy of a human being
- 120 years ago no human ever had set foot on either of the Earth's poles
- 480 years ago Nicolaus Copernicus was still working on his theory of the Earth revolving around the Sun
- 1000 years ago there was no such thing as government-issued paper money (and wouldn't be for about a century)
- 5000 years ago the global population of humans was under 50 million (right now Mexico has a population of 127 million)
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.
Open source notice
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.
Like this module? ❤
Please consider:
- Buying me a coffee ☕
- Supporting me on Patreon 🏆
- Starring this repo on Github 🌟
📣 v5 Notice
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.
Features
Ability to generate UUIDs that contain a timestamp which can be extracted:
1// js/ts 2 3const uid = new ShortUniqueId(); 4 5const uidWithTimestamp = uid.stamp(32); 6console.log(uidWithTimestamp); 7// GDa608f973aRCHLXQYPTbKDbjDeVsSb3 8 9const recoveredTimestamp = uid.parseStamp(uidWithTimestamp); 10console.log(recoveredTimestamp); 11// 2021-05-03T06:24:58.000Z
1# cli 2 3$ suid -s -l 42 4 5 lW611f30a2ky4276g3l8N7nBHI5AQ5rCiwYzU47HP2 6 7$ suid -p lW611f30a2ky4276g3l8N7nBHI5AQ5rCiwYzU47HP2 8 9 2021-08-20T04:33:38.000Z
Default dictionaries (generated on the spot to reduce memory footprint and avoid dictionary injection vulnerabilities):
- number
- alpha
- alpha_lower
- alpha_upper
- alphanum (default when no dictionary is provided to
new ShortUniqueId()) - alphanum_lower
- alphanum_upper
- hex
1// instantiate using one of the default dictionary strings 2const uid = new ShortUniqueId({ 3 dictionary: 'hex', 4}); 5 6console.log(uid.dict.join()); 7// 0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f 8 9// or change the dictionary after instantiation 10uid.setDictionary('alpha_upper'); 11 12console.log(uid.dict.join()); 13// 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
Ability to use custom formatting
Where $r is random UUID, $s is sequential UUID, and $t is timestamp UUID:
1const timestamp = new Date('4-01-29T03:21:21.000Z'); 2const result = uid.formattedUUID('Time: $t0 ID: $s2-$r4', timestamp); // timestamp is optional 3 4console.log(result); 5// Time: 63d5e631 ID: 0b-aaab
Ability to validate UUIDs against the instance dictionary or a provided dictionary
Example of using .validate() method:
1// Instantiate using one of the default dictionary strings 2const uid = new ShortUniqueId({ 3 dictionary: 'hex', 4}); 5 6const uuid = uid.stamp(32); // Generate a UUID 7 8// Validate the generated UUID against the instance dictionary 9const isValid = uid.validate(uuid); 10 11console.log(`Is the UUID valid? ${isValid}`); 12 13// --- 14 15// Validate the generated UUID against the provided dictionary 16const customDictionary = ['a', 'b', /* ... */]; 17const isValid = uid.validate(uuid, customDictionary); 18 19console.log(`Is the UUID valid? ${isValid}`);
Use in CLI
1$ npm install --global short-unique-id 2 3$ suid -h 4 5# Usage: 6# node short-unique-id [OPTION] 7# 8# Options: 9# -l, --length=ARG character length of the uid to generate. 10# -s, --stamp include timestamp in uid (must be used with --length (-l) of 10 or more). 11# -t, --timestamp=ARG custom timestamp to parse (must be used along with -s, --stamp, -f, or --format). 12# -f, --format=ARG string representing custom format to generate id with. 13# -p, --parse=ARG extract timestamp from stamped uid (ARG). 14# -d, --dictionaryJson=ARG json file with dictionary array. 15# -h, --help display this help
Use as module
Add to your project:
1// ES6 / TypeScript Import 2import ShortUniqueId from 'short-unique-id'; 3 4// Node.js require 5const ShortUniqueId = require('short-unique-id'); 6 7// Deno (web module) Import 8import ShortUniqueId from 'https://esm.sh/short-unique-id';
Instantiate and use:
1//Instantiate 2const uid = new ShortUniqueId(); 3 4// Random UUID 5console.log(uid.rnd()); 6 7// Sequential UUID 8console.log(uid.seq());
alternatively using destructuring assignment:
1// Instantiate and destructure (long method name recommended for code readability) 2const { randomUUID, sequentialUUID } = new ShortUniqueId(); 3 4// Random UUID 5console.log(randomUUID()); 6 7// Sequential UUID 8console.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.
Use in browser
1<!-- Add source (minified 4.6kB) --> 2<script src="https://cdn.jsdelivr.net/npm/short-unique-id@latest/dist/short-unique-id.min.js"></script> 3 4<!-- Usage --> 5<script> 6 // Instantiate 7 var uid = new ShortUniqueId(); 8 9 // Random UUID 10 document.write(uid.rnd()); 11 12 // Sequential UUID 13 document.write(uid.seq()); 14</script>
Options
Options can be passed when instantiating uid:
1const options = { ... }; 2 3const uid = new ShortUniqueId(options);
For more information take a look at the docs.
Available for
Documentation with Online Short UUID Generator
You can find the docs and online generator at:
What is the probability of generating the same id again?
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.
Acknowledgement and platform support
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.
Sponsors
Development
Clone this repo:
1# SSH 2git clone git@github.com:jeanlescure/short-unique-id.git 3 4# HTTPS 5git clone https://github.com/jeanlescure/short-unique-id.git
Tests run using:
pnpm test
Build
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
Contributing
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.
Contributors ✨
Thanks goes to these wonderful people (emoji key):
| 
| 
| 
| ||||
| 
| 
| 
| ||||
| 
| 
| 
| ||||
| 
| 
|
License
Copyright (c) 2018-2024 Short Unique ID Contributors.
Licensed under the Apache License 2.0.
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
7 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-78xj-cgh5-2h22
- Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
Found 0/28 approved changesets -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/main.yml:1
- Info: no jobLevel write permissions found
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/simplyhexagonal/short-unique-id/main.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/simplyhexagonal/short-unique-id/main.yml/main?enable=pin
- Warn: npmCommand not pinned by hash: .github/workflows/main.yml:34
- Info: 0 out of 2 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 1 npmCommand dependencies pinned
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
license file not detected
Details
- Warn: project does not have a license file
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
Project has not signed or included provenance with any releases.
Details
- Warn: release artifact v5.2.0 not signed: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/153580317
- Warn: release artifact v5.1.1 not signed: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/153373314
- Warn: release artifact v4.4.2 not signed: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/49359920
- Warn: release artifact v4.4.0 not signed: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/49096619
- Warn: release artifact v4.3.8 not signed: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/48640625
- Warn: release artifact v5.2.0 does not have provenance: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/153580317
- Warn: release artifact v5.1.1 does not have provenance: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/153373314
- Warn: release artifact v4.4.2 does not have provenance: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/49359920
- Warn: release artifact v4.4.0 does not have provenance: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/49096619
- Warn: release artifact v4.3.8 does not have provenance: https://api.github.com/repos/simplyhexagonal/short-unique-id/releases/48640625
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'main'
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 2 are checked with a SAST tool
Score
2.3
/10
Last Scanned on 2025-01-27
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More