fix(opds): align mapping with OPDS 2.0 WebPub properties, support OPD…

[zeedif]

This PR aims to refine the parser so that OPDS 1.x attributes perfectly align with the target OPDS 2.0 (Readium WebPub Manifest) layout without bleeding deprecated metadata onto the root object, while fixing deep DOM evaluation bugs and bringing support for OPDS-PSE (Page Streaming) and Paging extensions.

Improvements & Bug Fixes

• Aligning OPDS 1.x mapping exclusively with OPDS 2.0 properties:

  • Prevents OPDS 1.2 and OPDS 2.0 hybrid property bleeding onto the root object.
  • Correctly maps thr:count exclusively to OPDS 2.0's properties.numberOfItems.
  • OpenSearch attributes (totalResults, itemsPerPage, startIndex) are now natively mapped directly into OPDS 2.0 metadata pagination elements (numberOfItems, itemsPerPage, currentPage).
  • Facet activation (opds:activeFacet="true") is mapped seamlessly by appending the OPDS 2.0 native "self" to the rel array instead of preserving the legacy XML attribute.

• Prices & Indirect Acquisitions Hierarchy Bug Fix:

  • Previously, getElementsByTagNameNS(...)[0] was used. This caused two major issues: it ignored multiple prices/currencies (e.g., both USD and GBP for the same link) and it broke hierarchy for sibling nested indirectAcquisition branches (only capturing the first deep node instead of treating them as trees like an archive bundle with EPUB, MOBI, and PDF inside).
  • Replaced with getDirectChildren() to correctly map them strictly inside OPDS 2.0 properties.price and properties.indirectAcquisition maintaining full recursive JSON schema compatibility.

• OPDS Page Streaming Extension (OPDS-PSE) Support:

  • Added REL.STREAM (http://vaemendis.net/opds-pse/stream) to properly recognize stream endpoints as OPDS publications rather than navigational entries.
  • Safe-maps namespaced extensions (pse:count, pse:lastRead, and pse:lastReadDate) into the properties object to match the WebPub Manifest specification for custom properties.

• RFC 5005 (Paging and Archiving):

  • Adds evaluation for the fh:complete and fh:archive elements using the http://purl.org/syndication/history/1.0 namespace exposing them transparently at the root level of the returned feed wrapper.

[johnfactotum]

Thanks. Currently the PR is rather large, with many unrelated changes. Can you perhaps make each change a separate PR?

In particular, a lot of the changes seem to be merely avoiding having properties with undefined values on the resulting objects. Is there a reason for this? It doesn't seem to be related to the main changes that you're describing.

[zeedif]

The reason for removing null and omitting empty properties is strict compliance with the OPDS 2.0 Specification. The spec defines a Blank Value as null, "", [], or {}. Furthermore, Section 5.2 Metadata explicitly states: "A metadata object in OPDS 2.0 should not contain any properties with a blank value."

I viewed the initial mapping fixes and the blank value omissions as a single logical unit, as both serve the exact same goal: mapping OPDS 1.x feeds into a perfectly spec-compliant OPDS 2.0 / WebPub layout.

However, the middle commit was definitely a tangent. I have removed the 2nd commit (Legacy/Stanza support) from this branch right now and move it to its own isolated PR.

Regarding the 1st and 3rd commits: since they both work together to achieve strict OPDS 2.0 compliance, does it make sense to keep them together here, or would you still prefer I split the "Blank Values" refactor into a third PR?

[johnfactotum]

OK. I think I got a bit confused, as the objects returned by getOpenSearch/getSearch are not OPDS documents at all. Personally I think empty values are OK as it's not really intended to be used to publish OPDS, but merely to convert them for use in reading systems ("SHOULD NOT [...] mean[s] that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful"). I also find it cleaner to just clean up the object afterwards, like what I did in epub.js with tidy(), though I guess that's a matter of taste depending on one's specific needs.

[zeedif]

My initial reasoning for omitting empty properties was to strictly adhere to the OPDS 2.0 specification regarding "Blank Values," aiming for a minimal JSON output. However, as you pointed out, since this library acts as a client consumer and not a publisher, the benefits of such strictness are minimal and unnecessary.

I've refactored the code to align with your suggested approach. The defensive checks have been removed in favor of a more direct, declarative style. I only retained the change from null to undefined and the conditional extraction logic for link attributes based on their role. Thank you for the feedback.

[zeedif]

I've mapped DOM null returns to undefined. This makes it much simpler when working with TypeScript, as the object will only expect undefined rather than having to handle both types. I also generalized the numberOfItems fallback because, according to OPDS 1.2 spec regarding the thr:count attribute (extracted from RFC4685), I realized that the thr:count property is not exclusively tied to links pointing to facet feeds. Because of this, the count attribute should apply as a fallback for numberOfItems on all non-stream links. Lastly, I removed the redundant check on properties (if (Object.keys(obj.properties).length === 0) delete obj.properties) because it was an unnecessary cleanup step.

I consider it ready for review and acceptance, if there are no other details.