# Making Requests

Welshman extends Nostr's base subscription model with intelligent caching, repository integration, and configurable behaviors.

## Key Concepts

- **Local Repository**: Events are automatically cached and tracked
- **Cache Intelligence**: Smart decisions about when to use cached data
- **Relay Integration**: Works with the router for optimal relay selection
- **Configurable Behavior**: Control caching and timeouts

## Request and Load

The base functionality for subscription management is implemented in `@welshman/net`. Please refer to [the documentation](/net) for that module for details.

## Collections and Loaders

The `collection` utility creates stores that handle caching, loading, and indexing of Nostr data. It provides a consistent pattern for managing entities that need to be fetched from the network and cached locally.

```typescript
const {
  indexStore,    // Map of all items by key
  deriveItem,    // Get reactive item by key
  loadItem       // Trigger network load
} = collection({
  name: "storeName",      // For persistence
  store: writable([]),    // Base store
  getKey: item => item.id // How to index items
  load: async (key) => {  // Network loader
    // Load logic here
  }
})
```

### Deriving Events

The best way to create collections is by deriving their contents from the app `repository` using `deriveEvents` from `@welshman/store`. For more control, use `deriveEventsMapped`.

```typescript
import {deriveEventsMapped} from "@welshman/store"

export const notes = deriveEvents<TrustedEvent>(repository, {filters: [{kinds: [NOTE]}]})
```

A collection could then be created by passing the `notes` store to `collection`.

### Available Collections

Several common collections are built-in and ready for use:

```typescript
// Profiles
profiles → profilesByPubkey → deriveProfile → loadProfile

// Lists
follows → followsByPubkey → deriveFollows → loadFollows
mutes → mutesByPubkey → deriveMutes → loadMutes
pins → pinsByPubkey → derivePins → loadPins

// Relays
relays → relaysByUrl → deriveRelay → loadRelay
relayLists → relayListsByPubkey → deriveRelayLists → loadRelayLists
messagingRelayLists → messagingRelayListsByPubkey → deriveMessagingRelayLists → loadMessagingRelayLists

// Identity
handles → handlesByNip05 → deriveHandle → loadHandle
zappers → zappersByLnurl → deriveZapper → loadZapper
```

### Example - Loading and Displaying Profiles

```typescript
import {get} from 'svelte/store'
import {displayProfile} from '@welshman/util'
import {deriveProfile, deriveProfileDisplay} from '@welshman/app'

// Subscribe to profile changes - this will automatically load the profile in the background
const profile = deriveProfile(pubkey)

// Display with fallback
const name = displayProfile(get(profile), 'unknown')

// Better: use built-in deriveProfileDisplay utility
const name = deriveProfileDisplay(pubkey)
```

### User-Specific Collections

Several modules provide user-specific derived stores that automatically load data for the currently signed-in user:

```typescript
import { userProfile, userFollows, userMutes, userPins } from '@welshman/app'

userProfile.subscribe(profile => {
  // Current user's profile data
})

userFollows.subscribe(follows => {
  // Current user's follow list
})
```

### Repository Integration

All events from subscriptions are automatically:

- Saved to the repository
- Tracked to their source relay
- Checked against deletion status

The repository serves as an intelligent cache layer, making subsequent queries for the same data faster.

## Feeds

A high-level feed loader utility is also provided, which combines application state with utilities from `@welshman/net` and `@welshman/feeds`.

```typescript
import {NOTE} from '@welshman/util'
import {makeKindFeed} from '@welshman/feeds'
import {createFeedController} from '@welshman/app'

const abortController = new AbortController()

let done = false

const ctrl = createFeedController({
  feed: makeKindFeed(NOTE),
  useWindowing: true,
  signal: abortController.signal,
  onEvent: e => {
    console.log(e)
  },
  onExhausted: () => {
    done = true
  },
})

// Load some notes
ctrl.load(100)

// Cancel any pending requests
abortController.abort()
```