dope-map

A wrapper around Map that uses structural equality for key matching instead of the SameValueZero algorithm. This means that (for example) objects of equal but not referential value will point to the same DopeMap entry. This can come with a slight performance tradeoff (see Benchmarks), so if your dataset is very large take that into consideration.

Ships with a hardcoded (dep-free) implementation of fast-json-stable-stringify and xxhashjs as its hashing function. You can supply a different hashing function in DopeMap's config (as long as it returns a string or number).

fafo here

Installation

yarn add @johnhaup/dope-map

Comparison

API Reference

In addition to standard Map methods

Config

DopeMaps constructor accepts a second config argument.

import { DopeMap } from "@johnhaup/dope-map";
import hashIt from "hash-it";

const dopeMap = new DopeMap(null, { hashFunction: hashIt });

Property	Type	Description
hashFunction	(key: unknown) => string | number	Custom hashing function for non-primitive keys.

Methods

Method	Return Value
getEntries	Array of [key, value] tuples in order of entry
getKeys	Array of keys in order of entry
getValues	Array of values in order of entry

Typescript

DopeMap's generics are flipped from traditional Map:

DopeMap<Value, Key = unknown> // Map<Key = any, Value = any>

Key is optional so you can just type the value and go crazy with the keys you pass.

Examples

API Cache

import { DopeMap } from "@johnhaup/dope-map";

const apiCache = new DopeMap();

const filters = {
  category: "electronics",
  priceRange: [100, 500],
  tags: ["sale"],
};

async function fetchProducts(query) {
  if (apiCache.has(query)) {
    console.log("Cache hit");
    return apiCache.get(query);
  }

  console.log("Cache miss");
  const response = await fetch(`/api/products?${new URLSearchParams(query)}`);
  const data = await response.json();

  apiCache.set(query, data);
  return data;
}

await fetchProducts(filters);
await fetchProducts({
  priceRange: [100, 500],
  category: "electronics",
  tags: ["sale"],
}); // <- Cache hit

Product Lookup

import { DopeMap } from "@johnhaup/dope-map";

type ProductAttributes = {
  color: string;
  size: string;
  material: string;
};

type Product = {
  id: string;
  price: number;
  promoPrice: number | null;
  title: string;
};

const initialEntries: [ProductAttributes, Product][] = [
  [
    { color: "blue", size: "sm", material: "cotton" },
    { id: "13nl54l", title: "Cool Blue", price: 24.99, promoPrice: null },
  ],
  [
    { color: "blue", size: "xs", material: "cotton" },
    { id: "909sadfj", title: "Cool Blue", price: 19.99, promoPrice: 9.99 },
  ],
];

const productMap = new DopeMap<Product>(initialEntries);

interface Props {
  filters: Partial<ProductAttributes>;
}

function SelectedProduct({ filters }: Props) {
  const product = useMemo(() => {
    return productMap.get(filters);
  }, [filters]);

  if (!product) {
    return null;
  }

  return (
    <div>
      <p>{product.title}</p>
      <p>{product.price}</p>
      <p>{product.promoPrice}</p>
    </div>
  );
}

Benchmarks

Each Dope/Map grows to the iteration size. Averages of method time are below. All times are in milliseconds.

OBJECTS keys

100 iterations

Map	Set	Get	Has	Delete
Map	0.001	0.0	0.0	0.0
DopeMap	0.004 (+0.003)	0.002 (+0.002)	0.001 (+0.001)	0.002 (+0.001)
DopeMap w/hash-it	0.004 (+0.004)	0.002 (+0.002)	0.001 (+0.001)	0.002 (+0.002)
DopeMap V1	0.070 (+0.069)	0.069 (+0.069)	0.069 (+0.069)	0.069 (+0.069)

1,000 iterations

Map	Set	Get	Has	Delete
Map	0.012	0.0	0.0	0.005
DopeMap	0.047 (+0.036)	0.028 (+0.027)	0.016 (+0.016)	0.024 (+0.019)
DopeMap w/hash-it	0.055 (+0.043)	0.033 (+0.033)	0.017 (+0.016)	0.024 (+0.019)
DopeMap V1	0.719 (+0.707)	0.709 (+0.709)	0.675 (+0.675)	0.684 (+0.679)

10,000 iterations

Map	Set	Get	Has	Delete
Map	0.170	0.022	0.031	0.052
DopeMap	0.681 (+0.511)	0.523 (+0.501)	0.188 (+0.157)	0.310 (+0.258)
DopeMap w/hash-it	0.653 (+0.484)	0.488 (+0.466)	0.191 (+0.159)	0.282 (+0.230)
DopeMap V1	7.6 (+7.4)	7.3 (+7.3)	6.9 (+6.9)	6.9 (+6.9)

100,000 iterations

Map	Set	Get	Has	Delete
Map	1.7	1.5	1.5	0.584
DopeMap	7.3 (+5.7)	5.9 (+4.4)	5.5 (+4.0)	3.1 (+2.5)
DopeMap w/hash-it	7.9 (+6.3)	6.2 (+4.7)	5.6 (+4.1)	2.8 (+2.2)
DopeMap V1	88.0 (+86.3)	83.1 (+81.6)	82.9 (+81.5)	75.5 (+74.9)

PRIMITIVES keys

100 iterations

Map	Set	Get	Has	Delete
Map	0.001	0.0	0.0	0.0
DopeMap	0.002 (+0.001)	0.001 (+0.001)	0.0	0.001
DopeMap w/hash-it	0.002 (+0.001)	0.001 (+0.001)	0.0	0.001
DopeMap V1	0.002 (+0.001)	0.001 (+0.001)	0.0	0.001

1,000 iterations

Map	Set	Get	Has	Delete
Map	0.012	0.001	0.001	0.005
DopeMap	0.033 (+0.021)	0.013 (+0.012)	0.003 (+0.003)	0.006 (+0.001)
DopeMap w/hash-it	0.034 (+0.022)	0.013 (+0.012)	0.003 (+0.003)	0.006 (+0.001)
DopeMap V1	0.027 (+0.015)	0.017 (+0.017)	0.007 (+0.007)	0.009 (+0.004)

10,000 iterations

Map	Set	Get	Has	Delete
Map	0.203	0.036	0.036	0.050
DopeMap	0.377 (+0.174)	0.195 (+0.159)	0.031 (-0.006)	0.060 (+0.010)
DopeMap w/hash-it	0.375 (+0.172)	0.192 (+0.156)	0.030 (-0.006)	0.061 (+0.011)
DopeMap V1	0.320 (+0.117)	0.239 (+0.204)	0.059 (+0.022)	0.091 (+0.041)

100,000 iterations

Map	Set	Get	Has	Delete
Map	2.9	2.1	2.1	0.562
DopeMap	5.4 (+2.5)	3.0 (+0.879)	2.9 (+0.771)	0.596 (+0.034)
DopeMap w/hash-it	5.4 (+2.5)	3.0 (+0.890)	2.7 (+0.588)	0.598 (+0.037)
DopeMap V1	4.4 (+1.5)	3.1 (+0.947)	0.575 (-1.5)	0.920 (+0.358)