cfw-graphql-bootstrap 1.0.0 → 1.0.1

package/README.md

@@ -6,7 +6,7 @@ Enterprise-grade GraphQL server framework for Cloudflare Workers with built-in s
 
 - 🚀 **Optimized for Cloudflare Workers** - Built specifically for edge runtime with minimal bundle size
 - 🔒 **Enterprise Security** - HMAC signature verification, CORS, rate limiting, and security headers
-- 💾 **Multi-tier Caching** - Support for Cloudflare KV and Redis with cache-aside pattern
+- 💾 **Built-in Caching** - Native Cloudflare KV support with cache-aside pattern
 - 📊 **Observability** - Distributed tracing, structured logging with Pino, and health checks
 - 🛡️ **Type Safety** - Full TypeScript support with proper type exports
 - ⚡ **High Performance** - Lightweight environment parsing, efficient middleware chain
@@ -56,15 +56,20 @@ const schema = createSchemaModule({
   },
 });
 
-// Create the server
+// Create the server (cache is automatically configured)
 const server = createGraphQLServer({
   name: 'my-graphql-api',
   version: '1.0.0',
   config: {
     apollo: {
       schema: schema.schema,
+      // Cache is automatically configured from KV binding
     },
-    datasources: (cache, context) => ({}),
+    // Optional: Define data sources (cache is provided)
+    datasources: (cache, context) => ({
+      // cache is Apollo's KeyValueCache<string> from KV
+      users: new UserDataSource(cache),
+    }),
   },
 });
 
@@ -105,28 +110,78 @@ const server = createGraphQLServer<any, MyContext>({
 
 ### Caching
 
-Enable KV caching by binding a KV namespace:
+The framework **requires** a KV namespace binding named `KV` for caching. The framework provides two cache interfaces that both use this KV storage:
+
+1. **Apollo's KeyValueCache** - Automatically configured for Apollo Server features (response caching, APQ)
+2. **KVCache** - Available in `context.cache` for application-level caching with enhanced features
+
+**Required Configuration:**
 
 ```toml
-# wrangler.toml
+# wrangler.toml (REQUIRED)
 [[kv_namespaces]]
-binding = "CACHE_KV"
+binding = "KV"  # Must be named "KV"
 id = "your-kv-namespace-id"
 ```
 
-Use the cache decorator in resolvers:
+If the KV binding is missing, the server will throw an error on startup.
 
 ```typescript
+// 1. Apollo cache is automatically configured from KV binding
+// No need to manually pass cache!
+
+// 2. Application cache in resolvers (context.cache is KVCache)
+const resolvers = {
+  Query: {
+    user: async (_, {id}, context) => {
+      // Use KVCache's memoize for auto key generation
+      return context.cache.memoize('user', {id}, () => fetchUserFromDB(id), {
+        ttl: 300,
+      });
+    },
+  },
+};
+
+// 3. Cache decorator for class-based resolvers
 import {cached} from 'cfw-graphql-bootstrap';
 
 class UserResolver {
-  @cached({ttl: 300}) // Cache for 5 minutes
+  @cached({ttl: 300}) // Uses KVCache
   async getUser(_, {id}, context) {
     return fetchUserFromDB(id);
   }
 }
 ```
 
+### Batching Data Sources
+
+Create efficient batched data sources with automatic caching:
+
+```typescript
+import {BatchingDataSource, ensureBatchOrder} from 'cfw-graphql-bootstrap';
+
+export class UserDataSource extends BatchingDataSource<
+  BaseContext,
+  string,
+  User
+> {
+  constructor() {
+    super(
+      async (ids: readonly string[]) => {
+        const users = await fetchUsersFromDB(ids);
+        return ensureBatchOrder(ids, users, 'id');
+      },
+      {cache: true}, // DataLoader options
+      'users' // KV cache namespace
+    );
+  }
+}
+
+// In your resolver
+const user = await context.dataSources.users.load(userId);
+const users = await context.dataSources.users.loadMany([id1, id2, id3]);
+```
+
 ### Environment Configuration
 
 The framework automatically validates and parses environment variables:
@@ -201,12 +256,18 @@ Built-in security features:
 - `envLoader` - Environment configuration loader
 - `EnvConfig` - Environment configuration type
 
-### Cache
+### Cache & Data Loading
 
-- `createCache(env)` - Create cache instance
-- `KVCache` - Cloudflare KV cache implementation
-- `RedisCache` - Redis cache implementation
-- `@cached(options)` - Cache decorator
+- `createCache(env)` - Create KV cache instance
+- `KVCache` - Cloudflare KV cache implementation with memoization
+- `ApolloKVAdapter` - Apollo KeyValueCache adapter for KV
+- `createApolloCache(kv)` - Create Apollo-compatible cache
+- `InMemoryCache` - Simple in-memory cache for development
+- `@cached(options)` - Cache decorator for resolver methods
+- `CachedDataLoader` - DataLoader with caching support
+- `BatchingDataSource` - Base class for batched data fetching
+- `createBatchingDataSource` - Factory for batching data sources
+- `ensureBatchOrder` - Helper to maintain batch order
 
 ### Middleware
 
@@ -240,7 +301,7 @@ vars = {
 }
 
 [[kv_namespaces]]
-binding = "CACHE_KV"
+binding = "KV"
 id = "your-kv-namespace-id"
 
 [[kv_namespaces]]
@@ -260,7 +321,7 @@ wrangler deploy --env production
 
 ## Performance
 
-- **Bundle Size**: ~30KB (ESM, before compression)
+- **Bundle Size**: ~32KB (ESM, before compression)
 - **Cold Start**: < 10ms typical
 - **Request Overhead**: < 2ms for middleware chain
 - **Memory Usage**: Optimized for Workers' 128MB limit

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import { BaseContext as BaseContext$1, ApolloServerOptions, ApolloServerPlugin } from '@apollo/server';
-import { KVNamespace, ExecutionContext } from '@cloudflare/workers-types';
+import { ExecutionContext } from '@cloudflare/workers-types';
 import { CloudflareContextFunctionArgument } from '@as-integrations/cloudflare-workers';
+import { KeyValueCache, KeyValueCacheSetOptions } from '@apollo/utils.keyvaluecache';
 import { GraphQLSchema, GraphQLError, DocumentNode } from 'graphql';
 import { Hono, MiddlewareHandler } from 'hono';
 import { ApolloServerErrorCode } from '@apollo/server/errors';
+import DataLoader, { BatchLoadFn, Options } from 'dataloader';
 export { gql } from 'graphql-tag';
 
 declare const logger: any;
@@ -29,20 +31,22 @@ interface ContextUser {
  * KV Cache implementation for Cloudflare Workers
  * Provides caching capabilities for GraphQL resolvers using Cloudflare KV
  */
-
 interface CacheOptions {
     ttl?: number;
+    namespace?: string;
     cacheKey?: string;
 }
 declare class KVCache {
     private kv;
-    constructor(kv: KVNamespace);
+    private defaultTTL;
+    private defaultNamespace;
+    constructor(kv: KVNamespace, defaultNamespace?: string);
     /**
      * Get a value from cache
      */
     get<T = any>(key: string): Promise<T | null>;
     /**
-     * Set a value in cache
+     * Set a value in cache with metadata
      */
     set(key: string, value: any, options?: CacheOptions): Promise<void>;
     /**
@@ -56,47 +60,205 @@ declare class KVCache {
     /**
      * Clear multiple keys matching a prefix
      */
-    clearPrefix(prefix: string): Promise<void>;
+    clearPrefix(prefix: string): Promise<number>;
+    /**
+     * Invalidate cache by pattern
+     */
+    invalidate(pattern: string): Promise<number>;
+    /**
+     * Clear all cache in a namespace
+     */
+    clearNamespace(namespace?: string): Promise<number>;
     /**
      * Get or set a value with a factory function
      * Useful for cache-aside pattern
      */
     getOrSet<T>(key: string, factory: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Memoize function with automatic key generation
+     */
+    memoize<T>(cacheKey: string, params: any, fetchFn: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /**
+     * Generate cache key with namespace and params
+     */
+    private generateKey;
+    /**
+     * Simple hash function for generating cache keys
+     */
+    private simpleHash;
 }
 
 /**
- * Redis Cache implementation for Cloudflare Workers
- * Alternative to KV for more advanced caching needs
+ * Ensures that output items has the same order as input keys (dataloader requirement).
+ * Returns error objects for non-existent ids.
+ *
+ * @param keys list of input keys
+ * @param items list of output items
+ * @param primaryKey name of the key-holding property
+ */
+declare function ensureBatchOrder<K extends string | number, T extends Record<string, any>>(keys: readonly K[], items: T[], primaryKey?: string): Array<T | Error>;
+/**
+ * Ensures that output items has the same order as input keys (dataloader requirement).
+ * Returns null for non-existent ids.
+ *
+ * @param keys list of input keys
+ * @param items list of output items
+ * @param primaryKey name of the key-holding property
+ */
+declare function ensureBatchOrderNullable<K extends string | number, T extends Record<string, any>>(keys: readonly K[], items: T[], primaryKey?: string): Array<T | null>;
+/**
+ * Base class for batching data sources with caching support.
+ * Uses DataLoader for request batching and deduplication.
+ *
+ * @typeParam TContext - Apollo context type
+ * @typeParam K - Primary key type
+ * @typeParam V - Output item type
+ * @typeParam CK - Cache key type (same as K by default)
+ *
+ * @example
+ * ```typescript
+ * export class UserBatchingDataSource extends BatchingDataSource<BaseContext, string, User> {
+ *   constructor() {
+ *     super(async (ids: readonly string[]) => {
+ *       const users = await fetchUsersFromDB(ids);
+ *       return ensureBatchOrder(ids, users);
+ *     });
+ *   }
+ * }
+ * ```
  */
+declare class BatchingDataSource<TContext extends BaseContext, K, V, CK = K> {
+    protected cacheNamespace?: string;
+    protected context: TContext;
+    protected loader: DataLoader<K, V, CK>;
+    protected cache?: KVCache;
+    /**
+     * Creates a new batching data source
+     *
+     * @param resolveBatch - Batch resolving function
+     * @param options - DataLoader options
+     * @param cacheNamespace - Optional namespace for KV caching
+     */
+    constructor(resolveBatch: BatchLoadFn<K, V>, options?: Options<K, V, CK>, cacheNamespace?: string);
+    /**
+     * Initialize with Apollo context
+     */
+    initialize(config: {
+        contextValue: TContext;
+    }): void;
+    /**
+     * Load a single item by key
+     */
+    load(id: K): Promise<V>;
+    /**
+     * Load multiple items by keys
+     */
+    loadMany(ids: readonly K[]): Promise<Array<V | Error>>;
+    /**
+     * Clear a single item from the DataLoader cache
+     */
+    clear(id: K): this;
+    /**
+     * Clear all items from the DataLoader cache
+     */
+    clearAll(): this;
+    /**
+     * Prime the cache with a specific value
+     */
+    prime(key: K, value: V): this;
+}
+/**
+ * Factory function for creating batching data sources
+ *
+ * @example
+ * ```typescript
+ * const userDataSource = createBatchingDataSource<BaseContext, string, User>(
+ *   async (ids) => {
+ *     const users = await fetchUsersFromDB(ids);
+ *     return ensureBatchOrder(ids, users);
+ *   },
+ *   { cache: true },
+ *   'users'
+ * );
+ * ```
+ */
+declare function createBatchingDataSource<TContext extends BaseContext, K, V, CK = K>(resolveBatch: BatchLoadFn<K, V>, options?: Options<K, V, CK>, cacheNamespace?: string): BatchingDataSource<TContext, K, V, CK>;
 
-declare class RedisCache {
-    private redis;
-    constructor(config?: {
-        url?: string;
-        token?: string;
-    });
-    private initUpstash;
-    private createMockRedis;
-    get<T = any>(key: string): Promise<T | null>;
-    set(key: string, value: any, options?: CacheOptions): Promise<void>;
-    delete(key: string): Promise<void>;
-    has(key: string): Promise<boolean>;
-    clearPrefix(prefix: string): Promise<void>;
-    getOrSet<T>(key: string, factory: () => Promise<T>, options?: CacheOptions): Promise<T>;
-    increment(key: string, by?: number): Promise<number>;
-    expire(key: string, seconds: number): Promise<boolean>;
-    ttl(key: string): Promise<number>;
+/**
+ * Apollo KeyValueCache adapter for Cloudflare KV
+ *
+ * Implements the Apollo Server KeyValueCache interface to work with
+ * Cloudflare Workers KV storage.
+ */
+
+/**
+ * Adapter that makes our KVCache compatible with Apollo's KeyValueCache interface
+ *
+ * Apollo Server uses this for:
+ * - Response caching
+ * - APQ (Automatic Persisted Queries)
+ * - DataSource caching
+ *
+ * @example
+ * ```typescript
+ * const apolloCache = new ApolloKVAdapter(new KVCache(env.KV));
+ *
+ * const server = new ApolloServer({
+ *   cache: apolloCache,
+ *   // ... other options
+ * });
+ * ```
+ */
+declare class ApolloKVAdapter implements KeyValueCache<string> {
+    private kvCache;
+    constructor(kvCache: KVCache);
+    /**
+     * Get a value from cache
+     * Apollo expects undefined for cache misses
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Set a value in cache with TTL support
+     * Apollo passes TTL in seconds via options
+     */
+    set(key: string, value: string, options?: KeyValueCacheSetOptions): Promise<void>;
+    /**
+     * Delete a value from cache
+     * Apollo expects boolean or void return
+     */
+    delete(key: string): Promise<boolean | void>;
+}
+/**
+ * Factory function to create an Apollo-compatible cache from KV namespace
+ *
+ * @param kv - Cloudflare KV namespace binding
+ * @returns Apollo-compatible KeyValueCache
+ */
+declare function createApolloCache(kv: KVNamespace): KeyValueCache<string>;
+/**
+ * In-memory LRU cache for development/testing
+ * Falls back to simple Map-based implementation
+ */
+declare class InMemoryCache implements KeyValueCache<string> {
+    private cache;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, options?: KeyValueCacheSetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
 }
 
 /**
  * Cache module for GraphQL resolvers
- * Provides unified caching interface with multiple backends
+ * Provides caching interface for Cloudflare Workers KV
  */
 
 /**
- * Cache factory - creates appropriate cache based on environment
+ * Cache factory - creates KV cache if available
  */
-declare function createCache(env: any): KVCache | RedisCache | null;
+declare function createCache(env: Env): KVCache | null;
 /**
  * Decorator for caching resolver results
  */
@@ -110,7 +272,7 @@ declare class CachedDataLoader<K, V> {
     private options;
     private loader;
     private cache;
-    constructor(batchFn: (keys: K[]) => Promise<V[]>, cache: KVCache | RedisCache, options?: CacheOptions);
+    constructor(batchFn: (keys: K[]) => Promise<V[]>, cache: KVCache, options?: CacheOptions);
     load(key: K): Promise<V>;
     loadMany(keys: K[]): Promise<V[]>;
     clear(key: K): Promise<void>;
@@ -133,8 +295,6 @@ interface EnvConfig {
     MAX_QUERY_DEPTH: number;
     MAX_QUERY_COMPLEXITY: number;
     INTROSPECTION_ENABLED: boolean;
-    REDIS_URL?: string;
-    REDIS_TOKEN?: string;
     LOG_SERVICE_URL?: string;
     LOG_SERVICE_TOKEN?: string;
 }
@@ -185,7 +345,7 @@ type Runner = {
 type ServerConfig<TDatasource, TContext extends BaseContext> = {
     path?: string;
     apollo: Partial<ApolloServerOptions<BaseContext>>;
-    datasources: (cache: any, context: TContext) => TDatasource;
+    datasources?: (cache: KeyValueCache<string>, context: TContext) => TDatasource;
     extendContext?: ContextExtendFunction<TContext>;
 };
 declare class ServerBuilder<TDatasource, TContext extends BaseContext> {
@@ -275,4 +435,13 @@ type SchemaModule = ReturnType<typeof createSchemaModule>;
 
 declare const getNonUserInputErrors: (errors: readonly GraphQLError[]) => GraphQLError[];
 
-export { AppError, type BaseContext, type BaseServerOptions, type CacheOptions, CachedDataLoader, type ContextExtendFunction, type ContextUser, type EnvConfig, ErrorCode, KVCache, RedisCache, type Runner, type SchemaModule, ServerBuilder, type ServerConfig, type ServerOptions, cached, configureHealthChecks, createApolloLoggingPlugin, createCache, createContextFunction, createGraphQLServer, createRateLimitMiddleware, createSchemaModule, createTracingMiddleware, createValidationMiddleware, envLoader, getNonUserInputErrors, logger };
+type DataSources = Record<string, any>;
+type DataSourcesFn = <TContext extends BaseContext = BaseContext>(cache: KeyValueCache<string>, contextValue: TContext) => DataSources;
+type ComputedContext<TDatasource, TContext extends BaseContext> = TContext & {
+    datasources: ReturnType<NonNullable<ServerConfig<TDatasource, TContext>['datasources']>>;
+};
+declare const ApolloDataSources: <TDatasource, TContext extends BaseContext>(options: {
+    datasources: DataSourcesFn;
+}) => ApolloServerPlugin<ComputedContext<TDatasource, TContext>>;
+
+export { ApolloDataSources, ApolloKVAdapter, AppError, type BaseContext, type BaseServerOptions, BatchingDataSource, type CacheOptions, CachedDataLoader, type ComputedContext, type ContextExtendFunction, type ContextUser, type EnvConfig, ErrorCode, InMemoryCache, KVCache, type Runner, type SchemaModule, ServerBuilder, type ServerConfig, type ServerOptions, cached, configureHealthChecks, createApolloCache, createApolloLoggingPlugin, createBatchingDataSource, createCache, createContextFunction, createGraphQLServer, createRateLimitMiddleware, createSchemaModule, createTracingMiddleware, createValidationMiddleware, ensureBatchOrder, ensureBatchOrderNullable, envLoader, getNonUserInputErrors, logger };