server/src/modules/book-dock/dto/index.ts (1)

60-60: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider adding a semantic date validation message to @Matches.

The regex ^\d{4}-\d{2}-\d{2}$ validates format but not semantic validity (e.g., 2023-13-45 passes). While downstream normalization likely catches invalid dates, adding a validation message improves error clarity for API consumers.

💡 Suggested improvement

-  `@IsOptional`() `@IsString`() `@Matches`(/^\d{4}-\d{2}-\d{2}$/) publishedDate?: string;
+  `@IsOptional`() `@IsString`() `@Matches`(/^\d{4}-\d{2}-\d{2}$/, { message: 'publishedDate must be a valid YYYY-MM-DD date string' }) publishedDate?: string;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@server/src/modules/book-dock/dto/index.ts` at line 60, The publishedDate
validation in the DTO only checks the YYYY-MM-DD shape via `@Matches`, so add a
custom validation message there to make invalid date input clearer for API
consumers. Update the publishedDate field in the book-dock DTO so the `@Matches`
decorator includes a semantic-friendly message, and keep the existing
`@IsOptional` and `@IsString` checks intact. Use the publishedDate property as the
target for the change so it is easy to locate even if lines shift.

client/src/features/book/lib/published-date.ts (1)

1-9: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Regex doesn't validate month/day value ranges.

The DATE_KEY_RE regex only checks the digit format (\d{4}-\d{2}-\d{2}), not valid ranges. Invalid dates like "2007-13-45" would match and produce rollover dates via the Date constructor (e.g., Feb 14, 2008). Since data should be validated upstream, this is low risk, but a brief comment noting the assumption would help future maintainers.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@client/src/features/book/lib/published-date.ts` around lines 1 - 9, Add a
brief inline comment near DATE_KEY_RE or in formatPublishedDate explaining that
the regex only enforces the YYYY-MM-DD shape and intentionally assumes upstream
validation for month/day ranges. Keep the existing parsing logic in
formatPublishedDate unchanged, but document the assumption so future maintainers
understand why invalid values like 2007-13-45 are not rejected here.

server/src/modules/book/dto/update-book-metadata.dto.ts (1)

49-49: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider adding a validation error message to @Matches.

The regex ^\d{4}-\d{2}-\d{2}$ validates the format but not semantic validity (e.g., 2020-13-45 would pass). Adding a message to the @Matches decorator would improve API error clarity for clients sending invalid date strings.

✨ Suggested improvement

-  `@IsOptional`() `@IsString`() `@Matches`(/^\d{4}-\d{2}-\d{2}$/) publishedDate?: string | null;
+  `@IsOptional`() `@IsString`() `@Matches`(/^\d{4}-\d{2}-\d{2}$/, { message: 'publishedDate must be in YYYY-MM-DD format' }) publishedDate?: string | null;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@server/src/modules/book/dto/update-book-metadata.dto.ts` at line 49, The
`publishedDate` validator in `UpdateBookMetadataDto` uses `@Matches` without an
explicit message, so add a clear validation `message` there to improve API
feedback for invalid date strings. Update the `publishedDate` decorator chain in
`UpdateBookMetadataDto` so the `@Matches(/^\d{4}-\d{2}-\d{2}$/)` rule reports a
user-friendly error when the value is not in the expected format.

server/src/common/utils/published-date.utils.test.ts (1)

40-46: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add coverage for year-only input to normalizePublishedDate.

No test pins down what normalizePublishedDate('1965') returns. This matters because book.service.ts's MOBI/AZW branch relies on this function to decide whether to derive publishedYear, and if it returns null/undefined for year-only strings, the year is silently dropped (see companion comment in book.service.ts).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@server/src/common/utils/published-date.utils.test.ts` around lines 40 - 46,
Add a test in published-date.utils.test for normalizePublishedDate with a
year-only string like '1965' so the expected return value is explicitly pinned
down. Update the normalizePublishedDate behavior if needed so year-only input is
handled consistently, and make sure the new assertion covers the path used by
book.service.ts in the MOBI/AZW branch when it reads publishedYear from
normalizePublishedDate.

server/src/modules/metadata/lib/fb2-parser.ts (1)

70-87: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Extract shared candidate-extraction helper to eliminate duplication.

parseFb2DateNode (lines 70–87) and parseFb2YearNode (lines 49–68) share identical candidate-extraction logic — building candidates from direct text and @_value attributes. Both are called on the same yearRaw value (lines 158–159), so the extraction runs twice.

♻️ Proposed refactor

+function extractFb2DateCandidates(val: unknown): string[] {
+  const candidates: string[] = [];
+  const direct = text(val);
+  if (direct) candidates.push(direct);
+  if (typeof val === 'object' && val !== null) {
+    const objectNode = val as Record<string, unknown>;
+    const valueAttr = text(objectNode['`@_value`']);
+    if (valueAttr) candidates.push(valueAttr);
+  }
+  return candidates;
+}
+
 function parseFb2YearNode(val: unknown): number | null {
-  const candidates: string[] = [];
-  const direct = text(val);
-  if (direct) candidates.push(direct);
-
-  if (typeof val === 'object' && val !== null) {
-    const objectNode = val as Record<string, unknown>;
-    const valueAttr = text(objectNode['`@_value`']);
-    if (valueAttr) candidates.push(valueAttr);
-  }
-
+  const candidates = extractFb2DateCandidates(val);
   for (const candidate of candidates) {
     const match = candidate.match(/(\d{4})/);
     if (!match) continue;
     const year = parseInt(match[1], 10);
     if (!isNaN(year) && year > 1000 && year < 2200) return year;
   }
   return null;
 }

 function parseFb2DateNode(val: unknown): string | null {
-  const candidates: string[] = [];
-  const direct = text(val);
-  if (direct) candidates.push(direct);
-
-  if (typeof val === 'object' && val !== null) {
-    const objectNode = val as Record<string, unknown>;
-    const valueAttr = text(objectNode['`@_value`']);
-    if (valueAttr) candidates.push(valueAttr);
-  }
-
+  const candidates = extractFb2DateCandidates(val);
   for (const candidate of candidates) {
     const publishedDate = parsePublishedDateKey(candidate);
     if (publishedDate) return publishedDate;
   }
   return null;
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@server/src/modules/metadata/lib/fb2-parser.ts` around lines 70 - 87, Extract
the duplicated candidate-building logic shared by parseFb2DateNode and
parseFb2YearNode into a single helper that gathers direct text and the `@_value`
attribute from the same input. Update both parseFb2DateNode and parseFb2YearNode
to call the shared helper, and reuse it at the yearRaw handling site so the same
value is not processed twice.

server/src/modules/metadata-fetch/providers/ranobedb/ranobedb.mapper.ts (1)

123-124: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Cache resolvePublishedDate to avoid duplicate resolution.

resolvePublishedDate is called once directly on line 123 and again inside resolvePublishedYear on line 124. For the same book/release pair, this duplicates the parsing work.

♻️ Proposed refactor

   return {
     provider: MetadataProviderKey.RANOBEDB,
     providerId: String(book.id),
     title: resolveTitle(book),
     subtitle: resolveSubtitle(book),
     authors: resolveAuthors(book),
     publisher: resolvePublisher(book),
-    publishedDate: resolvePublishedDate(book, selectedRelease),
-    publishedYear: resolvePublishedYear(book, selectedRelease),
+    publishedDate: (publishedDate => publishedDate ? publishedYearFromDateKey(publishedDate) : undefined)(resolvePublishedDate(book, selectedRelease)),

Or more readably, extract a local:

   const selectedRelease = selectEnglishRelease(book.releases);
   const communityRating = normalizeCommunityRating(book);
+  const publishedDate = resolvePublishedDate(book, selectedRelease);

   return {
     provider: MetadataProviderKey.RANOBEDB,
     providerId: String(book.id),
     title: resolveTitle(book),
     subtitle: resolveSubtitle(book),
     authors: resolveAuthors(book),
     publisher: resolvePublisher(book),
-    publishedDate: resolvePublishedDate(book, selectedRelease),
-    publishedYear: resolvePublishedYear(book, selectedRelease),
+    publishedDate,
+    publishedYear: publishedDate ? publishedYearFromDateKey(publishedDate) : undefined,

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@server/src/modules/metadata-fetch/providers/ranobedb/ranobedb.mapper.ts`
around lines 123 - 124, Cache the published date resolution in the ranobedb
mapper to avoid doing the same work twice for the same book/release pair. In the
mapper where `resolvePublishedDate` and `resolvePublishedYear` are used, compute
the date once into a local value and pass that value through so
`resolvePublishedYear` doesn’t re-run the same parsing logic. Use the existing
`resolvePublishedDate`, `resolvePublishedYear`, and mapper code around
`publishedDate`/`publishedYear` to place the shared result.

server/src/modules/metadata/metadata.service.ts (1)

609-619: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract duplicated published date/year handling into a shared helper.

The published date/year scalar assignment logic at lines 609-619 (persistAudioMetadata) and lines 690-700 (persistBookMetadata) is identical. Extracting it into a private helper would eliminate the duplication and ensure both paths stay in sync — particularly important given the lock-sensitivity of this logic.

♻️ Proposed helper extraction

+  private applyPublishedDateFields(
+    scalarFields: Partial<typeof schema.bookMetadata.$inferInsert>,
+    filteredPublishedDate: string | null | undefined,
+    filteredPublishedYear: number | null | undefined,
+  ): void {
+    const publishedDate = normalizePublishedDate(filteredPublishedDate);
+    if (publishedDate !== undefined) {
+      scalarFields.publishedDate = publishedDate;
+      if (publishedDate !== null) scalarFields.publishedYear = publishedYearFromDateKey(publishedDate);
+    }
+    if (filteredPublishedYear !== undefined && publishedDate === undefined) {
+      scalarFields.publishedYear = normalizePublishedYear(filteredPublishedYear);
+    } else if (filteredPublishedYear !== undefined && publishedDate === null) {
+      scalarFields.publishedYear = normalizePublishedYear(filteredPublishedYear);
+    }
+  }
+
   // In persistAudioMetadata, replace lines 609-619 with:
-    const publishedDate = normalizePublishedDate(filtered.publishedDate);
-    if (publishedDate !== undefined) {
-      scalarFields.publishedDate = publishedDate;
-      if (publishedDate !== null) scalarFields.publishedYear = publishedYearFromDateKey(publishedDate);
-    }
-    if (filtered.publishedYear !== undefined && publishedDate === undefined) {
-      scalarFields.publishedDate = null;
-      scalarFields.publishedYear = normalizePublishedYear(filtered.publishedYear);
-    } else if (filtered.publishedYear !== undefined && publishedDate === null) {
-      scalarFields.publishedYear = normalizePublishedYear(filtered.publishedYear);
-    }
+    this.applyPublishedDateFields(scalarFields, filtered.publishedDate, filtered.publishedYear);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@server/src/modules/metadata/metadata.service.ts` around lines 609 - 619, The
published date/year assignment logic in persistAudioMetadata and
persistBookMetadata is duplicated and should be moved into a shared private
helper. Extract the identical scalar-field handling into a helper with a clear
name, then call it from both metadata persistence paths so the
publishedDate/publishedYear behavior stays consistent and lock-sensitive logic
remains in one place.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes