graphile-settings 3.1.1 → 4.0.1

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/presets/constructive-preset.d.ts

@@ -0,0 +1,40 @@
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * Constructive PostGraphile v5 Preset
+ *
+ * This is the main preset that combines all our custom plugins and configurations.
+ * It provides a clean, opinionated GraphQL API built from PostgreSQL.
+ *
+ * FEATURES:
+ * - No Node/Relay features (keeps `id` as `id`, no global object identification)
+ * - Custom inflection using inflekt library
+ * - Conflict detection for multi-schema setups
+ * - Inflector logging for debugging (enable with INFLECTOR_LOG=1)
+ * - Primary key only lookups (no *ByEmail, *ByUsername, etc.)
+ * - Connection filter plugin with all columns filterable
+ * - Many-to-many relationships (opt-in via @behavior +manyToMany)
+ * - Meta schema plugin (_meta query for introspection of tables, fields, indexes)
+ * - PG type mappings (maps custom types like email, url to GraphQL scalars)
+ *
+ * DISABLED PLUGINS:
+ * - PgConnectionArgFilterBackwardRelationsPlugin (relation filters bloat the API)
+ * - PgConnectionArgFilterForwardRelationsPlugin (relation filters bloat the API)
+ *
+ * USAGE:
+ * ```typescript
+ * import { ConstructivePreset } from 'graphile-settings/presets';
+ * import { makePgService } from 'postgraphile/adaptors/pg';
+ *
+ * const preset: GraphileConfig.Preset = {
+ *   extends: [ConstructivePreset],
+ *   pgServices: [
+ *     makePgService({
+ *       connectionString: DATABASE_URL,
+ *       schemas: ['public'],
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export declare const ConstructivePreset: GraphileConfig.Preset;
+export default ConstructivePreset;

package/presets/constructive-preset.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConstructivePreset = void 0;
+const postgraphile_plugin_connection_filter_1 = require("postgraphile-plugin-connection-filter");
+const minimal_preset_1 = require("../plugins/minimal-preset");
+const custom_inflector_1 = require("../plugins/custom-inflector");
+const conflict_detector_1 = require("../plugins/conflict-detector");
+const inflector_logger_1 = require("../plugins/inflector-logger");
+const primary_key_only_1 = require("../plugins/primary-key-only");
+const enable_all_filter_columns_1 = require("../plugins/enable-all-filter-columns");
+const many_to_many_preset_1 = require("../plugins/many-to-many-preset");
+const meta_schema_1 = require("../plugins/meta-schema");
+const graphile_search_plugin_1 = require("graphile-search-plugin");
+const pg_type_mappings_1 = require("../plugins/pg-type-mappings");
+/**
+ * Constructive PostGraphile v5 Preset
+ *
+ * This is the main preset that combines all our custom plugins and configurations.
+ * It provides a clean, opinionated GraphQL API built from PostgreSQL.
+ *
+ * FEATURES:
+ * - No Node/Relay features (keeps `id` as `id`, no global object identification)
+ * - Custom inflection using inflekt library
+ * - Conflict detection for multi-schema setups
+ * - Inflector logging for debugging (enable with INFLECTOR_LOG=1)
+ * - Primary key only lookups (no *ByEmail, *ByUsername, etc.)
+ * - Connection filter plugin with all columns filterable
+ * - Many-to-many relationships (opt-in via @behavior +manyToMany)
+ * - Meta schema plugin (_meta query for introspection of tables, fields, indexes)
+ * - PG type mappings (maps custom types like email, url to GraphQL scalars)
+ *
+ * DISABLED PLUGINS:
+ * - PgConnectionArgFilterBackwardRelationsPlugin (relation filters bloat the API)
+ * - PgConnectionArgFilterForwardRelationsPlugin (relation filters bloat the API)
+ *
+ * USAGE:
+ * ```typescript
+ * import { ConstructivePreset } from 'graphile-settings/presets';
+ * import { makePgService } from 'postgraphile/adaptors/pg';
+ *
+ * const preset: GraphileConfig.Preset = {
+ *   extends: [ConstructivePreset],
+ *   pgServices: [
+ *     makePgService({
+ *       connectionString: DATABASE_URL,
+ *       schemas: ['public'],
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+exports.ConstructivePreset = {
+    extends: [
+        minimal_preset_1.MinimalPreset,
+        conflict_detector_1.ConflictDetectorPreset,
+        custom_inflector_1.InflektPreset,
+        inflector_logger_1.InflectorLoggerPreset,
+        primary_key_only_1.NoUniqueLookupPreset,
+        postgraphile_plugin_connection_filter_1.PostGraphileConnectionFilterPreset,
+        enable_all_filter_columns_1.EnableAllFilterColumnsPreset,
+        many_to_many_preset_1.ManyToManyOptInPreset,
+        meta_schema_1.MetaSchemaPreset,
+        (0, graphile_search_plugin_1.PgSearchPreset)({ pgSearchPrefix: 'fullText' }),
+        pg_type_mappings_1.PgTypeMappingsPreset,
+    ],
+    /**
+     * Disable relation filter plugins from postgraphile-plugin-connection-filter.
+     *
+     * WHY THIS EXISTS:
+     * The connection filter plugin includes PgConnectionArgFilterBackwardRelationsPlugin and
+     * PgConnectionArgFilterForwardRelationsPlugin which add relation filter fields like
+     * `apiExtensions`, `apiExtensionsExist`, `database`, `domains`, etc. to every filter type.
+     *
+     * The `connectionFilterRelations: false` schema option does NOT work - it's defined in the
+     * plugin's TypeScript types but the actual code always includes the plugins regardless.
+     * See: https://github.com/graphile-contrib/postgraphile-plugin-connection-filter/blob/master/src/index.ts
+     * The comments `//if (connectionFilterRelations)` are just comments, not actual conditional logic.
+     *
+     * The entityBehavior approach (setting `pgCodecRelation: '-filterBy'`) also doesn't work
+     * because the behavior system doesn't properly negate the plugin's default `filterBy` behavior.
+     *
+     * OUR FIX:
+     * We use `disablePlugins` to directly disable the two relation filter plugins.
+     * This is the most reliable way to prevent relation filter fields from being generated.
+     */
+    disablePlugins: [
+        'PgConnectionArgFilterBackwardRelationsPlugin',
+        'PgConnectionArgFilterForwardRelationsPlugin',
+    ],
+    /**
+     * Connection Filter Plugin Configuration
+     *
+     * These options control what fields appear in the `filter` argument on connections.
+     * We disable relation filters to keep the API surface clean and match our v4 behavior.
+     *
+     * NOTE: By default, PostGraphile v5 only allows filtering on INDEXED columns.
+     * We override this with EnableAllFilterColumnsPreset to allow filtering on ALL columns.
+     * This gives developers flexibility but requires monitoring for slow queries on
+     * non-indexed columns. See the plugin documentation for performance considerations.
+     *
+     * NOTE: Relation filtering is disabled via `disablePlugins` above.
+     *
+     * Documentation: https://github.com/graphile-contrib/postgraphile-plugin-connection-filter
+     */
+    schema: {
+        /**
+         * connectionFilterRelations: false
+         * This option is defined in the plugin's types but does NOT actually work.
+         * The relation filter plugins are disabled via `disablePlugins` above.
+         * We keep this option set to false for documentation purposes.
+         */
+        connectionFilterRelations: false,
+        /**
+         * connectionFilterComputedColumns: false
+         * Disables filtering on computed columns (functions that return a value for a row).
+         * Computed columns can be expensive to filter on since they may not be indexed.
+         * To selectively enable, use `@filterable` smart tag on specific functions.
+         */
+        connectionFilterComputedColumns: false,
+        /**
+         * connectionFilterSetofFunctions: false
+         * Disables filtering on functions that return `setof` (multiple rows).
+         * These can be expensive operations. To selectively enable, use `@filterable` smart tag.
+         */
+        connectionFilterSetofFunctions: false,
+        /**
+         * connectionFilterLogicalOperators: true (default)
+         * Keeps `and`, `or`, `not` operators for combining filter conditions.
+         * Example: filter: { or: [{ name: { eq: "foo" } }, { name: { eq: "bar" } }] }
+         */
+        connectionFilterLogicalOperators: true,
+        /**
+         * connectionFilterArrays: true (default)
+         * Allows filtering on PostgreSQL array columns.
+         * Example: filter: { tags: { contains: ["important"] } }
+         */
+        connectionFilterArrays: true,
+    },
+};
+exports.default = exports.ConstructivePreset;

package/presets/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * PostGraphile v5 Presets
+ *
+ * This module exports pre-configured presets that combine multiple plugins
+ * for common use cases.
+ */
+export { ConstructivePreset } from './constructive-preset';

package/presets/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * PostGraphile v5 Presets
+ *
+ * This module exports pre-configured presets that combine multiple plugins
+ * for common use cases.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConstructivePreset = void 0;
+var constructive_preset_1 = require("./constructive-preset");
+Object.defineProperty(exports, "ConstructivePreset", { enumerable: true, get: function () { return constructive_preset_1.ConstructivePreset; } });