EntityFormatter

Given a transformed item, validates that it respects the schema of the Entity, applies transformations backward and hide hidden attributes:

import { EntityFormatter } from 'dynamodb-toolbox/entity/actions/format'

const formattedPikachu =
  PokemonEntity.build(EntityFormatter).format(savedPikachu)

In DynamoDB-Toolbox, formatting is done in 2 steps:

Note that:

• Additional and hidden fields are omitted, but inputs are not mutated
• The formatting throws an error if the saved item is invalid
• Transformations (i.e. savedAs and transforms) are applied backward

info

This action is mostly a wrapper around the schema Formatter action, so we highly recommend you read its dedicated documentation first.

Methods

format(...)

(savedItem: unknown, options?: FormatItemOptions) => FormattedItem<ENTITY>

Formats a saved item:

const formattedItem = PokemonEntity.build(EntityFormatter).format(savedItem)

You can provide formatting options as a second argument. Available options:

Option	Type	Default	Description
transform	boolean	true	Whether to transform back the input (with savedAs and transform) prior to formatting or not.
partial	boolean	false	Allow every attribute (flat or deep) to be optional while formatting.
attributes	Path<Entity>[]	-	To specify a list of attributes to format (other attributes are omitted). See the PathParser action for more details on how to write attribute paths.

Examples

Partial

const saved = {
  pokemonId: 'pikachu1',
  name: 'Pikachu',
  ...
}

// 🙌 Typed as `DeepPartial<Pokemon>`
const formatted = PokemonEntity
  .build(EntityFormatter)
  .format(saved, { partial: true })

Attributes

const saved = {
  pokemonId: 'pikachu1',
  name: 'Pikachu',
  level: 42,
  ...
}

// 🙌 Typed as `Pick<Pokemon, 'name' | 'level'>`
const formatted = PokemonEntity
  .build(EntityFormatter)
  .format(saved, { attributes: ['name', 'level'] })

Formatting only

// 👇 Not transformed
const valid = {
  pokemonId: 'pikachu1',
  name: 'Pikachu',
  level: 42,
  ...
}

// 👇 Simply omits hidden attributes
const formatted = PokemonEntity
  .build(EntityFormatter)
  .format(valid, { transform: false })

You can use the FormattedItem type to explicitly type an object as a formatting output object:

import type { FormattedItem } from 'dynamodb-toolbox/entity'

const formattedItem: FormattedItem<
  typeof PokemonEntity,
  // 👇 Optional options
  { partial: false; attributes: 'name' | 'level' }
  // ❌ Throws a type error
> = { invalid: 'output' }