Release v3.1.0 of the Amazon QLDB Driver for Node.js

3.1.0

No new features are introduced but 570 updates the peer dependency requirement ion-js from ^4.3.0 to ^5.2.0.

What's Changed

• Bugfix session null after timeout by @bwinchester in #245
• actions: use OIDC aws credentials by @amzn-paunort in #246
• update npm doc script for doc generation by @bwinchester in #247
• npm: bump @typescript-eslint/parser from 5.41.0 to 5.42.1 by @dependabot in #253
• npm: bump chai from 4.3.6 to 4.3.7 by @dependabot in #252
• npm: bump mocha from 10.0.0 to 10.2.0 by @dependabot in #281
• npm: bump typedoc from 0.23.18 to 0.23.23 by @dependabot in #287
• npm: bump @types/node from 18.11.6 to 18.11.17 by @dependabot in #286
• npm: bump @types/node from 18.11.17 to 18.11.18 by @dependabot in #295
• Bump json5 from 2.2.1 to 2.2.3 by @dependabot in #306
• npm: bump eslint-plugin-jsdoc from 39.3.25 to 39.6.7 by @dependabot in #313
• npm: bump @typescript-eslint/eslint-plugin from 5.41.0 to 5.48.2 by @dependabot in #311
• Move AWS SDK dependencies into peerDependencies by @battesonb in #321
• npm: bump typescript from 4.8.4 to 4.9.5 by @dependabot in #327
• npm: bump @aws-sdk/client-qldb-session from 3.261.0 to 3.289.0 by @dependabot in #361
• npm: bump @aws-sdk/client-qldb from 3.261.0 to 3.289.0 by @dependabot in #363
• Update aws-sdk to fix fast-xml-parser vulnerability by @GanyuanTan in #464
• Fast xml vuln by @butleragrant in #506
• Bump @babel/traverse from 7.18.8 to 7.23.2 by @dependabot in #547
• Bump 'ion-js' to 5.2.0 by @trstephen-amazon in #570
• Release version 3.1.0 by @trstephen-amazon in #571

New Contributors

• @battesonb made their first contribution in #321
• @GanyuanTan made their first contribution in #464
• @trstephen-amazon made their first contribution in #570

Full Changelog: v3.0.1...v3.1.0

Release v3.0.1 of the Amazon QLDB Driver for Node.js

This is a minor release to incorporate a recent PR by the community: 245

🐛 Bug Fixes

• When the driver session is not live and a new one needs to be created and returned to the callee, the session is null resulting on an error: Cannot read properties of null (reading 'executeLambda'). The problem is that session var is not getting the new session recently created and it fails by returning null. It should re-up a connection and replace the driver object with the new session to the database.

Release v3.0.0 of the Amazon QLDB Driver for Node.js

All the changes are introduced by SDK V3, please check Migrating to the AWS SDK for JavaScript V3 to learn how to migrate to the AWS SDK for JavaScript V3 from AWS SDK for JavaScript V2.

🎉 Enhancements

• Migrated to AWS SDK for JavasScript V3.

🐛 Bug Fixes

• Fixed a order of operations bug in defaultBackoffFunction which would add up-to 10s of sleep over 4 retries, versus less than 300 ms total sleep between 4 retries. The defaultBackoffFunction strategy is defaulted if users do not provide their own backoff strategy function for the RetryConfig.

💥 Breaking changes

• Changed driver constructor to take a new type of qldbClientOptions and added a new parameter httpOptions to configure the low level node http client separately. Application code needs to be modified for driver construction.
  For example, the following:

import { Agent } from 'https';
import { QldbDriver, RetryConfig  } from 'amazon-qldb-driver-nodejs';

const maxConcurrentTransactions: number = 10;

const agentForQldb: Agent = new Agent({
    keepAlive: true,
    maxSockets: maxConcurrentTransactions
});

const serviceConfigurationOptions = {
    region: "us-east-1",
    httpOptions: {
        agent: agentForQldb
    }
};

const qldbDriver: QldbDriver = new QldbDriver("testLedger", serviceConfigurationOptions, maxConcurrentTransactions);

Should be changed to

import { Agent } from 'https';
import { QldbDriver, RetryConfig  } from 'amazon-qldb-driver-nodejs';
import { NodeHttpHandlerOptions } from "@aws-sdk/node-http-handler";

const maxConcurrentTransactions: number = 10;

const lowLevelClientHttpOptions: NodeHttpHandlerOptions = {
    httpAgent: new Agent({
      maxSockets: maxConcurrentTransactions
    })
};

const serviceConfigurationOptions = {
    region: "us-east-1"
};

const qldbDriver: QldbDriver = new QldbDriver("testLedger", serviceConfigurationOptions, lowLevelClientHttpOptions, maxConcurrentTransactions);

• Updated driver to comply with new service exception class.

Release v2.2.0 of the Amazon QLDB Driver for Node.js

Release v2.2.0

This release is focused on improving the retry logic, optimizing it and handling more possible failures, as well as more
strictly defining the API to help prevent misuse. These changes are potentially breaking if the driver is being used in
a way that isn't supported by the documentation.

🎉 Enhancements

• Improved retry logic
  • Failures when starting a new session are now retried.
  • Dead sessions are immediately discarded, reducing latency when using the driver.
  • ClientError, DriverClosedError, LambdaAbortedError, and SessionPoolEmptyError are now exported.
  • Peer dependency aws-sdk bumped to 2.841.0 or greater, which gives visibility to CapacityExceededException.
• Updated the exponential backoff algorithm to better align with the algorithm specified here.
• Specify minimum Node.js version to 10.0 in package.json.

⚠️ API Clean-up

These changes either remove unintentionally exported modules or remove the use of any. Updating to 2.2.0 should not break any documented usage of the driver and should not require code changes. If something is now incompatible and it's believed that it should be, please open an issue.

• TypeScript: updated executeLambda signature

  • // Old
    async ExecuteLambda(transactionLambda: (transactionExecutor: TransactionExecutor) => any, 
        retryConfig?: RetryConfig): Promise<any>;
    // New
    async ExecuteLambda<Type>(transactionLambda: (transactionExecutor: TransactionExecutor) => Promise<Type>,
        retryConfig?: RetryConfig): Promise<Type>;

  • The returned value from the transactionLambda is what ExecuteLambda returns, so it's now strictly defined by the Type.

  • The transactionLambda must return a Promise, as any methods called on the TransactionExecutor must be awaited for the driver to properly function.

• JavaScript: removed QldbDriver.getSession()

  • This is unavailable to TypeScript users and was not intended to be called directly by JavaScript users.

• Module exports

  • Removed Transaction from the exports list.
  • Removed modules being accessible when importing from amazon-qldb-driver-nodejs/src.
  • TypeScript: Removed constructors in the API for some exported types.

🐛 Bug Fixes

• Fixed a bug where No open transaction or Transaction already open errors would occur

Release v2.1.1 of the Amazon QLDB Driver for Node.js

Release v2.1.1

Note: A bug has been discovered in this version which results in No open transaction or Transaction already open errors, please use v2.2.0.

Fix a bug where the stream result was not able to return query statistics #59.

Enhancements

• Export ResultReadable
• Change the return type of executeAndStreamResults() from Readable to ResultReadable which extends Readable
• getConsumedIOs(): IOUsage and getTimingInformation(): TimingInformation functions are accessible through ResultReadable

Release v2.1.0 of the Amazon QLDB Driver for Node.js

Release v2.1.0 (December 22 , 2020)

Note: A bug has been discovered in this version which results in No open transaction or Transaction already open errors, please use v2.2.0.

Add support for obtaining basic server-side statistics on individual statement executions.

Enhancements

• Added IOUsage and TimingInformation interface to provide server-side execution statistics
  • IOUsage provides getReadIOs(): number
  • TimingInformation provides getProcessingTimeMilliseconds(): number
  • Added getConsumedIOs(): IOUsage and getTimingInformation(): TimingInformation to the Result and ResultStream
  • getConsumedIOs(): IOUsage and getTimingInformation(): TimingInformation methods are stateful, meaning the statistics returned by them reflect the state at the time of method execution

Check Getting statement statistics for details.

Note: For using version 2.1.0 and above of the driver, the version of the aws-sdk should be >= 2.815

Release v2.0.0 of the Amazon QLDB Driver for Node.js

The Amazon QLDB team is pleased to announce the release v2.0.0 of the Node.js driver. This is a public and generally available(GA) release of the driver.

Note: A bug has been discovered in this version which results in No open transaction or Transaction already open errors, please use v2.2.0.

Migrating from v2.0.0-rc.1 to v2.0.0

If you have been using v2.0.0-rc.1, you just need to change the version of amazon-qldb-driver-nodejs in your application’s package.json file. There are no code changes required.

Migrating from v1.x to v2.0.0

Please note the breaking changes mentioned in the release notes of v2.0.0-rc.1 and change your application code accordingly.

Migrating from v0.x to v2.0.0

Follow the migration guide mentioned in release notes of v1.0.0 along with the changes mentioned in the release notes of v2.0.0-rc.1

Release v2.0.0-rc.1 of the Amazon QLDB Driver for Node.js

The Amazon QLDB team is pleased to announce the release of version v2.0.0-rc.1 of Node.js driver. This release is aimed at enhancing the developer experience when interacting with the Amazon QLDB Driver.

Note: This version is a release candidate. We might introduce some additional changes before releasing v2.0.0
Note: A bug has been discovered in this version which results in No open transaction or Transaction already open errors, please use v2.2.0.

New Feature

Custom retry and backoff config.

You can now provide your own custom backoff time, which the driver will use when a transaction gets retried. You can specify the retry config as part of the QldbDriver initialization or you can pass this config as a part of QldbDriver.executeLambda method.

Usage

import { BackoffFunction, QldbDriver, RetryConfig } from "amazon-qldb-driver-nodejs"

// First, create a retryConfig, which takes optional arguments: retryLimit and backoffFunction.
const retryLimit: number = 3;
const backoffFunction: BackoffFunction = (retryAttempt: number, error: Error, transactionId: string) => {
     //Code that returns the time(in milliseconds) to wait before the next retry attempt.
     const delayTime: number = 5; //example value
     return delayTime;
}
const retryConfig: RetryConfig = new RetryConfig(retryLimit, backoffFunction);

//Pass the retryConfig during driver initialization.
const qldbDriver: QldbDriver = new QldbDriver(ledgerName, clientConfiguration, maxConcurrentTransactions, retryConfig);

// You can also pass the retryConfig(same or different) when trying to execute a transaction. This will override the retryConfig passed in QldbDriver
qldbDriver.executeLambda((txn) => {
     //code for transaction
}, retryConfig);

The default value of retryLimit is 4. The default backoff function is defined in DefaultRetryConfig

The driver uses the following precedence when selecting the Retry Config during a retry attempt of a transaction:

1. Use Custom Retry Config provided in QldbDriver.executeLambda.
2. If not # 1, then use Custom Retry Config provided during QldbDriver initialization.
3. If not # 1 and # 2, then use defaultRetryConfig defined by the driver.

Breaking Changes

• Renamed QldbDriver property poolLimit to maxConcurrentTransactions.
• Removed QldbDriver property poolTimeout.
• Removed retryIndicator from QldbDriver.executeLambda method and replaced it with retryConfig.
• Moved retryLimit from QldbDriver constructor to RetryConfig constructor.
• The classes and methods marked deprecated in version v1.0.0 have now been removed. List of classes and methods:
  • PooledQldbDriver has been removed . Please use QldbDriver instead.
  • QldbSession.getTableNames method has been removed. Please QldbDriver.getTableNames method instead.
  • QldbSession.executeLambda method has been removed. Please use QldbDriver.executeLambda method instead.

Release v1.0.0 of the Amazon QLDB Driver for Node JS

The Amazon QLDB team is pleased to announce the release v1.0.0 of the Node.js driver. This is a public and generally available(GA) release of the driver, and this version can be used in production applications.

Migrating from v1.0.0-rc.2 to v1.0.0

If you have been using v1.0.0-rc.2, you just need to change the version of amazon-qldb-driver-nodejs in your application’s package.json file. There are no code changes required.

Note: Please ensure you have followed the recommendations in the release notes of v1.0.0-rc.2, around the deprecated APIs

Migrating from v1.0.0-rc.1 to v1.0.0

Please follow the recommendations in the release notes of v1.0.0-rc.2 before changing the version of the driver in your application’s package.json file.

Migrating from preview versions to v1.0.0

Please follow the changes mentioned in the release notes of v1.0.0-rc.1, along with the changes suggested in release notes of v1.0.0-rc.2.

Release v1.0.0-rc.2 of the Amazon QLDB Driver for Node JS

Release notes for 1.0.0-rc.2

The Amazon QLDB team is pleased to announce the release V1.0.0-rc.2 of the Node.js driver. This release aims to provide some improvements in the APIs, while ensuring that there are no breaking changes.

The list of changes are included the change log

Migrating from v1.0.0-rc.1 to v1.0.0-rc.2

Note: v1.0.0-rc.2 is backward compatible with v1.0.0-rc.1. However, we do recommend you to incorporate the following suggested changes.

Session pooling functionality moved to QldbDriver

Up until and including v1.0.0-rc.1, the amazon-qldb-driver-nodejs vended two types of driver implementations: The standard QldbDriver and a PooledQldbDriver. As the name suggests, the PooledQldbDriver maintained a pool of sessions which allowed you to reuse the underlying connections.
Over a period of time, we realized that customers would just want to use the pooling mechanism for its benefits instead of the standard driver.

And hence, we have decided to move the pooling functionality into QldbDriver and deprecate PooledQldbDriver. We will remove PooledQldbDriver in the future versions.

This implies two changes:

1. If you have been using PooledQldbDriver simply replace that with QldbDriver. The signature of the constructor and all the methods are same for both the drivers. So apart from instantiation, no more changes are required.

   Before

   let qldbDriver: PooledQldbDriver = new PooledQdbDriver(..)
   

   After

   let qldbDriver: QldbDriver = new QldbDriver(..)
   

​

2. If you have been using the standard QldbDriver, you can now pass the additional parameters to the constructor. Please check the documentation of QldbDriver

Helper method getTableNames now available on the driver instance

The QldbSession exposed a helper method called getTableNames which listed all the tables present in your ledger. This method has been deprecated and will be removed in the future versions. Instead, use getTableNames which is now available on QldbDriver.

Before

let qldbDriver: QldbDriver = new QldbDriver(..);
let session: QldbSession = await qldbDriver.getSession();
let tableNames: String[] = await session.getTableNames();

After

let qldbDriver: QldbDriver = new QldbDriver(..);
let tableNames: String[] = await qldbDriver.getTableNames();

Use executeLambda method on the driver

If you have been using executeLambda method on a session instance, we recommend you to instead use the executeLambda method on the driver instance. We have deprecated the executeLambda method on the session instance and will remove it in future versions.

Before

let qldbDriver: QldbDriver = new QldbDriver(..);
let session: QldbSession = await qldbDriver.getSession();
session.executeLambda(..)

After

let qldbDriver: QldbDriver = new QldbDriver(..);
qldbDriver.executeLambda(..)