@graphoria/server 0.1.0

package/src/cli/seedAuthArgs.ts

@@ -0,0 +1,50 @@
+import { parseArgs } from "util";
+
+export type SeedAuthArgs = {
+  user: string;
+  password: string;
+  role: string;
+  config: string;
+  claims?: Record<string, unknown>;
+};
+
+const parseClaims = (raw: string | undefined): Record<string, unknown> => {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("--claims must be a JSON object");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid --claims JSON: ${msg}`);
+  }
+};
+
+export const parseSeedAuthArgs = (argv: string[]): SeedAuthArgs => {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      user: { type: "string", short: "u" },
+      password: { type: "string", short: "p" },
+      role: { type: "string", short: "r" },
+      config: { type: "string", short: "c" },
+      claims: { type: "string" },
+    },
+    strict: true,
+  });
+
+  if (!values.user) throw new Error("--user is required");
+  if (!values.password) throw new Error("--password is required");
+  if (!values.role) throw new Error("--role is required");
+  if (!values.config) throw new Error("--config is required");
+
+  return {
+    user: values.user,
+    password: values.password,
+    role: values.role,
+    config: values.config,
+    claims: parseClaims(values.claims),
+  };
+};

package/src/config/helpers/cronHelper.ts

@@ -0,0 +1,29 @@
+import type { DefaultVariables, TypedCronJob } from "../types/cron";
+
+import { createTypedCronJobZod } from "../types/cron";
+
+/**
+ * Helper function to create a typed cron job with Zod validation
+ * Use this when you want runtime validation of the cron job configuration
+ *
+ * @example
+ * ```typescript
+ * const cleanupJob = cron({
+ *   name: "cleanup",
+ *   pattern: "0 0 * * *",
+ *   variables: { maxAge: 30 },
+ *   onTick: async (gqlQuery, context) => {
+ *     // context.variables is typed as { maxAge: number }
+ *     const result = await gqlQuery(`mutation { deleteOld { affected_rows } }`);
+ *     console.log(`Deleted ${result.data.affected_rows} rows`);
+ *   },
+ * });
+ * ```
+ */
+export const cron = <TVariables extends DefaultVariables>(
+  config: TypedCronJob<TVariables>,
+): TypedCronJob<TVariables> => {
+  const schema = createTypedCronJobZod<TVariables>();
+
+  return schema.parse(config) as TypedCronJob<TVariables>;
+};

package/src/config/helpers/index.ts

@@ -0,0 +1,8 @@
+export {
+  operation,
+  type InferOperationInput,
+  type InferOperationOutput,
+  type InferOperationInitData,
+} from "./operationHelper";
+export { cron } from "./cronHelper";
+export { queue } from "./queueHelper";

package/src/config/helpers/operationHelper.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+
+import type {
+  DefaultInput,
+  HandlerOperation,
+  OperationHandler,
+  QueryOperation,
+  TypedOperation,
+} from "../types/operation";
+
+// ============================================================================
+// Type-safe operation helper with overloads
+// ============================================================================
+
+/**
+ * Helper type to infer input type from Zod schema
+ */
+type InferInput<TInputSchema> = TInputSchema extends z.ZodType<infer T> ? T : DefaultInput;
+
+/**
+ * Helper type to infer output type from Zod schema
+ */
+type InferOutput<TOutputSchema> = TOutputSchema extends z.ZodType<infer T> ? T : unknown;
+
+/**
+ * Config type for handler-based operations with inference
+ */
+type HandlerOperationConfig<
+  TRepository,
+  TInputSchema extends z.ZodType | undefined,
+  TOutputSchema extends z.ZodType | undefined,
+  TInitData,
+> = Omit<
+  HandlerOperation<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TInitData, TRepository>,
+  "handler" | "input" | "output"
+> & {
+  input?: TInputSchema;
+  output?: TOutputSchema;
+  handler: OperationHandler<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TRepository>;
+};
+
+/**
+ * Config type for query-based operations with inference
+ */
+type QueryOperationConfig<
+  TInputSchema extends z.ZodType | undefined,
+  TOutputSchema extends z.ZodType | undefined,
+  TInitData,
+> = Omit<
+  QueryOperation<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TInitData>,
+  "input" | "output"
+> & {
+  input?: TInputSchema;
+  output?: TOutputSchema;
+};
+
+// Overload 1: Query-based operation (has `query`, no `handler`)
+export function operation<
+  TInputSchema extends z.ZodType | undefined = undefined,
+  TOutputSchema extends z.ZodType | undefined = undefined,
+  TInitData = unknown,
+>(
+  config: QueryOperationConfig<TInputSchema, TOutputSchema, TInitData>,
+): QueryOperation<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TInitData>;
+
+// Overload 2: Handler-based operation without custom repository type (no generic provided)
+export function operation<
+  TInputSchema extends z.ZodType | undefined = undefined,
+  TOutputSchema extends z.ZodType | undefined = undefined,
+  TInitData = unknown,
+>(
+  config: HandlerOperationConfig<unknown, TInputSchema, TOutputSchema, TInitData>,
+): HandlerOperation<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TInitData, unknown>;
+
+// Implementation
+export function operation(config: unknown): unknown {
+  return config;
+}
+
+/**
+ * Creates a typed operation helper with custom repository type.
+ * Use this when you need typed access to repository in the handler.
+ *
+ * The generic is the databases map, keyed by database name (the same keys as
+ * `databases[].name`): at runtime `options.repository` holds one entry per
+ * database, so access a database's repository with `repository[dbName]`.
+ *
+ * @example
+ * ```ts
+ * type MainRepository = {
+ *   users: { create: (data: UserInput) => Promise<User> };
+ * };
+ *
+ * const createUser = operation.typed<{ main: MainRepository }>()({
+ *   input: z.object({ name: z.string(), email: z.string() }),
+ *   handler: async ({ repository }, input) => {
+ *     // repository is typed as { main: MainRepository }
+ *     const user = await repository.main.users.create(input);
+ *     return { id: user.id };
+ *   },
+ * });
+ * ```
+ */
+operation.typed = <TRepository>() => {
+  return <
+    TInputSchema extends z.ZodType | undefined = undefined,
+    TOutputSchema extends z.ZodType | undefined = undefined,
+    TInitData = unknown,
+  >(
+    config: HandlerOperationConfig<TRepository, TInputSchema, TOutputSchema, TInitData>,
+  ): HandlerOperation<
+    InferInput<TInputSchema>,
+    InferOutput<TOutputSchema>,
+    TInitData,
+    TRepository
+  > => {
+    return config as HandlerOperation<
+      InferInput<TInputSchema>,
+      InferOutput<TOutputSchema>,
+      TInitData,
+      TRepository
+    >;
+  };
+};
+
+// ============================================================================
+// Type utilities for operations
+// ============================================================================
+
+/**
+ * Infer the input type from an operation
+ */
+export type InferOperationInput<T> =
+  T extends TypedOperation<infer TInput, unknown, unknown> ? TInput : never;
+
+/**
+ * Infer the output type from an operation
+ */
+export type InferOperationOutput<T> =
+  T extends TypedOperation<unknown, infer TOutput, unknown> ? TOutput : never;
+
+/**
+ * Infer the init data type from an operation
+ */
+export type InferOperationInitData<T> =
+  T extends TypedOperation<unknown, unknown, infer TInitData> ? TInitData : never;

package/src/config/helpers/queueHelper.ts

@@ -0,0 +1,27 @@
+import type { KafkaConfigInput, RabbitMQConfigInput } from "../../types/zod/queue";
+
+/**
+ * Builder for a queue (RabbitMQ or Kafka) configuration. Adds the `type`
+ * discriminator so the rest of the config object can be written without it.
+ *
+ * @example
+ * ```ts
+ * import { queue } from "@graphoria/server/config";
+ *
+ * queues: [
+ *   queue.rabbitmq({ name: "events", connection: "amqp://localhost" }),
+ *   queue.kafka({ name: "events", connection: { brokers: ["localhost:9092"] } }),
+ * ];
+ * ```
+ */
+export const queue = {
+  rabbitmq: (config: Omit<RabbitMQConfigInput, "type">): RabbitMQConfigInput => ({
+    ...config,
+    type: "rabbitmq",
+  }),
+
+  kafka: (config: Omit<KafkaConfigInput, "type">): KafkaConfigInput => ({
+    ...config,
+    type: "kafka",
+  }),
+};

package/src/config/index.ts

@@ -0,0 +1,315 @@
+/**
+ * Configuration-authoring surface for `graphoria.ts` files.
+ *
+ * Exposed as `@graphoria/server/config`: the full configuration API
+ * (helpers + types) plus the server-only runtime maps, so consumers can
+ * install `@graphoria/server` alone and import everything a config file
+ * needs from `@graphoria/server/config`.
+ *
+ * @example
+ * ```ts
+ * import { operation, queue, z } from "@graphoria/server/config";
+ * import type { ConfigurationFn } from "@graphoria/server/config";
+ *
+ * const ping = operation({
+ *   input: z.object({}),
+ *   output: z.string(),
+ *   handler: async () => "pong",
+ * });
+ * ```
+ */
+// oxlint-disable typescript/no-explicit-any
+import { z } from "zod";
+
+import type {
+  ConfigurationInput,
+  CreateOneToBooleanMSSQLFn,
+  CreateYAndNToBooleanMSSQLFn,
+  DefaultInput,
+  OperationCacheConfig,
+  OperationGraphQLConfig,
+  OperationHandler,
+  OperationOptions,
+  OperationRestConfig,
+  TypedOperation,
+  VirtualColumnExpressionFn,
+  VirtualColumnFunctionFn,
+} from "./types";
+
+// ============================================================================
+// Operation Helper Function Type
+// ============================================================================
+
+/**
+ * Helper type to infer the output type from a Zod schema
+ * Uses z.output to get the transformed/parsed output type
+ */
+type InferZodOutput<T> = T extends z.ZodType<infer O, any, any> ? O : never;
+
+/**
+ * Infer TOutput from TOutputSchema
+ */
+type InferOutput<TOutputSchema> =
+  TOutputSchema extends z.ZodType<any> ? InferZodOutput<TOutputSchema> : unknown;
+
+/**
+ * Type for the operation helper function provided by @graphoria/server.
+ *
+ * This uses a simplified approach where we accept any ZodObject for input/output
+ * and return TypedOperation with appropriate type inference.
+ */
+export type OperationFn = {
+  // Query operation overload - with input schema
+  <
+    TInputSchema extends z.ZodObject<any>,
+    TOutputSchema extends z.ZodType<any> | undefined = undefined,
+    TInitData = unknown,
+  >(config: {
+    /** GraphQL query to execute */
+    query: string;
+    /** Custom handler is not allowed with query */
+    handler?: never;
+    /** Description for documentation */
+    description?: string;
+    /** Input schema (Zod) */
+    input: TInputSchema;
+    /** Output schema (Zod) */
+    output?: TOutputSchema;
+    /** Hooks for initialization and request transformation */
+    hooks?: {
+      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
+      beforeRequest?: (
+        context: { input: z.infer<TInputSchema> },
+        initData: TInitData | undefined,
+      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+      afterRequest?: (context: {
+        output: InferOutput<TOutputSchema>;
+      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
+    };
+    /** REST exposure configuration */
+    rest?: OperationRestConfig;
+    /** GraphQL exposure configuration (enabled by default) */
+    graphql?: OperationGraphQLConfig;
+    /** Cache configuration */
+    cache?: OperationCacheConfig;
+  }): TypedOperation<z.infer<TInputSchema>, InferOutput<TOutputSchema>, TInitData, unknown>;
+
+  // Query operation overload - without input schema
+  <TOutputSchema extends z.ZodType<any> | undefined = undefined, TInitData = unknown>(config: {
+    /** GraphQL query to execute */
+    query: string;
+    /** Custom handler is not allowed with query */
+    handler?: never;
+    /** Description for documentation */
+    description?: string;
+    /** Input schema (Zod) */
+    input?: undefined;
+    /** Output schema (Zod) */
+    output?: TOutputSchema;
+    /** Hooks for initialization and request transformation */
+    hooks?: {
+      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
+      beforeRequest?: (
+        context: { input: DefaultInput },
+        initData: TInitData | undefined,
+      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+      afterRequest?: (context: {
+        output: InferOutput<TOutputSchema>;
+      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
+    };
+    /** REST exposure configuration */
+    rest?: OperationRestConfig;
+    /** GraphQL exposure configuration (enabled by default) */
+    graphql?: OperationGraphQLConfig;
+    /** Cache configuration */
+    cache?: OperationCacheConfig;
+  }): TypedOperation<DefaultInput, InferOutput<TOutputSchema>, TInitData, unknown>;
+
+  // Handler operation overload - with input schema
+  <
+    TInputSchema extends z.ZodObject<any>,
+    TOutputSchema extends z.ZodType<any> | undefined = undefined,
+    TInitData = unknown,
+  >(config: {
+    /** Query is not allowed with handler */
+    query?: never;
+    /** Custom handler function */
+    handler: OperationHandler<z.infer<TInputSchema>, InferOutput<TOutputSchema>, unknown>;
+    /** Description for documentation */
+    description?: string;
+    /** Input schema (Zod) */
+    input: TInputSchema;
+    /** Output schema (Zod) */
+    output?: TOutputSchema;
+    /** Hooks for initialization and request transformation */
+    hooks?: {
+      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
+      beforeRequest?: (
+        context: { input: z.infer<TInputSchema> },
+        initData: TInitData | undefined,
+      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+      afterRequest?: (context: {
+        output: InferOutput<TOutputSchema>;
+      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
+    };
+    /** REST exposure configuration */
+    rest?: OperationRestConfig;
+    /** GraphQL exposure configuration (enabled by default) */
+    graphql?: OperationGraphQLConfig;
+    /** Cache configuration */
+    cache?: OperationCacheConfig;
+  }): TypedOperation<z.infer<TInputSchema>, InferOutput<TOutputSchema>, TInitData, unknown>;
+
+  // Handler operation overload - without input schema
+  <TOutputSchema extends z.ZodType<any> | undefined = undefined, TInitData = unknown>(config: {
+    /** Query is not allowed with handler */
+    query?: never;
+    /** Custom handler function */
+    handler: OperationHandler<DefaultInput, InferOutput<TOutputSchema>, unknown>;
+    /** Description for documentation */
+    description?: string;
+    /** Input schema (Zod) */
+    input?: undefined;
+    /** Output schema (Zod) */
+    output?: TOutputSchema;
+    /** Hooks for initialization and request transformation */
+    hooks?: {
+      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
+      beforeRequest?: (
+        context: { input: DefaultInput },
+        initData: TInitData | undefined,
+      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+      afterRequest?: (context: {
+        output: InferOutput<TOutputSchema>;
+      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
+    };
+    /** REST exposure configuration */
+    rest?: OperationRestConfig;
+    /** GraphQL exposure configuration (enabled by default) */
+    graphql?: OperationGraphQLConfig;
+    /** Cache configuration */
+    cache?: OperationCacheConfig;
+  }): TypedOperation<DefaultInput, InferOutput<TOutputSchema>, TInitData, unknown>;
+
+  /**
+   * Creates a typed operation helper with custom repository type.
+   * Use this when you need typed access to repository in the handler.
+   *
+   * The generic is the databases map, keyed by database name; the handler's
+   * `options.repository` is that map, so access a repository as
+   * `repository[dbName]` (e.g. `repository.main`).
+   */
+  typed: <TRepository>() => <
+    TInputSchema extends z.ZodObject<any>,
+    TOutputSchema extends z.ZodType<any> | undefined = undefined,
+    TInitData = unknown,
+  >(config: {
+    /** Query is not allowed with handler */
+    query?: never;
+    /** Custom handler function */
+    handler: OperationHandler<z.infer<TInputSchema>, InferOutput<TOutputSchema>, TRepository>;
+    /** Description for documentation */
+    description?: string;
+    /** Input schema (Zod) */
+    input: TInputSchema;
+    /** Output schema (Zod) */
+    output?: TOutputSchema;
+    /** Hooks for initialization and request transformation */
+    hooks?: {
+      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
+      beforeRequest?: (
+        context: { input: z.infer<TInputSchema> },
+        initData: TInitData | undefined,
+      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+      afterRequest?: (context: {
+        output: InferOutput<TOutputSchema>;
+      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
+    };
+    /** REST exposure configuration */
+    rest?: OperationRestConfig;
+    /** GraphQL exposure configuration (enabled by default) */
+    graphql?: OperationGraphQLConfig;
+    /** Cache configuration */
+    cache?: OperationCacheConfig;
+  }) => TypedOperation<z.infer<TInputSchema>, InferOutput<TOutputSchema>, TInitData, TRepository>;
+};
+
+// ============================================================================
+// Configuration Helpers Type
+// ============================================================================
+
+/**
+ * Configuration helpers object passed to the configuration function
+ */
+export type ConfigurationHelpers = {
+  /** Zod validation library instance */
+  z: typeof z;
+  /** Helper function to define operations */
+  operation: OperationFn;
+  /** Helper to create virtual columns from MSSQL 1/0 to boolean */
+  createOneToBooleanMSSQL: CreateOneToBooleanMSSQLFn;
+  /** Helper to create virtual columns from MSSQL Y/N to boolean */
+  createYAndNToBooleanMSSQL: CreateYAndNToBooleanMSSQLFn;
+  /** Helper to create virtual columns from SQL expressions */
+  virtualColumnExpression: VirtualColumnExpressionFn;
+  /** Helper to create virtual columns from SQL functions */
+  virtualColumnFunction: VirtualColumnFunctionFn;
+};
+
+/**
+ * Configuration function type that receives helpers and returns configuration
+ *
+ * @example
+ * ```ts
+ * import type { ConfigurationFn } from "@graphoria/server/config";
+ *
+ * export default (({ z, operation, virtualColumnFunction }) => ({
+ *   name: "My API",
+ *   version: "1.0.0",
+ *   databases: [...],
+ *   operations: {
+ *     getUsers: operation({
+ *       query: `query { users { id name } }`,
+ *       rest: { path: "/users" },
+ *     }),
+ *   },
+ * })) satisfies ConfigurationFn;
+ * ```
+ */
+export type ConfigurationFn = (helpers: ConfigurationHelpers) => ConfigurationInput;
+
+// Re-export all types
+export * from "./types";
+
+// Re-export helpers
+export {
+  operation,
+  cron,
+  queue,
+  type InferOperationInput,
+  type InferOperationOutput,
+  type InferOperationInitData,
+} from "./helpers";
+
+// Re-export cron definition types
+export {
+  DefaultVariablesSchema,
+  createTypedCronJobZod,
+  TypedCronJobZod,
+  type DefaultVariables,
+  type TickContext,
+  type TypedCronJob,
+  type CronJobType,
+} from "./types/cron";
+
+// Re-export zod for convenience
+export { z } from "zod";
+
+export const createApiResponse = <T extends z.ZodTypeAny>(dataSchema: T) =>
+  z.object({
+    status: z.string(),
+    data: dataSchema.optional(),
+  });
+
+/** Runtime maps populated during boot: live connection pools and repositories. */
+export type { RepositoryMap, DatabasesConnections } from "../singletons/databases";

package/src/config/types/ai.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+
+/**
+ * Model Context Protocol (MCP) server configuration, nested under `ai.mcp`.
+ * When enabled, exposes a `/mcp` endpoint for LLM agents.
+ */
+export const MCPZod = z.object({
+  /** Whether the MCP server is enabled. Off by default. */
+  enabled: z.boolean().default(false),
+});
+
+/** Authoring type for MCP configuration */
+export type MCPConfig = z.input<typeof MCPZod>;
+
+/**
+ * AI agent configuration. Exposes an admin-only natural-language → database
+ * Q&A agent as a GraphQL `ask` query and a REST `POST` endpoint.
+ *
+ * The LLM provider, model, and API keys are read from environment variables
+ * (`LLM_PROVIDER`, `LLM_MODEL`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+ * `DEEPSEEK_API_KEY`, `OLLAMA_HOST`), not from this config.
+ */
+export const AIZod = z.object({
+  /** Whether the AI agent is enabled. Off by default. */
+  enabled: z.boolean().default(false),
+  /** Overrides the built-in system prompt sent to the LLM. */
+  systemPrompt: z.string().optional(),
+  /** REST endpoint path for the agent (default: "/ai"). */
+  endpoint: z.string().default("/ai"),
+  /** Model Context Protocol (MCP) server. Off by default. See MCP.md. */
+  mcp: MCPZod.optional().default({ enabled: false }),
+});
+
+/** Authoring type for AI configuration */
+export type AIConfig = z.input<typeof AIZod>;