proposals/cordova-lib refactoring/ProjectApi.js

/*jshint node:true, unused:false */

/**
 * @class Class, that acts as abstract on top of Cordova project. Encapsulates the
 *   basic properties, that represents project configuration and methods for
 *   managing the project.
 */
function ProjectApi () {}

/**
 * Gets a ProjectApi instance for specified directory.
 *
 * @param   {String}  projectDir  Path to cordova project.
 *
 * @return  {Promise<ProjectApi>}  Returns a promise either fulfilled with a
 *   Cordova project instance or rejected with CordovaError.
 */
ProjectApi.getProjectAt = function (projectDir) {};

/**
 * Initializes an empty cordova project at specified directory. Copies
 *
 * @param  {String} targetDir Path to directory, where new project will be
 *   created.
 * @param  {String} [appName = 'HelloCordova']   Application name, that will be
 *   used for '<name>' element in config.xml. If not specified, 'HelloCordova'
 *   will be used.
 * @param  {String} [appId = 'io.cordova.hellocordova']     Application id in
 *   form of reverse domain style identifier, that will be used for 'id'
 *   attribute of '<widget>' element. If not specified 'io.cordova.hellocordova'
 *   will be used.
 * @param  {Object} [options]   An options object. The most common options are:
 * @param  {String} options.wwwSource  Specifies the www assets source for new
 *   application instead of default one. If not specified, the Cordova
 *   HelloWorld assets will be used.
 * @param  {Boolean}  options.link  Specifies that www source will be symlinked
 *   to app's directory instead of copying.
 *
 * @return {Promise<ProjectApi>} Returns a promise either fulfilled with a
 *   Cordova project instance or rejected with CordovaError.
 */
ProjectApi.createProject = function (targetDir, appName, appId, options) {};

/**
 * Gets a ProjectInfo structure that describes the project.
 *
 * @return  {CordovaProject}  A CordovaProject object.
 */
ProjectApi.prototype.getProjectInfo = function () {};

/**
 * Adds a new platform to project.
 *
 * @param  {String}  platformSpec  A platform spec that should be one of
 *   following:
 *
 * - valid platform name: 'android', 'windows', etc.
 * - valid npm identifier, that resolves to valid platform: cordova-android@4.0
 * - git url, that points to repo with valid platform:
 *       http://github.com/apache/cordova-android.git#4.0.0
 * - path to local repo of valid platform:
 *     /my/cordova/repositories/cordova-android
 *
 * @param {Object}  [options] The options object. Supported properties:
 * @param {Boolean} [options.saveToProject = false]  Flag that indicates, that added platform
 *   should be saved into project configuration to be easily restored after. The
 *   approach is similar to 'npm install --save' command.
 *
 * @return {Promise} A promise either fulfilled if platform is installed
 *   successfully, or rejected with CordovaError.
 */
ProjectApi.prototype.addPlatform = function (platformSpec, options) {};

/**
 * Removes a platform from project.
 *
 * @param  {String}  platformName  A name of platform that should be removed
 *   from project.
 * @param {Object}   [options] The options object. Supported properties:
 * @param {Boolean}  [options.saveToProject = false]  Flag that indicates, that
 *   platform also should be removed from project configuration.
 *
 * @return {Promise} A promise either fulfilled if platform is removed
 *   successfully, or rejected with CordovaError.
 */
ProjectApi.prototype.removePlatform = function (platformName, options) {};

/**
 * Adds a new plugin into project. Installs it to each platform in project.
 *
 * @param  {String}  pluginSpec  A plugin spec that should be one of following:
 *
 *   - valid plugin id that can be resolved through either cordova
 *   plugin registry or npm:
 *       'org.apache.cordova.globalization', 'cordova-plugin-globalization'
 *   - valid npm identifier, that resolves to valid plugin:
 *       cordova-plugin-globalization@1.0.0
 *   - git url, that points to repo with valid plugin:
 *       http://github.com/apache/cordova-plugin-globalization.git#r1.0.0
 *   - path to local repo of valid plugin:
 *       /my/cordova/repositories/cordova-plugin-globalization
 *
 * @param  {Object}  [options]    An options object. Possible options are:
 * @param  {Boolean} saveToProject Flag that indicates, that added plugin should
 *   be saved into project configuration.
 * @param  {Boolean} link       Flag that specifies that plugin sources will be
 *   symlinked to app's directory instead of copying if possible.
 * @param  {String}  searchPath Valid path, that will be used to search for
 *   plugin in local filesystem.
 * @param  {Object}  variables  An object that represents variables that will be
 *   used to install plugin. See more details on plugin variables in
 *   documentation:
 *   https://cordova.apache.org/docs/en/4.0.0/plugin_ref_spec.md.html
 *
 * @return {Promise} A promise either fulfilled if plugin is installed
 *   successfully, or rejected with CordovaError.
 */
ProjectApi.prototype.addPlugin = function (pluginSpec, options) {};

/**
 * Removes a plugin from project.
 *
 * @param  {String}  pluginId  An id of plugin that should be removed from
 *   project.
 * @param {Object} [options] The options object. Supported properties:
 * @param {Boolean}  options.saveToProject  Flag that indicates, that plugin
 *   also should be removed from project configuration.
 *
 * @return {Promise} A promise either fulfilled if platform is removed
 *   successfully, or rejected with CordovaError.
 */
ProjectApi.prototype.removePlugin = function (pluginId, options) {};

/**
 * Gets all platforms, installed into project.
 *
 * @return  {PlatformApi[]}  An array of PlatformApi instances.
 */
ProjectApi.prototype.getPlatforms = function () {};

/**
 * Gets a platform by name
 *
 * @param   {String}  platformName  The platform name.
 *
 * @return  {PlatformApi}  PlatformApi instance for specified platform.
 */
ProjectApi.prototype.getPlatform = function (platformName) {};

/**
 * Gets all the plugins, installed into project.
 *
 * @return  {Array<PluginInfo>}  An array of PluginInfo instances.
 */
ProjectApi.prototype.getPlugins = function () {};

/**
 * Gets plugins, specified by id.
 *
 * @return  {PluginInfo}  A PluginInfo instance for specified plugin.
 */
ProjectApi.prototype.getPlugin = function (pluginId) {};

/**
 * Prepares a project for building specified platform/platforms. The prepare
 *   step is need to be performed to update configuration and www assets for
 *   each platform from application's ones before the application will be built.
 *   The prepare step isn't required if no configuration changes or www assets
 *   changes was made.
 *
 * @param   {String|String[]}  [platform]  Single platform or array of platform
 *   names, that needs to be prepared. If omitted, all platform, added to
 *   project will be prepared.
 * @param   {Object}  [prepareOptions]  An options object with following fields:
 * @param   {Boolean} prepareOptions.browserify Specifies that project should be
 *   prepared with 'browserify' flow to embed all plugins' JS files and cordova
 *   JS sources into one single file.
 *
 * @return  {Promise}  A promise either fulfilled, if platform/platforms
 *   prepared successfully, or rejected with CordovaError otherwise.
 */
ProjectApi.prototype.prepare = function (platform, prepareOptions) {};

/**
 * Builds an application package for specified platform/platforms.
 *
 * @param   {String|String[]}  [platform]  A list of platform names/single name.
 *   If not specified, builds packages for all platforms, installed into
 *   project.
 *
 * @param  {Object}  [buildOptions]  A build options. This object's structure is
 *   highly depends on platform's specific. The most common options are:
 * @param  {Boolean}  buildOptions.debug  Indicates that packages should be
 *   built with debug configuration. This is set to true by default unless the
 *   'release' option is not specified.
 * @param  {Boolean}  buildOptions.release  Indicates that packages should be
 *   built with release configuration. If not set to true, debug configuration
 *   will be used.
 * @param   {Boolean}  buildOptions.device  Specifies that built app is intended
 *   to run on device
 * @param   {Boolean}  buildOptions.emulator: Specifies that built app is
 *   intended to run on emulator
 * @param   {String}  buildOptions.target  Specifies the device id that will be
 *   used to run built application.
 * @param   {Boolean}  buildOptions.nobuild  Indicates that this should be a
 *   dry-run call, so no build artifacts will be produced.
 * @param   {String[]}  buildOptions.archs  Specifies chip architectures which
 *   app packages should be built for. List of valid architectures is depends on
 *   platform.
 * @param   {String}  buildOptions.buildConfig  The path to build configuration
 *   file. The format of this file is depends on platform.
 * @param   {String[]} buildOptions.argv Raw array of command-line arguments,
 *   passed to `build` command. The purpose of this property is to pass a
 *   platform-specific arguments, and eventually let platform define own
 *   arguments processing logic.
 *
 * @return {Promise<Object>} A promise either fulfilled with an array of build
 *   artifacts for each platform, if package was built successfully, or rejected
 *   with CordovaError. The keys of resultant object is a platform names, and
 *   values - arrays of build artifact objects. The structure of build artifacts
 *   is descriped in PlatformApi reference.
 */
ProjectApi.prototype.build = function (platform, buildOptions) {};

/**
 * Builds and runs an application package for specified platform on specified
 *   device/emulator.
 *
 * @param   {String|String[]}  [platform]  A list of platform names/single name.
 *   If omitted, method runs packages for all platforms, installed into project.
 * @param   {Object}  [runOptions]  An options object. The structure is the same
 *   as for build options.
 *
 * @return {Promise} A promise either fulfilled if application ran successfully,
 *   or rejected with CordovaError.
 */
ProjectApi.prototype.run = function (platform, runOptions) {};

/**
 * Runs an application on a local web-server and launches a browser to display
 *   application content.
 *
 * @param   {String}  [platform]      A platform to run server for.
 * @param   {Object}  [serveOptions]  A set of options to pass to serve command.
 *   Available options are:
 * @param   {Number}  serveOptions.port  A port to bind server to.
 * @param   {String}  serveOptions.target  A browser name. Available targets
 *   depends on platform. Most common are: 'chrome', 'safari', 'opera', 'firefox'.s
 *
 * @return  {Promise}  A promise either fulfilled, if server ran successfully,
 *   or rejected with CordovaError otherwise.
 */
ProjectApi.prototype.serve = function (platform, serveOptions) {};

/**
 * Cleans out the build artifacts for specified platform.
 *
 * @param   {String|String[]}  [platform]  A list of platform names/single
 *   platform, which needs to be cleaned. If not specified, run clean for all
 *   platforms, installed into project.
 * @param   {Object}  [cleanOptions]  An options object. The structure is not
 *   defined explicitly, so it can be used to pass some platfom specific vaues
 *   to platform.
 *
 * @return {Promise} A promise either fulfilled or rejected with CordovaError.
 */
ProjectApi.prototype.clean = function(platform, cleanOptions) {};

/**
 * Performs a requirements check for each platforms installed. Each platform
 *   defines its own set of requirements, which should be resolved before
 *   platform can be built successfully.
 *
 * @param   {String|String[]}  [platform]  A list of platform names/single
 *   platform, which requirements needs to be checked for.
 *
 * @return  {Promise<Requirement[]>}  Promise resolved with set of Requirement
 *   objects for each platform.
 */
ProjectApi.prototype.requirements = function(platform) {};