Add flow types, update package structure.

Adds index.js.flow and index.d.ts to package.

Fixes #45

Author: leebyron

.flowconfig

@@ -3,6 +3,7 @@
 .*/dist/.*
 .*/coverage/.*
 .*/resources/.*
+.*/node_modules/y18n/test/.*
 
 [include]
 

dataloader.d.ts

@@ -16,7 +16,7 @@
     "type": "git",
     "url": "http://github.com/facebook/dataloader.git"
   },
-  "main": "dist/index.js",
+  "main": "index.js",
   "options": {
     "mocha": "--require resources/mocha-bootload src/**/__tests__/**/*.js"
   },
@@ -25,16 +25,17 @@
     "testonly": "mocha $npm_package_options_mocha",
     "lint": "eslint src",
     "check": "flow check",
-    "build": "babel src --ignore __tests__ --out-dir dist/",
+    "build": "babel src --ignore __tests__ --out-dir dist/ ; cp src/index.js dist/index.js.flow ; cp src/index.d.ts dist/",
     "watch": "babel --optional runtime resources/watch.js | node",
     "cover": "babel-node node_modules/.bin/isparta cover --root src --report html node_modules/.bin/_mocha -- $npm_package_options_mocha",
     "cover:lcov": "babel-node node_modules/.bin/isparta cover --root src --report lcovonly node_modules/.bin/_mocha -- $npm_package_options_mocha",
     "preversion": ". ./resources/checkgit.sh && npm test",
     "prepublish": ". ./resources/prepublish.sh"
   },
   "files": [
-    "dist",
-    "dataloader.d.ts",
+    "index.js",
+    "index.js.flow",
+    "index.d.ts",
     "README.md",
     "LICENSE",
     "PATENTS"
@@ -48,10 +49,10 @@
     "coveralls": "2.11.6",
     "eslint": "1.10.3",
     "eslint-plugin-babel": "2.2.0",
-    "flow-bin": "0.20.1",
+    "flow-bin": "0.32.0",
     "isparta": "3.0.3",
     "mocha": "2.3.4",
     "sane": "1.3.0"
   },
-  "typings": "dataloader.d.ts"
+  "typings": "index.d.ts"
 }

package.json

@@ -18,3 +18,16 @@ fi;
 
 # Build before publishing
 npm run build;
+
+# When Travis CI publishes to NPM, the published files are available in the root
+# directory, which produces a cleaner distribution.
+#
+cp dist/* .
+
+# Ensure a vanilla package.json before deploying so other tools do not interpret
+# The built output as requiring any further transformation.
+node -e "var package = require('./package.json'); \
+  delete package.scripts; \
+  delete package.options; \
+  delete package.devDependencies; \
+  require('fs').writeFileSync('package.json', JSON.stringify(package));"

resources/prepublish.sh

@@ -0,0 +1,108 @@
+/**
+ *  Copyright (c) 2015, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the BSD-style license found in the
+ *  LICENSE file in the root directory of this source tree. An additional grant
+ *  of patent rights can be found in the PATENTS file in the same directory.
+ */
+
+// If a custom cache is provided, it must be of this type (a subset of ES6 Map).
+type CacheMap<K, V> = {
+  get(key: K): V | void;
+  set(key: K, value: V): any;
+  delete(key: K): any;
+  clear(): any;
+}
+
+// A Function, which when given an Array of keys, returns a Promise of an Array
+// of values or Errors.
+type BatchLoadFn<K, V> = (keys: K[]) => Promise<Array<V | Error>>;
+
+// Optionally turn off batching or caching or provide a cache key function or a
+// custom cache instance.
+type Options<K, V> = {
+
+  /**
+   * Default `true`. Set to `false` to disable batching,
+   * instead immediately invoking `batchLoadFn` with a
+   * single load key.
+   */
+  batch?: boolean,
+
+  /**
+   * Default `true`. Set to `false` to disable caching,
+   * instead creating a new Promise and new key in
+   * the `batchLoadFn` for every load.
+   */
+  cache?: boolean,
+
+  /**
+   * A function to produce a cache key for a given load key.
+   * Defaults to `key => key`. Useful to provide when JavaScript
+   * objects are keys and two similarly shaped objects should
+   * be considered equivalent.
+   */
+  cacheKeyFn?: (key: any) => any,
+
+  /**
+   * An instance of Map (or an object with a similar API) to
+   * be used as the underlying cache for this loader.
+   * Default `new Map()`.
+   */
+  cacheMap?: CacheMap<K, Promise<V>>;
+}
+
+/**
+ * DataLoader creates a public API for loading data from a particular
+ * data back-end with unique keys such as the id column of a SQL table
+ * or document name in a MongoDB database, given a batch loading function.
+ *
+ * Each DataLoader instance contains a unique memoized cache. Use caution
+ * when used in long-lived applications or those which serve many users
+ * with different access permissions and consider creating a new instance
+ * per web request.
+ */
+export class DataLoader<K, V> {
+
+  constructor(batchLoadFn: BatchLoadFn<K, V>, options?: Options<K, V>);
+
+  /**
+   * Loads a key, returning a `Promise` for the value represented by that key.
+   */
+  load(key: K): Promise<V>;
+
+  /**
+   * Loads multiple keys, promising an array of values:
+   *
+   *     var [ a, b ] = await myLoader.loadMany([ 'a', 'b' ]);
+   *
+   * This is equivalent to the more verbose:
+   *
+   *     var [ a, b ] = await Promise.all([
+   *       myLoader.load('a'),
+   *       myLoader.load('b')
+   *     ]);
+   *
+   */
+  loadMany(keys: K[]): Promise<V[]>;
+
+  /**
+   * Clears the value at `key` from the cache, if it exists. Returns itself for
+   * method chaining.
+   */
+  clear(key: K): DataLoader<K, V>;
+
+  /**
+   * Clears the entire cache. To be used when some event results in unknown
+   * invalidations across this particular `DataLoader`. Returns itself for
+   * method chaining.
+   */
+  clearAll(): DataLoader<K, V>;
+
+  /**
+   * Adds the provied key and value to the cache. If the key already exists, no
+   * change is made. Returns itself for method chaining.
+   */
+  prime(key: K, value: V): DataLoader<K, V>;
+}

src/index.d.ts

@@ -52,7 +52,8 @@ export default class DataLoader<K, V> {
     }
     this._batchLoadFn = batchLoadFn;
     this._options = options;
-    this._promiseCache = options && options.cacheMap || new Map();
+    this._promiseCache =
+      options && options.cacheMap || (new Map(): Map<K,Promise<V>>);
     this._queue = [];
   }
 
@@ -69,7 +70,7 @@ export default class DataLoader<K, V> {
     if (key === null || key === undefined) {
       throw new TypeError(
         'The loader.load() function must be called with a value,' +
-        `but got: ${key}.`
+        `but got: ${String(key)}.`
       );
     }
 
@@ -232,7 +233,7 @@ function dispatchQueue<K, V>(loader: DataLoader<K, V>) {
     return failedDispatch(loader, queue, new TypeError(
       'DataLoader must be constructed with a function which accepts ' +
       'Array<key> and returns Promise<Array<value>>, but the function did ' +
-      `not return a Promise: ${batchPromise}.`
+      `not return a Promise: ${String(batchPromise)}.`
     ));
   }
 
@@ -244,7 +245,7 @@ function dispatchQueue<K, V>(loader: DataLoader<K, V>) {
       throw new Error(
         'DataLoader must be constructed with a function which accepts ' +
         'Array<key> and returns Promise<Array<value>>, but the function did ' +
-        `not return a Promise of an Array: ${values}.`
+        `not return a Promise of an Array: ${String(values)}.`
       );
     }
     if (values.length !== keys.length) {
@@ -253,8 +254,8 @@ function dispatchQueue<K, V>(loader: DataLoader<K, V>) {
         'Array<key> and returns Promise<Array<value>>, but the function did ' +
         'not return a Promise of an Array of the same length as the Array ' +
         'of keys.' +
-        `\n\nKeys:\n${keys}` +
-        `\n\nValues:\n${values}`
+        `\n\nKeys:\n${String(keys)}` +
+        `\n\nValues:\n${String(values)}`
       );
     }