applesauce-loaders 4.0.0 → 5.0.0

package/README.md

@@ -94,6 +94,51 @@ eventLoader({
 });
 ```
 
+## Unified Event Loader
+
+The Unified Event Loader is a single loader that can handle both `EventPointer` and `AddressPointer` types. It automatically routes to the appropriate loader (`createEventLoader` for events by ID, `createAddressLoader` for addressable/replaceable events) based on the pointer type.
+
+This is the recommended approach when setting up loaders for an EventStore, as it provides a single loader that works with the unified `eventLoader` property.
+
+```ts
+import { createUnifiedEventLoader, createEventLoaderForStore } from "applesauce-loaders/loaders";
+import { EventStore } from "applesauce-core";
+import { RelayPool } from "applesauce-relay";
+
+const eventStore = new EventStore();
+const pool = new RelayPool();
+
+// Option 1: Create and assign manually
+const unifiedLoader = createUnifiedEventLoader(pool, {
+  eventStore,
+  bufferTime: 1000,
+  followRelayHints: true,
+  extraRelays: ["wss://relay.example.com"],
+  lookupRelays: ["wss://purplepag.es", "wss://index.hzrd149.com"],
+});
+
+eventStore.eventLoader = unifiedLoader;
+
+// Option 2: Use the convenience function (recommended)
+createEventLoaderForStore(eventStore, pool, {
+  bufferTime: 1000,
+  followRelayHints: true,
+  extraRelays: ["wss://relay.example.com"],
+  lookupRelays: ["wss://purplepag.es", "wss://index.hzrd149.com"],
+});
+
+// Now the event store can load both events by ID and addressable events
+eventStore.event({ id: "event_id" }).subscribe((event) => {
+  console.log("Loaded event:", event);
+});
+
+eventStore.replaceable({ kind: 0, pubkey: "pubkey" }).subscribe((profile) => {
+  console.log("Loaded profile:", profile);
+});
+```
+
+The unified loader accepts all options from both `EventPointerLoaderOptions` and `AddressLoaderOptions`, making it easy to configure both types of loading in one place.
+
 ## Timeline Loader
 
 The Timeline Loader is designed for fetching paginated Nostr events in chronological order. It maintains state between calls, allowing you to efficiently load timeline events in blocks until you reach a specific timestamp or exhaust available events.
@@ -181,6 +226,12 @@ All loaders accept these common configuration options:
 - `followRelayHints`: Whether to follow relay hints (default true)
 - `extraRelays`: An array of relays to always fetch from
 
+### Unified Event Loader Options
+
+The unified event loader accepts all options from both Event Loader and Address Loader options, plus:
+
+- `lookupRelays`: Fallback lookup relays to check when event can't be found (from Address Loader)
+
 ### Timeline Loader Options
 
 - `limit`: Maximum number of events to request per filter

package/dist/helpers/address-pointer.d.ts

@@ -1,6 +1,5 @@
-import { AddressPointerWithoutD } from "applesauce-core/helpers";
-import { Filter } from "nostr-tools";
-import { AddressPointer } from "nostr-tools/nip19";
+import { Filter } from "applesauce-core/helpers/filter";
+import { AddressPointer, AddressPointerWithoutD } from "applesauce-core/helpers/pointers";
 /** Converts an array of address pointers to a filter */
 export declare function createFilterFromAddressPointers(pointers: AddressPointerWithoutD[] | AddressPointer[]): Filter;
 /** Takes a set of address pointers, groups them, then returns filters for the groups */

package/dist/helpers/address-pointer.js

@@ -1,11 +1,11 @@
-import { isAddressableKind, isReplaceableKind } from "nostr-tools/kinds";
+import { isAddressableKind, isReplaceableKind } from "applesauce-core/helpers/event";
 import { unique } from "./array.js";
 /** Converts an array of address pointers to a filter */
 export function createFilterFromAddressPointers(pointers) {
     const filter = {};
     filter.kinds = unique(pointers.map((p) => p.kind));
     filter.authors = unique(pointers.map((p) => p.pubkey));
-    const identifiers = unique(pointers.map((p) => p.identifier).filter((d) => !!d));
+    const identifiers = unique(pointers.map((p) => p.identifier).filter((d) => d !== undefined));
     if (identifiers.length > 0)
         filter["#d"] = identifiers;
     return filter;
@@ -29,7 +29,7 @@ export function createFiltersFromAddressPointers(pointers) {
 /** Checks if a relay will understand an address pointer */
 export function isLoadableAddressPointer(pointer) {
     if (isAddressableKind(pointer.kind))
-        return !!pointer.identifier;
+        return pointer.identifier !== undefined;
     else
         return isReplaceableKind(pointer.kind);
 }

package/dist/helpers/cache.d.ts

@@ -1,5 +1,6 @@
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { Filter } from "applesauce-core/helpers/filter";
 import { Observable } from "rxjs";
-import { Filter, NostrEvent } from "nostr-tools";
 import { CacheRequest } from "../types.js";
 /** Calls the cache request and converts the reponse into an observable */
 export declare function unwrapCacheRequest(request: CacheRequest, filters: Filter[]): Observable<NostrEvent>;

package/dist/helpers/cache.js

@@ -1,18 +1,24 @@
+import { markFromCache } from "applesauce-core/helpers/event";
 import { from, isObservable, of, switchMap, tap } from "rxjs";
-import { markFromCache } from "applesauce-core/helpers";
 /** Calls the cache request and converts the reponse into an observable */
 export function unwrapCacheRequest(request, filters) {
     const result = request(filters);
     if (isObservable(result))
         return result;
-    else if (result instanceof Promise)
-        return from(result).pipe(switchMap((v) => (Array.isArray(v) ? from(v) : of(v))));
-    else if (Array.isArray(result))
+    else if (result instanceof Promise) {
+        return from(result).pipe(switchMap((v) => (Array.isArray(v) ? from(v) : of(v))), tap((e) => markFromCache(e)));
+    }
+    else if (Array.isArray(result)) {
+        for (const event of result)
+            markFromCache(event);
         return from(result);
-    else
+    }
+    else {
+        markFromCache(result);
         return of(result);
+    }
 }
 /** Calls a cache request method with filters and marks all returned events as being from the cache */
 export function makeCacheRequest(request, filters) {
-    return unwrapCacheRequest(request, filters).pipe(tap((e) => markFromCache(e)));
+    return unwrapCacheRequest(request, filters);
 }

package/dist/helpers/upstream.d.ts

@@ -1,6 +1,7 @@
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { Filter } from "applesauce-core/helpers/filter";
 import { Observable } from "rxjs";
 import { NostrRequest, UpstreamPool } from "../types.js";
-import { Filter, NostrEvent } from "nostr-tools";
 /** Makes a nostr request on the upstream pool */
 export declare function makeUpstreamRequest(pool: UpstreamPool, relays: string[], filters: Filter[]): Observable<NostrEvent>;
 /** Wraps an upstream pool and returns a NostrRequest */

package/dist/loaders/address-loader.d.ts

@@ -1,5 +1,5 @@
-import { mapEventsToStore } from "applesauce-core";
-import { NostrEvent } from "nostr-tools";
+import { filterDuplicateEvents } from "applesauce-core";
+import { NostrEvent } from "applesauce-core/helpers/event";
 import { Observable } from "rxjs";
 import { CacheRequest, NostrRequest, UpstreamPool } from "../types.js";
 export type LoadableAddressPointer = {
@@ -33,8 +33,8 @@ export type AddressLoaderOptions = Partial<{
     bufferTime: number;
     /** Max buffer size ( default 200 ) */
     bufferSize: number;
-    /** An event store used to deduplicate events */
-    eventStore?: Parameters<typeof mapEventsToStore>[0];
+    /** An event store used to deduplicate events. Set to null to disable deduplication */
+    eventStore?: Parameters<typeof filterDuplicateEvents>[0] | null;
     /** A method used to load events from a local cache */
     cacheRequest: CacheRequest;
     /** Whether to follow relay hints ( default true ) */

package/dist/loaders/address-loader.js

@@ -1,6 +1,6 @@
-import { mapEventsToStore } from "applesauce-core";
+import { EventMemory, filterDuplicateEvents } from "applesauce-core";
 import { createReplaceableAddress, getReplaceableAddress, getReplaceableIdentifier, isReplaceable, mergeRelaySets, } from "applesauce-core/helpers";
-import { bufferTime, catchError, EMPTY } from "rxjs";
+import { bufferTime, catchError, EMPTY, identity } from "rxjs";
 import { createFiltersFromAddressPointers, isLoadableAddressPointer } from "../helpers/address-pointer.js";
 import { makeCacheRequest } from "../helpers/cache.js";
 import { batchLoader, unwrap } from "../helpers/loaders.js";
@@ -115,7 +115,7 @@ export function createAddressLoader(pool, opts) {
     // Filter resutls based on requests
     (pointer, event) => event.kind === pointer.kind &&
         event.pubkey === pointer.pubkey &&
-        (pointer.identifier ? getReplaceableIdentifier(event) === pointer.identifier : true), 
-    // Pass all events through the store if defined
-    opts?.eventStore && mapEventsToStore(opts.eventStore));
+        (pointer.identifier !== undefined ? getReplaceableIdentifier(event) === pointer.identifier : true), 
+    // Pass all events through the store if provided, or use EventMemory for deduplication by default
+    opts?.eventStore === null ? identity : filterDuplicateEvents(opts?.eventStore || new EventMemory()));
 }

package/dist/loaders/event-loader.d.ts

@@ -1,6 +1,6 @@
-import { mapEventsToStore } from "applesauce-core";
-import { NostrEvent } from "nostr-tools";
-import { EventPointer } from "nostr-tools/nip19";
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { EventPointer } from "applesauce-core/helpers/pointers";
+import { filterDuplicateEvents } from "applesauce-core/observable";
 import { Observable } from "rxjs";
 import { CacheRequest, NostrRequest, UpstreamPool } from "../types.js";
 export type LoadableEventPointer = EventPointer & {
@@ -23,8 +23,8 @@ export type EventPointerLoaderOptions = Partial<{
     bufferTime: number;
     /** Max buffer size ( default 200 ) */
     bufferSize: number;
-    /** An event store used to deduplicate events */
-    eventStore?: Parameters<typeof mapEventsToStore>[0];
+    /** An event store used to deduplicate events. Set to null to disable deduplication */
+    eventStore?: Parameters<typeof filterDuplicateEvents>[0] | null;
     /** A method used to load events from a local cache */
     cacheRequest: CacheRequest;
     /** Whether to follow relay hints ( default true ) */

package/dist/loaders/event-loader.js

@@ -1,5 +1,6 @@
-import { mapEventsToStore } from "applesauce-core";
-import { bufferTime, catchError, EMPTY, merge, tap } from "rxjs";
+import { EventMemory } from "applesauce-core/event-store";
+import { filterDuplicateEvents } from "applesauce-core/observable";
+import { bufferTime, catchError, EMPTY, identity, merge, tap } from "rxjs";
 import { makeCacheRequest } from "../helpers/cache.js";
 import { consolidateEventPointers } from "../helpers/event-pointer.js";
 import { batchLoader, unwrap } from "../helpers/loaders.js";
@@ -85,6 +86,6 @@ export function createEventLoader(pool, opts) {
     opts?.extraRelays ? relaysEventsLoader(request, opts.extraRelays) : undefined), 
     // Filter resutls based on requests
     (pointer, event) => event.id === pointer.id, 
-    // Pass all events through the store if defined
-    opts?.eventStore && mapEventsToStore(opts.eventStore));
+    // Pass all events through the store if provided, or use EventMemory for deduplication by default
+    opts?.eventStore === null ? identity : filterDuplicateEvents(opts?.eventStore || new EventMemory()));
 }

package/dist/loaders/index.d.ts

@@ -5,5 +5,6 @@ export * from "./reactions-loader.js";
 export * from "./social-graph.js";
 export * from "./tag-value-loader.js";
 export * from "./timeline-loader.js";
+export * from "./unified-event-loader.js";
 export * from "./user-lists-loader.js";
 export * from "./zaps-loader.js";

package/dist/loaders/index.js

@@ -5,5 +5,6 @@ export * from "./reactions-loader.js";
 export * from "./social-graph.js";
 export * from "./tag-value-loader.js";
 export * from "./timeline-loader.js";
+export * from "./unified-event-loader.js";
 export * from "./user-lists-loader.js";
 export * from "./zaps-loader.js";

package/dist/loaders/reactions-loader.d.ts

@@ -1,4 +1,4 @@
-import { NostrEvent } from "nostr-tools";
+import { NostrEvent } from "applesauce-core/helpers/event";
 import { Observable } from "rxjs";
 import { UpstreamPool } from "../types.js";
 import { TagValueLoaderOptions } from "./tag-value-loader.js";

package/dist/loaders/reactions-loader.js

@@ -1,5 +1,6 @@
-import { getReplaceableAddress, getSeenRelays, isReplaceable, mergeRelaySets } from "applesauce-core/helpers";
-import { kinds } from "nostr-tools";
+import { getReplaceableAddress, isReplaceable, kinds } from "applesauce-core/helpers/event";
+import { getSeenRelays, mergeRelaySets } from "applesauce-core/helpers/relays";
+import { EMPTY } from "rxjs";
 import { wrapUpstreamPool } from "../helpers/upstream.js";
 import { createTagValueLoader } from "./tag-value-loader.js";
 /** Creates a loader that loads reaction events for a given event */
@@ -11,8 +12,14 @@ export function createReactionsLoader(pool, opts) {
     return (event, relays) => {
         if (opts?.useSeenRelays ?? true)
             relays = mergeRelaySets(relays, getSeenRelays(event));
-        return isReplaceable(event.kind)
-            ? addressableLoader({ value: getReplaceableAddress(event), relays })
-            : eventLoader({ value: event.id, relays });
+        if (isReplaceable(event.kind)) {
+            const address = getReplaceableAddress(event);
+            if (!address)
+                return EMPTY;
+            return addressableLoader({ value: address, relays });
+        }
+        else {
+            return eventLoader({ value: event.id, relays });
+        }
     };
 }

package/dist/loaders/social-graph.d.ts

@@ -1,6 +1,6 @@
-import { mapEventsToStore } from "applesauce-core";
-import { NostrEvent } from "nostr-tools";
-import { ProfilePointer } from "nostr-tools/nip19";
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { ProfilePointer } from "applesauce-core/helpers/pointers";
+import { mapEventsToStore } from "applesauce-core/observable";
 import { Observable } from "rxjs";
 import { AddressPointerLoader } from "./address-loader.js";
 /** A loader that loads the social graph of a user out to a set distance */

package/dist/loaders/social-graph.js

@@ -1,6 +1,7 @@
-import { mapEventsToStore } from "applesauce-core";
-import { getProfilePointersFromList, mergeRelaySets } from "applesauce-core/helpers";
-import { kinds } from "nostr-tools";
+import { getPublicContacts } from "applesauce-core/helpers";
+import { kinds } from "applesauce-core/helpers/event";
+import { mergeRelaySets } from "applesauce-core/helpers/relays";
+import { mapEventsToStore } from "applesauce-core/observable";
 import { firstValueFrom, identity, isObservable, lastValueFrom, toArray } from "rxjs";
 import { wrapGeneratorFunction } from "../operators/generator.js";
 /** Create a social graph loader */
@@ -30,7 +31,7 @@ export function createSocialGraphLoader(addressLoader, opts) {
                 toArray()));
                 if (events.length === 0)
                     return;
-                const contacts = getProfilePointersFromList(events[events.length - 1]);
+                const contacts = getPublicContacts(events[events.length - 1]);
                 // if the distance is greater than 0, add the contacts to the queue
                 if (pointer.distance > 0) {
                     for (const contact of contacts) {

package/dist/loaders/tag-value-loader.d.ts

@@ -1,5 +1,5 @@
-import { mapEventsToStore } from "applesauce-core";
-import { NostrEvent } from "nostr-tools";
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { filterDuplicateEvents } from "applesauce-core/observable";
 import { Observable } from "rxjs";
 import { CacheRequest, NostrRequest, UpstreamPool } from "../types.js";
 export type TagValuePointer = {
@@ -25,8 +25,8 @@ export type TagValueLoaderOptions = {
     cacheRequest?: CacheRequest;
     /** An array of relays to always fetch from */
     extraRelays?: string[] | Observable<string[]>;
-    /** An event store used to deduplicate events */
-    eventStore?: Parameters<typeof mapEventsToStore>[0];
+    /** An event store used to deduplicate events. Set to null to disable deduplication */
+    eventStore?: Parameters<typeof filterDuplicateEvents>[0] | null;
 };
 export type TagValueLoader = (pointer: TagValuePointer) => Observable<NostrEvent>;
 /** Creates a loader that gets tag values from the cache */

package/dist/loaders/tag-value-loader.js

@@ -1,6 +1,7 @@
-import { mapEventsToStore } from "applesauce-core";
-import { mergeRelaySets } from "applesauce-core/helpers";
-import { bufferTime, EMPTY, merge } from "rxjs";
+import { EventMemory } from "applesauce-core/event-store";
+import { mergeRelaySets } from "applesauce-core/helpers/relays";
+import { filterDuplicateEvents } from "applesauce-core/observable";
+import { bufferTime, EMPTY, identity, merge } from "rxjs";
 import { unique } from "../helpers/array.js";
 import { makeCacheRequest } from "../helpers/cache.js";
 import { batchLoader, unwrap } from "../helpers/loaders.js";
@@ -70,6 +71,6 @@ export function createTagValueLoader(pool, tagName, opts) {
     }, 
     // Filter results based on requests
     (pointer, event) => event.tags.some((tag) => tag[0] === tagName && tag[1] === pointer.value), 
-    // Pass all events through the store if defined
-    opts?.eventStore && mapEventsToStore(opts?.eventStore));
+    // Pass all events through the store if provided, or use EventMemory for deduplication by default
+    opts?.eventStore === null ? identity : filterDuplicateEvents(opts?.eventStore || new EventMemory()));
 }

package/dist/loaders/timeline-loader.d.ts

@@ -1,24 +1,75 @@
-import { mapEventsToStore } from "applesauce-core";
-import { NostrEvent } from "nostr-tools";
-import { Observable } from "rxjs";
-import { CacheRequest, FilterRequest, NostrRequest, TimelessFilter, UpstreamPool } from "../types.js";
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { Filter } from "applesauce-core/helpers/filter";
+import { ProfilePointer } from "applesauce-core/helpers/pointers";
+import { FilterMap, OutboxMap } from "applesauce-core/helpers/relay-selection";
+import { mapEventsToStore } from "applesauce-core/observable";
+import { Observable, OperatorFunction } from "rxjs";
+import { CacheRequest, TimelessFilter, UpstreamPool } from "../types.js";
 /** A loader that optionally takes a timestamp to load till and returns a stream of events */
-export type TimelineLoader = (since?: number) => Observable<NostrEvent>;
+export type TimelineLoader = (since?: number | TimelineWindow) => Observable<NostrEvent>;
+/**
+ * The current `since` value of the timeline loader
+ * `undefined` is used to initialize the loader to "now"
+ * -Infinity (for since) and Infinity (for until) should be used to force loading the next block of events
+ */
+export type TimelineWindow = {
+    since?: number;
+    until?: number;
+};
 /** Common options for timeline loaders */
 export type CommonTimelineLoaderOptions = Partial<{
     limit: number;
+    /** Logger to extend */
+    logger?: debug.Debugger;
 }>;
+/**
+ * Watches for changes in the window and loads blocks of events going backward
+ * NOTE: this operator is stateful
+ */
+export declare function loadBackwardBlocks(request: (until?: number) => Observable<NostrEvent>, opts?: CommonTimelineLoaderOptions): OperatorFunction<TimelineWindow, NostrEvent>;
+/**
+ * Watches for changes in the window and loads blocks of events going forward
+ * NOTE: this operator is stateful
+ */
+export declare function loadForwardBlocks(request: (since?: number) => Observable<NostrEvent>, opts?: CommonTimelineLoaderOptions): OperatorFunction<TimelineWindow, NostrEvent>;
 /** A loader that loads blocks of events until none are returned or the since timestamp is reached */
-export declare function filterBlockLoader(request: FilterRequest, filters: TimelessFilter[], opts?: CommonTimelineLoaderOptions): TimelineLoader;
-/** Creates a loader that loads a timeline from a cache */
-export declare function cacheTimelineLoader(request: CacheRequest, filters: TimelessFilter[], opts?: CommonTimelineLoaderOptions): TimelineLoader;
-/** Creates a timeline loader that loads the same filters from multiple relays */
-export declare function relaysTimelineLoader(request: NostrRequest, relays: string[], filters: TimelessFilter[], opts?: CommonTimelineLoaderOptions): TimelineLoader;
+export declare function loadBlocksForTimelineWindow(request: (base: Filter) => Observable<NostrEvent>, opts?: CommonTimelineLoaderOptions): OperatorFunction<TimelineWindow, NostrEvent>;
+/** Loads timeline blocs from cache using a cache request */
+export declare function loadBlocksFromCache(request: CacheRequest, filters: TimelessFilter[] | TimelessFilter, opts?: CommonTimelineLoaderOptions): OperatorFunction<TimelineWindow, NostrEvent>;
+/** Loads timeline blocs from relays using a pool or request method */
+export declare function loadBlocksFromRelays(pool: UpstreamPool, relays: string[], filters: TimelessFilter[] | TimelessFilter, opts?: CommonTimelineLoaderOptions): OperatorFunction<TimelineWindow, NostrEvent>;
+/** Loads timeline blocs from relay set using a pool or request method */
+export declare function loadBlocksFromRelay(pool: UpstreamPool, relay: string, filters: TimelessFilter[] | TimelessFilter, opts?: CommonTimelineLoaderOptions): OperatorFunction<TimelineWindow, NostrEvent>;
+/** Loads timeline blocks from a map of relays and filters */
+export declare function loadBlocksFromFilterMap(pool: UpstreamPool, relayMap: FilterMap | Observable<FilterMap>, opts?: CommonTimelineLoaderOptions): OperatorFunction<TimelineWindow, NostrEvent>;
+/** Loads timeline blocks from an {@link OutboxMap} and {@link Filter} or a function that projects users to a filter */
+export declare function loadBlocksFromOutboxMap(pool: UpstreamPool, outboxes: OutboxMap | Observable<OutboxMap>, filter: TimelessFilter | ((users: ProfilePointer[]) => TimelessFilter | TimelessFilter[]), opts?: CommonTimelineLoaderOptions): OperatorFunction<TimelineWindow, NostrEvent>;
+/** Loads timeline blocks from a {@link CacheRequest} using a {@link OutboxMap} and filters */
+export declare function loadBlocksFromOutboxMapCache(cache: CacheRequest, outboxes: OutboxMap | Observable<OutboxMap>, filter: TimelessFilter | ((users: ProfilePointer[]) => TimelessFilter | TimelessFilter[]), opts?: CommonTimelineLoaderOptions): OperatorFunction<TimelineWindow, NostrEvent>;
+/** Options for the create timeline loader methods */
 export type TimelineLoaderOptions = Partial<{
     /** A method used to load the timeline from the cache */
     cache: CacheRequest;
     /** An event store to pass all the events to */
     eventStore?: Parameters<typeof mapEventsToStore>[0];
 }> & CommonTimelineLoaderOptions;
-/** A common timeline loader that takes an array of relays and a cache method */
+/** @deprecated Use the {@link loadBlocksFromCache} operator instead */
+export declare function cacheTimelineLoader(request: CacheRequest, filters: TimelessFilter[] | TimelessFilter, opts?: CommonTimelineLoaderOptions): TimelineLoader;
+/** @deprecated Use the {@link createTimelineLoader} operator instead */
+export declare function relaysTimelineLoader(pool: UpstreamPool, relays: string[], filters: TimelessFilter[] | TimelessFilter, opts?: CommonTimelineLoaderOptions): TimelineLoader;
+/**
+ * Creates a {@link TimelineLoader} that loads events from multiple relays and a cache
+ * @param pool - The upstream pool to use
+ * @param relays - The relays to load from
+ * @param filters - The filters to use
+ * @param opts - The options for the timeline loader
+ */
 export declare function createTimelineLoader(pool: UpstreamPool, relays: string[], filters: TimelessFilter[] | TimelessFilter, opts?: TimelineLoaderOptions): TimelineLoader;
+/**
+ * Creates a {@link TimelineLoader} that loads events for a {@link OutboxMap} or an observable of {@link OutboxMap}
+ * @param pool - The upstream pool to use
+ * @param outboxMap - An {@link OutboxMap} or an observable of {@link OutboxMap}
+ * @param filter - A function to create filters for a set of users
+ * @param opts - The options for the timeline loader
+ */
+export declare function createOutboxTimelineLoader(pool: UpstreamPool, outboxes: OutboxMap | Observable<OutboxMap>, filter: TimelessFilter | ((users: ProfilePointer[]) => TimelessFilter | TimelessFilter[]), opts?: TimelineLoaderOptions): TimelineLoader;

package/dist/loaders/timeline-loader.js

@@ -1,50 +1,282 @@
-import { mapEventsToStore } from "applesauce-core";
-import { EMPTY, finalize, identity, merge, tap } from "rxjs";
+import { logger as baseLogger } from "applesauce-core";
+import { EventMemory } from "applesauce-core/event-store";
+import { isFilterEqual, mergeFilters } from "applesauce-core/helpers/filter";
+import { createFilterMap } from "applesauce-core/helpers/relay-selection";
+import { filterDuplicateEvents } from "applesauce-core/observable";
+import { nanoid } from "nanoid";
+import { BehaviorSubject, distinctUntilChanged, EMPTY, filter, finalize, identity, isObservable, map, merge, mergeMap, Observable, of, share, switchMap, tap, } from "rxjs";
 import { makeCacheRequest } from "../helpers/cache.js";
 import { wrapUpstreamPool } from "../helpers/upstream.js";
-/** A loader that loads blocks of events until none are returned or the since timestamp is reached */
-export function filterBlockLoader(request, filters, opts) {
-    let cursor = Infinity;
-    let complete = false;
-    return (since) => {
-        if (complete)
-            return EMPTY;
-        if (since !== undefined && cursor <= since)
-            return EMPTY;
-        // Keep loading blocks until none are returned or an event is found that is ealier then the new cursor
-        const withTime = filters.map((filter) => ({
-            ...filter,
-            limit: filter.limit || opts?.limit,
-            until: cursor !== Infinity ? cursor : undefined,
+/**
+ * Watches for changes in the window and loads blocks of events going backward
+ * NOTE: this operator is stateful
+ */
+export function loadBackwardBlocks(request, opts) {
+    return (source) => {
+        const log = opts?.logger?.extend("backward").extend(nanoid(8));
+        let cursor = undefined;
+        let loading = false;
+        let complete = false;
+        return source.pipe(filter(({ since, until }) => {
+            // Once complete, prevent further requests
+            if (complete)
+                return false;
+            // If max is unset, initialize to until
+            if (cursor === undefined && until !== undefined && Number.isFinite(until))
+                cursor = until;
+            // Skip loads if since is still in range
+            if (
+            // Ignore undefined since values
+            since === undefined ||
+                // If number is finite and in the loaded range, skip
+                (Number.isFinite(since) && cursor !== undefined && since <= cursor))
+                return false;
+            // Don't load blocks in parallel
+            if (loading)
+                return false;
+            return true;
+        }), 
+        // NOTE: use mergeMap here to ensure old requests continue to load
+        mergeMap(() => {
+            // Set loading lock
+            loading = true;
+            // Count returned events so complete set
+            let count = 0;
+            log?.(`Loading block since:${cursor}`);
+            // Request the next block of events
+            return request(cursor).pipe(tap((event) => {
+                count++;
+                // Track the minimum created_at seen from the events
+                cursor = Math.min(event.created_at, cursor ?? Infinity);
+            }), finalize(() => {
+                loading = false;
+                complete = count === 0;
+                log?.(`Found ${count} events`);
+                if (complete)
+                    log?.("Complete");
+            }));
         }));
-        let count = 0;
-        // Load the next block of events
-        return request(withTime).pipe(tap((event) => {
-            // Update the cursor to the oldest event
-            cursor = Math.min(event.created_at - 1, cursor);
-            count++;
-        }), finalize(() => {
-            // Set the loader to complete if no events are returned
-            if (count === 0)
-                complete = true;
+    };
+}
+/**
+ * Watches for changes in the window and loads blocks of events going forward
+ * NOTE: this operator is stateful
+ */
+export function loadForwardBlocks(request, opts) {
+    return (source) => {
+        const log = opts?.logger?.extend("forward").extend(nanoid(8));
+        let cursor = undefined;
+        let loading = false;
+        let complete = false;
+        return source.pipe(filter(({ since, until }) => {
+            // Once complete, prevent further requests
+            if (complete)
+                return false;
+            // If min is unset, initialize to since
+            if (cursor === undefined && since !== undefined && Number.isFinite(since))
+                cursor = since;
+            // Skip loads if until is still in range
+            if (
+            // Ignore undefined until values
+            until === undefined ||
+                // If number is finite and in the loaded range, skip
+                (Number.isFinite(until) && cursor !== undefined && until <= cursor))
+                return false;
+            // Don't load blocks in parallel
+            if (loading)
+                return false;
+            return true;
+        }), 
+        // NOTE: use mergeMap here to ensure old requests continue to load
+        mergeMap(() => {
+            // Set loading lock
+            loading = true;
+            // Count returned events so complete set
+            let count = 0;
+            log?.(`Loading block until:${cursor}`);
+            // Request the next block of events
+            return request(cursor).pipe(tap((event) => {
+                count++;
+                // Track the maximum created_at seen from the events
+                cursor = Math.max(event.created_at, cursor ?? -Infinity);
+            }), finalize(() => {
+                loading = false;
+                complete = count === 0;
+                log?.(`Found ${count} events`);
+                if (complete)
+                    log?.("Complete");
+            }));
         }));
     };
 }
-/** Creates a loader that loads a timeline from a cache */
-export function cacheTimelineLoader(request, filters, opts) {
-    return filterBlockLoader((filters) => makeCacheRequest(request, filters), filters, opts);
+/** A loader that loads blocks of events until none are returned or the since timestamp is reached */
+export function loadBlocksForTimelineWindow(request, opts) {
+    return (source) => merge(source.pipe(loadBackwardBlocks((until) => request({ until }), opts)), source.pipe(loadForwardBlocks((since) => request({ since }), opts)));
 }
-/** Creates a timeline loader that loads the same filters from multiple relays */
-export function relaysTimelineLoader(request, relays, filters, opts) {
-    const loaders = relays.map((relay) => filterBlockLoader((f) => request([relay], f), filters, opts));
-    return (since) => merge(...loaders.map((l) => l(since)));
+/** Loads timeline blocs from cache using a cache request */
+export function loadBlocksFromCache(request, filters, opts) {
+    if (!Array.isArray(filters))
+        filters = [filters];
+    const logger = opts?.logger?.extend("cache");
+    const loader = (base) => makeCacheRequest(request, 
+    // Create filters from filters, base, and optional limit
+    filters.map((f) => (opts?.limit ? mergeFilters(f, base, { limit: opts.limit }) : mergeFilters(f, base))));
+    return (source) => source.pipe(loadBlocksForTimelineWindow(loader, { ...opts, logger }));
 }
-/** A common timeline loader that takes an array of relays and a cache method */
-export function createTimelineLoader(pool, relays, filters, opts) {
+/** Loads timeline blocs from relays using a pool or request method */
+export function loadBlocksFromRelays(pool, relays, filters, opts) {
+    if (!Array.isArray(filters))
+        filters = [filters];
+    const logger = opts?.logger?.extend("relays");
+    const request = wrapUpstreamPool(pool);
+    const loader = (base) => request(relays, 
+    // Create filters from filters, base, and optional limit
+    filters.map((f) => (opts?.limit ? mergeFilters(f, base, { limit: opts.limit }) : mergeFilters(f, base))));
+    return (source) => source.pipe(loadBlocksForTimelineWindow(loader, { ...opts, logger }));
+}
+/** Loads timeline blocs from relay set using a pool or request method */
+export function loadBlocksFromRelay(pool, relay, filters, opts) {
     if (!Array.isArray(filters))
         filters = [filters];
+    const logger = opts?.logger?.extend(relay);
     const request = wrapUpstreamPool(pool);
-    const cacheLoader = opts?.cache && cacheTimelineLoader(opts.cache, filters, opts);
-    const relayLoader = relaysTimelineLoader(request, relays, filters, opts);
-    return (since) => merge(cacheLoader?.(since) ?? EMPTY, relayLoader?.(since)).pipe(opts?.eventStore ? mapEventsToStore(opts.eventStore) : identity);
+    const loader = (base) => request([relay], 
+    // Create filters from filters, base, and optional limit
+    filters.map((f) => (opts?.limit ? mergeFilters(f, base, { limit: opts.limit }) : mergeFilters(f, base))));
+    return (source) => source.pipe(loadBlocksForTimelineWindow(loader, { ...opts, logger }));
+}
+/** Loads timeline blocks from a map of relays and filters */
+export function loadBlocksFromFilterMap(pool, relayMap, opts) {
+    return (source) => {
+        const map$ = isObservable(relayMap) ? relayMap : of(relayMap);
+        const cache = new Map();
+        const loaders$ = map$.pipe(map((relayMap) => Object.entries(relayMap).map(([relay, filters]) => {
+            const existing = cache.get(relay);
+            if (existing && isFilterEqual(existing.filters, filters))
+                return existing.loader;
+            // Create a new loader for this relay + filter set
+            const loader = source.pipe(loadBlocksFromRelay(pool, relay, filters, opts));
+            cache.set(relay, { filters, loader });
+            return loader;
+        })));
+        return loaders$.pipe(switchMap((loaders) => merge(...loaders)));
+    };
+}
+/** Loads timeline blocks from an {@link OutboxMap} and {@link Filter} or a function that projects users to a filter */
+export function loadBlocksFromOutboxMap(pool, outboxes, filter, opts) {
+    const outboxes$ = isObservable(outboxes) ? outboxes : of(outboxes);
+    // Project outbox map to filter map
+    const filterMap$ = outboxes$.pipe(map((outboxes) => {
+        // Filter is a dynamic method that returns a filter
+        if (typeof filter === "function")
+            return Object.fromEntries(Object.entries(outboxes).map(([relay, users]) => [relay, filter(users)]));
+        // Filter is just a filter
+        return createFilterMap(outboxes, filter);
+    }));
+    // Load blocks from the filter map
+    return loadBlocksFromFilterMap(pool, filterMap$, opts);
+}
+/** Loads timeline blocks from a {@link CacheRequest} using a {@link OutboxMap} and filters */
+export function loadBlocksFromOutboxMapCache(cache, outboxes, filter, opts) {
+    const outboxes$ = isObservable(outboxes) ? outboxes : of(outboxes);
+    // Project outboxes to filters
+    const filters$ = outboxes$.pipe(map((outboxes) => {
+        // Get all pubkeys from all relays
+        const pubkeys = new Set();
+        for (const users of Object.values(outboxes)) {
+            for (const user of users) {
+                pubkeys.add(user.pubkey);
+            }
+        }
+        // Create filters for all the pubkeys
+        if (typeof filter === "function") {
+            const users = Array.from(pubkeys).map((pubkey) => ({ pubkey }));
+            return filter(users);
+        }
+        else {
+            return mergeFilters(filter, { authors: Array.from(pubkeys) });
+        }
+    }), 
+    // Only create a new loader if the filters change
+    distinctUntilChanged((a, b) => isFilterEqual(a, b)));
+    // Load blocks from the filter map
+    return (source) => filters$.pipe(
+    // Every time the filters change, create a new cache loader instance
+    switchMap((filters) => source.pipe(loadBlocksFromCache(cache, filters, opts))));
+}
+/** Internal logic for function based timeline loaders */
+function wrapTimelineLoader(window$, loader$, eventStore) {
+    const singleton$ = loader$.pipe(
+    // Pass all events through the store if provided
+    eventStore === null ? identity : filterDuplicateEvents(eventStore || new EventMemory()), 
+    // Ensure a single subscription to the requests
+    share());
+    return (since) => {
+        // Return the loader so it can be subscribed to
+        return new Observable((observer) => {
+            const sub = singleton$.subscribe(observer);
+            // Once subscribed, update the window
+            if (typeof since === "object" && since !== undefined) {
+                // Pass new window to the loader
+                window$.next(since);
+            }
+            else {
+                // Only update window when this request is subscribed to (prevents window getting lost before subscription)
+                window$.next({
+                    // Default to -Infinity to force loading the next block of events (legacy behavior)
+                    since: since ?? -Infinity,
+                });
+            }
+            return () => sub.unsubscribe();
+        });
+    };
+}
+/** @deprecated Use the {@link loadBlocksFromCache} operator instead */
+export function cacheTimelineLoader(request, filters, opts) {
+    const window$ = new BehaviorSubject({});
+    return wrapTimelineLoader(window$, window$.pipe(loadBlocksFromCache(request, filters, opts)));
+}
+/** @deprecated Use the {@link createTimelineLoader} operator instead */
+export function relaysTimelineLoader(pool, relays, filters, opts) {
+    const window$ = new BehaviorSubject({});
+    return wrapTimelineLoader(window$, window$.pipe(loadBlocksFromRelays(pool, relays, filters, opts)));
+}
+/**
+ * Creates a {@link TimelineLoader} that loads events from multiple relays and a cache
+ * @param pool - The upstream pool to use
+ * @param relays - The relays to load from
+ * @param filters - The filters to use
+ * @param opts - The options for the timeline loader
+ */
+export function createTimelineLoader(pool, relays, filters, opts) {
+    const logger = (opts?.logger ?? baseLogger).extend("timeline").extend(nanoid(4));
+    const window$ = new BehaviorSubject({});
+    // Create cache and relays loaders
+    const cache$ = opts?.cache ? window$.pipe(loadBlocksFromCache(opts.cache, filters, { ...opts, logger })) : EMPTY;
+    // Load blocks from relays
+    const relays$ = window$.pipe(loadBlocksFromRelays(pool, relays, filters, { ...opts, logger }));
+    // Merge the cache and relays loaders
+    const loader$ = merge(cache$, relays$);
+    return wrapTimelineLoader(window$, loader$, opts?.eventStore);
+}
+/**
+ * Creates a {@link TimelineLoader} that loads events for a {@link OutboxMap} or an observable of {@link OutboxMap}
+ * @param pool - The upstream pool to use
+ * @param outboxMap - An {@link OutboxMap} or an observable of {@link OutboxMap}
+ * @param filter - A function to create filters for a set of users
+ * @param opts - The options for the timeline loader
+ */
+export function createOutboxTimelineLoader(pool, outboxes, filter, opts) {
+    const logger = (opts?.logger ?? baseLogger).extend("outbox-timeline").extend(nanoid(4));
+    const window$ = new BehaviorSubject({});
+    // An observable of a cache loader instance for all users
+    const cache$ = opts?.cache
+        ? window$.pipe(loadBlocksFromOutboxMapCache(opts?.cache, outboxes, filter, { ...opts, logger }))
+        : EMPTY;
+    // Load blocks from relays using outboxes
+    const relays$ = window$.pipe(loadBlocksFromOutboxMap(pool, outboxes, filter, { ...opts, logger }));
+    // Merge the cache and relays loaders
+    const loader$ = merge(cache$, relays$);
+    // Wrap the loader in a timeline loader function
+    return wrapTimelineLoader(window$, loader$, opts?.eventStore);
 }

package/dist/loaders/unified-event-loader.d.ts

@@ -0,0 +1,19 @@
+import { filterDuplicateEvents, IMissingEventLoader } from "applesauce-core";
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { AddressPointer, AddressPointerWithoutD, EventPointer } from "applesauce-core/helpers/pointers";
+import { Observable } from "rxjs";
+import { UpstreamPool } from "../types.js";
+import { AddressLoaderOptions } from "./address-loader.js";
+import { EventPointerLoaderOptions } from "./event-loader.js";
+export type UnifiedEventLoaderOptions = Partial<EventPointerLoaderOptions & AddressLoaderOptions>;
+export type UnifiedEventLoader = (pointer: EventPointer | AddressPointer | AddressPointerWithoutD) => Observable<NostrEvent>;
+/**
+ * Create a unified event loader that can handle both EventPointer and AddressPointer types.
+ * Internally routes to createEventLoader for EventPointer and createAddressLoader for AddressPointer.
+ */
+export declare function createUnifiedEventLoader(pool: UpstreamPool, opts?: UnifiedEventLoaderOptions): UnifiedEventLoader;
+/**
+ * Creates a {@link UnifiedEventLoader} that will be used to load events that are not found in the store
+ * @returns The created loader
+ */
+export declare function createEventLoaderForStore(store: IMissingEventLoader & Parameters<typeof filterDuplicateEvents>[0], pool: UpstreamPool, opts?: Omit<UnifiedEventLoaderOptions, "eventStore">): UnifiedEventLoader;

package/dist/loaders/unified-event-loader.js

@@ -0,0 +1,46 @@
+import { isEventPointer } from "applesauce-core/helpers/pointers";
+import { createAddressLoader } from "./address-loader.js";
+import { createEventLoader } from "./event-loader.js";
+/**
+ * Create a unified event loader that can handle both EventPointer and AddressPointer types.
+ * Internally routes to createEventLoader for EventPointer and createAddressLoader for AddressPointer.
+ */
+export function createUnifiedEventLoader(pool, opts) {
+    // Create both loaders with the appropriate options
+    const eventLoader = createEventLoader(pool, {
+        bufferTime: opts?.bufferTime,
+        bufferSize: opts?.bufferSize,
+        eventStore: opts?.eventStore,
+        cacheRequest: opts?.cacheRequest,
+        followRelayHints: opts?.followRelayHints,
+        extraRelays: opts?.extraRelays,
+    });
+    const addressLoader = createAddressLoader(pool, {
+        bufferTime: opts?.bufferTime,
+        bufferSize: opts?.bufferSize,
+        eventStore: opts?.eventStore,
+        cacheRequest: opts?.cacheRequest,
+        followRelayHints: opts?.followRelayHints,
+        extraRelays: opts?.extraRelays,
+        lookupRelays: opts?.lookupRelays,
+    });
+    // Return a unified loader that routes based on pointer type
+    return (pointer) => {
+        // Check if it's an EventPointer (has 'id' property)
+        if (isEventPointer(pointer)) {
+            return eventLoader(pointer);
+        }
+        else {
+            return addressLoader(pointer);
+        }
+    };
+}
+/**
+ * Creates a {@link UnifiedEventLoader} that will be used to load events that are not found in the store
+ * @returns The created loader
+ */
+export function createEventLoaderForStore(store, pool, opts) {
+    const loader = createUnifiedEventLoader(pool, { ...opts, eventStore: store });
+    store.eventLoader = loader;
+    return loader;
+}

package/dist/loaders/user-lists-loader.d.ts

@@ -1,6 +1,6 @@
 import { mapEventsToStore } from "applesauce-core";
-import { NostrEvent } from "nostr-tools";
-import { ProfilePointer } from "nostr-tools/nip19";
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { ProfilePointer } from "applesauce-core/helpers/pointers";
 import { Observable } from "rxjs";
 import { CacheRequest, UpstreamPool } from "../types.js";
 /** A list of NIP-51 list kinds that most clients will use */

package/dist/loaders/user-lists-loader.js

@@ -1,6 +1,6 @@
 import { mapEventsToStore } from "applesauce-core";
-import { mergeRelaySets } from "applesauce-core/helpers";
-import { kinds } from "nostr-tools";
+import { kinds } from "applesauce-core/helpers/event";
+import { mergeRelaySets } from "applesauce-core/helpers/relays";
 import { EMPTY, identity, merge } from "rxjs";
 import { makeCacheRequest } from "../helpers/cache.js";
 import { unwrap } from "../helpers/loaders.js";

package/dist/loaders/zaps-loader.d.ts

@@ -1,4 +1,4 @@
-import { NostrEvent } from "nostr-tools";
+import { NostrEvent } from "applesauce-core/helpers/event";
 import { Observable } from "rxjs";
 import { UpstreamPool } from "../types.js";
 import { TagValueLoaderOptions } from "./tag-value-loader.js";

package/dist/loaders/zaps-loader.js

@@ -1,5 +1,6 @@
-import { getReplaceableAddress, getSeenRelays, isReplaceable, mergeRelaySets } from "applesauce-core/helpers";
-import { kinds } from "nostr-tools";
+import { getReplaceableAddress, isReplaceable, kinds } from "applesauce-core/helpers/event";
+import { getSeenRelays, mergeRelaySets } from "applesauce-core/helpers/relays";
+import { EMPTY } from "rxjs";
 import { wrapUpstreamPool } from "../helpers/upstream.js";
 import { createTagValueLoader } from "./tag-value-loader.js";
 /** Creates a loader that loads zap events for a given event */
@@ -11,8 +12,14 @@ export function createZapsLoader(pool, opts) {
     return (event, relays) => {
         if (opts?.useSeenRelays ?? true)
             relays = mergeRelaySets(relays, getSeenRelays(event));
-        return isReplaceable(event.kind)
-            ? addressableLoader({ value: getReplaceableAddress(event), relays })
-            : eventLoader({ value: event.id, relays });
+        if (isReplaceable(event.kind)) {
+            const address = getReplaceableAddress(event);
+            if (!address)
+                return EMPTY;
+            return addressableLoader({ value: address, relays });
+        }
+        else {
+            return eventLoader({ value: event.id, relays });
+        }
     };
 }

package/dist/types.d.ts

@@ -1,14 +1,13 @@
-import { Filter, NostrEvent } from "nostr-tools";
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { Filter } from "applesauce-core/helpers/filter";
 import { Observable } from "rxjs";
 /** A flexible method for requesting events from a cache */
 export type CacheRequest = (filters: Filter[]) => Observable<NostrEvent> | Promise<NostrEvent | NostrEvent[]> | NostrEvent | NostrEvent[];
+/** A method for requesting events from multiple relays */
+export type NostrRequest = (relays: string[], filters: Filter[]) => Observable<NostrEvent>;
 /** A flexible type for the upstream relay pool */
 export type UpstreamPool = NostrRequest | {
     request: NostrRequest;
 };
-/** A method for requesting events from a relay or cache` */
-export type FilterRequest = (filters: Filter[]) => Observable<NostrEvent>;
-/** A method for requesting events from multiple relays */
-export type NostrRequest = (relays: string[], filters: Filter[]) => Observable<NostrEvent>;
 /** A filter that is does not have a since or until */
 export type TimelessFilter = Omit<Filter, "since" | "until">;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "applesauce-loaders",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "A collection of observable based loaders built on rx-nostr",
   "type": "module",
   "main": "dist/index.js",
@@ -52,17 +52,16 @@
     }
   },
   "dependencies": {
-    "applesauce-core": "^4.0.0",
+    "applesauce-core": "^5.0.0",
     "nanoid": "^5.0.9",
-    "nostr-tools": "~2.17",
     "rxjs": "^7.8.1"
   },
   "devDependencies": {
     "@hirez_io/observer-spy": "^2.2.0",
-    "applesauce-signers": "^4.0.0",
+    "applesauce-signers": "^5.0.0",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4",
+    "vitest": "^4.0.15",
     "vitest-websocket-mock": "^0.5.0"
   },
   "funding": {