@sindresorhus/fnv1a 3.0.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/index.d.ts +31 -3
  2. package/index.js +44 -17
  3. package/package.json +10 -12
  4. package/readme.md +34 -3
package/index.d.ts CHANGED
@@ -1,15 +1,37 @@
1
- export interface Options {
1
+ export type Options = {
2
2
  /**
3
3
  The bit size of the hash.
4
4
 
5
5
  @default 32
6
6
  */
7
7
  readonly size?: 32 | 64 | 128 | 256 | 512 | 1024;
8
- }
8
+
9
+ /**
10
+ A Uint8Array used to encode the string into UTF-8 bytes.
11
+
12
+ This array can be reused across calls to `fnv1a`. Doing so will improve performance because it avoids allocating a new Uint8Array when encoding the string.
13
+
14
+ The size of the array does not have to be large enough to hold the entire string, but performance will be improved if it is. It must have a length of at least 4, which is the largest size of a single character in UTF-8.
15
+
16
+ This option is only used when `value` is a string.
17
+
18
+ @example
19
+ ```
20
+ import fnv1a from '@sindresorhus/fnv1a';
21
+
22
+ const utf8Buffer = new Uint8Array(100);
23
+
24
+ fnv1a('🦄🌈', {size: 32, utf8Buffer});
25
+ //=> 2868248295n
26
+ ```
27
+ */
28
+ readonly utf8Buffer?: Uint8Array;
29
+ };
9
30
 
10
31
  /**
11
32
  [FNV-1a](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) non-cryptographic hash function.
12
33
 
34
+ @param value - A string or UTF-8 bytes.
13
35
  @returns The hash as a positive `BigInt`.
14
36
 
15
37
  @example
@@ -24,6 +46,12 @@ fnv1a('🦄🌈', {size: 128});
24
46
 
25
47
  Number(fnv1a('🦄🌈', {size: 32}));
26
48
  //=> 2868248295
49
+
50
+ const bytes = new Uint8Array([240, 159, 166, 132, 240, 159, 140, 136]);
51
+ fnv1a(bytes, {size: 32});
52
+ //=> 2868248295n
27
53
  ```
28
54
  */
29
- export default function fnv1a(string: string, options?: Options): bigint;
55
+ export default function fnv1a(value: string | Uint8Array, options?: Options): bigint;
56
+
57
+ export {}; // eslint-disable-line unicorn/require-module-specifiers -- It stops the implicit export of the declarations without `export`.
package/index.js CHANGED
@@ -1,5 +1,7 @@
1
1
  // FNV_PRIMES and FNV_OFFSETS from
2
- // http://www.isthe.com/chongo/tech/comp/fnv/index.html#FNV-param
2
+ // https://www.isthe.com/chongo/tech/comp/fnv/index.html#FNV-param
3
+
4
+ /* eslint-disable no-bitwise -- FNV-1a is defined in terms of XOR. Unlike the 32-bit number operators, `^=` on BigInt is exact and never coerces its operands to int32. */
3
5
 
4
6
  const FNV_PRIMES = {
5
7
  32: 16_777_619n,
@@ -19,30 +21,55 @@ const FNV_OFFSETS = {
19
21
  1024: 14_197_795_064_947_621_068_722_070_641_403_218_320_880_622_795_441_933_960_878_474_914_617_582_723_252_296_732_303_717_722_150_864_096_521_202_355_549_365_628_174_669_108_571_814_760_471_015_076_148_029_755_969_804_077_320_157_692_458_563_003_215_304_957_150_157_403_644_460_363_550_505_412_711_285_966_361_610_267_868_082_893_823_963_790_439_336_411_086_884_584_107_735_010_676_915n,
20
22
  };
21
23
 
22
- export default function fnv1a(string, {size = 32} = {}) {
23
- if (!FNV_PRIMES[size]) {
24
- throw new Error('The `size` option must be one of 32, 64, 128, 256, 512, or 1024');
25
- }
24
+ const cachedEncoder = new TextEncoder();
26
25
 
26
+ function fnv1aUint8Array(uint8Array, size) {
27
+ const fnvPrime = FNV_PRIMES[size];
27
28
  let hash = FNV_OFFSETS[size];
29
+
30
+ // eslint-disable-next-line unicorn/no-for-loop -- This is a performance-sensitive loop
31
+ for (let index = 0; index < uint8Array.length; index++) {
32
+ hash ^= BigInt(uint8Array[index]);
33
+ hash = BigInt.asUintN(size, hash * fnvPrime);
34
+ }
35
+
36
+ return hash;
37
+ }
38
+
39
+ function fnv1aEncodeInto(string, size, utf8Buffer) {
40
+ // `encodeInto` will not write a partial code point, so a buffer that cannot hold the next one reads nothing and the loop would never finish. A code point is at most 4 bytes in UTF-8.
41
+ if (utf8Buffer.length < 4) {
42
+ throw new RangeError('The `utf8Buffer` option must have a length of at least 4');
43
+ }
44
+
28
45
  const fnvPrime = FNV_PRIMES[size];
46
+ let hash = FNV_OFFSETS[size];
47
+ let remaining = string;
29
48
 
30
- // Handle Unicode code points > 0x7f
31
- let isUnicoded = false;
49
+ while (remaining.length > 0) {
50
+ const result = cachedEncoder.encodeInto(remaining, utf8Buffer);
51
+ remaining = remaining.slice(result.read);
52
+ for (let index = 0; index < result.written; index++) {
53
+ hash ^= BigInt(utf8Buffer[index]);
54
+ hash = BigInt.asUintN(size, hash * fnvPrime);
55
+ }
56
+ }
32
57
 
33
- for (let index = 0; index < string.length; index++) {
34
- let characterCode = string.charCodeAt(index);
58
+ return hash;
59
+ }
35
60
 
36
- // Non-ASCII characters trigger the Unicode escape logic
37
- if (characterCode > 0x7F && !isUnicoded) {
38
- string = unescape(encodeURIComponent(string));
39
- characterCode = string.charCodeAt(index);
40
- isUnicoded = true;
61
+ export default function fnv1a(value, {size = 32, utf8Buffer} = {}) {
62
+ if (!Object.hasOwn(FNV_PRIMES, size)) {
63
+ throw new Error('The `size` option must be one of 32, 64, 128, 256, 512, or 1024');
64
+ }
65
+
66
+ if (typeof value === 'string') {
67
+ if (utf8Buffer) {
68
+ return fnv1aEncodeInto(value, size, utf8Buffer);
41
69
  }
42
70
 
43
- hash ^= BigInt(characterCode);
44
- hash = BigInt.asUintN(size, hash * fnvPrime);
71
+ value = cachedEncoder.encode(value);
45
72
  }
46
73
 
47
- return hash;
74
+ return fnv1aUint8Array(value, size);
48
75
  }
package/package.json CHANGED
@@ -1,22 +1,22 @@
1
1
  {
2
2
  "name": "@sindresorhus/fnv1a",
3
- "version": "3.0.0",
3
+ "version": "4.0.0",
4
4
  "description": "FNV-1a non-cryptographic hash function",
5
5
  "license": "MIT",
6
6
  "repository": "sindresorhus/fnv1a",
7
7
  "funding": "https://github.com/sponsors/sindresorhus",
8
- "author": {
9
- "name": "Sindre Sorhus",
10
- "email": "sindresorhus@gmail.com",
11
- "url": "https://sindresorhus.com"
12
- },
8
+ "author": "Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)",
13
9
  "type": "module",
14
- "exports": "./index.js",
10
+ "exports": {
11
+ "types": "./index.d.ts",
12
+ "default": "./index.js"
13
+ },
14
+ "sideEffects": false,
15
15
  "engines": {
16
- "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
16
+ "node": ">=22"
17
17
  },
18
18
  "scripts": {
19
- "test": "xo && ava && tsd"
19
+ "test": "xo && node --test"
20
20
  },
21
21
  "files": [
22
22
  "index.js",
@@ -41,8 +41,6 @@
41
41
  "bigint"
42
42
  ],
43
43
  "devDependencies": {
44
- "ava": "3.15.0",
45
- "tsd": "0.17.0",
46
- "xo": "0.44.0"
44
+ "xo": "^5.0.1"
47
45
  }
48
46
  }
package/readme.md CHANGED
@@ -8,8 +8,8 @@ FNV hashes are designed to be fast while maintaining a low collision rate. The F
8
8
 
9
9
  ## Install
10
10
 
11
- ```
12
- $ npm install @sindresorhus/fnv1a
11
+ ```sh
12
+ npm install @sindresorhus/fnv1a
13
13
  ```
14
14
 
15
15
  ## Usage
@@ -25,16 +25,26 @@ fnv1a('🦄🌈', {size: 128});
25
25
 
26
26
  Number(fnv1a('🦄🌈', {size: 32}));
27
27
  //=> 2868248295
28
+
29
+ const bytes = new Uint8Array([240, 159, 166, 132, 240, 159, 140, 136]);
30
+ fnv1a(bytes, {size: 32});
31
+ //=> 2868248295n
28
32
  ```
29
33
 
30
34
  ## API
31
35
 
32
- ### fnv1a(string, options?)
36
+ ### fnv1a(value, options?)
33
37
 
34
38
  Returns the hash as a positive `BigInt`.
35
39
 
36
40
  If you need it as a `number`, use `32` as `size` and wrap the return value in `Number(…)`.
37
41
 
42
+ #### value
43
+
44
+ Type: `string | Uint8Array`
45
+
46
+ A string or UTF-8 bytes.
47
+
38
48
  #### options
39
49
 
40
50
  Type: `object`
@@ -47,6 +57,27 @@ Default: `32`
47
57
 
48
58
  The bit size of the hash.
49
59
 
60
+ ##### utf8Buffer
61
+
62
+ Type: `Uint8Array`
63
+
64
+ A Uint8Array used to encode the string into UTF-8 bytes.
65
+
66
+ This array can be reused across calls to `fnv1a`. Doing so will improve performance because it avoids allocating a new Uint8Array when encoding the string.
67
+
68
+ The size of the array does not have to be large enough to hold the entire string, but performance will be improved if it is. It must have a length of at least 4, which is the largest size of a single character in UTF-8.
69
+
70
+ This option is only used when `value` is a string.
71
+
72
+ ```js
73
+ import fnv1a from '@sindresorhus/fnv1a';
74
+
75
+ const utf8Buffer = new Uint8Array(100);
76
+
77
+ fnv1a('🦄🌈', {size: 32, utf8Buffer});
78
+ //=> 2868248295n
79
+ ```
80
+
50
81
  ## Related
51
82
 
52
83
  - [djb2a](https://github.com/sindresorhus/djb2a) - DJB2a non-cryptographic hash function