Jorge Bay Gondra

<p>'m excited to announce that we added support for&nbsp;<a href="https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise">promises</a>&nbsp;in the latest version of the DataStax drivers, while continuing to support callback-based execution.</p>

<h2>Alternate promise-based API</h2>

<p>The use of promises has been spreading fast in the Node.js ecosystem in recent years. There are several reasons to use promises as opposed to a callback-based execution most notably:</p>

<ul>
	<li>Straightforward error handling</li>
	<li>Simplified chaining of multiple async methods</li>
	<li>Control-flow methods are included in the Promise API</li>
</ul>

<p>A promise can be chained using the built-in&nbsp;<code>then()</code>&nbsp;method. In modern versions of JavaScript, promises can awaited upon with the&nbsp;<code>yield</code>&nbsp;keyword in conjunction with generator functions, aka&nbsp;<a href="http://bluebirdjs.com/docs/api/promise.coroutine.html">coroutines</a>, or using the&nbsp;<code>await</code>&nbsp;keyword in&nbsp;<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function">async functions</a>.</p>

<p>Note that we will continue to support callback-based execution and this new alternate API was added without introducing breaking changes to the existing functionality. Asynchronous methods in the driver expect a callback as the last parameter, according to the callback-style convention. If no callback is provided, the methods will return a&nbsp;<code>Promise</code>.</p>

<p>Let's look at how to use the Node.js drivers with this new API:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p><code>const</code> <code>query = </code><code>'SELECT name, email FROM users WHERE key = ?'</code><code>;</code></p>

			<p><code>client.execute(query, [ </code><code>'someone'</code> <code>], { prepare: </code><code>true</code> <code>})</code></p>

			<p><code>&nbsp;&nbsp;</code><code>.then(result =&gt; console.log(</code><code>'User with email %s'</code><code>, result.rows[</code><code>0</code><code>].email));</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>Using async functions:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p><code>const</code> <code>result = await client.execute(query);</code></p>

			<p><code>console.log(</code><code>'User with email %s'</code><code>, result.rows[</code><code>0</code><code>].email);</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>Besides CQL query executions, the drivers also support promises for metadata fetching methods, for example:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p><code>const</code> <code>tableMetadata = await client.metadata.getTable(</code><code>'ks1'</code><code>, </code><code>'table1'</code><code>);</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>Promises are created in the drivers using the&nbsp;<a href="https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise"><code>Promise</code>&nbsp;constructor</a>&nbsp;by default. Alternatively, you can use your Promise library of choice by overriding&nbsp;<code>promiseFactory</code>&nbsp;when creating a&nbsp;<code>Client</code>&nbsp;instance. For example, using&nbsp;<a href="http://bluebirdjs.com/">bluebird</a>:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p><code>const</code> <code>Promise = require(</code><code>'bluebird'</code><code>);</code></p>

			<p><code>const</code> <code>client = </code><code>new</code> <code>Client({ </code></p>

			<p><code>&nbsp;&nbsp;</code><code>contactPoints: [ </code><code>'host1'</code><code>, </code><code>'host2'</code> <code>],</code></p>

			<p><code>&nbsp;&nbsp;</code><code>promiseFactory: Promise.fromCallback</code></p>

			<p><code>});</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>Key things to remember:</p>

<ul>
	<li>We will continue to support callback based execution.</li>
	<li>Asynchronous methods in the driver accept a callback as the last parameter, according to the callback-style convention.</li>
	<li>When a callback is not provided, then the asynchronous methods will return a&nbsp;<code>Promise</code>.</li>
	<li>The new alternative API for promises does not break any existing functionality.</li>
</ul>

<h2>Other new features</h2>

<p>Along with&nbsp;<code>Promise</code>&nbsp;support, there are other noteworthy features in the version 1.2 of the&nbsp;<a href="http://docs.datastax.com/en/developer/nodejs-driver-dse/latest/">DataStax Enterprise Node.js Driver</a>&nbsp;and version 3.2 of the&nbsp;<a href="https://github.com/datastax/nodejs-driver">DataStax Node.js Driver for Apache Cassandra</a>.</p>

<h3>Timestamp Generator</h3>

<p>When using Apache Cassandra 2.1+ or DataStax Enterprise 4.7+, it's possible to send the operation timestamp in the request, as opposed to embedded in the query.&nbsp;<a href="https://github.com/datastax/nodejs-driver/tree/master/doc/features/query-timestamps#using-a-timestamp-generator">The drivers now use&nbsp;<code>MonotonicTimestampGenerator</code>&nbsp;by default</a>&nbsp;to generate the request timestamps.</p>

<p>You can provide a different generator when creating the&nbsp;<code>Client</code>&nbsp;instance:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p><code>const</code> <code>client = </code><code>new</code> <code>Client({</code></p>

			<p><code>&nbsp;&nbsp;</code><code>contactPoints: [ </code><code>'host1'</code><code>, </code><code>'host2'</code> <code>],</code></p>

			<p><code>&nbsp;&nbsp;</code><code>policies: {</code></p>

			<p><code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>timestampGeneration: </code><code>new</code> <code>MyCustomTimestampGenerator()</code></p>

			<p><code>&nbsp;&nbsp;</code><code>}</code></p>

			<p><code>});</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>As defined by ECMAScript, the&nbsp;<code>Date</code>&nbsp;object has millisecond resolution. The&nbsp;<code>MononoticTimestampGenerator</code>&nbsp;uses an incremental counter to generate the sub-millisecond part of the timestamp until the next clock tick. The implementation also guarantees that the returned timestamps will always be monotonically increasing, even if multiple updates happen under the same millisecond. To guarantee such monotonicity, if more than one thousand timestamps are generated within the same millisecond, or in the event of a system clock skew, the implementation might return timestamps that drift out into the future. When this happens, the built-in generator logs a periodic warning message.</p>

<h3>Query Idempotence Option</h3>

<p>We added a query option that can be used to define whether it's safe for the driver to apply the query multiple times without changing the result beyond the initial application.</p>

<p>Initially, this value can be retrieved at&nbsp;<a href="http://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#retry-policy">Retry policy</a>&nbsp;level to determine if the execution can be retried in case of a request error or write timeout. In future versions, the drivers will avoid the retry logic and directly rethrow the error in case of non-idempotent queries.</p>

<h3>ResultSet sync iterator,</h3>

<p>We added a bit of syntactic sugar on top of the&nbsp;<code>ResultSet</code>&nbsp;prototype to allow synchronous iteration of the rows using the new&nbsp;<code>for...of</code>&nbsp;statement in ES2015 by exposing a&nbsp;<code>Symbol.iterator</code>&nbsp;method.</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p><code>const</code> <code>result = await client.execute(query);</code></p>

			<p><code>for</code> <code>(let row of result) {</code></p>

			<p><code>&nbsp;&nbsp;</code><code>console.log(row.email);</code></p>

			<p><code>}</code></p>
			</td>
		</tr>
	</tbody>
</table>

<h2>Wrapping up</h2>

<p>The new versions of the DataStax drivers are available on npm:&nbsp;<a href="https://www.npmjs.org/package/dse-driver">dse-driver</a>&nbsp;and&nbsp;<a href="https://www.npmjs.org/package/cassandra-driver">cassandra-driver</a>.</p>

<p>We would love to hear your comments, feedback, and questions:</p>

<ul>
	<li><a href="https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user">Mailing list</a></li>
	<li><a href="https://datastax-oss.atlassian.net/projects/NODEJS/issues">Report issues on JIRA</a></li>
</ul>


Build and scale cloud native apps

Discover the benefits of DBaaS and why your apps deserve an upgrade.

Learn about NoSQL Databases

Learn about NoSQL databases with Apache Cassandra and Astra DB.

2022 Recap: A Year for Customers, Community, and Real-Time Data

Highlights from 2022 and a glimpse into the year ahead.

ViewingTechnical How To’s

Promise Support in the DataStax Node.js Drivers

Sign up for our Developer Newsletter