Support init or setup returning something other than new instance

can-construct.js

@@ -284,6 +284,9 @@ assign(Construct, {
 				writable: true
 			});
 			args = inst.setup.apply(inst, arguments);
+			if (args instanceof Construct.ReturnValue){
+				return args.value;
+			}
 			inst.__inSetup = false;
 		}
 		// Call `init` if there is an `init`
@@ -526,6 +529,49 @@ assign(Construct, {
 	 * dog.speak(); // 'woof'
 	 * blackMamba.speak(); // 'ssssss'
 	 * ```
+	 * 
+	 * ## Alternative value for a new instance
+	 * 
+	 * Sometimes you may want to return some custom value instead of a new object when creating an instance of your class.
+	 * For example, you want your class to act as a singleton, or check whether an item with the given id was already
+	 * created and return an existing one from your cache store (e.g. using [can-connect/constructor/store/store]).
+	 * 
+	 * To achieve this you can return [can-construct.ReturnValue] from `setup` method of your class.
+	 * 
+	 * Lets say you have `myStore` to cache all newly created instances. And if an item already exists you want to merge
+	 * the new data into the existing instance and return the updated instance.
+	 * 
+	 * ```
+	 * const myStore = {};
+	 * 
+	 * const Item = Construct.extend({
+	 *     setup: function(params){
+	 *         if (myStore[params.id]){
+	 *             var item = myStore[params.id];
+	 *             
+	 *             // Merge new data to the existing instance:
+	 *             Object.keys( params ).forEach(function( key ){
+	 *                 item[key] = params[key];
+	 *             });
+	 *             
+	 *             // Return the updated item:
+	 *             return new Construct.ReturnValue( item );
+	 *         } else {
+	 *             return [params];
+	 *         }
+	 *     },
+	 *     init: function(params){
+	 *         this.id = params.id;
+	 *         this.name = params.name;
+	 *         
+	 *         // Save to cache store:
+	 *         myStore[this.id] = this;
+	 *     }
+	 * });
+	 * 
+	 * const item_1  = new Item( {id: 1, name: "One"} );
+	 * const item_1a = new Item( {id: 1, name: "OnePlus"} )
+	 * ```
 	 */
 	extend: function (name, staticProperties, instanceProperties) {
 		var shortName = name,
@@ -663,6 +709,40 @@ assign(Construct, {
 		 * console.log(Counter.count); // 1
 		 * ```
 		 */
+	},
+	/**
+	 * @function can-construct.ReturnValue ReturnValue
+	 * @parent can-construct.static
+	 * 
+	 * A constructor function which `value` property will be used as a value for a new instance. 
+	 * 
+	 * @signature `new Construct.ReturnValue( value )`
+	 * 
+	 * 	@param {*} value A value to be used for a new instance instead of a new object.
+	 * 
+	 * ```
+	 * const Student = function( name, school ){
+	 *     this.name = name;
+	 *     this.school = school;
+	 * } 
+	 * 
+	 * const Person = Construct.extend({
+	 *     setup: function( options ){
+	 *         if (options.school){
+	 *             return new Constructor.ReturnValue( new Student( options.name, options.school ) );
+	 *         } else {
+	 *             return [options];
+	 *         }
+	 *     }
+	 * });
+	 * 
+	 * const myPerson = new Person( {name: "Peter", school: "UFT"} );
+	 * 
+	 * myPerson instanceof Student // => true
+	 * ```
+   */
+	ReturnValue: function(value){
+		this.value = value;
 	}
 });
 /**
@@ -675,8 +755,9 @@ assign(Construct, {
  *
  * @param {*} args The arguments passed to the constructor.
  *
- * @return {Array|undefined} If an array is returned, the array's items are passed as
- * arguments to [can-construct::init init]. The following example always makes
+ * @return {Array|undefined|can-construct.ReturnValue} If an array is returned, the array's items are passed as
+ * arguments to [can-construct::init init]. If [can-construct.ReturnValue] is returned then the value that passed to it
+ * will be used as a value for a new instance. The following example always makes
  * sure that init is called with a jQuery wrapped element:
  *
  * ```js

can-construct_test.js

@@ -225,3 +225,38 @@ QUnit.test("setters not invoked on extension (#28)", function(){
 	extending = false;
 	new Base().something = "foo";
 });
+
+QUnit.test("return alternative value simple", function(){
+	var Alternative = function(){};
+	var Base = Construct.extend({
+		setup: function(){
+			return new Construct.ReturnValue( new Alternative() );
+		}
+	});
+	QUnit.ok(new Base() instanceof Alternative, "Should create an instance of Alternative");
+});
+
+QUnit.test("return alternative value on setup (full case)", function(){
+	var Student = function(name, school){
+		this.name = name;
+		this.school = school;
+		this.isStudent = true;
+	};
+	var Person = Construct.extend({
+		setup: function(opts){
+			if (opts.age >= 16){
+				return new Construct.ReturnValue( new Student(opts.name, opts.school) );
+			}
+			opts.isStudent = false;
+			return [opts];
+		},
+		init: function(params){
+			this.age = params.age;
+			this.name = params.name;
+			this.isStudent = params.isStudent;
+		}
+	});
+	QUnit.equal(new Person({age: 12}).isStudent, false, "Age 12 cannot be a student");
+	QUnit.equal(new Person({age: 30}).isStudent, true, "Age 20 can be a student");
+	QUnit.ok(new Person({age: 30}) instanceof Student, "Should return an instance of Student");
+});