首次提交

2026-07-13 12:06:16 +08:00
commit e3c810b1a6
1690 changed files with 228324 additions and 0 deletions
@@ -0,0 +1,98 @@
+# hyperid
+
+[![Build Status](https://img.shields.io/github/workflow/status/mcollina/hyperid/CI)](https://github.com/mcollina/hyperid/actions)
+
+Uber-fast unique id generation, for Node.js and the browser.
+Here are the benchmarks:
+
+```
+crypto.randomUUID x 12,969,725 ops/sec ±0.88% (91 runs sampled)
+hashids process.hrtime x 419,350 ops/sec ±0.66% (94 runs sampled)
+hashids counter x 819,049 ops/sec ±0.58% (93 runs sampled)
+shortid x 40,820 ops/sec ±2.49% (87 runs sampled)
+crypto.random x 372,773 ops/sec ±2.39% (84 runs sampled)
+nid x 1,614,450 ops/sec ±0.38% (93 runs sampled)
+uuid.v4 x 1,446,051 ops/sec ±0.60% (98 runs sampled)
+napiRsUuid.v4 x 8,676,151 ops/sec ±0.49% (97 runs sampled)
+uuid.v1 x 2,051,072 ops/sec ±0.15% (99 runs sampled)
+nanoid x 4,293,733 ops/sec ±0.31% (97 runs sampled)
+hyperid - variable length x 25,937,129 ops/sec ±1.48% (91 runs sampled)
+hyperid - fixed length x 24,970,478 ops/sec ±1.48% (92 runs sampled)
+hyperid - fixed length, url safe x 25,856,735 ops/sec ±1.93% (92 runs sampled)
+
+Fastest is hyperid - variable length,hyperid - fixed length, url safe
+Slowest is shortid
+```
+
+_Note:_ Benchmark run with Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz and Node.js v22.0.0
+
+As you can see the native `crypto.randomUUID` is almost as fast as hyperid
+on Node.js v16, but not on v14.
+
+## Install
+
+```
+npm i hyperid --save
+```
+
+## Example
+
+```js
+'use strict'
+
+const hyperid = require('hyperid')
+const instance = hyperid()
+
+const id = instance()
+
+console.log(id)
+console.log(instance())
+console.log(hyperid.decode(id))
+console.log(hyperid.decode(instance()))
+```
+
+## API
+
+### hyperid([fixedLength || options])
+
+Returns a function to generate unique ids.
+The function can accept one of the following parameters:
+- `fixedLength: Boolean`
+If *fixedLength* is `true` the function will always generate an id
+that is 33 characters in length, by default `fixedLength` is `false`.
+- `options: Object`
+If `{ fixedLength: true }` is passed in, the function will always generate an id
+that is 33 characters in length, by default `fixedLength` is `false`.
+If `{ urlSafe: true }` is passed in, the function will generate url safe ids according to RFC4648.
+If `{ startFrom: <int> }` is passed in, the first counter will start from that
+number, which must be between 0 and 2147483647. Fractions are discarded, only the
+integer part matters.
+If `{ maxInt: <int> }` is passed in, the uuid will be re-generated once the *maxInt* is reached. The lesser the *maxInt*, higher the performance because of SMI (a V8 optimization).
+
+### instance()
+
+Returns an unique id.
+
+### instance.uuid
+
+The uuid used to generate the ids, it will change over time.
+If `maxInt` is provided in options, then it will regenerated every `maxInt`, else it will be regenerated every `Math.pow(2, 31) - 1` to keep the integer a SMI (a V8 optimization). 
+
+### hyperid.decode(id, [options])
+
+Decode the unique id into its two components, a `uuid` and a counter.
+If you are generating *url safe* ids, you must pass `{ urlSafe: true }` as option.
+It returns:
+
+```js
+{
+  uuid: '049b7020-c787-41bf-a1d2-a97612c11418',
+  count: 1
+}
+```
+
+This is aliased as `instance.decode`.
+
+## License
+
+MIT