graphile-settings 4.1.0 → 4.3.0

package/esm/plugins/meta-schema.js

@@ -1,20 +0,0 @@
-/**
- * PostGraphile v5 Meta Schema Plugin
- *
- * Exposes a `_meta` GraphQL query that provides metadata about tables, fields,
- * constraints, indexes, and relations for code generation tooling.
- */
-import { cachedTablesMeta } from './meta-schema/cache';
-import { MetaSchemaPlugin } from './meta-schema/plugin';
-import { buildFieldMeta, pgTypeToGqlType } from './meta-schema/type-mappings';
-export { MetaSchemaPlugin };
-export const MetaSchemaPreset = {
-    plugins: [MetaSchemaPlugin],
-};
-/** @internal Exported for testing only */
-export { pgTypeToGqlType as _pgTypeToGqlType };
-/** @internal Exported for testing only */
-export { buildFieldMeta as _buildFieldMeta };
-/** @internal Exported for testing only */
-export { cachedTablesMeta as _cachedTablesMeta };
-export default MetaSchemaPlugin;

package/esm/plugins/minimal-preset.d.ts

@@ -1,7 +0,0 @@
-import type { GraphileConfig } from 'graphile-config';
-/**
- * Minimal preset with all the PostgreSQL functionality but without Node/Relay features.
- * This keeps `id` columns as `id` (no renaming to `rowId`).
- */
-export declare const MinimalPreset: GraphileConfig.Preset;
-export default MinimalPreset;

package/esm/plugins/minimal-preset.js

@@ -1,42 +0,0 @@
-import { defaultPreset as graphileBuildPreset } from 'graphile-build';
-import { defaultPreset as graphileBuildPgPreset } from 'graphile-build-pg';
-/**
- * Minimal PostGraphile v5 preset without Node/Relay features.
- *
- * This preset builds a clean GraphQL API from PostgreSQL without:
- * - Global Node ID (Relay spec) - so `id` columns stay as `id`
- * - Schema prefixing for naming conflicts
- *
- * We use the default presets from graphile-build and graphile-build-pg
- * and disable all Node-related plugins.
- */
-/**
- * List of Node/Relay-related plugins to disable.
- * These implement the Relay Global Object Identification spec which:
- * - Adds a global `id` field to types
- * - Renames actual `id` columns to `rowId`
- * - Adds Node interface and nodeId lookups
- *
- * Since we use UUIDs, we don't need any of this.
- */
-const NODE_PLUGINS_TO_DISABLE = [
-    // Core Node plugins from graphile-build
-    'NodePlugin',
-    'AddNodeInterfaceToSuitableTypesPlugin',
-    'NodeIdCodecBase64JSONPlugin',
-    'NodeIdCodecPipeStringPlugin',
-    'RegisterQueryNodePlugin',
-    'NodeAccessorPlugin',
-    // PG-specific Node plugins from graphile-build-pg
-    'PgNodeIdAttributesPlugin',
-    'PgTableNodePlugin',
-];
-/**
- * Minimal preset with all the PostgreSQL functionality but without Node/Relay features.
- * This keeps `id` columns as `id` (no renaming to `rowId`).
- */
-export const MinimalPreset = {
-    extends: [graphileBuildPreset, graphileBuildPgPreset],
-    disablePlugins: NODE_PLUGINS_TO_DISABLE,
-};
-export default MinimalPreset;

package/esm/plugins/pg-type-mappings.d.ts

@@ -1,41 +0,0 @@
-import type { GraphileConfig } from 'graphile-config';
-/**
- * Type mapping configuration for custom PostgreSQL types.
- */
-export interface TypeMapping {
-    /** PostgreSQL type name */
-    name: string;
-    /** PostgreSQL schema/namespace name */
-    namespaceName: string;
-    /** GraphQL type to map to */
-    type: 'String';
-}
-/**
- * Plugin that maps custom PostgreSQL types to GraphQL scalar types.
- *
- * This is useful for domain types or composite types that should be
- * represented as simple scalars (String, JSON) in the GraphQL API.
- *
- * For example, if you have:
- *   CREATE DOMAIN email AS text;
- *   CREATE TYPE url AS (value text);
- *
- * This plugin will map them to GraphQL String type instead of creating
- * complex object types.
- *
- * The plugin handles both:
- * 1. Domain types (simple aliases) - maps directly to the target scalar
- * 2. Composite types - extracts the first field's value when converting from PG
- */
-export declare const PgTypeMappingsPlugin: GraphileConfig.Plugin;
-/**
- * Preset that includes the PG type mappings plugin.
- *
- * This preset maps common custom PostgreSQL types to GraphQL scalars:
- * - email -> String
- * - hostname -> String
- * - url -> String
- * - origin -> String
- */
-export declare const PgTypeMappingsPreset: GraphileConfig.Preset;
-export default PgTypeMappingsPlugin;

package/esm/plugins/pg-type-mappings.js

@@ -1,122 +0,0 @@
-import { GraphQLString } from 'graphql';
-import sql from 'pg-sql2';
-/**
- * Default type mappings for common custom PostgreSQL types.
- * These are typically domain types or composite types that should be
- * represented as simple scalars in GraphQL.
- */
-const DEFAULT_MAPPINGS = [
-    { name: 'email', namespaceName: 'public', type: 'String' },
-    { name: 'hostname', namespaceName: 'public', type: 'String' },
-    { name: 'origin', namespaceName: 'public', type: 'String' },
-    { name: 'url', namespaceName: 'public', type: 'String' },
-];
-/**
- * Plugin that maps custom PostgreSQL types to GraphQL scalar types.
- *
- * This is useful for domain types or composite types that should be
- * represented as simple scalars (String, JSON) in the GraphQL API.
- *
- * For example, if you have:
- *   CREATE DOMAIN email AS text;
- *   CREATE TYPE url AS (value text);
- *
- * This plugin will map them to GraphQL String type instead of creating
- * complex object types.
- *
- * The plugin handles both:
- * 1. Domain types (simple aliases) - maps directly to the target scalar
- * 2. Composite types - extracts the first field's value when converting from PG
- */
-export const PgTypeMappingsPlugin = {
-    name: 'PgTypeMappingsPlugin',
-    version: '1.0.0',
-    gather: {
-        hooks: {
-            async pgCodecs_findPgCodec(info, event) {
-                if (event.pgCodec) {
-                    return;
-                }
-                const { pgType: type, serviceName } = event;
-                // Find the namespace for this type
-                const namespace = await info.helpers.pgIntrospection.getNamespace(serviceName, type.typnamespace);
-                if (!namespace) {
-                    return;
-                }
-                // Check if this type matches any of our mappings
-                const mapping = DEFAULT_MAPPINGS.find(m => m.name === type.typname && m.namespaceName === namespace.nspname);
-                if (!mapping) {
-                    return;
-                }
-                // Create a codec for this type
-                // For composite types, the fromPg function extracts the first field's value
-                // For domain types, it just passes through the value
-                event.pgCodec = {
-                    name: type.typname,
-                    sqlType: sql.identifier(namespace.nspname, type.typname),
-                    fromPg: (value) => {
-                        if (value == null) {
-                            return null;
-                        }
-                        // If it's already a scalar, return it
-                        if (typeof value !== 'object' || Array.isArray(value)) {
-                            return value;
-                        }
-                        // For composite types, extract the first field's value
-                        const obj = value;
-                        const keys = Object.keys(obj);
-                        if (keys.length > 0) {
-                            return obj[keys[0]];
-                        }
-                        return value;
-                    },
-                    toPg: (value) => value,
-                    attributes: undefined,
-                    executor: null,
-                    extensions: {
-                        oid: type._id,
-                        pg: {
-                            serviceName,
-                            schemaName: namespace.nspname,
-                            name: type.typname,
-                        },
-                        tags: {
-                            // Mark this as a custom mapped type
-                            pgTypeMappings: mapping.type,
-                        },
-                    },
-                };
-            },
-        },
-    },
-    schema: {
-        hooks: {
-            init(_, build) {
-                const { setGraphQLTypeForPgCodec } = build;
-                // Map our custom codecs to GraphQL types
-                for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
-                    const mappingType = codec.extensions?.tags?.pgTypeMappings;
-                    if (mappingType) {
-                        const gqlTypeName = GraphQLString.name;
-                        setGraphQLTypeForPgCodec(codec, 'input', gqlTypeName);
-                        setGraphQLTypeForPgCodec(codec, 'output', gqlTypeName);
-                    }
-                }
-                return _;
-            },
-        },
-    },
-};
-/**
- * Preset that includes the PG type mappings plugin.
- *
- * This preset maps common custom PostgreSQL types to GraphQL scalars:
- * - email -> String
- * - hostname -> String
- * - url -> String
- * - origin -> String
- */
-export const PgTypeMappingsPreset = {
-    plugins: [PgTypeMappingsPlugin],
-};
-export default PgTypeMappingsPlugin;

package/esm/plugins/primary-key-only.d.ts

@@ -1,96 +0,0 @@
-import type { GraphileConfig } from 'graphile-config';
-/**
- * Configuration options for unique lookup behavior.
- */
-export interface UniqueLookupOptions {
-    /**
-     * If true, disables ALL unique constraint lookups including primary keys.
-     * Users must use collection queries with filters instead.
-     * Default: false (primary key lookups are kept)
-     */
-    disableAllUniqueLookups?: boolean;
-}
-/**
- * PrimaryKeyOnlyPlugin - Disables non-primary-key unique constraint lookups for
- * BOTH queries AND mutations.
- *
- * WHY THIS EXISTS:
- * PostGraphile v5 creates fields for EVERY unique constraint on a table:
- *
- * QUERIES (PgRowByUniquePlugin):
- * - `user(id)`, `userByEmail(email)`, `userByUsername(username)`
- *
- * MUTATIONS (PgMutationUpdateDeletePlugin):
- * - `updateUser`, `updateUserByEmail`, `updateUserByUsername`
- * - `deleteUser`, `deleteUserByEmail`, `deleteUserByUsername`
- *
- * For code generation (React Query, etc.), this creates unnecessary complexity.
- * The same operations can be done using the primary key lookup or filters.
- * Standardizing on primary keys reduces the API surface and generated code.
- *
- * SOURCE CODE REFERENCES:
- *
- * 1. Query fields (PgRowByUniquePlugin):
- * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRowByUniquePlugin.ts#L42-L257
- *
- * The behavior check for queries:
- * ```typescript
- * const fieldBehaviorScope = "query:resource:single";
- * if (!build.behavior.pgResourceUniqueMatches([resource, unique], fieldBehaviorScope)) {
- *   return memo;  // Skip this field
- * }
- * ```
- *
- * 2. Mutation fields (PgMutationUpdateDeletePlugin):
- * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgMutationUpdateDeletePlugin.ts
- *
- * The behavior check for mutations:
- * ```typescript
- * const constraintMode = `constraint:${mode}`;  // "constraint:resource:update" or "constraint:resource:delete"
- * ...resource.uniques.filter((unique) => {
- *   return build.behavior.pgResourceUniqueMatches([resource, unique], constraintMode);
- * })
- * ```
- *
- * OUR FIX:
- * We use the behavior system's OVERRIDE phase (not inferred) to disable these behaviors.
- * The override phase runs AFTER the behavior multiplication/preferences system processes
- * behaviors, giving us the final say on what's enabled/disabled.
- *
- * Behaviors we control:
- * - `-single` - Disables query lookups (userByEmail, etc.)
- * - `-constraint:resource:update` - Disables updateByX mutations
- * - `-constraint:resource:delete` - Disables deleteByX mutations
- *
- * CONFIGURATION OPTIONS:
- *
- * 1. `disableAllUniqueLookups: false` (default - PrimaryKeyOnlyPreset):
- *    - Primary key: query lookup + mutations enabled
- *    - Non-primary-key: everything disabled
- *    Result: `user(id)`, `updateUser`, `deleteUser` only
- *
- * 2. `disableAllUniqueLookups: true` (NoUniqueLookupPreset):
- *    - Primary key: query lookup DISABLED, mutations ENABLED
- *    - Non-primary-key: everything disabled
- *    Result: No query lookups (use filters), but `updateUser`, `deleteUser` still work
- */
-/**
- * Creates a plugin that controls unique constraint lookup behavior.
- *
- * @param options - Configuration options
- * @param options.disableAllUniqueLookups - If true, disables ALL unique lookups including primary keys
- */
-export declare function createUniqueLookupPlugin(options?: UniqueLookupOptions): GraphileConfig.Plugin;
-export declare const PrimaryKeyOnlyPlugin: GraphileConfig.Plugin;
-export declare const NoUniqueLookupPlugin: GraphileConfig.Plugin;
-/**
- * Preset that keeps only primary key lookups.
- * Use this in your main preset's `extends` array.
- */
-export declare const PrimaryKeyOnlyPreset: GraphileConfig.Preset;
-/**
- * Preset that disables ALL unique lookups (including primary keys).
- * Users must use collection queries with filters instead.
- * Use this in your main preset's `extends` array.
- */
-export declare const NoUniqueLookupPreset: GraphileConfig.Preset;

package/esm/plugins/primary-key-only.js

@@ -1,143 +0,0 @@
-/**
- * PrimaryKeyOnlyPlugin - Disables non-primary-key unique constraint lookups for
- * BOTH queries AND mutations.
- *
- * WHY THIS EXISTS:
- * PostGraphile v5 creates fields for EVERY unique constraint on a table:
- *
- * QUERIES (PgRowByUniquePlugin):
- * - `user(id)`, `userByEmail(email)`, `userByUsername(username)`
- *
- * MUTATIONS (PgMutationUpdateDeletePlugin):
- * - `updateUser`, `updateUserByEmail`, `updateUserByUsername`
- * - `deleteUser`, `deleteUserByEmail`, `deleteUserByUsername`
- *
- * For code generation (React Query, etc.), this creates unnecessary complexity.
- * The same operations can be done using the primary key lookup or filters.
- * Standardizing on primary keys reduces the API surface and generated code.
- *
- * SOURCE CODE REFERENCES:
- *
- * 1. Query fields (PgRowByUniquePlugin):
- * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgRowByUniquePlugin.ts#L42-L257
- *
- * The behavior check for queries:
- * ```typescript
- * const fieldBehaviorScope = "query:resource:single";
- * if (!build.behavior.pgResourceUniqueMatches([resource, unique], fieldBehaviorScope)) {
- *   return memo;  // Skip this field
- * }
- * ```
- *
- * 2. Mutation fields (PgMutationUpdateDeletePlugin):
- * https://github.com/graphile/crystal/blob/924b2515c6bd30e5905ac1419a25244b40c8bb4d/graphile-build/graphile-build-pg/src/plugins/PgMutationUpdateDeletePlugin.ts
- *
- * The behavior check for mutations:
- * ```typescript
- * const constraintMode = `constraint:${mode}`;  // "constraint:resource:update" or "constraint:resource:delete"
- * ...resource.uniques.filter((unique) => {
- *   return build.behavior.pgResourceUniqueMatches([resource, unique], constraintMode);
- * })
- * ```
- *
- * OUR FIX:
- * We use the behavior system's OVERRIDE phase (not inferred) to disable these behaviors.
- * The override phase runs AFTER the behavior multiplication/preferences system processes
- * behaviors, giving us the final say on what's enabled/disabled.
- *
- * Behaviors we control:
- * - `-single` - Disables query lookups (userByEmail, etc.)
- * - `-constraint:resource:update` - Disables updateByX mutations
- * - `-constraint:resource:delete` - Disables deleteByX mutations
- *
- * CONFIGURATION OPTIONS:
- *
- * 1. `disableAllUniqueLookups: false` (default - PrimaryKeyOnlyPreset):
- *    - Primary key: query lookup + mutations enabled
- *    - Non-primary-key: everything disabled
- *    Result: `user(id)`, `updateUser`, `deleteUser` only
- *
- * 2. `disableAllUniqueLookups: true` (NoUniqueLookupPreset):
- *    - Primary key: query lookup DISABLED, mutations ENABLED
- *    - Non-primary-key: everything disabled
- *    Result: No query lookups (use filters), but `updateUser`, `deleteUser` still work
- */
-/**
- * Creates a plugin that controls unique constraint lookup behavior.
- *
- * @param options - Configuration options
- * @param options.disableAllUniqueLookups - If true, disables ALL unique lookups including primary keys
- */
-export function createUniqueLookupPlugin(options = {}) {
-    const { disableAllUniqueLookups = false } = options;
-    return {
-        name: 'UniqueLookupPlugin',
-        version: '1.0.0',
-        description: disableAllUniqueLookups
-            ? 'Disables all unique constraint lookups (use filters instead)'
-            : 'Disables non-primary-key unique constraint lookups to reduce API surface',
-        schema: {
-            entityBehavior: {
-                pgResourceUnique: {
-                    // Use 'override' phase instead of 'inferred' - override runs AFTER
-                    // the behavior multiplication/preferences system processes behaviors,
-                    // so it has the final say on what behaviors are enabled/disabled.
-                    override: {
-                        provides: ['uniqueLookupControl'],
-                        callback(behavior, [_resource, unique]) {
-                            if (disableAllUniqueLookups) {
-                                // Disable ALL unique QUERY lookups - users must use filters
-                                // But KEEP primary key mutations (updateX, deleteX)
-                                if (unique.isPrimary) {
-                                    // Primary key: only disable query lookups, keep mutations
-                                    return [behavior, '-single'];
-                                }
-                                // Non-primary-key: disable everything (queries and mutations)
-                                return [
-                                    behavior,
-                                    '-single',
-                                    '-constraint:resource:update',
-                                    '-constraint:resource:delete',
-                                ];
-                            }
-                            // Only allow primary key lookups (both queries and mutations)
-                            if (!unique.isPrimary) {
-                                // Disable non-primary-key unique constraint lookups for queries and mutations
-                                return [
-                                    behavior,
-                                    '-single',
-                                    '-constraint:resource:update',
-                                    '-constraint:resource:delete',
-                                ];
-                            }
-                            return behavior;
-                        },
-                    },
-                },
-            },
-        },
-    };
-}
-// Default plugin instance (primary key only)
-export const PrimaryKeyOnlyPlugin = createUniqueLookupPlugin({
-    disableAllUniqueLookups: false,
-});
-// Plugin that disables ALL unique lookups
-export const NoUniqueLookupPlugin = createUniqueLookupPlugin({
-    disableAllUniqueLookups: true,
-});
-/**
- * Preset that keeps only primary key lookups.
- * Use this in your main preset's `extends` array.
- */
-export const PrimaryKeyOnlyPreset = {
-    plugins: [PrimaryKeyOnlyPlugin],
-};
-/**
- * Preset that disables ALL unique lookups (including primary keys).
- * Users must use collection queries with filters instead.
- * Use this in your main preset's `extends` array.
- */
-export const NoUniqueLookupPreset = {
-    plugins: [NoUniqueLookupPlugin],
-};

package/plugins/conflict-detector.d.ts

@@ -1,7 +0,0 @@
-import type { GraphileConfig } from 'graphile-config';
-export declare const ConflictDetectorPlugin: GraphileConfig.Plugin;
-/**
- * Preset that includes the conflict detector plugin.
- */
-export declare const ConflictDetectorPreset: GraphileConfig.Preset;
-export default ConflictDetectorPlugin;

package/plugins/conflict-detector.js

@@ -1,70 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConflictDetectorPreset = exports.ConflictDetectorPlugin = void 0;
-exports.ConflictDetectorPlugin = {
-    name: 'ConflictDetectorPlugin',
-    version: '1.0.0',
-    schema: {
-        hooks: {
-            build(build) {
-                // Track codecs by their GraphQL name to detect conflicts
-                const codecsByName = new Map();
-                // Get configured schemas from pgServices to only check relevant codecs
-                const configuredSchemas = new Set();
-                const pgServices = build.resolvedPreset?.pgServices ?? [];
-                for (const service of pgServices) {
-                    for (const schema of service.schemas ?? ['public']) {
-                        configuredSchemas.add(schema);
-                    }
-                }
-                // Iterate through all codecs to find tables
-                for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
-                    // Skip non-table codecs (those without attributes or anonymous ones)
-                    if (!codec.attributes || codec.isAnonymous)
-                        continue;
-                    // Get the schema name from the codec's extensions
-                    const pgExtensions = codec.extensions?.pg;
-                    const schemaName = pgExtensions?.schemaName || 'unknown';
-                    const tableName = codec.name;
-                    // Skip codecs from schemas not in the configured list
-                    if (configuredSchemas.size > 0 && !configuredSchemas.has(schemaName)) {
-                        continue;
-                    }
-                    // Get the GraphQL name that would be generated
-                    const graphqlName = build.inflection.tableType(codec);
-                    const info = {
-                        name: graphqlName,
-                        schemaName,
-                        tableName,
-                    };
-                    if (!codecsByName.has(graphqlName)) {
-                        codecsByName.set(graphqlName, []);
-                    }
-                    codecsByName.get(graphqlName).push(info);
-                }
-                // Check for conflicts and log warnings
-                for (const [graphqlName, codecs] of codecsByName) {
-                    if (codecs.length > 1) {
-                        const locations = codecs
-                            .map((c) => `${c.schemaName}.${c.tableName}`)
-                            .join(', ');
-                        console.warn(`\nNAMING CONFLICT DETECTED: GraphQL type "${graphqlName}" would be generated from multiple tables:\n` +
-                            `   Tables: ${locations}\n` +
-                            `   Resolution options:\n` +
-                            `   1. Add @name smart tag to one table: COMMENT ON TABLE schema.table IS E'@name UniqueTypeName';\n` +
-                            `   2. Rename one of the tables in the database\n` +
-                            `   3. Exclude one table from the schema using @omit smart tag\n`);
-                    }
-                }
-                return build;
-            },
-        },
-    },
-};
-/**
- * Preset that includes the conflict detector plugin.
- */
-exports.ConflictDetectorPreset = {
-    plugins: [exports.ConflictDetectorPlugin],
-};
-exports.default = exports.ConflictDetectorPlugin;

package/plugins/custom-inflector.d.ts

@@ -1,9 +0,0 @@
-import type { GraphileConfig } from 'graphile-config';
-export declare const InflektPlugin: GraphileConfig.Plugin;
-/**
- * Preset that includes the inflekt-based inflector plugin.
- * Use this in your main preset's `extends` array.
- */
-export declare const InflektPreset: GraphileConfig.Preset;
-export declare const CustomInflectorPlugin: GraphileConfig.Plugin;
-export declare const CustomInflectorPreset: GraphileConfig.Preset;