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

Update docs, tweak url based event derivation

Browse Source
This commit is contained in:
Jon Staab
2025-11-20 15:08:59 -08:00
parent 6d36f5a912
commit 2fec078a5b
12 changed files with 154 additions and 317 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/app/making-requests.md
+26 -18
View File
@@ -13,37 +13,45 @@ Welshman extends Nostr's base subscription model with intelligent caching, repos
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
## Indexed 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.
Create indexed stores with automatic loading using repository derivations and loader utilities:
```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
}
import {deriveItemsByKey, deriveItems, makeDeriveItem, makeLoadItem, getter} from "@welshman/store"
// Create indexed map from repository
const itemsByKey = deriveItemsByKey({
repository,
filters: [{kinds: [SOME_KIND]}],
eventToItem: event => transformEvent(event),
getKey: item => item.id
})
// Create array view
const items = deriveItems(itemsByKey)
// Create getter for accessing map
const getItemsByKey = getter(itemsByKey)
// Create loader
const loadItem = makeLoadItem(fetchItem, key => getItemsByKey().get(key))
// Create deriver with automatic loading
const deriveItem = makeDeriveItem(itemsByKey, loadItem)
```
### 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`.
Query events from the repository using `deriveEventsById` and `deriveEvents`:
```typescript
import {deriveEventsMapped} from "@welshman/store"
import {deriveEventsById, deriveEvents} from "@welshman/store"
export const notes = deriveEvents<TrustedEvent>(repository, {filters: [{kinds: [NOTE]}]})
const noteEventsById = deriveEventsById({repository, filters: [{kinds: [NOTE]}]})
export const notes = deriveEvents(noteEventsById)
```
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:
docs/store/collection.md
-71
View File
@@ -1,71 +0,0 @@
# Collection
Utilities for creating reactive collections with automatic loading, caching, and staleness management using Svelte stores.
## Functions
### collection(options)
Creates a reactive collection that automatically loads missing items and manages freshness.
**Options:**
- `name` - Collection name for freshness tracking
- `store` - Readable store containing array of items
- `getKey` - Function to extract unique key from items
- `load` - Async function to load missing items
**Returns:**
- `indexStore` - Derived store with items indexed by key
- `deriveItem(key, relays)` - Creates a derived store for a specific item
- `loadItem(key, relays)` - Manually loads an item
- `onItem(callback)` - Subscribe to individual item updates
### makeCachedLoader(options)
Creates a cached loader function with staleness checking and exponential backoff.
**Options:**
- `name` - Loader name for freshness tracking
- `indexStore` - Store containing indexed items
- `load` - Async function to load items
- `subscribers` - Array of item update subscribers
### Freshness Management
- `getFreshness(ns, key)` - Get last update timestamp for an item
- `setFreshnessImmediate(update)` - Immediately update freshness
- `setFreshnessThrottled(update)` - Throttled freshness updates
## Example
```typescript
import {writable} from 'svelte/store'
import {derived, readable} from "svelte/store"
import {readProfile, PROFILE, PublishedProfile} from "@welshman/util"
import {Repository} from "@welshman/net"
import {deriveEventsMapped, collection, withGetter} from "@welshman/store"
const repository = new Repository()
export const profiles = writable([])
export const {
indexStore: profilesByPubkey,
deriveItem: deriveProfile,
loadItem: loadProfile,
} = collection({
name: "profiles",
store: profiles,
getKey: profile => profile.event.pubkey,
load: (pubkey: string) => // Load the user's profile
})
// Get a reactive store for a specific profile
const hints = [/* optional relay hints to load from */]
const userProfile = deriveProfile("user-pubkey", hints)
// Subscribe to profile updates
userProfile.subscribe(profile => {
console.log("Profile updated:", profile)
})
```
docs/store/custom.md
-56
View File
@@ -1,56 +0,0 @@
# Custom Store
Utility for creating custom Svelte stores with start/stop lifecycle and optional throttling.
## Functions
### custom(start, options)
Creates a custom store that starts when first subscribed and stops when last subscriber unsubscribes.
**Parameters:**
- `start` - Function called when first subscriber is added. Receives a `set` function and should return an unsubscriber function
- `options` - Optional configuration object
**Options:**
- `throttle` - Throttle subscriber notifications (milliseconds)
- `onUpdate` - Callback function called when store value is set
**Returns:** WritableWithGetter store with `get()`, `set()`, `update()`, and `subscribe()` methods
## Example
```typescript
import {custom} from "@welshman/store"
// Create a store that tracks window width
const windowWidth = custom(
set => {
const updateWidth = () => set(window.innerWidth)
// Set initial value
updateWidth()
// Listen for resize events
window.addEventListener('resize', updateWidth)
// Return cleanup function
return () => window.removeEventListener('resize', updateWidth)
},
{
throttle: 100, // Throttle updates to every 100ms
onUpdate: (width) => console.log(`Window width: ${width}px`)
}
)
// Subscribe to changes
const unsubscribe = windowWidth.subscribe(width => {
console.log("Width changed:", width)
})
// Get current value
console.log("Current width:", windowWidth.get())
// Clean up
unsubscribe()
```
docs/store/getter.md
+10 -49
View File
@@ -1,55 +1,16 @@
# Getter
Utilities for adding synchronous `get()` methods to Svelte stores, allowing immediate value access without subscribing. Note that this has performance implications, since it will activate a subscription that will never get unsubscribed. Do not use this on stores that require complex calculations, or which are created and destroyed.
## Functions
### getter(store)
Creates a getter function that returns the current value of a store.
**Parameters:**
- `store` - Any readable Svelte store
**Returns:** Function that returns the current store value
### withGetter(store)
Enhances a store by adding a synchronous `get()` method.
**Parameters:**
- `store` - Readable or writable Svelte store
**Returns:** Store with added `get()` method
## Types
- `ReadableWithGetter<T>` - Readable store with `get()` method
- `WritableWithGetter<T>` - Writable store with `get()` method
## Example
Utility for creating optimized getter functions that adapt based on access patterns.
```typescript
import {writable, derived} from "svelte/store"
import {withGetter, getter} from "@welshman/store"
// Create optimized getter that switches to subscription when hot
getter<T>(store: Readable<T>, options?: {
threshold?: number // Calls per second before switching to subscription (default: 10)
}): () => T
// Create enhanced stores with getter methods
const count = withGetter(writable(0))
const doubled = withGetter(derived(count, $count => $count * 2))
// Access values synchronously without subscribing
console.log(count.get()) // 0
console.log(doubled.get()) // 0
// Update the store
count.set(5)
// Get updated values immediately
console.log(count.get()) // 5
console.log(doubled.get()) // 10
// Alternative: create getter function separately
const regularStore = writable(42)
const getValue = getter(regularStore)
console.log(getValue()) // 42
// Add .get() method to a store
withGetter<T>(store: Readable<T>): ReadableWithGetter<T>
withGetter<T>(store: Writable<T>): WritableWithGetter<T>
```
The `getter` function automatically switches between `get()` and subscription based on call frequency, optimizing performance for hot code paths.
docs/store/index.md
+5 -4
View File
@@ -16,15 +16,16 @@ A utility package providing welshman-specific svelte store functionality and uti
```typescript
import {Repository, NAMED_PEOPLE, TrustedEvent, PublishedList, readList} from '@welshman/util'
import {deriveEventsMapped} from '@welshman/store'
import {deriveItemsByKey} from '@welshman/store'
const repository = new Repository()
// Create a store that performantly maps matching events in the repository to List objects
const lists = deriveEventsMapped<PublishedList>(repository, {
// Create a reactive map of lists indexed by pubkey
const listsByPubkey = deriveItemsByKey<PublishedList>({
repository,
filters: [{kinds: [NAMED_PEOPLE]}],
eventToItem: (event: TrustedEvent) => (event.tags.length > 1 ? readList(event) : null),
itemToEvent: (list: PublishedList) => list.event,
getKey: (list: PublishedList) => list.event.pubkey,
})
```
docs/store/repository.md
+66 -38
View File
@@ -1,74 +1,102 @@
# Repository
Reactive Svelte stores for querying and mapping events from a Repository with automatic updates.
Reactive Svelte stores for querying events from a Repository with automatic updates.
## Functions
## Event Stores
### deriveEventsMapped(repository, options)
```typescript
// Derive map of events by ID
deriveEventsById(options: {
repository: Repository
filters: Filter[]
includeDeleted?: boolean
}): Readable<Map<string, TrustedEvent>>
Creates a reactive store that maps events to custom items and keeps them synchronized with repository updates.
// Convert events by ID to array
deriveEvents(eventsByIdStore: Readable<Map<string, TrustedEvent>>): Readable<TrustedEvent[]>
**Options:**
- `filters` - Array of Nostr filters to query events
- `eventToItem` - Function to transform events to items (can return Promise)
- `itemToEvent` - Function to extract the event from an item
- `throttle?` - Throttle updates (milliseconds, default: 0)
- `includeDeleted?` - Include deleted events (default: false)
// Sort events ascending by created_at
deriveEventsAsc(eventsStore: Readable<TrustedEvent[]>): Readable<TrustedEvent[]>
### deriveEvents(repository, options)
// Sort events descending by created_at
deriveEventsDesc(eventsStore: Readable<TrustedEvent[]>): Readable<TrustedEvent[]>
Creates a reactive store of events without transformation.
// Derive single event by ID or address
deriveEvent(repository: Repository, idOrAddress: string): Readable<TrustedEvent | undefined>
**Options:**
- `filters` - Array of Nostr filters
- `throttle?` - Throttle updates
- `includeDeleted?` - Include deleted events
// Track if event is deleted
deriveIsDeleted(repository: Repository, event: TrustedEvent): Readable<boolean>
```
### deriveEvent(repository, idOrAddress)
## Indexed Collections
Creates a reactive store for a single event by ID or address.
```typescript
// Create indexed map of items from repository events
deriveItemsByKey<T>(options: {
repository: Repository
filters: Filter[]
eventToItem: (event: TrustedEvent) => MaybeAsync<Maybe<T>>
getKey: (item: T) => string
includeDeleted?: boolean
}): Readable<Map<string, T>>
### deriveIsDeleted(repository, event)
// Convert itemsByKey map to array
deriveItems<T>(itemsByKeyStore: Readable<Map<string, T>>): Readable<T[]>
Creates a reactive store that tracks whether an event is deleted.
// Create function to derive single item by key
makeDeriveItem<T>(
itemsByKeyStore: Readable<Map<string, T>>,
onDerive?: (key: string, ...args: any[]) => void
): (key: string, ...args: any[]) => Readable<T | undefined>
### deriveIsDeletedByAddress(repository, event)
// Create cached loader with staleness checking and exponential backoff
makeLoadItem<T>(
loadItem: (key: string, ...args: any[]) => Promise<unknown>,
getItem: (key: string) => T | undefined,
options?: {getFetched?, setFetched?, timeout?}
): (key: string, ...args: any[]) => Promise<T | undefined>
Creates a reactive store that tracks whether an event is deleted by address.
// Create loader that always fetches fresh data
makeForceLoadItem<T>(
loadItem: (key: string, ...args: any[]) => Promise<unknown>,
getItem: (key: string) => T | undefined
): (key: string, ...args: any[]) => Promise<T | undefined>
// Optimized getter that switches to subscription when hot
getter<T>(store: Readable<T>, options?: {threshold?: number}): () => T
```
## Example
```typescript
import {Repository} from "@welshman/net"
import {deriveEventsMapped, deriveEvents} from "@welshman/store"
import {deriveEventsById, deriveEvents, deriveItemsByKey, deriveItems} from "@welshman/store"
import {readProfile, PROFILE} from "@welshman/util"
const repository = new Repository()
// Reactive store of text notes
const textNotes = deriveEvents(repository, {
filters: [{kinds: [1], limit: 100}],
throttle: 100
const noteEventsById = deriveEventsById({
repository,
filters: [{kinds: [1], limit: 100}]
})
const notes = deriveEvents(noteEventsById)
// Reactive store of profiles mapped to custom objects
const profiles = deriveEventsMapped(repository, {
// Reactive store of profiles indexed by pubkey
const profilesByPubkey = deriveItemsByKey({
repository,
filters: [{kinds: [PROFILE]}],
eventToItem: event => readProfile(event),
itemToEvent: profile => profile.event,
includeDeleted: false
getKey: profile => profile.event.pubkey
})
const profiles = deriveItems(profilesByPubkey)
// Subscribe to updates
textNotes.subscribe(notes => {
console.log(`Found ${notes.length} text notes`)
notes.subscribe($notes => {
console.log(`Found ${$notes.length} text notes`)
})
profiles.subscribe(profiles => {
console.log(`Found ${profiles.length} profiles`)
profiles.subscribe($profiles => {
console.log(`Found ${$profiles.length} profiles`)
})
// Add some events to the repository
repository.publish(someTextNoteEvent)
repository.publish(someProfileEvent)
```