graphile-settings 3.1.0 → 4.0.0

package/esm/plugins/inflector-logger.js

@@ -0,0 +1,215 @@
+/**
+ * InflectorLoggerPlugin - Logs inflector calls during schema build for debugging.
+ *
+ * This plugin wraps key inflectors to log what fields are being generated and why.
+ * It passes through to the default behavior but logs the inputs and outputs.
+ *
+ * WHEN DO PLUGINS RUN?
+ * Plugins only run at BUILD TIME, not on every request. The schema is built once
+ * and cached. This means logging only happens during schema generation, not during
+ * query execution.
+ *
+ * SOURCE CODE REFERENCES:
+ *
+ * 1. PgRowByUniquePlugin - Creates root Query fields for unique constraints
+ *    (e.g., `userById`, `userByEmail`, `postBySlug`)
+ *    https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRowByUniquePlugin.ts#L42-L257
+ *
+ * 2. PgRelationsPlugin - Creates relationship fields on types for foreign keys
+ *    - Forward relations: `post.author` (from posts.author_id -> users.id)
+ *    - Backward relations: `user.posts` (from users.id <- posts.author_id)
+ *    https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRelationsPlugin.ts#L167-L638
+ *
+ * 3. PgAttributesPlugin - Creates fields for table columns
+ *    Also contains the `_attributeName` inflector that renames `id` to `rowId`
+ *    https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgAttributesPlugin.ts#L289-L298
+ *
+ * 4. PgTablesPlugin - Creates GraphQL types for tables
+ *    Contains the `_schemaPrefix` inflector that adds schema prefixes
+ *    https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgTablesPlugin.ts#L261-L271
+ *
+ * USAGE:
+ * Add InflectorLoggerPlugin to your preset's plugins array.
+ * Set INFLECTOR_LOG=1 environment variable to enable logging.
+ */
+const LOG_ENABLED = process.env.INFLECTOR_LOG === '1';
+function log(category, message, details) {
+    if (!LOG_ENABLED)
+        return;
+    const detailsStr = details ? ` ${JSON.stringify(details)}` : '';
+    console.log(`[Inflector:${category}]${detailsStr} => ${message}`);
+}
+export const InflectorLoggerPlugin = {
+    name: 'InflectorLoggerPlugin',
+    version: '1.0.0',
+    description: 'Logs inflector calls during schema build for debugging',
+    inflection: {
+        replace: {
+            /**
+             * Logs when root Query fields are created for unique constraints.
+             * Source: PgRowByUniquePlugin
+             * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRowByUniquePlugin.ts#L50-L63
+             */
+            rowByUnique(previous, _options, details) {
+                const result = previous(details);
+                const { unique, resource } = details;
+                log('rowByUnique', result, {
+                    resource: resource.name,
+                    uniqueAttributes: unique.attributes,
+                    isPrimary: unique.isPrimary,
+                });
+                return result;
+            },
+            /**
+             * Logs when forward relation fields are created (e.g., post.author).
+             * Source: PgRelationsPlugin
+             * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRelationsPlugin.ts#L228-L230
+             */
+            singleRelation(previous, _options, details) {
+                const result = previous(details);
+                const { codec, relationName, registry } = details;
+                const relation = registry.pgRelations[codec.name]?.[relationName];
+                log('singleRelation', result, {
+                    fromType: codec.name,
+                    relationName,
+                    toType: relation?.remoteResource?.name,
+                    localAttributes: relation?.localAttributes,
+                });
+                return result;
+            },
+            /**
+             * Logs when backward single relation fields are created.
+             * Source: PgRelationsPlugin
+             * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRelationsPlugin.ts#L250-L252
+             */
+            singleRelationBackwards(previous, _options, details) {
+                const result = previous(details);
+                const { codec, relationName, registry } = details;
+                const relation = registry.pgRelations[codec.name]?.[relationName];
+                log('singleRelationBackwards', result, {
+                    fromType: codec.name,
+                    relationName,
+                    toType: relation?.remoteResource?.name,
+                    remoteAttributes: relation?.remoteAttributes,
+                });
+                return result;
+            },
+            /**
+             * Logs when many-relation fields are created (e.g., user.posts).
+             * Source: PgRelationsPlugin
+             * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRelationsPlugin.ts#L268-L270
+             */
+            _manyRelation(previous, _options, details) {
+                const result = previous(details);
+                const { codec, relationName, registry } = details;
+                const relation = registry.pgRelations[codec.name]?.[relationName];
+                log('manyRelation', result, {
+                    fromType: codec.name,
+                    relationName,
+                    toType: relation?.remoteResource?.name,
+                    remoteAttributes: relation?.remoteAttributes,
+                });
+                return result;
+            },
+            /**
+             * Logs when connection fields are created for many relations.
+             * Source: PgRelationsPlugin
+             * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRelationsPlugin.ts#L271-L279
+             */
+            manyRelationConnection(previous, _options, details) {
+                const result = previous(details);
+                const { codec, relationName } = details;
+                log('manyRelationConnection', result, {
+                    fromType: codec.name,
+                    relationName,
+                });
+                return result;
+            },
+            /**
+             * Logs when list fields are created for many relations.
+             * Source: PgRelationsPlugin
+             * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRelationsPlugin.ts#L280-L288
+             */
+            manyRelationList(previous, _options, details) {
+                const result = previous(details);
+                const { codec, relationName } = details;
+                log('manyRelationList', result, {
+                    fromType: codec.name,
+                    relationName,
+                });
+                return result;
+            },
+            /**
+             * Logs when root connection fields are created (e.g., Query.users).
+             * Source: PgAllRowsPlugin
+             */
+            allRowsConnection(previous, _options, resource) {
+                const result = previous(resource);
+                log('allRowsConnection', result, {
+                    resource: resource.name,
+                });
+                return result;
+            },
+            /**
+             * Logs when update mutation fields are created.
+             * Source: PgMutationUpdateDeletePlugin
+             */
+            updateByKeysField(previous, _options, details) {
+                const result = previous(details);
+                const { resource, unique } = details;
+                log('updateByKeysField', result, {
+                    resource: resource.name,
+                    uniqueAttributes: unique.attributes,
+                    isPrimary: unique.isPrimary,
+                });
+                return result;
+            },
+            /**
+             * Logs when delete mutation fields are created.
+             * Source: PgMutationUpdateDeletePlugin
+             */
+            deleteByKeysField(previous, _options, details) {
+                const result = previous(details);
+                const { resource, unique } = details;
+                log('deleteByKeysField', result, {
+                    resource: resource.name,
+                    uniqueAttributes: unique.attributes,
+                    isPrimary: unique.isPrimary,
+                });
+                return result;
+            },
+            /**
+             * Logs when attribute (column) fields are created.
+             * Source: PgAttributesPlugin
+             * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgAttributesPlugin.ts#L289-L298
+             */
+            attribute(previous, _options, details) {
+                const result = previous(details);
+                const { attributeName, codec } = details;
+                log('attribute', result, {
+                    codec: codec.name,
+                    attributeName,
+                });
+                return result;
+            },
+            /**
+             * Logs when table types are created.
+             * Source: PgTablesPlugin
+             */
+            tableType(previous, _options, codec) {
+                const result = previous(codec);
+                log('tableType', result, {
+                    codec: codec.name,
+                });
+                return result;
+            },
+        },
+    },
+};
+/**
+ * Preset that includes the inflector logger plugin.
+ * Use this in your main preset's `extends` array.
+ */
+export const InflectorLoggerPreset = {
+    plugins: [InflectorLoggerPlugin],
+};

package/esm/plugins/many-to-many-preset.d.ts

@@ -0,0 +1,62 @@
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * Many-to-Many Preset with OPT-IN behavior (disabled by default).
+ *
+ * WHY THIS EXISTS:
+ * The default @graphile-contrib/pg-many-to-many plugin adds many-to-many connection
+ * fields to EVERY junction table automatically. This can bloat the API with fields
+ * that may never be used.
+ *
+ * OUR FIX:
+ * We override the default behavior to be OPT-IN instead of OPT-OUT:
+ * - By default, NO many-to-many fields are generated
+ * - To enable for a specific junction table, use: @behavior +manyToMany
+ *
+ * USAGE:
+ * To enable many-to-many for a specific junction table, add a smart comment:
+ *
+ * ```sql
+ * -- Enable many-to-many through this junction table
+ * COMMENT ON TABLE post_tags IS E'@behavior +manyToMany';
+ *
+ * -- Or enable on a specific constraint
+ * COMMENT ON CONSTRAINT post_tags_tag_id_fkey ON post_tags IS E'@behavior +manyToMany';
+ * ```
+ *
+ * SOURCE CODE REFERENCE:
+ * The many-to-many plugin uses the behavior system to control field generation:
+ * https://github.com/graphile-contrib/pg-many-to-many/blob/v2.0.0-rc.1/src/PgManyToManyRelationPlugin.ts#L478-L503
+ *
+ * The plugin defines these behaviors:
+ * - `manyToMany` - Controls whether many-to-many fields are generated
+ * - `connection` - Controls whether connection fields are generated
+ * - `list` - Controls whether list fields are generated
+ *
+ * By default, the plugin's entityBehavior for pgManyToMany includes:
+ * `["manyToMany", "connection", "list", behavior]`
+ *
+ * We override this to be `-manyToMany` by default, requiring explicit opt-in.
+ */
+/**
+ * Plugin that makes many-to-many fields opt-in by default.
+ *
+ * This overrides the default behavior from @graphile-contrib/pg-many-to-many
+ * to require explicit `@behavior +manyToMany` smart tags.
+ */
+export declare const ManyToManyOptInPlugin: GraphileConfig.Plugin;
+/**
+ * Preset that includes the many-to-many plugin with opt-in behavior.
+ *
+ * Use this in your main preset's `extends` array:
+ * ```typescript
+ * const preset: GraphileConfig.Preset = {
+ *   extends: [
+ *     MinimalPreset,
+ *     ManyToManyOptInPreset,
+ *     // ... other presets
+ *   ],
+ * };
+ * ```
+ */
+export declare const ManyToManyOptInPreset: GraphileConfig.Preset;
+export default ManyToManyOptInPreset;

package/esm/plugins/many-to-many-preset.js

@@ -0,0 +1,86 @@
+import { PgManyToManyPreset } from '@graphile-contrib/pg-many-to-many';
+/**
+ * Many-to-Many Preset with OPT-IN behavior (disabled by default).
+ *
+ * WHY THIS EXISTS:
+ * The default @graphile-contrib/pg-many-to-many plugin adds many-to-many connection
+ * fields to EVERY junction table automatically. This can bloat the API with fields
+ * that may never be used.
+ *
+ * OUR FIX:
+ * We override the default behavior to be OPT-IN instead of OPT-OUT:
+ * - By default, NO many-to-many fields are generated
+ * - To enable for a specific junction table, use: @behavior +manyToMany
+ *
+ * USAGE:
+ * To enable many-to-many for a specific junction table, add a smart comment:
+ *
+ * ```sql
+ * -- Enable many-to-many through this junction table
+ * COMMENT ON TABLE post_tags IS E'@behavior +manyToMany';
+ *
+ * -- Or enable on a specific constraint
+ * COMMENT ON CONSTRAINT post_tags_tag_id_fkey ON post_tags IS E'@behavior +manyToMany';
+ * ```
+ *
+ * SOURCE CODE REFERENCE:
+ * The many-to-many plugin uses the behavior system to control field generation:
+ * https://github.com/graphile-contrib/pg-many-to-many/blob/v2.0.0-rc.1/src/PgManyToManyRelationPlugin.ts#L478-L503
+ *
+ * The plugin defines these behaviors:
+ * - `manyToMany` - Controls whether many-to-many fields are generated
+ * - `connection` - Controls whether connection fields are generated
+ * - `list` - Controls whether list fields are generated
+ *
+ * By default, the plugin's entityBehavior for pgManyToMany includes:
+ * `["manyToMany", "connection", "list", behavior]`
+ *
+ * We override this to be `-manyToMany` by default, requiring explicit opt-in.
+ */
+/**
+ * Plugin that makes many-to-many fields opt-in by default.
+ *
+ * This overrides the default behavior from @graphile-contrib/pg-many-to-many
+ * to require explicit `@behavior +manyToMany` smart tags.
+ */
+export const ManyToManyOptInPlugin = {
+    name: 'ManyToManyOptInPlugin',
+    version: '1.0.0',
+    description: 'Makes many-to-many fields opt-in by default (disabled unless explicitly enabled)',
+    schema: {
+        entityBehavior: {
+            pgManyToMany: {
+                // Override the default behavior to be opt-out (disabled by default)
+                // The 'inferred' phase runs before 'override', so we use 'inferred'
+                // to set the default before any smart tags are processed.
+                inferred: {
+                    provides: ['manyToManyOptIn'],
+                    before: ['default'],
+                    callback(behavior) {
+                        // Default to disabled - require explicit @behavior +manyToMany
+                        return ['-manyToMany', behavior];
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * Preset that includes the many-to-many plugin with opt-in behavior.
+ *
+ * Use this in your main preset's `extends` array:
+ * ```typescript
+ * const preset: GraphileConfig.Preset = {
+ *   extends: [
+ *     MinimalPreset,
+ *     ManyToManyOptInPreset,
+ *     // ... other presets
+ *   ],
+ * };
+ * ```
+ */
+export const ManyToManyOptInPreset = {
+    extends: [PgManyToManyPreset],
+    plugins: [ManyToManyOptInPlugin],
+};
+export default ManyToManyOptInPreset;

package/esm/plugins/meta-schema/cache.d.ts

@@ -0,0 +1,4 @@
+import type { TableMeta } from './types';
+export declare let cachedTablesMeta: TableMeta[];
+export declare function getCachedTablesMeta(): TableMeta[];
+export declare function setCachedTablesMeta(tablesMeta: TableMeta[]): void;

package/esm/plugins/meta-schema/cache.js

@@ -0,0 +1,7 @@
+export let cachedTablesMeta = [];
+export function getCachedTablesMeta() {
+    return cachedTablesMeta;
+}
+export function setCachedTablesMeta(tablesMeta) {
+    cachedTablesMeta = tablesMeta;
+}

package/esm/plugins/meta-schema/constraint-meta-builders.d.ts

@@ -0,0 +1,13 @@
+import { type BuildContext } from './table-meta-context';
+import type { ForeignKeyConstraintMeta, PgAttribute, PgCodec, PgRelation, PgUnique, PrimaryKeyConstraintMeta, UniqueConstraintMeta } from './types';
+export declare function buildForeignKeyConstraint(constraintName: string, localCodec: PgCodec, localAttributes: Record<string, PgAttribute>, localAttributeNames: string[], remoteCodec: PgCodec | undefined, remoteAttributes: Record<string, PgAttribute>, remoteAttributeNames: string[], context: BuildContext): ForeignKeyConstraintMeta;
+export declare function buildIndexes(codec: PgCodec, attributes: Record<string, PgAttribute>, uniques: PgUnique[], context: BuildContext): {
+    name: string;
+    isUnique: boolean;
+    isPrimary: boolean;
+    columns: string[];
+    fields: import("./types").FieldMeta[];
+}[];
+export declare function buildPrimaryKey(codec: PgCodec, attributes: Record<string, PgAttribute>, uniques: PgUnique[], context: BuildContext): PrimaryKeyConstraintMeta | null;
+export declare function buildUniqueConstraints(codec: PgCodec, attributes: Record<string, PgAttribute>, uniques: PgUnique[], context: BuildContext): UniqueConstraintMeta[];
+export declare function buildForeignKeyConstraints(codec: PgCodec, attributes: Record<string, PgAttribute>, relations: Record<string, PgRelation>, context: BuildContext): ForeignKeyConstraintMeta[];

package/esm/plugins/meta-schema/constraint-meta-builders.js

@@ -0,0 +1,51 @@
+import { buildFieldMeta } from './type-mappings';
+import { buildFieldList } from './table-meta-context';
+export function buildForeignKeyConstraint(constraintName, localCodec, localAttributes, localAttributeNames, remoteCodec, remoteAttributes, remoteAttributeNames, context) {
+    const referencedTable = remoteCodec?.name || 'unknown';
+    const referencedFields = remoteAttributeNames.map((attrName) => remoteCodec ? context.inflectAttr(attrName, remoteCodec) : attrName);
+    return {
+        name: constraintName,
+        fields: buildFieldList(localAttributeNames, localCodec, localAttributes, context),
+        referencedTable,
+        referencedFields,
+        refFields: remoteAttributeNames.map((attrName) => buildFieldMeta(remoteCodec ? context.inflectAttr(attrName, remoteCodec) : attrName, remoteAttributes[attrName], context.build)),
+        refTable: { name: referencedTable },
+    };
+}
+export function buildIndexes(codec, attributes, uniques, context) {
+    return uniques.map((unique) => ({
+        name: unique.tags?.name || `${codec.name}_${unique.attributes.join('_')}_idx`,
+        isUnique: true,
+        isPrimary: !!unique.isPrimary,
+        columns: unique.attributes.map((attrName) => context.inflectAttr(attrName, codec)),
+        fields: buildFieldList(unique.attributes, codec, attributes, context),
+    }));
+}
+export function buildPrimaryKey(codec, attributes, uniques, context) {
+    const primaryUnique = uniques.find((unique) => unique.isPrimary);
+    if (!primaryUnique)
+        return null;
+    return {
+        name: primaryUnique.tags?.name || `${codec.name}_pkey`,
+        fields: buildFieldList(primaryUnique.attributes, codec, attributes, context),
+    };
+}
+export function buildUniqueConstraints(codec, attributes, uniques, context) {
+    return uniques
+        .filter((unique) => !unique.isPrimary)
+        .map((unique) => ({
+        name: unique.tags?.name || `${codec.name}_${unique.attributes.join('_')}_key`,
+        fields: buildFieldList(unique.attributes, codec, attributes, context),
+    }));
+}
+export function buildForeignKeyConstraints(codec, attributes, relations, context) {
+    const constraints = [];
+    for (const [relationName, relation] of Object.entries(relations)) {
+        if (relation.isReferencee !== false)
+            continue;
+        const remoteCodec = relation.remoteResource?.codec;
+        const remoteAttributes = remoteCodec?.attributes || {};
+        constraints.push(buildForeignKeyConstraint(relationName, codec, attributes, relation.localAttributes || [], remoteCodec, remoteAttributes, relation.remoteAttributes || [], context));
+    }
+    return constraints;
+}

package/esm/plugins/meta-schema/graphql-meta-field.d.ts

@@ -0,0 +1,4 @@
+import type { TableMeta } from './types';
+type FieldMap = Record<string, unknown>;
+export declare function extendQueryWithMetaField(fields: FieldMap, tablesMeta: TableMeta[]): FieldMap;
+export {};

package/esm/plugins/meta-schema/graphql-meta-field.js

@@ -0,0 +1,201 @@
+import { GraphQLBoolean, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLString, } from 'graphql';
+function nn(type) {
+    return new GraphQLNonNull(type);
+}
+function nnList(type) {
+    return nn(new GraphQLList(nn(type)));
+}
+function createMetaSchemaType() {
+    const MetaTypeType = new GraphQLObjectType({
+        name: 'MetaType',
+        description: 'Information about a PostgreSQL type',
+        fields: () => ({
+            pgType: { type: nn(GraphQLString) },
+            gqlType: { type: nn(GraphQLString) },
+            isArray: { type: nn(GraphQLBoolean) },
+            isNotNull: { type: GraphQLBoolean },
+            hasDefault: { type: GraphQLBoolean },
+        }),
+    });
+    const MetaFieldType = new GraphQLObjectType({
+        name: 'MetaField',
+        description: 'Information about a table field/column',
+        fields: () => ({
+            name: { type: nn(GraphQLString) },
+            type: { type: nn(MetaTypeType) },
+            isNotNull: { type: nn(GraphQLBoolean) },
+            hasDefault: { type: nn(GraphQLBoolean) },
+        }),
+    });
+    const MetaIndexType = new GraphQLObjectType({
+        name: 'MetaIndex',
+        description: 'Information about a database index',
+        fields: () => ({
+            name: { type: nn(GraphQLString) },
+            isUnique: { type: nn(GraphQLBoolean) },
+            isPrimary: { type: nn(GraphQLBoolean) },
+            columns: { type: nnList(GraphQLString) },
+            fields: { type: new GraphQLList(nn(MetaFieldType)) },
+        }),
+    });
+    const MetaPrimaryKeyConstraintType = new GraphQLObjectType({
+        name: 'MetaPrimaryKeyConstraint',
+        description: 'Information about a primary key constraint',
+        fields: () => ({
+            name: { type: nn(GraphQLString) },
+            fields: { type: nnList(MetaFieldType) },
+        }),
+    });
+    const MetaUniqueConstraintType = new GraphQLObjectType({
+        name: 'MetaUniqueConstraint',
+        description: 'Information about a unique constraint',
+        fields: () => ({
+            name: { type: nn(GraphQLString) },
+            fields: { type: nnList(MetaFieldType) },
+        }),
+    });
+    const MetaRefTableType = new GraphQLObjectType({
+        name: 'MetaRefTable',
+        description: 'Reference to a related table',
+        fields: () => ({
+            name: { type: nn(GraphQLString) },
+        }),
+    });
+    const MetaForeignKeyConstraintType = new GraphQLObjectType({
+        name: 'MetaForeignKeyConstraint',
+        description: 'Information about a foreign key constraint',
+        fields: () => ({
+            name: { type: nn(GraphQLString) },
+            fields: { type: nnList(MetaFieldType) },
+            referencedTable: { type: nn(GraphQLString) },
+            referencedFields: { type: nnList(GraphQLString) },
+            refFields: { type: new GraphQLList(nn(MetaFieldType)) },
+            refTable: { type: MetaRefTableType },
+        }),
+    });
+    const MetaConstraintsType = new GraphQLObjectType({
+        name: 'MetaConstraints',
+        description: 'Table constraints',
+        fields: () => ({
+            primaryKey: { type: MetaPrimaryKeyConstraintType },
+            unique: { type: nnList(MetaUniqueConstraintType) },
+            foreignKey: { type: nnList(MetaForeignKeyConstraintType) },
+        }),
+    });
+    const MetaInflectionType = new GraphQLObjectType({
+        name: 'MetaInflection',
+        description: 'Table inflection names',
+        fields: () => ({
+            tableType: { type: nn(GraphQLString) },
+            allRows: { type: nn(GraphQLString) },
+            connection: { type: nn(GraphQLString) },
+            edge: { type: nn(GraphQLString) },
+            filterType: { type: GraphQLString },
+            orderByType: { type: nn(GraphQLString) },
+            conditionType: { type: nn(GraphQLString) },
+            patchType: { type: GraphQLString },
+            createInputType: { type: nn(GraphQLString) },
+            createPayloadType: { type: nn(GraphQLString) },
+            updatePayloadType: { type: GraphQLString },
+            deletePayloadType: { type: nn(GraphQLString) },
+        }),
+    });
+    const MetaQueryType = new GraphQLObjectType({
+        name: 'MetaQuery',
+        description: 'Table query/mutation names',
+        fields: () => ({
+            all: { type: nn(GraphQLString) },
+            one: { type: GraphQLString },
+            create: { type: GraphQLString },
+            update: { type: GraphQLString },
+            delete: { type: GraphQLString },
+        }),
+    });
+    const MetaBelongsToRelationType = new GraphQLObjectType({
+        name: 'MetaBelongsToRelation',
+        description: 'A belongs-to (forward FK) relation',
+        fields: () => ({
+            fieldName: { type: GraphQLString },
+            isUnique: { type: nn(GraphQLBoolean) },
+            type: { type: GraphQLString },
+            keys: { type: nnList(MetaFieldType) },
+            references: { type: nn(MetaRefTableType) },
+        }),
+    });
+    const MetaHasRelationType = new GraphQLObjectType({
+        name: 'MetaHasRelation',
+        description: 'A has-one or has-many (reverse FK) relation',
+        fields: () => ({
+            fieldName: { type: GraphQLString },
+            isUnique: { type: nn(GraphQLBoolean) },
+            type: { type: GraphQLString },
+            keys: { type: nnList(MetaFieldType) },
+            referencedBy: { type: nn(MetaRefTableType) },
+        }),
+    });
+    const MetaManyToManyRelationType = new GraphQLObjectType({
+        name: 'MetaManyToManyRelation',
+        description: 'A many-to-many relation via junction table',
+        fields: () => ({
+            fieldName: { type: GraphQLString },
+            type: { type: GraphQLString },
+            junctionTable: { type: nn(MetaRefTableType) },
+            junctionLeftConstraint: { type: nn(MetaForeignKeyConstraintType) },
+            junctionLeftKeyAttributes: { type: nnList(MetaFieldType) },
+            junctionRightConstraint: { type: nn(MetaForeignKeyConstraintType) },
+            junctionRightKeyAttributes: { type: nnList(MetaFieldType) },
+            leftKeyAttributes: { type: nnList(MetaFieldType) },
+            rightKeyAttributes: { type: nnList(MetaFieldType) },
+            rightTable: { type: nn(MetaRefTableType) },
+        }),
+    });
+    const MetaRelationsType = new GraphQLObjectType({
+        name: 'MetaRelations',
+        description: 'Table relations',
+        fields: () => ({
+            belongsTo: { type: nnList(MetaBelongsToRelationType) },
+            has: { type: nnList(MetaHasRelationType) },
+            hasOne: { type: nnList(MetaHasRelationType) },
+            hasMany: { type: nnList(MetaHasRelationType) },
+            manyToMany: { type: nnList(MetaManyToManyRelationType) },
+        }),
+    });
+    const MetaTableType = new GraphQLObjectType({
+        name: 'MetaTable',
+        description: 'Information about a database table',
+        fields: () => ({
+            name: { type: nn(GraphQLString) },
+            schemaName: { type: nn(GraphQLString) },
+            fields: { type: nnList(MetaFieldType) },
+            indexes: { type: nnList(MetaIndexType) },
+            constraints: { type: nn(MetaConstraintsType) },
+            foreignKeyConstraints: { type: nnList(MetaForeignKeyConstraintType) },
+            primaryKeyConstraints: { type: nnList(MetaPrimaryKeyConstraintType) },
+            uniqueConstraints: { type: nnList(MetaUniqueConstraintType) },
+            relations: { type: nn(MetaRelationsType) },
+            inflection: { type: nn(MetaInflectionType) },
+            query: { type: nn(MetaQueryType) },
+        }),
+    });
+    return new GraphQLObjectType({
+        name: 'MetaSchema',
+        description: 'Root meta schema type',
+        fields: () => ({
+            tables: { type: nnList(MetaTableType) },
+        }),
+    });
+}
+export function extendQueryWithMetaField(fields, tablesMeta) {
+    const metaSchemaType = createMetaSchemaType();
+    const metaField = {
+        type: metaSchemaType,
+        description: 'Metadata about the database schema, including tables, fields, indexes, and constraints. Useful for code generation tools.',
+        resolve() {
+            return { tables: tablesMeta };
+        },
+    };
+    return {
+        ...fields,
+        _meta: metaField,
+    };
+}

package/esm/plugins/meta-schema/inflection-utils.d.ts

@@ -0,0 +1,4 @@
+import type { MetaInflection, PgCodec } from './types';
+export declare function safeInflection<T>(fn: () => T, fallback: T): T;
+export declare function createAttributeInflector(inflection: MetaInflection): (attrName: string, codec: PgCodec) => string;
+export declare function fallbackTableType(codecName: string): string;

package/esm/plugins/meta-schema/inflection-utils.js

@@ -0,0 +1,20 @@
+export function safeInflection(fn, fallback) {
+    try {
+        return fn() ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export function createAttributeInflector(inflection) {
+    return (attrName, codec) => {
+        const attributeName = safeInflection(() => inflection._attributeName?.({ attributeName: attrName, codec }), attrName);
+        return safeInflection(() => inflection.camelCase?.(attributeName), attributeName);
+    };
+}
+export function fallbackTableType(codecName) {
+    return codecName
+        .replace(/_/g, ' ')
+        .replace(/\b\w/g, (char) => char.toUpperCase())
+        .replace(/ /g, '');
+}