Event References

IEventRef names an event by id or by address. A nip19 note, nevent or naddr, a quote in content, and a tag pointing at an event all reduce to one, and relay selections such as seen and eventOutbox route on it. It is plain data, so an event or a literal like {id, relays} is an IEventRef.

Every field is optional and additive. A known pubkey lets the router reach the author's relays without finding the event. An id, or a kind, pubkey and identifier, lets it look the event up. relays are hints for that lookup and a last-resort fallback.

EventRef implements IEventRef and adds conversions and lookups that work whether it names an id or an address. Code takes an IEventRef and parses it with new EventRef(ref) where it needs those methods.

API

export type IEventRef = {
  id?: string
  pubkey?: string
  kind?: number
  identifier?: string
  relays?: string[]
}

export declare class EventRef implements IEventRef {
  readonly id?: string
  readonly pubkey?: string
  readonly kind?: number
  readonly identifier?: string
  readonly relays: string[]

  constructor(ref: IEventRef)

  // From an event already in hand, with the relays it was seen on; a replaceable one gets its identifier
  static fromEvent(event: TrustedEvent, relays?: string[]): EventRef

  // From a nip19 event or address pointer; an event pointer's `author` becomes `pubkey`
  static fromPointer(pointer: EventPointer | AddressPointer): EventRef

  static fromAddress(address: Address): EventRef

  // From an id or a `kind:pubkey:identifier` address
  static fromString(idOrAddress: string, relays?: string[]): EventRef

  // Two references to one event, pooling what each knows; the first wins where they disagree
  static merge(a: IEventRef, b: IEventRef): EventRef

  // From a note, nevent or naddr, with or without its nostr: prefix; undefined for anything else
  static fromNip19(entity: string): EventRef | undefined

  // The address, when the reference carries a kind, pubkey and identifier
  getAddress(): Address | undefined

  // The id when there is one, naming that version, and otherwise the address
  getIdOrAddress(): string | undefined

  // The address when there is one, naming whichever version is current; matches getIdOrAddress(event)
  getAddressOrId(): string | undefined

  // The id and the address, whichever it has; matches getIdAndAddress(event)
  getIdAndAddress(): string[]

  // Filters that load the event, or none when the reference names neither an id nor an address
  getFilters(): Filter[]

  // Its hints, the relays it was seen on, and its author's outbox
  getRelaySelections(): RelaySelection[]

  // An nevent when there is an id, and an naddr when there is only an address
  toNip19(): string | undefined
}

Examples

import {EventRef} from '@welshman/util'

// A quote parsed out of content
const ref = EventRef.fromPointer(parsed.value)

// Any IEventRef parses into one
const parent = new EventRef({id, pubkey, relays})

// Load it from wherever it is likely to be
const relays = await router.resolver.relays(ref.getRelaySelections())
const events = await network.load({filters: ref.getFilters(), relays})

// Look it up locally, whether it was named by id or by address
const idOrAddress = ref.getIdOrAddress()
const event = idOrAddress ? repository.getEvent(idOrAddress) : undefined

// An event is itself an IEventRef, so routing relative to one needs no conversion
const selections = [seen(reply)]