A value equality utility library.
npm install @a11d/equals@a11d/equalsValue equality for JavaScript. Compares objects, arrays, maps, sets, and functions by structure instead of reference.
``typescript
import '@a11d/equals'
import { equals } from '@a11d/equals'
const obj1 = { a: 1, b: [1, 2, 3] }
const obj2 = { a: 1, b: [1, 2, 3] }
Objectequals // true
obj1 === obj2 // false
`
`bash`
npm install @a11d/equals
Two APIs available:
Symbol-based (recommended):
`typescript`
import { equals } from '@a11d/equals'
objequals
Global methods (for .equals() syntax or when the symbol conflicts with other libraries):`typescript`
import '@a11d/equals/global'
obj.equals(other)
Objects — Deep comparison of properties. Requires same constructor and all property values to be equal.
Objects with valueOf()
Compared by their primitive values:
`typescript
const a = { valueOf: () => 1 }
const b = { valueOf: () => 1 }
Objectequals // true
`
undefined vs absence
Missing properties and undefined values are treated as equal, but null is different:
`typescript
const obj1 = { a: 1, b: undefined }
const obj2 = { a: 1 }
const obj3 = { a: 1, b: null }
Objectequals // true
Objectequals // false
`
Prototype-less objects
Objects created with Object.create(null) work fine:
`typescript
const a = Object.create(null)
a.prop = 'value'
const b = { prop: 'value' }
Objectequals // true
`
Arrays — Element-by-element comparison.
Nested structures are compared deeply:
`typescript
const arr1 = [1, 2, { key: 'value' }]
const arr2 = [1, 2, { key: 'value' }]
Objectequals // true
`
Maps & Sets — Entry/element comparison with deep equality.
Values and elements are compared deeply. Note that Map keys are compared by identity:
`typescript
const map1 = new Map([['a', { id: 1 }], ['b', { id: 2 }]])
const map2 = new Map([['a', { id: 1 }], ['b', { id: 2 }]])
const set1 = new Set([1, { key: 'value' }])
const set2 = new Set([1, { key: 'value' }])
Objectequals // true
Objectequals // true
`
Functions — Functions with identical string representation are equal.
`typescript
const fn1 = () => 42
const fn2 = () => 42
Objectequals // true
`
Note: This compares the .toString() output, so functions with the same code but different names or closures may differ.
Implement the equals symbol (or .equals() method with global API):
`typescript
import { equals } from '@a11d/equals'
class Person {
constructor(public name: string, public age: number) {}
equals: boolean {
return other instanceof Person
&& this.name === other.name
&& this.age === other.age
}
}
`
Use hasChanged to trigger re-renders only on structural changes:
`typescript
import { hasChanged } from '@a11d/equals'
class MyComponent extends Component {
@property({ type: Object, hasChanged })
data = { name: 'John', items: [1, 2, 3] }
}
``
Without this, Lit re-renders whenever you assign a new object reference, even if the content is identical.