mongodb-filesystem

Exports the MongoFS class that implements a filesystem using GridFS.

Example (Installation)

npm install --save mongodb-filesystem

Example (Usage)

const { MongoFS } = require('mongodb-filesystem');
const mongofs = new MongoFS(db);

• mongodb-filesystem
  • MongoFS ⏏
    • new MongoFS(db, [options], [modified])
    • .createFile(pathname, buf, [metadata], [contentType]) ⇒ Promise
    • .createOrUpdateFile(pathname, buf, [metadata], [contentType]) ⇒ Promise
    • .deleteFile(pathname) ⇒ Promise
    • .deleteFolder(folder) ⇒ Promise
    • .findFiles(query) ⇒ Promise
    • .getFile(pathname) ⇒ Promise
    • .getFiles(folder, filenamesOnly) ⇒ Promise
    • .getFolders(parent) ⇒ Promise
    • .getMetadata(pathname) ⇒ Promise
    • .isFile(pathname) ⇒ Promise
    • .isFolder(pathname) ⇒ Promise
    • .renameFile(oldPathname, newPathname) ⇒ Promise
    • .renameFolder(oldFolder, newFolder) ⇒ Promise
    • .updateFile(pathname, buf, [metadata], [contentType]) ⇒ Promise
    • .updateMetadata(pathname, metadata) ⇒ Promise

MongoFS ⏏

Implements a basic filesystem using the MongoDB GridFS interface. In GridFS, everything is a file so the concept of folders containing files must be artifically created by giving each file a pathname as the filename.

This approach has two consequences:

First, there is no concept of moving a file (or folder) into another folder. In Unix, mv myfile.txt mydir moves the file into the mydir folder if it is a directory. Otherwise, myfile.txt is renamed to mydir. In this module, the only option is renaming a file (or folder).

Second, the concept of an empty directory also does not exist. Folders are implicitly defined by one or more files having the same folder prefix. If no files have a specific folder prefix, then deleteFolder performs no action and getFiles and getFolders return an empty array.

Please note that all write operations are checked for conflicts. For example, when renaming '/my/dir/myfile.txt' to '/my/dir/yourfile.txt' and '/my/dir/yourfile.txt' aready exists, the promise is rejected. This comparison is case-insensitive, meaning that it would fail even if the existing file was named '/My/Dir/YourFile.txt'. This conflict test also applies to creating or renaming files to existing file or folder names and renaming folders to existing folder or file names.

Kind: Exported class

new MongoFS(db, [options], [modified])

Creates a new MongoFS instance by creating a GridFSBucket using the specified (optional) options. The modified function, if specified, is called for all actions that perform a mutation. The function is passed a single string argument identifying the mutation.

Params

• db object - A database handle.
• [options] object - The options passed to the GridFSBucket constructor.
• [modified] function - A function called for all mutation actions.

mongoFS.createFile(pathname, buf, [metadata], [contentType]) ⇒ Promise

Creates a new file from the specified buffer.

Kind: instance method of MongoFS
Returns: Promise - Resolved if successful.
Params

• pathname string - The pathname of the file to create.
• buf string | Buffer - The file data.
• [metadata] object - Optional metadata.
• [contentType] string - Optional content type.

mongoFS.createOrUpdateFile(pathname, buf, [metadata], [contentType]) ⇒ Promise

Creates a new file or updates an existing file from the specified buffer. On update, if the metadata is not specified, then the existing metadata is used.

Kind: instance method of MongoFS
Returns: Promise - Resolved with true if created, false if updated.
Params

• pathname string - The pathname of the file to create or update.
• buf string | Buffer - The file data.
• [metadata] object - Optional metadata.
• [contentType] string - Optional content type.

mongoFS.deleteFile(pathname) ⇒ Promise

Deletes the file specified by the pathname. The promise is rejected if the file does not exist.

Kind: instance method of MongoFS
Returns: Promise - Resolved with the number of files deleted (always 1).
Params

• pathname string - The pathname of the file to delete.

mongoFS.deleteFolder(folder) ⇒ Promise

Deletes all files and folders in the specified folder. Essentially, this method performs an rm -rf operation.

Kind: instance method of MongoFS
Returns: Promise - Resolved with the number of files deleted.
Params

• folder string - The folder to delete.

mongoFS.findFiles(query) ⇒ Promise

Finds all files matching the specified query. The query is a standard MongoDB query.

Kind: instance method of MongoFS
Returns: Promise - - Resolved with an array of descriptor objects.
Params

• query object - The MongoDB query.

Example (Find files authored by Smith)

{ 'metadata.author.name.last': 'Smith' }

mongoFS.getFile(pathname) ⇒ Promise

Gets the specified file and its content. The returned promise is resolved with a descriptor object that has the following structure:

{
  filename: '/myfile.txt',
  pathname: '/myfolder/myfile.txt',
  metadata: { author: 'John Smith' },
  content: <Buffer 74 65 78 74>,
  contentType: 'text/plain',
  contentLength: 4,
  lastModified: '2020-06-05T12:53:03.128Z'
}

Kind: instance method of MongoFS
Returns: Promise - Resolved with a descriptor that includes content.
Params

• pathname string - The pathname of the file to get.

mongoFS.getFiles(folder, filenamesOnly) ⇒ Promise

Gets a list of the files in the specified folder. If the filenamesOnly flag is true, then an array of filenames is returned instead of an array of descriptor objects. The content is not included in the returned array.

Kind: instance method of MongoFS
Returns: Promise - Resolved with an array of descriptor objects or filenames.
Params

• folder string - The folder of which to list the files.
• filenamesOnly boolean - True to return only filenames.

mongoFS.getFolders(parent) ⇒ Promise

Gets a list of folders contained within the specified parent folder.

Kind: instance method of MongoFS
Returns: Promise - Resolved with an array of subfolder names.
Params

• parent string - The folder of which to list the subfolders.

mongoFS.getMetadata(pathname) ⇒ Promise

Gets the metadata of the file specified by the pathname.

Kind: instance method of MongoFS
Returns: Promise - - Resolved with the metadata of the file.
Params

• pathname string - The pathname of the file to retrieve.

mongoFS.isFile(pathname) ⇒ Promise

Determines if the pathname identifies an existing file.

Kind: instance method of MongoFS
Returns: Promise - - Resolved with a boolean.
Params

• pathname string - The pathname of the file to check.

mongoFS.isFolder(pathname) ⇒ Promise

Determines if the pathname identifies an existing folder. Since the concept of folders is somewhat artificial, this method simply checks if there are any files having the folder prefix.

Kind: instance method of MongoFS
Returns: Promise - - Resolved with a boolean.
Params

• pathname string - The pathname of the folder to check.

mongoFS.renameFile(oldPathname, newPathname) ⇒ Promise

Renames a file specified by the oldPathname with the newPathname. The promise is rejected if the file does not exist, a file by that name already exists, or the newPathname is actually a folder already containing other files.

Kind: instance method of MongoFS
Returns: Promise - Resolved with the number of files renamed (always 1).
Params

• oldPathname string - The absolute pathname of the file to rename.
• newPathname string - The relative or absolute target pathname.

mongoFS.renameFolder(oldFolder, newFolder) ⇒ Promise

Renames a folder by finding all files where the filename begins with the specified oldFolder and replacing that part of the filename with the prefix specified by the newFolder. The promise is rejected if the newFolder already exists.

Kind: instance method of MongoFS
Returns: Promise - Resolved with the number of files renamed.
Params

• oldFolder string - The old absolute folder path.
• newFolder string - The new relative or absolute folder path.

mongoFS.updateFile(pathname, buf, [metadata], [contentType]) ⇒ Promise

Updates an existing file from the specified buffer. If the metadata is not specified, then the existing metadata is used.

Kind: instance method of MongoFS
Returns: Promise - Resolved if successful.
Params

• pathname string - The pathname of the file to update.
• buf string | Buffer - The file data.
• [metadata] object - Optional metadata.
• [contentType] string - Optional content type.

mongoFS.updateMetadata(pathname, metadata) ⇒ Promise

Updates the metadata of the file specified by the pathname to the specified metadata. This replaces the current metadata object.

Kind: instance method of MongoFS
Returns: Promise - Resolved with the number of files updated (always 1).
Params

• pathname string - The pathname of the file to update.
• metadata object - The new metadata object.