@graphoria/server 0.1.0

package/src/config/types/auth.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+
+// ============================================================================
+// Base Zod Schemas for Auth Configuration
+// ============================================================================
+// These are the pre-transform base schemas — the single source of truth for
+// auth config authoring types. The permissions-dictionary normalization
+// transform stays in types/zod/auth.ts.
+
+// ============================================================================
+// Shared Primitives
+// ============================================================================
+
+/**
+ * Direction for ORDER BY clause
+ */
+export const DirectionUnionZod = z.enum([
+  "ASC",
+  "DESC",
+  "ASC_NULLS_FIRST",
+  "ASC_NULLS_LAST",
+  "DESC_NULLS_FIRST",
+  "DESC_NULLS_LAST",
+]);
+
+export type DirectionUnion = z.input<typeof DirectionUnionZod>;
+
+/**
+ * Order by clause for role-based default ordering
+ */
+export const OrderByClauseZod = z.object({
+  column: z.string(),
+  direction: DirectionUnionZod,
+});
+
+export type OrderByClause = z.input<typeof OrderByClauseZod>;
+
+/**
+ * Filter condition — matches GraphQL where argument structure.
+ * Supports operators: eq, neq, gt, gte, lt, lte, like, in, is_null, not_null.
+ */
+export const FilterConditionZod = z.record(z.string(), z.record(z.string(), z.unknown()));
+
+export type FilterCondition = z.input<typeof FilterConditionZod>;
+
+// ============================================================================
+// Permission Schemas
+// ============================================================================
+
+/**
+ * Table-level permission configuration
+ */
+export const TablePermissionZod = z.object({
+  /** Allowed columns — "ALL" or array of column names */
+  columns: z.union([z.literal("ALL"), z.array(z.string())]),
+  /** Role-based query filtering (WHERE clause) */
+  filter: FilterConditionZod.optional(),
+  /** Role-based default ordering (ORDER BY clause) */
+  orderBy: z.array(OrderByClauseZod).optional(),
+});
+
+export type TablePermission = z.input<typeof TablePermissionZod>;
+
+/**
+ * Permission configuration for a role
+ */
+export const RolePermissionZod = z
+  .object({
+    /** Tables accessible by this role */
+    tables: z
+      .union([
+        z.array(z.string()),
+        z.literal("ALL"),
+        z.record(z.string(), z.union([z.literal("ALL"), TablePermissionZod])),
+      ])
+      .optional()
+      .default([]),
+    /** Stored procedures accessible by this role */
+    storedProcedures: z
+      .union([z.array(z.string()), z.literal("ALL")])
+      .optional()
+      .default([]),
+    /** Queues accessible by this role */
+    queues: z
+      .union([z.array(z.string()), z.literal("ALL")])
+      .optional()
+      .default([]),
+    /** Operations accessible by this role */
+    operations: z
+      .union([z.array(z.string()), z.literal("ALL")])
+      .optional()
+      .default([]),
+    /** Remote schemas accessible by this role */
+    remoteSchemas: z
+      .union([z.array(z.string()), z.literal("ALL")])
+      .optional()
+      .default([]),
+    /** Remote REST APIs accessible by this role */
+    remoteREST: z
+      .union([z.array(z.string()), z.literal("ALL")])
+      .optional()
+      .default([]),
+  })
+  .default({
+    tables: [],
+    storedProcedures: [],
+    queues: [],
+    operations: [],
+    remoteSchemas: [],
+    remoteREST: [],
+  });
+
+export type RolePermission = z.input<typeof RolePermissionZod>;
+
+// ============================================================================
+// Auth Config Schema
+// ============================================================================
+
+/**
+ * Authentication configuration
+ */
+export const AuthConfigZod = z
+  .object({
+    /** Whether authentication is enabled */
+    enabled: z.boolean(),
+    /** Database name where auth tables are stored */
+    database: z.string(),
+    /** Schema name for auth tables (default: "auth") */
+    schema: z.string().optional().default("auth"),
+    /**
+     * Whether Graphoria should run CREATE SCHEMA / TABLE IF NOT EXISTS for the
+     * auth user table on every boot. Default: false.
+     */
+    autoCreateTables: z.boolean().optional().default(false),
+    /** Permissions per role */
+    permissions: z.record(z.string(), RolePermissionZod).optional().default({}),
+  })
+  .optional()
+  .default({
+    enabled: false,
+    database: "",
+    schema: "auth",
+    autoCreateTables: false,
+    permissions: {},
+  });
+
+export type AuthConfig = z.input<typeof AuthConfigZod>;

package/src/config/types/configuration.ts

@@ -0,0 +1,69 @@
+import type { SQL } from "bun";
+import type { ConnectionPool } from "mssql";
+import { z } from "zod";
+import type { AIConfig } from "./ai";
+import type { AuthConfig } from "./auth";
+import type { CronJobConfig } from "./cron";
+import type { AnyDatabaseConfig } from "./db";
+import type { TypedOperation } from "./operation";
+import type { QueueConfig } from "./queue";
+import type { RemoteRESTConfig } from "./remote-rest";
+import type { RemoteSchemaConfig } from "./remote-schema";
+
+/**
+ * Union of supported database connection types
+ */
+export type DatabaseConnectionInstance = SQL | ConnectionPool;
+
+// ============================================================================
+// Token Strategy
+// ============================================================================
+
+/**
+ * Token strategy for authentication
+ * - "jwt": JSON Web Tokens (default)
+ * - "paseto_local": PASETO v4.local (symmetric encryption)
+ * - "paseto_public": PASETO v4.public (public-key signatures)
+ */
+export const TokenStrategyZod = z.enum(["jwt", "paseto_local", "paseto_public"]);
+
+export type TokenStrategy = z.input<typeof TokenStrategyZod>;
+
+// ============================================================================
+// Configuration Input Type
+// ============================================================================
+
+/**
+ * Full configuration input type for Graphoria
+ */
+export type ConfigurationInput = {
+  /** Project name */
+  name: string;
+  /** Project version */
+  version: string;
+  /**
+   * Token strategy: "jwt" (default), "paseto_local", or "paseto_public"
+   *
+   * When using PASETO, set the corresponding environment variables:
+   * - paseto_local: PASETO_LOCAL_KEY (k4.local.xxx format)
+   * - paseto_public: PASETO_SECRET_KEY (k4.secret.xxx) + PASETO_PUBLIC_KEY (k4.public.xxx)
+   */
+  tokenStrategy?: TokenStrategy;
+  /** Database connections */
+  databases?: AnyDatabaseConfig[];
+  /** Message queues (RabbitMQ, Kafka) */
+  queues?: QueueConfig[];
+  /** Cron jobs */
+  cron?: CronJobConfig[];
+  /** Operations - unified handlers for REST + GraphQL */
+  // oxlint-disable-next-line typescript/no-explicit-any
+  operations?: Record<string, TypedOperation<any, any, any, any>>;
+  /** Authentication configuration */
+  auth?: AuthConfig;
+  /** Remote GraphQL schemas to merge into the API */
+  remoteSchemas?: RemoteSchemaConfig[];
+  /** Remote REST APIs (OpenAPI) to proxy under /rest */
+  remoteREST?: RemoteRESTConfig[];
+  /** AI agent (admin-only NL → database Q&A) + MCP server. Off by default. */
+  ai?: AIConfig;
+};

package/src/config/types/cron.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+
+/**
+ * Default variables type
+ */
+export const DefaultVariablesSchema = z.record(z.string(), z.unknown());
+
+export type DefaultVariables = z.infer<typeof DefaultVariablesSchema>;
+
+/**
+ * Context passed to the tick callback
+ */
+export type TickContext<TVariables = DefaultVariables> = {
+  name: string;
+  pattern: string;
+  variables: TVariables;
+  executionCount: number;
+  nextRun: Date | null;
+  previousRun: Date | null;
+};
+
+/**
+ * Cron job tick callback
+ */
+export type CronTickCallback<TVariables = Record<string, unknown>> = (
+  options: {
+    gqlQuery: <TReturn = unknown>(
+      query: string,
+      params?: Record<string, unknown>,
+      req?: unknown,
+    ) => Promise<{ data: TReturn; errors?: unknown[] }>;
+    databases: unknown;
+    queues: unknown;
+    repository: Record<string, unknown>;
+  },
+  context: TickContext<TVariables>,
+  response?: { data: unknown; errors?: unknown[] },
+) => Promise<void> | void;
+
+/**
+ * Generic Zod schema factory for typed cron jobs
+ * This allows TypeScript to infer the variables type
+ */
+export const createTypedCronJobZod = <TVariables extends DefaultVariables>() =>
+  z.object({
+    /**
+     * Unique name/identifier for the cron job
+     */
+    name: z.string().min(1, "Cron job name is required"),
+
+    /**
+     * Cron pattern or ISO 8601 date string
+     * Examples:
+     * - "0 0 * * *" (daily at midnight)
+     * - "*\/5 * * * *" (every 5 minutes)
+     * - "2024-01-23T00:00:00" (specific date/time)
+     */
+    pattern: z.string().min(1, "Cron pattern is required"),
+
+    /**
+     * Optional GraphQL query to execute when the cron job runs
+     * If not provided, you must use the gqlQuery function in onTick callback
+     */
+    query: z.string().optional(),
+
+    /**
+     * Optional variables to pass to the GraphQL query
+     */
+    variables: z.custom<TVariables>().optional(),
+
+    /**
+     * Optional timezone (e.g., "America/New_York", "Europe/Stockholm")
+     */
+    timezone: z.string().optional(),
+
+    /**
+     * Whether the job should be paused from start
+     */
+    paused: z.boolean().optional().default(false),
+
+    /**
+     * Maximum number of times the job should run
+     */
+    maxRuns: z.number().int().positive().optional(),
+
+    /**
+     * Minimum number of seconds between triggers
+     */
+    interval: z.number().int().nonnegative().optional(),
+
+    /**
+     * ISO 8601 formatted datetime to start the job
+     */
+    startAt: z.string().optional(),
+
+    /**
+     * ISO 8601 formatted datetime to stop the job
+     */
+    stopAt: z.string().optional(),
+
+    /**
+     * Enable over-run protection (blocks new triggers while old one is in progress)
+     */
+    protect: z.boolean().optional(),
+
+    /**
+     * Whether to catch errors silently or handle them
+     */
+    catchErrors: z.boolean().optional().default(true),
+
+    /**
+     * Context to pass along with the cron job (for logging, etc.)
+     */
+    context: z.record(z.string(), z.any()).optional(),
+
+    /**
+     * Callback executed on each tick
+     */
+    onTick: z.custom<CronTickCallback<TVariables>>().optional(),
+  });
+
+export const TypedCronJobZod = createTypedCronJobZod();
+
+export type CronJobType = z.input<typeof TypedCronJobZod>;
+
+/**
+ * Typed cron job definition
+ */
+export type TypedCronJob<TVariables = DefaultVariables> = Omit<
+  CronJobType,
+  "variables" | "onTick"
+> & {
+  variables?: TVariables;
+  onTick?: CronTickCallback<TVariables>;
+};
+
+/**
+ * Cron job configuration (alias of TypedCronJob, kept for the public config surface)
+ */
+export type CronJobConfig<TVariables = DefaultVariables> = TypedCronJob<TVariables>;

package/src/config/types/db.ts

@@ -0,0 +1,256 @@
+import { z } from "zod";
+
+import type { SQL } from "bun";
+import type { ConnectionPool } from "mssql";
+
+import { VirtualColumnZod } from "./virtual-columns";
+
+// ============================================================================
+// Base Zod Schemas for Database Configuration
+// ============================================================================
+// These are the base schemas — the single source of truth for database config
+// authoring types. Introspection-only schemas (TableZod, DatabaseStructureZod,
+// etc.) stay in types/zod/db.ts.
+
+// ============================================================================
+// Database Type
+// ============================================================================
+
+export type DatabaseType = "mssql" | "pg" | "mysql";
+
+// ============================================================================
+// Table Relationship (config shape, no transform)
+// ============================================================================
+
+export const TableRelationshipZod = z.object({
+  schema: z.string(),
+  name: z.string(),
+  columns: z.array(z.object({ source: z.string(), target: z.string() })),
+});
+
+export type TableRelationship = z.input<typeof TableRelationshipZod>;
+
+// ============================================================================
+// Table Schema Config
+// ============================================================================
+
+export const TableSchemaConfigZod = z.object({
+  columns: z.array(VirtualColumnZod).optional().default([]),
+  relationships: z.array(TableRelationshipZod).optional().default([]),
+  /** Overrides the table description from the database */
+  description: z.string().optional(),
+  /** Overrides column descriptions from the database, keyed by column name */
+  columnDescriptions: z.record(z.string(), z.string()).optional().default({}),
+});
+
+export type TableSchemaConfig = z.input<typeof TableSchemaConfigZod>;
+
+// ============================================================================
+// Database Schema Config
+// ============================================================================
+
+export const DatabaseSchemaConfigZod = z.object({
+  database: z
+    .record(
+      z.string(),
+      TableSchemaConfigZod.optional()
+        .default({
+          columns: [],
+          relationships: [],
+          columnDescriptions: {},
+        })
+        .catch({
+          columns: [],
+          relationships: [],
+          columnDescriptions: {},
+        }),
+    )
+    .optional()
+    .default({}),
+  excludedTables: z.array(z.string()).optional().default([]),
+});
+
+export type DatabaseSchemaConfig = z.input<typeof DatabaseSchemaConfigZod>;
+
+// ============================================================================
+// Connection Options
+// ============================================================================
+
+/**
+ * Connection pool and transport options for PostgreSQL and MySQL (Bun SQL).
+ * All timeout values are in seconds.
+ */
+export const BunSQLConnectionOptionsZod = z.object({
+  /** Maximum number of connections in the pool */
+  max: z.number().int().positive().default(10),
+  /** Maximum time in seconds a connection can be idle before being closed */
+  idleTimeout: z.number().nonnegative().default(30),
+  /** Maximum time in seconds to wait when establishing a connection */
+  connectionTimeout: z.number().nonnegative().default(30),
+  /** Maximum lifetime in seconds of a connection */
+  maxLifetime: z.number().nonnegative().default(3600),
+  /** Whether to use TLS/SSL for the connection */
+  tls: z.boolean().default(false),
+  /** Automatic creation of prepared statements (default: true) */
+  prepare: z.boolean().default(true),
+  /** Return values outside i32 range as BigInts instead of strings (default: false) */
+  bigint: z.boolean().default(false),
+});
+
+export type BunSQLConnectionOptions = z.input<typeof BunSQLConnectionOptionsZod>;
+
+/**
+ * Connection pool and transport options for MSSQL.
+ * All timeout values are in seconds (converted to milliseconds internally).
+ */
+export const MSSQLConnectionOptionsZod = z.object({
+  /** Connection pool options */
+  pool: z
+    .object({
+      /** Maximum number of connections in the pool */
+      max: z.number().int().positive().default(10),
+      /** Minimum number of connections in the pool */
+      min: z.number().int().nonnegative().default(0),
+      /** Maximum time in seconds a connection can be idle before being closed */
+      idleTimeout: z.number().nonnegative().default(30),
+    })
+    .default({
+      max: 10,
+      min: 0,
+      idleTimeout: 30,
+    }),
+  /** Maximum time in seconds to wait when establishing a connection */
+  connectionTimeout: z.number().nonnegative().default(30),
+  /** Maximum time in seconds to wait for a request to complete */
+  requestTimeout: z.number().nonnegative().default(30),
+  /** Whether to encrypt the connection */
+  encrypt: z.boolean().default(false),
+  /** Whether to trust the server certificate without validation */
+  trustServerCertificate: z.boolean().default(false),
+  /** Whether to use Windows Authentication (trusted connection) */
+  trustedConnection: z.boolean().default(false),
+  /** Whether to automatically parse JSON responses */
+  parseJSON: z.boolean().default(true),
+});
+
+export type MSSQLConnectionOptions = z.input<typeof MSSQLConnectionOptionsZod>;
+
+// ============================================================================
+// Generic Types (hand-written — generics can't be inferred from Zod)
+// The `type: "pg"` narrowing of `onConnect` / `repository` is load-bearing.
+// ============================================================================
+
+/**
+ * Maps database type to the corresponding native connection type.
+ * SQL for Bun/PostgreSQL/MySQL, ConnectionPool for MSSQL.
+ */
+export type DatabaseConnectionForType<T extends DatabaseType> = T extends "pg" | "mysql"
+  ? SQL
+  : T extends "mssql"
+    ? ConnectionPool
+    : never;
+
+/**
+ * Custom repository factory function type.
+ * Accepts the native connection typed per engine.
+ */
+export type CustomRepositoryFactory<T extends DatabaseType = DatabaseType> = (
+  connection: DatabaseConnectionForType<T>,
+) => unknown;
+
+/**
+ * Handler invoked once at startup after the database connection is established.
+ * Receives the live connection (typed per engine) and the database config.
+ * Throwing aborts server boot.
+ */
+export type OnConnectHandler<T extends DatabaseType = DatabaseType> = (
+  connection: DatabaseConnectionForType<T>,
+  db: DatabaseConfig<T>,
+) => void | Promise<void>;
+
+/**
+ * Maps database type to the corresponding connection options type.
+ */
+export type ConnectionOptionsForType<T extends DatabaseType> = T extends "pg" | "mysql"
+  ? BunSQLConnectionOptions
+  : T extends "mssql"
+    ? MSSQLConnectionOptions
+    : never;
+
+// ============================================================================
+// Database Connection Zod Schema
+// ============================================================================
+
+export const DatabaseConnectionZod = z.object({
+  /** Unique name for the database connection */
+  name: z.string(),
+  /** Whether the database is enabled */
+  enabled: z.boolean(),
+  /** Database type */
+  type: z.union([z.literal("mssql"), z.literal("pg"), z.literal("mysql")]),
+  /** Connection configuration */
+  connection: z.object({
+    host: z.string(),
+    port: z.number(),
+    user: z.string(),
+    password: z.string(),
+    database: z.string(),
+  }),
+  /** Field naming pattern (default: "{schema}_{name}") */
+  fieldNaming: z.string().optional().default("{schema}_{name}"),
+  /** Factory function to create custom database repository */
+  repository: z.custom<CustomRepositoryFactory>().optional(),
+  /** Handler run once at startup against the connected database */
+  onConnect: z.custom<OnConnectHandler>().optional(),
+  /** Schema configuration (virtual columns, relationships, excluded tables) */
+  schema: DatabaseSchemaConfigZod.optional(),
+  /** Optional connection pool and transport options */
+  connectionOptions: z.union([BunSQLConnectionOptionsZod, MSSQLConnectionOptionsZod]).optional(),
+});
+
+// ============================================================================
+// Database Config (hand-written generic wrapper over z.input field inventory)
+// The generic `T` narrowing of `onConnect` / `repository` / `connectionOptions`
+// is load-bearing — Zod can't express this narrowing.
+// ============================================================================
+
+/**
+ * Database connection shape (derived from the Zod schema).
+ */
+export type DatabaseConnection = z.input<typeof DatabaseConnectionZod>["connection"];
+
+/**
+ * Database configuration with engine-type narrowing.
+ */
+export type DatabaseConfig<T extends DatabaseType = DatabaseType> = {
+  /** Unique name for the database connection */
+  name: string;
+  /** Whether the database is enabled */
+  enabled: boolean;
+  /** Database type */
+  type: T;
+  /** Connection configuration */
+  connection: DatabaseConnection;
+  /** Field naming pattern (default: "{schema}_{name}") */
+  fieldNaming?: string;
+  /** Factory function to create custom database repository */
+  repository?: CustomRepositoryFactory<T>;
+  /** Handler run once at startup against the connected database */
+  onConnect?: OnConnectHandler<T>;
+  /** Schema configuration (virtual columns, relationships, excluded tables) */
+  schema?: DatabaseSchemaConfig;
+  /** Optional connection pool and transport options */
+  connectionOptions?: ConnectionOptionsForType<T>;
+};
+
+// ============================================================================
+// Discriminated Union
+// ============================================================================
+
+/**
+ * Discriminated union of all database configs — allows proper type narrowing
+ * for repository function parameter based on the database type field.
+ */
+export type AnyDatabaseConfig = {
+  [K in DatabaseType]: DatabaseConfig<K>;
+}[DatabaseType];