applesauce-loaders 1.0.0 → 2.1.0

package/dist/loaders/address-loader.js

@@ -0,0 +1,121 @@
+import { mapEventsToStore } from "applesauce-core";
+import { createReplaceableAddress, getReplaceableAddress, getReplaceableIdentifier, isReplaceable, mergeRelaySets, } from "applesauce-core/helpers";
+import { bufferTime, catchError, EMPTY } from "rxjs";
+import { createFiltersFromAddressPointers, isLoadableAddressPointer } from "../helpers/address-pointer.js";
+import { makeCacheRequest } from "../helpers/cache.js";
+import { batchLoader, unwrap } from "../helpers/loaders.js";
+import { wrapUpstreamPool } from "../helpers/upstream.js";
+import { wrapGeneratorFunction } from "../operators/generator.js";
+/**
+ * Loads address pointers from an async cache
+ * @note ignores pointers with force=true
+ */
+export function cacheAddressPointersLoader(request) {
+    return (pointers) => {
+        pointers = pointers.filter((p) => p.cache !== false);
+        // Skip if there are no pointers to load from cache
+        if (pointers.length === 0)
+            return EMPTY;
+        return makeCacheRequest(request, createFiltersFromAddressPointers(pointers));
+    };
+}
+/** 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) => unwrap(relays, (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) {
+        // Filter out invalid pointers and consolidate
+        pointers = consolidateAddressPointers(pointers.filter(isLoadableAddressPointer));
+        // Skip if there are no pointers
+        if (pointers.length === 0)
+            return;
+        // Keep track of remaining pointers to load
+        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)));
+            // If there are no remaining pointers, complete
+            if (remaining.length === 0)
+                return;
+        }
+    });
+}
+/** deep clone a loadable pointer to ensure its safe to modify */
+function cloneLoadablePointer(pointer) {
+    const clone = { ...pointer };
+    if (pointer.relays)
+        clone.relays = [...pointer.relays];
+    return clone;
+}
+/** deduplicates an array of address pointers and merges their relays array */
+export function consolidateAddressPointers(pointers) {
+    const byAddress = new Map();
+    for (const pointer of pointers) {
+        const addr = createReplaceableAddress(pointer.kind, pointer.pubkey, pointer.identifier);
+        if (byAddress.has(addr)) {
+            // duplicate, merge pointers
+            const current = byAddress.get(addr);
+            // merge relays
+            if (pointer.relays && pointer.relays.length > 0) {
+                if (current.relays)
+                    current.relays = mergeRelaySets(current.relays, pointer.relays);
+                else
+                    current.relays = pointer.relays;
+            }
+            // merge cache flag
+            if (pointer.cache === false)
+                current.cache = false;
+        }
+        else
+            byAddress.set(addr, cloneLoadablePointer(pointer));
+    }
+    // return consolidated pointers
+    return Array.from(byAddress.values());
+}
+/** Create a pre-built address pointer loader that supports batching, caching, and lookup relays */
+export function createAddressLoader(pool, opts) {
+    const request = wrapUpstreamPool(pool);
+    return batchLoader(
+    // buffer requests by time or size
+    bufferTime(opts?.bufferTime ?? 1000, undefined, opts?.bufferSize ?? 200), 
+    // Create a loader for batching
+    addressPointerLoadingSequence(
+    // Step 1. load from cache if available
+    opts?.cacheRequest ? cacheAddressPointersLoader(opts.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));
+}

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

@@ -0,0 +1,36 @@
+import { IEventStore } from "applesauce-core";
+import { NostrEvent } from "nostr-tools";
+import { EventPointer } from "nostr-tools/nip19";
+import { Observable } from "rxjs";
+import { CacheRequest, NostrRequest, UpstreamPool } from "../types.js";
+export type LoadableEventPointer = EventPointer & {
+    cache?: boolean;
+};
+export type EventPointerLoader = (pointer: LoadableEventPointer) => Observable<NostrEvent>;
+export type createEventLoader = (pointers: LoadableEventPointer[]) => Observable<NostrEvent>;
+/** Creates a loader that gets a single event from the cache */
+export declare function cacheEventsLoader(request: CacheRequest): createEventLoader;
+/** Creates a loader that gets an array of events from a list of relays */
+export declare function relaysEventsLoader(request: NostrRequest, relays: string[] | Observable<string[]>): createEventLoader;
+/** Creates a loader that gets an array of events from a single relay */
+export declare function relayEventsLoader(request: NostrRequest, relay: string): createEventLoader;
+/** Creates a loader that creates a new loader for each relay hint and uses them to load events */
+export declare function relayHintsEventsLoader(request: NostrRequest, upstream?: (request: NostrRequest, relay: string) => createEventLoader): createEventLoader;
+/** Creates a loader that tries to load events from a list of loaders in order */
+export declare function eventLoadingSequence(...loaders: (createEventLoader | undefined)[]): createEventLoader;
+export type EventPointerLoaderOptions = 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;
+    /** 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 createEventLoader(pool: UpstreamPool, opts?: EventPointerLoaderOptions): EventPointerLoader;

package/dist/loaders/event-loader.js

@@ -0,0 +1,90 @@
+import { mapEventsToStore } from "applesauce-core";
+import { bufferTime, catchError, EMPTY, merge, tap } from "rxjs";
+import { makeCacheRequest } from "../helpers/cache.js";
+import { consolidateEventPointers } from "../helpers/event-pointer.js";
+import { batchLoader, unwrap } from "../helpers/loaders.js";
+import { groupByRelay } from "../helpers/pointer.js";
+import { wrapUpstreamPool } from "../helpers/upstream.js";
+import { wrapGeneratorFunction } from "../operators/generator.js";
+/** Creates a loader that gets a single event from the cache */
+export function cacheEventsLoader(request) {
+    return (pointers) => {
+        pointers = pointers.filter((p) => p.cache !== false);
+        if (pointers.length === 0)
+            return EMPTY;
+        return makeCacheRequest(request, [{ ids: pointers.map((p) => p.id) }]);
+    };
+}
+/** Creates a loader that gets an array of events from a list of relays */
+export function relaysEventsLoader(request, relays) {
+    return (pointers) => unwrap(relays, (relays) => request(relays, [{ ids: pointers.map((p) => p.id) }]));
+}
+/** Creates a loader that gets an array of events from a single relay */
+export function relayEventsLoader(request, relay) {
+    return relaysEventsLoader(request, [relay]);
+}
+/** Creates a loader that creates a new loader for each relay hint and uses them to load events */
+export function relayHintsEventsLoader(request, upstream = relayEventsLoader) {
+    const loaders = new Map();
+    // Get or create a new loader for each relay
+    const getLoader = (relay) => {
+        let loader = loaders.get(relay);
+        if (!loader) {
+            loader = upstream(request, relay);
+            loaders.set(relay, loader);
+        }
+        return loader;
+    };
+    return (pointers) => {
+        // Group pointers by thier relay hints
+        const byRelay = groupByRelay(pointers);
+        // Request the pointers from each relay
+        return merge(...Array.from(byRelay).map(([relay, pointers]) => getLoader(relay)(pointers)));
+    };
+}
+/** Creates a loader that tries to load events from a list of loaders in order */
+export function eventLoadingSequence(...loaders) {
+    return wrapGeneratorFunction(function* (pointers) {
+        // Filter out invalid pointers and consolidate
+        pointers = consolidateEventPointers(pointers);
+        // Skip if there are no pointers
+        if (pointers.length === 0)
+            return;
+        const found = new Set();
+        let remaining = Array.from(pointers);
+        for (const loader of loaders) {
+            if (loader === undefined)
+                continue;
+            yield loader(remaining).pipe(
+            // If the loader throws an error, skip it
+            catchError(() => EMPTY), 
+            // Record events that where found
+            tap((e) => found.add(e.id)));
+            // Remove poniters that where found
+            remaining = remaining.filter((p) => !found.has(p.id));
+            // 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 createEventLoader(pool, opts) {
+    const request = wrapUpstreamPool(pool);
+    return batchLoader(
+    // Create batching sequence
+    // buffer requests by time or size
+    bufferTime(opts?.bufferTime ?? 1000, undefined, opts?.bufferSize ?? 200), 
+    // Create a loader for batching
+    eventLoadingSequence(
+    // Step 1. load from cache if available
+    opts?.cacheRequest ? cacheEventsLoader(opts.cacheRequest) : undefined, 
+    // Step 2. load from relay hints on pointers
+    opts?.followRelayHints !== false ? relayHintsEventsLoader(request) : undefined, 
+    // Step 3. load from extra relays
+    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));
+}

package/dist/loaders/index.d.ts

@@ -1,9 +1,9 @@
-export * from "./loader.js";
-export * from "./replaceable-loader.js";
-export * from "./single-event-loader.js";
-export * from "./user-sets-loader.js";
-export * from "./timeline-loader.js";
-export * from "./relay-timeline-loader.js";
-export * from "./cache-timeline-loader.js";
-export * from "./tag-value-loader.js";
+export * from "./address-loader.js";
 export * from "./dns-identity-loader.js";
+export * from "./event-loader.js";
+export * from "./reactions-loader.js";
+export * from "./social-graph.js";
+export * from "./tag-value-loader.js";
+export * from "./timeline-loader.js";
+export * from "./user-lists-loader.js";
+export * from "./zaps-loader.js";

package/dist/loaders/index.js

@@ -1,9 +1,9 @@
-export * from "./loader.js";
-export * from "./replaceable-loader.js";
-export * from "./single-event-loader.js";
-export * from "./user-sets-loader.js";
-export * from "./timeline-loader.js";
-export * from "./relay-timeline-loader.js";
-export * from "./cache-timeline-loader.js";
-export * from "./tag-value-loader.js";
+export * from "./address-loader.js";
 export * from "./dns-identity-loader.js";
+export * from "./event-loader.js";
+export * from "./reactions-loader.js";
+export * from "./social-graph.js";
+export * from "./tag-value-loader.js";
+export * from "./timeline-loader.js";
+export * from "./user-lists-loader.js";
+export * from "./zaps-loader.js";

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

@@ -0,0 +1,12 @@
+import { NostrEvent } from "nostr-tools";
+import { Observable } from "rxjs";
+import { UpstreamPool } from "../types.js";
+import { TagValueLoaderOptions } from "./tag-value-loader.js";
+/** A loader that takes an event and returns zaps */
+export type ReactionsLoader = (event: NostrEvent, relays?: string[]) => Observable<NostrEvent>;
+export type ReactionsLoaderOptions = Omit<TagValueLoaderOptions, "kinds"> & {
+    /** Whether to request reactions from the relays the event was seen on ( default true ) */
+    useSeenRelays?: boolean;
+};
+/** Creates a loader that loads reaction events for a given event */
+export declare function createReactionsLoader(pool: UpstreamPool, opts?: ReactionsLoaderOptions): ReactionsLoader;

package/dist/loaders/reactions-loader.js

@@ -0,0 +1,18 @@
+import { getReplaceableAddress, getSeenRelays, isReplaceable, mergeRelaySets } from "applesauce-core/helpers";
+import { kinds } from "nostr-tools";
+import { wrapUpstreamPool } from "../helpers/upstream.js";
+import { createTagValueLoader } from "./tag-value-loader.js";
+/** Creates a loader that loads reaction events for a given event */
+export function createReactionsLoader(pool, opts) {
+    const request = wrapUpstreamPool(pool);
+    const eventLoader = createTagValueLoader(request, "e", { ...opts, kinds: [kinds.Reaction] });
+    const addressableLoader = createTagValueLoader(request, "a", { ...opts, kinds: [kinds.Reaction] });
+    // Return diffrent loaders depending on if the event is addressable
+    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 });
+    };
+}

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

@@ -0,0 +1,21 @@
+import { IEventStore } from "applesauce-core";
+import { NostrEvent } from "nostr-tools";
+import { ProfilePointer } from "nostr-tools/nip19";
+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 */
+export type SocialGraphLoader = (user: ProfilePointer & {
+    distance: number;
+}) => Observable<NostrEvent>;
+export type SocialGraphLoaderOptions = Partial<{
+    /** An event store to send all the events to */
+    eventStore: IEventStore;
+    /** The number of parallel requests to make (default 300) */
+    parallel: number;
+    /** Extra relays to load from */
+    extraRelays?: string[] | Observable<string[]>;
+    /** Whether to follow relay hints in contact events */
+    hints?: boolean;
+}>;
+/** Create a social graph loader */
+export declare function createSocialGraphLoader(addressLoader: AddressPointerLoader, opts?: SocialGraphLoaderOptions): SocialGraphLoader;

package/dist/loaders/social-graph.js

@@ -0,0 +1,50 @@
+import { mapEventsToStore } from "applesauce-core";
+import { getProfilePointersFromList, mergeRelaySets } from "applesauce-core/helpers";
+import { kinds } from "nostr-tools";
+import { firstValueFrom, identity, isObservable, lastValueFrom, toArray } from "rxjs";
+import { wrapGeneratorFunction } from "../operators/generator.js";
+/** Create a social graph loader */
+export function createSocialGraphLoader(addressLoader, opts) {
+    return wrapGeneratorFunction(async function* (user) {
+        const seen = new Set();
+        const queue = [user];
+        // Maximum parallel requests (default to 300)
+        const maxParallel = opts?.parallel ?? 300;
+        // get the relays to load from
+        const relays = mergeRelaySets(user.relays, isObservable(opts?.extraRelays) ? await firstValueFrom(opts?.extraRelays) : opts?.extraRelays);
+        // Keep loading while the queue has items
+        while (queue.length > 0) {
+            // Process up to maxParallel items at once
+            const batch = queue.splice(0, maxParallel);
+            const promises = batch.map(async (pointer) => {
+                const address = {
+                    kind: kinds.Contacts,
+                    pubkey: pointer.pubkey,
+                    relays: opts?.hints ? mergeRelaySets(pointer.relays, relays) : relays,
+                };
+                // load the contacts events
+                const events = await lastValueFrom(addressLoader(address).pipe(
+                // Pass all events to the store if set
+                opts?.eventStore ? mapEventsToStore(opts.eventStore) : identity, 
+                // Conver to array
+                toArray()));
+                if (events.length === 0)
+                    return;
+                const contacts = getProfilePointersFromList(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) {
+                        // Dont add any contacts that have already been seen
+                        if (seen.has(contact.pubkey))
+                            continue;
+                        seen.add(contact.pubkey);
+                        // Add to queue
+                        queue.push({ ...contact, distance: pointer.distance - 1 });
+                    }
+                }
+            });
+            // Wait for all parallel operations to complete
+            await Promise.all(promises);
+        }
+    });
+}

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

@@ -1,7 +1,8 @@
-import { logger } from "applesauce-core";
+import { IEventStore } from "applesauce-core";
 import { NostrEvent } from "nostr-tools";
-import { CacheRequest, Loader, NostrRequest } from "./loader.js";
-export type TabValuePointer = {
+import { Observable } from "rxjs";
+import { CacheRequest, NostrRequest, UpstreamPool } from "../types.js";
+export type TagValuePointer = {
     /** The value of the tag to load */
     value: string;
     /** The relays to load from */
@@ -10,13 +11,10 @@ export type TabValuePointer = {
     force?: boolean;
 };
 export type TagValueLoaderOptions = {
-    /** the name of this loader (for debugging) */
-    name?: string;
-    /**
-     * Time interval to buffer requests in ms
-     * @default 1000
-     */
+    /** Time interval to buffer requests in ms ( default 1000 ) */
     bufferTime?: number;
+    /** Max buffer size ( default 200 ) */
+    bufferSize?: number;
     /** Restrict queries to specific kinds */
     kinds?: number[];
     /** Restrict queries to specific authors */
@@ -26,14 +24,14 @@ export type TagValueLoaderOptions = {
     /** Method used to load from the cache */
     cacheRequest?: CacheRequest;
     /** An array of relays to always fetch from */
-    extraRelays?: string[];
+    extraRelays?: string[] | Observable<string[]>;
+    /** An event store used to deduplicate events */
+    eventStore?: IEventStore;
 };
-export declare class TagValueLoader extends Loader<TabValuePointer, NostrEvent> {
-    name: string;
-    protected log: typeof logger;
-    /** A method to load events from a local cache */
-    cacheRequest?: CacheRequest;
-    /** An array of relays to always fetch from */
-    extraRelays?: string[];
-    constructor(request: NostrRequest, tagName: string, opts?: TagValueLoaderOptions);
-}
+export type TagValueLoader = (pointer: TagValuePointer) => Observable<NostrEvent>;
+/** Creates a loader that gets tag values from the cache */
+export declare function cacheTagValueLoader(request: CacheRequest, tagName: string, opts?: TagValueLoaderOptions): (pointers: TagValuePointer[]) => Observable<NostrEvent>;
+/** Creates a loader that gets tag values from relays */
+export declare function relaysTagValueLoader(request: NostrRequest, tagName: string, opts?: TagValueLoaderOptions): (pointers: TagValuePointer[]) => Observable<NostrEvent>;
+/** Create a pre-built tag value loader that supports batching, caching, and relay hints */
+export declare function createTagValueLoader(pool: UpstreamPool, tagName: string, opts?: TagValueLoaderOptions): TagValueLoader;

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

@@ -1,76 +1,75 @@
-import { logger } from "applesauce-core";
-import { markFromCache, mergeRelaySets } from "applesauce-core/helpers";
-import { bufferTime, filter, merge, mergeMap, tap } from "rxjs";
+import { mapEventsToStore } from "applesauce-core";
+import { mergeRelaySets } from "applesauce-core/helpers";
+import { bufferTime, EMPTY, merge } from "rxjs";
 import { unique } from "../helpers/array.js";
-import { completeOnEOSE } from "../operators/complete-on-eose.js";
-import { distinctRelaysBatch } from "../operators/distinct-relays.js";
-import { Loader } from "./loader.js";
-export class TagValueLoader extends Loader {
-    name;
-    log = logger.extend("TagValueLoader");
-    /** A method to load events from a local cache */
-    cacheRequest;
-    /** An array of relays to always fetch from */
-    extraRelays;
-    constructor(request, tagName, opts) {
+import { makeCacheRequest } from "../helpers/cache.js";
+import { batchLoader, unwrap } from "../helpers/loaders.js";
+import { wrapUpstreamPool } from "../helpers/upstream.js";
+/** Creates a loader that gets tag values from the cache */
+export function cacheTagValueLoader(request, tagName, opts) {
+    return (pointers) => {
+        const baseFilter = {};
+        if (opts?.kinds)
+            baseFilter.kinds = opts.kinds;
+        if (opts?.authors)
+            baseFilter.authors = opts.authors;
+        if (opts?.since)
+            baseFilter.since = opts.since;
         const filterTag = `#${tagName}`;
-        super((source) => source.pipe(
-        // batch the pointers
-        bufferTime(opts?.bufferTime ?? 1000), 
-        // filter out empty batches
-        filter((pointers) => pointers.length > 0), 
-        // only request from each relay once
-        distinctRelaysBatch((m) => m.value), 
-        // batch pointers into requests
-        mergeMap((pointers) => {
-            const baseFilter = {};
-            if (opts?.kinds)
-                baseFilter.kinds = opts.kinds;
-            if (opts?.since)
-                baseFilter.since = opts.since;
-            if (opts?.authors)
-                baseFilter.authors = opts.authors;
-            // build request map for relays
-            const requestMap = pointers.reduce((map, pointer) => {
-                const relays = mergeRelaySets(pointer.relays, this.extraRelays);
-                for (const relay of relays) {
-                    if (!map[relay]) {
-                        // create new filter for relay
-                        const filter = { ...baseFilter, [filterTag]: [pointer.value] };
-                        map[relay] = [filter];
-                    }
-                    else {
-                        // map for relay already exists, add the tag value
-                        const filter = map[relay][0];
-                        filter[filterTag].push(pointer.value);
-                    }
+        const filter = { ...baseFilter, [filterTag]: unique(pointers.map((p) => p.value)) };
+        return makeCacheRequest(request, [filter]);
+    };
+}
+/** Creates a loader that gets tag values from relays */
+export function relaysTagValueLoader(request, tagName, opts) {
+    const filterTag = `#${tagName}`;
+    return (pointers) => unwrap(opts?.extraRelays, (extraRelays) => {
+        const baseFilter = {};
+        if (opts?.kinds)
+            baseFilter.kinds = opts.kinds;
+        if (opts?.authors)
+            baseFilter.authors = opts.authors;
+        if (opts?.since)
+            baseFilter.since = opts.since;
+        // build request map for relays
+        const requestMap = pointers.reduce((map, pointer) => {
+            const relays = mergeRelaySets(pointer.relays, extraRelays);
+            for (const relay of relays) {
+                if (!map[relay]) {
+                    // create new filter for relay
+                    map[relay] = { ...baseFilter, [filterTag]: [pointer.value] };
+                }
+                else {
+                    // map for relay already exists, add the tag value
+                    map[relay][filterTag].push(pointer.value);
                 }
-                return map;
-            }, {});
-            let fromCache = 0;
-            const cacheRequest = this?.cacheRequest?.([
-                { ...baseFilter, [filterTag]: unique(pointers.map((p) => p.value)) },
-            ]).pipe(
-            // mark the event as from the cache
-            tap({
-                next: (event) => {
-                    markFromCache(event);
-                    fromCache++;
-                },
-                complete: () => {
-                    if (fromCache > 0)
-                        this.log(`Loaded ${fromCache} from cache`);
-                },
-            }));
-            const requests = Object.entries(requestMap).map(([relay, filters]) => request([relay], filters).pipe(completeOnEOSE()));
-            this.log(`Requesting ${pointers.length} tag values from ${requests.length} relays`);
-            return cacheRequest ? merge(cacheRequest, ...requests) : merge(...requests);
-        })));
-        // Set options
-        this.cacheRequest = opts?.cacheRequest;
-        this.extraRelays = opts?.extraRelays;
-        // create a unique logger for this instance
-        this.name = opts?.name ?? "";
-        this.log = this.log.extend(opts?.kinds ? `${this.name} ${filterTag} (${opts?.kinds?.join(",")})` : `${this.name} ${filterTag}`);
-    }
+            }
+            return map;
+        }, {});
+        const requests = Object.entries(requestMap).map(([relay, filter]) => request([relay], [filter]));
+        return merge(...requests);
+    });
+}
+/** Create a pre-built tag value loader that supports batching, caching, and relay hints */
+export function createTagValueLoader(pool, tagName, opts) {
+    const request = wrapUpstreamPool(pool);
+    return batchLoader(
+    // buffer requests by time or size
+    bufferTime(opts?.bufferTime ?? 1000, undefined, opts?.bufferSize ?? 200), 
+    // Create a loader for batching
+    (pointers) => {
+        // Skip if there are no pointers
+        if (pointers.length === 0)
+            return EMPTY;
+        // Load from cache and relays in parallel
+        return merge(
+        // load from cache if available
+        opts?.cacheRequest ? cacheTagValueLoader(opts.cacheRequest, tagName, opts)(pointers) : [], 
+        // load from relays
+        relaysTagValueLoader(request, tagName, opts)(pointers));
+    }, 
+    // 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));
 }