Initial commit

node_modules/fast-equals/recipes/explicit-property-check.md

@@ -0,0 +1,26 @@
+# Explicit property check
+
+Sometimes it is necessary to squeeze every once of performance out of your runtime code, and deep equality checks can be a bottleneck. When this is occurs, it can be advantageous to build a custom comparison that allows for highly specific equality checks.
+
+An example where you know the shape of the objects being passed in, where the `foo` property is a simple primitive and the `bar` property is a nested object:
+
+```ts
+import { createCustomEqual } from 'fast-equals';
+import type { TypeEqualityComparator } from 'fast-equals';
+
+interface SpecialObject {
+  foo: string;
+  bar: {
+    baz: number;
+  };
+}
+
+const areObjectsEqual: TypeEqualityComparator<SpecialObject, undefined> = (
+  a,
+  b,
+) => a.foo === b.foo && a.bar.baz === b.bar.baz;
+
+const isSpecialObjectEqual = createCustomEqual({
+  createCustomConfig: () => ({ areObjectsEqual }),
+});
+```

node_modules/fast-equals/recipes/legacy-circular-equal-support.md

@@ -0,0 +1,75 @@
+# Legacy environment support for circular equal comparators
+
+Starting in `4.x.x`, `WeakMap` is expected to be available in the environment. All modern browsers support this global object, however there may be situations where a legacy environmental support is required (example: IE11). If you need to support such an environment and polyfilling is not an option, creating a custom comparator that uses a custom cache implementation with the same contract is a simple solution.
+
+```ts
+import { createCustomEqual, sameValueZeroEqual } from 'fast-equals';
+import type { Cache } from 'fast-equals';
+
+function getCache(): Cache<any, any> {
+  const entries: Array<[object, any]> = [];
+
+  return {
+    delete(key) {
+      for (let index = 0; index < entries.length; ++index) {
+        if (entries[index][0] === key) {
+          entries.splice(index, 1);
+          return true;
+        }
+      }
+
+      return false;
+    },
+
+    get(key) {
+      for (let index = 0; index < entries.length; ++index) {
+        if (entries[index][0] === key) {
+          return entries[index][1];
+        }
+      }
+    },
+
+    set(key, value) {
+      for (let index = 0; index < entries.length; ++index) {
+        if (entries[index][0] === key) {
+          entries[index][1] = value;
+          return this;
+        }
+      }
+
+      entries.push([key, value]);
+
+      return this;
+    },
+  };
+}
+
+interface Meta {
+  customMethod(): void;
+  customValue: string;
+}
+
+const meta = {
+  customMethod() {
+    console.log('hello!');
+  },
+  customValue: 'goodbye',
+};
+
+const circularDeepEqual = createCustomEqual<Cache>({
+  circular: true,
+  createState: () => ({
+    cache: getCache(),
+    meta,
+  }),
+});
+
+const circularShallowEqual = createCustomEqual<Cache>({
+  circular: true,
+  comparator: sameValueZeroEqual,
+  createState: () => ({
+    cache: getCache(),
+    meta,
+  }),
+});
+```

node_modules/fast-equals/recipes/legacy-regexp-support.md

@@ -0,0 +1,24 @@
+# Legacy environment support for `RegExp` comparators
+
+Starting in `4.x.x`, `RegExp.prototype.flags` is expected to be available in the environment. All modern browsers support this feature, however there may be situations where a legacy environmental support is required (example: IE11). If you need to support such an environment and polyfilling is not an option, creating a custom comparator that uses a more verbose comparison of all possible flags is a simple solution.
+
+```ts
+import { createCustomEqual, sameValueZeroEqual } from 'deep-Equals';
+
+const areRegExpsEqual = (a: RegExp, b: RegExp) =>
+  a.source === b.source &&
+  a.global === b.global &&
+  a.ignoreCase === b.ignoreCase &&
+  a.multiline === b.multiline &&
+  a.unicode === b.unicode &&
+  a.sticky === b.sticky &&
+  a.lastIndex === b.lastIndex;
+
+const deepEqual = createCustomEqual({
+  createCustomConfig: () => ({ areRegExpsEqual }),
+});
+const shallowEqual = createCustomEqual({
+  comparator: sameValueZero,
+  createCustomConfig: () => ({ areRegExpsEqual }),
+});
+```

node_modules/fast-equals/recipes/non-standard-properties.md

@@ -0,0 +1,48 @@
+# Non-standard properties
+
+Sometimes, objects require a comparison that extend beyond its own keys, or even its own properties or symbols. Using a custom object comparator with `createCustomEqual` allows these kinds of comparisons.
+
+```ts
+import { createCustomEqual } from 'fast-equals';
+import type { TypeEqualityComparator } from 'fast-equals';
+
+type AreObjectsEqual = TypeEqualityComparator<Record<any, any>, undefined>;
+
+class HiddenProperty {
+  visible: boolean;
+  #hidden: string;
+
+  constructor(value: string) {
+    this.visible = true;
+    this.#hidden = value;
+  }
+
+  get hidden() {
+    return this.#hidden;
+  }
+}
+
+function createAreObjectsEqual(
+  areObjectsEqual: AreObjectsEqual,
+): AreObjectsEqual {
+  return function (a, b, state) {
+    if (!areObjectsEqual(a, b, state)) {
+      return false;
+    }
+
+    const aInstance = a instanceof HiddenProperty;
+    const bInstance = b instanceof HiddenProperty;
+
+    if (aInstance || bInstance) {
+      return aInstance && bInstance && a.hidden === b.hidden;
+    }
+
+    return true;
+  };
+}
+
+const deepEqual = createCustomEqual({
+  createCustomConfig: ({ areObjectsEqual }) =>
+    createAreObjectsEqual(areObjectsEqual),
+});
+```

node_modules/fast-equals/recipes/using-meta-in-comparison.md

@@ -0,0 +1,20 @@
+# Using `meta` in comparison
+
+Sometimes a "pure" equality between two objects is insufficient, because the comparison relies on some external state. While these kinds of scenarios should generally be avoided, it is possible to handle them with a custom internal comparator that checks `meta` values.
+
+```ts
+import { createCustomEqual } from 'fast-equals';
+
+interface Meta {
+  value: string;
+}
+
+const meta: Meta = { value: 'baz' };
+
+const deepEqual = createCustomEqual<Meta>({
+  createInternalComparator:
+    (compare) => (a, b, _keyA, _keyB, _parentA, _parentB, state) =>
+      compare(a, b, state) || a === state.meta.value || b === state.meta.value,
+  createState: () => ({ meta }),
+});
+```