@signalium/query 0.0.1 → 0.0.2

package/src/QueryClient.ts

@@ -11,18 +11,16 @@
  * - Self-contained validator (no external dependencies except Signalium)
  */
 
-import {
-  relay,
-  type RelayState,
-  context,
-  DiscriminatedReactivePromise,
-  type Context,
-  notifier,
-  Notifier,
-  Signal,
-} from 'signalium';
+import { relay, type RelayState, context, DiscriminatedReactivePromise, type Context, Signal, signal } from 'signalium';
 import { hashValue, setReactivePromise } from 'signalium/utils';
-import { DiscriminatedQueryResult, EntityDef, QueryResult, ObjectFieldTypeDef, ComplexTypeDef } from './types.js';
+import {
+  DiscriminatedQueryResult,
+  EntityDef,
+  QueryResult,
+  ObjectFieldTypeDef,
+  ComplexTypeDef,
+  RefetchInterval,
+} from './types.js';
 import { parseValue } from './proxy.js';
 import { parseEntities } from './parseEntities.js';
 import { EntityRecord, EntityStore } from './EntityMap.js';
@@ -31,11 +29,15 @@ import { ValidatorDef } from './typeDefs.js';
 
 export interface QueryContext {
   fetch: typeof fetch;
+  evictionMultiplier?: number;
+  refetchMultiplier?: number;
 }
 
 export interface QueryCacheOptions {
   maxCount?: number;
-  maxAge?: number; // milliseconds
+  gcTime?: number; // milliseconds - only applies to on-disk/persistent storage cleanup
+  staleTime?: number;
+  refetchInterval?: RefetchInterval;
 }
 
 export interface QueryDefinition<Params, Result> {
@@ -43,35 +45,203 @@ export interface QueryDefinition<Params, Result> {
   shape: ObjectFieldTypeDef;
   fetchFn: (context: QueryContext, params: Params) => Promise<Result>;
 
-  staleTime?: number;
-  refetchInterval?: number;
-
   cache?: QueryCacheOptions;
 }
 
-interface QueryInstance<T> {
-  relay: QueryResultImpl<T>;
-  initialized: boolean;
-  notifier: Notifier;
-}
+// QueryInstance is now merged into QueryResultImpl below
 
 const queryKeyFor = (queryDef: QueryDefinition<any, any>, params: unknown): number => {
   return hashValue([queryDef.id, params]);
 };
 
+const BASE_TICK_INTERVAL = 1000; // 1 second
+
+// Refetch interval manager - uses a fixed 1-second tick
+class RefetchManager {
+  private intervalId: NodeJS.Timeout;
+  private clock: number = 0; // Increments by 1000ms on each tick
+
+  // Buckets: Map of actual interval -> Set of query instances
+  private buckets = new Map<number, Set<QueryResultImpl<any>>>();
+
+  constructor(private multiplier: number = 1) {
+    // Start the timer immediately and keep it running
+    const tickInterval = BASE_TICK_INTERVAL * this.multiplier;
+    this.intervalId = setTimeout(() => this.tick(), tickInterval);
+  }
+
+  addQuery(instance: QueryResultImpl<any>) {
+    const interval = instance.def.cache?.refetchInterval;
+
+    if (!interval) {
+      return;
+    }
+
+    const actualInterval = interval * this.multiplier;
+    // Add to bucket by actual interval
+    let bucket = this.buckets.get(actualInterval);
+    if (!bucket) {
+      bucket = new Set();
+      this.buckets.set(actualInterval, bucket);
+    }
+    bucket.add(instance);
+  }
+
+  removeQuery(query: QueryResultImpl<any>) {
+    const interval = query.def.cache?.refetchInterval;
+
+    if (!interval) {
+      return;
+    }
+
+    const actualInterval = interval * this.multiplier;
+    // Remove from bucket
+    const bucket = this.buckets.get(actualInterval);
+    if (bucket) {
+      bucket.delete(query);
+
+      if (bucket.size === 0) {
+        this.buckets.delete(actualInterval);
+      }
+    }
+  }
+
+  private tick() {
+    this.clock += BASE_TICK_INTERVAL * this.multiplier;
+
+    // Only process buckets where clock is aligned with the interval
+    for (const [interval, bucket] of this.buckets.entries()) {
+      if (this.clock % interval === 0) {
+        // Process all queries in this bucket
+        for (const query of bucket) {
+          // Skip if already fetching - let the current fetch complete
+          if (query && !query.isFetching) {
+            query.refetch();
+          }
+        }
+      }
+    }
+
+    const tickInterval = BASE_TICK_INTERVAL * this.multiplier;
+    this.intervalId = setTimeout(() => this.tick(), tickInterval);
+  }
+
+  destroy(): void {
+    clearTimeout(this.intervalId);
+  }
+}
+
+const EVICTION_INTERVAL = 60 * 1000; // 1 minute
+
+// Memory eviction manager - uses a single interval with rotating sets to avoid timeout overhead
+class MemoryEvictionManager {
+  private intervalId: NodeJS.Timeout;
+  private currentFlush = new Set<number>(); // Queries to evict on next tick
+  private nextFlush = new Set<number>(); // Queries to evict on tick after next
+
+  constructor(
+    private queryClient: QueryClient,
+    private multiplier: number = 1,
+  ) {
+    this.intervalId = setInterval(this.tick, EVICTION_INTERVAL * this.multiplier);
+  }
+
+  scheduleEviction(queryKey: number) {
+    // Add to nextFlush so it waits at least one full interval
+    // This prevents immediate eviction if scheduled right before a tick
+    this.nextFlush.add(queryKey);
+  }
+
+  cancelEviction(queryKey: number) {
+    // Remove from both sets to handle reactivation
+    this.currentFlush.delete(queryKey);
+    this.nextFlush.delete(queryKey);
+  }
+
+  private tick = () => {
+    if (!this.queryClient) return;
+
+    // Evict all queries in currentFlush
+    for (const queryKey of this.currentFlush) {
+      this.queryClient.queryInstances.delete(queryKey);
+    }
+
+    // Rotate: currentFlush becomes nextFlush, nextFlush becomes empty
+    this.currentFlush = this.nextFlush;
+    this.nextFlush = new Set();
+  };
+
+  destroy(): void {
+    clearInterval(this.intervalId);
+  }
+}
+
 /**
  * QueryResult wraps a DiscriminatedReactivePromise and adds additional functionality
  * like refetch, while forwarding all the base relay properties.
+ * This class combines the old QueryInstance and QueryResultImpl into a single entity.
  */
 export class QueryResultImpl<T> implements QueryResult<T> {
-  constructor(
-    private relay: DiscriminatedReactivePromise<T>,
-    private instance: QueryInstance<T>,
-  ) {
+  // Fields from old QueryInstance
+  def: QueryDefinition<any, any>;
+  initialized: boolean = false;
+  isRefetchingSignal: Signal<boolean>;
+  updatedAt: number | undefined = undefined;
+
+  // References for refetch functionality
+  private queryClient: QueryClient;
+  queryKey: number;
+  private params: any;
+  private relay: DiscriminatedReactivePromise<T>;
+  private relayState: RelayState<any> | undefined = undefined;
+
+  constructor(def: QueryDefinition<any, any>, queryClient: QueryClient, queryKey: number, params: any) {
     setReactivePromise(this);
+    this.def = def;
+    this.queryClient = queryClient;
+    this.queryKey = queryKey;
+    this.params = params;
+    this.isRefetchingSignal = signal(false);
+
+    // Create the relay and handle activation/deactivation
+    this.relay = relay<T>(
+      state => {
+        this.relayState = state;
+        // Load from cache first, then fetch fresh data
+        this.queryClient.activateQuery(this);
+
+        if (this.initialized) {
+          if (this.isStale()) {
+            this.refetch();
+          }
+        } else {
+          this.initialize(state as RelayState<unknown>);
+        }
+
+        // Return deactivation callback
+        return {
+          update: () => {
+            state.setPromise(this.runQuery());
+          },
+          deactivate: () => {
+            // Last subscriber left, deactivate refetch and schedule memory eviction
+            if (this.def.cache?.refetchInterval) {
+              this.queryClient.refetchManager.removeQuery(this);
+            }
+
+            // Schedule removal from memory using the global eviction manager
+            // This allows quick reactivation from memory if needed again soon
+            // Disk cache (if configured) will still be available after eviction
+            this.queryClient.memoryEvictionManager.scheduleEviction(this.queryKey);
+          },
+        };
+      },
+      // {
+      //   equals: false,
+      // },
+    ) as DiscriminatedReactivePromise<T>;
   }
 
-  // Forward all ReactivePromise properties through getters
   get value(): T | undefined {
     return this.relay.value;
   }
@@ -100,9 +270,17 @@ export class QueryResultImpl<T> implements QueryResult<T> {
     return this.relay.isReady;
   }
 
+  get isRefetching(): boolean {
+    return this.isRefetchingSignal.value;
+  }
+
+  get isFetching(): boolean {
+    return this.relay.isPending || this.isRefetching;
+  }
+
   // TODO: Intimate APIs needed for `useReactive`, this is a code smell and
   // we should find a better way to entangle these more generically
-  private get _version(): Promise<T> {
+  private get _version(): Signal<number> {
     return (this.relay as any)._version;
   }
 
@@ -133,121 +311,154 @@ export class QueryResultImpl<T> implements QueryResult<T> {
   }
 
   // Additional methods
-  refetch(): Promise<T> {
-    this.instance.notifier.notify();
-    // pull the value to make sure the relay is activated
-    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-    this.instance.relay.value;
-    return this.relay;
-  }
+  async refetch(): Promise<T> {
+    this.isRefetchingSignal.value = true;
 
-  // Make it work with Symbol.toStringTag for Promise detection
-  get [Symbol.toStringTag](): string {
-    return 'QueryResult';
-  }
-}
+    try {
+      const result = await this.runQuery();
 
-export class QueryClient {
-  private entityMap = new EntityStore();
-  private queryInstances = new Map<number, QueryInstance<unknown>>();
+      if (this.relayState) {
+        this.relayState.value = result;
 
-  constructor(
-    private store: QueryStore,
-    private context: QueryContext = { fetch },
-  ) {}
+        // Update the version to trigger a re-render for direct React consumers
+        // e.g. `useReactive(query, params)`
+        this._version.update(v => v + 1);
+      }
+
+      return result;
+    } finally {
+      this.isRefetchingSignal.value = false;
+    }
+  }
 
   /**
-   * Loads a query from the document store and returns a QueryResult
-   * that triggers fetches and prepopulates with cached data
+   * Fetches fresh data, updates the cache, and updates updatedAt timestamp
    */
-  getQuery<Params, Result>(
-    queryDef: QueryDefinition<Params, Result>,
-    params: Params,
-  ): DiscriminatedQueryResult<Result> {
-    const queryKey = queryKeyFor(queryDef, params);
+  async runQuery(): Promise<T> {
+    const freshData = await this.def.fetchFn(this.queryClient.getContext(), this.params);
 
-    let queryInstance = this.queryInstances.get(queryKey);
-
-    // Create a new relay if it doesn't exist
-    if (queryInstance === undefined) {
-      queryInstance = {
-        relay: undefined as any,
-        initialized: false,
-        notifier: notifier(),
-      };
+    // Parse and cache the fresh data
+    const entityRefs = new Set<number>();
+    const shape = this.def.shape;
 
-      const queryRelay = relay<Result>(state => {
-        // Load from cache first, then fetch fresh data
-        queryInstance!.notifier.consume();
+    const parsedData =
+      shape instanceof ValidatorDef
+        ? parseEntities(freshData, shape as ComplexTypeDef, this.queryClient, entityRefs)
+        : parseValue(freshData, shape, this.def.id);
 
-        this.store.activateQuery(queryDef, queryKey);
+    // Cache the data (synchronous, fire-and-forget)
+    this.queryClient.saveQueryData(this.def, this.queryKey, freshData, entityRefs);
 
-        if (queryInstance!.initialized) {
-          state.setPromise(this.runQuery(queryDef, queryKey, params));
-        } else {
-          this.initializeQuery(queryDef, params, state as RelayState<unknown>, queryInstance as QueryInstance<Result>);
-        }
-      });
+    // Update the timestamp
+    this.updatedAt = Date.now();
 
-      queryInstance.relay = new QueryResultImpl(queryRelay as DiscriminatedReactivePromise<Result>, queryInstance);
+    return parsedData as T;
+  }
 
-      // Store the relay for future use
-      this.queryInstances.set(queryKey, queryInstance);
+  isStale(): boolean {
+    if (this.updatedAt === undefined) {
+      return true; // No data yet, needs fetch
     }
 
-    return queryInstance.relay as DiscriminatedQueryResult<Result>;
+    const staleTime = this.def.cache?.staleTime ?? 0;
+    return Date.now() - this.updatedAt >= staleTime;
   }
 
-  private async initializeQuery<Params, Result>(
-    queryDef: QueryDefinition<Params, Result>,
-    params: Params,
-    state: RelayState<unknown>,
-    instance: QueryInstance<Result>,
-  ): Promise<void> {
+  /**
+   * Initialize the query by loading from cache and fetching if stale
+   */
+  private async initialize(state: RelayState<unknown>): Promise<void> {
     try {
-      instance.initialized = true;
-      const queryKey = queryKeyFor(queryDef, params);
+      this.initialized = true;
       // Load from cache first
-      const query = this.store.loadQuery(queryDef, queryKey, this.entityMap);
+      const cached = await this.queryClient.loadCachedQuery(this.def, this.queryKey);
 
-      if (query !== undefined) {
-        const shape = queryDef.shape;
+      if (cached !== undefined) {
+        const shape = this.def.shape;
         state.value =
           shape instanceof ValidatorDef
-            ? parseEntities(query, shape as ComplexTypeDef, this, new Set())
-            : parseValue(query, shape, queryDef.id);
-      }
+            ? parseEntities(cached.value, shape as ComplexTypeDef, this.queryClient, new Set())
+            : parseValue(cached.value, shape, this.def.id);
 
-      state.setPromise(this.runQuery(queryDef, queryKey, params));
+        // Set the cached timestamp
+        this.updatedAt = cached.updatedAt;
+
+        // Check if data is stale
+        if (this.isStale()) {
+          // Data is stale, trigger background refetch
+          this.refetch();
+        }
+      } else {
+        // No cached data, fetch fresh
+        state.setPromise(this.runQuery());
+      }
     } catch (error) {
       // Relay will handle the error state automatically
       state.setError(error as Error);
     }
   }
 
+  // Make it work with Symbol.toStringTag for Promise detection
+  get [Symbol.toStringTag](): string {
+    return 'QueryResult';
+  }
+}
+
+export class QueryClient {
+  private entityMap = new EntityStore();
+  queryInstances = new Map<number, QueryResultImpl<unknown>>();
+  memoryEvictionManager: MemoryEvictionManager;
+  refetchManager: RefetchManager;
+
+  constructor(
+    private store: QueryStore,
+    private context: QueryContext = { fetch },
+  ) {
+    this.memoryEvictionManager = new MemoryEvictionManager(this, this.context.evictionMultiplier);
+    this.refetchManager = new RefetchManager(this.context.refetchMultiplier);
+  }
+
+  getContext(): QueryContext {
+    return this.context;
+  }
+
+  saveQueryData(queryDef: QueryDefinition<any, any>, queryKey: number, data: unknown, entityRefs: Set<number>): void {
+    this.store.saveQuery(queryDef, queryKey, data, entityRefs);
+  }
+
+  activateQuery(queryInstance: QueryResultImpl<unknown>): void {
+    const { def, queryKey } = queryInstance;
+    this.store.activateQuery(def, queryKey);
+
+    this.refetchManager.addQuery(queryInstance);
+    this.memoryEvictionManager.cancelEviction(queryKey);
+  }
+
+  loadCachedQuery(queryDef: QueryDefinition<any, any>, queryKey: number) {
+    return this.store.loadQuery(queryDef, queryKey, this.entityMap);
+  }
+
   /**
-   * Fetches fresh data and updates the cache
+   * Loads a query from the document store and returns a QueryResult
+   * that triggers fetches and prepopulates with cached data
    */
-  private async runQuery<Params, Result>(
+  getQuery<Params, Result>(
     queryDef: QueryDefinition<Params, Result>,
-    queryKey: number,
     params: Params,
-  ): Promise<Result> {
-    const freshData = await queryDef.fetchFn(this.context, params);
-    // Parse and cache the fresh data
-    const entityRefs = new Set<number>();
+  ): DiscriminatedQueryResult<Result> {
+    const queryKey = queryKeyFor(queryDef, params);
 
-    const shape = queryDef.shape;
+    let queryInstance = this.queryInstances.get(queryKey) as QueryResultImpl<Result> | undefined;
 
-    const parsedData =
-      shape instanceof ValidatorDef
-        ? parseEntities(freshData, shape as ComplexTypeDef, this, entityRefs)
-        : parseValue(freshData, shape, queryDef.id);
+    // Create a new instance if it doesn't exist
+    if (queryInstance === undefined) {
+      queryInstance = new QueryResultImpl(queryDef, this, queryKey, params);
 
-    // Cache the data (synchronous, fire-and-forget)
-    this.store.saveQuery(queryDef, queryKey, freshData, entityRefs);
+      // Store for future use
+      this.queryInstances.set(queryKey, queryInstance as QueryResultImpl<unknown>);
+    }
 
-    return parsedData as Result;
+    return queryInstance as DiscriminatedQueryResult<Result>;
   }
 
   hydrateEntity(key: number, shape: EntityDef): EntityRecord {
@@ -261,6 +472,11 @@ export class QueryClient {
 
     return record;
   }
+
+  destroy(): void {
+    this.refetchManager.destroy();
+    this.memoryEvictionManager.destroy();
+  }
 }
 
 export const QueryClientContext: Context<QueryClient | undefined> = context<QueryClient | undefined>(undefined);

package/src/QueryStore.ts

@@ -13,6 +13,11 @@ import { QueryDefinition } from './QueryClient.js';
 // QueryStore Interface
 // -----------------------------------------------------------------------------
 
+export interface CachedQuery {
+  value: unknown;
+  updatedAt: number;
+}
+
 export interface QueryStore {
   /**
    * Asynchronously retrieves a document by key.
@@ -22,7 +27,7 @@ export interface QueryStore {
     queryDef: QueryDefinition<any, any>,
     queryKey: number,
     entityMap: EntityStore,
-  ): MaybePromise<unknown | undefined>;
+  ): MaybePromise<CachedQuery | undefined>;
 
   /**
    * Synchronously stores a document with optional reference IDs.
@@ -61,7 +66,7 @@ export interface SyncPersistentStore {
 }
 
 const DEFAULT_MAX_COUNT = 50;
-const DEFAULT_MAX_AGE = 1000 * 60 * 60 * 24; // 24 hours
+const DEFAULT_GC_TIME = 1000 * 60 * 60 * 24; // 24 hours
 
 export class MemoryPersistentStore implements SyncPersistentStore {
   private readonly kv: Record<string, unknown> = Object.create(null);
@@ -113,16 +118,16 @@ export class SyncQueryStore implements QueryStore {
 
   constructor(private readonly kv: SyncPersistentStore) {}
 
-  loadQuery(queryDef: QueryDefinition<any, any>, queryKey: number, entityMap: EntityStore): unknown | undefined {
+  loadQuery(queryDef: QueryDefinition<any, any>, queryKey: number, entityMap: EntityStore): CachedQuery | undefined {
     const updatedAt = this.kv.getNumber(updatedAtKeyFor(queryKey));
 
-    if (updatedAt === undefined || updatedAt < Date.now() - (queryDef.cache?.maxAge ?? DEFAULT_MAX_AGE)) {
+    if (updatedAt === undefined || updatedAt < Date.now() - (queryDef.cache?.gcTime ?? DEFAULT_GC_TIME)) {
       return;
     }
 
-    const value = this.kv.getString(valueKeyFor(queryKey));
+    const valueStr = this.kv.getString(valueKeyFor(queryKey));
 
-    if (value === undefined) {
+    if (valueStr === undefined) {
       return;
     }
 
@@ -134,7 +139,10 @@ export class SyncQueryStore implements QueryStore {
 
     this.activateQuery(queryDef, queryKey);
 
-    return JSON.parse(value) as Record<string, unknown>;
+    return {
+      value: JSON.parse(valueStr) as Record<string, unknown>,
+      updatedAt,
+    };
   }
 
   private preloadEntities(entityIds: Uint32Array, entityMap: EntityStore): void {

package/src/__tests__/caching-persistence.test.ts

@@ -139,6 +139,7 @@ describe('Caching and Persistence', () => {
   let store: any;
 
   beforeEach(() => {
+    client?.destroy();
     kv = new MemoryPersistentStore();
     const queryStore = new SyncQueryStore(kv);
     mockFetch = createMockFetch();
@@ -199,8 +200,18 @@ describe('Caching and Persistence', () => {
 
         const result = await relay;
 
-        expect(result).toEqual({ id: 1, name: 'Fresh Data' });
+        // Immediate value should be the same as the cached value because we're
+        // background refetching but have a value that is still valid.
+        expect(result).toEqual({ id: 1, name: 'Cached Data' });
+        expect(relay.value).toEqual({ id: 1, name: 'Cached Data' });
+        expect(relay.isPending).toBe(false);
+        expect(relay.isRefetching).toBe(true);
+
+        await sleep(20);
+
+        expect(relay.isRefetching).toBe(false);
         expect(relay.value).toEqual({ id: 1, name: 'Fresh Data' });
+        expect(await relay).toEqual({ id: 1, name: 'Fresh Data' });
       });
     });
 
@@ -234,8 +245,17 @@ describe('Caching and Persistence', () => {
 
         const result = await relay;
 
-        expect(result).toEqual({ id: 1, value: 'New Data' });
+        // Immediate value should be the same as the cached value because we're
+        // background refetching but have a value that is still valid.
+        expect(result).toEqual({ id: 1, value: 'Persistent' });
+        expect(relay.value).toEqual({ id: 1, value: 'Persistent' });
+        expect(relay.isPending).toBe(false);
+        expect(relay.isRefetching).toBe(true);
+
+        await sleep(30);
+
         expect(relay.value).toEqual({ id: 1, value: 'New Data' });
+        expect(await relay).toEqual({ id: 1, value: 'New Data' });
       });
     });
   });
@@ -321,6 +341,15 @@ describe('Caching and Persistence', () => {
 
         const result = await relay;
 
+        // Immediate value should be the same as the cached value because we're
+        // background refetching but have a value that is still valid.
+        expect(result).toEqual({ user: { __typename: 'User', id: 1, name: 'Persisted User' } });
+        expect(relay.value).toEqual({ user: { __typename: 'User', id: 1, name: 'Persisted User' } });
+        expect(relay.isPending).toBe(false);
+        expect(relay.isRefetching).toBe(true);
+
+        await sleep(20);
+
         expect(result).toEqual({ user: { __typename: 'User', id: 1, name: 'Fresh User' } });
         expect(relay.value).toEqual({ user: { __typename: 'User', id: 1, name: 'Fresh User' } });
       });

package/src/__tests__/entity-system.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { SyncQueryStore, MemoryPersistentStore, refIdsKeyFor, refCountKeyFor } from '../QueryStore.js';
 import { QueryClient } from '../QueryClient.js';
 import { entity, t } from '../typeDefs.js';
@@ -26,6 +26,10 @@ describe('Entity System', () => {
     client = new QueryClient(store, { fetch: mockFetch as any });
   });
 
+  afterEach(() => {
+    client?.destroy();
+  });
+
   describe('Entity Proxies', () => {
     it('should create reactive entity proxies', async () => {
       const User = entity(() => ({