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
setDefaultDeepEqualConfig replaces any previously set
default config- it does not merge them.
You can use the provided getDefaultDeepEqualConfig and
mergeConfigs functions 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.
- Provide better circular reference identification in the failure data.
- Provide a support library for deep
Instancecomparators. - Implement workflow for test coverage.
- Implement tests for provided comparators.
- Add workflow for checking API diff and version bumping according to semver.
- Add note in contributing about checking the api diff.
If you're interested in contributing to deep-equal, give the CONTRIBUTING doc a read.