fix(cache): skip cache queries for subscriptions with only ephemeral kinds

Ephemeral events (kinds 20000-29999) are never stored in cache, so querying
the cache for them is wasteful. This adds proper filtering to skip cache
queries when all filters contain only ephemeral kinds.

Also exports filterForCache utilities for cache adapters to use.

Author: pablof7z

bun.lock

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+import { filterEphemeralKindsFromFilter, filterForCache, isEphemeralKind } from "./filter";
+import type { NDKFilter, NDKSubscription } from "../subscription/index.js";
+
+describe("isEphemeralKind", () => {
+    it("should return true for kinds in the 20000-29999 range", () => {
+        expect(isEphemeralKind(20000)).toBe(true);
+        expect(isEphemeralKind(20001)).toBe(true);
+        expect(isEphemeralKind(25000)).toBe(true);
+        expect(isEphemeralKind(29999)).toBe(true);
+    });
+
+    it("should return false for kinds outside the ephemeral range", () => {
+        expect(isEphemeralKind(0)).toBe(false);
+        expect(isEphemeralKind(1)).toBe(false);
+        expect(isEphemeralKind(19999)).toBe(false);
+        expect(isEphemeralKind(30000)).toBe(false);
+        expect(isEphemeralKind(10002)).toBe(false);
+    });
+});
+
+describe("filterEphemeralKindsFromFilter", () => {
+    it("should return the original filter if no kinds are specified", () => {
+        const filter: NDKFilter = { authors: ["pubkey1"] };
+        const result = filterEphemeralKindsFromFilter(filter);
+        expect(result).toEqual(filter);
+    });
+
+    it("should return the original filter if no ephemeral kinds are present", () => {
+        const filter: NDKFilter = { kinds: [1, 3, 10002], authors: ["pubkey1"] };
+        const result = filterEphemeralKindsFromFilter(filter);
+        expect(result).toEqual(filter);
+    });
+
+    it("should filter out ephemeral kinds while keeping non-ephemeral ones", () => {
+        const filter: NDKFilter = { kinds: [1, 20001, 3, 25000], authors: ["pubkey1"] };
+        const result = filterEphemeralKindsFromFilter(filter);
+        expect(result).toEqual({ kinds: [1, 3], authors: ["pubkey1"] });
+    });
+
+    it("should return null if all kinds are ephemeral", () => {
+        const filter: NDKFilter = { kinds: [20000, 20001, 25000], authors: ["pubkey1"] };
+        const result = filterEphemeralKindsFromFilter(filter);
+        expect(result).toBeNull();
+    });
+
+    it("should return null for filters with only ephemeral kinds (edge case: exactly 20000)", () => {
+        const filter: NDKFilter = { kinds: [20000] };
+        const result = filterEphemeralKindsFromFilter(filter);
+        expect(result).toBeNull();
+    });
+
+    it("should return null for filters with only ephemeral kinds (edge case: exactly 29999)", () => {
+        const filter: NDKFilter = { kinds: [29999] };
+        const result = filterEphemeralKindsFromFilter(filter);
+        expect(result).toBeNull();
+    });
+});
+
+describe("filterForCache", () => {
+    // Create a minimal mock subscription
+    const createMockSubscription = (filters: NDKFilter[], cacheUnconstrainFilter?: string[]): NDKSubscription => ({
+        filters,
+        cacheUnconstrainFilter,
+    } as unknown as NDKSubscription);
+
+    it("should remove ephemeral kinds from filters", () => {
+        const subscription = createMockSubscription([
+            { kinds: [1, 20001], authors: ["pubkey1"] },
+        ]);
+        const result = filterForCache(subscription);
+        expect(result).toEqual([{ kinds: [1], authors: ["pubkey1"] }]);
+    });
+
+    it("should remove filters where all kinds are ephemeral", () => {
+        const subscription = createMockSubscription([
+            { kinds: [20001, 25000], authors: ["pubkey1"] },
+            { kinds: [1, 3], authors: ["pubkey2"] },
+        ]);
+        const result = filterForCache(subscription);
+        expect(result).toEqual([{ kinds: [1, 3], authors: ["pubkey2"] }]);
+    });
+
+    it("should return empty array if all filters only have ephemeral kinds", () => {
+        const subscription = createMockSubscription([
+            { kinds: [20001], authors: ["pubkey1"] },
+            { kinds: [25000], authors: ["pubkey2"] },
+        ]);
+        const result = filterForCache(subscription);
+        expect(result).toEqual([]);
+    });
+
+    it("should handle cacheUnconstrainFilter by removing specified keys", () => {
+        const subscription = createMockSubscription(
+            [{ kinds: [1], authors: ["pubkey1"], limit: 10, since: 1234567890 }],
+            ["limit", "since"]
+        );
+        const result = filterForCache(subscription);
+        expect(result).toEqual([{ kinds: [1], authors: ["pubkey1"] }]);
+    });
+
+    it("should handle both cacheUnconstrainFilter and ephemeral filtering", () => {
+        const subscription = createMockSubscription(
+            [{ kinds: [1, 20001], authors: ["pubkey1"], limit: 10 }],
+            ["limit"]
+        );
+        const result = filterForCache(subscription);
+        expect(result).toEqual([{ kinds: [1], authors: ["pubkey1"] }]);
+    });
+
+    it("should not break filters without kinds specified", () => {
+        const subscription = createMockSubscription([
+            { authors: ["pubkey1"] },
+            { ids: ["eventid1"] },
+        ]);
+        const result = filterForCache(subscription);
+        expect(result).toEqual([
+            { authors: ["pubkey1"] },
+            { ids: ["eventid1"] },
+        ]);
+    });
+
+    it("should handle empty kinds array", () => {
+        const subscription = createMockSubscription([
+            { kinds: [], authors: ["pubkey1"] },
+        ]);
+        const result = filterForCache(subscription);
+        expect(result).toEqual([{ kinds: [], authors: ["pubkey1"] }]);
+    });
+
+    it("should filter out filters that become empty after cacheUnconstrainFilter", () => {
+        const subscription = createMockSubscription(
+            [{ limit: 10 }],
+            ["limit"]
+        );
+        const result = filterForCache(subscription);
+        expect(result).toEqual([]);
+    });
+});

core/src/cache/filter.test.ts

@@ -0,0 +1,78 @@
+import type { NDKFilter, NDKSubscription } from "../subscription/index.js";
+
+/**
+ * Checks if a kind is ephemeral (20000-29999 range).
+ * Ephemeral events are not stored in cache, so there's no point querying for them.
+ */
+export function isEphemeralKind(kind: number): boolean {
+    return kind >= 20000 && kind < 30000;
+}
+
+/**
+ * Filters out ephemeral kinds from a filter's kinds array.
+ * Returns null if the filter had kinds but all were ephemeral (meaning the filter should be skipped entirely).
+ * Returns the original filter if no kinds were specified (don't break REQs without kind filters).
+ * Returns a new filter with non-ephemeral kinds if some kinds were valid.
+ */
+export function filterEphemeralKindsFromFilter(filter: NDKFilter): NDKFilter | null {
+    // If no kinds are specified, return the filter as-is
+    // (we don't want to break REQs that don't specify kinds)
+    if (!filter.kinds || filter.kinds.length === 0) {
+        return filter;
+    }
+
+    // Filter out ephemeral kinds
+    const nonEphemeralKinds = filter.kinds.filter((kind) => !isEphemeralKind(kind));
+
+    // If all kinds were ephemeral, return null to skip this filter entirely
+    if (nonEphemeralKinds.length === 0) {
+        return null;
+    }
+
+    // If no kinds were filtered out, return the original filter
+    if (nonEphemeralKinds.length === filter.kinds.length) {
+        return filter;
+    }
+
+    // Return a new filter with only non-ephemeral kinds
+    return {
+        ...filter,
+        kinds: nonEphemeralKinds,
+    };
+}
+
+/**
+ * Processes filters for cache queries by:
+ * 1. Removing constrained fields (limit, since, until) if cacheUnconstrainFilter is set
+ * 2. Filtering out ephemeral kinds (20000-29999) since they're never cached
+ *
+ * Returns an empty array if all filters should be skipped (all kinds were ephemeral).
+ */
+export function filterForCache(subscription: NDKSubscription): NDKFilter[] {
+    let filters = subscription.filters;
+
+    // First, handle cacheUnconstrainFilter if set
+    if (subscription.cacheUnconstrainFilter) {
+        filters = filters.map((filter) => {
+            const filterCopy = { ...filter };
+            for (const key of subscription.cacheUnconstrainFilter!) {
+                delete (filterCopy as Record<string, unknown>)[key];
+            }
+            return filterCopy;
+        });
+        // Remove filters that became empty after removing constrained keys
+        filters = filters.filter((filter) => Object.keys(filter).length > 0);
+    }
+
+    // Then, filter out ephemeral kinds
+    const processedFilters: NDKFilter[] = [];
+
+    for (const filter of filters) {
+        const processed = filterEphemeralKindsFromFilter(filter);
+        if (processed !== null) {
+            processedFilters.push(processed);
+        }
+    }
+
+    return processedFilters;
+}

core/src/cache/filter.ts

@@ -8,6 +8,9 @@ import type { Hexpubkey, ProfilePointer } from "../user/index.js";
 import type { NDKUserProfile } from "../user/profile.js";
 import type { NDKLnUrlData } from "../zapper/ln.js";
 
+// Export filter utilities for cache adapters
+export { filterForCache, filterEphemeralKindsFromFilter, isEphemeralKind } from "./filter.js";
+
 export type NDKCacheEntry<T> = T & {
     cachedAt?: number;
 };

core/src/cache/index.ts

@@ -517,13 +517,14 @@ export class NDKSubscription extends EventEmitter<{
     }
 
     private shouldQueryCache(): boolean {
-        if (this.opts.addSinceFromCache) return true;
-
         // explicitly told to not query the cache
         if (this.opts?.cacheUsage === NDKSubscriptionCacheUsage.ONLY_RELAY) return false;
 
-        const hasNonEphemeralKind = this.filters.some((f) => f.kinds?.some((k) => kindIsEphemeral(k)));
-        if (hasNonEphemeralKind) return true;
+        // If all filters contain only ephemeral kinds, don't query cache
+        const allFiltersEphemeralOnly = this.filters.every((f) =>
+            f.kinds && f.kinds.length > 0 && f.kinds.every((k) => kindIsEphemeral(k))
+        );
+        if (allFiltersEphemeralOnly) return false;
 
         return true;
     }