graphile-settings 4.9.3 → 4.10.0

package/plugins/primary-key-only.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoUniqueLookupPreset = exports.PrimaryKeyOnlyPreset = exports.NoUniqueLookupPlugin = exports.PrimaryKeyOnlyPlugin = void 0;
+exports.createUniqueLookupPlugin = createUniqueLookupPlugin;
+/**
+ * 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
+ */
+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)
+exports.PrimaryKeyOnlyPlugin = createUniqueLookupPlugin({
+    disableAllUniqueLookups: false,
+});
+// Plugin that disables ALL unique lookups
+exports.NoUniqueLookupPlugin = createUniqueLookupPlugin({
+    disableAllUniqueLookups: true,
+});
+/**
+ * Preset that keeps only primary key lookups.
+ * Use this in your main preset's `extends` array.
+ */
+exports.PrimaryKeyOnlyPreset = {
+    plugins: [exports.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.
+ */
+exports.NoUniqueLookupPreset = {
+    plugins: [exports.NoUniqueLookupPlugin],
+};

package/plugins/required-input-plugin.d.ts

@@ -0,0 +1,37 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * RequiredInputPlugin - Makes @requiredInput tagged fields non-nullable in mutation inputs.
+ *
+ * WHY THIS EXISTS:
+ * Some foreign key columns are nullable at the database level (to allow SET NULL cascades
+ * on FK deletion) but should be required at the API level (the application should always
+ * provide a value when creating or updating a record).
+ *
+ * The `api_required` column in constructive-db's metaschema injects a `@requiredInput`
+ * smart tag via PostgreSQL COMMENT ON COLUMN. This plugin reads that tag and wraps the
+ * corresponding GraphQL input field type with NonNull, making it required in mutations
+ * while keeping the output type nullable.
+ *
+ * USAGE:
+ * In the database, set the smart tag on a column:
+ *   COMMENT ON COLUMN app_public.membership.grantor_id IS E'@requiredInput';
+ *
+ * Or via constructive-db's metaschema:
+ *   UPDATE metaschema_public.field SET api_required = true WHERE ...;
+ *
+ * The trigger `tg_sync_api_required_smart_tag` will inject `{"requiredInput": true}`
+ * into the column's smart_tags JSONB, which PostGraphile reads as `@requiredInput`.
+ *
+ * RESULT:
+ * - Mutation input types (create, patch, base): field becomes non-nullable (required)
+ * - Output types: field remains nullable (unchanged)
+ * - Query filters: unaffected
+ */
+export declare const RequiredInputPlugin: GraphileConfig.Plugin;
+/**
+ * Preset that includes the RequiredInputPlugin.
+ * Add this to your main preset's `extends` array.
+ */
+export declare const RequiredInputPreset: GraphileConfig.Preset;

package/plugins/required-input-plugin.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequiredInputPreset = exports.RequiredInputPlugin = void 0;
+require("graphile-build");
+require("graphile-build-pg");
+/**
+ * RequiredInputPlugin - Makes @requiredInput tagged fields non-nullable in mutation inputs.
+ *
+ * WHY THIS EXISTS:
+ * Some foreign key columns are nullable at the database level (to allow SET NULL cascades
+ * on FK deletion) but should be required at the API level (the application should always
+ * provide a value when creating or updating a record).
+ *
+ * The `api_required` column in constructive-db's metaschema injects a `@requiredInput`
+ * smart tag via PostgreSQL COMMENT ON COLUMN. This plugin reads that tag and wraps the
+ * corresponding GraphQL input field type with NonNull, making it required in mutations
+ * while keeping the output type nullable.
+ *
+ * USAGE:
+ * In the database, set the smart tag on a column:
+ *   COMMENT ON COLUMN app_public.membership.grantor_id IS E'@requiredInput';
+ *
+ * Or via constructive-db's metaschema:
+ *   UPDATE metaschema_public.field SET api_required = true WHERE ...;
+ *
+ * The trigger `tg_sync_api_required_smart_tag` will inject `{"requiredInput": true}`
+ * into the column's smart_tags JSONB, which PostGraphile reads as `@requiredInput`.
+ *
+ * RESULT:
+ * - Mutation input types (create, patch, base): field becomes non-nullable (required)
+ * - Output types: field remains nullable (unchanged)
+ * - Query filters: unaffected
+ */
+exports.RequiredInputPlugin = {
+    name: 'RequiredInputPlugin',
+    version: '1.0.0',
+    description: 'Makes @requiredInput tagged fields non-nullable in mutation input types',
+    schema: {
+        hooks: {
+            GraphQLInputObjectType_fields(fields, build, context) {
+                const { scope: { pgCodec, isPgPatch, isPgBaseInput, isMutationInput }, } = context;
+                // Only process row-based input types (create inputs, patch inputs, base inputs)
+                if (!pgCodec || !pgCodec.attributes) {
+                    return fields;
+                }
+                // Must be a mutation-related input type
+                if (!isPgPatch && !isPgBaseInput && !isMutationInput) {
+                    return fields;
+                }
+                const { graphql: { GraphQLNonNull }, } = build;
+                let newFields = fields;
+                for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
+                    // Check for @requiredInput smart tag
+                    const tags = attribute.extensions?.tags;
+                    if (!tags || !tags.requiredInput) {
+                        continue;
+                    }
+                    // Find the corresponding GraphQL field name using inflection
+                    const fieldName = build.inflection.attribute({
+                        codec: pgCodec,
+                        attributeName,
+                    });
+                    const existingField = newFields[fieldName];
+                    if (!existingField) {
+                        continue;
+                    }
+                    // If the field type is already NonNull, skip
+                    const fieldType = existingField.type;
+                    if (fieldType instanceof GraphQLNonNull) {
+                        continue;
+                    }
+                    // Wrap the field type with NonNull to make it required
+                    newFields = build.extend(newFields, {
+                        [fieldName]: {
+                            ...existingField,
+                            type: new GraphQLNonNull(fieldType),
+                        },
+                    }, `RequiredInputPlugin making '${fieldName}' non-nullable on '${pgCodec.name}' (via @requiredInput smart tag)`);
+                }
+                return newFields;
+            },
+        },
+    },
+};
+/**
+ * Preset that includes the RequiredInputPlugin.
+ * Add this to your main preset's `extends` array.
+ */
+exports.RequiredInputPreset = {
+    plugins: [exports.RequiredInputPlugin],
+};

package/presets/constructive-preset.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConstructivePreset = void 0;
 const graphile_connection_filter_1 = require("graphile-connection-filter");
-const graphile_misc_plugins_1 = require("graphile-misc-plugins");
+const plugins_1 = require("../plugins");
 const graphile_search_1 = require("graphile-search");
 const graphile_postgis_1 = require("graphile-postgis");
 const graphile_upload_plugin_1 = require("graphile-upload-plugin");
@@ -62,15 +62,15 @@ const upload_resolver_1 = require("../upload-resolver");
  */
 exports.ConstructivePreset = {
     extends: [
-        graphile_misc_plugins_1.MinimalPreset,
-        graphile_misc_plugins_1.ConflictDetectorPreset,
-        graphile_misc_plugins_1.InflektPreset,
-        graphile_misc_plugins_1.InflectorLoggerPreset,
-        graphile_misc_plugins_1.NoUniqueLookupPreset,
+        plugins_1.MinimalPreset,
+        plugins_1.ConflictDetectorPreset,
+        plugins_1.InflektPreset,
+        plugins_1.InflectorLoggerPreset,
+        plugins_1.NoUniqueLookupPreset,
         (0, graphile_connection_filter_1.ConnectionFilterPreset)({ connectionFilterRelations: true }),
-        graphile_misc_plugins_1.EnableAllFilterColumnsPreset,
-        graphile_misc_plugins_1.ManyToManyOptInPreset,
-        graphile_misc_plugins_1.MetaSchemaPreset,
+        plugins_1.EnableAllFilterColumnsPreset,
+        plugins_1.ManyToManyOptInPreset,
+        plugins_1.MetaSchemaPreset,
         (0, graphile_search_1.UnifiedSearchPreset)({ fullTextScalarName: 'FullText', tsConfig: 'english' }),
         graphile_postgis_1.GraphilePostgisPreset,
         (0, graphile_upload_plugin_1.UploadPreset)({
@@ -78,7 +78,8 @@ exports.ConstructivePreset = {
             maxFileSize: 10 * 1024 * 1024, // 10MB
         }),
         (0, graphile_sql_expression_validator_1.SqlExpressionValidatorPreset)(),
-        graphile_misc_plugins_1.PgTypeMappingsPreset,
+        plugins_1.PgTypeMappingsPreset,
+        plugins_1.RequiredInputPreset,
     ],
     /**
      * Disable PostGraphile core's condition argument entirely.