Hello TypeScript

tl;dr

In retrospect, it was inevitable. Formal support for TypeScript applications has landed in Connector/Node.js. Type definitions for the entire public API are now available to ensure developers are able to leverage some goodies unlocked by traditional statically-typed languages such as autocompletion, integrated refactoring, visual type-related hints and compile-time errors.

How to TypeScript?

TypeScript is a JavaScript superset that extends the language with type annotations. It has been around for a decade, and its popularity has exploded in the last few years, to the point where most people that start writing new JavaScript applications nowadays are doing it with TypeScript. Nothing prevents a TypeScript application from using vanilla JavaScript modules and libraries, but the developer experience is usually not the best.

One way to improve that is by exposing type declaration files (*.d.ts) for the corresponding JavaScript API constructs which will create a “contract” that can be used by the TypeScript engine to understand how to “talk” to a library and be able to “explain” that to the application developer. That conversation is based in autocompletion, type-related hints and error checks. In the end, the code is always compiled to JavaScript, but it effectively introduces a compile-time stage where this feedback loop happens beforehand.

Ever-increasing demand

People began asking us to provide these type definition files for the Connector/Node.js API a long time ago. Requests came via our public bug tracker, in the form of Stack Overflow questions, answers and comments, using forum threads and even with formal contributions. Additionally, various passionate users reached out via private email requests pleading us to do something about it.

Although we never dismissed these requests and recommmendations, we decided that the timing just was not right and it was something that did not deserve the highest of priorities. Not only would it require to maintain code in a different language which needed additional tooling and care, the fact that TypeScript developers could still use the connector didn’t exactly contribute to put some pressure on us. On the other hand, there was also ongoing community effort to fill that gap.

However, due to the big increase in demand, not only for TypeScript in general, but for using it with our product in particular and the fact that the community project was lagging a bit behind, we decided to take matters into our own hands.

Getting started

The type definitions for the public Connector/Node.js API are now part of the release package and are available under the types/ directory in the project source tree. Automated tests for each type definition file (*.d.ts) are also availabe under the same directory (and the test/ subdirectory) and use the *.test-d.ts extension that is compatible with tools like tsd. Those tests are executed as part of the regular test script, but it is possible to run them in isolation using the following command:

$ npm run test:types

There is nothing that developers need to do in order to start using these type definitions for the corresponding type annotations in their TypeScript source code. For instance, the code to create X DevAPI sessions using a connection pool and executing an SQL statement can be extended like the following:

import * as mysqlx from '@mysql/xdevapi';

let config: mysqlx.ConnectionOptions = {
  user: 'root'
};

let options: mysqlx.ClientOptions = {
  pooling: {
    enabled: true,
    maxSize: 10
  }
}; 

let client: mysqlx.Client = mysqlx.getClient(config, options);

try {
  let session: mysqlx.Session = await client.getSession();
  let res: mysqlx.SqlResult = await session.sql('select 1').execute();
  console.log(res.fetchOne()); // [1]
} finally {
  await client.close();
}

Additionally, developers using an IDE with support for TypeScript should be able to directly inspect any variables via editor hints and leverage code completion for any public API building blocks. In the absence of an explicit type annotation, the TypeScript engine is smart enough to infer the correct type based on the signature of the corresponding API call. Some text editors and IDEs should be also able to detect type error assignments in real time. The following are some usage examples on Visual Studio Code.

Type hints

Autocompletion

Compile-time errors

Giving it a go

The type definitions have been introduced on Connector/Node.js 8.0.30 and should be perfectly stable for production use. Most type declaration files have been extensively tested and all of them are covered by automated tests. Please give them a try and let us know if there are any issues or concerns. You can use the Connector for Node.js category on the public MySQL bug tracker or you can catch us in the MySQL community Slack at the #connectors channel. Follow this link to sign up for the Slack workspace.

The latest Connector/Node.js release (v8.0.31) is available on npm and on the official MySQL website. The source code can be found on GitHub.

For more details about how to use Connector/Node.js, check the official documentation and the X DevAPI user guide.

Thank you to all MySQL Connector/Node.js users that somehow contributed to this. We hope you keep enjoying the MySQL product family.