首次提交

2026-07-13 12:06:16 +08:00
commit e3c810b1a6
1690 changed files with 228324 additions and 0 deletions
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christoph Guttandin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,55 @@
+# fast-unique-numbers
+
+**A module to create a set of unique numbers as fast as possible.**
+
+[![version](https://img.shields.io/npm/v/fast-unique-numbers.svg?style=flat-square)](https://www.npmjs.com/package/fast-unique-numbers)
+
+This module is meant to create unique numbers within a given [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) or [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set). To achieve that as fast as possible the resulting set of numbers will only contain integers. Additionally only small integers will be used for as long as possible. Small integers can be stored more efficiently by JavaScript engines like [SpiderMonkey](https://spidermonkey.dev/) or [V8](https://v8.dev).
+
+To verify the expected perfomance benefit an expectation test is used to make sure small integers do actually perform better in Chromium based browsers, Firefox and when using Node.js.
+
+## Usage
+
+This module is available on [npm](https://www.npmjs.com/package/fast-unique-numbers) and can be
+installed by running the following command:
+
+```shell
+npm install fast-unique-numbers
+```
+
+This module exports two functions.
+
+### addUniqueNumber()
+
+This function takes a `Set` of numbers as argument and appends a new unique number to it. It also returns that number.
+
+```js
+import { addUniqueNumber } from 'fast-unique-numbers';
+
+const set = new Set([1, 4, 8]);
+const uniqueNumber = addUniqueNumber(set);
+
+console.log(uniqueNumber); // 3
+console.log(set); // Set(4) { 1, 4, 8, 3 }
+```
+
+### generateUniqueNumber()
+
+This function can be used to generate a unique number which is not yet present in the given `Set` or is no key in the given `Map`. The resulting number gets not appended. It only gets returned.
+
+```js
+import { generateUniqueNumber } from 'fast-unique-numbers';
+
+const map = new Map([
+    [1, 'something'],
+    [4, 'something else']
+]);
+
+const uniqueNumber = generateUniqueNumber(map);
+
+console.log(uniqueNumber); // 2
+```
+
+## Security contact information
+
+To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.
@@ -0,0 +1,82 @@
+{
+    "author": "Christoph Guttandin",
+    "browser": "build/es5/bundle.js",
+    "bugs": {
+        "url": "https://github.com/chrisguttandin/fast-unique-numbers/issues"
+    },
+    "config": {
+        "commitizen": {
+            "path": "cz-conventional-changelog"
+        }
+    },
+    "dependencies": {
+        "@babel/runtime": "^7.29.2",
+        "tslib": "^2.8.1"
+    },
+    "description": "A module to create a set of unique numbers as fast as possible.",
+    "devDependencies": {
+        "@babel/cli": "^7.28.6",
+        "@babel/core": "^7.29.0",
+        "@babel/plugin-external-helpers": "^7.27.1",
+        "@babel/plugin-transform-runtime": "^7.29.0",
+        "@babel/preset-env": "^7.29.2",
+        "@commitlint/cli": "^20.5.0",
+        "@commitlint/config-angular": "^20.5.0",
+        "@rollup/plugin-babel": "^7.0.0",
+        "@vitest/browser-webdriverio": "^4.1.0",
+        "commitizen": "^4.3.1",
+        "cz-conventional-changelog": "^3.3.0",
+        "eslint": "^8.57.0",
+        "eslint-config-holy-grail": "^61.0.11",
+        "husky": "^9.1.7",
+        "lint-staged": "^16.4.0",
+        "prettier": "^3.8.1",
+        "rimraf": "^6.1.3",
+        "rollup": "^4.59.0",
+        "tinybench": "^4.0.1",
+        "tsconfig-holy-grail": "^15.0.3",
+        "tslint": "^6.1.3",
+        "tslint-config-holy-grail": "^56.0.7",
+        "typescript": "^5.9.3",
+        "vitest": "^4.1.0"
+    },
+    "engines": {
+        "node": ">=18.2.0"
+    },
+    "files": [
+        "build/es2019/",
+        "build/es5/",
+        "build/node/",
+        "src/"
+    ],
+    "homepage": "https://github.com/chrisguttandin/fast-unique-numbers",
+    "keywords": [
+        "performance",
+        "speed"
+    ],
+    "license": "MIT",
+    "main": "build/node/module.js",
+    "module": "build/es2019/module.js",
+    "name": "fast-unique-numbers",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/chrisguttandin/fast-unique-numbers.git"
+    },
+    "scripts": {
+        "build": "rimraf build/* && tsc --project src/tsconfig.json && rollup --config config/rollup/bundle.mjs && babel ./build/es2019 --config-file ./config/babel/build.json --out-dir ./build/node",
+        "lint": "npm run lint:config && npm run lint:src && npm run lint:test",
+        "lint:config": "eslint --config config/eslint/config.json --ext .cjs --ext .js --ext .mjs --report-unused-disable-directives config/",
+        "lint:src": "tslint --config config/tslint/src.json --project src/tsconfig.json src/*.ts src/**/*.ts",
+        "lint:test": "eslint --config config/eslint/test.json --ext .js --report-unused-disable-directives test/",
+        "prepare": "husky",
+        "prepublishOnly": "npm run build",
+        "test": "npm run lint && npm run build && npm run test:expectation-chrome && npm run test:expectation-firefox && npm run test:expectation-node && npm run test:unit-browser && npm run test:unit-node",
+        "test:expectation-chrome": "if [ \"$TYPE\" = \"\" -o \"$TYPE\" = \"expectation\" ] && [ \"$TARGET\" = \"\" -o \"$TARGET\" = \"chrome\" ]; then npx vitest --config config/vitest/expectation-chrome-current.ts; fi",
+        "test:expectation-firefox": "if [ \"$TYPE\" = \"\" -o \"$TYPE\" = \"expectation\" ] && [ \"$TARGET\" = \"\" -o \"$TARGET\" = \"firefox\" ]; then npx vitest --config config/vitest/expectation-firefox-current.ts; fi",
+        "test:expectation-node": "if [ \"$TYPE\" = \"\" -o \"$TYPE\" = \"expectation\" ] && [ \"$TARGET\" = \"\" -o \"$TARGET\" = \"node\" ]; then npx vitest --config config/vitest/expectation-node.ts; fi",
+        "test:unit-browser": "if [ \"$TYPE\" = \"\" -o \"$TYPE\" = \"unit\" ] && [ \"$TARGET\" = \"\" -o \"$TARGET\" = \"chrome\" -o \"$TARGET\" = \"firefox\" -o \"$TARGET\" = \"safari\" ]; then npx vitest --config config/vitest/unit.ts; fi",
+        "test:unit-node": "if [ \"$TYPE\" = \"\" -o \"$TYPE\" = \"unit\" ] && [ \"$TARGET\" = \"\" -o \"$TARGET\" = \"node\" ]; then npx vitest --browser.enabled false --config config/vitest/unit.ts; fi"
+    },
+    "types": "build/es2019/module.d.ts",
+    "version": "9.0.27"
+}
@@ -0,0 +1,11 @@
+import type { createGenerateUniqueNumber } from './generate-unique-number';
+
+export const createAddUniqueNumber = (generateUniqueNumber: ReturnType<typeof createGenerateUniqueNumber>) => {
+    return (set: Set<number>) => {
+        const number = generateUniqueNumber(set);
+
+        set.add(number);
+
+        return number;
+    };
+};
@@ -0,0 +1,7 @@
+export const createCache = (lastNumberWeakMap: WeakMap<Map<number, any> | Set<number>, number>) => {
+    return (collection: Map<number, any> | Set<number>, nextNumber: number) => {
+        lastNumberWeakMap.set(collection, nextNumber);
+
+        return nextNumber;
+    };
+};
@@ -0,0 +1,58 @@
+import type { createCache } from './cache';
+
+/*
+ * The value of the constant Number.MAX_SAFE_INTEGER equals (2 ** 53 - 1) but it
+ * is fairly new.
+ */
+const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER === undefined ? 9007199254740991 : Number.MAX_SAFE_INTEGER;
+const TWO_TO_THE_POWER_OF_TWENTY_NINE = 536870912;
+const TWO_TO_THE_POWER_OF_THIRTY = TWO_TO_THE_POWER_OF_TWENTY_NINE * 2;
+
+export const createGenerateUniqueNumber = (
+    cache: ReturnType<typeof createCache>,
+    lastNumberWeakMap: WeakMap<Map<number, any> | Set<number>, number>
+) => {
+    return (collection: Map<number, any> | Set<number>) => {
+        const lastNumber = lastNumberWeakMap.get(collection);
+
+        /*
+         * Let's try the cheapest algorithm first. It might fail to produce a new
+         * number, but it is so cheap that it is okay to take the risk. Just
+         * increase the last number by one or reset it to 0 if we reached the upper
+         * bound of SMIs (which stands for small integers). When the last number is
+         * unknown it is assumed that the collection contains zero based consecutive
+         * numbers.
+         */
+        let nextNumber = lastNumber === undefined ? collection.size : lastNumber < TWO_TO_THE_POWER_OF_THIRTY ? lastNumber + 1 : 0;
+
+        if (!collection.has(nextNumber)) {
+            return cache(collection, nextNumber);
+        }
+
+        /*
+         * If there are less than half of 2 ** 30 numbers stored in the collection,
+         * the chance to generate a new random number in the range from 0 to 2 ** 30
+         * is at least 50%. It's benifitial to use only SMIs because they perform
+         * much better in any environment based on V8.
+         */
+        if (collection.size < TWO_TO_THE_POWER_OF_TWENTY_NINE) {
+            while (collection.has(nextNumber)) {
+                nextNumber = Math.floor(Math.random() * TWO_TO_THE_POWER_OF_THIRTY);
+            }
+
+            return cache(collection, nextNumber);
+        }
+
+        // Quickly check if there is a theoretical chance to generate a new number.
+        if (collection.size > MAX_SAFE_INTEGER) {
+            throw new Error('Congratulations, you created a collection of unique numbers which uses all available integers!');
+        }
+
+        // Otherwise use the full scale of safely usable integers.
+        while (collection.has(nextNumber)) {
+            nextNumber = Math.floor(Math.random() * MAX_SAFE_INTEGER);
+        }
+
+        return cache(collection, nextNumber);
+    };
+};
@@ -0,0 +1,11 @@
+import { createAddUniqueNumber } from './factories/add-unique-number';
+import { createCache } from './factories/cache';
+import { createGenerateUniqueNumber } from './factories/generate-unique-number';
+
+const LAST_NUMBER_WEAK_MAP = new WeakMap<Map<number, any> | Set<number>, number>();
+
+const cache = createCache(LAST_NUMBER_WEAK_MAP);
+const generateUniqueNumber = createGenerateUniqueNumber(cache, LAST_NUMBER_WEAK_MAP);
+const addUniqueNumber = createAddUniqueNumber(generateUniqueNumber);
+
+export { addUniqueNumber, generateUniqueNumber };
@@ -0,0 +1,6 @@
+{
+    "compilerOptions": {
+        "isolatedModules": true
+    },
+    "extends": "tsconfig-holy-grail/src/tsconfig-universal"
+}