index/functions/deduplicateByKey.md

deduplicateByKey<T>(items, keyFn, keepFirst?): T[]

Remove duplicate items from array based on key function

Returns a new array with duplicate items removed, maintaining original order. Determines uniqueness by comparing the result of keyFn for each item.

Consolidates 6+ occurrences of deduplication patterns in:

• Event deduplication (by transaction ID, pool ID, etc.)
• Position result deduplication
• Pool discovery deduplication

Related to groupByKey() in array-helpers.ts but returns deduplicated array instead of grouped Map structure.

Type Parameters

Type Parameter	Description
T	Type of items in array

Parameters

Parameter	Type	Description
items	T[]	Array of items to deduplicate (may contain duplicates)
keyFn	(item) => unknown	Function that computes uniqueness key for each item
keepFirst?	boolean	If true, keeps first occurrence; if false, keeps last (default: true)

Returns

T[]

New array with duplicates removed, original order maintained

Examples

Basic deduplication

interface Position {
  id: string;
  amount: string;
}

const positions: Position[] = [
  { id: '1', amount: '100' },
  { id: '2', amount: '200' },
  { id: '1', amount: '150' }, // Duplicate ID
];

const unique = deduplicateByKey(positions, (pos) => pos.id);
// Returns: [{ id: '1', amount: '100' }, { id: '2', amount: '200' }]
// (first occurrence of id '1' is kept)

String key deduplication

interface Event {
  txId: string;
  type: string;
  timestamp: number;
}

const events: Event[] = [
  { txId: 'abc', type: 'swap', timestamp: 1000 },
  { txId: 'def', type: 'liquidity', timestamp: 2000 },
  { txId: 'abc', type: 'swap', timestamp: 1500 }, // Duplicate txId
];

const deduplicated = deduplicateByKey(events, (e) => e.txId);
// Returns: [{ txId: 'abc', type: 'swap', timestamp: 1000 }, ...]

Keep last occurrence

const items = [
  { id: 'a', value: 1 },
  { id: 'b', value: 2 },
  { id: 'a', value: 3 }, // Same id, newer value
];

const lastOccurrence = deduplicateByKey(
  items,
  (item) => item.id,
  false // Keep last occurrence
);
// Returns: [{ id: 'b', value: 2 }, { id: 'a', value: 3 }]

Composite key deduplication

interface Pair {
  token0: string;
  token1: string;
  fee: number;
}

const pairs: Pair[] = [
  { token0: 'GALA', token1: 'GUSDC', fee: 3000 },
  { token0: 'GALA', token1: 'GWETH', fee: 3000 },
  { token0: 'GALA', token1: 'GUSDC', fee: 3000 }, // Duplicate
];

const uniquePairs = deduplicateByKey(
  pairs,
  (pair) => `${pair.token0}/${pair.token1}/${pair.fee}`
);
// Returns: [
//   { token0: 'GALA', token1: 'GUSDC', fee: 3000 },
//   { token0: 'GALA', token1: 'GWETH', fee: 3000 }
// ]