Welshman

Appearance

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
  }
}