@keyv/bigmap 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Jared Wray
+
+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.

package/README.md

@@ -0,0 +1,41 @@
+# @keyv/redis [<img width="100" align="right" src="https://jaredwray.com/images/keyv-symbol.svg" alt="keyv">](https://github.com/jaredwra/keyv)
+
+> Bigmap for Keyv
+
+[![build](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml)
+[![codecov](https://codecov.io/gh/jaredwray/keyv/branch/main/graph/badge.svg?token=bRzR3RyOXZ)](https://codecov.io/gh/jaredwray/keyv)
+[![npm](https://img.shields.io/npm/v/@keyv/redis.svg)](https://www.npmjs.com/package/@keyv/redis)
+[![npm](https://img.shields.io/npm/dm/@keyv/redis)](https://npmjs.com/package/@keyv/redis)
+
+# Features
+* Based on the Map interface and uses the same API.
+* Lightweight with no dependencies.
+* Scales to past the 17 million key limit of a regular Map.
+* Uses a hash `djb2Hash` for fast key lookups.
+* Ability to use your own hash function.
+* Built in Typescript and Generics for type safety.
+* Used as default in-memory store for `Keyv`.
+* Used as in-memory store for `@keyv/fs`.
+* Used in `@cacheable/memory` for scalable in-memory caching.
+* Maintained regularly with a focus on performance and reliability.
+
+# Table of Contents
+
+
+# Installation
+
+```bash
+npm install --save keyv @keyv/bigmap
+```
+
+# Usage
+
+# Benchmarks
+
+# Contributing
+
+Please see our [contributing](https://github.com/jaredwray/keyv/blob/main/CONTRIBUTING.md) guide.
+
+# License
+
+[MIT © Jared Wray](LICENSE)

package/dist/index.cjs

@@ -0,0 +1,253 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BigMap: () => BigMap,
+  defaultHashFunction: () => defaultHashFunction,
+  djb2Hash: () => djb2Hash
+});
+module.exports = __toCommonJS(index_exports);
+var import_hookified = require("hookified");
+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;
+}
+var BigMap = class extends import_hookified.Hookified {
+  _storeSize = 4;
+  _store = Array.from({ length: this._storeSize }, () => /* @__PURE__ */ new Map());
+  _storeHashFunction;
+  /**
+   * Creates an instance of BigMap.
+   * @param {BigMapOptions<K, V>} [options] - Optional configuration options for the BigMap.
+   */
+  constructor(options) {
+    super(options);
+    if (options?.storeSize !== void 0) {
+      if (options.storeSize < 1) {
+        throw new Error("Store size must be at least 1.");
+      }
+      this.storeSize = options.storeSize;
+    }
+    this.initStore();
+    this._storeHashFunction = options?.storeHashFunction ?? defaultHashFunction;
+  }
+  /**
+   * Gets the number of maps in the store.
+   * @returns {number} The number of maps in the store.
+   */
+  get storeSize() {
+    return this._storeSize;
+  }
+  /**
+   * Sets the number of maps in the store. If the size is less than 1, an error is thrown.
+   * If you change the store size it will clear all entries.
+   * @param {number} size - The new size of the store.
+   * @throws {Error} If the size is less than 1.
+   */
+  set storeSize(size) {
+    if (size < 1) {
+      throw new Error("Store size must be at least 1.");
+    }
+    this._storeSize = size;
+    this.clear();
+    this.initStore();
+  }
+  /**
+   * Gets the hash function used for storing keys.
+   * @returns {StoreHashFunction | undefined} The hash function used for storing keys, or undefined if not set.
+   */
+  get storeHashFunction() {
+    return this._storeHashFunction;
+  }
+  /**
+   * Sets the hash function used for storing keys.
+   * @param {StoreHashFunction} hashFunction - The hash function to use for storing keys.
+   */
+  set storeHashFunction(hashFunction) {
+    this._storeHashFunction = hashFunction ?? defaultHashFunction;
+  }
+  /**
+   * Gets the store, which is an array of maps.
+   * @returns {Array<Map<K, V>>} The array of maps in the store.
+   */
+  get store() {
+    return this._store;
+  }
+  /**
+   * Gets the map at the specified index in the store.
+   * @param {number} index - The index of the map to retrieve.
+   * @returns {Map<K, V>} The map at the specified index.
+   */
+  getStoreMap(index) {
+    if (index < 0 || index >= this._storeSize) {
+      throw new Error(`Index out of bounds: ${index}. Valid range is 0 to ${this._storeSize - 1}.`);
+    }
+    return this._store[index];
+  }
+  /**
+   * Initializes the store with empty maps.
+   * This method is called when the BigMap instance is created.
+   */
+  initStore() {
+    this._store = Array.from({ length: this._storeSize }, () => /* @__PURE__ */ new Map());
+  }
+  /**
+   * Gets the store for a specific key.
+   * The store is determined by applying the hash function to the key and the store size.
+   * If the hash function is not set, it defaults to using the default hash function.
+   * @param key - The key for which to get the store.
+   * @returns The store for the specified key.
+   */
+  getStore(key) {
+    if (this._storeSize === 1) {
+      return this.getStoreMap(0);
+    }
+    const storeSize = this._storeSize - 1;
+    const index = this._storeHashFunction ? this._storeHashFunction(String(key), storeSize) : defaultHashFunction(String(key), storeSize);
+    return this.getStoreMap(index);
+  }
+  /**
+   * Returns an iterable of key-value pairs in the map.
+   * @returns {IterableIterator<[K, V]>} An iterable of key-value pairs in the map.
+   */
+  entries() {
+    const entries = [];
+    for (const store of this._store) {
+      store.forEach((value, key) => entries.push([key, value]));
+    }
+    return entries[Symbol.iterator]();
+  }
+  /**
+   * Returns an iterable of keys in the map.
+   * @returns {IterableIterator<K>} An iterable of keys in the map.
+   */
+  keys() {
+    const keys = [];
+    for (const store of this._store) {
+      store.forEach((_, key) => keys.push(key));
+    }
+    return keys[Symbol.iterator]();
+  }
+  /**
+   * Returns an iterable of values in the map.
+   * @returns {IterableIterator<V>} An iterable of values in the map.
+   */
+  values() {
+    const values = [];
+    for (const store of this._store) {
+      store.forEach((value) => values.push(value));
+    }
+    return values[Symbol.iterator]();
+  }
+  /**
+   * Returns an iterator that iterates over the key-value pairs in the map.
+   * @returns {IterableIterator<[K, V]>} An iterator that iterates over the key-value pairs in the map.
+   */
+  [Symbol.iterator]() {
+    const entries = [];
+    for (const store of this._store) {
+      store.forEach((value, key) => entries.push([key, value]));
+    }
+    return entries[Symbol.iterator]();
+  }
+  /**
+   * Clears all entries in the map.
+   * @returns {void} This method does not return a value.
+   */
+  clear() {
+    for (const store of this._store) {
+      store.clear();
+    }
+  }
+  /**
+   * Deletes a key-value pair from the map.
+   * @param {K} key - The key of the entry to delete.
+   * @returns {boolean} Returns true if the entry was deleted, false if the key was not found.
+   */
+  delete(key) {
+    const store = this.getStore(key);
+    const deleted = store.delete(key);
+    return deleted;
+  }
+  /**
+   * Calls a provided callback function once for each key-value pair in the map.
+   * @param {function} callbackfn - The function to execute for each key-value pair.
+   * @param {any} [thisArg] - An optional value to use as `this` when executing the callback.
+   */
+  forEach(callbackfn, thisArg) {
+    this._store.forEach((store) => {
+      store.forEach(callbackfn, thisArg);
+    });
+  }
+  /**
+   * Gets the value associated with the specified key.
+   * @param {K} key - The key of the entry to get.
+   * @returns {V | undefined} The value associated with the key, or undefined if the key does not exist.
+   */
+  get(key) {
+    const store = this.getStore(key);
+    return store.get(key);
+  }
+  /**
+   * Checks if the map contains a key.
+   * @param {K} key - The key to check for existence.
+   * @returns {boolean} Returns true if the key exists, false otherwise.
+   */
+  has(key) {
+    const store = this.getStore(key);
+    return store.has(key);
+  }
+  /**
+   * Sets the value for a key in the map.
+   * @param {K} key - The key of the entry to set.
+   * @param {V} value - The value to set for the entry.
+   * @returns {Map<K, V>} The map instance.
+   */
+  set(key, value) {
+    const store = this.getStore(key);
+    store.set(key, value);
+    return store;
+  }
+  /**
+   * Gets the number of entries in the map.
+   * @returns {number} The number of entries in the map.
+   */
+  get size() {
+    let size = 0;
+    for (const store of this._store) {
+      size += store.size;
+    }
+    return size;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BigMap,
+  defaultHashFunction,
+  djb2Hash
+});

package/dist/index.d.cts

@@ -0,0 +1,149 @@
+import { HookifiedOptions, Hookified } from 'hookified';
+
+type MapInterfacee<K, V> = {
+    readonly size: number;
+    clear(): void;
+    delete(key: K): boolean;
+    forEach(callbackfn: (value: V, key: K, map: MapInterfacee<K, V>) => void, thisArg?: any): void;
+    entries(): IterableIterator<[K, V]>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): Map<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<K, V> = {
+    /**
+     * Optional size of the store. The default is 4 maps objects.
+     * @default 4
+     */
+    storeSize?: number;
+    /**
+     * Optional hash function to use for storing keys.
+     * @default undefined
+     */
+    storeHashFunction?: StoreHashFunction;
+} & HookifiedOptions;
+declare class BigMap<K, V> extends Hookified implements MapInterfacee<K, V> {
+    private _storeSize;
+    private _store;
+    private _storeHashFunction?;
+    /**
+     * Creates an instance of BigMap.
+     * @param {BigMapOptions<K, V>} [options] - Optional configuration options for the BigMap.
+     */
+    constructor(options?: BigMapOptions<K, V>);
+    /**
+     * Gets the number of maps in the store.
+     * @returns {number} The number of maps in the store.
+     */
+    get storeSize(): number;
+    /**
+     * Sets the number of maps in the store. If the size is less than 1, an error is thrown.
+     * If you change the store size it will clear all entries.
+     * @param {number} size - The new size of the store.
+     * @throws {Error} If the size is less than 1.
+     */
+    set storeSize(size: number);
+    /**
+     * Gets the hash function used for storing keys.
+     * @returns {StoreHashFunction | undefined} The hash function used for storing keys, or undefined if not set.
+     */
+    get storeHashFunction(): StoreHashFunction | undefined;
+    /**
+     * Sets the hash function used for storing keys.
+     * @param {StoreHashFunction} hashFunction - The hash function to use for storing keys.
+     */
+    set storeHashFunction(hashFunction: StoreHashFunction | undefined);
+    /**
+     * Gets the store, which is an array of maps.
+     * @returns {Array<Map<K, V>>} The array of maps in the store.
+     */
+    get store(): Array<Map<K, V>>;
+    /**
+     * Gets the map at the specified index in the store.
+     * @param {number} index - The index of the map to retrieve.
+     * @returns {Map<K, V>} The map at the specified index.
+     */
+    getStoreMap(index: number): Map<K, V>;
+    /**
+     * Initializes the store with empty maps.
+     * This method is called when the BigMap instance is created.
+     */
+    initStore(): void;
+    /**
+     * Gets the store for a specific key.
+     * The store is determined by applying the hash function to the key and the store size.
+     * If the hash function is not set, it defaults to using the default hash function.
+     * @param key - The key for which to get the store.
+     * @returns The store for the specified key.
+     */
+    getStore(key: K): Map<K, V>;
+    /**
+     * Returns an iterable of key-value pairs in the map.
+     * @returns {IterableIterator<[K, V]>} An iterable of key-value pairs in the map.
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Returns an iterable of keys in the map.
+     * @returns {IterableIterator<K>} An iterable of keys in the map.
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Returns an iterable of values in the map.
+     * @returns {IterableIterator<V>} An iterable of values in the map.
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Returns an iterator that iterates over the key-value pairs in the map.
+     * @returns {IterableIterator<[K, V]>} An iterator that iterates over the key-value pairs in the map.
+     */
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    /**
+     * Clears all entries in the map.
+     * @returns {void} This method does not return a value.
+     */
+    clear(): void;
+    /**
+     * Deletes a key-value pair from the map.
+     * @param {K} key - The key of the entry to delete.
+     * @returns {boolean} Returns true if the entry was deleted, false if the key was not found.
+     */
+    delete(key: K): boolean;
+    /**
+     * Calls a provided callback function once for each key-value pair in the map.
+     * @param {function} callbackfn - The function to execute for each key-value pair.
+     * @param {any} [thisArg] - An optional value to use as `this` when executing the callback.
+     */
+    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
+    /**
+     * Gets the value associated with the specified key.
+     * @param {K} key - The key of the entry to get.
+     * @returns {V | undefined} The value associated with the key, or undefined if the key does not exist.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Checks if the map contains a key.
+     * @param {K} key - The key to check for existence.
+     * @returns {boolean} Returns true if the key exists, false otherwise.
+     */
+    has(key: K): boolean;
+    /**
+     * Sets the value for a key in the map.
+     * @param {K} key - The key of the entry to set.
+     * @param {V} value - The value to set for the entry.
+     * @returns {Map<K, V>} The map instance.
+     */
+    set(key: K, value: V): Map<K, V>;
+    /**
+     * Gets the number of entries in the map.
+     * @returns {number} The number of entries in the map.
+     */
+    get size(): number;
+}
+
+export { BigMap, type BigMapOptions, type MapInterfacee, type StoreHashFunction, defaultHashFunction, djb2Hash };

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+import { HookifiedOptions, Hookified } from 'hookified';
+
+type MapInterfacee<K, V> = {
+    readonly size: number;
+    clear(): void;
+    delete(key: K): boolean;
+    forEach(callbackfn: (value: V, key: K, map: MapInterfacee<K, V>) => void, thisArg?: any): void;
+    entries(): IterableIterator<[K, V]>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): Map<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<K, V> = {
+    /**
+     * Optional size of the store. The default is 4 maps objects.
+     * @default 4
+     */
+    storeSize?: number;
+    /**
+     * Optional hash function to use for storing keys.
+     * @default undefined
+     */
+    storeHashFunction?: StoreHashFunction;
+} & HookifiedOptions;
+declare class BigMap<K, V> extends Hookified implements MapInterfacee<K, V> {
+    private _storeSize;
+    private _store;
+    private _storeHashFunction?;
+    /**
+     * Creates an instance of BigMap.
+     * @param {BigMapOptions<K, V>} [options] - Optional configuration options for the BigMap.
+     */
+    constructor(options?: BigMapOptions<K, V>);
+    /**
+     * Gets the number of maps in the store.
+     * @returns {number} The number of maps in the store.
+     */
+    get storeSize(): number;
+    /**
+     * Sets the number of maps in the store. If the size is less than 1, an error is thrown.
+     * If you change the store size it will clear all entries.
+     * @param {number} size - The new size of the store.
+     * @throws {Error} If the size is less than 1.
+     */
+    set storeSize(size: number);
+    /**
+     * Gets the hash function used for storing keys.
+     * @returns {StoreHashFunction | undefined} The hash function used for storing keys, or undefined if not set.
+     */
+    get storeHashFunction(): StoreHashFunction | undefined;
+    /**
+     * Sets the hash function used for storing keys.
+     * @param {StoreHashFunction} hashFunction - The hash function to use for storing keys.
+     */
+    set storeHashFunction(hashFunction: StoreHashFunction | undefined);
+    /**
+     * Gets the store, which is an array of maps.
+     * @returns {Array<Map<K, V>>} The array of maps in the store.
+     */
+    get store(): Array<Map<K, V>>;
+    /**
+     * Gets the map at the specified index in the store.
+     * @param {number} index - The index of the map to retrieve.
+     * @returns {Map<K, V>} The map at the specified index.
+     */
+    getStoreMap(index: number): Map<K, V>;
+    /**
+     * Initializes the store with empty maps.
+     * This method is called when the BigMap instance is created.
+     */
+    initStore(): void;
+    /**
+     * Gets the store for a specific key.
+     * The store is determined by applying the hash function to the key and the store size.
+     * If the hash function is not set, it defaults to using the default hash function.
+     * @param key - The key for which to get the store.
+     * @returns The store for the specified key.
+     */
+    getStore(key: K): Map<K, V>;
+    /**
+     * Returns an iterable of key-value pairs in the map.
+     * @returns {IterableIterator<[K, V]>} An iterable of key-value pairs in the map.
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Returns an iterable of keys in the map.
+     * @returns {IterableIterator<K>} An iterable of keys in the map.
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Returns an iterable of values in the map.
+     * @returns {IterableIterator<V>} An iterable of values in the map.
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Returns an iterator that iterates over the key-value pairs in the map.
+     * @returns {IterableIterator<[K, V]>} An iterator that iterates over the key-value pairs in the map.
+     */
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    /**
+     * Clears all entries in the map.
+     * @returns {void} This method does not return a value.
+     */
+    clear(): void;
+    /**
+     * Deletes a key-value pair from the map.
+     * @param {K} key - The key of the entry to delete.
+     * @returns {boolean} Returns true if the entry was deleted, false if the key was not found.
+     */
+    delete(key: K): boolean;
+    /**
+     * Calls a provided callback function once for each key-value pair in the map.
+     * @param {function} callbackfn - The function to execute for each key-value pair.
+     * @param {any} [thisArg] - An optional value to use as `this` when executing the callback.
+     */
+    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
+    /**
+     * Gets the value associated with the specified key.
+     * @param {K} key - The key of the entry to get.
+     * @returns {V | undefined} The value associated with the key, or undefined if the key does not exist.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Checks if the map contains a key.
+     * @param {K} key - The key to check for existence.
+     * @returns {boolean} Returns true if the key exists, false otherwise.
+     */
+    has(key: K): boolean;
+    /**
+     * Sets the value for a key in the map.
+     * @param {K} key - The key of the entry to set.
+     * @param {V} value - The value to set for the entry.
+     * @returns {Map<K, V>} The map instance.
+     */
+    set(key: K, value: V): Map<K, V>;
+    /**
+     * Gets the number of entries in the map.
+     * @returns {number} The number of entries in the map.
+     */
+    get size(): number;
+}
+
+export { BigMap, type BigMapOptions, type MapInterfacee, type StoreHashFunction, defaultHashFunction, djb2Hash };

package/dist/index.js

@@ -0,0 +1,226 @@
+// src/index.ts
+import { Hookified } from "hookified";
+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;
+}
+var BigMap = class extends Hookified {
+  _storeSize = 4;
+  _store = Array.from({ length: this._storeSize }, () => /* @__PURE__ */ new Map());
+  _storeHashFunction;
+  /**
+   * Creates an instance of BigMap.
+   * @param {BigMapOptions<K, V>} [options] - Optional configuration options for the BigMap.
+   */
+  constructor(options) {
+    super(options);
+    if (options?.storeSize !== void 0) {
+      if (options.storeSize < 1) {
+        throw new Error("Store size must be at least 1.");
+      }
+      this.storeSize = options.storeSize;
+    }
+    this.initStore();
+    this._storeHashFunction = options?.storeHashFunction ?? defaultHashFunction;
+  }
+  /**
+   * Gets the number of maps in the store.
+   * @returns {number} The number of maps in the store.
+   */
+  get storeSize() {
+    return this._storeSize;
+  }
+  /**
+   * Sets the number of maps in the store. If the size is less than 1, an error is thrown.
+   * If you change the store size it will clear all entries.
+   * @param {number} size - The new size of the store.
+   * @throws {Error} If the size is less than 1.
+   */
+  set storeSize(size) {
+    if (size < 1) {
+      throw new Error("Store size must be at least 1.");
+    }
+    this._storeSize = size;
+    this.clear();
+    this.initStore();
+  }
+  /**
+   * Gets the hash function used for storing keys.
+   * @returns {StoreHashFunction | undefined} The hash function used for storing keys, or undefined if not set.
+   */
+  get storeHashFunction() {
+    return this._storeHashFunction;
+  }
+  /**
+   * Sets the hash function used for storing keys.
+   * @param {StoreHashFunction} hashFunction - The hash function to use for storing keys.
+   */
+  set storeHashFunction(hashFunction) {
+    this._storeHashFunction = hashFunction ?? defaultHashFunction;
+  }
+  /**
+   * Gets the store, which is an array of maps.
+   * @returns {Array<Map<K, V>>} The array of maps in the store.
+   */
+  get store() {
+    return this._store;
+  }
+  /**
+   * Gets the map at the specified index in the store.
+   * @param {number} index - The index of the map to retrieve.
+   * @returns {Map<K, V>} The map at the specified index.
+   */
+  getStoreMap(index) {
+    if (index < 0 || index >= this._storeSize) {
+      throw new Error(`Index out of bounds: ${index}. Valid range is 0 to ${this._storeSize - 1}.`);
+    }
+    return this._store[index];
+  }
+  /**
+   * Initializes the store with empty maps.
+   * This method is called when the BigMap instance is created.
+   */
+  initStore() {
+    this._store = Array.from({ length: this._storeSize }, () => /* @__PURE__ */ new Map());
+  }
+  /**
+   * Gets the store for a specific key.
+   * The store is determined by applying the hash function to the key and the store size.
+   * If the hash function is not set, it defaults to using the default hash function.
+   * @param key - The key for which to get the store.
+   * @returns The store for the specified key.
+   */
+  getStore(key) {
+    if (this._storeSize === 1) {
+      return this.getStoreMap(0);
+    }
+    const storeSize = this._storeSize - 1;
+    const index = this._storeHashFunction ? this._storeHashFunction(String(key), storeSize) : defaultHashFunction(String(key), storeSize);
+    return this.getStoreMap(index);
+  }
+  /**
+   * Returns an iterable of key-value pairs in the map.
+   * @returns {IterableIterator<[K, V]>} An iterable of key-value pairs in the map.
+   */
+  entries() {
+    const entries = [];
+    for (const store of this._store) {
+      store.forEach((value, key) => entries.push([key, value]));
+    }
+    return entries[Symbol.iterator]();
+  }
+  /**
+   * Returns an iterable of keys in the map.
+   * @returns {IterableIterator<K>} An iterable of keys in the map.
+   */
+  keys() {
+    const keys = [];
+    for (const store of this._store) {
+      store.forEach((_, key) => keys.push(key));
+    }
+    return keys[Symbol.iterator]();
+  }
+  /**
+   * Returns an iterable of values in the map.
+   * @returns {IterableIterator<V>} An iterable of values in the map.
+   */
+  values() {
+    const values = [];
+    for (const store of this._store) {
+      store.forEach((value) => values.push(value));
+    }
+    return values[Symbol.iterator]();
+  }
+  /**
+   * Returns an iterator that iterates over the key-value pairs in the map.
+   * @returns {IterableIterator<[K, V]>} An iterator that iterates over the key-value pairs in the map.
+   */
+  [Symbol.iterator]() {
+    const entries = [];
+    for (const store of this._store) {
+      store.forEach((value, key) => entries.push([key, value]));
+    }
+    return entries[Symbol.iterator]();
+  }
+  /**
+   * Clears all entries in the map.
+   * @returns {void} This method does not return a value.
+   */
+  clear() {
+    for (const store of this._store) {
+      store.clear();
+    }
+  }
+  /**
+   * Deletes a key-value pair from the map.
+   * @param {K} key - The key of the entry to delete.
+   * @returns {boolean} Returns true if the entry was deleted, false if the key was not found.
+   */
+  delete(key) {
+    const store = this.getStore(key);
+    const deleted = store.delete(key);
+    return deleted;
+  }
+  /**
+   * Calls a provided callback function once for each key-value pair in the map.
+   * @param {function} callbackfn - The function to execute for each key-value pair.
+   * @param {any} [thisArg] - An optional value to use as `this` when executing the callback.
+   */
+  forEach(callbackfn, thisArg) {
+    this._store.forEach((store) => {
+      store.forEach(callbackfn, thisArg);
+    });
+  }
+  /**
+   * Gets the value associated with the specified key.
+   * @param {K} key - The key of the entry to get.
+   * @returns {V | undefined} The value associated with the key, or undefined if the key does not exist.
+   */
+  get(key) {
+    const store = this.getStore(key);
+    return store.get(key);
+  }
+  /**
+   * Checks if the map contains a key.
+   * @param {K} key - The key to check for existence.
+   * @returns {boolean} Returns true if the key exists, false otherwise.
+   */
+  has(key) {
+    const store = this.getStore(key);
+    return store.has(key);
+  }
+  /**
+   * Sets the value for a key in the map.
+   * @param {K} key - The key of the entry to set.
+   * @param {V} value - The value to set for the entry.
+   * @returns {Map<K, V>} The map instance.
+   */
+  set(key, value) {
+    const store = this.getStore(key);
+    store.set(key, value);
+    return store;
+  }
+  /**
+   * Gets the number of entries in the map.
+   * @returns {number} The number of entries in the map.
+   */
+  get size() {
+    let size = 0;
+    for (const store of this._store) {
+      size += store.size;
+    }
+    return size;
+  }
+};
+export {
+  BigMap,
+  defaultHashFunction,
+  djb2Hash
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@keyv/bigmap",
+  "version": "1.0.0",
+  "description": "Bigmap for Keyv",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaredwray/keyv.git"
+  },
+  "keywords": [
+    "bigmap",
+    "keyv",
+    "key",
+    "value",
+    "store",
+    "cache",
+    "ttl"
+  ],
+  "author": "Jared Wray <me@jaredwray.com> (http://jaredwray.com)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jaredwray/keyv/issues"
+  },
+  "homepage": "https://github.com/jaredwray/keyv",
+  "dependencies": {
+    "hookified": "^1.10.0"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^9.9.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "rimraf": "^6.0.1",
+    "tsd": "^0.32.0",
+    "vitest": "^3.2.4",
+    "xo": "^1.1.1"
+  },
+  "tsd": {
+    "directory": "test"
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "xo --fix && vitest run --coverage",
+    "test:ci": "xo && vitest --run --sequence.setupFiles=list --coverage",
+    "clean": "rimraf ./node_modules ./coverage ./dist"
+  }
+}