Support for @optional dependencies

README.md

@@ -235,6 +235,7 @@ Let's take a look to the InversifyJS features!
 - [Declaring container modules](https://github.com/inversify/InversifyJS/blob/master/wiki/container_modules.md)
 - [Container snapshots](https://github.com/inversify/InversifyJS/blob/master/wiki/container_snapshots.md)
 - [Controlling the scope of the dependencies](https://github.com/inversify/InversifyJS/blob/master/wiki/scope.md)
+- [Declaring optional dependencies](https://github.com/inversify/InversifyJS/blob/master/wiki/optional_dependencies.md)
 - [Injecting a constant or dynamic value](https://github.com/inversify/InversifyJS/blob/master/wiki/value_injection.md)
 - [Injecting a class constructor](https://github.com/inversify/InversifyJS/blob/master/wiki/constructor_injection.md)
 - [Injecting a Factory](https://github.com/inversify/InversifyJS/blob/master/wiki/factory_injection.md)

src/annotation/optional.ts

@@ -0,0 +1,12 @@
+import { Metadata } from "../planning/metadata";
+import { tagParameter } from "./decorator_utils";
+import * as METADATA_KEY from "../constants/metadata_keys";
+
+function optional() {
+    return function(target: any, targetKey: string, index: number) {
+        let metadata = new Metadata(METADATA_KEY.OPTIONAL_TAG, true);
+        return tagParameter(target, targetKey, index, metadata);
+    };
+}
+
+export { optional };

src/constants/metadata_keys.ts

@@ -7,6 +7,9 @@ export const NAME_TAG = "name";
 // The for unmanaged injections (in base classes when using inheritance)
 export const UNMANAGED_TAG = "unmanaged";
 
+// The for optional injections
+export const OPTIONAL_TAG = "optional";
+
 // The type of the binding at design time
 export const INJECT_TAG = "inject";
 

src/interfaces/interfaces.ts

@@ -150,6 +150,7 @@ namespace interfaces {
         matchesArray(name: interfaces.ServiceIdentifier<any>): boolean;
         isNamed(): boolean;
         isTagged(): boolean;
+        isOptional(): boolean;
         matchesNamedTag(name: string): boolean;
         matchesTag(key: string|number|symbol): (value: any) => boolean;
     }

src/inversify.ts

@@ -4,6 +4,7 @@ export { injectable } from "./annotation/injectable";
 export { tagged } from "./annotation/tagged";
 export { named } from "./annotation/named";
 export { inject } from "./annotation/inject";
+export { optional } from "./annotation/optional";
 export { unmanaged } from "./annotation/unmanaged";
 export { multiInject } from "./annotation/multi_inject";
 export { targetName } from "./annotation/target_name";

src/planning/planner.ts

@@ -91,11 +91,15 @@ function _validateActiveBindingCount(
     switch (bindings.length) {
 
         case BindingCount.NoBindingsAvailable:
-            let serviceIdentifierString = getServiceIdentifierAsString(serviceIdentifier);
-            let msg = ERROR_MSGS.NOT_REGISTERED;
-            msg += listMetadataForTarget(serviceIdentifierString, target);
-            msg += listRegisteredBindingsForServiceIdentifier(container, serviceIdentifierString, getBindings);
-            throw new Error(msg);
+            if (target.isOptional() === true) {
+                return bindings;
+            } else {
+                let serviceIdentifierString = getServiceIdentifierAsString(serviceIdentifier);
+                let msg = ERROR_MSGS.NOT_REGISTERED;
+                msg += listMetadataForTarget(serviceIdentifierString, target);
+                msg += listRegisteredBindingsForServiceIdentifier(container, serviceIdentifierString, getBindings);
+                throw new Error(msg);
+            }
 
         case BindingCount.OnlyOneBindingAvailable:
             if (target.isArray() === false) {

src/planning/target.ts

@@ -74,6 +74,10 @@ class Target implements interfaces.Target {
         });
     }
 
+    public isOptional(): boolean {
+        return this.matchesTag(METADATA_KEY.OPTIONAL_TAG)(true);
+    }
+
     public getNamedTag(): interfaces.Metadata | null {
         if (this.isNamed()) {
             return this.metadata.filter((m) => m.key === METADATA_KEY.NAMED_TAG)[0];

src/resolution/resolver.ts

@@ -26,6 +26,11 @@ function _resolveRequest(request: interfaces.Request): any {
     } else {
 
         let result: any = null;
+
+        if (request.target.isOptional() === true && bindings.length === 0) {
+            return undefined;
+        }
+
         let binding = bindings[0];
         let isSingleton = binding.scope === BindingScopeEnum.Singleton;
 

test/annotation/optional.test.ts

@@ -0,0 +1,110 @@
+import { expect } from "chai";
+import { Container, injectable, inject, optional } from "../../src/inversify";
+
+describe("@optional", () => {
+
+  it("Should allow to flag dependencies as optional", () => {
+
+      @injectable()
+      class Katana {
+          public name: string;
+          public constructor() {
+              this.name = "Katana";
+          }
+      }
+
+      @injectable()
+      class Shuriken {
+          public name: string;
+          public constructor() {
+              this.name = "Shuriken";
+          }
+      }
+
+      @injectable()
+      class Ninja {
+          public name: string;
+          public katana: Katana;
+          public shuriken: Shuriken;
+          public constructor(
+              @inject("Katana") katana: Katana,
+              @inject("Shuriken") @optional() shuriken: Shuriken
+          ) {
+              this.name = "Ninja";
+              this.katana = katana;
+              this.shuriken = shuriken;
+          }
+      }
+
+      let container = new Container();
+
+      container.bind<Katana>("Katana").to(Katana);
+      container.bind<Ninja>("Ninja").to(Ninja);
+
+      let ninja =  container.get<Ninja>("Ninja");
+      expect(ninja.name).to.eql("Ninja");
+      expect(ninja.katana.name).to.eql("Katana");
+      expect(ninja.shuriken).to.eql(undefined);
+
+      container.bind<Shuriken>("Shuriken").to(Shuriken);
+
+      ninja =  container.get<Ninja>("Ninja");
+      expect(ninja.name).to.eql("Ninja");
+      expect(ninja.katana.name).to.eql("Katana");
+      expect(ninja.shuriken.name).to.eql("Shuriken");
+
+  });
+
+  it("Should allow to set a default value for dependencies flagged as optional", () => {
+
+      @injectable()
+      class Katana {
+          public name: string;
+          public constructor() {
+              this.name = "Katana";
+          }
+      }
+
+      @injectable()
+      class Shuriken {
+          public name: string;
+          public constructor() {
+              this.name = "Shuriken";
+          }
+      }
+
+      @injectable()
+      class Ninja {
+          public name: string;
+          public katana: Katana;
+          public shuriken: Shuriken;
+          public constructor(
+              @inject("Katana") katana: Katana,
+              @inject("Shuriken") @optional() shuriken: Shuriken = { name: "DefaultShuriken" }
+          ) {
+              this.name = "Ninja";
+              this.katana = katana;
+              this.shuriken = shuriken;
+          }
+      }
+
+      let container = new Container();
+
+      container.bind<Katana>("Katana").to(Katana);
+      container.bind<Ninja>("Ninja").to(Ninja);
+
+      let ninja =  container.get<Ninja>("Ninja");
+      expect(ninja.name).to.eql("Ninja");
+      expect(ninja.katana.name).to.eql("Katana");
+      expect(ninja.shuriken.name).to.eql("DefaultShuriken");
+
+      container.bind<Shuriken>("Shuriken").to(Shuriken);
+
+      ninja =  container.get<Ninja>("Ninja");
+      expect(ninja.name).to.eql("Ninja");
+      expect(ninja.katana.name).to.eql("Katana");
+      expect(ninja.shuriken.name).to.eql("Shuriken");
+
+  });
+
+});

test/bugs/bugs.test.ts

@@ -71,7 +71,9 @@ describe("Bugs", () => {
 
     });
 
-    it("Should not throw when args length of base and derived class match (inject into the derived class)", () => {
+    it("Should not throw when args length of base and derived class match", () => {
+
+        // Injecting into the derived class
 
         @injectable()
         class Warrior {
@@ -103,7 +105,9 @@ describe("Bugs", () => {
 
     });
 
-    it("Should not throw when args length of base and derived class match (inject into the derived class with multiple args)", () => {
+    it("Should not throw when args length of base and derived class match", () => {
+
+        // Injecting into the derived class with multiple args
 
         @injectable()
         class Warrior {

wiki/optional_dependencies.md

@@ -0,0 +1,86 @@
+# Optional dependencies
+
+We can declare an optional dependency using the `@optional()` decorator:
+
+```ts
+@injectable()
+class Katana {
+    public name: string;
+    public constructor() {
+        this.name = "Katana";
+    }
+}
+
+@injectable()
+class Shuriken {
+    public name: string;
+    public constructor() {
+        this.name = "Shuriken";
+    }
+}
+
+@injectable()
+class Ninja {
+    public name: string;
+    public katana: Katana;
+    public shuriken: Shuriken;
+    public constructor(
+        @inject("Katana") katana: Katana,
+        @inject("Shuriken") @optional() shuriken: Shuriken // Optional!
+    ) {
+        this.name = "Ninja";
+        this.katana = katana;
+        this.shuriken = shuriken;
+    }
+}
+
+let container = new Container();
+
+container.bind<Katana>("Katana").to(Katana);
+container.bind<Ninja>("Ninja").to(Ninja);
+
+let ninja =  container.get<Ninja>("Ninja");
+expect(ninja.name).to.eql("Ninja");
+expect(ninja.katana.name).to.eql("Katana");
+expect(ninja.shuriken).to.eql(undefined);
+
+container.bind<Shuriken>("Shuriken").to(Shuriken);
+
+ninja =  container.get<Ninja>("Ninja");
+expect(ninja.name).to.eql("Ninja");
+expect(ninja.katana.name).to.eql("Katana");
+expect(ninja.shuriken.name).to.eql("Shuriken");
+```
+
+In the example we can see how the first time we resolve `Ninja`, its 
+property `shuriken` is undefined because no binsings have been declared
+for `Shuriken` and the property is annotated with the `@optional()` decorator.
+
+After declaring a binding for `Shuriken`:
+
+```ts
+container.bind<Shuriken>("Shuriken").to(Shuriken);
+```
+
+All the resolved instances of `Ninja` will contain an instance of `Shuriken`.
+
+## Default values
+If a dependency is decorated with the `@optional()` decorator, we will be able to to declare
+a default value just like you can do in any other TypeScript application:
+
+```ts
+@injectable()
+class Ninja {
+    public name: string;
+    public katana: Katana;
+    public shuriken: Shuriken;
+    public constructor(
+        @inject("Katana") katana: Katana,
+        @inject("Shuriken") @optional() shuriken: Shuriken = { name: "DefaultShuriken" } // Default value!
+    ) {
+        this.name = "Ninja";
+        this.katana = katana;
+        this.shuriken = shuriken;
+    }
+}
+```

wiki/readme.md

@@ -16,6 +16,7 @@ Welcome to the InversifyJS wiki!
 - [Declaring container modules](https://github.com/inversify/InversifyJS/blob/master/wiki/container_modules.md)
 - [Container snapshots](https://github.com/inversify/InversifyJS/blob/master/wiki/container_snapshots.md)
 - [Controlling the scope of the dependencies](https://github.com/inversify/InversifyJS/blob/master/wiki/scope.md)
+- [Declaring optional dependencies](https://github.com/inversify/InversifyJS/blob/master/wiki/optional_dependencies.md)
 - [Injecting a constant or dynamic value](https://github.com/inversify/InversifyJS/blob/master/wiki/value_injection.md)
 - [Injecting a class constructor](https://github.com/inversify/InversifyJS/blob/master/wiki/constructor_injection.md)
 - [Injecting a Factory](https://github.com/inversify/InversifyJS/blob/master/wiki/factory_injection.md)