Skip to main content

Files

Get file info​

You can get file info by calling the getInfo method. It returns the basic metadata information of a file.

const storageName = "default";
const bucketName = "profile-images";
const fileName = "rooby-avatar.png";

// Returns the metadata information about the file
let result = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file(fileName)
  .getInfo();
Example response
{
  "id": "fl-234e3rwrwr",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "rooby-avatar.png",
  "size": 212233,
  "mimeType": "image/png",
  "isPublic": true,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {
    "size": "small"
  }
}

Check whether file exists​

You can check whether the file exists by calling the exists method. It checks whether the file exists or not and returns true if file exists, otherwise false .

const storageName = "default";
const bucketName = "profile-images";

// Checks whether the `rooby-avatar.png` file exists
// in `profile-images` bucket or not
let result = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file("rooby-avatar.png")
  .exists();

Copy file​

You can copy the file to another path by calling the copyTo method in the same bucket. If there already exists a file with the same name in destination path, it throws an error.

const storageName = "default";
const bucketName = "profile-images";
const toPath = "archive/rooby-avatar.png";

// Copies the file to another bucket
let result = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file("rooby-avatar.png")
  .copyTo(toPath);
Example response
{
  "id": "fl-343rwsf324",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "archive/rooby-avatar.png",
  "size": 212233,
  "mimeType": "image/png",
  "isPublic": true,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {
    "size": "small"
  }
}

Parameters​

Here you can find parameters for the copyTo method.

#

Name

Data type

Required

Description

1toPathstringYesThe new file path where this file will be copied to.

Move file​

You can move the file to another path by calling the moveTo method in the same bucket. The file will be removed from its current path and will be moved to its new path. If there already exists a file with the same name in destination path, it throws an error.

const storageName = "default";
const bucketName = "profile-images";
const toPath = "backup/rooby-avatar.png";

// Moves the file to another bucket
let result = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file("rooby.png")
  .moveTo(toPath);
Example response
{
  "id": "fl-234e3rwrwr",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "backup/rooby-avatar.pn",
  "size": 212233,
  "mimeType": "image/png",
  "isPublic": true,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {
    "size": "small"
  }
}

Parameters​

Here you can find parameters for the moveTo method.

#

Name

Data type

Required

Description

1toPathstringYesThe new file path where this file will be moved to.

Make file public​

You can make the file public by calling the makePublic method. It changes the privacy of the file to true.

const storageName = "default";
const bucketName = "profile-images";

// Makes the file public
let result = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file("rooby-avatar.png")
  .makePublic();
Example response
{
  "id": "fl-343rwsf324",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "rooby-avatar.png",
  "size": 212233,
  "mimeType": "image/png",
  "isPublic": true,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {
    "size": "small"
  }
}

Make file private​

You can make the file private by calling the makePrivate method. It changes the privacy of the file to false.

const storageName = "default";
const bucketName = "profile-images";

// Makes the file private
let result = await agnost.storage
  .bucket(bucketName)
  .file("rooby-avatar.png")
  .makePrivate();
Example response
{
  "id": "fl-343rwsf324",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "rooby-avatar.png",
  "size": 212233,
  "mimeType": "image/png",
  "isPublic": false,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {
    "size": "small"
  }
}

Add tag to file​

You can add your own tags to each uploaded file.

const storageName = "default";
const bucketName = "profile-images";

// Set a tag for a file
const key = "quality"
const value = "high"

let result = await agnost.storage
  .bucket(bucketName)
  .file("rooby-avatar.png")
  .setTag(key, value);
Example response
{
  "id": "fl-343rwsf324",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "rooby-avatar.png",
  "size": 212233,
  "mimeType": "image/png",
  "isPublic": true,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {
    "size": "small",
    "quality": "high"
  }
}

Parameters​

Here you can find parameters for the setTag method.

#

Name

Data type

Required

Description

1keystringYesKey (name) of tag.
2valueanyYesValue of tag.

Remove tag from file​

You can also remove tags (e.g., your custom metadata associated with your files) from your files.

const storageName = "default";
const bucketName = "profile-images";

const key = "size"

let result = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file("rooby-avatar.png")
  .removeTag(key);
Example response
{
  "id": "fl-343rwsf324",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "rooby-avatar.png",
  "size": 212233,
  "mimeType": "image/png",
  "isPublic": true,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {
    "quality": "high
  }
}

Parameters​

Here you can find parameters for the removeTag method.

#

Name

Data type

Required

Description

1tagstringYesName of the tag to remove from file's metadata.

Remove all tags from file​

You can also remove all tags (e.g., your custom metadata associated with your files) from your files.

const storageName = "default";
const bucketName = "profile-images";

const key = "quality"

let result = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file("rooby-avatar.png")
  .removeAllTags(key);
Example response
{
  "id": "fl-343rwsf324",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "rooby-avatar.png",
  "size": 212233,
  "mimeType": "image/png",
  "isPublic": true,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {}
}

Update file info​

You can update the overall file information (path, isPublic and tags) in a single method call, instead of calling each individual update method separately.

const storageName = "default";
const bucketName = "profile-images";

const tags = {
  category: "documents",
  author: "John Doe",
}

// Renames the file, upddates it tags and marks it as private
let result = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file("rooby-avatar.png")
  .updateInfo("avatar.png", false, tags);
Example response
{
  "id": "fl-343rwsf324",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "avatar.png",
  "size": 212233,
  "mimeType": "image/png",
  "isPublic": false,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {
    "category": "documents",
    "author": "John Doe",
  }
}

Parameters​

Here you can find parameters for the updateInfo method.

#

Name

Data type

Required

Description

1newNamestringYesThe new name of the file.
2isPublicbooleanYesThe privacy setting of the file.
3tagsKeyValuePairYesA JSON object (key-value pairs) to set as the file metadata.

Replace file​

You can replace the file by calling the replace method. It keeps the name of the file but replaces file contents, size and mime-type with the newly uploaded file info and returns the metadata of the file after replacement. Please note that FileStreamObject.path or FileDiskObject.path data will be ignored since only the contents of the file is replaced not its path or name.

const storageName = "default";
const bucketName = "profile-images";

const newFile = {
  path: "filename.png",
  mimeType: "image/png",
  size: 1024, // File size in bytes
  localPath: 'path/to/file/on/disk',
};


// Replaces the file
let result = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file("booby-avatar.png")
  .replace(newFile);
Example response
{
  "id": "fl-343rwsf324",
  "bucketId": "bck-o5nnyhs19dgw",
  "storageId": "str-o0dlitj2x5id",
  "path": "booby-avatar.png",
  "size": 456789,
  "mimeType": "image/png",
  "isPublic": false,
  "uploadedAt": "2022-03-20T15:01:41.993Z",
  "updatedAt": "2022-03-20T15:01:41.993Z",
  "userId": "611a45f9f3e7ec001950175f",
  "tags": {
    "category": "documents",
    "author": "John Doe",
  }
}

Parameters​

Parameters​

Here are the parameters for the replace method:

#NameData TypeRequiredDescription
1fileFileStreamObject | FileDiskObjectYesThe file object that will be stored in the bucket. A file can be uploaded from a readable stream or from a file locally stored on the disk using its localPath.

If FileStreamObject is provided, the following values need to be provided:
- path: The path of the file (e.g., "path/to/my/file/filename.jpg")
- mimeType: The mime-type of the file (e.g., "image/png")
- size: The size of the file in bytes
- stream: The Readable stream of file contents

If FileDiskObject is provided, the following values need to be provided:
- path: The path of the file (e.g., "path/to/my/file/filename.jpg")
- mimeType: The mime-type of the file (e.g., "image/png")
- size: The size of the file in bytes
- localPath: The local path of the file where it is stored locally.

Delete file​

You can delete the file by calling the delete method. It deletes the file from the bucket.

const storageName = "default";
const bucketName = "profile-images";

// Deletes the file from the bucket
let { errors } = await agnost
  .storage(storageName)
  .bucket(bucketName)
  .file("rooby-avatar.png")
  .delete();

Create Read Stream​

The createReadStream method allows you to download a file as a readable stream. You can use the returned readable stream to pipe the file's contents to a writable stream or listen to 'data' events to read the file's contents.

const storageName = "default";
const bucketName = "profile-images";

// Create a readable stream to download a file
try {
  const fileStream = await agnost
    .storage(storageName)
    .bucket(bucketName)
    .file("rooby-avatar.png")
    .createReadStream();

  // Listen to 'data' events to read the file's contents
  fileStream.on("data", (chunk) => {
    console.log("Received chunk of data:", chunk);
  });

  // Handle 'end' event when the file has been fully read
  fileStream.on("end", () => {
    console.log("File reading completed.");
  });

  // Handle errors if any occur
  fileStream.on("error", (error) => {
    console.error("Error reading file:", error);
  });
} catch (error) {
  console.error("Error creating readable stream:", error);
}

Returns​

The createReadStream method returns a Promise that resolves to a readable stream, which can be used to read the contents of the stored file.