The minimalistic document archiving platform.
feat(documents): add configurable sorting to document search (#1088)
Corentin Thomassetbbe03aa53dd1
diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.tsindex ad8becb7..9549b786 100644--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts@@ -9,8 +9,8 @@ export function createDatabaseFts5DocumentSearchServices({ db }: { db: Databasereturn {name: DATABASE_FTS5_DOCUMENT_SEARCH_PROVIDER_NAME,- searchDocuments: async ({ searchQuery, organizationId, pageIndex, pageSize }) => {- const { documents, documentsCount } = await documentsSearchRepository.searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize });+ searchDocuments: async ({ searchQuery, organizationId, pageIndex, pageSize, sort }) => {+ const { documents, documentsCount } = await documentsSearchRepository.searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize, sort });return {documents,diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.test.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.test.tsindex c7463b61..57ceb08b 100644--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.test.ts+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.test.ts@@ -1,7 +1,8 @@+import type { SQL } from 'drizzle-orm';import { describe, expect, test } from 'vitest';import { stringifySqlQuery } from '../../../app/database/database.models';import { createInMemoryDatabase } from '../../../app/database/database.test-utils';-import { makeSearchWhereClause } from './database-fts5.repository.models';+import { makeSearchOrderByClauses, makeSearchWhereClause } from './database-fts5.repository.models';describe('database-fts5 repository models', () => {describe('makeSearchWhereClause', async () => {@@ -43,4 +44,64 @@ describe('database-fts5 repository models', () => {});});});++ describe('makeSearchOrderByClauses', () => {+ const toOrderByClause = ({ orderByClauses }: { orderByClauses: SQL[] }) => orderByClauses.map(clause => stringifySqlQuery(clause)).map(({ query }) => query).join(', ');++ test('sort by createdAt', () => {+ expect(+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'createdAt', order: 'asc' } })),+ ).to.eql(+ '"documents"."created_at" asc, "documents"."id" asc',+ );++ expect(+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'createdAt', order: 'desc' } })),+ ).to.eql(+ '"documents"."created_at" desc, "documents"."id" desc',+ );+ });++ test('sort by name, the name is sorted case-insensitively', () => {+ expect(+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'name', order: 'desc' } })),+ ).to.eql(+ '"documents"."name" COLLATE NOCASE desc, "documents"."id" desc',+ );++ expect(+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'name', order: 'asc' } })),+ ).to.eql(+ '"documents"."name" COLLATE NOCASE asc, "documents"."id" asc',+ );+ });++ test('sort by documentDate asc', () => {+ expect(+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'documentDate', order: 'asc' } })),+ ).to.eql(+ '"documents"."document_date" asc, "documents"."id" asc',+ );++ expect(+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'documentDate', order: 'desc' } })),+ ).to.eql(+ '"documents"."document_date" desc, "documents"."id" desc',+ );+ });++ test('sort by updatedAt desc', () => {+ expect(+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'updatedAt', order: 'desc' } })),+ ).to.eql(+ '"documents"."updated_at" desc, "documents"."id" desc',+ );++ expect(+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'updatedAt', order: 'asc' } })),+ ).to.eql(+ '"documents"."updated_at" asc, "documents"."id" asc',+ );+ });+ });});diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.tsindex 4b81b14d..e65c9a29 100644--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.ts+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.ts@@ -1,7 +1,10 @@+import type { SQL } from 'drizzle-orm';+import type { SQLiteColumn } from 'drizzle-orm/sqlite-core';import type { Database } from '../../../app/database/database.types';+import type { DocumentSearchSort, DocumentSearchSortField } from '../document-search.constants';import type { CustomPropertyDefinition } from './query-builder/query-builder.custom-properties';import { parseSearchQuery } from '@papra/search-parser';-import { and, eq } from 'drizzle-orm';+import { and, asc, desc, eq, sql } from 'drizzle-orm';import { documentsTable } from '../../documents.table';import { buildQueryFromExpression } from './query-builder/query-builder';@@ -23,3 +26,22 @@ export function makeSearchWhereClause({ query, organizationId, db, now = new Datissues: [...parsedIssues, ...issues],};}++const sortableColumnsByField: Record<DocumentSearchSortField, SQLiteColumn | SQL> = {+ createdAt: documentsTable.createdAt,+ updatedAt: documentsTable.updatedAt,+ name: sql`${documentsTable.name} COLLATE NOCASE`, // case-insensitive sorting for name+ documentDate: documentsTable.documentDate,+};++export function makeSearchOrderByClauses({ sort }: { sort: DocumentSearchSort }) {+ const sortColumn = sortableColumnsByField[sort.field];+ const orderDirection = sort.order === 'desc' ? desc : asc;++ const orderByClauses = [+ orderDirection(sortColumn),+ orderDirection(documentsTable.id), // tie-breaker to ensure deterministic order+ ];++ return { orderByClauses, sortColumn };+}diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.test.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.test.tsindex 39b70c65..a371b64f 100644--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.test.ts+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.test.ts@@ -438,6 +438,141 @@ describe('database-fts5 repository', () => {expect(searchResults).to.have.length(3);expect(searchResults.map(doc => doc.id)).to.eql(['doc_3', 'doc_1', 'doc_2']);});++ describe('sort', () => {+ test('documents can be sorted by name, case-insensitively', async () => {+ const documents = [+ { id: 'doc_1', organizationId: 'org_1', name: 'Banana', originalName: 'document-1.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false },+ { id: 'doc_2', organizationId: 'org_1', name: 'apple', originalName: 'document-2.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false },+ { id: 'doc_3', organizationId: 'org_1', name: 'cherry', originalName: 'document-3.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false },+ ];++ const { db } = await createInMemoryDatabase({+ organizations: [{ id: 'org_1', name: 'Organization 1' }],+ documents,+ });++ const documentsSearchRepository = createDocumentSearchRepository({ db });+ await documentsSearchRepository.indexDocuments({ documents });++ const { documents: ascResults } = await documentsSearchRepository.searchOrganizationDocuments({+ organizationId: 'org_1',+ searchQuery: 'lorem',+ pageIndex: 0,+ pageSize: 10,+ sort: { field: 'name', order: 'asc' },+ });++ expect(ascResults.map(doc => doc.id)).to.eql(['doc_2', 'doc_1', 'doc_3']);++ const { documents: descResults } = await documentsSearchRepository.searchOrganizationDocuments({+ organizationId: 'org_1',+ searchQuery: 'lorem',+ pageIndex: 0,+ pageSize: 10,+ sort: { field: 'name', order: 'desc' },+ });++ expect(descResults.map(doc => doc.id)).to.eql(['doc_3', 'doc_1', 'doc_2']);+ });++ test('documents can be sorted by document date, with null dates ordered first ascending and last descending', async () => {+ const documents = [+ { id: 'doc_1', organizationId: 'org_1', name: 'Document 1', originalName: 'document-1.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false, documentDate: new Date('2026-03-01') },+ { id: 'doc_2', organizationId: 'org_1', name: 'Document 2', originalName: 'document-2.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false, documentDate: new Date('2026-01-01') },+ { id: 'doc_3', organizationId: 'org_1', name: 'Document 3', originalName: 'document-3.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false },+ ];++ const { db } = await createInMemoryDatabase({+ organizations: [{ id: 'org_1', name: 'Organization 1' }],+ documents,+ });++ const documentsSearchRepository = createDocumentSearchRepository({ db });+ await documentsSearchRepository.indexDocuments({ documents });++ const { documents: ascResults } = await documentsSearchRepository.searchOrganizationDocuments({+ organizationId: 'org_1',+ searchQuery: 'lorem',+ pageIndex: 0,+ pageSize: 10,+ sort: { field: 'documentDate', order: 'asc' },+ });++ expect(ascResults.map(doc => doc.id)).to.eql(['doc_3', 'doc_2', 'doc_1']);++ const { documents: descResults } = await documentsSearchRepository.searchOrganizationDocuments({+ organizationId: 'org_1',+ searchQuery: 'lorem',+ pageIndex: 0,+ pageSize: 10,+ sort: { field: 'documentDate', order: 'desc' },+ });++ expect(descResults.map(doc => doc.id)).to.eql(['doc_1', 'doc_2', 'doc_3']);+ });++ test('documents can be sorted by update date', async () => {+ const documents = [+ { id: 'doc_1', organizationId: 'org_1', name: 'Document 1', originalName: 'document-1.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false, updatedAt: new Date('2026-01-02T10:00:00Z') },+ { id: 'doc_2', organizationId: 'org_1', name: 'Document 2', originalName: 'document-2.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false, updatedAt: new Date('2026-01-03T10:00:00Z') },+ { id: 'doc_3', organizationId: 'org_1', name: 'Document 3', originalName: 'document-3.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false, updatedAt: new Date('2026-01-01T10:00:00Z') },+ ];++ const { db } = await createInMemoryDatabase({+ organizations: [{ id: 'org_1', name: 'Organization 1' }],+ documents,+ });++ const documentsSearchRepository = createDocumentSearchRepository({ db });+ await documentsSearchRepository.indexDocuments({ documents });++ const { documents: searchResults } = await documentsSearchRepository.searchOrganizationDocuments({+ organizationId: 'org_1',+ searchQuery: 'lorem',+ pageIndex: 0,+ pageSize: 10,+ sort: { field: 'updatedAt', order: 'desc' },+ });++ expect(searchResults.map(doc => doc.id)).to.eql(['doc_2', 'doc_1', 'doc_3']);+ });++ test('sort is applied across pages', async () => {+ const documents = [+ { id: 'doc_1', organizationId: 'org_1', name: 'delta', originalName: 'document-1.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false },+ { id: 'doc_2', organizationId: 'org_1', name: 'alpha', originalName: 'document-2.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false },+ { id: 'doc_3', organizationId: 'org_1', name: 'charlie', originalName: 'document-3.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false },+ { id: 'doc_4', organizationId: 'org_1', name: 'bravo', originalName: 'document-4.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash4', isDeleted: false },+ ];++ const { db } = await createInMemoryDatabase({+ organizations: [{ id: 'org_1', name: 'Organization 1' }],+ documents,+ });++ const documentsSearchRepository = createDocumentSearchRepository({ db });+ await documentsSearchRepository.indexDocuments({ documents });++ const { documents: page0 } = await documentsSearchRepository.searchOrganizationDocuments({+ organizationId: 'org_1',+ searchQuery: 'lorem',+ pageIndex: 0,+ pageSize: 2,+ sort: { field: 'name', order: 'asc' },+ });+ const { documents: page1 } = await documentsSearchRepository.searchOrganizationDocuments({+ organizationId: 'org_1',+ searchQuery: 'lorem',+ pageIndex: 1,+ pageSize: 2,+ sort: { field: 'name', order: 'asc' },+ });++ expect(page0.map(doc => doc.id)).to.eql(['doc_2', 'doc_4']);+ expect(page1.map(doc => doc.id)).to.eql(['doc_3', 'doc_1']);+ });+ });});describe('indexDocuments', () => {diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.tsindex 6bae5fa8..649a1e4e 100644--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts@@ -1,12 +1,14 @@import type { Database } from '../../../app/database/database.types';+import type { DocumentSearchSort } from '../document-search.constants';import type { DocumentSearchableData, DocumentUpdate } from '../document-search.types';import { injectArguments } from '@corentinth/chisels';-import { desc, eq, getTableColumns, inArray, sql } from 'drizzle-orm';+import { eq, getTableColumns, inArray, sql } from 'drizzle-orm';import { customPropertyDefinitionsTable } from '../../../custom-properties/custom-properties.table';import { isNonEmptyArray } from '../../../shared/arrays/arrays.utils';import { omit, omitUndefined } from '../../../shared/objects';import { documentsTable } from '../../documents.table';-import { makeSearchWhereClause } from './database-fts5.repository.models';+import { DEFAULT_DOCUMENT_SEARCH_SORT } from '../document-search.constants';+import { makeSearchOrderByClauses, makeSearchWhereClause } from './database-fts5.repository.models';import { documentsFtsTable } from './database-fts5.tables';export type DocumentSearchRepository = ReturnType<typeof createDocumentSearchRepository>;@@ -21,19 +23,21 @@ export function createDocumentSearchRepository({ db }: { db: Database }) {}, { db });}-async function searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize, db, now = new Date() }: { organizationId: string; searchQuery: string; pageIndex: number; pageSize: number; db: Database; now?: Date }) {+async function searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize, sort = DEFAULT_DOCUMENT_SEARCH_SORT, db, now = new Date() }: { organizationId: string; searchQuery: string; pageIndex: number; pageSize: number; sort?: DocumentSearchSort; db: Database; now?: Date }) {const customPropertyDefinitions = await db.select().from(customPropertyDefinitionsTable).where(eq(customPropertyDefinitionsTable.organizationId, organizationId));const { searchWhereClause } = makeSearchWhereClause({ organizationId, query: searchQuery, db, now, customPropertyDefinitions });+ const { orderByClauses, sortColumn } = makeSearchOrderByClauses({ sort });const paginatedIdsSubquery = db- .selectDistinct({ id: documentsTable.id, createdAt: documentsTable.createdAt })+ // selecting the sort value keeps it in the result set so the DISTINCT + ORDER BY of the paginated subquery stays unambiguous (the tag filters can otherwise produce duplicate rows per document)+ .selectDistinct({ id: documentsTable.id, sortValue: sql`${sortColumn}`.as('sort_value') }).from(documentsTable).where(searchWhereClause)- .orderBy(desc(documentsTable.createdAt))+ .orderBy(...orderByClauses).limit(pageSize).offset(pageIndex * pageSize).as('paginated_docs');@@ -50,7 +54,8 @@ async function searchOrganizationDocuments({ organizationId, searchQuery, pageIn}).from(paginatedIdsSubquery).innerJoin(documentsTable, eq(documentsTable.id, paginatedIdsSubquery.id))- .orderBy(desc(paginatedIdsSubquery.createdAt)),+ // re-apply the sort on the joined documents table so the collation of `sortColumn` is honoured here too+ .orderBy(...orderByClauses),]);const documentsCount = totalCountResult[0]?.count ?? 0;diff --git a/apps/papra-server/src/modules/documents/document-search/document-search.constants.ts b/apps/papra-server/src/modules/documents/document-search/document-search.constants.tsnew file mode 100644index 00000000..2f0c44a0--- /dev/null+++ b/apps/papra-server/src/modules/documents/document-search/document-search.constants.ts@@ -0,0 +1,12 @@+export const documentSearchSortFields = ['createdAt', 'updatedAt', 'name', 'documentDate'] as const;+export type DocumentSearchSortField = (typeof documentSearchSortFields)[number];++export const documentSearchSortOrders = ['asc', 'desc'] as const;+export type DocumentSearchSortOrder = (typeof documentSearchSortOrders)[number];++export type DocumentSearchSort = {+ field: DocumentSearchSortField;+ order: DocumentSearchSortOrder;+};++export const DEFAULT_DOCUMENT_SEARCH_SORT: DocumentSearchSort = { field: 'createdAt', order: 'desc' };diff --git a/apps/papra-server/src/modules/documents/document-search/document-search.types.ts b/apps/papra-server/src/modules/documents/document-search/document-search.types.tsindex 4963a14e..62d54a9c 100644--- a/apps/papra-server/src/modules/documents/document-search/document-search.types.ts+++ b/apps/papra-server/src/modules/documents/document-search/document-search.types.ts@@ -1,4 +1,5 @@import type { Document } from '../documents.types';+import type { DocumentSearchSort } from './document-search.constants';export type DocumentSearchableData = {id: string;@@ -25,6 +26,7 @@ export type DocumentSearchServices = {organizationId: string;pageIndex: number;pageSize: number;+ sort?: DocumentSearchSort;}) => Promise<DocumentSearchResult>;getDocumentIdsMatchingQuery: (args: {diff --git a/apps/papra-server/src/modules/documents/document-search/document-search.usecase.ts b/apps/papra-server/src/modules/documents/document-search/document-search.usecase.tsindex 0834a3d0..411db766 100644--- a/apps/papra-server/src/modules/documents/document-search/document-search.usecase.ts+++ b/apps/papra-server/src/modules/documents/document-search/document-search.usecase.ts@@ -1,12 +1,15 @@import type { Logger } from '../../shared/logger/logger';+import type { DocumentSearchSort } from './document-search.constants';import type { DocumentSearchServices } from './document-search.types';import { createLogger } from '../../shared/logger/logger';+import { DEFAULT_DOCUMENT_SEARCH_SORT } from './document-search.constants';export async function searchOrganizationDocuments({searchQuery,organizationId,pageIndex,pageSize,+ sort = DEFAULT_DOCUMENT_SEARCH_SORT,documentSearchServices,logger = createLogger({ namespace: 'document-search.usecase' }),}: {@@ -14,6 +17,7 @@ export async function searchOrganizationDocuments({organizationId: string;pageIndex: number;pageSize: number;+ sort?: DocumentSearchSort;documentSearchServices: DocumentSearchServices;logger?: Logger;}) {@@ -23,6 +27,7 @@ export async function searchOrganizationDocuments({organizationId,pageIndex,pageSize,+ sort,});const durationMs = Date.now() - startTime;@@ -30,6 +35,8 @@ export async function searchOrganizationDocuments({organizationId,pageIndex,pageSize,+ sortField: sort.field,+ sortOrder: sort.order,durationMs,pageDocumentCount: documents.length,}, 'Executed document search');