Tuple

Describes tuple values, i.e. a finite list of index-value pairs. Child attributes can have any type:

import { tuple } from 'dynamodb-toolbox/schema/tuple'

const dateRangeSchema = tuple(string(), string())

type DateRange = FormattedValue<typeof dateRangeSchema>
// => [number, number]

info

For the moment, tuple properties can only be set by using methods.

Tuple elements can have any type. However, they must respect some constraints:

• They cannot be optional or always required
• They cannot be hidden or key (tagging the tuple itself as key is enough)
• They cannot be renamed (with savedAs)

// ❌ Raises a type AND a run-time error
const strTuple = tuple(string().optional())
const strTuple = tuple(string().hidden())
const strTuple = tuple(string().key())
const strTuple = tuple(string().savedAs('foo'))

Properties

.required()

string | undefined

Tags schema values as required (within items or maps). Possible values are:

• 'atLeastOnce' (default): Required (starting value)
• 'always': Always required (including updates)
• 'never': Optional

const dateRangeSchema = tuple(string(), string()).required()

// shorthand for `.required('never')`
const dateRangeSchema = tuple(...).optional()

.hidden()

boolean | undefined

Omits schema values during formatting:

const dateRangeSchema = tuple(string(), string()).hidden()

.key()

boolean | undefined

Tags schema values as a primary key attribute or linked to a primary key 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 dateRangeSchema = tuple(string(), string()).key()

.savedAs(...)

string

Renames schema values during the transformation step (at root level or within other Maps):

const dateRangeSchema = tuple(string(), string())
  .savedAs('d')

.default(...)

ValueOrGetter<CHILD_ATTRIBUTES>

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

Examples

Put/Update

const now = () => new Date().toISOString()

const timestampsSchema = tuple(string())
  .default(() => [now()])
  .updateDefault(() => [now()])
// 👇 Similar to
const timestampsSchema = tuple(string())
  .putDefault(() => [now()])
  .updateDefault(() => [now()])

Key

const timestampsSchema = tuple(string())
  .key()
  .default(() => [now()])
// 👇 Similar to
const timestampsSchema = tuple(string())
  .key()
  .keyDefault(() => [now()])

.link<Schema>(...)

Link<SCHEMA, CHILD_ATTRIBUTES>

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

const pokemonSchema = item({
  name: string()
}).and(prevSchema => ({
  parsedName: tuple(string(), string()).link<
    typeof prevSchema
  >(
    // 🙌 Correctly typed!
    ({ name }) => {
      const [firstName, lastName] = name.split(' ')
      return [firstName, lastName]
    }
  )
}))

.validate(...)

Validator<CHILD_ATTRIBUTES>

Adds custom validation. See Custom Validation for more details:

Examples

const nonEmpty = tuple(string(), string()).validate(input =>
  input.some(value => value !== '')
)
// 👇 Similar to
const nonEmpty = tuple(string(), string()).putValidate(
  input => input.some(value => value !== '')
)