@rbxts/deep-equal
Advanced tools
Recursive comparator for ROBLOX projects.
import { deepEqual } from "@rbxts/deep-equal";
const result = deepEqual([1,2,3], [1,2,4]);
warn(result);
Install deep-equal with your preferred package manager.
npm install @rbxts/deep-equal
pnpm add @rbxts/deep-equal
yarn add @rbxts/deep-equal
deep-equal is an implementation of the common recrusive comparator, but for roblox projects.
Since roblox tables are typically compared by reference, utilizing deep-equal allows you
to compare them by nested values, and get specific failure data on where the comparison failed.
deep-equal is also able to differentiate between arrays and non-array tables, so your comparisons on two arrays can be more array specific.
[!NOTE] deep-equal is built to primarily be used as an implementor of deep equal algorithms for other assertion libraries, or more complex validation systems.
That's why failures return an object of specific failure data, instead of throwing an error.
deepEqual("daymon", "michael");
/**
* {
* failType: FailureType.DIFFERENT_VALUES,
* leftValue: "daymon",
* rightValue: "michael"
* }
*/
deepEqual(5, 10);
/**
* {
* failType: FailureType.DIFFERENT_VALUES,
* leftValue: 5,
* rightValue: 10
* }
*/
deepEqual(true, false);
/**
* {
* failType: FailureType.DIFFERENT_VALUES,
* leftValue: true,
* rightValue: false
* }
*/
deepEqual(5, "5");
/**
* {
* failType: FailureType.DIFFERENT_TYPES,
* leftValue: 5,
* leftType: "number",
* rightValue: "5",
* rightType: "string"
* }
*/
deepEqual([1,2,3], [1,2,4]);
/**
* {
* failType: FailureType.MISSING_ARRAY_VALUE,
* leftValue: [1,2,3],
* rightValue: [1,2,4],
* leftMissing: [4],
* rightMissing: [3]
* }
*/
deepEqual({
name: "daymon",
age: 100
}, {
name: "daymon",
age: 200
});
/**
* {
* failType: FailureType.DIFFERENT_VALUES,
* leftValue: 100,
* rightValue: 200,
* path: "age"
* }
*/
deepEqual({
name: "daymon",
cars: ["Tesla", "Civic"]
}, {
name: "daymon",
cars: ["Tesla"]
});
/**
* {
* failType: FailureType.MISSING_ARRAY_VALUE,
* leftValue: ["Tesla", "Civic"],
* rightValue: ["Tesla"],
* rightMissing: ["Civic"],
* path: "cars"
* }
*/
deepEqual({
name: "daymon",
age: 100
}, {
name: "daymon",
});
/**
* {
* failType: FailureType.MISSING,
* leftValue: 100,
* rightValue: undefined,
* path: "age"
* }
*/
deepEqual({
name: "daymon",
details: {
origin: {
city: "Kansas City",
state: "MO"
}
}
}, {
name: "daymon",
details: {
origin: {
city: "Kansas City",
state: "KS"
}
}
});
/**
* {
* failType: FailureType.DIFFERENT_VALUES,
* leftValue: "MO",
* rightValue: "KS",
* path: "details.origin.state"
* }
*/
Roblox types can be split into two categories: ones that are compared by value and ones that are compared by reference.
deepEqual(new Vector3(1,2,3), new Vector3(1,2,3)); // pass
deepEqual(new Vector3(1,2,3), new Vector3(2,4,6));
/**
* {
* failType: FailureType.DIFFERENT_VALUES,
* leftValue: (1, 2, 3),
* rightValue: (2, 4, 6)
* }
*/
[!TIP] You can provide custom comparators for comparing reference types.
deepEqual(new OverlapParams(), new OverlapParams());
/**
* {
* failType: FailureType.DIFFERENT_REFERENCE,
* leftValue: "OverlapParams{...}",
* rightValue: "OverlapParams{...}"
* }
*/
You can optionally provide some configuration in your calls to deep-equal, or set them at the global level.
An array of types to ignore.
deepEqual({
name: "daymon",
position: new Vector3(1,2,3),
cars: ["Tesla", "Civic"]
}, {
name: "daymon",
position: new Vector3(2,4,6),
cars: ["Tesla"]
}, { ignore: ["Vector3"] });
/**
* {
* failType: FailureType.MISSING_ARRAY_VALUE,
* leftValue: ["Tesla", "Civic"],
* rightValue: ["Tesla"],
* rightMissing: ["Civic"],
* path: "cars"
* }
*/
When the left or right is any of these types,
it will be skipped; effectively "ignoring" it for the
purposes of checking if two objects are equal.
An array of types to only compare by reference.
deepEqual(new Vector3(1,2,3), new Vector3(2,4,6), { referenceOnly: ["Vector3"] });
/**
* {
* failType: FailureType.DIFFERENT_REFERENCE,
* leftValue: (1, 2, 3),
* rightValue: (2, 4, 6)
* }
*/
Some roblox types are compared by value instead of reference. Adding
said types to this array will instead force them to be compared by reference instead, with a FailureType.DIFFERENT_REFERENCE
failure type attached.
Check for missing values from the right in comparison to the left.
deepEqual({
name: "daymon",
cars: ["Tesla", "Civic"]
}, {
name: "daymon",
cars: ["Tesla", "Mustang"]
}, { rightMissing: true });
/**
* {
* failType: FailureType.MISSING_ARRAY_VALUE,
* leftValue: ["Tesla", "Civic"],
* rightValue: ["Tesla", "Mustang"],
* leftMissing: ["Mustang"]
* rightMissing: ["Civic"],
* path: "cars"
* }
*/
Since this setting is enabled by default, its usage is primarily for disabling it when you only want to check certain values- while ignoring others.
deepEqual({
name: "daymon",
details: {
origin: {
city: "Kansas City",
state: "MO"
}
}
}, {
details: {
origin: {
state: "KS"
}
}
}, { rightMissing: false });
/**
* {
* failType: FailureType.DIFFERENT_VALUES,
* leftValue: "MO",
* rightValue: "KS",
* path: "details.origin.state"
* }
*/
Compares arrays in order instead of by missing.
deepEqual({
name: "daymon",
cars: ["Tesla", "Civic"]
}, {
name: "daymon",
cars: ["Tesla"]
});
/**
* {
* failType: FailureType.DIFFERENT_VALUES,
* leftValue: "Civic",
* rightValue: undefined,
* path: "cars.[1]"
* }
*/
By default, arrays are looked at in their entirety and a
list of elements missing from either (depending on if
checkRightMissing is enabled) is provided.
You can enable inOrder to instead throw at the first failure,
with data pertaining to where the failure occurred.
Useful when working with arrays of complex types, or when you want to assert that an array is "exactly in order".
If you want to provide your own behavior for certain types (like reference types) or override existing behavior, you can provide your own methods for certain types.
const checkInstance: CustomChecker<"Instance"> = (config, left, right) => {
if(left.Name === right.Name) return Option.none();
return return Option.some({
failType: FailureType.DIFFERENT_VALUES,
leftValue: left.Name,
rightValue: right.Name,
leftMissing: [],
rightMissing: [],
leftType: "Instance",
rightType: "Instance",
path: "",
});
};
deepEqual(Workspace.Part1, Workspace.Part2, {
customCheckers: {
Instance: checkInstance
}
});
![TIP] By default, deep-equal provides some checkers for certain reference types out of the box that are already attached to the default config!
Take a look at the checkers directory to see which types, and further examples of custom comparators.
If you have configurations you want to apply to all usages of deep-equal, you can set a global configuration.
setDefaultDeepEqualConfig({
customCheckers: {
Instance: checkInstance
}
});
deepEqual(Workspace.Part1, Workspace.Part2); // inherits the default config
[!WARNING]
setDefaultDeepEqualConfigreplaces any previously set default config- it does not merge them.You can use the provided
getDefaultDeepEqualConfigandmergeConfigsfunctions to add this behavior on your own, but the default config is not intended to be used in such a way- which is why this behavior is not provided out of the box.
Instance comparators.If you're interested in contributing to deep-equal, give the CONTRIBUTING doc a read.
0.8.1
FAQs
Recursive comparator for ROBLOX projects.
The npm package @rbxts/deep-equal receives a total of 20 weekly downloads. As such, @rbxts/deep-equal popularity was classified as not popular.
We found that @rbxts/deep-equal demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Snyk's use of malicious npm packages for research raises ethical concerns, highlighting risks in public deployment, data exfiltration, and unauthorized testing.
Research
Security News
Socket researchers found several malicious npm packages typosquatting Chalk and Chokidar, targeting Node.js developers with kill switches and data theft.
Security News
pnpm 10 blocks lifecycle scripts by default to improve security, addressing supply chain attack risks but sparking debate over compatibility and workflow changes.