Category Archives: Javascript

NodeRT: Accessing WinRT from Node.js

If you’re using node.js on Windows and are interested in getting easy access to some of the cool WinRT-based APIs in Windows 8.0 and later, you should check out the new NodeRT project on Github. It’s a tool that allows you to automagically generate native node.js modules from WinRT winmd metadata files, making them easily available in node:

Since node.js runs as a regular Win32 application and not a Windows Store application (is that what we’re calling Metro these days?), you won’t be able to get access to Store-only WinRT APIs, but there are still quite a few useful WinRT APIs available to desktop apps.

Pretty awesome, check it out!

You should also follow me on Twitter here.

JsRT: Wrappers updated to v1.1

Even though I may not be working on the Chakra team any more, I’m still doing some noodling on making the hosting APIs easier to use. I’ve got some other interesting things coming soon, but on the way there I made some improvements/fixes to the wrappers that I released a while back.

Changes to v1.1:

  • PDB files are generated along with the LIB, and debug builds are included. All flavors are now packaged together.
  • Header file name is changed to jsrt-wrappers.h to be consistent with the other files.
  • Added equality operators for handles.
  • Added function_base::create which can deduce the strongly typed function wrapper from the function signature.
  • Fixes the handling of optional parameters in functions.
  • Changes the handling of rest parameters to use std::vector rather than a JavaScript array, which is more efficient.
  • Simplified prototype handling.
  • Bug fixes.

Let me know if there are any problems!

You should also follow me on Twitter here.

JsRT: Wrappers for C++

One unfortunate side-effect of the fact that the JsRT API is a flat Win32-style API is that it can be a little… painful to use in C++. Some of the conventions, particularly the use of error code returns everywhere and the use of return parameters, mean that you have to write a lot of boilerplate code. And marshalling values between C++ and JavaScript can be very cumbersome. So with that in mind, I’ve written some sample C++ wrappers that make the process of working with the JsRT APIs a lot nicer in C++.

You can get them from my GitHub account here. For more information, here’s part of the readme, which covers some of the highlights of the wrappers:

A Tour Through the Helpers

Most of the wrappers simply provide a nice object-oriented interface over the JsRT API. For example, creating a runtime and a context works like this:

jsrt::runtime runtime = jsrt::runtime::create();
jsrt::context context = runtime.create_context();

There are, however, a number of special features in the wrappers.

Context scopes

A context scope (jsrt::context::scope) automatically sets the current context when it comes into scope and clears the current context when it goes out of scope. This greatly simplifies working with scopes. For example:

jsrt::runtime runtime = jsrt::runtime::create();
jsrt::context context = runtime.create_context();
    jsrt::context::scope scope(context);
    ... work with context ...
// Context has automatically been set back to original value.

Pinned references

To keep a reference to a Chakra object alive, it must be visible to the Chakra garbage collector (i.e. on the stack or stored in the garbage collected heap) or it has to be pinned using JsAddRef. The pinned<T> class functions as a smart-pointer template that keeps a reference alive using JsAddRef and JsRelease automatically. For example:

    jsrt::pinned<jsrt::object> pinned_obj = jsrt::object::create();
    // Object reference does not have to stay on the stack or in the GC heap
// Reference can now be garbage collected

Value translation

Value getter and setter functions can be strongly-typed, allowing automatic marshalling of JavaScript values to C++ values and vice versa. For example:

jsrt::object obj = jsrt::object::create();
obj.set_property(jsrt::property_id::create(L"boolProperty"), true);
bool bool_value = obj.get_property<bool>(jsrt::property_id::create(L"boolProperty"));
obj.set_property(jsrt::property_id::create(L"stringProperty"), L"foo");

The wrappers marshal types in the following way:

  • number values are marshalled to/from double

  • string values are marshalled to/from std::wstring

  • Boolean values are marshalled to/from bool

Strongly-typed arrays

Similarly, arrays can be strongly typed and accessed using numeric indexes:

jsrt::array<double> darray = jsrt::array<double>::create(1);
darray[0] = 10;
darray[1] = 20;


Perhaps the most useful aspect of the wrappers is the way that JavaScript functions can be wrapped and their arguments and return values marshalled to C++ types, and vice versa. For example:

auto f = (jsrt::function<double, double, double>)jsrt::context::evaluate(
    L"function f(a, b) { return a + b; }; f;");
double a = f(jsrt::context::undefined(), 1, 2);

Native functions can also be wrapped:

double add(const jsrt::call_info &info, double a, double b) { return a + b; }
auto nf = jsrt::function<double, double, double>::create(add);
jsrt::context::global().set_property(jsrt::property_id::create(L"add"), nf);
jsrt::context::run(L"add(1, 2)");

When calling a function wrapper, the first argument to the function call is the this value for the call. Function wrappers can also be bound to a particular value of this. For example:

auto bf = jsrt::bound_function<jsrt::value, double, double, double>::create(
    (jsrt::function<double, double, double>)jsrt::context::evaluate(
        L"function f(a, b) { return a + b; }; f;"));
double ba = bf(1, 2);

You should also follow me on Twitter here.

Using Jake with TypeScript

I’ve been playing around a lot lately with TypeScript and node.js, and have been using Jake as my make system. Oddly, I haven’t been able to find any npms that simplify Jake/TypeScript integration (maybe I’m not looking hard enough?), so I wrote a little one of my own, jake-typescript. It exposes two methods:

  • batchFiles takes a list of files and produces a Jake task that compiles each of the files separately (i.e. the default tsc behavior).
  • singleFile takes a list of files and produces a Jake file task that compiles all of the files into a single .js file (i.e. the –out behavior).

There’s also a structure to specify command-line arguments for the compile. It’s my first npm and I’m still getting up to speed on all the various conventions, definitely looking for feedback…

You should also follow me on Twitter here.

JsRT Sample Bug Fixed

This happened a while ago but just getting to it now because of my blog hiccup. A sharp-eyed reader pointed out a problem with my C# and VB Chakra hosting samples (on MSDN and on GitHub). When passing a host callback from managed code, I forgot to hold on to a managed reference to the delegate I was passing out to Chakra. So if the CLR ran a GC, it would dispose the delegate and then a callback on that delegate would jump into hyperspace. The samples are now correct. Ah, the joys of coordinating GCs.

You should also follow me on Twitter here.

Memory profiling in Visual Studio 2013 with JsRT

One of the cool features of Visual Studio (starting in Visual Studio 2012 Update 1) is its JavaScript memory profiler. The profiler can take snapshots of the JavaScript heap and then gives you a nice UI you can use to drill in to those snapshots and compare them as you like:

Comparing two snapshots

Drilling in to a snapshot

Wouldn’t it be great to be able to utilize this to analyze the JavaScript memory usage in an app that hosts Chakra using JsRT? Well, you can! I’ve uploaded a new sample (and checked it in to my GitHub repo) that allows a JsRT app to generate heap dumps in a way that Visual Studio 2013 will be able to read. It doesn’t look quite as beautiful at the examples above–I didn’t go through the trouble of generating a screenshot for the summary page–but it should be entirely functional.

The sample project builds a C++ DLL that exports five functions:

  • bool InitializeMemoryProfileWriter() initializes the overall profile writer and should be called when you load the DLL.
  • MemoryProfileHandle StartMemoryProfile() starts a specific profile (called a “diagnostic session” in Visual Studio).
  • bool WriteSnapshot(MemoryProfileHandle memoryProfileHandle, IActiveScriptProfilerHeapEnum *enumerator) takes a memory profile handle and a heap enumerator (which can be obtained from JsEnumerateHeap) and writes the actual memory snapshot. Note that you can do this multiple times before finishing the memory profile. Each snapshot is written separately into the diagnostic session.
  • bool EndMemoryProfile(MemoryProfileHandle memoryProfileHandle, const wchar_t *filename) finishes the memory profile and writes it out to a file. The file should have a .diagsession extension if you want it to be natively recognized by VS when you open it. After this call, the memory profile handle is now invalid.
  • void ReleaseMemoryProfileWriter() releases the overall profiler writer and should be called when you’re shutting down or done with all profiling.

One thing to note is that once you’ve called JsEnumerateHeap for a particular JsRT runtime, you won’t be able to do anything in that runtime until the IActiveScriptProfilerHeapEnum pointer has been released.

We’ve already been using this code internally to look at the memory usage of some internal JsRT hosts, and it’s been very helpful! Let me know if there are problems or issues, and feel free to grab me on Twitter if you have any questions.

You should also follow me on Twitter here.

JsRT samples updated for Windows 8.1 RTM

As a few people have noticed, we took a small breaking change to the JsRT API between the Windows 8.1 Preview and Windows 8.1 RTM. The JsCreateFunction API got an additional parameter that allows registering a piece of data (which can just be null) with the native callback which will be provided to the callback when it’s invoked. It’s a super-useful place to stash something like a “this” pointer for a C++ callback, which is why we added it before the concrete completely dried on the API. It does mean, though, that most applications compiled against the preview will break and need to be recompiled against RTM.

Accordingly, we’ve updated both the MSDN documentation for JSRT and the Code Gallery hosting sample.

You can always reach me on Twitter here.

JsRT: Handling exceptions

The last major conceptual topic to cover for JsRT is how exceptions are handled.

Internally, Chakra uses C++ exception handling to handle both JavaScript exceptions and internal engine exceptions. However, even though the host might also be using C++ exception handling, the JsRT API surface enforces a strict separation between the host and Chakra when it comes to exceptions. Chakra exceptions will never cross over into the host (i.e. they will always be caught at the API boundary), and host exceptions should never cross over into the Chakra engine. Thus, hosts need to guard any callbacks to ensure that internal host exceptions don’t escape into Chakra.

OK, so, then how do exceptions work?

When a JavaScript exception occurs during script execution or during script compilation, and the exception is not handled in the script itself (i.e. the exception makes it to a JsRT API boundary), the containing runtime is put into an exception state. While in the exception state, no code can run in the runtime and all API calls will fail (with the error code JsErrorInExceptionState). This will continue until the host retrieves and clears the exception using the JsGetAndClearException API. This API will return an object representing the JavaScript value thrown (or the compile exception if the error occurred during compilation), and the runtime will be free to run code. How the host handles the exception is up to the host.

If the host is in the middle of a callback from Chakra, the host can also just return from the callback without clearing the runtime from an exception state. This will cause the JavaScript exception to be re-thrown when control passes back to the JavaScript engine.

If the host is in the middle of a callback and wants to “throw” a JavaScript exception, it can set the runtime into an exception state using JsSetException and then return from the callback. Just as above, the exception will be thrown in JavaScript once control passes back to the Chakra engine.

You should also follow me on Twitter here.