Advanced Comparators

function caseInsensitive<T>(fn: (value: T) => string): Comparator<T>

// ❌ Case-sensitive (default)
['banana', 'Apple', 'cherry', 'BANANA'].sort()
// => ['Apple', 'BANANA', 'banana', 'cherry']
//     ^ Uppercase first (not intuitive for users)

// ✅ Case-insensitive
import { caseInsensitive } from '@ontologyio/receta/compare'

['banana', 'Apple', 'cherry', 'BANANA'].sort(caseInsensitive(x => x))
// => ['Apple', 'banana', 'BANANA', 'cherry']
//     ^ Alphabetical regardless of case

import { caseInsensitive } from '@ontologyio/receta/compare'

const files = [
  'README.md',
  'index.ts',
  'App.tsx',
  'package.json',
  'API.md'
]

// Case-sensitive (default) - uppercase first
files.sort()
// => ['API.md', 'App.tsx', 'README.md', 'index.ts', 'package.json']

// Case-insensitive - truly alphabetical
files.sort(caseInsensitive(x => x))
// => ['API.md', 'App.tsx', 'index.ts', 'package.json', 'README.md']

interface User {
  username: string
  displayName: string
}

const users: User[] = [
  { username: 'alice', displayName: 'Alice Smith' },
  { username: 'BOB', displayName: 'Bob Jones' },
  { username: 'Charlie', displayName: 'Charlie Brown' }
]

// Sort by username (case-insensitive)
users.sort(caseInsensitive(u => u.username))
// => [alice, BOB, Charlie] (alphabetical)

interface SearchResult {
  title: string
  relevance: number
}

// Sort alphabetically (case-insensitive) after filtering
const results = searchResults
  .filter(r => r.relevance > 0.5)
  .sort(caseInsensitive(r => r.title))

interface Tag {
  name: string
  count: number
}

const tags: Tag[] = [
  { name: 'TypeScript', count: 50 },
  { name: 'javascript', count: 100 },
  { name: 'REACT', count: 75 }
]

// Alphabetical tag list (case-insensitive)
tags.sort(caseInsensitive(t => t.name))
// => [javascript, REACT, TypeScript]

interface Repository {
  name: string
  stars: number
  language: string
}

// Sort repos by name (case-insensitive)
repos.sort(caseInsensitive(r => r.name))

// Multi-level: language (case-insensitive), then stars (descending)
repos.sort(
  compose(
    caseInsensitive(r => r.language),
    descending(r => r.stars)
  )
)

interface SelectOption {
  label: string
  value: string
}

// Sort dropdown options alphabetically (case-insensitive)
options.sort(caseInsensitive(o => o.label))

function localeCompare<T>(
  fn: (value: T) => string,
  locale: string
): Comparator<T>

// ❌ ASCII sorting (wrong for non-English)
['Zürich', 'Berlin', 'Åarhus'].sort()
// => Depends on implementation, often wrong

// ✅ Locale-aware sorting
import { localeCompare } from '@ontologyio/receta/compare'

['Zürich', 'Berlin', 'Åarhus'].sort(localeCompare(x => x, 'de-DE'))
// => Correct German ordering

import { localeCompare } from '@ontologyio/receta/compare'

const germanCities = [
  'Zürich',
  'Berlin',
  'München',
  'Hamburg'
]

// German locale (handles ü, ö correctly)
germanCities.sort(localeCompare(x => x, 'de-DE'))
// => Correct German alphabetical order

const frenchNames = [
  'Étienne',
  'Eric',
  'Émile',
  'Éric'
]

// French locale (handles é, è, ê correctly)
frenchNames.sort(localeCompare(x => x, 'fr-FR'))
// => Correct French ordering (é variations grouped correctly)

const spanishWords = [
  'mañana',
  'manana',
  'manzana',
  'mano'
]

// Spanish locale (ñ comes after n)
spanishWords.sort(localeCompare(x => x, 'es-ES'))
// => [mano, manana, manzana, mañana]

const swedishWords = [
  'öga',
  'ärlig',
  'adam',
  'åsa'
]

// Swedish locale (å, ä, ö come after z)
swedishWords.sort(localeCompare(x => x, 'sv-SE'))
// => [adam, åsa, ärlig, öga]

const japaneseWords = [
  'さくら',  // sakura
  'あさひ',  // asahi
  'たけし'   // takeshi
]

// Japanese locale
japaneseWords.sort(localeCompare(x => x, 'ja-JP'))
// => Correct hiragana ordering

interface User {
  name: string
  country: string
  locale: string
}

// Sort users by their locale
function sortUsersByLocale(users: User[]): User[] {
  // Group by locale, sort within each group
  const grouped = R.groupBy(users, u => u.locale)

  return Object.entries(grouped).flatMap(([locale, users]) =>
    users.sort(localeCompare(u => u.name, locale))
  )
}

interface Product {
  name: string
  nameTranslations: Record<string, string>
}

function sortProductsForLocale(
  products: Product[],
  locale: string
): Product[] {
  return products.sort(
    localeCompare(p => p.nameTranslations[locale] || p.name, locale)
  )
}

// German users see German-sorted names
sortProductsForLocale(products, 'de-DE')

// French users see French-sorted names
sortProductsForLocale(products, 'fr-FR')

interface Contact {
  firstName: string
  lastName: string
  country: string
}

function sortContacts(contacts: Contact[], userLocale: string) {
  return contacts.sort(
    compose(
      localeCompare(c => c.lastName, userLocale),
      localeCompare(c => c.firstName, userLocale)
    )
  )
}

interface FileEntry {
  name: string
  type: 'directory' | 'file'
  locale: string
}

function sortFiles(files: FileEntry[], userLocale: string) {
  return files.sort(
    compose(
      ascending(f => f.type === 'directory' ? 0 : 1), // Directories first
      localeCompare(f => f.name, userLocale)         // Then locale-aware by name
    )
  )
}

interface Player {
  name: string
  score: number
  country: string
}

// Sort by score, then name (locale-aware)
function sortLeaderboard(players: Player[], locale: string) {
  return players.sort(
    compose(
      descending(p => p.score),
      localeCompare(p => p.name, locale)
    )
  )
}

// caseInsensitive() converts to lowercase internally
// Slight overhead, but usually negligible

// For very large lists, consider:
const normalized = items.map(item => ({
  ...item,
  lowerName: item.name.toLowerCase()
}))
normalized.sort(ascending(x => x.lowerName))

// localeCompare() is slower than simple string comparison
// Consider caching if sorting frequently:

const collator = new Intl.Collator('de-DE')
items.sort((a, b) => collator.compare(a.name, b.name))

// Or use localeCompare() for clarity (uses String.prototype.localeCompare)
items.sort(localeCompare(x => x.name, 'de-DE'))