Item

Describes items with a finite list of attributes, i.e. key-schema pairs. Items differ from maps as they are meant to be used as the root schema of an Entity (and not to be nested within other schemas):

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

const fullNameSchema = item({
  firstName: string(),
  lastName: string()
})

type FullName = FormattedValue<typeof fullNameSchema>
// => {
//  firstName: string
//  lastName: string
// }

Properties

.strict()

boolean | undefined

Rejects additional (undeclared) attributes when parsing input values:

const pokemonSchema = item({
  name: string()
}).strict()

// ❌ Throws `parsing.additionalProperty`
pokemonSchema.build(Parser).parse({
  name: 'Pikachu',
  level: 42
})

Enforcement happens on writes only and on all modes.

.meta(...)

SchemaMeta

Attaches documentation metadata to the schema (e.g. title, description, examples or arbitrary custom keys):

const pokemonSchema = item({ name: string() }).meta({
  title: 'Pokémon',
  description: 'A Pokémon item'
})

Methods

Item schemas can be used to build new schemas with the following methods:

and(...)

(attr: NEW_ATTR | (MapSchema<OLD_ATTR> => NEW_ATTR)) => MapSchema<OLD_ATTR & NEW_ATTR>

Produces a new item schema by extending the original schema with new attributes:

const extendedSchema = baseSchema.and({
  newAttribute: string(),
  ...
})

info

In case of naming conflicts, new attributes override the previous ones.

The method also accepts functions that return new attributes. In this case, the previous schema is provided as an argument (which is particularly useful for building Links):

const extendedSchema = mySchema.and(prevSchema => ({
  newAttribute: string(),
  ...
}))

pick(...)

(...attrNames: ATTR_NAMES[]) => MapSchema<Pick<ATTR, ATTR_NAMES>>

Produces a new item schema by picking only certain attributes from the original schema:

const picked = pokemonSchema.pick('name', 'pokemonLevel')

Due to the potential disruptive nature of this method on links, they are reset in the process:

const nameSchema = item({
  firstName: string(),
  lastName: string(),
  completeName: string().link(({ firstName, lastName }) =>
    [firstName, lastName].join(' ')
  )
})

const picked = nameSchema.pick('lastName', 'completeName')

picked.attributes.completeName.props.putLink
// => undefined

omit(...)

(...attrNames: ATTR_NAMES[]) => MapSchema<Omit<ATTR, ATTR_NAMES>>

Produces a new item schema by omitting certain attributes out of the original schema:

const omitted = pokemonSchema.omit('name', 'pokemonLevel')

Due to the potential disruptive nature of this method on links, they are reset in the process:

const nameSchema = item({
  firstName: string(),
  lastName: string(),
  completeName: string().link(({ firstName, lastName }) =>
    [firstName, lastName].join(' ')
  )
})

const omitted = nameSchema.omit('firstName')

omitted.attributes.completeName.props.putLink
// => undefined