@keyv/bigmap 1.1.0 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-# @keyv/redis [<img width="100" align="right" src="https://jaredwray.com/images/keyv-symbol.svg" alt="keyv">](https://github.com/jaredwra/keyv)
+# @keyv/bigmap [<img width="100" align="right" src="https://jaredwray.com/images/keyv-symbol.svg" alt="keyv">](https://github.com/jaredwra/keyv)
 
 > Bigmap for Keyv
 
@@ -18,7 +18,6 @@
 * Maintained regularly with a focus on performance and reliability.
 
 # Table of Contents
-
 - [Features](#features)
 - [Installation](#installation)
 - [Overview](#overview)
@@ -26,38 +25,37 @@
 - [Custom Store Size](#custom-store-size)
 - [Custom Hash Function](#custom-hash-function)
 - [Iteration](#iteration)
-  - [For...of Loop](#forof-loop)
-  - [forEach](#foreach)
-  - [Keys, Values, and Entries](#keys-values-and-entries)
+	- [For...of Loop](#forof-loop)
+	- [forEach](#foreach)
+	- [Keys, Values, and Entries](#keys-values-and-entries)
 - [Advanced Features](#advanced-features)
-  - [Type Safety with Generics](#type-safety-with-generics)
-  - [Large-Scale Data](#large-scale-data)
+	- [Type Safety with Generics](#type-safety-with-generics)
+	- [Large-Scale Data](#large-scale-data)
 - [Using with Keyv](#using-with-keyv)
-  - [`createKeyv(options?)`](#createkeyvoptions)
-  - [With Custom Options](#with-custom-options)
-  - [Type Safety](#type-safety)
-  - [Integration with Keyv Ecosystem](#integration-with-keyv-ecosystem)
+	- [createKeyv](#createkeyv)
+	- [With Custom Options](#with-custom-options)
+	- [Type Safety](#type-safety)
+- [Integration with Keyv Ecosystem](#integration-with-keyv-ecosystem)
 - [API](#api)
-- [Constructor](#constructor)
-- [Properties](#properties)
-- [Methods](#methods)
-  - [`set(key, value)`](#setkey-value)
-  - [`get(key)`](#getkey)
-  - [`has(key)`](#haskey)
-  - [`delete(key)`](#deletekey)
-  - [`clear()`](#clear)
-  - [`forEach(callbackfn, thisArg?)`](#foreachcallbackfn-thisarg)
-  - [`keys()`](#keys)
-  - [`values()`](#values)
-  - [`entries()`](#entries)
-  - [`[Symbol.iterator]()`](#symboliterator)
-  - [`getStore(key)`](#getstorekey)
-  - [`getStoreMap(index)`](#getstoremapindex)
-  - [`initStore()`](#initstore)
+	- [Constructor](#constructor)
+	- [Properties](#properties)
+	- [Methods](#methods)
+		- [set](#set)
+		- [get](#get)
+		- [has](#has)
+		- [delete](#delete)
+		- [clear](#clear)
+		- [forEach](#foreach)
+		- [keys](#keys)
+		- [values](#values)
+		- [entries](#entries)
+		- [Symbol.iterator](#symboliterator)
+		- [getStore](#getstorekey)
+		- [getStoreMap](#getstoremapindex)
+		- [initStore](#initstore)
 - [Types](#types)
-  - [`StoreHashFunction`](#storehashfunction)
-  - [`defaultHashFunction(key, storeSize)`](#defaulthashfunctionkey-storesize)
-  - [`djb2Hash(string, min?, max?)`](#djb2hashstring-min-max)
+- [StoreHashFunction](#storehashfunction)
+- [defaultHashFunction(key, storeSize)](#defaulthashfunctionkey-storesize)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -99,7 +97,7 @@ console.log(bigMap.size); // 1
 bigMap.clear();
 ```
 
-## Custom Store Size
+# Custom Store Size
 
 By default, BigMap uses 4 internal Map instances. You can configure this:
 
@@ -109,7 +107,7 @@ const bigMap = new BigMap<string, number>({ storeSize: 10 });
 
 **Note:** Changing the `storeSize` after initialization will clear all entries.
 
-## Custom Hash Function
+# Custom Hash Function
 
 Provide your own hash function for key distribution:
 
@@ -123,11 +121,43 @@ const bigMap = new BigMap<string, string>({
 });
 ```
 
-## Iteration
+## Using Hashery for Hash Functions
+
+[Hashery](https://github.com/jaredwray/hashery) is a powerful hashing library that provides multiple hash algorithms. You can use it for better key distribution and it is available as an export:
+
+```typescript
+import { BigMap, Hashery } from '@keyv/bigmap';
+
+const hashery = new Hashery();
+
+// Using Hashery's toNumberSync for deterministic key distribution
+const bigMap = new BigMap<string, string>({
+  storeHashFunction: (key: string, storeSize: number) => {
+    return hashery.toNumberSync(key, { min: 0, max: storeSize - 1 });
+  }
+});
+
+// You can also use different algorithms
+const hasheryFnv1 = new Hashery({ defaultAlgorithmSync: 'fnv1' });
+
+const bigMapWithFnv1 = new BigMap<string, string>({
+  storeHashFunction: (key: string, storeSize: number) => {
+    return hasheryFnv1.toNumberSync(key, { min: 0, max: storeSize - 1 });
+  }
+});
+```
+
+Hashery supports multiple synchronous hash algorithms:
+- **djb2** - Fast hash function (default)
+- **fnv1** - Excellent distribution for hash tables
+- **murmer** - MurmurHash algorithm
+- **crc32** - Cyclic Redundancy Check
+
+# Iteration
 
 BigMap supports all standard Map iteration methods:
 
-### For...of Loop
+## For...of Loop
 
 ```typescript
 const bigMap = new BigMap<string, number>();
@@ -172,9 +202,9 @@ for (const [key, value] of bigMap.entries()) {
 }
 ```
 
-## Advanced Features
+# Advanced Features
 
-### Type Safety with Generics
+## Type Safety with Generics
 
 ```typescript
 interface User {
@@ -186,7 +216,7 @@ const userMap = new BigMap<string, User>();
 userMap.set('user1', { id: 1, name: 'Alice' });
 ```
 
-### Large-Scale Data
+## Large-Scale Data
 
 BigMap is designed to handle millions of entries:
 
@@ -201,11 +231,11 @@ for (let i = 0; i < 20000000; i++) {
 console.log(bigMap.size); // 20000000
 ```
 
-## Using with Keyv
+# Using with Keyv
 
 BigMap can be used as a storage adapter for [Keyv](https://github.com/jaredwray/keyv), providing a scalable in-memory store with TTL support.
 
-### `createKeyv(options?)`
+## createKeyv
 
 The `createKeyv` function creates a Keyv instance with BigMap as the storage adapter.
 
@@ -241,7 +271,7 @@ await keyv.delete('user:123');
 await keyv.clear();
 ```
 
-### With Custom Options
+## With Custom Options
 
 ```typescript
 import { createKeyv } from '@keyv/bigmap';
@@ -259,7 +289,7 @@ const keyv = createKeyv({
 });
 ```
 
-### Type Safety
+## Type Safety
 
 ```typescript
 import { createKeyv } from '@keyv/bigmap';
@@ -281,7 +311,7 @@ await keyv.set('product:1', {
 const product = await keyv.get<Product>('product:1');
 ```
 
-### Integration with Keyv Ecosystem
+# Integration with Keyv Ecosystem
 
 BigMap works seamlessly with the Keyv ecosystem:
 
@@ -305,9 +335,9 @@ for await (const [key, value] of cache.iterator()) {
 
 # API
 
-# Constructor
+## Constructor
 
- `new BigMap<K, V>(options?)`
+`new BigMap<K, V>(options?)`
 
 Creates a new BigMap instance.
 
@@ -353,9 +383,9 @@ bigMap.storeHashFunction = (key, storeSize) => key.length % storeSize;
 console.log(bigMap.store.length); // 8
 ```
 
-# Methods
+## Methods
 
-## `set(key, value)`
+### set
 
 Sets the value for a key in the map.
 
@@ -370,7 +400,7 @@ Sets the value for a key in the map.
 bigMap.set('user123', { name: 'Alice' });
 ```
 
-## `get(key)`
+### get
 
 Gets the value associated with a key.
 
@@ -384,7 +414,7 @@ Gets the value associated with a key.
 const value = bigMap.get('user123');
 ```
 
-## `has(key)`
+### has
 
 Checks if a key exists in the map.
 
@@ -400,7 +430,7 @@ if (bigMap.has('user123')) {
 }
 ```
 
-## `delete(key)`
+### delete
 
 Deletes a key-value pair from the map.
 
@@ -414,7 +444,7 @@ Deletes a key-value pair from the map.
 const deleted = bigMap.delete('user123');
 ```
 
-## `clear()`
+### clear
 
 Removes all entries from the map.
 
@@ -426,7 +456,7 @@ bigMap.clear();
 console.log(bigMap.size); // 0
 ```
 
-## `forEach(callbackfn, thisArg?)`
+### forEach
 
 Executes a provided function once for each key-value pair.
 
@@ -434,7 +464,7 @@ Executes a provided function once for each key-value pair.
 - `callbackfn` (function): Function to execute for each entry
   - `value` (V): The value of the current entry
   - `key` (K): The key of the current entry
-  - `map` (Map<K, V>): The BigMap instance
+  - `map` (`Map<K, V>`): The BigMap instance
 - `thisArg` (optional): Value to use as `this` when executing the callback
 
 **Returns:** `void`
@@ -452,7 +482,7 @@ bigMap.forEach(function(value) {
 }, context);
 ```
 
-## `keys()`
+### keys
 
 Returns an iterator of all keys in the map.
 
@@ -465,7 +495,7 @@ for (const key of bigMap.keys()) {
 }
 ```
 
-## `values()`
+### values
 
 Returns an iterator of all values in the map.
 
@@ -478,7 +508,7 @@ for (const value of bigMap.values()) {
 }
 ```
 
-## `entries()`
+### entries
 
 Returns an iterator of all key-value pairs in the map.
 
@@ -491,7 +521,7 @@ for (const [key, value] of bigMap.entries()) {
 }
 ```
 
-## `[Symbol.iterator]()`
+### Symbol.iterator
 
 Returns an iterator for the map (same as `entries()`). Enables `for...of` loops.
 
@@ -504,7 +534,7 @@ for (const [key, value] of bigMap) {
 }
 ```
 
-## `getStore(key)`
+### getStore
 
 Gets the internal Map instance for a specific key.
 
@@ -518,7 +548,7 @@ Gets the internal Map instance for a specific key.
 const store = bigMap.getStore('user123');
 ```
 
-## `getStoreMap(index)`
+### getStoreMap
 
 Gets the internal Map instance at a specific index.
 
@@ -534,15 +564,15 @@ Gets the internal Map instance at a specific index.
 const firstMap = bigMap.getStoreMap(0);
 ```
 
-## `initStore()`
+### initStore
 
 Initializes the internal store with empty Map instances. Called automatically during construction.
 
 **Returns:** `void`
 
-# Types
+## Types
 
-## `StoreHashFunction`
+### StoreHashFunction
 
 Type definition for custom hash functions.
 
@@ -556,9 +586,9 @@ type StoreHashFunction = (key: string, storeSize: number) => number;
 
 **Returns:** `number` - The index of the store to use (0 to storeSize - 1)
 
-## `defaultHashFunction(key, storeSize)`
+### defaultHashFunction
 
-The default hash function using DJB2 algorithm.
+The default hash function using DJB2 algorithm from [Hashery](https://npmjs.com/package/hashery):
 
 **Example:**
 ```typescript
@@ -567,7 +597,7 @@ import { defaultHashFunction } from '@keyv/bigmap';
 const index = defaultHashFunction('myKey', 4);
 ```
 
-## `djb2Hash(string, min?, max?)`
+### djb2Hash
 
 DJB2 hash algorithm implementation.
 

package/dist/index.cjs

@@ -21,25 +21,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BigMap: () => BigMap,
+  Hashery: () => import_hashery2.Hashery,
   Keyv: () => import_keyv2.Keyv,
   createKeyv: () => createKeyv,
-  defaultHashFunction: () => defaultHashFunction,
-  djb2Hash: () => djb2Hash
+  defaultHashFunction: () => defaultHashFunction
 });
 module.exports = __toCommonJS(index_exports);
+var import_hashery = require("hashery");
 var import_hookified = require("hookified");
 var import_keyv = require("keyv");
+var import_hashery2 = require("hashery");
 var import_keyv2 = require("keyv");
 function defaultHashFunction(key, storeSize) {
-  return djb2Hash(key, 0, storeSize - 1);
-}
-function djb2Hash(string_, min = 0, max = 10) {
-  let hash = 5381;
-  for (let i = 0; i < string_.length; i++) {
-    hash = hash * 33 ^ string_.charCodeAt(i);
-  }
-  const range = max - min + 1;
-  return min + Math.abs(hash) % range;
+  return new import_hashery.Hashery().toNumberSync(key, { min: 0, max: storeSize - 1 });
 }
 var BigMap = class extends import_hookified.Hookified {
   _storeSize = 4;
@@ -267,8 +261,8 @@ function createKeyv(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BigMap,
+  Hashery,
   Keyv,
   createKeyv,
-  defaultHashFunction,
-  djb2Hash
+  defaultHashFunction
 });

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { HookifiedOptions, Hookified } from 'hookified';
 import { Keyv } from 'keyv';
 export { Keyv } from 'keyv';
+export { Hashery } from 'hashery';
 
 type MapInterfacee<K, V> = {
     readonly size: number;
@@ -17,7 +18,6 @@ type MapInterfacee<K, V> = {
 };
 type StoreHashFunction = (key: string, storeSize: number) => number;
 declare function defaultHashFunction(key: string, storeSize: number): number;
-declare function djb2Hash(string_: string, min?: number, max?: number): number;
 type BigMapOptions = {
     /**
      * Optional size of the store. The default is 4 maps objects.
@@ -154,4 +154,4 @@ declare class BigMap<K, V> extends Hookified implements MapInterfacee<K, V> {
  */
 declare function createKeyv<K = string, V = unknown>(options?: BigMapOptions): Keyv;
 
-export { BigMap, type BigMapOptions, type MapInterfacee, type StoreHashFunction, createKeyv, defaultHashFunction, djb2Hash };
+export { BigMap, type BigMapOptions, type MapInterfacee, type StoreHashFunction, createKeyv, defaultHashFunction };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { HookifiedOptions, Hookified } from 'hookified';
 import { Keyv } from 'keyv';
 export { Keyv } from 'keyv';
+export { Hashery } from 'hashery';
 
 type MapInterfacee<K, V> = {
     readonly size: number;
@@ -17,7 +18,6 @@ type MapInterfacee<K, V> = {
 };
 type StoreHashFunction = (key: string, storeSize: number) => number;
 declare function defaultHashFunction(key: string, storeSize: number): number;
-declare function djb2Hash(string_: string, min?: number, max?: number): number;
 type BigMapOptions = {
     /**
      * Optional size of the store. The default is 4 maps objects.
@@ -154,4 +154,4 @@ declare class BigMap<K, V> extends Hookified implements MapInterfacee<K, V> {
  */
 declare function createKeyv<K = string, V = unknown>(options?: BigMapOptions): Keyv;
 
-export { BigMap, type BigMapOptions, type MapInterfacee, type StoreHashFunction, createKeyv, defaultHashFunction, djb2Hash };
+export { BigMap, type BigMapOptions, type MapInterfacee, type StoreHashFunction, createKeyv, defaultHashFunction };

package/dist/index.js

@@ -1,17 +1,11 @@
 // src/index.ts
+import { Hashery } from "hashery";
 import { Hookified } from "hookified";
 import { Keyv } from "keyv";
+import { Hashery as Hashery2 } from "hashery";
 import { Keyv as Keyv2 } from "keyv";
 function defaultHashFunction(key, storeSize) {
-  return djb2Hash(key, 0, storeSize - 1);
-}
-function djb2Hash(string_, min = 0, max = 10) {
-  let hash = 5381;
-  for (let i = 0; i < string_.length; i++) {
-    hash = hash * 33 ^ string_.charCodeAt(i);
-  }
-  const range = max - min + 1;
-  return min + Math.abs(hash) % range;
+  return new Hashery().toNumberSync(key, { min: 0, max: storeSize - 1 });
 }
 var BigMap = class extends Hookified {
   _storeSize = 4;
@@ -238,8 +232,8 @@ function createKeyv(options) {
 }
 export {
   BigMap,
+  Hashery2 as Hashery,
   Keyv2 as Keyv,
   createKeyv,
-  defaultHashFunction,
-  djb2Hash
+  defaultHashFunction
 };

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@keyv/bigmap",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Bigmap for Keyv",
   "type": "module",
-  "main": "dist/index.cjs",
+  "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.js"
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
     }
   },
   "repository": {
@@ -32,18 +38,19 @@
   },
   "homepage": "https://github.com/jaredwray/keyv",
   "dependencies": {
-    "hookified": "^1.12.2"
+    "hashery": "^1.2.0",
+    "hookified": "^1.13.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.2.6",
+    "@biomejs/biome": "^2.3.6",
     "@faker-js/faker": "^10.1.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "rimraf": "^6.0.1",
+    "@vitest/coverage-v8": "^4.0.10",
+    "rimraf": "^6.1.0",
     "tsd": "^0.33.0",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.10"
   },
   "peerDependencies": {
-    "keyv": "^5.5.3"
+    "keyv": "^5.5.4"
   },
   "tsd": {
     "directory": "test"