@graphoria/server 0.1.0

package/src/config/types/index.ts

@@ -0,0 +1,129 @@
+// Virtual column types and helpers
+export type {
+  VirtualColumnType,
+  VirtualColumnFunctionFn,
+  VirtualColumnExpressionFn,
+  CreateYAndNToBooleanMSSQLFn,
+  CreateOneToBooleanMSSQLFn,
+} from "./virtual-columns";
+
+export {
+  virtualColumnFunction,
+  virtualColumnExpression,
+  createYAndNToBooleanMSSQL,
+  createOneToBooleanMSSQL,
+  VirtualColumnZod,
+} from "./virtual-columns";
+
+// Operation types and Zod schemas
+export type {
+  DefaultInput,
+  OperationRestConfig,
+  OperationGraphQLConfig,
+  OperationCacheConfig,
+  BeforeRequestContext,
+  AfterRequestContext,
+  GqlQueryResult,
+  OperationOptions,
+  OperationInitHook,
+  OperationBeforeRequestHook,
+  OperationAfterRequestHook,
+  OperationHandler,
+  BaseOperation,
+  QueryOperation,
+  HandlerOperation,
+  TypedOperation,
+  Operation,
+  Operations,
+} from "./operation";
+
+export {
+  OperationRestConfigZod,
+  OperationGraphQLConfigZod,
+  OperationCacheConfigZod,
+  OperationZod,
+  OperationsZod,
+} from "./operation";
+
+// Cron types
+export type { CronTickCallback, CronJobConfig } from "./cron";
+
+// AI / MCP types
+export type { AIConfig, MCPConfig } from "./ai";
+
+// Remote schema types
+export type { RemoteSchemaConfig, RemoteSchemaIntrospectionConfig } from "./remote-schema";
+
+// Remote REST types
+export type { RemoteRESTConfig } from "./remote-rest";
+
+// Queue types and Zod schemas
+export type {
+  ReconnectConfig,
+  PublisherConfig,
+  SubscriberConfig,
+  TopicConfig,
+  CacheContext,
+  SubscriberHandler,
+  RabbitMQConnection,
+  KafkaConnection,
+  QueueConfig,
+} from "./queue";
+
+export {
+  ReconnectConfigZod,
+  PublisherConfigZod,
+  SubscriberConfigZod,
+  TopicConfigZod,
+  BaseQueueConfigZod,
+  RabbitMQConnectionZod,
+  KafkaConnectionZod,
+} from "./queue";
+
+// Auth types and Zod schemas
+export type {
+  DirectionUnion,
+  OrderByClause,
+  FilterCondition,
+  TablePermission,
+  RolePermission,
+  AuthConfig,
+} from "./auth";
+
+export {
+  DirectionUnionZod,
+  OrderByClauseZod,
+  FilterConditionZod,
+  TablePermissionZod,
+  RolePermissionZod,
+  AuthConfigZod,
+} from "./auth";
+
+// Database types and Zod schemas
+export type {
+  DatabaseType,
+  DatabaseConnection,
+  TableRelationship,
+  TableSchemaConfig,
+  DatabaseSchemaConfig,
+  CustomRepositoryFactory,
+  DatabaseConfig,
+  OnConnectHandler,
+  BunSQLConnectionOptions,
+  MSSQLConnectionOptions,
+  ConnectionOptionsForType,
+  AnyDatabaseConfig,
+} from "./db";
+
+export {
+  TableRelationshipZod,
+  TableSchemaConfigZod,
+  DatabaseSchemaConfigZod,
+  BunSQLConnectionOptionsZod,
+  MSSQLConnectionOptionsZod,
+  DatabaseConnectionZod,
+} from "./db";
+
+export type { ConfigurationInput, TokenStrategy } from "./configuration";
+
+export { TokenStrategyZod } from "./configuration";

package/src/config/types/operation.ts

@@ -0,0 +1,253 @@
+import { z } from "zod";
+
+/**
+ * Default input type when no schema is provided
+ */
+export type DefaultInput = Record<string, unknown>;
+
+// ============================================================================
+// Zod Schemas for Runtime Validation
+// ============================================================================
+
+/**
+ * Zod schema for REST configuration
+ */
+export const OperationRestConfigZod = z.object({
+  path: z.string(),
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET"),
+  pathParams: z.custom<z.ZodType>().optional(),
+  queryParams: z.custom<z.ZodType>().optional(),
+  body: z.custom<z.ZodType>().optional(),
+});
+
+/**
+ * Zod schema for GraphQL configuration
+ */
+export const OperationGraphQLConfigZod = z.object({
+  enabled: z.boolean().optional().default(true),
+  name: z.string().optional(),
+});
+
+/**
+ * Zod schema for cache configuration
+ */
+export const OperationCacheConfigZod = z.object({
+  max: z.number().int().positive().optional(),
+  maxSize: z.number().int().positive().optional(),
+  ttl: z.number().int().positive().optional(),
+  allowStale: z.boolean().optional(),
+  updateAgeOnGet: z.boolean().optional(),
+  updateAgeOnHas: z.boolean().optional().default(false),
+  ttlAutopurge: z.boolean().optional().default(true),
+});
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/**
+ * REST exposure configuration for an operation
+ */
+export type OperationRestConfig = z.input<typeof OperationRestConfigZod>;
+
+/**
+ * GraphQL exposure configuration for an operation
+ */
+export type OperationGraphQLConfig = z.input<typeof OperationGraphQLConfigZod>;
+
+/**
+ * Cache configuration for an operation
+ */
+export type OperationCacheConfig = z.input<typeof OperationCacheConfigZod>;
+
+// ============================================================================
+// Runtime Operation Validation Schema
+// ============================================================================
+
+export const OperationZod = z
+  .object({
+    description: z.string().optional(),
+    query: z.string().optional(),
+    // oxlint-disable-next-line typescript/no-explicit-any
+    handler: z.custom<OperationHandler<any, any, any>>().optional(),
+    // oxlint-disable-next-line typescript/no-explicit-any
+    input: z.custom<z.ZodType<any>>().optional(),
+    // oxlint-disable-next-line typescript/no-explicit-any
+    output: z.custom<z.ZodType<any>>().optional(),
+    hooks: z
+      .object({
+        // oxlint-disable-next-line typescript/no-explicit-any
+        init: z.custom<OperationInitHook<any>>().optional(),
+        beforeRequest: z
+          // oxlint-disable-next-line typescript/no-explicit-any
+          .custom<OperationBeforeRequestHook<any, any, any>>()
+          .optional(),
+        // oxlint-disable-next-line typescript/no-explicit-any
+        afterRequest: z.custom<OperationAfterRequestHook<any>>().optional(),
+      })
+      .optional(),
+    rest: OperationRestConfigZod.optional(),
+    graphql: OperationGraphQLConfigZod.optional().default({ enabled: true }),
+    cache: OperationCacheConfigZod.optional(),
+  })
+  .refine(
+    (operation) => {
+      const hasQuery = operation.query !== undefined;
+      const hasHandler = operation.handler !== undefined;
+      return (hasQuery || hasHandler) && !(hasQuery && hasHandler);
+    },
+    {
+      message: "Operation must have either 'query' or 'handler', but not both",
+    },
+  );
+
+export type Operation = z.input<typeof OperationZod>;
+
+export const OperationsZod = z.record(z.string(), OperationZod);
+
+export type Operations = z.input<typeof OperationsZod>;
+
+/**
+ * Context passed to beforeRequest hook
+ */
+export type BeforeRequestContext<TInput = DefaultInput> = {
+  input: TInput;
+};
+
+/**
+ * Context passed to afterRequest hook
+ */
+export type AfterRequestContext<TOutput = unknown> = {
+  output: TOutput;
+};
+
+/**
+ * Result type for GraphQL queries
+ */
+export type GqlQueryResult<TReturn = unknown> = {
+  data: TReturn;
+  errors?: unknown[];
+};
+
+/**
+ * Base options passed to operation handlers and hooks.
+ * This is a simplified type for configuration purposes.
+ * At runtime, @graphoria/server provides a fully-typed version with BunRequest support.
+ */
+export type OperationOptions<TRepository = unknown> = {
+  // oxlint-disable-next-line typescript/no-explicit-any
+  gqlQuery: <TReturn = unknown>(
+    query: string,
+    params?: Record<string, unknown>,
+    // oxlint-disable-next-line typescript/no-explicit-any
+    req?: any,
+  ) => Promise<GqlQueryResult<TReturn>>;
+  // oxlint-disable-next-line typescript/no-explicit-any
+  databases: any;
+  // oxlint-disable-next-line typescript/no-explicit-any
+  queues: any;
+  /**
+   * Custom repositories keyed by database name (`repository[dbName]`).
+   * `TRepository` is that whole map — e.g. `{ main: MainRepo }`.
+   */
+  repository: TRepository;
+};
+
+/**
+ * Init hook - runs once at startup, can return cached data
+ */
+export type OperationInitHook<TInitData = unknown> = (
+  options: OperationOptions,
+) => TInitData | Promise<TInitData>;
+
+/**
+ * BeforeRequest hook - transforms input before execution
+ */
+export type OperationBeforeRequestHook<
+  TInput = DefaultInput,
+  TInitData = unknown,
+  TVariables = Record<string, unknown>,
+> = (
+  context: BeforeRequestContext<TInput>,
+  initData: TInitData | undefined,
+) => TVariables | Promise<TVariables>;
+
+/**
+ * AfterRequest hook - transforms output after execution
+ */
+export type OperationAfterRequestHook<TOutput = unknown> = (
+  context: AfterRequestContext<TOutput>,
+) => TOutput | Promise<TOutput>;
+
+/**
+ * Custom handler function for operations with custom logic
+ */
+export type OperationHandler<TInput = DefaultInput, TOutput = unknown, TRepository = unknown> = (
+  options: OperationOptions<TRepository>,
+  input: TInput,
+) => TOutput | Promise<TOutput>;
+
+/**
+ * Base operation properties shared by all operation types
+ */
+export type BaseOperation<TInput, TOutput, TInitData> = {
+  /** Description for documentation */
+  description?: string;
+  /** Input schema (Zod) - defines what the operation accepts */
+  input?: z.ZodType<TInput>;
+  /** Output schema (Zod) - defines what the operation returns (for OpenAPI) */
+  output?: z.ZodType<TOutput>;
+  /** Hooks for initialization and request transformation */
+  hooks?: {
+    init?: OperationInitHook<TInitData>;
+    beforeRequest?: OperationBeforeRequestHook<TInput, TInitData>;
+    afterRequest?: OperationAfterRequestHook<TOutput>;
+  };
+  /** REST exposure configuration */
+  rest?: OperationRestConfig;
+  /** GraphQL exposure configuration (enabled by default) */
+  graphql?: OperationGraphQLConfig;
+  /** Cache configuration */
+  cache?: OperationCacheConfig;
+};
+
+/**
+ * Query-based operation - executes a GraphQL query
+ */
+export type QueryOperation<
+  TInput = DefaultInput,
+  TOutput = unknown,
+  TInitData = unknown,
+> = BaseOperation<TInput, TOutput, TInitData> & {
+  /** GraphQL query to execute */
+  query: string;
+  /** Custom handler is not allowed with query */
+  handler?: never;
+};
+
+/**
+ * Handler-based operation - executes custom logic
+ */
+export type HandlerOperation<
+  TInput = DefaultInput,
+  TOutput = unknown,
+  TInitData = unknown,
+  TRepository = unknown,
+> = BaseOperation<TInput, TOutput, TInitData> & {
+  /** Query is not allowed with handler */
+  query?: never;
+  /** Custom handler function */
+  handler: OperationHandler<TInput, TOutput, TRepository>;
+};
+
+/**
+ * Union type for typed operations - must have either query OR handler
+ */
+export type TypedOperation<
+  TInput = DefaultInput,
+  TOutput = unknown,
+  TInitData = unknown,
+  TRepository = unknown,
+> =
+  | QueryOperation<TInput, TOutput, TInitData>
+  | HandlerOperation<TInput, TOutput, TInitData, TRepository>;

package/src/config/types/queue.ts

@@ -0,0 +1,172 @@
+import { z } from "zod";
+
+// ============================================================================
+// Base Zod Schemas for Queue Configuration
+// ============================================================================
+// These are the pre-transform base schemas — the single source of truth for
+// queue config authoring types. Server-only extensions and the publishers/
+// subscribers/topics → exchanges/queues pivot transform live in types/zod/queue.ts.
+
+/**
+ * Reconnection configuration
+ */
+export const ReconnectConfigZod = z.object({
+  /** Initial delay before first reconnect attempt (ms) */
+  initialDelay: z.number().int().positive().default(1000),
+  /** Maximum delay between reconnect attempts (ms) */
+  maxDelay: z.number().int().positive().default(30000),
+  /** Multiplier for exponential backoff */
+  multiplier: z.number().positive().default(2),
+  /** Maximum number of reconnect attempts (0 = infinite) */
+  maxAttempts: z.number().int().nonnegative().default(0),
+});
+
+export type ReconnectConfig = z.input<typeof ReconnectConfigZod>;
+
+/**
+ * Publisher configuration — defines how to send messages
+ */
+export const PublisherConfigZod = z.object({
+  /** Topic/Exchange name to publish to */
+  topic: z.string(),
+  /** Routing key (RabbitMQ) or message key (Kafka) */
+  routingKey: z.string().optional(),
+  /** Whether messages should survive broker restart (RabbitMQ only) */
+  persistent: z.boolean().optional().default(true),
+  /** Custom headers (Kafka only) */
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+export type PublisherConfig = z.input<typeof PublisherConfigZod>;
+
+/**
+ * Cache invalidation context passed to subscriber handlers
+ */
+export type CacheContext = {
+  invalidate: (operationName: string, pattern?: Record<string, unknown>) => Promise<boolean>;
+};
+
+/**
+ * Subscriber handler function — single canonical spelling used by both
+ * SubscriberConfigZod and the transformQueueConfig return type.
+ */
+export type SubscriberHandler = (
+  message: unknown,
+  context: { cache: CacheContext },
+) => Promise<void> | void;
+
+/**
+ * Subscriber configuration — defines how to receive messages
+ */
+export const SubscriberConfigZod = z.object({
+  /** Topic/Exchange name to subscribe to */
+  topic: z.string(),
+  /** Pattern for filtering messages (routing key pattern for RabbitMQ) */
+  pattern: z.string().optional().default("#"),
+  /** Explicit queue name (RabbitMQ) — auto-generated if not provided */
+  queue: z.string().optional(),
+  /** Consumer group ID (Kafka) — auto-generated if not provided */
+  group: z.string().optional(),
+  /** Whether queue should survive broker restart (RabbitMQ only) */
+  durable: z.boolean().optional(),
+  /** Whether queue should auto-delete when no consumers (RabbitMQ only) */
+  autoDelete: z.boolean().optional(),
+  /** Handler function to process received messages */
+  handler: z.custom<SubscriberHandler>().optional(),
+});
+
+export type SubscriberConfig = z.input<typeof SubscriberConfigZod>;
+
+/**
+ * Topic/Exchange configuration — for auto-setup
+ */
+export const TopicConfigZod = z.object({
+  /** Exchange type (RabbitMQ only) */
+  type: z.enum(["direct", "fanout", "topic", "headers"]).optional().default("topic"),
+  /** Whether exchange should survive broker restart */
+  durable: z.boolean().optional().default(true),
+  /** Whether exchange should auto-delete when no bindings */
+  autoDelete: z.boolean().optional().default(false),
+});
+
+export type TopicConfig = z.input<typeof TopicConfigZod>;
+
+/**
+ * Base queue configuration shared by all providers
+ */
+export const BaseQueueConfigZod = z.object({
+  /** Unique name for this queue connection */
+  name: z.string(),
+  /** Whether to auto-create topics/exchanges/queues */
+  autoSetup: z.boolean().optional().default(true),
+  /** Whether this queue is enabled */
+  enabled: z.boolean().optional().default(true),
+  /** Reconnection configuration */
+  reconnect: ReconnectConfigZod.optional(),
+  /** Publishers keyed by resolver name — become GraphQL mutations */
+  publishers: z.record(z.string(), PublisherConfigZod).optional().default({}),
+  /** Subscribers keyed by subscription name — become GraphQL subscriptions */
+  subscribers: z.record(z.string(), SubscriberConfigZod).optional().default({}),
+  /** Topic configurations for customizing auto-setup behavior */
+  topics: z.record(z.string(), TopicConfigZod).optional().default({}),
+});
+
+// ============================================================================
+// Connection Schemas
+// ============================================================================
+
+/**
+ * RabbitMQ connection configuration (object form)
+ */
+export const RabbitMQConnectionZod = z.object({
+  hostname: z.string().default("localhost"),
+  port: z.number().default(5672),
+  username: z.string().optional(),
+  password: z.string().optional(),
+  vhost: z.string().default("/"),
+});
+
+export type RabbitMQConnection = z.input<typeof RabbitMQConnectionZod>;
+
+/**
+ * Kafka connection configuration
+ */
+export const KafkaConnectionZod = z.object({
+  /** Broker addresses — "host:port" or ["host1:port1", "host2:port2"] */
+  brokers: z.union([z.string(), z.array(z.string())]),
+  /** Client identifier sent to the broker (default: "datagraph-<queue name>") */
+  clientId: z.string().optional(),
+  /** Enable SSL/TLS */
+  ssl: z.boolean().optional().default(false),
+  /** SASL authentication (optional) */
+  sasl: z
+    .object({
+      mechanism: z.enum(["plain", "scram-sha-256", "scram-sha-512"]).optional().default("plain"),
+      username: z.string(),
+      password: z.string(),
+    })
+    .optional(),
+});
+
+export type KafkaConnection = z.input<typeof KafkaConnectionZod>;
+
+// ============================================================================
+// Pre-transform Queue Config Union (used by ConfigurationInput)
+// ============================================================================
+// These mirror the .extend() logic in types/zod/queue.ts — the shape users
+// write in graphoria.ts before transformQueueConfig derives exchanges/queues.
+
+/** RabbitMQ queue config as authored by the user (pre-transform) */
+export type RabbitMQQueueConfig = z.input<typeof BaseQueueConfigZod> & {
+  type: "rabbitmq";
+  connection: string | RabbitMQConnection;
+};
+
+/** Kafka queue config as authored by the user (pre-transform) */
+export type KafkaQueueConfig = z.input<typeof BaseQueueConfigZod> & {
+  type: "kafka";
+  connection: string | KafkaConnection;
+};
+
+/** Queue configuration union — the shape users write in graphoria.ts */
+export type QueueConfig = RabbitMQQueueConfig | KafkaQueueConfig;

package/src/config/types/remote-rest.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+/**
+ * Remote REST API configuration (OpenAPI-based)
+ */
+export const RemoteRESTConfigZod = z.object({
+  /** Unique identifier for this remote REST API */
+  name: z.string().min(1),
+  /** Base URL of the remote API for proxying requests */
+  url: z.url().optional(),
+  /** URL to fetch the OpenAPI spec from */
+  specUrl: z.url().optional(),
+  /** Local file path to the OpenAPI spec (JSON or YAML) */
+  specPath: z.string().optional(),
+  /** Whether the remote REST API is enabled (default: true) */
+  enabled: z.boolean().optional().default(true),
+  /** Subpath prefix under /rest (default: name) */
+  prefix: z.string().optional(),
+  /** Static headers to send with every proxied request */
+  headers: z.record(z.string(), z.string()).optional(),
+  /** Client headers to forward to the remote endpoint */
+  forwardHeaders: z.array(z.string()).optional(),
+  /** Request timeout in milliseconds (default: 10000) */
+  timeout: z.number().int().positive().optional().default(10000),
+});
+
+/** Authoring type for remote REST API config */
+export type RemoteRESTConfig = z.input<typeof RemoteRESTConfigZod>;

package/src/config/types/remote-schema.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+/**
+ * Remote GraphQL schema introspection configuration
+ */
+export const RemoteSchemaIntrospectionConfigZod = z
+  .object({
+    /** Re-introspect interval in ms (0 = only at startup, default: 0) */
+    interval: z.number().int().min(0).optional().default(0),
+  })
+  .optional();
+
+/** Authoring type for remote schema introspection config */
+export type RemoteSchemaIntrospectionConfig = z.input<typeof RemoteSchemaIntrospectionConfigZod>;
+
+/**
+ * Remote GraphQL schema configuration
+ */
+export const RemoteSchemaConfigZod = z.object({
+  /** Unique identifier for this remote schema */
+  name: z.string().min(1),
+  /** Remote GraphQL endpoint URL */
+  url: z.url(),
+  /** Whether the remote schema is enabled (default: true) */
+  enabled: z.boolean().optional().default(true),
+  /** Type/field prefix (default: name + "_") */
+  prefix: z.string().optional(),
+  /** Static headers to send with every request */
+  headers: z.record(z.string(), z.string()).optional(),
+  /** Client headers to forward to the remote endpoint */
+  forwardHeaders: z.array(z.string()).optional(),
+  /** Request timeout in milliseconds (default: 10000) */
+  timeout: z.number().int().positive().optional().default(10000),
+  /** Introspection configuration */
+  introspection: RemoteSchemaIntrospectionConfigZod,
+});
+
+/** Authoring type for remote GraphQL schema config */
+export type RemoteSchemaConfig = z.input<typeof RemoteSchemaConfigZod>;