@sindresorhus/fnv1a 3.0.0 → 3.1.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 +27 -1
  2. package/index.js +40 -16
  3. package/package.json +3 -1
  4. package/readme.md +34 -3
package/index.d.ts CHANGED
@@ -5,11 +5,33 @@ export interface Options {
5
5
  @default 32
6
6
  */
7
7
  readonly size?: 32 | 64 | 128 | 256 | 512 | 1024;
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 enugh to hold the entire string, but performance will be improved if it is.
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;
8
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,10 @@ 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;
package/index.js CHANGED
@@ -19,30 +19,54 @@ const FNV_OFFSETS = {
19
19
  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
20
  };
21
21
 
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
- }
22
+ const cachedEncoder = new globalThis.TextEncoder();
26
23
 
24
+ function fnv1aUint8Array(uint8Array, size) {
25
+ const fnvPrime = FNV_PRIMES[size];
27
26
  let hash = FNV_OFFSETS[size];
27
+
28
+ // eslint-disable-next-line unicorn/no-for-loop -- This is a performance-sensitive loop
29
+ for (let index = 0; index < uint8Array.length; index++) {
30
+ hash ^= BigInt(uint8Array[index]);
31
+ hash = BigInt.asUintN(size, hash * fnvPrime);
32
+ }
33
+
34
+ return hash;
35
+ }
36
+
37
+ function fnv1aEncodeInto(string, size, utf8Buffer) {
38
+ if (utf8Buffer.length === 0) {
39
+ throw new Error('The `utf8Buffer` option must have a length greater than zero');
40
+ }
41
+
28
42
  const fnvPrime = FNV_PRIMES[size];
43
+ let hash = FNV_OFFSETS[size];
44
+ let remaining = string;
45
+
46
+ while (remaining.length > 0) {
47
+ const result = cachedEncoder.encodeInto(remaining, utf8Buffer);
48
+ remaining = remaining.slice(result.read);
49
+ for (let index = 0; index < result.written; index++) {
50
+ hash ^= BigInt(utf8Buffer[index]);
51
+ hash = BigInt.asUintN(size, hash * fnvPrime);
52
+ }
53
+ }
29
54
 
30
- // Handle Unicode code points > 0x7f
31
- let isUnicoded = false;
55
+ return hash;
56
+ }
32
57
 
33
- for (let index = 0; index < string.length; index++) {
34
- let characterCode = string.charCodeAt(index);
58
+ export default function fnv1a(value, {size = 32, utf8Buffer} = {}) {
59
+ if (!FNV_PRIMES[size]) {
60
+ throw new Error('The `size` option must be one of 32, 64, 128, 256, 512, or 1024');
61
+ }
35
62
 
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;
63
+ if (typeof value === 'string') {
64
+ if (utf8Buffer) {
65
+ return fnv1aEncodeInto(value, size, utf8Buffer);
41
66
  }
42
67
 
43
- hash ^= BigInt(characterCode);
44
- hash = BigInt.asUintN(size, hash * fnvPrime);
68
+ value = cachedEncoder.encode(value);
45
69
  }
46
70
 
47
- return hash;
71
+ return fnv1aUint8Array(value, size);
48
72
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sindresorhus/fnv1a",
3
- "version": "3.0.0",
3
+ "version": "3.1.0",
4
4
  "description": "FNV-1a non-cryptographic hash function",
5
5
  "license": "MIT",
6
6
  "repository": "sindresorhus/fnv1a",
@@ -12,6 +12,8 @@
12
12
  },
13
13
  "type": "module",
14
14
  "exports": "./index.js",
15
+ "types": "./index.d.ts",
16
+ "sideEffects": false,
15
17
  "engines": {
16
18
  "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
17
19
  },
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 enugh to hold the entire string, but performance will be improved if it is.
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