refactor: update GetCollectionsForUrlUseCase to support sorting and pagination

Co-authored-by: aider (anthropic/claude-sonnet-4-5-20250929) <[e-mail]>

src/modules/cards/application/useCases/queries/GetCollectionsForUrlUseCase.ts

···
 import { Result, ok, err } from '../../../../../shared/core/Result';
 import { UseCase } from '../../../../../shared/core/UseCase';
-import { ICollectionQueryRepository } from '../../../domain/ICollectionQueryRepository';
+import {
+  ICollectionQueryRepository,
+  CollectionSortField,
+  SortOrder,
+} from '../../../domain/ICollectionQueryRepository';
 import { URL } from '../../../domain/value-objects/URL';
 
 export interface GetCollectionsForUrlQuery {
   url: string;
   page?: number;
   limit?: number;
+  sortBy?: CollectionSortField;
+  sortOrder?: SortOrder;
 }
 
 export interface CollectionForUrlDTO {
···
     hasMore: boolean;
     limit: number;
   };
+  sorting: {
+    sortBy: CollectionSortField;
+    sortOrder: SortOrder;
+  };
 }
 
 export class ValidationError extends Error {
···
     // Set defaults
     const page = query.page || 1;
     const limit = Math.min(query.limit || 20, 100); // Cap at 100
+    const sortBy = query.sortBy || CollectionSortField.NAME;
+    const sortOrder = query.sortOrder || SortOrder.ASC;
 
     try {
       // Execute query to get collections containing cards with this URL
···
         {
           page,
           limit,
+          sortBy,
+          sortOrder,
         },
       );
 
···
           totalCount: result.totalCount,
           hasMore: result.hasMore,
           limit,
+        },
+        sorting: {
+          sortBy,
+          sortOrder,
         },
       });
     } catch (error) {

src/modules/cards/domain/ICollectionQueryRepository.ts

···
 export interface CollectionForUrlQueryOptions {
   page: number;
   limit: number;
+  sortBy: CollectionSortField;
+  sortOrder: SortOrder;
 }
 
 export interface ICollectionQueryRepository {

src/modules/cards/infrastructure/repositories/DrizzleCollectionQueryRepository.ts

···
     options: CollectionForUrlQueryOptions,
   ): Promise<PaginatedQueryResult<CollectionForUrlDTO>> {
     try {
-      const { page, limit } = options;
+      const { page, limit, sortBy, sortOrder } = options;
       const offset = (page - 1) * limit;
+
+      // Build the sort order
+      const orderDirection = sortOrder === SortOrder.ASC ? asc : desc;
 
       // Find all URL cards with this URL
       const urlCardsQuery = this.db
···
 
       const cardIds = urlCardsResult.map((card) => card.id);
 
-      // Find all collections that contain any of these cards with pagination
+      // Find all collections that contain any of these cards with pagination and sorting
       const collectionsQuery = this.db
         .selectDistinct({
           id: collections.id,
···
           description: collections.description,
           authorId: collections.authorId,
           uri: publishedRecords.uri,
+          createdAt: collections.createdAt,
+          updatedAt: collections.updatedAt,
+          cardCount: collections.cardCount,
         })
         .from(collections)
         .leftJoin(
···
           eq(collections.id, collectionCards.collectionId),
         )
         .where(inArray(collectionCards.cardId, cardIds))
-        .orderBy(asc(collections.name))
+        .orderBy(orderDirection(this.getSortColumn(sortBy)))
         .limit(limit)
         .offset(offset);
 
···
       case CollectionSortField.CARD_COUNT:
         return collections.cardCount;
       default:
-        return collections.updatedAt;
+        return collections.name;
     }
   }
 }

src/modules/cards/tests/application/GetCollectionsForUrlUseCase.test.ts

···
 import { CardTypeEnum } from '../../domain/value-objects/CardType';
 import { URL } from '../../domain/value-objects/URL';
 import { PublishedRecordId } from '../../domain/value-objects/PublishedRecordId';
+import { CollectionSortField, SortOrder } from '../../domain/ICollectionQueryRepository';
 
 describe('GetCollectionsForUrlUseCase', () => {
   let useCase: GetCollectionsForUrlUseCase;
···
 
       expect(response.pagination.currentPage).toBe(1);
       expect(response.pagination.limit).toBe(20);
+    });
+  });
+
+  describe('Sorting', () => {
+    it('should use default sorting parameters (NAME, ASC)', async () => {
+      const testUrl = 'https://example.com/test-article';
+
+      const query = {
+        url: testUrl,
+      };
+
+      const result = await useCase.execute(query);
+      expect(result.isOk()).toBe(true);
+      const response = result.unwrap();
+
+      expect(response.sorting.sortBy).toBe(CollectionSortField.NAME);
+      expect(response.sorting.sortOrder).toBe(SortOrder.ASC);
+    });
+
+    it('should use provided sorting parameters', async () => {
+      const testUrl = 'https://example.com/test-article';
+
+      const query = {
+        url: testUrl,
+        sortBy: CollectionSortField.CREATED_AT,
+        sortOrder: SortOrder.DESC,
+      };
+
+      const result = await useCase.execute(query);
+      expect(result.isOk()).toBe(true);
+      const response = result.unwrap();
+
+      expect(response.sorting.sortBy).toBe(CollectionSortField.CREATED_AT);
+      expect(response.sorting.sortOrder).toBe(SortOrder.DESC);
+    });
+
+    it('should sort collections by name in ascending order by default', async () => {
+      const testUrl = 'https://example.com/article';
+      const url = URL.create(testUrl).unwrap();
+
+      // Create URL cards
+      const card1 = new CardBuilder()
+        .withCuratorId(curator1.value)
+        .withType(CardTypeEnum.URL)
+        .withUrl(url)
+        .build();
+
+      const card2 = new CardBuilder()
+        .withCuratorId(curator2.value)
+        .withType(CardTypeEnum.URL)
+        .withUrl(url)
+        .build();
+
+      const card3 = new CardBuilder()
+        .withCuratorId(curator3.value)
+        .withType(CardTypeEnum.URL)
+        .withUrl(url)
+        .build();
+
+      if (
+        card1 instanceof Error ||
+        card2 instanceof Error ||
+        card3 instanceof Error
+      ) {
+        throw new Error('Failed to create cards');
+      }
+
+      card1.addToLibrary(curator1);
+      card2.addToLibrary(curator2);
+      card3.addToLibrary(curator3);
+
+      await cardRepository.save(card1);
+      await cardRepository.save(card2);
+      await cardRepository.save(card3);
+
+      // Create collections with names that should be sorted
+      const collectionZ = new CollectionBuilder()
+        .withAuthorId(curator1.value)
+        .withName('Zebra Collection')
+        .build();
+
+      const collectionA = new CollectionBuilder()
+        .withAuthorId(curator2.value)
+        .withName('Apple Collection')
+        .build();
+
+      const collectionM = new CollectionBuilder()
+        .withAuthorId(curator3.value)
+        .withName('Mango Collection')
+        .build();
+
+      if (
+        collectionZ instanceof Error ||
+        collectionA instanceof Error ||
+        collectionM instanceof Error
+      ) {
+        throw new Error('Failed to create collections');
+      }
+
+      collectionZ.addCard(card1.cardId, curator1);
+      collectionA.addCard(card2.cardId, curator2);
+      collectionM.addCard(card3.cardId, curator3);
+
+      await collectionRepository.save(collectionZ);
+      await collectionRepository.save(collectionA);
+      await collectionRepository.save(collectionM);
+
+      const query = {
+        url: testUrl,
+      };
+
+      const result = await useCase.execute(query);
+      expect(result.isOk()).toBe(true);
+      const response = result.unwrap();
+
+      expect(response.collections).toHaveLength(3);
+      expect(response.collections[0]!.name).toBe('Apple Collection');
+      expect(response.collections[1]!.name).toBe('Mango Collection');
+      expect(response.collections[2]!.name).toBe('Zebra Collection');
+    });
+
+    it('should sort collections by name in descending order', async () => {
+      const testUrl = 'https://example.com/article';
+      const url = URL.create(testUrl).unwrap();
+
+      // Create URL cards
+      const card1 = new CardBuilder()
+        .withCuratorId(curator1.value)
+        .withType(CardTypeEnum.URL)
+        .withUrl(url)
+        .build();
+
+      const card2 = new CardBuilder()
+        .withCuratorId(curator2.value)
+        .withType(CardTypeEnum.URL)
+        .withUrl(url)
+        .build();
+
+      const card3 = new CardBuilder()
+        .withCuratorId(curator3.value)
+        .withType(CardTypeEnum.URL)
+        .withUrl(url)
+        .build();
+
+      if (
+        card1 instanceof Error ||
+        card2 instanceof Error ||
+        card3 instanceof Error
+      ) {
+        throw new Error('Failed to create cards');
+      }
+
+      card1.addToLibrary(curator1);
+      card2.addToLibrary(curator2);
+      card3.addToLibrary(curator3);
+
+      await cardRepository.save(card1);
+      await cardRepository.save(card2);
+      await cardRepository.save(card3);
+
+      // Create collections with names that should be sorted
+      const collectionZ = new CollectionBuilder()
+        .withAuthorId(curator1.value)
+        .withName('Zebra Collection')
+        .build();
+
+      const collectionA = new CollectionBuilder()
+        .withAuthorId(curator2.value)
+        .withName('Apple Collection')
+        .build();
+
+      const collectionM = new CollectionBuilder()
+        .withAuthorId(curator3.value)
+        .withName('Mango Collection')
+        .build();
+
+      if (
+        collectionZ instanceof Error ||
+        collectionA instanceof Error ||
+        collectionM instanceof Error
+      ) {
+        throw new Error('Failed to create collections');
+      }
+
+      collectionZ.addCard(card1.cardId, curator1);
+      collectionA.addCard(card2.cardId, curator2);
+      collectionM.addCard(card3.cardId, curator3);
+
+      await collectionRepository.save(collectionZ);
+      await collectionRepository.save(collectionA);
+      await collectionRepository.save(collectionM);
+
+      const query = {
+        url: testUrl,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.DESC,
+      };
+
+      const result = await useCase.execute(query);
+      expect(result.isOk()).toBe(true);
+      const response = result.unwrap();
+
+      expect(response.collections).toHaveLength(3);
+      expect(response.collections[0]!.name).toBe('Zebra Collection');
+      expect(response.collections[1]!.name).toBe('Mango Collection');
+      expect(response.collections[2]!.name).toBe('Apple Collection');
     });
   });
 

src/modules/cards/tests/infrastructure/DrizzleCollectionQueryRepository.getCollectionsWithUrl.integration.test.ts

···
 import { createTestSchema } from '../test-utils/createTestSchema';
 import { CardTypeEnum } from '../../domain/value-objects/CardType';
 import { PublishedRecordId } from '../../domain/value-objects/PublishedRecordId';
+import { CollectionSortField, SortOrder } from '../../domain/ICollectionQueryRepository';
 
 describe('DrizzleCollectionQueryRepository - getCollectionsWithUrl', () => {
   let container: StartedPostgreSqlContainer;
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 1,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       // Verify the result
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 1,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result.items).toHaveLength(0);
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl1, {
         page: 1,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result.items).toHaveLength(1);
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 1,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result.items).toHaveLength(3);
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 1,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result.items).toHaveLength(1);
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 1,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       // Should return the collection only once, even though it has multiple cards with the URL
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 1,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       // Should only return the collection with the URL card, not the NOTE card
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 1,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       // Should return empty since card is not in any collection
       expect(result.items).toHaveLength(0);
     });
 
-    it('should return collections sorted alphabetically by name', async () => {
+    it('should return collections sorted alphabetically by name in ascending order', async () => {
       const testUrl = 'https://example.com/article';
       const url = URL.create(testUrl).unwrap();
 
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 1,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result.items).toHaveLength(3);
···
       expect(result.items[1]!.name).toBe('Mango Collection');
       expect(result.items[2]!.name).toBe('Zebra Collection');
     });
+
+    it('should return collections sorted alphabetically by name in descending order', async () => {
+      const testUrl = 'https://example.com/article';
+      const url = URL.create(testUrl).unwrap();
+
+      // Create URL cards
+      const card1 = new CardBuilder()
+        .withCuratorId(curator1.value)
+        .withType(CardTypeEnum.URL)
+        .withUrl(url)
+        .buildOrThrow();
+
+      const card2 = new CardBuilder()
+        .withCuratorId(curator2.value)
+        .withType(CardTypeEnum.URL)
+        .withUrl(url)
+        .buildOrThrow();
+
+      const card3 = new CardBuilder()
+        .withCuratorId(curator3.value)
+        .withType(CardTypeEnum.URL)
+        .withUrl(url)
+        .buildOrThrow();
+
+      card1.addToLibrary(curator1);
+      card2.addToLibrary(curator2);
+      card3.addToLibrary(curator3);
+
+      await cardRepository.save(card1);
+      await cardRepository.save(card2);
+      await cardRepository.save(card3);
+
+      // Create collections with names that should be sorted
+      const collectionZ = new CollectionBuilder()
+        .withAuthorId(curator1.value)
+        .withName('Zebra Collection')
+        .buildOrThrow();
+
+      const collectionA = new CollectionBuilder()
+        .withAuthorId(curator2.value)
+        .withName('Apple Collection')
+        .buildOrThrow();
+
+      const collectionM = new CollectionBuilder()
+        .withAuthorId(curator3.value)
+        .withName('Mango Collection')
+        .buildOrThrow();
+
+      collectionZ.addCard(card1.cardId, curator1);
+      collectionA.addCard(card2.cardId, curator2);
+      collectionM.addCard(card3.cardId, curator3);
+
+      await collectionRepository.save(collectionZ);
+      await collectionRepository.save(collectionA);
+      await collectionRepository.save(collectionM);
+
+      const result = await queryRepository.getCollectionsWithUrl(testUrl, {
+        page: 1,
+        limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.DESC,
+      });
+
+      expect(result.items).toHaveLength(3);
+      expect(result.items[0]!.name).toBe('Zebra Collection');
+      expect(result.items[1]!.name).toBe('Mango Collection');
+      expect(result.items[2]!.name).toBe('Apple Collection');
+    });
   });
 
   describe('Pagination', () => {
···
       const result1 = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 1,
         limit: 2,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result1.items).toHaveLength(2);
···
       const result2 = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 2,
         limit: 2,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result2.items).toHaveLength(2);
···
       const result3 = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 3,
         limit: 2,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result3.items).toHaveLength(1);
···
       const allCollectionIds = [
         ...result1.items.map((c) => c.id),
         ...result2.items.map((c) => c.id),
-        ...result3.items.map((c) => c.i),
+        ...result3.items.map((c) => c.id),
       ];
       const uniqueCollectionIds = [...new Set(allCollectionIds)];
       expect(uniqueCollectionIds).toHaveLength(5);
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 2,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result.items).toHaveLength(0);
···
       const result = await queryRepository.getCollectionsWithUrl(testUrl, {
         page: 10,
         limit: 10,
+        sortBy: CollectionSortField.NAME,
+        sortOrder: SortOrder.ASC,
       });
 
       expect(result.items).toHaveLength(0);

src/modules/cards/tests/utils/InMemoryCollectionQueryRepository.ts

···
         options.sortOrder,
       );
 
-      const startIndex = (options.page - 1) * options.limit;
+      const start Index = (options.page - 1) * options.limit;
       const endIndex = startIndex + options.limit;
       const paginatedCollections = sortedCollections.slice(
         startIndex,
···
         ),
       );
 
-      // Sort by name (alphabetically)
-      const sortedCollections = [...collectionsWithUrl].sort((a, b) =>
-        a.name.value.localeCompare(b.name.value),
+      // Sort collections
+      const sortedCollections = this.sortCollections(
+        collectionsWithUrl,
+        options.sortBy,
+        options.sortOrder,
       );
 
       // Apply pagination