@graphoria/server 0.1.5 → 0.2.1

package/src/config/types/auth.ts

@@ -28,18 +28,49 @@ export type DirectionUnion = z.input<typeof DirectionUnionZod>;
 /**
  * Order by clause for role-based default ordering
  */
-export const OrderByClauseZod = z.object({
+export const OrderByClauseZod = z.strictObject({
   column: z.string(),
   direction: DirectionUnionZod,
 });
 
 export type OrderByClause = z.input<typeof OrderByClauseZod>;
 
+/**
+ * Every operator the query builder implements. `databases/common.ts` imports this
+ * list rather than keeping its own: an operator that exists in one place and not
+ * the other is how a role filter ends up matching every row.
+ */
+export const FILTER_OPERATORS = [
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "like",
+  "in",
+  "between",
+  "is_null",
+  "is_not_null",
+  "not_null",
+] as const;
+
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+
 /**
  * Filter condition — matches GraphQL where argument structure.
- * Supports operators: eq, neq, gt, gte, lt, lte, like, in, is_null, not_null.
+ *
+ * A value is either a column filter (`{ eq: … }`) or a nested relation filter
+ * holding more of the same. Operators are constrained to the implemented set so
+ * a typo fails at boot instead of evaluating to no condition, which would hand
+ * the role the whole table.
  */
-export const FilterConditionZod = z.record(z.string(), z.record(z.string(), z.unknown()));
+export const FilterConditionZod: z.ZodType<Record<string, unknown>> = z.lazy(() =>
+  z.record(
+    z.string(),
+    z.union([z.record(z.enum(FILTER_OPERATORS), z.unknown()), FilterConditionZod]),
+  ),
+);
 
 export type FilterCondition = z.input<typeof FilterConditionZod>;
 
@@ -50,7 +81,7 @@ export type FilterCondition = z.input<typeof FilterConditionZod>;
 /**
  * Table-level permission configuration
  */
-export const TablePermissionZod = z.object({
+export const TablePermissionZod = z.strictObject({
   /** Allowed columns — "ALL" or array of column names */
   columns: z.union([z.literal("ALL"), z.array(z.string())]),
   /** Role-based query filtering (WHERE clause) */
@@ -65,7 +96,7 @@ export type TablePermission = z.input<typeof TablePermissionZod>;
  * Permission configuration for a role
  */
 export const RolePermissionZod = z
-  .object({
+  .strictObject({
     /** Tables accessible by this role */
     tables: z
       .union([
@@ -120,7 +151,7 @@ export type RolePermission = z.input<typeof RolePermissionZod>;
  * Authentication configuration
  */
 export const AuthConfigZod = z
-  .object({
+  .strictObject({
     /** Whether authentication is enabled */
     enabled: z.boolean(),
     /** Database name where auth tables are stored */

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

@@ -42,7 +42,7 @@ export const RELATIONSHIP_CONDITION_OPERATORS = [
  * A `value` is required for every operator except `is_null` / `is_not_null`.
  */
 export const RelationshipConditionZod = z
-  .object({
+  .strictObject({
     /** Column on the declaring (source) table */
     source: z.string().optional(),
     /** Column on the referenced (target) table */
@@ -67,10 +67,10 @@ 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(),
 });
@@ -81,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 */
@@ -96,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(),
@@ -127,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 */
@@ -150,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 */
@@ -228,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 */
@@ -236,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,

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

@@ -6,6 +6,7 @@ import type { ResolverRegistry } from "../../../types/resolver";
 import type { TypedOperation } from "../../../types/zod/operation";
 
 import { EntitySource, createResolverEntry } from "../../../types/resolver";
+import { columnFieldName } from "../../../databases/transformers/graphqlName";
 import { SqlTypeCategory, categorizeSqlType } from "../../../databases/sqlTypeUtils";
 
 const dataTypeToOpenApiType = (dataType: string): string => {
@@ -33,7 +34,23 @@ export const mergeEntities = (
   const resolverRegistry: ResolverRegistry = {};
 
   // Register tables (queries)
+  // Sanitisation is not injective — `categoría` and `categor_a` both produce
+  // `categoria` — so two tables can land on one resolver name. Serving one
+  // table's rows under the other's name is worse than not booting.
+  const sourceOfResolverName: Record<string, string> = {};
+
   const queriesMap = entityOfRole.tables.reduce<Record<string, TableResolver>>((acc, table) => {
+    const source = `${table.schema}.${table.name}`;
+    const previousSource = sourceOfResolverName[table.resolverName];
+
+    if (previousSource) {
+      throw new Error(
+        `Duplicate GraphQL name "${table.resolverName}": both ${previousSource} and ${source} map to it. Rename one of them, or exclude it with schema.excludedTables.`,
+      );
+    }
+
+    sourceOfResolverName[table.resolverName] = source;
+
     acc[table.resolverName] = table;
     acc[`${table.resolverName}_single`] = table;
     acc[`${table.resolverName}_aggregate`] = table;
@@ -87,6 +104,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;
   }, {});
 
@@ -201,10 +224,18 @@ export const mergeEntities = (
     },
     isVirtualColumn: (table: string, column: string): VirtualColumn | undefined => {
       const col = queriesMap[table]?.columns.find(
-        (c) => c.name === column && "virtual" in c && c.virtual,
+        (c) => columnFieldName(c) === column && "virtual" in c && c.virtual,
       );
       return col ? (col as VirtualColumn) : undefined;
     },
+    /**
+     * The SQL identifier behind a GraphQL field name. Columns whose name GraphQL
+     * cannot spell are exposed under a sanitised field name, so anything that
+     * emits SQL for a field the client named has to come back through here.
+     * Unknown names pass through: a legal name always sanitises to itself.
+     */
+    columnSqlName: (table: string, fieldName: string): string =>
+      queriesMap[table]?.columns.find((c) => columnFieldName(c) === fieldName)?.name ?? fieldName,
     getColumnTypeForOpenApi: (table: string, column: string) => {
       const tableObj = queriesMap[table];
 

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

@@ -1,6 +1,7 @@
 import type { OpenAPIV3_1 } from "openapi-types";
 
 import { SqlTypeCategory, categorizeSqlType, isNumericType } from "../../../databases/sqlTypeUtils";
+import { columnFieldName } from "../../../databases/transformers/graphqlName";
 import { convertFromZod } from "../../rest/openApiErrors";
 import { type MergedEntities } from "../mergeEntities";
 
@@ -91,8 +92,8 @@ export const generateTableType = (mergedEntities: MergedEntities) =>
         ${lj([
           lj(
             columns,
-            ({ name, dataType, isNullable, description }) =>
-              `${sdlDesc(description)}${name}: ${mapSQLTypeToGraphQLType(dataType)}${isNullable ? "" : "!"}`,
+            (column) =>
+              `${sdlDesc(column.description)}${columnFieldName(column)}: ${mapSQLTypeToGraphQLType(column.dataType)}${column.isNullable ? "" : "!"}`,
           ),
           lj(
             relationships,
@@ -115,7 +116,11 @@ export const generateWhereInputType = (mergedEntities: MergedEntities) =>
       ({ resolverName, columns, relationships, relationshipsReversed }) => `
         input ${resolverName}WhereInput {
           ${lj([
-            lj(columns, ({ name, dataType }) => `${name}: ${mapSQLTypeToConditionType(dataType)}`),
+            lj(
+              columns,
+              (column) =>
+                `${columnFieldName(column)}: ${mapSQLTypeToConditionType(column.dataType)}`,
+            ),
             lj(
               relationships,
               ({ toResolverName, toInternalName }) =>
@@ -138,12 +143,19 @@ export const generateOrderByInputType = (mergedEntities: MergedEntities) =>
     mergedEntities.tables.map(
       ({ internalName, columns }) => `
       input ${internalName}OrderByInput {
-        ${lj(columns, ({ name }) => `${name}: OrderByEnum`)}
+        ${lj(columns, (column) => `${columnFieldName(column)}: OrderByEnum`)}
       }`,
     ),
   );
 
-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 +167,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, (column) => `${columnFieldName(column)}: ${graphQLType ?? mapSQLTypeToGraphQLType(column.dataType)}`)}
                   }
                 `,
               )
@@ -171,14 +183,16 @@ 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}]
       }
       
       enum ${resolverName}GroupByKeys {
-        ${columns.map((c) => c.name).join("\n")}
+        ${columns.map(columnFieldName).join("\n")}
       }
       `;
   });

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!)