graphile-upload-plugin 1.1.0 → 2.2.0

package/esm/preset.js

@@ -0,0 +1,38 @@
+/**
+ * PostGraphile v5 Upload Preset
+ *
+ * Provides a convenient preset for including upload support in PostGraphile.
+ */
+import { createUploadPlugin } from './plugin';
+/**
+ * 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 function UploadPreset(options = {}) {
+    return {
+        plugins: [createUploadPlugin(options)]
+    };
+}
+export default UploadPreset;

package/esm/types.d.ts

@@ -0,0 +1,70 @@
+import type { Readable } from 'stream';
+/**
+ * Represents a file upload received from the client.
+ */
+export interface FileUpload {
+    filename: string;
+    mimetype?: string;
+    encoding?: string;
+    createReadStream: () => Readable;
+}
+/**
+ * Additional metadata passed to the upload resolver via the info parameter.
+ */
+export interface UploadPluginInfo {
+    tags: Record<string, any>;
+    type?: string;
+}
+/**
+ * A function that processes an uploaded file and returns the value to store
+ * in the database column (e.g., a URL string or a JSON object).
+ *
+ * Called with the upload stream. The filename comes from user input
+ * and MUST be sanitized by the implementation before use in file paths
+ * or storage keys (e.g., strip path separators, limit length, validate characters).
+ */
+export type UploadResolver = (upload: FileUpload, args: any, context: any, info: {
+    uploadPlugin: UploadPluginInfo;
+}) => Promise<any>;
+/**
+ * Defines which columns should receive upload handling.
+ *
+ * Two forms are supported:
+ * 1. Type-name based: match columns by their PG type name and namespace.
+ * 2. Smart-tag based: match columns that have a specific smart tag.
+ */
+export type UploadFieldDefinition = {
+    /** PG type name (e.g., 'text') */
+    name: string;
+    /** PG schema name (e.g., 'pg_catalog') */
+    namespaceName: string;
+    /** The GraphQL type name to override to (e.g., 'Upload') */
+    type: string;
+    /** The resolver function to process the upload */
+    resolve: UploadResolver;
+    tag?: never;
+} | {
+    /** Smart tag name to match (e.g., '@upload') */
+    tag: string;
+    /** The resolver function to process the upload */
+    resolve: UploadResolver;
+    name?: never;
+    namespaceName?: never;
+    /** Optional type hint for the resolver */
+    type?: string;
+};
+/**
+ * Plugin options for the upload plugin.
+ */
+export interface UploadPluginOptions {
+    /**
+     * Array of upload field definitions that configure which columns
+     * should get upload handling.
+     */
+    uploadFieldDefinitions?: UploadFieldDefinition[];
+    /**
+     * Maximum file size in bytes. If set, streams exceeding this are rejected.
+     * Default: no limit (rely on graphql-upload middleware).
+     */
+    maxFileSize?: number;
+}

package/esm/types.js

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

package/index.d.ts

@@ -1,4 +1,31 @@
-import UploadPostGraphilePlugin, { type FileUpload, type UploadPluginInfo, type UploadResolver, type UploadFieldDefinition } from './plugin';
-export { UploadPostGraphilePlugin, type FileUpload, type UploadPluginInfo, type UploadResolver, type UploadFieldDefinition, };
-export { Uploader, type UploaderOptions } 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';
+export type { FileUpload, UploadFieldDefinition, UploadPluginInfo, UploadPluginOptions, UploadResolver } from './types';

package/index.js

@@ -1,11 +1,36 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+/**
+ * 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 },
+ *   ],
+ * });
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Uploader = exports.UploadPostGraphilePlugin = void 0;
-const plugin_1 = __importDefault(require("./plugin"));
-exports.UploadPostGraphilePlugin = plugin_1.default;
-var upload_1 = require("./resolvers/upload");
-Object.defineProperty(exports, "Uploader", { enumerable: true, get: function () { return upload_1.Uploader; } });
-exports.default = plugin_1.default;
+exports.UploadPreset = exports.createUploadPlugin = exports.UploadPlugin = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "UploadPlugin", { enumerable: true, get: function () { return plugin_1.UploadPlugin; } });
+Object.defineProperty(exports, "createUploadPlugin", { enumerable: true, get: function () { return plugin_1.createUploadPlugin; } });
+var preset_1 = require("./preset");
+Object.defineProperty(exports, "UploadPreset", { enumerable: true, get: function () { return preset_1.UploadPreset; } });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "graphile-upload-plugin",
-  "version": "1.1.0",
-  "description": "Graphile upload plugin for PostGraphile",
+  "version": "2.2.0",
+  "description": "File upload support for PostGraphile v5",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
   "license": "MIT",
@@ -10,12 +10,11 @@
   "types": "index.d.ts",
   "scripts": {
     "clean": "makage clean",
-    "prepack": "pnpm run build",
+    "prepack": "npm run build",
     "build": "makage build",
     "build:dev": "makage build --dev",
     "lint": "eslint . --fix",
-    "test": "jest --passWithNoTests",
-    "test:watch": "jest --watch"
+    "test": "jest"
   },
   "publishConfig": {
     "access": "public",
@@ -29,32 +28,26 @@
     "postgraphile",
     "graphile",
     "constructive",
-    "pgpm",
     "plugin",
     "postgres",
     "graphql",
-    "upload"
+    "upload",
+    "file-upload",
+    "s3"
   ],
   "bugs": {
     "url": "https://github.com/constructive-io/constructive/issues"
   },
-  "devDependencies": {
-    "@aws-sdk/client-s3": "^3.971.0",
-    "@constructive-io/graphql-env": "^2.10.0",
-    "@constructive-io/s3-utils": "^2.6.0",
-    "@types/pg": "^8.16.0",
-    "graphile-test": "^3.1.0",
-    "graphql-tag": "^2.12.6",
-    "makage": "^0.1.12",
-    "pgsql-test": "^3.1.0",
-    "ts-jest": "^29.4.6"
+  "peerDependencies": {
+    "graphile-build": "^5.0.0-rc.4",
+    "graphile-build-pg": "^5.0.0-rc.5",
+    "graphile-config": "^1.0.0-rc.5",
+    "graphql": "^16.9.0",
+    "postgraphile": "^5.0.0-rc.4"
   },
-  "dependencies": {
-    "@constructive-io/s3-streamer": "^2.11.0",
-    "@constructive-io/upload-names": "^2.5.0",
-    "@pgpmjs/types": "^2.16.0",
-    "graphile-build": "^4.14.1",
-    "graphql": "15.10.1"
+  "devDependencies": {
+    "@types/node": "^22.19.1",
+    "makage": "^0.1.10"
   },
-  "gitHead": "048188f6b43ffaa6146e7694b2b0d35d34cb2945"
+  "gitHead": "b758178b808ce0bf451e86c0bd7e92079155db7c"
 }

package/plugin.d.ts

@@ -1,31 +1,32 @@
-import type { ReadStream } from 'fs';
-import type { Plugin } from 'graphile-build';
-import type { GraphQLResolveInfo } from 'graphql';
-export interface FileUpload {
-    filename: string;
-    mimetype?: string;
-    encoding?: string;
-    createReadStream: () => ReadStream;
-}
-export interface UploadPluginInfo {
-    tags: Record<string, any>;
-    type?: string;
-}
-export type UploadResolver = (upload: FileUpload, args: any, context: any, info: GraphQLResolveInfo & {
-    uploadPlugin: UploadPluginInfo;
-}) => Promise<any>;
-export type UploadFieldDefinition = {
-    name: string;
-    namespaceName: string;
-    type: string;
-    resolve: UploadResolver;
-    tag?: never;
-} | {
-    tag: string;
-    resolve: UploadResolver;
-    name?: never;
-    namespaceName?: never;
-    type?: string;
-};
-declare const UploadPostGraphilePlugin: Plugin;
-export default UploadPostGraphilePlugin;
+/**
+ * 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;