Use camelCase identifiers in the JS API

NEWS.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Changed
+
+* Options formatted in kebab-case (i.e., with hyphens) are available in camelCase, per JavaScript naming standards (#580)
+
+### Deprecated
+
+* Options formatted in kebab-case (i.e., with hyphens) are deprecated in favor of their camelCase variants, per JavaScript naming standards (#580)
+
 ## [8.5.2] - 2017-02-19
 
 ### Fixed

common.js

@@ -40,8 +40,11 @@ function parseCLIArgs (argv) {
   args.dir = args._[0]
   args.name = args._[1]
 
+  // Transform hyphenated keys into camelCase
+  module.exports.camelCase(args, false)
+
   var protocolSchemes = [].concat(args.protocol || [])
-  var protocolNames = [].concat(args['protocol-name'] || [])
+  var protocolNames = [].concat(args.protocolName || [])
 
   if (protocolSchemes && protocolNames && protocolNames.length === protocolSchemes.length) {
     args.protocols = protocolSchemes.map(function (scheme, i) {
@@ -53,10 +56,6 @@ function parseCLIArgs (argv) {
     args.out = null
   }
 
-  // Transform hyphenated keys into camelCase
-  args.electronVersion = args['electron-version']
-  delete args['electron-version']
-
   // Overrides for multi-typed arguments, because minimist doesn't support it
 
   // asar: `Object` or `true`
@@ -65,8 +64,8 @@ function parseCLIArgs (argv) {
   }
 
   // osx-sign: `Object` or `true`
-  if (args['osx-sign'] === 'true') {
-    args['osx-sign'] = true
+  if (args.osxSign === 'true') {
+    args.osxSign = true
   }
 
   // tmpdir: `String` or `false`
@@ -194,6 +193,35 @@ module.exports = {
     }
   },
 
+  kebabProperties: {
+    'electron-version': 'electronVersion',
+    'app-copyright': 'appCopyright',
+    'app-version': 'appVersion',
+    'build-version': 'buildVersion',
+    'app-bundle-id': 'appBundleId',
+    'app-category-type': 'appCategoryType',
+    'extend-info': 'extendInfo',
+    'extra-resource': 'extraResource',
+    'helper-bundle-id': 'helperBundleId',
+    'osx-sign': 'osxSign',
+    'protocol-name': 'protocolName'
+  },
+
+  camelCase: function camelCase (properties, warn) {
+    Object.keys(module.exports.kebabProperties).forEach(function (key) {
+      var value = module.exports.kebabProperties[key]
+      if (properties.hasOwnProperty(key)) {
+        if (warn) {
+          warning(`The ${key} parameter is deprecated when used from JS, use ${value} instead. It will be removed in the next major version.`)
+        }
+        if (!properties.hasOwnProperty(value)) {
+          properties[value] = properties[key]
+        }
+        delete properties[key]
+      }
+    })
+  },
+
   downloadElectronZip: function downloadElectronZip (downloadOpts, cb) {
     // armv7l builds have only been backfilled for Electron >= 1.0.0.
     // See: https://github.com/electron/electron/pull/6986

docs/api.md

@@ -53,12 +53,22 @@ When `true`, sets both [`arch`](#arch) and [`platform`](#platform) to `all`.
 
 ##### `app-copyright`
 
+*String* (**deprecated** and will be removed in a future major version, please use the
+[`appCopyright`](#appCopyright) parameter instead)
+
+##### `appCopyright`
+
 *String*
 
 The human-readable copyright line for the app. Maps to the `LegalCopyright` metadata property on Windows, and `NSHumanReadableCopyright` on OS X.
 
 ##### `app-version`
 
+*String* (**deprecated** and will be removed in a future major version, please use the
+[`appVersion`](#appVersion) parameter instead)
+
+##### `appVersion`
+
 *String*
 
 The release version of the application. By default the `version` property in the `package.json` is used but it can be overridden with this argument. If neither are provided, the version of Electron will be used. Maps to the `ProductVersion` metadata property on Windows, and `CFBundleShortVersionString` on OS X.
@@ -93,6 +103,12 @@ Whether to package the application's source code into an archive, using [Electro
 
 ##### `build-version`
 
+*String* (**deprecated** and will be removed in a future major version, please use the
+[`buildVersion`](#buildVersion) parameter instead)
+
+
+##### `buildVersion`
+
 *String*
 
 The build version of the application. Defaults to the value of [`app-version`](#app-version). Maps to the `FileVersion` metadata property on Windows, and `CFBundleVersion` on OS X.
@@ -116,6 +132,7 @@ but are not limited to:
 - `strictSSL` (*Boolean* - default: `true`): Whether SSL certificates are required to be valid when
   downloading Electron.
 
+
 ##### `electronVersion`
 
 *String*
@@ -232,12 +249,22 @@ The base directory to use as a temp directory. Set to `false` to disable use of
 
 ##### `app-bundle-id`
 
+*String* (**deprecated** and will be removed in a future major version, please use the
+[`appBundleId`](#appBundleId) parameter instead)
+
+##### `appBundleId`
+
 *String*
 
 The bundle identifier to use in the application's plist.
 
 ##### `app-category-type`
 
+*String* (**deprecated** and will be removed in a future major version, please use the
+  [`appCategoryType`](#appCategoryType) parameter instead)
+
+##### `appCategoryType`
+
 *String*
 
 The application category type, as shown in the Finder via *View → Arrange by Application Category* when viewing the Applications directory.
@@ -248,28 +275,46 @@ Valid values are listed in [Apple's documentation](https://developer.apple.com/l
 
 ##### `extend-info`
 
+*String* (**deprecated** and will be removed in a future major version, please use the
+  [`extendInfo`](#extendInfo) parameter instead)
+
+##### `extendInfo`
+
 *String* or *Object*
 
 When the value is a `String`, the filename of a plist file. Its contents are added to the app's plist. When the value is an `Object`, an already-parsed plist data structure that is merged into the app's plist.
 
 Entries from `extend-info` override entries in the base plist file supplied by `electron` or `electron-prebuilt`, but are overridden by other explicit arguments such as [`app-version`](#app-version) or [`app-bundle-id`](#app-bundle-id).
 
+##### `extra-resource`
 
+*String* (**deprecated** and will be removed in a future major version, please use the
+  [`extraResource`](#extraResource) parameter instead)
 
-##### `extra-resource`
+##### `extraResource`
 
 *String* or *Array*
 
 Filename of a file to be copied directly into the app's `Contents/Resources` directory.
 
 ##### `helper-bundle-id`
 
+*String* (**deprecated** and will be removed in a future major version, please use the
+  [`helperBundleId`](#helperBundleId) parameter instead)
+
+##### `helperBundleId`
+
 *String*
 
 The bundle identifier to use in the application helper's plist.
 
 ##### `osx-sign`
 
+*String* (**deprecated** and will be removed in a future major version, please use the
+  [`osxSign`](#osxSign) parameter instead)
+
+##### `osxSign`
+
 *Object* or *`true`*
 
 If present, signs OS X target apps when the host platform is OS X and XCode is installed. When the value is `true`, pass default configuration to the signing module. The configuration values listed below can be customized when the value is an `Object`. See [electron-osx-sign](https://www.npmjs.com/package/electron-osx-sign#opts) for more detailed option descriptions and the defaults.
@@ -279,7 +324,7 @@ If present, signs OS X target apps when the host platform is OS X and XCode is i
 
 ##### `protocol`
 
-*Array* of *String*s
+*Array* of *String*​s
 
 The URL protocol scheme(s) to associate the app with. For example, specifying
 `myapp` would cause URLs such as `myapp://path` to be opened with the app. Maps
@@ -288,7 +333,12 @@ corresponding `protocol-name` option to be specified.
 
 ##### `protocol-name`
 
-*Array* of *String*s
+*String* (**deprecated** and will be removed in a future major version, please use the
+[`protocolName`](#protocolName) parameter instead)
+
+##### `protocolName`
+
+*Array* of *String*​s
 
 The descriptive name(s) of the URL protocol scheme(s) specified via the `protocol`
 option. Maps to the `CFBundleURLName` metadata property.

index.js

@@ -21,7 +21,7 @@ function debugHostInfo () {
 function getMetadata (opts, dir, cb) {
   var props = []
   if (!opts.name) props.push(['productName', 'name'])
-  if (!opts['app-version']) props.push('version')
+  if (!opts.appVersion) props.push('version')
   if (!opts.electronVersion) {
     props.push([
       'dependencies.electron',
@@ -62,7 +62,7 @@ function getMetadata (opts, dir, cb) {
 
     if (result.values.version) {
       debug(`Inferring app-version from version in ${result.source.version.src}`)
-      opts['app-version'] = result.values.version
+      opts.appVersion = result.values.version
     }
 
     if (result.values['dependencies.electron']) {
@@ -240,6 +240,8 @@ module.exports = function packager (opts, cb) {
 
   common.deprecatedParameter(opts, 'version', 'electronVersion', 'electron-version')
 
+  common.camelCase(opts, true)
+
   getMetadata(opts, path.resolve(process.cwd(), opts.dir) || process.cwd(), function (err) {
     if (err) return cb(err)
 

mac.js

@@ -22,19 +22,19 @@ class MacApp {
   }
 
   get appCategoryType () {
-    return this.opts['app-category-type']
+    return this.opts.appCategoryType
   }
 
   get appCopyright () {
-    return this.opts['app-copyright']
+    return this.opts.appCopyright
   }
 
   get appVersion () {
-    return this.opts['app-version']
+    return this.opts.appVersion
   }
 
   get buildVersion () {
-    return this.opts['build-version']
+    return this.opts.buildVersion
   }
 
   get protocols () {
@@ -99,11 +99,11 @@ class MacApp {
 
     let defaultBundleName = `com.electron.${common.sanitizeAppName(this.appName).toLowerCase()}`
 
-    let appBundleIdentifier = filterCFBundleIdentifier(this.opts['app-bundle-id'] || defaultBundleName)
-    this.helperBundleIdentifier = filterCFBundleIdentifier(this.opts['helper-bundle-id'] || `${appBundleIdentifier}.helper`)
+    let appBundleIdentifier = filterCFBundleIdentifier(this.opts.appBundleId || defaultBundleName)
+    this.helperBundleIdentifier = filterCFBundleIdentifier(this.opts.helperBundleId || `${appBundleIdentifier}.helper`)
 
-    if (this.opts['extend-info']) {
-      this.appPlist = this.extendAppPlist(this.opts['extend-info'])
+    if (this.opts.extendInfo) {
+      this.appPlist = this.extendAppPlist(this.opts.extendInfo)
     }
 
     this.appPlist = this.updatePlist(this.appPlist, this.appName, appBundleIdentifier, this.appName)
@@ -193,7 +193,7 @@ class MacApp {
   }
 
   enqueueAppSigningIfSpecified () {
-    let osxSignOpt = this.opts['osx-sign']
+    let osxSignOpt = this.opts.osxSign
     let platform = this.opts.platform
     let version = this.opts.electronVersion
 
@@ -250,7 +250,7 @@ function createSignOpts (properties, platform, app, version, quiet) {
   }
 
   // Take argument osx-sign as signing identity:
-  // if opts['osx-sign'] is true (bool), fallback to identity=null for
+  // if opts.osxSign is true (bool), fallback to identity=null for
   // autodiscovery. Otherwise, provide signing certificate info.
   if (signOpts.identity === true) {
     signOpts.identity = null
@@ -272,8 +272,8 @@ module.exports = {
         appCreator.enqueueCopyingIcon()
       }
 
-      if (opts['extra-resource']) {
-        appCreator.enqueueCopyingExtraFiles(opts['extra-resource'])
+      if (opts.extraResource) {
+        appCreator.enqueueCopyingExtraFiles(opts.extraResource)
       }
 
       appCreator.enqueueRenamingElectronBinary()

test/basic.js

@@ -420,6 +420,19 @@ function createDisableSymlinkDereferencingTest (opts) {
   }
 }
 
+test('camelCase de-kebab-cases known parameters', (t) => {
+  let opts = {
+    'abc-def': true,
+    'electron-version': '1.6.0'
+  }
+  common.camelCase(opts, false)
+  t.equal('1.6.0', opts.electronVersion, 'camelCased known property exists')
+  t.equal(undefined, opts['electron-version'], 'kebab-cased known property does not exist')
+  t.equal(undefined, opts.abcDef, 'camelCased unknown property does not exist')
+  t.equal(true, opts['abc-def'], 'kebab-cased unknown property exists')
+  t.end()
+})
+
 test('validateListFromOptions does not take non-Array/String values', (t) => {
   t.notOk(targets.validateListFromOptions({digits: 64}, {'64': true, '65': true}, 'digits') instanceof Array,
           'should not be an Array')

test/cli.js

@@ -33,7 +33,7 @@ test('CLI argument test: using --asar overrides other --asar.options', (t) => {
 
 test('CLI argument test: --osx-sign=true', function (t) {
   var args = common.parseCLIArgs(['--osx-sign=true'])
-  t.equal(args['osx-sign'], true)
+  t.equal(args.osxSign, true)
   t.end()
 })