graphile-settings 4.10.3 → 4.12.0

package/esm/plugins/blueprint-types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Node Type Registry Plugin
+ *
+ * Exports the gather-phase plugin and preset for generating @oneOf typed
+ * input types for blueprint definitions from node_type_registry.
+ *
+ * The NodeTypeRegistryPlugin queries node_type_registry through the existing
+ * pgService connection during the gather phase — no separate pool needed.
+ */
+export { NodeTypeRegistryPlugin, NodeTypeRegistryPreset, createBlueprintTypesPlugin, BlueprintTypesPreset, } from './plugin';
+export type { NodeTypeRegistryEntry } from './plugin';

package/esm/plugins/blueprint-types/index.js

@@ -0,0 +1,12 @@
+/**
+ * Node Type Registry Plugin
+ *
+ * Exports the gather-phase plugin and preset for generating @oneOf typed
+ * input types for blueprint definitions from node_type_registry.
+ *
+ * The NodeTypeRegistryPlugin queries node_type_registry through the existing
+ * pgService connection during the gather phase — no separate pool needed.
+ */
+export { NodeTypeRegistryPlugin, NodeTypeRegistryPreset, 
+// Legacy exports for backward compatibility
+createBlueprintTypesPlugin, BlueprintTypesPreset, } from './plugin';

package/esm/plugins/blueprint-types/json-schema-to-graphql.d.ts

@@ -0,0 +1,64 @@
+/**
+ * JSON Schema to GraphQL Input Field Spec Converter
+ *
+ * Converts JSON Schema objects (from node_type_registry.parameter_schema)
+ * into field spec objects compatible with PostGraphile v5's fieldWithHooks API.
+ *
+ * Handles:
+ * - string, integer, number, boolean primitives
+ * - arrays (items -> GraphQLList)
+ * - enums -> GraphQLEnumType
+ * - required fields -> GraphQLNonNull
+ * - union types (["integer", "string"]) -> JSON scalar fallback
+ */
+import type { GraphQLInputType, GraphQLScalarType, GraphQLNullableType } from 'graphql';
+interface JsonSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    anyOf?: JsonSchema[];
+    description?: string;
+}
+/**
+ * A field spec that mirrors GraphQLInputFieldConfig.
+ */
+export interface FieldSpec {
+    type: GraphQLInputType;
+    description?: string;
+}
+/**
+ * Minimal build interface — only what we need from PostGraphile's Build object.
+ *
+ * Uses permissive constructor signatures to avoid variance issues between
+ * GraphQLNullableType and GraphQLInputType in the graphql-js type hierarchy.
+ */
+export interface BuildLike {
+    graphql: {
+        GraphQLString: GraphQLScalarType;
+        GraphQLInt: GraphQLScalarType;
+        GraphQLFloat: GraphQLScalarType;
+        GraphQLBoolean: GraphQLScalarType;
+        GraphQLNonNull: new (type: any) => GraphQLInputType;
+        GraphQLList: new (type: any) => GraphQLInputType & GraphQLNullableType;
+        GraphQLEnumType: new (config: {
+            name: string;
+            values: Record<string, {
+                value: string;
+            }>;
+        }) => GraphQLInputType & GraphQLNullableType;
+    };
+    getTypeByName: (name: string) => unknown;
+}
+/**
+ * Convert a full JSON Schema (from parameter_schema) to field specs.
+ *
+ * Uses the build object from PostGraphile v5 to access GraphQL types,
+ * avoiding direct graphql imports (which can cause version mismatches).
+ *
+ * @param schema - The JSON Schema object
+ * @param typeName - The name prefix for generated enum types
+ * @param build - The PostGraphile build object
+ * @returns Record of field name -> FieldSpec
+ */
+export declare function jsonSchemaToGraphQLFieldSpecs(schema: JsonSchema, typeName: string, build: BuildLike): Record<string, FieldSpec>;
+export {};

package/esm/plugins/blueprint-types/json-schema-to-graphql.js

@@ -0,0 +1,89 @@
+/**
+ * JSON Schema to GraphQL Input Field Spec Converter
+ *
+ * Converts JSON Schema objects (from node_type_registry.parameter_schema)
+ * into field spec objects compatible with PostGraphile v5's fieldWithHooks API.
+ *
+ * Handles:
+ * - string, integer, number, boolean primitives
+ * - arrays (items -> GraphQLList)
+ * - enums -> GraphQLEnumType
+ * - required fields -> GraphQLNonNull
+ * - union types (["integer", "string"]) -> JSON scalar fallback
+ */
+/**
+ * Convert a JSON Schema type string to a GraphQL scalar type.
+ */
+function jsonTypeToGraphQL(jsonType, graphql, jsonScalar) {
+    if (Array.isArray(jsonType)) {
+        return jsonScalar;
+    }
+    switch (jsonType) {
+        case 'string':
+            return graphql.GraphQLString;
+        case 'integer':
+            return graphql.GraphQLInt;
+        case 'number':
+            return graphql.GraphQLFloat;
+        case 'boolean':
+            return graphql.GraphQLBoolean;
+        case 'object':
+            return jsonScalar;
+        case 'array':
+            return new graphql.GraphQLList(jsonScalar);
+        default:
+            return jsonScalar;
+    }
+}
+/**
+ * Convert a full JSON Schema (from parameter_schema) to field specs.
+ *
+ * Uses the build object from PostGraphile v5 to access GraphQL types,
+ * avoiding direct graphql imports (which can cause version mismatches).
+ *
+ * @param schema - The JSON Schema object
+ * @param typeName - The name prefix for generated enum types
+ * @param build - The PostGraphile build object
+ * @returns Record of field name -> FieldSpec
+ */
+export function jsonSchemaToGraphQLFieldSpecs(schema, typeName, build) {
+    const fields = {};
+    const properties = schema.properties;
+    if (!properties) {
+        return fields;
+    }
+    const { graphql } = build;
+    const jsonScalar = (build.getTypeByName('JSON') ?? graphql.GraphQLString);
+    const required = new Set(schema.required ?? []);
+    for (const [propName, prop] of Object.entries(properties)) {
+        let fieldType;
+        if (prop.enum && prop.enum.length > 0) {
+            const values = {};
+            for (const val of prop.enum) {
+                const safeName = val.replace(/[^_a-zA-Z0-9]/g, '_').toUpperCase();
+                values[safeName] = { value: val };
+            }
+            fieldType = new graphql.GraphQLEnumType({
+                name: `${typeName}_${propName}`,
+                values,
+            });
+        }
+        else if (prop.type === 'array' && prop.items) {
+            const innerType = prop.items.type
+                ? jsonTypeToGraphQL(prop.items.type, graphql, jsonScalar)
+                : jsonScalar;
+            fieldType = new graphql.GraphQLList(innerType);
+        }
+        else {
+            fieldType = jsonTypeToGraphQL(prop.type ?? 'string', graphql, jsonScalar);
+        }
+        if (required.has(propName)) {
+            fieldType = new graphql.GraphQLNonNull(fieldType);
+        }
+        fields[propName] = {
+            type: fieldType,
+            description: prop.description ?? undefined,
+        };
+    }
+    return fields;
+}

package/esm/plugins/blueprint-types/plugin.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Node Type Registry Plugin
+ *
+ * Generic PostGraphile v5 plugin that queries node_type_registry at schema
+ * build time through the existing pgService connection (gather phase) and
+ * generates @oneOf typed input types with SuperCase node type names as
+ * discriminant keys.
+ *
+ * Architecture (correct PostGraphile v5 pattern):
+ * 1. `gather` phase: hooks into pgIntrospection_introspection to query
+ *    node_type_registry through the existing pgService (no separate pool —
+ *    uses withPgClientFromPgService like PgIntrospectionPlugin)
+ * 2. `init` hook: registers all input type shells from gathered entries
+ * 3. `GraphQLInputObjectType_fields` hook: populates fields on those types
+ *
+ * Generated type hierarchy:
+ *
+ *   BlueprintDefinitionInput
+ *   +-- tables: [BlueprintTableInput!]
+ *   |   +-- ref: String!
+ *   |   +-- tableName: String!
+ *   |   +-- nodes: [BlueprintNodeInput!]!    <-- @oneOf
+ *   |       +-- shorthand: String
+ *   |       +-- DataId: DataIdParams
+ *   |       +-- DataTimestamps: DataTimestampsParams
+ *   |       +-- AuthzEntityMembership: AuthzEntityMembershipParams
+ *   |       +-- ...
+ *   +-- relations: [BlueprintRelationInput!]  <-- @oneOf
+ *       +-- RelationBelongsTo: RelationBelongsToParams
+ *       +-- ...
+ *
+ * When codegen runs, @oneOf types become discriminated union types:
+ *
+ *   type BlueprintNodeInput =
+ *     | { DataId: DataIdParams }
+ *     | { DataTimestamps: DataTimestampsParams }
+ *     | { AuthzEntityMembership: AuthzEntityMembershipParams }
+ */
+import type { GraphileConfig } from 'graphile-config';
+export interface NodeTypeRegistryEntry {
+    name: string;
+    slug: string;
+    category: string;
+    display_name: string;
+    description: string;
+    parameter_schema: Record<string, unknown>;
+    tags: string[];
+}
+declare global {
+    namespace GraphileBuild {
+        interface ScopeInputObject {
+            isBlueprintOneOf?: boolean;
+            isBlueprintNodeParams?: boolean;
+            isBlueprintTable?: boolean;
+            isBlueprintDefinition?: boolean;
+            isBlueprintRelation?: boolean;
+            blueprintNodeTypeName?: string;
+        }
+        interface BuildInput {
+            nodeTypeRegistryEntries?: NodeTypeRegistryEntry[];
+        }
+    }
+}
+/**
+ * NodeTypeRegistryPlugin
+ *
+ * Gather-phase plugin that queries node_type_registry through the existing
+ * pgService connection, then generates @oneOf typed input types in the
+ * schema phase. No separate PG pool -- uses the same connection PostGraphile
+ * already has (same pattern as PgIntrospectionPlugin / PgEnumTablesPlugin).
+ *
+ * If the table doesn't exist (42P01) or the query fails, the plugin
+ * gracefully skips and no types are registered.
+ */
+export declare const NodeTypeRegistryPlugin: GraphileConfig.Plugin;
+/**
+ * Preset that includes the NodeTypeRegistryPlugin.
+ *
+ * Add to ConstructivePreset.extends[] -- the plugin will automatically
+ * query node_type_registry through the existing pgService connection
+ * during the gather phase. No separate pool, no manual wiring.
+ */
+export declare const NodeTypeRegistryPreset: GraphileConfig.Preset;
+/**
+ * @deprecated Use NodeTypeRegistryPlugin directly. The gather-phase plugin
+ * queries node_type_registry automatically via pgService. This factory is
+ * kept for backward compatibility and tests that pass static entries.
+ */
+export declare function createBlueprintTypesPlugin(nodeTypes: NodeTypeRegistryEntry[]): GraphileConfig.Plugin;
+/**
+ * @deprecated Use NodeTypeRegistryPreset directly. The gather-phase plugin
+ * queries node_type_registry automatically via pgService. This factory is
+ * kept for backward compatibility and tests that pass static entries.
+ */
+export declare function BlueprintTypesPreset(nodeTypes: NodeTypeRegistryEntry[]): GraphileConfig.Preset;

package/esm/plugins/blueprint-types/plugin.js

@@ -0,0 +1,287 @@
+import { withPgClientFromPgService } from 'graphile-build-pg';
+import { jsonSchemaToGraphQLFieldSpecs } from './json-schema-to-graphql';
+// ============================================================================
+// Constants
+// ============================================================================
+const BLUEPRINT_NODE_INPUT = 'BlueprintNodeInput';
+const BLUEPRINT_TABLE_INPUT = 'BlueprintTableInput';
+const BLUEPRINT_RELATION_INPUT = 'BlueprintRelationInput';
+const BLUEPRINT_DEFINITION_INPUT = 'BlueprintDefinitionInput';
+const NODE_TYPE_REGISTRY_QUERY = `
+  SELECT
+    name,
+    slug,
+    category,
+    COALESCE(display_name, name) as display_name,
+    COALESCE(description, '') as description,
+    COALESCE(parameter_schema, '{}'::jsonb) as parameter_schema,
+    COALESCE(tags, '{}') as tags
+  FROM metaschema_public.node_type_registry
+  ORDER BY category, name
+`;
+// ============================================================================
+// Shared schema hooks
+// ============================================================================
+/**
+ * Builds the schema hooks (init + GraphQLInputObjectType_fields) from
+ * a function that retrieves node type entries. Used by both the gather-phase
+ * plugin (reads from build.input) and the static/legacy plugin (closure).
+ */
+function buildSchemaHooks(getNodeTypes) {
+    return {
+        hooks: {
+            init(_, build) {
+                const nodeTypes = getNodeTypes(build);
+                if (nodeTypes.length === 0)
+                    return _;
+                for (const nt of nodeTypes) {
+                    const paramsTypeName = nt.name + 'Params';
+                    build.registerInputObjectType(paramsTypeName, {
+                        isBlueprintNodeParams: true,
+                        blueprintNodeTypeName: nt.name,
+                    }, () => ({
+                        description: nt.description,
+                    }), 'NodeTypeRegistryPlugin: ' + paramsTypeName);
+                }
+                build.registerInputObjectType(BLUEPRINT_NODE_INPUT, { isBlueprintOneOf: true }, () => ({
+                    description: 'A single node in a blueprint definition. Exactly one field must be set. Use the SuperCase node type name as the key with its parameters as the value, or use "shorthand" with just the node type name string.',
+                    isOneOf: true,
+                }), 'NodeTypeRegistryPlugin: BlueprintNodeInput');
+                build.registerInputObjectType(BLUEPRINT_RELATION_INPUT, { isBlueprintOneOf: true, isBlueprintRelation: true }, () => ({
+                    description: 'A relation in a blueprint definition. Exactly one field must be set. Use the SuperCase relation type name as the key.',
+                    isOneOf: true,
+                }), 'NodeTypeRegistryPlugin: BlueprintRelationInput');
+                build.registerInputObjectType(BLUEPRINT_TABLE_INPUT, { isBlueprintTable: true }, () => ({
+                    description: 'A table definition within a blueprint. Specifies the table reference, name, and an array of typed nodes.',
+                }), 'NodeTypeRegistryPlugin: BlueprintTableInput');
+                build.registerInputObjectType(BLUEPRINT_DEFINITION_INPUT, { isBlueprintDefinition: true }, () => ({
+                    description: 'The complete blueprint definition. Contains tables with typed nodes and relations.',
+                }), 'NodeTypeRegistryPlugin: BlueprintDefinitionInput');
+                return _;
+            },
+            GraphQLInputObjectType_fields(fields, build, context) {
+                const nodeTypes = getNodeTypes(build);
+                if (nodeTypes.length === 0)
+                    return fields;
+                const nodeTypesByName = new Map();
+                const relationNodeTypes = [];
+                const nonRelationNodeTypes = [];
+                for (const nt of nodeTypes) {
+                    nodeTypesByName.set(nt.name, nt);
+                    if (nt.category === 'relation') {
+                        relationNodeTypes.push(nt);
+                    }
+                    else {
+                        nonRelationNodeTypes.push(nt);
+                    }
+                }
+                const { extend, graphql: { GraphQLString, GraphQLNonNull, GraphQLList }, } = build;
+                const { fieldWithHooks, scope: { isBlueprintOneOf, isBlueprintNodeParams, isBlueprintTable, isBlueprintDefinition, isBlueprintRelation, blueprintNodeTypeName, }, } = context;
+                // --- Per-node-type params (e.g., DataIdParams) ---
+                if (isBlueprintNodeParams && blueprintNodeTypeName) {
+                    const nt = nodeTypesByName.get(blueprintNodeTypeName);
+                    if (!nt)
+                        return fields;
+                    const schema = nt.parameter_schema;
+                    const fieldSpecs = jsonSchemaToGraphQLFieldSpecs(schema, nt.name + 'Params', build);
+                    if (Object.keys(fieldSpecs).length > 0) {
+                        let result = fields;
+                        for (const [fieldName, spec] of Object.entries(fieldSpecs)) {
+                            result = extend(result, {
+                                [fieldName]: fieldWithHooks({ fieldName }, () => spec),
+                            }, 'NodeTypeRegistryPlugin: ' + blueprintNodeTypeName + '.' + fieldName);
+                        }
+                        return result;
+                    }
+                    return extend(fields, {
+                        _: fieldWithHooks({ fieldName: '_' }, () => ({
+                            type: build.graphql.GraphQLBoolean,
+                            description: 'No parameters required. Pass true or omit entirely.',
+                        })),
+                    }, 'NodeTypeRegistryPlugin: ' + blueprintNodeTypeName + '._');
+                }
+                // --- BlueprintNodeInput (@oneOf with all non-relation node types) ---
+                if (isBlueprintOneOf && !isBlueprintRelation) {
+                    let result = fields;
+                    result = extend(result, {
+                        shorthand: fieldWithHooks({ fieldName: 'shorthand' }, () => ({
+                            type: GraphQLString,
+                            description: 'String shorthand: just the SuperCase node type name (e.g., "DataTimestamps"). Use when the node type has no required parameters.',
+                        })),
+                    }, 'NodeTypeRegistryPlugin: BlueprintNodeInput.shorthand');
+                    for (const nt of nonRelationNodeTypes) {
+                        const paramsTypeName = nt.name + 'Params';
+                        const ParamsType = build.getTypeByName(paramsTypeName);
+                        if (!ParamsType)
+                            continue;
+                        result = extend(result, {
+                            [nt.name]: fieldWithHooks({ fieldName: nt.name }, () => ({
+                                type: ParamsType,
+                                description: 'Parameters for ' + nt.name + ' (' + nt.display_name + ')',
+                            })),
+                        }, 'NodeTypeRegistryPlugin: BlueprintNodeInput.' + nt.name);
+                    }
+                    return result;
+                }
+                // --- BlueprintRelationInput (@oneOf with relation node types) ---
+                if (isBlueprintOneOf && isBlueprintRelation) {
+                    let result = fields;
+                    for (const nt of relationNodeTypes) {
+                        const paramsTypeName = nt.name + 'Params';
+                        const ParamsType = build.getTypeByName(paramsTypeName);
+                        if (!ParamsType)
+                            continue;
+                        result = extend(result, {
+                            [nt.name]: fieldWithHooks({ fieldName: nt.name }, () => ({
+                                type: ParamsType,
+                                description: 'Parameters for ' + nt.name + ' (' + nt.display_name + ')',
+                            })),
+                        }, 'NodeTypeRegistryPlugin: BlueprintRelationInput.' + nt.name);
+                    }
+                    return result;
+                }
+                // --- BlueprintTableInput ---
+                if (isBlueprintTable) {
+                    const BlueprintNodeInputType = build.getTypeByName(BLUEPRINT_NODE_INPUT);
+                    return extend(fields, {
+                        ref: fieldWithHooks({ fieldName: 'ref' }, () => ({
+                            type: new GraphQLNonNull(GraphQLString),
+                            description: 'Unique reference key for this table within the blueprint (used for cross-references in relations).',
+                        })),
+                        tableName: fieldWithHooks({ fieldName: 'tableName' }, () => ({
+                            type: new GraphQLNonNull(GraphQLString),
+                            description: 'The PostgreSQL table name to create.',
+                        })),
+                        nodes: fieldWithHooks({ fieldName: 'nodes' }, () => ({
+                            type: BlueprintNodeInputType
+                                ? new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(BlueprintNodeInputType)))
+                                : new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLString))),
+                            description: 'Array of node type entries (data, authz, field behaviors) to apply to this table.',
+                        })),
+                    }, 'NodeTypeRegistryPlugin: BlueprintTableInput fields');
+                }
+                // --- BlueprintDefinitionInput ---
+                if (isBlueprintDefinition) {
+                    const BlueprintTableInputType = build.getTypeByName(BLUEPRINT_TABLE_INPUT);
+                    const BlueprintRelationInputType = build.getTypeByName(BLUEPRINT_RELATION_INPUT);
+                    return extend(fields, {
+                        tables: fieldWithHooks({ fieldName: 'tables' }, () => ({
+                            type: BlueprintTableInputType
+                                ? new GraphQLList(new GraphQLNonNull(BlueprintTableInputType))
+                                : new GraphQLList(GraphQLString),
+                            description: 'Array of table definitions.',
+                        })),
+                        relations: fieldWithHooks({ fieldName: 'relations' }, () => ({
+                            type: BlueprintRelationInputType
+                                ? new GraphQLList(new GraphQLNonNull(BlueprintRelationInputType))
+                                : new GraphQLList(GraphQLString),
+                            description: 'Array of relation definitions.',
+                        })),
+                    }, 'NodeTypeRegistryPlugin: BlueprintDefinitionInput fields');
+                }
+                return fields;
+            },
+        },
+    };
+}
+// ============================================================================
+// Gather-phase plugin (production -- queries DB through existing pgService)
+// ============================================================================
+/**
+ * NodeTypeRegistryPlugin
+ *
+ * Gather-phase plugin that queries node_type_registry through the existing
+ * pgService connection, then generates @oneOf typed input types in the
+ * schema phase. No separate PG pool -- uses the same connection PostGraphile
+ * already has (same pattern as PgIntrospectionPlugin / PgEnumTablesPlugin).
+ *
+ * If the table doesn't exist (42P01) or the query fails, the plugin
+ * gracefully skips and no types are registered.
+ */
+export const NodeTypeRegistryPlugin = {
+    name: 'NodeTypeRegistryPlugin',
+    version: '1.0.0',
+    description: 'Queries node_type_registry via the existing pgService and generates @oneOf typed input types with SuperCase keys',
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    gather: {
+        namespace: 'nodeTypeRegistry',
+        version: 1,
+        initialState() {
+            return { entries: [] };
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async finalize(info) {
+            info.buildInput.nodeTypeRegistryEntries =
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                info.state.entries ?? [];
+        },
+        hooks: {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            async pgIntrospection_introspection(info, event) {
+                const { serviceName } = event;
+                const pgService = info.resolvedPreset.pgServices?.find((svc) => svc.name === serviceName);
+                if (!pgService)
+                    return;
+                try {
+                    const result = await withPgClientFromPgService(pgService, null, (client) => client.query({ text: NODE_TYPE_REGISTRY_QUERY }));
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const state = info.state;
+                    if (!state.entries) {
+                        state.entries = [];
+                    }
+                    state.entries.push(...result.rows);
+                }
+                catch (error) {
+                    const pgError = error;
+                    if (pgError.code === '42P01') {
+                        // 42P01 = undefined_table -- expected when DB hasn't been migrated
+                        return;
+                    }
+                    // Warn but don't fail the schema build
+                    console.warn('[NodeTypeRegistryPlugin] Failed to query node_type_registry:', pgError.message ?? String(error));
+                }
+            },
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    },
+    schema: buildSchemaHooks((build) => build.input.nodeTypeRegistryEntries ?? []),
+};
+// ============================================================================
+// Preset
+// ============================================================================
+/**
+ * Preset that includes the NodeTypeRegistryPlugin.
+ *
+ * Add to ConstructivePreset.extends[] -- the plugin will automatically
+ * query node_type_registry through the existing pgService connection
+ * during the gather phase. No separate pool, no manual wiring.
+ */
+export const NodeTypeRegistryPreset = {
+    plugins: [NodeTypeRegistryPlugin],
+};
+// ============================================================================
+// Legacy exports for backward compatibility
+// ============================================================================
+/**
+ * @deprecated Use NodeTypeRegistryPlugin directly. The gather-phase plugin
+ * queries node_type_registry automatically via pgService. This factory is
+ * kept for backward compatibility and tests that pass static entries.
+ */
+export function createBlueprintTypesPlugin(nodeTypes) {
+    return {
+        name: 'BlueprintTypesPlugin',
+        version: '1.0.0',
+        description: 'Generates @oneOf typed input types from static node_type_registry entries',
+        schema: buildSchemaHooks(() => nodeTypes),
+    };
+}
+/**
+ * @deprecated Use NodeTypeRegistryPreset directly. The gather-phase plugin
+ * queries node_type_registry automatically via pgService. This factory is
+ * kept for backward compatibility and tests that pass static entries.
+ */
+export function BlueprintTypesPreset(nodeTypes) {
+    return {
+        plugins: [createBlueprintTypesPlugin(nodeTypes)],
+    };
+}

package/esm/plugins/index.d.ts

@@ -20,3 +20,5 @@ export { _pgTypeToGqlType, _buildFieldMeta, _cachedTablesMeta } from './meta-sch
 export { RequiredInputPlugin, RequiredInputPreset, } from './required-input-plugin';
 export { createUnifiedSearchPlugin, UnifiedSearchPreset, TsvectorCodecPlugin, TsvectorCodecPreset, createTsvectorCodecPlugin, Bm25CodecPlugin, Bm25CodecPreset, bm25IndexStore, VectorCodecPlugin, VectorCodecPreset, createTsvectorAdapter, createBm25Adapter, createTrgmAdapter, createPgvectorAdapter, createMatchesOperatorFactory, createTrgmOperatorFactories, } from 'graphile-search';
 export type { SearchAdapter, SearchableColumn, UnifiedSearchOptions, UnifiedSearchPresetOptions, TsvectorCodecPluginOptions, Bm25IndexInfo, TsvectorAdapterOptions, Bm25AdapterOptions, TrgmAdapterOptions, PgvectorAdapterOptions, } from 'graphile-search';
+export { NodeTypeRegistryPlugin, NodeTypeRegistryPreset, createBlueprintTypesPlugin, BlueprintTypesPreset, } from './blueprint-types';
+export type { NodeTypeRegistryEntry } from './blueprint-types';

package/esm/plugins/index.js

@@ -37,3 +37,8 @@ TsvectorCodecPlugin, TsvectorCodecPreset, createTsvectorCodecPlugin, Bm25CodecPl
 createTsvectorAdapter, createBm25Adapter, createTrgmAdapter, createPgvectorAdapter, 
 // Operator factories for connection filter integration
 createMatchesOperatorFactory, createTrgmOperatorFactories, } from 'graphile-search';
+// Node type registry — @oneOf typed input types for blueprint definitions
+// Gather-phase plugin queries node_type_registry through existing pgService
+export { NodeTypeRegistryPlugin, NodeTypeRegistryPreset, 
+// Legacy exports for backward compatibility
+createBlueprintTypesPlugin, BlueprintTypesPreset, } from './blueprint-types';

package/esm/presets/constructive-preset.js

@@ -1,5 +1,5 @@
 import { ConnectionFilterPreset } from 'graphile-connection-filter';
-import { MinimalPreset, InflektPreset, ConflictDetectorPreset, InflectorLoggerPreset, NoUniqueLookupPreset, EnableAllFilterColumnsPreset, ManyToManyOptInPreset, MetaSchemaPreset, PgTypeMappingsPreset, RequiredInputPreset, } from '../plugins';
+import { MinimalPreset, InflektPreset, ConflictDetectorPreset, InflectorLoggerPreset, NoUniqueLookupPreset, EnableAllFilterColumnsPreset, ManyToManyOptInPreset, MetaSchemaPreset, PgTypeMappingsPreset, RequiredInputPreset, NodeTypeRegistryPreset, } from '../plugins';
 import { UnifiedSearchPreset, createMatchesOperatorFactory, createTrgmOperatorFactories } from 'graphile-search';
 import { GraphilePostgisPreset, createPostgisOperatorFactory } from 'graphile-postgis';
 import { UploadPreset } from 'graphile-upload-plugin';
@@ -77,6 +77,7 @@ export const ConstructivePreset = {
         SqlExpressionValidatorPreset(),
         PgTypeMappingsPreset,
         RequiredInputPreset,
+        NodeTypeRegistryPreset,
     ],
     /**
      * Disable PostGraphile core's condition argument entirely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-settings",
-  "version": "4.10.3",
+  "version": "4.12.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "graphile settings",
   "main": "index.js",
@@ -47,7 +47,7 @@
     "graphile-build-pg": "5.0.0-rc.8",
     "graphile-config": "1.0.0-rc.6",
     "graphile-connection-filter": "^1.1.6",
-    "graphile-postgis": "^2.6.6",
+    "graphile-postgis": "^2.7.0",
     "graphile-search": "^1.3.1",
     "graphile-sql-expression-validator": "^2.5.0",
     "graphile-upload-plugin": "^2.4.4",
@@ -80,5 +80,5 @@
     "constructive",
     "graphql"
   ],
-  "gitHead": "3b3735292589a49601f40645ea7880f584a23b77"
+  "gitHead": "b8d4ae2b36e37e7f3533f858f19ec000febaa04b"
 }

package/plugins/blueprint-types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Node Type Registry Plugin
+ *
+ * Exports the gather-phase plugin and preset for generating @oneOf typed
+ * input types for blueprint definitions from node_type_registry.
+ *
+ * The NodeTypeRegistryPlugin queries node_type_registry through the existing
+ * pgService connection during the gather phase — no separate pool needed.
+ */
+export { NodeTypeRegistryPlugin, NodeTypeRegistryPreset, createBlueprintTypesPlugin, BlueprintTypesPreset, } from './plugin';
+export type { NodeTypeRegistryEntry } from './plugin';

package/plugins/blueprint-types/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlueprintTypesPreset = exports.createBlueprintTypesPlugin = exports.NodeTypeRegistryPreset = exports.NodeTypeRegistryPlugin = void 0;
+/**
+ * Node Type Registry Plugin
+ *
+ * Exports the gather-phase plugin and preset for generating @oneOf typed
+ * input types for blueprint definitions from node_type_registry.
+ *
+ * The NodeTypeRegistryPlugin queries node_type_registry through the existing
+ * pgService connection during the gather phase — no separate pool needed.
+ */
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "NodeTypeRegistryPlugin", { enumerable: true, get: function () { return plugin_1.NodeTypeRegistryPlugin; } });
+Object.defineProperty(exports, "NodeTypeRegistryPreset", { enumerable: true, get: function () { return plugin_1.NodeTypeRegistryPreset; } });
+// Legacy exports for backward compatibility
+Object.defineProperty(exports, "createBlueprintTypesPlugin", { enumerable: true, get: function () { return plugin_1.createBlueprintTypesPlugin; } });
+Object.defineProperty(exports, "BlueprintTypesPreset", { enumerable: true, get: function () { return plugin_1.BlueprintTypesPreset; } });

package/plugins/blueprint-types/json-schema-to-graphql.d.ts

@@ -0,0 +1,64 @@
+/**
+ * JSON Schema to GraphQL Input Field Spec Converter
+ *
+ * Converts JSON Schema objects (from node_type_registry.parameter_schema)
+ * into field spec objects compatible with PostGraphile v5's fieldWithHooks API.
+ *
+ * Handles:
+ * - string, integer, number, boolean primitives
+ * - arrays (items -> GraphQLList)
+ * - enums -> GraphQLEnumType
+ * - required fields -> GraphQLNonNull
+ * - union types (["integer", "string"]) -> JSON scalar fallback
+ */
+import type { GraphQLInputType, GraphQLScalarType, GraphQLNullableType } from 'graphql';
+interface JsonSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    anyOf?: JsonSchema[];
+    description?: string;
+}
+/**
+ * A field spec that mirrors GraphQLInputFieldConfig.
+ */
+export interface FieldSpec {
+    type: GraphQLInputType;
+    description?: string;
+}
+/**
+ * Minimal build interface — only what we need from PostGraphile's Build object.
+ *
+ * Uses permissive constructor signatures to avoid variance issues between
+ * GraphQLNullableType and GraphQLInputType in the graphql-js type hierarchy.
+ */
+export interface BuildLike {
+    graphql: {
+        GraphQLString: GraphQLScalarType;
+        GraphQLInt: GraphQLScalarType;
+        GraphQLFloat: GraphQLScalarType;
+        GraphQLBoolean: GraphQLScalarType;
+        GraphQLNonNull: new (type: any) => GraphQLInputType;
+        GraphQLList: new (type: any) => GraphQLInputType & GraphQLNullableType;
+        GraphQLEnumType: new (config: {
+            name: string;
+            values: Record<string, {
+                value: string;
+            }>;
+        }) => GraphQLInputType & GraphQLNullableType;
+    };
+    getTypeByName: (name: string) => unknown;
+}
+/**
+ * Convert a full JSON Schema (from parameter_schema) to field specs.
+ *
+ * Uses the build object from PostGraphile v5 to access GraphQL types,
+ * avoiding direct graphql imports (which can cause version mismatches).
+ *
+ * @param schema - The JSON Schema object
+ * @param typeName - The name prefix for generated enum types
+ * @param build - The PostGraphile build object
+ * @returns Record of field name -> FieldSpec
+ */
+export declare function jsonSchemaToGraphQLFieldSpecs(schema: JsonSchema, typeName: string, build: BuildLike): Record<string, FieldSpec>;
+export {};

package/plugins/blueprint-types/json-schema-to-graphql.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * JSON Schema to GraphQL Input Field Spec Converter
+ *
+ * Converts JSON Schema objects (from node_type_registry.parameter_schema)
+ * into field spec objects compatible with PostGraphile v5's fieldWithHooks API.
+ *
+ * Handles:
+ * - string, integer, number, boolean primitives
+ * - arrays (items -> GraphQLList)
+ * - enums -> GraphQLEnumType
+ * - required fields -> GraphQLNonNull
+ * - union types (["integer", "string"]) -> JSON scalar fallback
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonSchemaToGraphQLFieldSpecs = jsonSchemaToGraphQLFieldSpecs;
+/**
+ * Convert a JSON Schema type string to a GraphQL scalar type.
+ */
+function jsonTypeToGraphQL(jsonType, graphql, jsonScalar) {
+    if (Array.isArray(jsonType)) {
+        return jsonScalar;
+    }
+    switch (jsonType) {
+        case 'string':
+            return graphql.GraphQLString;
+        case 'integer':
+            return graphql.GraphQLInt;
+        case 'number':
+            return graphql.GraphQLFloat;
+        case 'boolean':
+            return graphql.GraphQLBoolean;
+        case 'object':
+            return jsonScalar;
+        case 'array':
+            return new graphql.GraphQLList(jsonScalar);
+        default:
+            return jsonScalar;
+    }
+}
+/**
+ * Convert a full JSON Schema (from parameter_schema) to field specs.
+ *
+ * Uses the build object from PostGraphile v5 to access GraphQL types,
+ * avoiding direct graphql imports (which can cause version mismatches).
+ *
+ * @param schema - The JSON Schema object
+ * @param typeName - The name prefix for generated enum types
+ * @param build - The PostGraphile build object
+ * @returns Record of field name -> FieldSpec
+ */
+function jsonSchemaToGraphQLFieldSpecs(schema, typeName, build) {
+    const fields = {};
+    const properties = schema.properties;
+    if (!properties) {
+        return fields;
+    }
+    const { graphql } = build;
+    const jsonScalar = (build.getTypeByName('JSON') ?? graphql.GraphQLString);
+    const required = new Set(schema.required ?? []);
+    for (const [propName, prop] of Object.entries(properties)) {
+        let fieldType;
+        if (prop.enum && prop.enum.length > 0) {
+            const values = {};
+            for (const val of prop.enum) {
+                const safeName = val.replace(/[^_a-zA-Z0-9]/g, '_').toUpperCase();
+                values[safeName] = { value: val };
+            }
+            fieldType = new graphql.GraphQLEnumType({
+                name: `${typeName}_${propName}`,
+                values,
+            });
+        }
+        else if (prop.type === 'array' && prop.items) {
+            const innerType = prop.items.type
+                ? jsonTypeToGraphQL(prop.items.type, graphql, jsonScalar)
+                : jsonScalar;
+            fieldType = new graphql.GraphQLList(innerType);
+        }
+        else {
+            fieldType = jsonTypeToGraphQL(prop.type ?? 'string', graphql, jsonScalar);
+        }
+        if (required.has(propName)) {
+            fieldType = new graphql.GraphQLNonNull(fieldType);
+        }
+        fields[propName] = {
+            type: fieldType,
+            description: prop.description ?? undefined,
+        };
+    }
+    return fields;
+}

package/plugins/blueprint-types/plugin.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Node Type Registry Plugin
+ *
+ * Generic PostGraphile v5 plugin that queries node_type_registry at schema
+ * build time through the existing pgService connection (gather phase) and
+ * generates @oneOf typed input types with SuperCase node type names as
+ * discriminant keys.
+ *
+ * Architecture (correct PostGraphile v5 pattern):
+ * 1. `gather` phase: hooks into pgIntrospection_introspection to query
+ *    node_type_registry through the existing pgService (no separate pool —
+ *    uses withPgClientFromPgService like PgIntrospectionPlugin)
+ * 2. `init` hook: registers all input type shells from gathered entries
+ * 3. `GraphQLInputObjectType_fields` hook: populates fields on those types
+ *
+ * Generated type hierarchy:
+ *
+ *   BlueprintDefinitionInput
+ *   +-- tables: [BlueprintTableInput!]
+ *   |   +-- ref: String!
+ *   |   +-- tableName: String!
+ *   |   +-- nodes: [BlueprintNodeInput!]!    <-- @oneOf
+ *   |       +-- shorthand: String
+ *   |       +-- DataId: DataIdParams
+ *   |       +-- DataTimestamps: DataTimestampsParams
+ *   |       +-- AuthzEntityMembership: AuthzEntityMembershipParams
+ *   |       +-- ...
+ *   +-- relations: [BlueprintRelationInput!]  <-- @oneOf
+ *       +-- RelationBelongsTo: RelationBelongsToParams
+ *       +-- ...
+ *
+ * When codegen runs, @oneOf types become discriminated union types:
+ *
+ *   type BlueprintNodeInput =
+ *     | { DataId: DataIdParams }
+ *     | { DataTimestamps: DataTimestampsParams }
+ *     | { AuthzEntityMembership: AuthzEntityMembershipParams }
+ */
+import type { GraphileConfig } from 'graphile-config';
+export interface NodeTypeRegistryEntry {
+    name: string;
+    slug: string;
+    category: string;
+    display_name: string;
+    description: string;
+    parameter_schema: Record<string, unknown>;
+    tags: string[];
+}
+declare global {
+    namespace GraphileBuild {
+        interface ScopeInputObject {
+            isBlueprintOneOf?: boolean;
+            isBlueprintNodeParams?: boolean;
+            isBlueprintTable?: boolean;
+            isBlueprintDefinition?: boolean;
+            isBlueprintRelation?: boolean;
+            blueprintNodeTypeName?: string;
+        }
+        interface BuildInput {
+            nodeTypeRegistryEntries?: NodeTypeRegistryEntry[];
+        }
+    }
+}
+/**
+ * NodeTypeRegistryPlugin
+ *
+ * Gather-phase plugin that queries node_type_registry through the existing
+ * pgService connection, then generates @oneOf typed input types in the
+ * schema phase. No separate PG pool -- uses the same connection PostGraphile
+ * already has (same pattern as PgIntrospectionPlugin / PgEnumTablesPlugin).
+ *
+ * If the table doesn't exist (42P01) or the query fails, the plugin
+ * gracefully skips and no types are registered.
+ */
+export declare const NodeTypeRegistryPlugin: GraphileConfig.Plugin;
+/**
+ * Preset that includes the NodeTypeRegistryPlugin.
+ *
+ * Add to ConstructivePreset.extends[] -- the plugin will automatically
+ * query node_type_registry through the existing pgService connection
+ * during the gather phase. No separate pool, no manual wiring.
+ */
+export declare const NodeTypeRegistryPreset: GraphileConfig.Preset;
+/**
+ * @deprecated Use NodeTypeRegistryPlugin directly. The gather-phase plugin
+ * queries node_type_registry automatically via pgService. This factory is
+ * kept for backward compatibility and tests that pass static entries.
+ */
+export declare function createBlueprintTypesPlugin(nodeTypes: NodeTypeRegistryEntry[]): GraphileConfig.Plugin;
+/**
+ * @deprecated Use NodeTypeRegistryPreset directly. The gather-phase plugin
+ * queries node_type_registry automatically via pgService. This factory is
+ * kept for backward compatibility and tests that pass static entries.
+ */
+export declare function BlueprintTypesPreset(nodeTypes: NodeTypeRegistryEntry[]): GraphileConfig.Preset;

package/plugins/blueprint-types/plugin.js

@@ -0,0 +1,292 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeTypeRegistryPreset = exports.NodeTypeRegistryPlugin = void 0;
+exports.createBlueprintTypesPlugin = createBlueprintTypesPlugin;
+exports.BlueprintTypesPreset = BlueprintTypesPreset;
+const graphile_build_pg_1 = require("graphile-build-pg");
+const json_schema_to_graphql_1 = require("./json-schema-to-graphql");
+// ============================================================================
+// Constants
+// ============================================================================
+const BLUEPRINT_NODE_INPUT = 'BlueprintNodeInput';
+const BLUEPRINT_TABLE_INPUT = 'BlueprintTableInput';
+const BLUEPRINT_RELATION_INPUT = 'BlueprintRelationInput';
+const BLUEPRINT_DEFINITION_INPUT = 'BlueprintDefinitionInput';
+const NODE_TYPE_REGISTRY_QUERY = `
+  SELECT
+    name,
+    slug,
+    category,
+    COALESCE(display_name, name) as display_name,
+    COALESCE(description, '') as description,
+    COALESCE(parameter_schema, '{}'::jsonb) as parameter_schema,
+    COALESCE(tags, '{}') as tags
+  FROM metaschema_public.node_type_registry
+  ORDER BY category, name
+`;
+// ============================================================================
+// Shared schema hooks
+// ============================================================================
+/**
+ * Builds the schema hooks (init + GraphQLInputObjectType_fields) from
+ * a function that retrieves node type entries. Used by both the gather-phase
+ * plugin (reads from build.input) and the static/legacy plugin (closure).
+ */
+function buildSchemaHooks(getNodeTypes) {
+    return {
+        hooks: {
+            init(_, build) {
+                const nodeTypes = getNodeTypes(build);
+                if (nodeTypes.length === 0)
+                    return _;
+                for (const nt of nodeTypes) {
+                    const paramsTypeName = nt.name + 'Params';
+                    build.registerInputObjectType(paramsTypeName, {
+                        isBlueprintNodeParams: true,
+                        blueprintNodeTypeName: nt.name,
+                    }, () => ({
+                        description: nt.description,
+                    }), 'NodeTypeRegistryPlugin: ' + paramsTypeName);
+                }
+                build.registerInputObjectType(BLUEPRINT_NODE_INPUT, { isBlueprintOneOf: true }, () => ({
+                    description: 'A single node in a blueprint definition. Exactly one field must be set. Use the SuperCase node type name as the key with its parameters as the value, or use "shorthand" with just the node type name string.',
+                    isOneOf: true,
+                }), 'NodeTypeRegistryPlugin: BlueprintNodeInput');
+                build.registerInputObjectType(BLUEPRINT_RELATION_INPUT, { isBlueprintOneOf: true, isBlueprintRelation: true }, () => ({
+                    description: 'A relation in a blueprint definition. Exactly one field must be set. Use the SuperCase relation type name as the key.',
+                    isOneOf: true,
+                }), 'NodeTypeRegistryPlugin: BlueprintRelationInput');
+                build.registerInputObjectType(BLUEPRINT_TABLE_INPUT, { isBlueprintTable: true }, () => ({
+                    description: 'A table definition within a blueprint. Specifies the table reference, name, and an array of typed nodes.',
+                }), 'NodeTypeRegistryPlugin: BlueprintTableInput');
+                build.registerInputObjectType(BLUEPRINT_DEFINITION_INPUT, { isBlueprintDefinition: true }, () => ({
+                    description: 'The complete blueprint definition. Contains tables with typed nodes and relations.',
+                }), 'NodeTypeRegistryPlugin: BlueprintDefinitionInput');
+                return _;
+            },
+            GraphQLInputObjectType_fields(fields, build, context) {
+                const nodeTypes = getNodeTypes(build);
+                if (nodeTypes.length === 0)
+                    return fields;
+                const nodeTypesByName = new Map();
+                const relationNodeTypes = [];
+                const nonRelationNodeTypes = [];
+                for (const nt of nodeTypes) {
+                    nodeTypesByName.set(nt.name, nt);
+                    if (nt.category === 'relation') {
+                        relationNodeTypes.push(nt);
+                    }
+                    else {
+                        nonRelationNodeTypes.push(nt);
+                    }
+                }
+                const { extend, graphql: { GraphQLString, GraphQLNonNull, GraphQLList }, } = build;
+                const { fieldWithHooks, scope: { isBlueprintOneOf, isBlueprintNodeParams, isBlueprintTable, isBlueprintDefinition, isBlueprintRelation, blueprintNodeTypeName, }, } = context;
+                // --- Per-node-type params (e.g., DataIdParams) ---
+                if (isBlueprintNodeParams && blueprintNodeTypeName) {
+                    const nt = nodeTypesByName.get(blueprintNodeTypeName);
+                    if (!nt)
+                        return fields;
+                    const schema = nt.parameter_schema;
+                    const fieldSpecs = (0, json_schema_to_graphql_1.jsonSchemaToGraphQLFieldSpecs)(schema, nt.name + 'Params', build);
+                    if (Object.keys(fieldSpecs).length > 0) {
+                        let result = fields;
+                        for (const [fieldName, spec] of Object.entries(fieldSpecs)) {
+                            result = extend(result, {
+                                [fieldName]: fieldWithHooks({ fieldName }, () => spec),
+                            }, 'NodeTypeRegistryPlugin: ' + blueprintNodeTypeName + '.' + fieldName);
+                        }
+                        return result;
+                    }
+                    return extend(fields, {
+                        _: fieldWithHooks({ fieldName: '_' }, () => ({
+                            type: build.graphql.GraphQLBoolean,
+                            description: 'No parameters required. Pass true or omit entirely.',
+                        })),
+                    }, 'NodeTypeRegistryPlugin: ' + blueprintNodeTypeName + '._');
+                }
+                // --- BlueprintNodeInput (@oneOf with all non-relation node types) ---
+                if (isBlueprintOneOf && !isBlueprintRelation) {
+                    let result = fields;
+                    result = extend(result, {
+                        shorthand: fieldWithHooks({ fieldName: 'shorthand' }, () => ({
+                            type: GraphQLString,
+                            description: 'String shorthand: just the SuperCase node type name (e.g., "DataTimestamps"). Use when the node type has no required parameters.',
+                        })),
+                    }, 'NodeTypeRegistryPlugin: BlueprintNodeInput.shorthand');
+                    for (const nt of nonRelationNodeTypes) {
+                        const paramsTypeName = nt.name + 'Params';
+                        const ParamsType = build.getTypeByName(paramsTypeName);
+                        if (!ParamsType)
+                            continue;
+                        result = extend(result, {
+                            [nt.name]: fieldWithHooks({ fieldName: nt.name }, () => ({
+                                type: ParamsType,
+                                description: 'Parameters for ' + nt.name + ' (' + nt.display_name + ')',
+                            })),
+                        }, 'NodeTypeRegistryPlugin: BlueprintNodeInput.' + nt.name);
+                    }
+                    return result;
+                }
+                // --- BlueprintRelationInput (@oneOf with relation node types) ---
+                if (isBlueprintOneOf && isBlueprintRelation) {
+                    let result = fields;
+                    for (const nt of relationNodeTypes) {
+                        const paramsTypeName = nt.name + 'Params';
+                        const ParamsType = build.getTypeByName(paramsTypeName);
+                        if (!ParamsType)
+                            continue;
+                        result = extend(result, {
+                            [nt.name]: fieldWithHooks({ fieldName: nt.name }, () => ({
+                                type: ParamsType,
+                                description: 'Parameters for ' + nt.name + ' (' + nt.display_name + ')',
+                            })),
+                        }, 'NodeTypeRegistryPlugin: BlueprintRelationInput.' + nt.name);
+                    }
+                    return result;
+                }
+                // --- BlueprintTableInput ---
+                if (isBlueprintTable) {
+                    const BlueprintNodeInputType = build.getTypeByName(BLUEPRINT_NODE_INPUT);
+                    return extend(fields, {
+                        ref: fieldWithHooks({ fieldName: 'ref' }, () => ({
+                            type: new GraphQLNonNull(GraphQLString),
+                            description: 'Unique reference key for this table within the blueprint (used for cross-references in relations).',
+                        })),
+                        tableName: fieldWithHooks({ fieldName: 'tableName' }, () => ({
+                            type: new GraphQLNonNull(GraphQLString),
+                            description: 'The PostgreSQL table name to create.',
+                        })),
+                        nodes: fieldWithHooks({ fieldName: 'nodes' }, () => ({
+                            type: BlueprintNodeInputType
+                                ? new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(BlueprintNodeInputType)))
+                                : new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLString))),
+                            description: 'Array of node type entries (data, authz, field behaviors) to apply to this table.',
+                        })),
+                    }, 'NodeTypeRegistryPlugin: BlueprintTableInput fields');
+                }
+                // --- BlueprintDefinitionInput ---
+                if (isBlueprintDefinition) {
+                    const BlueprintTableInputType = build.getTypeByName(BLUEPRINT_TABLE_INPUT);
+                    const BlueprintRelationInputType = build.getTypeByName(BLUEPRINT_RELATION_INPUT);
+                    return extend(fields, {
+                        tables: fieldWithHooks({ fieldName: 'tables' }, () => ({
+                            type: BlueprintTableInputType
+                                ? new GraphQLList(new GraphQLNonNull(BlueprintTableInputType))
+                                : new GraphQLList(GraphQLString),
+                            description: 'Array of table definitions.',
+                        })),
+                        relations: fieldWithHooks({ fieldName: 'relations' }, () => ({
+                            type: BlueprintRelationInputType
+                                ? new GraphQLList(new GraphQLNonNull(BlueprintRelationInputType))
+                                : new GraphQLList(GraphQLString),
+                            description: 'Array of relation definitions.',
+                        })),
+                    }, 'NodeTypeRegistryPlugin: BlueprintDefinitionInput fields');
+                }
+                return fields;
+            },
+        },
+    };
+}
+// ============================================================================
+// Gather-phase plugin (production -- queries DB through existing pgService)
+// ============================================================================
+/**
+ * NodeTypeRegistryPlugin
+ *
+ * Gather-phase plugin that queries node_type_registry through the existing
+ * pgService connection, then generates @oneOf typed input types in the
+ * schema phase. No separate PG pool -- uses the same connection PostGraphile
+ * already has (same pattern as PgIntrospectionPlugin / PgEnumTablesPlugin).
+ *
+ * If the table doesn't exist (42P01) or the query fails, the plugin
+ * gracefully skips and no types are registered.
+ */
+exports.NodeTypeRegistryPlugin = {
+    name: 'NodeTypeRegistryPlugin',
+    version: '1.0.0',
+    description: 'Queries node_type_registry via the existing pgService and generates @oneOf typed input types with SuperCase keys',
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    gather: {
+        namespace: 'nodeTypeRegistry',
+        version: 1,
+        initialState() {
+            return { entries: [] };
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async finalize(info) {
+            info.buildInput.nodeTypeRegistryEntries =
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                info.state.entries ?? [];
+        },
+        hooks: {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            async pgIntrospection_introspection(info, event) {
+                const { serviceName } = event;
+                const pgService = info.resolvedPreset.pgServices?.find((svc) => svc.name === serviceName);
+                if (!pgService)
+                    return;
+                try {
+                    const result = await (0, graphile_build_pg_1.withPgClientFromPgService)(pgService, null, (client) => client.query({ text: NODE_TYPE_REGISTRY_QUERY }));
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const state = info.state;
+                    if (!state.entries) {
+                        state.entries = [];
+                    }
+                    state.entries.push(...result.rows);
+                }
+                catch (error) {
+                    const pgError = error;
+                    if (pgError.code === '42P01') {
+                        // 42P01 = undefined_table -- expected when DB hasn't been migrated
+                        return;
+                    }
+                    // Warn but don't fail the schema build
+                    console.warn('[NodeTypeRegistryPlugin] Failed to query node_type_registry:', pgError.message ?? String(error));
+                }
+            },
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    },
+    schema: buildSchemaHooks((build) => build.input.nodeTypeRegistryEntries ?? []),
+};
+// ============================================================================
+// Preset
+// ============================================================================
+/**
+ * Preset that includes the NodeTypeRegistryPlugin.
+ *
+ * Add to ConstructivePreset.extends[] -- the plugin will automatically
+ * query node_type_registry through the existing pgService connection
+ * during the gather phase. No separate pool, no manual wiring.
+ */
+exports.NodeTypeRegistryPreset = {
+    plugins: [exports.NodeTypeRegistryPlugin],
+};
+// ============================================================================
+// Legacy exports for backward compatibility
+// ============================================================================
+/**
+ * @deprecated Use NodeTypeRegistryPlugin directly. The gather-phase plugin
+ * queries node_type_registry automatically via pgService. This factory is
+ * kept for backward compatibility and tests that pass static entries.
+ */
+function createBlueprintTypesPlugin(nodeTypes) {
+    return {
+        name: 'BlueprintTypesPlugin',
+        version: '1.0.0',
+        description: 'Generates @oneOf typed input types from static node_type_registry entries',
+        schema: buildSchemaHooks(() => nodeTypes),
+    };
+}
+/**
+ * @deprecated Use NodeTypeRegistryPreset directly. The gather-phase plugin
+ * queries node_type_registry automatically via pgService. This factory is
+ * kept for backward compatibility and tests that pass static entries.
+ */
+function BlueprintTypesPreset(nodeTypes) {
+    return {
+        plugins: [createBlueprintTypesPlugin(nodeTypes)],
+    };
+}

package/plugins/index.d.ts

@@ -20,3 +20,5 @@ export { _pgTypeToGqlType, _buildFieldMeta, _cachedTablesMeta } from './meta-sch
 export { RequiredInputPlugin, RequiredInputPreset, } from './required-input-plugin';
 export { createUnifiedSearchPlugin, UnifiedSearchPreset, TsvectorCodecPlugin, TsvectorCodecPreset, createTsvectorCodecPlugin, Bm25CodecPlugin, Bm25CodecPreset, bm25IndexStore, VectorCodecPlugin, VectorCodecPreset, createTsvectorAdapter, createBm25Adapter, createTrgmAdapter, createPgvectorAdapter, createMatchesOperatorFactory, createTrgmOperatorFactories, } from 'graphile-search';
 export type { SearchAdapter, SearchableColumn, UnifiedSearchOptions, UnifiedSearchPresetOptions, TsvectorCodecPluginOptions, Bm25IndexInfo, TsvectorAdapterOptions, Bm25AdapterOptions, TrgmAdapterOptions, PgvectorAdapterOptions, } from 'graphile-search';
+export { NodeTypeRegistryPlugin, NodeTypeRegistryPreset, createBlueprintTypesPlugin, BlueprintTypesPreset, } from './blueprint-types';
+export type { NodeTypeRegistryEntry } from './blueprint-types';

package/plugins/index.js

@@ -5,7 +5,7 @@
  * This module exports all custom plugins (consolidated from graphile-misc-plugins).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTrgmOperatorFactories = exports.createMatchesOperatorFactory = exports.createPgvectorAdapter = exports.createTrgmAdapter = exports.createBm25Adapter = exports.createTsvectorAdapter = exports.VectorCodecPreset = exports.VectorCodecPlugin = exports.bm25IndexStore = exports.Bm25CodecPreset = exports.Bm25CodecPlugin = exports.createTsvectorCodecPlugin = exports.TsvectorCodecPreset = exports.TsvectorCodecPlugin = exports.UnifiedSearchPreset = exports.createUnifiedSearchPlugin = exports.RequiredInputPreset = exports.RequiredInputPlugin = exports._cachedTablesMeta = exports._buildFieldMeta = exports._pgTypeToGqlType = exports.PublicKeySignature = exports.PgTypeMappingsPreset = exports.PgTypeMappingsPlugin = exports.MetaSchemaPreset = exports.MetaSchemaPlugin = exports.NoUniqueLookupPreset = exports.PrimaryKeyOnlyPreset = exports.NoUniqueLookupPlugin = exports.PrimaryKeyOnlyPlugin = exports.createUniqueLookupPlugin = exports.ManyToManyOptInPreset = exports.ManyToManyOptInPlugin = exports.EnableAllFilterColumnsPreset = exports.EnableAllFilterColumnsPlugin = exports.InflectorLoggerPreset = exports.InflectorLoggerPlugin = exports.ConflictDetectorPreset = exports.ConflictDetectorPlugin = exports.CustomInflectorPreset = exports.CustomInflectorPlugin = exports.InflektPreset = exports.InflektPlugin = exports.MinimalPreset = void 0;
+exports.BlueprintTypesPreset = exports.createBlueprintTypesPlugin = exports.NodeTypeRegistryPreset = exports.NodeTypeRegistryPlugin = exports.createTrgmOperatorFactories = exports.createMatchesOperatorFactory = exports.createPgvectorAdapter = exports.createTrgmAdapter = exports.createBm25Adapter = exports.createTsvectorAdapter = exports.VectorCodecPreset = exports.VectorCodecPlugin = exports.bm25IndexStore = exports.Bm25CodecPreset = exports.Bm25CodecPlugin = exports.createTsvectorCodecPlugin = exports.TsvectorCodecPreset = exports.TsvectorCodecPlugin = exports.UnifiedSearchPreset = exports.createUnifiedSearchPlugin = exports.RequiredInputPreset = exports.RequiredInputPlugin = exports._cachedTablesMeta = exports._buildFieldMeta = exports._pgTypeToGqlType = exports.PublicKeySignature = exports.PgTypeMappingsPreset = exports.PgTypeMappingsPlugin = exports.MetaSchemaPreset = exports.MetaSchemaPlugin = exports.NoUniqueLookupPreset = exports.PrimaryKeyOnlyPreset = exports.NoUniqueLookupPlugin = exports.PrimaryKeyOnlyPlugin = exports.createUniqueLookupPlugin = exports.ManyToManyOptInPreset = exports.ManyToManyOptInPlugin = exports.EnableAllFilterColumnsPreset = exports.EnableAllFilterColumnsPlugin = exports.InflectorLoggerPreset = exports.InflectorLoggerPlugin = exports.ConflictDetectorPreset = exports.ConflictDetectorPlugin = exports.CustomInflectorPreset = exports.CustomInflectorPlugin = exports.InflektPreset = exports.InflektPlugin = exports.MinimalPreset = void 0;
 // Minimal preset - PostGraphile without Node/Relay features
 var minimal_preset_1 = require("./minimal-preset");
 Object.defineProperty(exports, "MinimalPreset", { enumerable: true, get: function () { return minimal_preset_1.MinimalPreset; } });
@@ -80,3 +80,11 @@ Object.defineProperty(exports, "createPgvectorAdapter", { enumerable: true, get:
 // Operator factories for connection filter integration
 Object.defineProperty(exports, "createMatchesOperatorFactory", { enumerable: true, get: function () { return graphile_search_1.createMatchesOperatorFactory; } });
 Object.defineProperty(exports, "createTrgmOperatorFactories", { enumerable: true, get: function () { return graphile_search_1.createTrgmOperatorFactories; } });
+// Node type registry — @oneOf typed input types for blueprint definitions
+// Gather-phase plugin queries node_type_registry through existing pgService
+var blueprint_types_1 = require("./blueprint-types");
+Object.defineProperty(exports, "NodeTypeRegistryPlugin", { enumerable: true, get: function () { return blueprint_types_1.NodeTypeRegistryPlugin; } });
+Object.defineProperty(exports, "NodeTypeRegistryPreset", { enumerable: true, get: function () { return blueprint_types_1.NodeTypeRegistryPreset; } });
+// Legacy exports for backward compatibility
+Object.defineProperty(exports, "createBlueprintTypesPlugin", { enumerable: true, get: function () { return blueprint_types_1.createBlueprintTypesPlugin; } });
+Object.defineProperty(exports, "BlueprintTypesPreset", { enumerable: true, get: function () { return blueprint_types_1.BlueprintTypesPreset; } });

package/presets/constructive-preset.js

@@ -80,6 +80,7 @@ exports.ConstructivePreset = {
         (0, graphile_sql_expression_validator_1.SqlExpressionValidatorPreset)(),
         plugins_1.PgTypeMappingsPreset,
         plugins_1.RequiredInputPreset,
+        plugins_1.NodeTypeRegistryPreset,
     ],
     /**
      * Disable PostGraphile core's condition argument entirely.