如何将接口实现传递给Google Closure JavaScript库中的函数

Question

I would like to define an interface and let the implementation on the library user, and make sure, that in some function, the input parameter is an implementation of the given interface. How to do that?

Example:

/**
 * @interface
 */
var FooInterface = function(){};

/**
 * nothing special
 */
FooInterface.prototype.bar = function(){};

/**
 * @constructor
 * @implements {FooInterface}
 */
var Foo = function() { /* hello world */ };

/**
 * @override
 */
Foo.prototype.bar = function() { /* do something */ };


/**
 * ?? How to annotate, that 'foo' is an implementation of FooInterface,
 * but also instance of something else ??
 * @function
 * @param {FooInterface} foo
 */
 var the_function = function(foo) {
     // foo should be actually instance of Foo, but I want to make sure, 
     // it is an implementation of FooInterface
     // how to indicate that?
     foo.bar(); // code continues
 }

Answer 1

EDIT: The asker expanded his question in another forum, whose discussion thread provides additional insights.

https://groups.google.com/forum/#!topic/closure-library-discuss/fF1epI9BPyA

---

To ensure your library function the_function takes the implementation of an interface, but do not wish to include the definition of what could possibly implement it (leave Foo completely in the hands of the user), you can simply tighten the parameter to a non-nullable interface type:

// ...snip: FooInterface declaration...
/**
 * @param {!FooInterface} foo
 */
var the_function = function(foo) {
  // non-nullable ensures that something like null.bar() is not invoked here.
  foo.bar(); 
};

The user will have to define his own implementation of FooInterface , and pass it as the foo parameter. If he were to pass FooInterface the compiler, running with advanced optimizations, will detect it is not a constructor (as interfaces and constructors are mutually exclusive) and output the warning:

JSC_TYPE_MISMATCH: actual parameter 1 of the_function does not match formal parameter
found   : function (this:FooInterface): ?
required: FooInterface at line ... character ...

So, by tightening the interface parameter type your requirement is met: "parameter is both an implementation of an interface and instance of something else".

---

Another approach is to provide a minimally functional implementation that can both fulfill the execution of the_function within your library code, and serve as the blueprint of the user's implementation. You can do this by including Foo in your library code and make the definition of the_function reliant on Foo :

// ...snip: FooInterface declaration...
/**
 * @constructor
 * @implements {FooInterface}
 */
var Foo = function() {/* ... */};

/** @override */
Foo.prototype.bar = function() {/* ... */};

/** @param {!Foo} foo */
var the_function = function(foo) {
  foo.bar();
};

In this case, the_function need not be annotated with anything referencing FooInterface . The compiler will have required that the above interface check is fulfilled. If Foo fails to implement bar() , it will output the warning: JSC_INTERFACE_METHOD_NOT_IMPLEMENTED: property bar on interface FooInterface is not implemented by type Foo at line ... character ... .

---

To sum it up, both approaches fulfill your requirement, but mean different things to the user of your library:

1. With the first approach, your user needs to provide a whole new type annotated with @implements .
2. With the second approach, your user may have to subclass Foo with his own implementation. Referencing the interface may not be needed. Basic functionality laid out in Foo could be reused.

Answer 2

If you can just use the interface type FooInterface as the annotated type (as in your example), which I'm not sure is valid, then you can test the object for the concrete type within the_function using instanceof . See: https://groups.google.com/forum/m/#!topic/closure-library-discuss/AphCYwDbI7w

As I said before, I am not sure if you can use interface types as the annotated param type. If not, you will probably have to use the unknown type annotation (?) and duck-test the object. Just make sure you cast it to the interface type before accessing fields in any way, so the compiler can properly resolve property names in Advanced Compilation mode.

I'd do something along these lines:

/**
  * @function
  * @param {*} foo
  */
var the_function = function(foo) {
    // foo can be any object, we just want to make sure, 
    // it is implementing of FooInterface
    if (foo instanceof FooInterface) {
        (/** @type{FooInterface}*/(foo)).bar();
    } 
 };