@graphoria/server 0.1.0

package/src/subscriptions/utils/polling.ts

@@ -0,0 +1,119 @@
+import type { AnalysisResult, VariableDefinition } from "../../analyzeQuery/types";
+import type { GetSchemaReturn } from "../../configuration/getSchemas";
+import type { Database } from "../../types/configuration";
+import type { DatabasePoller, QueryEventEmitter } from "../types";
+
+import { executeQuery, executeQueryJSON, generateSQL } from "../../databases";
+import { logger } from "../../logging";
+
+export interface DatabasePollerConfig {
+  analysis: AnalysisResult;
+  variableDefinitions: VariableDefinition[];
+  variables: Record<string, unknown>;
+  schemaEntity: GetSchemaReturn;
+  subscriptionKey: string;
+  eventEmitter: QueryEventEmitter;
+  pollIntervalMs?: number;
+}
+
+/**
+ * Get the first field name from analysis
+ */
+const getFirstFieldName = (analysis: AnalysisResult): string | undefined => {
+  return analysis.operations[0]?.fields[0]?.name;
+};
+
+/**
+ * Compute hash of query results for change detection
+ */
+const getResultHash = async (
+  queryHash: string,
+  db: Database,
+  variableDefinitions: VariableDefinition[],
+  variables: Record<string, unknown>,
+): Promise<string> => {
+  const hashResult = await executeQuery<{ ResultHash: string }>(
+    queryHash,
+    db,
+    variableDefinitions,
+    variables,
+  );
+  return Buffer.from(hashResult[0].ResultHash)?.toString("hex");
+};
+
+/**
+ * Create a database poller that detects changes via hash comparison
+ */
+export const createDatabasePoller = async (
+  config: DatabasePollerConfig,
+): Promise<DatabasePoller> => {
+  const {
+    analysis,
+    variableDefinitions,
+    variables,
+    schemaEntity,
+    subscriptionKey,
+    eventEmitter,
+    pollIntervalMs = 1000,
+  } = config;
+
+  const firstFieldName = getFirstFieldName(analysis);
+  const db = schemaEntity.queriesMap[firstFieldName!]!.db!;
+
+  // Generate SQL queries (data query and hash query)
+  const [[, queryData]] = generateSQL(schemaEntity, analysis, variables);
+  const [[, queryHash]] = generateSQL(schemaEntity, analysis, variables, true);
+
+  // Get initial hash and send initial data
+  let previousHash = await getResultHash(queryHash, db, variableDefinitions, variables);
+
+  eventEmitter.sendDataUpdate(subscriptionKey, {
+    data: await executeQueryJSON(queryData, db, variableDefinitions, variables),
+  });
+
+  // Poll function that checks for changes
+  const log = logger("polling").child({ subscription: subscriptionKey });
+  const poll = async () => {
+    try {
+      const currentHash = await getResultHash(queryHash, db, variableDefinitions, variables);
+
+      if (currentHash !== previousHash) {
+        log.info(
+          { changed: !!previousHash, operation: analysis.operations[0].name },
+          previousHash ? "data changed" : "initial fetch",
+        );
+
+        previousHash = currentHash;
+
+        eventEmitter.sendDataUpdate(subscriptionKey, {
+          data: await executeQueryJSON(queryData, db, variableDefinitions, variables),
+        });
+      }
+    } catch (error) {
+      log.error({ err: error }, "polling failed");
+    }
+  };
+
+  // Poller control
+  let stopped = false;
+  let scheduledTimeout: Timer;
+
+  const poller: DatabasePoller = {
+    start() {
+      if (stopped) return;
+
+      scheduledTimeout = setTimeout(() => {
+        poll();
+        poller.start();
+      }, pollIntervalMs);
+
+      return scheduledTimeout;
+    },
+    stop() {
+      stopped = true;
+      clearTimeout(scheduledTimeout);
+    },
+  };
+
+  return poller;
+};

package/src/types/common.ts

@@ -0,0 +1,57 @@
+import type { GqlQueryResult } from "../config";
+import type { BunRequest } from "bun";
+import type { DatabasesConnections, RepositoryMap } from "../singletons/databases";
+import type { QueueManager } from "../singletons/queues";
+
+/**
+ * GraphQL query function type
+ * @param TReqOptional - Whether the request parameter is optional (true for cron jobs, false for operations)
+ */
+export type GqlQueryFn<TReqOptional extends boolean = false> = TReqOptional extends true
+  ? <TReturn = unknown>(
+      query: string,
+      params?: Record<string, unknown>,
+      req?: BunRequest,
+    ) => Promise<GqlQueryResult<TReturn>>
+  : <TReturn = unknown>(
+      query: string,
+      params: Record<string, unknown>,
+      req: BunRequest,
+    ) => Promise<GqlQueryResult<TReturn>>;
+
+/**
+ * Base callback options containing gqlQuery and database connections
+ * Used by operations, cron jobs, and other callback-based features
+ *
+ * @param TReqOptional - Whether the request parameter in gqlQuery is optional
+ */
+export type CallbackOptions<TReqOptional extends boolean = false, TRepository = unknown> = {
+  /**
+   * Execute a GraphQL query against the server
+   */
+  gqlQuery: GqlQueryFn<TReqOptional>;
+  /**
+   * Database connections available for direct database access
+   */
+  databases: DatabasesConnections;
+  /**
+   * Queue manager for managing queues
+   */
+  queues: QueueManager | undefined;
+  /**
+   * Custom database repository created from repository factory functions.
+   * Keys are database names, values are the result of the repository factory.
+   * Access with: repository["dbName"] to get the repository for that database.
+   */
+  repository: RepositoryMap<TRepository>;
+};
+
+/**
+ * Callback options with required request parameter (for operations, REST handlers)
+ */
+export type OperationCallbackOptions<TRepository = unknown> = CallbackOptions<false, TRepository>;
+
+/**
+ * Callback options with optional request parameter (for cron jobs, background tasks)
+ */
+export type BackgroundCallbackOptions<TRepository = unknown> = CallbackOptions<true, TRepository>;

package/src/types/configuration.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+import type { FilterCondition, OrderByClause } from "../config";
+import type { ConfigurationZod } from "./zod/configuration";
+
+// Re-export base types from the config module
+export type { DirectionUnion, FilterCondition, OrderByClause, VirtualColumnType } from "../config";
+
+export type Configuration = z.infer<typeof ConfigurationZod>;
+
+export type Database = Configuration["databases"][number];
+
+export type DatabaseType = Database["type"];
+
+export type ConnectionInfo = Database["connection"];
+
+export type ResolverNamePattern = Database["fieldNaming"];
+
+export type Operations = Configuration["operations"];
+
+export type Schema = NonNullable<Database["schema"]>;
+export type Relationships = Schema["database"][""]["relationships"];
+export type VirtualColumns = Schema["database"][""]["columns"];
+
+export type VirtualColumn = VirtualColumns[number];
+export type Relationship = Relationships[number];
+
+export type Auth = Configuration["auth"];
+export type Permissions = Auth["permissions"];
+export type Role = Permissions[keyof Permissions];
+
+export type TableFilter = {
+  filter?: FilterCondition;
+  orderBy?: OrderByClause[];
+};
+
+export type MessageQueue = Configuration["queues"][number];
+
+export type Publisher = MessageQueue["exchanges"][number]["publishers"][number];
+
+export type Subscriber = MessageQueue["queues"][number];
+
+export type CronJob = Configuration["cron"][number];
+
+// Virtual-column builders live in the config module; re-export so existing
+// server-internal imports (and @graphoria/server/config) keep resolving.
+export {
+  virtualColumnFunction,
+  virtualColumnExpression,
+  createYAndNToBooleanMSSQL,
+  createOneToBooleanMSSQL,
+} from "../config";

package/src/types/db.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+
+import type {
+  buildProcedureResolver,
+  buildRelationshipResolver,
+  buildTableResolver,
+} from "../databases";
+import type { TableFilter, VirtualColumn } from "./configuration";
+
+import {
+  DatabaseStructureZod,
+  StoredProcedureBaseZod,
+  StoredProcedureZod,
+  TableBaseZod,
+  TableColumnZod,
+  TableZod,
+  ViewZod,
+  VirtualColumnZod,
+} from "./zod/db";
+
+// Re-export VirtualColumnType from the config module
+export type { VirtualColumnType } from "../config";
+
+/**
+ * TYPE HIERARCHY:
+ *
+ * 1. BASE TYPES (from database):
+ *    - TableColumn: Raw column from DB (with isNullable transformed)
+ *    - VirtualColumn: Column from configuration (with virtual/function/expression properties)
+ *    - TableBase: Raw table structure
+ *    - StoredProcedureBase: Raw stored procedure structure
+ *
+ * 2. ENRICHED TYPES (with computed properties):
+ *    - Table: Base table + dashedName, dottedName, schemaName, etc.
+ *    - StoredProcedure: Base SP + dashedName, dottedName, schemaName, etc.
+ *
+ * 3. RESOLVER TYPES (with database reference & resolver info):
+ *    - TableResolver: Table + db, internalName, resolverName, relationships
+ *      Note: columns can be TableColumn[] | VirtualColumn[] depending on configuration
+ *    - ProcedureResolver: StoredProcedure + db, internalName, resolverName
+ *    - RelationshipResolver: Relationship with full resolver naming
+ */
+
+// Base types from database (raw structure)
+export type TableColumn = z.output<typeof TableColumnZod>;
+export type TableBase = z.output<typeof TableBaseZod>;
+export type StoredProcedureBase = z.output<typeof StoredProcedureBaseZod>;
+
+// Column type that can be either base or virtual
+export type Column = TableColumn | VirtualColumn;
+
+// Enriched types (with computed naming properties from Zod transforms)
+export type Table = z.infer<typeof TableZod>;
+export type StoredProcedure = z.infer<typeof StoredProcedureZod>;
+
+// Resolver types (with database references and full application context)
+// Note: These come from runtime functions since they depend on cross-table relationships
+export type RelationshipResolver = ReturnType<typeof buildRelationshipResolver>;
+type _TableResolver = ReturnType<typeof buildTableResolver>;
+
+// Override columns to allow both TableColumn and VirtualColumn
+export type TableResolver = Omit<_TableResolver, "columns"> & {
+  columns: Column[];
+  rolePermission?: TableFilter;
+};
+
+export type ProcedureResolver = ReturnType<typeof buildProcedureResolver>;
+
+// Database structure types
+export type DatabaseStructure = z.infer<typeof DatabaseStructureZod>;
+export type Tables = DatabaseStructure["tables"];
+export type StoredProcedures = DatabaseStructure["storedProcedures"];
+
+// Utility types
+export type View = z.infer<typeof ViewZod>;
+
+// Re-export Zod schemas for validation purposes
+export {
+  DatabaseStructureZod,
+  StoredProcedureBaseZod,
+  StoredProcedureZod,
+  TableBaseZod,
+  TableColumnZod,
+  TableZod,
+  VirtualColumnZod,
+  ViewZod,
+} from "./zod/db";

package/src/types/env.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+
+import { version } from "../../package.json";
+import { ConfigurationZod } from "./zod/configuration";
+
+export const EnvZod = z
+  .object({
+    PORT: z.coerce.number().default(3000),
+    NODE_ENV: z.string().default("DEVELOPMENT"),
+    ADMIN_SECRET: z.string(),
+    CONFIGURATION: z.union([z.string(), ConfigurationZod]).optional(),
+    ANONYMOUS_ROLE: z.string().default("anonymous"),
+    JWT_SECRET: z.string().optional().default(""),
+    JWT_EXPIRES_IN: z.string().default("5m"),
+    JWT_RT_EXPIRES_IN: z.string().default("7d"),
+    PASETO_LOCAL_KEY: z.string().optional().default(""),
+    PASETO_SECRET_KEY: z.string().optional().default(""),
+    PASETO_PUBLIC_KEY: z.string().optional().default(""),
+    AUTH_STRATEGY: z.enum(["jwt", "paseto_local", "paseto_public"]).optional(),
+    REDIS_URL: z.string().default("redis://localhost:6379"),
+    CACHE_STORE: z.enum(["memory", "redis"]).default("memory"),
+    REST_API_PREFIX: z.string().default("/rest"),
+    GRAPHQL_API_ENDPOINT: z.string().default("/graphql"),
+    ADMIN_SECRET_HEADER: z.string().default("x-admin-secret"),
+    AUTHORIZATION_HEADER: z.string().default("authorization"),
+    GRAPHIQL_ENDPOINT: z.string().default("/graphiql"),
+    SCALAR_ENDPOINT: z.string().default("/scalar"),
+    OPENAPI_ENDPOINT: z.string().default("/openapi.json"),
+    SUPERADMIN_ROLE: z.string().default("superadmin"),
+    // Boolean flags use stringbool, not coerce.boolean: Boolean("false") === true would flip them on
+    CONSOLE_ENABLED: z.stringbool().default(false),
+    CONSOLE_ENDPOINT: z.string().default("/_console"),
+    PREFIX: z.string().default(""),
+    CORS_ENABLED: z.stringbool().default(true),
+    PRINT_SCHEMAS: z.stringbool().default(false),
+    SCHEMAS_OUTPUT_DIR: z.string().default("./.graphoria/schemas"),
+    QUERY_ON_RESPONSE: z.stringbool().default(false),
+    MAX_QUERY_DEPTH: z.coerce.number().int().min(0).default(0),
+    AI_ENABLED: z.stringbool().optional(),
+    AI_GRAPHQL_ENABLED: z.stringbool().default(true),
+    AI_REST_ENABLED: z.stringbool().default(true),
+    AI_MCP_ENABLED: z.stringbool().optional(),
+    AI_MCP_ENDPOINT: z.string().default("/mcp"),
+    AI_MCP_REQUIRE_ADMIN_SECRET: z.stringbool().default(false),
+    AI_MCP_MAX_QUERY_DEPTH: z.coerce.number().int().min(0).optional(),
+    AI_MCP_DISABLED_TOOLS: z.string().default(""),
+    AI_MCP_DISABLED_RESOURCES: z.string().default(""),
+    AI_MCP_DISABLED_PROMPTS: z.string().default(""),
+    AI_SYSTEM_PROMPT: z.string().optional(),
+    AI_PROMPT_TEMPLATE: z.string().optional(),
+  })
+  .transform((env) => ({
+    port: env.PORT,
+    nodeEnv: env.NODE_ENV,
+    version,
+    configuration: env.CONFIGURATION,
+    prefix: env.PREFIX,
+    enableCors: env.CORS_ENABLED,
+    restApiPrefix: env.REST_API_PREFIX,
+    graphqlApiEndpoint: env.GRAPHQL_API_ENDPOINT,
+    graphiqlEndpoint: env.GRAPHIQL_ENDPOINT,
+    scalarEndpoint: env.SCALAR_ENDPOINT,
+    openApiEndpoint: env.OPENAPI_ENDPOINT,
+    authorizationHeader: env.AUTHORIZATION_HEADER,
+    anonymousRole: env.ANONYMOUS_ROLE,
+    authStrategy: env.AUTH_STRATEGY,
+    queryOnResponse: env.QUERY_ON_RESPONSE,
+    maxQueryDepth: env.MAX_QUERY_DEPTH,
+    admin: {
+      secret: env.ADMIN_SECRET,
+      header: env.ADMIN_SECRET_HEADER,
+    },
+    jwt: {
+      secret: env.JWT_SECRET,
+      expiresIn: env.JWT_EXPIRES_IN,
+      rtExpiresIn: env.JWT_RT_EXPIRES_IN,
+    },
+    paseto: {
+      localKey: env.PASETO_LOCAL_KEY,
+      secretKey: env.PASETO_SECRET_KEY,
+      publicKey: env.PASETO_PUBLIC_KEY,
+    },
+    cache: {
+      store: env.CACHE_STORE,
+      redisUrl: env.REDIS_URL,
+    },
+    schemas: {
+      print: env.PRINT_SCHEMAS,
+      outputDir: env.SCHEMAS_OUTPUT_DIR,
+    },
+    superadmin: {
+      role: env.SUPERADMIN_ROLE,
+    },
+    console: {
+      enabled: env.CONSOLE_ENABLED,
+      endpoint: env.CONSOLE_ENDPOINT,
+    },
+    ai: {
+      enabled: env.AI_ENABLED,
+      graphqlEnabled: env.AI_GRAPHQL_ENABLED,
+      restEnabled: env.AI_REST_ENABLED,
+      mcp: {
+        enabled: env.AI_MCP_ENABLED,
+        endpoint: env.AI_MCP_ENDPOINT,
+        requireAdminSecret: env.AI_MCP_REQUIRE_ADMIN_SECRET,
+        maxQueryDepth: env.AI_MCP_MAX_QUERY_DEPTH,
+        disabledTools: env.AI_MCP_DISABLED_TOOLS
+          ? env.AI_MCP_DISABLED_TOOLS.split(",")
+              .map((s) => s.trim())
+              .filter(Boolean)
+          : [],
+        disabledResources: env.AI_MCP_DISABLED_RESOURCES
+          ? env.AI_MCP_DISABLED_RESOURCES.split(",")
+              .map((s) => s.trim())
+              .filter(Boolean)
+          : [],
+        disabledPrompts: env.AI_MCP_DISABLED_PROMPTS
+          ? env.AI_MCP_DISABLED_PROMPTS.split(",")
+              .map((s) => s.trim())
+              .filter(Boolean)
+          : [],
+      },
+      systemPrompt: env.AI_SYSTEM_PROMPT,
+      promptTemplate: env.AI_PROMPT_TEMPLATE,
+    },
+  }));
+
+export type EnvInput = z.input<typeof EnvZod>;
+export type Env = z.infer<typeof EnvZod> & {
+  logger?: import("pino").Logger | import("pino").LoggerOptions;
+};
+
+declare module "bun" {
+  interface Env extends EnvInput {
+    VERSION?: string;
+  }
+}

package/src/types/resolver.ts

@@ -0,0 +1,181 @@
+import type { RemoteRESTResolved, RemoteRESTRoute } from "../remoteREST/types";
+import type { RemoteSchemaResolved } from "../remoteSchemas/types";
+import type { Publisher } from "./configuration";
+import type { ProcedureResolver, TableResolver } from "./db";
+import type { TypedOperation } from "./zod/operation";
+
+/**
+ * Entity source types - identifies where a resolver's data comes from
+ */
+export enum EntitySource {
+  /** Database table or view */
+  TABLE = "table",
+  /** Database stored procedure */
+  STORED_PROCEDURE = "stored_procedure",
+  /** Message queue (RabbitMQ, Kafka, etc.) */
+  QUEUE_PUBLISHER = "queue_publisher",
+  /** Authentication mutations (login, refresh, etc.) */
+  AUTH = "auth",
+  /** Custom operation handlers */
+  OPERATION = "operation",
+  /** Remote GraphQL schema */
+  REMOTE_SCHEMA = "remote_schema",
+  /** Remote REST API (OpenAPI) */
+  REMOTE_REST = "remote_rest",
+  /** AI agent query */
+  AI = "ai",
+}
+
+/**
+ * Base resolver entry with source identification
+ */
+export type ResolverEntryBase = {
+  source: EntitySource;
+};
+
+/**
+ * Resolver entry for database tables
+ */
+export type TableResolverEntry = ResolverEntryBase & {
+  source: EntitySource.TABLE;
+  resolver: TableResolver;
+};
+
+/**
+ * Resolver entry for stored procedures
+ */
+export type StoredProcedureResolverEntry = ResolverEntryBase & {
+  source: EntitySource.STORED_PROCEDURE;
+  resolver: ProcedureResolver;
+};
+
+/**
+ * Resolver entry for message queues
+ */
+export type QueueResolverEntry = ResolverEntryBase & {
+  source: EntitySource.QUEUE_PUBLISHER;
+  resolver: Publisher;
+};
+
+/**
+ * Resolver entry for authentication operations
+ */
+export type AuthResolverEntry = ResolverEntryBase & {
+  source: EntitySource.AUTH;
+  resolver: {
+    name: string;
+    operation: "login" | "refresh" | "logout" | "register" | "me";
+  };
+};
+
+/**
+ * Resolver entry for custom operations
+ */
+export type OperationResolverEntry = ResolverEntryBase & {
+  source: EntitySource.OPERATION;
+  // oxlint-disable-next-line typescript/no-explicit-any
+  resolver: TypedOperation<any, any, any>;
+};
+
+/**
+ * Resolver entry for remote schema fields
+ */
+export type RemoteSchemaResolverEntry = ResolverEntryBase & {
+  source: EntitySource.REMOTE_SCHEMA;
+  resolver: {
+    remoteSchema: RemoteSchemaResolved;
+    originalFieldName: string;
+  };
+};
+
+/**
+ * Resolver entry for remote REST API routes
+ */
+export type RemoteRESTResolverEntry = ResolverEntryBase & {
+  source: EntitySource.REMOTE_REST;
+  resolver: {
+    remoteREST: RemoteRESTResolved;
+    route: RemoteRESTRoute;
+  };
+};
+
+/**
+ * Resolver entry for the AI agent query
+ */
+export type AIResolverEntry = ResolverEntryBase & {
+  source: EntitySource.AI;
+  resolver: { name: string };
+};
+
+/**
+ * Union type of all resolver entries
+ */
+export type ResolverEntry =
+  | TableResolverEntry
+  | StoredProcedureResolverEntry
+  | QueueResolverEntry
+  | AuthResolverEntry
+  | OperationResolverEntry
+  | RemoteSchemaResolverEntry
+  | RemoteRESTResolverEntry
+  | AIResolverEntry;
+
+/**
+ * Registry type - plain object for fast access
+ */
+export type ResolverRegistry = Record<string, ResolverEntry>;
+
+/**
+ * Helper to create typed resolver entries
+ */
+export const createResolverEntry = {
+  table: (resolver: TableResolver): TableResolverEntry => ({
+    source: EntitySource.TABLE,
+    resolver,
+  }),
+
+  storedProcedure: (resolver: ProcedureResolver): StoredProcedureResolverEntry => ({
+    source: EntitySource.STORED_PROCEDURE,
+    resolver,
+  }),
+
+  queuePublisher: (resolver: Publisher): QueueResolverEntry => ({
+    source: EntitySource.QUEUE_PUBLISHER,
+    resolver,
+  }),
+
+  auth: (
+    name: string,
+    operation: AuthResolverEntry["resolver"]["operation"],
+  ): AuthResolverEntry => ({
+    source: EntitySource.AUTH,
+    resolver: { name, operation },
+  }),
+
+  // oxlint-disable-next-line typescript/no-explicit-any
+  operation: (resolver: TypedOperation<unknown, unknown, unknown>): OperationResolverEntry => ({
+    source: EntitySource.OPERATION,
+    resolver,
+  }),
+
+  remoteSchema: (
+    remoteSchema: RemoteSchemaResolved,
+    originalFieldName: string,
+  ): RemoteSchemaResolverEntry => ({
+    source: EntitySource.REMOTE_SCHEMA,
+    resolver: { remoteSchema, originalFieldName },
+  }),
+
+  remoteREST: (
+    remoteREST: RemoteRESTResolved,
+    route: RemoteRESTRoute,
+  ): RemoteRESTResolverEntry => ({
+    source: EntitySource.REMOTE_REST,
+    resolver: { remoteREST, route },
+  }),
+
+  ai: (name: string): AIResolverEntry => ({
+    source: EntitySource.AI,
+    resolver: { name },
+  }),
+};

package/src/types/zod/ai.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+import { AIZod, MCPZod } from "../../config/types/ai";
+
+export { AIZod, MCPZod };
+
+/** Runtime (z.output) type for AI configuration — used by singletons/ai.ts */
+export type AIConfig = z.output<typeof AIZod>;