fix: assertArrayLength narrows to exclude optional undefined

[hughgrigg]

Summary by CodeRabbit

• Refactor

  • Enhanced assertArrayLength to improve type narrowing for optional array properties, providing better TypeScript inference when arrays may be undefined.

• Tests

  • Added test coverage validating type narrowing behavior with optional array inputs.

[coderabbitai]

📝 Walkthrough

Walkthrough

assertArrayLength is refactored from two overloads to a single generic signature accepting unknown[] | null | undefined, narrowing via Extract<NonNullable<TArray>, unknown[]> & ArrayOfLengthMatch<TArray, N>. The ArrayOfLengthMatch type replaces the direct ArrayOfLength import. A new test verifies narrowing of an optional string[] | undefined property to [string].

Changes

assertArrayLength nullable narrowing refactor

Layer / File(s)	Summary
New generic signature, import update, and narrowing test src/assert/array-length/array-length.assert.ts, src/assert/array-length/array-length.test.ts	The two overloads are replaced by a single generic declaration with TArray extends unknown[] | null | undefined and ArrayOfLengthMatch narrowing. The ArrayOfLengthMatch type is added to the import, and a test case is added verifying that an optional string[] | undefined property is narrowed to [string] after the assertion.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hoppity-hop through the type terrain,
No more overloads to juggle and strain!
One signature rules where two used to roam,
Null and undefined now have a home.
Extract and NonNullable guide the way,
The rabbit refactored a cleaner array! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: refactoring assertArrayLength to properly narrow optional undefined types, which is confirmed by the test case and signature updates in the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/hg/assertArrayLength-optional-undefined

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/assert/array-length/array-length.assert.ts (1)

16-29: ⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Critical: Remove the old overload declarations.

These overload signatures should have been removed as part of this refactor. Their presence conflicts with the new generic signature at lines 6-14, causing TypeScript to resolve calls ambiguously. For example, a call with string[] would match both the new signature (line 6) and the overload at line 16, leading to unpredictable type narrowing.

🔧 Remove the conflicting overloads

-export function assertArrayLength<
-  TArray extends unknown[],
-  const N extends number,
->(
-  value: TArray,
-  expectedLength: N,
-  message?: string,
-): asserts value is TArray & ArrayOfLength<TArray[number], N>;
-
-export function assertArrayLength<const N extends number>(
-  value: unknown,
-  expectedLength: N,
-  message?: string,
-): asserts value is ArrayOfLength<unknown, N>;
-
 /**
  * Assert that an array has exactly the expected length, with type narrowing.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/assert/array-length/array-length.assert.ts` around lines 16 - 29, The
assertArrayLength function has duplicate overload declarations that conflict
with the new generic signature, causing ambiguous type resolution. Remove the
two old overload declarations for assertArrayLength (the ones that appear after
the new generic signature) and keep only the new generic signature that is
already defined earlier in the file. These obsolete overloads are no longer
needed and their presence creates conflicting type narrowing behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/assert/array-length/array-length.assert.ts`:
- Around line 16-29: The assertArrayLength function has duplicate overload
declarations that conflict with the new generic signature, causing ambiguous
type resolution. Remove the two old overload declarations for assertArrayLength
(the ones that appear after the new generic signature) and keep only the new
generic signature that is already defined earlier in the file. These obsolete
overloads are no longer needed and their presence creates conflicting type
narrowing behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 30ac3fa8-f95b-4e93-8eb8-0d68479a66da

📥 Commits

Reviewing files that changed from the base of the PR and between e366c95 and 07ad11d.

📒 Files selected for processing (2)

• src/assert/array-length/array-length.assert.ts
• src/assert/array-length/array-length.test.ts