@molecule/api-feed-rss-parser 1.0.0

package/dist/utilities.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Normalize a value that may be a single item or an array into a definite array.
+ * `undefined` and `null` collapse to `[]` so callers can iterate unconditionally.
+ *
+ * @param value - The (possibly array, possibly nullish, possibly scalar) value.
+ * @returns A non-null array. Never returns `undefined`.
+ */
+export declare function toArray<T>(value: T | T[] | undefined | null): T[];
+/**
+ * Coerce a (possibly array-valued) fast-xml-parser node to its first usable
+ * text value. Mirrors {@link textOf} but transparently unwraps arrays — which
+ * the parser produces for any element listed in `isArray`.
+ *
+ * @param value - The fast-xml-parser node — string, primitive, object, array, or nullish.
+ * @returns Trimmed first text value, or `undefined` when no usable value exists.
+ */
+export declare function firstText(value: unknown): string | undefined;
+/**
+ * Coerce a fast-xml-parser node to a string.
+ *
+ * fast-xml-parser may emit a leaf as either:
+ * - a primitive (`string` / `number` / `boolean`)
+ * - an object with `#text` (when the element has attributes alongside content)
+ * - an object with attribute keys (when `textNodeName` differs)
+ *
+ * This helper handles all three. Returns `undefined` when no usable value exists.
+ *
+ * @param value - The fast-xml-parser leaf value.
+ * @returns Trimmed string or `undefined`.
+ */
+export declare function textOf(value: unknown): string | undefined;
+/**
+ * Extract an attribute value (e.g. `href`, `url`) from a fast-xml-parser node.
+ *
+ * Attributes are exposed under the `attributeNamePrefix` ('@_' by default).
+ * This helper is tolerant of missing attribute objects.
+ *
+ * @param value - The fast-xml-parser node (object, primitive, or undefined).
+ * @param name - Attribute name without the prefix (e.g. `'href'`).
+ * @returns Attribute value as a trimmed string, or `undefined`.
+ */
+export declare function attrOf(value: unknown, name: string): string | undefined;
+/**
+ * Parse a date-ish string into an ISO 8601 timestamp.
+ *
+ * Accepts RFC 822 (RSS `pubDate`), RFC 3339 (Atom / JSON Feed), and most
+ * common variants the JavaScript `Date` constructor handles natively.
+ *
+ * @param value - Possibly a date string, or `undefined`.
+ * @returns ISO 8601 string when parseable, else `undefined`.
+ */
+export declare function toIsoDate(value: string | undefined): string | undefined;
+/**
+ * Parse iTunes podcast `<itunes:duration>` formats into seconds.
+ *
+ * Accepted shapes:
+ * - bare integer seconds: `"3600"`
+ * - `MM:SS`: `"42:30"`
+ * - `HH:MM:SS`: `"01:42:30"`
+ *
+ * @param value - The duration string, or `undefined`.
+ * @returns Duration in seconds, or `undefined` when unparseable.
+ */
+export declare function parseItunesDuration(value: string | undefined): number | undefined;
+/**
+ * Compute a stable identifier when a feed item has neither a GUID nor a link.
+ *
+ * Uses SHA-1 over `title + '
' + publishedAt` to give a deterministic,
+ * compact key. Collisions are tolerable here — this is a deduplication aid,
+ * not a security primitive.
+ *
+ * @param title - Item title (may be empty).
+ * @param publishedAt - Pre-parsed ISO 8601 publication date, if any.
+ * @returns Hex-encoded SHA-1 digest. Always 40 characters.
+ */
+export declare function synthesizeItemId(title: string, publishedAt: string | undefined): string;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,EAAE,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAS5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAuBzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAavE;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAejF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMvF"}

package/dist/utilities.js

@@ -0,0 +1,162 @@
+import { createHash } from 'node:crypto';
+/**
+ * Normalize a value that may be a single item or an array into a definite array.
+ * `undefined` and `null` collapse to `[]` so callers can iterate unconditionally.
+ *
+ * @param value - The (possibly array, possibly nullish, possibly scalar) value.
+ * @returns A non-null array. Never returns `undefined`.
+ */
+export function toArray(value) {
+    if (value == null)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * Coerce a (possibly array-valued) fast-xml-parser node to its first usable
+ * text value. Mirrors {@link textOf} but transparently unwraps arrays — which
+ * the parser produces for any element listed in `isArray`.
+ *
+ * @param value - The fast-xml-parser node — string, primitive, object, array, or nullish.
+ * @returns Trimmed first text value, or `undefined` when no usable value exists.
+ */
+export function firstText(value) {
+    if (Array.isArray(value)) {
+        for (const candidate of value) {
+            const text = textOf(candidate);
+            if (text)
+                return text;
+        }
+        return undefined;
+    }
+    return textOf(value);
+}
+/**
+ * Coerce a fast-xml-parser node to a string.
+ *
+ * fast-xml-parser may emit a leaf as either:
+ * - a primitive (`string` / `number` / `boolean`)
+ * - an object with `#text` (when the element has attributes alongside content)
+ * - an object with attribute keys (when `textNodeName` differs)
+ *
+ * This helper handles all three. Returns `undefined` when no usable value exists.
+ *
+ * @param value - The fast-xml-parser leaf value.
+ * @returns Trimmed string or `undefined`.
+ */
+export function textOf(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed === '' ? undefined : trimmed;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        if ('#text' in obj) {
+            const text = obj['#text'];
+            if (typeof text === 'string') {
+                const trimmed = text.trim();
+                return trimmed === '' ? undefined : trimmed;
+            }
+            if (typeof text === 'number' || typeof text === 'boolean') {
+                return String(text);
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract an attribute value (e.g. `href`, `url`) from a fast-xml-parser node.
+ *
+ * Attributes are exposed under the `attributeNamePrefix` ('@_' by default).
+ * This helper is tolerant of missing attribute objects.
+ *
+ * @param value - The fast-xml-parser node (object, primitive, or undefined).
+ * @param name - Attribute name without the prefix (e.g. `'href'`).
+ * @returns Attribute value as a trimmed string, or `undefined`.
+ */
+export function attrOf(value, name) {
+    if (value == null || typeof value !== 'object')
+        return undefined;
+    const obj = value;
+    const raw = obj[`@_${name}`];
+    if (raw == null)
+        return undefined;
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        return trimmed === '' ? undefined : trimmed;
+    }
+    if (typeof raw === 'number' || typeof raw === 'boolean') {
+        return String(raw);
+    }
+    return undefined;
+}
+/**
+ * Parse a date-ish string into an ISO 8601 timestamp.
+ *
+ * Accepts RFC 822 (RSS `pubDate`), RFC 3339 (Atom / JSON Feed), and most
+ * common variants the JavaScript `Date` constructor handles natively.
+ *
+ * @param value - Possibly a date string, or `undefined`.
+ * @returns ISO 8601 string when parseable, else `undefined`.
+ */
+export function toIsoDate(value) {
+    if (!value)
+        return undefined;
+    const ts = Date.parse(value);
+    if (Number.isNaN(ts))
+        return undefined;
+    return new Date(ts).toISOString();
+}
+/**
+ * Parse iTunes podcast `<itunes:duration>` formats into seconds.
+ *
+ * Accepted shapes:
+ * - bare integer seconds: `"3600"`
+ * - `MM:SS`: `"42:30"`
+ * - `HH:MM:SS`: `"01:42:30"`
+ *
+ * @param value - The duration string, or `undefined`.
+ * @returns Duration in seconds, or `undefined` when unparseable.
+ */
+export function parseItunesDuration(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return undefined;
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    const parts = trimmed.split(':').map((p) => p.trim());
+    if (parts.length === 2 || parts.length === 3) {
+        const nums = parts.map((p) => Number(p));
+        if (nums.some((n) => Number.isNaN(n)))
+            return undefined;
+        if (parts.length === 3) {
+            return nums[0] * 3600 + nums[1] * 60 + nums[2];
+        }
+        return nums[0] * 60 + nums[1];
+    }
+    return undefined;
+}
+/**
+ * Compute a stable identifier when a feed item has neither a GUID nor a link.
+ *
+ * Uses SHA-1 over `title + '
' + publishedAt` to give a deterministic,
+ * compact key. Collisions are tolerable here — this is a deduplication aid,
+ * not a security primitive.
+ *
+ * @param title - Item title (may be empty).
+ * @param publishedAt - Pre-parsed ISO 8601 publication date, if any.
+ * @returns Hex-encoded SHA-1 digest. Always 40 characters.
+ */
+export function synthesizeItemId(title, publishedAt) {
+    const hash = createHash('sha1');
+    hash.update(title);
+    hash.update('
');
+    hash.update(publishedAt ?? '');
+    return hash.digest('hex');
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@molecule/api-feed-rss-parser",
+  "version": "1.0.0",
+  "description": "RSS/Atom/JSON Feed parser — normalizes RSS 2.0, Atom 1.0, RDF 1.0, and JSON Feed into a uniform { feed, items[] } shape.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "feed",
+    "rss",
+    "atom",
+    "json-feed",
+    "podcast",
+    "parser"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "fast-xml-parser": "5.10.1"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  }
+}