-
-
Notifications
You must be signed in to change notification settings - Fork 402
Description
Summary
TypeScript 5.9 introduces breaking changes to TypedArray generics that cause type compatibility issues with Effect's Schema.Uint8Array
and potentially other APIs that expose Uint8Array
types.
Problem Description
When using TypeScript 5.9, the following type error occurs:
Type 'Uint8Array<ArrayBufferLike>' is not assignable to type 'Uint8Array<ArrayBuffer>'
Type 'ArrayBufferLike' is not assignable to type 'ArrayBuffer'
Type 'SharedArrayBuffer' is not assignable to type 'ArrayBuffer'
This affects:
Schema.Uint8Array
decoding/encoding operations- APIs that expect
Uint8Array<ArrayBuffer>
but receiveUint8Array<ArrayBufferLike>
- Potentially other Effect APIs that expose
Uint8Array
types (e.g.,Transferable
)
Root Cause
TypeScript 5.9 introduced significant changes to TypedArray handling:
-
TypedArrays are now generic over
ArrayBufferLike
: All TypedArray types (includingUint8Array
) now have a generic type parameter for the underlying buffer type, defaulting toArrayBufferLike
. -
ArrayBufferLike
now includesSharedArrayBuffer
: The union typeArrayBufferLike
now includes bothArrayBuffer
andSharedArrayBuffer
, which have diverging interfaces in ES2024. -
Breaking assignment compatibility:
SharedArrayBuffer
is no longer assignment-compatible withArrayBuffer
due to different capabilities (resizing, growing, etc.).
Reproduction
import { Schema } from "effect"
const uint8ArraySchema = Schema.Uint8Array
// This now fails in TypeScript 5.9
const decoded = Schema.decodeUnknownSync(uint8ArraySchema)(new Uint8Array([1, 2, 3]))
// Type 'Uint8Array<ArrayBufferLike>' is not assignable to type 'Uint8Array<ArrayBuffer>'
// Functions expecting specific Uint8Array<ArrayBuffer> also fail
function processBuffer(data: Uint8Array<ArrayBuffer>) {
// Process buffer
}
processBuffer(decoded) // Type error in TS 5.9
Current Workaround
Currently, the workaround is to cast to the expected type:
const decoded = Schema.decodeUnknownSync(uint8ArraySchema)(new Uint8Array([1, 2, 3])) as Uint8Array<ArrayBuffer>
Proposed Solution
Effect should update its type definitions to handle the new TypeScript 5.9 TypedArray generics properly. This might involve:
-
Updating Schema.Uint8Array: Ensure it properly handles both
ArrayBuffer
andSharedArrayBuffer
cases or explicitly constrains toArrayBuffer
when appropriate. -
Review related APIs: Check other Effect APIs that expose
Uint8Array
types for similar compatibility issues. -
Consider type parameter constraints: Use explicit type parameters like
Uint8Array<ArrayBuffer>
in API signatures whereSharedArrayBuffer
is not intended.
References
- TypeScript 5.9 Release Notes
- TypeScript PR #59417: Make typed arrays generic over ArrayBufferLike
- TypeScript Breaking Changes Documentation
Impact
This issue affects any Effect codebase that:
- Uses
Schema.Uint8Array
for binary data processing - Upgrades to TypeScript 5.9
- Has strict type checking enabled
The issue prevents clean TypeScript compilation without type assertions, potentially masking real type safety issues.