cleanup

README.md

@@ -66,9 +66,9 @@ Decoding is the same process but in reverse. A few things worth noting:
 Implementations of new languages are more than welcome! To start:
 
 1. Make sure you have access to the org's repo. The format is `https://github.com/sqids/sqids-[LANGUAGE]`. If you don't have access, ask one of the maintainers to add you; if it doesn't exist, ask [@4kimov](https://github.com/4kimov).
-1. The main spec is here: <https://github.com/sqids/sqids-spec/blob/main/src/index.ts>. It's under 400 lines of code and heavily commented. Comments are there for clarity, they don't have to exist in your own implementation.
+1. The main spec is here: <https://github.com/sqids/sqids-spec/blob/main/src/index.ts>. It's ~300 lines of code and heavily commented. Comments are there for clarity, they don't have to exist in your own implementation.
 1. Please use the blocklist from <https://github.com/sqids/sqids-blocklist> (copy and paste the output it gives you into your own code). It will contain the most up-to-date list. Do not copy and paste the blocklist from other implementations, as they might not be up-to-date.
-1. Be sure to implement unit tests. We want to make sure all implementations produce the same IDs. Unit tests are here: <https://github.com/sqids/sqids-spec/tree/main/tests>.
+1. Be sure to implement unit tests. We want to make sure all implementations produce the same IDs. Unit tests are here: <https://github.com/sqids/sqids-spec/tree/main/tests>. You **do not need to port tests in the "internal" folder**; they are there to test the algorithm itself.
 1. If you're publishing to a package manager, please add a co-maintainer so more than one person has access.
 1. When done, please let [@4kimov](https://github.com/4kimov) know so we can update the website.
 
@@ -77,6 +77,7 @@ Implementations of new languages are more than welcome! To start:
 - The reason `prefix` character is used is to randomize sequential inputs (eg: [0, 1], [0, 2], [0, 3]). Without the extra `prefix` character embedded into the ID, the output would start with the same characters.
 - Internal shuffle function does not use random input. It consistently produces the same output.
 - If new words are blocked (or removed from the blocklist), the `encode()` function might produce new IDs, but the `decode()` function would still work for old/blocked IDs, plus new IDs. So, there's more than one ID that can be produced for same numbers.
+- FAQ section is here: <https://sqids.org/faq>
 
 ## 🍻 License
 

src/index.ts

@@ -12,7 +12,7 @@ export const defaultOptions = {
 	// `minLength` is the minimum length IDs should be (`u8` type)
 	minLength: 0,
 	// a list of words that should not appear anywhere in the IDs
-	blocklist: new Set<string>()
+	blocklist: new Set<string>(defaultBlocklist)
 };
 
 export default class Sqids {
@@ -23,7 +23,7 @@ export default class Sqids {
 	constructor(options?: SqidsOptions) {
 		const alphabet = options?.alphabet ?? defaultOptions.alphabet;
 		const minLength = options?.minLength ?? defaultOptions.minLength;
-		const blocklist = options?.blocklist ?? new Set<string>(defaultBlocklist);
+		const blocklist = options?.blocklist ?? defaultOptions.blocklist;
 
 		// alphabet cannot contain multibyte characters
 		if (new Blob([alphabet]).size != alphabet.length) {

tests/internal/README.md

@@ -0,0 +1,2 @@
+Tests in this folder are not necessary for individual implementations to implement
+since they test the algorithm, and not the implementations themselves

tests/shuffle.test.ts → tests/internal/shuffle.test.ts

@@ -1,8 +1,5 @@
 import { expect, test } from 'vitest';
-import { defaultOptions } from '../src/index.ts';
-
-// `shuffle` is an internal function, so these are tests to check how well it shuffles
-// there's no need for individual implementations to copy over these tests
+import { defaultOptions } from '../../src/index.ts';
 
 const shuffle = (alphabet: string): string => {
 	const chars = alphabet.split('');

tests/internal/uniques.test.ts

@@ -0,0 +1,75 @@
+import { expect, test } from 'vitest';
+import Sqids, { defaultOptions } from '../../src/index.ts';
+
+// @NOTE: "uniques, with blocked words" is auto-tested since a lot of these big ids
+// will match some words on the blocklist and will be re-generated anyway
+
+const upTo = 100_000_000;
+
+test('uniques', () => {
+	const sqids = new Sqids();
+
+	const idSet = new Set<string>();
+	const numbersSet = new Set<string>();
+
+	for (let i = 0; i != upTo; i++) {
+		const numbers = [i];
+
+		const id = sqids.encode(numbers);
+
+		const decodedNumbers = sqids.decode(id);
+		expect.soft(decodedNumbers).toEqual(numbers);
+
+		idSet.add(id);
+		numbersSet.add(decodedNumbers.join(','));
+	}
+
+	expect.soft(idSet.size).toBe(upTo);
+	expect.soft(numbersSet.size).toBe(upTo);
+});
+
+test('uniques, with padding', () => {
+	const sqids = new Sqids({
+		minLength: defaultOptions.alphabet.length
+	});
+
+	const idSet = new Set<string>();
+	const numbersSet = new Set<string>();
+
+	for (let i = 0; i != upTo; i++) {
+		const numbers = [i];
+
+		const id = sqids.encode(numbers);
+
+		const decodedNumbers = sqids.decode(id);
+		expect.soft(decodedNumbers).toEqual(numbers);
+
+		idSet.add(id);
+		numbersSet.add(decodedNumbers.join(','));
+	}
+
+	expect.soft(idSet.size).toBe(upTo);
+	expect.soft(numbersSet.size).toBe(upTo);
+});
+
+test('uniques, with multiple numbers', () => {
+	const sqids = new Sqids();
+
+	const idSet = new Set<string>();
+	const numbersSet = new Set<string>();
+
+	for (let i = 0; i != upTo; i++) {
+		const numbers = [0, i, i + 1, 100, 999999999];
+
+		const id = sqids.encode(numbers);
+
+		const decodedNumbers = sqids.decode(id);
+		expect.soft(decodedNumbers).toEqual(numbers);
+
+		idSet.add(id);
+		numbersSet.add(decodedNumbers.join(','));
+	}
+
+	expect.soft(idSet.size).toBe(upTo);
+	expect.soft(numbersSet.size).toBe(upTo);
+});