Add support for bigint attribute type

[tixxit]

This PR adds support for a new type: 'bigint' attribute type. It requires the DocumentClient to have wrapNumbers: true configured in the options, but otherwise allows use of integers > 53 bits.

I'm hoping there is interest for merging this type of feature! Currently it is using native bigint support, which means I've update the target to ES2019. Alternatively, we could use JSBI if you'd prefer to stick with 2015.

[shellscape]

I think covers the bases for support. my only question is around the DocumentClient requirements; if the user doesn't specify wrapNumbers: true and attempts to use a bigint, what happens?

@jeremydaly thoughts?

[tixxit]

Right now, if wrapNumbers: false and an attribute uses type: 'bigint', then Entity construction will fail with an error message telling the developers to use wrapNumbers: true in their table's DocumentClient. Not super ideal, but there is no way to know if DocumentClient lost precision without it, so it would otherwise have silently lost precision.

[shellscape]

And there's a test present for that error, so that looks good. I don't have merge capabilities, so we'll have to wait for other maintainers to have a look. @tixxit looks like you may need rebase from upstream/origin to bring your branch up to date.

[naorpeled]

LGTM!
left a small comment but good stuff,
thanks for creating this awesome PR!

once rebased from master, will merge this in and release :)

[shellscape]

@naorpeled do you have merge permissions? just curious if there's a collaborator that has merge permissions or we need to bug jeremy.

[naorpeled]

@naorpeled do you have merge permissions? just curious if there's a collaborator that has merge permissions or we need to bug jeremy.

Yeah, the PR can't be merged before rebased

[tixxit]

I merged the main branch and removed the unneeded test:bigint script. Thanks for the reviews!

[shellscape]

@tixxit something that may have been overlooked: when returning attributes from DynamoDB, aws-sdk returns a NumberValue as a result of the wrapNumbers: true setting. Consumers of this will likely expect to get a bigint rather than NumberValue - I did. Since all numbers are wrapped, this changes the expected output of Attributes on Item for all numbers. So while there is bigint support, the documentation needs to be updated for the bigint type to alert users that the type of number and bigint attributes will be the wrapped NumberValue. Consumers that don't go to the AWS documentation to read about what side effects wrapNumbers will have will be caught off guard, and that's not a good DX.

[tixxit]

@shellscape Are you seeing this when using parse/autoparse/etc? We should be converting NumberValue to the proper type, number or bigint regardless. The raw data from the DocumentClient will return the wrapped values though. We've been using this in prod for a bit and it's been good!

[shellscape]

@tixxit here's the entity we're using:

const Event = new Entity({
  attributes: {
    createdAt: {
      default: () => new Date().toISOString(),
      onUpdate: false,
      required: true,
      type: 'string'
    },
    event: { partitionKey: true, type: 'string' },
    data: { required: true, type: 'map' },
    id: { default: () => nanoid(), required: true, type: 'string' },
    sequence: { default: () => getSequence(), sortKey: true, type: 'bigint' },
    type: { type: 'string' },
    version: { type: 'string' }
  },
  name: 'Event',
  table,
  timestamps: false
});

Here's how we're calling out to the db:

export const listEventsByName = async (eventName: string, options: ListEventOptions = {}) => {
  log.debug('listEventsByName:', { eventName, options });
  const { limit = 100 } = options;
  const result = await Event.query(eventName, { limit });

  result.Items = result.Items.map((item) => unwrap(item as EventEntity)) as any;

  return result as EventEntityList;
};

// Note: Because the aws-sdk v2 returns a `NumberValue` wrapper for bigint, we must unwrap the value
// so we can use bigint as per usual elsewhere
const unwrap = (entity: EventEntity) => {
  return { ...entity, sequence: BigInt(entity.sequence.toString()) };
};

In this scenario, we're getting the wrapped value for sequence for each item in Items. Perhaps there's a hole in the tests?

[shellscape]

@tixxit as a followup, we're continuing to see this in new places. namely the map field seen above, where the result Items contain data in the data field that resembles:

  oneTimeFee: {
    value: NumberValue { wrapperName: 'NumberValue', value: '3000' },
    currency: 'CAD'
  },

We've not changed the parsing settings, using the default, so something is definitely awry there