Since the initial release of Bridge.NET, we have shipped several C# binding libraries, such as jQuery and Bootstrap, but the goal from the beginning was always to support more. Many many more.

The initial Bridge packages, such as Bridge.jQuery, could be considered more of a handcrafted API experience. The functions, properties, classes, and events from the JavaScript library were transposed into a C# Class Library project that could then be included into any Bridge enable application.

While handcrafting the binding library allows for the greatest flexibility, and for the most part produced a high-quality experience; the process tends to be inefficient, prone to human error, and often does not provide 100% coverage of the library API.

We embarked on a journey to solve these problems with the goal of adding the entire JavaScript library universe into the toolkit of C# developers.

1000+ commits later… we are excited to announce the release of Retyped.

What is Retyped?

Retyped reads TypeScript definition files (.d.ts) and generates a C# Class Library project based on that library. The C# project is then compiled into a NuGet package and published to NuGet.org.

At its core, Retyped is a binding library generator for Bridge.NET.

“Any Retyped package can be used in any Bridge project.”

Several thousand JavaScript libraries are currently supported by Retyped. Search for available libraries on the retyped.com or bridge.net websites.

Each Retyped library has been created as an individual NuGet Package and can be found through the NuGet Package Manager, or by using the naming pattern of retyped.{library-name} in the NuGet Package Console, or by searching the NuGet website. It's really easy to find and install the library you're looking for.

For example, to install Node:

install-package retyped.node

To install jQuery:

install-package retyped.jquery

The TypeScript Definition files are sourced from several locations including Definitely Typed and direct from the original author via NPM.

Getting Started

If you’re starting a fresh new project, the first step is to create a C# Class Library project, then install Bridge.

The following tutorial videos demonstrate several options for creating a Bridge enabled C# Class Library project.

The first tutorial demonstrates using the Bridge.NET for Visual Studio extension templates.

Another option is using the NuGet Package Manager or NuGet Console.

Once you have Bridge installed to your project, Retyped is added using NuGet.

Search for Retyped within the NuGet Package Manager, or by running the following command within your NuGet Package Console:

install-package retyped

The base Retyped package installs support for the entire JavaScript ES5 and DOM API’s, which includes all native JavaScript types, functions, classes, and events. Everything.

PRO TIP: Use Deck.NET to easily experiment with the Retyped base packages in an online playground.

Hello, World!

Let’s demonstrate the most basic usage of Retyped by triggering a standard JavaScript alert message on initial page load.

Example

https://deck.net/5492ef6c5e96ebff74ca7c2280b5ff42

Package Structure

Retyped parses TypeScript declaration files, compiles each into an individual C# Class Library project, and creates a NuGet Package for each. These are considered Binding Libraries for Bridge.NET projects.

Each Retyped package also embeds the source .d.ts declaration file. That file (or files) can be emitted to your output folder if the corresponding generateTypeScript setting is configured in your projects bridge.json file:

"generateTypeScript": true

One important gotcha to remember is that Retyped packages embed the libraries .d.ts file, but currently do not embed the .js file. The .js file(s) for the library or Module will have to be acquired separately, then manually added to your app .html file.

In a future release, Retyped packages will also embed all required JavaScript (.js) source files. This is a priority task for the development team. Once this feature is supported, the process of running your application will be as smooth as possible because referencing the correct .js files in your projects .html file will be automated.

Bridge.Html5 vs Retyped.dom

The original Bridge.Html5 package will continue to be fully supported until the Bridge 17.0 release, but we’re encouraging everyone to replace with the Retyped package whenever it’s feasible to do so in your project.

The Retyped package includes the entire native (vanilla) JavaScript API and no additional .js files are required. The JavaScript API is native in the browser so Bridge treats these libraries as [External] .

Replacing Bridge.Html5 with Retyped should be simple, but Retyped is not a drop-in replacement for Bridge.Html5. For the most part, the API is identical, but the casing is different, and using statements would have to be revised.

For example, a Document.Body call in Bridge.Html5 would be revised to document.body with Retyped. Properties would also be mapped to their lowerCamelCase equivalent, such as InnerHTML vs innerHTML in Retyped.

Example

The lowerCamelCase vs UpperCamelCase convention mirrors the JavaScript vs C# API’s. Internally, we often referred to these two languages as separate Dimensions or Universes. Your application code may pass transparently between these two dimensions, but you can only exist within one dimension at any one particular instant.

“Retyped opens a portal into the JavaScript universe.”

Retyped forces a clean separation of concerns with the JavaScript and C# API’s being self contained within unique frameworks. Installing Bridge gives you access to the C# API with no access to the JavaScript API. If you want to call down into the JavaScript API, add in Retyped and you now have access to the entire JavaScript universe.

PRO TIP: The casing convention for all entities within your project is highly configurable by applying the [Convention] attribute.

Retyped on Deck

Deck.NET samples now have access to the Retyped base packages. Currently, only the dom, es5, and jquery packages are supported on Deck. We’re planning to add configurable support for testing every Retyped package soon.

The following sample demonstrates a basic scenario of creating a simple HTML Button, setting a few properties, configuring an event listener, then adding the Button to the page.

Example

https://deck.net/welcome

The webservice sample available on Deck.NET demonstrates a few more Retyped syntax scenarios, including using Retyped.jquery which makes an AJAX call to a .NET .asmx WebService.

Package Versioning

The version number for Retyped packages follow the pattern of MAJOR.MINOR.DDDD with DDDD being the number of days since 2000–01–01 UTC.

The DDDD calculation is simple and a Deck is available to easily determine the todays DDDD value, or find the release date from a DDDD value.

For example, the package Retyped.node 7.0.6477 was created from the Node 7.0 release and published by Retyped on 6477, which was September 24, 2017.

// Determine publish date 6477

new DateTime(2000, 1, 1).AddDays(6477)

This versioning scheme allows for quick referencing of the particular JavaScript libraries version and easy lookup of the publish date, while conforming to the NuGet package versioning spec.

License

Retyped packages are licensed under Apache-2.0 licence and are free to use in both commercial and open-source projects.

Licensing for use of the individual JavaScript libraries should be sourced from the original JavaScript library.

Currently, the C# source code generated for each library by the Retyped compiler is not publicly available. We hope to release at some point in the future, but for now, they’re private. The NuGet Packages are public, the C# source code for each package is private.

The Retyped parser and compiler source code is private.

Summary

Our team has been working hard to make the Retyped compiler powerful, efficient, and capable of making intelligent decisions for generating C# binding libraries. The final API design for the libraries should be convenient and familiar for C# developers while at the same time providing the same degree of functionality as TypeScript.

Retyped is under active development and there are many more features planned. Defects and Feature Requests are being tracked in the Retyped GitHub repo.

The Retyped Community Forum is the perfect place to start a conversation if you have some comments or ideas.

We can also be reached on Twitter and Gitter.

Please let us know what you think of Retyped and feel free to contribute.

FAQ

Where do the .d.ts files come from?

Currently Retyped is reading the entire Definitely Typed repository and creating as many binding libraries as possible.

What libraries are supported?

Retyped currently supports 2200+ JavaScript libraries and more are being added all the time. High profile libraries available from Retyped include: Node, Electron, React, Angular, Lodash, jQuery, the entire JavaScript ES5 API, and the entire JavaScript DOM API.

Search for supported packages on the Retyped website. For example, there are currently about 60 packages associated to React.

I’ve found a mistake in the Retyped package {library_name}. How can it be fixed?

Since Retyped parses the original TypeScript declaration files, please double check the error does not originate from within the original .d.ts file. If it does, please report the issue (or submit a PR) to the DefinitelyTyped repository. Once the issue is fixed, Retyped will recompile the library and publish an updated NuGet package.

I’ve found an issue related to incorrect JavaScript being emitted, or the C# API doesn’t correspond to the source declaration file. The source .d.ts file appears to be correct?

Please report the issue and we will investigate right away.

I have a proposal for simplifying or enhancing Retyped syntax. Where can we discuss?

We really appreciate your feedback and ideas. Please create an issue so we can discuss with you and the community.

I need a Retyped package for {library_name} . The library is available in the DefinitelyTyped repository but I cannot find a Retyped package for it?

Sorry for that. We do our best to support all libraries available from DefinitelyTyped. However, some libraries can’t be compiled due to specific syntax scenarios that are not currently supported by the Retyped compiler, circular references, or the library may just contain a defect.

Another possible reason is the library has just been added. In this case, a Retyped package is on its way.

Either way, please report the issue to draw our attention to the problem. Don’t hesitate to add a comment or reaction if the issue has been previously logged.

I need a Retyped package for a library that is not in the DefinitelyTyped repository. Can we get a custom Retyped package made?

The simplest process is to get that library included into the DefinitelyTyped repository. On the next recompile by Retyped, the library will be discoverable on the retyped.com website and NuGet.org.

If the library is private or proprietary and cannot be released publicly, please send an email to hello@object.net and we can discuss some options.