graphile-settings 3.1.1 → 4.0.1

package/README.md

@@ -16,118 +16,203 @@
   </a>
 </p>
 
-**`graphile-settings`** is a batteries-included configuration builder for [PostGraphile](https://www.graphile.org/postgraphile/), purpose-built for the Constructive ecosystem. It centralizes plugin setup, schema wiring, and feature flags into a single, composable interface — enabling consistent, high-performance GraphQL APIs across projects.
+A batteries-included configuration builder for [PostGraphile v5](https://www.graphile.org/postgraphile/), purpose-built for the Constructive ecosystem. It centralizes plugin setup, schema wiring, and feature flags into a single, composable interface — enabling consistent, high-performance GraphQL APIs across projects.
 
-## 🚀 Installation
+## Installation
 
 ```bash
 npm install graphile-settings
 ```
 
-## ✨ Features
+## Quick Start
 
-* Built-in support for:
-
-  * ✅ Connection filters
-  * 🔍 Full-text search
-  * 🌍 PostGIS support (with filters)
-  * 🧩 Many-to-many helpers
-  * 🆎 Simplified inflectors
-  * 🗂 Upload field support (S3/MinIO)
-  * 🌐 i18n support via `graphile-i18n`
-  * 🧠 Meta schema plugin
-  * 🔎 Graphile search plugin
-* Smart schema and plugin configuration via environment or options
-* Express-compatible with support for request-aware context
-
-## 📦 Usage
-
-```ts
-import { getGraphileSettings } from 'graphile-settings';
+```typescript
+import { ConstructivePreset, makePgService } from 'graphile-settings';
 import { postgraphile } from 'postgraphile';
+import { grafserv } from 'grafserv/express/v4';
 import express from 'express';
 
 const app = express();
 
-const settings = getGraphileSettings({
-  server: {
-    port: 5000,
-    host: '0.0.0.0',
-    strictAuth: true,
-  },
-  graphile: {
-    schema: ['app_public'],
-    metaSchemas: ['metaschema_public', 'services_public', 'metaschema_modules_public'],
-  },
-  features: {
-    postgis: true,
-    simpleInflection: true,
-    oppositeBaseNames: true,
-  },
-  cdn: {
-    bucketName: 'media-bucket',
-    awsRegion: 'us-west-1',
-    awsAccessKey: 'AKIA...',
-    awsSecretKey: 'secret',
-    minioEndpoint: 'http://localhost:9000'
-  }
-});
+const preset = {
+  extends: [ConstructivePreset],
+  pgServices: [
+    makePgService({
+      connectionString: 'postgres://user:pass@localhost/mydb',
+      schemas: ['app_public'],
+    }),
+  ],
+};
+
+const pgl = postgraphile(preset);
+const serv = pgl.createServ(grafserv);
+
+const httpServer = require('http').createServer(app);
+serv.addTo(app, httpServer);
+httpServer.listen(5000);
+```
+
+## Features
+
+The `ConstructivePreset` combines multiple plugins and configurations to provide a clean, opinionated GraphQL API. Below is a detailed breakdown of each feature.
+
+### No Node/Relay Features (MinimalPreset)
+
+PostGraphile v5 includes Relay Global Object Identification by default, which adds a global `id` field to types and renames actual `id` columns to `rowId`. Since Constructive uses UUIDs, we disable all Node/Relay plugins to keep `id` columns as `id`.
+
+Disabled plugins: `NodePlugin`, `AddNodeInterfaceToSuitableTypesPlugin`, `NodeIdCodecBase64JSONPlugin`, `NodeIdCodecPipeStringPlugin`, `RegisterQueryNodePlugin`, `NodeAccessorPlugin`, `PgNodeIdAttributesPlugin`, `PgTableNodePlugin`
+
+### Custom Inflection (InflektPreset)
+
+Uses the `inflekt` library for consistent naming conventions with proper Latin plural handling (e.g., "schemata" → "schema" instead of "schematum"). Key simplifications include simplified root query fields (`allUsers` → `users`), simplified relation fields (`userByAuthorId` → `author`, `postsByAuthorId` → `posts`), simplified many-to-many fields (`tagsByPostTagPostIdAndTagId` → `tags`), and shortened mutation names (`updateUserById` → `updateUser`).
 
-app.use(postgraphile({
-  ...settings,
-  pgPool: myPool // your initialized pg.Pool
-}));
+The many-to-many inflector includes conflict detection — if a direct relation to the same target table exists or there are multiple many-to-many relations to the same target, it falls back to verbose naming to avoid conflicts.
 
-app.listen(settings.port);
+### Connection Filter Plugin
+
+Adds powerful filtering capabilities to connections with operators like `eq`, `ne`, `lt`, `gt`, `contains`, `startsWith`, etc. Configuration includes logical operators (`and`, `or`, `not`) enabled for combining conditions, array filtering enabled for PostgreSQL array columns, computed column filtering disabled by default (enable with `@filterable` smart tag), setof function filtering disabled by default, and relation filtering disabled to keep the API surface clean.
+
+### Filter All Columns (EnableAllFilterColumnsPreset)
+
+By default, PostGraphile v5 only allows filtering on indexed columns. This preset enables filtering on ALL columns, giving developers flexibility while leaving index optimization to DBAs. Monitor query performance and add indexes as needed for frequently filtered columns.
+
+### Many-to-Many Relationships (ManyToManyOptInPreset)
+
+Uses `@graphile-contrib/pg-many-to-many` with opt-in behavior. By default, no many-to-many fields are generated. To enable for a specific junction table:
+
+```sql
+COMMENT ON TABLE post_tags IS E'@behavior +manyToMany';
 ```
 
-## 🧰 Configuration Options
+This prevents API bloat from unused junction table fields.
 
-### `ConstructiveOptions`
+### Primary Key Only Lookups (NoUniqueLookupPreset)
 
-#### `server`
+Disables non-primary-key unique constraint lookups for both queries and mutations. Instead of generating `user(id)`, `userByEmail(email)`, `userByUsername(username)`, only `user(id)` is generated. The same operations can be done using filters, reducing API surface and generated code complexity.
+
+### Meta Schema Plugin (MetaSchemaPreset)
+
+Exposes a `_meta` GraphQL query for database schema introspection:
+
+```graphql
+query {
+  _meta {
+    tables {
+      name
+      schemaName
+      fields { name, type { pgType, gqlType, isArray }, isNotNull, hasDefault }
+      indexes { name, isUnique, isPrimary, columns }
+      constraints { primaryKey, unique, foreignKey }
+      inflection { tableType, allRows, connection, edge }
+      query { all, one, create, update, delete }
+    }
+  }
+}
+```
 
-* `port` — (number) Port to use
-* `host` — (string) Hostname
-* `trustProxy` — (boolean) Whether to trust proxy headers (e.g. for real IPs)
-* `origin` — (string) Origin for CORS/auth logic
-* `strictAuth` — (boolean) Whether to enforce strict auth
+Useful for code generation tools that need to understand the database structure.
 
-#### `graphile`
+Testing strategy:
+- Metadata behavior is tested in-process with mocked PostGraphile build resources (no live DB required).
+- Snapshot coverage captures full multi-table metadata scenarios and query contract shape.
+- Run: `pnpm --filter graphile-settings exec jest --runInBand`
 
-* `schema` — (string or string\[]) Required list of main GraphQL schemas
-* `metaSchemas` — (string\[]) Optional list of meta/introspection schemas
-* `isPublic` — (boolean) Flag for public GraphQL instance
-* `appendPlugins` — (Plugin\[]) Additional Graphile plugins
-* `graphileBuildOptions` — (PostGraphileOptions.graphileBuildOptions) Extra build options
-* `overrideSettings` — (Partial<PostGraphileOptions>) Manual overrides of generated config
+### Tsvector Codec (TsvectorCodecPreset)
 
-#### `features`
+Adds support for PostgreSQL's `tsvector` and `tsquery` types used in full-text search. These types are represented as strings in GraphQL.
 
-* `simpleInflection` — Use simplified inflection (e.g. `fooByBarId`)
-* `oppositeBaseNames` — Enable smart reverse relation names
-* `postgis` — Enable PostGIS and filter plugin
+### Conflict Detector (ConflictDetectorPreset)
+
+Detects naming conflicts between tables in different schemas. When two tables would have the same GraphQL type name, logs a warning with resolution options (smart tags, rename, or omit).
+
+### Inflector Logger (InflectorLoggerPreset)
+
+Logs inflector calls during schema build for debugging. Enable with `INFLECTOR_LOG=1` environment variable. Only runs at build time, not on every request.
+
+## Presets
+
+| Preset | Description |
+|--------|-------------|
+| `ConstructivePreset` | Main preset combining all features (recommended) |
+| `MinimalPreset` | PostGraphile without Node/Relay features |
+| `InflektPreset` | Custom inflection using inflekt library |
+| `ConflictDetectorPreset` | Warns about naming conflicts between schemas |
+| `InflectorLoggerPreset` | Debug logging for inflector calls |
+| `EnableAllFilterColumnsPreset` | Allow filtering on all columns |
+| `ManyToManyOptInPreset` | Many-to-many with opt-in behavior |
+| `NoUniqueLookupPreset` | Disable non-primary-key lookups |
+| `MetaSchemaPreset` | `_meta` query for schema introspection |
+| `TsvectorCodecPreset` | Support for tsvector/tsquery types |
+
+## Plugins
+
+Each preset includes one or more plugins that can be used individually:
+
+| Plugin | Description |
+|--------|-------------|
+| `InflektPlugin` | Custom inflection rules |
+| `ConflictDetectorPlugin` | Naming conflict detection |
+| `InflectorLoggerPlugin` | Debug logging |
+| `EnableAllFilterColumnsPlugin` | Enable all column filters |
+| `ManyToManyOptInPlugin` | Opt-in many-to-many behavior |
+| `PrimaryKeyOnlyPlugin` | Keep only primary key lookups |
+| `NoUniqueLookupPlugin` | Disable all unique lookups |
+| `MetaSchemaPlugin` | Schema introspection |
+| `TsvectorCodecPlugin` | Tsvector type support |
+
+## Building Schema Directly
+
+For codegen, testing, or other use cases where you need the schema without a server:
+
+```typescript
+import { ConstructivePreset, makePgService } from 'graphile-settings';
+import { makeSchema } from 'graphile-build';
+import { printSchema } from 'graphql';
+
+const preset = {
+  extends: [ConstructivePreset],
+  pgServices: [
+    makePgService({
+      connectionString: 'postgres://user:pass@localhost/mydb',
+      schemas: ['app_public'],
+    }),
+  ],
+};
+
+const { schema } = await makeSchema(preset);
+const sdl = printSchema(schema);
+```
+
+## Smart Tags Reference
+
+Control schema generation with PostgreSQL comments:
+
+```sql
+-- Enable many-to-many on a junction table
+COMMENT ON TABLE post_tags IS E'@behavior +manyToMany';
+
+-- Customize many-to-many field name
+COMMENT ON CONSTRAINT post_tags_tag_id_fkey ON post_tags IS E'@manyToManyFieldName tags';
+
+-- Rename a type
+COMMENT ON TABLE users IS E'@name Person';
+
+-- Omit a table from the schema
+COMMENT ON TABLE internal_logs IS E'@omit';
+
+-- Make a computed column filterable
+COMMENT ON FUNCTION full_name(users) IS E'@filterable';
+```
 
-#### `cdn`
+## Environment Variables
 
-* `bucketName` — Required for upload plugin (S3 or MinIO)
-* `awsRegion` — AWS region
-* `awsAccessKey` — Access key for upload
-* `awsSecretKey` — Secret key
-* `minioEndpoint` — Optional override for MinIO compatibility
+| Variable | Description |
+|----------|-------------|
+| `INFLECTOR_LOG=1` | Enable inflector debug logging |
 
-## 🔌 Included Plugins
+## License
 
-* `graphile-plugin-connection-filter`
-* `graphile-plugin-fulltext-filter`
-* `graphile-postgis`
-* `graphile-plugin-connection-filter-postgis`
-* `graphile-simple-inflector`
-* `graphile-i18n`
-* `graphile-meta-schema`
-* `@graphile-contrib/pg-many-to-many`
-* `graphile-search-plugin`
-* `graphile-pg-type-mappings`
+MIT
 
 ---
 

package/esm/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * graphile-settings
+ *
+ * Shared PostGraphile v5 settings, presets, and plugins for Constructive.
+ *
+ * This package provides:
+ * - Custom plugins for PostGraphile v5
+ * - Pre-configured presets combining multiple plugins
+ *
+ * USAGE:
+ *
+ * 1. Use the main preset:
+ * ```typescript
+ * import { ConstructivePreset, makePgService } from 'graphile-settings';
+ * import { makeSchema } from 'graphile-build';
+ *
+ * const preset = {
+ *   extends: [ConstructivePreset],
+ *   pgServices: [makePgService({ connectionString, schemas })],
+ * };
+ * const { schema } = await makeSchema(preset);
+ * ```
+ *
+ * 2. Use individual plugins:
+ * ```typescript
+ * import { MinimalPreset, InflektPreset } from 'graphile-settings/plugins';
+ * ```
+ */
+import { makePgService } from 'postgraphile/adaptors/pg';
+import 'postgraphile/grafserv';
+import 'graphile-build';
+export { ConstructivePreset } from './presets/constructive-preset';
+export * from './plugins/index';
+export * from './presets/index';
+import { MinimalPreset } from './plugins/minimal-preset';
+export { MinimalPreset };
+export { makePgService };

package/esm/index.js

@@ -1,103 +1,54 @@
-import PgManyToMany from '@graphile-contrib/pg-many-to-many';
-import { getEnvOptions } from '@constructive-io/graphql-env';
-import PgPostgis from 'graphile-postgis';
-import FulltextFilterPlugin from 'graphile-plugin-fulltext-filter';
-import { NodePlugin } from 'graphile-build';
-import { additionalGraphQLContextFromRequest as langAdditional, LangPlugin } from 'graphile-i18n';
-import PgMetaschema from 'graphile-meta-schema';
-import PgSearch from 'graphile-search-plugin';
-import PgSimpleInflector from 'graphile-simple-inflector';
-import ConnectionFilterPlugin from 'graphile-plugin-connection-filter';
-import PgPostgisFilter from 'graphile-plugin-connection-filter-postgis';
-import CustomPgTypeMappingsPlugin from 'graphile-pg-type-mappings';
-import UploadPostGraphilePlugin, { Uploader } from 'graphile-upload-plugin';
-export const getGraphileSettings = (rawOpts) => {
-    const opts = getEnvOptions(rawOpts);
-    const { server, graphile, features, cdn } = opts;
-    // Instantiate uploader with merged cdn opts
-    const uploader = new Uploader({
-        bucketName: cdn.bucketName,
-        awsRegion: cdn.awsRegion,
-        awsAccessKey: cdn.awsAccessKey,
-        awsSecretKey: cdn.awsSecretKey,
-        minioEndpoint: cdn.minioEndpoint,
-        provider: cdn.provider,
-    });
-    const resolveUpload = uploader.resolveUpload.bind(uploader);
-    const plugins = [
-        ConnectionFilterPlugin,
-        FulltextFilterPlugin,
-        CustomPgTypeMappingsPlugin,
-        UploadPostGraphilePlugin,
-        PgMetaschema,
-        PgManyToMany,
-        PgSearch,
-    ];
-    if (features?.postgis) {
-        plugins.push(PgPostgis, PgPostgisFilter);
-    }
-    if (features?.simpleInflection) {
-        plugins.push(PgSimpleInflector);
-    }
-    plugins.push(LangPlugin);
-    return {
-        graphileBuildOptions: {
-            uploadFieldDefinitions: [
-                {
-                    name: 'upload',
-                    namespaceName: 'public',
-                    type: 'JSON',
-                    resolve: resolveUpload,
-                },
-                {
-                    name: 'attachment',
-                    namespaceName: 'public',
-                    type: 'String',
-                    resolve: resolveUpload,
-                },
-                {
-                    name: 'image',
-                    namespaceName: 'public',
-                    type: 'JSON',
-                    resolve: resolveUpload,
-                },
-                {
-                    tag: 'upload',
-                    resolve: resolveUpload,
-                },
-            ],
-            pgSimplifyOppositeBaseNames: features?.oppositeBaseNames,
-            connectionFilterComputedColumns: false,
-        },
-        appendPlugins: plugins,
-        skipPlugins: [NodePlugin],
-        dynamicJson: true,
-        disableGraphiql: false,
-        enhanceGraphiql: true,
-        enableQueryBatching: true,
-        graphiql: true,
-        watch: false,
-        port: server?.port,
-        host: server?.host,
-        schema: graphile?.schema,
-        ignoreRBAC: false,
-        legacyRelations: 'omit',
-        showErrorStack: false,
-        // @ts-ignore
-        extendedErrors: false,
-        disableQueryLog: false,
-        includeExtensionResources: true,
-        setofFunctionsContainNulls: false,
-        retryOnInitFail: async (_error) => {
-            return false;
-        },
-        additionalGraphQLContextFromRequest: async (req, res) => {
-            const langContext = await langAdditional(req, res);
-            return {
-                ...langContext,
-                req,
-                res,
-            };
-        },
-    };
-};
+/**
+ * graphile-settings
+ *
+ * Shared PostGraphile v5 settings, presets, and plugins for Constructive.
+ *
+ * This package provides:
+ * - Custom plugins for PostGraphile v5
+ * - Pre-configured presets combining multiple plugins
+ *
+ * USAGE:
+ *
+ * 1. Use the main preset:
+ * ```typescript
+ * import { ConstructivePreset, makePgService } from 'graphile-settings';
+ * import { makeSchema } from 'graphile-build';
+ *
+ * const preset = {
+ *   extends: [ConstructivePreset],
+ *   pgServices: [makePgService({ connectionString, schemas })],
+ * };
+ * const { schema } = await makeSchema(preset);
+ * ```
+ *
+ * 2. Use individual plugins:
+ * ```typescript
+ * import { MinimalPreset, InflektPreset } from 'graphile-settings/plugins';
+ * ```
+ */
+import { makePgService } from 'postgraphile/adaptors/pg';
+// Import modules for type augmentation
+// These add properties to the GraphileConfig.Preset interface:
+// - grafserv: adds 'grafserv' property
+// - graphile-build: adds 'schema' property (typed as GraphileBuild.SchemaOptions)
+// - postgraphile-plugin-connection-filter: augments SchemaOptions with connectionFilter* options
+import 'postgraphile/grafserv';
+import 'graphile-build';
+// ============================================================================
+// Re-export all plugins and presets
+// ============================================================================
+// Main preset
+export { ConstructivePreset } from './presets/constructive-preset';
+// Re-export all plugins for convenience
+export * from './plugins/index';
+// Re-export presets
+export * from './presets/index';
+// ============================================================================
+// Utilities
+// ============================================================================
+// Import the new MinimalPreset from plugins
+import { MinimalPreset } from './plugins/minimal-preset';
+// Re-export MinimalPreset for backward compatibility
+export { MinimalPreset };
+// Re-export makePgService for convenience
+export { makePgService };

package/esm/plugins/conflict-detector.d.ts

@@ -0,0 +1,7 @@
+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/esm/plugins/conflict-detector.js

@@ -0,0 +1,67 @@
+export const 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.
+ */
+export const ConflictDetectorPreset = {
+    plugins: [ConflictDetectorPlugin],
+};
+export default ConflictDetectorPlugin;

package/esm/plugins/custom-inflector.d.ts

@@ -0,0 +1,9 @@
+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;