Summary
Changes
Please provide a summary of what's being changed
What were you searching in the docs?
I was reading the API reference for isStrictEqual in the commons package to understand how it compares arrays.
Is this related to an existing documentation section?
https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/packages/commons/src/typeUtils.ts
How can we improve?
The JSDoc for isStrictEqual and areArraysEqual says array comparison is "regardless of order", but the implementation is order-dependent. It compares elements at the same index: left.every((value, i) => isStrictEqual(value, right[i])).
The existing unit test confirms this: isStrictEqual([1, 2, 3], [1, 3, 2]) is expected to return false.
Two things in the JSDoc are wrong:
areArraysEqual says "This function compares each element in the arrays, regardless of order." It should say something like "at the same position".isStrictEqual has the same issue. The code example shows isStrictEqual([1, 2, 3], [3, 2, 1]) // true, but the actual return value is false.
Suggestion:
- Change "regardless of order" to "at the same position" in both JSDoc blocks.
- Update the
isStrictEqual example: either change [3, 2, 1] to [1, 2, 3], or change the comment from // true to // false.
Acknowledgment
Summary
Changes
What were you searching in the docs?
I was reading the API reference for
isStrictEqualin the commons package to understand how it compares arrays.Is this related to an existing documentation section?
https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/packages/commons/src/typeUtils.ts
How can we improve?
The JSDoc for
isStrictEqualandareArraysEqualsays array comparison is "regardless of order", but the implementation is order-dependent. It compares elements at the same index:left.every((value, i) => isStrictEqual(value, right[i])).The existing unit test confirms this:
isStrictEqual([1, 2, 3], [1, 3, 2])is expected to returnfalse.Two things in the JSDoc are wrong:
areArraysEqualsays "This function compares each element in the arrays, regardless of order." It should say something like "at the same position".isStrictEqualhas the same issue. The code example showsisStrictEqual([1, 2, 3], [3, 2, 1]) // true, but the actual return value isfalse.Suggestion:
isStrictEqualexample: either change[3, 2, 1]to[1, 2, 3], or change the comment from// trueto// false.Acknowledgment