feat(without, difference): Improve TypeScript type inference for without() and difference()

[Yeom-JinHo]

Closed #1503

Description

This PR focuses on improving TypeScript type inference for the without and difference functions.
By adding smart overloads, the return type now narrows correctly when literal values are passed,
while preserving full backward compatibility for general use cases.

No runtime logic has been changed — this update only affects type declarations.

---

Changes

• Type Overloads Added
  Introduced three overloads for both without() and difference():
  1. values: [] → returns T[]
  2. values: V[] → returns Exclude<T, V>[]
  3. values: T[] → fallback for backward compatibility
• Type Consistency
  Ensured difference() and without() now share the same overload pattern and type behavior.
• Readonly Style
  Unified parameter style to readonly T[] for consistency across array utility functions.
• Documentation Updated
  Updated English (without.mdx), Korean (without.ko.mdx), and Japanese (without.ja.mdx) documents to reflect:
  • New overload-based type behavior (Exclude<T, V>[])
  • Unified parameter and return descriptions
  • Type narrowing examples (const result = without(['a','b','c'] as const, 'a') → ('b' | 'c')[])

---

Motivation

• Improve developer experience by providing more accurate and predictable type inference.
• Align the type definitions of difference() with without() to ensure consistent behavior.
• Maintain backward compatibility to avoid breaking any existing usage.

---

Breaking Changes

None.
This change only improves type inference and does not modify runtime behavior or output.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
es-toolkit	Ready	Preview	Comment	Nov 7, 2025 2:53pm

[Copilot]

Pull Request Overview

This PR enhances TypeScript type inference for the without and difference array utility functions by adding function overloads that leverage the Exclude<T, V> utility type to automatically narrow return types when literal values are provided.

Key Changes:

• Added function overloads with improved type inference using Exclude<T, V> for without and difference
• Updated JSDoc comments to document the new generic type parameters and narrowed return types
• Updated documentation across multiple languages (English, Korean, Japanese) to explain the enhanced type inference behavior

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/array/without.ts	Added function overloads for type narrowing with Exclude<T, V> and updated JSDoc
src/array/difference.ts	Added function overloads for type narrowing with Exclude<T, V> and updated JSDoc
docs/reference/array/without.md	Updated documentation to describe enhanced type inference and added type annotations to examples
docs/reference/array/difference.md	Updated documentation to describe enhanced type inference and added type annotations to examples
docs/ko/reference/array/without.md	Updated Korean documentation with type inference details and fixed missing closing quote
docs/ko/reference/array/difference.md	Updated Korean documentation with type inference details
docs/ja/reference/array/without.md	Updated Japanese documentation with type inference details and fixed missing closing quote
docs/ja/reference/array/difference.md	Updated Japanese documentation with type inference details

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Yeom-JinHo]

I understand that this change might look somewhat excessive in terms of overloading —
please let me know if you think so.

I made this update because I believe it’s an important improvement for achieving accurate type inference.

The overload structure remains minimal (three concise layers) and fully backward-compatible,
preserving both implementation simplicity and interface clarity.

Thx