Initial push (#1)

Author: adamhamlin

.eslintrc.js

@@ -0,0 +1,15 @@
+module.exports = {
+    extends: ['@adamhamlin/eslint-config'],
+    overrides: [
+        {
+            files: ['**/__tests__/**'],
+            plugins: ['jest'],
+            extends: ['plugin:jest/all'],
+            rules: {
+                'jest/prefer-expect-assertions': 'off',
+                'jest/prefer-lowercase-title': 'off',
+                'jest/max-expects': ['error', { max: 8 }],
+            },
+        },
+    ],
+};

.gitignore

@@ -1,104 +1,14 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
+# TS build dir
+out/
 
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
+# Coverage
+coverage/
 
 # Dependency directories
 node_modules/
-jspm_packages/
-
-# TypeScript v1 declaration files
-typings/
-
-# TypeScript cache
-*.tsbuildinfo
 
 # Optional npm cache directory
 .npm
 
 # Optional eslint cache
 .eslintcache
-
-# Microbundle cache
-.rpt2_cache/
-.rts2_cache_cjs/
-.rts2_cache_es/
-.rts2_cache_umd/
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variables file
-.env
-.env.test
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-
-# Next.js build output
-.next
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and *not* Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# TernJS port file
-.tern-port

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged

.prettierignore

@@ -0,0 +1,3 @@
+# Ignore artifacts:
+out
+coverage

.prettierrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+    ...require('@adamhamlin/eslint-config/prettier'),
+};

README.md

@@ -1,2 +1,83 @@
-# deep-equality-data-structures
-Javascript data structures (e.g., Map, Set) that support deep object equality
+# Deep Equality Javascript Data Structures
+
+A drop-in replacement for ES native `Map` and `Set` with deep equality support for objects.
+
+## Why?
+
+ES `Map` and `Set` only support referential equality:
+
+```typescript
+interface MyObject {
+    a: number;
+}
+const set = new Set<MyObject>();
+set.add({ a: 1 });
+set.add({ a: 1 });
+set.size; // 2
+```
+
+Now, using deep equality:
+
+```typescript
+import { DeepSet } from '@adamhamlin/deep-equality-data-strucures';
+
+interface MyObject {
+    a: number;
+}
+const set = new DeepSet<MyObject>();
+set.add({ a: 1 });
+set.add({ a: 1 });
+set.size; // 1
+```
+
+## How?
+
+This project relies on the [object-hash](https://github.com/puleos/object-hash) library to map object types to strings.
+
+## Comparable Interface
+
+Equality and subset comparisons are supported:
+
+```typescript
+const set1 = new DeepSet([{ a: 1 }, { b: 2 }]);
+const set2 = new DeepSet([{ a: 1 }, { b: 2 }]);
+set1.equals(set2); // true
+
+const set3 = new DeepSet([{ a: 1 }]);
+set1.equals(set3); // false
+set1.contains(set3); // true
+```
+
+## Configuration Options
+
+```typescript
+new DeepSet(values?, options?)
+new DeepMap(entries?, options?)
+```
+
+The `options` argument is a superset of the options defined for [object-hash](https://github.com/puleos/object-hash#hashvalue-options), with the same defaults (exception: the default algoritm is `md5`).
+
+Additional project-specific options:
+
+-   `jsonSerializableOnly` - if true, only use JSON-serializable properties when computing hashes, equality, etc. (default: false)
+
+    ```typescript
+    class A {
+        constructor(public x: number) {}
+    }
+    class B {
+        constructor(public x: number) {}
+    }
+    const b = new B(45);
+    const c = new C(45);
+
+    const set = new DeepSet([b, c]);
+    set.size; // 2
+    const set = new DeepSet([b, c], { jsonSerializableOnly: true });
+    set.size; // 1
+    ```
+
+## Notes/Caveats
+
+-   Don't mutate a map key (or set value) while still using the data structure. The internal representation is not affected by this mutation, so behavior may be unexpected.
+-   This implementation does not explicitly "handle" key collisions. However, with the default algorithm (MD5), even if a map contained one TRILLION entries, the probability of a collision on the next insert is only 0.000000000000001. If you need better odds, use SHA1, SHA256, etc.

index.ts

@@ -0,0 +1,5 @@
+import { DeepMap } from './src/map';
+import { DeepSet } from './src/set';
+
+export { DeepMap };
+export { DeepSet };