graphile-upload-plugin 1.1.0 → 2.2.0

package/README.md

@@ -1,85 +1,6 @@
 # graphile-upload-plugin
 
-<p align="center" width="100%">
-  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
-</p>
-
-<p align="center" width="100%">
-  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
-    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
-  </a>
-  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE">
-    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
-  </a>
-  <a href="https://www.npmjs.com/package/graphile-upload-plugin">
-    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-upload-plugin%2Fpackage.json"/>
-  </a>
-</p>
-
-**`graphile-upload-plugin`** adds an `Upload` scalar and upload field resolvers for PostGraphile, letting you store uploaded metadata in PostgreSQL columns.
-
-## 🚀 Installation
-
-```bash
-pnpm add graphile-upload-plugin
-```
-
-## ✨ Features
-
-- Adds the `Upload` scalar to PostGraphile
-- Supports upload resolvers by type or smart comment tag
-- Flexible resolver hook to store files anywhere (S3, local, etc.)
-
-## 📦 Usage
-
-```ts
-import express from 'express';
-import { postgraphile } from 'postgraphile';
-import UploadPostGraphilePlugin from 'graphile-upload-plugin';
-
-const app = express();
-app.use(
-  postgraphile(process.env.DATABASE_URL, ['app_public'], {
-    appendPlugins: [UploadPostGraphilePlugin],
-    graphileBuildOptions: {
-      uploadFieldDefinitions: [
-        {
-          name: 'upload',
-          namespaceName: 'public',
-          type: 'JSON',
-          resolve: async (upload, args, context, info) => {
-            // Handle upload
-            return { url: '...', size: upload.size };
-          },
-        },
-        {
-          tag: 'upload',
-          resolve: async (upload, args, context, info) => {
-            // Handle upload by tag
-            return { url: '...' };
-          },
-        },
-      ],
-    },
-  })
-);
-```
-
-## 🔧 Configuration
-
-The plugin accepts `uploadFieldDefinitions` in `graphileBuildOptions`:
-
-- **By type**: Match PostgreSQL types by `name` and `namespaceName`
-- **By tag**: Match columns via smart comments (e.g., `@upload`)
-
-Each definition requires a `resolve` function that processes the upload and returns the value to store in the database.
-
-## 🧪 Testing
-
-```sh
-# requires a local Postgres available (defaults to postgres/password@localhost:5432)
-pnpm --filter graphile-upload-plugin test
-```
+File upload support for PostGraphile v5.
 
 ---
 

package/esm/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PostGraphile v5 Upload Plugin
+ *
+ * Provides file upload capabilities for PostGraphile v5 mutations.
+ *
+ * @example
+ * ```typescript
+ * import { UploadPlugin, UploadPreset } from 'graphile-upload-plugin';
+ *
+ * // Option 1: Use the preset (recommended)
+ * const preset = {
+ *   extends: [
+ *     UploadPreset({
+ *       uploadFieldDefinitions: [
+ *         { tag: 'upload', resolve: myUploadResolver },
+ *       ],
+ *     }),
+ *   ],
+ * };
+ *
+ * // Option 2: Use the plugin directly
+ * const plugin = UploadPlugin({
+ *   uploadFieldDefinitions: [
+ *     { tag: 'upload', resolve: myUploadResolver },
+ *   ],
+ * });
+ * ```
+ */
+export { UploadPlugin, createUploadPlugin } from './plugin';
+export { UploadPreset } from './preset';
+export type { FileUpload, UploadFieldDefinition, UploadPluginInfo, UploadPluginOptions, UploadResolver } from './types';

package/esm/index.js

@@ -1,4 +1,30 @@
-import UploadPostGraphilePlugin from './plugin';
-export { UploadPostGraphilePlugin, };
-export { Uploader } from './resolvers/upload';
-export default UploadPostGraphilePlugin;
+/**
+ * PostGraphile v5 Upload Plugin
+ *
+ * Provides file upload capabilities for PostGraphile v5 mutations.
+ *
+ * @example
+ * ```typescript
+ * import { UploadPlugin, UploadPreset } from 'graphile-upload-plugin';
+ *
+ * // Option 1: Use the preset (recommended)
+ * const preset = {
+ *   extends: [
+ *     UploadPreset({
+ *       uploadFieldDefinitions: [
+ *         { tag: 'upload', resolve: myUploadResolver },
+ *       ],
+ *     }),
+ *   ],
+ * };
+ *
+ * // Option 2: Use the plugin directly
+ * const plugin = UploadPlugin({
+ *   uploadFieldDefinitions: [
+ *     { tag: 'upload', resolve: myUploadResolver },
+ *   ],
+ * });
+ * ```
+ */
+export { UploadPlugin, createUploadPlugin } from './plugin';
+export { UploadPreset } from './preset';

package/esm/plugin.d.ts

@@ -0,0 +1,32 @@
+/**
+ * PostGraphile v5 Upload Plugin
+ *
+ * Adds file upload support to PostGraphile v5 mutations. For columns that match
+ * the configured upload field definitions (by PG type name/namespace or by smart
+ * tag), this plugin:
+ *
+ * 1. Registers a GraphQL `Upload` scalar type
+ * 2. Adds `*Upload` input fields on mutation input types
+ * 3. Wraps mutation field resolvers to process file uploads before the mutation
+ *    executes, calling the user-supplied resolver for each upload
+ *
+ * In v5, the `GraphQLObjectType_fields_field` hook wraps the `resolve` function
+ * (which still exists on mutation fields alongside `plan`) to intercept uploads
+ * at the HTTP layer before the plan executes.
+ *
+ * COMPATIBILITY NOTE:
+ * This plugin uses v4-style resolver wrapping via GraphQLObjectType_fields_field hook.
+ * grafserv v5 supports this through its backwards-compatibility layer.
+ * This plugin requires grafserv's resolver support to be enabled (default in v5 RC).
+ * It will NOT work in a pure grafast plan-only execution context.
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+import type { UploadPluginOptions } from './types';
+/**
+ * Creates the Upload plugin with the given options.
+ */
+export declare function createUploadPlugin(options?: UploadPluginOptions): GraphileConfig.Plugin;
+export declare const UploadPlugin: typeof createUploadPlugin;
+export default UploadPlugin;

package/esm/plugin.js

@@ -1,158 +1,260 @@
-// PostGraphile plugin
-const UploadPostGraphilePlugin = (builder, opts = {}) => {
-    const { uploadFieldDefinitions = [] } = opts;
-    // Determine whether a table attribute should be treated as an Upload according to configuration
-    const relevantUploadType = (attr) => {
-        const types = uploadFieldDefinitions.filter(({ name, namespaceName, tag }) => (name &&
-            namespaceName &&
-            attr.type?.name === name &&
-            attr.type?.namespaceName === namespaceName) ||
-            (tag && attr.tags?.[tag]));
-        if (types.length === 1) {
-            return types[0];
+/**
+ * PostGraphile v5 Upload Plugin
+ *
+ * Adds file upload support to PostGraphile v5 mutations. For columns that match
+ * the configured upload field definitions (by PG type name/namespace or by smart
+ * tag), this plugin:
+ *
+ * 1. Registers a GraphQL `Upload` scalar type
+ * 2. Adds `*Upload` input fields on mutation input types
+ * 3. Wraps mutation field resolvers to process file uploads before the mutation
+ *    executes, calling the user-supplied resolver for each upload
+ *
+ * In v5, the `GraphQLObjectType_fields_field` hook wraps the `resolve` function
+ * (which still exists on mutation fields alongside `plan`) to intercept uploads
+ * at the HTTP layer before the plan executes.
+ *
+ * COMPATIBILITY NOTE:
+ * This plugin uses v4-style resolver wrapping via GraphQLObjectType_fields_field hook.
+ * grafserv v5 supports this through its backwards-compatibility layer.
+ * This plugin requires grafserv's resolver support to be enabled (default in v5 RC).
+ * It will NOT work in a pure grafast plan-only execution context.
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import { Transform } from 'stream';
+/**
+ * Determines whether a codec attribute matches an upload field definition.
+ * Returns the matching definition or undefined.
+ */
+function relevantUploadType(attribute, uploadFieldDefinitions) {
+    const types = uploadFieldDefinitions.filter(({ name, namespaceName, tag }) => {
+        if (name && namespaceName) {
+            // Type-name based matching: check the attribute's codec PG extension metadata
+            const pgExt = attribute.codec?.extensions?.pg;
+            if (pgExt && pgExt.name === name && pgExt.schemaName === namespaceName) {
+                return true;
+            }
+            // Fallback: check codec name directly
+            if (attribute.codec?.name === name) {
+                return true;
+            }
         }
-        else if (types.length > 1) {
-            throw new Error('Upload field definitions are ambiguous');
+        if (tag) {
+            // Smart-tag based matching: check if the attribute has the specified tag
+            const tags = attribute.extensions?.tags;
+            if (tags && tags[tag]) {
+                return true;
+            }
         }
-        return undefined;
-    };
-    builder.hook('build', (input, build) => {
-        const { addType, graphql: { GraphQLScalarType, GraphQLError }, } = build;
-        const GraphQLUpload = new GraphQLScalarType({
-            name: 'Upload',
-            description: 'The `Upload` scalar type represents a file upload.',
-            parseValue(value) {
-                // The value should be an object with a `.promise` that resolves to the file upload
-                const maybe = value;
-                if (maybe &&
-                    maybe.promise &&
-                    typeof maybe.promise.then === 'function') {
-                    return maybe.promise;
-                }
-                throw new GraphQLError('Upload value invalid.');
-            },
-            parseLiteral(ast) {
-                throw new GraphQLError('Upload literal unsupported.', ast);
-            },
-            serialize() {
-                throw new GraphQLError('Upload serialization unsupported.');
-            },
-        });
-        addType(GraphQLUpload);
-        // Override the internal types for configured upload-backed columns
-        uploadFieldDefinitions.forEach(({ name, namespaceName, type }) => {
-            if (!name || !type || !namespaceName)
-                return; // tag-based or incomplete definitions
-            const theType = build.pgIntrospectionResultsByKind.type.find((typ) => typ.name === name && typ.namespaceName === namespaceName);
-            if (theType) {
-                build.pgRegisterGqlTypeByTypeId(theType.id, () => build.getTypeByName(type));
+        return false;
+    });
+    if (types.length === 1) {
+        return types[0];
+    }
+    else if (types.length > 1) {
+        throw new Error('Upload field definitions are ambiguous');
+    }
+    return undefined;
+}
+function createSizeLimitStream(source, maxFileSize) {
+    let bytesRead = 0;
+    const limiter = new Transform({
+        transform(chunk, _encoding, callback) {
+            const chunkSize = Buffer.isBuffer(chunk)
+                ? chunk.length
+                : Buffer.byteLength(String(chunk));
+            bytesRead += chunkSize;
+            if (bytesRead > maxFileSize) {
+                callback(new Error(`File exceeds maximum size of ${maxFileSize} bytes`));
+                return;
             }
-        });
-        return input;
+            callback(null, chunk);
+        }
     });
-    builder.hook('inflection', (inflection, build) => {
-        return build.extend(inflection, {
-            // NO ARROW FUNCTIONS HERE (this)
-            uploadColumn(attr) {
-                return this.column(attr) + 'Upload';
-            },
-        });
+    // Ensure source stream errors are always forwarded to the consumer stream.
+    source.on('error', (error) => {
+        limiter.destroy(error);
     });
-    // Add Upload input fields alongside matching columns
-    builder.hook('GraphQLInputObjectType:fields', (fields, build, context) => {
-        const { scope: { isPgRowType, pgIntrospection: table }, } = context;
-        if (!isPgRowType || !table || table.kind !== 'class') {
-            return fields;
+    limiter.on('error', (error) => {
+        if (!source.destroyed) {
+            source.destroy(error);
         }
-        return build.extend(fields, table.attributes.reduce((memo, attr) => {
-            if (!build.pgColumnFilter(attr, build, context))
-                return memo;
-            const action = context.scope.isPgBaseInput
-                ? 'base'
-                : context.scope.isPgPatch
-                    ? 'update'
-                    : 'create';
-            if (build.pgOmit(attr, action))
-                return memo;
-            if (attr.identity === 'a')
-                return memo;
-            if (!relevantUploadType(attr)) {
-                return memo;
-            }
-            const fieldName = build.inflection.uploadColumn(attr);
-            if (memo[fieldName]) {
-                throw new Error(`Two columns produce the same GraphQL field name '${fieldName}' on class '${table.namespaceName}.${table.name}'; one of them is '${attr.name}'`);
-            }
-            memo = build.extend(memo, {
-                [fieldName]: context.fieldWithHooks(fieldName, {
-                    description: attr.description,
-                    type: build.getTypeByName('Upload'),
-                }, { pgFieldIntrospection: attr, isPgUploadField: true }),
-            }, `Adding field for ${build.describePgEntity(attr)}. You can rename this field with a 'Smart Comment':\n\n  ${build.sqlCommentByAddingTags(attr, {
-                name: 'newNameHere',
-            })}`);
-            return memo;
-        }, {}), `Adding columns to '${build.describePgEntity(table)}'`);
     });
-    builder.hook('GraphQLObjectType:fields:field', (field, build, context) => {
-        const { pgIntrospectionResultsByKind: introspectionResultsByKind, inflection, } = build;
-        const { scope: { isRootMutation, fieldName, pgFieldIntrospection: table }, } = context;
-        if (!isRootMutation || !table) {
-            return field;
+    source.pipe(limiter);
+    return limiter;
+}
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+function wrapUploadForMaxFileSize(upload, maxFileSize) {
+    if (!maxFileSize) {
+        return upload;
+    }
+    return {
+        ...upload,
+        createReadStream() {
+            const source = upload.createReadStream();
+            return createSizeLimitStream(source, maxFileSize);
         }
-        // It's possible that `resolve` isn't specified on a field, so in that case
-        // we fall back to a default resolver.
-        const defaultResolver = (obj) => obj[fieldName];
-        // Extract the old resolver from `field`
-        const { resolve: oldResolve = defaultResolver, ...rest } = field; // GraphQLFieldConfig
-        const tags = {};
-        const types = {};
-        const originals = {};
-        const uploadResolversByFieldName = introspectionResultsByKind.attribute
-            .filter((attr) => attr.classId === table.id)
-            .reduce((memo, attr) => {
-            // first, try to directly match the types here
-            const typeMatched = relevantUploadType(attr);
-            if (typeMatched) {
-                const fieldName = inflection.column(attr);
-                const uploadFieldName = inflection.uploadColumn(attr);
-                memo[uploadFieldName] = typeMatched.resolve;
-                tags[uploadFieldName] = attr.tags;
-                types[uploadFieldName] = attr.type.name;
-                originals[uploadFieldName] = fieldName;
-            }
-            return memo;
-        }, {});
-        return {
-            // Copy over everything except 'resolve'
-            ...rest,
-            // Add our new resolver which wraps the old resolver
-            async resolve(source, args, context, info) {
-                // Recursively check for Upload promises to resolve
-                async function resolvePromises(obj) {
-                    for (const key of Object.keys(obj)) {
-                        if (obj[key] instanceof Promise) {
-                            if (uploadResolversByFieldName[key]) {
-                                const upload = await obj[key];
-                                // eslint-disable-next-line require-atomic-updates
-                                obj[originals[key]] = await uploadResolversByFieldName[key](upload, args, context, {
-                                    ...info,
-                                    uploadPlugin: { tags: tags[key], type: types[key] },
-                                });
+    };
+}
+/**
+ * Creates the Upload plugin with the given options.
+ */
+export function createUploadPlugin(options = {}) {
+    const { uploadFieldDefinitions = [], maxFileSize } = options;
+    return {
+        name: 'UploadPlugin',
+        version: '2.0.0',
+        description: 'File upload support for PostGraphile v5',
+        after: ['PgAttributesPlugin', 'PgMutationCreatePlugin', 'PgMutationUpdateDeletePlugin'],
+        schema: {
+            hooks: {
+                // Register the Upload scalar type
+                init(_, build) {
+                    const { graphql: { GraphQLScalarType, GraphQLError } } = build;
+                    const GraphQLUpload = new GraphQLScalarType({
+                        name: 'Upload',
+                        description: 'The `Upload` scalar type represents a file upload.',
+                        parseValue(value) {
+                            const maybe = value;
+                            if (maybe &&
+                                maybe.promise &&
+                                typeof maybe.promise.then === 'function') {
+                                return maybe.promise;
                             }
+                            throw new GraphQLError('Upload value invalid.');
+                        },
+                        parseLiteral(_ast) {
+                            throw new GraphQLError('Upload literal unsupported.');
+                        },
+                        serialize() {
+                            throw new GraphQLError('Upload serialization unsupported.');
                         }
-                        else if (obj[key] !== null && typeof obj[key] === 'object') {
-                            await resolvePromises(obj[key]);
+                    });
+                    build.registerScalarType(GraphQLUpload.name, {}, () => GraphQLUpload, 'UploadPlugin registering Upload scalar');
+                    return _;
+                },
+                // Add *Upload input fields alongside matching columns on mutation input types
+                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 UploadType = build.getTypeByName('Upload');
+                    if (!UploadType) {
+                        return fields;
+                    }
+                    let newFields = fields;
+                    for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
+                        const matchedDef = relevantUploadType(attribute, uploadFieldDefinitions);
+                        if (!matchedDef)
+                            continue;
+                        // Generate the upload field name: columnName + 'Upload'
+                        const baseFieldName = build.inflection.attribute({
+                            codec: pgCodec,
+                            attributeName
+                        });
+                        const uploadFieldName = baseFieldName + 'Upload';
+                        if (newFields[uploadFieldName]) {
+                            throw new Error(`Two columns produce the same upload field name '${uploadFieldName}' ` +
+                                `on codec '${pgCodec.name}'; one of them is '${attributeName}'`);
                         }
+                        newFields = build.extend(newFields, {
+                            [uploadFieldName]: context.fieldWithHooks({ fieldName: uploadFieldName, isPgUploadField: true }, {
+                                description: attribute.description
+                                    ? `Upload for ${attribute.description}`
+                                    : `File upload for the \`${baseFieldName}\` field.`,
+                                type: UploadType
+                            })
+                        }, `UploadPlugin adding upload field '${uploadFieldName}' for ` +
+                            `attribute '${attributeName}' on '${pgCodec.name}'`);
+                    }
+                    return newFields;
+                },
+                // Wrap mutation field resolvers to process file uploads
+                GraphQLObjectType_fields_field(field, build, context) {
+                    const { scope: { isRootMutation, fieldName, pgCodec } } = context;
+                    if (!isRootMutation || !pgCodec || !pgCodec.attributes) {
+                        return field;
                     }
+                    // Build the mapping of upload field names to their resolvers
+                    const uploadResolversByFieldName = {};
+                    const tags = {};
+                    const types = {};
+                    const originals = {};
+                    for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
+                        const matchedDef = relevantUploadType(attribute, uploadFieldDefinitions);
+                        if (!matchedDef)
+                            continue;
+                        const baseFieldName = build.inflection.attribute({
+                            codec: pgCodec,
+                            attributeName
+                        });
+                        const uploadFieldName = baseFieldName + 'Upload';
+                        uploadResolversByFieldName[uploadFieldName] = matchedDef.resolve;
+                        tags[uploadFieldName] = attribute.extensions?.tags || {};
+                        types[uploadFieldName] = matchedDef.type || '';
+                        originals[uploadFieldName] = baseFieldName;
+                    }
+                    // If no upload fields match this mutation's codec, skip wrapping
+                    if (Object.keys(uploadResolversByFieldName).length === 0) {
+                        return field;
+                    }
+                    const defaultResolver = (obj) => obj[fieldName];
+                    const { resolve: oldResolve = defaultResolver, ...rest } = field;
+                    return {
+                        ...rest,
+                        async resolve(source, args, context, info) {
+                            // Recursively walk args to find and resolve upload thenables.
+                            async function resolvePromises(obj) {
+                                const pending = [];
+                                for (const key of Object.keys(obj)) {
+                                    const value = obj[key];
+                                    if (isThenable(value)) {
+                                        const resolver = uploadResolversByFieldName[key];
+                                        if (!resolver)
+                                            continue;
+                                        pending.push((async () => {
+                                            const upload = await value;
+                                            const uploadForResolver = wrapUploadForMaxFileSize(upload, maxFileSize);
+                                            obj[originals[key]] = await resolver(uploadForResolver, args, context, {
+                                                ...info,
+                                                uploadPlugin: {
+                                                    tags: tags[key],
+                                                    type: types[key]
+                                                }
+                                            });
+                                            // Remove consumed `*Upload` key so downstream resolvers only
+                                            // see the materialized column value.
+                                            delete obj[key];
+                                        })());
+                                        continue;
+                                    }
+                                    if (value !== null && typeof value === 'object') {
+                                        pending.push(resolvePromises(value));
+                                    }
+                                }
+                                if (pending.length > 0) {
+                                    await Promise.all(pending);
+                                }
+                            }
+                            await resolvePromises(args);
+                            return oldResolve(source, args, context, info);
+                        }
+                    };
                 }
-                await resolvePromises(args);
-                // Call the old resolver
-                const oldResolveResult = await oldResolve(source, args, context, info);
-                // Finally return the result.
-                return oldResolveResult;
-            },
-        };
-    });
-};
-export default UploadPostGraphilePlugin;
+            }
+        }
+    };
+}
+export const UploadPlugin = createUploadPlugin;
+export default UploadPlugin;

package/esm/preset.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PostGraphile v5 Upload Preset
+ *
+ * Provides a convenient preset for including upload support in PostGraphile.
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { UploadPluginOptions } from './types';
+/**
+ * Creates a preset that includes the upload plugin with the given options.
+ *
+ * @example
+ * ```typescript
+ * import { UploadPreset } from 'graphile-upload-plugin';
+ *
+ * const preset = {
+ *   extends: [
+ *     UploadPreset({
+ *       uploadFieldDefinitions: [
+ *         {
+ *           tag: 'upload',
+ *           resolve: async (upload, args, context, info) => {
+ *             // Process the upload and return the value to store in the column
+ *             const stream = upload.createReadStream();
+ *             const url = await uploadToStorage(stream, upload.filename);
+ *             return url;
+ *           },
+ *         },
+ *       ],
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export declare function UploadPreset(options?: UploadPluginOptions): GraphileConfig.Preset;
+export default UploadPreset;