Bug Fix: Sorting Logic Bug

[gbabaisaac]

Issue

Leaderboard sorting fails when values match.

Fix Ideas

• Use stable sorting with secondary key

Acceptance Criteria

• Deterministic ordering
• Include short write-up: cause + fix
• Screenshots (if UI)

[ipezygj]

Bug Fix: Leaderboard Sorting Stability

Root Cause Analysis

The bug occurs because JavaScript's Array.prototype.sort() is not guaranteed to be stable across all engines (though V8 has been stable since Node 11+), and more critically, when two entries share the same primary sort value (e.g., score), there is no secondary sort key — producing non-deterministic, arbitrary ordering that can flip between renders, API calls, or server instances.

---

The Fix

leaderboard.js — Core Sorting Utility

/**
 * leaderboard.js
 * Stable, deterministic leaderboard sorting with configurable keys.
 */

/**
 * Sorts leaderboard entries with a stable, multi-key comparison.
 *
 * Primary:   score          (descending)
 * Secondary: achievedAt     (ascending  — earlier timestamp wins ties)
 * Tertiary:  userId         (ascending  — lexicographic, fully deterministic)
 *
 * @param {LeaderboardEntry[]} entries
 * @param {SortOptions}        [options]
 * @returns {LeaderboardEntry[]}  New sorted array (original is not mutated)
 *
 * @typedef {{ userId: string, score: number, achievedAt: string|Date }} LeaderboardEntry
 * @typedef {{ primaryKey?: string, order?: 'asc'|'desc' }} SortOptions
 */
function sortLeaderboard(entries, options = {}) {
  const { primaryKey = 'score', order = 'desc' } = options;
  const direction = order === 'desc' ? -1 : 1;

  // Shallow-clone to avoid mutating the caller's array
  return [...entries].sort((a, b) => {
    // ── 1. Primary key (e.g. score) ───────────────────────────────────────
    const primaryDiff = (a[primaryKey] - b[primaryKey]) * direction;
    if (primaryDiff !== 0) return primaryDiff;

    // ── 2. Secondary: achievedAt — earlier timestamp ranks higher ─────────
    const timeA = new Date(a.achievedAt).getTime();
    const timeB = new Date(b.achievedAt).getTime();
    const timeDiff = timeA - timeB; // ascending: earlier is better
    if (timeDiff !== 0) return timeDiff;

    // ── 3. Tertiary: userId — pure lexicographic tie-breaker ──────────────
    //    Guarantees identical output regardless of input order or JS engine.
    return a.userId < b.userId ? -1 : a.userId > b.userId ? 1 : 0;
  });
}

module.exports = { sortLeaderboard };

---

leaderboard.test.js — Full Test Coverage

const { sortLeaderboard } = require('./leaderboard');

// ── Fixtures ───────────────────────────────────────────────────────────────
const BASE_ENTRIES = [
  { userId: 'user-c', score: 100, achievedAt: '2024-01-03T10:00:00Z' },
  { userId: 'user-a', score: 200, achievedAt: '2024-01-01T10:00:00Z' },
  { userId: 'user-b', score: 100, achievedAt: '2024-01-02T10:00:00Z' },
  { userId: 'user-d', score: 200, achievedAt: '2024-01-01T10:00:00Z' }, // same score AND time as user-a
];

describe('sortLeaderboard', () => {
  describe('primary key (score)', () => {
    it('sorts by score descending by default', () => {
      const result = sortLeaderboard(BASE_ENTRIES);
      expect(result[0].score).toBe(200);
      expect(result[result.length - 1].score).toBe(100);
    });

    it('sorts by score ascending when specified', () => {
      const result = sortLeaderboard(BASE_ENTRIES, { order: 'asc' });
      expect(result[0].score).toBe(100);
      expect(result[result.length - 1].score).toBe(200);
    });
  });

  describe('secondary key (achievedAt) — tie-breaking', () => {
    it('ranks earlier timestamp higher when scores are equal', () => {
      const tied = [
        { userId: 'user-late',  score: 100, achievedAt: '2024-01-03T10:00:00Z' },
        { userId: 'user-early', score: 100, achievedAt: '2024-01-01T10:00:00Z' },
      ];
      const result = sortLeader

---
**Payment:** `0xa32ca744f86a91eaf567e2be4902f64bc33c2813`

[Fred-Zhang83]

我可以来做这个（如果确实是有偿/悬赏任务的话）。为了对齐预期并尽快开始，麻烦确认几件事：

1. 悬赏/报酬金额与结算方式（是 GitHub Sponsors / Bounty 平台 / 直接转账？）
2. 验收标准（通过哪些测试/功能点算完成？）
3. 期望交付形式（PR 合并即算？还是需要 release/文档/示例？）

你补充以上信息后，我可以先给出实现方案与预计工期，然后直接开 PR 推进。

[Pitrat-wav]

I've implemented deterministic sorting with reputation and name as tie-breakers for Issue #8. PR: #37