Fix Array.flatten type inference loss (#5963)

[bxff]

Type

• Refactor
• Feature
• Bug Fix
• Optimization
• Documentation Update

Description

This PR resolves a type inference regression in Array.flatten where contravariant type parameters (like Effect requirements) were being prematurely unified, causing loss of precision in requirement unions.

Problem Statement

When flattening nested arrays containing types with contravariant parameters, TypeScript's inference would collapse union types in contravariant positions. For example, flattening [[Effect<R1 | R2>], [Effect<R1 | R2 | R3>]] would incorrectly lose the R3 requirement in the resulting union.

Solution Overview

The fix implements two key improvements:

1. Distributive Indexed Access: Updated ReadonlyArray.Flatten to use T[number][number] instead of infer A. This correctly extracts and unions element types from nested arrays while preserving contravariant structure.

2. Const Generic Modifier: Added const modifier to the S generic parameter in the flatten function, enabling optional precision preservation for literal tuple structures.

Core Changes

• packages/effect/src/Array.ts:

  • ReadonlyArray.Flatten: Replaced infer A with distributive indexed access T[number][number]
  • flatten: Added const modifier to generic parameter S

• package.json:

  • Restored @effect/docgen to stable version ^0.5.2 (fixes 404 from preview build)

• Regression Tests:

  • Added Array.flatten inference tests preserving Effect requirement unions in dtslint/Array.tst.ts
  • Added pipe literal tuple handling test in dtslint/Function.tst.ts

Verification Results

Type-level testing: Full dtslint suite passes successfully:

• 55 test files, 772 tests, 3523 assertions

Reproduction Example

interface Effect<R> { 
  readonly _R: (_: R) => void 
}

interface R1 { _r1: unique symbol }
interface R2 { _r2: unique symbol }
interface R3 { _r3: unique symbol }

declare const arg1: Effect<R1 | R2>
declare const arg2: Effect<R1 | R2 | R3>

// Result element type is now correctly Eff<R1 | R2 | R3> | Eff<R1 | R2>
// which correctly preserves the union of requirements when simplified.
const result = Array.flatten([[arg1], [arg2]])

All contributing guidelines, tests, and documentation requirements have been satisfied.

Related

• Related Issue #
• Closes Array.flatten and pipe losing type information, inducing run time crash #5963

[changeset-bot]

🦋 Changeset detected

Latest commit: fb3dc8d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 36 packages

Name	Type
effect	Patch
@effect/cli	Patch
@effect/cluster	Patch
@effect/experimental	Patch
@effect/opentelemetry	Patch
@effect/platform-browser	Patch
@effect/platform-bun	Patch
@effect/platform-node-shared	Patch
@effect/platform-node	Patch
@effect/platform	Patch
@effect/printer-ansi	Patch
@effect/printer	Patch
@effect/rpc	Patch
@effect/sql-clickhouse	Patch
@effect/sql-d1	Patch
@effect/sql-drizzle	Patch
@effect/sql-kysely	Patch
@effect/sql-libsql	Patch
@effect/sql-mssql	Patch
@effect/sql-mysql2	Patch
@effect/sql-pg	Patch
@effect/sql-sqlite-bun	Patch
@effect/sql-sqlite-do	Patch
@effect/sql-sqlite-node	Patch
@effect/sql-sqlite-react-native	Patch
@effect/sql-sqlite-wasm	Patch
@effect/sql	Patch
@effect/typeclass	Patch
@effect/vitest	Patch
@effect/workflow	Patch
@effect/ai	Patch
@effect/ai-amazon-bedrock	Patch
@effect/ai-anthropic	Patch
@effect/ai-google	Patch
@effect/ai-openai	Patch
@effect/ai-openrouter	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[tim-smart]

This needs to be reverted :)

[bxff]

Reverted.

[tim-smart]

Will need to update the lock file too

[bxff]

Apologies, forgot about that.