Formatter

Given a saved item, validates that it respects the schema and formats it:

import { Formatter } from 'dynamodb-toolbox/schema/actions/format'

const formattedPikachu = pokemonSchema
  .build(Formatter)
  .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) by default

Methods

format(...)

(savedValue: unknown, options?: FormatValueOptions) => FormattedValue<SCHEMA>

Formats a saved item:

const formattedValue = pokemonSchema.build(Formatter).format(savedValue)

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.
format	boolean	true	Whether to format the input (hide hidden attributes) after transformation. No effect if transform is set to false.
partial	boolean	false	Allow every attribute (flat or deep) to be optional while formatting.
attributes	Path<Schema>[]	-	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 transformed = {
  pokemonId: 'pikachu1',
  name: 'Pikachu'
}

// 🙌 Typed as `DeepPartial<FormattedPokemon>`
const formatted = pokemonSchema
  .build(Formatter)
  .format(transformed, { partial: true })

Attributes

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

// 🙌 Typed as `Pick<FormattedPokemon, 'name' | 'level'>`
const formatted = pokemonSchema
  .build(Formatter)
  .format(transformed, { attributes: ['name', 'level'] })

Formatting only

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

// 👇 Only omits hidden attributes
const formatted = pokemonSchema
  .build(Formatter)
  .format(valid, { transform: false })

Transform only

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

// 👇 Keeps hidden attributes
const valid = pokemonSchema
  .build(Formatter)
  .format(transformed, { format: false })

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

import type { FormattedValue } from 'dynamodb-toolbox/format'

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

start(...)

(input: unknown, options?: FormatValueOptions) => Generator<FormattingResults<SCHEMA>>

Similar to .format, but returns the underlying Generator to inspect the intermediate results of the formatting steps:

Examples

Complete

const formattingGenerator = pokemonSchema
  .build(Formatter)
  .start(pokemon)

const transformedPokemon = formattingGenerator.next().value
const formattedPokemon = formattingGenerator.next().value

Formatting only

const formattingGenerator = pokemonSchema
  .build(Formatter)
  .start(pokemon, { transform: false })

// 👇 No `transform` step
const formattedPokemon = formattingGenerator.next().value

validate(...)

(input: unknown) => boolean

Runs only the transform step of the formatting workflow on the provided input. Returns true if the input is valid, catches any parsing error and returns false otherwise:

const isValid = pokemonSchema
  .build(Formatter)
  .validate(input)

Note that .validate(...) acts as a type guard:

if (pokemonSchema.build(Formatter).validate(input)) {
  // 🙌 Typed as `TransformedPokemon`!
  const { level, name } = input
  ...
}