@constructive-io/graphql-server 3.1.1 → 4.0.1

package/options.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * GraphQL Server Options - Configuration utilities
+ *
+ * This module provides type-safe configuration utilities for the GraphQL server.
+ * It includes type guards for runtime validation and utility functions for
+ * configuration normalization.
+ *
+ * The main configuration type is `ConstructiveOptions` from @constructive-io/graphql-types.
+ *
+ * @module options
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverDefaults = void 0;
+exports.isConstructiveOptions = isConstructiveOptions;
+exports.hasPgConfig = hasPgConfig;
+exports.hasServerConfig = hasServerConfig;
+exports.hasApiConfig = hasApiConfig;
+exports.isLegacyOptions = isLegacyOptions;
+exports.normalizeServerOptions = normalizeServerOptions;
+const deepmerge_1 = __importDefault(require("deepmerge"));
+const graphql_types_1 = require("@constructive-io/graphql-types");
+// ============================================
+// Default Configuration
+// ============================================
+/**
+ * Default configuration values for GraphQL server
+ *
+ * Provides sensible defaults for all currently active fields.
+ */
+exports.serverDefaults = {
+    pg: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'postgres'
+    },
+    server: {
+        host: 'localhost',
+        port: 3000,
+        trustProxy: false,
+        strictAuth: false
+    },
+    api: graphql_types_1.apiDefaults,
+    graphile: graphql_types_1.graphileDefaults,
+    features: graphql_types_1.graphileFeatureDefaults
+};
+// ============================================
+// Type Guards
+// ============================================
+/**
+ * List of all recognized fields in ConstructiveOptions
+ */
+const RECOGNIZED_FIELDS = [
+    'pg',
+    'server',
+    'api',
+    'graphile',
+    'features',
+    'db',
+    'cdn',
+    'deployment',
+    'migrations',
+    'jobs'
+];
+/**
+ * Type guard to validate if an unknown value is a valid ConstructiveOptions object
+ *
+ * Validates that:
+ * 1. The value is a non-null object
+ * 2. Contains at least one recognized field from the interface
+ * 3. All recognized fields that exist have object values (not primitives)
+ *
+ * @param opts - Unknown value to validate
+ * @returns True if opts is a valid ConstructiveOptions object
+ *
+ * @example
+ * ```typescript
+ * if (isConstructiveOptions(unknownConfig)) {
+ *   // TypeScript knows unknownConfig is ConstructiveOptions
+ *   const { pg, server } = unknownConfig;
+ * }
+ * ```
+ */
+function isConstructiveOptions(opts) {
+    if (opts === null || opts === undefined) {
+        return false;
+    }
+    if (typeof opts !== 'object') {
+        return false;
+    }
+    const obj = opts;
+    // Check for at least one recognized field from the interface
+    const hasRecognizedField = RECOGNIZED_FIELDS.some((field) => field in obj);
+    if (!hasRecognizedField) {
+        return false;
+    }
+    // Validate that recognized fields have object values (not primitives)
+    for (const field of RECOGNIZED_FIELDS) {
+        if (field in obj && obj[field] !== undefined && obj[field] !== null) {
+            if (typeof obj[field] !== 'object') {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Type guard to check if an object has PostgreSQL configuration
+ *
+ * @param opts - Unknown value to check
+ * @returns True if opts has a defined pg property
+ *
+ * @example
+ * ```typescript
+ * if (hasPgConfig(config)) {
+ *   console.log(config.pg.host);
+ * }
+ * ```
+ */
+function hasPgConfig(opts) {
+    if (opts === null || opts === undefined || typeof opts !== 'object') {
+        return false;
+    }
+    return 'pg' in opts && opts.pg !== undefined;
+}
+/**
+ * Type guard to check if an object has HTTP server configuration
+ *
+ * @param opts - Unknown value to check
+ * @returns True if opts has a defined server property
+ *
+ * @example
+ * ```typescript
+ * if (hasServerConfig(config)) {
+ *   console.log(config.server.port);
+ * }
+ * ```
+ */
+function hasServerConfig(opts) {
+    if (opts === null || opts === undefined || typeof opts !== 'object') {
+        return false;
+    }
+    return 'server' in opts && opts.server !== undefined;
+}
+/**
+ * Type guard to check if an object has API configuration
+ *
+ * @param opts - Unknown value to check
+ * @returns True if opts has a defined api property
+ *
+ * @example
+ * ```typescript
+ * if (hasApiConfig(config)) {
+ *   console.log(config.api.exposedSchemas);
+ * }
+ * ```
+ */
+function hasApiConfig(opts) {
+    if (opts === null || opts === undefined || typeof opts !== 'object') {
+        return false;
+    }
+    return 'api' in opts && opts.api !== undefined;
+}
+// ============================================
+// Internal Utilities
+// ============================================
+/**
+ * Array merge strategy that replaces arrays (source wins over target).
+ * This ensures that when a user specifies an array value, it replaces
+ * the default rather than merging/concatenating.
+ *
+ * @internal
+ */
+const replaceArrays = (_target, source) => source;
+// ============================================
+// Utility Functions
+// ============================================
+/**
+ * Legacy field names that indicate old configuration format
+ */
+const LEGACY_FIELDS = [
+    'schemas', // Old array-style schema config (should be graphile.schema)
+    'pgConfig', // Old naming (should be pg)
+    'serverPort', // Flat config (should be server.port)
+    'serverHost', // Flat config (should be server.host)
+    'dbConfig', // Old naming (should be db)
+    'postgraphile', // Old Graphile v4 naming (should be graphile)
+    'pgPool', // Direct pool config (deprecated)
+    'jwtSecret', // Flat JWT config (should be in api or auth)
+    'watchPg' // Old PostGraphile v4 option
+];
+/**
+ * Detects if the given options object uses a deprecated/legacy format
+ *
+ * Checks for presence of legacy field names that indicate the configuration
+ * needs to be migrated to ConstructiveOptions format.
+ *
+ * @param opts - Unknown value to check
+ * @returns True if legacy configuration patterns are detected
+ *
+ * @example
+ * ```typescript
+ * if (isLegacyOptions(config)) {
+ *   console.warn('Detected legacy configuration format. Please migrate to ConstructiveOptions.');
+ * }
+ * ```
+ */
+function isLegacyOptions(opts) {
+    if (opts === null || opts === undefined || typeof opts !== 'object') {
+        return false;
+    }
+    const obj = opts;
+    return LEGACY_FIELDS.some((field) => field in obj);
+}
+/**
+ * Normalizes input to a ConstructiveOptions object with defaults applied
+ *
+ * Accepts ConstructiveOptions and returns a fully normalized object
+ * with default values applied via deep merge. User-provided values override defaults.
+ *
+ * @param opts - ConstructiveOptions to normalize
+ * @returns ConstructiveOptions with defaults filled in
+ *
+ * @example
+ * ```typescript
+ * // Partial config - missing fields filled from defaults
+ * const normalized = normalizeServerOptions({
+ *   pg: { database: 'myapp' }
+ * });
+ *
+ * // normalized.pg.host === 'localhost' (from default)
+ * // normalized.pg.database === 'myapp' (from user config)
+ * // normalized.server.port === 3000 (from default)
+ * ```
+ */
+function normalizeServerOptions(opts) {
+    // Deep merge with defaults - user options override defaults
+    return (0, deepmerge_1.default)(exports.serverDefaults, opts, { arrayMerge: replaceArrays });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "3.1.1",
+  "version": "4.0.1",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -42,38 +42,37 @@
     "backend"
   ],
   "dependencies": {
-    "@constructive-io/graphql-env": "^2.10.0",
-    "@constructive-io/graphql-types": "^2.15.0",
+    "@constructive-io/graphql-env": "^3.0.0",
+    "@constructive-io/graphql-types": "^3.0.0",
     "@constructive-io/s3-utils": "^2.6.0",
     "@constructive-io/upload-names": "^2.5.0",
     "@constructive-io/url-domains": "^2.5.0",
-    "@graphile-contrib/pg-many-to-many": "^1.0.2",
+    "@graphile-contrib/pg-many-to-many": "2.0.0-rc.1",
+    "@graphile/simplify-inflection": "8.0.0-rc.3",
     "@pgpmjs/logger": "^2.1.0",
     "@pgpmjs/server-utils": "^3.1.0",
     "@pgpmjs/types": "^2.16.0",
     "cors": "^2.8.5",
+    "deepmerge": "^4.3.1",
     "express": "^5.2.1",
-    "gql-ast": "^2.7.0",
-    "graphile-build": "^4.14.1",
-    "graphile-cache": "^2.1.0",
-    "graphile-i18n": "^1.1.1",
-    "graphile-meta-schema": "^1.1.1",
-    "graphile-plugin-connection-filter": "^3.1.1",
-    "graphile-plugin-connection-filter-postgis": "^2.1.1",
-    "graphile-plugin-fulltext-filter": "^3.1.1",
-    "graphile-query": "^2.6.0",
-    "graphile-search-plugin": "^1.1.1",
-    "graphile-settings": "^3.1.1",
-    "graphile-simple-inflector": "^1.1.1",
-    "graphile-utils": "^4.14.1",
-    "graphql": "15.10.1",
-    "graphql-tag": "2.12.6",
+    "gql-ast": "^3.0.0",
+    "grafast": "^1.0.0-rc.4",
+    "grafserv": "^1.0.0-rc.4",
+    "graphile-build": "^5.0.0-rc.3",
+    "graphile-build-pg": "^5.0.0-rc.3",
+    "graphile-cache": "^3.0.0",
+    "graphile-config": "1.0.0-rc.3",
+    "graphile-settings": "^4.0.1",
+    "graphql": "^16.9.0",
     "graphql-upload": "^13.0.0",
     "lru-cache": "^11.2.4",
     "pg": "^8.17.1",
-    "pg-cache": "^2.1.0",
+    "pg-cache": "^3.0.0",
+    "pg-env": "^1.4.0",
     "pg-query-context": "^2.5.0",
-    "postgraphile": "^4.14.1",
+    "pg-sql2": "^5.0.0-rc.3",
+    "postgraphile": "^5.0.0-rc.4",
+    "postgraphile-plugin-connection-filter": "^3.0.0-rc.1",
     "request-ip": "^3.3.0"
   },
   "devDependencies": {
@@ -83,11 +82,11 @@
     "@types/graphql-upload": "^8.0.12",
     "@types/pg": "^8.16.0",
     "@types/request-ip": "^0.0.41",
-    "graphile-test": "3.1.1",
-    "makage": "^0.1.12",
+    "graphile-test": "4.0.0",
+    "makage": "^0.1.10",
     "nodemon": "^3.1.10",
     "rimraf": "^6.1.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "49049ad3ddd762d35625f657cb42fa0862b829a0"
+  "gitHead": "c05d6bd3dfa36690aefe21079042666dfae801a1"
 }

package/schema.d.ts

@@ -1,8 +1,8 @@
-import { PostGraphileOptions } from 'postgraphile';
+import type { GraphileConfig } from 'graphile-config';
 export type BuildSchemaOptions = {
     database?: string;
     schemas: string[];
-    graphile?: Partial<PostGraphileOptions>;
+    graphile?: Partial<GraphileConfig.Preset>;
 };
 export declare function buildSchemaSDL(opts: BuildSchemaOptions): Promise<string>;
 export declare function fetchEndpointSchemaSDL(endpoint: string, opts?: {

package/schema.js

@@ -37,22 +37,35 @@ exports.buildSchemaSDL = buildSchemaSDL;
 exports.fetchEndpointSchemaSDL = fetchEndpointSchemaSDL;
 const graphql_1 = require("graphql");
 const graphile_settings_1 = require("graphile-settings");
+const graphile_build_1 = require("graphile-build");
 const pg_cache_1 = require("pg-cache");
-const postgraphile_1 = require("postgraphile");
 const http = __importStar(require("node:http"));
 const https = __importStar(require("node:https"));
-// Build GraphQL Schema SDL directly from Postgres using PostGraphile, without HTTP.
+// Build GraphQL Schema SDL directly from Postgres using PostGraphile v5, without HTTP.
 async function buildSchemaSDL(opts) {
     const database = opts.database ?? 'constructive';
     const schemas = Array.isArray(opts.schemas) ? opts.schemas : [];
-    const settings = (0, graphile_settings_1.getGraphileSettings)({
-        graphile: {
-            schema: schemas,
-            ...(opts.graphile ?? {})
-        }
-    });
-    const pgPool = (0, pg_cache_1.getPgPool)({ database });
-    const schema = await (0, postgraphile_1.createPostGraphileSchema)(pgPool, schemas, settings);
+    // Get pool config for connection string
+    const pool = (0, pg_cache_1.getPgPool)({ database });
+    const poolConfig = pool.options || {};
+    const connectionString = `postgres://${poolConfig.user || 'postgres'}:${poolConfig.password || ''}@${poolConfig.host || 'localhost'}:${poolConfig.port || 5432}/${database}`;
+    // Build v5 preset
+    const preset = {
+        extends: [
+            graphile_settings_1.ConstructivePreset,
+            ...(opts.graphile?.extends ?? []),
+        ],
+        ...(opts.graphile?.disablePlugins && { disablePlugins: opts.graphile.disablePlugins }),
+        ...(opts.graphile?.plugins && { plugins: opts.graphile.plugins }),
+        ...(opts.graphile?.schema && { schema: opts.graphile.schema }),
+        pgServices: [
+            (0, graphile_settings_1.makePgService)({
+                connectionString,
+                schemas,
+            }),
+        ],
+    };
+    const { schema } = await (0, graphile_build_1.makeSchema)(preset);
     return (0, graphql_1.printSchema)(schema);
 }
 // Fetch GraphQL Schema SDL from a running GraphQL endpoint via introspection.

package/server.d.ts

@@ -1,7 +1,29 @@
+import type { ConstructiveOptions } from '@constructive-io/graphql-types';
 import { PgpmOptions } from '@pgpmjs/types';
 import type { Server as HttpServer } from 'http';
 import { Pool, PoolClient } from 'pg';
-export declare const GraphQLServer: (rawOpts?: PgpmOptions) => void;
+/**
+ * Creates and starts a GraphQL server instance
+ *
+ * Accepts ConstructiveOptions or PgpmOptions.
+ * Options are normalized using normalizeServerOptions to apply defaults.
+ *
+ * @param rawOpts - Server configuration options
+ * @returns void (server runs until shutdown)
+ *
+ * @example
+ * ```typescript
+ * // Using ConstructiveOptions (recommended)
+ * GraphQLServer({
+ *   pg: { database: 'myapp' },
+ *   server: { port: 4000 }
+ * });
+ *
+ * // Using PgpmOptions (backward compatible)
+ * GraphQLServer(pgpmOptions);
+ * ```
+ */
+export declare const GraphQLServer: (rawOpts?: ConstructiveOptions | PgpmOptions) => void;
 declare class Server {
     private app;
     private opts;
@@ -10,7 +32,7 @@ declare class Server {
     private shuttingDown;
     private closed;
     private httpServer;
-    constructor(opts: PgpmOptions);
+    constructor(opts: ConstructiveOptions);
     listen(): HttpServer;
     flush(databaseId: string): Promise<void>;
     getPool(): Pool;

package/server.js

@@ -18,12 +18,40 @@ const request_ip_1 = __importDefault(require("request-ip"));
 const api_1 = require("./middleware/api");
 const auth_1 = require("./middleware/auth");
 const cors_1 = require("./middleware/cors");
+const error_handler_1 = require("./middleware/error-handler");
+const favicon_1 = require("./middleware/favicon");
 const flush_1 = require("./middleware/flush");
 const graphile_1 = require("./middleware/graphile");
+const options_1 = require("./options");
 const log = new logger_1.Logger('server');
 const isDev = () => (0, graphql_env_1.getNodeEnv)() === 'development';
+/**
+ * Creates and starts a GraphQL server instance
+ *
+ * Accepts ConstructiveOptions or PgpmOptions.
+ * Options are normalized using normalizeServerOptions to apply defaults.
+ *
+ * @param rawOpts - Server configuration options
+ * @returns void (server runs until shutdown)
+ *
+ * @example
+ * ```typescript
+ * // Using ConstructiveOptions (recommended)
+ * GraphQLServer({
+ *   pg: { database: 'myapp' },
+ *   server: { port: 4000 }
+ * });
+ *
+ * // Using PgpmOptions (backward compatible)
+ * GraphQLServer(pgpmOptions);
+ * ```
+ */
 const GraphQLServer = (rawOpts = {}) => {
-    const envOptions = (0, graphql_env_1.getEnvOptions)(rawOpts);
+    // Normalize options to ConstructiveOptions with defaults applied
+    const normalizedOpts = (0, options_1.normalizeServerOptions)(rawOpts);
+    // Apply environment variable overrides via getEnvOptions
+    // Cast to PgpmOptions for backward compatibility with getEnvOptions
+    const envOptions = (0, graphql_env_1.getEnvOptions)(normalizedOpts);
     const app = new Server(envOptions);
     app.addEventListener();
     app.listen();
@@ -78,6 +106,7 @@ class Server {
             roleName: apiOpts.roleName
         });
         (0, server_utils_1.healthz)(app);
+        app.use(favicon_1.favicon);
         (0, server_utils_1.trustProxy)(app, effectiveOpts.server.trustProxy);
         // Warn if a global CORS override is set in production
         const fallbackOrigin = effectiveOpts.server?.origin?.trim();
@@ -99,6 +128,9 @@ class Server {
         app.use(authenticate);
         app.use((0, graphile_1.graphile)(effectiveOpts));
         app.use(flush_1.flush);
+        // Error handling - MUST be LAST
+        app.use(error_handler_1.notFoundHandler); // Catches unmatched routes (404)
+        app.use(error_handler_1.errorHandler); // Catches all thrown errors
         this.app = app;
     }
     listen() {
@@ -199,9 +231,13 @@ class Server {
     static async closeCaches(opts = {}) {
         const { closePools = false } = opts;
         server_utils_1.svcCache.clear();
-        graphile_cache_1.graphileCache.clear();
+        // Use closeAllCaches to properly await async disposal of PostGraphile instances
+        // before closing pg pools - this ensures all connections are released
         if (closePools) {
-            await pg_cache_1.pgCache.close();
+            await (0, graphile_cache_1.closeAllCaches)();
+        }
+        else {
+            graphile_cache_1.graphileCache.clear();
         }
     }
     log(text) {

package/codegen/orm/client.d.ts

@@ -1,55 +0,0 @@
-/**
- * ORM Client - Runtime GraphQL executor
- * @generated by @constructive-io/graphql-codegen
- * DO NOT EDIT - changes will be overwritten
- */
-export interface OrmClientConfig {
-    endpoint: string;
-    headers?: Record<string, string>;
-}
-export interface GraphQLError {
-    message: string;
-    locations?: {
-        line: number;
-        column: number;
-    }[];
-    path?: (string | number)[];
-    extensions?: Record<string, unknown>;
-}
-/**
- * Error thrown when GraphQL request fails
- */
-export declare class GraphQLRequestError extends Error {
-    readonly errors: GraphQLError[];
-    readonly data: unknown;
-    constructor(errors: GraphQLError[], data?: unknown);
-}
-/**
- * Discriminated union for query results
- * Use .ok to check success, or use .unwrap() to get data or throw
- */
-export type QueryResult<T> = {
-    ok: true;
-    data: T;
-    errors: undefined;
-} | {
-    ok: false;
-    data: null;
-    errors: GraphQLError[];
-};
-/**
- * Legacy QueryResult type for backwards compatibility
- * @deprecated Use QueryResult discriminated union instead
- */
-export interface LegacyQueryResult<T> {
-    data: T | null;
-    errors?: GraphQLError[];
-}
-export declare class OrmClient {
-    private endpoint;
-    private headers;
-    constructor(config: OrmClientConfig);
-    execute<T>(document: string, variables?: Record<string, unknown>): Promise<QueryResult<T>>;
-    setHeaders(headers: Record<string, string>): void;
-    getEndpoint(): string;
-}

package/codegen/orm/client.js

@@ -1,75 +0,0 @@
-"use strict";
-/**
- * ORM Client - Runtime GraphQL executor
- * @generated by @constructive-io/graphql-codegen
- * DO NOT EDIT - changes will be overwritten
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OrmClient = exports.GraphQLRequestError = void 0;
-/**
- * Error thrown when GraphQL request fails
- */
-class GraphQLRequestError extends Error {
-    errors;
-    data;
-    constructor(errors, data = null) {
-        const messages = errors.map((e) => e.message).join('; ');
-        super(`GraphQL Error: ${messages}`);
-        this.errors = errors;
-        this.data = data;
-        this.name = 'GraphQLRequestError';
-    }
-}
-exports.GraphQLRequestError = GraphQLRequestError;
-class OrmClient {
-    endpoint;
-    headers;
-    constructor(config) {
-        this.endpoint = config.endpoint;
-        this.headers = config.headers ?? {};
-    }
-    async execute(document, variables) {
-        const response = await fetch(this.endpoint, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Accept: 'application/json',
-                ...this.headers,
-            },
-            body: JSON.stringify({
-                query: document,
-                variables: variables ?? {},
-            }),
-        });
-        if (!response.ok) {
-            return {
-                ok: false,
-                data: null,
-                errors: [
-                    { message: `HTTP ${response.status}: ${response.statusText}` },
-                ],
-            };
-        }
-        const json = (await response.json());
-        // Return discriminated union based on presence of errors
-        if (json.errors && json.errors.length > 0) {
-            return {
-                ok: false,
-                data: null,
-                errors: json.errors,
-            };
-        }
-        return {
-            ok: true,
-            data: json.data,
-            errors: undefined,
-        };
-    }
-    setHeaders(headers) {
-        this.headers = { ...this.headers, ...headers };
-    }
-    getEndpoint() {
-        return this.endpoint;
-    }
-}
-exports.OrmClient = OrmClient;

package/codegen/orm/index.d.ts

@@ -1,36 +0,0 @@
-import type { OrmClientConfig } from './client';
-import { ApiModel } from './models/api';
-import { DomainModel } from './models/domain';
-export type { OrmClientConfig, QueryResult, GraphQLError } from './client';
-export { GraphQLRequestError } from './client';
-export { QueryBuilder } from './query-builder';
-export * from './select-types';
-/**
- * Create an ORM client instance
- *
- * @example
- * ```typescript
- * const db = createClient({
- *   endpoint: 'https://api.example.com/graphql',
- *   headers: { Authorization: 'Bearer token' },
- * });
- *
- * // Query apis
- * const apis = await db.api.findMany({
- *   select: { id: true, name: true },
- *   first: 10,
- * }).execute();
- * ```
- */
-export declare function createClient(config: OrmClientConfig): {
-    api: ApiModel;
-    domain: DomainModel;
-    query: {
-        apiByDatabaseIdAndName: <const S extends import("./input-types").ApiSelect>(args: import("./query").ApiByDatabaseIdAndNameVariables, options?: {
-            select?: import("./select-types").DeepExact<S, import("./input-types").ApiSelect>;
-        }) => import("./query-builder").QueryBuilder<{
-            apiByDatabaseIdAndName: import("./select-types").InferSelectResult<import("./input-types").Api, S>;
-        }>;
-    };
-    mutation: {};
-};