Nylas Node.js SDK v6: TypeScript types, models, and more

Nylas is proud to announce Node.js SDK v6.0. We’ve listened to your feedback and this update improves the developer experience by making our Node SDK more TypeScript-like. Read the article to learn more about our most recent update.

Mostafa Rashed | March 23, 2022

The Nylas Node.js SDK v6.0 is one of our biggest updates to the SDK to date. This update was centered around improving the developer experience for SDK users. A common theme in user feedback was to make our Node SDK more TypeScript-like. We set out to do that and more!

New Features

Typing

All class properties and function parameters have been re-evaluated to determine if they are required or can be set to be optional. This is done to reduce confusion and to stay consistent with our API—we only make a field in the SDK required if the corresponding property is required as part of an API request. 

Want a PDF of this article?

Share it with a friend or save it for later reading.

Additionally, every function now has a proper return type to help eliminate confusion on what a function is supposed to return. This allows you as the developer to properly anticipate and plan around the response.

Finally, to better improve our best practices we tightened up types by replacing the use of any with either a specific type or unknown. We also now use Record as a type to describe JavaScript object types.

If you’d like a deeper look into what went into porting our Node SDK to TypeScript, have a look at my post “TypeScriptifying JavaScript code”

Instantiating new objects

Previously, new objects were created by invoking build(), where optionally passing in an object of key-value pairs would instantiate the object with those values. The issue with this approach was that it allowed for any value to be passed in, forgoing the opportunity for type hinting or enforcing strictness. 

Now, objects get instantiated by importing object models and using the new keyword. We can now leverage the use of type aliases and optional parameters to provide every model with an accompanying type describing all the possible fields for the model. 

const Nylas = require('nylas');
const { default: Draft } = require('nylas/lib/models/draft');

Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});
const nylas = Nylas.with('access_token');

/*
* Create a new draft object by passing in the correct properties
* 
* For `Draft`, the accompanying `DraftProperties` type outlines all the fields
*   and at the very least you must provide a 'to' field 
*/
const draftProperties = {
  to: [{ name: 'Nylas Swag', email: '[email protected]' }],
  subject: 'With Love, From Nylas',
  body: 'This email was sent using the Nylas email API. Visit https://nylas.com for details.'
}

/*
* Note that because `Draft` is a `RestfulModel` type we must pass in
*  a `NylasConnection` type at the minimum.
* We will pass in the 'draftProperties' from above to init our `Draft`
*  object with the values we want
*/
const draft = new Draft(nylas, draftProperties);

// Save the draft to send it
draft.save()

By virtue of the SDK now supporting types, when you are instantiating objects using the new keyword, your IDE will be able to hint at the parameters you can set during the construction of an object, including which properties are required. No need to refer back to the API reference!

New secondary models

Previously the SDK only modeled major API objects and their sub-objects. The new update introduces a new Model superclass to allow us flexibility in modeling more basic API objects. 

Now, every API object has a corresponding model class or type alias. This allows developers to properly anticipate responses and API payloads, leading to better-designed code.

Fully switch to camelCase

Building on the previous points, now that we can model all the return types from the API, we can deserialize them properly into camelCase format. This means that the SDK now conforms to using camelCase consistently.

We also eliminated instances where some of our functions took either a snake_case or camelCase parameter and opted for a strict camelCase-only notation.

How do I upgrade?

You can get the latest Nylas Node SDK on npm. If this is your first time using the SDK, see our Node SDK documentation.

If you are an existing user of older versions of the Nylas Node SDK, note that because this is such a major release, there are quite a few breaking changes; this release is not backward compatible with previous versions of the Node SDK. It is highly recommended that you go through both the full changelog as well as our migration guide.

Mostafa Rashed

Mostafa is a Software Engineer on the SDK team at Nylas. He a polyglot that loves to develop in many different languages. In his free time, Mostafa loves to travel across the globe and play sports.