add commonjs entrypoint for nodejs environment (ramda#1928)

* add commonjs entrypoint for nodejs environment

* add section about removing/adding to contributing guide

* add test for consistent api surface

* update contributing guide

* update test for api surface

* test: sort both api arrays before asserting them

* tweak build script to use package's entrypoint to build files for distribution

* rewrite APIs test, add note about used convention and explanation

* fix eslint issues

* remove "npm pretest", because you dont need to build ramda before tests anymore

* keep eslint check, but in CI now

.gitignore

@@ -1,7 +1,6 @@
 /lib/bench/report/
 /lib/docs/public/
 /node_modules/
-/index.js
 /npm-debug.log
 /ramda.js.tmp
 /lib/test/bundle.js

.npmignore

@@ -14,7 +14,6 @@
 /CONTRIBUTING.md
 /Makefile
 /bower.json
-/index.js
 /npm-debug.log
 /ramda.js.tmp
 /testem.json

.travis.yml

@@ -6,4 +6,4 @@ node_js:
 - 4
 - 6
 before_script:
-- make clean && make dist/ramda.js
+- npm run lint

CONTRIBUTING.md

@@ -6,11 +6,11 @@
 
         $ git checkout -b <branch>
 
-3.  If adding a function `R.foo`, define it in __src/foo.js__ and include unit
-    tests in __test/foo.js__. It is not necessary to include the `@since`
-    annotation for new functions as it will be set during the release process
-    of the following release. If adding an internal function `_foo`, define it
-    in __src/internal/_foo.js__.
+3.  If adding a function `R.foo`, define it in __src/foo.js__, require it in
+    __index.js__, and include unit tests in __test/foo.js__. It is not necessary
+    to include the `@since` annotation for new functions as it will be set
+    during the release process of the following release. If adding an internal
+    function `_foo`, define it in __src/internal/_foo.js__.
 
 4.  Make one or more atomic commits. Each commit should have a descriptive
     commit message, wrapped at 72 characters. Do not commit changes to

index.js

@@ -0,0 +1,236 @@
+module.exports = {
+  F: require('./src/F'),
+  T: require('./src/T'),
+  __: require('./src/__'),
+  add: require('./src/add'),
+  addIndex: require('./src/addIndex'),
+  adjust: require('./src/adjust'),
+  all: require('./src/all'),
+  allPass: require('./src/allPass'),
+  always: require('./src/always'),
+  and: require('./src/and'),
+  any: require('./src/any'),
+  anyPass: require('./src/anyPass'),
+  ap: require('./src/ap'),
+  aperture: require('./src/aperture'),
+  append: require('./src/append'),
+  apply: require('./src/apply'),
+  applySpec: require('./src/applySpec'),
+  assoc: require('./src/assoc'),
+  assocPath: require('./src/assocPath'),
+  binary: require('./src/binary'),
+  bind: require('./src/bind'),
+  both: require('./src/both'),
+  call: require('./src/call'),
+  chain: require('./src/chain'),
+  clamp: require('./src/clamp'),
+  clone: require('./src/clone'),
+  comparator: require('./src/comparator'),
+  complement: require('./src/complement'),
+  compose: require('./src/compose'),
+  composeK: require('./src/composeK'),
+  composeP: require('./src/composeP'),
+  concat: require('./src/concat'),
+  cond: require('./src/cond'),
+  construct: require('./src/construct'),
+  constructN: require('./src/constructN'),
+  contains: require('./src/contains'),
+  converge: require('./src/converge'),
+  countBy: require('./src/countBy'),
+  curry: require('./src/curry'),
+  curryN: require('./src/curryN'),
+  dec: require('./src/dec'),
+  defaultTo: require('./src/defaultTo'),
+  difference: require('./src/difference'),
+  differenceWith: require('./src/differenceWith'),
+  dissoc: require('./src/dissoc'),
+  dissocPath: require('./src/dissocPath'),
+  divide: require('./src/divide'),
+  drop: require('./src/drop'),
+  dropLast: require('./src/dropLast'),
+  dropLastWhile: require('./src/dropLastWhile'),
+  dropRepeats: require('./src/dropRepeats'),
+  dropRepeatsWith: require('./src/dropRepeatsWith'),
+  dropWhile: require('./src/dropWhile'),
+  either: require('./src/either'),
+  empty: require('./src/empty'),
+  eqBy: require('./src/eqBy'),
+  eqProps: require('./src/eqProps'),
+  equals: require('./src/equals'),
+  evolve: require('./src/evolve'),
+  filter: require('./src/filter'),
+  find: require('./src/find'),
+  findIndex: require('./src/findIndex'),
+  findLast: require('./src/findLast'),
+  findLastIndex: require('./src/findLastIndex'),
+  flatten: require('./src/flatten'),
+  flip: require('./src/flip'),
+  forEach: require('./src/forEach'),
+  fromPairs: require('./src/fromPairs'),
+  groupBy: require('./src/groupBy'),
+  groupWith: require('./src/groupWith'),
+  gt: require('./src/gt'),
+  gte: require('./src/gte'),
+  has: require('./src/has'),
+  hasIn: require('./src/hasIn'),
+  head: require('./src/head'),
+  identical: require('./src/identical'),
+  identity: require('./src/identity'),
+  ifElse: require('./src/ifElse'),
+  inc: require('./src/inc'),
+  indexBy: require('./src/indexBy'),
+  indexOf: require('./src/indexOf'),
+  init: require('./src/init'),
+  insert: require('./src/insert'),
+  insertAll: require('./src/insertAll'),
+  intersection: require('./src/intersection'),
+  intersectionWith: require('./src/intersectionWith'),
+  intersperse: require('./src/intersperse'),
+  into: require('./src/into'),
+  invert: require('./src/invert'),
+  invertObj: require('./src/invertObj'),
+  invoker: require('./src/invoker'),
+  is: require('./src/is'),
+  isArrayLike: require('./src/isArrayLike'),
+  isEmpty: require('./src/isEmpty'),
+  isNil: require('./src/isNil'),
+  join: require('./src/join'),
+  juxt: require('./src/juxt'),
+  keys: require('./src/keys'),
+  keysIn: require('./src/keysIn'),
+  last: require('./src/last'),
+  lastIndexOf: require('./src/lastIndexOf'),
+  length: require('./src/length'),
+  lens: require('./src/lens'),
+  lensIndex: require('./src/lensIndex'),
+  lensPath: require('./src/lensPath'),
+  lensProp: require('./src/lensProp'),
+  lift: require('./src/lift'),
+  liftN: require('./src/liftN'),
+  lt: require('./src/lt'),
+  lte: require('./src/lte'),
+  map: require('./src/map'),
+  mapAccum: require('./src/mapAccum'),
+  mapAccumRight: require('./src/mapAccumRight'),
+  mapObjIndexed: require('./src/mapObjIndexed'),
+  match: require('./src/match'),
+  mathMod: require('./src/mathMod'),
+  max: require('./src/max'),
+  maxBy: require('./src/maxBy'),
+  mean: require('./src/mean'),
+  median: require('./src/median'),
+  memoize: require('./src/memoize'),
+  merge: require('./src/merge'),
+  mergeAll: require('./src/mergeAll'),
+  mergeWith: require('./src/mergeWith'),
+  mergeWithKey: require('./src/mergeWithKey'),
+  min: require('./src/min'),
+  minBy: require('./src/minBy'),
+  modulo: require('./src/modulo'),
+  multiply: require('./src/multiply'),
+  nAry: require('./src/nAry'),
+  negate: require('./src/negate'),
+  none: require('./src/none'),
+  not: require('./src/not'),
+  nth: require('./src/nth'),
+  nthArg: require('./src/nthArg'),
+  objOf: require('./src/objOf'),
+  of: require('./src/of'),
+  omit: require('./src/omit'),
+  once: require('./src/once'),
+  or: require('./src/or'),
+  over: require('./src/over'),
+  pair: require('./src/pair'),
+  partial: require('./src/partial'),
+  partialRight: require('./src/partialRight'),
+  partition: require('./src/partition'),
+  path: require('./src/path'),
+  pathEq: require('./src/pathEq'),
+  pathOr: require('./src/pathOr'),
+  pathSatisfies: require('./src/pathSatisfies'),
+  pick: require('./src/pick'),
+  pickAll: require('./src/pickAll'),
+  pickBy: require('./src/pickBy'),
+  pipe: require('./src/pipe'),
+  pipeK: require('./src/pipeK'),
+  pipeP: require('./src/pipeP'),
+  pluck: require('./src/pluck'),
+  prepend: require('./src/prepend'),
+  product: require('./src/product'),
+  project: require('./src/project'),
+  prop: require('./src/prop'),
+  propEq: require('./src/propEq'),
+  propIs: require('./src/propIs'),
+  propOr: require('./src/propOr'),
+  propSatisfies: require('./src/propSatisfies'),
+  props: require('./src/props'),
+  range: require('./src/range'),
+  reduce: require('./src/reduce'),
+  reduceBy: require('./src/reduceBy'),
+  reduceRight: require('./src/reduceRight'),
+  reduceWhile: require('./src/reduceWhile'),
+  reduced: require('./src/reduced'),
+  reject: require('./src/reject'),
+  remove: require('./src/remove'),
+  repeat: require('./src/repeat'),
+  replace: require('./src/replace'),
+  reverse: require('./src/reverse'),
+  scan: require('./src/scan'),
+  sequence: require('./src/sequence'),
+  set: require('./src/set'),
+  slice: require('./src/slice'),
+  sort: require('./src/sort'),
+  sortBy: require('./src/sortBy'),
+  split: require('./src/split'),
+  splitAt: require('./src/splitAt'),
+  splitEvery: require('./src/splitEvery'),
+  splitWhen: require('./src/splitWhen'),
+  subtract: require('./src/subtract'),
+  sum: require('./src/sum'),
+  symmetricDifference: require('./src/symmetricDifference'),
+  symmetricDifferenceWith: require('./src/symmetricDifferenceWith'),
+  tail: require('./src/tail'),
+  take: require('./src/take'),
+  takeLast: require('./src/takeLast'),
+  takeLastWhile: require('./src/takeLastWhile'),
+  takeWhile: require('./src/takeWhile'),
+  tap: require('./src/tap'),
+  test: require('./src/test'),
+  times: require('./src/times'),
+  toLower: require('./src/toLower'),
+  toPairs: require('./src/toPairs'),
+  toPairsIn: require('./src/toPairsIn'),
+  toString: require('./src/toString'),
+  toUpper: require('./src/toUpper'),
+  transduce: require('./src/transduce'),
+  transpose: require('./src/transpose'),
+  traverse: require('./src/traverse'),
+  trim: require('./src/trim'),
+  tryCatch: require('./src/tryCatch'),
+  type: require('./src/type'),
+  unapply: require('./src/unapply'),
+  unary: require('./src/unary'),
+  uncurryN: require('./src/uncurryN'),
+  unfold: require('./src/unfold'),
+  union: require('./src/union'),
+  unionWith: require('./src/unionWith'),
+  uniq: require('./src/uniq'),
+  uniqBy: require('./src/uniqBy'),
+  uniqWith: require('./src/uniqWith'),
+  unless: require('./src/unless'),
+  unnest: require('./src/unnest'),
+  until: require('./src/until'),
+  update: require('./src/update'),
+  useWith: require('./src/useWith'),
+  values: require('./src/values'),
+  valuesIn: require('./src/valuesIn'),
+  view: require('./src/view'),
+  when: require('./src/when'),
+  where: require('./src/where'),
+  whereEq: require('./src/whereEq'),
+  without: require('./src/without'),
+  xprod: require('./src/xprod'),
+  zip: require('./src/zip'),
+  zipObj: require('./src/zipObj'),
+  zipWith: require('./src/zipWith')
+}

package.json

@@ -31,7 +31,7 @@
     "type": "git",
     "url": "git://github.com/ramda/ramda.git"
   },
-  "main": "dist/ramda.js",
+  "main": "index.js",
   "scripts": {
     "bench": "scripts/benchRunner",
     "bookmarklet": "scripts/bookmarklet",
@@ -41,7 +41,6 @@
     "coverage": "istanbul cover node_modules/.bin/_mocha -- --reporter spec",
     "postcoverage": "npm run posttest",
     "lint": "eslint scripts/bookmarklet scripts/build src/*.js src/internal/*.js test/*.js test/**/*.js lib/sauce/*.js lib/bench/*.js",
-    "pretest": "npm install && npm run lint && npm run clean && npm run build",
     "test": "mocha --reporter spec",
     "posttest": "git checkout -- dist",
     "prebrowser_test": "npm run pretest",

scripts/build

@@ -258,9 +258,8 @@ program
 .parse(process.argv);
 
 //  filenames :: [String]
-var filenames = program.complete ?
-  R.filter(R.test(/(^|[/]).*[.]js$/),
-           fs.readdirSync(path.join(__dirname, '..', 'src'))) :
-  program.args;
+var filenames = program.complete
+  ? R.keys(require('../'))
+  : program.args;
 
 process.stdout.write(build(R.map(path.resolve, filenames)));

test/index.js

@@ -0,0 +1,41 @@
+var R = require('..');
+var eq = require('./shared/eq');
+var fs = require('fs');
+var path = require('path');
+
+
+function sourceMethods(dir) {
+  var isJsFile = function(file) { return file.match(/\.js$/); };
+  var removeJsEnding = function(file) { return file.replace('.js', ''); };
+  return fs.readdirSync(dir).filter(isJsFile).map(removeJsEnding);
+}
+
+/**
+ * Convention is
+ *  * Actual API—all `./src/*.js` files are top level API methods
+ *  * Exported API—object in `./index.js` to be exported
+ *  * Actual and exported APIs should be the same
+ *
+ * Two cases, when exported and actual APIs might differ
+ *  1. newly added API `./src/method.js` is forgotten to be added into './index.js'
+ *  2. API method is deprecated and actual source file from `./src/` removed,
+ *     while continues to exist in `./index.js`
+ *
+ * 1st case is detected in first assertion, and detailed in second one
+ *
+ * 2st case doesnt need detection, because NodeJS will throw an error
+ * if you would attempt to require non existing file
+ */
+describe('API surface', function() {
+  var exported = Object.keys(R);
+  var actual = sourceMethods(path.join(__dirname, '..', 'src'));
+
+  it('both APIs are in sync', function() {
+    eq(actual.length, exported.length);
+  });
+
+  it('list of not exported API methods is empty', function() {
+    function isNotExported(method) { return exported.indexOf(method) === -1; }
+    eq(actual.filter(isNotExported), []);
+  });
+});