bind factory: create partial function applications with injected arguments

docs/components.md

@@ -49,8 +49,9 @@ are:
 1. `module` - loads a module (AMD or CommonJS, depending on your environment)
 2. `create` - creates objects using a constructor function, regular function, or by using Object.create.
 3. `compose` - composes functions using a declarative syntax
-4. `literal` - wire will not parse the right-hand side, but rather use it verbatim as a component
-5. `wire` - recursively invokes wire on another wire spec
+4. `partial` - creates a partial function application with the supplied arguments
+5. `literal` - wire will not parse the right-hand side, but rather use it verbatim as a component
+6. `wire` - recursively invokes wire on another wire spec
 
 ## Using factories
 
@@ -214,6 +215,23 @@ Functions are first-class citizens in wire.js.  For example, you can [use them a
 
 See [Composing Functions](functions.md#composing-functions) for more information on composing new functions with the compose factory.
 
+## partial
+
+The partial factory creates a partial function application with the supplied arguments.
+
+### Syntax
+
+```js
+myComponent: {
+	partial: {
+		fn: { module: 'my/app/ModuleA' },
+
+		// Required: use these args to create a partially applied my/app/ModuleA
+		args: [arg1, arg2, arg3...]
+	}
+}
+```
+
 ## literal
 
 It can be useful to have object literals in [wire specs](concepts.md#wire-specs) for various reasons, such as reference data or common configuration shared between several components.  Most times, object literals can be declared directly:

lib/plugin/basePlugin.js

@@ -206,6 +206,22 @@ define(function(require) {
 		resolver.resolve(wire.loadModule(componentDef.options));
 	}
 
+	function partialFactory(resolver, componentDef, wire) {
+		var partial, fn, args, appliedFn;
+
+		partial = componentDef.options;
+		fn = wire(partial.fn);
+		args = partial.args ? wire(asArray(partial.args)) : [];
+
+		appliedFn = when.join(fn, args).spread(applyFunction);
+
+		resolver.resolve(appliedFn);
+
+		function applyFunction(fn, args) {
+			return functional.partial.apply(functional, [fn].concat(args));
+		}
+	}
+
 	/**
 	 * Factory that uses an AMD module either directly, or as a
 	 * constructor or plain function to create the resulting item.
@@ -265,6 +281,7 @@ define(function(require) {
 	pluginInstance = {
 		factories: {
 			module: moduleFactory,
+			partial: partialFactory,
 			create: instanceFactory,
 			literal: literalFactory,
 			prototype: protoFactory,

test/node/lib/plugin/basePlugin-test.js

@@ -276,6 +276,99 @@ buster.testCase('lib/plugin/basePlugin', {
 		}
 	},
 
+	'partial factory': {
+		'should apply a single argument': function() {
+			var spy, add;
+
+			spy = this.spy();
+			add = function(x, y) { this(); return x + y; }.bind(spy);
+
+			return createContext({
+				increment: {
+					partial: {
+						fn: add,
+						args: 1
+					}
+				}
+			}).then(
+				function(context) {
+					var result = context.increment(4);
+					assert.calledOnce(spy);
+					assert.equals(result, 5);
+				},
+				fail
+			);
+		},
+
+		'should apply multiple arguments': function() {
+			var spy, add;
+
+			spy = this.spy();
+			add = function(x, y) { this(); return x + y; }.bind(spy);
+
+			return createContext({
+				three: {
+					partial: {
+						fn: add,
+						args: [1, 2]
+					}
+				}
+			}).then(
+				function(context) {
+					var result = context.three();
+					assert.calledOnce(spy);
+					assert.equals(result, 3);
+				},
+				fail
+			);
+		},
+
+		'should wire modules': function() {
+			return createContext({
+				increment: {
+					partial: {
+						fn: { module: '../../fixtures/function' },
+						args: 1
+					}
+				}
+			}).then(
+				function(context) {
+					assert.equals(context.increment(2), 3);
+				},
+				fail
+			);
+		},
+
+		'should wire references': function() {
+			var spy, add;
+
+			spy = this.spy();
+			add = function(x, y) { this(); return x + y; }.bind(spy);
+
+			return createContext({
+				increment: {
+					partial: {
+						fn: add,
+						args: 1
+					}
+				},
+				three: {
+					partial: {
+						fn: { $ref: 'increment' },
+						args: 2
+					}
+				}
+			}).then(
+				function(context) {
+					var result = context.three();
+					assert.calledOnce(spy);
+					assert.equals(result, 3);
+				},
+				fail
+			);
+		}
+	},
+
 	'create factory': {
 		'should call non-constructor functions': function() {
 			var spy = this.spy();