sqids / sqids-javascript

Official JavaScript port of Sqids. Generate short unique IDs from numbers.

Sqids JavaScript

Sqids (pronounced "squids") is a small library that lets you generate unique IDs from numbers. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.

Features:

• Encode multiple numbers - generate short IDs from one or several non-negative numbers
• Quick decoding - easily decode IDs back into numbers
• Unique IDs - generate unique IDs by shuffling the alphabet once
• ID padding - provide minimum length to make IDs more uniform
• URL safe - auto-generated IDs do not contain common profanity
• Randomized output - Sequential input provides nonconsecutive IDs
• Many implementations - Support for 40+ programming languages

🧰 Use-cases

Good for:

• Generating IDs for public URLs (eg: link shortening)
• Generating IDs for internal systems (eg: event tracking)
• Decoding for quicker database lookups (eg: by primary keys)

Not good for:

• Sensitive data (this is not an encryption library)
• User IDs (can be decoded revealing user count)

🚀 Getting started

Install Sqids via:

yarn add sqids

👩‍💻 Examples

Simple encode & decode:

const sqids = new Sqids()
const id = sqids.encode([1, 2, 3]) // "86Rf07"
const numbers = sqids.decode(id) // [1, 2, 3]

Note 🚧 Because of the algorithm's design, multiple IDs can decode back into the same sequence of numbers. If it's important to your design that IDs are canonical, you have to manually re-encode decoded numbers and check that the generated ID matches.

Enforce a minimum length for IDs:

const sqids = new Sqids({
  minLength: 10,
})
const id = sqids.encode([1, 2, 3]) // "86Rf07xd4z"
const numbers = sqids.decode(id) // [1, 2, 3]

Randomize IDs by providing a custom alphabet:

const sqids = new Sqids({
  alphabet: 'FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE',
})
const id = sqids.encode([1, 2, 3]) // "B4aajs"
const numbers = sqids.decode(id) // [1, 2, 3]

Prevent specific words from appearing anywhere in the auto-generated IDs:

const sqids = new Sqids({
  blocklist: new Set(['86Rf07']),
})
const id = sqids.encode([1, 2, 3]) // "se8ojk"
const numbers = sqids.decode(id) // [1, 2, 3]

📝 License

MIT

sqids-javascript's Issues

Suggested strings for blocklist: suck and 5uck

As the tittle suggest, I'd recommend adding those two to the blocklist:
suck
5uck

What do you think?

How to check Error: Invalid ID like "https://sqids.org/playground"

i try to check if i change some value still i will get result or not
for example
const sqids = new Sqids({
alphabet: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789',
minLength:11
});

// encode
sqids.encode([1])
'UkLWZg9DAJQ'
// decode
sqids.decode('UkLWZg9DAJQ')

---

// the problem is when i change value from 'UkLWZg9DAJQ' to akLWZg9DAJQ still i will get value
sqids.decode('akLWZg9DAJQ')=>[368240725753862300]
BUT when i try it akLWZg9DAJQ with playground,"https://sqids.org/playground" it's give me Error: Invalid ID how can i do like playground

Submit to cdnjs

Hashids is there: https://cdnjs.com/libraries/hashids
Sqids should be added too

Impossible to filter out certain words because they are too short

I'm using a limited character set to avoid transcription errors: 34ACDEFHJKPRTXY.

This works great with Sqids and the effective list of profanity is quite small since there aren't that many words that can be formed with this alphabet.

However, also due to the limited character set, the triplet KKK shows up fairly often and I would like to block it. For instance: CPEYJDCYAHPF3AKKKR4DFCTH

But because the blocklist does not really block short words nested in longer id's, I've had to resolve to adding all of these to the blocklist:

3kkk
4kkk
akkk
ckkk
dkkk
ekkk
fkkk
hkkk
jkkk
kkkk
pkkk
rkkk
tkkk
xkkk
ykkk
kkk3
kkk4
kkka
kkkc
kkkd
kkke
kkkf
kkkh
kkkj
kkkk
kkkp
kkkr
kkkt
kkkx
kkky

etc. for every short word I want to block.

This is less than ideal. Is there a better way?

Support passing in a salt for unique IDs per object type

It would be useful to be able to pass a salt in the Sqids config in order to generate unique ids for different salt.

Similar to hashIds for PHP feature documented here https://github.com/vinkla/hashids?tab=readme-ov-file#making-your-output-ids-unique

Sqids does not support Node.js >= 16

When running the following code with Node.js 16, an error occurs:

const Sqids = require("sqids").default;

const sqids = new Sqids({ minLength: 6 });

The error has the following stack-trace:

ReferenceError: Blob is not defined
    at new Sqids (node_modules/sqids/cjs/sqids.js:576:9)

where Blob is being used. In Node.js 16, Blob is not a global object and needs to be imported using

import { Blob } from 'node:buffer';
// or const { Blob } = require('node:buffer');

Note that the example above is using CommonJS syntax, but this issue occurs when using ES6 imports and when trying to import from sqids/esm/sqids as well.

BigInt support

Right now max value is Number.MAX_SAFE_INTEGER, with no support for bigints. This is an issue for tracking this feature. Hashids has support for it here (for reference): https://github.com/niieani/hashids.js/blob/master/src/hashids.ts

Todos:

• Support in encode()/decode()
• Adjust maxValue()
• Add tests specifically for bigints
• Add an example of how to use bigints

Missing Node Support

hashIDs supported Node.js use, which makes sense in my opinion for this library. Removing Blob from the js code may be the solution to be able to use it in Node as well.

Output from hashids and sqids for the same input is different

To repro: https://stackblitz.com/edit/node-q4xnc5?file=index.mjs

I'm considering migrating from hashids to sqids but I don't know how to, if the output is different. I use hashids to generate urls and this will break existing ones

Support hex

Please support hex

ReferenceError: Blob is not defined (NodeJS 16)

It doesn't run in NodeJS, because Blob is used globally without being imported.

/home/toilal/projects/pysae/driver/node_modules/sqids/src/sqids.ts:584
    if (new Blob([alphabet]).size !== alphabet.length) {
    ^

ReferenceError: Blob is not defined
    at Sqids (/home/toilal/projects/pysae/driver/node_modules/sqids/src/sqids.ts:584:5)
   ...

Where is encodeHex()?

It would be nice to have encode/decode HEX values.

Create a function to check if the const encoded is valid

As an update, it is worth inserting a function that can validate the value being decoded. If this value is not created with the minLenght and Alphabet, it could return an empty value, or length == 0. This way we could receive n values , but only decode information that respects standards.

First push

Hey @niieani, I made a good mess in this repo (out of all the awesomeness you have going on in https://github.com/niieani/hashids.js)

A few notes:

• Tests have been replaced with those from the spec (maybe we should copy over your custom ones too?)
• I did not copy over src/tests/tests-mjs (mostly because I don't know what they are)
• I'll copy over the basic README (like the one Go has), but we should also copy over a lot of the details you have in the original README
• For tests I kept vitest in there (should we use something else?)

Do you think you could take a look when you get a chance so this can become a proper repo? In the meantime, I'm still cleaning up random bits and pieces.

Broken packaging: Unexpected token 'export'

How do we package all this stuff? Tests are passing, but when using via npm/yarn in external projects, getting:

.../node_modules/sqids/esm/sqids.js:1
export const defaultOptions = {