atomic-fns 1.2.0 → 2.0.0

package/dist/object/cloneDeep.js

@@ -0,0 +1,200 @@
+/**
+ * `cloneDeep`: a structural copy that keeps prototypes, symbol keys, sharing and cycles.
+ */
+import { isEnumerable } from '../internal/keys.js';
+import { bytesOf, kindOf, typedArrayLength, typedArrayName, unbox } from '../internal/kind.js';
+import { isCanonicalArrayIndex, walkArray } from '../internal/sparse.js';
+import { enterDepth, exitDepth, guardDepth } from '../internal/walk.js';
+const dateTime = Date.prototype.getTime;
+const mapEntries = Map.prototype.entries;
+const mapSet = Map.prototype.set;
+const setValues = Set.prototype.values;
+const setAdd = Set.prototype.add;
+/** This realm's typed array constructors by `[[TypedArrayName]]`. */
+const VIEW_CONSTRUCTORS = new Map([
+    'Int8Array',
+    'Uint8Array',
+    'Uint8ClampedArray',
+    'Int16Array',
+    'Uint16Array',
+    'Int32Array',
+    'Uint32Array',
+    'Float16Array',
+    'Float32Array',
+    'Float64Array',
+    'BigInt64Array',
+    'BigUint64Array'
+].flatMap((name) => {
+    const ctor = globalThis[name];
+    return typeof ctor === 'function' ? [[name, ctor]] : [];
+}));
+function defineValue(out, key, value) {
+    Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+}
+/**
+ * Copy the own enumerable symbol keys of `src` onto `out`, and the string keys `strings` names,
+ * cloning each value.
+ */
+function copyKeys(src, out, copies, strings) {
+    const record = src;
+    if (strings !== 'none') {
+        for (const key of Object.keys(src)) {
+            if (strings === 'non-index' && isCanonicalArrayIndex(key))
+                continue;
+            defineValue(out, key, cloneValue(record[key], copies));
+        }
+    }
+    for (const sym of Object.getOwnPropertySymbols(src)) {
+        if (!isEnumerable(src, sym))
+            continue;
+        defineValue(out, sym, cloneValue(record[sym], copies));
+    }
+}
+function withPrototype(out, src) {
+    const proto = Object.getPrototypeOf(src);
+    if (Object.getPrototypeOf(out) !== proto)
+        Object.setPrototypeOf(out, proto);
+    return out;
+}
+/** Record `out` as the copy of `src`, then copy the keys of `src` onto it. */
+function finish(src, out, copies, strings) {
+    copies.set(src, out);
+    copyKeys(src, out, copies, strings);
+    return out;
+}
+function cloneBuffer(src, copies) {
+    const known = copies.get(src);
+    if (known !== undefined)
+        return known;
+    const bytes = bytesOf(src);
+    let out;
+    if (Object.prototype.toString.call(src) === '[object SharedArrayBuffer]') {
+        const shared = src;
+        out = new SharedArrayBuffer(bytes.length, shared.growable ? { maxByteLength: shared.maxByteLength } : undefined);
+    }
+    else {
+        const buffer = src;
+        out = new ArrayBuffer(bytes.length, buffer.resizable ? { maxByteLength: buffer.maxByteLength } : undefined);
+    }
+    new Uint8Array(out).set(bytes);
+    return finish(src, withPrototype(out, src), copies, 'all');
+}
+function cloneView(src, copies) {
+    const name = typedArrayName(src);
+    const isDataView = name === undefined;
+    const buffer = cloneBuffer(src.buffer, copies);
+    // The buffer's own keys can lead back to this view, which is then copied already.
+    const known = copies.get(src);
+    if (known !== undefined)
+        return known;
+    let offset = 0;
+    let length = 0;
+    try {
+        offset = src.byteOffset;
+        length = isDataView ? src.byteLength : (typedArrayLength(src) ?? 0);
+    }
+    catch {
+        // Detached or out-of-bounds DataViews have no readable offset or length.
+    }
+    const ctor = isDataView ? DataView : VIEW_CONSTRUCTORS.get(name);
+    if (ctor === undefined)
+        throw new TypeError(`cannot copy a ${name ?? 'view'}`);
+    return finish(src, withPrototype(new ctor(buffer, offset, length), src), copies, 'none');
+}
+function cloneObject(src, copies) {
+    switch (kindOf(src)) {
+        case 'plain':
+            return finish(src, Object.create(Object.getPrototypeOf(src)), copies, 'all');
+        case 'array': {
+            const list = src;
+            const out = withPrototype([], src);
+            copies.set(src, out);
+            out.length = list.length;
+            walkArray(list, (event) => {
+                if (event.kind === 'value')
+                    out[event.index] = cloneValue(event.value, copies);
+            });
+            copyKeys(src, out, copies, 'non-index');
+            return out;
+        }
+        case 'map': {
+            const out = withPrototype(new Map(), src);
+            copies.set(src, out);
+            for (const [key, value] of mapEntries.call(src)) {
+                mapSet.call(out, key, cloneValue(value, copies));
+            }
+            copyKeys(src, out, copies, 'all');
+            return out;
+        }
+        case 'set': {
+            const out = withPrototype(new Set(), src);
+            copies.set(src, out);
+            for (const value of setValues.call(src)) {
+                setAdd.call(out, cloneValue(value, copies));
+            }
+            copyKeys(src, out, copies, 'all');
+            return out;
+        }
+        case 'date':
+            return finish(src, withPrototype(new Date(dateTime.call(src)), src), copies, 'all');
+        case 'regexp': {
+            const re = src;
+            const out = withPrototype(new RegExp(re.source, re.flags), src);
+            out.lastIndex = src.lastIndex;
+            return finish(src, out, copies, 'all');
+        }
+        case 'buffer':
+            return cloneBuffer(src, copies);
+        case 'view':
+            return cloneView(src, copies);
+        case 'boxed': {
+            const primitive = unbox(src);
+            const out = withPrototype(Object(primitive), src);
+            // A String wrapper lists one index key per character; only its symbol keys are copied.
+            return finish(src, out, copies, typeof primitive === 'string' ? 'none' : 'all');
+        }
+        default:
+            return src;
+    }
+}
+function cloneValue(value, copies) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    const known = copies.get(value);
+    if (known !== undefined)
+        return known;
+    enterDepth();
+    try {
+        return cloneObject(value, copies);
+    }
+    finally {
+        exitDepth();
+    }
+}
+/**
+ * A deep copy of `value`. Plain objects, arrays, `Map`, `Set`, `Date`, `RegExp`, typed arrays,
+ * `DataView`, `ArrayBuffer`, `SharedArrayBuffer` and boxed primitives are copied with their
+ * prototype (a subclass stays a subclass) and their own enumerable symbol keys; all but typed
+ * arrays, `DataView` and `String` wrappers also keep their own enumerable string keys, and arrays
+ * keep their holes. `Map` keys keep their identity while values are copied. A subclass copy gets
+ * the prototype only: its constructor does not run, so it has none of its private fields. A
+ * resizable or growable buffer stays so, and a detached one copies as an empty buffer. Class
+ * instances, functions, errors, promises and every other object are kept by reference:
+ * `structuredClone` throws on them, and copying their fields would produce an object whose private
+ * state and invariants are gone. An object reached twice is copied once, so shared references and
+ * cycles stay shared and cyclic in the copy, and views over one buffer share one copied buffer.
+ * @param value The value to copy.
+ * @returns The copy.
+ * @throws {RangeError} past 1000 levels of nesting.
+ * @throws {TypeError} for a typed array kind this runtime has no constructor for.
+ * @example
+ * ```ts
+ * const src = { when: new Date(0), tags: new Set(['a']), list: [{ id: 1 }] }
+ * const copy = cloneDeep(src)
+ * copy.list[0] === src.list[0] // false
+ * copy.when.getTime() // 0
+ * ```
+ */
+export function cloneDeep(value) {
+    return guardDepth(() => cloneValue(value, new Map()));
+}

package/dist/object/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Objects by path, structure and shape: `get`, `set`, `has`, `unset`, deep equality, and the
+ * object helpers that copy, merge and match.
+ * @module object
+ */
+export { cloneDeep } from './cloneDeep.js';
+export { type EqualityCustomizer, isEqual, isEqualWith } from './isEqual.js';
+export { isMatch, matches } from './matches.js';
+export { defaults, defaultsDeep, merge } from './merge.js';
+export type { Path } from './parsePath.js';
+export { get, has, set, unset } from './path.js';
+export { omit, omitBy, type Paths, type PickedBy, pick, pickBy, type PlainKey } from './pick.js';
+export { type FlattenOptions, flattenObject, invert, mapKeys, mapValues } from './reshape.js';
+export { isPlainObject } from '../is/isPlainObject.js';

package/dist/object/index.js

@@ -0,0 +1,13 @@
+/**
+ * Objects by path, structure and shape: `get`, `set`, `has`, `unset`, deep equality, and the
+ * object helpers that copy, merge and match.
+ * @module object
+ */
+export { cloneDeep } from './cloneDeep.js';
+export { isEqual, isEqualWith } from './isEqual.js';
+export { isMatch, matches } from './matches.js';
+export { defaults, defaultsDeep, merge } from './merge.js';
+export { get, has, set, unset } from './path.js';
+export { omit, omitBy, pick, pickBy } from './pick.js';
+export { flattenObject, invert, mapKeys, mapValues } from './reshape.js';
+export { isPlainObject } from '../is/isPlainObject.js';

package/dist/object/isEqual.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Decides one pair for {@link isEqualWith}: `true` or `false` to answer, `undefined` to let
+ * `isEqualWith` compare the pair itself. `key` is the key, index or Map key the pair was found
+ * under, and `undefined` for the two values passed in.
+ */
+export type EqualityCustomizer = (a: unknown, b: unknown, key: unknown) => boolean | undefined;
+/**
+ * Deep structural equality, lodash's `isEqual` with the platform's rules. Primitives compare by
+ * SameValueZero, so `NaN` equals `NaN`, `0` equals `-0`, and `1` does not equal `1n`. Plain objects
+ * compare by own enumerable keys (symbols included), arrays by index (a hole equals `undefined`;
+ * other keys are ignored), `Map` by key membership and then value, `Set` by membership, Dates by
+ * time, RegExps by source, flags and `lastIndex` (SameValueZero), typed arrays, `DataView` and
+ * `ArrayBuffer` by content, boxed primitives by their primitive, `arguments` like an array, and
+ * errors by name, message, own `cause` and `errors` and own enumerable properties (not `stack`,
+ * nor JavaScriptCore's `line`, `column` and `sourceURL`), as Node's `isDeepStrictEqual` does.
+ * Both sides must be of one class,
+ * or its twin from another realm. Any other object (a class instance, a function, a promise) equals
+ * only itself; use {@link isEqualWith} to compare such types.
+ *
+ * Cycles and shared objects are compared once each. Nesting past 1000 levels, or more than 2^24
+ * objects in one comparison, throws `RangeError`.
+ * @param a Any value.
+ * @param b Any value.
+ * @returns Whether `a` and `b` are structurally equal.
+ * @example
+ * ```ts
+ * class Point {
+ *   constructor(public x: number, public y: number) {}
+ * }
+ * isEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }) // true
+ * isEqual(new Map([[1, NaN]]), new Map([[1, NaN]])) // true
+ * isEqual(new Set([{}]), new Set([{}])) // false: members are matched by SameValueZero
+ * isEqual(new Point(1, 2), new Point(1, 2)) // false: class instances compare by identity
+ * ```
+ */
+export declare function isEqual(a: unknown, b: unknown): boolean;
+/**
+ * {@link isEqual} with a `customizer` that may decide any pair first. It sees the two values passed
+ * in, then every nested pair with the key it was found under; returning `true` or `false` answers
+ * that pair, and `undefined` leaves it to `isEqual`'s rules. This is how to compare class instances
+ * by their fields, or values of a type like `Decimal` by its own `equals`. Set members and Map keys
+ * still match by SameValueZero and never reach the customizer; to compare those by content, decide
+ * the Set or Map pair itself.
+ *
+ * The customizer need not be transitive (a tolerance such as `Math.abs(a - b) <= 1` works), so each
+ * pair of objects is remembered as walked rather than joined into a class: a shared pair is walked
+ * once, and two cycles of different lengths are walked until they line up, which counts toward the
+ * nesting limit. Nesting past 1000 levels, or more than 2^24 pairs in one comparison, throws
+ * `RangeError`.
+ * @param a Any value.
+ * @param b Any value.
+ * @param customizer Decides a pair, or returns `undefined` to fall through.
+ * @returns Whether `a` and `b` are equal under `customizer`.
+ * @example
+ * ```ts
+ * class Point {
+ *   constructor(public x: number, public y: number) {}
+ * }
+ * const byFields = (a: unknown, b: unknown) =>
+ *   a instanceof Point && b instanceof Point ? a.x === b.x && a.y === b.y : undefined
+ * isEqualWith([new Point(1, 2)], [new Point(1, 2)], byFields) // true
+ * ```
+ */
+export declare function isEqualWith(a: unknown, b: unknown, customizer: EqualityCustomizer): boolean;

package/dist/object/isEqual.js

@@ -0,0 +1,289 @@
+import { sameValueZero } from '../internal/compare.js';
+import { ERROR_LOCATION_KEYS, enumerableKeys, isEnumerable } from '../internal/keys.js';
+import { bytesOf, contentKindOf, isFloatView, sameClass, unbox } from '../internal/kind.js';
+import { walkArrayIndices } from '../internal/sparse.js';
+import { enterDepth, exitDepth, guardDepth } from '../internal/walk.js';
+/** Past this many tracked objects, or pairs with a customizer, a comparison throws `RangeError`. */
+const MAX_TRACKED = 2 ** 24;
+const getTime = Date.prototype.getTime;
+/**
+ * Equal pairs as a union-find over the objects met. `isEqual`'s own rules are an equivalence, so a
+ * pair in one class is equal without a walk, and each object is walked once.
+ */
+class EqualClasses {
+    #ids = new Map();
+    #parent = [];
+    assumed(a, b) {
+        const [rx, ry] = [this.#root(this.#id(a)), this.#root(this.#id(b))];
+        if (rx === ry)
+            return true;
+        this.#parent[rx] = ry;
+        return false;
+    }
+    #id(value) {
+        let id = this.#ids.get(value);
+        if (id === undefined) {
+            if (this.#ids.size >= MAX_TRACKED) {
+                throw new RangeError(`comparing more than ${String(MAX_TRACKED)} objects`);
+            }
+            id = this.#parent.length;
+            this.#ids.set(value, id);
+            this.#parent.push(id);
+        }
+        return id;
+    }
+    #root(id) {
+        let root = id;
+        while (this.#parent[root] !== root)
+            root = this.#parent[root];
+        while (this.#parent[id] !== root)
+            [this.#parent[id], id] = [root, this.#parent[id]];
+        return root;
+    }
+}
+/**
+ * Equal pairs exactly as walked. A customizer need not be transitive (`a` near `b` and `b` near `c`
+ * says nothing of `a` and `c`), so only a pair already walked is equal without a walk.
+ */
+class EqualPairs {
+    #partners = new Map();
+    #size = 0;
+    assumed(a, b) {
+        const partners = this.#partners.get(a);
+        if (partners?.has(b))
+            return true;
+        if (this.#size >= MAX_TRACKED) {
+            throw new RangeError(`comparing more than ${String(MAX_TRACKED)} pairs`);
+        }
+        this.#size++;
+        if (partners === undefined)
+            this.#partners.set(a, new Set([b]));
+        else
+            partners.add(b);
+        return false;
+    }
+}
+/** One comparison: its customizer, if any, and the pairs it has taken to be equal. */
+class Session {
+    customizer;
+    #assumptions;
+    constructor(customizer) {
+        this.customizer = customizer;
+        this.#assumptions = customizer === undefined ? new EqualClasses() : new EqualPairs();
+    }
+    /** Whether `a` and `b` were already taken to be equal; if not, takes them to be from now on. */
+    assumed(a, b) {
+        return this.#assumptions.assumed(a, b);
+    }
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function viewsEqual(a, b) {
+    if (!isFloatView(a))
+        return bytesEqual(bytesOf(a), bytesOf(b));
+    const other = b;
+    const length = a.length;
+    if (length !== other.length)
+        return false;
+    for (let i = 0; i < length; i++)
+        if (!sameValueZero(a[i], other[i]))
+            return false;
+    return true;
+}
+function recordsEqual(a, b, session, ignored) {
+    const keysOf = (value) => {
+        const keys = enumerableKeys(value);
+        return ignored === undefined ? keys : keys.filter((key) => !ignored.has(key));
+    };
+    const keys = keysOf(a);
+    if (keys.length !== keysOf(b).length)
+        return false;
+    const [x, y] = [a, b];
+    return keys.every((key) => isEnumerable(b, key) && equalValues(x[key], y[key], key, session));
+}
+/** Own elements from `from` on, so holes cost nothing and read as `undefined`. */
+function sparseArraysEqual(a, b, from, session) {
+    const ownEqual = (array, skip) => {
+        let equal = true;
+        walkArrayIndices(array, (ev) => {
+            if (ev.kind !== 'index' ||
+                ev.index < from ||
+                (skip !== undefined && isEnumerable(skip, ev.index)))
+                return;
+            equal = equalValues(isEnumerable(a, ev.index) ? a[ev.index] : undefined, isEnumerable(b, ev.index) ? b[ev.index] : undefined, ev.index, session);
+            return equal ? undefined : false;
+        });
+        return equal;
+    };
+    return ownEqual(a) && ownEqual(b, a);
+}
+function arraysEqual(a, b, session) {
+    if (a.length !== b.length)
+        return false;
+    let i = 0;
+    for (; i < a.length && i in a && i in b; i++) {
+        if (!equalValues(a[i], b[i], i, session))
+            return false;
+    }
+    return i === a.length || sparseArraysEqual(a, b, i, session);
+}
+function mapsEqual(a, b, session) {
+    if (a.size !== b.size)
+        return false;
+    for (const [key, value] of Map.prototype.entries.call(a)) {
+        if (!Map.prototype.has.call(b, key))
+            return false;
+        if (!equalValues(value, Map.prototype.get.call(b, key), key, session))
+            return false;
+    }
+    return true;
+}
+function setsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const value of Set.prototype.values.call(a)) {
+        if (!Set.prototype.has.call(b, value))
+            return false;
+    }
+    return true;
+}
+/**
+ * Name, message, an own `cause` and `errors`, and own enumerable properties but the location keys
+ * an engine adds, as `isDeepStrictEqual` reads them.
+ */
+function errorsEqual(a, b, session) {
+    if (!equalValues(a.name, b.name, 'name', session))
+        return false;
+    if (!equalValues(a.message, b.message, 'message', session))
+        return false;
+    const [x, y] = [a, b];
+    for (const key of ['cause', 'errors']) {
+        const has = Object.hasOwn(a, key);
+        if (has !== Object.hasOwn(b, key))
+            return false;
+        if (has && !equalValues(x[key], y[key], key, session))
+            return false;
+    }
+    return recordsEqual(a, b, session, ERROR_LOCATION_KEYS);
+}
+function regExpsEqual(a, b) {
+    return a.source === b.source && a.flags === b.flags && sameValueZero(a.lastIndex, b.lastIndex);
+}
+function contentEqual(a, b, kind, session) {
+    switch (kind) {
+        case 'boxed':
+            return sameValueZero(unbox(a), unbox(b));
+        case 'date':
+            return sameValueZero(getTime.call(a), getTime.call(b));
+        case 'regexp':
+            return regExpsEqual(a, b);
+        case 'buffer':
+            return bytesEqual(bytesOf(a), bytesOf(b));
+        case 'view':
+            return viewsEqual(a, b);
+        case 'array':
+        case 'arguments':
+            return arraysEqual(a, b, session);
+        case 'error':
+            return errorsEqual(a, b, session);
+        case 'map':
+            return mapsEqual(a, b, session);
+        case 'set':
+            return setsEqual(a, b);
+        default:
+            return recordsEqual(a, b, session);
+    }
+}
+function equalValues(a, b, key, session) {
+    if (session.customizer !== undefined) {
+        const answer = session.customizer(a, b, key);
+        if (answer !== undefined)
+            return Boolean(answer);
+    }
+    if (sameValueZero(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    const kind = contentKindOf(a);
+    if (kind === 'other' || kind !== contentKindOf(b) || !sameClass(a, b))
+        return false;
+    if (session.assumed(a, b))
+        return true;
+    enterDepth();
+    try {
+        return contentEqual(a, b, kind, session);
+    }
+    finally {
+        exitDepth();
+    }
+}
+/**
+ * Deep structural equality, lodash's `isEqual` with the platform's rules. Primitives compare by
+ * SameValueZero, so `NaN` equals `NaN`, `0` equals `-0`, and `1` does not equal `1n`. Plain objects
+ * compare by own enumerable keys (symbols included), arrays by index (a hole equals `undefined`;
+ * other keys are ignored), `Map` by key membership and then value, `Set` by membership, Dates by
+ * time, RegExps by source, flags and `lastIndex` (SameValueZero), typed arrays, `DataView` and
+ * `ArrayBuffer` by content, boxed primitives by their primitive, `arguments` like an array, and
+ * errors by name, message, own `cause` and `errors` and own enumerable properties (not `stack`,
+ * nor JavaScriptCore's `line`, `column` and `sourceURL`), as Node's `isDeepStrictEqual` does.
+ * Both sides must be of one class,
+ * or its twin from another realm. Any other object (a class instance, a function, a promise) equals
+ * only itself; use {@link isEqualWith} to compare such types.
+ *
+ * Cycles and shared objects are compared once each. Nesting past 1000 levels, or more than 2^24
+ * objects in one comparison, throws `RangeError`.
+ * @param a Any value.
+ * @param b Any value.
+ * @returns Whether `a` and `b` are structurally equal.
+ * @example
+ * ```ts
+ * class Point {
+ *   constructor(public x: number, public y: number) {}
+ * }
+ * isEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }) // true
+ * isEqual(new Map([[1, NaN]]), new Map([[1, NaN]])) // true
+ * isEqual(new Set([{}]), new Set([{}])) // false: members are matched by SameValueZero
+ * isEqual(new Point(1, 2), new Point(1, 2)) // false: class instances compare by identity
+ * ```
+ */
+export function isEqual(a, b) {
+    return guardDepth(() => equalValues(a, b, undefined, new Session()));
+}
+/**
+ * {@link isEqual} with a `customizer` that may decide any pair first. It sees the two values passed
+ * in, then every nested pair with the key it was found under; returning `true` or `false` answers
+ * that pair, and `undefined` leaves it to `isEqual`'s rules. This is how to compare class instances
+ * by their fields, or values of a type like `Decimal` by its own `equals`. Set members and Map keys
+ * still match by SameValueZero and never reach the customizer; to compare those by content, decide
+ * the Set or Map pair itself.
+ *
+ * The customizer need not be transitive (a tolerance such as `Math.abs(a - b) <= 1` works), so each
+ * pair of objects is remembered as walked rather than joined into a class: a shared pair is walked
+ * once, and two cycles of different lengths are walked until they line up, which counts toward the
+ * nesting limit. Nesting past 1000 levels, or more than 2^24 pairs in one comparison, throws
+ * `RangeError`.
+ * @param a Any value.
+ * @param b Any value.
+ * @param customizer Decides a pair, or returns `undefined` to fall through.
+ * @returns Whether `a` and `b` are equal under `customizer`.
+ * @example
+ * ```ts
+ * class Point {
+ *   constructor(public x: number, public y: number) {}
+ * }
+ * const byFields = (a: unknown, b: unknown) =>
+ *   a instanceof Point && b instanceof Point ? a.x === b.x && a.y === b.y : undefined
+ * isEqualWith([new Point(1, 2)], [new Point(1, 2)], byFields) // true
+ * ```
+ */
+export function isEqualWith(a, b, customizer) {
+    if (typeof customizer !== 'function')
+        throw new TypeError('customizer must be a function');
+    return guardDepth(() => equalValues(a, b, undefined, new Session(customizer)));
+}

package/dist/object/matches.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Partial deep matching: `isMatch`, `matches`.
+ */
+/**
+ * True when `obj` has every key of `source`, deeply, with an {@link isEqual} value, as lodash's
+ * `isMatch` checks. A plain object in `source` matches an object with at least its own enumerable
+ * keys, symbols included, and a key whose source value is `undefined` must be present with the
+ * value `undefined`. An array in `source` matches an array that holds a match for each of its
+ * elements, each element of `obj` serving one, so arrays match as subsets in any order. A hole is
+ * not an element: it wants nothing in `source` and offers nothing in `obj`, as an absent key does.
+ * Anything else in `source`, a `Date` or `Map` included, must be {@link isEqual} to the value found.
+ * At the top, `obj` may be any value: a primitive is read as its boxed form, and `null` or
+ * `undefined` matches only a `source` with no keys.
+ *
+ * Cycles are assumed to match, and each pair of objects is answered once.
+ * @param obj The value to test.
+ * @param source The partial shape to look for.
+ * @returns Whether `obj` matches.
+ * @throws {RangeError} past 1000 levels of nesting, or past 33554432 steps of work.
+ * @example
+ * ```ts
+ * isMatch({ a: 1, b: { c: 2, d: 3 } }, { b: { c: 2 } }) // true
+ * isMatch({ tags: ['a', 'b', 'c'] }, { tags: ['c', 'a'] }) // true
+ * isMatch({ a: 1 }, { a: undefined }) // false
+ * isMatch({}, { a: {} }) // false
+ * ```
+ */
+export declare function isMatch(obj: unknown, source: unknown): boolean;
+/**
+ * A predicate that tells whether a value matches `source`, by the rules of {@link isMatch}; it is
+ * lodash's `matches` shorthand as a function to pass to `filter`, `find` and the like.
+ * @param source The partial shape to look for.
+ * @returns `(obj) => isMatch(obj, source)`.
+ * @example
+ * ```ts
+ * const users = [{ name: 'a', active: true }, { name: 'b', active: false }]
+ * users.filter(matches({ active: true })) // [{ name: 'a', active: true }]
+ * ```
+ */
+export declare function matches(source: unknown): (obj: unknown) => boolean;