File

Parse. File

A Parse.File is a local representation of a file that is saved to the Parse cloud.

Constructor

new File(name, data, type, metadata, tags)

Parameters:
Name Type Description
name String

The file's name. This will be prefixed by a unique value once the file has finished saving. The file name must begin with an alphanumeric character, and consist of alphanumeric characters, periods, spaces, underscores, or dashes.
data Array

The data for the file, as either: 1. an Array of byte value Numbers or Uint8Array. 2. an Object like { base64: "..." } with a base64-encoded String. 3. an Object like { uri: "..." } with a uri String. 4. a File object selected with a file upload control. 5. (Node.js only) a Buffer. Uploaded as raw binary data instead of base64-encoding, reducing memory usage. Falls back to base64 JSON encoding if metadata or tags are set. 6. (Node.js only) a Readable stream, or a Web ReadableStream. Streamed as raw binary data directly into the upload request. Supports metadata, tags, and directory when Parse Server >= 9.5.0. For example:

var fileUploadControl = $("#profilePhotoFileUpload")[0];
if (fileUploadControl.files.length > 0) {
  var file = fileUploadControl.files[0];
  var name = "photo.jpg";
  var parseFile = new Parse.File(name, file);
  parseFile.save().then(function() {
    // The file has been saved to Parse.
  }, function(error) {
    // The file either could not be read, or could not be saved to Parse.
  });
}
type String

Optional Content-Type header to use for the file. If this is omitted, the content type will be inferred from the name's extension.
metadata object

Optional key value pairs to be stored with file object
tags object

Optional key value pairs to be stored with file object

Methods

addMetadata(key, value)

Sets metadata to be saved with file object. Adds to existing metadata. When used with a stream-based file, requires Parse Server >= 9.5.0.

Parameters:
Name Type Description
key string

key to store the metadata
value *

metadata

addTag(key, value)

Sets tags to be saved with file object. Adds to existing tags. When used with a stream-based file, requires Parse Server >= 9.5.0.

Parameters:
Name Type Description
key string

key to store tags
value *

tag

cancel()

Aborts the request if it has already been sent.

destroy(options) → {Promise}

Deletes the file from the Parse cloud. In Cloud Code and Node only with Master Key.

Parameters:
Name Type Description
options object

Valid options are:

  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
Returns:
Type:
Promise

Promise that is resolved when the delete finishes.

directory() → {string|undefined}

Gets the directory of the file. Requires Parse Server >= 9.4.0.

Returns:
Type:
string | undefined

(async) getData(options) → {Promise}

Return the data for the file, downloading it if not already present. Data is present if initialized with Byte Array, Base64 or Saved with Uri. Data is cleared if saved with File object selected with a file upload control

Parameters:
Name Type Description
options object
Name Type Attributes Description
progress function <optional>

callback for download progress

const parseFile = new Parse.File(name, file);
parseFile.getData({
  progress: (progressValue, loaded, total) => {
    if (progressValue !== null) {
      // Update the UI using progressValue
    }
  }
});
Returns:
Type:
Promise

Promise that is resolve with base64 data

metadata() → {object}

Gets the metadata of the file.

Returns:
Type:
object

name() → {string}

Gets the name of the file. Before save is called, this is the filename given by the user. After save is called, that name gets prefixed with a unique identifier.

Returns:
Type:
string

save(options) → {Promise|undefined}

Saves the file to the Parse cloud.

In Node.js, files created with Buffer or ReadableStream are uploaded as raw binary data, avoiding base64 encoding overhead. If metadata or tags are set on a Buffer-backed file, the upload falls back to base64 JSON encoding. Stream-backed files support metadata, tags, and directory when Parse Server >= 9.5.0.

Parameters:
Name Type Description
options object

Valid options are:

  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
  • progress: callback for upload progress. For example: 
    let parseFile = new Parse.File(name, file);
parseFile.save({
  progress: (progressValue, loaded, total) => {
    if (progressValue !== null) {
      // Update the UI using progressValue
    }
  }
});
  • maxUploadSize: Overrides the server's maxUploadSize for this upload. Requires the master key. Only supported for Buffer and Stream source types; files created from base64 strings, number arrays, Blobs, or URIs do not support this option. Requires Parse Server >= 9.5.0.
Returns:
Type:
Promise | undefined

Promise that is resolved when the save finishes.

setDirectory(directory)

Sets the directory where the file will be stored. Requires the Master Key when saving. Requires Parse Server >= 9.4.0; when used with a stream-based file, requires Parse Server >= 9.5.0.

Parameters:
Name Type Description
directory string

the directory path

setMetadata(metadata)

Sets metadata to be saved with file object. Overwrites existing metadata. When used with a stream-based file, requires Parse Server >= 9.5.0.

Parameters:
Name Type Description
metadata object

Key value pairs to be stored with file object

setTags(tags)

Sets tags to be saved with file object. Overwrites existing tags. When used with a stream-based file, requires Parse Server >= 9.5.0.

Parameters:
Name Type Description
tags object

Key value pairs to be stored with file object

tags() → {object}

Gets the tags of the file.

Returns:
Type:
object

url(options) → {string|undefined}

Gets the url of the file. It is only available after you save the file or after you get the file from a Parse.Object.

Parameters:
Name Type Description
options object

An object to specify url options

Name Type Attributes Description
forceSecure boolean <optional>

force the url to be secure
Returns:
Type:
string | undefined