@graphoria/server 0.1.0

package/src/singletons/cache/redisCacheStore.ts

@@ -0,0 +1,81 @@
+import type { CacheStore } from "./types";
+
+import { getCacheRedisClient } from "./redisClient";
+import { logger } from "../../logging";
+
+export class RedisCacheStore implements CacheStore {
+  private prefix: string;
+  private trackingKey: string;
+  private ttlSeconds: number | undefined;
+  private client: ReturnType<typeof getCacheRedisClient>;
+  private log = logger("redis-cache");
+
+  constructor(operationName: string, ttlMs?: number) {
+    this.prefix = `cache:${operationName}:`;
+    this.trackingKey = `${this.prefix}__keys`;
+    this.ttlSeconds = ttlMs ? Math.ceil(ttlMs / 1000) : undefined;
+    this.client = getCacheRedisClient();
+  }
+
+  private fullKey(key: string): string {
+    const hash = Bun.hash(key).toString(36);
+    return `${this.prefix}${hash}`;
+  }
+
+  async get(key: string): Promise<unknown | undefined> {
+    try {
+      const raw = await this.client.get(this.fullKey(key));
+      if (raw === null) return undefined;
+      return JSON.parse(raw);
+    } catch (error) {
+      this.log.error({ err: error, operation: "get" }, "cache get failed");
+      return undefined;
+    }
+  }
+
+  async set(key: string, value: unknown): Promise<void> {
+    try {
+      const redisKey = this.fullKey(key);
+      await this.client.set(redisKey, JSON.stringify(value));
+      if (this.ttlSeconds) {
+        await this.client.expire(redisKey, this.ttlSeconds);
+      }
+      await this.client.sadd(this.trackingKey, key);
+    } catch (error) {
+      this.log.error({ err: error, operation: "set" }, "cache set failed");
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      await this.client.del(this.fullKey(key));
+      await this.client.srem(this.trackingKey, key);
+    } catch (error) {
+      this.log.error({ err: error, operation: "delete" }, "cache delete failed");
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      const originalKeys = await this.client.smembers(this.trackingKey);
+      if (originalKeys.length > 0) {
+        const redisKeys = originalKeys.map((k: string) => this.fullKey(k));
+        for (const redisKey of redisKeys) {
+          await this.client.del(redisKey);
+        }
+      }
+      await this.client.del(this.trackingKey);
+    } catch (error) {
+      this.log.error({ err: error, operation: "clear" }, "cache clear failed");
+    }
+  }
+
+  async keys(): Promise<string[]> {
+    try {
+      return await this.client.smembers(this.trackingKey);
+    } catch (error) {
+      this.log.error({ err: error, operation: "keys" }, "cache keys failed");
+      return [];
+    }
+  }
+}

package/src/singletons/cache/redisClient.ts

@@ -0,0 +1,12 @@
+import { RedisClient as ValkeyClient } from "bun";
+
+import { env } from "../env";
+
+let client: InstanceType<typeof ValkeyClient> | null = null;
+
+export const getCacheRedisClient = (): InstanceType<typeof ValkeyClient> => {
+  if (!client) {
+    client = new ValkeyClient(env.cache.redisUrl);
+  }
+  return client;
+};

package/src/singletons/cache/registry.ts

@@ -0,0 +1,51 @@
+import type { CacheStore } from "./types";
+
+const cacheRegistry = new Map<string, CacheStore>();
+
+export const registerCache = (name: string, cache: CacheStore) => {
+  cacheRegistry.set(name, cache);
+};
+
+export const getCache = (name: string): CacheStore | undefined => {
+  return cacheRegistry.get(name);
+};
+
+export const InvalidationHelper = {
+  invalidate: async (
+    operationName: string,
+    pattern?: Record<string, unknown>,
+  ): Promise<boolean> => {
+    const cache = cacheRegistry.get(operationName);
+    if (!cache) {
+      return false;
+    }
+
+    if (!pattern || Object.keys(pattern).length === 0) {
+      await cache.clear();
+      return true;
+    }
+
+    const allKeys = await cache.keys();
+    for (const key of allKeys) {
+      try {
+        const parsedKey = JSON.parse(key);
+        const cachedVariables = parsedKey.variables;
+
+        let match = true;
+        for (const [k, v] of Object.entries(pattern)) {
+          if (cachedVariables[k] !== v) {
+            match = false;
+            break;
+          }
+        }
+
+        if (match) {
+          await cache.delete(key);
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    }
+    return true;
+  },
+};

package/src/singletons/cache/types.ts

@@ -0,0 +1,7 @@
+export interface CacheStore {
+  get(key: string): Promise<unknown | undefined>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+  keys(): Promise<string[]>;
+}

package/src/singletons/cron.ts

@@ -0,0 +1,21 @@
+import type { StartCronJobsReturn } from "../cron";
+import type { GqlQueryFn } from "../types/common";
+import type { CronJob } from "../types/configuration";
+
+import { startCronJobs } from "../cron";
+
+let cronJobs: StartCronJobsReturn | null = null;
+
+export const instantiateCronJobs = async (jobs: CronJob[], gqlQuery: GqlQueryFn<true>) => {
+  if (!cronJobs) {
+    cronJobs = await startCronJobs(jobs, gqlQuery);
+  }
+
+  return cronJobs;
+};
+
+export const getCronJobs = () => cronJobs;
+
+export const setCronJobs = (jobs: StartCronJobsReturn | null) => {
+  cronJobs = jobs;
+};

package/src/singletons/databases.ts

@@ -0,0 +1,68 @@
+import { SQL } from "bun";
+
+import type { ConnectionPool } from "mssql";
+import type { Database } from "../types/configuration.ts";
+
+import { getPool as getPoolMSSQL } from "../databases/engines/mssql/connection.ts";
+import { getPool as getPoolMySQL } from "../databases/engines/mysql/connection.ts";
+import { getPool as getPoolPostgreSQL } from "../databases/engines/postgresql/connection.ts";
+
+/**
+ * Type for database connections mapping
+ * Keys are database names from configuration, values are connection pools
+ */
+export type DatabasesConnections = Record<string, SQL | ConnectionPool>;
+
+/**
+ * Type for custom repository mapping
+ * Keys are database names from configuration, values are the result of repository factory
+ */
+export type RepositoryMap<TRepository = unknown> = Record<string, TRepository>;
+
+export const databasesConnections: DatabasesConnections = {};
+export const repositoryMap: RepositoryMap = {};
+
+export const instantiateDatabasesConnections = async (databases: Database[]) => {
+  for await (const db of databases) {
+    let connection: SQL | ConnectionPool | undefined;
+
+    if (db.type === "pg") {
+      connection = await getPoolPostgreSQL(db);
+      databasesConnections[db.name] = connection;
+    } else if (db.type === "mssql") {
+      connection = await getPoolMSSQL(db);
+      databasesConnections[db.name] = connection;
+    } else if (db.type === "mysql") {
+      connection = await getPoolMySQL(db);
+      databasesConnections[db.name] = connection;
+    }
+
+    if (connection && db.onConnect) {
+      await db.onConnect(connection, db);
+    }
+
+    // Initialize custom repository if factory is provided
+    if (connection && db.repository) {
+      repositoryMap[db.name] = db.repository(connection);
+    }
+  }
+
+  return { databasesConnections, repositoryMap };
+};
+
+/**
+ * Close every open database connection and clear the singleton maps. Bun's `SQL`
+ * and mssql's `ConnectionPool` both expose `close()`. Used by
+ * `createGraphQLEngine`'s `close()` so an in-process consumer can release
+ * connections without a running server.
+ */
+export const disconnectDatabases = async () => {
+  await Promise.all(Object.values(databasesConnections).map((connection) => connection.close()));
+
+  for (const name of Object.keys(databasesConnections)) {
+    delete databasesConnections[name];
+  }
+  for (const name of Object.keys(repositoryMap)) {
+    delete repositoryMap[name];
+  }
+};

package/src/singletons/env.ts

@@ -0,0 +1,3 @@
+import { EnvZod } from "../types/env";
+
+export const env = EnvZod.parse(process.env);

package/src/singletons/queues.ts

@@ -0,0 +1,101 @@
+import type { KafkaPublisher } from "../queues/kafka";
+import type { RabbitMQPublisher } from "../queues/rabbitmq";
+import type { QueueConfig } from "../types/zod/queue";
+
+import { startKafkaConnections } from "../queues/kafka";
+import { startRabbitMQConnections } from "../queues/rabbitmq";
+import { logger } from "../logging";
+
+export type QueueConnectionStatus = { type: "rabbitmq" | "kafka"; connected: boolean };
+
+export type QueueManager = {
+  publisherMap: () => Record<string, RabbitMQPublisher | KafkaPublisher>;
+  sendMessage: (
+    publisherName: string,
+    message: string | object,
+    key?: string,
+  ) => Promise<boolean> | boolean;
+  connections: () => QueueConnectionStatus[];
+  cleanup?: () => Promise<void>;
+};
+
+export let queueManager: QueueManager | undefined;
+
+export const setQueueManager = (manager: QueueManager | undefined) => {
+  queueManager = manager;
+};
+
+export const instantiateQueues = async (queues: QueueConfig[]) => {
+  // Separate RabbitMQ and Kafka queues
+  const rabbitMQQueues = queues.filter((queue) => queue.type === "rabbitmq");
+  const kafkaQueues = queues.filter((queue) => queue.type === "kafka");
+
+  const managers: QueueManager[] = [];
+
+  // Initialize RabbitMQ connections
+  if (rabbitMQQueues.length > 0) {
+    const rabbitMQManager = await startRabbitMQConnections(rabbitMQQueues);
+
+    managers.push({
+      publisherMap: rabbitMQManager.publisherMap,
+      sendMessage: rabbitMQManager.sendMessage,
+      connections: () =>
+        rabbitMQManager.managers.map((manager) => ({
+          type: "rabbitmq" as const,
+          connected: manager.isConnected(),
+        })),
+    });
+  }
+
+  // Initialize Kafka connections
+  if (kafkaQueues.length > 0) {
+    const kafkaManager = await startKafkaConnections(kafkaQueues);
+
+    managers.push({
+      publisherMap: kafkaManager.publisherMap,
+      sendMessage: kafkaManager.sendMessage,
+      connections: () =>
+        kafkaManager.managers.map((manager) => ({
+          type: "kafka" as const,
+          connected: manager.isConnected(),
+        })),
+      cleanup: kafkaManager.cleanup,
+    });
+  }
+
+  // Merge all publisher maps and create unified send function
+  const combinedPublisherMap = () =>
+    managers.reduce((acc, manager) => ({ ...acc, ...manager.publisherMap() }), {});
+
+  const combinedSendMessage = async (
+    publisherName: string,
+    message: string | object,
+    key?: string,
+  ) => {
+    // Find which manager has this publisher
+    for (const manager of managers) {
+      if (manager.publisherMap()[publisherName]) {
+        return await manager.sendMessage(publisherName, message, key);
+      }
+    }
+
+    logger("queues").error(
+      { publisher: publisherName },
+      "publisher not found in any queue manager",
+    );
+    return false;
+  };
+
+  const combinedCleanup = async () => {
+    await Promise.all(
+      managers.filter((manager) => manager.cleanup).map((manager) => manager.cleanup!()),
+    );
+  };
+
+  queueManager = {
+    publisherMap: combinedPublisherMap,
+    sendMessage: combinedSendMessage,
+    connections: () => managers.flatMap((manager) => manager.connections()),
+    cleanup: combinedCleanup,
+  };
+};

package/src/subscriptions/index.ts

@@ -0,0 +1,20 @@
+// Types
+export type {
+  SubscriptionContext,
+  SubscriptionResult,
+  SubscriptionStrategy,
+  SubscriptionStrategyRegistry,
+  QueryEventEmitter,
+  DatabasePoller,
+} from "./types";
+
+// Strategy registry
+export {
+  createSubscriptionStrategyRegistry,
+  getStrategyForSource,
+  createDatabaseSubscriptionStrategy,
+  createQueueSubscriptionStrategy,
+} from "./strategies";
+
+// Polling utilities
+export { createDatabasePoller, type DatabasePollerConfig } from "./utils/polling";

package/src/subscriptions/strategies/database.ts

@@ -0,0 +1,68 @@
+import type { SubscriptionContext, SubscriptionResult, SubscriptionStrategy } from "../types";
+import { EntitySource } from "../../types/resolver";
+import { createDatabasePoller } from "../utils/polling";
+
+/**
+ * Database subscription strategy - polls database for changes using hash comparison
+ *
+ * This strategy:
+ * 1. Manages connection registration with the event emitter
+ * 2. Creates a poller that executes the query periodically
+ * 3. Uses hash comparison to detect data changes
+ * 4. Only broadcasts updates when data has actually changed
+ */
+export const createDatabaseSubscriptionStrategy = (): SubscriptionStrategy => ({
+  source: EntitySource.TABLE,
+
+  getSubscriptionKey(context) {
+    const { analysis } = context;
+    const operation = analysis.operations[0];
+    // Use operation name as the base key (existing behavior)
+    return operation.name ?? operation.fields[0]?.name ?? "unknown";
+  },
+
+  async subscribe(context: SubscriptionContext): Promise<SubscriptionResult> {
+    const {
+      ws,
+      subscriptionId,
+      analysis,
+      variableDefinitions,
+      variables,
+      schemaEntity,
+      eventEmitter,
+    } = context;
+
+    const subscriptionKey = this.getSubscriptionKey(context);
+
+    // Check if connection already exists - join existing subscription
+    if (eventEmitter.hasConnection(subscriptionKey)) {
+      eventEmitter.sendDataByQueryNameToSingleClient(subscriptionKey, ws, subscriptionId);
+      eventEmitter.addConnection(subscriptionKey, subscriptionId, ws);
+      return { alreadyExists: true };
+    }
+
+    // Register new connection
+    eventEmitter.addConnection(subscriptionKey, subscriptionId, ws);
+
+    // Create and start the poller
+    const poller = await createDatabasePoller({
+      analysis,
+      variableDefinitions,
+      variables,
+      schemaEntity,
+      subscriptionKey,
+      eventEmitter,
+      pollIntervalMs: 1000,
+    });
+
+    // Store poll reference for cleanup by event emitter
+    eventEmitter.setPoll(subscriptionKey, poller);
+
+    // Start polling
+    poller.start();
+
+    return {
+      cleanup: () => poller.stop(),
+    };
+  },
+});

package/src/subscriptions/strategies/index.ts

@@ -0,0 +1,38 @@
+import type { SubscriptionStrategy, SubscriptionStrategyRegistry } from "../types";
+import { EntitySource } from "../../types/resolver";
+import { createDatabaseSubscriptionStrategy } from "./database";
+import { createQueueSubscriptionStrategy } from "./queue";
+
+/**
+ * Create and populate the subscription strategy registry
+ */
+export const createSubscriptionStrategyRegistry = (): SubscriptionStrategyRegistry => {
+  const registry: SubscriptionStrategyRegistry = new Map();
+
+  // Register built-in strategies
+  const databaseStrategy = createDatabaseSubscriptionStrategy();
+  const queueStrategy = createQueueSubscriptionStrategy();
+
+  registry.set(EntitySource.TABLE, databaseStrategy);
+  registry.set(EntitySource.QUEUE_PUBLISHER, queueStrategy);
+
+  return registry;
+};
+
+/**
+ * Helper to get strategy by source, with fallback to database strategy
+ */
+export const getStrategyForSource = (
+  registry: SubscriptionStrategyRegistry,
+  source: string | undefined,
+): SubscriptionStrategy | undefined => {
+  if (!source) {
+    // Default to database strategy for backward compatibility
+    return registry.get(EntitySource.TABLE);
+  }
+  return registry.get(source);
+};
+
+// Re-export individual strategies for testing or custom registration
+export { createDatabaseSubscriptionStrategy } from "./database";
+export { createQueueSubscriptionStrategy } from "./queue";

package/src/subscriptions/strategies/queue.ts

@@ -0,0 +1,61 @@
+import type { SubscriptionContext, SubscriptionResult, SubscriptionStrategy } from "../types";
+import { EntitySource } from "../../types/resolver";
+import { filterResultBySelection } from "../../utils/selection";
+
+/**
+ * Builds a composite subscription key from the field name, alias, and
+ * selections. Clients with the exact same query (including alias and
+ * requested fields) share a single connection group; any difference
+ * produces a distinct key and therefore its own group with its own
+ * responseKey and dataTransform.
+ */
+const buildCompositeKey = (context: SubscriptionContext): string => {
+  const { field } = context;
+  return `${field.name}:${field.alias ?? ""}:${JSON.stringify(field.selections)}`;
+};
+
+/**
+ * Queue subscription strategy - leverages existing queue consumer infrastructure
+ *
+ * Queue subscriptions are push-based, unlike database subscriptions:
+ * - No polling needed - messages are pushed via the queue consumer
+ * - The queue consumer (kafka.ts/rabbitmq.ts) already calls queryEventEmitter.sendDataUpdate()
+ * - This strategy manages connection registration with the event emitter
+ */
+export const createQueueSubscriptionStrategy = (): SubscriptionStrategy => ({
+  source: EntitySource.QUEUE_PUBLISHER,
+
+  getSubscriptionKey(context) {
+    return buildCompositeKey(context);
+  },
+
+  async subscribe(context: SubscriptionContext): Promise<SubscriptionResult> {
+    const { ws, subscriptionId, eventEmitter, field } = context;
+    const subscriptionKey = this.getSubscriptionKey(context);
+    // The field key is what queue consumers broadcast on (e.g. "conn_queueName")
+    const fieldKey = field.name;
+
+    // Check if connection already exists - join existing subscription group
+    if (eventEmitter.hasConnection(subscriptionKey)) {
+      eventEmitter.sendDataByQueryNameToSingleClient(subscriptionKey, ws, subscriptionId);
+      eventEmitter.addConnection(subscriptionKey, subscriptionId, ws);
+      return { alreadyExists: true };
+    }
+
+    // Register new connection group
+    eventEmitter.addConnection(subscriptionKey, subscriptionId, ws);
+    // Tie the composite key to the field key so sendDataUpdate fan-out works
+    eventEmitter.registerFieldMapping(fieldKey, subscriptionKey);
+    // Top-level response key (handles field alias)
+    eventEmitter.setResponseKey(subscriptionKey, field.alias || field.name);
+    // Apply selection filtering and nested alias mapping to each message
+    eventEmitter.setDataTransform(subscriptionKey, (data) =>
+      filterResultBySelection(data, field.selections),
+    );
+
+    return {
+      // No cleanup needed - queue consumers manage their own lifecycle
+      cleanup: undefined,
+    };
+  },
+});

package/src/subscriptions/types.ts

@@ -0,0 +1,74 @@
+import type { ServerWebSocket } from "bun";
+import type { AnalysisResult, SelectionAnalysis, VariableDefinition } from "../analyzeQuery/types";
+import type { GetSchemaReturn } from "../configuration/getSchemas";
+import type { createQueryEventEmitter } from "../utils/event-emitter";
+
+/**
+ * Type for the query event emitter instance
+ */
+export type QueryEventEmitter = ReturnType<typeof createQueryEventEmitter>;
+
+/**
+ * Database poller interface - controls polling lifecycle
+ */
+export interface DatabasePoller {
+  start(): Timer | undefined;
+  stop(): void;
+}
+
+/**
+ * Context provided to subscription strategy handlers
+ */
+export interface SubscriptionContext {
+  /** The WebSocket connection */
+  ws: ServerWebSocket<unknown>;
+  /** Unique subscription ID from the client */
+  subscriptionId: string;
+  /** Analyzed GraphQL query */
+  analysis: AnalysisResult;
+  /** The first field being subscribed to */
+  field: SelectionAnalysis;
+  /** Variable definitions from the query */
+  variableDefinitions: VariableDefinition[];
+  /** Resolved variable values (after object flattening and $session.* replacement) */
+  variables: Record<string, unknown>;
+  /** Schema and entity information for the current role */
+  schemaEntity: GetSchemaReturn;
+  /** Shared event emitter for broadcasting updates */
+  eventEmitter: QueryEventEmitter;
+}
+
+/**
+ * Result of starting a subscription
+ */
+export interface SubscriptionResult {
+  /** Cleanup function called when subscription ends */
+  cleanup?: () => void | Promise<void>;
+  /** True if subscription was joined to an existing connection (no new poll/consumer needed) */
+  alreadyExists?: boolean;
+}
+
+/**
+ * Strategy interface for handling different subscription sources
+ */
+export interface SubscriptionStrategy {
+  /**
+   * Unique identifier for this strategy (matches EntitySource enum value)
+   */
+  readonly source: string;
+
+  /**
+   * Start the subscription and return a cleanup function
+   */
+  subscribe(context: SubscriptionContext): Promise<SubscriptionResult>;
+
+  /**
+   * Generate the unique subscription key for this subscription
+   */
+  getSubscriptionKey(context: SubscriptionContext): string;
+}
+
+/**
+ * Registry type for subscription strategies
+ */
+export type SubscriptionStrategyRegistry = Map<string, SubscriptionStrategy>;