@uppy/tus, @uppy/xhr-upload, @uppy/aws-s3: `metaFields` -> `allowedMetaFields` (#4023)

packages/@uppy/aws-s3/src/MiniXHRUpload.js

@@ -25,11 +25,11 @@ function setTypeInBlob (file) {
 }
 
 function addMetadata (formData, meta, opts) {
-  const metaFields = Array.isArray(opts.metaFields)
-    ? opts.metaFields
+  const allowedMetaFields = Array.isArray(opts.allowedMetaFields)
+    ? opts.allowedMetaFields
     // Send along all fields by default.
     : Object.keys(meta)
-  metaFields.forEach((item) => {
+  allowedMetaFields.forEach((item) => {
     formData.append(item, meta[item])
   })
 }
@@ -255,8 +255,8 @@ export default class MiniXHRUpload {
     const opts = this.#getOptions(file)
     const Client = file.remote.providerOptions.provider ? Provider : RequestClient
     const client = new Client(this.uppy, file.remote.providerOptions)
-    const metaFields = Array.isArray(opts.metaFields)
-      ? opts.metaFields
+    const allowedMetaFields = Array.isArray(opts.allowedMetaFields)
+      ? opts.allowedMetaFields
       // Send along all fields by default.
       : Object.keys(file.meta)
 
@@ -271,7 +271,7 @@ export default class MiniXHRUpload {
       endpoint: opts.endpoint,
       size: file.data.size,
       fieldname: opts.fieldName,
-      metadata: Object.fromEntries(metaFields.map(name => [name, file.meta[name]])),
+      metadata: Object.fromEntries(allowedMetaFields.map(name => [name, file.meta[name]])),
       httpMethod: opts.method,
       useFormData: opts.formData,
       headers: opts.headers,

packages/@uppy/aws-s3/src/index.js

@@ -115,13 +115,17 @@ export default class AwsS3 extends BasePlugin {
     const defaultOptions = {
       timeout: 30 * 1000,
       limit: 0,
-      metaFields: [], // have to opt in
+      allowedMetaFields: [], // have to opt in
       getUploadParameters: this.getUploadParameters.bind(this),
       companionHeaders: {},
     }
 
     this.opts = { ...defaultOptions, ...opts }
 
+    if (opts?.allowedMetaFields === undefined && 'metaFields' in this.opts) {
+      throw new Error('The `metaFields` option has been renamed to `allowedMetaFields`.')
+    }
+
     // TODO: remove i18n once we can depend on XHRUpload instead of MiniXHRUpload
     this.i18nInit()
 
@@ -144,7 +148,7 @@ export default class AwsS3 extends BasePlugin {
     const filename = file.meta.name
     const { type } = file.meta
     const metadata = Object.fromEntries(
-      this.opts.metaFields
+      this.opts.allowedMetaFields
         .filter(key => file.meta[key] != null)
         .map(key => [`metadata[${key}]`, file.meta[key].toString()]),
     )
@@ -198,7 +202,7 @@ export default class AwsS3 extends BasePlugin {
           method,
           formData: method.toLowerCase() === 'post',
           endpoint: url,
-          metaFields: fields ? Object.keys(fields) : [],
+          allowedMetaFields: fields ? Object.keys(fields) : [],
         }
 
         if (headers) {

packages/@uppy/aws-s3/types/index.d.ts

@@ -12,7 +12,7 @@ export interface AwsS3UploadParameters {
 export interface AwsS3Options extends PluginOptions {
     companionUrl?: string
     getUploadParameters?: (file: UppyFile) => MaybePromise<AwsS3UploadParameters>
-    metaFields?: string[]
+    allowedMetaFields?: string[] | null
     timeout?: number
     limit?: number
 }

packages/@uppy/transloadit/src/index.js

@@ -793,7 +793,7 @@ export default class Transloadit extends BasePlugin {
         // so it can't just reuse the same tus.Upload instance server-side.
         useFastRemoteRetry: false,
         // Only send Assembly metadata to the tus endpoint.
-        metaFields: ['assembly_url', 'filename', 'fieldname'],
+        allowedMetaFields: ['assembly_url', 'filename', 'fieldname'],
         // Pass the limit option to @uppy/tus
         limit: this.opts.limit,
         rateLimitedQueue: this.#rateLimitedQueue,

packages/@uppy/tus/src/index.js

@@ -81,6 +81,10 @@ export default class Tus extends BasePlugin {
     /** @type {import("..").TusOptions} */
     this.opts = { ...defaultOptions, ...opts }
 
+    if (opts?.allowedMetaFields === undefined && 'metaFields' in this.opts) {
+      throw new Error('The `metaFields` option has been renamed to `allowedMetaFields`.')
+    }
+
     if ('autoRetry' in opts) {
       throw new Error('The `autoRetry` option was deprecated and has been removed.')
     }
@@ -344,11 +348,11 @@ export default class Tus extends BasePlugin {
 
       /** @type {Record<string, string>} */
       const meta = {}
-      const metaFields = Array.isArray(opts.metaFields)
-        ? opts.metaFields
+      const allowedMetaFields = Array.isArray(opts.allowedMetaFields)
+        ? opts.allowedMetaFields
         // Send along all fields by default.
         : Object.keys(file.meta)
-      metaFields.forEach((item) => {
+      allowedMetaFields.forEach((item) => {
         meta[item] = file.meta[item]
       })
 

packages/@uppy/tus/types/index.d.ts

@@ -17,7 +17,7 @@ type TusUploadOptions = Pick<UploadOptions, Exclude<keyof UploadOptions,
 type Next = (err: Error | undefined, retryAttempt?: number, options?: TusOptions) => boolean
 
 export interface TusOptions extends PluginOptions, TusUploadOptions {
-    metaFields?: string[] | null
+    allowedMetaFields?: string[] | null
     limit?: number
     useFastRemoteRetry?: boolean
     withCredentials?: boolean

packages/@uppy/xhr-upload/src/index.js

@@ -63,7 +63,7 @@ export default class XHRUpload extends BasePlugin {
       formData: true,
       fieldName: opts.bundle ? 'files[]' : 'file',
       method: 'post',
-      metaFields: null,
+      allowedMetaFields: null,
       responseUrlFieldName: 'url',
       bundle: false,
       headers: {},
@@ -124,6 +124,10 @@ export default class XHRUpload extends BasePlugin {
       throw new Error('`opts.formData` must be true when `opts.bundle` is enabled.')
     }
 
+    if (opts?.allowedMetaFields === undefined && 'metaFields' in this.opts) {
+      throw new Error('The `metaFields` option has been renamed to `allowedMetaFields`.')
+    }
+
     this.uploaderEvents = Object.create(null)
   }
 
@@ -161,11 +165,11 @@ export default class XHRUpload extends BasePlugin {
 
   // eslint-disable-next-line class-methods-use-this
   addMetadata (formData, meta, opts) {
-    const metaFields = Array.isArray(opts.metaFields)
-      ? opts.metaFields
+    const allowedMetaFields = Array.isArray(opts.allowedMetaFields)
+      ? opts.allowedMetaFields
       : Object.keys(meta) // Send along all fields by default.
 
-    metaFields.forEach((item) => {
+    allowedMetaFields.forEach((item) => {
       formData.append(item, meta[item])
     })
   }
@@ -353,12 +357,12 @@ export default class XHRUpload extends BasePlugin {
       this.uppy.emit('upload-started', file)
 
       const fields = {}
-      const metaFields = Array.isArray(opts.metaFields)
-        ? opts.metaFields
+      const allowedMetaFields = Array.isArray(opts.allowedMetaFields)
+        ? opts.allowedMetaFields
         // Send along all fields by default.
         : Object.keys(file.meta)
 
-      metaFields.forEach((name) => {
+      allowedMetaFields.forEach((name) => {
         fields[name] = file.meta[name]
       })
 

packages/@uppy/xhr-upload/types/index.d.ts

@@ -10,7 +10,7 @@ export interface XHRUploadOptions extends PluginOptions {
     bundle?: boolean
     formData?: boolean
     headers?: Headers | ((file: UppyFile) => Headers)
-    metaFields?: string[]
+    allowedMetaFields?: string[] | null
     fieldName?: string
     timeout?: number
     responseUrlFieldName?: string

website/src/docs/aws-s3.md

@@ -66,12 +66,13 @@ uppy.use(AwsS3, {
 
 Custom headers that should be sent along to [Companion][companion docs] on every request.
 
-### `metaFields: []`
+### `allowedMetaFields: null`
 
-Pass an array of field names to specify the metadata fields that should be stored in S3 as Object Metadata. This takes values from each file’s `file.meta` property.
+Pass an array of field names to limit the metadata fields that will be added to upload as query parameters.
 
-* Set this to `['name']` to only send the name field.
-* Set this to an empty array `[]` (the default) to not send any fields.
+* Set this to `['name']` to only send the `name` field.
+* Set this to `null` (the default) to send _all_ metadata fields.
+* Set this to an empty array `[]` to not send any fields.
 
 ### `getUploadParameters(file)`
 

website/src/docs/tus.md

@@ -125,7 +125,7 @@ new Uppy().use(Tus, {
 })
 ```
 
-### `metaFields: null`
+### `allowedMetaFields: null`
 
 Pass an array of field names to limit the metadata fields that will be added to uploads as [Tus Metadata](https://tus.io/protocols/resumable-upload.html#upload-metadata).
 

website/src/docs/xhr-upload.md

@@ -67,9 +67,9 @@ When [`formData`](#formData-true) is set to true, this is used as the form field
 name for the file to be uploaded. It defaults to `'files[]'` if `bundle` option
 is set to `true`, otherwise it defaults to `'file'`.
 
-### `metaFields: null`
+### `allowedMetaFields: null`
 
-Pass an array of field names to limit the metadata fields that will be sent to the endpoint as form fields.
+Pass an array of field names to limit the metadata fields that will be added to upload.
 
 * Set this to `['name']` to only send the `name` field.
 * Set this to `null` (the default) to send _all_ metadata fields.