@cyanheads/pubmed-mcp-server 1.0.12

package/dist/utils/parsing/ncbi-parsing/eSummaryResultParser.js

@@ -0,0 +1,295 @@
+/**
+ * @fileoverview Helper functions for parsing ESummary results from NCBI.
+ * Handles different ESummary XML structures and formats the data into
+ * consistent ParsedBriefSummary objects.
+ * @module src/utils/parsing/ncbi-parsing/eSummaryResultParser
+ */
+import { dateParser, logger, requestContextService, } from "../../../utils/index.js"; // Note: utils/index.js is the barrel file
+import { ensureArray, getAttribute, getText } from "./xmlGenericHelpers.js";
+/**
+ * Formats an array of ESummary authors into a string.
+ * Limits to the first 3 authors and adds "et al." if more exist.
+ * @param authors - Array of ESummary author objects (normalized).
+ * @returns A string like "Doe J, Smith A, Brown B, et al." or empty if no authors.
+ */
+export function formatESummaryAuthors(authors) {
+    if (!authors || authors.length === 0)
+        return "";
+    return (authors
+        .slice(0, 3)
+        .map((author) => author.name) // Assumes author.name is the string representation
+        .join(", ") + (authors.length > 3 ? ", et al." : ""));
+}
+/**
+ * Standardizes date strings from ESummary to "YYYY-MM-DD" format.
+ * Uses the dateParser utility.
+ * @param dateStr - Date string from ESummary (e.g., "2023/01/15", "2023 Jan 15", "2023").
+ * @param parentContext - Optional parent request context for logging.
+ * @returns A promise resolving to a standardized date string ("YYYY-MM-DD") or undefined if parsing fails.
+ */
+export async function standardizeESummaryDate(dateStr, parentContext) {
+    if (dateStr === undefined || dateStr === null)
+        return undefined; // Check for null as well
+    const dateInputString = String(dateStr); // Ensure it's a string
+    const currentContext = parentContext ||
+        requestContextService.createRequestContext({
+            operation: "standardizeESummaryDateInternal",
+            inputDate: dateInputString, // Log the stringified version
+        });
+    try {
+        // Pass the stringified version to the date parser
+        const parsedDate = await dateParser.parseDate(dateInputString, currentContext);
+        if (parsedDate) {
+            return parsedDate.toISOString().split("T")[0]; // Format as YYYY-MM-DD
+        }
+        logger.debug(`standardizeESummaryDate: dateParser could not parse "${dateInputString}", returning undefined.`, currentContext);
+    }
+    catch (e) {
+        logger.warning(`standardizeESummaryDate: Error during dateParser.parseDate for "${dateInputString}", returning undefined.`, {
+            ...currentContext,
+            error: e instanceof Error ? e.message : String(e),
+        });
+    }
+    return undefined; // Return undefined if parsing fails
+}
+/**
+ * Parses authors from an ESummary DocumentSummary structure.
+ * Handles various ways authors might be represented.
+ * Returns an array of normalized XmlESummaryAuthor objects.
+ * Internal helper function.
+ */
+function parseESummaryAuthorsFromDocumentSummary(docSummary) {
+    const authorsProp = docSummary.Authors;
+    if (!authorsProp)
+        return [];
+    const parsedAuthors = [];
+    const processRawAuthor = (rawAuthInput) => {
+        let name = "";
+        let authtype;
+        let clusterid;
+        if (typeof rawAuthInput === "string") {
+            name = rawAuthInput;
+        }
+        else if (rawAuthInput && typeof rawAuthInput === "object") {
+            const authorObj = rawAuthInput; // Now typed
+            // Try extracting text from the object itself (e.g., if it's { '#text': 'Author Name' })
+            name = getText(authorObj, "");
+            // If name is still empty, try common property names for author names
+            if (!name) {
+                name = getText(authorObj.Name || authorObj.name, "");
+            }
+            authtype = getText(authorObj.AuthType || authorObj.authtype, undefined);
+            clusterid = getText(authorObj.ClusterId || authorObj.clusterid, undefined);
+            // Fallback for unhandled structures: log and try to stringify
+            if (!name) {
+                const authInputString = JSON.stringify(authorObj);
+                logger.warning(`Unhandled author structure in parseESummaryAuthorsFromDocumentSummary. authInput: ${authInputString.substring(0, 100)}`, requestContextService.createRequestContext({
+                    operation: "parseESummaryAuthorsFromDocumentSummary",
+                    detail: "Unhandled author structure",
+                }));
+                // As a last resort, if it's a simple object with a single value, that might be the name
+                const keys = Object.keys(authorObj);
+                if (keys.length === 1 &&
+                    typeof authorObj[keys[0]] === "string") {
+                    name = authorObj[keys[0]];
+                }
+                else if (authInputString.length < 100) {
+                    // Avoid overly long stringified objects
+                    name = authInputString; // Not ideal, but better than empty for debugging
+                }
+            }
+        }
+        if (name.trim()) {
+            parsedAuthors.push({
+                name: name.trim(),
+                authtype,
+                clusterid,
+            });
+        }
+    };
+    if (Array.isArray(authorsProp)) {
+        // authorsProp could be Array<string> or Array<XmlESummaryAuthorRaw>
+        authorsProp.forEach(processRawAuthor);
+    }
+    else if (typeof authorsProp === "object" &&
+        "Author" in authorsProp && // authorsProp is { Author: ... }
+        authorsProp.Author) {
+        const rawAuthors = ensureArray(authorsProp.Author);
+        rawAuthors.forEach(processRawAuthor);
+    }
+    else if (typeof authorsProp === "string") {
+        try {
+            // Attempt to parse if it looks like a JSON array string
+            if (authorsProp.startsWith("[") && authorsProp.endsWith("]")) {
+                const parsedJsonAuthors = JSON.parse(authorsProp);
+                if (Array.isArray(parsedJsonAuthors)) {
+                    parsedJsonAuthors.forEach((authItem) => {
+                        if (typeof authItem === "string") {
+                            parsedAuthors.push({ name: authItem.trim() });
+                        }
+                        else if (typeof authItem === "object" &&
+                            authItem !== null &&
+                            (authItem.name || authItem.Name)) {
+                            // If it's an object with a name property, treat as XmlESummaryAuthorRaw
+                            processRawAuthor(authItem);
+                        }
+                    });
+                    if (parsedAuthors.length > 0)
+                        return parsedAuthors; // Return if JSON parsing yielded results
+                }
+            }
+        }
+        catch (e) {
+            logger.debug(`Failed to parse Authors string as JSON: ${authorsProp.substring(0, 100)}`, requestContextService.createRequestContext({
+                operation: "parseESummaryAuthorsFromString",
+                input: authorsProp.substring(0, 100),
+                error: e instanceof Error ? e.message : String(e),
+            }));
+        }
+        // Fallback: split string by common delimiters
+        authorsProp
+            .split(/[,;]/)
+            .map((namePart) => namePart.trim())
+            .filter((namePart) => namePart)
+            .forEach((namePart) => parsedAuthors.push({ name: namePart }));
+    }
+    return parsedAuthors.filter((author) => author.name);
+}
+/**
+ * Parses a single ESummary DocumentSummary (newer XML format) into a raw summary object.
+ * Internal helper function.
+ */
+function parseSingleDocumentSummary(docSummary) {
+    const pmid = docSummary["@_uid"];
+    const authorsArray = parseESummaryAuthorsFromDocumentSummary(docSummary);
+    let doiValue = getText(docSummary.DOI, undefined);
+    if (!doiValue) {
+        const articleIdsProp = docSummary.ArticleIds;
+        if (articleIdsProp) {
+            const idsArray = Array.isArray(articleIdsProp)
+                ? articleIdsProp
+                : ensureArray(articleIdsProp.ArticleId);
+            const doiEntry = idsArray.find((id) => id.idtype === "doi");
+            if (doiEntry) {
+                doiValue = getText(doiEntry.value, undefined);
+            }
+        }
+    }
+    return {
+        pmid: String(pmid),
+        title: getText(docSummary.Title, undefined),
+        authors: formatESummaryAuthors(authorsArray),
+        source: getText(docSummary.Source, undefined) ||
+            getText(docSummary.FullJournalName, undefined) ||
+            getText(docSummary.SO, undefined) ||
+            undefined,
+        doi: doiValue,
+        rawPubDate: getText(docSummary.PubDate, undefined),
+        rawEPubDate: getText(docSummary.EPubDate, undefined),
+    };
+}
+/**
+ * Parses a single ESummary DocSum (older XML item-based format) into a raw summary object.
+ * Internal helper function.
+ */
+function parseSingleDocSumOldXml(docSum) {
+    const pmid = docSum.Id;
+    const items = ensureArray(docSum.Item);
+    const getItemValue = (name, type) => {
+        const namesToTry = ensureArray(name);
+        for (const n of namesToTry) {
+            const item = items.find((i) => i._Name === n &&
+                (type ? i._Type === type : true) &&
+                i._Type !== "ERROR");
+            if (item) {
+                const textVal = getText(item);
+                if (textVal !== undefined)
+                    return String(textVal);
+            }
+        }
+        return undefined;
+    };
+    const getAuthorList = () => {
+        const authorListItem = items.find((i) => i._Name === "AuthorList" && i._Type === "List");
+        if (authorListItem && authorListItem.Item) {
+            return ensureArray(authorListItem.Item)
+                .filter((a) => a._Name === "Author" && a._Type === "String")
+                .map((a) => ({ name: getText(a, "") }));
+        }
+        // Fallback for authors directly under DocSum items
+        return items
+            .filter((i) => i._Name === "Author" && i._Type === "String")
+            .map((a) => ({ name: getText(a, "") }));
+    };
+    const authorsArray = getAuthorList();
+    let doiFromItems = getItemValue("DOI", "String");
+    if (!doiFromItems) {
+        const articleIdsItem = items.find((i) => i._Name === "ArticleIds" && i._Type === "List");
+        if (articleIdsItem && articleIdsItem.Item) {
+            const ids = ensureArray(articleIdsItem.Item);
+            const doiIdItem = ids.find((id) => getAttribute(id, "idtype") === "doi" ||
+                id._Name === "doi");
+            if (doiIdItem) {
+                doiFromItems = getText(doiIdItem);
+            }
+        }
+    }
+    return {
+        pmid: String(pmid),
+        title: getItemValue("Title", "String"),
+        authors: formatESummaryAuthors(authorsArray),
+        source: getItemValue(["Source", "FullJournalName", "SO"], "String"),
+        doi: doiFromItems,
+        rawPubDate: getItemValue(["PubDate", "ArticleDate"], "Date"),
+        rawEPubDate: getItemValue("EPubDate", "Date"),
+    };
+}
+/**
+ * Extracts and formats brief summaries from ESummary XML result.
+ * Handles both DocumentSummarySet (newer) and older DocSum structures.
+ * Asynchronously standardizes dates.
+ * @param eSummaryResult - The parsed XML object from ESummary (eSummaryResult part).
+ * @param context - Request context for logging and passing to date standardization.
+ * @returns A promise resolving to an array of parsed brief summary objects.
+ */
+export async function extractBriefSummaries(eSummaryResult, context) {
+    if (!eSummaryResult)
+        return [];
+    const opContext = context ||
+        requestContextService.createRequestContext({
+            operation: "extractBriefSummariesInternal",
+        });
+    if (eSummaryResult.ERROR) {
+        logger.warning("ESummary result contains an error", {
+            ...opContext,
+            errorDetails: eSummaryResult.ERROR,
+        });
+        return [];
+    }
+    let rawSummaries = [];
+    if (eSummaryResult.DocumentSummarySet?.DocumentSummary) {
+        const docSummaries = ensureArray(eSummaryResult.DocumentSummarySet.DocumentSummary);
+        rawSummaries = docSummaries
+            .map(parseSingleDocumentSummary)
+            .filter((s) => s.pmid);
+    }
+    else if (eSummaryResult.DocSum) {
+        const docSums = ensureArray(eSummaryResult.DocSum);
+        rawSummaries = docSums.map(parseSingleDocSumOldXml).filter((s) => s.pmid);
+    }
+    const processedSummaries = [];
+    for (const rawSummary of rawSummaries) {
+        const pubDate = await standardizeESummaryDate(rawSummary.rawPubDate, opContext);
+        const epubDate = await standardizeESummaryDate(rawSummary.rawEPubDate, opContext);
+        processedSummaries.push({
+            pmid: rawSummary.pmid,
+            title: rawSummary.title,
+            authors: rawSummary.authors,
+            source: rawSummary.source,
+            doi: rawSummary.doi,
+            pubDate,
+            epubDate,
+        });
+    }
+    return processedSummaries;
+}

package/dist/utils/parsing/ncbi-parsing/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Barrel file for NCBI XML parsing helper utilities.
+ * Re-exports functions from more specific parser modules.
+ * @module src/utils/parsing/ncbi-parsing/index
+ */
+export * from "./xmlGenericHelpers.js";
+export * from "./pubmedArticleStructureParser.js";
+export * from "./eSummaryResultParser.js";

package/dist/utils/parsing/ncbi-parsing/index.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Barrel file for NCBI XML parsing helper utilities.
+ * Re-exports functions from more specific parser modules.
+ * @module src/utils/parsing/ncbi-parsing/index
+ */
+export * from "./xmlGenericHelpers.js";
+export * from "./pubmedArticleStructureParser.js";
+export * from "./eSummaryResultParser.js";

package/dist/utils/parsing/ncbi-parsing/pubmedArticleStructureParser.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Helper functions for parsing detailed PubMed Article XML structures,
+ * typically from EFetch results.
+ * @module src/utils/parsing/ncbi-parsing/pubmedArticleStructureParser
+ */
+import { XmlArticle, XmlAuthorList, XmlGrantList, XmlJournal, XmlKeywordList, XmlMedlineCitation, XmlMeshHeadingList, XmlPublicationTypeList, ParsedArticleAuthor, ParsedJournalInfo, ParsedMeshTerm, ParsedGrant, ParsedArticleDate } from "../../../types-global/pubmedXml.js";
+/**
+ * Extracts and formats author information from XML.
+ * @param authorListXml - The XML AuthorList element.
+ * @returns An array of formatted author objects.
+ */
+export declare function extractAuthors(authorListXml?: XmlAuthorList): ParsedArticleAuthor[];
+/**
+ * Extracts and formats journal information from XML.
+ * @param journalXml - The XML Journal element from an Article.
+ * @param medlineCitationXml - The XML MedlineCitation element (for MedlinePgn).
+ * @returns Formatted journal information.
+ */
+export declare function extractJournalInfo(journalXml?: XmlJournal, medlineCitationXml?: XmlMedlineCitation): ParsedJournalInfo | undefined;
+/**
+ * Extracts and formats MeSH terms from XML.
+ * @param meshHeadingListXml - The XML MeshHeadingList element.
+ * @returns An array of formatted MeSH term objects.
+ */
+export declare function extractMeshTerms(meshHeadingListXml?: XmlMeshHeadingList): ParsedMeshTerm[];
+/**
+ * Extracts and formats grant information from XML.
+ * @param grantListXml - The XML GrantList element.
+ * @returns An array of formatted grant objects.
+ */
+export declare function extractGrants(grantListXml?: XmlGrantList): ParsedGrant[];
+/**
+ * Extracts DOI from various possible locations in the XML.
+ * Prioritizes ELocationID with ValidYN="Y", then any ELocationID, then ArticleIdList.
+ * @param articleXml - The XML Article element.
+ * @returns The DOI string or undefined.
+ */
+export declare function extractDoi(articleXml?: XmlArticle): string | undefined;
+/**
+ * Extracts publication types from XML.
+ * @param publicationTypeListXml - The XML PublicationTypeList element.
+ * @returns An array of publication type strings.
+ */
+export declare function extractPublicationTypes(publicationTypeListXml?: XmlPublicationTypeList): string[];
+/**
+ * Extracts keywords from XML. Handles single or multiple KeywordList elements.
+ * @param keywordListsXml - The XML KeywordList element or an array of them.
+ * @returns An array of keyword strings.
+ */
+export declare function extractKeywords(keywordListsXml?: XmlKeywordList[] | XmlKeywordList): string[];
+/**
+ * Extracts abstract text from XML. Handles structured abstracts by concatenating sections.
+ * If AbstractText is an array, joins them. If it's a single object/string, uses it directly.
+ * Prefixes with Label if present.
+ * @param abstractXml - The XML Abstract element from an Article.
+ * @returns The abstract text string, or undefined if not found or empty.
+ */
+export declare function extractAbstractText(abstractXml?: XmlArticle["Abstract"]): string | undefined;
+/**
+ * Extracts PMID from MedlineCitation.
+ * @param medlineCitationXml - The XML MedlineCitation element.
+ * @returns The PMID string or undefined.
+ */
+export declare function extractPmid(medlineCitationXml?: XmlMedlineCitation): string | undefined;
+/**
+ * Extracts article dates from XML.
+ * @param articleXml - The XML Article element.
+ * @returns An array of parsed article dates.
+ */
+export declare function extractArticleDates(articleXml?: XmlArticle): ParsedArticleDate[];

package/dist/utils/parsing/ncbi-parsing/pubmedArticleStructureParser.js

@@ -0,0 +1,229 @@
+/**
+ * @fileoverview Helper functions for parsing detailed PubMed Article XML structures,
+ * typically from EFetch results.
+ * @module src/utils/parsing/ncbi-parsing/pubmedArticleStructureParser
+ */
+import { ensureArray, getText, getAttribute } from "./xmlGenericHelpers.js";
+/**
+ * Extracts and formats author information from XML.
+ * @param authorListXml - The XML AuthorList element.
+ * @returns An array of formatted author objects.
+ */
+export function extractAuthors(authorListXml) {
+    if (!authorListXml)
+        return [];
+    const authors = ensureArray(authorListXml.Author);
+    return authors.map((auth) => {
+        let affiliation = "";
+        const affiliations = ensureArray(auth.AffiliationInfo);
+        if (affiliations.length > 0) {
+            affiliation = getText(affiliations[0]?.Affiliation);
+        }
+        return {
+            lastName: getText(auth.LastName),
+            firstName: getText(auth.ForeName), // XML uses ForeName
+            initials: getText(auth.Initials),
+            affiliation: affiliation || undefined, // Ensure undefined if empty
+        };
+    });
+}
+/**
+ * Extracts and formats journal information from XML.
+ * @param journalXml - The XML Journal element from an Article.
+ * @param medlineCitationXml - The XML MedlineCitation element (for MedlinePgn).
+ * @returns Formatted journal information.
+ */
+export function extractJournalInfo(journalXml, medlineCitationXml) {
+    if (!journalXml)
+        return undefined;
+    const pubDate = journalXml.JournalIssue?.PubDate;
+    const year = getText(pubDate?.Year, getText(pubDate?.MedlineDate, "").match(/\d{4}/)?.[0]);
+    return {
+        title: getText(journalXml.Title),
+        isoAbbreviation: getText(journalXml.ISOAbbreviation),
+        volume: getText(journalXml.JournalIssue?.Volume),
+        issue: getText(journalXml.JournalIssue?.Issue),
+        pages: getText(medlineCitationXml?.MedlinePgn) ||
+            getText(medlineCitationXml?.Article?.Pagination?.MedlinePgn),
+        publicationDate: {
+            year: year || undefined,
+            month: getText(pubDate?.Month) || undefined,
+            day: getText(pubDate?.Day) || undefined,
+            medlineDate: getText(pubDate?.MedlineDate) || undefined,
+        },
+    };
+}
+/**
+ * Extracts and formats MeSH terms from XML.
+ * @param meshHeadingListXml - The XML MeshHeadingList element.
+ * @returns An array of formatted MeSH term objects.
+ */
+export function extractMeshTerms(meshHeadingListXml) {
+    if (!meshHeadingListXml)
+        return [];
+    const meshHeadings = ensureArray(meshHeadingListXml.MeshHeading);
+    return meshHeadings.map((mh) => {
+        const qualifiers = ensureArray(mh.QualifierName);
+        const firstQualifier = qualifiers[0];
+        // Check MajorTopicYN at DescriptorName, QualifierName, and the root MeshHeading element
+        const isMajorDescriptor = getAttribute(mh.DescriptorName, "MajorTopicYN") === "Y";
+        const isMajorQualifier = firstQualifier
+            ? getAttribute(firstQualifier, "MajorTopicYN") === "Y"
+            : false;
+        // Some schemas might place MajorTopicYN directly on MeshHeading if no qualifiers
+        const isMajorRoot = getAttribute(mh, "MajorTopicYN") === "Y";
+        return {
+            descriptorName: getText(mh.DescriptorName),
+            descriptorUi: getAttribute(mh.DescriptorName, "UI"),
+            qualifierName: firstQualifier ? getText(firstQualifier) : undefined,
+            qualifierUi: firstQualifier
+                ? getAttribute(firstQualifier, "UI")
+                : undefined,
+            isMajorTopic: isMajorRoot || isMajorDescriptor || isMajorQualifier,
+        };
+    });
+}
+/**
+ * Extracts and formats grant information from XML.
+ * @param grantListXml - The XML GrantList element.
+ * @returns An array of formatted grant objects.
+ */
+export function extractGrants(grantListXml) {
+    if (!grantListXml)
+        return [];
+    const grants = ensureArray(grantListXml.Grant);
+    return grants.map((g) => ({
+        grantId: getText(g.GrantID) || undefined,
+        agency: getText(g.Agency) || undefined,
+        country: getText(g.Country) || undefined,
+    }));
+}
+/**
+ * Extracts DOI from various possible locations in the XML.
+ * Prioritizes ELocationID with ValidYN="Y", then any ELocationID, then ArticleIdList.
+ * @param articleXml - The XML Article element.
+ * @returns The DOI string or undefined.
+ */
+export function extractDoi(articleXml) {
+    if (!articleXml)
+        return undefined;
+    // Check ELocationID first
+    const eLocationIDs = ensureArray(articleXml.ELocationID);
+    // Prioritize valid DOI
+    for (const eloc of eLocationIDs) {
+        if (getAttribute(eloc, "EIdType") === "doi" &&
+            getAttribute(eloc, "ValidYN") === "Y") {
+            const doi = getText(eloc);
+            if (doi)
+                return doi;
+        }
+    }
+    // Fallback to any DOI in ELocationID
+    for (const eloc of eLocationIDs) {
+        if (getAttribute(eloc, "EIdType") === "doi") {
+            const doi = getText(eloc);
+            if (doi)
+                return doi;
+        }
+    }
+    // Check ArticleIdList as a secondary source
+    const articleIds = ensureArray(articleXml.ArticleIdList?.ArticleId);
+    for (const aid of articleIds) {
+        if (getAttribute(aid, "IdType") === "doi") {
+            const doi = getText(aid);
+            if (doi)
+                return doi;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extracts publication types from XML.
+ * @param publicationTypeListXml - The XML PublicationTypeList element.
+ * @returns An array of publication type strings.
+ */
+export function extractPublicationTypes(publicationTypeListXml) {
+    if (!publicationTypeListXml)
+        return [];
+    const pubTypes = ensureArray(publicationTypeListXml.PublicationType);
+    return pubTypes.map((pt) => getText(pt)).filter(Boolean);
+}
+/**
+ * Extracts keywords from XML. Handles single or multiple KeywordList elements.
+ * @param keywordListsXml - The XML KeywordList element or an array of them.
+ * @returns An array of keyword strings.
+ */
+export function extractKeywords(keywordListsXml) {
+    if (!keywordListsXml)
+        return [];
+    const lists = ensureArray(keywordListsXml);
+    const allKeywords = [];
+    for (const list of lists) {
+        const keywords = ensureArray(list.Keyword);
+        keywords.forEach((kw) => {
+            const keywordText = getText(kw);
+            if (keywordText) {
+                allKeywords.push(keywordText);
+            }
+        });
+    }
+    return allKeywords;
+}
+/**
+ * Extracts abstract text from XML. Handles structured abstracts by concatenating sections.
+ * If AbstractText is an array, joins them. If it's a single object/string, uses it directly.
+ * Prefixes with Label if present.
+ * @param abstractXml - The XML Abstract element from an Article.
+ * @returns The abstract text string, or undefined if not found or empty.
+ */
+export function extractAbstractText(abstractXml) {
+    if (!abstractXml || !abstractXml.AbstractText)
+        return undefined;
+    const abstractTexts = ensureArray(abstractXml.AbstractText);
+    if (abstractTexts.length === 0)
+        return undefined;
+    const processedTexts = abstractTexts
+        .map((at) => {
+        // AbstractText can be string directly or object
+        if (typeof at === "string") {
+            return at;
+        }
+        // If it's an object, it should have #text or Label
+        let sectionText = getText(at); // Handles at["#text"]
+        const label = getAttribute(at, "Label");
+        if (label && sectionText) {
+            return `${label.trim()}: ${sectionText.trim()}`;
+        }
+        return sectionText.trim();
+    })
+        .filter(Boolean); // Remove any empty strings resulting from empty sections
+    if (processedTexts.length === 0)
+        return undefined;
+    return processedTexts.join("\n\n").trim() || undefined; // Join sections with double newline
+}
+/**
+ * Extracts PMID from MedlineCitation.
+ * @param medlineCitationXml - The XML MedlineCitation element.
+ * @returns The PMID string or undefined.
+ */
+export function extractPmid(medlineCitationXml) {
+    if (!medlineCitationXml || !medlineCitationXml.PMID)
+        return undefined;
+    return getText(medlineCitationXml.PMID);
+}
+/**
+ * Extracts article dates from XML.
+ * @param articleXml - The XML Article element.
+ * @returns An array of parsed article dates.
+ */
+export function extractArticleDates(articleXml) {
+    if (!articleXml || !articleXml.ArticleDate)
+        return [];
+    const articleDatesXml = ensureArray(articleXml.ArticleDate);
+    return articleDatesXml.map((ad) => ({
+        dateType: getAttribute(ad, "DateType"),
+        year: getText(ad.Year),
+        month: getText(ad.Month),
+        day: getText(ad.Day),
+    }));
+}

package/dist/utils/parsing/ncbi-parsing/xmlGenericHelpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Generic helper functions for parsing XML data, particularly
+ * structures from fast-xml-parser.
+ * @module src/utils/parsing/ncbi-parsing/xmlGenericHelpers
+ */
+/**
+ * Ensures that the input is an array. If it's not an array, it wraps it in one.
+ * Handles undefined or null by returning an empty array.
+ * @param item - The item to ensure is an array.
+ * @returns An array containing the item, or an empty array if item is null/undefined.
+ * @template T - The type of the items in the array.
+ */
+export declare function ensureArray<T>(item: T | T[] | undefined | null): T[];
+/**
+ * Safely extracts text content from an XML element, which might be a string or an object with a "#text" property.
+ * Handles cases where #text might be a number or boolean by converting to string.
+ * @param element - The XML element (string, object with #text, or undefined).
+ * @param defaultValue - The value to return if text cannot be extracted. Defaults to an empty string.
+ * @returns The text content or the default value.
+ */
+export declare function getText(element: any, defaultValue?: string): string;
+/**
+ * Safely extracts an attribute value from an XML element.
+ * Assumes attributes are prefixed with "@_" by fast-xml-parser.
+ * @param element - The XML element object.
+ * @param attributeName - The name of the attribute (e.g., "_UI", "_MajorTopicYN", without the "@_" prefix).
+ * @param defaultValue - The value to return if the attribute is not found. Defaults to an empty string.
+ * @returns The attribute value or the default value.
+ */
+export declare function getAttribute(element: any, attributeName: string, // e.g., "UI", "MajorTopicYN"
+defaultValue?: string): string;