@engjts/nexus 0.1.0

package/src/advanced/cache/RedisCacheStore.ts

@@ -0,0 +1,341 @@
+import { EventEmitter } from 'events';
+import { CacheStore, CacheEntry } from './types';
+
+/**
+ * Redis cache store configuration
+ */
+export interface RedisCacheConfig {
+    /**
+     * Redis connection URL
+     * @example 'redis://localhost:6379'
+     */
+    url?: string;
+
+    /**
+     * Redis host
+     * @default 'localhost'
+     */
+    host?: string;
+
+    /**
+     * Redis port
+     * @default 6379
+     */
+    port?: number;
+
+    /**
+     * Redis password
+     */
+    password?: string;
+
+    /**
+     * Redis database number
+     * @default 0
+     */
+    db?: number;
+
+    /**
+     * Key prefix for namespacing
+     * @default 'nexus:'
+     */
+    prefix?: string;
+
+    /**
+     * Connection timeout in milliseconds
+     * @default 5000
+     */
+    connectTimeout?: number;
+
+    /**
+     * Enable TLS/SSL
+     * @default false
+     */
+    tls?: boolean;
+
+    /**
+     * Lazy connect - don't connect immediately
+     * @default false
+     */
+    lazyConnect?: boolean;
+}
+
+/**
+ * Redis client interface
+ * Supports both 'redis' and 'ioredis' packages
+ */
+export interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: { EX?: number; PX?: number }): Promise<any>;
+    setex?(key: string, seconds: number, value: string): Promise<any>;
+    del(key: string | string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    flushdb?(): Promise<any>;
+    flushDb?(): Promise<any>;
+    quit?(): Promise<any>;
+    disconnect?(): Promise<any>;
+    on?(event: string, listener: (...args: any[]) => void): void;
+}
+
+/**
+ * Redis cache store with full feature support
+ * 
+ * @example
+ * ```typescript
+ * // Using with ioredis
+ * import Redis from 'ioredis';
+ * 
+ * const redis = new Redis({ host: 'localhost', port: 6379 });
+ * const cache = new RedisCacheStore('sessions', { client: redis });
+ * 
+ * // Using with node-redis
+ * import { createClient } from 'redis';
+ * 
+ * const client = createClient({ url: 'redis://localhost:6379' });
+ * await client.connect();
+ * const cache = new RedisCacheStore('sessions', { client });
+ * ```
+ */
+export class RedisCacheStore<Value = unknown> implements CacheStore<Value> {
+    readonly name: string;
+    private client: RedisClientLike;
+    private prefix: string;
+    private emitter = new EventEmitter();
+    private connected: boolean = false;
+
+    constructor(
+        name: string,
+        options: RedisCacheConfig & { client: RedisClientLike }
+    ) {
+        this.name = name;
+        this.client = options.client;
+        this.prefix = options.prefix ?? 'nexus:';
+
+        // Listen for connection events if supported
+        if (this.client.on) {
+            this.client.on('connect', () => {
+                this.connected = true;
+                this.emitter.emit('connect');
+            });
+            this.client.on('error', (err) => {
+                this.emitter.emit('error', err);
+            });
+            this.client.on('close', () => {
+                this.connected = false;
+                this.emitter.emit('disconnect');
+            });
+        } else {
+            this.connected = true;
+        }
+    }
+
+    /**
+     * Build the full Redis key with prefix
+     */
+    private buildKey(key: string): string {
+        return `${this.prefix}${this.name}:${key}`;
+    }
+
+    /**
+     * Get a value from cache
+     */
+    async get(key: string): Promise<CacheEntry<Value> | undefined> {
+        try {
+            const data = await this.client.get(this.buildKey(key));
+            if (!data) {
+                return undefined;
+            }
+
+            const entry = JSON.parse(data) as CacheEntry<Value>;
+
+            // Check expiration (Redis handles TTL, but we double-check for safety)
+            if (entry.expiresAt && entry.expiresAt < Date.now()) {
+                await this.delete(key);
+                return undefined;
+            }
+
+            return entry;
+        } catch (error) {
+            this.emitter.emit('error', error);
+            return undefined;
+        }
+    }
+
+    /**
+     * Set a value in cache
+     */
+    async set(key: string, entry: CacheEntry<Value>): Promise<void> {
+        try {
+            const fullKey = this.buildKey(key);
+            const data = JSON.stringify(entry);
+
+            if (entry.expiresAt) {
+                const ttlMs = entry.expiresAt - Date.now();
+                if (ttlMs > 0) {
+                    const ttlSec = Math.ceil(ttlMs / 1000);
+                    // Try different methods for compatibility
+                    if (this.client.setex) {
+                        // ioredis style
+                        await this.client.setex(fullKey, ttlSec, data);
+                    } else {
+                        // node-redis style
+                        await this.client.set(fullKey, data, { EX: ttlSec });
+                    }
+                }
+            } else {
+                await this.client.set(fullKey, data);
+            }
+
+            this.emitter.emit('set', key, entry);
+        } catch (error) {
+            this.emitter.emit('error', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Delete a key from cache
+     */
+    async delete(key: string): Promise<void> {
+        try {
+            await this.client.del(this.buildKey(key));
+            this.emitter.emit('delete', key);
+        } catch (error) {
+            this.emitter.emit('error', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Clear all keys in this cache namespace
+     */
+    async clear(): Promise<void> {
+        try {
+            const pattern = `${this.prefix}${this.name}:*`;
+            const keys = await this.client.keys(pattern);
+            
+            if (keys.length > 0) {
+                await this.client.del(keys);
+            }
+            
+            this.emitter.emit('clear');
+        } catch (error) {
+            this.emitter.emit('error', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Get all keys matching a pattern
+     */
+    async keys(pattern?: RegExp): Promise<string[]> {
+        try {
+            const redisPattern = `${this.prefix}${this.name}:*`;
+            const allKeys = await this.client.keys(redisPattern);
+            
+            // Remove prefix to get clean keys
+            const prefixLength = `${this.prefix}${this.name}:`.length;
+            const cleanKeys = allKeys.map(k => k.slice(prefixLength));
+
+            if (!pattern) {
+                return cleanKeys;
+            }
+
+            return cleanKeys.filter(key => pattern.test(key));
+        } catch (error) {
+            this.emitter.emit('error', error);
+            return [];
+        }
+    }
+
+    /**
+     * Check if connected to Redis
+     */
+    isConnected(): boolean {
+        return this.connected;
+    }
+
+    /**
+     * Subscribe to cache events
+     */
+    on(event: 'set' | 'delete' | 'clear' | 'connect' | 'disconnect' | 'error', listener: (...args: any[]) => void): void {
+        this.emitter.on(event, listener);
+    }
+
+    /**
+     * Disconnect from Redis
+     */
+    async disconnect(): Promise<void> {
+        if (this.client.quit) {
+            await this.client.quit();
+        } else if (this.client.disconnect) {
+            await this.client.disconnect();
+        }
+        this.connected = false;
+    }
+}
+
+/**
+ * Create a Redis cache store with automatic client creation
+ * Requires 'ioredis' or 'redis' package to be installed
+ * 
+ * @example
+ * ```typescript
+ * // Auto-create Redis client
+ * const cache = await createRedisCache('sessions', {
+ *   host: 'localhost',
+ *   port: 6379,
+ *   prefix: 'myapp:'
+ * });
+ * 
+ * await cache.set('user:123', { value: { name: 'John' }, expiresAt: Date.now() + 3600000 });
+ * const user = await cache.get('user:123');
+ * ```
+ */
+export async function createRedisCache<Value = unknown>(
+    name: string,
+    config: RedisCacheConfig = {}
+): Promise<RedisCacheStore<Value>> {
+    let client: RedisClientLike;
+
+    // Try ioredis first
+    try {
+        const Redis = require('ioredis');
+        client = new Redis({
+            host: config.host ?? 'localhost',
+            port: config.port ?? 6379,
+            password: config.password,
+            db: config.db ?? 0,
+            connectTimeout: config.connectTimeout ?? 5000,
+            tls: config.tls ? {} : undefined,
+            lazyConnect: config.lazyConnect ?? false
+        });
+    } catch {
+        // Try node-redis
+        try {
+            const { createClient } = require('redis');
+            const url = config.url ?? `redis://${config.host ?? 'localhost'}:${config.port ?? 6379}`;
+            
+            client = createClient({
+                url,
+                password: config.password,
+                database: config.db ?? 0,
+                socket: {
+                    connectTimeout: config.connectTimeout ?? 5000,
+                    tls: config.tls ?? false
+                }
+            });
+
+            // node-redis requires explicit connect
+            await (client as any).connect();
+        } catch {
+            throw new Error(
+                'Redis client not found. Please install either "ioredis" or "redis" package:\n' +
+                '  npm install ioredis\n' +
+                '  # or\n' +
+                '  npm install redis'
+            );
+        }
+    }
+
+    return new RedisCacheStore<Value>(name, { ...config, client });
+}

package/src/advanced/cache/index.ts

@@ -0,0 +1,5 @@
+export { InMemoryCacheStore } from './InMemoryCacheStore';
+export { MultiTierCache } from './MultiTierCache';
+export { RedisCacheStore, createRedisCache } from './RedisCacheStore';
+export type { RedisCacheConfig, RedisClientLike } from './RedisCacheStore';
+export * from './types';

package/src/advanced/cache/types.ts

@@ -0,0 +1,40 @@
+export interface CacheEntry<Value = unknown> {
+    value: Value;
+    expiresAt?: number;
+    tags?: string[];
+    meta?: Record<string, any>;
+}
+
+export interface CacheStore<Value = unknown> {
+    readonly name: string;
+    get(key: string): Promise<CacheEntry<Value> | undefined>;
+    set(key: string, entry: CacheEntry<Value>): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    keys?(pattern?: RegExp): Promise<string[]>;
+}
+
+export interface CacheTierConfig<Value = unknown> {
+    store: CacheStore<Value>;
+    ttl?: number;
+    maxSize?: number;
+}
+
+export interface CacheSetOptions<Value = unknown> {
+    ttl?: number;
+    tags?: string[];
+    meta?: CacheEntry<Value>['meta'];
+}
+
+export interface CacheWrapOptions<Value = unknown> extends CacheSetOptions<Value> {
+    refresh?: boolean;
+}
+
+export interface MemoizeOptions<Value = unknown> extends CacheSetOptions<Value> {
+    keyResolver?: (...args: any[]) => string;
+}
+
+export interface TagIndexEntry {
+    keys: Set<string>;
+    expiresAt?: number;
+}

package/src/advanced/graphql/SimpleDataLoader.ts

@@ -0,0 +1,42 @@
+interface SimpleDataLoaderBatch<Key, Value> {
+    keys: Key[];
+    resolvers: Array<{ resolve: (value: Value) => void; reject: (error: Error) => void }>;
+}
+
+export class SimpleDataLoader<Key = any, Value = any> {
+    private batch: SimpleDataLoaderBatch<Key, Value> | null = null;
+
+    constructor(private batchLoadFn: (keys: Key[]) => Promise<Map<Key, Value>>) { }
+
+    load(key: Key): Promise<Value> {
+        if (!this.batch) {
+            this.batch = { keys: [], resolvers: [] };
+            queueMicrotask(() => this.dispatch());
+        }
+
+        return new Promise<Value>((resolve, reject) => {
+            this.batch!.keys.push(key);
+            this.batch!.resolvers.push({ resolve, reject });
+        });
+    }
+
+    private async dispatch() {
+        if (!this.batch) return;
+        const current = this.batch;
+        this.batch = null;
+
+        try {
+            const result = await this.batchLoadFn(current.keys);
+            current.keys.forEach((key, index) => {
+                const value = result.get(key);
+                if (value === undefined) {
+                    current.resolvers[index].reject(new Error(`DataLoader missing key "${String(key)}"`));
+                } else {
+                    current.resolvers[index].resolve(value);
+                }
+            });
+        } catch (error) {
+            current.resolvers.forEach(resolver => resolver.reject(error as Error));
+        }
+    }
+}

package/src/advanced/graphql/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Nexus GraphQL Module
+ * 
+ * Optional GraphQL integration for Nexus framework.
+ * Requires `graphql` as peer dependency.
+ * 
+ * Install: npm install graphql
+ * 
+ * Usage:
+ * import { GraphQLServer, SimpleDataLoader } from '@engjts/server/graphql';
+ */
+
+export { GraphQLServer } from './server';
+export { SimpleDataLoader } from './SimpleDataLoader';
+export type {
+    GraphQLComplexityOptions,
+    GraphQLCacheOptions,
+    GraphQLRequestPayload,
+    GraphQLServerOptions,
+    SimpleDataLoaderBatch,
+    DataLoaderFactory
+} from './types';

package/src/advanced/graphql/server.ts

@@ -0,0 +1,252 @@
+import {
+    DocumentNode,
+    ExecutionResult,
+    GraphQLSchema,
+    Kind,
+    OperationDefinitionNode,
+    execute,
+    getOperationAST,
+    parse,
+    validate
+} from 'graphql';
+import { Context, Handler, Response } from '../../core/types';
+import { GraphQLComplexityOptions, GraphQLRequestPayload, GraphQLServerOptions } from './types';
+
+export class GraphQLServer {
+    private schema: GraphQLSchema;
+    private options: GraphQLServerOptions;
+
+    constructor(options: GraphQLServerOptions) {
+        this.schema = options.schema;
+        this.options = {
+            playground: options.playground ?? false,
+            introspection: options.introspection ?? process.env.NODE_ENV !== 'production',
+            dataloaders: options.dataloaders ?? true,
+            ...options
+        };
+    }
+
+    /**
+     * Returns a framework route handler
+     */
+    handler(): Handler {
+        return async (ctx: Context): Promise<Response> => {
+            if (ctx.method === 'GET' && this.shouldRenderPlayground(ctx)) {
+                return ctx.html(this.renderPlayground());
+            }
+
+            const payload = await this.parseRequest(ctx);
+            const document = this.parseDocument(payload.query);
+            this.enforceRules(document, payload);
+
+            const cacheKey = await this.computeCacheKey(payload);
+            if (cacheKey) {
+                const cached = await this.options.cache!.instance.get(cacheKey);
+                if (cached) {
+                    return this.buildResponse(cached as ExecutionResult);
+                }
+            }
+
+            const contextValue = await this.buildContext(ctx);
+            const result = await execute({
+                schema: this.schema,
+                document,
+                variableValues: payload.variables,
+                operationName: payload.operationName,
+                contextValue
+            });
+
+            if (cacheKey && !result.errors) {
+                await this.options.cache!.instance.set(cacheKey, result, { ttl: this.options.cache?.ttl });
+            }
+
+            return this.buildResponse(result);
+        };
+    }
+
+    private shouldRenderPlayground(ctx: Context): boolean {
+        if (!this.options.playground) {
+            return false;
+        }
+        const accept = ctx.headers['accept'];
+        if (!accept) return false;
+        const acceptHeader = Array.isArray(accept) ? accept.join(',') : accept;
+        return acceptHeader.includes('text/html');
+    }
+
+    private async parseRequest(ctx: Context): Promise<GraphQLRequestPayload> {
+        if (ctx.method === 'GET') {
+            return {
+                query: ctx.query.query,
+                variables: this.safeParseJSON(ctx.query.variables),
+                operationName: ctx.query.operationName as string | undefined
+            };
+        }
+
+        if (typeof ctx.body === 'string') {
+            return JSON.parse(ctx.body);
+        }
+
+        return ctx.body ?? {};
+    }
+
+    private parseDocument(query?: string): DocumentNode {
+        if (!query) {
+            throw new Error('GraphQL query is required');
+        }
+        return parse(query);
+    }
+
+    private enforceRules(document: DocumentNode, payload: GraphQLRequestPayload) {
+        if (!this.options.introspection) {
+            const operation = getOperationAST(document, payload.operationName || undefined);
+            if (operation?.operation === 'query' && operation.name?.value === '__schema') {
+                throw new Error('Introspection is disabled');
+            }
+        }
+
+        const validationErrors = validate(this.schema, document);
+        if (validationErrors.length > 0) {
+            throw validationErrors[0];
+        }
+
+        if (this.options.depthLimit !== undefined) {
+            const depth = this.calculateDepth(document);
+            if (depth > this.options.depthLimit) {
+                throw new Error(`Query depth ${depth} exceeds limit of ${this.options.depthLimit}`);
+            }
+        }
+
+        if (this.options.complexity) {
+            const complexity = this.calculateComplexity(document, this.options.complexity);
+            if (complexity > this.options.complexity.limit) {
+                throw new Error(`Query complexity ${complexity} exceeds limit of ${this.options.complexity.limit}`);
+            }
+        }
+    }
+
+    private async buildContext(ctx: Context) {
+        const base = typeof this.options.context === 'function'
+            ? await this.options.context({ ctx })
+            : this.options.context ?? {};
+
+        if (this.options.dataloaders) {
+            Object.assign(base, { loaders: {} });
+        }
+
+        return { ...base, request: ctx };
+    }
+
+    private calculateDepth(document: DocumentNode): number {
+        let maxDepth = 0;
+
+        const traverse = (node: any, depth: number) => {
+            if (!node.selectionSet) {
+                return;
+            }
+            depth += 1;
+            maxDepth = Math.max(maxDepth, depth);
+            for (const selection of node.selectionSet.selections) {
+                traverse(selection, depth);
+            }
+        };
+
+        for (const definition of document.definitions) {
+            if (definition.kind === Kind.OPERATION_DEFINITION) {
+                traverse(definition, 0);
+            }
+        }
+
+        return maxDepth;
+    }
+
+    private calculateComplexity(
+        document: DocumentNode,
+        options: GraphQLComplexityOptions
+    ): number {
+        const costs = options.cost || {};
+        const defaultCost = options.defaultCost ?? 1;
+        let complexity = 0;
+
+        const visitNode = (node: OperationDefinitionNode | any) => {
+            if (!node.selectionSet) {
+                return;
+            }
+
+            for (const selection of node.selectionSet.selections) {
+                if (selection.kind === Kind.FIELD) {
+                    const fieldName = selection.name.value;
+                    complexity += costs[fieldName] ?? defaultCost;
+                }
+                visitNode(selection);
+            }
+        };
+
+        for (const definition of document.definitions) {
+            if (definition.kind === Kind.OPERATION_DEFINITION) {
+                visitNode(definition);
+            }
+        }
+
+        return complexity;
+    }
+
+    private async computeCacheKey(payload: GraphQLRequestPayload): Promise<string | null> {
+        if (!this.options.cache) {
+            return null;
+        }
+
+        const generator = this.options.cache.keyGenerator ??
+            ((data: GraphQLRequestPayload) => JSON.stringify(data));
+
+        return generator(payload);
+    }
+
+    private buildResponse(result: ExecutionResult): Response {
+        if (result.errors && this.options.formatError) {
+            result = {
+                ...result,
+                errors: result.errors.map(err => this.options.formatError!(err))
+            };
+        }
+
+        return {
+            statusCode: result.errors ? 400 : 200,
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(result)
+        };
+    }
+
+    private safeParseJSON(value: any) {
+        if (!value) return undefined;
+        try {
+            if (typeof value === 'string') {
+                return JSON.parse(value);
+            }
+            return value;
+        } catch {
+            return undefined;
+        }
+    }
+
+    private renderPlayground() {
+        return `
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset=utf-8/>
+    <title>GraphQL Playground</title>
+    <link rel="stylesheet" href="https://unpkg.com/graphql-playground-react/build/static/css/index.css" />
+    <link rel="shortcut icon" href="https://raw.githubusercontent.com/graphql/graphql-playground/main/packages/graphql-playground-react/public/favicon.png" />
+    <script src="https://unpkg.com/graphql-playground-react/build/static/js/middleware.js"></script>
+  </head>
+  <body>
+    <div id="root" />
+    <script>window.addEventListener('load', function () {
+      GraphQLPlayground.init(document.getElementById('root'), { endpoint: '/graphql' })
+    })</script>
+  </body>
+</html>`;
+    }
+}
+