@harishreddym/baqend/lib/binding/File.js

Baqend JavaScript SDK

'use strict';

const error = require('../error');
const Acl = require('../Acl');
const uuid = require('../util/uuid').uuid;
const message = require('../message');
const StatusCode = require('../connector/Message').StatusCode;
const deprecated = require('../util/deprecated');
const trailingSlashIt = require('./trailingSlashIt').trailingSlashIt;

const FILE_BUCKET = '/file';
const FILE_BUCKET_LENGTH = FILE_BUCKET.length;

const ID = Symbol('Id');
const METADATA = Symbol('Metadata');
const DATA = Symbol('Data');

/**
 * Creates a file object, which represents one specific file reference.
 * This File object can afterwards be used to up- and download the file contents or to retrieves and change the files
 * metadata.
 *
 * The file data can be uploaded and downloaded as:
 *
 *  <table class="table">
 *   <tr>
 *     <th>type</th>
 *     <th>JavaScript type</th>
 *     <th>Description</th>
 *   </tr>
 *   <tr>
 *     <td>'arraybuffer'</td>
 *     <td>ArrayBuffer</td>
 *     <td>The content is represented as a fixed-length raw binary data buffer</td>
 *   </tr>
 *   <tr>
 *     <td>'blob'</th>
 *     <td>Blob</td>
 *     <td>The content is represented as a simple blob</td>
 *   </tr>
 *   <tr>
 *     <td>'json'</td>
 *     <td>object|array|string</td>
 *     <td>The file content is represented as json</td>
 *   </tr>
 *   <tr>
 *     <td>'text'</td>
 *     <td>string</td>
 *     <td>The file content is represented through the string</td>
 *   </tr>
 *   <tr>
 *     <td>'base64'</td>
 *     <td>string</td>
 *     <td>The file content as base64 encoded string</td>
 *   </tr>
 *   <tr>
 *     <td>'data-url'</td>
 *     <td>string</td>
 *     <td>A data url which represents the file content</td>
 *   </tr>
 * </table>
 *
 *
 * @alias binding.File
 */
class File {
  /**
   * The complete id of the file, including folder and name
   * @type {string}
   * @readonly
   */
  get id() {
    return this[ID];
  }

  /**
   * The fully url to the file, can be directly used to link the file, i.e. in link tags ot image sources
   * @type {string}
   * @readonly
   */
  get url() {
    if (this.isFolder) {
      throw new Error('Url can not be created for folders.');
    }

    return this.db.createURL(this.id, this.bucket !== 'www');
  }

  /**
   * The name of the file
   * @type {string}
   * @readonly
   */
  get name() {
    return this.id.substring(this.id.lastIndexOf('/', this.id.length - 2) + 1);
  }

  /**
   * The mimeType of the file, only accessible after fetching the metadata or downloading/uploading/providing the file
   * @type {string}
   * @readonly
   */
  get mimeType() {
    if (this.isFolder) {
      throw new Error('A folder has no mimeType');
    }
    this.checkAvailable();
    return this[METADATA].mimeType;
  }

  /**
   * The current file acl, only accessible after fetching the metadata or downloading/uploading/providing the file
   * @type {Acl}
   * @readonly
   */
  get acl() {
    this.checkAvailable();
    return this[METADATA].acl;
  }

  /**
   * The last modified date of the file, only accessible after fetching the metadata
   * or downloading/uploading/providing the eTag
   * @type {?Date}
   * @readonly
   */
  get lastModified() {
    if (this.isFolder) {
      throw new Error('A folder has no lastModified');
    }
    this.checkAvailable();
    return this[METADATA].lastModified;
  }

  /**
   * The creation date of the file, only accessible after fetching the metadata
   * or downloading/uploading/providing the eTag
   * @type {?Date}
   * @readonly
   */
  get createdAt() {
    if (this.isFolder) {
      throw new Error('A folder has no creation date');
    }
    this.checkAvailable();
    return this[METADATA].createdAt;
  }

  /**
   * The eTag of the file, only accessible after fetching the metadata or downloading/uploading/providing the file
   * @type {string}
   * @readonly
   */
  get eTag() {
    if (this.isFolder) {
      throw new Error('A folder has no eTag');
    }
    this.checkAvailable();
    return this[METADATA].eTag;
  }

  /**
   * The custom headers of the file, only accessible after fetching the metadata or downloading/uploading/providing
   * the file
   * @type {Object<string,string>}
   * @readonly
   */
  get headers() {
    if (this.isFolder) {
      throw new Error('A folder has no custom headers');
    }

    this.checkAvailable();
    return this[METADATA].headers;
  }

  /**
   * The size of the file, only accessible after fetching the metadata or downloading/uploading/providing the file
   * @type {number}
   * @readonly
   */
  get size() {
    if (this.isFolder) {
      throw new Error('A folder has no size');
    }
    this.checkAvailable();
    return this[METADATA].size;
  }

  /**
   * @type {string}
   * @readonly
   */
  get bucket() {
    return this.id.substring(FILE_BUCKET_LENGTH + 1, this.id.indexOf('/', FILE_BUCKET_LENGTH + 1));
  }

  /**
   * @type {string}
   * @readonly
   */
  get key() {
    return this.id.substring(this.id.indexOf('/', FILE_BUCKET_LENGTH + 1) + 1);
  }

  /**
   * The full path of the file.
   * @type {string}
   * @readonly
   */
  get path() {
    return this.id.substring(FILE_BUCKET_LENGTH);
  }

  /**
   * The parent folder of the file.
   * @type {string}
   * @readonly
   */
  get parent() {
    return this.id.substring(FILE_BUCKET_LENGTH, this.id.lastIndexOf('/', this.id.length - 2));
  }

  /**
   * Indicates if the metadata are loaded.
   * @type {boolean}
   * @readonly
   */
  get isMetadataLoaded() {
    return !!this[METADATA];
  }

  /**
   * Creates a new file object which represents a file at the given id. Data which is provided to the constructor will
   * be uploaded by invoking {@link upload()}
   * @param {object|string} fileOptions The fileOptions used to create a new file object, or just the id of the file
   * @param {string=} fileOptions.id The id of the file.
   * @param {string=} fileOptions.name The filename without the id. If omitted and data is provided as a file object,
   * the {@link File#name} will be used otherwise a UUID will be generated.
   * @param {string} [fileOptions.parent="/www"] The parent folder which contains the file
   * @param {string} [fileOptions.path="/www"] The full path of the file.
   * You might either specify the path of the file or a combination of parent and file name.
   * @param {string|Blob|File|ArrayBuffer|json=} fileOptions.data The initial file content, which will be uploaded by
   * invoking {@link #upload} later on.
   * @param {string=} fileOptions.type A optional type hint used to correctly interpret the provided data
   * @param {string=} fileOptions.mimeType The mimType of the file. Defaults to the mimeType of the provided data if
   * it is a file object, blob or data-url
   * @param {number=} fileOptions.size The size of the file content in bytes
   * @param {string=} fileOptions.eTag The optional current ETag of the file
   * @param {string|Date=} fileOptions.lastModified The optional last modified date
   * @param {Acl=} fileOptions.acl The file acl which will be set, if the file is uploaded afterwards
   * @param {Object<string,string>} [fileOptions.headers] The custom headers which will be send with the file after
   * uploading it
   */
  constructor(fileOptions) {
    // Is fileOptions just an id?
    const opt = typeof fileOptions === 'string' ? { id: fileOptions } : (fileOptions || {});

    if (opt.id) {
      // Check validity of id
      const nameSeparator = opt.id.indexOf('/', '/file/'.length);
      if (nameSeparator === -1 || opt.id.indexOf('/file/') !== 0) {
        throw new Error('Invalid file reference ' + opt.id);
      }

      this[ID] = opt.id;
    } else {
      this[ID] = this.createIdFromOptions(opt);
    }

    // Assign metadata
    this.setDataOptions(opt);

    /**
     * Specifies whether this file is a folder.
     * @type {boolean}
     * @readonly
     */
    this.isFolder = this.id.charAt(this.id.length - 1) === '/';
  }

  /**
   * Parses an E-Tag header
   * @param {string=} eTag The E-Tag to parse or something falsy
   * @return {?string} Returns the parsed E-Tag or null, if it could not be parsed
   */
  static parseETag(eTag) {
    if (!eTag) {
      return null;
    }

    const match = eTag.match(/^(?:[wW]\/)?["'](.*)["']$/);
    if (!match) {
      return null;
    }

    return match[1];
  }

  /**
   * Uploads the file content which was provided in the constructor or by uploadOptions.data
   * @param {object=} uploadOptions The upload options
   * @param {string|Blob|File|ArrayBuffer|json} [uploadOptions.data] The initial file content, which will be uploaded by
   * invoking {@link #upload} later on.
   * @param {string=} uploadOptions.type A optional type hint used to correctly interpret the provided data
   * @param {string=} uploadOptions.mimeType The mimType of the file. Defaults to the mimeType of the provided data if
   * it is a file object, blob or data-url
   * @param {string=} uploadOptions.eTag The optional current ETag of the file
   * @param {string=} uploadOptions.lastModified The optional last modified date
   * @param {Acl=} uploadOptions.acl The file acl which will be set, if the file is uploaded afterwards
   * @param {Object<string,string>} [uploadOptions.headers] The custom headers which will be send with the file after
   * uploading it
   * @param {boolean} [uploadOptions.force=false] force the upload and overwrite any existing files without validating
   * it
   * @param {connector.Message~progressCallback} [uploadOptions.progress] listen to progress changes during upload
   * @param {binding.File~fileCallback=} doneCallback The callback is invoked after the upload succeed successfully
   * @param {binding.File~failCallback=} failCallback The callback is invoked if any error is occurred
   * @return {Promise<binding.File>} A promise which will be fulfilled with this file object
   * where the metadata is updated
   */
  upload(uploadOptions, doneCallback, failCallback) {
    const opt = uploadOptions || {};

    if (this.isFolder) {
      throw new Error('A folder cannot be uploaded');
    }

    this.setDataOptions(opt);

    const uploadMessage = new message.UploadFile(this.bucket, this.key)
      .entity(this[DATA].data, this[DATA].type);

    const meta = this[METADATA];
    if (meta) {
      uploadMessage.acl(meta.acl);
      uploadMessage.contentLength(meta.size);
      uploadMessage.mimeType(meta.mimeType);
      uploadMessage.customHeaders(meta.headers);
    }

    uploadMessage.progress(opt.progress);

    this.conditional(uploadMessage, opt);

    this.db.addToBlackList(this.id);
    return this.db.send(uploadMessage).then((response) => {
      this[DATA] = null;
      this.fromJSON(response.entity);
      return this;
    }).then(doneCallback, failCallback);
  }

  /**
   * Download a file and providing it in the requested type
   * @param {object=} downloadOptions The download options
   * @param {string} [downloadOptions.type="blob"] The type used to provide the file
   * @param {string} [downloadOptions.refresh=false] Indicates to make a revalidation request and not use the cache
   * @param {binding.File~downloadCallback=} doneCallback The callback is invoked after the download succeed
   * successfully
   * @param {binding.File~failCallback=} failCallback The callback is invoked if any error is occurred
   * @return {Promise<string|Blob|File|ArrayBuffer|json>} A promise which will be fulfilled with the downloaded
   * file content
   */
  download(downloadOptions, doneCallback, failCallback) {
    const opt = downloadOptions || {};

    if (this.isFolder) {
      throw new Error('A folder cannot be downloaded');
    }

    const type = opt.type || 'blob';

    const downloadMessage = new message.DownloadFile(this.bucket, this.key)
      .responseType(type);

    this.db.ensureCacheHeader(this.id, downloadMessage, opt.refresh);

    return this.db.send(downloadMessage).then((response) => {
      this.db.addToWhiteList(this.id);
      this.fromHeaders(response.headers);
      return response.entity;
    }, (e) => {
      if (e.status === StatusCode.OBJECT_NOT_FOUND) {
        return null;
      }
      throw e;
    }).then(doneCallback, failCallback);
  }

  /**
   * Deletes a file
   * @param {object=} deleteOptions The delete options
   * @param {boolean} [deleteOptions.force=false] force the deletion without verifying any version
   * @param {binding.File~deleteCallback=} doneCallback The callback is invoked after the deletion succeed successfully
   * @param {binding.File~failCallback=} failCallback The callback is invoked if any error is occurred
   * @return {Promise<binding.File|binding.File[]>} A promise which will be fulfilled with this file object,
   * or with a list of all deleted files, if this file is an folder
   */
  delete(deleteOptions, doneCallback, failCallback) {
    const opt = deleteOptions || {};

    const deleteMessage = new message.DeleteFile(this.bucket, this.key);
    this.conditional(deleteMessage, opt);

    if (!this.isFolder) {
      this.db.addToBlackList(this.id);
    }

    return this.db.send(deleteMessage).then((response) => {
      if (!this.isFolder) {
        return this;
      }

      return response.entity.map(fileId => this.db.File(fileId));
    }).then(doneCallback, failCallback);
  }

  /**
   * Creates the file id from given options.
   * @param {*} fileOptions
   * @return {string}
   * @private
   */
  createIdFromOptions(fileOptions) {
    /** @var {string} */
    let path;
    if (fileOptions.path) {
      path = fileOptions.path;
    } else {
      const parent = trailingSlashIt(fileOptions.parent || '/www');
      if (parent.length < 3) {
        throw new Error('Invalid parent name: ' + parent);
      }

      const name = fileOptions.name || (fileOptions.data && fileOptions.data.name) || uuid();
      path = parent + name;
    }

    // Add leading slash if missing
    if (path.charAt(0) !== '/') {
      path = '/' + path;
    }

    // Check path validity
    if (path.indexOf('//') !== -1 || path.length < 3) {
      throw new Error('Invalid path: ' + path);
    }

    return FILE_BUCKET + path;
  }

  /**
   * Makes the given message a conditional request based on the file metadata
   * @param {connector.Message} msg The message to make conditional
   * @param {object} options additional request options
   * @param {boolean} [options.force=false] Force the request operation by didn't make it conditional
   * @return {void}
   */
  conditional(msg, options) {
    if (options.force) {
      return;
    }

    const meta = this[METADATA];
    if (!meta || (!meta.lastModified && !meta.eTag)) {
      msg.ifNoneMatch('*');
      return;
    }

    msg.ifUnmodifiedSince(meta.lastModified);
    msg.ifMatch(meta.eTag);
  }

  /**
   * Gets the file metadata of a file
   * @param {Object=} options The load metadata options
   * @param {boolean} [options.refresh=false] Force a revalidation while fetching the metadata
   * @param {binding.File~fileCallback=} doneCallback The callback is invoked after the metadata is fetched
   * @param {binding.File~failCallback=} failCallback The callback is invoked if any error has occurred
   * @return {Promise<binding.File>} A promise which will be fulfilled with this file
   */
  loadMetadata(options, doneCallback, failCallback) {
    const opt = options || {};

    if (this.isFolder) {
      throw new Error('A folder has no matadata.');
    }

    const msg = new message.GetFileMetadata(this.bucket, this.key);
    this.db.ensureCacheHeader(this.id, msg, opt.refresh);
    return this.db.send(msg).then((response) => {
      // do not white list the file, because head-request does not revalidate the cache.
      this.fromHeaders(response.headers);
      return this;
    }, (e) => {
      if (e.status === StatusCode.OBJECT_NOT_FOUND) {
        return null;
      }
      throw e;
    }).then(doneCallback, failCallback);
  }

  /**
   * Updates the matadata of this file.
   * @param {Object=} options The save metadata options
   * @param {boolean} [options.force=false] force the update and overwrite the existing metadata without validating it
   * @param {binding.File~fileCallback=} doneCallback The callback is invoked after the metadata is saved
   * @param {binding.File~failCallback=} failCallback The callback is invoked if any error has occurred
   * @return {Promise<binding.File>} A promise which will be fulfilled with this file
   */
  saveMetadata(options, doneCallback, failCallback) {
    const opt = options || {};

    const json = this.toJSON();
    const msg = new message.UpdateFileMetadata(this.bucket, this.key)
      .entity(json);

    this.conditional(msg, opt);

    return this.db.send(msg).then((response) => {
      this.fromJSON(response.entity);
      return this;
    }).then(doneCallback, failCallback);
  }

  /**
   * Validates and sets the file metadata based on the given options
   * @param {object} options
   * @private
   */
  setDataOptions(options) {
    const data = options.data;
    const type = options.type;

    if (!data) {
      return;
    }

    // Set data
    this[DATA] = { type, data };

    const mimeType = this.guessMimeType(options);
    this.fromJSON(Object.assign({}, options, { mimeType }));
  }

  /**
   * Gets the MIME type of given file options.
   * @param {object} options
   * @return {?string} Returns the guessed MIME type or null, if it could not be guessed.
   * @private
   */
  guessMimeType(options) {
    const mimeType = options.mimeType;
    if (mimeType) {
      return mimeType;
    }

    if (typeof Blob !== 'undefined' && options.data instanceof Blob) {
      return options.data.type;
    }

    if (options.type === 'data-url') {
      const match = options.data.match(/^data:(.+?)(;base64)?,.*$/);
      return match[1];
    }

    return null;
  }

  /**
   * @param {Object<string,string>} headers
   * @return {void}
   * @private
   */
  fromHeaders(headers) {
    this.fromJSON({
      eTag: File.parseETag(headers.etag),
      lastModified: headers['last-modified'],
      createdAt: headers['baqend-created-at'],
      mimeType: headers['content-type'],
      acl: headers['baqend-acl'] && JSON.parse(headers['baqend-acl']),
      size: +headers['baqend-size'],
      headers: headers['baqend-custom-headers'] && JSON.parse(headers['baqend-custom-headers']),
    });
  }

  /**
   * Deserialize the given JSON file metadata back to this file instance
   *
   * If the JSON object contains an ID, it must match with this file ID, otherwise an exception is thrown.
   *
   * @param {json} json The json to deserialize
   * @return {void}
   */
  fromJSON(json) {
    if (json.id && this.id !== json.id) {
      throw new Error('This file id ' + this.id + ' does not match the given json id ' + json.id);
    }

    const meta = this[METADATA] || {};

    let acl;
    if (json.acl instanceof Acl) {
      acl = json.acl;
    } else {
      acl = meta.acl || new Acl();
      if (json.acl) {
        acl.fromJSON(json.acl);
      }
    }

    // keep last known lastModified, createdAt, eTag and headers
    this[METADATA] = Object.assign({}, this[METADATA], {
      mimeType: json.mimeType,
      lastModified: (json.lastModified && new Date(json.lastModified)) || meta.lastModified,
      createdAt: (json.createdAt && new Date(json.createdAt)) || meta.createdAt,
      eTag: json.eTag || meta.eTag,
      acl,
      size: typeof json.size === 'number' ? json.size : json.contentLength,
      headers: json.headers || meta.headers || {},
    });
  }

  /**
   * Serialize the file metadata of this object to json
   * @return {json} The serialized file metadata as json
   */
  toJSON() {
    this.checkAvailable();
    const meta = this[METADATA];

    return {
      id: this.id,
      mimeType: meta.mimeType,
      eTag: meta.eTag,
      acl: meta.acl.toJSON(),
      size: meta.size,
      lastModified: meta.lastModified && meta.lastModified.toISOString(),
      createdAt: meta.createdAt && meta.createdAt.toISOString(),
      headers: meta.headers,
    };
  }

  /**
   * Checks whenever metadata are already loaded of the file, throws an error otherwise
   * @return {void}
   */
  checkAvailable() {
    if (!this.isMetadataLoaded) {
      throw new error.PersistentError('The file metadata of ' + this.id + ' is not available.');
    }
  }

  /**
   * The database connection to use
   * @name db
   * @type {EntityManager}
   * @memberOf File.prototype
   * @field
   * @readonly
   */
}

/**
 * The database connection to use
 * @member File.prototype
 */
deprecated(File.prototype, '_db', 'db');
deprecated(File.prototype, '_conditional', 'conditional');
deprecated(File.prototype, '_setMetadata', 'setDataOptions');
deprecated(File.prototype, '_checkAvailable', 'checkAvailable');

/**
 * The file callback is called, when the asynchronous operation completes successfully
 * @callback binding.File~fileCallback
 * @param {binding.File} file The updated file metadata
 * @return {*} A Promise, result or undefined
 */

/**
 * The download callback is called, when the asynchronous download completes successfully
 * @callback binding.File~downloadCallback
 * @param {string|Blob|File|ArrayBuffer|json} data The download file content in the requested format
 * @return {*} A Promise, result or undefined
 */

/**
 * The delete callback is called, when the asynchronous deletion completes successfully
 * @callback binding.File~deleteCallback
 * @param {binding.File} data The file metadata
 * @return {*} A Promise, result or undefined
 */

/**
 * The fail callback is called, when the asynchronous operation is rejected by an error
 * @callback binding.File~failCallback
 * @param {error.PersistentError} error The error which reject the operation
 * @return {*} A Promise, result or undefined
 */

module.exports = File;