Add RSS/Atom feed collection package for TanStack DB

Co-authored-by: sam.willis <[email protected]>

Author: cursoragent

packages/rss-db-collection/README.md

@@ -0,0 +1,62 @@
+{
+  "name": "@tanstack/rss-db-collection",
+  "description": "RSS/Atom feed collection for TanStack DB",
+  "version": "0.1.0",
+  "dependencies": {
+    "@standard-schema/spec": "^1.0.0",
+    "@tanstack/db": "workspace:*",
+    "debug": "^4.4.1",
+    "fast-xml-parser": "^4.5.0"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@vitest/coverage-istanbul": "^3.0.9"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.js",
+  "packageManager": "[email protected]",
+  "peerDependencies": {
+    "typescript": ">=4.7"
+  },
+  "author": "Claude AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TanStack/db.git",
+    "directory": "packages/rss-db-collection"
+  },
+  "homepage": "https://tanstack.com/db",
+  "keywords": [
+    "rss",
+    "atom",
+    "feed",
+    "polling",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "lint": "eslint . --fix",
+    "test": "npx vitest --run"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "types": "dist/esm/index.d.ts"
+}

packages/rss-db-collection/package.json

@@ -0,0 +1,81 @@
+/**
+ * Base error class for RSS Collection errors
+ */
+export abstract class RSSCollectionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = this.constructor.name
+  }
+}
+
+/**
+ * Error thrown when feed URL is required but not provided
+ */
+export class FeedURLRequiredError extends RSSCollectionError {
+  constructor() {
+    super(`Feed URL is required for RSS collection`)
+  }
+}
+
+/**
+ * Error thrown when polling interval is invalid
+ */
+export class InvalidPollingIntervalError extends RSSCollectionError {
+  constructor(interval: number) {
+    super(
+      `Invalid polling interval: ${interval}. Must be a positive number in milliseconds.`
+    )
+  }
+}
+
+/**
+ * Error thrown when feed parsing fails
+ */
+export class FeedParsingError extends RSSCollectionError {
+  constructor(url: string, originalError: Error) {
+    super(`Failed to parse feed from ${url}: ${originalError.message}`)
+    this.cause = originalError
+  }
+}
+
+/**
+ * Error thrown when feed fetch fails
+ */
+export class FeedFetchError extends RSSCollectionError {
+  constructor(url: string, status?: number) {
+    super(
+      status
+        ? `Failed to fetch feed from ${url}: HTTP ${status}`
+        : `Failed to fetch feed from ${url}`
+    )
+  }
+}
+
+/**
+ * Error thrown when timeout occurs while fetching feed
+ */
+export class FeedTimeoutError extends RSSCollectionError {
+  constructor(url: string, timeout: number) {
+    super(`Timeout after ${timeout}ms while fetching feed from ${url}`)
+  }
+}
+
+/**
+ * Error thrown when feed format is not supported
+ */
+export class UnsupportedFeedFormatError extends RSSCollectionError {
+  constructor(url: string) {
+    super(
+      `Unsupported feed format from ${url}. Only RSS and Atom feeds are supported.`
+    )
+  }
+}
+
+/**
+ * Error thrown when required getKey function is not provided
+ */
+export class GetKeyRequiredError extends RSSCollectionError {
+  constructor() {
+    super(`getKey function is required for RSS collection`)
+  }
+}

packages/rss-db-collection/src/errors.ts

@@ -0,0 +1,94 @@
+/**
+ * RSS/Atom Feed Collection for TanStack DB
+ *
+ * This package provides RSS and Atom feed collection capabilities with:
+ * - Automatic feed type detection (RSS/Atom)
+ * - Configurable polling intervals
+ * - Built-in deduplication
+ * - Custom transform functions
+ * - Full TypeScript support
+ *
+ * @example RSS Collection
+ * ```typescript
+ * import { createCollection } from '@tanstack/db'
+ * import { rssCollectionOptions } from '@tanstack/rss-db-collection'
+ *
+ * interface BlogPost {
+ *   id: string
+ *   title: string
+ *   description: string
+ *   link: string
+ *   publishedAt: Date
+ * }
+ *
+ * const blogFeed = createCollection({
+ *   ...rssCollectionOptions<BlogPost>({
+ *     feedUrl: 'https://blog.example.com/rss.xml',
+ *     pollingInterval: 5 * 60 * 1000, // 5 minutes
+ *     getKey: (item) => item.id,
+ *     transform: (item) => ({
+ *       id: item.guid || item.link || '',
+ *       title: item.title || '',
+ *       description: item.description || '',
+ *       link: item.link || '',
+ *       publishedAt: new Date(item.pubDate || Date.now())
+ *     })
+ *   })
+ * })
+ * ```
+ *
+ * @example Atom Collection
+ * ```typescript
+ * import { createCollection } from '@tanstack/db'
+ * import { atomCollectionOptions } from '@tanstack/rss-db-collection'
+ *
+ * const atomFeed = createCollection({
+ *   ...atomCollectionOptions<BlogPost>({
+ *     feedUrl: 'https://blog.example.com/atom.xml',
+ *     pollingInterval: 5 * 60 * 1000, // 5 minutes
+ *     getKey: (item) => item.id,
+ *     transform: (item) => ({
+ *       id: item.id || '',
+ *       title: typeof item.title === 'string' ? item.title : item.title?.$text || '',
+ *       description: typeof item.summary === 'string' ? item.summary : item.summary?.$text || '',
+ *       link: typeof item.link === 'string' ? item.link : item.link?.href || '',
+ *       publishedAt: new Date(item.published || item.updated || Date.now())
+ *     })
+ *   })
+ * })
+ * ```
+ */
+
+// RSS collection functionality
+export {
+  rssCollectionOptions,
+  type RSSCollectionConfig,
+  type RSSItem,
+} from "./rss"
+
+// Atom collection functionality
+export {
+  atomCollectionOptions,
+  type AtomCollectionConfig,
+  type AtomItem,
+} from "./rss"
+
+// Shared types and utilities
+export {
+  type FeedItem,
+  type FeedType,
+  type HTTPOptions,
+  type FeedCollectionUtils,
+} from "./rss"
+
+// Error types
+export {
+  RSSCollectionError,
+  FeedURLRequiredError,
+  InvalidPollingIntervalError,
+  FeedParsingError,
+  FeedFetchError,
+  FeedTimeoutError,
+  UnsupportedFeedFormatError,
+  GetKeyRequiredError,
+} from "./errors"