graphile-settings 4.9.2 → 4.10.0

package/esm/plugins/meta-schema/type-mappings.js

@@ -0,0 +1,75 @@
+const PG_TO_GQL_TYPE = {
+    text: 'String',
+    varchar: 'String',
+    char: 'String',
+    name: 'String',
+    bpchar: 'String',
+    uuid: 'UUID',
+    int2: 'Int',
+    int4: 'Int',
+    integer: 'Int',
+    int8: 'BigInt',
+    bigint: 'BigInt',
+    float4: 'Float',
+    float8: 'Float',
+    numeric: 'BigFloat',
+    bool: 'Boolean',
+    boolean: 'Boolean',
+    timestamptz: 'Datetime',
+    timestamp: 'Datetime',
+    date: 'Date',
+    time: 'Time',
+    timetz: 'Time',
+    json: 'JSON',
+    jsonb: 'JSON',
+    interval: 'Interval',
+    point: 'Point',
+    geometry: 'GeoJSON',
+    geography: 'GeoJSON',
+    inet: 'InternetAddress',
+    cidr: 'InternetAddress',
+    xml: 'String',
+    bytea: 'String',
+    macaddr: 'String',
+};
+export function pgTypeToGqlType(pgTypeName) {
+    return PG_TO_GQL_TYPE[pgTypeName] || pgTypeName;
+}
+function resolveGqlTypeName(build, codec) {
+    if (!codec)
+        return 'unknown';
+    try {
+        const codecForLookup = codec.arrayOfCodec || codec;
+        if (build?.hasGraphQLTypeForPgCodec?.(codecForLookup, 'output')) {
+            const resolved = build.getGraphQLTypeNameByPgCodec?.(codecForLookup, 'output');
+            if (resolved)
+                return resolved;
+        }
+    }
+    catch {
+        // Fall through to static fallback mapping.
+    }
+    const pgTypeName = codec.name || 'unknown';
+    const mapped = pgTypeToGqlType(pgTypeName);
+    if (mapped !== pgTypeName)
+        return mapped;
+    const nestedTypeName = codec.arrayOfCodec?.name;
+    return nestedTypeName ? pgTypeToGqlType(nestedTypeName) : pgTypeName;
+}
+export function buildFieldMeta(name, attr, build) {
+    const pgType = attr?.codec?.name || 'unknown';
+    const isNotNull = attr?.notNull || false;
+    const hasDefault = attr?.hasDefault || false;
+    return {
+        name,
+        type: {
+            pgType,
+            gqlType: build ? resolveGqlTypeName(build, attr?.codec) : pgTypeToGqlType(pgType),
+            isArray: !!attr?.codec?.arrayOfCodec,
+            isNotNull,
+            hasDefault,
+        },
+        isNotNull,
+        hasDefault,
+    };
+}

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

@@ -0,0 +1,206 @@
+export interface TableMeta {
+    name: string;
+    schemaName: string;
+    fields: FieldMeta[];
+    indexes: IndexMeta[];
+    constraints: ConstraintsMeta;
+    foreignKeyConstraints: ForeignKeyConstraintMeta[];
+    primaryKeyConstraints: PrimaryKeyConstraintMeta[];
+    uniqueConstraints: UniqueConstraintMeta[];
+    relations: RelationsMeta;
+    inflection: InflectionMeta;
+    query: QueryMeta;
+}
+export interface FieldMeta {
+    name: string;
+    type: TypeMeta;
+    isNotNull: boolean;
+    hasDefault: boolean;
+}
+export interface TypeMeta {
+    pgType: string;
+    gqlType: string;
+    isArray: boolean;
+    isNotNull?: boolean;
+    hasDefault?: boolean;
+}
+export interface IndexMeta {
+    name: string;
+    isUnique: boolean;
+    isPrimary: boolean;
+    columns: string[];
+    fields: FieldMeta[];
+}
+export interface ConstraintsMeta {
+    primaryKey: PrimaryKeyConstraintMeta | null;
+    unique: UniqueConstraintMeta[];
+    foreignKey: ForeignKeyConstraintMeta[];
+}
+export interface PrimaryKeyConstraintMeta {
+    name: string;
+    fields: FieldMeta[];
+}
+export interface UniqueConstraintMeta {
+    name: string;
+    fields: FieldMeta[];
+}
+export interface ForeignKeyConstraintMeta {
+    name: string;
+    fields: FieldMeta[];
+    referencedTable: string;
+    referencedFields: string[];
+    refFields: FieldMeta[];
+    refTable: {
+        name: string;
+    };
+}
+export interface RelationsMeta {
+    belongsTo: BelongsToRelation[];
+    has: HasRelation[];
+    hasOne: HasRelation[];
+    hasMany: HasRelation[];
+    manyToMany: ManyToManyRelation[];
+}
+export interface BelongsToRelation {
+    fieldName: string | null;
+    isUnique: boolean;
+    type: string | null;
+    keys: FieldMeta[];
+    references: {
+        name: string;
+    };
+}
+export interface HasRelation {
+    fieldName: string | null;
+    isUnique: boolean;
+    type: string | null;
+    keys: FieldMeta[];
+    referencedBy: {
+        name: string;
+    };
+}
+export interface ManyToManyRelation {
+    fieldName: string | null;
+    type: string | null;
+    junctionTable: {
+        name: string;
+    };
+    junctionLeftConstraint: ForeignKeyConstraintMeta;
+    junctionLeftKeyAttributes: FieldMeta[];
+    junctionRightConstraint: ForeignKeyConstraintMeta;
+    junctionRightKeyAttributes: FieldMeta[];
+    leftKeyAttributes: FieldMeta[];
+    rightKeyAttributes: FieldMeta[];
+    rightTable: {
+        name: string;
+    };
+}
+export interface InflectionMeta {
+    tableType: string;
+    allRows: string;
+    connection: string;
+    edge: string;
+    filterType: string | null;
+    orderByType: string;
+    conditionType: string;
+    patchType: string | null;
+    createInputType: string;
+    createPayloadType: string;
+    updatePayloadType: string | null;
+    deletePayloadType: string;
+}
+export interface QueryMeta {
+    all: string;
+    one: string | null;
+    create: string | null;
+    update: string | null;
+    delete: string | null;
+}
+export interface PgCodec {
+    name: string;
+    attributes?: Record<string, PgAttribute>;
+    arrayOfCodec?: PgCodec | null;
+    isAnonymous?: boolean;
+    extensions?: {
+        pg?: {
+            schemaName?: string;
+        };
+    };
+}
+export interface PgAttribute {
+    codec?: PgCodec | null;
+    notNull?: boolean;
+    hasDefault?: boolean;
+}
+export interface PgUnique {
+    attributes: string[];
+    isPrimary?: boolean;
+    tags?: {
+        name?: string;
+    };
+}
+export interface PgRelation {
+    isReferencee?: boolean;
+    localAttributes?: string[];
+    remoteAttributes?: string[];
+    remoteResource?: PgTableResource | null;
+}
+export interface PgTableResource {
+    codec?: PgCodec;
+    uniques?: PgUnique[];
+    relations?: Record<string, PgRelation>;
+    parameters?: unknown;
+    isVirtual?: boolean;
+    isUnique?: boolean;
+    getRelation?: (relationName: string) => PgRelation | undefined;
+    getRelations?: () => Record<string, PgRelation>;
+}
+export interface PgManyToManyRelationDetails {
+    leftTable: PgTableResource;
+    leftRelationName: string;
+    junctionTable: PgTableResource;
+    rightRelationName: string;
+    rightTable: PgTableResource;
+    allowsMultipleEdgesToNode?: boolean;
+}
+export interface MetaInflection {
+    tableType: (codec: PgCodec) => string;
+    _attributeName?: (input: {
+        attributeName: string;
+        codec: PgCodec;
+    }) => string;
+    camelCase?: (value: string) => string;
+    _manyToManyRelation?: (details: PgManyToManyRelationDetails) => string | null | undefined;
+    allRows?: (resource: PgTableResource) => string | null | undefined;
+    connectionType?: (tableType: string) => string | null | undefined;
+    edgeType?: (tableType: string) => string | null | undefined;
+    filterType?: (tableType: string) => string | null | undefined;
+    orderByType?: (tableType: string) => string | null | undefined;
+    conditionType?: (tableType: string) => string | null | undefined;
+    patchType?: (tableType: string) => string | null | undefined;
+    createInputType?: (resource: PgTableResource) => string | null | undefined;
+    createPayloadType?: (resource: PgTableResource) => string | null | undefined;
+    updatePayloadType?: (resource: PgTableResource) => string | null | undefined;
+    deletePayloadType?: (resource: PgTableResource) => string | null | undefined;
+    tableFieldName?: (resource: PgTableResource) => string | null | undefined;
+    createField?: (resource: PgTableResource) => string | null | undefined;
+    updateByKeys?: (resource: PgTableResource) => string | null | undefined;
+    deleteByKeys?: (resource: PgTableResource) => string | null | undefined;
+}
+export interface GqlTypeResolverBuild {
+    hasGraphQLTypeForPgCodec?: (codec: PgCodec, mode?: 'output' | 'input' | string) => boolean;
+    getGraphQLTypeNameByPgCodec?: (codec: PgCodec, mode?: 'output' | 'input' | string) => string | null | undefined;
+}
+export interface MetaBuild extends GqlTypeResolverBuild {
+    input: {
+        pgRegistry: {
+            pgResources: Record<string, PgTableResource>;
+        };
+    };
+    inflection: MetaInflection;
+    options?: {
+        pgSchemas?: string[];
+        [key: string]: unknown;
+    };
+    pgManyToManyRealtionshipsByResource?: Map<unknown, unknown>;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,19 @@
+/**
+ * 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 type { GraphileConfig } from 'graphile-config';
+import { cachedTablesMeta } from './meta-schema/cache';
+import { MetaSchemaPlugin } from './meta-schema/plugin';
+import { buildFieldMeta, pgTypeToGqlType } from './meta-schema/type-mappings';
+export { MetaSchemaPlugin };
+export declare const MetaSchemaPreset: GraphileConfig.Preset;
+/** @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/meta-schema.js

@@ -0,0 +1,20 @@
+/**
+ * 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

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

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

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

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

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