applesauce-loaders 1.0.0 → 2.0.0

package/README.md

@@ -1,93 +1,232 @@
 # applesauce-loaders
 
-A collection of loader classes to make loading common events from multiple relays easier.
+A collection of functional loading methods to make common event loading patterns easier.
 
-## Replaceable event loader
+[Documentation](https://hzrd149.github.io/applesauce/loaders/package.html) [typedoc](https://hzrd149.github.io/applesauce/typedoc/modules/applesauce-loaders.html)
 
-The `ReplaceableLoader` class can be used to load profiles (kind 0), contact lists (kind 3), and any other replaceable (1xxxx) or parameterized replaceable event (3xxxx)
+## Address Loader
+
+The Address Loader is a specialized loader for fetching Nostr replaceable events by their address (kind, pubkey, and optional identifier). It provides an efficient way to batch and deduplicate requests, cache results, and handle relay hints.
 
 ```ts
-import { Observable } from "rxjs";
+import { createAddressLoader } from "applesauce-loaders/loaders";
 import { EventStore } from "applesauce-core";
-import { ReplaceableLoader } from "applesauce-loaders/loaders";
-
-export const eventStore = new EventStore();
-
-// Create a method to let the loaders use nostr-tools relay pool
-function nostrRequest(relays: string[], filters: Filter[]) {
-  return new Observable((observer) => {
-    const sub = pool.subscribe(filters, {
-      onevent: (event) => observer.next(event),
-      oneose: () => {
-        sub.close();
-        observer.complete();
-      },
-    });
-
-    return () => sub.close();
-  });
-}
+import { RelayPool } from "applesauce-relay";
 
-// create method to load events from the cache relay
-function cacheRequest(filters: Filter[]) {
-  return new Observable((observer) => {
-    const sub = cacheRelay.subscribe(filters, {
-      onevent: (event) => observer.next(event),
-      oneose: () => {
-        sub.close();
-        observer.complete();
-      },
-    });
-  });
-}
+const eventStore = new EventStore();
+const pool = new RelayPool();
 
-const replaceableLoader = new ReplaceableLoader(rxNostr, {
+// Create an address loader (do this once at the app level)
+const addressLoader = createAddressLoader(pool, {
+  // Pass all events to the event store to deduplicate them
+  eventStore,
+  // Optional configuration options
   bufferTime: 1000,
-  // check the cache first for events
-  cacheRequest: cacheRequest,
-  // lookup relays are used as a fallback if the event cant be found
-  lookupRelays: ["wss://purplepag.es/"],
+  followRelayHints: true,
+  extraRelays: ["wss://relay.example.com"],
 });
 
-// start the loader by subscribing to it
-replaceableLoader.subscribe((packet) => {
-  // send all loaded events to the event store
-  eventStore.add(packet.event, packet.from);
+// Load a profile (kind 0)
+addressLoader({
+  kind: 0,
+  pubkey: "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
+  relays: ["wss://relay.example.com"],
+}).subscribe((event) => {
+  // Handle the loaded event
+  console.log(event);
 });
 
-// start loading some replaceable events
-replaceableLoader.next({
-  kind: 0,
+// Load a contact list (kind 3)
+addressLoader({
+  kind: 3,
   pubkey: "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
-  relays: ["wss://pyramid.fiatjaf.com/"],
+  relays: ["wss://relay.example.com"],
+}).subscribe((event) => {
+  // Handle the loaded event
+  console.log(event);
 });
 
-// load a parameterized replaceable event
-replaceableLoader.next({
+// Load a parameterized replaceable event
+addressLoader({
   kind: 30000,
   pubkey: "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
   identifier: "list of bad people",
-  relays: ["wss://pyramid.fiatjaf.com/"],
+  relays: ["wss://relay.example.com"],
+}).subscribe((event) => {
+  // Handle the loaded event
+  console.log(event);
 });
+```
 
-// if no relays are provided only the cache and lookup relays will be checked
-replaceableLoader.next({
-  kind: 3,
-  pubkey: "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
+## Event Loader
+
+The Event Loader is a specialized loader for fetching Nostr events by their IDs. It provides an efficient way to batch and deduplicate requests, cache results, and handle relay hints.
+
+```ts
+import { createEventLoader } from "applesauce-loaders/loaders";
+
+// Create an event loader (do this once at the app level)
+const eventLoader = createEventLoader(pool, {
+  // Pass all events to the event store to deduplicate them
+  eventStore,
+  // Optional configuration options
+  bufferTime: 1000,
+  followRelayHints: true,
+  extraRelays: ["wss://relay.example.com"],
 });
 
-// passing a new relay will cause it to be loaded again
-replaceableLoader.next({
-  kind: 0,
-  pubkey: "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
-  relays: ["wss://relay.westernbtc.com/"],
+// Load an event by ID
+eventLoader({
+  id: "2650f6292166624f45795248edb9ca136c276a3d10a0d8f4efd2b8b23eb2d5fc",
+  relays: ["wss://relay.example.com"],
+}).subscribe((event) => {
+  // Handle the loaded event
+  console.log(event);
 });
 
-// or force it to load it again from the same relays
-replaceableLoader.next({
-  kind: 0,
-  pubkey: "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
-  relays: ["wss://pyramid.fiatjaf.com/"],
-  force: true,
+// Load from extra relays
+eventLoader({
+  id: "2650f6292166624f45795248edb9ca136c276a3d10a0d8f4efd2b8b23eb2d5fc",
+  relays: ["wss://relay.example.com"],
+}).subscribe((event) => {
+  // Handle the loaded event
+  console.log(event);
+});
+```
+
+## 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.
+
+```ts
+import { createTimelineLoader } from "applesauce-loaders/loaders";
+
+// Create a timeline loader
+const timelineLoader = createTimelineLoader(
+  pool,
+  ["wss://relay.example.com"],
+  { kinds: [1] }, // Load text notes
+  { eventStore },
+);
+
+// Initial load - gets the most recent events
+timelineLoader().subscribe((event) => {
+  console.log("Loaded event:", event);
+});
+
+// Later, load older events by calling the loader again
+// Each call continues from where the previous one left off
+timelineLoader().subscribe((event) => {
+  console.log("Loaded older event:", event);
+});
+
+// Load events until a specific timestamp
+const oneWeekAgo = Math.floor(Date.now() / 1000) - 7 * 24 * 60 * 60;
+timelineLoader(oneWeekAgo).subscribe((event) => {
+  console.log("Event from last week:", event);
 });
 ```
+
+## Loading from cache
+
+All loaders support a `cacheRequest` option to load events from a local cache.
+
+```ts
+import { NostrEvent, Filter } from "nostr-tools";
+import { createEventLoader } from "applesauce-loaders/loaders";
+
+// Custom method for loading events from a database
+async function cacheRequest(filters: Filter[]): Promise<NostrEvent[]> {
+  return await cacheDatabase.getEvents(filters);
+}
+
+const eventLoader = createEventLoader(pool, {
+  // Pass all events to the event store to deduplicate them
+  eventStore,
+  // Pass a custom cache method
+  cacheRequest,
+  // Optional configuration options
+  bufferTime: 1000,
+});
+
+// Because no relays are specified, the event will be loaded from the cache
+eventLoader({
+  id: "2650f6292166624f45795248edb9ca136c276a3d10a0d8f4efd2b8b23eb2d5fc",
+}).subscribe((event) => {
+  // Handle the loaded event
+  console.log(event);
+});
+```
+
+## Configuration Options
+
+All loaders accept these common configuration options:
+
+### Address Loader Options
+
+- `bufferTime`: Time interval to buffer requests in ms (default 1000)
+- `bufferSize`: Max buffer size (default 200)
+- `eventStore`: An event store used to deduplicate events
+- `cacheRequest`: A method used to load events from a local cache
+- `followRelayHints`: Whether to follow relay hints (default true)
+- `lookupRelays`: Fallback lookup relays to check when event can't be found
+- `extraRelays`: An array of relays to always fetch from
+
+### Event Loader Options
+
+- `bufferTime`: Time interval to buffer requests in ms (default 1000)
+- `bufferSize`: Max buffer size (default 200)
+- `eventStore`: An event store used to deduplicate events
+- `cacheRequest`: A method used to load events from a local cache
+- `followRelayHints`: Whether to follow relay hints (default true)
+- `extraRelays`: An array of relays to always fetch from
+
+### Timeline Loader Options
+
+- `limit`: Maximum number of events to request per filter
+- `cache`: A method used to load events from a local cache
+- `eventStore`: An event store to pass all events to
+
+## Working with Relay Pools
+
+All loaders require a request method for loading Nostr events from relays. You can provide this in multiple ways:
+
+### Using a RelayPool instance
+
+The simplest approach is to pass a RelayPool instance directly:
+
+```ts
+import { createAddressLoader, createEventLoader } from "applesauce-loaders/loaders";
+import { RelayPool } from "applesauce-relay";
+
+const pool = new RelayPool();
+const addressLoader = createAddressLoader(pool, { eventStore });
+const eventLoader = createEventLoader(pool, { eventStore });
+```
+
+### Using a custom request method
+
+You can also provide a custom request method, such as one from nostr-tools:
+
+```ts
+import { createEventLoader } from "applesauce-loaders/loaders";
+import { SimplePool } from "nostr-tools";
+import { Observable } from "rxjs";
+
+const pool = SimplePool();
+
+// Create a custom request function using nostr-tools
+function customRequest(relays, filters) {
+  return new Observable((observer) => {
+    const sub = pool.subscribeMany(relays, filters, {
+      onevent: (event) => observer.next(event),
+      eose: () => observer.complete(),
+    });
+
+    return () => sub.close();
+  });
+}
+
+// Create event loader with custom request
+const eventLoader = createEventLoader(customRequest, options);
+```

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

@@ -8,7 +8,7 @@ export type LoadableAddressPointer = {
     identifier?: string;
     /** Relays to load from */
     relays?: string[];
-    /** Load this address pointer even if it has already been loaded */
+    /** Ignore all forms of caching */
     force?: boolean;
 };
 /** Converts an array of address pointers to a filter */
@@ -23,7 +23,7 @@ export declare function groupAddressPointersByKind(pointers: AddressPointerWitho
 export declare function groupAddressPointersByPubkey(pointers: AddressPointerWithoutD[]): Map<string, AddressPointerWithoutD[]>;
 /** Groups address pointers by kind or pubkey depending on which is most optimal */
 export declare function groupAddressPointersByPubkeyOrKind(pointers: AddressPointerWithoutD[]): Map<string, AddressPointerWithoutD[]> | Map<number, AddressPointerWithoutD[]>;
+/** @deprecated use mergeRelaySets instead */
 export declare function getRelaysFromPointers(pointers: AddressPointerWithoutD[]): Set<string>;
-export declare function getAddressPointerId<T extends AddressPointerWithoutD>(pointer: T): string;
 /** deduplicates an array of address pointers and merges their relays array */
 export declare function consolidateAddressPointers(pointers: LoadableAddressPointer[]): LoadableAddressPointer[];

package/dist/helpers/address-pointer.js

@@ -1,4 +1,4 @@
-import { getReplaceableUID, mergeRelaySets } from "applesauce-core/helpers";
+import { createReplaceableAddress, mergeRelaySets } from "applesauce-core/helpers";
 import { isAddressableKind, isReplaceableKind } from "nostr-tools/kinds";
 import { unique } from "./array.js";
 /** Converts an array of address pointers to a filter */
@@ -62,6 +62,7 @@ export function groupAddressPointersByPubkeyOrKind(pointers) {
     const pubkeys = new Set(pointers.map((p) => p.pubkey));
     return pubkeys.size < kinds.size ? groupAddressPointersByPubkey(pointers) : groupAddressPointersByKind(pointers);
 }
+/** @deprecated use mergeRelaySets instead */
 export function getRelaysFromPointers(pointers) {
     const relays = new Set();
     for (const pointer of pointers) {
@@ -73,9 +74,6 @@ export function getRelaysFromPointers(pointers) {
     }
     return relays;
 }
-export function getAddressPointerId(pointer) {
-    return getReplaceableUID(pointer.kind, pointer.pubkey, pointer.identifier);
-}
 /** deep clone a loadable pointer to ensure its safe to modify */
 function cloneLoadablePointer(pointer) {
     const clone = { ...pointer };
@@ -85,12 +83,12 @@ function cloneLoadablePointer(pointer) {
 }
 /** deduplicates an array of address pointers and merges their relays array */
 export function consolidateAddressPointers(pointers) {
-    const byId = new Map();
+    const byAddress = new Map();
     for (const pointer of pointers) {
-        const id = getAddressPointerId(pointer);
-        if (byId.has(id)) {
+        const addr = createReplaceableAddress(pointer.kind, pointer.pubkey, pointer.identifier);
+        if (byAddress.has(addr)) {
             // duplicate, merge pointers
-            const current = byId.get(id);
+            const current = byAddress.get(addr);
             // merge relays
             if (pointer.relays) {
                 if (current.relays)
@@ -104,8 +102,8 @@ export function consolidateAddressPointers(pointers) {
             }
         }
         else
-            byId.set(id, cloneLoadablePointer(pointer));
+            byAddress.set(addr, cloneLoadablePointer(pointer));
     }
     // return consolidated pointers
-    return Array.from(byId.values());
+    return Array.from(byAddress.values());
 }

package/dist/helpers/cache.d.ts

@@ -0,0 +1,9 @@
+import { Observable } from "rxjs";
+import { Filter, NostrEvent } from "nostr-tools";
+import { CacheRequest, FilterRequest } from "../types.js";
+/** Calls the cache request and converts the reponse into an observable */
+export declare function unwrapCacheRequest(request: CacheRequest, filters: Filter[]): Observable<NostrEvent>;
+/** Calls a cache request method with filters and marks all returned events as being from the cache */
+export declare function makeCacheRequest(request: CacheRequest, filters: Filter[]): Observable<NostrEvent>;
+/** Wraps a cache request method and returns a FilterRequest */
+export declare function wrapCacheRequest(request: CacheRequest): FilterRequest;

package/dist/helpers/cache.js

@@ -0,0 +1,22 @@
+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))
+        return from(result);
+    else
+        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)));
+}
+/** Wraps a cache request method and returns a FilterRequest */
+export function wrapCacheRequest(request) {
+    return (filters) => makeCacheRequest(request, filters);
+}

package/dist/helpers/event-pointer.js

@@ -3,17 +3,17 @@ export function consolidateEventPointers(pointers) {
     let ids = new Map();
     for (let pointer of pointers) {
         let existing = ids.get(pointer.id);
-        if (existing) {
-            // merge relays
-            if (pointer.relays) {
-                if (!existing.relays)
-                    existing.relays = [...pointer.relays];
-                else
-                    existing.relays = [...existing.relays, ...pointer.relays.filter((r) => !existing.relays.includes(r))];
-            }
+        // merge relays
+        if (existing && pointer.relays) {
+            if (!existing.relays)
+                existing.relays = [...pointer.relays];
+            // TODO: maybe use mergeRelaySets here if its performant enough
+            else
+                existing.relays = [...existing.relays, ...pointer.relays.filter((r) => !existing.relays.includes(r))];
+        }
+        else if (!existing) {
+            ids.set(pointer.id, { ...pointer });
         }
-        else
-            ids.set(pointer.id, pointer);
     }
     return Array.from(ids.values());
 }

package/dist/helpers/index.d.ts

@@ -1 +1,6 @@
 export * from "./dns-identity.js";
+export * from "./cache.js";
+export * from "./event-pointer.js";
+export * from "./address-pointer.js";
+export * from "./loaders.js";
+export * from "./upstream.js";

package/dist/helpers/index.js

@@ -1 +1,6 @@
 export * from "./dns-identity.js";
+export * from "./cache.js";
+export * from "./event-pointer.js";
+export * from "./address-pointer.js";
+export * from "./loaders.js";
+export * from "./upstream.js";

package/dist/helpers/loaders.d.ts

@@ -0,0 +1,3 @@
+import { MonoTypeOperatorFunction, Observable, OperatorFunction } from "rxjs";
+/** Creates a loader that takes a single value and batches the requests to an upstream loader */
+export declare function batchLoader<Input extends unknown = unknown, Output extends unknown = unknown>(buffer: OperatorFunction<Input, Input[]>, upstream: (input: Input[]) => Observable<Output>, matcher: (input: Input, output: Output) => boolean, output?: MonoTypeOperatorFunction<Output>): (value: Input) => Observable<Output>;

package/dist/helpers/loaders.js

@@ -0,0 +1,27 @@
+import { filter, identity, map, mergeAll, Observable, share, Subject, take, } from "rxjs";
+/** Creates a loader that takes a single value and batches the requests to an upstream loader */
+export function batchLoader(buffer, upstream, matcher, output) {
+    const queue = new Subject();
+    const requests = queue.pipe(buffer, 
+    // ignore empty buffers
+    filter((buffer) => buffer.length > 0), 
+    // create a new upstream request for each buffer and make sure only one is created
+    map((v) => upstream(v).pipe(share())), 
+    // Make sure that only a single upstream buffer is created
+    share());
+    return (input) => new Observable((observer) => {
+        // Add the pointer to the queue when observable is subscribed
+        setTimeout(() => queue.next(input), 0);
+        return requests
+            .pipe(
+        // wait for the next batch to run
+        take(1), 
+        // subscribe to it
+        mergeAll(), 
+        // filter the results for the requested input
+        filter((output) => matcher(input, output)), 
+        // Extra output operations
+        output ?? identity)
+            .subscribe(observer);
+    });
+}

package/dist/helpers/pointer.d.ts

@@ -1,3 +1,4 @@
+/** Takes an array of objects with a `relays` property and returns a map of relays to the objects */
 export declare function groupByRelay<T extends {
     relays?: string[];
 }>(pointers: T[], extraRelays?: string[]): Map<string, T[]>;

package/dist/helpers/pointer.js

@@ -1,4 +1,5 @@
 import { mergeRelaySets } from "applesauce-core/helpers";
+/** Takes an array of objects with a `relays` property and returns a map of relays to the objects */
 export function groupByRelay(pointers, extraRelays) {
     let byRelay = new Map();
     for (const pointer of pointers) {

package/dist/helpers/upstream.d.ts

@@ -0,0 +1,7 @@
+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 */
+export declare function wrapUpstreamPool(pool: UpstreamPool): NostrRequest;

package/dist/helpers/upstream.js

@@ -0,0 +1,13 @@
+/** Makes a nostr request on the upstream pool */
+export function makeUpstreamRequest(pool, relays, filters) {
+    if (typeof pool === "function")
+        return pool(relays, filters);
+    else if (typeof pool === "object" && "request" in pool)
+        return pool.request(relays, filters);
+    else
+        throw new Error("Invalid upstream pool");
+}
+/** Wraps an upstream pool and returns a NostrRequest */
+export function wrapUpstreamPool(pool) {
+    return (relays, filters) => makeUpstreamRequest(pool, relays, filters);
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export * from "./loaders/index.js";
+export * as Loaders from "./loaders/index.js";
 export * as Operators from "./operators/index.js";
+export * from "./types.js";

package/dist/index.js

@@ -1,2 +1,3 @@
-export * from "./loaders/index.js";
+export * as Loaders from "./loaders/index.js";
 export * as Operators from "./operators/index.js";
+export * from "./types.js";

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

@@ -0,0 +1,37 @@
+import { IEventStore } from "applesauce-core";
+import { NostrEvent } from "nostr-tools";
+import { Observable } from "rxjs";
+import { LoadableAddressPointer } from "../helpers/address-pointer.js";
+import { CacheRequest, NostrRequest, UpstreamPool } from "../types.js";
+/** A method that takes address pointers and returns an observable of events */
+export type AddressPointersLoader = (pointers: LoadableAddressPointer[]) => Observable<NostrEvent>;
+export type AddressPointerLoader = (pointer: LoadableAddressPointer) => Observable<NostrEvent>;
+/**
+ * Loads address pointers from an async cache
+ * @note ignores pointers with force=true
+ */
+export declare function cacheAddressPointersLoader(request: CacheRequest): AddressPointersLoader;
+/** Loads address pointers from the relay hints */
+export declare function relayHintsAddressPointersLoader(request: NostrRequest): AddressPointersLoader;
+/** Loads address pointers from an array of relays */
+export declare function relaysAddressPointersLoader(request: NostrRequest, relays: Observable<string[]> | string[]): AddressPointersLoader;
+/** Creates a loader that loads all event pointers based on their relays */
+export declare function addressPointerLoadingSequence(...loaders: (AddressPointersLoader | undefined)[]): AddressPointersLoader;
+export type AddressLoaderOptions = Partial<{
+    /** Time interval to buffer requests in ms ( default 1000 ) */
+    bufferTime: number;
+    /** Max buffer size ( default 200 ) */
+    bufferSize: number;
+    /** An event store used to deduplicate events */
+    eventStore: IEventStore;
+    /** A method used to load events from a local cache */
+    cacheRequest: CacheRequest;
+    /** Whether to follow relay hints ( default true ) */
+    followRelayHints: boolean;
+    /** Fallback lookup relays to check when event cant be found */
+    lookupRelays: string[] | Observable<string[]>;
+    /** An array of relays to always fetch from */
+    extraRelays: string[] | Observable<string[]>;
+}>;
+/** Create a pre-built address pointer loader that supports batching, caching, and lookup relays */
+export declare function createAddressLoader(pool: UpstreamPool, opts?: AddressLoaderOptions): AddressPointerLoader;

package/dist/loaders/address-loader.js

@@ -0,0 +1,94 @@
+import { mapEventsToStore } from "applesauce-core";
+import { createReplaceableAddress, getReplaceableAddress, getReplaceableIdentifier, isReplaceable, mergeRelaySets, } from "applesauce-core/helpers";
+import { bufferTime, catchError, EMPTY, filter, isObservable, map, of, pipe, switchMap, take } from "rxjs";
+import { consolidateAddressPointers, createFiltersFromAddressPointers, isLoadableAddressPointer, } from "../helpers/address-pointer.js";
+import { makeCacheRequest, wrapCacheRequest } from "../helpers/cache.js";
+import { batchLoader } from "../helpers/loaders.js";
+import { wrapGeneratorFunction } from "../operators/generator.js";
+import { wrapUpstreamPool } from "../helpers/upstream.js";
+/**
+ * Loads address pointers from an async cache
+ * @note ignores pointers with force=true
+ */
+export function cacheAddressPointersLoader(request) {
+    return (pointers) => makeCacheRequest(request, createFiltersFromAddressPointers(pointers
+        // Ignore pointers that want to skip cache
+        .filter((p) => p.force !== true)));
+}
+/** Loads address pointers from the relay hints */
+export function relayHintsAddressPointersLoader(request) {
+    return (pointers) => {
+        const relays = mergeRelaySets(...pointers.map((p) => p.relays));
+        if (relays.length === 0)
+            return EMPTY;
+        const filters = createFiltersFromAddressPointers(pointers);
+        return request(relays, filters);
+    };
+}
+/** Loads address pointers from an array of relays */
+export function relaysAddressPointersLoader(request, relays) {
+    return (pointers) => 
+    // Resolve the relays as an observable
+    (isObservable(relays) ? relays : of(relays)).pipe(
+    // Only take the first value
+    take(1), 
+    // Make the request
+    switchMap((relays) => {
+        if (relays.length === 0)
+            return EMPTY;
+        const filters = createFiltersFromAddressPointers(pointers);
+        return request(relays, filters);
+    }));
+}
+/** Creates a loader that loads all event pointers based on their relays */
+export function addressPointerLoadingSequence(...loaders) {
+    return wrapGeneratorFunction(function* (pointers) {
+        let remaining = Array.from(pointers);
+        for (const loader of loaders) {
+            if (loader === undefined)
+                continue;
+            const results = yield loader(remaining).pipe(
+            // If the loader throws an error, skip it
+            catchError(() => EMPTY));
+            // Get set of addresses loaded
+            const addresses = new Set(results.filter((e) => isReplaceable(e.kind)).map((event) => getReplaceableAddress(event)));
+            // Remove the pointers that were loaded
+            remaining = remaining.filter((p) => !addresses.has(createReplaceableAddress(p.kind, p.pubkey, p.identifier)) || p.force === true);
+            // If there are no remaining pointers, complete
+            if (remaining.length === 0)
+                return;
+        }
+    });
+}
+/** Create a pre-built address pointer loader that supports batching, caching, and lookup relays */
+export function createAddressLoader(pool, opts) {
+    const request = wrapUpstreamPool(pool);
+    const cacheRequest = opts?.cacheRequest ? wrapCacheRequest(opts.cacheRequest) : undefined;
+    return batchLoader(
+    // Create batching sequence
+    pipe(
+    // filter out invalid pointers
+    filter(isLoadableAddressPointer), 
+    // buffer requests by time or size
+    bufferTime(opts?.bufferTime ?? 1000, undefined, opts?.bufferSize ?? 200), 
+    // Ingore empty buffers
+    filter((b) => b.length > 0), 
+    // consolidate buffered pointers
+    map(consolidateAddressPointers)), 
+    // Create a loader for batching
+    addressPointerLoadingSequence(
+    // Step 1. load from cache if available
+    cacheRequest ? cacheAddressPointersLoader(cacheRequest) : undefined, 
+    // Step 2. load from relay hints on pointers
+    opts?.followRelayHints !== false ? relayHintsAddressPointersLoader(request) : undefined, 
+    // Step 3. load from extra relays
+    opts?.extraRelays ? relaysAddressPointersLoader(request, opts.extraRelays) : undefined, 
+    // Step 4. load from lookup relays
+    opts?.lookupRelays ? relaysAddressPointersLoader(request, opts.lookupRelays) : undefined), 
+    // 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));
+}