{{ t('author.list.sortBy') }}
-
-
-
-
-
-
-
- {{ t('author.list.sortBy') }}
+
+
+
+
+
+
+
+
+
+
+
-
+
+
- {{ t('views.library.filterRules') }}
-
-
-
-
-
-
- {{ t('views.library.saveAsSmartScopeTooltip') }}
-
-
-
-
-
- {{ isFilterSaved ? t('views.library.filterSaved') : t('views.library.saveFilterTooltip') }}
-
-
-
-
-
- {{ t('views.library.removeSavedFilter') }}
-
+
- {{ error }}
- {{ t('views.library.empty.noFilterMatch') }}
@@ -991,7 +955,7 @@ defineOptions({ name: 'HomeView' }) :selection-mode="selectionMode" :is-selected="isSelected" :selected-count="selectedCount" - :filter-active="activeFilterCount > 0" + :filter-active="filterRuleCount > 0" :initialized="booksInitialized" @update:sort="localSortModel = $event" :allow-move-to-library="true" @@ -1129,22 +1093,8 @@ defineOptions({ name: 'HomeView' })
-
-
-
-
-
-
@@ -805,23 +751,6 @@ defineOptions({ name: 'SmartScopeView' })
-
-
{
expect(total).toBe(42);
});
+ it('countFormatFacets counts distinct visible books per requested format through an aliased file join', async () => {
+ const db = {
+ execute: vi.fn().mockResolvedValue({
+ rows: [
+ { format: 'epub', count: '7' },
+ { format: 'pdf', count: 3 },
+ ],
+ }),
+ };
+ const repo = new BookRepository(db as never);
+
+ const result = await repo.countFormatFacets(sql`${bookMetadata.title} is not null`, ['epub', 'pdf']);
+
+ const query = new PgDialect().sqlToQuery(db.execute.mock.calls[0]![0]);
+ const normalized = query.sql.replace(/\s+/g, ' ');
+ expect(normalized).toContain('count(DISTINCT "books"."id")');
+ expect(normalized).toContain('LEFT JOIN "book_metadata" ON "book_metadata"."book_id" = "books"."id"');
+ expect(normalized).toContain('INNER JOIN "book_files" AS facet_file ON facet_file.book_id = "books"."id"');
+ expect(normalized).toContain('"book_metadata"."title" is not null');
+ expect(normalized).toContain('"books"."status" <>');
+ expect(normalized).toContain('facet_file.format IN ($2, $3)');
+ expect(normalized).toContain('GROUP BY facet_file.format');
+ expect(query.params).toEqual(['processing', 'epub', 'pdf']);
+ expect(result).toEqual([
+ { format: 'epub', count: 7 },
+ { format: 'pdf', count: 3 },
+ ]);
+ });
+
+ it('countFormatFacets skips the query when no formats are requested', async () => {
+ const db = { execute: vi.fn() };
+ const repo = new BookRepository(db as never);
+
+ await expect(repo.countFormatFacets(undefined, [])).resolves.toEqual([]);
+ expect(db.execute).not.toHaveBeenCalled();
+ });
+
it('returns empty file lists without querying when bookIds are empty', async () => {
const db = {
select: vi.fn(),
diff --git a/server/src/modules/book/book.repository.ts b/server/src/modules/book/book.repository.ts
index 13c3d9cf6..efd882a8d 100644
--- a/server/src/modules/book/book.repository.ts
+++ b/server/src/modules/book/book.repository.ts
@@ -1928,6 +1928,28 @@ export class BookRepository {
return Number(total);
}
+ /**
+ * Books matching `where` per file format, counting a book under every format it holds a file in,
+ * the way the `format` filter matches. The joined files are aliased so a `format` rule's correlated
+ * `book_files` subquery inside `where` visibly binds to its own rows, never to this join.
+ */
+ async countFormatFacets(where: SQL | undefined, formats: readonly F[]): Promise> {
+ if (formats.length === 0) return [];
+ const result = await this.db.execute<{ format: F; count: string | number }>(sql`
+ SELECT facet_file.format AS format, count(DISTINCT ${books.id}) AS count
+ FROM ${books}
+ LEFT JOIN ${bookMetadata} ON ${bookMetadata.bookId} = ${books.id}
+ INNER JOIN ${bookFiles} AS facet_file ON facet_file.book_id = ${books.id}
+ WHERE ${this.visibleWhere(where)}
+ AND facet_file.format IN (${sql.join(
+ formats.map((format) => sql`${format}`),
+ sql`, `,
+ )})
+ GROUP BY facet_file.format
+ `);
+ return result.rows.map((row) => ({ format: row.format, count: Number(row.count) }));
+ }
+
async findLibraryIdsByBookIds(bookIds: number[]): Promise<{ id: number; libraryId: number }[]> {
if (bookIds.length === 0) return [];
return this.db.select({ id: books.id, libraryId: books.libraryId }).from(books).where(inArray(books.id, bookIds));
diff --git a/server/src/modules/book/book.service.test.ts b/server/src/modules/book/book.service.test.ts
index 7360bdef2..92a09893c 100644
--- a/server/src/modules/book/book.service.test.ts
+++ b/server/src/modules/book/book.service.test.ts
@@ -8,7 +8,15 @@ import { join } from 'path';
import type { RequestUser } from '../../common/types/request-user';
import { SelfWriteRegistry } from '../../common/services/self-write-registry.service';
import { FileWatcherService, WATCHER_DEBOUNCE_MS } from '../scanner/file-watcher.service';
-import { AUDIO_BOOK_FILE_WRITE_FIELDS, MetadataProviderKey, Permission, type BookQuery, type MetadataFetchDiagnostics } from '@bookorbit/types';
+import {
+ AUDIO_BOOK_FILE_WRITE_FIELDS,
+ BOOK_FORMATS,
+ MetadataProviderKey,
+ Permission,
+ type BookQuery,
+ type GroupRule,
+ type MetadataFetchDiagnostics,
+} from '@bookorbit/types';
import { extractEpubMetadata } from '../metadata/lib/epub';
import { extractAudioMetadata } from '../metadata/extractors/audio.extractor';
import { extractCbzMetadata, extractCbrMetadata, extractCb7Metadata } from '../metadata/lib/cbz-metadata';
@@ -116,6 +124,7 @@ function makeService(overrides: { bookMetadataLockService?: unknown; appDataPath
const bookRepo = {
findCards: vi.fn(),
countWhere: vi.fn(),
+ countFormatFacets: vi.fn(),
findPatternMetadataByBookIds: vi.fn(),
findLibraryIdsByBookIds: vi.fn(),
findDeletionAuditBooksByIds: vi.fn(),
@@ -5460,6 +5469,167 @@ describe('BookService', () => {
});
});
+ describe('facetsForLibrary', () => {
+ type WhereToken = { filter: GroupRule | undefined; q: string | undefined };
+
+ function makeFacetService(counts: { total?: number; libraryTotal?: number } = {}) {
+ const harness = makeService();
+ harness.queryBuilder.buildWhere.mockImplementation(((filter: GroupRule | undefined, ctx: { q?: string }) => ({ filter, q: ctx.q })) as never);
+ harness.bookRepo.countWhere.mockImplementation((where: WhereToken) =>
+ Promise.resolve(where.filter === undefined && where.q === undefined ? (counts.libraryTotal ?? 40) : (counts.total ?? 12)),
+ );
+ harness.bookRepo.countFormatFacets.mockResolvedValue([]);
+ return harness;
+ }
+
+ const formatRule = (format: string) => ({ type: 'rule' as const, field: 'format' as const, operator: 'includesAny' as const, value: [format] });
+ const unreadRule = { type: 'rule' as const, field: 'readStatus' as const, operator: 'includesAny' as const, value: ['unread'] };
+ const facetQuery = (filter: GroupRule | undefined, q?: string) =>
+ ({
+ ...(filter ? { filter } : {}),
+ ...(q !== undefined ? { q } : {}),
+ sort: [{ field: 'title', dir: 'asc' }],
+ pagination: { page: 3, size: 10 },
+ collapseSeries: true,
+ }) as BookQuery;
+
+ it('verifies access and builds every where with the listing scope, content filters and q', async () => {
+ const { service, libraryService, queryBuilder, bookRepo } = makeFacetService();
+ const user = makeUser({ id: 42, settings: { timezone: 'Europe/Berlin' } });
+ const contentFilters = { includeTagIds: [], excludeTagIds: [9], includeGenreIds: [], excludeGenreIds: [] };
+ user.contentFilters = contentFilters;
+ const filter: GroupRule = { type: 'group', join: 'AND', rules: [unreadRule] };
+
+ const result = await service.facetsForLibrary(user, 7, facetQuery(filter, 'dune'));
+
+ expect(libraryService.verifyUserAccess).toHaveBeenCalledWith(42, 7, false);
+ const scope = { accessibleLibraryIds: [7], implicitLibraryId: 7, userId: 42, timeZone: 'Europe/Berlin', contentFilters };
+ expect(queryBuilder.buildWhere).toHaveBeenCalledWith(filter, { ...scope, q: 'dune' });
+ expect(queryBuilder.buildWhere).toHaveBeenCalledWith(undefined, scope);
+ expect(queryBuilder.buildWhere).toHaveBeenCalledTimes(2);
+ expect(bookRepo.countWhere).toHaveBeenCalledWith({ filter, q: 'dune' });
+ expect(bookRepo.countWhere).toHaveBeenCalledWith({ filter: undefined, q: undefined });
+ expect(bookRepo.countFormatFacets).toHaveBeenCalledWith({ filter, q: 'dune' }, BOOK_FORMATS);
+ expect(result).toEqual({ total: 12, libraryTotal: 40, formats: [] });
+ });
+
+ it('leaves content filters off for superusers', async () => {
+ const { service, libraryService, queryBuilder } = makeFacetService();
+ const user = makeUser({ id: 3, isSuperuser: true });
+ user.contentFilters = { includeTagIds: [1], excludeTagIds: [], includeGenreIds: [], excludeGenreIds: [] };
+
+ await service.facetsForLibrary(user, 7, facetQuery({ type: 'group', join: 'AND', rules: [unreadRule] }));
+
+ expect(libraryService.verifyUserAccess).toHaveBeenCalledWith(3, 7, true);
+ expect(queryBuilder.buildWhere.mock.calls.length).toBeGreaterThan(0);
+ for (const [, ctx] of queryBuilder.buildWhere.mock.calls) {
+ expect((ctx as { contentFilters?: unknown }).contentFilters).toBeUndefined();
+ }
+ });
+
+ it('counts formats without root format rules under an AND root, keeping nested format rules and the rest', async () => {
+ const { service, queryBuilder, bookRepo } = makeFacetService();
+ const nested: GroupRule = { type: 'group', join: 'OR', rules: [formatRule('pdf'), unreadRule] };
+ const filter: GroupRule = { type: 'group', join: 'AND', rules: [formatRule('epub'), unreadRule, nested, formatRule('mobi')] };
+
+ await service.facetsForLibrary(makeUser(), 7, facetQuery(filter, 'dune'));
+
+ const stripped: GroupRule = { type: 'group', join: 'AND', rules: [unreadRule, nested] };
+ expect(queryBuilder.buildWhere).toHaveBeenCalledWith(filter, expect.objectContaining({ q: 'dune' }));
+ expect(queryBuilder.buildWhere).toHaveBeenCalledWith(stripped, expect.objectContaining({ q: 'dune' }));
+ expect(bookRepo.countWhere).toHaveBeenCalledWith({ filter, q: 'dune' });
+ expect(bookRepo.countFormatFacets).toHaveBeenCalledWith({ filter: stripped, q: 'dune' }, BOOK_FORMATS);
+ expect(filter.rules).toHaveLength(4);
+ });
+
+ it('strips nothing under an OR root', async () => {
+ const { service, queryBuilder, bookRepo } = makeFacetService();
+ const filter: GroupRule = { type: 'group', join: 'OR', rules: [formatRule('epub'), unreadRule] };
+
+ await service.facetsForLibrary(makeUser(), 7, facetQuery(filter));
+
+ expect(queryBuilder.buildWhere).toHaveBeenCalledTimes(2);
+ expect(bookRepo.countWhere).toHaveBeenCalledWith({ filter, q: undefined });
+ expect(bookRepo.countFormatFacets).toHaveBeenCalledWith({ filter, q: undefined }, BOOK_FORMATS);
+ });
+
+ it('keeps a root format exclusion, which the chips do not own', async () => {
+ const { service, bookRepo } = makeFacetService();
+ const excludePdf = { type: 'rule' as const, field: 'format' as const, operator: 'excludesAll' as const, value: ['pdf'] };
+ const filter: GroupRule = { type: 'group', join: 'AND', rules: [formatRule('epub'), excludePdf] };
+
+ await service.facetsForLibrary(makeUser(), 7, facetQuery(filter));
+
+ expect(bookRepo.countFormatFacets).toHaveBeenCalledWith(
+ { filter: { type: 'group', join: 'AND', rules: [excludePdf] }, q: undefined },
+ BOOK_FORMATS,
+ );
+ });
+
+ it('keeps a nested-only format filter intact', async () => {
+ const { service, bookRepo } = makeFacetService();
+ const filter: GroupRule = {
+ type: 'group',
+ join: 'AND',
+ rules: [{ type: 'group', join: 'OR', rules: [formatRule('epub'), formatRule('pdf')] }],
+ };
+
+ await service.facetsForLibrary(makeUser(), 7, facetQuery(filter));
+
+ expect(bookRepo.countFormatFacets).toHaveBeenCalledWith({ filter, q: undefined }, BOOK_FORMATS);
+ });
+
+ it('drops the filter entirely when the only root rule is a format rule, still applying q', async () => {
+ const { service, queryBuilder, bookRepo } = makeFacetService();
+ const filter: GroupRule = { type: 'group', join: 'AND', rules: [formatRule('epub')] };
+
+ await service.facetsForLibrary(makeUser(), 7, facetQuery(filter, 'dune'));
+
+ expect(queryBuilder.buildWhere).toHaveBeenCalledWith(undefined, expect.objectContaining({ q: 'dune' }));
+ expect(bookRepo.countWhere).toHaveBeenCalledWith({ filter, q: 'dune' });
+ expect(bookRepo.countFormatFacets).toHaveBeenCalledWith({ filter: undefined, q: 'dune' }, BOOK_FORMATS);
+ });
+
+ it('sorts formats by count then name and omits empty ones', async () => {
+ const { service, bookRepo } = makeFacetService();
+ bookRepo.countFormatFacets.mockResolvedValue([
+ { format: 'pdf', count: 3 },
+ { format: 'epub', count: 7 },
+ { format: 'cbz', count: 0 },
+ { format: 'mobi', count: 3 },
+ { format: 'azw3', count: 1 },
+ ]);
+
+ const result = await service.facetsForLibrary(makeUser(), 7, facetQuery({ type: 'group', join: 'AND', rules: [unreadRule] }));
+
+ expect(result.formats).toEqual([
+ { format: 'epub', count: 7 },
+ { format: 'mobi', count: 3 },
+ { format: 'pdf', count: 3 },
+ { format: 'azw3', count: 1 },
+ ]);
+ });
+
+ it('reuses the total as the library total when neither a filter nor q narrows it', async () => {
+ const { service, queryBuilder, bookRepo } = makeFacetService({ total: 40 });
+
+ const result = await service.facetsForLibrary(makeUser(), 7, facetQuery(undefined, ' '));
+
+ expect(queryBuilder.buildWhere).toHaveBeenCalledTimes(1);
+ expect(bookRepo.countWhere).toHaveBeenCalledTimes(1);
+ expect(result).toEqual({ total: 40, libraryTotal: 40, formats: [] });
+ });
+
+ it('refuses before querying when the user cannot see the library', async () => {
+ const { service, libraryService, bookRepo } = makeFacetService();
+ libraryService.verifyUserAccess.mockRejectedValue(new ForbiddenException('No library access'));
+
+ await expect(service.facetsForLibrary(makeUser(), 7, facetQuery(undefined))).rejects.toBeInstanceOf(ForbiddenException);
+ expect(bookRepo.countWhere).not.toHaveBeenCalled();
+ expect(bookRepo.countFormatFacets).not.toHaveBeenCalled();
+ });
+ });
+
describe('executeBooksQuery', () => {
const emptyCardQueryResult = {
rows: [],
diff --git a/server/src/modules/book/book.service.ts b/server/src/modules/book/book.service.ts
index 2fb5d2011..99f80a9a9 100644
--- a/server/src/modules/book/book.service.ts
+++ b/server/src/modules/book/book.service.ts
@@ -37,6 +37,7 @@ import { basename, dirname, extname, join, relative } from 'path';
import { tmpdir } from 'os';
import {
+ BOOK_FORMATS,
BOOK_METADATA_LOCK_FIELDS,
DEFAULT_DOWNLOAD_PATTERN,
COVER_MEDIA,
@@ -69,6 +70,7 @@ import type {
GroupRule,
JumpBucketsResponse,
JumpBucketsQuery,
+ LibraryBookFacets,
MetadataFetchDiagnostics,
ReadStatus,
ReadAloudProgressSync,
@@ -281,6 +283,20 @@ export type ProgressStatusFileContext = {
libraryId: number;
};
+/**
+ * Format facets are counted disjunctively: without the root-level "format includes any of" rules the
+ * chips write, so choosing one format still shows how many books the others hold. Any other format
+ * rule, such as an exclusion built in the filter panel, keeps applying. That is only sound when the
+ * root joins with AND; under OR, dropping a branch would widen the result rather than relax one
+ * dimension.
+ */
+function withoutRootFormatRules(filter: GroupRule | undefined): GroupRule | undefined {
+ if (!filter || filter.join !== 'AND') return filter;
+ const rules = filter.rules.filter((rule) => rule.type !== 'rule' || rule.field !== 'format' || rule.operator !== 'includesAny');
+ if (rules.length === filter.rules.length) return filter;
+ return rules.length > 0 ? { ...filter, rules } : undefined;
+}
+
@Injectable()
export class BookService {
private readonly logger = new Logger(BookService.name);
@@ -1120,6 +1136,39 @@ export class BookService {
return this.executeBooksQuery(user.id, where, query);
}
+ /** Browse-header counts from the listing's own where clause; sort, paging and collapse are ignored. */
+ async facetsForLibrary(user: RequestUser, libraryId: number, query: BookQuery): Promise {
+ await this.libraryService.verifyUserAccess(user.id, libraryId, this.isSuperuser(user));
+ const start = Date.now();
+ const scope = {
+ accessibleLibraryIds: [libraryId],
+ implicitLibraryId: libraryId,
+ userId: user.id,
+ timeZone: this.resolveUserTimeZone(user),
+ contentFilters: this.isSuperuser(user) ? undefined : user.contentFilters,
+ };
+ const where = this.queryBuilder.buildWhere(query.filter, { ...scope, q: query.q });
+ const formatFilter = withoutRootFormatRules(query.filter);
+ const formatWhere = formatFilter === query.filter ? where : this.queryBuilder.buildWhere(formatFilter, { ...scope, q: query.q });
+ const hasQuery = Boolean(query.q?.trim());
+ const narrowed = Boolean(query.filter) || hasQuery;
+
+ const [total, libraryTotal, formatCounts] = await Promise.all([
+ this.bookRepo.countWhere(where),
+ narrowed ? this.bookRepo.countWhere(this.queryBuilder.buildWhere(undefined, scope)) : null,
+ this.bookRepo.countFormatFacets(formatWhere, BOOK_FORMATS),
+ ]);
+ const formats = formatCounts.filter((facet) => facet.count > 0).sort((a, b) => b.count - a.count || a.format.localeCompare(b.format));
+
+ const durationMs = Date.now() - start;
+ if (durationMs >= 500) {
+ this.logger.warn(
+ `[book.facets_query] [end] userId=${user.id} libraryId=${libraryId} filterCount=${query.filter?.rules?.length ?? 0} hasQuery=${hasQuery} total=${total} formatCount=${formats.length} durationMs=${durationMs} - slow query`,
+ );
+ }
+ return { total, libraryTotal: libraryTotal ?? total, formats };
+ }
+
async globalQuery(user: RequestUser, query: BookQuery): Promise {
this.assertPaginationWindow(query.pagination.page, query.pagination.size);
const libs = await this.libraryService.findAll(user);
diff --git a/server/src/modules/library/library.controller.test.ts b/server/src/modules/library/library.controller.test.ts
index edd25446c..d01d518b0 100644
--- a/server/src/modules/library/library.controller.test.ts
+++ b/server/src/modules/library/library.controller.test.ts
@@ -21,7 +21,7 @@ describe('LibraryController', () => {
writeMetadataToFiles: vi.fn(),
};
- const bookService = { queryForLibrary: vi.fn(), queryJumpBucketsForLibrary: vi.fn() };
+ const bookService = { queryForLibrary: vi.fn(), queryJumpBucketsForLibrary: vi.fn(), facetsForLibrary: vi.fn() };
const bulkRenameService = {
getPreview: vi.fn(),
@@ -127,14 +127,18 @@ describe('LibraryController', () => {
expect(reply.raw.end).toHaveBeenCalled();
});
- it('queryBooks and queryJumpBuckets delegate to the book service', async () => {
+ it('queryBooks, getBookFacets and queryJumpBuckets delegate to the book service', async () => {
const user = { id: 4, isSuperuser: false } as any;
const query = { sort: [{ field: 'title', dir: 'asc' }], pagination: { page: 0, size: 50 } } as any;
+ bookService.facetsForLibrary.mockResolvedValue({ total: 3, libraryTotal: 5, formats: [{ format: 'epub', count: 3 }] });
await controller.queryBooks(7, query, user);
+ const facets = await controller.getBookFacets(7, query, user);
await controller.queryJumpBuckets(7, query, user);
expect(bookService.queryForLibrary).toHaveBeenCalledWith(user, 7, query);
+ expect(bookService.facetsForLibrary).toHaveBeenCalledWith(user, 7, query);
+ expect(facets).toEqual({ total: 3, libraryTotal: 5, formats: [{ format: 'epub', count: 3 }] });
expect(bookService.queryJumpBucketsForLibrary).toHaveBeenCalledWith(user, 7, query);
});
});
diff --git a/server/src/modules/library/library.controller.ts b/server/src/modules/library/library.controller.ts
index 9b21a1de7..8bd553d62 100644
--- a/server/src/modules/library/library.controller.ts
+++ b/server/src/modules/library/library.controller.ts
@@ -2,7 +2,7 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, ParseIntPip
import type { FastifyReply } from 'fastify';
import { Permission, AuditAction, AuditResource } from '@bookorbit/types';
-import type { BookQuery, BulkRenameProgressEvent, JumpBucketsQuery, LibraryFileSyncProgressEvent } from '@bookorbit/types';
+import type { BookQuery, BulkRenameProgressEvent, JumpBucketsQuery, LibraryBookFacets, LibraryFileSyncProgressEvent } from '@bookorbit/types';
import { CurrentUser } from '../../common/decorators/current-user.decorator';
import { RequireLibraryAccess } from '../../common/decorators/require-library-access.decorator';
import { RequireLibraryType } from '../../common/decorators/require-library-type.decorator';
@@ -61,6 +61,17 @@ export class LibraryController {
return this.bookService.queryForLibrary(user, libraryId, query);
}
+ @Post(':id/books/facets')
+ @RequireLibraryAccess('viewer')
+ @RequireLibraryType('books')
+ getBookFacets(
+ @Param('id', ParseIntPipe) libraryId: number,
+ @Body(BookQueryPipe) query: BookQuery,
+ @CurrentUser() user: RequestUser,
+ ): Promise {
+ return this.bookService.facetsForLibrary(user, libraryId, query);
+ }
+
@Post(':id/books/jump-buckets')
@RequireLibraryAccess('viewer')
@RequireLibraryType('books')
diff --git a/server/test/authorization-matrix.e2e-spec.ts b/server/test/authorization-matrix.e2e-spec.ts
index 47f853c0b..b590813e4 100644
--- a/server/test/authorization-matrix.e2e-spec.ts
+++ b/server/test/authorization-matrix.e2e-spec.ts
@@ -931,6 +931,7 @@ describe('Authorization matrix (e2e)', () => {
'POST /libraries/:id/write-metadata-to-files',
'GET /scanner/libraries/:id/scan-history',
'POST /libraries/:id/books/jump-buckets',
+ 'POST /libraries/:id/books/facets',
'GET /libraries/:id/bulk-rename/preview',
'GET /libraries/:id/bulk-rename/status',
'POST /libraries/:id/bulk-rename/execute',
diff --git a/server/test/browse-facets-invariant.e2e-spec.ts b/server/test/browse-facets-invariant.e2e-spec.ts
new file mode 100644
index 000000000..7f9b3d63a
--- /dev/null
+++ b/server/test/browse-facets-invariant.e2e-spec.ts
@@ -0,0 +1,275 @@
+import { BOOK_FORMATS, type BookFormat, type BooksPage, type GroupRule, type LibraryBookFacets, type Rule } from '@bookorbit/types';
+import { eq } from 'drizzle-orm';
+
+import { bookFiles, bookMetadata, books, userBookStatus, users } from '../src/db/schema';
+import {
+ authHeader,
+ closeMetadataWriteE2EContext,
+ createLibraryWithFolder,
+ createMetadataWriteE2EContext,
+ createUserAndLogin,
+ grantLibraryAccess,
+ type MetadataWriteE2EContext,
+ type TestUserSession,
+} from './e2e/metadata-write/metadata-write-harness';
+
+const SCENARIO_TIMEOUT_MS = 120_000;
+
+type SeededStatus = 'reading' | 'read' | 'want_to_read';
+
+type SeedSpec = {
+ title: string;
+ status?: 'present' | 'missing' | 'processing';
+ files: Array<{ format: string; role?: 'content' | 'cover' | 'metadata' }>;
+ adminStatus?: SeededStatus;
+ viewerStatus?: SeededStatus;
+};
+
+// Two-format books, a missing book, a processing book (the only fb2 holder), a book with no files,
+// an audiobook with two files of one format and a book carrying cover and OPF sidecars.
+const SEEDS: SeedSpec[] = [
+ { title: 'Dune', files: [{ format: 'epub' }], adminStatus: 'read' },
+ { title: 'Dune Messiah', files: [{ format: 'epub' }, { format: 'mobi' }], adminStatus: 'reading', viewerStatus: 'read' },
+ { title: 'Children of Dune', files: [{ format: 'epub' }, { format: 'mobi' }] },
+ { title: 'Foundation', files: [{ format: 'pdf' }], viewerStatus: 'reading' },
+ { title: 'Foundation and Empire', files: [{ format: 'pdf' }, { format: 'epub' }], adminStatus: 'read' },
+ { title: 'Second Foundation', files: [{ format: 'pdf' }], adminStatus: 'want_to_read' },
+ { title: 'Watchmen', files: [{ format: 'cbz' }], viewerStatus: 'read' },
+ { title: 'Saga Volume One', files: [{ format: 'cbz' }, { format: 'cbr' }], adminStatus: 'reading' },
+ { title: 'Project Hail Mary', files: [{ format: 'm4b' }, { format: 'epub' }] },
+ { title: 'The Martian', files: [{ format: 'm4b' }], adminStatus: 'read', viewerStatus: 'want_to_read' },
+ { title: 'Dune Audio Drama', files: [{ format: 'mp3' }, { format: 'mp3' }] },
+ {
+ title: 'Hyperion',
+ files: [{ format: 'azw3' }, { format: 'jpg', role: 'cover' }, { format: 'opf', role: 'metadata' }],
+ adminStatus: 'reading',
+ },
+ { title: 'Lost Dune Notes', status: 'missing', files: [{ format: 'epub' }, { format: 'pdf' }] },
+ { title: 'Missing Watchmen', status: 'missing', files: [{ format: 'cbz' }], adminStatus: 'read' },
+ { title: 'Dune Processing', status: 'processing', files: [{ format: 'epub' }, { format: 'fb2' }], adminStatus: 'reading' },
+ { title: 'Bookless', files: [] },
+];
+
+const VISIBLE_SEED_COUNT = SEEDS.filter((seed) => seed.status !== 'processing').length;
+
+function formatRule(format: string): Rule {
+ return { type: 'rule', field: 'format', operator: 'includesAny', value: [format] };
+}
+
+function readStatusRule(status: string): Rule {
+ return { type: 'rule', field: 'readStatus', operator: 'includesAny', value: [status] };
+}
+
+type Scenario = {
+ name: string;
+ filter?: GroupRule;
+ q?: string;
+ /** The listing filter whose total must equal the facet count for `format`. */
+ formatListingFilter: (format: BookFormat) => GroupRule;
+};
+
+const SCENARIOS: Scenario[] = [
+ {
+ name: 'no filter',
+ formatListingFilter: (format) => ({ type: 'group', join: 'AND', rules: [formatRule(format)] }),
+ },
+ {
+ name: 'readStatus unread',
+ filter: { type: 'group', join: 'AND', rules: [readStatusRule('unread')] },
+ formatListingFilter: (format) => ({ type: 'group', join: 'AND', rules: [readStatusRule('unread'), formatRule(format)] }),
+ },
+ {
+ name: 'quick search',
+ q: 'dune',
+ formatListingFilter: (format) => ({ type: 'group', join: 'AND', rules: [formatRule(format)] }),
+ },
+ {
+ name: 'quick search with readStatus unread',
+ q: 'dune',
+ filter: { type: 'group', join: 'AND', rules: [readStatusRule('unread')] },
+ formatListingFilter: (format) => ({ type: 'group', join: 'AND', rules: [readStatusRule('unread'), formatRule(format)] }),
+ },
+ {
+ name: 'a selected format counted disjunctively',
+ filter: { type: 'group', join: 'AND', rules: [formatRule('epub'), readStatusRule('unread')] },
+ formatListingFilter: (format) => ({ type: 'group', join: 'AND', rules: [readStatusRule('unread'), formatRule(format)] }),
+ },
+ {
+ name: 'an OR root, which strips nothing',
+ filter: { type: 'group', join: 'OR', rules: [formatRule('pdf'), readStatusRule('read')] },
+ formatListingFilter: (format) => ({
+ type: 'group',
+ join: 'AND',
+ rules: [{ type: 'group', join: 'OR', rules: [formatRule('pdf'), readStatusRule('read')] }, formatRule(format)],
+ }),
+ },
+ {
+ name: 'a nested format group, which stays',
+ filter: { type: 'group', join: 'AND', rules: [{ type: 'group', join: 'OR', rules: [formatRule('epub'), formatRule('cbz')] }] },
+ formatListingFilter: (format) => ({
+ type: 'group',
+ join: 'AND',
+ rules: [{ type: 'group', join: 'OR', rules: [formatRule('epub'), formatRule('cbz')] }, formatRule(format)],
+ }),
+ },
+];
+
+describe('Browse facets invariant (e2e)', { timeout: SCENARIO_TIMEOUT_MS }, () => {
+ let ctx!: MetadataWriteE2EContext;
+ let libraryId!: number;
+ let viewer!: TestUserSession;
+
+ beforeAll(async () => {
+ ctx = await createMetadataWriteE2EContext();
+ const library = await createLibraryWithFolder(ctx, { name: 'browse-facets-invariant' });
+ libraryId = library.libraryId;
+
+ const [admin] = await ctx.db.select({ id: users.id }).from(users).where(eq(users.username, 'metadata-write-e2e-admin')).limit(1);
+ if (!admin) throw new Error('e2e admin user not found');
+ viewer = await createUserAndLogin(ctx);
+ await grantLibraryAccess(ctx, viewer.userId, libraryId, 'viewer');
+
+ let ino = 910_000;
+ for (const [index, seed] of SEEDS.entries()) {
+ const [book] = await ctx.db
+ .insert(books)
+ .values({
+ libraryId,
+ libraryFolderId: library.libraryFolderId,
+ folderPath: `/seed/facets-${index}`,
+ status: seed.status ?? 'present',
+ })
+ .returning({ id: books.id });
+ const bookId = book!.id;
+ await ctx.db.insert(bookMetadata).values({ bookId, title: seed.title });
+
+ if (seed.files.length > 0) {
+ const files = await ctx.db
+ .insert(bookFiles)
+ .values(
+ seed.files.map((file, fileIndex) => ({
+ bookId,
+ libraryFolderId: library.libraryFolderId,
+ absolutePath: `/seed/facets-${index}/file-${fileIndex}.${file.format}`,
+ relPath: `facets-${index}/file-${fileIndex}.${file.format}`,
+ ino: BigInt(ino++),
+ format: file.format,
+ role: file.role ?? 'content',
+ })),
+ )
+ .returning({ id: bookFiles.id });
+ await ctx.db.update(books).set({ primaryFileId: files[0]!.id }).where(eq(books.id, bookId));
+ }
+
+ const statusRows = [
+ ...(seed.adminStatus ? [{ userId: admin.id, status: seed.adminStatus }] : []),
+ ...(seed.viewerStatus ? [{ userId: viewer.userId, status: seed.viewerStatus }] : []),
+ ];
+ if (statusRows.length > 0) {
+ await ctx.db.insert(userBookStatus).values(statusRows.map((row) => ({ ...row, bookId, source: 'manual' as const })));
+ }
+ }
+ });
+
+ afterAll(async () => {
+ await closeMetadataWriteE2EContext(ctx);
+ });
+
+ async function fetchFacets(token: string, body: { filter?: GroupRule; q?: string }): Promise {
+ const response = await ctx.app.inject({
+ method: 'POST',
+ url: `/api/v1/libraries/${libraryId}/books/facets`,
+ headers: authHeader(token),
+ // Sort, paging, collapse and shuffle seed are accepted and must not change any count.
+ payload: { ...body, sort: [{ field: 'title', dir: 'desc' }], pagination: { page: 2, size: 3 }, collapseSeries: true, randomSeed: 7 },
+ });
+ expect(response.statusCode).toBe(201);
+ return response.json() as LibraryBookFacets;
+ }
+
+ async function listingTotal(token: string, body: { filter?: GroupRule; q?: string }): Promise {
+ const response = await ctx.app.inject({
+ method: 'POST',
+ url: `/api/v1/libraries/${libraryId}/books`,
+ headers: authHeader(token),
+ payload: { ...body, sort: [{ field: 'title', dir: 'asc' }], pagination: { page: 0, size: 1 }, collapseSeries: false },
+ });
+ expect(response.statusCode).toBe(201);
+ return (response.json() as BooksPage).total;
+ }
+
+ const personas = [
+ { name: 'superuser admin', token: () => ctx.adminToken },
+ { name: 'viewer', token: () => viewer.accessToken },
+ ];
+
+ for (const persona of personas) {
+ for (const scenario of SCENARIOS) {
+ it(`matches the listing for ${scenario.name} as the ${persona.name}`, async () => {
+ const token = persona.token();
+ const body = { ...(scenario.filter ? { filter: scenario.filter } : {}), ...(scenario.q !== undefined ? { q: scenario.q } : {}) };
+ const [facets, total, libraryTotal] = await Promise.all([fetchFacets(token, body), listingTotal(token, body), listingTotal(token, {})]);
+
+ expect(facets.total).toBe(total);
+ expect(facets.libraryTotal).toBe(libraryTotal);
+ expect(facets.libraryTotal).toBe(VISIBLE_SEED_COUNT);
+
+ const formatTotals = await Promise.all(
+ BOOK_FORMATS.map(async (format) => ({
+ format,
+ count: await listingTotal(token, {
+ filter: scenario.formatListingFilter(format),
+ ...(scenario.q !== undefined ? { q: scenario.q } : {}),
+ }),
+ })),
+ );
+ const expected = formatTotals.filter((facet) => facet.count > 0).sort((a, b) => b.count - a.count || a.format.localeCompare(b.format));
+
+ expect(facets.formats).toEqual(expected);
+ });
+ }
+ }
+
+ it('counts every format a visible book holds, once per book, and nothing else', async () => {
+ const facets = await fetchFacets(ctx.adminToken, {});
+ const counts = Object.fromEntries(facets.formats.map((facet) => [facet.format, facet.count]));
+
+ expect(counts).toEqual({ epub: 6, pdf: 4, cbz: 3, mobi: 2, m4b: 2, cbr: 1, mp3: 1, azw3: 1 });
+ expect(facets.total).toBe(VISIBLE_SEED_COUNT);
+ for (const facet of facets.formats) expect(BOOK_FORMATS).toContain(facet.format);
+ });
+
+ it('keeps the other formats visible while one is selected, but narrows the total', async () => {
+ const filter: GroupRule = { type: 'group', join: 'AND', rules: [formatRule('epub')] };
+ const [facets, epubTotal] = await Promise.all([fetchFacets(ctx.adminToken, { filter }), listingTotal(ctx.adminToken, { filter })]);
+
+ expect(facets.total).toBe(epubTotal);
+ expect(facets.total).toBe(6);
+ expect(facets.formats.length).toBeGreaterThan(1);
+ expect(facets.formats.find((facet) => facet.format === 'pdf')?.count).toBe(4);
+ });
+
+ it('denies a user without library access, matching the listing endpoint', async () => {
+ const outsider = await createUserAndLogin(ctx);
+ const payload = { sort: [{ field: 'title', dir: 'asc' }], pagination: { page: 0, size: 50 } };
+
+ const [facetsResponse, listingResponse] = await Promise.all([
+ ctx.app.inject({ method: 'POST', url: `/api/v1/libraries/${libraryId}/books/facets`, headers: authHeader(outsider.accessToken), payload }),
+ ctx.app.inject({ method: 'POST', url: `/api/v1/libraries/${libraryId}/books`, headers: authHeader(outsider.accessToken), payload }),
+ ]);
+
+ expect(facetsResponse.statusCode).toBe(403);
+ expect(listingResponse.statusCode).toBe(403);
+ });
+
+ it('rejects a non-numeric library id with 400', async () => {
+ const response = await ctx.app.inject({
+ method: 'POST',
+ url: '/api/v1/libraries/not-a-number/books/facets',
+ headers: authHeader(ctx.adminToken),
+ payload: {},
+ });
+
+ expect(response.statusCode).toBe(400);
+ });
+});
diff --git a/server/test/e2e/authorization-matrix/route-inventory/manifest.json b/server/test/e2e/authorization-matrix/route-inventory/manifest.json
index 0934a2291..892dcb614 100644
--- a/server/test/e2e/authorization-matrix/route-inventory/manifest.json
+++ b/server/test/e2e/authorization-matrix/route-inventory/manifest.json
@@ -1,7 +1,7 @@
{
- "totalRoutes": 649,
+ "totalRoutes": 650,
"byPermission": {
- "(none)": 281,
+ "(none)": 282,
"Permission.ManageMetadataConfig": 38,
"Permission.EmailSend": 34,
"Permission.LibraryEditMetadata": 35,
@@ -35,7 +35,7 @@
"Permission.PodcastDownload": 4
},
"byLibraryAccess": {
- "'viewer'": 9,
+ "'viewer'": 10,
"'editor'": 15,
"'owner'": 4
},
diff --git a/server/test/e2e/authorization-matrix/route-inventory/routes-09.json b/server/test/e2e/authorization-matrix/route-inventory/routes-09.json
index f7e2f3e41..f02a1f98b 100644
--- a/server/test/e2e/authorization-matrix/route-inventory/routes-09.json
+++ b/server/test/e2e/authorization-matrix/route-inventory/routes-09.json
@@ -1,4 +1,16 @@
[
+ {
+ "file": "server/src/modules/library/library.controller.ts",
+ "className": "LibraryController",
+ "methodName": "getBookFacets",
+ "httpMethod": "POST",
+ "path": "/libraries/:id/books/facets",
+ "permissions": [],
+ "libraryAccess": ["'viewer'"],
+ "isPublic": false,
+ "allowDefault": false,
+ "useGuards": []
+ },
{
"file": "server/src/modules/library/library.controller.ts",
"className": "LibraryController",