sdk/lib/js/dartium/js_dartium.dart

// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

/**
 * The js.dart library provides simple JavaScript invocation from Dart that
 * works on both Dartium and on other modern browsers via Dart2JS.
 *
 * It provides a model based on scoped [JsObject] objects.  Proxies give Dart
 * code access to JavaScript objects, fields, and functions as well as the
 * ability to pass Dart objects and functions to JavaScript functions.  Scopes
 * enable developers to use proxies without memory leaks - a common challenge
 * with cross-runtime interoperation.
 *
 * The top-level [context] getter provides a [JsObject] to the global JavaScript
 * context for the page your Dart code is running on.  In the following example:
 *
 *     import 'dart:js';
 *
 *     void main() {
 *       context.callMethod('alert', ['Hello from Dart via JavaScript']);
 *     }
 *
 * context['alert'] creates a proxy to the top-level alert function in
 * JavaScript.  It is invoked from Dart as a regular function that forwards to
 * the underlying JavaScript one.  By default, proxies are released when
 * the currently executing event completes, e.g., when main is completes
 * in this example.
 *
 * The library also enables JavaScript proxies to Dart objects and functions.
 * For example, the following Dart code:
 *
 *     context['dartCallback'] = new Callback.once((x) => print(x*2));
 *
 * defines a top-level JavaScript function 'dartCallback' that is a proxy to
 * the corresponding Dart function.  The [Callback.once] constructor allows the
 * proxy to the Dart function to be retained across multiple events;
 * instead it is released after the first invocation.  (This is a common
 * pattern for asychronous callbacks.)
 *
 * Note, parameters and return values are intuitively passed by value for
 * primitives and by reference for non-primitives.  In the latter case, the
 * references are automatically wrapped and unwrapped as proxies by the library.
 *
 * This library also allows construction of JavaScripts objects given a
 * [JsObject] to a corresponding JavaScript constructor.  For example, if the
 * following JavaScript is loaded on the page:
 *
 *     function Foo(x) {
 *       this.x = x;
 *     }
 *
 *     Foo.prototype.add = function(other) {
 *       return new Foo(this.x + other.x);
 *     }
 *
 * then, the following Dart:
 *
 *     var foo = new JsObject(context['Foo'], [42]);
 *     var foo2 = foo.callMethod('add', [foo]);
 *     print(foo2['x']);
 *
 * will construct a JavaScript Foo object with the parameter 42, invoke its
 * add method, and return a [JsObject] to a new Foo object whose x field is 84.
 */

library dart.js;

import 'dart:html';
import 'dart:isolate';

// Global ports to manage communication from Dart to JS.
SendPortSync _jsPortSync = window.lookupPort('dart-js-context');
SendPortSync _jsPortCreate = window.lookupPort('dart-js-create');
SendPortSync _jsPortInstanceof = window.lookupPort('dart-js-instanceof');
SendPortSync _jsPortDeleteProperty = window.lookupPort('dart-js-delete-property');
SendPortSync _jsPortConvert = window.lookupPort('dart-js-convert');

/**
 * Returns a proxy to the global JavaScript context for this page.
 */
JsObject get context {
  var port = _jsPortSync;
  if (port == null) {
    return null;
  }
  return _deserialize(_jsPortSync.callSync([]));
}

/**
 * Converts a json-like [data] to a JavaScript map or array and return a
 * [JsObject] to it.
 */
JsObject jsify(dynamic data) => data == null ? null : new JsObject._json(data);

/**
 * Converts a local Dart function to a callback that can be passed to
 * JavaScript.
 */
class Callback implements Serializable<JsFunction> {
  JsFunction _f;

  Callback._(Function f, bool withThis) {
    final id = _proxiedObjectTable.add((List args) {
      final arguments = new List.from(args);
      if (!withThis) arguments.removeAt(0);
      return Function.apply(f, arguments);
    });
    _f = new JsFunction._internal(_proxiedObjectTable.sendPort, id);
  }

  factory Callback(Function f) => new Callback._(f, false);
  factory Callback.withThis(Function f) => new Callback._(f, true);

  JsFunction toJs() => _f;
}

/**
 * Proxies to JavaScript objects.
 */
class JsObject implements Serializable<JsObject> {
  final SendPortSync _port;
  final String _id;

  /**
   * Constructs a [JsObject] to a new JavaScript object by invoking a (proxy to
   * a) JavaScript [constructor].  The [arguments] list should contain either
   * primitive values, DOM elements, or Proxies.
   */
  factory JsObject(Serializable<JsFunction> constructor, [List arguments]) {
    final params = [constructor];
    if (arguments != null) params.addAll(arguments);
    final serialized = params.map(_serialize).toList();
    final result = _jsPortCreate.callSync(serialized);
    return _deserialize(result);
  }

  /**
   * Constructs a [JsObject] to a new JavaScript map or list created defined via
   * Dart map or list.
   */
  factory JsObject._json(data) => _convert(data);

  static _convert(data) =>
      _deserialize(_jsPortConvert.callSync(_serializeDataTree(data)));

  static _serializeDataTree(data) {
    if (data is Map) {
      final entries = new List();
      for (var key in data.keys) {
        entries.add([key, _serializeDataTree(data[key])]);
      }
      return ['map', entries];
    } else if (data is Iterable) {
      return ['list', data.map(_serializeDataTree).toList()];
    } else {
      return ['simple', _serialize(data)];
    }
  }

  JsObject._internal(this._port, this._id);

  JsObject toJs() => this;

  // Resolve whether this is needed.
  operator[](arg) => _forward(this, '[]', 'method', [ arg ]);

  // Resolve whether this is needed.
  operator[]=(key, value) => _forward(this, '[]=', 'method', [ key, value ]);

  int get hashCode => _id.hashCode;

  // Test if this is equivalent to another Proxy.  This essentially
  // maps to JavaScript's === operator.
  operator==(other) => other is JsObject && this._id == other._id;

  /**
   * Check if this [JsObject] has a [name] property.
   */
  bool hasProperty(String name) => _forward(this, name, 'hasProperty', []);

  /**
   * Delete the [name] property.
   */
  void deleteProperty(String name) {
    _jsPortDeleteProperty.callSync([this, name].map(_serialize).toList());
  }

  /**
   * Check if this [JsObject] is instance of [type].
   */
  bool instanceof(Serializable<JsFunction> type) =>
      _jsPortInstanceof.callSync([this, type].map(_serialize).toList());

  String toString() {
    try {
      return _forward(this, 'toString', 'method', []);
    } catch(e) {
      return super.toString();
    }
  }

  callMethod(String name, [List args]) {
    return _forward(this, name, 'method', args != null ? args : []);
  }

  // Forward member accesses to the backing JavaScript object.
  static _forward(JsObject receiver, String member, String kind, List args) {
    var result = receiver._port.callSync([receiver._id, member, kind,
                                          args.map(_serialize).toList()]);
    switch (result[0]) {
      case 'return': return _deserialize(result[1]);
      case 'throws': throw _deserialize(result[1]);
      case 'none': throw new NoSuchMethodError(receiver, member, args, {});
      default: throw 'Invalid return value';
    }
  }
}

/// A [JsObject] subtype to JavaScript functions.
class JsFunction extends JsObject implements Serializable<JsFunction> {
  JsFunction._internal(SendPortSync port, String id)
      : super._internal(port, id);

  apply(thisArg, [List args]) {
    return JsObject._forward(this, '', 'apply',
        [thisArg]..addAll(args == null ? [] : args));
  }
}

/// Marker class used to indicate it is serializable to js. If a class is a
/// [Serializable] the "toJs" method will be called and the result will be used
/// as value.
abstract class Serializable<T> {
  T toJs();
}

// A table to managed local Dart objects that are proxied in JavaScript.
class _ProxiedObjectTable {
  // Debugging name.
  final String _name;

  // Generator for unique IDs.
  int _nextId;

  // Table of IDs to Dart objects.
  final Map<String, Object> _registry;

  // Port to handle and forward requests to the underlying Dart objects.
  // A remote proxy is uniquely identified by an ID and SendPortSync.
  final ReceivePortSync _port;

  _ProxiedObjectTable() :
      _name = 'dart-ref',
      _nextId = 0,
      _registry = {},
      _port = new ReceivePortSync() {
    _port.receive((msg) {
      try {
        final receiver = _registry[msg[0]];
        final method = msg[1];
        final args = msg[2].map(_deserialize).toList();
        if (method == '#call') {
          final func = receiver as Function;
          var result = _serialize(func(args));
          return ['return', result];
        } else {
          // TODO(vsm): Support a mechanism to register a handler here.
          throw 'Invocation unsupported on non-function Dart proxies';
        }
      } catch (e) {
        // TODO(vsm): callSync should just handle exceptions itself.
        return ['throws', '$e'];
      }
    });
  }

  // Adds a new object to the table and return a new ID for it.
  String add(x) {
    // TODO(vsm): Cache x and reuse id.
    final id = '$_name-${_nextId++}';
    _registry[id] = x;
    return id;
  }

  // Gets an object by ID.
  Object get(String id) {
    return _registry[id];
  }

  // Gets the current number of objects kept alive by this table.
  get count => _registry.length;

  // Gets a send port for this table.
  get sendPort => _port.toSendPort();
}

// The singleton to manage proxied Dart objects.
_ProxiedObjectTable _proxiedObjectTable = new _ProxiedObjectTable();

/// End of proxy implementation.

// Dart serialization support.

_serialize(var message) {
  if (message == null) {
    return null;  // Convert undefined to null.
  } else if (message is String ||
             message is num ||
             message is bool) {
    // Primitives are passed directly through.
    return message;
  } else if (message is SendPortSync) {
    // Non-proxied objects are serialized.
    return message;
  } else if (message is JsFunction) {
    // Remote function proxy.
    return [ 'funcref', message._id, message._port ];
  } else if (message is JsObject) {
    // Remote object proxy.
    return [ 'objref', message._id, message._port ];
  } else if (message is Serializable) {
    // use of result of toJs()
    return _serialize(message.toJs());
  } else if (message is Function) {
    return _serialize(new Callback(message));
  } else {
    // Local object proxy.
    return [ 'objref',
             _proxiedObjectTable.add(message),
             _proxiedObjectTable.sendPort ];
  }
}

_deserialize(var message) {
  deserializeFunction(message) {
    var id = message[1];
    var port = message[2];
    if (port == _proxiedObjectTable.sendPort) {
      // Local function.
      return _proxiedObjectTable.get(id);
    } else {
      // Remote function.  Forward to its port.
      return new JsFunction._internal(port, id);
    }
  }

  deserializeObject(message) {
    var id = message[1];
    var port = message[2];
    if (port == _proxiedObjectTable.sendPort) {
      // Local object.
      return _proxiedObjectTable.get(id);
    } else {
      // Remote object.
      return new JsObject._internal(port, id);
    }
  }

  if (message == null) {
    return null;  // Convert undefined to null.
  } else if (message is String ||
             message is num ||
             message is bool) {
    // Primitives are passed directly through.
    return message;
  } else if (message is SendPortSync) {
    // Serialized type.
    return message;
  }
  var tag = message[0];
  switch (tag) {
    case 'funcref': return deserializeFunction(message);
    case 'objref': return deserializeObject(message);
  }
  throw 'Unsupported serialized data: $message';
}