Skip to main content

Number

Defines a number attribute:

import { number } from 'dynamodb-toolbox/attributes/number';

const pokemonSchema = schema({
  ...
  level: number(),
});

type FormattedPokemon = FormattedItem<typeof PokemonEntity>;
// => {
//   ...
//   level: number
// }

Options​

.required()​

string | undefined

Tags the attribute as required (at root level or within Maps). Possible values are:

  • 'atLeastOnce' (default): Required (starting value)
  • 'always': Always required (including updates)
  • 'never': Optional
// Equivalent
const levelSchema = number()
const levelSchema = number().required()
const levelSchema = number({ required: 'atLeastOnce' })

// shorthand for `.required('never')`
const levelSchema = number().optional()
const levelSchema = number({ required: 'never' })

.hidden()​

boolean | undefined

Skips the attribute when formatting items:

const levelSchema = number().hidden()
const levelSchema = number({ hidden: true })

.key()​

boolean | undefined

Tags the attribute as a primary key attribute or linked to a primary attribute:

// Note: The method also sets the `required` property to 'always'
// (it is often the case in practice, you can still use `.optional()` if needed)
const levelSchema = number().key()
const levelSchema = number({
  key: true,
  required: 'always'
})

.savedAs(...)​

string

Renames the attribute during the transformation step (at root level or within Maps):

const levelSchema = number().savedAs('lvl')
const levelSchema = number({ savedAs: 'lvl' })

.enum(...)​

number[]

Provides a finite range of possible values:

const pokemonGenerationSchema = number().enum(1, 2, 3)

// 👇 Equivalent to `.enum(1).default(1)`
const pokemonGenerationSchema = number().const(1)
info

For type inference reasons, the enum option is only available as a method and not as a constructor property.

.transform(...)​

Transformer<number>

Allows modifying the attribute values during the transformation step:

const addOne = {
  parse: (input: number) => input + 1,
  format: (saved: number) => saved - 1
}

// Saves the value plus one
const levelSchema = number().transform(addOne)
const levelSchema = number({ transform: addOne })

DynamoDB-Toolbox exposes on-the-shelf transformers, so feel free to use them!

.big()​

boolean | undefined

Allows BigInt values:

const levelSchema = number().big()
const levelSchema = number({ big: true })

type FormattedPokemon = FormattedItem<typeof PokemonEntity>
// => {
//   ...
//   level: number | bigint
// }

.default(...)​

ValueOrGetter<number>

Specifies default values for the attribute. See Defaults and Links for more details:

Examples
const levelSchema = number().default(42)
// 👇 Similar to
const levelSchema = number().putDefault(42)
// 👇 ...or
const levelSchema = number({
  defaults: {
    key: undefined,
    put: 42,
    update: undefined
  }
})

// 🙌 Getters also work!
const levelSchema = number().default(() => 42)

.link<Schema>(...)​

Link<SCHEMA, number>

Similar to .default(...) but allows deriving the default value from other attributes. See Defaults and Links for more details:

const pokemonSchema = schema({
  level: number()
}).and(prevSchema => ({
  captureLevel: number().link<typeof prevSchema>(
    // 🙌 Correctly typed!
    item => item.level
  )
}))

.validate(...)​

Validator<number>

Adds custom validation to the attribute. See Custom Validation for more details:

Examples
const integerSchema = number().validate(input =>
  Number.isInteger(input)
)
// 👇 Similar to
const integerSchema = number().putValidate(input =>
  Number.isInteger(input)
)
// 👇 ...or
const integerSchema = number({
  validators: {
    key: undefined,
    put: input => Number.isInteger(input),
    update: undefined
  }
})