GraphQL IDBLink

The foundation of our caching layer is a set of low-level IndexedDB operations. These utilities handle database connection, data storage, retrieval, and expiration checking.

Configuration Constants

First, we define our database configuration and scheduler priorities:

// index-db/constants.ts
export const DB_NAME = 'app-idb';
export const STORE_NAME = 'apollo-cache';
export const DEFAULT_TTL = 2 * 60; // 2 minutes default

// Prioritize cache writes as background tasks
export const IDB_SET_POST_TASK = {
  priority: 'background',
};

// Prioritize cache reads as user-visible tasks
export const IDB_GET_POST_TASK = {
  priority: 'user-visible',
};

Database Operations

The core IndexedDB module provides connection pooling, TTL-based expiration, and SSR-aware cache invalidation through the markSSRHydration() function.

// index-db/index.ts
import { DB_NAME, DEFAULT_TTL, STORE_NAME, IDB_SET_POST_TASK, IDB_GET_POST_TASK } from './constants';

let storage: IDBDatabase | null = null;

interface IDBStoredValue<T> {
  value: T;
  timestamp: number;
}

// Track SSR hydration timestamp for cache invalidation
let lastSSRHydrationTimestamp = 0;

export function markSSRHydration(): void {
  lastSSRHydrationTimestamp = Date.now();
}

/**
 * Check if IndexedDB is supported and enabled
 */
export function isSupported(): boolean {
  if (typeof window === 'undefined') {
    return false;
  }
  return 'indexedDB' in window;
}

/**
 * Check if cached data has expired
 */
function checkExpired(createdAt: number, ttl: number) {
  const minuteToMs = ttl * 60 * 1000;
  const now = new Date().getTime();
  const expiredTime = createdAt + minuteToMs;

  // If SSR hydration happened after cache entry was written, treat as expired
  if (lastSSRHydrationTimestamp > 0 && createdAt < lastSSRHydrationTimestamp) {
    return true;
  }

  return expiredTime <= now;
}

/**
 * Connect to IndexedDB database
 */
function connect(): Promise<IDBDatabase> {
  if (!isSupported()) {
    return Promise.reject(new Error('[IDBLink] IndexedDB is not supported'));
  }

  if (storage) {
    return Promise.resolve(storage);
  }

  const open = indexedDB.open(DB_NAME);

  // Create object store on first run or version upgrade
  open.onupgradeneeded = () => {
    const store = open.result.createObjectStore(STORE_NAME);
    store.createIndex('timestamp', 'timestamp');
  };

  return new Promise((resolve, reject) => {
    open.onsuccess = () => {
      storage = open.result;
      resolve(open.result);
    };
    open.onerror = () => {
      console.error('[IDBLink] request error: ', open.error);
      reject(open.error);
    };
  });
}

/**
 * Store data in IndexedDB with background priority
 */
export async function set<T = Record<string, unknown>>(
  key: string,
  value: T
): Promise<void> {
  const task = async () => {
    const db = await connect();
    const now = new Date();
    const timestamp = now.getTime();

    const transaction = db.transaction(STORE_NAME, 'readwrite');
    const objectStore = transaction.objectStore(STORE_NAME);
    objectStore.put({ value, timestamp }, key);

    return new Promise<void>((resolve, reject) => {
      transaction.oncomplete = () => resolve();
      transaction.onerror = () => {
        console.error(`[IDBLink] failed to store value with key ${key}:`, transaction.error);
        reject(transaction.error);
      };
    });
  };

  // Use scheduler.postTask if available for background priority
  if ('scheduler' in window) {
    return (window as any).scheduler.postTask(task, IDB_SET_POST_TASK);
  }
  return task();
}

/**
 * Retrieve data from IndexedDB with user-visible priority
 */
export async function get<T = Record<string, unknown>>(
  key: string
): Promise<IDBStoredValue<T>> {
  const task = async () => {
    const db = await connect();
    const transaction = db.transaction(STORE_NAME, 'readonly');
    const objectStore = transaction.objectStore(STORE_NAME);
    const request = objectStore.get(key);

    return new Promise<IDBStoredValue<T>>((resolve, reject) => {
      transaction.oncomplete = () => resolve(request.result);
      transaction.onerror = () => reject(transaction.error);
    });
  };

  if ('scheduler' in window) {
    return (window as any).scheduler.postTask(task, IDB_GET_POST_TASK);
  }
  return task();
}

/**
 * Check if key exists and hasn't expired
 */
export async function has(key: string, ttl = DEFAULT_TTL): Promise<boolean> {
  const task = async () => {
    const db = await connect();
    const transaction = db.transaction(STORE_NAME, 'readwrite');
    const objectStore = transaction.objectStore(STORE_NAME);
    const request = objectStore.openCursor(key);

    return new Promise<boolean>((resolve, reject) => {
      request.onsuccess = (event: Event) => {
        const cursor = (event.target as IDBRequest).result as IDBCursorWithValue;
        const isExist = Boolean(cursor);

        if (!isExist) {
          return resolve(false);
        }

        const createdAt = cursor?.value?.timestamp ?? 0;
        const isExpired = checkExpired(createdAt, ttl);

        if (isExpired) {
          cursor.delete(); // Clean up expired entries
          resolve(false);
        } else {
          resolve(true);
        }
      };

      request.onerror = () => reject(request.error);
    });
  };

  if ('scheduler' in window) {
    return (window as any).scheduler.postTask(task);
  }
  return task();
}