graphile-cache 2.0.0 → 3.0.0

package/README.md

@@ -1,32 +1,29 @@
 # graphile-cache
 
 <p align="center" width="100%">
-  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+  <img height="250" src="https://raw.githubusercontent.com/launchql/launchql/refs/heads/main/assets/outline-logo.svg" />
 </p>
 
 <p align="center" width="100%">
-  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
-    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
-  </a>
-  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE">
-    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
-  </a>
-  <a href="https://www.npmjs.com/package/graphile-cache">
-    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-cache%2Fpackage.json"/>
+  <a href="https://github.com/launchql/launchql/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/launchql/launchql/actions/workflows/run-tests.yaml/badge.svg" />
   </a>
+   <a href="https://github.com/launchql/launchql/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/graphile-cache"><img height="20" src="https://img.shields.io/github/package-json/v/launchql/launchql?filename=packages%2Fgraphile-cache%2Fpackage.json"/></a>
 </p>
 
-**`graphile-cache`** is an LRU cache for PostGraphile handlers with automatic cleanup when PostgreSQL pools are disposed.
 
-> This package integrates with `pg-cache` for PostgreSQL pool management.
+PostGraphile instance LRU cache with automatic cleanup when PostgreSQL pools are disposed.
 
-## 🚀 Installation
+## Installation
 
 ```bash
 npm install graphile-cache pg-cache
 ```
 
-## ✨ Features
+Note: This package depends on `pg-cache` for the PostgreSQL pool management.
+
+## Features
 
 - LRU cache for PostGraphile instances
 - Automatic cleanup when associated PostgreSQL pools are disposed
@@ -34,24 +31,26 @@ npm install graphile-cache pg-cache
 - Service cache re-exported for convenience
 - TypeScript support
 
-## 🧠 How It Works
+## How It Works
 
 When you import this package, it automatically registers a cleanup callback with `pg-cache`. When a PostgreSQL pool is disposed, any PostGraphile instances using that pool are automatically removed from the cache.
 
-## 📦 Usage
+## Usage
 
-### Basic caching flow
+### Basic Usage
 
 ```typescript
 import { graphileCache, GraphileCache } from 'graphile-cache';
 import { getPgPool } from 'pg-cache';
 import { postgraphile } from 'postgraphile';
 
+// Create a PostGraphile instance
 const pgPool = getPgPool({ database: 'mydb' });
 const handler = postgraphile(pgPool, 'public', {
   // PostGraphile options
 });
 
+// Cache it
 const cacheEntry: GraphileCache = {
   pgPool,
   pgPoolKey: 'mydb',
@@ -67,7 +66,7 @@ if (cached) {
 }
 ```
 
-### Automatic cleanup
+### Automatic Cleanup
 
 The cleanup happens automatically:
 
@@ -87,7 +86,7 @@ console.log(graphileCache.has('mydb.public')); // false
 console.log(graphileCache.has('mydb.private')); // false
 ```
 
-### Complete example with Express
+### Complete Example
 
 ```typescript
 import { graphileCache, GraphileCache } from 'graphile-cache';
@@ -96,13 +95,13 @@ import { postgraphile } from 'postgraphile';
 
 function getGraphileInstance(database: string, schema: string): GraphileCache {
   const key = `${database}.${schema}`;
-
+  
   // Check cache first
   const cached = graphileCache.get(key);
   if (cached) {
     return cached;
   }
-
+  
   // Create new instance
   const pgPool = getPgPool({ database });
   const handler = postgraphile(pgPool, schema, {
@@ -110,13 +109,13 @@ function getGraphileInstance(database: string, schema: string): GraphileCache {
     graphiqlRoute: '/graphiql',
     // other options...
   });
-
+  
   const entry: GraphileCache = {
     pgPool,
     pgPoolKey: database,
     handler
   };
-
+  
   // Cache it
   graphileCache.set(key, entry);
   return entry;
@@ -134,14 +133,14 @@ app.use((req, res, next) => {
 ```typescript
 import { closeAllCaches } from 'graphile-cache';
 
+// This closes all caches including pg pools
 process.on('SIGTERM', async () => {
-  // Closes all caches including pg pools
   await closeAllCaches();
   process.exit(0);
 });
 ```
 
-## 📘 API Reference
+## API Reference
 
 ### graphileCache
 
@@ -171,7 +170,7 @@ Closes all caches including the service cache, graphile cache, and all PostgreSQ
 
 Re-exported from `pg-cache` for convenience.
 
-## 🔌 Integration Details
+## Integration Details
 
 The integration with `pg-cache` happens automatically when this module is imported. The cleanup callback is registered immediately, ensuring that PostGraphile instances are cleaned up whenever their associated PostgreSQL pools are disposed.
 

package/create-instance.d.ts

@@ -0,0 +1,17 @@
+import type { GraphileCacheEntry } from './graphile-cache';
+interface GraphileInstanceOptions {
+    preset: any;
+    cacheKey: string;
+}
+/**
+ * Create a PostGraphile v5 instance backed by grafserv/express.
+ *
+ * This is the shared factory used by both graphql/server and graphql/explorer
+ * to spin up a fully-initialised PostGraphile handler that fits into the
+ * graphile-cache LRU cache.
+ *
+ * Callers are responsible for building the `GraphileConfig.Preset` (including
+ * pgServices, grafserv options, grafast context, etc.) before passing it here.
+ */
+export declare const createGraphileInstance: (opts: GraphileInstanceOptions) => Promise<GraphileCacheEntry>;
+export {};

package/create-instance.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGraphileInstance = void 0;
+const node_http_1 = require("node:http");
+const express_1 = __importDefault(require("express"));
+const postgraphile_1 = require("postgraphile");
+const v4_1 = require("grafserv/express/v4");
+/**
+ * Create a PostGraphile v5 instance backed by grafserv/express.
+ *
+ * This is the shared factory used by both graphql/server and graphql/explorer
+ * to spin up a fully-initialised PostGraphile handler that fits into the
+ * graphile-cache LRU cache.
+ *
+ * Callers are responsible for building the `GraphileConfig.Preset` (including
+ * pgServices, grafserv options, grafast context, etc.) before passing it here.
+ */
+const createGraphileInstance = async (opts) => {
+    const { preset, cacheKey } = opts;
+    const pgl = (0, postgraphile_1.postgraphile)(preset);
+    const serv = pgl.createServ(v4_1.grafserv);
+    const handler = (0, express_1.default)();
+    const httpServer = (0, node_http_1.createServer)(handler);
+    await serv.addTo(handler, httpServer);
+    await serv.ready();
+    return {
+        pgl,
+        serv,
+        handler,
+        httpServer,
+        cacheKey,
+        createdAt: Date.now(),
+    };
+};
+exports.createGraphileInstance = createGraphileInstance;

package/esm/create-instance.js

@@ -0,0 +1,31 @@
+import { createServer } from 'node:http';
+import express from 'express';
+import { postgraphile } from 'postgraphile';
+import { grafserv } from 'grafserv/express/v4';
+/**
+ * Create a PostGraphile v5 instance backed by grafserv/express.
+ *
+ * This is the shared factory used by both graphql/server and graphql/explorer
+ * to spin up a fully-initialised PostGraphile handler that fits into the
+ * graphile-cache LRU cache.
+ *
+ * Callers are responsible for building the `GraphileConfig.Preset` (including
+ * pgServices, grafserv options, grafast context, etc.) before passing it here.
+ */
+export const createGraphileInstance = async (opts) => {
+    const { preset, cacheKey } = opts;
+    const pgl = postgraphile(preset);
+    const serv = pgl.createServ(grafserv);
+    const handler = express();
+    const httpServer = createServer(handler);
+    await serv.addTo(handler, httpServer);
+    await serv.ready();
+    return {
+        pgl,
+        serv,
+        handler,
+        httpServer,
+        cacheKey,
+        createdAt: Date.now(),
+    };
+};

package/esm/graphile-cache.js

@@ -1,38 +1,194 @@
+import { EventEmitter } from 'events';
 import { Logger } from '@pgpmjs/logger';
 import { LRUCache } from 'lru-cache';
 import { pgCache } from 'pg-cache';
 const log = new Logger('graphile-cache');
-const ONE_HOUR_IN_MS = 1000 * 60 * 60;
-const ONE_DAY = ONE_HOUR_IN_MS * 24;
+// --- Time Constants ---
+export const ONE_HOUR_MS = 1000 * 60 * 60;
+export const FIVE_MINUTES_MS = 1000 * 60 * 5;
+const ONE_DAY = ONE_HOUR_MS * 24;
 const ONE_YEAR = ONE_DAY * 366;
+export class CacheEventEmitter extends EventEmitter {
+    emitEviction(event) {
+        this.emit('eviction', event);
+    }
+    onEviction(handler) {
+        this.on('eviction', handler);
+    }
+}
+export const cacheEvents = new CacheEventEmitter();
+/**
+ * Get cache configuration from environment variables
+ *
+ * Supports:
+ * - GRAPHILE_CACHE_MAX: Maximum number of entries (default: 15)
+ * - GRAPHILE_CACHE_TTL_MS: TTL in milliseconds
+ *   - Production default: ONE_YEAR
+ *   - Development default: FIVE_MINUTES_MS
+ */
+export function getCacheConfig() {
+    const isDevelopment = process.env.NODE_ENV === 'development';
+    const max = process.env.GRAPHILE_CACHE_MAX
+        ? parseInt(process.env.GRAPHILE_CACHE_MAX, 10)
+        : 15;
+    const ttl = process.env.GRAPHILE_CACHE_TTL_MS
+        ? parseInt(process.env.GRAPHILE_CACHE_TTL_MS, 10)
+        : isDevelopment
+            ? FIVE_MINUTES_MS
+            : ONE_YEAR;
+    return { max, ttl };
+}
+// Track disposed entries to prevent double-disposal
+const disposedKeys = new Set();
+// Track keys that are being manually evicted for accurate eviction reason
+const manualEvictionKeys = new Set();
+/**
+ * Dispose a PostGraphile v5 cache entry
+ *
+ * Properly releases resources by:
+ * 1. Closing the HTTP server if listening
+ * 2. Releasing the PostGraphile instance (which internally releases grafserv)
+ *
+ * Uses disposedKeys set to prevent double-disposal when closeAllCaches()
+ * explicitly disposes entries and then clear() triggers the dispose callback.
+ */
+const disposeEntry = async (entry, key) => {
+    // Prevent double-disposal
+    if (disposedKeys.has(key)) {
+        return;
+    }
+    disposedKeys.add(key);
+    log.debug(`Disposing PostGraphile[${key}]`);
+    try {
+        // Close HTTP server if it's listening
+        if (entry.httpServer?.listening) {
+            await new Promise((resolve) => {
+                entry.httpServer.close(() => resolve());
+            });
+        }
+        // Release PostGraphile instance (this also releases grafserv internally)
+        if (entry.pgl) {
+            await entry.pgl.release();
+        }
+    }
+    catch (err) {
+        log.error(`Error disposing PostGraphile[${key}]:`, err);
+    }
+};
+/**
+ * Determine the eviction reason for a cache entry
+ */
+const getEvictionReason = (key, entry) => {
+    if (manualEvictionKeys.has(key)) {
+        manualEvictionKeys.delete(key);
+        return 'manual';
+    }
+    // Check if TTL expired
+    const age = Date.now() - entry.createdAt;
+    const config = getCacheConfig();
+    if (age >= config.ttl) {
+        return 'ttl';
+    }
+    return 'lru';
+};
+// Get initial cache configuration
+const initialConfig = getCacheConfig();
 // --- Graphile Cache ---
 export const graphileCache = new LRUCache({
-    max: 15,
-    ttl: ONE_YEAR,
+    max: initialConfig.max,
+    ttl: initialConfig.ttl,
     updateAgeOnGet: true,
-    dispose: (_, key) => {
-        log.debug(`Disposing PostGraphile[${key}]`);
+    dispose: (entry, key) => {
+        // Determine eviction reason before disposal
+        const reason = getEvictionReason(key, entry);
+        // Emit eviction event
+        cacheEvents.emitEviction({ key, reason, entry });
+        log.debug(`Evicting PostGraphile[${key}] (reason: ${reason})`);
+        // LRU dispose is synchronous, but v5 disposal is async
+        // Fire and forget the async cleanup
+        disposeEntry(entry, key).catch((err) => {
+            log.error(`Failed to dispose PostGraphile[${key}]:`, err);
+        });
     }
 });
+/**
+ * Get current cache statistics
+ */
+export function getCacheStats() {
+    const config = getCacheConfig();
+    return {
+        size: graphileCache.size,
+        max: config.max,
+        ttl: config.ttl,
+        keys: [...graphileCache.keys()]
+    };
+}
+// --- Clear Matching Entries ---
+/**
+ * Clear cache entries matching a regex pattern
+ *
+ * @param pattern - RegExp to match against cache keys
+ * @returns Number of entries cleared
+ */
+export function clearMatchingEntries(pattern) {
+    let cleared = 0;
+    for (const key of graphileCache.keys()) {
+        if (pattern.test(key)) {
+            // Mark as manual eviction before deleting
+            manualEvictionKeys.add(key);
+            graphileCache.delete(key);
+            cleared++;
+        }
+    }
+    return cleared;
+}
 // Register cleanup callback with pgCache
 // When a pg pool is disposed, clean up any graphile instances using it
 const unregister = pgCache.registerCleanupCallback((pgPoolKey) => {
+    log.debug(`pgPool[${pgPoolKey}] disposed - checking graphile entries`);
+    // Remove graphile entries that reference this pool key
     graphileCache.forEach((entry, k) => {
-        if (entry.pgPoolKey === pgPoolKey) {
-            log.debug(`Removing graphileCache[${k}] due to pgPool[${pgPoolKey}]`);
+        if (entry.cacheKey.includes(pgPoolKey)) {
+            log.debug(`Removing graphileCache[${k}] due to pgPool[${pgPoolKey}] disposal`);
+            manualEvictionKeys.add(k);
             graphileCache.delete(k);
         }
     });
 });
 // Enhanced close function that handles all caches
 const closePromise = { promise: null };
+/**
+ * Close all caches and release resources
+ *
+ * This function:
+ * 1. Disposes all PostGraphile v5 instances (async)
+ * 2. Clears the graphile cache
+ * 3. Closes all pg pools via pgCache
+ *
+ * The function is idempotent - calling it multiple times
+ * returns the same promise.
+ */
 export const closeAllCaches = async (verbose = false) => {
     if (closePromise.promise)
         return closePromise.promise;
     closePromise.promise = (async () => {
         if (verbose)
             log.info('Closing all server caches...');
+        // Collect all entries and dispose them properly
+        const entries = [...graphileCache.entries()];
+        // Mark all as manual evictions
+        for (const [key] of entries) {
+            manualEvictionKeys.add(key);
+        }
+        const disposePromises = entries.map(([key, entry]) => disposeEntry(entry, key));
+        // Wait for all disposals to complete
+        await Promise.allSettled(disposePromises);
+        // Clear the cache after disposal (dispose callback will no-op due to disposedKeys)
         graphileCache.clear();
+        // Clear disposed keys tracking after full cleanup
+        disposedKeys.clear();
+        manualEvictionKeys.clear();
+        // Close pg pools
         await pgCache.close();
         if (verbose)
             log.success('All caches disposed.');

package/esm/index.js

@@ -1,2 +1,12 @@
 // Main exports from graphile-cache package
-export { closeAllCaches, graphileCache } from './graphile-cache';
+export { 
+// Cache instance and entry type
+graphileCache, closeAllCaches, 
+// Time constants
+ONE_HOUR_MS, FIVE_MINUTES_MS, 
+// Event emitter for cache events
+CacheEventEmitter, cacheEvents, getCacheConfig, getCacheStats, 
+// Clear matching entries
+clearMatchingEntries } from './graphile-cache';
+// Factory for creating PostGraphile v5 instances
+export { createGraphileInstance } from './create-instance';

package/graphile-cache.d.ts

@@ -1,10 +1,82 @@
+import { EventEmitter } from 'events';
 import { LRUCache } from 'lru-cache';
-import pg from 'pg';
-import { HttpRequestHandler } from 'postgraphile';
-export interface GraphileCache {
-    pgPool: pg.Pool;
-    pgPoolKey: string;
-    handler: HttpRequestHandler;
-}
-export declare const graphileCache: LRUCache<string, GraphileCache, unknown>;
+import type { Express } from 'express';
+import type { Server as HttpServer } from 'http';
+import type { PostGraphileInstance } from 'postgraphile';
+import type { GrafservBase } from 'grafserv';
+export declare const ONE_HOUR_MS: number;
+export declare const FIVE_MINUTES_MS: number;
+export type EvictionReason = 'lru' | 'ttl' | 'manual';
+export interface CacheEvictionEvent {
+    key: string;
+    reason: EvictionReason;
+    entry: GraphileCacheEntry;
+}
+export declare class CacheEventEmitter extends EventEmitter {
+    emitEviction(event: CacheEvictionEvent): void;
+    onEviction(handler: (event: CacheEvictionEvent) => void): void;
+}
+export declare const cacheEvents: CacheEventEmitter;
+export interface CacheConfig {
+    max: number;
+    ttl: number;
+}
+/**
+ * Get cache configuration from environment variables
+ *
+ * Supports:
+ * - GRAPHILE_CACHE_MAX: Maximum number of entries (default: 15)
+ * - GRAPHILE_CACHE_TTL_MS: TTL in milliseconds
+ *   - Production default: ONE_YEAR
+ *   - Development default: FIVE_MINUTES_MS
+ */
+export declare function getCacheConfig(): CacheConfig;
+/**
+ * Cache entry for PostGraphile v5 instances
+ *
+ * Each entry contains:
+ * - pgl: The PostGraphile instance (manages schema, plugins, etc.)
+ * - serv: The Grafserv server instance (handles HTTP/WS)
+ * - handler: Express app for routing requests
+ * - httpServer: Node HTTP server (required by grafserv)
+ * - cacheKey: Unique identifier for this entry
+ * - createdAt: Timestamp when this entry was created
+ */
+export interface GraphileCacheEntry {
+    pgl: PostGraphileInstance;
+    serv: GrafservBase;
+    handler: Express;
+    httpServer: HttpServer;
+    cacheKey: string;
+    createdAt: number;
+}
+export declare const graphileCache: LRUCache<string, GraphileCacheEntry, unknown>;
+export interface CacheStats {
+    size: number;
+    max: number;
+    ttl: number;
+    keys: string[];
+}
+/**
+ * Get current cache statistics
+ */
+export declare function getCacheStats(): CacheStats;
+/**
+ * Clear cache entries matching a regex pattern
+ *
+ * @param pattern - RegExp to match against cache keys
+ * @returns Number of entries cleared
+ */
+export declare function clearMatchingEntries(pattern: RegExp): number;
+/**
+ * Close all caches and release resources
+ *
+ * This function:
+ * 1. Disposes all PostGraphile v5 instances (async)
+ * 2. Clears the graphile cache
+ * 3. Closes all pg pools via pgCache
+ *
+ * The function is idempotent - calling it multiple times
+ * returns the same promise.
+ */
 export declare const closeAllCaches: (verbose?: boolean) => Promise<void>;

package/graphile-cache.js

@@ -1,41 +1,201 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.closeAllCaches = exports.graphileCache = void 0;
+exports.closeAllCaches = exports.graphileCache = exports.cacheEvents = exports.CacheEventEmitter = exports.FIVE_MINUTES_MS = exports.ONE_HOUR_MS = void 0;
+exports.getCacheConfig = getCacheConfig;
+exports.getCacheStats = getCacheStats;
+exports.clearMatchingEntries = clearMatchingEntries;
+const events_1 = require("events");
 const logger_1 = require("@pgpmjs/logger");
 const lru_cache_1 = require("lru-cache");
 const pg_cache_1 = require("pg-cache");
 const log = new logger_1.Logger('graphile-cache');
-const ONE_HOUR_IN_MS = 1000 * 60 * 60;
-const ONE_DAY = ONE_HOUR_IN_MS * 24;
+// --- Time Constants ---
+exports.ONE_HOUR_MS = 1000 * 60 * 60;
+exports.FIVE_MINUTES_MS = 1000 * 60 * 5;
+const ONE_DAY = exports.ONE_HOUR_MS * 24;
 const ONE_YEAR = ONE_DAY * 366;
+class CacheEventEmitter extends events_1.EventEmitter {
+    emitEviction(event) {
+        this.emit('eviction', event);
+    }
+    onEviction(handler) {
+        this.on('eviction', handler);
+    }
+}
+exports.CacheEventEmitter = CacheEventEmitter;
+exports.cacheEvents = new CacheEventEmitter();
+/**
+ * Get cache configuration from environment variables
+ *
+ * Supports:
+ * - GRAPHILE_CACHE_MAX: Maximum number of entries (default: 15)
+ * - GRAPHILE_CACHE_TTL_MS: TTL in milliseconds
+ *   - Production default: ONE_YEAR
+ *   - Development default: FIVE_MINUTES_MS
+ */
+function getCacheConfig() {
+    const isDevelopment = process.env.NODE_ENV === 'development';
+    const max = process.env.GRAPHILE_CACHE_MAX
+        ? parseInt(process.env.GRAPHILE_CACHE_MAX, 10)
+        : 15;
+    const ttl = process.env.GRAPHILE_CACHE_TTL_MS
+        ? parseInt(process.env.GRAPHILE_CACHE_TTL_MS, 10)
+        : isDevelopment
+            ? exports.FIVE_MINUTES_MS
+            : ONE_YEAR;
+    return { max, ttl };
+}
+// Track disposed entries to prevent double-disposal
+const disposedKeys = new Set();
+// Track keys that are being manually evicted for accurate eviction reason
+const manualEvictionKeys = new Set();
+/**
+ * Dispose a PostGraphile v5 cache entry
+ *
+ * Properly releases resources by:
+ * 1. Closing the HTTP server if listening
+ * 2. Releasing the PostGraphile instance (which internally releases grafserv)
+ *
+ * Uses disposedKeys set to prevent double-disposal when closeAllCaches()
+ * explicitly disposes entries and then clear() triggers the dispose callback.
+ */
+const disposeEntry = async (entry, key) => {
+    // Prevent double-disposal
+    if (disposedKeys.has(key)) {
+        return;
+    }
+    disposedKeys.add(key);
+    log.debug(`Disposing PostGraphile[${key}]`);
+    try {
+        // Close HTTP server if it's listening
+        if (entry.httpServer?.listening) {
+            await new Promise((resolve) => {
+                entry.httpServer.close(() => resolve());
+            });
+        }
+        // Release PostGraphile instance (this also releases grafserv internally)
+        if (entry.pgl) {
+            await entry.pgl.release();
+        }
+    }
+    catch (err) {
+        log.error(`Error disposing PostGraphile[${key}]:`, err);
+    }
+};
+/**
+ * Determine the eviction reason for a cache entry
+ */
+const getEvictionReason = (key, entry) => {
+    if (manualEvictionKeys.has(key)) {
+        manualEvictionKeys.delete(key);
+        return 'manual';
+    }
+    // Check if TTL expired
+    const age = Date.now() - entry.createdAt;
+    const config = getCacheConfig();
+    if (age >= config.ttl) {
+        return 'ttl';
+    }
+    return 'lru';
+};
+// Get initial cache configuration
+const initialConfig = getCacheConfig();
 // --- Graphile Cache ---
 exports.graphileCache = new lru_cache_1.LRUCache({
-    max: 15,
-    ttl: ONE_YEAR,
+    max: initialConfig.max,
+    ttl: initialConfig.ttl,
     updateAgeOnGet: true,
-    dispose: (_, key) => {
-        log.debug(`Disposing PostGraphile[${key}]`);
+    dispose: (entry, key) => {
+        // Determine eviction reason before disposal
+        const reason = getEvictionReason(key, entry);
+        // Emit eviction event
+        exports.cacheEvents.emitEviction({ key, reason, entry });
+        log.debug(`Evicting PostGraphile[${key}] (reason: ${reason})`);
+        // LRU dispose is synchronous, but v5 disposal is async
+        // Fire and forget the async cleanup
+        disposeEntry(entry, key).catch((err) => {
+            log.error(`Failed to dispose PostGraphile[${key}]:`, err);
+        });
     }
 });
+/**
+ * Get current cache statistics
+ */
+function getCacheStats() {
+    const config = getCacheConfig();
+    return {
+        size: exports.graphileCache.size,
+        max: config.max,
+        ttl: config.ttl,
+        keys: [...exports.graphileCache.keys()]
+    };
+}
+// --- Clear Matching Entries ---
+/**
+ * Clear cache entries matching a regex pattern
+ *
+ * @param pattern - RegExp to match against cache keys
+ * @returns Number of entries cleared
+ */
+function clearMatchingEntries(pattern) {
+    let cleared = 0;
+    for (const key of exports.graphileCache.keys()) {
+        if (pattern.test(key)) {
+            // Mark as manual eviction before deleting
+            manualEvictionKeys.add(key);
+            exports.graphileCache.delete(key);
+            cleared++;
+        }
+    }
+    return cleared;
+}
 // Register cleanup callback with pgCache
 // When a pg pool is disposed, clean up any graphile instances using it
 const unregister = pg_cache_1.pgCache.registerCleanupCallback((pgPoolKey) => {
+    log.debug(`pgPool[${pgPoolKey}] disposed - checking graphile entries`);
+    // Remove graphile entries that reference this pool key
     exports.graphileCache.forEach((entry, k) => {
-        if (entry.pgPoolKey === pgPoolKey) {
-            log.debug(`Removing graphileCache[${k}] due to pgPool[${pgPoolKey}]`);
+        if (entry.cacheKey.includes(pgPoolKey)) {
+            log.debug(`Removing graphileCache[${k}] due to pgPool[${pgPoolKey}] disposal`);
+            manualEvictionKeys.add(k);
             exports.graphileCache.delete(k);
         }
     });
 });
 // Enhanced close function that handles all caches
 const closePromise = { promise: null };
+/**
+ * Close all caches and release resources
+ *
+ * This function:
+ * 1. Disposes all PostGraphile v5 instances (async)
+ * 2. Clears the graphile cache
+ * 3. Closes all pg pools via pgCache
+ *
+ * The function is idempotent - calling it multiple times
+ * returns the same promise.
+ */
 const closeAllCaches = async (verbose = false) => {
     if (closePromise.promise)
         return closePromise.promise;
     closePromise.promise = (async () => {
         if (verbose)
             log.info('Closing all server caches...');
+        // Collect all entries and dispose them properly
+        const entries = [...exports.graphileCache.entries()];
+        // Mark all as manual evictions
+        for (const [key] of entries) {
+            manualEvictionKeys.add(key);
+        }
+        const disposePromises = entries.map(([key, entry]) => disposeEntry(entry, key));
+        // Wait for all disposals to complete
+        await Promise.allSettled(disposePromises);
+        // Clear the cache after disposal (dispose callback will no-op due to disposedKeys)
         exports.graphileCache.clear();
+        // Clear disposed keys tracking after full cleanup
+        disposedKeys.clear();
+        manualEvictionKeys.clear();
+        // Close pg pools
         await pg_cache_1.pgCache.close();
         if (verbose)
             log.success('All caches disposed.');

package/index.d.ts

@@ -1 +1,2 @@
-export { closeAllCaches, GraphileCache, graphileCache } from './graphile-cache';
+export { graphileCache, GraphileCacheEntry, closeAllCaches, ONE_HOUR_MS, FIVE_MINUTES_MS, EvictionReason, CacheEventEmitter, CacheEvictionEvent, cacheEvents, CacheConfig, getCacheConfig, CacheStats, getCacheStats, clearMatchingEntries } from './graphile-cache';
+export { createGraphileInstance } from './create-instance';

package/index.js

@@ -1,7 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.graphileCache = exports.closeAllCaches = void 0;
+exports.createGraphileInstance = exports.clearMatchingEntries = exports.getCacheStats = exports.getCacheConfig = exports.cacheEvents = exports.CacheEventEmitter = exports.FIVE_MINUTES_MS = exports.ONE_HOUR_MS = exports.closeAllCaches = exports.graphileCache = void 0;
 // Main exports from graphile-cache package
 var graphile_cache_1 = require("./graphile-cache");
-Object.defineProperty(exports, "closeAllCaches", { enumerable: true, get: function () { return graphile_cache_1.closeAllCaches; } });
+// Cache instance and entry type
 Object.defineProperty(exports, "graphileCache", { enumerable: true, get: function () { return graphile_cache_1.graphileCache; } });
+Object.defineProperty(exports, "closeAllCaches", { enumerable: true, get: function () { return graphile_cache_1.closeAllCaches; } });
+// Time constants
+Object.defineProperty(exports, "ONE_HOUR_MS", { enumerable: true, get: function () { return graphile_cache_1.ONE_HOUR_MS; } });
+Object.defineProperty(exports, "FIVE_MINUTES_MS", { enumerable: true, get: function () { return graphile_cache_1.FIVE_MINUTES_MS; } });
+// Event emitter for cache events
+Object.defineProperty(exports, "CacheEventEmitter", { enumerable: true, get: function () { return graphile_cache_1.CacheEventEmitter; } });
+Object.defineProperty(exports, "cacheEvents", { enumerable: true, get: function () { return graphile_cache_1.cacheEvents; } });
+Object.defineProperty(exports, "getCacheConfig", { enumerable: true, get: function () { return graphile_cache_1.getCacheConfig; } });
+Object.defineProperty(exports, "getCacheStats", { enumerable: true, get: function () { return graphile_cache_1.getCacheStats; } });
+// Clear matching entries
+Object.defineProperty(exports, "clearMatchingEntries", { enumerable: true, get: function () { return graphile_cache_1.clearMatchingEntries; } });
+// Factory for creating PostGraphile v5 instances
+var create_instance_1 = require("./create-instance");
+Object.defineProperty(exports, "createGraphileInstance", { enumerable: true, get: function () { return create_instance_1.createGraphileInstance; } });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "graphile-cache",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "author": "Constructive <developers@constructive.io>",
-  "description": "PostGraphile LRU cache with automatic pool cleanup integration",
+  "description": "PostGraphile v5 LRU cache with automatic pool cleanup integration",
   "main": "index.js",
   "module": "esm/index.js",
   "types": "index.d.ts",
@@ -29,14 +29,15 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@pgpmjs/logger": "^2.0.0",
+    "@pgpmjs/logger": "^2.1.0",
+    "express": "^5.2.1",
+    "grafserv": "^1.0.0-rc.4",
     "lru-cache": "^11.2.4",
-    "pg": "^8.17.1",
-    "pg-cache": "^2.0.0",
-    "postgraphile": "^4.14.1"
+    "pg-cache": "^3.0.0",
+    "postgraphile": "^5.0.0-rc.4"
   },
   "devDependencies": {
-    "@types/pg": "^8.16.0",
+    "@types/express": "^5.0.6",
     "makage": "^0.1.10",
     "nodemon": "^3.1.10",
     "ts-node": "^10.9.2"
@@ -47,7 +48,8 @@
     "cache",
     "lru",
     "postgresql",
-    "constructive"
+    "constructive",
+    "v5"
   ],
-  "gitHead": "390f4dd57fc158554518ec454bf2a4856d550552"
+  "gitHead": "b2daeefe49cdefb3d01ea63cf778fb9b847ab5fe"
 }