coracle/welshman
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update feed docs

Browse Source
This commit is contained in:
Jon Staab
2025-06-10 14:15:45 -07:00
parent 26739f9271
commit 5b73c507b7
4 changed files with 227 additions and 510 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/feeds/core.md
+59 -303
View File
@@ -1,341 +1,97 @@
# Feed Types and Core Definitions
# Feed Core Types
This module defines the core types and structures used to build Nostr feeds.
It provides a type-safe way to define complex feed compositions using various filtering mechanisms and set operations.
Core type definitions for the feed system, providing structured ways to query and filter Nostr events.
## Feed Types
```typescript
enum FeedType {
Address = "address", // Filter by event addresses
Author = "author", // Filter by author pubkeys
CreatedAt = "created_at", // Filter by timestamp
DVM = "dvm", // Data Vending Machine based feed
Difference = "difference", // Set difference operation
ID = "id", // Filter by event IDs
Intersection = "intersection", // Set intersection operation
Global = "global", // Global feed (no filters)
Kind = "kind", // Filter by event kinds
List = "list", // List-based feed
Label = "label", // Label-based feed
WOT = "wot", // Web of Trust based feed
Relay = "relay", // Relay-specific feed
Scope = "scope", // Scoped feed (followers, network)
Search = "search", // Search-based feed
Tag = "tag", // Filter by specific tags
Union = "union" // Set union operation
export enum FeedType {
Address = "address",
Author = "author",
CreatedAt = "created_at",
DVM = "dvm",
Difference = "difference",
ID = "id",
Intersection = "intersection",
Global = "global",
Kind = "kind",
List = "list",
Label = "label",
WOT = "wot",
Relay = "relay",
Scope = "scope",
Search = "search",
Tag = "tag",
Union = "union",
}
export enum Scope {
Followers = "followers",
Follows = "follows",
Network = "network",
Self = "self",
}
```
## Scope Types
## Item Types
```typescript
enum Scope {
Followers = "followers", // People who follow the user
Follows = "follows", // People the user follows
Network = "network", // Extended network
Self = "self" // The signed in user
}
```
## Feed Definitions
Each feed type has its own structure:
### Basic Filter Feeds
```typescript
type AddressFeed = [type: FeedType.Address, ...addresses: string[]]
type AuthorFeed = [type: FeedType.Author, ...pubkeys: string[]]
type IDFeed = [type: FeedType.ID, ...ids: string[]]
type KindFeed = [type: FeedType.Kind, ...kinds: number[]]
type TagFeed = [type: FeedType.Tag, key: string, ...values: string[]]
```
### Time-based Feeds
```typescript
type CreatedAtItem = {
since?: number
until?: number
relative?: string[] // For relative time references
}
type CreatedAtFeed = [type: FeedType.CreatedAt, ...items: CreatedAtItem[]]
```
### Advanced Filter Feeds
```typescript
// DVM-based feed
type DVMItem = {
export type DVMItem = {
kind: number
tags?: string[][]
relays?: string[]
mappings?: TagFeedMapping[]
}
type DVMFeed = [type: FeedType.DVM, ...items: DVMItem[]]
// List-based feed
type ListItem = {
export type ListItem = {
addresses: string[]
mappings?: TagFeedMapping[]
}
type ListFeed = [type: FeedType.List, ...items: ListItem[]]
// Label-based feed
type LabelItem = {
export type LabelItem = {
relays?: string[]
authors?: string[]
[key: `#${string}`]: string[]
mappings?: TagFeedMapping[]
}
type LabelFeed = [type: FeedType.Label, ...items: LabelItem[]]
// Web of Trust feed
type WOTItem = {
export type WOTItem = {
min?: number
max?: number
}
type WOTFeed = [type: FeedType.WOT, ...items: WOTItem[]]
```
## Tag Feed Mapping
export type CreatedAtItem = {
since?: number
until?: number
relative?: string[]
}
`TagFeedMapping` is a mechanism to convert event tags into feed definitions. It's particularly useful when working with DVMs, Lists, and Labels where you want to interpret tags in a specific way.
```typescript
type TagFeedMapping = [string, Feed]
```
### Usage
```typescript
// Example mappings
const mappings: TagFeedMapping[] = [
// Convert 'p' tags into author feeds
["p", [FeedType.Author]],
// Convert 't' tags into hashtag filters
["t", [FeedType.Tag, "#t"]],
// Convert 'e' tags into event ID feeds
["e", [FeedType.ID]],
// Convert 'r' tags into relay feeds
["r", [FeedType.Relay]]
]
// Using mappings in a DVM feed
const dvmFeed: Feed = [
FeedType.DVM,
{
kind: 5300,
mappings: mappings
}
]
// Using mappings in a List feed
const listFeed: Feed = [
FeedType.List,
{
addresses: ["list_id"],
mappings: mappings
}
]
```
### Default Mappings
The system comes with default mappings for common tags:
```typescript
const defaultTagFeedMappings: TagFeedMapping[] = [
["a", [FeedType.Address]], // Address references
["e", [FeedType.ID]], // Event references
["p", [FeedType.Author]], // Person/Pubkey references
["r", [FeedType.Relay]], // Relay references
["t", [FeedType.Tag, "#t"]], // Hashtags
]
```
## Set Operation Feeds
### Union Feed
A Union feed combines multiple feeds with an OR operation. Events matching any of the constituent feeds will be included.
```typescript
type UnionFeed = [type: FeedType.Union, ...feeds: Feed[]]
// Example: Events from either Alice OR Bob
const unionFeed: UnionFeed = [
FeedType.Union,
[FeedType.Author, "alice_pubkey"],
[FeedType.Author, "bob_pubkey"]
]
// Example: Events from a list OR matching a search term
const complexUnion: UnionFeed = [
FeedType.Union,
[FeedType.List, { addresses: ["trending_list"] }],
[FeedType.Search, "bitcoin"]
]
```
### Intersection Feed
An Intersection feed combines multiple feeds with an AND operation. Only events that match all constituent feeds will be included.
```typescript
type IntersectionFeed = [type: FeedType.Intersection, ...feeds: Feed[]]
// Example: Text notes (kind 1) from trusted authors
const intersectionFeed: IntersectionFeed = [
FeedType.Intersection,
[FeedType.Kind, 1],
[FeedType.WOT, { min: 0.5 }]
]
// Example: Recent posts from followed users
const timeAndScope: IntersectionFeed = [
FeedType.Intersection,
[FeedType.CreatedAt, { since: Date.now() - 86400000 }], // Last 24h
[FeedType.Scope, Scope.Follows]
]
```
### Difference Feed
A Difference feed excludes events from the second feed from the first feed (NOT operation).
```typescript
type DifferenceFeed = [type: FeedType.Difference, ...feeds: Feed[]]
// Example: Posts from everyone except blocked users
const differenceFeed: DifferenceFeed = [
FeedType.Difference,
[FeedType.Global], // All events
[FeedType.List, { addresses: ["blocked_users"] }] // Except from blocked users
]
// Example: Posts from follows except reposts
const noReposts: DifferenceFeed = [
FeedType.Difference,
[FeedType.Scope, Scope.Follows],
[FeedType.Kind, 6] // Kind 6 is repost
]
```
### Complex Combinations
You can nest set operations to create sophisticated feed definitions:
```typescript
// Posts that are either:
// - from trusted authors AND about bitcoin
// - OR from a curated list
const complexFeed: Feed = [
FeedType.Union,
[
FeedType.Intersection,
[FeedType.WOT, { min: 0.7 }],
[FeedType.Search, "bitcoin"]
],
[FeedType.List, { addresses: ["curated_content"] }]
]
// Posts that are:
// - from follows
// - AND (from the last 24h OR highly rated by DVMs)
// - AND NOT marked as sensitive content
const advancedFeed: Feed = [
FeedType.Difference,
[
FeedType.Intersection,
[FeedType.Scope, Scope.Follows],
[
FeedType.Union,
[FeedType.CreatedAt, { since: Date.now() - 86400000 }],
[FeedType.DVM, { kind: 5300, pubkey: "rating_dvm" }]
]
],
[FeedType.Label, { authors: ["content_warning_dvm"] }]
]
```
## Feed Controller Options
The `FeedOptions` interface defines the configuration required to execute a feed:
```typescript
interface FeedOptions {
// The feed definition to execute
feed: Feed
// Function to request events from relays
request: (opts: RequestOpts) => Promise<void>
// Function to request events from DVMs
requestDVM: (opts: DVMOpts) => Promise<void>
// Function to get pubkeys for a given scope
getPubkeysForScope: (scope: Scope) => string[]
// Function to get pubkeys within a WOT range
getPubkeysForWOTRange: (minWOT: number, maxWOT: number) => string[]
// Event handler
onEvent?: (event: TrustedEvent) => void
// Called when feed is exhausted
onExhausted?: () => void
// Enable time-window based loading
useWindowing?: boolean
// Optional abort controller
abortController?: AbortController
export type RequestItem = {
relays?: string[]
filters?: Filter[]
}
```
## Examples
## Feed Definitions
### Simple Author Feed
```typescript
const authorFeed: Feed = [FeedType.Author, "pubkey1", "pubkey2"]
```
export type AddressFeed = [type: FeedType.Address, ...addresses: string[]]
export type AuthorFeed = [type: FeedType.Author, ...pubkeys: string[]]
export type CreatedAtFeed = [type: FeedType.CreatedAt, ...items: CreatedAtItem[]]
export type DVMFeed = [type: FeedType.DVM, ...items: DVMItem[]]
export type DifferenceFeed = [type: FeedType.Difference, ...feeds: Feed[]]
export type IDFeed = [type: FeedType.ID, ...ids: string[]]
export type IntersectionFeed = [type: FeedType.Intersection, ...feeds: Feed[]]
export type GlobalFeed = [type: FeedType.Global, ...feeds: Feed[]]
export type KindFeed = [type: FeedType.Kind, ...kinds: number[]]
export type ListFeed = [type: FeedType.List, ...items: ListItem[]]
export type LabelFeed = [type: FeedType.Label, ...items: LabelItem[]]
export type WOTFeed = [type: FeedType.WOT, ...items: WOTItem[]]
export type RelayFeed = [type: FeedType.Relay, ...urls: string[]]
export type ScopeFeed = [type: FeedType.Scope, ...scopes: Scope[]]
export type SearchFeed = [type: FeedType.Search, ...searches: string[]]
export type TagFeed = [type: FeedType.Tag, key: string, ...values: string[]]
export type UnionFeed = [type: FeedType.Union, ...feeds: Feed[]]
### Time-filtered Feed
```typescript
const recentFeed: Feed = [
FeedType.CreatedAt,
{
since: Date.now() - 24 * 60 * 60 * 1000, // Last 24 hours
relative: ["since"]
}
]
export type Feed = /* union of all feed types */
```
### Complex Feed Composition
```typescript
const complexFeed: Feed = [
FeedType.Intersection,
[FeedType.Kind, 1], // Text notes
[FeedType.WOT, { min: 0.5 }], // Trusted authors
[
FeedType.Union,
[FeedType.Scope, Scope.Follows], // From follows
[FeedType.List, { addresses: ["list_id"] }] // Or from list
]
]
```
### DVM Feed with Mappings
```typescript
const dvmFeed: Feed = [
FeedType.DVM,
{
kind: 5300,
mappings: [
["p", [FeedType.Author]], // Map 'p' tags to authors
["t", [FeedType.Tag, "#t"]] // Map 't' tags to hashtags
]
}
]
```
This core module provides the foundation for building complex, type-safe feed definitions that can be executed by the [feed controller](/feeds/controller).