Is lack of DocumentClient in aws-sdk v3 a breaking change?

[jpet710122]

There is much discussion around the decision by the AWS development team to leave DocumentClient capability out of v3 of the Javascript AWS-SDK. See #1223, and the response at #2031.

Does this mean your excellent library will only work with V2? Will there be any plans to support v3?

[mobsense]

Currently OneTable requires the AWS V2 SDK and utilizes DocumentClient. We're monitoring the discussion re V3 & DocumentClient. We definitely want to support V3 but would rather not have to write mapping that emulates DocumentClient ourselves, but we will do that if required. My hope is that the community pressure will force some kind of better DocumentClient upgrade path for V3 by AWS. Failing that in the short term, we will provide an upgrade path.

Since V3 is brand new, it will take a little while for the dust to settle.

[jpet710122]

Thanks. I'll just stick with v2 for the time being, then!

[trivikr]

Update: The AWS SDK for JavaScript has prioritized development of DocumentClient for DynamoDB in v3, and an experimental PR can be viewed at aws/aws-sdk-js-v3#2031

[mobsense]

In parallel with the AWS DocumentClient PR, we're prototyping V3 support here.

Progressing well and will post updates here.

Our plan is to support both V2 and V3 in the one code base. The V3 support will provide a helper class which will import the required DynamoDB V3 classes and transparently integrate the marshall / unmarshall into and out of Javascript objects.

[mobsense]

Okay, got the basic AWS SDK V3 support working. Really not too bad. The marshall / unmarshall support does most of the heavy lifting.

@trivikr I still believe that V3 DocumentClient is probably worthwhile for the general developer so they can more easily upgrade to V3. However, for OneTable, there are performance benefits in going directly to the V3 APIs. So we'll offer both options.

V3 support looks like this:

import {Model, Table} from 'dynamodb-onetable'
import Dynamo from 'dynamodb-onetable/Dynamo'

const table = new Table({
    dynamo: new Dynamo(params),
    name: 'MyTable',
    schema: MySchema,
})

With this configuration, all OneTable APIs work the same as for AWS V2.

For comparison using AWS V2:

import DynamoDB from 'aws-sdk/clients/dynamodb'
import {Model, Table} from 'dynamodb-onetable'

const table = new Table({
    client:  new DynamoDB.DocumentClient(params),
    name: 'MyTable',
    schema: MySchema,
})

In the V3 support, the OneTable Dynamo class is a helper which constructs the V3 DynamoDBClient instance for the given params. The Dynamo helper class separates the dependencies for V3 and will be not-bundled for V2 users. It imports 11 DynamoDBClient commands and wraps these for use by OneTable. The marshall and unmarshall routines are also imported from @aws-sdk/util-dynamodb and passed into OneTable to use transparently.

I know having a helper class import 11 methods defeats perfect tree shaking, but the benefit in a terse interface I believe outweighs shaking a few more bytes that are probably going to be used in any real app anyway.

If you want to construct the DynamoDBClient instance yourself with V3, pass in as new Dynamo({client}).

import DynamoDBClient from '@aws-sdk/client-dynamodb'
import {Model, Table} from 'dynamodb-onetable'
import Dynamo from 'dynamodb-onetable/Dynamo'

const client = new DynamoDBClient(params)
const table = new Table({
    dynamo: new Dynamo({client}),
    name: 'MyTable',
    schema: MySchema,
})

[mobsense]

We've cleaned up the API a little by requiring the user to always pass in a DocumentClient or V3 DynamoDBClient instance.

Running through our test suite now. Looks pretty interchangeable with V2 and V3. No user app code that uses OneTable needs changing after the initialization.

import {Table} from 'dynamodb-onetable'

// V2
import DynamoDB from 'aws-sdk/clients/dynamodb'
const client = new DynamoDB.DocumentClient({...})

// V3
import {DynamoDBClient} from '@aws-sdk/client-dynamodb'
import Dynamo from 'dynamodb-onetable/Dynamo'
const client = new Dynamo({client: new DynamoDBClient({...})})

// V2 or V3
const table = new Table({
    client: client,
    name: 'MyTable',
    schema: MySchema,
})

Tagging: @trivikr, @jpet710122

[mobsense]

Supported added in 0.7.0 released.