billy - npm Package Compare versions

Comparing version 1.4.1 to 1.5.0

HISTORY.md

 # Change History
 
+## v1.5.0 (???)
+
+* `container()` method deprecated
+* Updated dependencies
+* Updated documentation
+
 ## v1.4.1 (2014-06-10)
@@ -4,0 +10,0 @@

lib/Application.js

@@ -27,2 +27,3 @@ module.exports = Application;
  * Change the IoC container instance.
+ * @deprecated
  * @param {{register:function(name:string,thing:object): IocBinding}} container
@@ -77,4 +78,4 @@ * @return {object} Old container.
 {
+  this._services.push(T);
   debug('registered service %s', getName(T));
-  this._services.push(T);
 };
@@ -84,12 +85,13 @@
  * Delegate registering things to to underlying IoC container.
- * @param {string} name
+ * @param {string} tag
  * @param {Function|object} thing
  * @return {IoCBinding}
  */
-Application.prototype.register = function(name, thing)
+Application.prototype.register = function(tag, thing)
 {
-  if (typeof name !== 'string')
-    throw new TypeError('name');
+  if (typeof tag !== 'string')
+    throw new TypeError('tag');
 
-  return this._container.register(name, thing);
+  debug('registering dependency with tag %s', tag);
+  return this._container.register(tag, thing);
 };
@@ -130,13 +132,3 @@
 
-  function start(s) {
-    return function() {
-      debug('starting service %s', getName(s.constructor));
-      return s.start ? s.start() : s;
-    };
-  }
-
-  // Start them (if we can) in order. If the service has a start() method, it
-  // can return a promise to delay the rest of the services from getting
-  // started until it finishes. The service itself could simply be a function
-  // that returns a promise as well.
+  // Start in order and async
   var sequence = Promise.resolve();
@@ -166,9 +158,2 @@ for (var m = 0; m < this._running.length; m++) {
 
-  function stop(s) {
-    return function() {
-      debug('stopping service %s', getName(s.constructor));
-      return s.stop ? s.stop() : s;
-    };
-  }
-
   // Loop through all services in reverse, allowing them to customize stop
@@ -190,1 +175,15 @@ // behavior if needed
 
+function start(s) {
+  return function() {
+    debug('starting service %s', getName(s.constructor));
+    return s.start ? s.start() : s;
+  };
+}
+
+function stop(s) {
+  return function() {
+    debug('stopping service %s', getName(s.constructor));
+    return s.stop ? s.stop() : s;
+  };
+}
+

package.json

 {
   "name": "billy",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A minimal application harness that stays out of your way and out of your code.",
@@ -19,3 +19,3 @@ "author": {
   "devDependencies": {
-    "tape": "^2.13.2"
+    "tape": "^2.14.0"
   },
@@ -41,7 +41,7 @@ "repository": {
   "dependencies": {
-    "bluebird": "^2.0.7",
-    "debug": "^1.0.1",
-    "sack": "^2.0.4",
-    "typedef": "^1.0.4"
+    "bluebird": "^2.3.2",
+    "debug": "^1.0.4",
+    "sack": "^2.1.1",
+    "typedef": "^1.1.0"
   }
 }

README.md

@@ -31,3 +31,3 @@ # billy
 
-* Dependency injection / inversion-of-control container
+* [Dependency injection / inversion-of-control container](https://github.com/bvalosek/sack)
 * Generic configuration store
@@ -39,15 +39,158 @@ * Asynchronous promise-based service stack
 
-## Philosophy
+## Overview
 
-The primary philosophy of Billy is to provide a cohesive and useful set of
-patterns for building an application that doesn't creep its way into your
-business logic and domain code.
+The primary goal and driving philosophy of Billy is to provide a cohesive and
+useful set of patterns for building an application that doesn't creep its way
+into your business logic and domain code.
 
 It is flexible and generic enough to work great for building server apps,
-browser apps, or even CLI apps.
+browser apps, javascript games, or even CLI utilities.
 
-Billy very much so strives to be the
-[express](https://github.com/visionmedia/express) of general application
-architecture.
+Much like [express](https://github.com/visionmedia/express), Billy strives not
+to be a framework that permeates all parts of your codebase, but rather the
+scaffolding that allows you to roll your own application architecture stack.
 
+## Services
+
+Billy views your application as the composition of several dependency-injected
+Services. When the application is started via `app.start()`, all registered
+services will be instantiated in turn and be given a chance to startup.
+
+A service should be used to create various run-time objects and register them
+as dependencies with the IoC container via the `app` dependency for other parts
+of the application to use.
+
+Services are effectively the place where all the various pieces of your
+application are booted, configured, and wired together.
+
+### Registering a service
+
+Your application entry point will register a series of services that will power
+your app. Services can either be a simple closure or a class constructor, and
+can optionally use promises to signal an asynchronous startup.
+
+### Using closures as a Service
+
+The simplest example of a service is a function:
+
+```javascript
+app.service(function main() {
+  console.log('service created');
+});
+```
+
+If our service took some time to startup, we could return a `Promise` to ensure
+during the service start phase, the application would wait.
+
+```javascript
+app.service(function main() {
+  console.log('service created');
+
+  return someAsyncTask()
+    .then(function() {
+      console.log('service started');
+    });
+});
+```
+
+Note that all services are first *created* all at once (by calling the provided
+function), synchronously. Then, all of the services are *started* (by waiting
+on any promises returned in the service function).
+
+#### Using Class Constructors as a Service
+
+A simple class constructor can be passed to the `app.service()` method as well.
+
+```javascript
+// MyService.js
+module.exports = MyService;
+
+function MyService()
+{
+  console.log('service created');
+}
+```
+
+In our startup file:
+
+```javascript
+// main.js
+var Application = require('billy');
+var MyService = require('./MyService.js');
+
+var app = new Application();
+
+app.service(MyService);
+app.start();
+```
+
+If this service requires some additional setup after all services have been
+created, or requires an asynchronous startup, we can implement a `start`
+method:
+
+```javascript
+MyService.prototype.start = function()
+{
+  return someAsyncTask()
+    .then(function() {
+      console.log('service started');
+    });
+};
+```
+
+Any promise return is waited on until it resolves before attempting to start
+any subsequent services.
+
+This is useful for things like downloading external data, verifying
+credentials, bootstrapping external connections, etc. The application startup
+process will block until the service resolves, guaranteeing a deterministic
+boot up.
+
+## Application Methods
+
+### app.service(TService)
+
+Registers a new dependency-injected service `TService` to be started with the
+application. See *Services* above.
+
+### var pStarted = app.start()
+
+Starts the application by first by instantiating all the services
+synchronously, and then attempting to start the services asynchronously. See
+*Services* above.
+
+Returns a `Promise` that either resolves when all services have started, or
+fails with any error / rejected promise during service startup.
+
+### var pStopped = app.stop()
+
+Stop the application by trying to asynchronously stop all services in the
+reverse order they started. See *Services* above.
+
+Returns a `Promise` that either resolves when all services have stopped, or
+fails with any error / rejected promise during service tear down.
+
+### var thing = app.make(tag)
+
+Will resolve / create an object instance out of the container based on what was
+registered with the string `tag`.
+
+See [sack](https://github.com/bvalosek/sack) for more details.
+
+### var thing = app.make(T)
+
+Create a new object instance via the object constructor `T` (e.g, `new T()`).
+
+Also resolve any constructor parameters out of the container. See
+[sack](https://github.com/bvalosek/sack) for more info on how creating
+IoC-injected objects works.
+
+### var binding = app.register(tag, thing)
+
+Registers a new dependency `thing` with name `tag` and returns an `IoCBinding`.
+
+`thing` could be an object instance, an object constructor function, or a
+closure. See [sack](https://github.com/bvalosek/sack) for more details on
+registering objects with the container..
+
 ## Testing
@@ -54,0 +197,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

27522

increased by18.45%

Number of lines in readme file

203

increased by238.33%

Worsened metrics

Lines of code

475

decreased by-0.21%

Dependency changes

• Updatedbluebird@^2.3.2

• Updateddebug@^1.0.4

• Updatedsack@^2.1.1

• Updatedtypedef@^1.1.0