easejs/doc/interop.texi

@c  This document is part of the GNU ease.js manual.
@c  Copyright (C) 2014 Free Software Foundation, Inc.
@c    Permission is granted to copy, distribute and/or modify this document
@c    under the terms of the GNU Free Documentation License, Version 1.3 or
@c    any later version published by the Free Software Foundation; with no
@c    Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c    A copy of the license is included in the section entitled ``GNU Free
@c    Documentation License''.

@node Interoperability
@chapter Interoperability
GNU ease.js is not for everyone, so it is important to play nicely with
vanilla ECMAScript so that prototypes and objects can be integrated with
the strict restrictions of ease.js (imposed by classical OOP). In general,
you should not have to worry about this: everything is designed to work
fairly transparently. This chapter will go over what ease.js intentionally
supports and some interesting concepts that may even be useful even if you
have adopted ease.js for your own projects.

@menu
* Using GNU ease.js Classes Outside of ease.js::
* Prototypally Extending Classes::
* Interoperable Polymorphism::
@end menu


@node Using GNU ease.js Classes Outside of ease.js
@section Using GNU ease.js Classes Outside of ease.js
GNU ease.js is a prototype generator---it takes the class definition,
applies its validations and conveniences, and generates a prototype and
constructor that can be instantiated and used just as any other ECMAScript
constructor/prototype. One thing to note immediately, as mentioned in
the section @ref{Defining Classes,,Defining Classes}, is that constructors
generated by ease.js may be instantiated either with or without the
@code{new} keyword:

@float Figure, f:interop-new
@verbatim
  var Foo = Class( { /*...*/ } );

  // both of these are equivalent
  Foo();
  new Foo();
@end verbatim
@caption{Constructors generated by ease.js may omit the @code{new} keyword}
@end float

ease.js convention is to omit the keyword for more concise code that is more
easily chained, but you should follow the coding conventions of the project
that you are working on.

@node Prototypally Extending Classes
@section Prototypally Extending Classes
Since @ref{Classes,,classes} are also constructors with prototypes, they may
be used as part of a prototype chain. There are, however, some important
considerations when using any sort of constructor as part of a prototype
chain.

Conventionally, prototypes are subtyped by using a new instance as the
prototype of the subtype's constructor, as so:

@float Figure, f:interop-protochain-incorrect
@verbatim
  var Foo = Class( { /*...*/ } );

  // extending class as a prototype
  function SubFoo() {};
  SubFoo.prototype = Foo();  // INCORRECT
  SubFoo.prototype.constructor = SubFoo;
@end verbatim
@caption{Incorrectly prototypally extending GNU ease.js classes}
@end float

The problem with this approach is that constructors may perform validations
on their arguments to ensure that the instance is in a consistent state. GNU
ease.js solves this problem by introducing an @code{asPrototype} method on
all classes:

@float Figure, f:interop-protochain
@verbatim
  var Foo = Class( { /*...*/ } );

  // extending class as a prototype
  function SubFoo()
  {
      // it is important to call the constructor ourselves; this is a
      // generic method that should work for all subtypes, even if SubFoo
      // implements its own __construct method
      this.constructor.prototype.__construct.apply( this, arguments );

      // OR, if SubFoo does not define its own __construct method, you can
      // alternatively do this:
      this.__construct();
  };
  SubFoo.prototype = Foo.asPrototype();  // Correct
  SubFoo.prototype.constructor = SubFoo;
@end verbatim
@caption{Correctly prototypally extending GNU ease.js classes}
@end float

The @code{asPrototype} method instantiates the class, but does not execute
the constructor. This allows it to be used as the prototype without any
issues, but it is important that the constructor of the subtype invokes the
constructor of the class, as in @ref{f:interop-protochain}. Otherwise, the
state of the subtype is undefined.

Keep in mind the following when using classes as part of the prototype
chain:

@itemize
  @item
  GNU ease.js member validations are not enforced; you will not be warned if
  an abstract method remains unimplemented or if you override a non-virtual
  method, for example. Please exercise diligence.

  @item
  It is not wise to override non-@ref{Inheritance,,virtual} methods, because
  the class designer may not have exposed a proper API for accessing and
  manipulating internal state, and may not provide proper protections to
  ensure consistent state after the method call.

  @item
  Note the @ref{Private Member Dilemma} to ensure that your prototype works
  properly in pre-ES5 environments and with potential future ease.js
  optimizations for production environments: you should not define or
  manipulate properties on the prototype that would conflict with private
  members of the subtype. This is an awkward situation, since private
  members are unlikely to be included in API documentation for a class;
  ease.js normally prevents this from happening automatically.
@end itemize


@node Interoperable Polymorphism
@section Interoperable Polymorphism
GNU ease.js encourages polymorphism through type checking. In the case of
@ref{Prototypally Extending Classes,,prototypal subtyping}, type checks will
work as expected:

@float Figure, f:typecheck-protosub
@verbatim
  var Foo = Class( {} );

  function SubFoo() {};
  SubFoo.prototype = Foo.asPrototype();
  SubFoo.constructor = Foo;

  var SubSubFoo = Class.extend( SubFoo, {} );

  // vanilla ECMAScript
  ( new Foo() ) instanceof Foo;           // true
  ( new Subfoo() ) instanceof Foo;        // true
  ( new SubSubFoo() ) instanceof Foo;     // true
  ( new SubSubFoo() ) instanceof SubFoo;  // true

  // GNU ease.js
  Class.isA( Foo, ( new Foo() ) );           // true
  Class.isA( Foo, ( new SubFoo() ) );        // true
  Class.isA( Foo, ( new SubSubFoo() ) );     // true
  Class.isA( SubFoo, ( new SubSubFoo() ) );  // true
@end verbatim
@caption{Type checking with prototypal subtypes of GNU ease.js classes}
@end float

Plainly---this means that prototypes that perform type checking for
polymorphism will accept GNU ease.js classes and vice versa. But this is not
the only form of type checking that ease.js supports.

This is the simplest type of polymorphism and is directly compatible with
ECMAScript's prototypal mode. However, GNU ease.js offers other features
that are alien to ECMAScript on its own.

@menu
* Interface Interop:: Using GNU ease.js interfaces in conjunction with
                      vanilla ECMAScript
@end menu


@node Interface Interop
@subsection Interface Interop
@ref{Interfaces}, when used within the bounds of GNU ease.js, allow for
strong typing of objects. Further, two interfaces that share the same API
are not equivalent; this permits conveying intent: Consider two interfaces
@code{Enemy} and @code{Toad}, each defining a method @code{croak}. The
method for @code{Enemy} results in its death, whereas the method for
@code{Toad} produces a bellowing call. Clearly classes implementing these
interfaces will have different actions associated with them; we would
probably not want an invincible enemy that croaks like a toad any time you
try to kill it (although that'd make for amusing gameplay).

@float figure, f:interface-croak
@verbatim
  var Enemy = Interface( { croak: [] } ),
      Toad  = Interface( { croak: [] } ),

      AnEnemy = Class.implement( Enemy ).extend( /*...*/ ),
      AToad   = Class.implement( Toad ).extend( /*...*/ );

  // GNU ease.js does not consider these interfaces to be equivalent
  Class.isA( Enemy, AnEnemy() );  // true
  Class.isA( Toad, AnEnemy() );   // false
  Class.isA( Enemy, AToad() );    // false
  Class.isA( Toad, AToad() );     // true

  defeatEnemy( AnEnemy() );  // okay; is an enemy
  defeatEnemy( AToad() );    // error; is a toad

  function defeatEnemy( enemy )
  {
      if ( !( Class.isA( Enemy, enemy ) ) ) {
          throw TypeError( "Expecting enemy" );
      }

      enemy.croak();
  }
@end verbatim
@caption{Croak like an enemy or a toad?}
@end float

In JavaScript, it is common convention to instead use @emph{duck typing},
which does not care what the intent of the interface is---it merely cares
whether the method being invoked actually exists.@footnote{``When I see a
bird that walks like a duck and swims like a duck and quacks like a duck, I
call that bird a duck.'' (James Whitcomb Riley).} So, in the case of the
above example, it is not a problem that an toad may be used in place of an
enemy---they both implement @code{croak} and so @emph{something} will
happen. This is most often exemplified by the use of object literals to
create ad-hoc instances of sorts:

@float figure, f:interface-objlit
@verbatim
  var enemy = { croak: function() { /* ... */ ) },
      toad  = { croak: function() { /* ... */ ) };

  defeatEnemy( enemy );  // okay; duck typing
  defeatEnemy( toad );   // okay; duck typing

  // TypeError: object has no method 'croak'
  defeatEnemy( { moo: function() { /*...*/ } } );

  function defeatEnemy( enemy )
  {
      enemy.croak();
  }
@end verbatim
@caption{Duck typing with object literals}
@end float

Duck typing has the benefit of being ad-hoc and concise, but places the onus
on the developer to realize the interface and ensure that it is properly
implemented. Therefore, there are two situations to address for GNU ease.js
users that prefer strongly typed interfaces:

@enumerate
 @item
 Ensure that non-ease.js users can create objects acceptable to the
 strongly-typed API; and

 @item
 Allow ease.js classes to require a strong API for existing objects.
@end enumerate

These two are closely related and rely on the same underlying concepts.

@menu
* Object Interface Compatibility:: Using vanilla ECMAScript objects where
                                   type checking is performed on GNU ease.js
                                   interfaces
* Building Interfaces Around Objects:: Using interfaces to validate APIs of
                                       ECMAScript objects
@end menu


@node Object Interface Compatibility
@subsubsection Object Interface Compatibility
It is clear that GNU ease.js' distinction between two separate interfaces
that share the same API is not useful for vanilla ECMAScript objects,
because those objects do not have an API for implementing interfaces (and if
they did, they wouldn't be ease.js' interfaces). Therefore, in order to
design a transparently interoperable system, this distinction must be
removed (but will be @emph{retained} within ease.js' system).

The core purpose of an interface is to declare an expected API, providing
preemptive warnings and reducing the risk of runtime error. This is in
contrast with duck typing, which favors recovering from errors when (and if)
they occur. Since an ECMAScript object cannot implement an ease.js interface
(if it did, it'd be using ease.js), the conclusion is that ease.js should
fall back to scanning the object to ensure that it is compatible with a
given interface.

A vanilla ECMAScript object is compatible with an ease.js interface if it
defines all interface members and meets the parameter count requirements of
those members.

@float Figure, f:interface-compat
@verbatim
  var Duck = Interface( {
    quack: [ 'str' ],
    waddle: [],
  } );

  // false; no quack
  Class.isA( Duck, { waddle: function() {} } );

  // false; quack requires one parameter
  Class.isA( Duck, {
    quack: function() {},
    waddle: function() {},
  } );

  // true
  Class.isA( Duck, {
    quack: function( str ) {},
    waddle: function() {},
  } );

  // true
  function ADuck() {};
  ADuck.prototype = {
    quack: function( str ) {},
    waddle: function() {},
  };
  Class.isA( Duck, ( new ADuck() ) );
@end verbatim
@caption{Vanilla ECMAScript object interface compatibility}
@end float


@node Building Interfaces Around Objects
@subsubsection Building Interfaces Around Objects
A consequence of @ref{Object Interface Compatibility,,the previous section}
is that users of GNU ease.js can continue to use strongly typed interfaces
even if the objects they are interfacing with do not support ease.js'
interfaces. Consider, for example, a system that uses @code{XMLHttpRequest}:

@float Figure, f:interface-xmlhttp
@verbatim
  // modeled around XMLHttpRequest
  var HttpRequest = Interface(
  {
      abort: [],
      open: [ 'method', 'url', 'async', 'user', 'password' ],
      send: [],
  } );

  var FooApi = Class(
  {
      __construct: function( httpreq )
      {
          if ( !( Class.isA( HttpRequest, httpreq ) ) )
          {
              throw TypeError( "Expecting HttpRequest" );
          }

          // ...
      }
  } );

  FooApi( new XMLHttpRequest() );  // okay
@end verbatim
@caption{Building an interface around needed functionality of
XMLHttpRequest}
@end float

This feature permits runtime polymorphism with preemptive failure instead of
inconsistently requiring duck typing for external objects, but interfaces for
objects handled through ease.js.