Add vitepress docs

docs/feeds/utils.md

@@ -0,0 +1,175 @@
+# Feed Utilities
+
+The utils module provides helper functions for creating, type-checking, and manipulating feed definitions. It includes factory functions, type guards, feed transformation utilities, and feed traversal tools.
+
+## Feed Factory Functions
+
+Create strongly-typed feed definitions:
+
+```typescript
+// Basic Feeds
+const authors = makeAuthorFeed("pubkey1", "pubkey2")
+const kinds = makeKindFeed(1, 6)
+const search = makeSearchFeed("bitcoin", "nostr")
+const global = makeGlobalFeed()
+
+// Time-based Feeds
+const recent = makeCreatedAtFeed({
+  since: Date.now() - 86400000,
+  relative: ["since"]
+})
+
+// Advanced Feeds
+const dvm = makeDVMFeed({
+  kind: 5300,
+  mappings: [["p", [FeedType.Author]]]
+})
+
+const list = makeListFeed({
+  addresses: ["list_id"],
+  mappings: [["t", [FeedType.Tag, "#t"]]]
+})
+
+// Set Operations
+const union = makeUnionFeed(authors, kinds)
+const intersection = makeIntersectionFeed(authors, recent)
+const difference = makeDifferenceFeed(global, authors)
+```
+
+## Type Guards
+
+Check feed types safely:
+
+```typescript
+const feed: Feed = makeDVMFeed({ kind: 5300 })
+
+if (isDVMFeed(feed)) {
+  // feed is now typed as DVMFeed
+  const [kind] = feed.slice(1)
+}
+
+if (hasSubFeeds(feed)) {
+  // feed is now typed as UnionFeed | IntersectionFeed | DifferenceFeed
+  const subFeeds = getFeedArgs(feed)
+}
+```
+
+## Feed Transformations
+
+### Tag to Feed Conversion
+
+```typescript
+// Default tag mappings
+const defaultTagFeedMappings: TagFeedMapping[] = [
+  ["a", [FeedType.Address]],   // address tags
+  ["e", [FeedType.ID]],        // event references
+  ["p", [FeedType.Author]],    // people/pubkeys
+  ["r", [FeedType.Relay]],     // relay URLs
+  ["t", [FeedType.Tag, "#t"]], // hashtags
+]
+
+// Convert event tags to feeds
+const tags = [["p", "pubkey1"], ["t", "bitcoin"]]
+const feeds = feedsFromTags(tags)
+// => [[FeedType.Author, "pubkey1"], [FeedType.Tag, "#t", "bitcoin"]]
+
+// Convert tags to a single intersection feed
+const feed = feedFromTags(tags)
+// => [FeedType.Intersection, [FeedType.Author, "pubkey1"], [FeedType.Tag, "#t", "bitcoin"]]
+```
+
+### Filter to Feed Conversion
+
+```typescript
+// Convert a single filter to feeds
+const filter = {
+  kinds: [1],
+  authors: ["pubkey1"],
+  "#t": ["bitcoin"],
+  since: 1234567890
+}
+
+const feeds = feedsFromFilter(filter)
+// => [
+//   [FeedType.CreatedAt, { since: 1234567890 }],
+//   [FeedType.Kind, 1],
+//   [FeedType.Author, "pubkey1"],
+//   [FeedType.Tag, "#t", "bitcoin"]
+// ]
+
+// Convert a filter to an intersection feed
+const feed = feedFromFilter(filter)
+
+// Convert multiple filters to a union feed
+const feeds = feedFromFilters([filter1, filter2])
+```
+
+## Feed Traversal
+
+Walk through a feed tree and visit each node:
+
+```typescript
+const feed = makeIntersectionFeed(
+  makeAuthorFeed("pubkey1"),
+  makeUnionFeed(
+    makeKindFeed(1),
+    makeTagFeed("#t", "bitcoin")
+  )
+)
+
+walkFeed(feed, (node) => {
+  console.log(`Visiting feed of type: ${node[0]}`)
+})
+```
+
+## Type Extraction
+
+Get typed arguments from feeds:
+
+```typescript
+function getFeedArgs(feed: IntersectionFeed): Feed[]
+function getFeedArgs(feed: AuthorFeed): string[]
+function getFeedArgs(feed: CreatedAtFeed): CreatedAtItem[]
+function getFeedArgs(feed: WOTFeed): WOTItem[]
+// ... and so on for each feed type
+
+const feed = makeAuthorFeed("pubkey1", "pubkey2")
+const pubkeys = getFeedArgs(feed) // => ["pubkey1", "pubkey2"]
+```
+
+## Best Practices
+
+1. Use factory functions instead of raw arrays:
+   ```typescript
+   // Good
+   const feed = makeAuthorFeed("pubkey1")
+
+   // Avoid
+   const feed = [FeedType.Author, "pubkey1"]
+   ```
+
+2. Use type guards for safe type narrowing:
+   ```typescript
+   if (isAuthorFeed(feed)) {
+     const pubkeys = getFeedArgs(feed) // Properly typed
+   }
+   ```
+
+3. Use feed transformations for dynamic feed creation:
+   ```typescript
+   // Convert event tags to feeds
+   const feeds = feedsFromTags(event.tags)
+
+   // Convert filters to feeds
+   const feed = feedFromFilter(filter)
+   ```
+
+4. Use feed traversal for analysis or transformation:
+   ```typescript
+   const kinds = new Set<number>()
+   walkFeed(feed, (node) => {
+     if (isKindFeed(node)) {
+       getFeedArgs(node).forEach(k => kinds.add(k))
+     }
+   })
+   ```