sack - npm Package Compare versions

Comparing version 2.1.1 to 2.1.2

HISTORY.md

 # Change History
 
+## 2.1.2 (2014-09-22)
+
+* JSDoc + documenation build script
+
 ## 2.1.1 (2014-08-30)
@@ -4,0 +8,0 @@

lib/Container.js

@@ -7,6 +7,36 @@ module.exports = Container;
 /**
+ * @class
  * Basic dependency resolver / IoC container that allows for the registering of
- * types and instances, as well as auto-guessing constructor and function
- * injecting via parameter names.
- * @constructor
+ * types and instances under string tags.
+ *
+ * Dependencies are injected to class constructors and closures via parameter
+ * name matching
+ *
+ * ```
+ * var Container = require('sack');
+ *
+ * var container = new Container();
+ *
+ * container.register('http', MyHttpServer)
+ *   .asSingleton();
+ *
+ * container.register('messenger', new GlobalMessageBus())
+ *   .asInstance();
+ *
+ * ...
+ *
+ * // http and messenger need to get injected to this class...
+ *
+ * function MyApp(http, messenger)
+ * {
+ *   this.http      = http;
+ *   this.messenger = messenger;
+ * }
+ *
+ * ...
+ *
+ * // We can use the container to automatically inject the needed dependencies...
+ *
+ * container.make(MyApp);
+ * ```
  */
@@ -17,2 +47,3 @@ function Container()
    * @type {object.<string,IoCBinding>}
+   * @private
    */
@@ -23,5 +54,21 @@ this._bindings = {};
 /**
- * Add a new dependency
- * @param {string} name
- * @param {Function|object} source
+ * Register a new depdency with this container.
+ *
+ * Dependencies are either class constructors, closures, or existing objects.
+ * The `name` that a dependency is registered under determines what parameter
+ * names we need to resolve it out of the container.
+ *
+ * Use the methods on the returned {@link IoCBinding} instance to further
+ * configure how this dependency will be used.
+ * @example
+ * // Lazily created singleton
+ * container.register('service', SomeService)
+ *   .asSingleton();
+ *
+ * // Regsitering existing objects
+ * conatiner.regsiter('http', express())
+ *   .asInstance();
+ * @param {string} name The tag we want to register this dependency under
+ * @param {function|object} source The class constructor, closure, or existing
+ * object instance we want to register
  * @return {IoCBinding}
@@ -46,3 +93,21 @@ */
 /**
- * Return a maker function
+ * Return a factory function that can be used to create objects via class
+ * constructors or strings that get built via the container.
+ *
+ * This allows for passing around a simple factory function to other parts of
+ * your application that can use it to build domain objects without having to
+ * know about the IoC container API or semantics.
+ *
+ * This is the prefered way of giving power to a manager-type object to serve
+ * as a factory during runtime and let it delegate object creation / resolution
+ * to this container transparently.
+ *
+ * It effectively just provides a wrapper around a call to
+ * {@link Container#make}.
+ * @example
+ * var factory = container.getFactory();
+ *
+ * var thing = factory(Thing);
+ *
+ * var thing = factory('thing');
  * @return {function(thing:any): object}
@@ -55,7 +120,25 @@ */
     return _this.make(thing);
-  }
+  };
 };
 
 /**
- * @param {string} thing
+ * Resolve an object out of the container via a class constructor, closure, or
+ * string tag.
+ *
+ * When calling this function with a class constructor or closure, the
+ * parameters are automatically resolved out of the container as well via their
+ * name.
+ *
+ * If a string is used, the container will create objects directly with their
+ * string tag used in  {@link Container#register}
+ * @example
+ * // "dep1" and "dep2" are first resolved out of the container, and then this
+ * // closure is called
+ * var thing = container.make(function(dep1, dep2) {
+ *   ...
+ * });
+ *
+ * var transport = container.make('transport');
+ * @param {function|string} thing A string or class constructor/closure to
+ * resolve out of the container.
  * @return {object}
@@ -84,2 +167,3 @@ */
  * @return {object}
+ * @private
  */
@@ -86,0 +170,0 @@ Container.prototype._build = function(T, depNames)

lib/IoCBinding.js

@@ -6,6 +6,9 @@ module.exports = IoCBinding;
 /**
- * @constructor
- * @param {string} name
- * @param {object} source
- * @param {function(name:string): object} factory
+ * Will be created during {@link Container#register} calls, and should not be
+ * instantiated directly.
+ * @param {string} name Tag of the dependency
+ * @param {object} source Source function/object
+ * @param {function(name:string): object} factory Builder
+ * @class
+ * A binding object used to handle configuring IoC bindings.
  */
@@ -27,3 +30,17 @@ function IoCBinding(name, source, factory)
 /**
+ * Allow a binding to be overridden at a later time.
+ *
+ * Marking a binding as weak will let it get overridden but a subsequent
+ * binding without throwing an error.
  * @return {IoCBinding} This binding.
+ * @example
+ * container.register('config', MemoryStoreConfig);
+ *   .asWeak();
+ *
+ * ...
+ *
+ * // Would normally throw an error, but is okay since it was registered as
+ * // weak above. Notice that since this new dependency was not registered as
+ * // weak, if it overridden again it WILL throw an error this time.
+ * container.register('config', LocalStorageConfig);
  */
@@ -37,2 +54,3 @@ IoCBinding.prototype.asWeak = function()
 /**
+ * Determine if a binding is currently set as weak
  * @return {boolean}
@@ -46,4 +64,7 @@ */
 /**
- * @return {array.<string>} List of all the dep names needed in the constructor
- * of the source (if we have one)
+ * Get a list of all the names of dependencies needed to resolve this binding.
+ *
+ * If the source is a class constructor or closure, it'll be the named
+ * parameters. Otherwise it'll be an empty array.
+ * @return {array.<string>}
  */
@@ -65,3 +86,19 @@ IoCBinding.prototype.getDependencyNames = function()
 /**
+ * Mark this dependency to be instantiated only once.
+ *
+ * This will allow a dependency to only actually be resolved and created a
+ * single time, after which that instance is cached and re-used for all
+ * subsequent requests.
+ *
+ * This is how you would implement a "global singleton" pattern without the
+ * consumer of the dependency necessarily knowing that.
  * @return {IoCBinding} This binding.
+ * @example
+ * container.register('http', MyHttpServer)
+ *   .asSingleton();
+ *
+ * var s1 = container.make('http');
+ * var s2 = container.make('http');
+ *
+ * s1 === s2; // true
  */
@@ -75,3 +112,18 @@ IoCBinding.prototype.asSingleton = function()
 /**
+ * Use the source object directly as the dependency.
+ *
+ * This is used to signal that we should simply recall the dependency directly
+ * that we've registered with a container.
+ *
+ * This is typically used either to register plain objects to the container, or
+ * to register instantiated classes that require a little extra setup at run
+ * time.
  * @return {IoCBinding} This binding.
+ * @example
+ * container.register('configs', { ... })
+ *   .asInstance();
+ *
+ * ...
+ *
+ * var configs = container.make('configs');
  */
@@ -86,2 +138,3 @@ IoCBinding.prototype.asInstance = function()
 /**
+ * Create the dependency.
  * @return {object}
@@ -88,0 +141,0 @@ */

package.json

 {
   "name": "sack",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "An Inversion-of-Control container for all your dependency injection needs.",
@@ -11,3 +11,4 @@ "keywords": [
     "dependency injection",
-    "injection"
+    "injection",
+    "dependency inversion"
   ],
@@ -19,7 +20,5 @@ "author": {
   },
-  "directories": {
-    "test": "test"
-  },
   "scripts": {
-    "test": "tape test/*.js"
+    "test": "tape test/*.js",
+    "doc": "jsdoc -c ./.jsdoc.json"
   },
@@ -29,3 +28,5 @@ "main": "index.js",
   "devDependencies": {
-    "tape": "^2.14.0"
+    "jsdoc": "^3.3.0-alpha9",
+    "jsdoc3-bootstrap": "^0.7.1",
+    "tape": "^3.0.0"
   },
@@ -32,0 +33,0 @@ "repository": {

No alert changes

Improved metrics

Total package byte prevSize

27453

increased by22.69%

Number of package files

15

increased by7.14%

Lines of code

484

increased by45.35%

Worsened metrics

Dev dependency count

3

increased by200%

No dependency changes