BigInt

Introduction

BigInt represents DynamoDB's big Number data type (marshalled as "N") for DynamoQL.

info

BigInt is almost similar to Number type, except it accepts only JS BigInt values.
When reteving an item DynamoDB number type is returned as JS BigInt, even if it may be a number.

Define a BigInt

DynamoQL

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

 const userSchema = new Schema({
  id: {
    type: String,
    primaryIndex: true,
    default: randomUUID
  },
  order: BigInt,
  score: {
    type: BigInt,
  }
} as const);

produced type

interface IUserSchema {
    id: string,
    order: bigint,
    score?: bigint
}

Options

- primaryIndex

top-level only

boolean which markes attribute as HASH key and makes attribute as required, default is false.
A Schema can have only one primaryIndex.

import { Schema } from "dynamoql";

 const userSchema = new Schema({
  id: {
    type: BigInt,
    primaryIndex: true,
  },
} as const);

- sortKey

top-level only

boolean which markes attribute as RANGE key and makes attribute as required, default is false.
A Schema can have only one sortKey.

import { Schema } from "dynamoql";

 const userSchema = new Schema({
  countryCode: {
    type: BigInt,
    primaryIndex: true,
  },
  cityCode: {
    type: BigInt,
    sortKey: true
  }
} as const);

- LSI

top-level only

defines a Local Secondary Index.

LSI option is an object where you must provide:

• indexName which should be unique across the Schema.
• project which may be ALL | KEYS or string[] where strings are attriubute names defined in the Schema.

import { Schema } from "dynamoql";

 const userSchema = new Schema({
  id: {
    type: String,
    primaryIndex: true,
  },
  age: {
    type: BigInt,
    LSI: {
        indexName: "age-index",
        project: "ALL"
    }
  }
} as const);

- GSI

top-level only

defines a Global Secondary Index.

GSI option is an object where you must provide:

• indexName which should be unique across the Schema.
• project which may be ALL | KEYS or string[] where strings are attriubute names defined in the Schema.

import { Schema } from "dynamoql";

 const userSchema = new Schema({
  id: {
    type: String,
    primaryIndex: true,
  },
  age: {
    type: BigInt,
    GSI: {
        indexName: "age-index",
        project: "ALL"
    }
  }
} as const);

for composite table (HASH and RANGE) you must provide another attribute with GSI:

• indexName which must be one of defined GSI indexName.
• sortKey true.

import { Schema } from "dynamoql";

 const userSchema = new Schema({
  id: {
    type: String,
    primaryIndex: true,
  },
  age: {
    type: BigInt,
    GSI: {
        indexName: "age-index",
        project: "ALL"
    }
  },
  order: {
    type: BigInt,
    GSI: {
        indexName: "age-index",
        sortKey: true
    }
  }
} as const);

- required

boolean which makes attribute as required or optionnal, default is false when type is defined with an Object.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

 const userSchema = new Schema({
  id: {
    type: String,
    primaryIndex: true,
    default: randomUUID
  },
  score: {
    type: BigInt,
    required: true
  }
} as const);

- default

To set a default value for an attribute use default option.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

 const userSchema = new Schema({
  id: {
    type: String,
    primaryIndex: true,
    default: randomUUID
  },
  score: {
    type: BigInt,
    default: 5290288293971332n
  }
} as const);

With this configuration when you put an Item into your table, your Item will contain score attribute with 5290288293971332n as value.

default must be a BigInt.
Otherwise it will throw an error during dev time and runtime.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

const userSchema = new Schema({
 id: {
   type: String,
   primaryIndex: true,
   default: randomUUID
 },
 score: {
   type: BigInt,
   default: "some-score" // DynamoQLInvalidTypeException: "score" expected to be "N" received "S".
 }
} as const);

default can also be a (async) function which accepts one argument (put Item value) and must return a BigInt.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

const userSchema = new Schema({
id: {
  type: String,
  primaryIndex: true,
  default: randomUUID
},
moderator: Boolean,
score: {
  type: BigInt,
  default: (item: Record<string, any>)=> {
      if(item.moderator) {
          return 123456789012345n
      }
      return []
  }
}
} as const);

- validate

validate option allows you to manually validate provided value in put and update commands.
To return an error you should return a string which explains value invalidity. Any other returned value is considered as valid.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

const userSchema = new Schema({
id: {
  type: String,
  primaryIndex: true,
  default: randomUUID
},
moderator: Boolean,
score: {
  type: BigInt,
  validate: (self: bigint)=> {
      if(self > 9999999999999999n) {
          return "Can not be greater than 9999999999999999n."
      }
  }
}
} as const);

- min

define minimum accepted value.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

const userSchema = new Schema({
id: {
  type: String,
  primaryIndex: true,
  default: randomUUID
},
moderator: Boolean,
score: {
  type: BigInt,
  min: 123456780234n // or BigInt(123456780234)
}
} as const);

- max

define maximum accepted value.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

const userSchema = new Schema({
id: {
  type: String,
  primaryIndex: true,
  default: randomUUID
},
moderator: Boolean,
score: {
  type: BigInt,
  max: 123456780234n // or BigInt(123456780234)
}
} as const);

- enum

define accepted values.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

const userSchema = new Schema({
id: {
  type: String,
  primaryIndex: true,
  default: randomUUID
},
moderator: Boolean,
score: {
  type: BigInt,
  enum: [1111111111111111n, 222222222222222n,]
}
} as const);

- set

To modify a value before storing it use set option.
set (async) function accepts 3 arguments:

1. self provided value.
2. item entier put Item object.
3. setterInfo an optionnal value provided inside in put, batchPut, batchWrite, transactWrite command's options.

set will not be called if attribute doesn't exists in put Item object.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

const userSchema = new Schema({
id: {
  type: String,
  primaryIndex: true,
  default: randomUUID
},
moderator: Boolean,
score: {
  type: BigInt,
  set: (self: bigint, item: Record<string, any>, setterInfo?: any)=> {

      if(item.moderator && setterInfo?.someCondition) {
       return BigInt("12345")
      }

      return self
  }
}
} as const);

- get

When reteving an Item we can transform field's value with get option.

get (async) function accepts 3 arguments:

1. self retrieved value.
2. item entier retrieved Item object.
3. getterInfo an optionnal value provided inside get, batchGet, transactGet, query, scan command's options.

get can return anything.
get will not be called if attribute doesn't exists in stored Item.

import { Schema } from "dynamoql";
import { randomUUID } from "crypto";

const userSchema = new Schema({
id: {
  type: String,
  primaryIndex: true,
  default: randomUUID
},
moderator: Boolean,
score: {
  type: BigInt,
  items: String,
  get: (self: bigint, item: Record<string, any>, getterInfo?: any)=> {
      if(getterInfo.someCondition) {
          return null
      }
       return self
  }
}
} as const);

info

get returned value's type affects Item type when retriving Item(s) from DynamoDB.

- description

add any information to the Schema for your personal usage.

Condition expression

Same as Number Condition expression except provided values should be BigInt instead of Number.

Update expressions

Same as Number Update expressions except provided values should be BigInt instead of Number.