fast-equals 4.0.3 → 5.0.0-beta.0

package/.babelrc

@@ -0,0 +1,34 @@
+{
+  "env": {
+    "lib": {
+      "presets": [
+        [
+          "@babel/preset-env",
+          {
+            "loose": true
+          }
+        ]
+      ]
+    },
+    "test": {
+      "presets": [
+        [
+          "@babel/preset-env",
+          {
+            "loose": true
+          }
+        ]
+      ]
+    }
+  },
+  "presets": [
+    "@babel/preset-typescript",
+    [
+      "@babel/preset-env",
+      {
+        "loose": true,
+        "modules": false
+      }
+    ]
+  ]
+}

package/.prettierrc

@@ -1,4 +1,8 @@
 {
+  "arrowParens": "always",
+  "bracketSpacing": true,
+  "semi": true,
   "singleQuote": true,
+  "tabWidth": 2,
   "trailingComma": "all"
 }

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # fast-equals CHANGELOG
 
+## 5.0.0
+
+### Breaking changes
+
+#### `createCustomEqual` contract has changed
+
+To better facilitate strict comparisons, but also to allow for `meta` use separate from caching, the contract for `createCustomEqual` has changed. See the [README documentation](./README.md#createcustomequal) for more details.
+
+#### `createCustomCircularEqual` has been removed
+
+You can create a custom circular equality comparator through `createCustomEqual` now by providing `circular: true` to the options.
+
+#### Deep links have changed
+
+If you were deep-linking into a specific asset type (ESM / CJS / UMD), they have changed location.
+
+**NOTE**: You may no longer need to deep-link, as [the build resolution has improved](#better-build-system-resolution).
+
+### Enhancements
+
+#### New "strict" comparators available
+
+The following new comparators are available:
+
+- `strictDeepEqual`
+- `strictShallowEqual`
+- `strictCircularDeepEqual`
+- `strictCircularShallowEqual`
+
+This will perform the same comparisons as their non-strict counterparts, but will verify additional properties (non-enumerable properties on objects, keyed objects on `Array` / `Map` / `Set`) and that the descriptors for the properties align.
+
+#### Better build system resolution
+
+The library now leverages the `exports` property in the `package.json` to provide builds specific to your method of consumption (ESM / CommonJS / UMD). There is still a minified UMD version available if you want to use it instead.
+
+#### `arePrimitiveWrappersEqual` added to `createCustomEqual` configuration
+
+If you want a custom comparator for primitive wrappers (`new Boolean()` / `new Number()` / `new String()`) it is now available.
+
 ## 4.0.3
 
 - Remove unnecessary second strict equality check for objects in edge-case scenarios

package/README.md

@@ -30,10 +30,12 @@ Starting with version `1.5.0`, circular objects are supported for both deep and
     - [sameValueZeroEqual](#samevaluezeroequal)
     - [circularDeepEqual](#circulardeepequal)
     - [circularShallowEqual](#circularshallowequal)
+    - [strictDeepEqual](#strictdeepequal)
+    - [strictShallowEqual](#strictshallowequal)
+    - [strictCircularDeepEqual](#strictcirculardeepequal)
+    - [strictCircularShallowEqual](#strictcircularshallowequal)
     - [createCustomEqual](#createcustomequal)
       - [Recipes](#recipes)
-    - [`createCustomCircularEqual`](#createcustomcircularequal)
-      - [Recipes](#recipes-1)
   - [Benchmarks](#benchmarks)
   - [Development](#development)
 
@@ -47,13 +49,14 @@ console.log(deepEqual({ foo: 'bar' }, { foo: 'bar' })); // true
 
 ### Specific builds
 
-There are three builds, an ESM build for modern build systems / runtimes, a CommonJS build for traditional NodeJS environments, and a UMD build for legacy implementations. The ideal one will likely be chosen for you automatically, however if you want to use a specific build you can always import it directly:
+By default, npm should resolve the correct build of the package based on your consumption (ESM vs CommonJS). However, if you want to force use of a specific build, they can be located here:
 
-- ESM => `fast-equals/dist/fast-equals.esm.js`
-  - For older `nodejs` versions that do not allow ESM with file extensions other than `.mjs` => `fast-equals/dist/fast-equals.mjs`
-- CommonJS => `fast-equals/dist/fast-equals.cjs.js`
-- UMD => `fast-equals/dist/fast-equals.js`
-- Minified UMD => `fast-equals/dist/fast-equals.min.js`
+- ESM => `fast-equals/dist/esm/index.mjs`
+- CommonJS => `fast-equals/dist/cjs/index.cjs`
+- UMD => `fast-equals/dist/umd/index.js`
+- Minified UMD => `fast-equals/dist/min/index.js`
+
+If you are having issues loading a specific build type, [please file an issue](https://github.com/planttheidea/fast-equals/issues).
 
 ## Available methods
 
@@ -155,6 +158,108 @@ console.log(circularShallowEqual(array, ['foo', array])); // true
 console.log(circularShallowEqual(array, [array])); // false
 ```
 
+### strictDeepEqual
+
+Performs the same comparison as `deepEqual` but performs a strict comparison of the objects. In this includes:
+
+- Checking non-enumerable properties in object comparisons
+- Checking full descriptor of properties on the object to match
+- Checking non-index properties on arrays
+- Checking non-key properties on `Map` / `Set` objects
+
+```ts
+const array = [{ foo: 'bar' }];
+const otherArray = [{ foo: 'bar' }];
+
+array.bar = 'baz';
+otherArray.bar = 'baz';
+
+console.log(strictDeepEqual(array, otherArray)); // true;
+console.log(strictDeepEqual(array, [{ foo: 'bar' }])); // false;
+```
+
+### strictShallowEqual
+
+Performs the same comparison as `shallowEqual` but performs a strict comparison of the objects. In this includes:
+
+- Checking non-enumerable properties in object comparisons
+- Checking full descriptor of properties on the object to match
+- Checking non-index properties on arrays
+- Checking non-key properties on `Map` / `Set` objects
+
+```ts
+const array = ['foo'];
+const otherArray = ['foo'];
+
+array.bar = 'baz';
+otherArray.bar = 'baz';
+
+console.log(strictDeepEqual(array, otherArray)); // true;
+console.log(strictDeepEqual(array, ['foo'])); // false;
+```
+
+### strictCircularDeepEqual
+
+Performs the same comparison as `circularDeepEqual` but performs a strict comparison of the objects. In this includes:
+
+- Checking non-enumerable properties in object comparisons
+- Checking full descriptor of properties on the object to match
+- Checking non-index properties on arrays
+- Checking non-key properties on `Map` / `Set` objects
+
+```ts
+function Circular(value) {
+  this.me = {
+    deeply: {
+      nested: {
+        reference: this,
+      },
+    },
+    value,
+  };
+}
+
+const first = new Circular('foo');
+
+Object.defineProperty(first, 'bar', {
+  enumerable: false,
+  value: 'baz',
+});
+
+const second = new Circular('foo');
+
+Object.defineProperty(second, 'bar', {
+  enumerable: false,
+  value: 'baz',
+});
+
+console.log(circularDeepEqual(first, second)); // true
+console.log(circularDeepEqual(first, new Circular('foo'))); // false
+```
+
+### strictCircularShallowEqual
+
+Performs the same comparison as `circularShallowEqual` but performs a strict comparison of the objects. In this includes:
+
+- Checking non-enumerable properties in object comparisons
+- Checking full descriptor of properties on the object to match
+- Checking non-index properties on arrays
+- Checking non-key properties on `Map` / `Set` objects
+
+```ts
+const array = ['foo'];
+const otherArray = ['foo'];
+
+array.push(array);
+otherArray.push(otherArray);
+
+array.bar = 'baz';
+otherArray.bar = 'baz';
+
+console.log(circularShallowEqual(array, otherArray)); // true
+console.log(circularShallowEqual(array, ['foo', array])); // false
+```
+
 ### createCustomEqual
 
 Creates a custom equality comparator that will be used on nested values in the object. Unlike `deepEqual` and `shallowEqual`, this is a factory method that receives the default options used internally, and allows you to override the defaults as needed. This is generally for extreme edge-cases, or supporting legacy environments.
@@ -162,21 +267,21 @@ Creates a custom equality comparator that will be used on nested values in the o
 The signature is as follows:
 
 ```ts
-type InternalEqualityComparator = (
-  a: any,
-  b: any,
-  indexOrKeyA: any,
-  indexOrKeyB: any,
-  parentA: any,
-  parentB: any,
-  meta: any,
-) => boolean;
+interface BaseCircular extends Pick<WeakMap<any, any>, 'delete' | 'get'> {
+  set(key: object, value: any): any;
+}
 
-type TypeEqualityComparator = <Type, Meta>(
-  a: Type,
-  b: Type,
-  isEqual: InternalEqualityComparator,
-  meta: Meta,
+interface DefaultState<Meta> {
+  readonly cache: undefined | BaseCircular;
+  readonly equals: InternalEqualityComparator<Meta>;
+  meta: Meta;
+  readonly strict: boolean;
+}
+
+type EqualityComparator<Meta> = <A, B>(
+  a: A,
+  b: B,
+  state: State<Meta>,
 ) => boolean;
 
 interface CreateComparatorCreatorOptions<Meta> {
@@ -184,21 +289,31 @@ interface CreateComparatorCreatorOptions<Meta> {
   areDatesEqual: TypeEqualityComparator<Date, Meta>;
   areMapsEqual: TypeEqualityComparator<Map<any, any>, Meta>;
   areObjectsEqual: TypeEqualityComparator<Record<string, any>, Meta>;
+  arePrimitiveWrappersEqual: TypeEqualityComparator<
+    boolean | string | number,
+    Meta
+  >;
   areRegExpsEqual: TypeEqualityComparator<RegExp, Meta>;
   areSetsEqual: TypeEqualityComparator<Set<any>, Meta>;
-  createIsNestedEqual?: (
-    comparator: <A, B>(a: A, b: B, meta: Meta) => boolean,
-  ) => InternalEqualityComparator;
+}
+
+interface CustomEqualCreatorOptions<Meta> {
+  circular?: boolean;
+  comparator?: EqualityComparator<Meta>;
+  createCustomConfig?: CreateCustomComparatorConfig<Meta>;
+  createInternalComparator?: <Meta>(
+    compare: EqualityComparator<Meta>,
+  ) => InternalEqualityComparator<Meta>;
+  createState?: CreateState<Meta>;
+  strict?: boolean;
 }
 
 function createCustomEqual(
-  getComparatorOptions: (
-    defaultOptions: CreateComparatorOptions,
-  ) => Partial<CreateComparatorOptions>,
-): EqualityComparator;
+  options: CustomEqualCreatorOptions<Meta>,
+): <A, B>(a: A, b: B, metaOverride?: Meta) => boolean;
 ```
 
-The `meta` parameter above is whatever you want it to be. It will be passed through to all equality checks, and is meant specifically for use with custom equality methods. For example, with the `circularDeepEqual` and `circularShallowEqual` methods, it is used to pass through a cache of processed objects. You also only need to return the override handlers; absent being provided, the defaults are used.
+Create a custom equality comparator. This allows complete control over building a bespoke equality method, in case your use-case requires a higher degree of performance, legacy environment support, or any other non-standard usage. The [recipes](#recipes) provide examples of use in different use-cases, but if you have a specific goal in mind and would like assistance feel free to [file an issue](https://github.com/planttheidea/fast-equals/issues).
 
 _**NOTE**: `Map` implementations compare equality for both keys and value. When using a custom comparator and comparing equality of the keys, the iteration index is provided as both `indexOrKeyA` and `indexOrKeyB` to help use-cases where ordering of keys matters to equality._
 
@@ -211,15 +326,6 @@ Some recipes have been created to provide examples of use-cases for `createCusto
 - [Using `meta` in comparison](./recipes//using-meta-in-comparison.md)
 - [Comparing non-standard properties](./recipes/non-standard-properties.md)
 - [Strict property descriptor comparison](./recipes/strict-property-descriptor-check.md)
-
-### `createCustomCircularEqual`
-
-Operates nearly identically to [`createCustomEqual`](#createcustomequal), with the difference being that the `meta` property expected by the comparator is expected to have a `WeakMap` contract. This is because it is used for caching accessed objects to avoid maximum stack exceeded errors. The most common use for this method is a simple way to support circular checks for references that do not have `WeakMap` natively.
-
-#### Recipes
-
-Some recipes have been created to provide examples of use-cases for `createCustomEqual`. Even if not directly applicable to the problem you are solving, they can offer guidance of how to structure your solution.
-
 - [Legacy environment support for circualr equal comparators](./recipes/legacy-circular-equal-support.md)
 
 ## Benchmarks

package/build/rollup/config.base.js

@@ -0,0 +1,49 @@
+import commonjs from '@rollup/plugin-commonjs';
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import replace from '@rollup/plugin-replace';
+import typescript from '@rollup/plugin-typescript';
+import fs from 'fs';
+import path from 'path';
+import tsc from 'typescript';
+import { fileURLToPath } from 'url';
+
+const ROOT = fileURLToPath(new URL('../..', import.meta.url));
+
+export const PACKAGE_JSON = JSON.parse(
+  fs.readFileSync(path.resolve(ROOT, 'package.json')),
+);
+
+const external = [
+  ...Object.keys(PACKAGE_JSON.dependencies || {}),
+  ...Object.keys(PACKAGE_JSON.peerDependencies || {}),
+];
+const globals = external.reduce((globals, name) => {
+  globals[name] = name;
+
+  return globals;
+}, {});
+
+export const BASE_CONFIG = {
+  external,
+  input: path.resolve(ROOT, 'src', 'index.ts'),
+  output: {
+    exports: 'named',
+    globals,
+    name: 'fast-equals',
+    sourcemap: true,
+  },
+  plugins: [
+    replace({
+      'process.env.NODE_ENV': JSON.stringify('production'),
+      preventAssignment: true,
+    }),
+    nodeResolve({
+      mainFields: ['module', 'browser', 'main'],
+    }),
+    commonjs({ include: /use-sync-external-store/ }),
+    typescript({
+      tsconfig: path.resolve(ROOT, 'build', 'tsconfig', 'base.json'),
+      typescript: tsc,
+    }),
+  ],
+};

package/build/rollup/config.cjs.js

@@ -0,0 +1,10 @@
+import { BASE_CONFIG, PACKAGE_JSON } from './config.base.js';
+
+export default {
+  ...BASE_CONFIG,
+  output: {
+    ...BASE_CONFIG.output,
+    file: PACKAGE_JSON.main,
+    format: 'cjs',
+  },
+};

package/build/rollup/config.esm.js

@@ -0,0 +1,10 @@
+import { BASE_CONFIG, PACKAGE_JSON } from './config.base.js';
+
+export default {
+  ...BASE_CONFIG,
+  output: {
+    ...BASE_CONFIG.output,
+    file: PACKAGE_JSON.module,
+    format: 'es',
+  },
+};

package/build/rollup/config.min.js

@@ -0,0 +1,13 @@
+import { BASE_CONFIG, PACKAGE_JSON } from './config.base.js';
+import terser from '@rollup/plugin-terser';
+
+export default {
+  ...BASE_CONFIG,
+  output: {
+    ...BASE_CONFIG.output,
+    file: PACKAGE_JSON.browser.replace('umd', 'min'),
+    format: 'umd',
+    sourcemap: false,
+  },
+  plugins: [...BASE_CONFIG.plugins, terser()],
+};

package/build/rollup/config.umd.js

@@ -0,0 +1,10 @@
+import { BASE_CONFIG, PACKAGE_JSON } from './config.base.js';
+
+export default {
+  ...BASE_CONFIG,
+  output: {
+    ...BASE_CONFIG.output,
+    file: PACKAGE_JSON.browser,
+    format: 'umd',
+  },
+};

package/build/tsconfig/base.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowUnreachableCode": false,
+    "baseUrl": "../../src",
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "lib": ["DOM", "ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "outDir": "../../../dist",
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "strictBindCallApply": true,
+    "strictNullChecks": true,
+    "inlineSources": true,
+    "target": "es5",
+    "types": ["jest", "node", "react"]
+  },
+  "exclude": ["../../node_modules"],
+  "include": ["../../src/**/*", "../../__tests__/**/*", "../../DEV_ONLY/**/*"],
+  "files": ["../../node_modules/jest-expect-message/types/index.d.ts"]
+}

package/build/tsconfig/cjs.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./declarations.json",
+  "compilerOptions": {
+    "declarationDir": "../../dist/cjs/types",
+    "module": "CommonJS",
+    "outDir": "../../dist/cjs"
+  }
+}

package/build/tsconfig/declarations.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./base.json",
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "resolveJsonModule": false
+  },
+  "include": ["../../src/*"]
+}

package/build/tsconfig/esm.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./declarations.json",
+  "compilerOptions": {
+    "declarationDir": "../../dist/esm/types",
+    "module": "ESNext",
+    "outDir": "../../dist/esm"
+  }
+}

package/build/tsconfig/min.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./declarations.json",
+  "compilerOptions": {
+    "declarationDir": "../../dist/min/types",
+    "module": "UMD",
+    "outDir": "../../dist/min"
+  }
+}

package/build/tsconfig/umd.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./declarations.json",
+  "compilerOptions": {
+    "declarationDir": "../../dist/umd/types",
+    "module": "UMD",
+    "outDir": "../../dist/umd"
+  }
+}

package/build/webpack.config.js

@@ -0,0 +1,57 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+import ESLintWebpackPlugin from 'eslint-webpack-plugin';
+import HtmlWebpackPlugin from 'html-webpack-plugin';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import webpack from 'webpack';
+
+const ROOT = fileURLToPath(new URL('..', import.meta.url));
+const PORT = 3000;
+
+export default {
+  cache: true,
+
+  devServer: {
+    host: 'localhost',
+    port: PORT,
+  },
+
+  devtool: 'source-map',
+
+  entry: [path.resolve(ROOT, 'DEV_ONLY', 'index.tsx')],
+
+  mode: 'development',
+
+  module: {
+    rules: [
+      {
+        include: [path.resolve(ROOT, 'src'), path.resolve(ROOT, 'DEV_ONLY')],
+        loader: 'ts-loader',
+        options: {
+          reportFiles: ['src/*.{ts|tsx}'],
+        },
+        test: /\.(ts|tsx)$/,
+      },
+    ],
+  },
+
+  output: {
+    filename: 'fast-equals.js',
+    library: 'fastEquals',
+    libraryTarget: 'umd',
+    path: path.resolve(ROOT, 'dist'),
+    publicPath: `http://localhost:${PORT}/`,
+    umdNamedDefine: true,
+  },
+
+  plugins: [
+    new ESLintWebpackPlugin(),
+    new webpack.EnvironmentPlugin(['NODE_ENV']),
+    new HtmlWebpackPlugin(),
+  ],
+
+  resolve: {
+    extensions: ['.tsx', '.ts', '.js'],
+  },
+};