Add vitepress docs

docs/feeds/controller.md

@@ -0,0 +1,132 @@
+# Feed Controller
+
+The `FeedController` class is responsible for managing and executing feed queries in a performant and organized manner. It handles the compilation of feed definitions into executable queries and manages the loading of events based on those queries.
+
+## Usage
+
+```typescript
+import { FeedController } from '@welshman/feeds'
+
+const controller = new FeedController({
+  feed: yourFeedDefinition,
+  request: async ({ filters, relays, onEvent }) => {
+    // Your implementation for fetching events
+  },
+  requestDVM: async ({ kind, tags, relays, onEvent }) => {
+    // Your implementation for DVM requests
+  },
+  getPubkeysForScope: (scope) => {
+    // Return pubkeys for given scope
+    return ['pubkey1', 'pubkey2']
+  },
+  getPubkeysForWOTRange: (min, max) => {
+    // Return pubkeys within WOT range
+    return ['pubkey1', 'pubkey2']
+  },
+  onEvent: (event) => {
+    // Handle received events
+  },
+  onExhausted: () => {
+    // Called when no more events are available
+  },
+  useWindowing: true, // Optional: enable time-window based loading
+})
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+constructor(options: FeedOptions)
+```
+
+Creates a new feed controller with the given options:
+- `feed`: The feed definition to execute
+- `request`: Function to fetch events from relays
+- `requestDVM`: Function to fetch events from DVMs
+- `getPubkeysForScope`: Function to get pubkeys for a scope
+- `getPubkeysForWOTRange`: Function to get pubkeys within a WOT range
+- `onEvent`: Optional callback for received events
+- `onExhausted`: Optional callback when feed is exhausted
+- `useWindowing`: Optional flag to enable time-window based loading
+
+### Methods
+
+#### `load(limit: number): Promise<void>`
+```typescript
+const controller = new FeedController(options)
+await controller.load(10) // Load 10 events
+```
+Loads events from the feed up to the specified limit.
+
+#### `getLoader(): Promise<(limit: number) => Promise<void>>`
+Gets the loader function for this feed. Usually called internally by `load()`.
+
+#### `getRequestItems(): Promise<RequestItem[] | undefined>`
+Gets the compiled request items for this feed. Usually called internally.
+
+## Advanced Features
+
+### Time Windowing
+
+When `useWindowing` is enabled, the controller uses a time-based window approach to load events:
+
+```typescript
+const controller = new FeedController({
+  ...options,
+  useWindowing: true
+})
+```
+
+This is useful for:
+- Loading recent events first
+- Handling large datasets efficiently
+- Progressive loading of historical data
+
+
+## Examples
+
+### Basic Loading
+
+```typescript
+const controller = new FeedController(options)
+await controller.load(20) // Load 20 events
+```
+
+### Custom Loading Strategy
+
+```typescript
+const controller = new FeedController({
+  ...options,
+  useWindowing: true,
+  onEvent: (event) => {
+    console.log('Received event:', event.id)
+  },
+  onExhausted: () => {
+    console.log('No more events available')
+  }
+})
+
+// Load events in batches
+async function loadAllEvents() {
+  while (!exhausted) {
+    await controller.load(10)
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  await controller.load(10)
+} catch (error) {
+  if (error.message.includes('relay')) {
+    // Handle relay errors
+  } else {
+    // Handle other errors
+  }
+}
+```