Page History

...

No matter how compilation unit initialization is triggered, it is always executed as a whole:

1. first, its superclass is created (which creates its superclass the compilation unit containing the superclass of its primary declaration is initialized (which initializes its "super compilation unit" transitively)
2. then, all static initializers are evaluated, in the order in which they appear in the source code
3. last, all static code statements are executed, in the order in which they appear in the source code

Note that 1. and 2. only apply to compilation units whose primary declaration is a class.

Implementation Solution

For our implementation, we have to take into account that in a browser, code loading cannot be done synchronously "on demand". Thus we use AMD and map compilation units to AMD modules. The AMD loader resolves all static dependencies and loads the code of all compilation units that are potentially needed at runtime. We have to take care of initializing those compilation units only when they are actually used. This determines the value of a compilation unit the corresponding AMD module returns: Instead of the primary declaration itself, the return value is a compilation unit object from which you can retrieve the primary declaration. The trick is that the compilation unit self-initializes when the primary declaration is first requested!

We could implement the primary declaration request by a method of the compilation unit object. But this would involve a function call for each retrieval of the primary declaration, even if the compilation has already been initialized. A trick for an efficient implementation is to use a get property that, upon its first invocation, initializes the compilation unit and replaces itself by a simple field with a direct reference to the primary declaration. For the sake of brevity and readability (we want the reader to mainly ignore this helper property), let's call that property _ (underscore).

Example

Here is a compilation unit with an ActionScript class with a reference to another class:

compilation unit com/acme/ThisClass.as:

package com.acme {
import com.acme.OtherClass;

public class ThisClass {
  public function ThisClass() {
    OtherClass.doSomething();
  }
  ...
}

trace("ThisClass is being initialized...");

}

would in generated JavaScript become

define("com/acme/ThisClass", ["com/acme/OtherClass"], function(OtherClass) {
  return Object.defineProperty({}, "_", {
    configurable: true, // so we can replace it later!
    get: function() {
      function ThisClass() {
        OtherClass._.doSomething();
      }
      // replace "_" by simple property, returning the class:
      Object.defineProperty(this, "_", { value: ThisClass });
      ...
      trace("ThisClass is being initialized...");
      return ThisClass;
    }
  });
});

The first argument to define can be left out when the definition is the only one contained in the file, then the module name is derived from the file name.

Note how the definition of ThisClass, instead of directly returning its constructor function, returns an object with a get property _, and how its implementation replaces that property by a read-only reference to the constructor (that's why it has to be configurable first).
Also note that we use OtherClass as a reference to the compilation unit containing OtherClass as its primary declaration, and so have to rewrite normal access to the class by OtherClass._.

Non-ES5 Browser Issues

Since for the time being, we still target Internet Explorer 8 (or even 7), we need a solution that also works without get properties, so we need a more sophisticated solution for the _ property.
In order not to always need to perform a function call (which results in a runtime penalty and is distracting during debugging), we try to read the field first and only call the function in case the property is not yet defined. Following the general pattern of naming explicit get functions (see below), the factory function for IE8 would be called _$get, resulting in the following expression to access a class from potentially not-yet-initialized compilation unit: (OtherClass_._ || OtherClass_._$get())

Packages

In ActionScript, packages do not exist at run-time, instead they lead to primary declarations having a fully qualified name to avoid name clashes of global identifiers.
Mapping compilation units to AMD modules, it is straight-forward to define a primary declaration that is inside a package as a module with the fully qualified name of that class. AMD modules usually use nested directories and thus slashes ("/") instead of dots.

Looking at how classes are usually used in ActionScript, it turns out that they have to be imported (in contrast to Java, even if they are used by their fully-qualified names in the code!) and are only used by their fully-qualified names in the rare case of local name clashes.
When a module with a fully qualified name / path is required (loaded), it is assigned to a callback parameter, so that there is no need to use the fully qualified name. Only on name-clashes between un-qualified names, the parameter has to be renamed, for example by using the fully-qualified names with "." replaced by "$".

Conclusion

Granted, simulating compilation units and exact static code execution makes the solution a bit more complex, but it is an important AS3 language feature, and using the property access trick makes the implementation quite efficient, at least in modern browsers. In many cases, creating classes only when they are actually needed even increases performance, at least application start-up time, but also when many static dependencies are not actually needed at runtime at all.

Classes

Like most JavaScript frameworks, we simulate classes by a constructor function and its prototype chain.
The ES5 API Object.create(prototype,propertyDescriptors) serves this task very well.
While members are properties of the constructor function prototype, static members are properties of the constructor function itself.
Non-public members are discussed in a dedicated sub-section.

Class structure

The translation pattern is a follows:

public class Foo extends Bar {
  // constructor
  public function Foo(/*constructor parameters*/) {
    // constructor code
  }
  // member declarations
  ...
  // static member declarations
  ...
}

becomes

function Foo(/*constructor parameters*/) {
  // constructor code
}
Object.defineProperties(Foo, {
  ... // rewritten static member declarations
});
Foo.prototype = Object.create(Bar.prototype, {
  constructor: { value: Foo },
  ... // rewritten member declarations
});

The constructor property has to be defined explicitly, as otherwise, a subclass would inherit that property from its superclass, resulting in the subclass having the same constructor as its superclass.

Members and visibility (public, protected, internal, private)

Only public and protected members should be stored as properties of the constructor function / its prototype as-is. For protected members, access rights are checked by the compiler.
For private and internal members, we have to avoid name-clashes. There are different cases:

• Private methods (non-static as well as static ones) and private static fields are declared in a new scope, shared by all class members. Thus, they are visible for every method, but not from outside. Non-static private method calls have to be rewritten to run with the correct this.
• Private non-static fields and internal members are renamed: they are post-fixed by $ plus the inheritance level of the declaring class, so that they cannot name-clash with fields of the same name, declared in a subclass or superclass. The inheritance level is a number starting at 0 for Object, continuing with 1 for each direct subclass of Object, then 2 for classes inheriting from these classes, and so on. So for example a private field foo in a class extending Object would be renamed to foo$1. Internal members are also renamed, because they could name-clash with members of the same name, declared in a subclass or superclass residing in another package.

Interfaces plus "is" and "as" operator

In ActionScript, interfaces are mainly used by the compiler for type checking. However, type checks can also be performed at runtime, using the AS3 operators instanceof, is, and as. instanceof only works for classes and automatically has the correct semantics when simulating classes via the prototype chain, so it can be used as-is in JavaScript.
x as T is simply defined as x is T ? x : null and would be implemented as a runtime helper function.
So the only operator we really have to simulate is is. To do so, we need some information about interfaces:

• for a class, the set of interfaces it implements
• for an interface, the set of interfaces it extends

For easy on-demand loading of the second information, we should implement interfaces as AMD modules, too. The AMD value of an interface could simply be set set of extended interfaces, but I chose to use a function that receives an object and sets the names of all extended interfaces as keys in that object (the values do not matter, they are simply true). This implementation makes it easy and efficient to unite interfaces: simply apply all interface functions on an empty object.
A class definition requires all AMD modules of interfaces it implements and can thus easily create the set of all interfaces it (transitively) implements. This set is stored as a static meta property, let's call it $implements.
It is convenient to have a check whether a given object implements an interface as a method isInstance(object) each interface provides. This method has to check whether the given object's constructor (its class) has a $implements property, and if so, whether the interface's name is contained in $implements:

function isInstance(object) {
  return object !== null && typeof object === "object" &&
         !!object.constructor.$implements &&
         fullyQualifiedName in object.constructor.$implements;
}

where fullyQualifiedName is the fully qualified name of the interface.

The is function now has to tackle some special cases, then check instanceof, and finally check whether T is an interface, and if so, call its isInstance() method:

function is(object, type) {
  return !!type && object !== undefined && object !== null &&
         (object instanceof type ||
          typeof type.isInstance === "function" && type.isInstance(object));
}

Parameter default values

TODO

Rest (...) parameter

TODO

Bound methods

Circular Dependencies

Compilation units are allowed to have circular dependencies (e.g. class A uses a constant from class B and class B calls a static method of class A).
This is important for our JavaScript solution, as it means that a compilation unit reference must be available early, to allow mutual references between compilation units.

Packages

In ActionScript, packages do not exist at run-time, instead they lead to primary declarations having a fully qualified name to avoid name clashes of global identifiers.
Mapping compilation units to AMD modules, it is straight-forward to define a primary declaration that is inside a package as a module with the fully qualified name of that class. AMD modules usually use nested directories and thus slashes ("/") instead of dots.

Looking at how classes are usually used in ActionScript, it turns out that they have to be imported (in contrast to Java, even if they are used by their fully-qualified names in the code!) and are only used by their fully-qualified names in the rare case of local name clashes.
When a module with a fully qualified name / path is required (loaded), it is assigned to a callback parameter, so that there is no need to use the fully qualified name. Only on name-clashes between un-qualified names, the parameter has to be renamed, for example by using the fully-qualified names with "." replaced by "$".

Implementation Solution

For our implementation, we have to take into account that in a browser, code loading cannot be done synchronously "on demand". Thus we use AMD and map compilation units to AMD modules. The AMD loader resolves all static dependencies and loads the code of all compilation units that are potentially needed at runtime. We have to take care of initializing those compilation units only when they are actually used. This determines the value of a compilation unit the corresponding AMD module returns: Instead of the primary declaration itself, the return value is a compilation unit object from which you can retrieve the primary declaration. The trick is that the compilation unit self-initializes when the primary declaration is first requested!

We could implement the primary declaration request by a method of the compilation unit object. But this would involve a function call for each retrieval of the primary declaration, even if the compilation has already been initialized. A trick for an efficient implementation is to use a get property that, upon its first invocation, initializes the compilation unit and replaces itself by a simple field with a direct reference to the primary declaration. For the sake of brevity and readability (we want the reader to mainly ignore this helper property), let's call that property _ (underscore).

Following from circular dependencies being allowed (see above), we have to use a certain AMD format, where the module value is an object created and handed-in by the module loader (usually called exports, but to avoid name clashes, we call it $exports), which is then populated by the module code.

Example

Here is a compilation unit with an ActionScript class with a reference to another class:

compilation unit com/acme/ThisClass.as:

package com.acme {
import com.acme.OtherClass;

public class ThisClass {
  public function ThisClass() {
    OtherClass.doSomething();
  }
  ...
}

trace("ThisClass is being initialized...");

}

would in generated JavaScript become

define("com/acme/ThisClass", ["exports", "com/acme/OtherClass"], function($exports, OtherClass) {
  Object.defineProperty($exports, "_", {
    configurable: true, // so we can replace it later!
    get: function() {
      function ThisClass() {
        OtherClass._.doSomething();
      }
      // replace "_" by simple property, returning the class:
      Object.defineProperty(this, "_", { value: ThisClass });
      ...
      trace("ThisClass is being initialized...");
      return ThisClass;
    }
  });
});

The first argument to define can be left out when the definition is the only one contained in the file, then the module name is derived from the file name.

Note how the definition of ThisClass, instead of directly returning its constructor function, exports a get property _, and how its implementation replaces that property by a read-only reference to the constructor (that's why it has to be configurable first).
Also note that we use OtherClass as a reference to the compilation unit containing OtherClass as its primary declaration, and so have to rewrite normal access to the class by OtherClass._.

Non-ES5 Browser Issues

Since for the time being, we still target Internet Explorer 8 (or even 7), we need a solution that also works without get properties, so we need a more sophisticated solution for the _ property.
In order not to always need to perform a function call (which results in a runtime penalty and is distracting during debugging), we try to read the field first and only call the function in case the property is not yet defined. Following the general pattern of naming explicit get functions (see below), the factory function for IE8 would be called _$get, resulting in the following expression to access a class from potentially not-yet-initialized compilation unit: (OtherClass_._ || OtherClass_._$get())

Conclusion

Granted, simulating compilation units and exact static code execution makes the solution a bit more complex, but it is an important AS3 language feature, and using the property access trick makes the implementation quite efficient, at least in modern browsers. In many cases, creating classes only when they are actually needed even increases performance, at least application start-up time, but also when many static dependencies are not actually needed at runtime at all.

Classes

Like most JavaScript frameworks, we simulate classes by a constructor function and its prototype chain.
The ES5 API Object.create(prototype,propertyDescriptors) serves this task very well.
While members are properties of the constructor function prototype, static members are properties of the constructor function itself.
Non-public members are discussed in a dedicated sub-section.

Class structure

The translation pattern is a follows:

public class Foo extends Bar {
  // constructor
  public function Foo(/*constructor parameters*/) {
    // constructor code
  }
  // member declarations
  ...
  // static member declarations
  ...
}

becomes

function Foo(/*constructor parameters*/) {
  // constructor code
}
Object.defineProperties(Foo, {
  ... // rewritten static member declarations
});
Foo.prototype = Object.create(Bar.prototype, {
  constructor: { value: Foo },
  ... // rewritten member declarations
});

The constructor property has to be defined explicitly, as otherwise, a subclass would inherit that property from its superclass, resulting in the subclass having the same constructor as its superclass.

Members and visibility (public, protected, internal, private)

Only public and protected members should be stored as properties of the constructor function / its prototype as-is. For protected members, access rights are checked by the compiler.
For private and internal members, we have to avoid name-clashes. There are different cases:

• Private methods (non-static as well as static ones) and private static fields are declared in a new scope, shared by all class members. Thus, they are visible for every method, but not from outside. Non-static private method calls have to be rewritten to run with the correct this.
• Private non-static fields and internal members are renamed: they are post-fixed by $ plus the inheritance level of the declaring class, so that they cannot name-clash with fields of the same name, declared in a subclass or superclass. The inheritance level is a number starting at 0 for Object, continuing with 1 for each direct subclass of Object, then 2 for classes inheriting from these classes, and so on. So for example a private field foo in a class extending Object would be renamed to foo$1. Internal members are also renamed, because they could name-clash with members of the same name, declared in a subclass or superclass residing in another package.

For private members, see blog posts Simulating ActionScript in JavaScript: Private Members and its follow-up.

Interfaces plus "is" and "as" operator

In ActionScript, interfaces are mainly used by the compiler for type checking. However, type checks can also be performed at runtime, using the AS3 operators instanceof, is, and as. instanceof only works for classes and automatically has the correct semantics when simulating classes via the prototype chain, so it can be used as-is in JavaScript.
x as T is simply defined as x is T ? x : null and would be implemented as a runtime helper function.
So the only operator we really have to simulate is is. To do so, we need some information about interfaces:

• for a class, the set of interfaces it implements
• for an interface, the set of interfaces it extends

For easy on-demand loading of the second information, we should implement interfaces as AMD modules, too. The AMD value of an interface could simply be set set of extended interfaces, but I chose to use a function that receives an object and sets the names of all extended interfaces as keys in that object (the values do not matter, they are simply true). This implementation makes it easy and efficient to unite interfaces: simply apply all interface functions on an empty object.
A class definition requires all AMD modules of interfaces it implements and can thus easily create the set of all interfaces it (transitively) implements. This set is stored as a static meta property, let's call it $implements.
It is convenient to have a check whether a given object implements an interface as a method isInstance(object) each interface provides. This method has to check whether the given object's constructor (its class) has a $implements property, and if so, whether the interface's name is contained in $implements:

function isInstance(object) {
  return object !== null && typeof object === "object" &&
         !!object.constructor.$implements &&
         fullyQualifiedName in object.constructor.$implements;
}

where fullyQualifiedName is the fully qualified name of the interface.

The is function now has to tackle some special cases, then check instanceof, and finally check whether T is an interface, and if so, call its isInstance() method:

function is(object, type) {
  return !!type && object !== undefined && object !== null &&
         (object instanceof type ||
          typeof type.isInstance === "function" && type.isInstance(object));
}

Parameter default values

See blog post Simulating ActionScript Parameter Default Values in JavaScript.

Rest (...) parameter

See blog post Simulating ActionScript Rest Parameter in JavaScript.

Bound methods

In contrast to JavaScript, in ActionScript, when a method is not instantly invoked, but instead used like a value, it stays bound to its original object.
This is best shown in an example:

JavaScript:

>>> o = { foo: "foo", method: function() { return this.foo; } }
[object Object]
>>> o.method()
"foo"
>>> f = o.method
function()
>>> f()
undefined

Actually, in the last call, this references the global object, usually window.

ActionScript 3:

public class BindTest {
  public var foo:String = "foo";
  public function method() { return this.foo; }
}

>>> o = new BindTest();
[object BindTest]
>>> o.method()
"foo"
>>> f = o.method
function()
>>> f()
"foo"

To simulate this behavior in JavaScript, there is the ES5 API Function#bind(), which can easily be polyfilled for IE8.
JavaScript:

>>> f = o.method.bind(o)
function()
>>> f()
"foo"

One important thing to note is that bind() creates a new function object every time it is invoked:

>>> o.method.bind(o) === o.method.bind(o)
false

This is not only a performance / memory consumption problem, as in AS3, the method keeps is identity. This is important for the typical use case that bound methods are registered as event listener callbacks. When trying to remove an event listener, identity has to be ensured, or the function will not be found and the event listener is not removed.

The following utility function "caches" the bound version of a method at the object and returns the cached version if already present:

function bind(object, boundMethodName) {
  if (object.hasOwnProperty(boundMethodName)) {
    return object[boundMethodName];
  }
  var boundMethod = object[boundMethodName].bind(object);
  Object.defineProperty(object, boundMethodName, {
    value: boundMethod
  });
  return boundMethod;
}

This ensures that

>>> bind(o, "method") === bind(o, "method")
true

All the compiler has to do is to rewrite all method accesses that are not part of an apply expression by a call to bind():

ActionScript 3:

  var f:Function = o.method;

If method is a method of o, the code is rewritten to

JavaScript:

  var f = bind(o, "method");

...

"this" is always in scope

...