@graphoria/server 0.1.4 → 0.2.0

package/src/config/types/cron.ts

@@ -42,7 +42,7 @@ export type CronTickCallback<TVariables = Record<string, unknown>> = (
  * This allows TypeScript to infer the variables type
  */
 export const createTypedCronJobZod = <TVariables extends DefaultVariables>() =>
-  z.object({
+  z.strictObject({
     /**
      * Unique name/identifier for the cron job
      */

package/src/config/types/db.ts

@@ -18,14 +18,61 @@ import { VirtualColumnZod } from "./virtual-columns";
 
 export type DatabaseType = "mssql" | "pg" | "mysql";
 
+// ============================================================================
+// Relationship Join Condition (static-value predicate)
+// ============================================================================
+
+/** Comparison operators allowed in a static relationship join condition. */
+export const RELATIONSHIP_CONDITION_OPERATORS = [
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "like",
+  "is_null",
+  "is_not_null",
+] as const;
+
+/**
+ * A static-value predicate added to a relationship's JOIN. Targets exactly one
+ * side of the relationship — `source` (a column on the declaring table) or
+ * `target` (a column on the referenced table) — and compares it to a literal.
+ * A `value` is required for every operator except `is_null` / `is_not_null`.
+ */
+export const RelationshipConditionZod = z
+  .strictObject({
+    /** Column on the declaring (source) table */
+    source: z.string().optional(),
+    /** Column on the referenced (target) table */
+    target: z.string().optional(),
+    /** Comparison operator (default `eq`) */
+    operator: z.enum(RELATIONSHIP_CONDITION_OPERATORS).optional().default("eq"),
+    /** Literal compared against the column (omit for `is_null` / `is_not_null`) */
+    value: z.union([z.string(), z.number(), z.boolean()]).optional(),
+  })
+  .refine((cond) => (cond.source === undefined) !== (cond.target === undefined), {
+    message: 'Relationship condition must set exactly one of "source" or "target"',
+  })
+  .refine(
+    (cond) =>
+      cond.operator === "is_null" || cond.operator === "is_not_null" || cond.value !== undefined,
+    { message: 'Relationship condition requires a "value" unless operator is is_null/is_not_null' },
+  );
+
+export type RelationshipCondition = z.input<typeof RelationshipConditionZod>;
+
 // ============================================================================
 // Table Relationship (config shape, no transform)
 // ============================================================================
 
-export const TableRelationshipZod = z.object({
+export const TableRelationshipZod = z.strictObject({
   schema: z.string(),
   name: z.string(),
-  columns: z.array(z.object({ source: z.string(), target: z.string() })),
+  columns: z.array(z.strictObject({ source: z.string(), target: z.string() })),
+  /** Static-value predicates ANDed into the JOIN condition */
+  conditions: z.array(RelationshipConditionZod).optional(),
 });
 
 export type TableRelationship = z.input<typeof TableRelationshipZod>;
@@ -34,7 +81,7 @@ export type TableRelationship = z.input<typeof TableRelationshipZod>;
 // Table Schema Config
 // ============================================================================
 
-export const TableSchemaConfigZod = z.object({
+export const TableSchemaConfigZod = z.strictObject({
   columns: z.array(VirtualColumnZod).optional().default([]),
   relationships: z.array(TableRelationshipZod).optional().default([]),
   /** Overrides the table description from the database */
@@ -49,7 +96,7 @@ export type TableSchemaConfig = z.input<typeof TableSchemaConfigZod>;
 // Database Schema Config
 // ============================================================================
 
-export const DatabaseSchemaConfigZod = z.object({
+export const DatabaseSchemaConfigZod = z.strictObject({
   database: z
     .record(
       z.string(),
@@ -80,7 +127,7 @@ export type DatabaseSchemaConfig = z.input<typeof DatabaseSchemaConfigZod>;
  * Connection pool and transport options for PostgreSQL and MySQL (Bun SQL).
  * All timeout values are in seconds.
  */
-export const BunSQLConnectionOptionsZod = z.object({
+export const BunSQLConnectionOptionsZod = z.strictObject({
   /** 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 */
@@ -103,10 +150,10 @@ 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({
+export const MSSQLConnectionOptionsZod = z.strictObject({
   /** Connection pool options */
   pool: z
-    .object({
+    .strictObject({
       /** Maximum number of connections in the pool */
       max: z.number().int().positive().default(10),
       /** Minimum number of connections in the pool */
@@ -181,7 +228,7 @@ export type ConnectionOptionsForType<T extends DatabaseType> = T extends "pg" |
 // Database Connection Zod Schema
 // ============================================================================
 
-export const DatabaseConnectionZod = z.object({
+export const DatabaseConnectionZod = z.strictObject({
   /** Unique name for the database connection */
   name: z.string(),
   /** Whether the database is enabled */
@@ -189,7 +236,7 @@ export const DatabaseConnectionZod = z.object({
   /** Database type */
   type: z.union([z.literal("mssql"), z.literal("pg"), z.literal("mysql")]),
   /** Connection configuration */
-  connection: z.object({
+  connection: z.strictObject({
     host: z.string(),
     port: z.number(),
     user: z.string(),

package/src/config/types/index.ts

@@ -18,6 +18,8 @@ export {
 // Operation types and Zod schemas
 export type {
   DefaultInput,
+  AnyQueryDocument,
+  QueryResultOf,
   OperationRestConfig,
   OperationGraphQLConfig,
   OperationCacheConfig,
@@ -104,6 +106,7 @@ export type {
   DatabaseType,
   DatabaseConnection,
   TableRelationship,
+  RelationshipCondition,
   TableSchemaConfig,
   DatabaseSchemaConfig,
   CustomRepositoryFactory,
@@ -117,6 +120,8 @@ export type {
 
 export {
   TableRelationshipZod,
+  RelationshipConditionZod,
+  RELATIONSHIP_CONDITION_OPERATORS,
   TableSchemaConfigZod,
   DatabaseSchemaConfigZod,
   BunSQLConnectionOptionsZod,

package/src/config/types/operation.ts

@@ -5,6 +5,25 @@ import { z } from "zod";
  */
 export type DefaultInput = Record<string, unknown>;
 
+/**
+ * A gql.tada / `TypedDocumentNode` query document. Every GraphQL AST node has a
+ * `kind`, which distinguishes a document from a plain string query; documents
+ * additionally carry their result type on the `__apiType` phantom property.
+ */
+export type AnyQueryDocument = { readonly kind: string };
+
+/**
+ * Extracts a query document's result type (the GraphQL `data` payload) from its
+ * gql.tada / TypedDocumentNode `__apiType` phantom. A plain string query (or a
+ * document without embedded types) resolves to `unknown`.
+ */
+export type QueryResultOf<TQuery> = TQuery extends string
+  ? unknown
+  : // oxlint-disable-next-line typescript/no-explicit-any
+    TQuery extends { __apiType?: (variables: any) => infer TResult }
+    ? TResult
+    : unknown;
+
 // ============================================================================
 // Zod Schemas for Runtime Validation
 // ============================================================================
@@ -12,7 +31,7 @@ export type DefaultInput = Record<string, unknown>;
 /**
  * Zod schema for REST configuration
  */
-export const OperationRestConfigZod = z.object({
+export const OperationRestConfigZod = z.strictObject({
   path: z.string(),
   method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET"),
   pathParams: z.custom<z.ZodType>().optional(),
@@ -23,7 +42,7 @@ export const OperationRestConfigZod = z.object({
 /**
  * Zod schema for GraphQL configuration
  */
-export const OperationGraphQLConfigZod = z.object({
+export const OperationGraphQLConfigZod = z.strictObject({
   enabled: z.boolean().optional().default(true),
   name: z.string().optional(),
 });
@@ -31,7 +50,7 @@ export const OperationGraphQLConfigZod = z.object({
 /**
  * Zod schema for cache configuration
  */
-export const OperationCacheConfigZod = z.object({
+export const OperationCacheConfigZod = z.strictObject({
   max: z.number().int().positive().optional(),
   maxSize: z.number().int().positive().optional(),
   ttl: z.number().int().positive().optional(),
@@ -65,7 +84,7 @@ export type OperationCacheConfig = z.input<typeof OperationCacheConfigZod>;
 // ============================================================================
 
 export const OperationZod = z
-  .object({
+  .strictObject({
     description: z.string().optional(),
     query: z.string().optional(),
     // oxlint-disable-next-line typescript/no-explicit-any
@@ -75,7 +94,7 @@ export const OperationZod = z
     // oxlint-disable-next-line typescript/no-explicit-any
     output: z.custom<z.ZodType<any>>().optional(),
     hooks: z
-      .object({
+      .strictObject({
         // oxlint-disable-next-line typescript/no-explicit-any
         init: z.custom<OperationInitHook<any>>().optional(),
         beforeRequest: z
@@ -108,14 +127,30 @@ export const OperationsZod = z.record(z.string(), OperationZod);
 export type Operations = z.input<typeof OperationsZod>;
 
 /**
- * Context passed to beforeRequest hook
+ * Context passed to beforeRequest hook.
+ *
+ * `input` is the merged view of every REST parameter source. `pathParams`,
+ * `queryParams`, and `body` expose each source separately (parsed with its own
+ * schema), or `undefined` when that source has no schema configured.
  */
-export type BeforeRequestContext<TInput = DefaultInput> = {
+export type BeforeRequestContext<
+  TInput = DefaultInput,
+  TPathParams = unknown,
+  TQueryParams = unknown,
+  TBody = unknown,
+> = {
   input: TInput;
+  pathParams?: TPathParams;
+  queryParams?: TQueryParams;
+  body?: TBody;
 };
 
 /**
- * Context passed to afterRequest hook
+ * Context passed to the afterRequest hook.
+ *
+ * `output` is the operation's output payload — for query-based operations the
+ * unwrapped GraphQL `data` (the hook's return replaces `data` in the response
+ * envelope); for handler-based operations the value the handler returned.
  */
 export type AfterRequestContext<TOutput = unknown> = {
   output: TOutput;
@@ -173,7 +208,12 @@ export type OperationBeforeRequestHook<
 ) => TVariables | Promise<TVariables>;
 
 /**
- * AfterRequest hook - transforms output after execution
+ * AfterRequest hook — transforms the output after a successful query/handler.
+ *
+ * Receives the output payload and returns the (possibly transformed) payload.
+ * Runs on success only; throw to turn a successful response into an error. For
+ * cached query operations it runs on the cache miss and the transformed result
+ * is cached, so cache hits reuse it without re-invoking the hook.
  */
 export type OperationAfterRequestHook<TOutput = unknown> = (
   context: AfterRequestContext<TOutput>,

package/src/config/types/queue.ts

@@ -10,7 +10,7 @@ import { z } from "zod";
 /**
  * Reconnection configuration
  */
-export const ReconnectConfigZod = z.object({
+export const ReconnectConfigZod = z.strictObject({
   /** Initial delay before first reconnect attempt (ms) */
   initialDelay: z.number().int().positive().default(1000),
   /** Maximum delay between reconnect attempts (ms) */
@@ -26,7 +26,7 @@ export type ReconnectConfig = z.input<typeof ReconnectConfigZod>;
 /**
  * Publisher configuration — defines how to send messages
  */
-export const PublisherConfigZod = z.object({
+export const PublisherConfigZod = z.strictObject({
   /** Topic/Exchange name to publish to */
   topic: z.string(),
   /** Routing key (RabbitMQ) or message key (Kafka) */
@@ -58,7 +58,7 @@ export type SubscriberHandler = (
 /**
  * Subscriber configuration — defines how to receive messages
  */
-export const SubscriberConfigZod = z.object({
+export const SubscriberConfigZod = z.strictObject({
   /** Topic/Exchange name to subscribe to */
   topic: z.string(),
   /** Pattern for filtering messages (routing key pattern for RabbitMQ) */
@@ -80,7 +80,7 @@ export type SubscriberConfig = z.input<typeof SubscriberConfigZod>;
 /**
  * Topic/Exchange configuration — for auto-setup
  */
-export const TopicConfigZod = z.object({
+export const TopicConfigZod = z.strictObject({
   /** Exchange type (RabbitMQ only) */
   type: z.enum(["direct", "fanout", "topic", "headers"]).optional().default("topic"),
   /** Whether exchange should survive broker restart */
@@ -94,7 +94,7 @@ export type TopicConfig = z.input<typeof TopicConfigZod>;
 /**
  * Base queue configuration shared by all providers
  */
-export const BaseQueueConfigZod = z.object({
+export const BaseQueueConfigZod = z.strictObject({
   /** Unique name for this queue connection */
   name: z.string(),
   /** Whether to auto-create topics/exchanges/queues */
@@ -118,7 +118,7 @@ export const BaseQueueConfigZod = z.object({
 /**
  * RabbitMQ connection configuration (object form)
  */
-export const RabbitMQConnectionZod = z.object({
+export const RabbitMQConnectionZod = z.strictObject({
   hostname: z.string().default("localhost"),
   port: z.number().default(5672),
   username: z.string().optional(),
@@ -131,7 +131,7 @@ export type RabbitMQConnection = z.input<typeof RabbitMQConnectionZod>;
 /**
  * Kafka connection configuration
  */
-export const KafkaConnectionZod = z.object({
+export const KafkaConnectionZod = z.strictObject({
   /** 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>") */
@@ -140,7 +140,7 @@ export const KafkaConnectionZod = z.object({
   ssl: z.boolean().optional().default(false),
   /** SASL authentication (optional) */
   sasl: z
-    .object({
+    .strictObject({
       mechanism: z.enum(["plain", "scram-sha-256", "scram-sha-512"]).optional().default("plain"),
       username: z.string(),
       password: z.string(),

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

@@ -3,7 +3,7 @@ import { z } from "zod";
 /**
  * Remote REST API configuration (OpenAPI-based)
  */
-export const RemoteRESTConfigZod = z.object({
+export const RemoteRESTConfigZod = z.strictObject({
   /** Unique identifier for this remote REST API */
   name: z.string().min(1),
   /** Base URL of the remote API for proxying requests */

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

@@ -4,7 +4,7 @@ import { z } from "zod";
  * Remote GraphQL schema introspection configuration
  */
 export const RemoteSchemaIntrospectionConfigZod = z
-  .object({
+  .strictObject({
     /** Re-introspect interval in ms (0 = only at startup, default: 0) */
     interval: z.number().int().min(0).optional().default(0),
   })
@@ -16,7 +16,7 @@ export type RemoteSchemaIntrospectionConfig = z.input<typeof RemoteSchemaIntrosp
 /**
  * Remote GraphQL schema configuration
  */
-export const RemoteSchemaConfigZod = z.object({
+export const RemoteSchemaConfigZod = z.strictObject({
   /** Unique identifier for this remote schema */
   name: z.string().min(1),
   /** Remote GraphQL endpoint URL */

package/src/config/types/virtual-columns.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 /**
  * Virtual column schema for computed/virtual columns in database schema
  */
-export const VirtualColumnZod = z.object({
+export const VirtualColumnZod = z.strictObject({
   name: z.string(),
   dataType: z.string(),
   isNullable: z.boolean(),

package/src/configuration/getSchemas/mergeEntities/index.ts

@@ -87,6 +87,12 @@ export const mergeEntities = (
         acc[publisher.resolverName] = publisher;
       });
     });
+    // Subscribers become subscriptions (not mutations): register in the resolver
+    // registry only — not queuesMap — so getResolverSource routes them to the queue strategy.
+    queue.queues.forEach((subscriber) => {
+      resolverRegistry[`${queue.name}_${subscriber.name}`] =
+        createResolverEntry.queueSubscriber(subscriber);
+    });
     return acc;
   }, {});
 

package/src/configuration/getSchemas/type-definition-generator/index.ts

@@ -143,7 +143,14 @@ export const generateOrderByInputType = (mergedEntities: MergedEntities) =>
     ),
   );
 
-const aggTypes: string[] = ["Min", "Max", "Sum", "Avg"];
+// An average is fractional whatever the column holds, so it cannot inherit the
+// column's type the way min/max/sum do.
+const aggTypes: { name: string; graphQLType?: string }[] = [
+  { name: "Min" },
+  { name: "Max" },
+  { name: "Sum" },
+  { name: "Avg", graphQLType: "Float" },
+];
 
 // Generate aggregation types for each table
 export const generateAggregationTypes = (mergedEntities: MergedEntities) => {
@@ -155,10 +162,10 @@ export const generateAggregationTypes = (mergedEntities: MergedEntities) => {
         numericColumns.length
           ? aggTypes
               .map(
-                (agg) =>
+                ({ name: agg, graphQLType }) =>
                   `
                   type ${resolverName}${agg} {
-                    ${lj(numericColumns, ({ name }) => `${name}: ${mapSQLTypeToGraphQLType(columns.find((c) => c.name === name)?.dataType || "")}`)}
+                    ${lj(numericColumns, ({ name }) => `${name}: ${graphQLType ?? mapSQLTypeToGraphQLType(columns.find((c) => c.name === name)?.dataType || "")}`)}
                   }
                 `,
               )
@@ -171,7 +178,9 @@ export const generateAggregationTypes = (mergedEntities: MergedEntities) => {
         count: Int
         ${
           numericColumns.length
-            ? aggTypes.map((agg) => `${agg.toLowerCase()}: ${resolverName}${agg}`).join("\n")
+            ? aggTypes
+                .map(({ name: agg }) => `${agg.toLowerCase()}: ${resolverName}${agg}`)
+                .join("\n")
             : ""
         }
         items: [${resolverName}]

package/src/configuration/rest/generateOpenAPI.ts

@@ -189,23 +189,19 @@ export const generateOpenAPI = ({
               parameters: [
                 ...(Object.entries(
                   pathParametersPOJO.properties ?? ({} as OpenAPIV3_1.SchemaObject),
-                ).map(([key, { type }]) => ({
+                ).map(([key, paramSchema]) => ({
                   name: key,
                   in: "path",
                   required: true,
-                  schema: {
-                    type,
-                  },
+                  schema: paramSchema,
                 })) ?? []),
                 ...Object.entries(
                   queryParametersPOJO.properties ?? ({} as OpenAPIV3_1.SchemaObject),
-                ).map(([key, { type, required }]) => ({
+                ).map(([key, paramSchema]) => ({
                   name: key,
                   in: "query",
-                  required,
-                  schema: {
-                    type,
-                  },
+                  required: queryParametersPOJO.required?.includes(key) ?? false,
+                  schema: paramSchema,
                 })),
               ],
               ...(hasBody && ["POST", "PUT", "PATCH"].includes(value.rest!.method!)

package/src/configuration/rest/handleRESTRequestFactory.ts

@@ -114,24 +114,28 @@ export const handleRESTRequestFactory = (
         });
       }
 
-      // Validate and parse path parameters with Zod
-      const pathVariables = route.rest!.pathParams?.parse(pathParameters) as Record<
-        string,
-        unknown
-      >;
+      // Validate and parse each REST parameter source with Zod. A source is
+      // left `undefined` when its schema is not configured; that `undefined` is
+      // forwarded to `beforeRequest` so the hook can tell the sources apart,
+      // while `allVariables` stays identical because spreading `undefined` is a
+      // no-op.
+      const pathVariables = route.rest!.pathParams?.parse(pathParameters) as
+        | Record<string, unknown>
+        | undefined;
 
       const paramsQuery = new URLSearchParams(url.search);
       const paramsQueryDictionary = Object.fromEntries(paramsQuery.entries());
 
-      const queryVariables = (route.rest!.queryParams?.parse(paramsQueryDictionary) ??
-        {}) as Record<string, unknown>;
+      const queryVariables = route.rest!.queryParams?.parse(paramsQueryDictionary) as
+        | Record<string, unknown>
+        | undefined;
 
-      let bodyVariables: Record<string, unknown> = {};
+      let bodyVariables: Record<string, unknown> | undefined;
 
       if (req.method === "POST") {
         const body = req.body ? await req.json() : {};
 
-        bodyVariables = (route.rest!.body?.parse(body) ?? {}) as Record<string, unknown>;
+        bodyVariables = route.rest!.body?.parse(body) as Record<string, unknown> | undefined;
       }
 
       // Prepare all variables for the request
@@ -150,6 +154,9 @@ export const handleRESTRequestFactory = (
         (await route.hooks?.beforeRequest?.(
           {
             input: allVariables,
+            pathParams: pathVariables,
+            queryParams: queryVariables,
+            body: bodyVariables,
           },
           routesInitDataPromises[route.routeKey],
         )) ?? allVariables;
@@ -286,6 +293,19 @@ export const handleRESTRequestFactory = (
         }
       }
 
+      // Apply the operation's afterRequest hook (if configured) to a GraphQL
+      // result. The hook receives the unwrapped `data` payload; its return
+      // replaces `data`, leaving the rest of the envelope (e.g. `sqlQueries`)
+      // intact.
+      const applyAfterRequest = async (result: Awaited<ReturnType<typeof gql.handler>>) => {
+        if (!route.hooks?.afterRequest) return result;
+
+        return {
+          ...result,
+          data: await route.hooks.afterRequest({ output: result.data }),
+        };
+      };
+
       // Check if this route has caching enabled
       const cache = route.routeKey ? getCache(route.routeKey) : undefined;
 
@@ -299,7 +319,8 @@ export const handleRESTRequestFactory = (
           role: session?.role,
         });
 
-        // Try to get from cache first
+        // Try to get from cache first. A cached entry has already been through
+        // afterRequest, so serve it directly without re-running the hook.
         const cachedResult = await cache.get(cacheKey);
         if (cachedResult) {
           log.debug({ route: route.routeKey }, "rest cache hit");
@@ -308,10 +329,13 @@ export const handleRESTRequestFactory = (
         log.debug({ route: route.routeKey }, "rest cache miss");
 
         try {
-          // Execute the GraphQL request
-          const result = await gql.handler(queryAnalysis!, variables, req, session);
+          // Execute the GraphQL request, then transform via afterRequest before
+          // caching so hits and misses return the same shape.
+          const result = await applyAfterRequest(
+            await gql.handler(queryAnalysis!, variables, req, session),
+          );
 
-          // Cache the result
+          // Cache the (already transformed) result
           await cache.set(cacheKey, result);
 
           return new S200(result);
@@ -321,7 +345,9 @@ export const handleRESTRequestFactory = (
         }
       } else if (queryAnalysis) {
         // No caching for this route, execute normally
-        return new S200(await gql.handler(queryAnalysis, variables, req, session));
+        return new S200(
+          await applyAfterRequest(await gql.handler(queryAnalysis, variables, req, session)),
+        );
       }
 
       // Fallback - should not reach here if endpoint is properly configured